@casual-simulation/aux-records 3.8.1 → 3.10.2

package/financial/FinancialController.d.ts

@@ -0,0 +1,272 @@
+import type { MultiError, Result, ServerError, SimpleError } from '@casual-simulation/aux-common';
+import { AccountBalance } from '@casual-simulation/aux-common';
+import type { InterfaceTransferError, TransferCodes } from './FinancialInterface';
+import { AccountCodes, LEDGERS, type FinancialInterface } from './FinancialInterface';
+import type { Account, Transfer } from 'tigerbeetle-node';
+import { TransferFlags } from 'tigerbeetle-node';
+import type { FinancialAccount, FinancialAccountFilter, FinancialStore, UniqueFinancialAccountFilter } from './FinancialStore';
+export declare class FinancialController {
+    private _financialInterface;
+    private _idempotentKeyMaxAgeMS;
+    private _financialStore;
+    constructor(financialInterface: FinancialInterface, financialStore: FinancialStore);
+    init(): Promise<Result<void, SimpleError>>;
+    generateId(): bigint;
+    /**
+     * Creates a new account with the given code.
+     * For internal use only.
+     * @param code The code for the new account.
+     * @param ledger The ledger for the new account.
+     */
+    createAccount(code: AccountCodes, ledger: (typeof LEDGERS)[keyof typeof LEDGERS]): Promise<CreateFinancialAccountResult>;
+    /**
+     * Gets the account with the given ID.
+     * @param accountId The ID of the account to get.
+     * @returns
+     */
+    getAccount(accountId: bigint | string): Promise<Result<Account, SimpleError>>;
+    getTransfer(transferId: bigint | string): Promise<Result<Transfer, SimpleError>>;
+    /**
+     * Gets the details for the financial account with the given ID.
+     * @param accountId The ID of the account to get details for.
+     */
+    getAccountDetails(accountId: bigint | string): Promise<GetFinancialAccountResult>;
+    /**
+     * Attempts to get the financial account for the given filter.
+     * @param filter The filter to use.
+     */
+    getFinancialAccount(filter: UniqueFinancialAccountFilter): Promise<GetFinancialAccountResult>;
+    /**
+     * Gets or creates a financial account for the given filter.
+     * @param filter The filter to use.
+     */
+    getOrCreateFinancialAccount(filter: UniqueFinancialAccountFilter): Promise<GetFinancialAccountResult>;
+    /**
+     * Gets the list of accounts for the given filter.
+     * @param filter The filter to use.
+     */
+    listAccounts(filter: FinancialAccountFilter): Promise<GetAccountsResult>;
+    /**
+     * Gets the account balances for the given account filter.
+     * @param filter The filter to use.
+     */
+    getAccountBalances(filter: Omit<UniqueFinancialAccountFilter, 'ledger'>): Promise<Result<AccountBalances | undefined, SimpleError>>;
+    /**
+     * Gets the balance for the account matching the given filter.
+     * @param filter The filter to use.
+     */
+    getAccountBalance(filter: UniqueFinancialAccountFilter): Promise<Result<AccountBalance | undefined, SimpleError>>;
+    /**
+     * Converts the given account data to an account balance.
+     * @param account The account to convert.
+     */
+    convertToAccountBalance(account: Account): AccountBalance;
+    /**
+     * Transfers funds between two internal accounts.
+     * Suitable for moving money between user accounts and contracts.
+     * Not suitable for interfacing with external systems such as Stripe.
+     *
+     * Not for public use.
+     * @param request The request for the transfer.
+     */
+    internalTransaction(request: InternalTransferRequest): Promise<TransferResult>;
+    completePendingTransfers(request: PostTransfersRequest): Promise<TransferResult>;
+    listTransfers(accountId: bigint | string): Promise<Result<Transfer[], SimpleError>>;
+    queryTransfers(query: TransfersQuery): Promise<Result<Transfer[], SimpleError>>;
+    private _processTransferResult;
+}
+/**
+ * Gets the balance of the given account.
+ *
+ * For asset accounts, the balance is calculated as: debits_posted - credits_posted.
+ * For liability accounts, the balance is calculated as: credits_posted - debits_posted.
+ * For revenue accounts, the balance is calculated as: credits_posted - debits_posted.
+ *
+ * @param account The account to get the balance of.
+ * @returns
+ */
+export declare function getAccountBalance(account: Account): number;
+/**
+ * Gets the balance of the given liability account.
+ * For liability accounts, the balance is calculated as: credits_posted - debits_posted.
+ * @param account The account to get the balance of.
+ */
+export declare function getLiabilityAccountBalance(account: Account): number;
+/**
+ * Gets the balance of the given asset account.
+ * For asset accounts, the balance is calculated as: debits_posted - credits_posted.
+ * @param account The account to get the balance of.
+ */
+export declare function getAssetAccountBalance(account: Account): number;
+/**
+ * Gets the balance of the given liquidity pool account.
+ * For liquidity accounts, the balance is calculated as: debits_posted - credits_posted.
+ * @param account The account to get the balance of.
+ */
+export declare function getLiquidityPoolBalance(account: Account): number;
+export type CreateFinancialAccountResult = Result<{
+    /**
+     * The ID of the account that was created.
+     */
+    id: string;
+}, SimpleError>;
+export interface AccountWithDetails {
+    account: Account;
+    financialAccount: FinancialAccount;
+}
+export type GetFinancialAccountResult = Result<AccountWithDetails, SimpleError>;
+export type GetAccountsResult = Result<{
+    accounts: Account[];
+}, MultiError<SimpleError>>;
+export type TransferError = {
+    errorCode: ServerError | 'debits_exceed_credits' | 'credits_exceed_debits' | 'invalid_transfer' | 'unsupported_currency' | 'transfer_already_exists' | 'transfer_already_completed';
+    errorMessage: string;
+    /**
+     * The ID of the account that had the issue.
+     */
+    accountId?: string;
+    /**
+     * The errors that occurred during the transfer.
+     */
+    errors: Omit<InterfaceTransferError, 'transfer'>[];
+};
+export type InternalTransfer = PendingTransfer | NonPendingTransfer;
+export interface InternalTransferBase {
+    /**
+     * The ID of the transfer that should be created.
+     * If null, then a new transfer will be created.
+     */
+    transferId?: bigint | string | null;
+    /**
+     * The ID of the account that is being debited.
+     */
+    debitAccountId: bigint | string;
+    /**
+     * The ID of the account that is being credited.
+     */
+    creditAccountId: bigint | string;
+    /**
+     * The amount of the transfer.
+     */
+    amount: bigint | number;
+    /**
+     * The currency of the transfer.
+     */
+    currency: string;
+    /**
+     * The code of the transfer.
+     */
+    code: TransferCodes;
+    /**
+     * Whether the transfer is a balancing credit or not.
+     *
+     * Balancing credits are used to transfer at most amount — automatically transferring less than amount as necessary such that `credit_account.credits_pending + credit_account.credits_posted ≤ credit_account.debits_posted`.
+     *
+     * Defaults to false.
+     */
+    balancingCredit?: boolean;
+    /**
+     * Whether the transfer is a balancing debit or not.
+     *
+     * Transfer at most amount — automatically transferring less than amount as necessary such that `debit_account.debits_pending + debit_account.debits_posted ≤ debit_account.credits_posted`.
+     *
+     * Defaults to false.
+     */
+    balancingDebit?: boolean;
+    /**
+     * Wether to mark the debit account as closed after this transfer is processed.
+     * If set, then the transfer will automatically be marked as pending.
+     */
+    closingDebit?: boolean;
+    /**
+     * Wether to mark the credit account as closed after this transfer is processed.
+     * If set, then the transfer will automatically be marked as pending.
+     */
+    closingCredit?: boolean;
+}
+export interface NonPendingTransfer extends InternalTransferBase {
+    /**
+     * Non-pending transfers cannot have a pending state.
+     */
+    pending?: never;
+    timeoutSeconds?: never;
+}
+/**
+ * A transfer that is pending completion.
+ */
+export interface PendingTransfer extends InternalTransferBase {
+    /**
+     * Wether the transfer is pending or not.
+     */
+    pending: true;
+    /**
+     * The number of seconds before the pending transfer times out.
+     *
+     * All pending transfers must have a timeout.
+     */
+    timeoutSeconds: number;
+}
+export interface InternalTransferRequest {
+    /**
+     * The transfers that should be performed in a transcation.
+     */
+    transfers: InternalTransfer[];
+    /**
+     * The ID of the transaction that should be created.
+     * If null, then a new transaction will be created.
+     */
+    transactionId?: bigint | string | null;
+}
+export interface PostTransfersRequest {
+    /**
+     * The transfers that should be performed in a transcation.
+     */
+    transfers: (string | bigint)[];
+    /**
+     * The ID of the transaction that should be created.
+     */
+    transactionId?: bigint | string | null;
+    /**
+     * The flags to set on the transfers.
+     * If not specified, then post_pending_transfer will be set.
+     */
+    flags?: TransferFlags;
+}
+export type TransferResult = Result<{
+    /**
+     * The IDs of the transfers that were created.
+     */
+    transferIds: string[];
+    /**
+     * The ID of the transaction that was created.
+     */
+    transactionId: string;
+}, TransferError>;
+export interface TransfersQuery {
+    /**
+     * The ID of the transaction to query transfers for.
+     */
+    transactionId?: bigint | string;
+    /**
+     * The code to fitler transfers by.
+     */
+    code?: TransferCodes;
+}
+/**
+ * Represents the balances of a user/studio/contract's financial accounts.
+ */
+export interface AccountBalances {
+    /**
+     * The USD account balance.
+     *
+     * This will be undefined if the user does not have a USD account.
+     */
+    usd: AccountBalance | undefined;
+    /**
+     * The credits account balance.
+     *
+     * This will be undefined if the user does not have a credits account.
+     */
+    credits: AccountBalance | undefined;
+}
+//# sourceMappingURL=FinancialController.d.ts.map