@happyvertical/smrt-commerce 0.30.0

package/dist/models/Payment.d.ts

@@ -0,0 +1,269 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { PaymentMethod, PaymentStatus, RecordPaymentOptions } from '../types/index.js';
+/**
+ * Payment represents a financial transaction against a contract.
+ *
+ * Payments can be integrated with smrt-ledgers to automatically
+ * create balanced journal entries for proper accounting.
+ *
+ * @example
+ * ```typescript
+ * // Create a payment
+ * const payment = await payments.create({
+ *   contractId: order.id,
+ *   customerId: customer.id,
+ *   amount: 1500.00,
+ *   method: PaymentMethod.CREDIT_CARD,
+ *   transactionId: 'stripe_pi_123456'
+ * });
+ *
+ * // Record with ledger integration
+ * await payment.recordPayment({
+ *   ledgerId: ledger.id,
+ *   receivablesAccountId: arAccount.id,
+ *   cashAccountId: bankAccount.id
+ * });
+ * ```
+ */
+export declare class Payment extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global payments
+     */
+    tenantId: string | null;
+    /**
+     * Contract this payment is for
+     */
+    contractId: string;
+    /**
+     * Customer who made the payment
+     */
+    customerId: string;
+    /**
+     * Payment amount
+     */
+    amount: number;
+    /**
+     * Currency code (ISO 4217)
+     */
+    currency: string;
+    /**
+     * Payment method used
+     */
+    method: PaymentMethod;
+    /**
+     * Current payment status
+     */
+    status: PaymentStatus;
+    /**
+     * External transaction ID (from payment processor)
+     */
+    transactionId: string;
+    /**
+     * Internal reference number
+     */
+    reference: string;
+    /**
+     * Link to smrt-ledgers Journal (created by recordPayment)
+     */
+    journalId: string;
+    /**
+     * When the payment was completed
+     */
+    paidAt: Date | null;
+    /**
+     * Notes about the payment
+     */
+    notes: string;
+    /**
+     * External ID in accounting provider (e.g., QBO payment ID)
+     */
+    externalId: string;
+    /**
+     * Accounting provider name ('quickbooks' | 'stripe' | 'paypal' | etc.)
+     */
+    externalProvider: string;
+    /**
+     * When payment was last synced to provider
+     */
+    syncedAt: Date | null;
+    /**
+     * Stable identifier of the `PaymentBackend` adapter that served this
+     * payment — e.g. `base-usdc`, `solana-usdc`, `btc`, `stripe`, `paypal`.
+     *
+     * Distinct from {@link externalProvider}: `backendId` names the SMRT
+     * payment-rail adapter, while `externalProvider` names a downstream
+     * accounting destination (QuickBooks, Stripe-the-accounting-source).
+     * The same Stripe payment will have `backendId: 'stripe'` AND
+     * `externalProvider: 'stripe'`; a crypto payment synced to QBO will
+     * have `backendId: 'base-usdc'` and `externalProvider: 'quickbooks'`.
+     */
+    backendId: string;
+    /**
+     * Chain transaction hash or backend aggregator's reference id. For
+     * on-chain payments this is the tx hash (`0x...` on EVM, base58 sig on
+     * Solana, txid on Bitcoin); for fiat-rail backends it's the gateway's
+     * own reference. Kept distinct from {@link transactionId} so consumers
+     * that already populate `transactionId` with a provider-internal id
+     * don't have to overload it.
+     */
+    backendTxRef: string;
+    /**
+     * The amount the backend actually moved, in its own native currency.
+     * For stablecoin rails this typically equals `amount`; for volatile-
+     * currency rails (BTC, ETH) it's the satoshi/wei figure that the chain
+     * recorded, independent of any USD valuation.
+     */
+    nativeAmount: number;
+    /**
+     * Code identifying the native currency `nativeAmount` is denominated
+     * in. Mirrors the `backendId` namespacing convention — `USDC-base`,
+     * `BTC`, `ETH`, `USD-stripe`. Empty string means "use {@link currency}"
+     * (i.e. the payment was already quoted and settled in the same
+     * currency).
+     */
+    nativeCurrency: string;
+    /**
+     * USD valuation of the payment at the moment the price was quoted to
+     * the buyer (typically the moment a `PaymentIntent` was issued).
+     * Stored at decimal precision; empty default `0.0` means no USD-quote
+     * snapshot was taken (the payment was already USD-denominated or the
+     * backend doesn't require drift accounting).
+     */
+    usdAtQuote: number;
+    /**
+     * USD valuation of the payment at the moment it was confirmed on the
+     * backend (chain confirmation, gateway settlement, etc.). The delta
+     * between {@link usdAtQuote} and `usdAtConfirmation` is the USD drift
+     * the operator absorbs (positive or negative) when accepting payment
+     * in a volatile native currency.
+     */
+    usdAtConfirmation: number;
+    constructor(options?: any);
+    /**
+     * Capture the persisted status the row was loaded with, so the save-time
+     * transition guard can reject illegal status flips made via raw field
+     * assignment (mass-assignment on the generated update route, a stale caller,
+     * etc.). Freshly-constructed (not-yet-saved) payments have no prior status.
+     */
+    initialize(): Promise<this>;
+    /**
+     * Save-time state-machine guard (S5 audit #1390).
+     *
+     * `status` is mass-assignable on the generated update/create routes, and a
+     * COMPLETED Payment is treated as settlement proof downstream — e.g.
+     * {@link PaymentIntent}'s PAID verification trusts a COMPLETED Payment row.
+     * A forged `status: 'completed'` (with arbitrary amounts and no journal)
+     * would therefore satisfy that check without any money having moved.
+     *
+     * This guard enforces two things:
+     *  - **Transitions must be legal** per {@link PAYMENT_STATUS_TRANSITIONS}.
+     *  - **Reaching COMPLETED requires the verified settlement path — on
+     *    creation AND on update.** Only `recordPayment()` (which posts a
+     *    balanced journal and links `journalId`) may write a Payment into
+     *    COMPLETED; it announces itself via {@link settlementInProgress}. A raw
+     *    `status: 'completed'` is rejected whether the row is brand-new (a
+     *    GENESIS `create({ status: 'completed' })`) or already persisted — that
+     *    is the exact path a forged COMPLETED would take to satisfy
+     *    PaymentIntent's PAID verification without any money having moved (codex
+     *    HIGH#1, #1390 round 5). There is deliberately NO import/fixture
+     *    carve-out: a COMPLETED Payment is settlement proof downstream, so it is
+     *    only ever reachable through `recordPayment()`, on every surface
+     *    (REST/MCP/CLI/direct). Fixtures/migrations that need a completed payment
+     *    must drive it through `recordPayment()` (or start non-COMPLETED).
+     */
+    save(): Promise<this>;
+    /**
+     * Reject an illegal status flip. Compares the about-to-be-written status
+     * against the status the row was loaded with. No-op transitions (status
+     * unchanged) and brand-new rows (no prior) are always allowed — the
+     * COMPLETED-specific settlement requirement is enforced separately in
+     * {@link save}.
+     */
+    private assertStatusTransition;
+    /**
+     * Load the AUTHORITATIVE persisted row (S5 audit #1390 round 4, codex HIGH#1;
+     * extended round 6 to carry the full row, not just `status`). The WeakMap is
+     * only populated when {@link initialize} loaded the row from the DB; it is
+     * empty for an instance built via
+     * `collection.create({ id: <existing>, _skipLoad: true })` — the upsert path
+     * that lets a caller write onto an existing row without hydrating it. Trusting
+     * an empty WeakMap there would treat the write as a brand-new row and skip the
+     * transition guard entirely (a poisonable prior-state).
+     *
+     * So when this instance carries an `id`, read the persisted row straight from
+     * the database and use it as the prior — a create-onto-existing is an update.
+     * Returns `undefined` when no row exists (truly new), so callers fall back to
+     * the WeakMap (which is also empty then). Settled-amount columns are
+     * snake_case (`native_amount`, etc.); the `status` column is single-word.
+     */
+    private loadPersistedRow;
+    /**
+     * Reject any change to the settled monetary fields of an already-COMPLETED
+     * Payment (S5 audit #1390 round 6 — codex ROOT INSIGHT). Mirrors the
+     * PaymentIntent PAID backing-field freeze. A COMPLETED Payment's economic
+     * identity is settled: the `amount` was posted into a balanced journal and is
+     * the figure PaymentIntent's PAID verification reconciles against, so it (and
+     * the native/USD valuation fields that describe the same money) must not
+     * drift. The only legal status move out of COMPLETED is REFUNDED, which
+     * reverses the funds without rewriting how much they were. Compared against
+     * the AUTHORITATIVE persisted row so the freeze holds on every surface, even
+     * for an un-hydrated create-onto-existing upsert.
+     */
+    private assertSettledAmountsUnchanged;
+    /**
+     * USD drift between quote time and confirmation time — what the
+     * operator gained (positive) or lost (negative) by accepting a
+     * volatile-currency payment. Returns `0` when either side of the
+     * comparison is missing or zero, so callers don't have to special-case
+     * fiat-rail / stablecoin payments.
+     */
+    usdDrift(): number;
+    /**
+     * Check if payment is pending
+     */
+    isPending(): boolean;
+    /**
+     * Check if payment is completed
+     */
+    isCompleted(): boolean;
+    /**
+     * Check if payment is refunded
+     */
+    isRefunded(): boolean;
+    /**
+     * Record the payment and create a balanced journal entry.
+     *
+     * Creates a journal entry in smrt-ledgers:
+     * - Debit: Cash/Bank account (assets increase)
+     * - Credit: Accounts Receivable (receivables decrease)
+     *
+     * @param options - Ledger and account configuration
+     * @returns The created journal
+     *
+     * @example
+     * ```typescript
+     * const journal = await payment.recordPayment({
+     *   ledgerId: ledger.id,
+     *   receivablesAccountId: arAccount.id,
+     *   cashAccountId: bankAccount.id
+     * });
+     * console.log(`Created journal: ${journal.number}`);
+     * ```
+     */
+    recordPayment(options: RecordPaymentOptions): Promise<any>;
+    /**
+     * Get the linked journal entry (if recorded)
+     */
+    getJournal(): Promise<any | null>;
+    /**
+     * Mark payment as failed
+     */
+    markFailed(reason?: string): void;
+    /**
+     * Cancel the payment
+     */
+    cancel(): void;
+}
+export default Payment;
+//# sourceMappingURL=Payment.d.ts.map

package/dist/models/Payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Payment.d.ts","sourceRoot":"","sources":["../../src/models/Payment.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,aAAa,EACb,aAAa,EACb,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AA6C3B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBA8Ca,OAAQ,SAAQ,UAAU;IACrC;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IAEH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAO;IAErB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAS;IAEzB;;OAEG;IACH,MAAM,EAAE,aAAa,CAA+B;IAEpD;;OAEG;IACH,MAAM,EAAE,aAAa,CAAyB;IAE9C;;OAEG;IACH,aAAa,EAAE,MAAM,CAAM;IAE3B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IACH,MAAM,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE3B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;IAMnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IACH,gBAAgB,EAAE,MAAM,CAAM;IAE9B;;OAEG;IACH,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAQ;IAiB7B;;;;;;;;;;OAUG;IACH,SAAS,EAAE,MAAM,CAAM;IAEvB;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAM;IAE1B;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAO;IAE3B;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAM;IAE5B;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAO;IAEzB;;;;;;OAMG;IACH,iBAAiB,EAAE,MAAM,CAAO;gBAEpB,OAAO,GAAE,GAAQ;IA+B7B;;;;;OAKG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ1C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkDpC;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;;;;;;;;;;;;;;OAeG;YACW,gBAAgB;IAW9B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,6BAA6B;IAwCrC;;;;;;OAMG;IACH,QAAQ,IAAI,MAAM;IAKlB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,GAAG,CAAC;IAwDhE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAavC;;OAEG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAOjC;;OAEG;IACH,MAAM,IAAI,IAAI;CAMf;AAED,eAAe,OAAO,CAAC"}

package/dist/models/PaymentAllocation.d.ts

@@ -0,0 +1,93 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * PaymentAllocation tracks how payments are applied to invoices.
+ *
+ * This enables:
+ * - Partial payments (one payment partially covering an invoice)
+ * - Split payments (one payment split across multiple invoices)
+ * - Payment history per invoice
+ *
+ * **Note**: This model does not automatically validate that allocations
+ * don't exceed the payment amount or invoice amount due. Use
+ * `PaymentAllocationCollection.getUnallocatedFromPayment()` before creating
+ * allocations to ensure sufficient funds are available.
+ *
+ * @example
+ * ```typescript
+ * import { PaymentAllocationCollection } from '@happyvertical/smrt-commerce';
+ *
+ * // Get the collection
+ * const allocations = await PaymentAllocationCollection.create(options);
+ *
+ * // Check available funds before allocating
+ * const available = await allocations.getUnallocatedFromPayment(
+ *   payment.id,
+ *   payment.amount
+ * );
+ *
+ * if (available >= amountToAllocate) {
+ *   const allocation = await allocations.create({
+ *     paymentId: payment.id,
+ *     invoiceId: invoice.id,
+ *     amount: amountToAllocate,
+ *     allocatedBy: 'user-uuid'
+ *   });
+ *
+ *   // Update invoice payment status
+ *   const totalAllocated = await allocations.getTotalAllocatedToInvoice(invoice.id);
+ *   invoice.updatePaymentStatus(totalAllocated);
+ *   await invoice.save();
+ * }
+ * ```
+ */
+export declare class PaymentAllocation extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     * Nullable to support both tenant-scoped and global payment allocations
+     */
+    tenantId: string | null;
+    /**
+     * Payment being allocated
+     */
+    paymentId: string;
+    /**
+     * Invoice receiving the allocation
+     */
+    invoiceId: string;
+    /**
+     * Amount allocated from payment to invoice
+     */
+    amount: number;
+    /**
+     * When the allocation was made
+     */
+    allocatedAt: Date;
+    /**
+     * User/agent who made the allocation
+     */
+    allocatedBy: string;
+    /**
+     * Notes about the allocation
+     */
+    notes: string;
+    constructor(options?: any);
+    /**
+     * Save-time integrity guard (S5 audit #1390):
+     *  - allocation `amount` must be a finite, positive number, and
+     *  - the sum of all allocations against the referenced Payment (this row
+     *    included) must not exceed the Payment's amount — over-applying a
+     *    payment across invoices would falsify both payment and invoice
+     *    balances.
+     *
+     * The Payment-amount cap is enforced against the persisted Payment row. An
+     * allocation always carries a `@foreignKey('Payment')` paymentId, so a
+     * `paymentId` that doesn't resolve to a real Payment is a **hard error** (S5
+     * audit #1390 round 2): previously a missing Payment silently skipped the cap
+     * entirely, letting a caller over-apply (or fabricate) funds simply by
+     * pointing at a non-existent payment. An empty `paymentId` is still rejected
+     * by the underlying FK requirement; the positivity check always applies.
+     */
+    save(): Promise<this>;
+}
+export default PaymentAllocation;
+//# sourceMappingURL=PaymentAllocation.d.ts.map

package/dist/models/PaymentAllocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaymentAllocation.d.ts","sourceRoot":"","sources":["../../src/models/PaymentAllocation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AASxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAoBa,iBAAkB,SAAQ,UAAU;IAC/C;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAK;IAEnB;;OAEG;IACH,WAAW,EAAE,IAAI,CAAc;IAE/B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAM;IAEzB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IAa7B;;;;;;;;;;;;;;;OAeG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA0CrC;AAED,eAAe,iBAAiB,CAAC"}