@voltro/plugin-billing 0.86.0 → 0.87.0

package/dist/stripeVerifiedEvent.js

@@ -0,0 +1,29 @@
+import { BillingError as e } from "./types.js";
+import { stripeCall as t } from "./stripeClient.js";
+import { stripeAccountIdentity as n } from "./stripeIdentity.js";
+import { Effect as r } from "effect";
+import { canonicalJson as i } from "@voltro/protocol";
+//#region src/stripeVerifiedEvent.ts
+var a = (a, o) => r.gen(function* () {
+	let s = yield* r.try({
+		try: () => a.webhooks.constructEvent(Buffer.from(o.rawBody), o.signatureHeader, o.secret),
+		catch: () => new e({
+			source: "stripe.webhooks.constructEvent",
+			message: "The webhook signature could not be verified.",
+			transient: !1
+		})
+	}), c = yield* t("stripe.events.retrieve", () => a.events.retrieve(s.id)), l = yield* n(a);
+	return yield* r.try({
+		try: () => {
+			if (c.id !== s.id || c.type !== s.type || c.created !== s.created || c.api_version !== s.api_version || c.livemode !== s.livemode || c.livemode !== l.livemode || (c.account ?? null) !== (s.account ?? null) || c.account !== void 0 && c.account !== null && c.account !== l.providerAccountId || i(JSON.parse(JSON.stringify(c.data))) !== i(JSON.parse(JSON.stringify(s.data)))) throw Error("Event context mismatch");
+			return c;
+		},
+		catch: () => new e({
+			source: "stripe.webhooks.account",
+			message: "The signed event does not match the configured provider account/mode.",
+			transient: !1
+		})
+	});
+});
+//#endregion
+export { a as verifyStripeBillingEvent };

package/dist/table.js

@@ -1,54 +1,77 @@
-import { id as e, integer as t, table as n, text as r, timestamp as i } from "@voltro/database";
+import { billingCustomerAccountsTable as e, billingCustomerCustodyTable as t } from "./customerStore.js";
+import { billingInvoiceHistoryPagesTable as n, billingInvoiceHistoryReferencesTable as r, billingInvoiceHistoryWalksTable as i } from "./invoiceHistoryJournal.js";
+import { BILLING_INVOICE_OBSERVATIONS_TABLE as a, billingInvoiceObservationsTable as o, billingRetainedInvoiceObservationsTable as s } from "./invoiceStore.js";
+import { billingInvoiceHistoryWorkTable as c } from "./invoiceHistoryWork.js";
+import { billingInvoiceHistoryDispatchTable as l, billingInvoiceHistoryScanAccountsTable as u } from "./invoiceHistoryProgress.js";
+import { billingUsageEventsTable as d } from "./usageEvents.js";
+import { billingCheckoutOperationsTable as f } from "./checkoutStore.js";
+import { billingCloseOperationsTable as p } from "./closeStore.js";
+import { billingDunningNoticesTable as m } from "./dunning.js";
+import { id as h, integer as g, table as _, text as v, timestamp as y } from "@voltro/database";
 //#region src/table.ts
-var a = "_voltro_billing_customers", o = "_voltro_billing_subscriptions", s = "_voltro_billing_invoices", c = "_voltro_billing_usage", l = n(a, {
-	id: e({ prefix: "bcust" }),
-	tenantId: r(),
-	provider: r(),
-	providerCustomerId: r(),
-	createdAt: i(),
-	updatedAt: i()
-}).index("byBillingCustomerTenant", ["tenantId"]).index("byBillingProviderCustomer", ["providerCustomerId"]), u = n(o, {
-	id: e({ prefix: "bsub" }),
-	tenantId: r(),
-	provider: r(),
-	providerSubscriptionId: r(),
-	plan: r(),
-	status: r(),
-	quantity: t().default(1),
-	currentPeriodStart: i().nullable(),
-	currentPeriodEnd: i().nullable(),
-	cancelAt: i().nullable(),
-	pastDueSince: i().nullable(),
-	statusEventAt: i().nullable(),
-	createdAt: i(),
-	updatedAt: i()
-}).index("byBillingSubscriptionTenant", ["tenantId"]).index("byBillingProviderSubscription", ["providerSubscriptionId"]).index("byBillingSubscriptionStatus", ["status"]), d = n(s, {
-	id: e({ prefix: "binv" }),
-	tenantId: r(),
-	provider: r(),
-	providerInvoiceId: r(),
-	amountMinor: t(),
-	currency: r(),
-	status: r(),
-	statusEventAt: i().nullable(),
-	createdAt: i()
-}).index("byBillingInvoiceTenant", ["tenantId"]).index("byBillingProviderInvoice", ["providerInvoiceId"]), f = n(c, {
-	id: e({ prefix: "buse" }),
-	tenantId: r().maxLength(191),
-	entitlementKey: r().maxLength(191),
-	period: r().maxLength(16),
-	used: t().default(0),
-	reportedToProvider: t().default(0),
-	updatedAt: i()
+var b = "_voltro_billing_customers", x = "_voltro_billing_subscriptions", S = "_voltro_billing_invoices", C = "_voltro_billing_usage", w = _(b, {
+	id: h({ prefix: "bcust" }),
+	tenantId: v(),
+	provider: v(),
+	providerCustomerId: v(),
+	createdAt: y(),
+	updatedAt: y()
+}).index("byBillingCustomerTenant", ["tenantId"]).index("byBillingProviderCustomer", ["providerCustomerId"]), T = _(x, {
+	id: h({ prefix: "bsub" }),
+	tenantId: v(),
+	provider: v(),
+	providerSubscriptionId: v(),
+	plan: v(),
+	status: v(),
+	quantity: g().default(1),
+	currentPeriodStart: y().nullable(),
+	currentPeriodEnd: y().nullable(),
+	cancelAt: y().nullable(),
+	pastDueSince: y().nullable(),
+	statusEventAt: y().nullable(),
+	createdAt: y(),
+	updatedAt: y()
+}).index("byBillingSubscriptionTenant", ["tenantId"]).index("byBillingProviderSubscription", ["providerSubscriptionId"]).index("byBillingSubscriptionStatus", ["status"]), E = _(S, {
+	id: h({ prefix: "binv" }),
+	tenantId: v(),
+	provider: v(),
+	providerInvoiceId: v(),
+	amountMinor: g(),
+	currency: v(),
+	status: v(),
+	statusEventAt: y().nullable(),
+	createdAt: y()
+}).index("byBillingInvoiceTenant", ["tenantId"]).index("byBillingProviderInvoice", ["providerInvoiceId"]), D = _(C, {
+	id: h({ prefix: "buse" }),
+	tenantId: v().maxLength(191),
+	entitlementKey: v().maxLength(191),
+	period: v().maxLength(16),
+	used: g().default(0),
+	reportedToProvider: g().default(0),
+	updatedAt: y()
 }).unique("byBillingUsageWindow", [
 	"tenantId",
 	"entitlementKey",
 	"period"
-]), p = () => [
-	l,
-	u,
+]), O = () => [
+	m,
 	d,
-	f
+	p,
+	f,
+	w,
+	e,
+	t,
+	i,
+	n,
+	r,
+	c,
+	u,
+	l,
+	T,
+	E,
+	o,
+	s,
+	D
 ];
 //#endregion
-export { a as BILLING_CUSTOMERS_TABLE, s as BILLING_INVOICES_TABLE, o as BILLING_SUBSCRIPTIONS_TABLE, c as BILLING_USAGE_TABLE, l as billingCustomersTable, d as billingInvoicesTable, u as billingSubscriptionsTable, p as billingTables, f as billingUsageTable };
+export { b as BILLING_CUSTOMERS_TABLE, S as BILLING_INVOICES_TABLE, a as BILLING_INVOICE_OBSERVATIONS_TABLE, x as BILLING_SUBSCRIPTIONS_TABLE, C as BILLING_USAGE_TABLE, w as billingCustomersTable, o as billingInvoiceObservationsTable, E as billingInvoicesTable, s as billingRetainedInvoiceObservationsTable, T as billingSubscriptionsTable, O as billingTables, D as billingUsageTable };

package/dist/types.d.ts

@@ -30,7 +30,7 @@ declare const BillingError_base: Schema.Class<BillingError, Schema.TaggedStruct<
 }>, YieldableError>;
 
 /**
- * The normalized event union a `BillingProvider.normalizeEvent` produces
+ * The tenant-resolved event union dispatched after `BillingService.applyEvent` accepts an event
  * 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.
@@ -86,17 +86,29 @@ export declare type BillingEvent = {
 /** The event tag union — handy for `onEvent` keys. */
 export declare type BillingEventTag = BillingEvent['_tag'];
 
-/**
- * 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 type BillingInvoiceTrigger = BillingInvoiceTriggerFields & ({
+    readonly _tag: 'invoicePaid';
+} | {
+    readonly _tag: 'invoicePaymentFailed';
+});
+
+/** Verified provider invoice trigger. Tenant metadata is never ownership evidence. */
+declare interface BillingInvoiceTriggerFields {
+    readonly providerCustomerId: string;
+    readonly providerInvoiceId: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly occurredAt: Date | null;
+}
+
 export declare interface BillingProvider {
+    /** Required by account-qualified custody consumers; absence is unsupported, not fallback authority. */
+    readonly fetchAccountIdentity?: () => Effect.Effect<ProviderAccountIdentity, BillingError>;
+    /** Must reject a different account/mode before reading customer data. A 404 is not positive deletion evidence. */
+    readonly fetchCustomerSnapshot?: (input: {
+        readonly account: ProviderAccountIdentity;
+        readonly providerCustomerId: string;
+    }) => Effect.Effect<ProviderCustomerSnapshot, BillingError>;
     readonly name: string;
     /** Whether the provider supports server-pushed metered usage. Stripe
      *  does (subscription-item usage records); a flat-plan provider may not.
@@ -107,9 +119,13 @@ export declare interface BillingProvider {
      *  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>;
+    readonly createCheckoutSession: (input: CheckoutInput) => Effect.Effect<CheckoutSessionReceipt, BillingError>;
+    /** Read positive evidence for one exact persisted checkout intent. */
+    readonly findCheckoutSession: (input: {
+        readonly tenantId: string;
+        readonly providerCustomerId?: string;
+        readonly operationId: string;
+    }) => Effect.Effect<CheckoutSessionLookup, BillingError>;
     readonly createPortalSession: (input: PortalInput) => Effect.Effect<{
         url: string;
     }, BillingError>;
@@ -141,6 +157,10 @@ export declare interface BillingProvider {
      * matters — the subscription's status right now does. Returns null when the
      * provider does not know the id.
      */
+    /** Direct customer-qualified observation, including terminal subscriptions.
+     * Null is absence, never proof of cancellation. Required for retired-customer
+     * reconciliation and for subscriptions absent from the live listing. */
+    readonly fetchSubscriptionSnapshot?: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionSnapshot | null, BillingError>;
     readonly fetchSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState | null, BillingError>;
     /**
      * Every live (not yet ended) subscription at the provider, optionally for
@@ -150,12 +170,19 @@ export declare interface BillingProvider {
     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. */
+    /** Quote the provider-clock settlement deadline after final usage dispatch.
+     * Persist it before requesting account-close cancellation. */
+    readonly prepareSubscriptionClose: (providerSubscriptionId: string) => Effect.Effect<{
+        readonly cancelAt: Date;
+    }, BillingError>;
     readonly cancelSubscription: (input: {
         readonly providerSubscriptionId: string;
-        readonly mode: CancelMode;
-    }) => Effect.Effect<ProviderSubscriptionState, BillingError>;
+    } & ({
+        readonly mode: 'periodEnd';
+    } | {
+        readonly mode: 'close';
+        readonly closeOperation: SubscriptionCloseOperation;
+    })) => Effect.Effect<ProviderSubscriptionState, BillingError>;
     /** Undo a period-end cancellation that has not taken effect yet. */
     readonly resumeSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState, BillingError>;
     /**
@@ -172,6 +199,7 @@ export declare interface BillingProvider {
      *  can be paid. Returns how many were expired. */
     readonly expireOpenCheckouts: (input: {
         readonly providerCustomerId: string;
+        readonly exceptOperationId?: string;
     }) => Effect.Effect<number, BillingError>;
     /** Add prices the subscription is missing (metered items), without
      *  proration. Prices already present are left alone. */
@@ -185,12 +213,22 @@ export declare interface BillingProvider {
      * the app keeps its own. Optional: a provider may model no customer email.
      */
     readonly customerEmail?: (providerCustomerId: string) => Effect.Effect<string | null, BillingError>;
-    /** The provider's invoice history. We mirror it for listing but never
-     *  render an invoice ourselves — `hostedUrl` / `pdfUrl` are theirs. */
+    /** Bounded recent invoice preview, not complete history. Provider-hosted
+     * links remain theirs; use listInvoiceHistory for explicit cursor traversal. */
     readonly listInvoices: (input: {
         readonly providerCustomerId: string;
         readonly limit?: number;
     }) => Effect.Effect<ReadonlyArray<InvoiceRecord>, BillingError>;
+    /** Explicit bounded history pages, including draft and terminal statuses.
+     * Cursor exhaustion describes this traversal, not a stable global snapshot.
+     * Unsupported adapters must fail; the latest-preview list is no fallback. */
+    readonly listInvoiceHistory?: (input: ProviderInvoiceHistoryInput) => Effect.Effect<ProviderInvoiceHistoryPage, BillingError>;
+    /** Read one finalized invoice with every line, after confirming its customer.
+     * Absence means this provider cannot supply detailed invoice evidence. */
+    readonly fetchInvoiceSnapshot?: (input: {
+        readonly providerCustomerId: string;
+        readonly providerInvoiceId: string;
+    }) => Effect.Effect<ProviderInvoiceSnapshot, 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
@@ -201,10 +239,10 @@ export declare interface BillingProvider {
         readonly signatureHeader: string;
         readonly secret: string;
     }) => Effect.Effect<unknown, BillingError>;
-    /** Map a verified, decoded webhook payload to a `BillingEvent`, or
+    /** Map a verified, decoded webhook payload to a `BillingProviderEvent`, 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>;
+    readonly normalizeEvent: (raw: unknown) => Effect.Effect<BillingProviderEvent | 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
@@ -221,9 +259,17 @@ export declare interface BillingProvider {
      * 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>;
+    readonly listUndeliveredEvents?: (input: {
+        readonly cursor: string | null;
+        readonly limit: number;
+    }) => Effect.Effect<UndeliveredEventPage, BillingError>;
 }
 
+/** Invoice ownership is resolved from native customer links before dispatch. */
+export declare type BillingProviderEvent = Exclude<BillingEvent, {
+    readonly _tag: 'invoicePaid' | 'invoicePaymentFailed';
+}> | BillingInvoiceTrigger;
+
 /** The billing service Tag — `const billing = yield* BillingService`. */
 export declare class BillingService extends BillingService_base {
 }
@@ -266,6 +312,8 @@ export declare interface BillingServiceShape {
     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>;
+    /** Atomically retain an occurrence receipt and increment its original UTC month. */
+    readonly reportUsageEvent: (event: MeteredUsageEvent) => 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
@@ -275,8 +323,27 @@ export declare interface BillingServiceShape {
         readonly plan?: PlanId;
         readonly quantity?: number;
     }) => Effect.Effect<SubscriptionChange, BillingError>;
-    /** The provider's invoice history for this tenant. */
+    /** Bounded recent provider invoice preview for this tenant, not history coverage. */
     readonly invoices: (tenantId: string) => Effect.Effect<ReadonlyArray<InvoiceRecord>, BillingError>;
+    /** Read history for an exact current or retained customer owned by the tenant.
+     * Does not create custody or persist observations. The caller authorizes access. */
+    readonly invoiceHistory: (tenantId: string, providerCustomerId: string, options?: {
+        readonly cursor?: ProviderInvoiceHistoryCursor;
+        readonly limit?: number;
+    }) => Effect.Effect<ProviderInvoiceHistoryPage, BillingError>;
+    /** Fresh detailed provider evidence for this tenant's current linked customer.
+     * This read neither grants entitlements nor replaces native reconciliation. */
+    readonly invoiceSnapshot: (tenantId: string, providerInvoiceId: string) => Effect.Effect<ProviderInvoiceSnapshot, BillingError>;
+    /** Persist and read back a complete owned observation. A lost revision race
+     * repeats the provider read; event payloads never replace provider evidence. */
+    readonly reconcileInvoice: (tenantId: string, providerInvoiceId: string, expectedCustomerId?: string) => Effect.Effect<InvoiceObservation, BillingError>;
+    /** One bounded durable account/customer pass. Counts are work observations,
+     * not global, payment or historical financial completion. */
+    readonly reconcileInvoiceHistory: () => Effect.Effect<InvoiceHistoryPassResult, BillingError>;
+    /** Process one retained owned history reference with fresh provider/native
+     * reads and a fenced durable result. Open/draft/error work stays pending;
+     * an observed result is not settlement or historical entitlement coverage. */
+    readonly processInvoiceHistoryReference: (tenantId: string, providerCustomerId: string, referenceId: string) => Effect.Effect<InvoiceHistoryReferenceResult, BillingError>;
     /** Mint a provider-hosted checkout URL for `plan`. */
     readonly startCheckout: (input: {
         readonly tenantId: string;
@@ -285,6 +352,9 @@ export declare interface BillingServiceShape {
         readonly cancelUrl: string;
         /** Seats to buy up front. Omit for 1. */
         readonly quantity?: number;
+        /** Server-call authority check repeated after waits, before provider work.
+         * Native RPC routes supply their current declared-guard check. */
+        readonly authorize?: () => Effect.Effect<void, BillingError>;
     }) => Effect.Effect<{
         url: string;
     }, BillingError>;
@@ -334,8 +404,8 @@ export declare interface BillingServiceShape {
      * 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>;
+    /** Apply a verified provider trigger and return its native tenant-resolved event. */
+    readonly applyEvent: (event: BillingProviderEvent) => Effect.Effect<BillingEvent, BillingError>;
     /**
      * Change the tenant's plan mid-cycle. Computes a TIME-BASED prorated
      * settlement on the amount difference for the unused remainder of the
@@ -373,6 +443,12 @@ export declare type CancelMode =
 
 export declare interface CheckoutInput {
     readonly tenantId: string;
+    /** Identity of one logical checkout request. Providers that support request
+     * idempotency must forward it unchanged across transport retries. The
+     * caller owns persistence and must not reuse it for different parameters. */
+    readonly idempotencyKey?: string;
+    /** Fixed deadline of a persisted intent; providers enforce it on creation. */
+    readonly expiresAt?: Date;
     /** Provider price id to subscribe to. */
     readonly priceId: string;
     /** Usage-based prices added next to `priceId` (no quantity). */
@@ -393,13 +469,50 @@ export declare interface CheckoutInput {
     readonly trialDays?: number;
 }
 
+export declare interface CheckoutSessionLookup {
+    readonly receipt: CheckoutSessionReceipt | null;
+    /** Provider-clock evidence, never the application host's clock. */
+    readonly observedAt: Date | null;
+}
+
+/**
+ * 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 CheckoutSessionReceipt {
+    readonly id: string;
+    readonly operationId: string | null;
+    readonly tenantId: string | null;
+    readonly providerCustomerId: string | null;
+    readonly providerSubscriptionId: string | null;
+    readonly status: 'open' | 'complete' | 'expired';
+    readonly url: string | null;
+    readonly expiresAt: Date;
+}
+
 /** What `closeAccount` did at the provider. */
 export declare interface CloseAccountResult {
     readonly tenantId: string;
-    /** Provider subscriptions ended (immediately, with a final invoice). */
+    /** Provider subscriptions positively confirmed canceled. A scheduled close remains pending. */
     readonly canceled: ReadonlyArray<string>;
 }
 
+declare interface CustomerBinding extends CustomerScope {
+    readonly tenantId: string;
+    readonly providerCustomerId: string;
+}
+
+declare interface CustomerScope {
+    readonly provider: string;
+    readonly account: ProviderAccountIdentity;
+}
+
 /** The free/fallback plan id every app implicitly has. */
 export declare const DEFAULT_PLAN: PlanId;
 
@@ -466,6 +579,59 @@ export declare interface EntitlementStatus {
     readonly lockout: LockoutMode;
 }
 
+/** Immutable native ownership of one provider invoice, not payment authority. */
+export declare interface InvoiceBinding extends ProviderAccountIdentity {
+    readonly tenantId: string;
+    readonly provider: string;
+    readonly providerCustomerId: string;
+    readonly providerInvoiceId: string;
+}
+
+declare interface InvoiceHistoryJournalOwner extends CustomerBinding {
+    readonly custodyId: string;
+}
+
+declare interface InvoiceHistoryPassResult {
+    readonly kind: 'idle' | 'advanced' | 'contended';
+    readonly customerCustodyId: string | null;
+    readonly admittedPages: number;
+    readonly observed: number;
+    readonly deferred: number;
+    readonly busy: number;
+    readonly unconfirmed: number;
+}
+
+declare interface InvoiceHistoryReferenceResult {
+    readonly kind: 'observed' | 'deferred' | 'busy';
+    readonly work: InvoiceHistoryWork;
+}
+
+declare interface InvoiceHistoryWork extends InvoiceHistoryJournalOwner {
+    readonly id: string;
+    readonly walkId: string;
+    readonly referenceId: string;
+    readonly providerInvoiceId: string;
+    readonly revision: number;
+    /** Logical attempts and acquired execution identities survive restarts. */
+    readonly attempt: number;
+    readonly executions: number;
+    readonly state: 'queued' | 'working' | 'retry' | 'deferred' | 'observed';
+    readonly activeClaimId: string | null;
+    readonly nextAttemptAt: Date;
+    readonly lastOutcome: 'unconfirmed' | 'open' | 'observed';
+    /** An observed native version, never a payment or entitlement receipt. */
+    readonly observationId: string | null;
+    readonly observationRevision: number | null;
+    readonly updatedAt: Date;
+}
+
+export declare interface InvoiceObservation extends InvoiceBinding {
+    readonly id: string;
+    readonly identityKey: string;
+    readonly revision: number;
+    readonly snapshot: ProviderInvoiceSnapshot;
+}
+
 export declare interface InvoiceRecord {
     readonly providerInvoiceId: string;
     readonly amountMinor: number;
@@ -488,6 +654,15 @@ export declare interface InvoiceRecord {
  */
 export declare type LockoutMode = 'hard' | 'soft';
 
+export declare interface MeteredUsageEvent {
+    readonly tenantId: string;
+    readonly entitlementKey: string;
+    readonly quantity: number;
+    readonly occurredAt: Date;
+    /** Stable tenant-scoped occurrence identity, reused unchanged on every retry. */
+    readonly idempotencyKey: string;
+}
+
 /** A monetary amount: integer minor units + ISO-4217 currency. */
 export declare interface Money {
     /** Integer minor units (cents). Never a float. */
@@ -529,6 +704,88 @@ export declare interface PortalInput {
     readonly returnUrl: string;
 }
 
+/** Provider-observed account/mode, not a configured key prefix or tenant hint. */
+export declare interface ProviderAccountIdentity {
+    readonly providerAccountId: string;
+    readonly livemode: boolean;
+}
+
+/** A positive customer response in an explicitly expected provider namespace.
+ * observedAt is local observation time, never provider-clock settlement evidence. */
+export declare interface ProviderCustomerSnapshot {
+    readonly account: ProviderAccountIdentity;
+    readonly providerCustomerId: string;
+    readonly deleted: boolean;
+    readonly observedAt: Date;
+}
+
+/** Explicit provider namespace/customer binding; not a bearer authorization. */
+export declare interface ProviderInvoiceHistoryCursor extends ProviderAccountIdentity {
+    readonly providerCustomerId: string;
+    readonly afterInvoiceId: string;
+}
+
+/** One history reference, not a complete invoice observation or payment proof. */
+export declare interface ProviderInvoiceHistoryEntry extends InvoiceRecord {
+    readonly providerCustomerId: string;
+    readonly livemode: boolean;
+    readonly status: 'draft' | 'open' | 'paid' | 'uncollectible' | 'void';
+    readonly createdAt: Date;
+}
+
+export declare interface ProviderInvoiceHistoryInput {
+    readonly account: ProviderAccountIdentity;
+    readonly providerCustomerId: string;
+    readonly cursor?: ProviderInvoiceHistoryCursor;
+    /** 1..100; defaults to 100. Invalid values fail rather than clamp. */
+    readonly limit?: number;
+}
+
+export declare interface ProviderInvoiceHistoryPage {
+    readonly account: ProviderAccountIdentity;
+    readonly providerCustomerId: string;
+    readonly invoices: ReadonlyArray<ProviderInvoiceHistoryEntry>;
+    readonly nextCursor: ProviderInvoiceHistoryCursor | null;
+    /** Local observation time, not provider-clock or financial coverage evidence. */
+    readonly observedAt: Date;
+}
+
+export declare interface ProviderInvoiceLineSnapshot {
+    readonly providerLineId: string;
+    readonly providerSubscriptionId: string | null;
+    readonly providerSubscriptionItemId: string | null;
+    readonly providerPriceId: string | null;
+    readonly amountMinor: number;
+    readonly currency: string;
+    /** Exact provider decimal; absent precision must never be replaced by a truncated integer. */
+    readonly quantityDecimal: string | null;
+    /** Provider period bounds are inclusive; they are not paid-through authority. */
+    readonly periodStart: Date;
+    readonly periodEnd: Date;
+    /** Null means the provider did not identify the line's origin. */
+    readonly proration: boolean | null;
+}
+
+/** A complete provider observation, not an entitlement or a payment receipt. */
+export declare interface ProviderInvoiceSnapshot {
+    readonly providerInvoiceId: string;
+    readonly providerCustomerId: string;
+    readonly providerSubscriptionId: string | null;
+    readonly providerRevisionId: string | null;
+    readonly status: 'open' | 'paid' | 'uncollectible' | 'void';
+    readonly livemode: boolean;
+    readonly currency: string;
+    readonly amountDueMinor: number;
+    readonly amountPaidMinor: number;
+    readonly amountRemainingMinor: number;
+    readonly finalizedAt: Date;
+    readonly paidAt: Date | null;
+    /** Local read completion time, never a provider clock or entitlement deadline. */
+    readonly observedAt: Date;
+    /** All pages. A bounded or failed read must fail instead of returning a prefix. */
+    readonly lines: ReadonlyArray<ProviderInvoiceLineSnapshot>;
+}
+
 /** What `reconcileFromProvider` found and corrected. */
 export declare interface ProviderReconcileResult {
     /** Subscriptions compared (provider-listed plus local rows it did not list). */
@@ -643,6 +900,12 @@ export declare interface SubscriptionChangeResult {
     readonly currentPeriodEnd: Date | null;
 }
 
+export declare interface SubscriptionCloseOperation {
+    readonly id: string;
+    /** Provider-clock deadline captured after final usage dispatch. */
+    readonly cancelAt: Date;
+}
+
 /**
  * Raised when dunning has locked a tenant out — the grace period after a
  * provider-confirmed past-due has expired. Distinct from
@@ -692,10 +955,18 @@ export declare interface SubscriptionUpdateInput {
 /** An event the provider failed to deliver, reduced to what a catch-up needs. */
 export declare interface UndeliveredEvent {
     readonly id: string;
+    readonly event: BillingProviderEvent | null;
+    /** A recognized provider event could not be normalized; retry/report it, never fall back to discovery. */
+    readonly rejected?: true;
     readonly providerCustomerId: string | null;
     readonly createdAt: Date | null;
 }
 
+export declare interface UndeliveredEventPage {
+    readonly events: ReadonlyArray<UndeliveredEvent>;
+    readonly nextCursor: string | null;
+}
+
 export declare interface UsagePush {
     readonly tenantId: string;
     readonly entitlementKey: string;