@voltro/plugin-billing 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ColumnDefinition } from '@voltro/database';
 import { Context } from 'effect';
 import { DataStore } from '@voltro/database';
+import { default as default_2 } from 'stripe';
 import { Effect } from 'effect';
 import { IncomingRequest } from '@voltro/plugin-webhooks';
 import { IncomingResponse } from '@voltro/plugin-webhooks';
@@ -15,18 +16,8 @@ import { TableIndex } from '@voltro/database';
 import { TableLike } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
-/**
- * Advance one due dunning record: if there is a NEXT offset in the schedule,
- * move to it (CAS on `attempt`); otherwise exhaust — cancel the subscription
- * and close the record. Returns which happened, or `null` if another tick won
- * the advance first (the CAS lost).
- */
-export declare const advanceDunning: (opts: DunningEngineOptions, record: DunningState) => Effect.Effect<"retried" | "canceled" | null, BillingError>;
-
 export declare const BILLING_CUSTOMERS_TABLE = "_voltro_billing_customers";
 
-export declare const BILLING_DUNNING_TABLE = "_voltro_billing_dunning";
-
 export declare const BILLING_FLUSH_CLAIMS_TABLE = "_voltro_billing_flush_claims";
 
 export declare const BILLING_INVOICES_TABLE = "_voltro_billing_invoices";
@@ -54,15 +45,6 @@ export declare interface BillingContext {
 /** tenant ↔ provider customer link. */
 export declare const billingCustomersTable: BillingTable;
 
-/**
- * Dunning ledger — one row per subscription with a failed payment being
- * retried. `providerSubscriptionId` is UNIQUE so the create-path `insertIgnore`
- * gate makes opening dunning idempotent under a replayed payment-failed
- * webhook. Deleted on recovery / cancellation, so the table is bounded by the
- * count of subscriptions CURRENTLY in dunning (small).
- */
-export declare const billingDunningTable: BillingTable;
-
 /**
  * A billing failure. `transient: true` marks failures the service retries
  * (network blip talking to the provider); non-transient failures (a 4xx
@@ -155,15 +137,25 @@ export declare interface BillingPluginOptions {
      *  self-scheduled flush — call `billing.flushUsage()` from your own
      *  `*.cron.tsx` instead (e.g. for cluster-coordinated flushing). */
     readonly flushIntervalMs?: number;
-    /** Dunning retry schedule — day-offsets from the original payment failure at
-     *  which to retry before canceling. Default `[1, 3, 5, 7]`. A failed payment
-     *  transitions the subscription `active → pastDue`; exhausting the schedule
-     *  transitions it to `canceled`; a recovered payment returns it to `active`. */
-    readonly dunningSchedule?: DunningSchedule;
     /** Typed per-event side effects, run AFTER the row is updated. */
     readonly onEvent?: OnEventMap;
     /** Transient-failure retries on provider calls. Default 3. */
     readonly attempts?: number;
+    /**
+     * Checkout behaviour, handed straight to the provider.
+     *
+     * `adjustableQuantity` renders STRIPE's seat stepper on STRIPE's checkout
+     * page — set it for a per-seat plan so a customer can buy the number of
+     * seats they want in one go. `trialDays` makes Stripe run the trial and
+     * report `trialing`; we neither count trial days nor expire them.
+     */
+    readonly checkout?: {
+        readonly adjustableQuantity?: {
+            readonly min: number;
+            readonly max: number;
+        };
+        readonly trialDays?: number;
+    };
     /**
      * Per-tenant entitlement-limit override — the seam for a cloud-issued license
      * snapshot. Pass `@voltro/plugin-licensing`'s `entitlementResolver` here to let
@@ -199,6 +191,39 @@ export declare interface BillingProvider {
         url: string;
     }, BillingError>;
     readonly reportUsage: (input: UsagePush) => Effect.Effect<void, BillingError>;
+    /**
+     * Apply a plan / seat change to the LIVE subscription.
+     *
+     * This is the call whose absence made `changeSeats` a lie: without it the
+     * service patched its own table and the provider went on billing the old
+     * quantity, so a customer could be granted seats nobody was charging for.
+     * The provider — not us — computes and bills the proration.
+     */
+    readonly updateSubscription: (input: SubscriptionUpdateInput) => Effect.Effect<SubscriptionChangeResult, BillingError>;
+    /**
+     * What WOULD a change cost, without applying it? Backed by the provider's
+     * own invoice preview, so the number quoted to the customer is the number
+     * they are charged — a locally-computed estimate can differ from the
+     * provider's rounding, its tax, and its credit balance, and any difference
+     * is a support ticket.
+     */
+    readonly previewSubscriptionChange: (input: SubscriptionUpdateInput) => Effect.Effect<SubscriptionChangeResult, BillingError>;
+    /** The provider's invoice history. We mirror it for listing but never
+     *  render an invoice ourselves — `hostedUrl` / `pdfUrl` are theirs. */
+    readonly listInvoices: (input: {
+        readonly providerCustomerId: string;
+        readonly limit?: number;
+    }) => Effect.Effect<ReadonlyArray<InvoiceRecord>, BillingError>;
+    /**
+     * Verify a webhook signature and decode the payload, using the provider's
+     * OWN verification. Returns `null` when this provider does not do its own
+     * verification (the mount's generic check then stands alone).
+     */
+    readonly verifyWebhook?: (input: {
+        readonly rawBody: Uint8Array;
+        readonly signatureHeader: string;
+        readonly secret: string;
+    }) => Effect.Effect<unknown, BillingError>;
     /** Map a verified, decoded webhook payload to a `BillingEvent`, or
      *  `null` for an event type this provider doesn't model (handler
      *  no-ops, still 200). */
@@ -223,11 +248,19 @@ export declare interface BillingServiceOptions {
     readonly stores?: BillingStores;
     /** Transient-failure retries on provider calls. Default 3. */
     readonly attempts?: number;
+    /** Checkout behaviour handed straight to the provider — we render none of
+     *  it ourselves. */
+    readonly checkout?: {
+        /** Seat stepper bounds on the provider's checkout page. */
+        readonly adjustableQuantity?: {
+            readonly min: number;
+            readonly max: number;
+        };
+        /** Free-trial length. The provider runs the trial and reports `trialing`. */
+        readonly trialDays?: number;
+    };
     /** Clock injection for deterministic period windowing in tests. */
     readonly now?: () => Date;
-    /** Dunning retry schedule (day-offsets from the original failure). Default
-     *  `[1, 3, 5, 7]`. */
-    readonly dunningSchedule?: DunningSchedule;
     /**
      * Optional per-tenant entitlement-limit override — the seam for a
      * cloud-issued license snapshot (e.g. `@voltro/plugin-licensing`'s
@@ -251,6 +284,15 @@ export declare interface BillingServiceShape {
     readonly reportUsage: (tenantId: string, key: string, qty: number) => Effect.Effect<void, BillingError>;
     /** Flush all pending local usage counters to the provider. */
     readonly flushUsage: () => Effect.Effect<void, BillingError>;
+    /** What a plan/seat change WOULD cost, from the provider's own invoice
+     *  preview. Quote this, not a local estimate — the two differ by the
+     *  provider's rounding, tax and credit balance. */
+    readonly previewChange: (tenantId: string, next: {
+        readonly plan?: PlanId;
+        readonly quantity?: number;
+    }) => Effect.Effect<SubscriptionChange, BillingError>;
+    /** The provider's invoice history for this tenant. */
+    readonly invoices: (tenantId: string) => Effect.Effect<ReadonlyArray<InvoiceRecord>, BillingError>;
     /** Mint a provider-hosted checkout URL for `plan`. */
     readonly startCheckout: (input: {
         readonly tenantId: string;
@@ -282,35 +324,13 @@ export declare interface BillingServiceShape {
      * positive integer. Fails `BillingError` on no subscription / bad quantity.
      */
     readonly changeSeats: (tenantId: string, quantity: number, changeAt?: Date) => Effect.Effect<SubscriptionChange, BillingError>;
-    /**
-     * Record a failed payment: schedule the first dunning retry (per the
-     * configured schedule) and transition the subscription `active → pastDue`.
-     * Idempotent — a replayed failure for a subscription already in dunning does
-     * not re-arm or double-schedule.
-     */
-    readonly recordPaymentFailure: (tenantId: string, at?: Date) => Effect.Effect<DunningState | null, BillingError>;
-    /**
-     * Record a recovered payment: clear any open dunning and transition the
-     * subscription back to `active`. Idempotent / a no-op when not in dunning.
-     */
-    readonly recordPaymentSuccess: (tenantId: string, at?: Date) => Effect.Effect<void, BillingError>;
-    /**
-     * Advance every due dunning entry: subscriptions whose next retry is due move
-     * to the next offset in the schedule; those that have exhausted the schedule
-     * transition `pastDue → canceled`. Idempotent per due-time (a claim gate
-     * makes a re-run over the same window a no-op). Driven by the self-scheduled
-     * interval, or call it from your own `*.cron.tsx`.
-     */
-    readonly runDunningCycle: (now?: Date) => Effect.Effect<DunningCycleResult, BillingError>;
 }
 
-/** The five billing stores bundled — swapped wholesale by `bindDataStore`. */
 export declare interface BillingStores {
     readonly customers: CustomerStore;
     readonly subscriptions: SubscriptionStore;
     readonly invoices: InvoiceStore;
     readonly usage: UsageStore;
-    readonly dunning: DunningStore;
 }
 
 /** One active subscription per tenant. */
@@ -327,7 +347,6 @@ export declare interface BillingTable extends TableLike {
     readonly appliedIndexes: ReadonlyArray<TableIndex>;
 }
 
-/** All billing tables, ready to spread into `extendSchema.tables`. */
 export declare const billingTables: () => ReadonlyArray<BillingTable>;
 
 /** Per-tenant metered counters driving the entitlement engine. */
@@ -344,6 +363,9 @@ declare interface BillingWebhookOptions {
     readonly provider: BillingProvider;
     readonly service: BillingServiceShape;
     readonly onEvent?: OnEventMap;
+    /** The signing secret, so the provider can run its OWN verification on the
+     *  raw bytes. Null → only the mount's generic check applies. */
+    readonly webhookSecret?: string | null;
 }
 
 /**
@@ -379,6 +401,16 @@ export declare interface CheckoutInput {
     readonly cancelUrl: string;
     /** Optional existing provider customer id to attach the checkout to. */
     readonly providerCustomerId?: string;
+    /** Seats to buy up front. Defaults to 1. */
+    readonly quantity?: number;
+    /** Let the buyer change the seat count on the checkout page itself.
+     *  Stripe renders the stepper; we neither build nor validate it. */
+    readonly adjustableQuantity?: {
+        readonly min: number;
+        readonly max: number;
+    };
+    /** Days of free trial. Stripe runs the trial and emits `trialing`. */
+    readonly trialDays?: number;
 }
 
 /**
@@ -390,16 +422,6 @@ export declare interface CheckoutInput {
  */
 export declare const claimFlushWindow: (store: DataStore, windowKey: string, replicaId: string, nowMs: number) => Promise<boolean>;
 
-/**
- * Compute the prorated settlement for a mid-cycle amount change.
- *
- * Fails `BillingError` (non-transient) when the period is degenerate
- * (`periodEnd <= periodStart`) — a caller must supply a real paid period; a
- * plan with no period (`currentPeriodEnd === null`) is not prorated at all
- * (the service short-circuits before calling this).
- */
-export declare const computeProration: (input: ProrationInput) => ProrationResult;
-
 declare interface CustomerRecord {
     readonly tenantId: string;
     readonly provider: string;
@@ -413,62 +435,9 @@ export declare interface CustomerStore {
 
 export declare const dataStoreStores: (store: DataStore) => BillingStores;
 
-export declare const DEFAULT_DUNNING_SCHEDULE: DunningSchedule;
-
 /** The free/fallback plan id every app implicitly has. */
 export declare const DEFAULT_PLAN: PlanId;
 
-/** What one `runDunningCycle` did. */
-export declare interface DunningCycleResult {
-    /** Subscriptions advanced to the next retry offset. */
-    readonly retried: number;
-    /** Subscriptions that exhausted the schedule and were canceled. */
-    readonly canceled: number;
-}
-
-export declare interface DunningEngineOptions {
-    readonly subscriptions: SubscriptionStore;
-    readonly dunning: DunningStore;
-    readonly schedule: DunningSchedule;
-}
-
-/** The dunning retry schedule: day-offsets from the original failure at which
- *  to retry. Default `[1, 3, 5, 7]` (four retries over a week, then cancel). */
-export declare type DunningSchedule = ReadonlyArray<number>;
-
-/** A tenant's live dunning record — a failed payment being retried. */
-export declare interface DunningState {
-    readonly tenantId: string;
-    readonly providerSubscriptionId: string;
-    /** 0-based index into the configured retry-offset schedule. */
-    readonly attempt: number;
-    /** When the current retry is due. */
-    readonly nextRetryAt: Date;
-    /** When dunning was first opened (the original failure). */
-    readonly startedAt: Date;
-}
-
-export declare interface DunningStore {
-    /**
-     * Open a dunning record for a subscription (attempt 0, due at `nextRetryAt`),
-     * IDEMPOTENTLY — if one already exists it is left untouched and `false` is
-     * returned. Returns `true` only when THIS call opened it. The create-path
-     * `insertIgnore` over the `providerSubscriptionId` UNIQUE makes a replayed
-     * payment-failed webhook a no-op across instances.
-     */
-    readonly open: (tenantId: string, providerSubscriptionId: string, nextRetryAt: Date, at: Date) => Effect.Effect<boolean, BillingError>;
-    readonly getByTenant: (tenantId: string) => Effect.Effect<DunningState | null, BillingError>;
-    /** All dunning records due at/before `at` (`nextRetryAt <= at`). */
-    readonly due: (at: Date) => Effect.Effect<ReadonlyArray<DunningState>, BillingError>;
-    /** Advance a record to the next attempt/retry time, CONDITIONALLY on the
-     *  record still being at `fromAttempt` (a CAS so two ticks can't both advance
-     *  the same record). Returns `true` iff this call won the advance. */
-    readonly advance: (providerSubscriptionId: string, fromAttempt: number, toAttempt: number, nextRetryAt: Date) => Effect.Effect<boolean, BillingError>;
-    /** Close (delete) the dunning record for a subscription — on recovery or on
-     *  exhaustion→cancel. No-op if absent. */
-    readonly close: (providerSubscriptionId: string) => Effect.Effect<void, BillingError>;
-}
-
 /** A registry with a single zero-quota `free` plan — the zero-config default. */
 export declare const emptyPlanRegistry: () => PlanRegistry;
 
@@ -534,6 +503,17 @@ export declare const evaluateEntitlement: (entitlement: string, limit: number, u
 export declare const flushWindowKey: (nowMs: number, intervalMs: number) => string;
 
 declare interface InvoiceRecord {
+    readonly providerInvoiceId: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly status: string;
+    readonly createdAt: Date | null;
+    /** Provider-hosted invoice page — we never render one ourselves. */
+    readonly hostedUrl: string | null;
+    readonly pdfUrl: string | null;
+}
+
+declare interface InvoiceRecord_2 {
     readonly tenantId: string;
     readonly provider: string;
     readonly providerInvoiceId: string;
@@ -545,8 +525,8 @@ declare interface InvoiceRecord {
 
 export declare interface InvoiceStore {
     /** Upsert by `providerInvoiceId` (idempotent under webhook replay). */
-    readonly upsert: (invoice: InvoiceRecord) => Effect.Effect<void, BillingError>;
-    readonly listByTenant: (tenantId: string) => Effect.Effect<ReadonlyArray<InvoiceRecord>, BillingError>;
+    readonly upsert: (invoice: InvoiceRecord_2) => Effect.Effect<void, BillingError>;
+    readonly listByTenant: (tenantId: string) => Effect.Effect<ReadonlyArray<InvoiceRecord_2>, BillingError>;
 }
 
 export declare const memoryStores: () => BillingStores;
@@ -587,6 +567,10 @@ declare type MeterSource =
 export declare interface MockProvider extends BillingProvider {
     /** Recorded usage pushes — assertion surface for tests. */
     readonly pushed: ReadonlyArray<UsagePush>;
+    /** Recorded subscription updates. The point of asserting on these is that
+     *  a change which never reaches the provider is a change the customer is
+     *  not billed for — the exact defect this contract was widened to fix. */
+    readonly updates: ReadonlyArray<SubscriptionUpdateInput>;
 }
 
 export declare const mockProvider: (options?: {
@@ -617,23 +601,15 @@ declare interface MountBillingWebhookOptions extends BillingWebhookOptions {
 }
 
 /**
- * Map a verified, decoded Stripe webhook event (`{ type, data: { object } }`)
- * to a `BillingEvent`, or null for unhandled types. Pure — the signature
- * was already checked by the webhook mounter.
+ * Map a verified Stripe event to a `BillingEvent`, or null for a type we do
+ * not model (the handler no-ops and still answers 200, which is what stops
+ * Stripe retrying an event we will never care about).
  */
-export declare const normalizeStripeEvent: (raw: unknown) => BillingEvent | null;
+export declare const normalizeStripeEvent: (event: default_2.Event, resolvePrice?: (priceId: string) => string | null) => BillingEvent | null;
 
 /** Per-event side effect, run AFTER the row is updated. */
 export declare type OnEventMap = Readonly<Record<string, (event: BillingEvent) => Effect.Effect<void, unknown>>>;
 
-/**
- * Open dunning for a subscription on a payment failure: schedule the first
- * retry (offset[0]) and transition `active → pastDue`. Idempotent — a replayed
- * failure whose record already exists is a no-op (returns `null`). Returns the
- * opened `DunningState` when this call opened it.
- */
-export declare const openDunning: (opts: DunningEngineOptions, tenantId: string, providerSubscriptionId: string, at: Date) => Effect.Effect<DunningState | null, BillingError>;
-
 /** Calendar-month window key (`'YYYY-MM'`) for metered counters. */
 export declare const periodKey: (now?: Date) => string;
 
@@ -687,35 +663,6 @@ export declare interface PortalInput {
     readonly returnUrl: string;
 }
 
-/** The inputs to one proration computation. All amounts are integer minor units. */
-export declare interface ProrationInput {
-    /** The amount the subscription was billing for the current period (minor units). */
-    readonly oldAmountMinor: number;
-    /** The amount it will bill after the change (minor units). */
-    readonly newAmountMinor: number;
-    /** Start of the current paid period. */
-    readonly periodStart: Date;
-    /** End of the current paid period (`currentPeriodEnd`). */
-    readonly periodEnd: Date;
-    /** When the change takes effect (usually "now"). */
-    readonly changeAt: Date;
-}
-
-/** The result of a proration: the settlement delta + the fraction it was based on. */
-export declare interface ProrationResult {
-    /** Integer minor-unit settlement: > 0 charge (upgrade), < 0 credit
-     *  (downgrade), 0 at the period boundary or when the amount is unchanged. */
-    readonly deltaMinor: number;
-    /** The unused fraction of the period the delta was prorated over, in [0, 1]. */
-    readonly unusedFraction: number;
-}
-
-/**
- * Recover a subscription: close any open dunning record and set it back to
- * `active`. Idempotent / no-op when not in dunning.
- */
-export declare const recoverDunning: (opts: DunningEngineOptions, providerSubscriptionId: string) => Effect.Effect<void, BillingError>;
-
 /**
  * In-handler entitlement guard. Resolves `ctx.request.subject.tenantId`,
  * consumes `cost` units of `key`, and fails with the typed
@@ -745,29 +692,10 @@ declare interface ResolveProviderInput {
     readonly provider?: BillingProviderName | BillingProvider;
     readonly apiKey?: string;
     readonly env: NodeJS.ProcessEnv;
+    /** Price id → plan id, from the plugin's plan registry. */
+    readonly planForPriceId?: (priceId: string) => string | null;
 }
 
-/**
- * The retry time for attempt `index` (0-based) given the original failure
- * `startedAt` and the schedule of day-offsets. Returns `null` when `index` is
- * past the end of the schedule — the signal to CANCEL rather than reschedule.
- */
-export declare const retryTimeFor: (startedAt: Date, index: number, schedule: DunningSchedule) => Date | null;
-
-/** Round half away from zero — symmetric for charges (+) and credits (−) so
- *  proration doesn't systematically favour either party. `Math.round` rounds
- *  half toward +∞ (−0.5 → 0, +0.5 → 1), which WOULD bias credits; this
- *  corrects the negative side. Operates on a float intermediate and returns an
- *  integer. */
-export declare const roundHalfAwayFromZero: (value: number) => number;
-
-/**
- * Run one dunning cycle: for every record due at `now`, advance it (retry to
- * the next offset, or cancel if exhausted). Idempotent per due-time — the CAS
- * on `attempt` means a re-run over an already-advanced record is a no-op.
- */
-export declare const runDunningCycle: (opts: DunningEngineOptions, now: Date) => Effect.Effect<DunningCycleResult, BillingError>;
-
 /**
  * A mutable holder so `bindDataStore` can swap the stores AFTER the service
  * layer is built. The service reads `holder.stores` on every call rather
@@ -784,6 +712,18 @@ export declare interface StripeProviderOptions {
     readonly apiKey: string;
     /** Override metered-usage support (Stripe supports it by default). */
     readonly supportsMeteredUsage?: boolean;
+    /**
+     * Map a Stripe price id to one of our plan ids.
+     *
+     * Without it, a subscription is only recognised when it carries
+     * `metadata.plan` — which our own checkout sets, but a subscription created
+     * in the Stripe Dashboard, by a sales-led flow, or by a migration does NOT.
+     * Those events were previously dropped on the floor and the customer stayed
+     * on `free` while paying. The plugin passes its plan registry here.
+     */
+    readonly planForPriceId?: (priceId: string) => string | null;
+    /** Injected in tests. */
+    readonly client?: default_2;
 }
 
 /** A tenant's subscription row, normalized across providers. */
@@ -815,6 +755,18 @@ export declare interface SubscriptionChange {
     readonly currency: string;
 }
 
+/** What a provider reports back after (or before) a subscription change. */
+declare interface SubscriptionChangeResult {
+    readonly plan: PlanId;
+    readonly quantity: number;
+    /** The proration the PROVIDER computed — and, unless `proration: 'none'`,
+     *  will actually bill. Positive = owed, negative = credited. */
+    readonly prorationMinor: number;
+    readonly currency: string;
+    readonly currentPeriodStart: Date | null;
+    readonly currentPeriodEnd: Date | null;
+}
+
 export declare type SubscriptionStatus = 'active' | 'trialing' | 'pastDue' | 'canceled' | 'incomplete';
 
 export declare interface SubscriptionStore {
@@ -835,6 +787,26 @@ export declare interface SubscriptionStore {
     readonly setStatus: (providerSubscriptionId: string, status: SubscriptionStatus) => Effect.Effect<void, BillingError>;
 }
 
+/** Apply a plan / seat change to the LIVE subscription at the provider. */
+declare interface SubscriptionUpdateInput {
+    readonly providerSubscriptionId: string;
+    /** New price to move to. Omit to keep the current one. */
+    readonly priceId?: string;
+    /** New seat quantity. Omit to keep the current one. */
+    readonly quantity?: number;
+    /**
+     * How the provider should handle the mid-period money.
+     *
+     *   - `'prorate'` — bill or credit the difference for the remaining period
+     *     (Stripe's `create_prorations`). The default, and the only option that
+     *     charges what the customer actually used.
+     *   - `'none'` — change takes effect with no adjustment.
+     *   - `'always_invoice'` — prorate AND invoice immediately rather than at
+     *     the next cycle.
+     */
+    readonly proration?: 'prorate' | 'none' | 'always_invoice';
+}
+
 export declare interface UsagePush {
     readonly tenantId: string;
     readonly entitlementKey: string;
@@ -875,13 +847,6 @@ export declare interface UsageStore {
     readonly markReported: (tenantId: string, key: string, period: string, reported: number) => Effect.Effect<void, BillingError>;
 }
 
-/**
- * Validate a dunning schedule at boot — fails LOUD on a bad config rather than
- * silently never retrying. Offsets must be a non-empty list of strictly
- * increasing positive numbers (days).
- */
-export declare const validateDunningSchedule: (schedule: DunningSchedule) => void;
-
 export { VoltroPlugin }
 
 export { }