@happyvertical/smrt-commerce 0.57.3 → 0.57.5

package/dist/retention-accounting.d.ts

@@ -0,0 +1,143 @@
+import { type AccountingProvider, type CreditMemoInput, type QuickBooksReceivableMapping } from '@happyvertical/accounting';
+import type { DatabaseInterface } from '@happyvertical/smrt-core/migrations';
+import { type AccountingStep } from './accounting-steps-internal.js';
+import { type FrozenInvoiceAccountingInput, type QuickBooksFrozenInvoiceMapping, type ReconcileFrozenInvoiceAccountingInput } from './invoice-accounting-sync.js';
+import type { Invoice } from './models/Invoice.js';
+import { type InvoiceRetentionEvidence } from './retention-money.js';
+import { type AccountingInvoiceInput } from './types/index.js';
+type Provider = Pick<AccountingProvider, 'type' | 'invoices' | 'creditMemos' | 'receivableTransfers'>;
+interface Scope {
+    db: DatabaseInterface;
+    tenantId: string;
+    invoiceId: string;
+    provider: Provider;
+}
+interface RefundRecording {
+    paymentId: string;
+    creditId: string;
+    requestId: string;
+    evidenceRef: string;
+    effectiveOn: string;
+    amountMinor: number;
+    paymentFingerprint: string;
+    committed: boolean;
+}
+interface CreditAdjustment {
+    creditId: string;
+    moneySnapshotId: string;
+    requestId: string;
+    evidenceRef: string;
+    effectiveOn: string;
+    grossMinor: number;
+    retainedMinor: number;
+    appliedMinor: number;
+    mapping: QuickBooksFrozenInvoiceMapping;
+    committed: boolean;
+}
+interface Release extends InvoiceRetentionEvidence {
+    amountMinor: number;
+    effectiveOn: string;
+    dueOn: string;
+    stepKey: string;
+    committed: boolean;
+}
+export interface RetainedInvoiceAccountingState {
+    version: 1;
+    invoiceId: string;
+    moneySnapshotId: string;
+    requestId: string;
+    evidenceRef: string;
+    currency: string;
+    grossMinor: number;
+    retainedMinor: number;
+    retentionAgreementHash: string;
+    effectiveOn: string;
+    mapping: QuickBooksReceivableMapping;
+    invoiceMapping: QuickBooksFrozenInvoiceMapping;
+    status: 'pending' | 'ready';
+    steps: AccountingStep[];
+    releases: Release[];
+    credits: CreditAdjustment[];
+    refunds: RefundRecording[];
+}
+export interface SyncRetainedInvoiceToAccountingInput extends Scope {
+    requestId: string;
+    evidenceRef: string;
+    effectiveOn: string;
+    mapping: QuickBooksReceivableMapping;
+    invoiceMapping: QuickBooksFrozenInvoiceMapping;
+}
+export interface ReleaseRetainedInvoiceToAccountingInput extends Scope, InvoiceRetentionEvidence {
+    amountMinor: number;
+    effectiveOn: string;
+    dueOn: string;
+    expectedUpdatedAt: string;
+}
+export declare function readRetainedInvoiceAccountingState(invoice: Invoice): RetainedInvoiceAccountingState | null;
+/** Read-only review of the exact retained document; generic export stays blocked.
+ * The host supplies authorization, and every read stays on the caller's executor.
+ */
+export declare function loadRetainedInvoiceAccountingSnapshot(input: Omit<FrozenInvoiceAccountingInput, 'mapping'>): Promise<import("./invoice-accounting-sync.js").FrozenInvoiceAccountingSnapshot>;
+/** Validate reviewed realm item/tax mapping without creating a provider operation. */
+export declare function toRetainedInvoiceAccountingInput(input: FrozenInvoiceAccountingInput): Promise<AccountingInvoiceInput>;
+type RetainedCreditReviewScope = Omit<FrozenInvoiceAccountingInput, 'mapping'> & {
+    creditInvoiceId: string;
+};
+/** Read an issued retained-first credit without permitting generic credit export. */
+export declare function loadRetainedCreditAccountingSnapshot(input: RetainedCreditReviewScope): Promise<import("./invoice-accounting-sync.js").FrozenInvoiceAccountingSnapshot>;
+/** Map a retained-first credit using the existing frozen reader's realm/lineage checks. */
+export declare function toRetainedCreditAccountingInput(input: RetainedCreditReviewScope & {
+    mapping: QuickBooksFrozenInvoiceMapping;
+}): Promise<CreditMemoInput>;
+/** Export unchanged gross/tax, then reclassify and apply its exact retained amount. */
+export declare function syncRetainedInvoiceToAccounting(input: SyncRetainedInvoiceToAccountingInput): Promise<RetainedInvoiceAccountingState>;
+/** Release date is provider TxnDate; dueOn remains explicit host collection policy. */
+export declare function releaseRetainedInvoiceToAccounting(input: ReleaseRetainedInvoiceToAccountingInput): Promise<RetainedInvoiceAccountingState>;
+export interface ReconcileRetainedAccountingStepInput extends Scope {
+    stepKey: string;
+    requestId: string;
+    attemptId: string;
+    confirmInterruptedOwnerStopped?: true;
+    outcome: {
+        status: 'found';
+        externalId: string;
+    } | {
+        status: 'absent';
+        evidenceRef: string;
+    };
+}
+/** Unknown remote outcomes never reset on a guessed absence or an unobserved owner. */
+export declare function reconcileRetainedAccountingStep(input: ReconcileRetainedAccountingStepInput): Promise<RetainedInvoiceAccountingState>;
+/** Reconcile the existing frozen invoice step using its established owner proof. */
+export declare function reconcileRetainedBaseInvoice(input: ReconcileFrozenInvoiceAccountingInput & {
+    provider: Provider;
+}): Promise<import("./invoice-accounting-sync.js").FrozenAccountingSyncResult | import("./invoice-accounting-sync.js").FrozenAccountingReconciliationReady>;
+export interface SyncRetainedCreditToAccountingInput extends Scope {
+    creditInvoiceId: string;
+    creditMapping: QuickBooksFrozenInvoiceMapping;
+    requestId: string;
+    evidenceRef: string;
+    effectiveOn: string;
+}
+/** Apply retained-first credit to the retained asset, then to the original due balance. */
+export declare function syncRetainedCreditToAccounting(input: SyncRetainedCreditToAccountingInput): Promise<RetainedInvoiceAccountingState>;
+export interface SyncRetainedRefundToAccountingInput extends Scope {
+    paymentId: string;
+    creditInvoiceId: string;
+    requestId: string;
+    evidenceRef: string;
+    effectiveOn: string;
+}
+/** Record an already settled local refund and consume its existing remote credit. No bank I/O. */
+export declare function syncRetainedRefundToAccounting(input: SyncRetainedRefundToAccountingInput): Promise<RetainedInvoiceAccountingState>;
+export interface ReconcileRetainedCreditAccountingInput extends Scope {
+    creditInvoiceId: string;
+    requestId: string;
+    attemptId: string;
+    confirmInterruptedOwnerStopped?: true;
+    outcome: ReconcileFrozenInvoiceAccountingInput['outcome'];
+}
+/** Resolve an interrupted credit-memo export before its retained-first applications resume. */
+export declare function reconcileRetainedCreditAccounting(input: ReconcileRetainedCreditAccountingInput): Promise<import("./invoice-accounting-sync.js").FrozenAccountingSyncResult | import("./invoice-accounting-sync.js").FrozenAccountingReconciliationReady>;
+export {};
+//# sourceMappingURL=retention-accounting.d.ts.map

package/dist/retention-accounting.d.ts.map

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

package/dist/retention-money.d.ts

@@ -0,0 +1,43 @@
+export interface InvoiceRetentionEvidence {
+    requestId: string;
+    policyVersion: string;
+    evidenceRef: string;
+    actorId: string;
+    reason: string;
+    /** Explicit business calendar date for original or current evidence; recordedAt stays actual record time. */
+    effectiveOn?: string;
+    sameDayCreditOrder?: 'credit-before-release' | 'release-before-credit' | null;
+}
+export interface InvoiceRetentionRelease extends InvoiceRetentionEvidence {
+    amountMinor: number;
+    recordedAt: string;
+}
+export interface InvoiceRetentionState extends InvoiceRetentionEvidence {
+    version: 1;
+    currency: string;
+    creditPolicy: 'retained-first';
+    retainedMinor: number;
+    recordedAt: string;
+    releases: InvoiceRetentionRelease[];
+}
+export interface InvoicePayableFacts {
+    grossMinor: number;
+    retainedMinor: number;
+    releasedMinor: number;
+    creditedRetentionMinor: number;
+    retainedRemainingMinor: number;
+    allocationCapMinor: number;
+    grossBalanceMinor: number;
+    currentlyDueMinor: number;
+}
+export declare function assertRetentionMinor(amount: number, label: string): void;
+export declare function validateRetentionEvidence(input: InvoiceRetentionEvidence): void;
+export declare function parseInvoiceRetention(json: string): InvoiceRetentionState | null;
+export declare function calculateInvoicePayable(input: {
+    totalAmount: number;
+    creditedAmount: number;
+    amountPaid: number;
+    currency: string;
+    retentionStateJson?: string;
+}): InvoicePayableFacts;
+//# sourceMappingURL=retention-money.d.ts.map

package/dist/retention-money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-money.d.ts","sourceRoot":"","sources":["../src/retention-money.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,6GAA6G;IAC7G,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,uBAAuB,GAAG,uBAAuB,GAAG,IAAI,CAAC;CAC/E;AACD,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,WAAW,qBAAsB,SAAQ,wBAAwB;IACrE,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,uBAAuB,EAAE,CAAC;CACrC;AACD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAID,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAGxE;AACD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,wBAAwB,GAC9B,IAAI,CAYN;AACD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GACX,qBAAqB,GAAG,IAAI,CAgD9B;AACD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,mBAAmB,CA2CtB"}