@happyvertical/smrt-commerce 0.30.0

package/AGENTS.md

@@ -0,0 +1,44 @@
+# @happyvertical/smrt-commerce
+
+E-commerce with Contract STI hierarchy, invoice lifecycle, payment tracking, payout remittance, and optional ledger integration.
+
+## Models
+
+- **Customer** / **Vendor**: linked to Profile via string ID (not FK). Customer has creditLimit, paymentTerms, customerType (DTC / WHOLESALE / RETAIL). Vendor has leadTimeDays, minimumOrder, and `payoutAddresses: Record<string, string>` — a flat map from payout-rail-qualified currency code (`USDC-base`, `BTC`, `USD-stripe`, ...) to destination string (EVM address, BTC address, Stripe Connect account id, IBAN). Use `getPayoutAddress(currency)` for a `Map.get`-style lookup; missing entries return `undefined` (caller decides skip-vs-error).
+- **Contract** (STI base → Estimate, Order, Lease, Agreement, PurchaseOrder, WholesaleOrder, ProductionOrder, Cart, LicenseSale): 9 contract types sharing one table. Carries `channelId` (open-ended string — `dtc-web`, `wholesale-b2b`, `pos-store-N`, etc.) so the same model serves DTC checkout, B2B portals, and POS.
+- **WholesaleOrder**: B2B order. Conventional pairing — customer has `customerType: 'wholesale'`, NET-30/60 terms, delivered via wholesale-portal channel.
+- **ProductionOrder**: manufacturing equivalent of a PurchaseOrder — commission your factory to make finished goods. Consumes raw materials per BOM (`@happyvertical/smrt-manufacturing`) and produces SKU stock (`@happyvertical/smrt-inventory`).
+- **Cart**: transient order-in-progress. Same shape as Order; the application promotes the row from `_meta_type: Cart` to `_meta_type: Order` at checkout instead of copying data between tables.
+- **LicenseSale**: industry-neutral licensing primitive. Carries an *immutable* rights snapshot (`rightsMedium`, `rightsDistributionScope`, `rightsExclusivity`, `rightsDuration`, `rightsTerritory`, `rightsSublicensing`, `rightsDerivatives` — typed `Meta<T>` fields), licensee identity (`licenseeEmail`, optional `licenseeLegalEntity` / `licenseeJurisdiction`), and a signed-PDF reference (`pdfUrl`, `pdfHash`, optional `onChainHashRegistryRef`). Once saved at `ContractStatus.ACCEPTED`, the rights snapshot is frozen — mutating any of the seven rights fields and re-saving throws. The only legal transition out of ACCEPTED is `revoke()` (moves to CANCELLED without touching rights). Useful for stock media, music licensing, code-asset marketplaces, license keys, anywhere rights are sold for a fee.
+- **ContractLineItem**: items on contracts.
+- **Invoice**: status machine `DRAFT → SENT → VIEWED → PARTIAL → PAID` (also OVERDUE, CANCELLED, WRITTEN_OFF). `recognizeRevenue()` creates balanced AR journal entry (DR: Accounts Receivable, CR: Revenue, CR: Tax Payable).
+- **InvoiceLineItem**: line items on invoices.
+- **Payment** / **PaymentAllocation**: tracks payments against invoices. Status controlled by `Invoice.updatePaymentStatus()`, not Payment model. Carries optional backend-adapter fields for PaymentBackend-routed flows: `backendId` (rail adapter id — `base-usdc`, `btc`, `stripe`, distinct from `externalProvider` which names an accounting sync destination), `backendTxRef` (chain tx hash or gateway settlement id), `nativeAmount` / `nativeCurrency` (what actually arrived), `usdAtQuote` / `usdAtConfirmation` (drift accounting for volatile-currency rails). `Payment.usdDrift()` returns the confirmation - quote delta, or `0` when either side is unset.
+- **PaymentIntent**: short-lived pre-payment commitment with multi-option semantics. Locks a USD price for a fixed window (default 15 minutes) and lists one or more `PaymentOption`s describing different rails (`backendId`, `currency`, `payTo`, `nativeAmount`, optional `chain` / `memo` / `x402Capable` / `expiresAt`). First option to receive payment wins; the others are implicitly retired. State machine `awaiting_payment → paid → (issued | retired)` plus `expired` and `cancelled`. Mutate via dedicated `markPaid` / `markIssued` / `expire` / `cancel` / `retire` helpers — direct status assignment bypasses the invariant checks. Idempotency via natural key `(tenant_id, offering_ref, licensee_email, idempotency_key)` and `PaymentIntentCollection.getOrCreateByIdempotencyKey()`.
+- **Payout**: operator-to-supplier remittance. Distinct from Payment because direction, status machine, and chain semantics differ. Status machine `pending → sent → confirmed → failed` (failed is terminal but resettable via `resetFromFailed()` after fixing the underlying problem). References source `paymentId` (plain string) and destination `vendorId` (foreign key). Amount invariant `supplierNet === grossAmount - operatorFee` (1¢ rounding tolerance) enforced on save. `PayoutCollection.createFromPayment()` is the typical entry point; it pulls native amount / currency from the source Payment.
+- **Fulfillment** / **FulfillmentLineItem**: shipment/delivery tracking.
+
+## Ledger Integration
+
+`@happyvertical/smrt-ledgers` is a regular dependency, loaded lazily via dynamic `import()` so the coupling stays runtime-only (no hard static import; the package graph stays a DAG — see #1582). Invoice stores `arJournalId` and `revenueJournalId` as string references. `recognizeRevenue()` creates a balanced AR journal entry; `getArJournal()` returns null when no journal has been recognized yet.
+
+## Cross-Package References
+
+- `customerId` → `@foreignKey('Customer')` (hard reference within package)
+- `profileId` → plain string to smrt-profiles
+- `arJournalId`, `revenueJournalId` → plain string to smrt-ledgers
+- `skuId` (on `PaymentIntent`, `LicenseSale`) → plain string to smrt-products
+- `paymentId` (on `PaymentIntent`, `Payout`, `LicenseSale`) → plain string to `Payment` (same package, but kept as plain string for cross-model consistency)
+- `vendorId` on `Payout` → `@foreignKey(Vendor)` (hard reference within package)
+
+## Gotchas
+
+- **Optional tenancy**: all models `@TenantScoped({ mode: 'optional' })` + nullable tenantId
+- **Currency in decimal fields**: price, taxAmount, totalAmount (not integer cents like affiliates)
+- **Invoice controls payment status**: not the Payment model — use `Invoice.updatePaymentStatus()`
+- **Tax rate is external**: no tax rate field on Invoice — rate must be calculated externally
+- **Profile linking**: separate `ProfileCollection.create()` needed to fetch actual Profile object
+- **PaymentIntent natural key**: `conflictColumns: ['tenant_id', 'offering_ref', 'licensee_email', 'idempotency_key']` — a retried `create` with the same tuple upserts the existing row. Use `getOrCreateByIdempotencyKey()` to branch on `{ intent, created }`. Empty natural-key inputs (e.g. blank `idempotencyKey`) disable dedup by design.
+- **Payout state-machine guards**: `markSent` requires a non-empty `backendTxRef`; `markConfirmed` only valid from `SENT`; `markFailed` only valid from `PENDING` / `SENT` (a confirmed payout can't fail — that path is a refund). `resetFromFailed()` is the dedicated escape hatch from `FAILED` back to `PENDING` after an operator fixes the underlying problem; it clears `backendTxRef` so the next attempt picks up a fresh one.
+- **LicenseSale immutability**: rights snapshot freezes on save-with-status-ACCEPTED. The captured snapshot lives in a module-scoped `WeakMap<LicenseSale, string>` so it doesn't interact with the schema or round-trip through `_meta_data`. Drafts (status != ACCEPTED) remain mutable. To "change" an issued license: `revoke()` it, then issue a new `LicenseSale` row.
+- **Vendor.payoutAddresses normalization**: the constructor accepts either a `Record<string, string>` or a pre-serialized JSON string. `initialize()` re-normalizes after the framework's option-override pass; `save()` re-normalizes defensively against direct field assignment. Non-string values inside the input map are silently dropped to preserve the typed invariant downstream.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# @happyvertical/smrt-commerce
+
+Commerce models for the SMRT framework. Covers customers, vendors, contracts (5 STI types), invoices with ledger integration, payments, and fulfillment tracking.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-commerce
+```
+
+## Usage
+
+```typescript
+import {
+  Customer, CustomerCollection,
+  Order, ContractCollection,
+  Invoice, InvoiceCollection,
+  Payment, PaymentCollection,
+  ContractStatus, InvoiceStatus, PaymentMethod
+} from '@happyvertical/smrt-commerce';
+
+// Create a customer linked to a profile
+const customers = new CustomerCollection(db);
+const customer = await customers.create({
+  profileId: 'profile-uuid',
+  creditLimit: 10000.00,
+  paymentTerms: 'Net 30',
+});
+await customer.save();
+
+// Create an order (STI contract type)
+const contracts = new ContractCollection(db);
+const order = await contracts.create({
+  _meta_type: 'Order',
+  customerId: customer.id,
+  subtotal: 1000.00,
+  taxAmount: 50.00,
+  totalAmount: 1050.00,
+  currency: 'CAD',
+});
+await order.save();
+
+// Create an invoice for the order
+const invoices = new InvoiceCollection(db);
+const invoiceNumber = await invoices.generateInvoiceNumber();
+const invoice = await invoices.create({
+  customerId: customer.id,
+  contractId: order.id,
+  invoiceNumber,
+  subtotal: 1000.00,
+  taxAmount: 50.00,
+  totalAmount: 1050.00,
+});
+await invoice.save();
+
+// Recognize revenue (creates balanced journal in smrt-ledgers)
+await invoice.recognizeRevenue({
+  arAccountId: 'ar-account-id',
+  revenueAccountId: 'revenue-account-id',
+  taxAccountId: 'tax-account-id',
+});
+
+// Record a payment
+const payments = new PaymentCollection(db);
+const payment = await payments.create({
+  contractId: order.id,
+  customerId: customer.id,
+  amount: 1050.00,
+  method: PaymentMethod.CREDIT_CARD,
+});
+await payment.save();
+
+// Record payment with ledger integration
+await payment.recordPayment({
+  ledgerId: 'ledger-id',
+  receivablesAccountId: 'ar-account-id',
+  cashAccountId: 'bank-account-id',
+});
+```
+
+## API
+
+### Models
+
+| Export | Description |
+|--------|------------|
+| `Customer` | Customer record with creditLimit, paymentTerms, tax exemption, addresses |
+| `Vendor` | Vendor/supplier with leadTimeDays, minimumOrderAmount, currency |
+| `Contract` | STI base class for all commercial agreements |
+| `Estimate` | Quote or proposal sent to a customer |
+| `Order` | Customer purchase order |
+| `Lease` | Rental or lease agreement |
+| `Agreement` | Service or maintenance agreement |
+| `PurchaseOrder` | Order sent to a vendor/supplier |
+| `ContractLineItem` | Line item within a contract |
+| `Invoice` | Billing document with status lifecycle and ledger integration |
+| `InvoiceLineItem` | Individual invoice line item |
+| `Payment` | Payment record with method, status, and optional ledger journal |
+| `PaymentAllocation` | Payment-to-invoice allocation |
+| `Fulfillment` | Shipment/delivery tracking with carrier and address |
+| `FulfillmentLineItem` | Individual fulfillment line item |
+
+### Collections
+
+`CustomerCollection`, `VendorCollection`, `ContractCollection`, `InvoiceCollection`, `InvoiceLineItemCollection`, `PaymentCollection`, `PaymentAllocationCollection`, `FulfillmentCollection`
+
+### Enums
+
+| Export | Values |
+|--------|--------|
+| `ContractType` | `estimate`, `order`, `lease`, `agreement`, `purchase_order` |
+| `ContractStatus` | `draft`, `sent`, `accepted`, `declined`, `completed`, `cancelled` |
+| `CustomerStatus` | `active`, `inactive`, `suspended` |
+| `VendorStatus` | `active`, `inactive`, `suspended` |
+| `InvoiceStatus` | `draft`, `sent`, `viewed`, `partial`, `paid`, `overdue`, `cancelled`, `written_off` |
+| `PaymentMethod` | `cash`, `check`, `credit_card`, `bank_transfer`, `crypto`, `other` |
+| `PaymentStatus` | `pending`, `completed`, `failed`, `refunded`, `cancelled` |
+| `FulfillmentStatus` | `pending`, `processing`, `shipped`, `delivered`, `cancelled` |
+| `FulfillmentType` | `shipment`, `delivery`, `pickup`, `digital`, `service` |
+
+### Types and Constants
+
+| Export | Description |
+|--------|------------|
+| `Address` | Shared address interface (street1, street2, city, state, postalCode, country) |
+| `RecognizeRevenueOptions` | Account IDs for invoice revenue recognition |
+| `RecordPaymentOptions` | Ledger and account IDs for payment recording |
+| `InvoiceNumberOptions` | Options for `generateInvoiceNumber()` (prefix, format) |
+| `UNPAID_STATUSES` | Array of invoice statuses considered unpaid (sent, viewed, partial, overdue) |
+| `COMMERCE_MODULE_META` | UI module metadata |
+| `COMMERCE_UI_SLOTS` | UI slot definitions |
+
+### Ledger Integration
+
+Invoice and Payment integrate with `@happyvertical/smrt-ledgers` via dynamic import (optional dependency). Invoice stores `arJournalId` and `revenueJournalId` as plain string references to ledger journals. `recognizeRevenue()` creates a balanced AR entry (DR: Accounts Receivable, CR: Revenue, CR: Tax Payable). `recordPayment()` creates a balanced cash receipt entry (DR: Cash, CR: Accounts Receivable). Both methods return null or throw if the ledgers package is not installed.
+
+### Cross-Package References
+
+Customer and Vendor link to `@happyvertical/smrt-profiles` via plain `profileId` string. Invoice and Payment reference `@happyvertical/smrt-ledgers` journals via plain string IDs (`arJournalId`, `revenueJournalId`, `journalId`). All models use `@TenantScoped({ mode: 'optional' })` with nullable `tenantId`.
+
+## Dependencies
+
+- `@happyvertical/smrt-core` -- ORM and code generation
+- `@happyvertical/smrt-tenancy` -- multi-tenant scoping
+- `@happyvertical/smrt-types` -- shared type definitions
+- Peer: `@happyvertical/smrt-ledgers`, `@happyvertical/smrt-profiles`, `@happyvertical/smrt-svelte`

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/collections/ContractCollection.d.ts

@@ -0,0 +1,87 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { Contract } from '../models/Contract.js';
+import { ContractStatus, ContractType } from '../types/index.js';
+export declare class ContractCollection extends SmrtCollection<Contract> {
+    static readonly _itemClass: typeof Contract;
+    /**
+     * Find contracts by customer
+     *
+     * @param customerId - Customer ID
+     * @returns Array of contracts
+     */
+    findByCustomer(customerId: string): Promise<Contract[]>;
+    /**
+     * Find contracts by vendor
+     *
+     * @param vendorId - Vendor ID
+     * @returns Array of contracts
+     */
+    findByVendor(vendorId: string): Promise<Contract[]>;
+    /**
+     * Find contracts by type (STI)
+     *
+     * @param contractType - Contract type
+     * @returns Array of contracts
+     */
+    findByType(contractType: ContractType): Promise<Contract[]>;
+    /**
+     * Find contracts by status
+     *
+     * @param status - Contract status
+     * @returns Array of contracts
+     */
+    findByStatus(status: ContractStatus): Promise<Contract[]>;
+    /**
+     * Find all draft contracts
+     *
+     * @returns Array of draft contracts
+     */
+    findDrafts(): Promise<Contract[]>;
+    /**
+     * Find all accepted contracts
+     *
+     * @returns Array of accepted contracts
+     */
+    findAccepted(): Promise<Contract[]>;
+    /**
+     * Find overdue contracts
+     *
+     * @returns Array of overdue contracts
+     */
+    findOverdue(): Promise<Contract[]>;
+    /**
+     * Find expired estimates/quotes
+     *
+     * @returns Array of expired estimates
+     */
+    findExpired(): Promise<Contract[]>;
+    /**
+     * Find contracts in date range
+     *
+     * @param startDate - Start date
+     * @param endDate - End date
+     * @returns Array of contracts
+     */
+    findByDateRange(startDate: Date, endDate: Date): Promise<Contract[]>;
+    /**
+     * Find all contracts belonging to a specific tenant
+     *
+     * @param tenantId - Tenant ID
+     * @returns Array of contracts for the tenant
+     */
+    findByTenant(tenantId: string): Promise<Contract[]>;
+    /**
+     * Find all global contracts (not associated with any tenant)
+     *
+     * @returns Array of global contracts
+     */
+    findGlobal(): Promise<Contract[]>;
+    /**
+     * Find contracts for a tenant including global contracts
+     *
+     * @param tenantId - Tenant ID
+     * @returns Array of tenant-specific and global contracts
+     */
+    findWithGlobals(tenantId: string): Promise<Contract[]>;
+}
+//# sourceMappingURL=ContractCollection.d.ts.map

package/dist/collections/ContractCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContractCollection.d.ts","sourceRoot":"","sources":["../../src/collections/ContractCollection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjE,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC9D,MAAM,CAAC,QAAQ,CAAC,UAAU,kBAAY;IAEtC;;;;;OAKG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAO7D;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAOzD;;;;;OAKG;IACG,UAAU,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAOjE;;;;;OAKG;IACG,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAO/D;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIvC;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIzC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAgBxC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAkBxC;;;;;;OAMG;IACG,eAAe,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAc1E;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIzD;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIvC;;;;;OAKG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAM7D"}

package/dist/collections/CustomerCollection.d.ts

@@ -0,0 +1,58 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { Customer } from '../models/Customer.js';
+import { CustomerStatus } from '../types/index.js';
+export declare class CustomerCollection extends SmrtCollection<Customer> {
+    static readonly _itemClass: typeof Customer;
+    /**
+     * Find customers by profile ID
+     *
+     * @param profileId - Profile ID from smrt-profiles
+     * @returns Array of customers linked to this profile
+     */
+    findByProfile(profileId: string): Promise<Customer[]>;
+    /**
+     * Find all active customers
+     *
+     * @returns Array of active customers
+     */
+    findActive(): Promise<Customer[]>;
+    /**
+     * Find customers by status
+     *
+     * @param status - Customer status
+     * @returns Array of customers
+     */
+    findByStatus(status: CustomerStatus): Promise<Customer[]>;
+    /**
+     * Get or create a customer for a profile
+     *
+     * @param profileId - Profile ID
+     * @param defaults - Default values if creating
+     * @returns Customer
+     */
+    getOrCreateForProfile(profileId: string, defaults?: Partial<{
+        creditLimit: number;
+        paymentTerms: string;
+    }>): Promise<Customer>;
+    /**
+     * Find all customers belonging to a specific tenant
+     *
+     * @param tenantId - Tenant ID
+     * @returns Array of customers for the tenant
+     */
+    findByTenant(tenantId: string): Promise<Customer[]>;
+    /**
+     * Find all global customers (not associated with any tenant)
+     *
+     * @returns Array of global customers
+     */
+    findGlobal(): Promise<Customer[]>;
+    /**
+     * Find customers for a tenant including global customers
+     *
+     * @param tenantId - Tenant ID
+     * @returns Array of tenant-specific and global customers
+     */
+    findWithGlobals(tenantId: string): Promise<Customer[]>;
+}
+//# sourceMappingURL=CustomerCollection.d.ts.map

package/dist/collections/CustomerCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomerCollection.d.ts","sourceRoot":"","sources":["../../src/collections/CustomerCollection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC9D,MAAM,CAAC,QAAQ,CAAC,UAAU,kBAAY;IAEtC;;;;;OAKG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAO3D;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAOvC;;;;;OAKG;IACG,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAO/D;;;;;;OAMG;IACG,qBAAqB,CACzB,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,OAAO,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAM,GACN,OAAO,CAAC,QAAQ,CAAC;IAoBpB;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIzD;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIvC;;;;;OAKG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAM7D"}

package/dist/collections/FulfillmentCollection.d.ts

@@ -0,0 +1,75 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { Fulfillment } from '../models/Fulfillment.js';
+import { FulfillmentStatus, FulfillmentType } from '../types/index.js';
+export declare class FulfillmentCollection extends SmrtCollection<Fulfillment> {
+    static readonly _itemClass: typeof Fulfillment;
+    /**
+     * Find fulfillments by contract
+     *
+     * @param contractId - Contract ID
+     * @returns Array of fulfillments
+     */
+    findByContract(contractId: string): Promise<Fulfillment[]>;
+    /**
+     * Find fulfillments by status
+     *
+     * @param status - Fulfillment status
+     * @returns Array of fulfillments
+     */
+    findByStatus(status: FulfillmentStatus): Promise<Fulfillment[]>;
+    /**
+     * Find fulfillments by type
+     *
+     * @param fulfillmentType - Fulfillment type
+     * @returns Array of fulfillments
+     */
+    findByType(fulfillmentType: FulfillmentType): Promise<Fulfillment[]>;
+    /**
+     * Find all pending fulfillments
+     *
+     * @returns Array of pending fulfillments
+     */
+    findPending(): Promise<Fulfillment[]>;
+    /**
+     * Find all in-transit shipments
+     *
+     * @returns Array of shipped fulfillments
+     */
+    findInTransit(): Promise<Fulfillment[]>;
+    /**
+     * Find by tracking number
+     *
+     * @param trackingNumber - Tracking number
+     * @returns Fulfillment or null
+     */
+    findByTracking(trackingNumber: string): Promise<Fulfillment | null>;
+    /**
+     * Find fulfillments shipped in date range
+     *
+     * @param startDate - Start date
+     * @param endDate - End date
+     * @returns Array of fulfillments
+     */
+    findShippedInRange(startDate: Date, endDate: Date): Promise<Fulfillment[]>;
+    /**
+     * Find all fulfillments belonging to a specific tenant
+     *
+     * @param tenantId - Tenant ID
+     * @returns Array of fulfillments for the tenant
+     */
+    findByTenant(tenantId: string): Promise<Fulfillment[]>;
+    /**
+     * Find all global fulfillments (not associated with any tenant)
+     *
+     * @returns Array of global fulfillments
+     */
+    findGlobal(): Promise<Fulfillment[]>;
+    /**
+     * Find fulfillments for a tenant including global fulfillments
+     *
+     * @param tenantId - Tenant ID
+     * @returns Array of tenant-specific and global fulfillments
+     */
+    findWithGlobals(tenantId: string): Promise<Fulfillment[]>;
+}
+//# sourceMappingURL=FulfillmentCollection.d.ts.map

package/dist/collections/FulfillmentCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FulfillmentCollection.d.ts","sourceRoot":"","sources":["../../src/collections/FulfillmentCollection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE5E,qBAAa,qBAAsB,SAAQ,cAAc,CAAC,WAAW,CAAC;IACpE,MAAM,CAAC,QAAQ,CAAC,UAAU,qBAAe;IAEzC;;;;;OAKG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAOhE;;;;;OAKG;IACG,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAOrE;;;;;OAKG;IACG,UAAU,CAAC,eAAe,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAO1E;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAI3C;;;;OAIG;IACG,aAAa,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAI7C;;;;;OAKG;IACG,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAQzE;;;;;;OAMG;IACG,kBAAkB,CACtB,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,IAAI,GACZ,OAAO,CAAC,WAAW,EAAE,CAAC;IAczB;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAI5D;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAI1C;;;;;OAKG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CAMhE"}

package/dist/collections/InvoiceCollection.d.ts

@@ -0,0 +1,162 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { Invoice } from '../models/Invoice.js';
+import { InvoiceStatus } from '../types/index.js';
+/**
+ * Statuses that indicate an invoice has outstanding balance.
+ * Used for calculating outstanding amounts and finding unpaid invoices.
+ */
+export declare const UNPAID_STATUSES: readonly [InvoiceStatus.SENT, InvoiceStatus.VIEWED, InvoiceStatus.PARTIAL, InvoiceStatus.OVERDUE];
+/**
+ * Options for generating invoice numbers
+ */
+export interface InvoiceNumberOptions {
+    /** Prefix for invoice numbers (default: 'INV') */
+    prefix?: string;
+    /** Format: 'prefix-year-seq' or 'prefix-seq' (default: 'prefix-year-seq') */
+    format?: 'prefix-year-seq' | 'prefix-seq';
+}
+export declare class InvoiceCollection extends SmrtCollection<Invoice> {
+    static readonly _itemClass: typeof Invoice;
+    /**
+     * Find invoices by customer
+     *
+     * @param customerId - Customer ID
+     * @returns Array of invoices
+     */
+    findByCustomer(customerId: string): Promise<Invoice[]>;
+    /**
+     * Find invoices by contract
+     *
+     * @param contractId - Contract ID
+     * @returns Array of invoices
+     */
+    findByContract(contractId: string): Promise<Invoice[]>;
+    /**
+     * Find invoices by status
+     *
+     * @param status - Invoice status
+     * @returns Array of invoices
+     */
+    findByStatus(status: InvoiceStatus): Promise<Invoice[]>;
+    /**
+     * Find all draft invoices
+     *
+     * @returns Array of draft invoices
+     */
+    findDrafts(): Promise<Invoice[]>;
+    /**
+     * Find all sent invoices
+     *
+     * @returns Array of sent invoices
+     */
+    findSent(): Promise<Invoice[]>;
+    /**
+     * Find all paid invoices
+     *
+     * @returns Array of paid invoices
+     */
+    findPaid(): Promise<Invoice[]>;
+    /**
+     * Find all partial invoices
+     *
+     * @returns Array of partially paid invoices
+     */
+    findPartial(): Promise<Invoice[]>;
+    /**
+     * Find overdue invoices (past due date, not paid).
+     *
+     * **Note**: This method finds invoices by date, but does not automatically
+     * update their status to OVERDUE. Use a background job or scheduled task
+     * to periodically update invoice statuses based on due dates.
+     *
+     * @returns Array of overdue invoices
+     */
+    findOverdue(): Promise<Invoice[]>;
+    /**
+     * Find invoices in date range (by issue date)
+     *
+     * @param startDate - Start date
+     * @param endDate - End date
+     * @returns Array of invoices
+     */
+    findByDateRange(startDate: Date, endDate: Date): Promise<Invoice[]>;
+    /**
+     * Find invoice by external ID (from accounting provider)
+     *
+     * @param externalId - External ID
+     * @returns Invoice or null
+     */
+    findByExternalId(externalId: string): Promise<Invoice | null>;
+    /**
+     * Find invoices needing sync to external provider
+     * (no externalId or stale syncedAt)
+     *
+     * @returns Array of invoices needing sync
+     */
+    findNeedingSync(): Promise<Invoice[]>;
+    /**
+     * Find invoice by invoice number
+     *
+     * @param invoiceNumber - Invoice number
+     * @returns Invoice or null
+     */
+    findByNumber(invoiceNumber: string): Promise<Invoice | null>;
+    /**
+     * Count invoices for a given year
+     *
+     * @param year - Year to count
+     * @returns Number of invoices
+     */
+    countForYear(year: number): Promise<number>;
+    /**
+     * Generate the next invoice number.
+     *
+     * **Warning**: This method has a potential race condition if multiple
+     * invoices are created concurrently. For high-concurrency environments,
+     * consider using a database sequence or atomic counter instead.
+     *
+     * @param options - Optional configuration for number format
+     * @returns Generated invoice number (e.g., 'INV-2025-0001')
+     *
+     * @example
+     * ```typescript
+     * // Default format: INV-2025-0001
+     * const num = await invoices.generateInvoiceNumber();
+     *
+     * // Custom prefix: BILL-2025-0001
+     * const num = await invoices.generateInvoiceNumber({ prefix: 'BILL' });
+     *
+     * // Simple sequential: INV-000001
+     * const num = await invoices.generateInvoiceNumber({ format: 'prefix-seq' });
+     * ```
+     */
+    generateInvoiceNumber(options?: InvoiceNumberOptions): Promise<string>;
+    /**
+     * Get total outstanding (unpaid) amount for a customer
+     *
+     * @param customerId - Customer ID
+     * @returns Total amount due
+     */
+    getTotalOutstandingForCustomer(customerId: string): Promise<number>;
+    /**
+     * Find all invoices belonging to a specific tenant
+     *
+     * @param tenantId - Tenant ID
+     * @returns Array of invoices for the tenant
+     */
+    findByTenant(tenantId: string): Promise<Invoice[]>;
+    /**
+     * Find all global invoices (not associated with any tenant)
+     *
+     * @returns Array of global invoices
+     */
+    findGlobal(): Promise<Invoice[]>;
+    /**
+     * Find invoices for a tenant including global invoices
+     *
+     * @param tenantId - Tenant ID
+     * @returns Array of tenant-specific and global invoices
+     */
+    findWithGlobals(tenantId: string): Promise<Invoice[]>;
+}
+//# sourceMappingURL=InvoiceCollection.d.ts.map

package/dist/collections/InvoiceCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvoiceCollection.d.ts","sourceRoot":"","sources":["../../src/collections/InvoiceCollection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,eAAe,mGAKlB,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,iBAAiB,GAAG,YAAY,CAAC;CAC3C;AAED,qBAAa,iBAAkB,SAAQ,cAAc,CAAC,OAAO,CAAC;IAC5D,MAAM,CAAC,QAAQ,CAAC,UAAU,iBAAW;IAErC;;;;;OAKG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAO5D;;;;;OAKG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAO5D;;;;;OAKG;IACG,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAO7D;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAItC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAIpC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAIpC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAIvC;;;;;;;;OAQG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAgBvC;;;;;;OAMG;IACG,eAAe,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAUzE;;;;;OAKG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAQnE;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAc3C;;;;;OAKG;IACG,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAQlE;;;;;OAKG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAcjD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,qBAAqB,CACzB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC;IAkBlB;;;;;OAKG;IACG,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBzE;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAIxD;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAItC;;;;;OAKG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAM5D"}