@voltro/plugin-billing 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,887 @@
+import { ColumnDefinition } from '@voltro/database';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { IncomingRequest } from '@voltro/plugin-webhooks';
+import { IncomingResponse } from '@voltro/plugin-webhooks';
+import { IncomingWebhookDescriptor } from '@voltro/plugin-webhooks';
+import { Layer } from 'effect';
+import { mountIncomingWebhook } from '@voltro/plugin-webhooks';
+import { RpcInterceptor } from '@voltro/protocol';
+import { RpcKind } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+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";
+
+export declare const BILLING_SUBSCRIPTIONS_TABLE = "_voltro_billing_subscriptions";
+
+export declare const BILLING_USAGE_TABLE = "_voltro_billing_usage";
+
+/** The webhook id + the path the doc + plugin mount at. */
+export declare const BILLING_WEBHOOK_ID = "billing";
+
+export declare const BILLING_WEBHOOK_PATH = "/billing/webhook";
+
+/**
+ * The shape every handler executor receives carries the resolved subject
+ * under `ctx.request.subject` (mirrors `@voltro/plugin-rbac`'s
+ * `RbacContext`). Kept structural so callers need no @voltro/runtime dep.
+ */
+export declare interface BillingContext {
+    readonly request: {
+        readonly subject: Subject;
+    };
+}
+
+/** 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
+ * from the provider, a misconfigured plan) are surfaced immediately. The
+ * `billingPlugin` registers this via `errorSchemas` so it decodes TYPED on
+ * the client rather than crossing as an untyped defect.
+ */
+export declare class BillingError extends BillingError_base {
+}
+
+declare const BillingError_base: Schema.TaggedErrorClass<BillingError, "BillingError", {
+    readonly _tag: Schema.tag<"BillingError">;
+} & {
+    /** Where the failure originated — provider name or an internal stage. */
+    source: typeof Schema.String;
+    message: typeof Schema.String;
+    /** Retryable? The service retries `transient` failures on a Schedule. */
+    transient: typeof Schema.Boolean;
+}>;
+
+/**
+ * The normalized event union a `BillingProvider.normalizeEvent` produces
+ * from a verified, decoded provider webhook payload. `BillingService`
+ * applies these to the DB rows — switching provider swaps the adapter;
+ * the service + rows + entitlement engine are unchanged.
+ */
+export declare type BillingEvent = {
+    readonly _tag: 'subscriptionUpserted';
+    readonly tenantId: string;
+    readonly providerSubscriptionId: string;
+    readonly plan: PlanId;
+    readonly status: SubscriptionStatus;
+    /** Seat quantity from the provider event; defaults to 1 when absent. */
+    readonly quantity?: number;
+    readonly currentPeriodStart?: Date | null;
+    readonly currentPeriodEnd: Date | null;
+    readonly cancelAt: Date | null;
+} | {
+    readonly _tag: 'subscriptionCanceled';
+    readonly tenantId: string;
+    readonly providerSubscriptionId: string;
+} | {
+    readonly _tag: 'invoicePaid';
+    readonly tenantId: string;
+    readonly providerInvoiceId: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+} | {
+    readonly _tag: 'invoicePaymentFailed';
+    readonly tenantId: string;
+    readonly providerInvoiceId: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+} | {
+    readonly _tag: 'customerLinked';
+    readonly tenantId: string;
+    readonly providerCustomerId: string;
+};
+
+/** The event tag union — handy for `onEvent` keys. */
+export declare type BillingEventTag = BillingEvent['_tag'];
+
+/** One row per flush window — `windowKey` UNIQUE makes the INSERT the gate. */
+export declare const billingFlushClaimsTable: TableLike;
+
+/** Invoice history (money as integer minor units). */
+export declare const billingInvoicesTable: BillingTable;
+
+export declare const billingPlugin: (options?: BillingPluginOptions) => VoltroPlugin;
+
+export declare interface BillingPluginOptions {
+    /** `'stripe' | 'mock'` (built from env) or a `BillingProvider`. Default:
+     *  `'stripe'` when `STRIPE_SECRET_KEY` is set, else `'mock'`. */
+    readonly provider?: BillingProviderName | BillingProvider;
+    /** Provider api key — server-only. Default `STRIPE_SECRET_KEY` env. */
+    readonly apiKey?: string;
+    /** Provider webhook signing secret (`whsec_…`). Default `STRIPE_WEBHOOK_SECRET` env. */
+    readonly webhookSecret?: string;
+    /** The single source of tier→limit truth. Keyed by plan id. */
+    readonly plans?: Readonly<Record<PlanId, PlanConfig>>;
+    /** Per-rpc-tag entitlement enforcement (the doc's fictional `guards:`
+     *  replacement) — installs the interceptor when present. */
+    readonly enforce?: EnforceMap;
+    /** Usage-based billing autopilot (round-2/02): derive per-tenant usage from
+     *  the graph's own telemetry (rpc calls / row writes / AI tokens) and flush
+     *  to the provider on a schedule — zero hand-wired counters. Keyed by the
+     *  meter (entitlement/usage) key reported to the provider. */
+    readonly metering?: MeteringConfig;
+    /** Autopilot flush cadence in ms (default 60_000). `0` disables the
+     *  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;
+    /**
+     * Per-tenant entitlement-limit override — the seam for a cloud-issued license
+     * snapshot. Pass `@voltro/plugin-licensing`'s `entitlementResolver` here to let
+     * a signed license decide limits per-tenant; a `null` result falls back to the
+     * static `plans` registry. Absent → static registry only.
+     */
+    readonly resolveEntitlementLimit?: (tenantId: string, key: string) => Effect.Effect<number | null, BillingError>;
+    /** Disambiguates multiple instances of this plugin in one app. */
+    readonly name?: string;
+}
+
+/**
+ * Dumb adapter over a billing provider. Holds NO policy — checkout/portal
+ * URL minting, usage push, and pure payload→event mapping only. The
+ * `BillingService` wraps it with the entitlement engine, the DB rows, and
+ * transient retry.
+ *
+ * `normalizeEvent` receives a payload whose signature was ALREADY verified
+ * by @voltro/plugin-webhooks' mounter — this is pure mapping, never a
+ * second signature check.
+ */
+export declare interface BillingProvider {
+    readonly name: string;
+    /** Whether the provider supports server-pushed metered usage. Stripe
+     *  does (subscription-item usage records); a flat-plan provider may not.
+     *  When false, `BillingService.reportUsage` records locally but never
+     *  calls `provider.reportUsage`. */
+    readonly supportsMeteredUsage: boolean;
+    readonly createCheckoutSession: (input: CheckoutInput) => Effect.Effect<{
+        url: string;
+    }, BillingError>;
+    readonly createPortalSession: (input: PortalInput) => Effect.Effect<{
+        url: string;
+    }, BillingError>;
+    readonly reportUsage: (input: UsagePush) => Effect.Effect<void, 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). */
+    readonly normalizeEvent: (raw: unknown) => Effect.Effect<BillingEvent | null, BillingError>;
+}
+
+export declare type BillingProviderName = 'stripe' | 'mock';
+
+/** The billing service Tag — `const billing = yield* BillingService`. */
+export declare class BillingService extends BillingService_base {
+}
+
+declare const BillingService_base: Context.TagClass<BillingService, "@voltro/plugin-billing/BillingService", BillingServiceShape>;
+
+/** Wrap a built service in a `Layer` for the plugin's `services` field. */
+export declare const billingServiceLayer: (service: BillingServiceShape) => Layer.Layer<BillingService, never, never>;
+
+export declare interface BillingServiceOptions {
+    readonly provider: BillingProvider;
+    readonly plans: PlanRegistry;
+    /** Stores — memory by default; swapped to DataStore-backed via `bindDataStore`. */
+    readonly stores?: BillingStores;
+    /** Transient-failure retries on provider calls. Default 3. */
+    readonly attempts?: 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
+     * `entitlementResolver`). Called before the static plan registry: a non-null
+     * result is used as the limit for `(tenantId, key)`; `null` falls back to the
+     * tenant's plan tier. Absent → behavior is exactly the static registry.
+     */
+    readonly resolveEntitlementLimit?: (tenantId: string, key: string) => Effect.Effect<number | null, BillingError>;
+}
+
+export declare interface BillingServiceShape {
+    /** Read the tenant's subscription row; null when none exists. */
+    readonly subscription: (tenantId: string) => Effect.Effect<Subscription | null, BillingError>;
+    /** Resolve the tenant's plan id; defaults to `'free'` when no row. */
+    readonly plan: (tenantId: string) => Effect.Effect<PlanId, BillingError>;
+    /** Pure read — would `cost` units of `key` be allowed? No mutation. */
+    readonly checkEntitlement: (tenantId: string, key: string, cost: number) => Effect.Effect<EntitlementDecision, BillingError>;
+    /** Check + decrement, atomically. Fails `EntitlementExceeded` over-limit. */
+    readonly consumeEntitlement: (tenantId: string, key: string, cost: number) => Effect.Effect<void, BillingError | EntitlementExceeded>;
+    /** Record metered usage locally; flushed to the provider in batches. */
+    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>;
+    /** Mint a provider-hosted checkout URL for `plan`. */
+    readonly startCheckout: (input: {
+        readonly tenantId: string;
+        readonly plan: PlanId;
+        readonly successUrl: string;
+        readonly cancelUrl: string;
+    }) => Effect.Effect<{
+        url: string;
+    }, BillingError>;
+    /** Mint a provider-hosted billing-portal URL. */
+    readonly portalUrl: (tenantId: string, returnUrl: string) => Effect.Effect<{
+        url: string;
+    }, BillingError>;
+    /** Apply a normalized provider event to the DB rows (idempotent upsert). */
+    readonly applyEvent: (event: BillingEvent) => Effect.Effect<void, BillingError>;
+    /**
+     * Change the tenant's plan mid-cycle. Computes a TIME-BASED prorated
+     * settlement on the amount difference for the unused remainder of the
+     * current period (positive = charge on upgrade, negative = credit on
+     * downgrade), persists the new plan, and returns the settlement. A same-plan
+     * call is a no-op with a zero delta. Fails `BillingError` when the tenant has
+     * no subscription or the target plan is unknown.
+     */
+    readonly changePlan: (tenantId: string, newPlan: PlanId, changeAt?: Date) => Effect.Effect<SubscriptionChange, BillingError>;
+    /**
+     * Set the tenant's seat quantity mid-cycle. Prorates the amount delta
+     * (`unitAmountMinor × Δquantity`) over the unused remainder of the period,
+     * persists the new quantity, and returns the settlement. `quantity` must be a
+     * 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. */
+export declare const billingSubscriptionsTable: BillingTable;
+
+/**
+ * The slice of a built `Table` this package exposes. Annotated explicitly
+ * because the full inferred `Table` type leaks @voltro/database's private
+ * column-builder class across the package boundary (TS4094) — the public
+ * surface only needs the table name, its columns, and its indexes.
+ */
+export declare interface BillingTable extends TableLike {
+    readonly fields: Record<string, ColumnDefinition<unknown>>;
+    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. */
+export declare const billingUsageTable: BillingTable;
+
+/**
+ * The incoming-webhook descriptor for billing. `payload` is `Unknown` —
+ * each provider's payload shape differs and `normalizeEvent` does the
+ * narrowing; the signature + idempotency layers don't need a typed body.
+ */
+export declare const billingWebhookDescriptor: (options: BillingWebhookOptions) => IncomingWebhookDescriptor<unknown>;
+
+declare interface BillingWebhookOptions {
+    readonly provider: BillingProvider;
+    readonly service: BillingServiceShape;
+    readonly onEvent?: OnEventMap;
+}
+
+/**
+ * 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;
+};
+
+/**
+ * Build the interceptor for the `enforce` map. Before the executor runs,
+ * for a matched rpc tag it consumes the rule's cost from the subject's
+ * tenant — short-circuiting with `EntitlementExceeded` BEFORE the
+ * executor when the quota is exhausted (the ratelimit precedent).
+ *
+ * The `service` is captured once at plugin-build time (the same memory/DB
+ * service the `services` layer exposes), so the interceptor doesn't need
+ * to resolve the Tag from a layer it isn't wired into.
+ */
+export declare const buildEnforceInterceptor: (enforce: EnforceMap, service: BillingServiceShape) => RpcInterceptor;
+
+/** Build the registry from `billingPlugin({ plans })`. */
+export declare const buildPlanRegistry: (plans: Readonly<Record<PlanId, PlanConfig>>) => PlanRegistry;
+
+export declare interface CheckoutInput {
+    readonly tenantId: string;
+    /** Provider price id to subscribe to. */
+    readonly priceId: string;
+    readonly successUrl: string;
+    readonly cancelUrl: string;
+    /** Optional existing provider customer id to attach the checkout to. */
+    readonly providerCustomerId?: string;
+}
+
+/**
+ * Try to claim the flush window. INSERT-wins: the first replica's row is the
+ * winner; a racing replica's `insertIgnore` returns that same row, so it sees a
+ * `claimedBy` that isn't its own and stands down. Returns true iff THIS replica
+ * owns the window (→ it runs the flush). Fails OPEN on a store error (better a
+ * possible double-flush — which markReported makes idempotent — than no flush).
+ */
+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;
+    readonly providerCustomerId: string;
+}
+
+export declare interface CustomerStore {
+    readonly upsert: (record: CustomerRecord) => Effect.Effect<void, BillingError>;
+    readonly getByTenant: (tenantId: string) => Effect.Effect<CustomerRecord | null, BillingError>;
+}
+
+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;
+
+export declare type EnforceMap = Readonly<Record<string, EnforceRule>>;
+
+/** One per-tag enforcement rule from `billingPlugin({ enforce })`. */
+export declare interface EnforceRule {
+    /** The entitlement key the tag consumes. */
+    readonly entitlement: string;
+    /** Units charged per call. Default 1. */
+    readonly cost?: number;
+}
+
+/** The result of a pure (non-mutating) entitlement check. */
+export declare interface EntitlementDecision {
+    /** Whether the call would be allowed. */
+    readonly allowed: boolean;
+    /** The entitlement key checked. */
+    readonly entitlement: string;
+    /** The static limit for the caller's plan (`Infinity` for `'unlimited'`). */
+    readonly limit: number;
+    /** How much is already used in the current window. */
+    readonly used: number;
+    /** The cost the call would charge. */
+    readonly cost: number;
+}
+
+/**
+ * Raised when a caller has exhausted an entitlement (quota). Distinct from
+ * the scope/permission `Forbidden` / `ScopeError` — those gate "may you
+ * call this proc"; this gates "do you have quota left". Both axes compose.
+ * `billingPlugin` registers it via `errorSchemas` so callers can
+ * pattern-match on `_tag === 'EntitlementExceeded'`.
+ */
+export declare class EntitlementExceeded extends EntitlementExceeded_base {
+}
+
+declare const EntitlementExceeded_base: Schema.TaggedErrorClass<EntitlementExceeded, "EntitlementExceeded", {
+    readonly _tag: Schema.tag<"EntitlementExceeded">;
+} & {
+    /** The entitlement key that was exhausted (`'aiCalls'`). */
+    entitlement: typeof Schema.String;
+    /** The static limit for the caller's plan. */
+    limit: typeof Schema.Number;
+    /** How much was already used in the current window. */
+    used: typeof Schema.Number;
+    /** The cost the rejected call would have charged. */
+    cost: typeof Schema.Number;
+}>;
+
+/** An entitlement limit: a finite quota or the unbounded `'unlimited'`. */
+export declare type EntitlementLimit = number | 'unlimited';
+
+/**
+ * Pure entitlement decision. `limit` is `Infinity` for an `'unlimited'`
+ * plan. `'unlimited'` and any non-positive cost always allow without
+ * touching the counter; otherwise allow iff `used + cost <= limit`.
+ */
+export declare const evaluateEntitlement: (entitlement: string, limit: number, used: number, cost: number) => EntitlementDecision;
+
+/** The window a `now` falls in, bucketed by the flush interval. Two replicas
+ *  flushing within the same interval land on the same key → one wins. */
+export declare const flushWindowKey: (nowMs: number, intervalMs: number) => string;
+
+declare interface InvoiceRecord {
+    readonly tenantId: string;
+    readonly provider: string;
+    readonly providerInvoiceId: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+    /** 'paid' | 'open' | 'uncollectible' | 'void'. */
+    readonly status: string;
+}
+
+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>;
+}
+
+export declare const memoryStores: () => BillingStores;
+
+/** `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>>;
+
+/** One meter's source — where its usage is derived from. */
+declare type MeterSource = 
+/** Count rpc calls whose tag matches (string = exact, RegExp = test). Optional
+*  `kind` restricts to mutation/query/action. */
+    {
+    readonly from: 'rpc';
+    readonly match: string | RegExp;
+    readonly kind?: RpcKind;
+}
+/** Count row writes to `table` (default op `insert`). */
+| {
+    readonly from: 'cdc';
+    readonly table: string;
+    readonly op?: 'insert' | 'update' | 'delete';
+}
+/** Sum the AI usage ledger — `tokens` (input+output, default) or `costMicroUsd`. */
+| {
+    readonly from: 'ai';
+    readonly metric?: 'tokens' | 'costMicroUsd';
+};
+
+/**
+ * In-memory provider with deterministic outputs. Checkout/portal URLs are
+ * stable functions of the input so tests can assert on them; usage pushes
+ * are recorded on `pushed` for assertion. `normalizeEvent` accepts the
+ * already-normalized `BillingEvent` shape directly (the test feeds events
+ * straight through) OR a `{ type, data }` envelope mirroring the Stripe
+ * mapping, so the same webhook path exercises the mock end-to-end.
+ */
+export declare interface MockProvider extends BillingProvider {
+    /** Recorded usage pushes — assertion surface for tests. */
+    readonly pushed: ReadonlyArray<UsagePush>;
+}
+
+export declare const mockProvider: (options?: {
+    readonly baseUrl?: string;
+    readonly supportsMeteredUsage?: boolean;
+}) => MockProvider;
+
+/** A monetary amount: integer minor units + ISO-4217 currency. */
+export declare interface Money {
+    /** Integer minor units (cents). Never a float. */
+    readonly amountMinor: number;
+    /** ISO-4217 currency code, lowercased (`'usd'`, `'eur'`). */
+    readonly currency: string;
+}
+
+/**
+ * Build the request handler for the billing webhook. The returned function
+ * takes the transport-agnostic `{ method, headers, rawBody }` triple and
+ * returns the typed `IncomingResponse`.
+ */
+export declare const mountBillingWebhook: (options: MountBillingWebhookOptions) => (request: IncomingRequest) => Promise<IncomingResponse>;
+
+declare interface MountBillingWebhookOptions extends BillingWebhookOptions {
+    /** The provider webhook signing secret (`whsec_…`). Null skips verification. */
+    readonly webhookSecret: string | null;
+    /** Optional idempotency-cache override (tests pass a fresh cache). */
+    readonly idempotencyCache?: Parameters<typeof mountIncomingWebhook>[1]['idempotencyCache'];
+}
+
+/**
+ * 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.
+ */
+export declare const normalizeStripeEvent: (raw: unknown) => 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;
+
+/** One plan/tier: its entitlement limits + (for paid plans) a provider price id. */
+export declare interface PlanConfig {
+    /** Provider price id (Stripe `price_…`). Absent for free/zero-cost plans. */
+    readonly priceId?: 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
+     *  amount for ONE seat. Multiplied by the subscription's seat `quantity` to
+     *  get the billed amount, and drives mid-cycle proration. Absent for free
+     *  plans (treated as 0). Never a float. */
+    readonly unitAmountMinor?: number;
+    /** ISO-4217 currency for `unitAmountMinor`, lowercased (`'usd'`). Defaults
+     *  to `'usd'` when a `unitAmountMinor` is set without one. */
+    readonly currency?: string;
+}
+
+/** Plan id (the key in `billingPlugin({ plans })`). */
+export declare type PlanId = string;
+
+export declare interface PlanRegistry {
+    /** Whether `plan` is a known plan id. */
+    readonly has: (plan: PlanId) => boolean;
+    /**
+     * The static limit for `(plan, key)`. `Infinity` for `'unlimited'`, `0`
+     * for an undeclared key. When `plan` is unknown the registry FAILS
+     * CLOSED — returns `0` — never silently granting an unknown plan's quota.
+     * So a redeploy that drops a live plan id DENIES that tenant's quota
+     * rather than falling back to the free-tier limit.
+     */
+    readonly entitlementLimit: (plan: PlanId, key: string) => number;
+    /** The plan id whose `priceId` matches, or null. */
+    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 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;
+    /** The ISO-4217 currency for a plan's price, lowercased; `'usd'` default. */
+    readonly currencyFor: (plan: PlanId) => string;
+    /** All declared plan ids. */
+    readonly planIds: () => ReadonlyArray<PlanId>;
+}
+
+export declare interface PortalInput {
+    readonly tenantId: string;
+    /** Provider customer id whose billing portal to open. */
+    readonly providerCustomerId: string;
+    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
+ * `EntitlementExceeded` when the quota is exhausted. Effect-native.
+ *
+ * ```ts
+ * export default (input, ctx) => Effect.gen(function* () {
+ *   yield* requireEntitlement(ctx, 'aiCalls', Math.ceil(input.tokens / 1000))
+ *   // …
+ * })
+ * ```
+ *
+ * Reads `BillingService` from the per-request layer — declare it in the
+ * effect's R channel (it's provided by `billingPlugin`'s `services`).
+ */
+export declare const requireEntitlement: (ctx: BillingContext, key: string, cost: number) => Effect.Effect<void, BillingError | EntitlementExceeded, BillingService>;
+
+/**
+ * Resolve `options.provider` to a concrete `BillingProvider`. A passed
+ * object is used verbatim. `'stripe'` needs an api key (option or
+ * `STRIPE_SECRET_KEY`). `'mock'` (and the absent default) is the
+ * zero-config in-memory provider.
+ */
+export declare const resolveProvider: (input: ResolveProviderInput) => BillingProvider;
+
+declare interface ResolveProviderInput {
+    readonly provider?: BillingProviderName | BillingProvider;
+    readonly apiKey?: string;
+    readonly env: NodeJS.ProcessEnv;
+}
+
+/**
+ * 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
+ * than capturing a snapshot — identical to how storage rebinds its ref
+ * store once the DataStore exists.
+ */
+declare interface StoreHolder {
+    stores: BillingStores;
+}
+
+export declare const stripeProvider: (options: StripeProviderOptions) => BillingProvider;
+
+export declare interface StripeProviderOptions {
+    readonly apiKey: string;
+    /** Override metered-usage support (Stripe supports it by default). */
+    readonly supportsMeteredUsage?: boolean;
+}
+
+/** A tenant's subscription row, normalized across providers. */
+export declare interface Subscription {
+    readonly tenantId: string;
+    readonly provider: string;
+    readonly providerSubscriptionId: string;
+    readonly plan: PlanId;
+    readonly status: SubscriptionStatus;
+    /** Per-seat quantity — the billed amount is `plan.unitAmountMinor × quantity`.
+     *  Defaults to 1 for a single-seat subscription. */
+    readonly quantity: number;
+    /** Start of the current paid period; null for plans without a period.
+     *  Anchors mid-cycle proration (the "used" side of the period). */
+    readonly currentPeriodStart: Date | null;
+    /** When the current paid period ends; null for plans without a period. */
+    readonly currentPeriodEnd: Date | null;
+    /** When the subscription is scheduled to cancel; null if not scheduled. */
+    readonly cancelAt: Date | null;
+}
+
+/** The outcome of a mid-cycle plan/seat change — the prorated settlement. */
+export declare interface SubscriptionChange {
+    readonly tenantId: string;
+    readonly plan: PlanId;
+    readonly quantity: number;
+    /** Integer minor-unit settlement: > 0 charge, < 0 credit, 0 at boundary. */
+    readonly prorationMinor: number;
+    readonly currency: string;
+}
+
+export declare type SubscriptionStatus = 'active' | 'trialing' | 'pastDue' | 'canceled' | 'incomplete';
+
+export declare interface SubscriptionStore {
+    /** Upsert by `providerSubscriptionId` — the webhook's idempotency anchor. */
+    readonly upsert: (sub: Subscription) => Effect.Effect<void, BillingError>;
+    readonly getByTenant: (tenantId: string) => Effect.Effect<Subscription | null, BillingError>;
+    /** Mark a subscription canceled by provider id (no-op if absent). */
+    readonly markCanceled: (providerSubscriptionId: string) => Effect.Effect<void, BillingError>;
+    /** Apply a mid-cycle plan/seat/status change to the tenant's row (no-op if
+     *  absent). Only the provided fields are patched. */
+    readonly patchByTenant: (tenantId: string, patch: {
+        readonly plan?: PlanId;
+        readonly quantity?: number;
+        readonly status?: SubscriptionStatus;
+    }) => Effect.Effect<void, BillingError>;
+    /** Set a subscription's status by provider id (no-op if absent) — the
+     *  dunning state machine's transition primitive. */
+    readonly setStatus: (providerSubscriptionId: string, status: SubscriptionStatus) => Effect.Effect<void, BillingError>;
+}
+
+export declare interface UsagePush {
+    readonly tenantId: string;
+    readonly entitlementKey: string;
+    /** Aggregate quantity to report for the current period. */
+    readonly quantity: number;
+    /** End of the period the usage falls in (provider timestamp anchor). */
+    readonly periodEnd?: Date;
+}
+
+declare interface UsageRow {
+    readonly tenantId: string;
+    readonly entitlementKey: string;
+    readonly period: string;
+    readonly used: number;
+    readonly reportedToProvider: number;
+}
+
+export declare interface UsageStore {
+    /** Current used count for `(tenant, key, period)`; 0 when no row. */
+    readonly used: (tenantId: string, key: string, period: string) => Effect.Effect<number, BillingError>;
+    /**
+     * Atomic check-and-increment — the entitlement quota gate. In ONE
+     * critical section: read the current `used`, and increment by `cost`
+     * IFF `used + cost <= limit`. Returns the decision; `allowed:false`
+     * means NOTHING was incremented. This is the fix for the read-then-write
+     * race the service layer had — the check and the increment can no longer
+     * interleave with a concurrent caller (memory: one sync tick; DataStore:
+     * a compare-and-set loop so it's safe across instances, not just one
+     * process). `limit` is finite and `cost > 0` by the time this is called
+     * (the service short-circuits unlimited / non-positive cost).
+     */
+    readonly consume: (tenantId: string, key: string, period: string, cost: number, limit: number) => Effect.Effect<EntitlementDecision, BillingError>;
+    /** Add `delta` to the used count, returning the new total. */
+    readonly increment: (tenantId: string, key: string, period: string, delta: number) => Effect.Effect<number, BillingError>;
+    /** All rows with un-flushed usage (`used > reportedToProvider`). */
+    readonly pending: () => Effect.Effect<ReadonlyArray<UsageRow>, BillingError>;
+    /** Mark `(tenant, key, period)` flushed up to `used`. */
+    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 { }