@voltro/plugin-billing 0.81.0 → 0.83.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { IncomingResponse } from '@voltro/plugin-webhooks';
 import { IncomingWebhookDescriptor } from '@voltro/plugin-webhooks';
 import { Layer } from 'effect';
 import { mountIncomingWebhook } from '@voltro/plugin-webhooks';
+import { PluginEgressDeclaration } from '@voltro/protocol';
 import { RpcInterceptor } from '@voltro/protocol';
 import { RpcKind } from '@voltro/protocol';
 import { Schema } from 'effect';
@@ -16,6 +17,14 @@ import { TableIndex } from '@voltro/database';
 import { TableLike } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
+export declare const assertBillingProductionReady: (input: {
+    readonly env: NodeJS.ProcessEnv;
+    readonly providerOption: BillingProviderName | BillingProvider | undefined;
+    readonly resolvedName: string;
+    readonly webhookSecret: string | null;
+    readonly redirectOrigins: ReadonlyArray<string> | undefined;
+}) => void;
+
 export declare const BILLING_CUSTOMERS_TABLE = "_voltro_billing_customers";
 
 export declare const BILLING_DUNNING_NOTICES_TABLE = "_voltro_billing_dunning_notices";
@@ -33,6 +42,14 @@ export declare const BILLING_WEBHOOK_ID = "billing";
 
 export declare const BILLING_WEBHOOK_PATH = "/billing/webhook";
 
+/**
+ * What a billing call would do to what the tenant pays — the unit an app's
+ * `admit` hook decides on. `checkout` starts paying, `change` moves a plan or
+ * seat count, `resume` takes a cancellation back, `portal` opens the provider's
+ * self-service page (which can do all of those), `cancel` stops paying.
+ */
+export declare type BillingAction = 'checkout' | 'change' | 'resume' | 'portal' | 'cancel';
+
 /**
  * The shape every handler executor receives carries the resolved subject
  * under `ctx.request.subject` (mirrors `@voltro/plugin-rbac`'s
@@ -58,6 +75,14 @@ export declare const billingDunningNoticesTable: TableLike & {
     readonly appliedIndexes: ReadonlyArray<TableIndex>;
 };
 
+/**
+ * Where billing data leaves the installation, for `voltro compliance generate`
+ * (egress.json): Stripe's API for the stripe provider (customers, their email
+ * and the subscription items), nothing for the mock, and the provider's own
+ * name for a custom one.
+ */
+export declare const billingEgressOf: (provider: Pick<BillingProvider, "name">) => ReadonlyArray<PluginEgressDeclaration>;
+
 /**
  * A billing failure. `transient: true` marks failures the service retries
  * (network blip talking to the provider); non-transient failures (a 4xx
@@ -122,6 +147,14 @@ export declare type BillingEvent = {
     readonly tenantId: string;
     readonly providerCustomerId: string;
     readonly occurredAt: Date | null;
+} | {
+    /** The provider customer was deleted (e.g. in the provider's dashboard).
+     *  `tenantId` is null when the customer carried no tenant metadata — the
+     *  link is then resolved from our own customer table. */
+    readonly _tag: 'customerUnlinked';
+    readonly tenantId: string | null;
+    readonly providerCustomerId: string;
+    readonly occurredAt: Date | null;
 };
 
 /** The event tag union — handy for `onEvent` keys. */
@@ -195,6 +228,29 @@ export declare interface BillingPluginOptions {
      * a signed license decide limits per-tenant; a `null` result falls back to the
      * static `plans` registry. Absent → static registry only.
      */
+    /**
+     * The app's say on whether a tenant may change what it pays right now —
+     * refuse a checkout, a plan change or the portal for an organization that is
+     * deleted or suspended. Fail with a `BillingError` to refuse; the provider
+     * is not called. The roles check (`billing:manage`) answers WHO may act; this
+     * answers whether the TENANT may, which a scope cannot see.
+     */
+    readonly admit?: (tenantId: string, action: BillingAction) => Effect.Effect<void, BillingError>;
+    /**
+     * Origins the provider may send the customer back to (`successUrl`,
+     * `cancelUrl`, the portal's `returnUrl`) — e.g. `['https://app.example.com']`.
+     * Without it any URL is accepted, which makes checkout a redirect to
+     * anywhere; the plugin says so at boot when the Stripe provider is active.
+     */
+    readonly redirectOrigins?: ReadonlyArray<string>;
+    /**
+     * Whether the app has closed (deleted) a tenant — positive evidence only.
+     * The next sync of a closed tenant that is still paying (any event, the
+     * catch-up, a checkpoint) ends its subscriptions: the safety net for a
+     * deletion path that did not call `closeAccount`. An unknown tenant is NOT closed (a subscription pointed at
+     * the wrong database must never be ended by it).
+     */
+    readonly isTenantClosed?: (tenantId: string) => Effect.Effect<boolean, BillingError>;
     readonly resolveEntitlementLimit?: (tenantId: string, key: string) => Effect.Effect<number | null, BillingError>;
     /**
      * Namespace for this plugin's rpc tags + inspect endpoints. Default `billing`.
@@ -237,6 +293,10 @@ export declare interface BillingProvider {
      *  When false, `BillingService.reportUsage` records locally but never
      *  calls `provider.reportUsage`. */
     readonly supportsMeteredUsage: boolean;
+    /** Whether a usage push must name a linked provider customer. Stripe
+     *  meters map events to a customer by id, so an unlinked tenant's usage
+     *  stays pending instead of being sent unattributable. */
+    readonly usageRequiresCustomer?: boolean;
     readonly createCheckoutSession: (input: CheckoutInput) => Effect.Effect<{
         url: string;
     }, BillingError>;
@@ -272,6 +332,43 @@ export declare interface BillingProvider {
      * provider does not know the id.
      */
     readonly fetchSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState | null, BillingError>;
+    /**
+     * Every live (not yet ended) subscription at the provider, optionally for
+     * one customer. The provider-side half of reconciliation: what it lists is
+     * the truth our rows are corrected to.
+     */
+    readonly listSubscriptions: (input: {
+        readonly providerCustomerId?: string;
+    }) => Effect.Effect<ReadonlyArray<ProviderSubscriptionSnapshot>, BillingError>;
+    /** End a subscription — at period end (reversible) or immediately with a
+     *  final invoice. Returns the provider's state afterwards. */
+    readonly cancelSubscription: (input: {
+        readonly providerSubscriptionId: string;
+        readonly mode: CancelMode;
+    }) => Effect.Effect<ProviderSubscriptionState, BillingError>;
+    /** Undo a period-end cancellation that has not taken effect yet. */
+    readonly resumeSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState, BillingError>;
+    /**
+     * The provider customer for a tenant, created when it has none — BEFORE the
+     * first checkout, so every checkout names its customer. That is what lets
+     * the provider refuse a second subscription for the same customer, and
+     * lets open checkouts be found and expired. Must be idempotent per tenant:
+     * two concurrent first checkouts get the same customer.
+     */
+    readonly ensureCustomer: (input: {
+        readonly tenantId: string;
+    }) => Effect.Effect<string, BillingError>;
+    /** Expire every checkout still open for a customer, so only the newest one
+     *  can be paid. Returns how many were expired. */
+    readonly expireOpenCheckouts: (input: {
+        readonly providerCustomerId: string;
+    }) => Effect.Effect<number, BillingError>;
+    /** Add prices the subscription is missing (metered items), without
+     *  proration. Prices already present are left alone. */
+    readonly addSubscriptionPrices: (input: {
+        readonly providerSubscriptionId: string;
+        readonly priceIds: ReadonlyArray<string>;
+    }) => Effect.Effect<void, BillingError>;
     /**
      * The billing contact the PROVIDER has on file, when it has one. Used as the
      * dunning recipient of last resort — `dunning.resolveRecipient` wins when
@@ -298,6 +395,23 @@ export declare interface BillingProvider {
      *  `null` for an event type this provider doesn't model (handler
      *  no-ops, still 200). */
     readonly normalizeEvent: (raw: unknown) => Effect.Effect<BillingEvent | null, BillingError>;
+    /**
+     * Who and when a verified payload is about: the provider customer it names
+     * and when the provider created it. The webhook syncs that customer from a
+     * fresh read instead of trusting the payload, and an event created long
+     * before it arrives means deliveries were failing — the cue to catch up.
+     * Optional: without it the webhook applies the normalized event as is.
+     */
+    readonly eventContext?: (raw: unknown) => {
+        readonly providerCustomerId: string | null;
+        readonly createdAt: Date | null;
+    };
+    /**
+     * Events the provider could not deliver to the app's webhook, as far back as
+     * it keeps them (Stripe: 30 days) — what an outage of the endpoint left
+     * behind. Optional: a provider without it has no catch-up.
+     */
+    readonly listUndeliveredEvents?: () => Effect.Effect<ReadonlyArray<UndeliveredEvent>, BillingError>;
 }
 
 export declare type BillingProviderName = 'stripe' | 'mock';
@@ -329,6 +443,31 @@ export declare interface BillingServiceOptions {
         /** Free-trial length. The provider runs the trial and reports `trialing`. */
         readonly trialDays?: number;
     };
+    /**
+     * The app's say on whether a tenant may change what it pays right now —
+     * e.g. refuse a checkout for a deleted or suspended organization. Called
+     * before the provider is; a failure refuses the call. Absent → every
+     * authorized caller is admitted.
+     */
+    readonly admit?: (tenantId: string, action: BillingAction) => Effect.Effect<void, BillingError>;
+    /**
+     * Origins a checkout's `successUrl` / `cancelUrl` and a portal's `returnUrl`
+     * may point at. The provider redirects the customer there, so an arbitrary
+     * URL would make our checkout a redirect to anywhere. Absent → any URL.
+     */
+    readonly redirectOrigins?: ReadonlyArray<string>;
+    /**
+     * Whether the app has closed (deleted) a tenant. The reconcile ends every
+     * subscription of a closed tenant still paying — the safety net for a
+     * deletion path that did not call `closeAccount`. Answer `true` only on
+     * positive evidence (a row marked deleted): an unknown tenant is not proof,
+     * and a failing check is treated as "not closed".
+     */
+    readonly isTenantClosed?: (tenantId: string) => Effect.Effect<boolean, BillingError>;
+    /** The app's per-event side effects, run for every correction a sync or
+     *  reconcile makes (the webhook runs them itself, and fails the delivery on
+     *  an error). */
+    readonly onEvent?: OnEventMap;
     /** Clock injection for deterministic period + grace windowing in tests. */
     readonly now?: () => Date;
     /**
@@ -400,6 +539,8 @@ export declare interface BillingServiceShape {
         readonly plan: PlanId;
         readonly successUrl: string;
         readonly cancelUrl: string;
+        /** Seats to buy up front. Omit for 1. */
+        readonly quantity?: number;
     }) => Effect.Effect<{
         url: string;
     }, BillingError>;
@@ -407,6 +548,48 @@ export declare interface BillingServiceShape {
     readonly portalUrl: (tenantId: string, returnUrl: string) => Effect.Effect<{
         url: string;
     }, BillingError>;
+    /**
+     * The customer's own cancellation: the subscription stays active until the
+     * paid period ends, then ends. The provider applies it first; the row
+     * mirrors its answer (`cancelAt`). Reversible with `resumeSubscription`.
+     */
+    readonly cancelSubscription: (tenantId: string) => Effect.Effect<Subscription, BillingError>;
+    /** Take back a period-end cancellation before it takes effect. */
+    readonly resumeSubscription: (tenantId: string) => Effect.Effect<Subscription, BillingError>;
+    /**
+     * End every provider subscription of a tenant — for deleting an
+     * organization or account. Pending usage is flushed first; each subscription
+     * then ends once that usage has settled on the meter (minutes, see
+     * `CancelMode` 'close') with a final invoice for it and a proration credit.
+     * The rows carry the end as `cancelAt` until the provider's deletion event
+     * marks them canceled. The provider customer and its invoices are KEPT: they
+     * are the accounting record. Fails without ending anything when the flush
+     * fails, so no usage is lost; the caller retries.
+     */
+    readonly closeAccount: (tenantId: string) => Effect.Effect<CloseAccountResult, BillingError>;
+    /**
+     * Correct every local row from the provider: what the provider lists wins,
+     * a local live row the provider no longer lists is re-read directly, missing
+     * metered items are added back. Run it on a schedule — it heals whatever a
+     * missed or failed webhook left behind.
+     */
+    readonly reconcileFromProvider: () => Effect.Effect<ProviderReconcileResult, BillingError>;
+    /**
+     * Bring one provider customer's rows to what the provider says now, and
+     * return its current state as events (all of it, not just changes). The
+     * webhook uses it for the customer an event names. Does not run `onEvent`.
+     */
+    readonly syncCustomer: (providerCustomerId: string, hintTenantId?: string) => Effect.Effect<{
+        readonly tenantId: string | null;
+        readonly events: ReadonlyArray<BillingEvent>;
+    }, BillingError>;
+    /**
+     * The checkpoint: sync a tenant from the provider, run `onEvent` for what it
+     * found, and answer with its current subscription. Call it where a stale row
+     * would matter — the return from checkout or the portal, a billing page
+     * load. Every call that changes what a tenant pays already runs it first.
+     */
+    readonly syncTenant: (tenantId: string) => Effect.Effect<Subscription | null, BillingError>;
     /** Apply a normalized provider event to the DB rows (idempotent upsert). */
     readonly applyEvent: (event: BillingEvent) => Effect.Effect<void, BillingError>;
     /**
@@ -471,13 +654,11 @@ declare interface BillingWebhookOptions {
      *  `constructEvent`) uses. Null → the mount answers 503: an unverifiable
      *  billing webhook must not reach subscription state. */
     readonly webhookSecret?: string | null;
+    /** Called when an event arrives long after it was created — deliveries were
+     *  failing; the plugin catches up on what the endpoint missed. */
+    readonly onLateDelivery?: () => void;
 }
 
-/**
- * Build the BillingService implementation. The interceptor + the plugin's
- * rpc routes share this single instance (so `enforce` and the rpc routes
- * see the same swapped-in stores).
- */
 export declare const buildBillingService: (options: BillingServiceOptions) => {
     readonly service: BillingServiceShape;
     readonly holder: StoreHolder;
@@ -498,10 +679,49 @@ export declare const buildEnforceInterceptor: (enforce: EnforceMap, service: Bil
 /** Build the registry from `billingPlugin({ plans })`. */
 export declare const buildPlanRegistry: (plans: Readonly<Record<PlanId, PlanConfig>>) => PlanRegistry;
 
+/** How a subscription ends. */
+export declare type CancelMode = 
+/** Stays active until the paid period ends, then ends — the customer's own
+*  cancellation. Reversible with `resumeSubscription` until then. */
+'periodEnd'
+/**
+* Closing an account: ends as soon as the last usage has settled on the
+* meter — a few minutes, not a period — with a final invoice for that usage
+* and a proration credit for the unused time.
+*
+* Not "now", on purpose: meter events aggregate asynchronously, and a
+* subscription ended the moment its last usage was sent is invoiced for none
+* of it (measured: the meter showed 250, the final invoice 0, and a finalized
+* invoice never picks the usage up later).
+*/
+| 'close';
+
+/** One finding. `apply` is the request that resolves it; absent → a human. */
+export declare type CatalogFinding = {
+    readonly kind: 'ok';
+    readonly object: string;
+} | {
+    readonly kind: 'create' | 'update' | 'adopt';
+    readonly object: string;
+    readonly detail: string;
+    readonly apply: StripeRequest;
+} | {
+    readonly kind: 'drift';
+    readonly object: string;
+    readonly detail: string;
+    readonly apply?: StripeRequest;
+} | {
+    readonly kind: 'manual';
+    readonly object: string;
+    readonly detail: string;
+};
+
 export declare interface CheckoutInput {
     readonly tenantId: string;
     /** Provider price id to subscribe to. */
     readonly priceId: string;
+    /** Usage-based prices added next to `priceId` (no quantity). */
+    readonly meteredPriceIds?: ReadonlyArray<string>;
     readonly successUrl: string;
     readonly cancelUrl: string;
     /** Optional existing provider customer id to attach the checkout to. */
@@ -527,6 +747,13 @@ export declare interface CheckoutInput {
  */
 export declare const claimFlushWindow: (store: DataStore, windowKey: string, replicaId: string, nowMs: number) => Promise<boolean>;
 
+/** What `closeAccount` did at the provider. */
+export declare interface CloseAccountResult {
+    readonly tenantId: string;
+    /** Provider subscriptions ended (immediately, with a final invoice). */
+    readonly canceled: ReadonlyArray<string>;
+}
+
 declare interface CustomerRecord {
     readonly tenantId: string;
     readonly provider: string;
@@ -536,6 +763,12 @@ declare interface CustomerRecord {
 export declare interface CustomerStore {
     readonly upsert: (record: CustomerRecord) => Effect.Effect<void, BillingError>;
     readonly getByTenant: (tenantId: string) => Effect.Effect<CustomerRecord | null, BillingError>;
+    readonly getByProviderCustomerId: (providerCustomerId: string) => Effect.Effect<CustomerRecord | null, BillingError>;
+    /** Every linked customer — the provider reconcile's per-customer pass. */
+    readonly list: () => Effect.Effect<ReadonlyArray<CustomerRecord>, BillingError>;
+    /** Drop the link to a provider customer that no longer exists. Returns the
+     *  tenant it belonged to, or null when it was not linked. */
+    readonly removeByProviderCustomerId: (providerCustomerId: string) => Effect.Effect<string | null, BillingError>;
 }
 
 export declare const dataStoreDunningNoticeStore: (store: DataStore) => DunningNoticeStore;
@@ -576,6 +809,50 @@ export declare const defaultDunningEmail: (notice: {
     readonly text: string;
 };
 
+/** A meter: found by event name (Stripe keeps it unique per account). Only the
+ *  display name is editable; anything else is a human's call. */
+export declare const diffMeter: (spec: StripeCatalogMeter, meters: ReadonlyArray<StripeMeter>) => {
+    finding: CatalogFinding;
+    id: string | null;
+};
+
+/** The portal configuration: found by `metadata.voltro_key`, else adopted by
+ *  its name; must be the account default, since sessions name none. */
+export declare const diffPortal: (portal: StripeCatalog["portal"], env: StripeCatalogEnvironment, plans: ReadonlyArray<{
+    readonly productId: string;
+    readonly priceId: string;
+}> | null, configs: ReadonlyArray<StripePortalConfiguration>) => ReadonlyArray<CatalogFinding>;
+
+/**
+ * A price: found by `lookup_key`. A price's amount, currency, interval, meter
+ * and tax behaviour cannot be edited at Stripe — a mismatch means a NEW price
+ * that takes the key over, which is a pricing change and runs only when
+ * `allowPriceChange` says so. Existing subscriptions stay on their old price
+ * (Stripe does not move them); that is the customer-facing half of the
+ * decision, and why it is never automatic.
+ */
+export declare const diffPrice: (spec: StripeCatalogPrice, productId: string | null, meterId: string | null, byLookup: StripePrice | null, productPrices: ReadonlyArray<StripePrice>, allowPriceChange: boolean) => {
+    finding: CatalogFinding;
+    id: string | null;
+};
+
+/**
+ * A product: found by `metadata.voltro_key`; failing that, ADOPTED from an
+ * active product carrying the same identifying metadata (one created before
+ * the catalog existed) — only when exactly one qualifies, never by guessing.
+ */
+export declare const diffProduct: (spec: StripeCatalogProduct, products: ReadonlyArray<StripeProduct>) => {
+    finding: CatalogFinding;
+    id: string | null;
+};
+
+export declare const diffTaxSettings: (tax: StripeCatalog["tax"], settings: StripeTaxSettings) => CatalogFinding;
+
+/** The webhook endpoint, where the environment has one: every event the plugin
+ *  maps, on the SDK's API version. Its signing secret exists only in the
+ *  response to its creation. */
+export declare const diffWebhook: (env: StripeCatalogEnvironment, endpoints: ReadonlyArray<StripeWebhookEndpoint>) => CatalogFinding;
+
 /** The steps whose `afterHours` have elapsed. Ledger claims — not this
  *  function — decide which of them actually SEND. */
 export declare const dueSteps: (steps: ReadonlyArray<DunningStep>, pastDueSince: Date, now: Date) => ReadonlyArray<DunningStep>;
@@ -776,6 +1053,13 @@ export declare interface EntitlementStatus {
     readonly lockout: LockoutMode;
 }
 
+/**
+ * Why `path` must not receive secrets, or null when it may: a file inside a git
+ * work tree that git would track (not ignored) is one `git add .` from being
+ * committed with a live account's price ids and webhook secret in it.
+ */
+export declare const envOutRefusal: (path: string, git?: (args: ReadonlyArray<string>, cwd: string) => boolean, realpath?: (p: string) => string) => string | null;
+
 /** The episode a `pastDueSince` identifies. Recovery clears the column, so the
  *  next failure necessarily produces a different key. */
 export declare const episodeKeyOf: (pastDueSince: Date) => string;
@@ -805,6 +1089,9 @@ export declare const evaluateEntitlement: (entitlement: string, limit: number, u
  *  flushing within the same interval land on the same key → one wins. */
 export declare const flushWindowKey: (nowMs: number, intervalMs: number) => string;
 
+/** Stripe's form encoding: `a[b][0][c]=v`. `null` unsets a field (empty value). */
+export declare const formEncode: (params: Readonly<Record<string, unknown>>) => string;
+
 /** When the grace for an episode runs out. */
 export declare const graceEndOf: (pastDueSince: Date, graceHours: number) => Date;
 
@@ -843,12 +1130,9 @@ export declare interface InvoiceStore {
     readonly listByTenant: (tenantId: string) => Effect.Effect<ReadonlyArray<InvoiceRecord_2>, BillingError>;
 }
 
-/**
- * Is `incoming` older than what the row already reflects? Undated events never
- * displace a dated one, and a dated event always wins over an undated row —
- * that ordering is what makes a hand-built (undated) payload usable in tests
- * without letting it stomp production ordering.
- */
+/** Is this a real deployment boot? Only an explicitly dev-like NODE_ENV is not. */
+export declare const isProductionBoot: (nodeEnv: string | undefined) => boolean;
+
 export declare const isStaleStatusEvent: (existing: Date | null, incoming: Date | null) => boolean;
 
 /**
@@ -866,6 +1150,9 @@ export declare const memoryDunningNoticeStore: () => DunningNoticeStore;
 
 export declare const memoryStores: () => BillingStores;
 
+/** Replace (or add) `NAME=value` lines; every other line is kept as it was. */
+export declare const mergeEnvFile: (text: string, values: Readonly<Record<string, string>>) => string;
+
 /** `meterKey → source`. The meterKey is the entitlement/usage key reported to
  *  the provider (`billing.reportUsage(tenant, meterKey, qty)`). */
 declare type MeteringConfig = Readonly<Record<string, MeterSource>>;
@@ -917,6 +1204,32 @@ export declare interface MockProvider extends BillingProvider {
     readonly setCustomerEmail: (providerCustomerId: string, email: string | null) => void;
     /** Every `fetchSubscription` id asked for — proves the reconcile happened. */
     readonly fetched: ReadonlyArray<string>;
+    /** Put a subscription on the provider's LIST (and its direct read) — what
+     *  `listSubscriptions` returns and a reconcile corrects local rows to. */
+    readonly listSubscription: (snapshot: ProviderSubscriptionSnapshot) => void;
+    /** Recorded cancellations, in order. */
+    readonly cancels: ReadonlyArray<{
+        readonly providerSubscriptionId: string;
+        readonly mode: CancelMode;
+    }>;
+    /** Recorded resumptions. */
+    readonly resumes: ReadonlyArray<string>;
+    /** Recorded `addSubscriptionPrices` calls. */
+    readonly priceAdds: ReadonlyArray<{
+        readonly providerSubscriptionId: string;
+        readonly priceIds: ReadonlyArray<string>;
+    }>;
+    /** Recorded checkout sessions. */
+    readonly checkouts: ReadonlyArray<CheckoutInput>;
+    /** Customers created by `ensureCustomer`, by tenant. */
+    readonly customersCreated: ReadonlyArray<string>;
+    /** Every `expireOpenCheckouts` call, by customer. */
+    readonly expiredFor: ReadonlyArray<string>;
+    /** Set what `listUndeliveredEvents` reports — events the provider could
+     *  not deliver to the app's webhook. */
+    readonly setUndelivered: (events: ReadonlyArray<UndeliveredEvent>) => void;
+    /** How often `listUndeliveredEvents` was asked — proves a catch-up ran. */
+    readonly undeliveredReads: () => number;
 }
 
 export declare const mockProvider: (options?: {
@@ -957,6 +1270,19 @@ export declare const normalizeStripeEvent: (event: default_2.Event, resolvePrice
 /** Per-event side effect, run AFTER the row is updated. */
 export declare type OnEventMap = Readonly<Record<string, (event: BillingEvent) => Effect.Effect<void, unknown>>>;
 
+/** Findings the account still differs by (after `apply`: what it could not fix). */
+export declare const openFindings: (findings: ProvisionResult["findings"]) => (CatalogFinding & {
+    readonly applied?: boolean;
+})[];
+
+export declare interface ParsedProvisionArgs extends ProvisionOptions {
+    readonly confirmLive: boolean;
+    readonly strict: boolean;
+}
+
+/** Parse the command line; a string is the refusal. */
+export declare const parseProvisionArgs: (argv: ReadonlyArray<string>) => ParsedProvisionArgs | string;
+
 /** Calendar-month window key (`'YYYY-MM'`) for metered counters. */
 export declare const periodKey: (now?: Date) => string;
 
@@ -964,6 +1290,13 @@ export declare const periodKey: (now?: Date) => string;
 export declare interface PlanConfig {
     /** Provider price id (Stripe `price_…`). Absent for free/zero-cost plans. */
     readonly priceId?: string;
+    /**
+     * Usage-based provider prices subscribed ALONGSIDE `priceId` (Stripe prices
+     * with `recurring.meter`). Checkout adds each as a quantity-less line item,
+     * so the subscription carries the metered item from its first invoice —
+     * without it, meter events are recorded at Stripe but never billed.
+     */
+    readonly meteredPriceIds?: ReadonlyArray<string>;
     /** Per-entitlement-key limits. Values are `number | 'unlimited'`. */
     readonly entitlements: Readonly<Record<string, EntitlementLimit>>;
     /** The plan's per-period price in INTEGER minor units (cents) — the unit
@@ -994,6 +1327,8 @@ export declare interface PlanRegistry {
     readonly planForPriceId: (priceId: string) => PlanId | null;
     /** The provider price id for a plan, or null (free plans have none). */
     readonly priceIdFor: (plan: PlanId) => string | null;
+    /** The usage-based price ids subscribed next to the plan price. */
+    readonly meteredPriceIdsFor: (plan: PlanId) => ReadonlyArray<string>;
     /** The per-seat unit amount in integer minor units for a plan; `0` for a
      *  free/undeclared plan. Multiplied by seat quantity for the billed amount. */
     readonly unitAmountFor: (plan: PlanId) => number;
@@ -1010,6 +1345,51 @@ export declare interface PortalInput {
     readonly returnUrl: string;
 }
 
+/** The portal configuration the plugin's sessions use (the account default). */
+export declare const portalParams: (portal: StripeCatalog["portal"], env: StripeCatalogEnvironment, plans: ReadonlyArray<{
+    readonly productId: string;
+    readonly priceId: string;
+}>) => Record<string, unknown>;
+
+/** What `reconcileFromProvider` found and corrected. */
+export declare interface ProviderReconcileResult {
+    /** Subscriptions compared (provider-listed plus local rows it did not list). */
+    readonly checked: number;
+    /** Tenants whose local rows changed because the provider said otherwise. */
+    readonly corrected: ReadonlyArray<string>;
+    /** Tenants with more than one live subscription at the provider — billed
+     *  twice. Never resolved automatically: refunding is a human decision. */
+    readonly duplicates: ReadonlyArray<string>;
+    /** Provider subscriptions naming no tenant; nothing to attribute them to. */
+    readonly unattributed: number;
+    /** Subscriptions that had a plan's metered price added back. */
+    readonly meteredItemsRestored: number;
+    /** Tenants the app reports closed whose subscriptions were still paying —
+     *  ended now (see `isTenantClosed`). */
+    readonly closedTenants: ReadonlyArray<string>;
+    /** Live rows the provider has never heard of that were NOT canceled, because
+     *  so many at once means the wrong account or provider (0 normally). */
+    readonly refusedUnknown: number;
+    /** Every correction as the event it stands for, for the app's `onEvent`
+     *  projections; the plugin's scheduled reconcile dispatches them. */
+    readonly events: ReadonlyArray<BillingEvent>;
+}
+
+/**
+ * One subscription as the provider lists it — the input of the provider-side
+ * reconcile. Carries the ids a local row is matched by and the price ids a
+ * plan's metered items are checked against.
+ */
+export declare interface ProviderSubscriptionSnapshot extends ProviderSubscriptionState {
+    readonly providerSubscriptionId: string;
+    readonly providerCustomerId: string | null;
+    /** From the subscription's own metadata; null when the provider object was
+     *  not created through our checkout and names no tenant. */
+    readonly tenantId: string | null;
+    /** Every price the subscription carries, licensed and metered. */
+    readonly priceIds: ReadonlyArray<string>;
+}
+
 /** The provider's CURRENT view of a subscription — read directly, not from an
  *  event body. `reconcileDunning` asks for this before it will lock anyone
  *  out. */
@@ -1023,6 +1403,34 @@ export declare interface ProviderSubscriptionState {
     readonly cancelAt: Date | null;
 }
 
+export declare interface ProvisionOptions {
+    readonly env: StripeEnvironment;
+    readonly apply: boolean;
+    readonly allowPriceChange: boolean;
+    /** Where `STRIPE_PRICE_*` ids and a created webhook's secret go; null →
+     *  nowhere (and a webhook endpoint is then not created). */
+    readonly envOut: string | null;
+}
+
+export declare interface ProvisionResult {
+    readonly livemode: boolean;
+    readonly findings: ReadonlyArray<CatalogFinding & {
+        readonly applied?: boolean;
+    }>;
+    /** Price ids by env name, and a created webhook's `STRIPE_WEBHOOK_SECRET`. */
+    readonly envOut: Readonly<Record<string, string>>;
+}
+
+/**
+ * Read the account, diff it against the catalog, and (with `apply`) fix what
+ * can be fixed — in dependency order: meters, products, prices, tax, portal,
+ * webhook.
+ */
+export declare const provisionStripeCatalog: (rest: StripeRest, catalog: StripeCatalog, options: ProvisionOptions) => Promise<ProvisionResult>;
+
+/** Stripe echoes a masked key in auth errors, and the mask ends in real characters. */
+export declare const redactStripeKeys: (text: string) => string;
+
 /**
  * In-handler DUNNING guard: refuse when the tenant's grace period has run out.
  *
@@ -1097,14 +1505,36 @@ declare interface ResolveProviderInput {
     readonly env: NodeJS.ProcessEnv;
     /** Price id → plan id, from the plugin's plan registry. */
     readonly planForPriceId?: (priceId: string) => string | null;
-    /** Where the mock-by-absence warning goes. Optional: a library caller
-     *  resolving a provider outside a boot has nowhere to put it, and a missing
-     *  logger must not be a reason to fail. */
-    readonly log?: {
-        readonly warn: (message: string) => void;
-    };
 }
 
+/** The key for `env`, checked against its mode. */
+export declare const resolveProvisionKey: (env: StripeEnvironment, vars: NodeJS.ProcessEnv, dotenvKey: string | undefined) => {
+    key: string;
+} | {
+    refusal: string;
+};
+
+/**
+ * The provisioning command. Exit code: 0 when the account matches the catalog
+ * (after `--apply`: when everything it could fix is fixed); 1 when something
+ * still differs; 2 on a refused invocation. `manual` items fail the run only
+ * with `--strict` — the launch-readiness check.
+ */
+export declare const runStripeProvision: (catalog: StripeCatalog, argv: ReadonlyArray<string>, options?: {
+    readonly dotenv?: string;
+    readonly rest?: (key: string) => StripeRest;
+    readonly vars?: NodeJS.ProcessEnv;
+}) => Promise<number>;
+
+/** What only a human can settle before an environment sells. */
+export declare const sellingReadiness: (input: {
+    readonly catalog: StripeCatalog;
+    readonly env: StripeCatalogEnvironment;
+    readonly chargesEnabled: boolean | null;
+    readonly accountTaxIds: number | null;
+    readonly activeRegistrations: ReadonlyArray<string>;
+}) => ReadonlyArray<CatalogFinding>;
+
 /**
  * A mutable holder so `bindDataStore` can swap the stores AFTER the service
  * layer is built. The service reads `holder.stores` on every call rather
@@ -1115,6 +1545,157 @@ declare interface StoreHolder {
     stores: BillingStores;
 }
 
+/** The API version every provisioning request and webhook endpoint uses — the
+ *  one the SDK the plugin bills with pins. */
+export declare const STRIPE_API_VERSION: string;
+
+/** The Dashboard steps no API can check, which every Stripe billing app needs. */
+export declare const STRIPE_DASHBOARD_REMINDERS: ReadonlyArray<string>;
+
+/**
+ * Every Stripe event type `normalizeStripeEvent` maps — the list a webhook
+ * endpoint subscribes to. Subscribing to fewer loses state changes; a test
+ * holds this list to the switch below.
+ */
+export declare const STRIPE_WEBHOOK_EVENTS: ReadonlyArray<string>;
+
+export declare interface StripeCatalog {
+    readonly products: ReadonlyArray<StripeCatalogProduct>;
+    readonly meters: ReadonlyArray<StripeCatalogMeter>;
+    readonly tax: {
+        /** The business location Stripe Tax computes from. */
+        readonly headOffice: StripeCatalogAddress;
+        readonly defaultTaxCode: string;
+        readonly defaultTaxBehavior: 'exclusive' | 'inclusive';
+        /** Countries an active registration must exist for before tax is collected. */
+        readonly registrationCountries: ReadonlyArray<string>;
+    };
+    readonly portal: {
+        readonly key: string;
+        readonly name: string;
+        readonly headline: string;
+        readonly privacyPolicyUrl: string;
+        readonly termsOfServiceUrl: string;
+    };
+    readonly environments: Readonly<Record<StripeEnvironment, StripeCatalogEnvironment>>;
+    /** Dashboard-only steps, listed as reminders where selling readiness is required. */
+    readonly dashboardReminders?: ReadonlyArray<string>;
+}
+
+export declare interface StripeCatalogAddress {
+    readonly line1: string;
+    readonly line2?: string;
+    readonly postal_code: string;
+    readonly city: string;
+    readonly state?: string;
+    readonly country: string;
+}
+
+export declare interface StripeCatalogEnvironment {
+    /** Where the customer portal returns to. */
+    readonly portalReturnUrl: string;
+    /** The app's `POST /billing/webhook` URL, or null where `stripe listen`
+     *  forwards instead (local development against a sandbox). */
+    readonly webhookUrl: string | null;
+    /** Whether account-level steps (activation, tax ids, Dashboard-only
+     *  settings) must be done before this environment sells. */
+    readonly requireSellingReadiness: boolean;
+}
+
+export declare interface StripeCatalogMeter {
+    readonly eventName: string;
+    readonly displayName: string;
+    readonly formula: 'sum' | 'count' | 'last';
+    /** Payload key naming the customer — `stripe_customer_id` for this plugin. */
+    readonly customerPayloadKey: string;
+    readonly valuePayloadKey: string;
+}
+
+export declare interface StripeCatalogPrice {
+    readonly lookupKey: string;
+    /** The env var the app reads this price's id from (`--env-out` writes it). */
+    readonly envName: string;
+    readonly currency: string;
+    readonly unitAmount: number;
+    readonly interval: 'day' | 'week' | 'month' | 'year';
+    readonly usageType: 'licensed' | 'metered';
+    /** For a metered price: the event name of the catalog meter it bills. */
+    readonly meter?: string;
+    readonly taxBehavior: 'exclusive' | 'inclusive';
+}
+
+export declare interface StripeCatalogProduct {
+    /** Stable identity, stored as `metadata.voltro_key`. */
+    readonly key: string;
+    readonly name: string;
+    readonly description: string;
+    readonly unitLabel: string;
+    readonly taxCode: string;
+    /** Extra metadata beside `voltro_key` — also what a product created before
+     *  the catalog is ADOPTED by (exactly one active product must carry it). */
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly price: StripeCatalogPrice;
+    /** Whether customers may switch to this product in the portal. */
+    readonly inPortal: boolean;
+}
+
+export declare type StripeEnvironment = 'sandbox' | 'live';
+
+declare interface StripeMeter {
+    readonly id: string;
+    readonly status: string;
+    readonly event_name: string;
+    readonly display_name: string;
+    readonly default_aggregation: {
+        readonly formula: string;
+    };
+    readonly customer_mapping: {
+        readonly type: string;
+        readonly event_payload_key: string;
+    };
+    readonly value_settings: {
+        readonly event_payload_key: string;
+    };
+}
+
+declare interface StripePortalConfiguration {
+    readonly id: string;
+    readonly active: boolean;
+    readonly is_default: boolean;
+    readonly name: string | null;
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly default_return_url: string | null;
+    readonly business_profile: Readonly<Record<string, unknown>>;
+    readonly features: Readonly<Record<string, unknown>>;
+}
+
+declare interface StripePrice {
+    readonly id: string;
+    readonly active: boolean;
+    readonly product: string;
+    readonly currency: string;
+    readonly unit_amount: number | null;
+    readonly lookup_key: string | null;
+    readonly tax_behavior: string | null;
+    readonly recurring: {
+        readonly interval: string;
+        readonly usage_type: string;
+        readonly meter: string | null;
+    } | null;
+}
+
+declare interface StripeProduct {
+    readonly id: string;
+    readonly active: boolean;
+    readonly name: string;
+    readonly description: string | null;
+    readonly unit_label: string | null;
+    readonly tax_code: string | null | {
+        readonly id: string;
+    };
+    readonly metadata: Readonly<Record<string, string>>;
+}
+
 export declare const stripeProvider: (options: StripeProviderOptions) => BillingProvider;
 
 export declare interface StripeProviderOptions {
@@ -1131,10 +1712,57 @@ export declare interface StripeProviderOptions {
      * on `free` while paying. The plugin passes its plan registry here.
      */
     readonly planForPriceId?: (priceId: string) => string | null;
+    /**
+     * How long a closed account's subscription runs on so its last metered usage
+     * settles before the final invoice (seconds, default 600). Meter events
+     * aggregate asynchronously; ending the subscription sooner invoices usage the
+     * meter has not counted yet as zero.
+     */
+    readonly closeSettleSeconds?: number;
     /** Injected in tests. */
     readonly client?: default_2;
 }
 
+declare interface StripeRequest {
+    readonly method: 'POST';
+    readonly path: string;
+    readonly params: Readonly<Record<string, unknown>>;
+}
+
+export declare interface StripeRest {
+    readonly get: <T>(path: string, query?: Readonly<Record<string, unknown>>) => Promise<T>;
+    readonly post: <T>(path: string, params: Readonly<Record<string, unknown>>) => Promise<T>;
+    /** Every page of a list endpoint. */
+    readonly list: <T>(path: string, query?: Readonly<Record<string, unknown>>) => Promise<ReadonlyArray<T>>;
+}
+
+export declare const stripeRest: (apiKey: string, fetchImpl?: typeof fetch) => StripeRest;
+
+export declare class StripeRestError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+declare interface StripeTaxSettings {
+    readonly status: string;
+    readonly livemode: boolean;
+    readonly head_office: {
+        readonly address: Readonly<Record<string, string | null>>;
+    } | null;
+    readonly defaults: {
+        readonly tax_code: string | null;
+        readonly tax_behavior: string | null;
+    };
+}
+
+declare interface StripeWebhookEndpoint {
+    readonly id: string;
+    readonly url: string;
+    readonly status: string;
+    readonly enabled_events: ReadonlyArray<string>;
+    readonly api_version: string | null;
+}
+
 /** A tenant's subscription row, normalized across providers. */
 export declare interface Subscription {
     readonly tenantId: string;
@@ -1250,7 +1878,11 @@ export declare interface SubscriptionStore {
      * only a provider-confirmed reconcile sets it.
      */
     readonly upsert: (sub: Subscription) => Effect.Effect<void, BillingError>;
+    /** The tenant's CURRENT subscription: a live one when there is one, else
+     *  the most recently changed. An old canceled row never hides a live one. */
     readonly getByTenant: (tenantId: string) => Effect.Effect<Subscription | null, BillingError>;
+    /** Every subscription row of a tenant, newest first. */
+    readonly listByTenant: (tenantId: string) => Effect.Effect<ReadonlyArray<Subscription>, BillingError>;
     /** Every subscription in a given status — the dunning sweep's only query. */
     readonly listByStatus: (status: SubscriptionStatus) => Effect.Effect<ReadonlyArray<Subscription>, BillingError>;
     /** Mark a subscription canceled by provider id (no-op if absent). */
@@ -1282,6 +1914,13 @@ declare interface SubscriptionUpdateInput {
     readonly proration?: 'prorate' | 'none' | 'always_invoice';
 }
 
+/** An event the provider failed to deliver, reduced to what a catch-up needs. */
+declare interface UndeliveredEvent {
+    readonly id: string;
+    readonly providerCustomerId: string | null;
+    readonly createdAt: Date | null;
+}
+
 export declare interface UsagePush {
     readonly tenantId: string;
     readonly entitlementKey: string;
@@ -1289,6 +1928,14 @@ export declare interface UsagePush {
     readonly quantity: number;
     /** End of the period the usage falls in (provider timestamp anchor). */
     readonly periodEnd?: Date;
+    /** The provider customer the usage is billed to, when one is linked. */
+    readonly providerCustomerId?: string;
+    /**
+     * Names THIS delta: the same flush replayed carries the same key (so the
+     * provider can dedupe it), the next delta carries a new one. A key per
+     * (tenant, key, period) alone would make every later delta a "duplicate".
+     */
+    readonly idempotencyKey?: string;
 }
 
 declare interface UsageRow {