@happyvertical/smrt-commerce 0.51.23 → 0.51.24

package/AGENTS.md

@@ -23,6 +23,52 @@ E-commerce with Contract STI hierarchy, invoice lifecycle, payment tracking, pay
 
 `@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.
 
+## Billing-period close (#3060)
+
+`src/billing/` closes periods from smrt-subscriptions charges; see the README
+for usage.
+
+- **Port, not provider.** Period close, events, and credit checkout call only
+  the `BillingProvider` port (integer minor units). `stripe.ts` adapts
+  `@happyvertical/accounting`, which takes currency *major* units; convert with
+  `units.ts` (ISO 4217 exponent) and never hand-roll a Stripe call here.
+  `sendAndReconcile` refuses a provider invoice whose subtotal or total
+  disagrees with the local invoice.
+- **Replay safety is identity.** Close, invoice, line, payment, allocation,
+  and claim ids are `deterministicId()`s; `BillingLineSource` (conflict key
+  `source_type, source_id`) is the only double-billing guard, so never bill a
+  source without claiming it, and never widen that key. Each close step is
+  persisted before the next; `acquireCloseLease()` serializes workers. A
+  close that nets to a credit keeps its claims and ends `carried_forward`;
+  its subtotal is a `credit_carry_forward` source for the payer's next billed
+  close, which marks the carried close `completed`.
+- **System tables.** `BillingAccount`, `BillingPeriodClose`, and
+  `BillingLineSource` are not tenant-scoped and have no generated surface.
+  Collections stay unexported; models are root exports (#3082). Invoices,
+  payments, and journals are written in the seller's tenant; payer-owned
+  subscriptions and credit grants in a system context, only after
+  verification.
+- **Events** use smrt-jobs' delivery inbox under provider
+  `<name>-billing:<sellerTenantId>` and a provider-filtered
+  `ForgeProjectionRuntime`, so a runtime never claims another seller's
+  events; any other runtime sharing the inbox must pass `providers` too. Only
+  events this package acts on are stored: foreign checkouts are `ignored`,
+  and only `smrt_*` checkout metadata is kept; it is
+  HMAC-signed with the webhook secret at creation (empty values are omitted:
+  Stripe drops them), so another integration on the same account cannot forge
+  a credit purchase; credit is granted only when the collected total equals
+  it. Rotating the webhook secret strands in-flight checkouts (up to 24 h). `observe()` re-reads provider state, so
+  ordering never depends on delivery order. The standing hook runs inside the
+  event transaction and must be idempotent.
+- **`Invoice.providerTaxAmount`** is added to line-item tax; it is
+  server-managed (not API-writable). `toAccountingInput()` emits major units.
+- **Known limits** (each tracked upstream): provider customer creation is not
+  idempotent (happyvertical/sdk#1268); credit checkouts are untaxed and
+  two-decimal only (sdk#1269); `autoTopUp` cannot charge a saved card
+  (sdk#1270); Stripe line discounts and uncollectible status are worked around
+  as negative lines and event types (sdk#1271). `RetailCharge` has no
+  adjustment ledger. Flat plans are monthly, in arrears, without proration.
+
 ## Cross-Package References
 
 - `customerId` → `@foreignKey('Customer')` (hard reference within package)
@@ -31,6 +77,7 @@ E-commerce with Contract STI hierarchy, invoice lifecycle, payment tracking, pay
 - `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)
+- Billing records reference tenants with `@crossPackageRef('@happyvertical/smrt-users:Tenant')` and charges, plan periods, and adjustments by plain `sourceId`
 
 ## Gotchas
 

package/README.md

@@ -99,6 +99,9 @@ await payment.recordPayment({
 | `PaymentAllocation` | Payment-to-invoice allocation |
 | `Fulfillment` | Shipment/delivery tracking with carrier and address |
 | `FulfillmentLineItem` | Individual fulfillment line item |
+| `BillingAccount` | A payer's account with a seller: customer, provider customer, terms, standing |
+| `BillingPeriodClose` | One payer's invoice for one period and currency; also the billing job target |
+| `BillingLineSource` | The claim that a charge or plan period is billed on exactly one close |
 
 ### Collections
 
@@ -138,10 +141,111 @@ Invoice and Payment integrate with `@happyvertical/smrt-ledgers` via dynamic imp
 
 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`.
 
+## Billing-period close
+
+`BillingRuntime` turns approved `@happyvertical/smrt-subscriptions` charges into
+invoices for each billing owner, pushes them to a payment provider with
+provider-calculated tax, posts revenue to the ledger, and applies the
+provider's webhook events. Every provider call goes through
+`@happyvertical/accounting`; `createStripeBillingProvider()` adapts its Stripe
+provider to the `BillingProvider` port. Money crossing the port is integer
+minor units.
+
+```ts
+import { getAccountingProvider } from '@happyvertical/accounting';
+import {
+  BillingRuntime,
+  createStripeBillingProvider,
+  enqueueBillingPeriodClose,
+  registerBillingRuntime,
+} from '@happyvertical/smrt-commerce';
+
+const stripe = await getAccountingProvider({ type: 'stripe', secretKey });
+const billing = await BillingRuntime.create({
+  db,
+  sellerTenantId: platformTenantId,
+  kind: 'provider', // or 'reseller' to bill a reseller's children
+  provider: createStripeBillingProvider({ stripe, webhookSecret }),
+  billingRelationships, // smrt-tenancy BillingRelationshipService
+  ledger: {
+    arAccountId,
+    revenueAccountId,
+    taxAccountId,
+    cashAccountId,
+    prepaidCreditAccountId,
+  },
+  onPayerStanding: async ({ payerTenantId, standing, db }) => {
+    // suspend or reinstate the payer; runs in the event transaction
+  },
+});
+
+// One account per payer: its customer, tax location, and terms.
+await billing.upsertAccount({
+  payerTenantId,
+  name: 'Network Co',
+  email: 'billing@example.test',
+  billingAddress: { country: 'CA', postalCode: 'T0L 0A0' },
+});
+
+// Close last month (default) — safe to run on every schedule tick.
+registerBillingRuntime('platform', billing);
+await enqueueBillingPeriodClose({ runtime: 'platform' });
+
+// Webhook route: verify, enqueue, respond 2xx.
+const intake = await billing.acceptWebhook(
+  rawBody,
+  request.headers.get('stripe-signature'),
+);
+if (intake.type?.endsWith(':unverified_credit_purchase')) {
+  // alert: a paid checkout claimed to buy credit but failed verification
+}
+await billing.processEvents(); // or enqueueBillingEvents({ runtime: 'platform' })
+
+// Prepaid credit through provider checkout.
+const { url } = await billing.createCreditCheckout({
+  spendingPolicyId,
+  amount: 5000,
+  purchaseId: cartId,
+  successUrl,
+  cancelUrl,
+});
+```
+
+- **What is billed.** A `provider` runtime bills `ClientCharge`s (and their
+  `BillingAdjustment`s) to the payer each charge names, plus monthly flat plans
+  it owns, to each subscriber's billing owner. A `reseller` runtime bills the
+  `RetailCharge`s its children owe it plus its own flat plans. Charges approved
+  before the period end are billed once, whatever period that is; flat plans
+  are billed in arrears for a closed calendar month (trials and
+  provider-managed subscriptions are skipped). One invoice per payer and
+  currency carries both kinds of lines.
+- **Replay safety.** Close, invoice, and line ids are derived from the payer,
+  currency, and period; each charge is claimed by exactly one close; the
+  provider invoice uses the close id as its idempotency key; and every step is
+  persisted before the next, so a retry resumes where it stopped. A lease stops
+  two workers advancing the same close. A payer whose charges net to a credit
+  gets no invoice; the credit is carried to its next invoice.
+- **Tax** comes from the provider (Stripe Tax) using the account customer's
+  `defaultBillingAddress`; the invoice records it as `providerTaxAmount`.
+- **Events** are verified, stored in smrt-jobs' durable delivery inbox, and
+  applied against current provider state: paid invoices record a payment and
+  allocation; failures and overdue notices mark the payer `past_due` and its
+  flat-plan subscriptions `past_due`; payment reinstates them. Dunning is the
+  provider's.
+- **Prepaid credit** purchases credit a `period: 'balance'` spending policy
+  once per checkout session, paid by the policy's tenant or, for a delegated
+  balance, the parent that set it.
+
+See [`AGENTS.md`](./AGENTS.md#billing-period-close-3060) for invariants and
+known limits.
+
 ## Dependencies
 
 - `@happyvertical/smrt-core` -- ORM and code generation
 - `@happyvertical/smrt-tenancy` -- multi-tenant scoping
+- `@happyvertical/smrt-subscriptions` -- charges, plans, and credit balances billed by period close
+- `@happyvertical/smrt-jobs` -- period-close jobs and the provider event inbox
+- `@happyvertical/accounting` -- payment-provider (Stripe) calls
 - `@happyvertical/smrt-types` -- shared type definitions
 - Peer: `@happyvertical/smrt-ledgers`, `@happyvertical/smrt-profiles`, `@happyvertical/smrt-svelte`
 

package/dist/billing/credits.d.ts

@@ -0,0 +1,33 @@
+import { BillingProviderCheckoutSession } from './provider.js';
+import { BillingRuntime } from './runtime.js';
+export declare const CREDIT_PURCHASE_PURPOSE = "credit_purchase";
+export interface CreateCreditCheckoutInput {
+    /** The `period: 'balance'` spending policy to credit. */
+    spendingPolicyId: string;
+    /** Credit to buy, in integer minor units of the policy currency. */
+    amount: number;
+    successUrl: string;
+    cancelUrl: string;
+    /**
+     * Caller-owned id for this purchase attempt (for example a cart id). A
+     * retried request with the same id returns the same checkout.
+     */
+    purchaseId: string;
+    /** Checkout line description (default `Prepaid credit`). */
+    description?: string;
+}
+/** The checkout metadata a completed purchase is settled from. */
+export interface CreditPurchaseMetadata {
+    purpose: string;
+    sellerTenantId: string;
+    payerTenantId: string;
+    billingAccountId: string;
+    spendingPolicyId: string;
+    grantedByTenantId: string;
+    amount: number;
+    currency: string;
+}
+/** Parse checkout metadata written by {@link createCreditCheckout}. */
+export declare function creditMetadata(raw: Record<string, string>): CreditPurchaseMetadata | null;
+export declare function createCreditCheckout(runtime: BillingRuntime, input: CreateCreditCheckoutInput): Promise<BillingProviderCheckoutSession>;
+//# sourceMappingURL=credits.d.ts.map

package/dist/billing/credits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../../src/billing/credits.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAEzD,MAAM,WAAW,yBAAyB;IACxC,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuBD,uEAAuE;AACvE,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,sBAAsB,GAAG,IAAI,CAwB/B;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,8BAA8B,CAAC,CAgEzC"}

package/dist/billing/events.d.ts

@@ -0,0 +1,26 @@
+import { ForgeProjector } from '@happyvertical/smrt-jobs';
+import { BillingProviderEvent, BillingProviderInvoiceState, BillingProviderSubscriptionState } from './provider.js';
+import { BillingRuntime } from './runtime.js';
+type InvoiceEvent = Extract<BillingProviderEvent, {
+    kind: 'invoice';
+}>;
+type SubscriptionEvent = Extract<BillingProviderEvent, {
+    kind: 'subscription';
+}>;
+type CheckoutEvent = Extract<BillingProviderEvent, {
+    kind: 'checkout_completed';
+}>;
+type ObservedEvent = {
+    event: InvoiceEvent;
+    invoice: BillingProviderInvoiceState;
+} | {
+    event: SubscriptionEvent;
+    subscription: BillingProviderSubscriptionState;
+} | {
+    event: CheckoutEvent;
+};
+/** Apply up to `limit` queued events for a runtime; returns how many ran. */
+export declare function processBillingEvents(runtime: BillingRuntime, limit: number): Promise<number>;
+export declare function createBillingEventProjector(runtime: BillingRuntime): ForgeProjector<ObservedEvent>;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/billing/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/billing/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAoBlC,OAAO,KAAK,EACV,oBAAoB,EACpB,2BAA2B,EAC3B,gCAAgC,EACjC,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AACvE,KAAK,iBAAiB,GAAG,OAAO,CAC9B,oBAAoB,EACpB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CACzB,CAAC;AACF,KAAK,aAAa,GAAG,OAAO,CAC1B,oBAAoB,EACpB;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAC/B,CAAC;AAEF,KAAK,aAAa,GACd;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,2BAA2B,CAAA;CAAE,GAC7D;IACE,KAAK,EAAE,iBAAiB,CAAC;IACzB,YAAY,EAAE,gCAAgC,CAAC;CAChD,GACD;IAAE,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAI7B,6EAA6E;AAC7E,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,cAAc,GACtB,cAAc,CAAC,aAAa,CAAC,CA+D/B"}

package/dist/billing/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Billing-period close, provider events, and prepaid credit purchases
+ * (#3060).
+ * @packageDocumentation
+ */
+export type { CreateCreditCheckoutInput } from './credits.js';
+export { type EnqueueBillingJobOptions, enqueueBillingEvents, enqueueBillingPeriodClose, getBillingRuntime, registerBillingRuntime, unregisterBillingRuntime, } from './jobs.js';
+export { type BillingPeriod, BillingPeriodCloseError, type ClosePeriodInput, type PeriodCloseGroupResult, type PeriodCloseOutcome, type PeriodCloseResult, previousCalendarMonth, } from './period-close.js';
+export { type BillingInvoiceEventType, type BillingProvider, type BillingProviderCheckoutInput, type BillingProviderCheckoutSession, type BillingProviderCustomerInput, type BillingProviderEvent, type BillingProviderInvoiceInput, type BillingProviderInvoiceLine, type BillingProviderInvoiceState, type BillingProviderInvoiceStatus, type BillingProviderSubscriptionState, BillingWebhookVerificationError, } from './provider.js';
+export { type BillingLedgerAccounts, BillingRuntime, type BillingRuntimeOptions, type PayerStandingChange, type PayerStandingHook, type SyncedBillingAccount, type UpsertBillingAccountInput, } from './runtime.js';
+export { createStripeBillingProvider, type StripeBillingProviderOptions, } from './stripe.js';
+export { currencyMinorUnitExponent, majorToMinorUnits, minorToMajorUnits, } from './units.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,KAAK,wBAAwB,EAC7B,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,aAAa,EAClB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,KAAK,8BAA8B,EACnC,KAAK,4BAA4B,EACjC,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,gCAAgC,EACrC,+BAA+B,GAChC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,qBAAqB,EAC1B,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,2BAA2B,EAC3B,KAAK,4BAA4B,GAClC,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/billing/jobs.d.ts

@@ -0,0 +1,31 @@
+import { SmrtJob } from '@happyvertical/smrt-jobs';
+import { PeriodCloseResult } from './period-close.js';
+import { BillingRuntime } from './runtime.js';
+/** Make a runtime available to billing jobs under `name`. */
+export declare function registerBillingRuntime(name: string, runtime: BillingRuntime): void;
+export declare function unregisterBillingRuntime(name: string): void;
+export declare function getBillingRuntime(name: string): BillingRuntime;
+export declare function runBillingPeriodCloseJob(args: Record<string, unknown>): Promise<PeriodCloseResult>;
+export declare function runBillingEventsJob(args: Record<string, unknown>): Promise<{
+    processed: number;
+}>;
+export interface EnqueueBillingJobOptions {
+    /** Registered runtime name. */
+    runtime: string;
+    runAt?: Date;
+    queue?: string;
+    maxAttempts?: number;
+}
+/**
+ * Queue a period close. Without a period the job closes the previous
+ * calendar month when it runs, so enqueueing it daily is safe.
+ */
+export declare function enqueueBillingPeriodClose(options: EnqueueBillingJobOptions & {
+    periodStart?: Date;
+    periodEnd?: Date;
+}): Promise<SmrtJob>;
+/** Queue processing of received provider events. */
+export declare function enqueueBillingEvents(options: EnqueueBillingJobOptions & {
+    limit?: number;
+}): Promise<SmrtJob>;
+//# sourceMappingURL=jobs.d.ts.map

package/dist/billing/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../src/billing/jobs.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,OAAO,EAAqB,MAAM,0BAA0B,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAmBnD,6DAA6D;AAC7D,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,GACtB,IAAI,CAGN;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAM9D;AAkBD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAK5B;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAGhC;AAED,MAAM,WAAW,wBAAwB;IACvC,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA4BD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,wBAAwB,GAAG;IAAE,WAAW,CAAC,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,IAAI,CAAA;CAAE,GAC3E,OAAO,CAAC,OAAO,CAAC,CAelB;AAED,oDAAoD;AACpD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,wBAAwB,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD,OAAO,CAAC,OAAO,CAAC,CAclB"}

package/dist/billing/period-close.d.ts

@@ -0,0 +1,41 @@
+import { BillingRuntime } from './runtime.js';
+export interface BillingPeriod {
+    /** Inclusive start. */
+    periodStart: Date;
+    /** Exclusive end; charges approved before it are billable. */
+    periodEnd: Date;
+}
+export interface ClosePeriodInput {
+    periodStart?: Date;
+    periodEnd?: Date;
+    /** Clock override for tests; defaults to now. */
+    now?: Date;
+}
+export type PeriodCloseOutcome = 'completed' | 'empty' | 'busy' | 'carried_forward' | 'failed';
+export interface PeriodCloseGroupResult {
+    payerTenantId: string;
+    currency: string;
+    closeId?: string;
+    invoiceId?: string;
+    providerInvoiceId?: string;
+    outcome: PeriodCloseOutcome;
+    error?: string;
+}
+export interface PeriodCloseResult extends BillingPeriod {
+    sellerTenantId: string;
+    groups: PeriodCloseGroupResult[];
+}
+/** Thrown when one or more payers could not be closed; the rest were. */
+export declare class BillingPeriodCloseError extends Error {
+    readonly result: PeriodCloseResult;
+    constructor(result: PeriodCloseResult);
+}
+/** The previous calendar month in UTC relative to `now`. */
+export declare function previousCalendarMonth(now?: Date): BillingPeriod;
+export declare function periodCloseId(runtime: Pick<BillingRuntime, 'sellerTenantId' | 'kind'>, payerTenantId: string, currency: string, period: BillingPeriod): Promise<string>;
+/**
+ * Close one billing period for a runtime's seller. Idempotent: re-running it
+ * for the same period resumes unfinished payers and bills nothing twice.
+ */
+export declare function closeBillingPeriod(runtime: BillingRuntime, input?: ClosePeriodInput): Promise<PeriodCloseResult>;
+//# sourceMappingURL=period-close.d.ts.map

package/dist/billing/period-close.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"period-close.d.ts","sourceRoot":"","sources":["../../src/billing/period-close.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,WAAW,EAAE,IAAI,CAAC;IAClB,8DAA8D;IAC9D,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,iDAAiD;IACjD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,OAAO,GACP,MAAM,GACN,iBAAiB,GACjB,QAAQ,CAAC;AAEb,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,sBAAsB,EAAE,CAAC;CAClC;AAED,yEAAyE;AACzE,qBAAa,uBAAwB,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,iBAAiB;gBAAzB,MAAM,EAAE,iBAAiB;CAW/C;AAwBD,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,GAAG,OAAa,GAAG,aAAa,CAQrE;AAoCD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,GAAG,MAAM,CAAC,EACxD,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAMD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,KAAK,GAAE,gBAAqB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CA0D5B"}

package/dist/billing/provider.d.ts

@@ -0,0 +1,136 @@
+import { SubscriptionStatus } from '@happyvertical/smrt-subscriptions';
+import { Address } from '../types/index.js';
+export interface BillingProviderCustomerInput {
+    /** The local billing account id, recorded on the provider customer. */
+    accountId: string;
+    /** Existing provider customer id; omitted to create one. */
+    providerCustomerId?: string;
+    name: string;
+    email?: string;
+    /** Tax location used by provider-calculated tax. */
+    billingAddress?: Address;
+    taxExempt: boolean;
+}
+export interface BillingProviderInvoiceLine {
+    description: string;
+    /** Signed line amount in minor units; discounts are negative lines. */
+    amount: number;
+    periodStart?: Date;
+    periodEnd?: Date;
+}
+export interface BillingProviderInvoiceInput {
+    /** Local invoice id; the provider tags its invoice with it. */
+    invoiceId: string;
+    invoiceNumber: string;
+    providerCustomerId: string;
+    currency: string;
+    issueDate: Date;
+    dueDate: Date;
+    lines: BillingProviderInvoiceLine[];
+    /** Sum of `lines`, in minor units. */
+    subtotal: number;
+    /** Stable key for this logical invoice; reused on every retry. */
+    idempotencyKey: string;
+    /** Ask the provider to calculate tax from the customer's tax location. */
+    automaticTax: boolean;
+    memo?: string;
+}
+export type BillingProviderInvoiceStatus = 'draft' | 'open' | 'paid' | 'void';
+export interface BillingProviderInvoiceState {
+    providerInvoiceId: string;
+    status: BillingProviderInvoiceStatus;
+    currency: string;
+    /** Pre-tax subtotal, minor units. */
+    subtotal: number;
+    /** Provider-calculated tax, minor units. */
+    taxAmount: number;
+    total: number;
+    amountPaid: number;
+    amountDue: number;
+}
+export interface BillingProviderSubscriptionState {
+    providerSubscriptionId: string;
+    status: SubscriptionStatus;
+    currentPeriodStart?: Date;
+    currentPeriodEnd?: Date;
+    cancelAtPeriodEnd: boolean;
+    canceledAt?: Date;
+    trialEndsAt?: Date;
+}
+export interface BillingProviderCheckoutInput {
+    /** Stable key reused when retrying the same checkout creation. */
+    idempotencyKey: string;
+    providerCustomerId?: string;
+    customerEmail?: string;
+    currency: string;
+    /** Amount charged, minor units. */
+    amount: number;
+    description: string;
+    successUrl: string;
+    cancelUrl: string;
+    /** Opaque values returned verbatim on the completion event. */
+    metadata: Record<string, string>;
+}
+export interface BillingProviderCheckoutSession {
+    sessionId: string;
+    url: string | null;
+}
+/** Invoice lifecycle changes this package acts on. */
+export type BillingInvoiceEventType = 'paid' | 'payment_failed' | 'overdue' | 'uncollectible' | 'voided';
+/** A verified provider event, normalized and stripped of customer data. */
+export type BillingProviderEvent = {
+    kind: 'invoice';
+    eventId: string;
+    type: BillingInvoiceEventType;
+    providerInvoiceId: string;
+} | {
+    kind: 'subscription';
+    eventId: string;
+    providerSubscriptionId: string;
+} | {
+    kind: 'checkout_completed';
+    eventId: string;
+    sessionId: string;
+    /** Only `paid` sessions settle a credit purchase. */
+    paid: boolean;
+    currency: string;
+    /** Line-item amount before discounts and tax, minor units. */
+    amountSubtotal: number;
+    /** Amount actually collected (after discounts, with tax), minor units. */
+    amountTotal: number;
+    metadata: Record<string, string>;
+} | {
+    kind: 'ignored';
+    eventId: string;
+    type: string;
+};
+/**
+ * A payment provider as period close sees it. Implementations must be
+ * replay-safe: `pushInvoice` with the same `idempotencyKey` returns the same
+ * provider invoice however often it is retried.
+ */
+export interface BillingProvider {
+    /** Provider name recorded on local rows (`stripe`). */
+    readonly name: string;
+    syncCustomer(input: BillingProviderCustomerInput): Promise<{
+        providerCustomerId: string;
+    }>;
+    pushInvoice(input: BillingProviderInvoiceInput): Promise<{
+        providerInvoiceId: string;
+    }>;
+    /** Finalize (if still a draft) and send an invoice for payment. */
+    sendInvoice(providerInvoiceId: string): Promise<void>;
+    getInvoice(providerInvoiceId: string): Promise<BillingProviderInvoiceState>;
+    getSubscription(providerSubscriptionId: string): Promise<BillingProviderSubscriptionState>;
+    createCheckout(input: BillingProviderCheckoutInput): Promise<BillingProviderCheckoutSession>;
+    /**
+     * Verify a webhook signature and normalize the event. Rejects with
+     * {@link BillingWebhookVerificationError} when the signature is invalid;
+     * anything verified but not actionable is returned as `ignored`.
+     */
+    verifyWebhook(payload: string, signature: string): Promise<BillingProviderEvent>;
+}
+export declare class BillingWebhookVerificationError extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/billing/provider.d.ts.map

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