@classytic/ledger 0.10.3 → 0.11.0

package/dist/sync/index.d.mts

@@ -1,324 +0,0 @@
-import { a as ImportMapper, c as JournalItemInput, i as ImportError, l as WireExportArgs, n as ExportSink, o as ImportReport, r as ImportContext, s as JournalEntryInput, t as ExportReport, u as WireImportArgs } from "../sync-JvchM3FO.mjs";
-import { CanonicalInvoice, CanonicalJournalEntry, CanonicalTransaction } from "@classytic/fin-io";
-
-//#region src/sync/builders/opening-balance.d.ts
-interface OpeningBalanceInput {
-  /** Cutover date — typically the start of fiscal year.
-   *  The opening balance entry is dated on this day. */
-  cutoverDate: Date;
-  /**
-   * Account balances in integer cents (minor units), signed:
-   *   - Positive = normal debit balance (assets, expenses)
-   *   - Negative = normal credit balance (liabilities, equity, revenue)
-   *
-   * Callers should include balance sheet accounts only (assets, liabilities,
-   * equity). P&L cumulative effect belongs in retained earnings (the equity
-   * contra account) — this matches the Odoo and Beancount convention.
-   *
-   * The `accountCode` is opaque at this layer — it can be a GIFI code, a
-   * custom account number, or an ObjectId string. The consumer resolves it.
-   */
-  balances: ReadonlyArray<{
-    accountCode: string; /** Signed balance in integer cents. */
-    balance: number;
-  }>;
-  /**
-   * The equity account that absorbs the difference. Typically:
-   *   - CA: '3600' (Retained Earnings)
-   *   - BD: '3310' (Retained Earnings)
-   *   - Generic: 'Opening Balance Equity'
-   *
-   * This follows Odoo's pattern (unaffected earnings) rather than ERPNext's
-   * temporary account, because the retained earnings approach is
-   * audit-clean and doesn't require a zeroing-out step.
-   */
-  equityAccountCode: string;
-  /** Optional label. Defaults to 'Opening Balance — Cutover YYYY-MM-DD'. */
-  label?: string;
-}
-interface OpeningBalanceResult {
-  /** The journal entry input, ready for `journalEntries.create()`. */
-  entry: JournalEntryInput;
-  /** The net residual posted to the equity account.
-   *  Should be zero for a balanced trial balance.
-   *  Non-zero means the TB was unbalanced — the equity account absorbs it. */
-  residual: number;
-  /** Number of account lines (excluding the equity contra line). */
-  lineCount: number;
-}
-declare function buildOpeningBalanceEntry(input: OpeningBalanceInput): OpeningBalanceResult;
-//#endregion
-//#region src/sync/ledger-bridge.d.ts
-/**
- * createLedgerBridge — adapter between @classytic/invoice's LedgerBridge
- * contract and @classytic/ledger's Record API.
- *
- * This is the glue layer that lets the invoice engine post journal entries,
- * record payments, and reverse entries through the ledger engine without
- * either package depending on the other.
- *
- * @example
- * ```typescript
- * import { createAccountingEngine } from '@classytic/ledger';
- * import { createLedgerBridge } from '@classytic/ledger/sync';
- * import { createInvoiceEngine } from '@classytic/invoice';
- *
- * const accounting = createAccountingEngine({ ... });
- *
- * const invoicing = createInvoiceEngine({
- *   ledger: createLedgerBridge(accounting, {
- *     accounts: {
- *       receivable: '1200',   // Accounts Receivable
- *       payable: '2000',      // Accounts Payable
- *       revenue: '4000',      // Revenue
- *       expense: '5000',      // Cost of Goods / Expenses
- *       taxPayable: '2100',   // Tax Payable (sales tax collected)
- *       taxReceivable: '1150', // Tax Receivable (purchase tax paid)
- *       cash: '1000',         // Cash / Bank
- *     },
- *   }),
- * });
- * ```
- *
- * The bridge maps each invoice moveType to the correct accounting entries:
- *
- *   out_invoice  → DR Receivable, CR Revenue per line, CR Tax Payable
- *   in_invoice   → DR Expense per line, DR Tax Receivable, CR Payable
- *   out_refund   → CR Receivable, DR Revenue per line, DR Tax Payable
- *   in_refund    → DR Payable, CR Expense per line, CR Tax Receivable
- *   receipt      → DR Cash/Receivable, CR Revenue per line, CR Tax Payable
- *
- * All amounts are integer cents. The bridge uses `record.adjustment()` for
- * multi-line entries (invoices with tax) and `record.payment()` for payment
- * recording.
- */
-/** Account code mapping — tells the bridge which ledger accounts to use. */
-interface LedgerBridgeAccounts {
-  /** Accounts Receivable (e.g. '1200'). Used for customer invoices + receipts. */
-  receivable: string;
-  /** Accounts Payable (e.g. '2000'). Used for vendor bills. */
-  payable: string;
-  /** Default revenue account (e.g. '4000'). Used for sales line items. */
-  revenue: string;
-  /** Default expense account (e.g. '5000'). Used for purchase line items. */
-  expense: string;
-  /** Tax payable / tax liability (e.g. '2100'). Sales tax collected. */
-  taxPayable: string;
-  /** Tax receivable / input tax (e.g. '1150'). Purchase tax paid. */
-  taxReceivable: string;
-  /** Cash / bank account (e.g. '1000'). Used for payments. */
-  cash: string;
-}
-interface LedgerBridgeConfig {
-  /** Account code mapping. */
-  accounts: LedgerBridgeAccounts;
-  /**
-   * Override the debit account for receipts (POS).
-   * Defaults to `accounts.receivable`. Set to `accounts.cash` if receipts
-   * are immediately paid (no AR).
-   */
-  receiptAccount?: string;
-  /**
-   * Custom resolver for payment accounts. When provided, the bridge calls
-   * this instead of using the default receivable/cash mapping.
-   *
-   * Use this when the invoice engine doesn't track moveType on payments
-   * and you need to determine AR vs AP based on context.
-   */
-  resolvePaymentAccounts?: (input: LedgerPaymentInput) => {
-    receivableOrPayable: string;
-    cash: string;
-  };
-}
-type MoveType = 'out_invoice' | 'in_invoice' | 'out_refund' | 'in_refund' | 'receipt';
-interface LedgerPostInput {
-  organizationId?: string;
-  invoiceId: string;
-  moveType: MoveType;
-  partnerId: string;
-  date: Date;
-  currency: string;
-  lines: LedgerPostLine[];
-  totalAmount: number;
-  taxAmount: number;
-  notes?: string;
-  idempotencyKey?: string;
-}
-interface LedgerPostLine {
-  description: string;
-  amount: number;
-  taxAmount: number;
-  taxCode?: string;
-  productId?: string;
-}
-interface LedgerPaymentInput {
-  organizationId?: string;
-  invoiceId: string;
-  paymentId: string;
-  amount: number;
-  currency: string;
-  date: Date;
-  method: string;
-}
-/**
- * The LedgerBridge interface that @classytic/invoice expects.
- * This is the contract — createLedgerBridge() returns an implementation.
- */
-interface LedgerBridge {
-  createJournalEntry(input: LedgerPostInput): Promise<string>;
-  reverseJournalEntry(journalEntryId: string, reason: string, ctx: LedgerReverseContext): Promise<string>;
-  recordPayment(input: LedgerPaymentInput): Promise<string>;
-}
-/**
- * Context threaded from the invoice engine into the ledger reversal call.
- * Required so the ledger can stamp `reversedByUser` and satisfy strict-mode
- * `requireActor` / multi-tenant guards.
- */
-interface LedgerReverseContext {
-  organizationId?: string;
-  actorId?: string;
-  session?: unknown;
-}
-interface AdjustmentLine {
-  account: string;
-  debit?: number;
-  credit?: number;
-  label?: string;
-}
-interface RecordAPILike {
-  adjustment(organizationId: unknown, input: {
-    date: Date;
-    lines: AdjustmentLine[];
-    label?: string;
-    journalType?: string;
-  }, options?: {
-    idempotencyKey?: string;
-    [key: string]: unknown;
-  }): Promise<unknown>;
-  payment(organizationId: unknown, input: {
-    date: Date;
-    amount: number;
-    fromReceivableAccount: string;
-    toCashAccount: string;
-    label?: string;
-  }, options?: {
-    idempotencyKey?: string;
-    [key: string]: unknown;
-  }): Promise<unknown>;
-}
-interface JournalEntryRepoLike {
-  reverse(id: unknown, orgId?: unknown, options?: {
-    actorId?: string;
-    session?: unknown;
-    reversalDate?: Date;
-  }): Promise<{
-    original: {
-      _id: unknown;
-    };
-    reversal: {
-      _id: unknown;
-    };
-  }>;
-}
-interface EngineLike {
-  record: RecordAPILike;
-  repositories: {
-    journalEntries: JournalEntryRepoLike;
-  };
-}
-/**
- * Create a LedgerBridge implementation backed by a @classytic/ledger engine.
- *
- * @param engine - The accounting engine (or any object matching the minimal
- *   shape: `{ record: { adjustment, payment }, repositories: { journalEntries: { reverse } } }`)
- * @param config - Account mapping configuration
- * @returns A LedgerBridge that the invoice engine can use
- */
-declare function createLedgerBridge(engine: EngineLike, config: LedgerBridgeConfig): LedgerBridge;
-//#endregion
-//#region src/sync/mappers/bank-statement.d.ts
-interface BankStatementMapperConfig {
-  /** ObjectId of the bank/cash account (debit side for inflows, credit side for outflows). */
-  bankAccountId: unknown;
-  /** ObjectId of the suspense/unclassified account (the other side). */
-  suspenseAccountId: unknown;
-  /**
-   * Optional categorization callback. Given a CanonicalTransaction, return
-   * the ObjectId of a more specific counter-account (e.g. rent, utilities,
-   * payroll). If returns undefined, suspenseAccountId is used.
-   *
-   * This is where AI categorization or a rules engine plugs in.
-   */
-  categorize?: (txn: CanonicalTransaction) => unknown | undefined;
-  /** Label prefix for imported entries. Default: 'Import'. */
-  labelPrefix?: string;
-}
-declare function bankStatementMapper(config: BankStatementMapperConfig): ImportMapper<CanonicalTransaction>;
-//#endregion
-//#region src/sync/mappers/invoice.d.ts
-interface InvoiceMapperConfig {
-  /** ObjectId for Accounts Receivable (sales) or Accounts Payable (purchase). */
-  receivablesAccountId: unknown;
-  payablesAccountId: unknown;
-  /** Default revenue account (used when invoice line has no accountCode). */
-  defaultRevenueAccountId: unknown;
-  /** Default expense account. */
-  defaultExpenseAccountId: unknown;
-  /** Tax liability account (for sales tax collected). */
-  taxLiabilityAccountId?: unknown;
-  /** Tax receivable account (for purchase tax paid). */
-  taxReceivableAccountId?: unknown;
-  /** Map accountCode from the source to a ledger Account ObjectId. */
-  resolveAccountCode?: (code: string) => unknown | undefined;
-}
-declare function invoiceMapper(config: InvoiceMapperConfig): ImportMapper<CanonicalInvoice>;
-//#endregion
-//#region src/sync/mappers/journal-entry.d.ts
-interface JournalEntryMapperConfig {
-  /** Map accountCode from the source to a ledger Account ObjectId. */
-  resolveAccountCode: (code: string) => unknown;
-}
-declare function journalEntryMapper(config: JournalEntryMapperConfig): ImportMapper<CanonicalJournalEntry>;
-//#endregion
-//#region src/sync/mappers/opening-balance.d.ts
-/** Minimal trial balance shape — matches CanonicalTrialBalance from fin-io
- *  but defined locally to avoid a hard dependency on fin-io. Any object
- *  matching this shape works. */
-interface TrialBalanceInput {
-  asOfDate: Date;
-  currency: string;
-  lines: ReadonlyArray<{
-    accountCode: string;
-    accountName: string;
-    debit?: {
-      amount: bigint;
-      currency: string;
-    };
-    credit?: {
-      amount: bigint;
-      currency: string;
-    };
-  }>;
-}
-interface OpeningBalanceMapperConfig {
-  /** Resolve an account type code to a ledger Account ObjectId (or any ID).
-   *  Return `undefined` to skip an account line. */
-  resolveAccountCode: (code: string) => unknown | undefined;
-  /** The ObjectId of the equity/retained earnings account. */
-  equityAccountId: unknown;
-  /** Cutover date for the opening balance entry. */
-  cutoverDate: Date;
-}
-declare function openingBalanceMapper(config: OpeningBalanceMapperConfig): ImportMapper<TrialBalanceInput>;
-//#endregion
-//#region src/sync/wire-export.d.ts
-declare function wireExport<TOut>(args: WireExportArgs<TOut>): {
-  run(): Promise<ExportReport>;
-};
-//#endregion
-//#region src/sync/wire-import.d.ts
-declare function wireImport<TRaw>(args: WireImportArgs<TRaw>): {
-  run(): Promise<ImportReport>;
-};
-//#endregion
-export { type BankStatementMapperConfig, type ExportReport, type ExportSink, type ImportContext, type ImportError, type ImportMapper, type ImportReport, type InvoiceMapperConfig, type JournalEntryInput, type JournalEntryMapperConfig, type JournalItemInput, type LedgerBridge, type LedgerBridgeAccounts, type LedgerBridgeConfig, type LedgerPaymentInput, type LedgerPostInput, type LedgerPostLine, type LedgerReverseContext, type OpeningBalanceInput, type OpeningBalanceMapperConfig, type OpeningBalanceResult, type TrialBalanceInput, type WireExportArgs, type WireImportArgs, bankStatementMapper, buildOpeningBalanceEntry, createLedgerBridge, invoiceMapper, journalEntryMapper, openingBalanceMapper, wireExport, wireImport };