@happyvertical/smrt-commerce 0.55.24 → 0.56.1

package/dist/tax/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/tax/identity.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,EAClD,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAajB;AAED,gFAAgF;AAChF,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GACxC,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/tax/index.d.ts

@@ -0,0 +1,4 @@
+export { applyCommerceCookbookSettings, applyCookbookTaxSettings, type CookbookTaxSettingsInput, cookbookTaxSettings, } from './cookbook.js';
+export { applyTaxCodeExamplePack, COMMON_TAX_CODE_EXAMPLE_PACK, type TaxCodeExamplePack, } from './example-pack.js';
+export { ensureTenantTaxCodes, type LegacyTaxMapReport, type LegacyTaxRateRow, type MapLegacyTaxRatesOptions, mapLegacyTaxRates, mapLegacyTaxRatesInTransaction, } from './legacy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tax/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tax/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,iBAAiB,EACjB,8BAA8B,GAC/B,MAAM,aAAa,CAAC"}

package/dist/tax/legacy.d.ts

@@ -0,0 +1,48 @@
+import type { DatabaseInterface } from '@happyvertical/smrt-core/migrations';
+import type { TaxCode } from '../models/TaxCode.js';
+export interface LegacyTaxMapReport {
+    tenantId: string;
+    createdComponents: number;
+    createdCodes: number;
+    missingLiabilityAccountComponentIds: string[];
+    /** Every legacy source rate and the durable tax code selected for it. */
+    mappings: Array<{
+        sourceRate: string;
+        taxCodeId: string;
+        taxComponentId: string | null;
+    }>;
+    /** Invalid legacy rates are retained through `legacy-unreconciled`. */
+    unreconciledRates: string[];
+}
+export interface MapLegacyTaxRatesOptions {
+    /** Limit a resumable migration to one tenant. Omit only for a system admin run. */
+    tenantId?: string;
+}
+export interface LegacyTaxRateRow {
+    tenantId?: string;
+    tenant_id?: string;
+    taxRate?: unknown;
+    tax_rate?: unknown;
+    customerTaxExempt?: unknown;
+    customer_tax_exempt?: unknown;
+}
+/**
+ * Ensure the three non-taxable codes every tenant needs. Repeating the call is
+ * safe; callers must use a transaction-capable database so the check/create
+ * sequence is atomic with their surrounding migration.
+ */
+export declare function ensureTenantTaxCodes(db: DatabaseInterface, tenantId: string): Promise<TaxCode[]>;
+/**
+ * Map old fractional line tax rates to rate components and one-component tax
+ * codes. A historical zero means no tax was applied, therefore it maps to
+ * out-of-scope unless the linked customer was explicitly exempt.
+ */
+export declare function mapLegacyTaxRates(db: DatabaseInterface, options?: MapLegacyTaxRatesOptions): Promise<LegacyTaxMapReport[]>;
+/**
+ * Executor-affine mapping entry point for a caller that already owns an open
+ * transaction. It never opens or commits a nested transaction. `tenantRows`
+ * are supplied by the wrapper after its source read so each tenant remains
+ * isolated and a failed mapping rolls back as one unit.
+ */
+export declare function mapLegacyTaxRatesInTransaction(tx: DatabaseInterface, tenantId: string, tenantRows: readonly LegacyTaxRateRow[]): Promise<LegacyTaxMapReport>;
+//# sourceMappingURL=legacy.d.ts.map

package/dist/tax/legacy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy.d.ts","sourceRoot":"","sources":["../../src/tax/legacy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAI7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,mCAAmC,EAAE,MAAM,EAAE,CAAC;IAC9C,yEAAyE;IACzE,QAAQ,EAAE,KAAK,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,CAAC,CAAC;IACH,uEAAuE;IACvE,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAgCD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,EAAE,CAAC,CAsEpB;AAmCD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,iBAAiB,EACrB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAkB/B;AAED;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAClD,EAAE,EAAE,iBAAiB,EACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,SAAS,gBAAgB,EAAE,GACtC,OAAO,CAAC,kBAAkB,CAAC,CAyF7B"}

package/dist/tax-summary-report-adapter.d.ts

@@ -0,0 +1,37 @@
+/** Existing report adapter/DataTable bridge for the commerce tax summary. */
+import type { DatabaseInterface } from '@happyvertical/smrt-core/migrations';
+import { type MaterializedReportDrilldownPresentation, type MaterializedReportHost, type MaterializedReportHostContext, type ReportAdapterDescriptor, type ReportAdapterOptions } from '@happyvertical/smrt-reports';
+import { type TaxSummaryContributorDrilldown, type TaxSummaryContributorDrilldownOptions, type TaxSummaryExpenseSource, type TaxSummaryInvoiceDrilldownOptions, type TaxSummaryLedgerDrilldownSource } from './collections/TaxSummaryReportCollection.js';
+import type { TaxSummaryComponentMapping } from './tax-summary.js';
+export declare const TAX_SUMMARY_REPORT_ADAPTER: ReportAdapterOptions;
+/** Tenant-bound owner dependencies used only while resolving a selected cell. */
+export interface TaxSummaryMaterializedReportDrilldownSources {
+    expenseSource?: TaxSummaryExpenseSource;
+    ledgerSource?: TaxSummaryLedgerDrilldownSource;
+    expenseComponentMappings?: readonly TaxSummaryComponentMapping[];
+}
+export interface TaxSummaryMaterializedReportHostOptions {
+    /**
+     * Resolve owner collections from the authenticated route context for each
+     * drilldown. A fixed source is intentionally unsupported so one tenant's
+     * collection cannot bleed into another request.
+     */
+    drilldownSources?: (context: Readonly<MaterializedReportHostContext>) => TaxSummaryMaterializedReportDrilldownSources | Promise<TaxSummaryMaterializedReportDrilldownSources>;
+}
+/** Normalize commerce source facts before a generic report route serializes them. */
+export declare function presentTaxSummaryDrilldown(drilldown: TaxSummaryContributorDrilldown): MaterializedReportDrilldownPresentation;
+/** Create a fixed, server-only tax-summary host for an authenticated template route. */
+export declare function createTaxSummaryMaterializedReportHost(database: DatabaseInterface | (() => Promise<DatabaseInterface>), options?: TaxSummaryMaterializedReportHostOptions): MaterializedReportHost<MaterializedReportDrilldownPresentation>;
+/** Descriptor consumed by the registered report runtime and DataTable host. */
+export declare function buildTaxSummaryReportAdapterDescriptor(): Promise<ReportAdapterDescriptor>;
+/**
+ * Application drilldown bridge. Callers obtain tenantId from their authenticated
+ * principal and must not use a tenant value supplied by the report row.
+ */
+export declare function drilldownTaxSummaryInvoiceFacts(db: DatabaseInterface, options: TaxSummaryInvoiceDrilldownOptions): Promise<import("./index.js").DocumentTaxReportFact[]>;
+/**
+ * Application bridge for a specific report cell. Expense and ledger owners are
+ * injected by the host so commerce does not create a package dependency cycle.
+ */
+export declare function drilldownTaxSummaryContributors(db: DatabaseInterface, options: TaxSummaryContributorDrilldownOptions): Promise<TaxSummaryContributorDrilldown>;
+//# sourceMappingURL=tax-summary-report-adapter.d.ts.map

package/dist/tax-summary-report-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tax-summary-report-adapter.d.ts","sourceRoot":"","sources":["../src/tax-summary-report-adapter.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAIL,KAAK,uCAAuC,EAE5C,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAElC,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAC1B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,KAAK,8BAA8B,EACnC,KAAK,qCAAqC,EAC1C,KAAK,uBAAuB,EAC5B,KAAK,iCAAiC,EACtC,KAAK,+BAA+B,EAGrC,MAAM,6CAA6C,CAAC;AAErD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAEnE,eAAO,MAAM,0BAA0B,EAAE,oBAoBxC,CAAC;AAEF,iFAAiF;AACjF,MAAM,WAAW,4CAA4C;IAC3D,aAAa,CAAC,EAAE,uBAAuB,CAAC;IACxC,YAAY,CAAC,EAAE,+BAA+B,CAAC;IAC/C,wBAAwB,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAClE;AAED,MAAM,WAAW,uCAAuC;IACtD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CACjB,OAAO,EAAE,QAAQ,CAAC,6BAA6B,CAAC,KAE9C,4CAA4C,GAC5C,OAAO,CAAC,4CAA4C,CAAC,CAAC;CAC3D;AA+ED,qFAAqF;AACrF,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,8BAA8B,GACxC,uCAAuC,CAYzC;AAED,wFAAwF;AACxF,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,iBAAiB,GAAG,CAAC,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC,EAChE,OAAO,GAAE,uCAA4C,GACpD,sBAAsB,CAAC,uCAAuC,CAAC,CAuEjE;AAED,+EAA+E;AAC/E,wBAAgB,sCAAsC,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAKzF;AAED;;;GAGG;AACH,wBAAsB,+BAA+B,CACnD,EAAE,EAAE,iBAAiB,EACrB,OAAO,EAAE,iCAAiC,yDAI3C;AAED;;;GAGG;AACH,wBAAsB,+BAA+B,CACnD,EAAE,EAAE,iBAAiB,EACrB,OAAO,EAAE,qCAAqC,2CAI/C"}

package/dist/tax-summary.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Pure stored-fact aggregation for the commerce tax summary report.
+ *
+ * Persistence owns source queries. This module deliberately accepts normalized
+ * snapshots so report arithmetic is testable without reaching into documents.
+ */
+export type TaxCodeKind = 'taxable' | 'zero-rated' | 'exempt' | 'out-of-scope';
+export type TaxSummaryDirection = 'sales' | 'purchase';
+export interface TaxSummaryStoredFact {
+    tenantId: string;
+    documentType: 'invoice' | 'credit_note' | 'contract';
+    documentId: string;
+    /** Invoice credits store positive facts and are negated here exactly once. */
+    documentKind: 'invoice' | 'credit_note' | 'contract';
+    issueDate: string;
+    status: string;
+    direction: TaxSummaryDirection;
+    currency: string;
+    /** Null means the stored snapshot cannot be assigned to a tax code. */
+    taxCodeId: string | null;
+    /** Null is an incomplete/unassigned stored snapshot, never out-of-scope. */
+    taxCodeKind: TaxCodeKind | null;
+    taxableMinor: number;
+    taxMinor: number;
+    recoverableMinor: number;
+    taxComponentId: string | null;
+    componentName: string | null;
+    liabilityAccountId: string | null;
+    commitmentId?: string | null;
+    commitmentLineId?: string | null;
+}
+export interface TaxSummaryExpenseFact {
+    tenantId: string;
+    expenseId: string;
+    incurredOn: string;
+    currency: string;
+    commitmentId: string | null;
+    commitmentLineId: string | null;
+    /** Null means a legacy fact whose supplier tax is unknown. */
+    financialBreakdown: {
+        taxes: ReadonlyArray<{
+            code: string;
+            amount: number;
+            recoverableAmount: number;
+        }>;
+    } | null;
+}
+export interface TaxSummaryComponentMapping {
+    tenantId: string;
+    expenseCode: string;
+    taxComponentId: string;
+    componentName: string;
+    liabilityAccountId: string | null;
+}
+export interface TaxSummaryLedgerMovement {
+    tenantId: string;
+    entryId: string;
+    accountId: string;
+    currency: string;
+    creditMinusDebit: number;
+}
+export interface TaxSummaryInput {
+    tenantId: string;
+    from: string;
+    to: string;
+    facts: ReadonlyArray<TaxSummaryStoredFact>;
+    expenses: ReadonlyArray<TaxSummaryExpenseFact>;
+    expenseComponentMappings: ReadonlyArray<TaxSummaryComponentMapping>;
+    ledgerMovements: ReadonlyArray<TaxSummaryLedgerMovement>;
+}
+export interface TaxSummaryComponentRow {
+    rowKind: 'component';
+    currency: string;
+    taxComponentId: string;
+    componentName: string;
+    liabilityAccountId: string | null;
+    /** Sum of stored component taxable bases; components intentionally overlap. */
+    taxableMinor: number;
+    collectedMinor: number;
+    purchaseRecoverableMinor: number;
+    expenseRecoverableMinor: number;
+    /** Null when unknown or ambiguous facts make an exact ITC unsafe. */
+    inputTaxCreditMinor: number | null;
+    /** Null when the corresponding ITC is incomplete. */
+    netTaxMinor: number | null;
+    documentCount: number;
+    /** Stable source classes used to reproduce a materialized drilldown. */
+    sourceScopes: readonly TaxSummarySourceScope[];
+}
+export interface TaxSummaryKindRow {
+    rowKind: 'kind';
+    currency: string;
+    direction: TaxSummaryDirection;
+    taxCodeKind: TaxCodeKind;
+    taxableMinor: number;
+    documentCount: number;
+    sourceScopes: readonly TaxSummarySourceScope[];
+}
+export interface TaxSummaryReconciliationRow {
+    rowKind: 'reconciliation';
+    currency: string;
+    taxComponentId: string;
+    liabilityAccountId: string | null;
+    collectedMinor: number;
+    ledgerMovementMinor: number | null;
+    differenceMinor: number | null;
+    status: 'reconciled' | 'difference' | 'unassigned' | 'ambiguous';
+    sourceScopes: readonly TaxSummarySourceScope[];
+}
+/** Source classes persisted for drilldown; amounts remain in the report rows. */
+export type TaxSummarySourceScope = 'invoice' | 'purchase' | 'expense' | 'ledger';
+export interface TaxSummaryWarning {
+    code: 'unknown-expense-tax' | 'unmapped-expense-component' | 'linked-purchase-expense' | 'unassigned-liability-account' | 'shared-liability-account' | 'unassigned-tax-code';
+    currency: string;
+    sourceId: string;
+    sourceType: 'document' | 'expense' | 'component' | 'account';
+    message: string;
+}
+export interface TaxSummaryResult {
+    componentRows: TaxSummaryComponentRow[];
+    kindRows: TaxSummaryKindRow[];
+    reconciliationRows: TaxSummaryReconciliationRow[];
+    warnings: TaxSummaryWarning[];
+    /** False means no row may be presented as an exact reconciled net tax total. */
+    complete: boolean;
+}
+/** Aggregate normalized stored facts without querying persistence. */
+export declare function aggregateTaxSummary(input: TaxSummaryInput): TaxSummaryResult;
+//# sourceMappingURL=tax-summary.d.ts.map

package/dist/tax-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tax-summary.d.ts","sourceRoot":"","sources":["../src/tax-summary.ts"],"names":[],"mappings":"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"}

package/dist/tenant-money-barrier.d.ts

@@ -0,0 +1,66 @@
+/** Shared tenant serialization barrier for commerce money runtime and migration. */
+import type { DatabaseInterface } from '@happyvertical/smrt-core/migrations';
+import type { TaxSettings } from './models/TaxSettings.js';
+export type TenantMoneyRuntimeRequirement = 'legacy-or-v2' | 'v2';
+export type TenantMoneyRuntimeBarrier = {
+    readonly moneyModel: 'legacy';
+    readonly settings: null;
+    readonly persistedBarrier: false;
+} | {
+    readonly moneyModel: 'legacy';
+    readonly settings: TaxSettings;
+    readonly persistedBarrier: true;
+} | {
+    readonly moneyModel: 'v2';
+    readonly settings: TaxSettings;
+    readonly persistedBarrier: true;
+};
+declare const tenantMoneyScopeBrand: unique symbol;
+/** Transaction-affine proof that a tenant marker is locked on `db`. */
+export interface TenantMoneyRuntimeScope {
+    readonly db: DatabaseInterface;
+    readonly tenantId: string;
+    readonly barrier: TenantMoneyRuntimeBarrier;
+    readonly phase: 'runtime';
+    readonly [tenantMoneyScopeBrand]: true;
+}
+declare const tenantMoneyMigrationScopeBrand: unique symbol;
+/** Transaction-affine proof held only by the active migration owner. */
+export interface TenantMoneyMigrationScope {
+    readonly db: DatabaseInterface;
+    readonly tenantId: string;
+    readonly migrationId: string;
+    readonly settings: TaxSettings;
+    readonly phase: 'migration';
+    readonly [tenantMoneyMigrationScopeBrand]: true;
+}
+/**
+ * Lock and re-read the tenant money marker before any runtime money work.
+ *
+ * Older schemas without TaxSettings stay byte-compatible legacy and are never
+ * modified. Once the table exists, a missing deterministic legacy row is
+ * materialized solely to provide the serialization point shared by migration.
+ */
+export declare function lockTenantMoneyRuntime(tx: DatabaseInterface, tenantId: string, requirement?: TenantMoneyRuntimeRequirement): Promise<TenantMoneyRuntimeBarrier>;
+/**
+ * Run tenant money work under the shared marker lock on exactly one executor.
+ *
+ * Supplying an existing scope proves re-entry on the same executor. Calls made
+ * through the owning transaction wrapper also reuse its exact registered
+ * executor. No optional adapter-property heuristic can grant this capability.
+ */
+export declare function withTenantMoneyRuntime<T>(db: DatabaseInterface, tenantId: string, requirement: TenantMoneyRuntimeRequirement, operation: (scope: TenantMoneyRuntimeScope) => Promise<T>, existingScope?: TenantMoneyRuntimeScope): Promise<T>;
+/**
+ * Run migration work under the exact owner marker and transaction executor.
+ * This is the only scope that lets guarded collections read while the marker
+ * is `migrating`; possession cannot be inferred from adapter shape.
+ */
+export declare function withTenantMoneyMigration<T>(db: DatabaseInterface, tenantId: string, migrationId: string, operation: (scope: TenantMoneyMigrationScope) => Promise<T>, existingScope?: TenantMoneyMigrationScope): Promise<T>;
+/** @internal Guard a generated collection read for runtime or migration. */
+export declare function withTenantMoneyCollectionRead<T>(db: DatabaseInterface, tenantId: string, operation: (boundDb: DatabaseInterface) => Promise<T>): Promise<T>;
+/** Lock a tenant at the legacy marker before the caller claims migration. */
+export declare function lockTenantMoneyMigrationClaim(tx: DatabaseInterface, tenantId: string): Promise<TaxSettings>;
+/** Lock and verify the exact owner of an active tenant migration. */
+export declare function lockTenantMoneyMigrationOwner(tx: DatabaseInterface, tenantId: string, migrationId: string): Promise<TaxSettings>;
+export {};
+//# sourceMappingURL=tenant-money-barrier.d.ts.map

package/dist/tenant-money-barrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-money-barrier.d.ts","sourceRoot":"","sources":["../src/tenant-money-barrier.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -82,6 +82,7 @@ export declare enum PaymentStatus {
     REFUNDED = "refunded",
     CANCELLED = "cancelled"
 }
+export type PaymentKind = 'payment' | 'refund';
 /**
  * Lifecycle status for a saved {@link PaymentInstrument} (card on file).
  * `active` while chargeable, `expired` once the card lapses, `removed` when the
@@ -257,6 +258,13 @@ export interface RecognizeRevenueOptions {
     revenueAccountId: string;
     /** Account ID for tax payable (credit side, optional) */
     taxAccountId?: string;
+    /** Explicit ledger book currency. Required when the tenant uses money v2. */
+    bookCurrency?: string;
+}
+/** Options for atomically cancelling a posted money-v2 invoice. */
+export interface CancelRevenueOptions {
+    /** Explicit ledger book currency; required for money-v2 cancellation. */
+    bookCurrency?: string;
 }
 /**
  * A single line item in the format expected by `@happyvertical/accounting`
@@ -295,6 +303,16 @@ export interface AccountingInvoiceInput {
     currency: string;
     reference?: string;
     memo?: string;
+    idempotencyKey?: string;
+    quickbooksRequest?: {
+        readonly requestId: string;
+        readonly realmId: string;
+        readonly environment: 'sandbox' | 'production';
+        readonly payloadHash: string;
+    };
+    quickbooksMapping?: {
+        globalTaxCalculation: 'TaxExcluded' | 'NotApplicable';
+    };
 }
 /**
  * Constructor options for {@link Customer}.
@@ -306,6 +324,7 @@ export interface CustomerOptions extends SmrtObjectOptions {
     paymentTerms?: string;
     taxExempt?: boolean;
     taxId?: string;
+    defaultTaxCodeId?: string;
     defaultShippingAddress?: Address;
     defaultBillingAddress?: Address;
     status?: CustomerStatus;
@@ -323,6 +342,8 @@ export interface VendorOptions extends SmrtObjectOptions {
     minimumOrderAmount?: number;
     paymentTerms?: string;
     currency?: string;
+    taxId?: string;
+    defaultTaxCodeId?: string;
     defaultContactEmail?: string;
     defaultContactPhone?: string;
     status?: VendorStatus;
@@ -330,6 +351,43 @@ export interface VendorOptions extends SmrtObjectOptions {
     payoutAddresses?: Record<string, string> | string | null;
     contacts?: PartyContact[] | string | null;
 }
+/** A component reference stored in a tax code's ordered component list. */
+export interface TaxCodePart {
+    taxComponentId: string;
+    compound: boolean;
+}
+export interface TaxComponentOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    name?: string;
+    percent?: string;
+    liabilityAccountId?: string;
+    recoverable?: boolean;
+    active?: boolean;
+}
+export interface TaxCodeOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    code?: string;
+    name?: string;
+    kind?: 'taxable' | 'zero-rated' | 'exempt' | 'out-of-scope';
+    appliesTo?: 'sales' | 'purchases' | 'both';
+    components?: TaxCodePart[];
+    active?: boolean;
+}
+export interface TaxRegistrationOptions {
+    taxComponentId: string;
+    number: string;
+    label: string;
+}
+export interface TaxSettingsOptions extends SmrtObjectOptions {
+    tenantId?: string;
+    defaultSalesTaxCodeId?: string;
+    defaultPurchaseTaxCodeId?: string;
+    defaultLineAmountType?: 'exclusive' | 'inclusive' | 'none';
+    taxRoundingScope?: 'line' | 'document';
+    taxRegistrations?: TaxRegistrationOptions[];
+    moneyModel?: 'legacy' | 'migrating' | 'v2';
+    moneyMigrationId?: string;
+}
 /**
  * Constructor options for {@link Contract} and its STI subtypes.
  */
@@ -337,9 +395,8 @@ export interface ContractOptions extends SmrtObjectOptions {
     tenantId?: string | null;
     contractType?: ContractType;
     status?: ContractStatus;
-    customerId?: string | null;
-    vendorId?: string | null;
     subtotal?: number;
+    discountTotal?: number;
     taxAmount?: number;
     totalAmount?: number;
     currency?: string;
@@ -350,9 +407,21 @@ export interface ContractOptions extends SmrtObjectOptions {
     notes?: string;
     terms?: string;
     channelId?: string;
+    lineAmountType?: 'exclusive' | 'inclusive' | 'none';
+    taxRoundingScope?: 'line' | 'document';
+    sellerTaxRegistrations?: TaxRegistrationOptions[];
+    sellerTaxRegistrationsJson?: string;
+    partyTaxId?: string;
+    moneySnapshotId?: string;
+}
+export interface SalesContractOptions extends ContractOptions {
+    customerId?: string | null;
+}
+export interface PurchaseContractOptions extends ContractOptions {
+    vendorId?: string | null;
 }
 /** Purchase-order header options stored in the existing STI metadata. */
-export interface PurchaseOrderOptions extends ContractOptions {
+export interface PurchaseOrderOptions extends PurchaseContractOptions {
     /** Expected delivery calendar date (YYYY-MM-DD); empty means unspecified. */
     expectedDate?: string;
     /** Delivery address/instructions snapshot. */
@@ -362,7 +431,7 @@ export interface PurchaseOrderOptions extends ContractOptions {
  * Constructor options for {@link LicenseSale} (Contract STI subtype). Extends
  * {@link ContractOptions} with the licensing-specific meta fields.
  */
-export interface LicenseSaleOptions extends ContractOptions {
+export interface LicenseSaleOptions extends SalesContractOptions {
     skuId?: string;
     paymentId?: string;
     licenseeEmail?: string;
@@ -389,7 +458,18 @@ export interface ContractLineItemOptions extends SmrtObjectOptions {
     quantity?: number;
     unitPrice?: number;
     discount?: number;
+    discountType?: 'none' | 'percent' | 'amount';
+    discountRate?: string;
     taxRate?: number;
+    taxMode?: 'inherit' | 'override';
+    taxCodeId?: string | null;
+    taxCodeCode?: string | null;
+    taxCodeName?: string | null;
+    taxComponents?: ContractTaxComponentSnapshot[];
+    taxComponentsJson?: string | null;
+    taxAmount?: number;
+    legacyAmount?: number | null;
+    moneySnapshotId?: string;
     amount?: number;
     productId?: string;
     sku?: string;
@@ -398,16 +478,45 @@ export interface ContractLineItemOptions extends SmrtObjectOptions {
     billingPeriod?: string;
     sortOrder?: number;
 }
+/** Immutable component tax allocation for one Contract line. */
+export interface ContractTaxComponentSnapshot {
+    taxComponentId: string;
+    name: string;
+    percent: string;
+    taxMinor: number;
+}
 /**
  * How the provider collects an invoice (#3190): `charge_automatically`
  * charges the payer's saved card; `send_invoice` asks the payer to pay. Empty
  * for an invoice never pushed to a provider, or pushed before it was recorded.
  */
 export type InvoiceCollectionMethod = '' | 'send_invoice' | 'charge_automatically';
+export type InvoiceKind = 'invoice' | 'credit_note';
+/** Frozen source pricing plus the one authoritative credit calculation basis. */
+export type InvoiceCreditCalculationBasis = {
+    kind: 'quantity';
+    quantity: string;
+    sourceQuantity: string;
+    sourceUnitPrice: number;
+    sourceDiscountType: 'none' | 'percent' | 'amount';
+    sourceDiscountRate: string;
+    sourceDiscountMinor: number;
+} | {
+    kind: 'net_amount';
+    netMinor: number;
+    sourceQuantity: string;
+    sourceUnitPrice: number;
+    sourceDiscountType: 'none' | 'percent' | 'amount';
+    sourceDiscountRate: string;
+    sourceDiscountMinor: number;
+};
 /**
  * Constructor options for {@link Invoice}.
  */
 export interface InvoiceOptions extends SmrtObjectOptions {
+    kind?: InvoiceKind;
+    creditedInvoiceId?: string | null;
+    creditedAmount?: number;
     tenantId?: string | null;
     customerId?: string;
     contractId?: string;
@@ -424,6 +533,7 @@ export interface InvoiceOptions extends SmrtObjectOptions {
     currency?: string;
     status?: InvoiceStatus;
     arJournalId?: string;
+    arReversalJournalId?: string | null;
     revenueJournalId?: string;
     externalId?: string;
     customerExternalId?: string;
@@ -437,6 +547,20 @@ export interface InvoiceOptions extends SmrtObjectOptions {
     notes?: string;
     customerNotes?: string;
     terms?: string;
+    lineAmountType?: 'exclusive' | 'inclusive' | 'none';
+    taxRoundingScope?: 'line' | 'document';
+    discountTotal?: number;
+    sellerTaxRegistrations?: TaxRegistrationOptions[];
+    sellerTaxRegistrationsJson?: string;
+    partyTaxId?: string;
+    moneySnapshotId?: string;
+    accountingSyncStateJson?: string;
+}
+export interface InvoiceTaxComponentSnapshot {
+    taxComponentId: string;
+    name: string;
+    percent: string;
+    taxMinor: number;
 }
 /** Retained editing modes, validated against resolved model fields before reuse. */
 export interface InvoiceLineEditorState {
@@ -447,6 +571,9 @@ export interface InvoiceLineEditorState {
 }
 /** Constructor options for {@link InvoiceLineItem}. */
 export interface InvoiceLineItemOptions extends SmrtObjectOptions {
+    creditedLineId?: string | null;
+    creditCalculationBasis?: InvoiceCreditCalculationBasis | null;
+    creditCalculationBasisJson?: string;
     /** Optional retained editor modes and their original calculation context. */
     invoiceEditorState?: InvoiceLineEditorState | null;
     /** Serialized editor state loaded from persistence; malformed JSON is ignored. */
@@ -455,16 +582,28 @@ export interface InvoiceLineItemOptions extends SmrtObjectOptions {
     invoiceId?: string;
     description?: string;
     sku?: string;
+    productId?: string | null;
     quantity?: number;
     unitPrice?: number;
     discount?: number;
+    discountType?: 'none' | 'percent' | 'amount';
+    discountRate?: string;
     taxRate?: number;
+    taxMode?: 'inherit' | 'override';
+    taxCodeId?: string | null;
+    taxCodeCode?: string | null;
+    taxCodeName?: string | null;
+    taxComponents?: InvoiceTaxComponentSnapshot[];
+    taxComponentsJson?: string | null;
+    taxAmount?: number;
+    legacyAmount?: number | null;
+    moneySnapshotId?: string;
     amount?: number;
     sourceType?: string;
     sourceId?: string;
     periodStart?: Date | null;
     periodEnd?: Date | null;
-    revenueAccountId?: string;
+    revenueAccountId?: string | null;
     sortOrder?: number;
 }
 /**
@@ -497,6 +636,7 @@ export interface FulfillmentLineItemOptions extends SmrtObjectOptions {
  * Constructor options for {@link Payment}.
  */
 export interface PaymentOptions extends SmrtObjectOptions {
+    kind?: PaymentKind;
     tenantId?: string | null;
     contractId?: string | null;
     customerId?: string | null;