@voltro/plugin-billing 0.33.0 → 0.34.0

package/dist/rpc.d.ts

@@ -47,6 +47,24 @@ export declare const changeSeatsDescriptor: ActionProcedureDescriptor<"billing.c
     currency: typeof Schema.String;
 }>, typeof BillingError>;
 
+/**
+ * "Is this tenant entitled right now?" — the dunning-aware answer a billing
+ * banner needs. `entitled: false` means the grace period expired; `inGrace`
+ * with a `graceEndsAt` is the "your payment failed, you have until …" state.
+ * Timestamps are ISO strings (the descriptor's Schema is String, so a Date
+ * would fail encode at the boundary).
+ */
+export declare const entitlementStatusDescriptor: QueryProcedureDescriptor<"billing.entitlementStatus", Schema.Struct<{}>, Schema.Struct<{
+    plan: typeof Schema.String;
+    billedPlan: typeof Schema.String;
+    status: typeof Schema.String;
+    entitled: typeof Schema.Boolean;
+    inGrace: typeof Schema.Boolean;
+    graceEndsAt: Schema.NullOr<typeof Schema.String>;
+    lockedSince: Schema.NullOr<typeof Schema.String>;
+    lockout: typeof Schema.String;
+}>, typeof BillingError>;
+
 /** The provider's invoice history. `hostedUrl` / `pdfUrl` are the provider's
  *  own pages — we never render an invoice ourselves. */
 export declare const invoicesDescriptor: QueryProcedureDescriptor<"billing.invoices", Schema.Struct<{}>, Schema.Struct<{

package/dist/rpc.js

@@ -28,7 +28,21 @@ var i = n({
 		cancelAt: t.NullOr(t.String)
 	})) }),
 	error: e
-}), s = n({
+}), s = r({
+	name: "billing.entitlementStatus",
+	input: t.Struct({}),
+	output: t.Struct({
+		plan: t.String,
+		billedPlan: t.String,
+		status: t.String,
+		entitled: t.Boolean,
+		inGrace: t.Boolean,
+		graceEndsAt: t.NullOr(t.String),
+		lockedSince: t.NullOr(t.String),
+		lockout: t.String
+	}),
+	error: e
+}), c = n({
 	name: "billing.reportUsage",
 	input: t.Struct({
 		key: t.String,
@@ -36,20 +50,20 @@ var i = n({
 	}),
 	output: t.Struct({ ok: t.Boolean }),
 	error: e
-}), c = t.Struct({
+}), l = t.Struct({
 	plan: t.String,
 	quantity: t.Number,
 	prorationMinor: t.Number,
 	currency: t.String
-}), l = n({
+}), u = n({
 	name: "billing.previewChange",
 	input: t.Struct({
 		plan: t.optional(t.String),
 		quantity: t.optional(t.Number)
 	}),
-	output: c,
+	output: l,
 	error: e
-}), u = r({
+}), d = r({
 	name: "billing.invoices",
 	input: t.Struct({}),
 	output: t.Struct({ invoices: t.Array(t.Struct({
@@ -62,17 +76,17 @@ var i = n({
 		pdfUrl: t.NullOr(t.String)
 	})) }),
 	error: e
-}), d = n({
+}), f = n({
 	name: "billing.changePlan",
 	input: t.Struct({ plan: t.String }),
-	output: c,
+	output: l,
 	error: e
-}), f = n({
+}), p = n({
 	name: "billing.changeSeats",
 	input: t.Struct({ quantity: t.Number }),
-	output: c,
+	output: l,
 	error: e
-}), p = [
+}), m = [
 	{
 		tag: "billing.startCheckout",
 		kind: "action",
@@ -97,6 +111,14 @@ var i = n({
 			name: "subscriptionDescriptor"
 		}
 	},
+	{
+		tag: "billing.entitlementStatus",
+		kind: "query",
+		import: {
+			module: "@voltro/plugin-billing/rpc",
+			name: "entitlementStatusDescriptor"
+		}
+	},
 	{
 		tag: "billing.reportUsage",
 		kind: "action",
@@ -139,4 +161,4 @@ var i = n({
 	}
 ];
 //#endregion
-export { p as billingRpcClientImports, d as changePlanDescriptor, f as changeSeatsDescriptor, u as invoicesDescriptor, a as portalUrlDescriptor, l as previewChangeDescriptor, s as reportUsageDescriptor, i as startCheckoutDescriptor, o as subscriptionDescriptor };
+export { m as billingRpcClientImports, f as changePlanDescriptor, p as changeSeatsDescriptor, s as entitlementStatusDescriptor, d as invoicesDescriptor, a as portalUrlDescriptor, u as previewChangeDescriptor, c as reportUsageDescriptor, i as startCheckoutDescriptor, o as subscriptionDescriptor };

package/dist/types.d.ts

@@ -39,26 +39,33 @@ export declare type BillingEvent = {
     readonly currentPeriodStart?: Date | null;
     readonly currentPeriodEnd: Date | null;
     readonly cancelAt: Date | null;
+    /** When the PROVIDER emitted this — the out-of-order guard. See
+     *  `occurredAt` on the union below. */
+    readonly occurredAt: Date | null;
 } | {
     readonly _tag: 'subscriptionCanceled';
     readonly tenantId: string;
     readonly providerSubscriptionId: string;
+    readonly occurredAt: Date | null;
 } | {
     readonly _tag: 'invoicePaid';
     readonly tenantId: string;
     readonly providerInvoiceId: string;
     readonly amountMinor: number;
     readonly currency: string;
+    readonly occurredAt: Date | null;
 } | {
     readonly _tag: 'invoicePaymentFailed';
     readonly tenantId: string;
     readonly providerInvoiceId: string;
     readonly amountMinor: number;
     readonly currency: string;
+    readonly occurredAt: Date | null;
 } | {
     readonly _tag: 'customerLinked';
     readonly tenantId: string;
     readonly providerCustomerId: string;
+    readonly occurredAt: Date | null;
 };
 
 /** The event tag union — handy for `onEvent` keys. */
@@ -105,6 +112,23 @@ export declare interface BillingProvider {
      * is a support ticket.
      */
     readonly previewSubscriptionChange: (input: SubscriptionUpdateInput) => Effect.Effect<SubscriptionChangeResult, BillingError>;
+    /**
+     * The provider's CURRENT view of a subscription — a direct read, not an
+     * event body.
+     *
+     * This is the method dunning refuses to lock a customer out without. An
+     * `invoice.payment_failed` can arrive after the retry that succeeded, a
+     * redelivery can arrive days late, and neither carries the state that
+     * matters — the subscription's status right now does. Returns null when the
+     * provider does not know the id.
+     */
+    readonly fetchSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState | null, BillingError>;
+    /**
+     * The billing contact the PROVIDER has on file, when it has one. Used as the
+     * dunning recipient of last resort — `dunning.resolveRecipient` wins when
+     * 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. */
     readonly listInvoices: (input: {
@@ -138,6 +162,31 @@ export declare interface BillingServiceShape {
     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>;
+    /**
+     * "Is this tenant entitled right now?" — the one truthful answer, dunning
+     * state included. A PURE read of the local row (no provider call, no write),
+     * so it is safe on a hot path: the grace clock is a column and the lockout
+     * is derived from it, never a flag some job had to remember to set.
+     */
+    readonly entitlementStatus: (tenantId: string) => Effect.Effect<EntitlementStatus, BillingError>;
+    /**
+     * Re-derive dunning state for a tenant FROM THE PROVIDER, then fire whatever
+     * notification steps are now due (each at most once per episode).
+     *
+     * Runs automatically after every subscription/invoice event, which is what
+     * makes the provider's own retry cadence the schedule. Call it directly only
+     * to force a re-check (e.g. from a support tool). It is idempotent, it never
+     * charges anything, and it never asks the provider to retry.
+     */
+    readonly reconcileDunning: (tenantId: string) => Effect.Effect<EntitlementStatus, BillingError>;
+    /**
+     * Reconcile every past-due tenant. Optional — the event path already covers
+     * the normal case; a sweep exists so a step configured for a moment the
+     * provider happens not to emit an event (and a reconcile missed during a
+     * provider outage) still lands. Wire it from your own `*.cron.tsx` if you
+     * want that; nothing schedules it for you. Returns the number reconciled.
+     */
+    readonly dunningSweep: () => Effect.Effect<number, 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. */
@@ -251,6 +300,31 @@ declare const EntitlementExceeded_base: Schema.TaggedErrorClass<EntitlementExcee
 /** An entitlement limit: a finite quota or the unbounded `'unlimited'`. */
 export declare type EntitlementLimit = number | 'unlimited';
 
+/** The truthful "is this tenant entitled right now" answer. */
+export declare interface EntitlementStatus {
+    readonly tenantId: string;
+    /** The plan whose LIMITS apply right now — `'free'` under a hard lockout. */
+    readonly plan: PlanId;
+    /** The plan the tenant is subscribed to, lockout or not. */
+    readonly billedPlan: PlanId;
+    readonly status: SubscriptionStatus | 'none';
+    /**
+     * False ONLY when dunning has locked this tenant out. A canceled
+     * subscription is not a lockout — it is simply the free tier, and reporting
+     * it as "not entitled" would conflate "never paid" with "stopped paying".
+     */
+    readonly entitled: boolean;
+    /** Past due, but still inside the grace window. */
+    readonly inGrace: boolean;
+    /** When grace runs out; null when the tenant is not past due — or when the
+     *  provider has not confirmed the past-due yet, in which case the tenant is
+     *  in grace with no expiry rather than locked. */
+    readonly graceEndsAt: Date | null;
+    /** Non-null iff locked out — the instant grace expired. */
+    readonly lockedSince: Date | null;
+    readonly lockout: LockoutMode;
+}
+
 export declare interface InvoiceRecord {
     readonly providerInvoiceId: string;
     readonly amountMinor: number;
@@ -262,6 +336,17 @@ export declare interface InvoiceRecord {
     readonly pdfUrl: string | null;
 }
 
+/**
+ * What "locked" means once the grace period is over.
+ *
+ *   - `'hard'` — entitlement limits fall to the `'free'` plan's. The app needs
+ *     no new code: every existing `requireEntitlement` / `enforce` check
+ *     starts answering with the free tier's numbers.
+ *   - `'soft'` — limits stay on the paid plan; only `entitlementStatus()`
+ *     reports the lockout, so the app decides what to withhold.
+ */
+export declare type LockoutMode = 'hard' | 'soft';
+
 /** A monetary amount: integer minor units + ISO-4217 currency. */
 export declare interface Money {
     /** Integer minor units (cents). Never a float. */
@@ -296,6 +381,19 @@ export declare interface PortalInput {
     readonly returnUrl: string;
 }
 
+/** The provider's CURRENT view of a subscription — read directly, not from an
+ *  event body. `reconcileDunning` asks for this before it will lock anyone
+ *  out. */
+export declare interface ProviderSubscriptionState {
+    readonly status: SubscriptionStatus;
+    /** Null when the provider cannot map the price to one of our plans. */
+    readonly plan: PlanId | null;
+    readonly quantity: number;
+    readonly currentPeriodStart: Date | null;
+    readonly currentPeriodEnd: Date | null;
+    readonly cancelAt: Date | null;
+}
+
 /** A tenant's subscription row, normalized across providers. */
 export declare interface Subscription {
     readonly tenantId: string;
@@ -313,6 +411,27 @@ export declare interface Subscription {
     readonly currentPeriodEnd: Date | null;
     /** When the subscription is scheduled to cancel; null if not scheduled. */
     readonly cancelAt: Date | null;
+    /**
+     * When this tenant went past due — the dunning grace clock, and the identity
+     * of the current dunning episode.
+     *
+     * Written ONLY by a provider-confirmed reconcile, never straight off a
+     * webhook: it is the value the lockout is derived from, and locking a
+     * customer out on an event body alone is the one mistake here with a
+     * real-world cost. Cleared the moment the provider reports the
+     * subscription healthy again, which is also what cancels the rest of the
+     * notification sequence.
+     */
+    readonly pastDueSince: Date | null;
+    /**
+     * The provider-event timestamp the current `status` came from — the
+     * out-of-order guard. Provider webhooks are at-least-once AND unordered, so
+     * an event that is older than what the row already reflects is DROPPED
+     * rather than applied (a stale `active` must not un-do a `pastDue`, and a
+     * stale `pastDue` must not resurrect a resolved one). Null on rows written
+     * before any dated event.
+     */
+    readonly statusEventAt: Date | null;
 }
 
 /** The outcome of a mid-cycle plan/seat change — the prorated settlement. */
@@ -337,6 +456,32 @@ export declare interface SubscriptionChangeResult {
     readonly currentPeriodEnd: Date | null;
 }
 
+/**
+ * Raised when dunning has locked a tenant out — the grace period after a
+ * provider-confirmed past-due has expired. Distinct from
+ * `EntitlementExceeded`: that one means "you used your quota", this one means
+ * "you did not pay". Registered via `errorSchemas`, so a client can branch on
+ * `_tag === 'SubscriptionLocked'` and route the user to the billing portal
+ * rather than showing a generic failure.
+ *
+ * Dates cross the wire as ISO strings — a `Schema.DateFromSelf` would not
+ * survive the JSON boundary the error union is encoded through.
+ */
+export declare class SubscriptionLocked extends SubscriptionLocked_base {
+}
+
+declare const SubscriptionLocked_base: Schema.TaggedErrorClass<SubscriptionLocked, "SubscriptionLocked", {
+    readonly _tag: Schema.tag<"SubscriptionLocked">;
+} & {
+    tenantId: typeof Schema.String;
+    /** The subscription status at the time of the refusal (`'pastDue'`). */
+    status: typeof Schema.String;
+    /** ISO timestamp at which the grace period expired. */
+    lockedSince: typeof Schema.String;
+    /** `'hard'` (limits fell to the free plan) or `'soft'` (report only). */
+    lockout: typeof Schema.String;
+}>;
+
 export declare type SubscriptionStatus = 'active' | 'trialing' | 'pastDue' | 'canceled' | 'incomplete';
 
 /** Apply a plan / seat change to the LIVE subscription at the provider. */

package/dist/types.js

@@ -4,11 +4,16 @@ var n = class extends t.TaggedError()("BillingError", {
 	source: t.String,
 	message: t.String,
 	transient: t.Boolean
-}) {}, r = class extends t.TaggedError()("EntitlementExceeded", {
+}) {}, r = class extends t.TaggedError()("SubscriptionLocked", {
+	tenantId: t.String,
+	status: t.String,
+	lockedSince: t.String,
+	lockout: t.String
+}) {}, i = class extends t.TaggedError()("EntitlementExceeded", {
 	entitlement: t.String,
 	limit: t.Number,
 	used: t.Number,
 	cost: t.Number
-}) {}, i = "free", a = class extends e.Tag("@voltro/plugin-billing/BillingService")() {};
+}) {}, a = "free", o = class extends e.Tag("@voltro/plugin-billing/BillingService")() {};
 //#endregion
-export { n as BillingError, a as BillingService, i as DEFAULT_PLAN, r as EntitlementExceeded };
+export { n as BillingError, o as BillingService, a as DEFAULT_PLAN, i as EntitlementExceeded, r as SubscriptionLocked };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-billing",
-  "version": "0.33.0",
+  "version": "0.34.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",
@@ -48,11 +48,11 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/logger": "0.33.0",
-    "@voltro/plugin-webhooks": "0.33.0",
-    "@voltro/protocol": "0.33.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/logger": "0.34.0",
+    "@voltro/plugin-webhooks": "0.34.0",
+    "@voltro/protocol": "0.34.0",
     "stripe": "22.3.2"
   },
   "peerDependencies": {