@happyvertical/smrt-commerce 0.51.31 → 0.51.33

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-commerce",
-  "packageVersion": "0.51.31",
+  "packageVersion": "0.51.33",
   "objects": {
     "@happyvertical/smrt-commerce:ContractCollection": {
       "name": "contractcollection",

package/dist/migrations/moneyMinorUnits.d.ts

@@ -1,4 +1,64 @@
-import { DatabaseInterface, MinorUnitsPreflightResult, MinorUnitsRescaleResult, MoneyColumnTarget } from '@happyvertical/smrt-core/migrations';
+/**
+ * Commerce money columns: floating-point major units → integer minor units.
+ *
+ * Ships as an explicit, opt-in migration rather than a schema-differ upgrade
+ * because REAL→INTEGER is not information-preserving: an automatic
+ * `ALTER … TYPE integer` would truncate a stored `19.99` to `19` and destroy 99
+ * cents on every row. The values have to be rescaled by the currency's
+ * minor-unit factor *during* the type change (#2401).
+ *
+ * Run it from one deploy process, after the writers are upgraded:
+ *
+ * ```ts
+ * import { getDatabase } from '@happyvertical/sql';
+ * import {
+ *   preflightCommerceMoneyMinorUnits,
+ *   migrateCommerceMoneyToMinorUnits,
+ * } from '@happyvertical/smrt-commerce';
+ *
+ * const db = await getDatabase({ type: 'postgres', url: process.env.DATABASE_URL! });
+ *
+ * // 1. Read-only. Prints rows that would be rounded or exceed JavaScript's
+ * //    safe-integer range when hydrated.
+ * console.log((await preflightCommerceMoneyMinorUnits(db)).summary);
+ *
+ * // 2. Convert. Idempotent — a second run is a no-op.
+ * await migrateCommerceMoneyToMinorUnits(db);
+ * ```
+ *
+ * Engine notes:
+ *
+ * - **PostgreSQL / DuckDB** — the column type changes in place with
+ *   `USING round(col * 100)`.
+ * - **SQLite** — values are rescaled, but the *declared* type cannot be altered
+ *   in place. SQLite's declared type is only an affinity, so the column already
+ *   behaves as integer minor units; bringing the declaration into line needs
+ *   the table-rebuild path (#2370). The result reports those columns in
+ *   `declaredTypeChangePending`.
+ *
+ * Fresh PostgreSQL and DuckDB INTEGER columns materialize as BIGINT. The
+ * preflight lists values that would exceed JavaScript's safe-integer range
+ * after rescaling, because SMRT rejects rather than rounds those on hydration.
+ * Existing PostgreSQL `int4` columns require the explicit widening in #2424.
+ *
+ * ## Two things this migration deliberately does NOT convert
+ *
+ * Both hold amounts in a **native asset's** minor unit rather than the
+ * deployment's currency, so there is no single scale that is correct for every
+ * row and a blanket ×100 would silently destroy data:
+ *
+ * - **`payments.native_amount`** — satoshis on a BTC rail (×1e8), cents on a
+ *   fiat or stablecoin rail (×1e2), in the same column, discriminated only by
+ *   `native_currency`. See {@link COMMERCE_NATIVE_UNIT_COLUMNS} for the
+ *   two-step conversion.
+ * - **`payment_intents.payment_options[].nativeAmount`** — the same problem
+ *   inside a JSON column, per option. Because an intent's price lock defaults
+ *   to 15 minutes, the supported answer is to **let open intents expire and be
+ *   re-quoted**: an unconverted option simply fails to reconcile against the
+ *   payment that arrives (the check is an exact `!==`), which is a safe, loud
+ *   failure rather than a silently mis-scaled quote.
+ */
+import { type DatabaseInterface, type MinorUnitsPreflightResult, type MinorUnitsRescaleResult, type MoneyColumnTarget } from '@happyvertical/smrt-core/migrations';
 /** Marker recorded in `_smrt_backfills` once the column rescale has run. */
 export declare const COMMERCE_MONEY_MINOR_UNITS_BACKFILL = "@happyvertical/smrt-commerce:money-minor-units:v1";
 /**

package/dist/models/Contract.d.ts

@@ -1,5 +1,9 @@
-import { Meta, SmrtObject } from '@happyvertical/smrt-core';
-import { ContractOptions, ContractStatus, ContractType, LicenseSaleOptions } from '../types/index.js';
+/**
+ * Contract model with STI for different contract types
+ * @packageDocumentation
+ */
+import { type Meta, SmrtObject } from '@happyvertical/smrt-core';
+import { type ContractOptions, ContractStatus, ContractType, type LicenseSaleOptions } from '../types/index.js';
 /**
  * Contract is the base class for all commercial agreements.
  *

package/dist/models/ContractLineItem.d.ts

@@ -1,5 +1,9 @@
+/**
+ * ContractLineItem model - individual items on a contract
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { ContractLineItemOptions } from '../types/index.js';
+import type { ContractLineItemOptions } from '../types/index.js';
 /**
  * ContractLineItem represents a single line item on a contract.
  *

package/dist/models/Customer.d.ts

@@ -1,5 +1,9 @@
+/**
+ * Customer model - links to Profile with customer-specific data
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { Address, CustomerOptions, CustomerStatus, CustomerType } from '../types/index.js';
+import { type Address, type CustomerOptions, CustomerStatus, CustomerType } from '../types/index.js';
 /**
  * Customer represents the customer role for a Profile.
  *

package/dist/models/Fulfillment.d.ts

@@ -1,5 +1,9 @@
+/**
+ * Fulfillment model - tracks delivery of contract items
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { Address, FulfillmentOptions, FulfillmentStatus, FulfillmentType } from '../types/index.js';
+import { type Address, type FulfillmentOptions, FulfillmentStatus, FulfillmentType } from '../types/index.js';
 /**
  * Fulfillment tracks the delivery or completion of contract items.
  *

package/dist/models/FulfillmentLineItem.d.ts

@@ -1,5 +1,9 @@
+/**
+ * FulfillmentLineItem model - tracks which contract items were fulfilled
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { FulfillmentLineItemOptions } from '../types/index.js';
+import type { FulfillmentLineItemOptions } from '../types/index.js';
 /**
  * FulfillmentLineItem tracks which contract line items are included
  * in a specific fulfillment and how much was fulfilled.

package/dist/models/Invoice.d.ts

@@ -1,6 +1,10 @@
+/**
+ * Invoice model - billing document sent to customers
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { Journal } from '@happyvertical/smrt-ledgers';
-import { AccountingInvoiceInput, InvoiceOptions, InvoiceStatus, RecognizeRevenueOptions } from '../types/index.js';
+import type { Journal } from '@happyvertical/smrt-ledgers';
+import { type AccountingInvoiceInput, type InvoiceOptions, InvoiceStatus, type RecognizeRevenueOptions } from '../types/index.js';
 /**
  * Invoice represents a bill sent to a customer for goods or services.
  *

package/dist/models/InvoiceLineItem.d.ts

@@ -1,5 +1,9 @@
+/**
+ * InvoiceLineItem model - individual items on an invoice
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { AccountingLineItemInput, InvoiceLineItemOptions } from '../types/index.js';
+import type { AccountingLineItemInput, InvoiceLineItemOptions } from '../types/index.js';
 /**
  * InvoiceLineItem represents a single line item on an invoice.
  *

package/dist/models/Payment.d.ts

@@ -1,6 +1,10 @@
+/**
+ * Payment model - tracks payments with ledger integration
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { Journal } from '@happyvertical/smrt-ledgers';
-import { PaymentMethod, PaymentOptions, PaymentStatus, RecordPaymentOptions } from '../types/index.js';
+import type { Journal } from '@happyvertical/smrt-ledgers';
+import { PaymentMethod, type PaymentOptions, PaymentStatus, type RecordPaymentOptions } from '../types/index.js';
 /**
  * Payment represents a financial transaction against a contract.
  *

package/dist/models/PaymentAllocation.d.ts

@@ -1,5 +1,9 @@
+/**
+ * PaymentAllocation model - maps payments to invoices
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { PaymentAllocationOptions } from '../types/index.js';
+import type { PaymentAllocationOptions } from '../types/index.js';
 /**
  * PaymentAllocation tracks how payments are applied to invoices.
  *

package/dist/models/PaymentInstrument.d.ts

@@ -1,5 +1,9 @@
+/**
+ * PaymentInstrument model - a reusable saved payment method ("card on file").
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { PaymentInstrumentOptions, PaymentInstrumentStatus } from '../types/index.js';
+import { type PaymentInstrumentOptions, PaymentInstrumentStatus } from '../types/index.js';
 /**
  * PaymentInstrument stores a reusable payment method a customer has saved with
  * a payment backend (e.g. a card vaulted by Stripe), so it can be charged later

package/dist/models/PaymentIntent.d.ts

@@ -1,5 +1,28 @@
+/**
+ * PaymentIntent — short-lived pre-payment commitment with multi-option
+ * semantics.
+ *
+ * A PaymentIntent is a one-shot quote that locks a USD price for a fixed
+ * window and lists one or more `PaymentOption`s describing different
+ * payment rails (USDC-on-Base, BTC, Stripe, etc.) that can each satisfy
+ * the intent. The first option that receives an incoming payment wins —
+ * the intent transitions to {@link PaymentIntentStatus.PAID} and the
+ * other options are implicitly retired. Later inbound funds to a
+ * retired option must be flagged for refund by the consumer's
+ * payment-routing layer.
+ *
+ * Distinct from `Estimate` (a long-form contract proposal STI subtype
+ * of `Contract`): a `PaymentIntent` is short-lived (minutes, not days),
+ * carries no line items, and exists to coordinate the moment-of-payment.
+ *
+ * Industry-neutral: any application that offers more than one route to
+ * pay for the same thing — marketplaces, billing systems with multi-
+ * provider checkout, agent-driven (x402) flows — benefits.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { PaymentIntentOptions, PaymentIntentStatus, PaymentOption } from '../types/index.js';
+import { type PaymentIntentOptions, PaymentIntentStatus, type PaymentOption } from '../types/index.js';
 export declare class PaymentIntent extends SmrtObject {
     /**
      * Tenant ID for multi-tenant isolation. Nullable so the same model

package/dist/models/Payout.d.ts

@@ -1,5 +1,28 @@
+/**
+ * Payout — operator-to-supplier outgoing remittance.
+ *
+ * A Payout sits on the opposite side of a {@link Payment}: it tracks
+ * funds *leaving* the operator's wallet and arriving at a vendor's
+ * payout address. The two are kept as distinct models (rather than
+ * overloading `Payment` with a `direction` field) because the status
+ * machine, chain semantics, and audit story differ.
+ *
+ * Industry-neutral: any operator that ingests one payment and remits
+ * funds to a third party — marketplaces, payment processors with
+ * Connect-style fan-out, royalty distributors, escrow services —
+ * benefits.
+ *
+ * MVP scope: no currency conversion. The payout's amounts and currency
+ * mirror the originating Payment's native currency, and the vendor
+ * needs a matching `Vendor.payoutAddresses` entry to receive funds.
+ * Filtering at quote time (`PaymentIntent.paymentOptions`) is the
+ * consumer's job; the model just enforces the natural-key invariant
+ * and the status machine.
+ *
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { PayoutOptions, PayoutStatus } from '../types/index.js';
+import { type PayoutOptions, PayoutStatus } from '../types/index.js';
 export declare class Payout extends SmrtObject {
     /**
      * Tenant ID for multi-tenant isolation. Nullable so global / single-

package/dist/models/Vendor.d.ts

@@ -1,5 +1,9 @@
+/**
+ * Vendor model - links to Profile with vendor-specific data
+ * @packageDocumentation
+ */
 import { SmrtObject } from '@happyvertical/smrt-core';
-import { VendorOptions, VendorStatus } from '../types/index.js';
+import { type VendorOptions, VendorStatus } from '../types/index.js';
 /**
  * Vendor represents the vendor/supplier role for a Profile.
  *

package/dist/models/billing.d.ts

@@ -1,5 +1,12 @@
+/**
+ * Billing-period close records (#3060).
+ *
+ * These are system tables managed by `BillingRuntime`, like smrt-tenancy's
+ * `_smrt_billing_relationships`: they span a seller and its payers, so they
+ * are not tenant-scoped and have no generated API, CLI, or MCP surface.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { JobExecutionContext } from '@happyvertical/smrt-jobs';
+import { type JobExecutionContext } from '@happyvertical/smrt-jobs';
 /**
  * Who a runtime bills. `provider` closes the platform's `ClientCharge`s,
  * their `BillingAdjustment`s, and the platform's flat plans; `reseller`

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-commerce",
-  "packageVersion": "0.51.31",
+  "packageVersion": "0.51.33",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "688c5d915cea4eaf60b54eafc4b161e14d6143fefc3043d54020c9e18f02aa17",
-    "packageJson": "e6ee5f0d8e93f49996a8f9e565c02e5e8524ac73c12188669db6123b60aaa233",
+    "manifest": "e0d8ced41c0783b44fcecbc8b7deec93a522341696cac0d14b0be9710c0985a9",
+    "packageJson": "c16cfdd1a63bd45bbfeb58f75d92bf824f9ec31856a7354e5a23b4f01e52c6ef",
     "agents": "05a98db8f3cc2137b030cbcbaedb112880f42613574cea68f6aebe03b7adcc3b"
   },
   "exports": [
@@ -34,7 +34,7 @@
     "fast-glob": "^3.3.3",
     "svelte": "^5.57.1",
     "svelte-check": "^4.7.6",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },

package/dist/types/index.d.ts

@@ -1,4 +1,8 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Commerce package type definitions
+ * @packageDocumentation
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
 export declare enum CustomerStatus {
     ACTIVE = "active",
     INACTIVE = "inactive",

package/dist/ui.d.ts

@@ -1,4 +1,17 @@
-import { ModuleUISlot, SmrtModuleMeta } from '@happyvertical/smrt-types';
+/**
+ * Commerce Module UI Slot Declarations
+ *
+ * This file defines the UI extension points for the commerce module.
+ * UI components are implemented in the ./svelte subpath.
+ *
+ * @example Usage
+ * ```typescript
+ * // In application code
+ * import { COMMERCE_MODULE_META } from '@happyvertical/smrt-commerce';
+ * console.log(COMMERCE_MODULE_META.uiSlots);
+ * ```
+ */
+import type { ModuleUISlot, SmrtModuleMeta } from '@happyvertical/smrt-types';
 /**
  * Commerce module UI slots
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-commerce",
-  "version": "0.51.31",
+  "version": "0.51.33",
   "smrtJsdoc": "strict",
   "description": "Commerce models for the SMRT framework - contracts, fulfillments, payments",
   "type": "module",
@@ -51,13 +51,13 @@
   },
   "dependencies": {
     "@happyvertical/accounting": "^0.94.1",
-    "@happyvertical/smrt-core": "0.51.31",
-    "@happyvertical/smrt-jobs": "0.51.31",
-    "@happyvertical/smrt-ledgers": "0.51.31",
-    "@happyvertical/smrt-subscriptions": "0.51.31",
-    "@happyvertical/smrt-tenancy": "0.51.31",
-    "@happyvertical/smrt-types": "0.51.31",
-    "@happyvertical/smrt-ui": "0.51.31"
+    "@happyvertical/smrt-core": "0.51.33",
+    "@happyvertical/smrt-jobs": "0.51.33",
+    "@happyvertical/smrt-ledgers": "0.51.33",
+    "@happyvertical/smrt-subscriptions": "0.51.33",
+    "@happyvertical/smrt-tenancy": "0.51.33",
+    "@happyvertical/smrt-types": "0.51.33",
+    "@happyvertical/smrt-ui": "0.51.33"
   },
   "peerDependencies": {
     "svelte": "^5.57.1"
@@ -68,14 +68,14 @@
     }
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.51.31",
+    "@happyvertical/smrt-vitest": "0.51.33",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@types/node": "24.13.6",
     "fast-glob": "^3.3.3",
     "svelte": "^5.57.1",
     "svelte-check": "^4.7.6",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },