@whocomply/ledger 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,590 @@
+interface LedgerClientOptions {
+    /** Ledger API origin, e.g. https://ledger.internal.example.com or http://localhost:8080 */
+    baseUrl: string;
+    /** Tenant slug all requests are scoped to */
+    tenant: string;
+    /** Machine access: sent as X-API-Key. Create keys in the dashboard under Settings. */
+    apiKey?: string;
+    /** User access: sent as Authorization: Bearer. Mostly for dashboards. */
+    token?: string;
+    /** Override fetch (testing, custom agents). Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+    /** Per-request timeout in milliseconds. No timeout when omitted. */
+    timeoutMs?: number;
+    /**
+     * Strict idempotency: posting/reversal/draft methods throw when called
+     * without an explicit idempotencyKey instead of auto-generating one.
+     */
+    requireIdempotencyKey?: boolean;
+}
+/** Per-call options accepted by every SDK method. */
+interface RequestOptions {
+    /** Abort the request (combined with the client timeout when both are set). */
+    signal?: AbortSignal;
+}
+type Query = Record<string, string | number | undefined>;
+interface InternalRequestOptions {
+    query?: Query;
+    body?: unknown;
+    /** Return the raw response text instead of unwrapping the JSON envelope (CSV exports). */
+    raw?: boolean;
+    signal?: AbortSignal;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly fetchImpl;
+    private readonly timeoutMs?;
+    readonly tenant: string;
+    readonly requireIdempotencyKey: boolean;
+    constructor(options: LedgerClientOptions);
+    /** Path inside the tenant scope, e.g. tenantPath('/accounts') */
+    tenantPath(path: string): string;
+    private effectiveSignal;
+    request<T>(method: string, path: string, options?: InternalRequestOptions): Promise<T>;
+}
+
+type AccountType = 'asset' | 'liability' | 'equity' | 'revenue' | 'expense';
+type EntrySide = 'debit' | 'credit';
+type TransactionStatus = 'draft' | 'pending' | 'posted' | 'failed' | 'rejected';
+type PeriodStatus = 'open' | 'closed';
+interface Account {
+    id: string;
+    code: string;
+    name: string;
+    account_type: AccountType;
+    parent_code?: string;
+    currency: string;
+    allow_negative: boolean;
+    is_active: boolean;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateAccountInput {
+    code: string;
+    name: string;
+    account_type: AccountType;
+    parent_code?: string;
+    currency?: string;
+    allow_negative?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateAccountInput {
+    name?: string;
+    allow_negative?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface AccountsPage {
+    accounts: Account[];
+    page: number;
+    page_size: number;
+    total: number;
+    total_pages: number;
+}
+interface ListAccountsParams {
+    accountType?: AccountType;
+    parentCode?: string;
+    currency?: string;
+    search?: string;
+    page?: number;
+    pageSize?: number;
+}
+interface AccountBalance {
+    currency: string;
+    balance: string;
+    version: number;
+}
+interface AsOfBalance {
+    account_id: string;
+    currency: string;
+    balance: string;
+    as_of: string;
+}
+interface AccountStats {
+    total_accounts: number;
+    asset_accounts: number;
+    liability_accounts: number;
+    equity_accounts: number;
+    revenue_accounts: number;
+    expense_accounts: number;
+    currencies_count: number;
+}
+interface EntryLineInput {
+    account_code: string;
+    amount: string;
+    side: EntrySide;
+    currency: string;
+    /** Up to 4 flat string tags, e.g. { product: "wallet", region: "lagos" } */
+    dimensions?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+interface PostEntryInput {
+    description: string;
+    entries: EntryLineInput[];
+    /**
+     * Generated automatically when omitted, unless the client was built with
+     * requireIdempotencyKey: true (then omission throws).
+     */
+    idempotencyKey?: string;
+    reference?: string;
+    /** RFC3339 backdating timestamp; requires the transactions:backdate scope. */
+    postedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Transaction {
+    id: string;
+    idempotency_key: string;
+    description: string;
+    reference?: string;
+    reverses_transaction_id?: string;
+    created_by?: string;
+    approved_by?: string;
+    status: TransactionStatus;
+    posted_at: string;
+    created_at: string;
+    metadata?: Record<string, unknown>;
+}
+interface TransactionLine {
+    id: string;
+    account_id: string;
+    account_code: string;
+    account_name: string;
+    amount: string;
+    side: EntrySide;
+    currency: string;
+    dimensions?: Record<string, string>;
+    created_at: string;
+}
+interface Pagination {
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface TransactionsPage {
+    transactions: Transaction[] | null;
+    pagination: Pagination;
+}
+interface ListTransactionsParams {
+    limit?: number;
+    offset?: number;
+    accountCode?: string;
+    /** Exact match on the consumer-supplied reference (ops lookup path). */
+    reference?: string;
+    /** Attach lines to every row in the same call (no N+1). */
+    includeLines?: boolean;
+    /** Filter by lifecycle state; 'draft' is the approvals queue */
+    status?: TransactionStatus;
+    /** YYYY-MM-DD; requires endDate */
+    startDate?: string;
+    /** YYYY-MM-DD; requires startDate */
+    endDate?: string;
+}
+interface Currency {
+    code: string;
+    name: string;
+    exponent: number;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface RegisterCurrencyInput {
+    code: string;
+    /** Decimal places enforced on postings: NGN 2, USDT 6, BTC 8, ETH 18 */
+    exponent: number;
+    name?: string;
+}
+interface UpdateCurrencyInput {
+    name?: string;
+    exponent?: number;
+    is_active?: boolean;
+}
+interface AccountingPeriod {
+    id: string;
+    name: string;
+    starts_on: string;
+    ends_on: string;
+    status: PeriodStatus;
+    closed_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreatePeriodInput {
+    name: string;
+    /** YYYY-MM-DD */
+    starts_on: string;
+    /** YYYY-MM-DD */
+    ends_on: string;
+}
+interface TrialBalanceRow {
+    account_id: string;
+    code: string;
+    name: string;
+    account_type: AccountType;
+    debit: string;
+    credit: string;
+}
+interface TrialBalanceCurrencyGroup {
+    currency: string;
+    rows: TrialBalanceRow[];
+    total_debit: string;
+    total_credit: string;
+    balanced: boolean;
+}
+interface TrialBalance {
+    as_of: string;
+    currencies: TrialBalanceCurrencyGroup[];
+}
+interface TransactionNote {
+    id: string;
+    author_id?: string;
+    note: string;
+    created_at: string;
+}
+interface StatementRow {
+    account_id: string;
+    code: string;
+    name: string;
+    amount: string;
+}
+interface ProfitAndLossCurrency {
+    currency: string;
+    revenue: StatementRow[] | null;
+    expenses: StatementRow[] | null;
+    total_revenue: string;
+    total_expenses: string;
+    net_income: string;
+}
+interface ProfitAndLoss {
+    start_date: string;
+    end_date: string;
+    currencies: ProfitAndLossCurrency[] | null;
+}
+interface BalanceSheetCurrency {
+    currency: string;
+    assets: StatementRow[] | null;
+    liabilities: StatementRow[] | null;
+    equity: StatementRow[] | null;
+    total_assets: string;
+    total_liabilities: string;
+    total_equity: string;
+    balanced: boolean;
+}
+interface BalanceSheet {
+    as_of: string;
+    currencies: BalanceSheetCurrency[] | null;
+}
+interface GeneralLedgerEntry {
+    transaction_id: string;
+    description: string;
+    reference?: string;
+    posted_at: string;
+    debit: string;
+    credit: string;
+    running_balance: string;
+}
+interface GeneralLedger {
+    account_id: string;
+    code: string;
+    name: string;
+    account_type: AccountType;
+    currency: string;
+    start_date: string;
+    end_date: string;
+    opening_balance: string;
+    entries: GeneralLedgerEntry[] | null;
+    closing_balance: string;
+}
+interface FxPosition {
+    currency: string;
+    assets: string;
+    liabilities: string;
+    net_position: string;
+    rate: string;
+    base_equivalent: string;
+}
+interface FxExposure {
+    as_of: string;
+    base_currency: string;
+    positions: FxPosition[] | null;
+}
+type RecurringFrequency = 'daily' | 'weekly' | 'monthly';
+interface RecurringJournal {
+    id: string;
+    name: string;
+    description: string;
+    reference?: string;
+    frequency: RecurringFrequency;
+    next_run_on: string;
+    last_run_on?: string;
+    is_active: boolean;
+    entries: EntryLineInput[];
+    created_at: string;
+}
+interface CreateRecurringJournalInput {
+    name: string;
+    description: string;
+    reference?: string;
+    frequency: RecurringFrequency;
+    /** YYYY-MM-DD of the first posting */
+    starts_on: string;
+    entries: EntryLineInput[];
+}
+interface ListBalancesParams {
+    limit?: number;
+    offset?: number;
+    codePrefix?: string;
+    codeSuffix?: string;
+    currency?: string;
+    /** Account metadata containment filter, e.g. { org_id: '...' } */
+    metadata?: Record<string, string>;
+}
+interface BulkBalanceRow {
+    account_code: string;
+    currency: string;
+    balance: string;
+    version: number;
+}
+interface BalancesPage {
+    balances: BulkBalanceRow[];
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface LedgerEvent {
+    id: string;
+    sequence: number;
+    type: string;
+    aggregate_type: string;
+    aggregate_id: string;
+    data: unknown;
+    created_at: string;
+}
+interface EventsPage {
+    events: LedgerEvent[];
+    next_cursor: number;
+    has_more: boolean;
+}
+
+declare class AccountsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(input: CreateAccountInput, options?: RequestOptions): Promise<Account>;
+    list(params?: ListAccountsParams, options?: RequestOptions): Promise<AccountsPage>;
+    get(accountId: string, options?: RequestOptions): Promise<Account>;
+    getByCode(code: string, options?: RequestOptions): Promise<Account>;
+    update(accountId: string, input: UpdateAccountInput, options?: RequestOptions): Promise<Account>;
+    deactivate(accountId: string, options?: RequestOptions): Promise<{
+        message: string;
+    }>;
+    /** Current materialized balance. Currency defaults to the tenant base currency. */
+    balance(accountId: string, options?: RequestOptions & {
+        currency?: string;
+    }): Promise<AccountBalance>;
+    /** Journal-derived balance through the end of a past day (YYYY-MM-DD, UTC). */
+    balanceAsOf(accountId: string, asOf: string, options?: RequestOptions & {
+        currency?: string;
+    }): Promise<AsOfBalance>;
+    hierarchy(options?: RequestOptions): Promise<Account[]>;
+    stats(options?: RequestOptions): Promise<AccountStats>;
+}
+
+declare class BalancesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Bulk balances: every (account, currency) row with its monotonic
+     * version. Filter by codePrefix/codeSuffix, currency, or account
+     * metadata containment (e.g. { org_id: '...' }).
+     */
+    list(params?: ListBalancesParams, options?: RequestOptions): Promise<BalancesPage>;
+}
+
+declare class EventsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Durable event feed, strictly ordered by sequence. Poll with
+     * afterId = the last sequence you processed; store next_cursor.
+     */
+    list(params?: {
+        afterId?: number;
+        limit?: number;
+    }, options?: RequestOptions): Promise<EventsPage>;
+}
+
+declare class CurrenciesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Register a currency with its precision policy. Postings beyond the
+     * exponent's decimal places are rejected. Unregistered currencies fall
+     * back to the storage maximum of 18 decimal places.
+     */
+    register(input: RegisterCurrencyInput, options?: RequestOptions): Promise<Currency>;
+    list(options?: RequestOptions): Promise<Currency[]>;
+    update(code: string, input: UpdateCurrencyInput, options?: RequestOptions): Promise<Currency>;
+}
+
+declare class PeriodsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Periods of one tenant may not overlap; violations raise a 409. */
+    create(input: CreatePeriodInput, options?: RequestOptions): Promise<AccountingPeriod>;
+    list(options?: RequestOptions): Promise<AccountingPeriod[]>;
+    /**
+     * Close a period. Enforced by the database: nothing can post into a
+     * closed period, and posting attempts raise a 409.
+     */
+    close(periodId: string, options?: RequestOptions): Promise<AccountingPeriod>;
+    reopen(periodId: string, options?: RequestOptions): Promise<AccountingPeriod>;
+}
+
+declare class RecurringJournalsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Register a repeating journal. Each occurrence posts exactly once: the
+     * worker derives the idempotency key from (schedule id, run date).
+     */
+    create(input: CreateRecurringJournalInput, options?: RequestOptions): Promise<RecurringJournal>;
+    list(options?: RequestOptions): Promise<RecurringJournal[]>;
+    pause(scheduleId: string, options?: RequestOptions): Promise<RecurringJournal>;
+    resume(scheduleId: string, options?: RequestOptions): Promise<RecurringJournal>;
+}
+
+declare class ReportsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Trial balance derived from posted journal lines, grouped by currency.
+     * asOf (YYYY-MM-DD) means "through the end of that day, UTC"; defaults
+     * to now.
+     */
+    trialBalance(options?: RequestOptions & {
+        asOf?: string;
+    }): Promise<TrialBalance>;
+    /** Revenue and expenses over an inclusive date range, optionally filtered by dimensions. */
+    profitAndLoss(options: RequestOptions & {
+        startDate: string;
+        endDate: string;
+        dimensions?: Record<string, string>;
+    }): Promise<ProfitAndLoss>;
+    /** Assets, liabilities, and equity (with computed retained earnings) as of a date. */
+    balanceSheet(options?: RequestOptions & {
+        asOf?: string;
+    }): Promise<BalanceSheet>;
+    /** One account's activity with opening, running, and closing balances. */
+    generalLedger(options: RequestOptions & {
+        accountCode: string;
+        startDate: string;
+        endDate: string;
+        currency?: string;
+    }): Promise<GeneralLedger>;
+    /** Per-currency net positions with base equivalents at the provided rates. */
+    fxExposure(options?: RequestOptions & {
+        rates?: Record<string, string>;
+        asOf?: string;
+    }): Promise<FxExposure>;
+    /**
+     * Posted journals as a Xero manual-journal import CSV (raw string).
+     * Dates are inclusive. Currency defaults to the tenant base currency.
+     */
+    xeroJournalsCsv(options: RequestOptions & {
+        startDate: string;
+        endDate: string;
+        currency?: string;
+    }): Promise<string>;
+}
+
+declare class TransactionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    private idempotencyKey;
+    /**
+     * Post a balanced double-entry transaction. Debits must equal credits per
+     * currency or the API rejects with UNBALANCED_TRANSACTION. posted_at
+     * backdates the posting and requires the transactions:backdate scope.
+     */
+    post(input: PostEntryInput, options?: RequestOptions): Promise<Transaction>;
+    get(transactionId: string, options?: RequestOptions & {
+        includeLines?: boolean;
+    }): Promise<Transaction>;
+    lines(transactionId: string, options?: RequestOptions): Promise<TransactionLine[]>;
+    list(params?: ListTransactionsParams, options?: RequestOptions): Promise<TransactionsPage>;
+    /**
+     * Maker-checker: store a fully validated entry with zero balance impact.
+     * Balances apply only when a DIFFERENT actor approves.
+     */
+    draft(input: PostEntryInput, options?: RequestOptions): Promise<Transaction>;
+    /** Approve a draft (requires the transactions:approve scope and a different actor). */
+    approve(transactionId: string, options?: RequestOptions): Promise<Transaction>;
+    /** Reject a draft; it never had balance impact. */
+    reject(transactionId: string, options?: RequestOptions): Promise<Transaction>;
+    /** Append an immutable note (audit support). */
+    addNote(transactionId: string, note: string, options?: RequestOptions): Promise<TransactionNote>;
+    listNotes(transactionId: string, options?: RequestOptions): Promise<TransactionNote[]>;
+    /**
+     * Post a reversal: a new transaction mirroring the original with debits
+     * and credits swapped, linked via reverses_transaction_id. A transaction
+     * can be reversed at most once; a second attempt raises ALREADY_REVERSED.
+     */
+    reverse(transactionId: string, reverseOptions?: {
+        idempotencyKey?: string;
+        description?: string;
+        metadata?: Record<string, unknown>;
+    }, options?: RequestOptions): Promise<Transaction>;
+}
+
+/** Stable machine-readable error codes; branch on these, never on message text. */
+type LedgerErrorCode = 'INSUFFICIENT_BALANCE' | 'UNBALANCED_TRANSACTION' | 'AMOUNT_PRECISION' | 'AMOUNT_TOO_LARGE' | 'CURRENCY_DEACTIVATED' | 'CURRENCY_PRECISION' | 'PERIOD_CLOSED' | 'ALREADY_REVERSED' | 'CANNOT_REVERSE_UNPOSTED' | 'ACCOUNT_NOT_FOUND' | 'ACCOUNT_EXISTS' | 'IDEMPOTENCY_CONFLICT' | 'VALIDATION_ERROR' | 'NOT_DRAFT' | 'SELF_APPROVAL' | 'TRANSACTION_NOT_FOUND' | (string & {});
+/** Structured detail attached to INSUFFICIENT_BALANCE errors. */
+interface InsufficientBalanceDetails {
+    account_code: string;
+    currency: string;
+    /** Decimal strings; render customer copy from these, never parse prose. */
+    attempted: string;
+    available: string;
+}
+/** Error raised for any non-success response from the ledger API. */
+declare class LedgerApiError extends Error {
+    /** HTTP status code */
+    readonly status: number;
+    /** Alias for status, per the Alphaex integration contract. */
+    readonly httpStatus: number;
+    /** Stable machine-readable code (absent on transport-level failures). */
+    readonly code?: LedgerErrorCode;
+    /** Structured error context (e.g. InsufficientBalanceDetails). */
+    readonly details?: unknown;
+    /** Raw response body, when one could be read */
+    readonly body?: unknown;
+    constructor(status: number, message: string, options?: {
+        code?: string;
+        details?: unknown;
+        body?: unknown;
+    });
+    /** True for 409s: double reversals, closed periods, existing resources. */
+    get isConflict(): boolean;
+    /** Typed accessor for INSUFFICIENT_BALANCE detail. */
+    get insufficientBalance(): InsufficientBalanceDetails | undefined;
+}
+/** Thrown in strict idempotency mode when a mutating call omits the key. */
+declare class MissingIdempotencyKeyError extends Error {
+    constructor(method: string);
+}
+
+declare class LedgerClient {
+    readonly accounts: AccountsResource;
+    readonly balances: BalancesResource;
+    readonly events: EventsResource;
+    readonly transactions: TransactionsResource;
+    readonly currencies: CurrenciesResource;
+    readonly periods: PeriodsResource;
+    readonly recurringJournals: RecurringJournalsResource;
+    readonly reports: ReportsResource;
+    constructor(options: LedgerClientOptions);
+}
+
+export { type Account, type AccountBalance, type AccountStats, type AccountType, type AccountingPeriod, type AccountsPage, type AsOfBalance, type BalanceSheet, type BalanceSheetCurrency, type BalancesPage, type BulkBalanceRow, type CreateAccountInput, type CreatePeriodInput, type CreateRecurringJournalInput, type Currency, type EntryLineInput, type EntrySide, type EventsPage, type FxExposure, type FxPosition, type GeneralLedger, type GeneralLedgerEntry, type InsufficientBalanceDetails, LedgerApiError, LedgerClient, type LedgerClientOptions, type LedgerErrorCode, type LedgerEvent, type ListAccountsParams, type ListBalancesParams, type ListTransactionsParams, MissingIdempotencyKeyError, type Pagination, type PeriodStatus, type PostEntryInput, type ProfitAndLoss, type ProfitAndLossCurrency, type RecurringFrequency, type RecurringJournal, type RegisterCurrencyInput, type RequestOptions, type StatementRow, type Transaction, type TransactionLine, type TransactionNote, type TransactionStatus, type TransactionsPage, type TrialBalance, type TrialBalanceCurrencyGroup, type TrialBalanceRow, type UpdateAccountInput, type UpdateCurrencyInput };