@voltro/plugin-billing 0.85.0 → 0.87.0

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;

package/dist/usageEvents.js

@@ -0,0 +1,65 @@
+import { BillingError as e } from "./types.js";
+import { Effect as t } from "effect";
+import { and as n, eq as r, id as i, integer as a, table as o, text as s, timestamp as c } from "@voltro/database";
+//#region src/usageEvents.ts
+var l = "_voltro_billing_usage_events", u = o(l, {
+	id: i({ prefix: "busage" }),
+	tenantId: s().maxLength(191),
+	idempotencyKey: s().maxLength(191),
+	entitlementKey: s().maxLength(100),
+	period: s().maxLength(7),
+	quantity: a(),
+	occurredAt: c(),
+	createdAt: c()
+}).unique("byBillingUsageEvent", ["tenantId", "idempotencyKey"]).index("byBillingUsageEventPeriod", ["tenantId", "period"]), d = () => new e({
+	source: "usageEvent",
+	message: "Usage event identity or immutable payload requires reconciliation.",
+	transient: !1
+}), f = (e) => {
+	if (e.tenantId.length === 0 || e.tenantId.length > 191 || e.idempotencyKey.trim().length === 0 || e.idempotencyKey.length > 191 || e.entitlementKey.length === 0 || e.entitlementKey.length > 100 || !Number.isSafeInteger(e.quantity) || e.quantity <= 0 || !(e.occurredAt instanceof Date) || !Number.isFinite(e.occurredAt.getTime())) throw d();
+	let t = new Date(e.occurredAt);
+	if (!/^[0-9]{4}-(0[1-9]|1[0-2])$/.test(e.period) || e.period !== `${t.getUTCFullYear()}-${String(t.getUTCMonth() + 1).padStart(2, "0")}`) throw d();
+	return {
+		tenantId: e.tenantId,
+		idempotencyKey: e.idempotencyKey,
+		entitlementKey: e.entitlementKey,
+		quantity: e.quantity,
+		period: e.period,
+		occurredAt: t
+	};
+}, p = (e, t) => e.tenantId === t.tenantId && e.idempotencyKey === t.idempotencyKey && e.entitlementKey === t.entitlementKey && e.period === t.period && e.quantity === t.quantity && new Date(e.occurredAt).getTime() === t.occurredAt.getTime(), m = (i, a, o) => t.tryPromise({
+	try: async () => {
+		let e = f(a);
+		await i.transactional(async (t) => {
+			let i = {
+				table: l,
+				predicate: n(r("tenantId", e.tenantId), r("idempotencyKey", e.idempotencyKey)),
+				order: [],
+				take: 2,
+				skip: void 0,
+				projection: void 0
+			}, a = await t.query(i);
+			if (a.length > 1) throw d();
+			if (a[0]) {
+				if (!p(a[0], e)) throw d();
+				return;
+			}
+			let s = "busage_" + globalThis.crypto.randomUUID();
+			await t.insertIgnore(l, {
+				...e,
+				id: s,
+				createdAt: /* @__PURE__ */ new Date()
+			}, { conflictColumns: ["tenantId", "idempotencyKey"] });
+			let c = await t.query(i);
+			if (c.length !== 1 || !c[0] || !p(c[0], e)) throw d();
+			c[0].id === s && await o(t, e);
+		});
+	},
+	catch: (t) => t instanceof e ? t : new e({
+		source: "usageEvent",
+		message: "Usage event could not be durably recorded. Retry the same event identity.",
+		transient: !0
+	})
+});
+//#endregion
+export { l as BILLING_USAGE_EVENTS_TABLE, u as billingUsageEventsTable, m as recordDataStoreUsageEvent };

package/dist/webhook.js

@@ -0,0 +1,38 @@
+import { makeBillingEventDelivery as e } from "./eventDelivery.js";
+import { Effect as t, Schema as n } from "effect";
+import { createLogger as r } from "@voltro/logger";
+import { IdempotencyCache as i, defineIncomingWebhook as a, mountIncomingWebhook as o } from "@voltro/plugin-webhooks";
+import { stripeProvider as s } from "@voltro/plugin-webhooks/providers";
+//#region src/webhook.ts
+var c = r({ scope: "@voltro/plugin-billing" }), l = "billing", u = "/billing/webhook", d = 3e5, f = (r) => {
+	let i = e(r);
+	return a({
+		id: l,
+		path: u,
+		provider: s(),
+		payload: n.Unknown,
+		handler: async (e) => {
+			let n = r.provider.verifyWebhook !== void 0 && r.webhookSecret !== null && r.webhookSecret !== void 0 ? await t.runPromise(r.provider.verifyWebhook({
+				rawBody: e.rawBody,
+				signatureHeader: e.headers["stripe-signature"] ?? "",
+				secret: r.webhookSecret ?? ""
+			})) : e.body, a = await t.runPromise(r.provider.normalizeEvent(n)), o = r.provider.eventContext?.(n) ?? {
+				providerCustomerId: null,
+				createdAt: null
+			};
+			(a !== null || o.providerCustomerId !== null) && (o.createdAt !== null && Date.now() - o.createdAt.getTime() > 3e5 && r.onLateDelivery?.(), await t.runPromise(i({
+				id: e.idempotencyKey,
+				event: a,
+				...o
+			})));
+		}
+	});
+}, p = (e) => o(f(e), {
+	resolveSecret: () => Promise.resolve(e.webhookSecret),
+	idempotencyCache: e.idempotencyCache ?? new i(),
+	log: (e) => {
+		e.status >= 400 && c.warn("billing webhook rejected", { ...e });
+	}
+});
+//#endregion
+export { l as BILLING_WEBHOOK_ID, u as BILLING_WEBHOOK_PATH, d as REDELIVERY_AGE_MS, f as billingWebhookDescriptor, p as mountBillingWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-billing",
-  "version": "0.85.0",
+  "version": "0.87.0",
   "description": "Billing on the official Stripe SDK — subscriptions, plans, entitlements and usage metering. Proration, failed-payment retries, tax, promotion codes, trials and the checkout seat stepper are Stripe's own; the plugin adds the entitlement engine, the enforce interceptor, typed BillingError/EntitlementExceeded, the /billing/webhook mount with Stripe's signature verification, the BillingService Tag, requireEntitlement(), and a browser-safe useStartCheckout() hook. Money is integer minor units end-to-end.",
   "keywords": [
     "voltro",
@@ -38,6 +38,11 @@
       "import": "./dist/rpc.js",
       "default": "./dist/rpc.js"
     },
+    "./economy": {
+      "types": "./dist/economy.d.ts",
+      "import": "./dist/economy.js",
+      "default": "./dist/economy.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
@@ -48,20 +53,25 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.85.0",
-    "@voltro/env": "0.85.0",
-    "@voltro/logger": "0.85.0",
-    "@voltro/plugin-webhooks": "0.85.0",
-    "@voltro/protocol": "0.85.0"
+    "@voltro/database": "0.87.0",
+    "@voltro/env": "0.87.0",
+    "@voltro/logger": "0.87.0",
+    "@voltro/plugin-webhooks": "0.87.0",
+    "@voltro/protocol": "0.87.0",
+    "@voltro/runtime": "0.87.0"
   },
   "peerDependencies": {
     "effect": "4.0.1",
     "react": "^19.0.0",
-    "stripe": "^22.6.1"
+    "stripe": "^22.6.1",
+    "@voltro/plugin-economy": "0.87.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "@voltro/plugin-economy": {
+      "optional": true
     }
   },
   "publishConfig": {