ledger

type Account interface {
	ID() models.NamespacedID
	Type() AccountType
}

type AccountCatalog interface {
	AccountReader
	AccountProvisioner
}

type AccountLocker interface {
	LockAccountsForPosting(ctx context.Context, accounts []Account) error
}

type AccountProvisioner interface {
	CreateAccount(ctx context.Context, input CreateAccountInput) (Account, error)
	EnsureSubAccount(ctx context.Context, input CreateSubAccountInput) (SubAccount, error)
}

type AccountReader interface {
	GetAccountByID(ctx context.Context, id models.NamespacedID) (Account, error)
	GetSubAccountByID(ctx context.Context, id models.NamespacedID) (SubAccount, error)

	ListSubAccounts(ctx context.Context, input ListSubAccountsInput) ([]SubAccount, error)
	ListAccounts(ctx context.Context, input ListAccountsInput) ([]Account, error)
}

type AccountResolver interface {
	GetCustomerAccounts(ctx context.Context, customerID customer.CustomerID) (CustomerAccounts, error)
	EnsureBusinessAccounts(ctx context.Context, namespace string) (BusinessAccounts, error)
	GetBusinessAccounts(ctx context.Context, namespace string) (BusinessAccounts, error)
}

type AccountType string

type Balance = alpacadecimal.Decimal

type BalanceBucket struct {
	Address       PostingAddress
	GroupByValues map[string]*string
	SettledAmount alpacadecimal.Decimal
	PendingAmount alpacadecimal.Decimal
}

type BalanceBucketQuery struct {
	Namespace string
	Filters   Filters
	GroupBy   []string
}

type BalanceQuerier interface {
	GetAccountBalance(ctx context.Context, account Account, route RouteFilter, query BalanceQuery) (Balance, error)
	GetSubAccountBalance(ctx context.Context, subAccount SubAccount, query BalanceQuery) (Balance, error)
	GetBalanceBuckets(ctx context.Context, query BalanceBucketQuery) ([]BalanceBucket, error)
}

type BalanceQuery struct {
	After *TransactionCursor
	AsOf  *time.Time
}

type BreakageKind string

type BreakageSourceKind string

type BusinessAccount interface {
	Account

	GetSubAccountForRoute(ctx context.Context, route BusinessRouteParams) (SubAccount, error)
}

type BusinessAccounts struct {
	WashAccount      BusinessAccount
	EarningsAccount  BusinessAccount
	BrokerageAccount BusinessAccount
	BreakageAccount  BusinessAccount
}

type BusinessRouteParams struct {
	Currency          currencies.CurrencyReference
	CostBasisCurrency *currencyx.Code
	TaxCode           *string
	TaxBehavior       *TaxBehavior
	CostBasis         *alpacadecimal.Decimal
}

type ChargeTransactionAnnotationsInput struct {
	ChargeID models.NamespacedID

	SubscriptionID      *string
	SubscriptionPhaseID *string
	SubscriptionItemID  *string
	FeatureID           *string
}

type CreateAccountInput struct {
	Namespace   string
	Type        AccountType
	Annotations models.Annotations
}

type CreateSubAccountInput struct {
	Namespace   string
	AccountID   string
	Annotations models.Annotations
	Route       Route
}

type CustomerAccount interface {
	Account
}

type CustomerAccounts struct {
	FBOAccount        CustomerFBOAccount
	ReceivableAccount CustomerReceivableAccount
	AccruedAccount    CustomerAccruedAccount
}

type CustomerAccruedAccount interface {
	CustomerAccount

	GetSubAccountForRoute(ctx context.Context, route CustomerAccruedRouteParams) (SubAccount, error)
}

type CustomerAccruedRouteParams struct {
	Currency          currencies.CurrencyReference
	CostBasisCurrency *currencyx.Code
	TaxCode           *string
	TaxBehavior       *TaxBehavior
	CostBasis         *alpacadecimal.Decimal
}

type CustomerFBOAccount interface {
	CustomerAccount

	GetSubAccountForRoute(ctx context.Context, route CustomerFBORouteParams) (SubAccount, error)
}

type CustomerFBORouteParams struct {
	Currency          currencies.CurrencyReference
	CostBasisCurrency *currencyx.Code
	CreditPriority    int
	Features          []string
	CostBasis         *alpacadecimal.Decimal
}

type CustomerReceivableAccount interface {
	CustomerAccount

	GetSubAccountForRoute(ctx context.Context, route CustomerReceivableRouteParams) (SubAccount, error)
}

type CustomerReceivableRouteParams struct {
	Currency                       currencies.CurrencyReference
	CostBasisCurrency              *currencyx.Code
	TaxCode                        *string
	Features                       []string
	CostBasis                      *alpacadecimal.Decimal
	TransactionAuthorizationStatus TransactionAuthorizationStatus
}

type Entry interface {
	EntryInput
	ID() models.NamespacedID
	TransactionID() models.NamespacedID
}

type EntryIdentityKeyText string

type EntryIdentityParts struct {
	CollectionSource *string // Custom key to keep 1:1 matching logic during collection
	CorrectionSource *string // References the ID of the entry we're collecting
	SourceChargeID   *string // The original creditpurchase charge (if exists) that funds this entry
	SpendChargeID    *string // The usage charge (if exists) that accrued this entry
}

type EntryIdentityVersion int

type EntryInput interface {
	PostingAddress() PostingAddress
	Amount() alpacadecimal.Decimal
	IdentityKey() string
	SchemaVersion() EntrySchemaVersion
	SourceChargeID() *string
	SpendChargeID() *string
	Annotations() models.Annotations
}

type EntrySchemaVersion int

type Filters struct {
	// BookedAtPeriod is inclusive-exclusive... should it be? Maybe finally add period inclusivity params?
	BookedAtPeriod *timeutil.OpenPeriod
	After          *TransactionCursor
	AsOf           *time.Time
	TransactionID  *string
	// AccountID narrows the query to a single account via its sub-accounts.
	AccountID *string
	// SourceChargeID narrows entries by the creditpurchase charge that funded them.
	// Absent aggregates across source charges, Some(nil) selects source-less entries.
	SourceChargeID mo.Option[*string]
	// SpendChargeID narrows entries by the charge that consumed or accrued value.
	// Absent aggregates across spend charges, Some(nil) selects spend-less entries.
	SpendChargeID mo.Option[*string]
	// Route is a partial route filter. AccountID plus a full Route.Filter() identifies
	// one sub-account, but arbitrary RouteFilter values can match many sub-accounts.
	Route RouteFilter
}

type ImpactFilter struct {
	AccountType AccountType
	Route       RouteFilter
}

type Ledger interface {
	// CommitGroup commits a list of transactions on the Ledger atomically
	CommitGroup(ctx context.Context, group TransactionGroupInput) (TransactionGroup, error)

	// GetTransactionGroup loads a previously committed transaction group including its transactions.
	GetTransactionGroup(ctx context.Context, id models.NamespacedID) (TransactionGroup, error)

	// ListTransactions lists transactions on the Ledger according to some filters
	//
	// TODO: Cursoring gets problematic due to diff between wall_clock and booked_at. It would be convenient to return in order of booked_at as that simplifies parsing. This API will likely change.
	ListTransactions(ctx context.Context, params ListTransactionsInput) (ListTransactionsResult, error)
}

type ListAccountsInput struct {
	Namespace    string
	AccountTypes []AccountType
}

type ListSubAccountsInput struct {
	Namespace string
	AccountID string

	Route RouteFilter
}

type ListTransactionsCreditMovement uint8

type ListTransactionsInput struct {
	Namespace string
	Cursor    *TransactionCursor
	Before    *TransactionCursor
	Limit     int

	TransactionID *models.NamespacedID

	// AccountIDs scopes the query to transactions with entries on these accounts.
	AccountIDs []string
	Currency   *currencyx.Code
	AsOf       *time.Time
	Route      RouteFilter

	CreditMovement ListTransactionsCreditMovement

	// AnnotationFilters matches transactions whose annotations contain all the given key-value pairs.
	AnnotationFilters map[string]string

	// ExcludeAnnotationFilters excludes transactions whose annotations contain any given key-value pair.
	ExcludeAnnotationFilters map[string]string
}

type ListTransactionsResult struct {
	Items      []Transaction
	NextCursor *TransactionCursor
}

type PostingAddress interface {
	models.Equaler[PostingAddress]

	SubAccountID() string
	AccountType() AccountType
	Route() SubAccountRoute
}

type Query struct {
	Namespace string

	Cursor *pagination.Cursor

	Filters Filters
}

type Route struct {
	// Version is auto-derived by Normalize() based on which fields are present.
	// Direct assignment is overwritten on the next Normalize call. Do not set
	// manually except for testing edge cases.
	Version  RoutingKeyVersion
	Currency currencies.CurrencyReference
	// CostBasisCurrency identifies the fiat currency exchanged into a custom currency.
	// Fiat and non-exchange routes keep CostBasisCurrency nil.
	CostBasisCurrency *currencyx.Code
	TaxCode           *string
	// TaxBehavior distinguishes taxable accrued and earnings buckets.
	// Customer FBO routes do not carry tax dimensions; credit sources are
	// attributed to charge tax configuration when they accrue.
	TaxBehavior                    *TaxBehavior
	Features                       []string
	CostBasis                      *alpacadecimal.Decimal
	CreditPriority                 *int
	TransactionAuthorizationStatus *TransactionAuthorizationStatus
}

type RouteFilter struct {
	Currency          currencies.CurrencyReference
	CostBasisCurrency mo.Option[*currencyx.Code]

	// Non-currency fields are retained for near-future expansion.
	TaxCode     mo.Option[*string]
	TaxBehavior mo.Option[*TaxBehavior]
	// Features is an exact-match filter for sub-account routes.
	Features mo.Option[[]string]
	// MatchFeature matches unrestricted routes and routes containing this single feature key.
	MatchFeature string
	CostBasis    mo.Option[*alpacadecimal.Decimal]

	// CreditPriority is only meaningful for customer_fbo queries.
	CreditPriority *int

	// TransactionAuthorizationStatus is currently only meaningful for customer_receivable queries.
	// Nil means "do not filter by authorization status", not "open".
	TransactionAuthorizationStatus *TransactionAuthorizationStatus
}

type RoutingKey struct {
	// contains filtered or unexported fields
}

type RoutingKeyVersion string

type RoutingValidator interface {
	ValidateEntries(entries []EntryInput) error
}

type SubAccount interface {
	// Returns the address of the sub-account
	Address() PostingAddress

	// AccountID returns the identifier of the parent account.
	AccountID() models.NamespacedID

	// Route returns the routing values of the sub-account.
	Route() Route
}

type SubAccountRoute struct {
	// contains filtered or unexported fields
}

type SubAccountRouteData struct {
	ID         string
	RoutingKey RoutingKey
	Route      Route
}

type TaxBehavior string

type Transaction interface {
	Cursor() TransactionCursor
	BookedAt() time.Time
	Entries() []Entry
	ID() models.NamespacedID
	Annotations() models.Annotations
}

type TransactionAuthorizationStatus string

type TransactionCursor struct {
	BookedAt  time.Time
	CreatedAt time.Time
	ID        models.NamespacedID
}

type TransactionDirection string

type TransactionGroup interface {
	ID() models.NamespacedID
	Transactions() []Transaction
	Annotations() models.Annotations
}

type TransactionGroupInput interface {
	Namespace() string
	Transactions() []TransactionInput
	Annotations() models.Annotations
}

type TransactionInput interface {
	BookedAt() time.Time
	EntryInputs() []EntryInput
	Annotations() models.Annotations
	AsGroupInput(namespace string, annotations models.Annotations) TransactionGroupInput
}