@voltro/plugin-billing 0.81.0 → 0.82.0

package/dist/rpc.d.ts

@@ -27,6 +27,18 @@ declare const BillingError_base: Schema.TaggedErrorClass<BillingError, "BillingE
  *  emitted into the generated client group. Kept in lockstep with the exports. */
 export declare const billingRpcClientImports: ReadonlyArray<PluginRpcClientDescriptor>;
 
+/** The customer's own cancellation: active until the paid period ends, then
+ *  ended. `cancelAt` on the answer is when. */
+export declare const cancelSubscriptionDescriptor: ActionProcedureDescriptor<"billing.cancel", Schema.Struct<{}>, Schema.Struct<{
+    subscription: Schema.Struct<{
+        plan: typeof Schema.String;
+        status: typeof Schema.String;
+        quantity: typeof Schema.Number;
+        currentPeriodEnd: Schema.NullOr<typeof Schema.String>;
+        cancelAt: Schema.NullOr<typeof Schema.String>;
+    }>;
+}>, typeof BillingError>;
+
 export declare const changePlanDescriptor: ActionProcedureDescriptor<"billing.changePlan", Schema.Struct<{
     plan: typeof Schema.String;
 }>, Schema.Struct<{
@@ -106,6 +118,17 @@ export declare const reportUsageDescriptor: ActionProcedureDescriptor<"billing.r
     ok: typeof Schema.Boolean;
 }>, typeof BillingError>;
 
+/** Take back a cancellation before the period ends. */
+export declare const resumeSubscriptionDescriptor: ActionProcedureDescriptor<"billing.resume", Schema.Struct<{}>, Schema.Struct<{
+    subscription: Schema.Struct<{
+        plan: typeof Schema.String;
+        status: typeof Schema.String;
+        quantity: typeof Schema.Number;
+        currentPeriodEnd: Schema.NullOr<typeof Schema.String>;
+        cancelAt: Schema.NullOr<typeof Schema.String>;
+    }>;
+}>, typeof BillingError>;
+
 export declare const startCheckoutDescriptor: ActionProcedureDescriptor<"billing.startCheckout", Schema.Struct<{
     plan: typeof Schema.String;
     successUrl: typeof Schema.String;
@@ -126,4 +149,17 @@ export declare const subscriptionDescriptor: QueryProcedureDescriptor<"billing.s
     }>>;
 }>, typeof BillingError>;
 
+/** The checkpoint: sync the caller's tenant from the provider and answer with
+ *  its current subscription. Call it on the return from checkout or the
+ *  portal, and when a billing page loads. */
+export declare const syncDescriptor: ActionProcedureDescriptor<"billing.sync", Schema.Struct<{}>, Schema.Struct<{
+    subscription: Schema.NullOr<Schema.Struct<{
+        plan: typeof Schema.String;
+        status: typeof Schema.String;
+        quantity: typeof Schema.Number;
+        currentPeriodEnd: Schema.NullOr<typeof Schema.String>;
+        cancelAt: Schema.NullOr<typeof Schema.String>;
+    }>>;
+}>, typeof BillingError>;
+
 export { }

package/dist/rpc.js

@@ -19,19 +19,19 @@ var i = n({
 	output: t.Struct({ url: t.String }),
 	error: e,
 	guards: [{ scope: "billing:manage" }]
-}), o = r({
+}), o = t.Struct({
+	plan: t.String,
+	status: t.String,
+	quantity: t.Number,
+	currentPeriodEnd: t.NullOr(t.String),
+	cancelAt: t.NullOr(t.String)
+}), s = r({
 	name: "billing.subscription",
 	input: t.Struct({}),
-	output: t.Struct({ subscription: t.NullOr(t.Struct({
-		plan: t.String,
-		status: t.String,
-		quantity: t.Number,
-		currentPeriodEnd: t.NullOr(t.String),
-		cancelAt: t.NullOr(t.String)
-	})) }),
+	output: t.Struct({ subscription: t.NullOr(o) }),
 	error: e,
 	openAccess: "tenant-scoped read of the caller's own tenant's plan/seat state for account UI every member renders; carries no payment credentials"
-}), s = r({
+}), c = r({
 	name: "billing.entitlementStatus",
 	input: t.Struct({}),
 	output: t.Struct({
@@ -46,7 +46,7 @@ var i = n({
 	}),
 	error: e,
 	openAccess: "tenant-scoped read of the caller's own tenant's entitlement/grace state — the banner every signed-in member renders on payment failure"
-}), c = n({
+}), l = n({
 	name: "billing.reportUsage",
 	input: t.Struct({
 		key: t.String,
@@ -55,21 +55,21 @@ var i = n({
 	output: t.Struct({ ok: t.Boolean }),
 	error: e,
 	guards: [{ scope: "billing:report" }]
-}), l = t.Struct({
+}), u = t.Struct({
 	plan: t.String,
 	quantity: t.Number,
 	prorationMinor: t.Number,
 	currency: t.String
-}), u = n({
+}), d = n({
 	name: "billing.previewChange",
 	input: t.Struct({
 		plan: t.optional(t.String),
 		quantity: t.optional(t.Number)
 	}),
-	output: l,
+	output: u,
 	error: e,
 	guards: [{ scope: "billing:manage" }]
-}), d = r({
+}), f = r({
 	name: "billing.invoices",
 	input: t.Struct({}),
 	output: t.Struct({ invoices: t.Array(t.Struct({
@@ -83,19 +83,37 @@ var i = n({
 	})) }),
 	error: e,
 	guards: [{ scope: "billing:manage" }]
-}), f = n({
+}), p = n({
 	name: "billing.changePlan",
 	input: t.Struct({ plan: t.String }),
-	output: l,
+	output: u,
 	error: e,
 	guards: [{ scope: "billing:manage" }]
-}), p = n({
+}), m = n({
 	name: "billing.changeSeats",
 	input: t.Struct({ quantity: t.Number }),
-	output: l,
+	output: u,
+	error: e,
+	guards: [{ scope: "billing:manage" }]
+}), h = n({
+	name: "billing.cancel",
+	input: t.Struct({}),
+	output: t.Struct({ subscription: o }),
+	error: e,
+	guards: [{ scope: "billing:manage" }]
+}), g = n({
+	name: "billing.sync",
+	input: t.Struct({}),
+	output: t.Struct({ subscription: t.NullOr(o) }),
+	error: e,
+	guards: [{ scope: "billing:manage" }]
+}), _ = n({
+	name: "billing.resume",
+	input: t.Struct({}),
+	output: t.Struct({ subscription: o }),
 	error: e,
 	guards: [{ scope: "billing:manage" }]
-}), m = [
+}), v = [
 	{
 		tag: "billing.startCheckout",
 		kind: "action",
@@ -152,6 +170,30 @@ var i = n({
 			name: "changeSeatsDescriptor"
 		}
 	},
+	{
+		tag: "billing.cancel",
+		kind: "action",
+		import: {
+			module: "@voltro/plugin-billing/rpc",
+			name: "cancelSubscriptionDescriptor"
+		}
+	},
+	{
+		tag: "billing.resume",
+		kind: "action",
+		import: {
+			module: "@voltro/plugin-billing/rpc",
+			name: "resumeSubscriptionDescriptor"
+		}
+	},
+	{
+		tag: "billing.sync",
+		kind: "action",
+		import: {
+			module: "@voltro/plugin-billing/rpc",
+			name: "syncDescriptor"
+		}
+	},
 	{
 		tag: "billing.previewChange",
 		kind: "action",
@@ -170,4 +212,4 @@ var i = n({
 	}
 ];
 //#endregion
-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 };
+export { v as billingRpcClientImports, h as cancelSubscriptionDescriptor, p as changePlanDescriptor, m as changeSeatsDescriptor, c as entitlementStatusDescriptor, f as invoicesDescriptor, a as portalUrlDescriptor, d as previewChangeDescriptor, l as reportUsageDescriptor, _ as resumeSubscriptionDescriptor, i as startCheckoutDescriptor, s as subscriptionDescriptor, g as syncDescriptor };

package/dist/types.d.ts

@@ -2,6 +2,14 @@ import { Context } from 'effect';
 import { Effect } from 'effect';
 import { Schema } from 'effect';
 
+/**
+ * What a billing call would do to what the tenant pays — the unit an app's
+ * `admit` hook decides on. `checkout` starts paying, `change` moves a plan or
+ * seat count, `resume` takes a cancellation back, `portal` opens the provider's
+ * self-service page (which can do all of those), `cancel` stops paying.
+ */
+export declare type BillingAction = 'checkout' | 'change' | 'resume' | 'portal' | 'cancel';
+
 /**
  * A billing failure. `transient: true` marks failures the service retries
  * (network blip talking to the provider); non-transient failures (a 4xx
@@ -66,6 +74,14 @@ export declare type BillingEvent = {
     readonly tenantId: string;
     readonly providerCustomerId: string;
     readonly occurredAt: Date | null;
+} | {
+    /** The provider customer was deleted (e.g. in the provider's dashboard).
+     *  `tenantId` is null when the customer carried no tenant metadata — the
+     *  link is then resolved from our own customer table. */
+    readonly _tag: 'customerUnlinked';
+    readonly tenantId: string | null;
+    readonly providerCustomerId: string;
+    readonly occurredAt: Date | null;
 };
 
 /** The event tag union — handy for `onEvent` keys. */
@@ -88,6 +104,10 @@ export declare interface BillingProvider {
      *  When false, `BillingService.reportUsage` records locally but never
      *  calls `provider.reportUsage`. */
     readonly supportsMeteredUsage: boolean;
+    /** Whether a usage push must name a linked provider customer. Stripe
+     *  meters map events to a customer by id, so an unlinked tenant's usage
+     *  stays pending instead of being sent unattributable. */
+    readonly usageRequiresCustomer?: boolean;
     readonly createCheckoutSession: (input: CheckoutInput) => Effect.Effect<{
         url: string;
     }, BillingError>;
@@ -123,6 +143,43 @@ export declare interface BillingProvider {
      * provider does not know the id.
      */
     readonly fetchSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState | null, BillingError>;
+    /**
+     * Every live (not yet ended) subscription at the provider, optionally for
+     * one customer. The provider-side half of reconciliation: what it lists is
+     * the truth our rows are corrected to.
+     */
+    readonly listSubscriptions: (input: {
+        readonly providerCustomerId?: string;
+    }) => Effect.Effect<ReadonlyArray<ProviderSubscriptionSnapshot>, BillingError>;
+    /** End a subscription — at period end (reversible) or immediately with a
+     *  final invoice. Returns the provider's state afterwards. */
+    readonly cancelSubscription: (input: {
+        readonly providerSubscriptionId: string;
+        readonly mode: CancelMode;
+    }) => Effect.Effect<ProviderSubscriptionState, BillingError>;
+    /** Undo a period-end cancellation that has not taken effect yet. */
+    readonly resumeSubscription: (providerSubscriptionId: string) => Effect.Effect<ProviderSubscriptionState, BillingError>;
+    /**
+     * The provider customer for a tenant, created when it has none — BEFORE the
+     * first checkout, so every checkout names its customer. That is what lets
+     * the provider refuse a second subscription for the same customer, and
+     * lets open checkouts be found and expired. Must be idempotent per tenant:
+     * two concurrent first checkouts get the same customer.
+     */
+    readonly ensureCustomer: (input: {
+        readonly tenantId: string;
+    }) => Effect.Effect<string, BillingError>;
+    /** Expire every checkout still open for a customer, so only the newest one
+     *  can be paid. Returns how many were expired. */
+    readonly expireOpenCheckouts: (input: {
+        readonly providerCustomerId: string;
+    }) => Effect.Effect<number, BillingError>;
+    /** Add prices the subscription is missing (metered items), without
+     *  proration. Prices already present are left alone. */
+    readonly addSubscriptionPrices: (input: {
+        readonly providerSubscriptionId: string;
+        readonly priceIds: ReadonlyArray<string>;
+    }) => Effect.Effect<void, BillingError>;
     /**
      * The billing contact the PROVIDER has on file, when it has one. Used as the
      * dunning recipient of last resort — `dunning.resolveRecipient` wins when
@@ -149,6 +206,23 @@ export declare interface BillingProvider {
      *  `null` for an event type this provider doesn't model (handler
      *  no-ops, still 200). */
     readonly normalizeEvent: (raw: unknown) => Effect.Effect<BillingEvent | null, BillingError>;
+    /**
+     * Who and when a verified payload is about: the provider customer it names
+     * and when the provider created it. The webhook syncs that customer from a
+     * fresh read instead of trusting the payload, and an event created long
+     * before it arrives means deliveries were failing — the cue to catch up.
+     * Optional: without it the webhook applies the normalized event as is.
+     */
+    readonly eventContext?: (raw: unknown) => {
+        readonly providerCustomerId: string | null;
+        readonly createdAt: Date | null;
+    };
+    /**
+     * Events the provider could not deliver to the app's webhook, as far back as
+     * it keeps them (Stripe: 30 days) — what an outage of the endpoint left
+     * behind. Optional: a provider without it has no catch-up.
+     */
+    readonly listUndeliveredEvents?: () => Effect.Effect<ReadonlyArray<UndeliveredEvent>, BillingError>;
 }
 
 /** The billing service Tag — `const billing = yield* BillingService`. */
@@ -210,6 +284,8 @@ export declare interface BillingServiceShape {
         readonly plan: PlanId;
         readonly successUrl: string;
         readonly cancelUrl: string;
+        /** Seats to buy up front. Omit for 1. */
+        readonly quantity?: number;
     }) => Effect.Effect<{
         url: string;
     }, BillingError>;
@@ -217,6 +293,48 @@ export declare interface BillingServiceShape {
     readonly portalUrl: (tenantId: string, returnUrl: string) => Effect.Effect<{
         url: string;
     }, BillingError>;
+    /**
+     * The customer's own cancellation: the subscription stays active until the
+     * paid period ends, then ends. The provider applies it first; the row
+     * mirrors its answer (`cancelAt`). Reversible with `resumeSubscription`.
+     */
+    readonly cancelSubscription: (tenantId: string) => Effect.Effect<Subscription, BillingError>;
+    /** Take back a period-end cancellation before it takes effect. */
+    readonly resumeSubscription: (tenantId: string) => Effect.Effect<Subscription, BillingError>;
+    /**
+     * End every provider subscription of a tenant — for deleting an
+     * organization or account. Pending usage is flushed first; each subscription
+     * then ends once that usage has settled on the meter (minutes, see
+     * `CancelMode` 'close') with a final invoice for it and a proration credit.
+     * The rows carry the end as `cancelAt` until the provider's deletion event
+     * marks them canceled. The provider customer and its invoices are KEPT: they
+     * are the accounting record. Fails without ending anything when the flush
+     * fails, so no usage is lost; the caller retries.
+     */
+    readonly closeAccount: (tenantId: string) => Effect.Effect<CloseAccountResult, BillingError>;
+    /**
+     * Correct every local row from the provider: what the provider lists wins,
+     * a local live row the provider no longer lists is re-read directly, missing
+     * metered items are added back. Run it on a schedule — it heals whatever a
+     * missed or failed webhook left behind.
+     */
+    readonly reconcileFromProvider: () => Effect.Effect<ProviderReconcileResult, BillingError>;
+    /**
+     * Bring one provider customer's rows to what the provider says now, and
+     * return its current state as events (all of it, not just changes). The
+     * webhook uses it for the customer an event names. Does not run `onEvent`.
+     */
+    readonly syncCustomer: (providerCustomerId: string, hintTenantId?: string) => Effect.Effect<{
+        readonly tenantId: string | null;
+        readonly events: ReadonlyArray<BillingEvent>;
+    }, BillingError>;
+    /**
+     * The checkpoint: sync a tenant from the provider, run `onEvent` for what it
+     * found, and answer with its current subscription. Call it where a stale row
+     * would matter — the return from checkout or the portal, a billing page
+     * load. Every call that changes what a tenant pays already runs it first.
+     */
+    readonly syncTenant: (tenantId: string) => Effect.Effect<Subscription | null, BillingError>;
     /** Apply a normalized provider event to the DB rows (idempotent upsert). */
     readonly applyEvent: (event: BillingEvent) => Effect.Effect<void, BillingError>;
     /**
@@ -237,10 +355,29 @@ export declare interface BillingServiceShape {
     readonly changeSeats: (tenantId: string, quantity: number, changeAt?: Date) => Effect.Effect<SubscriptionChange, BillingError>;
 }
 
+/** How a subscription ends. */
+export declare type CancelMode = 
+/** Stays active until the paid period ends, then ends — the customer's own
+*  cancellation. Reversible with `resumeSubscription` until then. */
+'periodEnd'
+/**
+* Closing an account: ends as soon as the last usage has settled on the
+* meter — a few minutes, not a period — with a final invoice for that usage
+* and a proration credit for the unused time.
+*
+* Not "now", on purpose: meter events aggregate asynchronously, and a
+* subscription ended the moment its last usage was sent is invoiced for none
+* of it (measured: the meter showed 250, the final invoice 0, and a finalized
+* invoice never picks the usage up later).
+*/
+| 'close';
+
 export declare interface CheckoutInput {
     readonly tenantId: string;
     /** Provider price id to subscribe to. */
     readonly priceId: string;
+    /** Usage-based prices added next to `priceId` (no quantity). */
+    readonly meteredPriceIds?: ReadonlyArray<string>;
     readonly successUrl: string;
     readonly cancelUrl: string;
     /** Optional existing provider customer id to attach the checkout to. */
@@ -257,6 +394,13 @@ export declare interface CheckoutInput {
     readonly trialDays?: number;
 }
 
+/** What `closeAccount` did at the provider. */
+export declare interface CloseAccountResult {
+    readonly tenantId: string;
+    /** Provider subscriptions ended (immediately, with a final invoice). */
+    readonly canceled: ReadonlyArray<string>;
+}
+
 /** The free/fallback plan id every app implicitly has. */
 export declare const DEFAULT_PLAN: PlanId;
 
@@ -359,6 +503,13 @@ export declare interface Money {
 export declare interface PlanConfig {
     /** Provider price id (Stripe `price_…`). Absent for free/zero-cost plans. */
     readonly priceId?: string;
+    /**
+     * Usage-based provider prices subscribed ALONGSIDE `priceId` (Stripe prices
+     * with `recurring.meter`). Checkout adds each as a quantity-less line item,
+     * so the subscription carries the metered item from its first invoice —
+     * without it, meter events are recorded at Stripe but never billed.
+     */
+    readonly meteredPriceIds?: ReadonlyArray<string>;
     /** Per-entitlement-key limits. Values are `number | 'unlimited'`. */
     readonly entitlements: Readonly<Record<string, EntitlementLimit>>;
     /** The plan's per-period price in INTEGER minor units (cents) — the unit
@@ -381,6 +532,45 @@ export declare interface PortalInput {
     readonly returnUrl: string;
 }
 
+/** What `reconcileFromProvider` found and corrected. */
+export declare interface ProviderReconcileResult {
+    /** Subscriptions compared (provider-listed plus local rows it did not list). */
+    readonly checked: number;
+    /** Tenants whose local rows changed because the provider said otherwise. */
+    readonly corrected: ReadonlyArray<string>;
+    /** Tenants with more than one live subscription at the provider — billed
+     *  twice. Never resolved automatically: refunding is a human decision. */
+    readonly duplicates: ReadonlyArray<string>;
+    /** Provider subscriptions naming no tenant; nothing to attribute them to. */
+    readonly unattributed: number;
+    /** Subscriptions that had a plan's metered price added back. */
+    readonly meteredItemsRestored: number;
+    /** Tenants the app reports closed whose subscriptions were still paying —
+     *  ended now (see `isTenantClosed`). */
+    readonly closedTenants: ReadonlyArray<string>;
+    /** Live rows the provider has never heard of that were NOT canceled, because
+     *  so many at once means the wrong account or provider (0 normally). */
+    readonly refusedUnknown: number;
+    /** Every correction as the event it stands for, for the app's `onEvent`
+     *  projections; the plugin's scheduled reconcile dispatches them. */
+    readonly events: ReadonlyArray<BillingEvent>;
+}
+
+/**
+ * One subscription as the provider lists it — the input of the provider-side
+ * reconcile. Carries the ids a local row is matched by and the price ids a
+ * plan's metered items are checked against.
+ */
+export declare interface ProviderSubscriptionSnapshot extends ProviderSubscriptionState {
+    readonly providerSubscriptionId: string;
+    readonly providerCustomerId: string | null;
+    /** From the subscription's own metadata; null when the provider object was
+     *  not created through our checkout and names no tenant. */
+    readonly tenantId: string | null;
+    /** Every price the subscription carries, licensed and metered. */
+    readonly priceIds: ReadonlyArray<string>;
+}
+
 /** The provider's CURRENT view of a subscription — read directly, not from an
  *  event body. `reconcileDunning` asks for this before it will lock anyone
  *  out. */
@@ -504,6 +694,13 @@ export declare interface SubscriptionUpdateInput {
     readonly proration?: 'prorate' | 'none' | 'always_invoice';
 }
 
+/** An event the provider failed to deliver, reduced to what a catch-up needs. */
+export declare interface UndeliveredEvent {
+    readonly id: string;
+    readonly providerCustomerId: string | null;
+    readonly createdAt: Date | null;
+}
+
 export declare interface UsagePush {
     readonly tenantId: string;
     readonly entitlementKey: string;
@@ -511,6 +708,14 @@ export declare interface UsagePush {
     readonly quantity: number;
     /** End of the period the usage falls in (provider timestamp anchor). */
     readonly periodEnd?: Date;
+    /** The provider customer the usage is billed to, when one is linked. */
+    readonly providerCustomerId?: string;
+    /**
+     * Names THIS delta: the same flush replayed carries the same key (so the
+     * provider can dedupe it), the next delta carries a new one. A key per
+     * (tenant, key, period) alone would make every later delta a "duplicate".
+     */
+    readonly idempotencyKey?: string;
 }
 
 export { }

package/dist/web/index.d.ts

@@ -1,3 +1,12 @@
+/** The fields of `billing.subscription` the cancel flow reads. */
+export declare interface CancelableSubscription {
+    readonly status: string;
+    /** ISO instant a scheduled cancellation takes effect, else null. */
+    readonly cancelAt: string | null;
+    /** ISO instant the paid period ends. */
+    readonly currentPeriodEnd: string | null;
+}
+
 /** The plan id + redirect URLs a checkout needs. */
 export declare interface StartCheckoutInput {
     readonly plan: string;
@@ -15,6 +24,9 @@ export declare type StartCheckoutRpc = (input: StartCheckoutInput) => Promise<{
     readonly url: string;
 }>;
 
+/** The generated `billing.cancel` / `billing.resume` action bindings. */
+export declare type SubscriptionActionRpc = (input: Record<string, never>) => Promise<unknown>;
+
 /**
  * React hook that drives provider-hosted checkout. Pass the generated
  * `billing.startCheckout` rpc binding; the hook tracks pending/error and
@@ -38,4 +50,49 @@ export declare interface UseStartCheckoutResult {
     readonly error: Error | null;
 }
 
+/**
+ * The two-step cancellation an app renders on its own billing page: an entry,
+ * then a separate confirmation that names the end date, then — once scheduled —
+ * the way back. The cancellation itself is the provider's period-end cancel
+ * (`billing.cancel`); the subscription stays active until it ends.
+ *
+ * The state comes from the subscription the app already reads, so a
+ * cancellation made in the provider's portal shows here too.
+ *
+ * ```tsx
+ * const flow = useSubscriptionCancel({ subscription, cancel: rpc.billing.cancel, resume: rpc.billing.resume })
+ * flow.stage === 'active'     && <button onClick={flow.begin}>Cancel your subscription here</button>
+ * flow.stage === 'confirming' && <><p>Ends on {flow.endsOn}</p><button onClick={flow.confirm}>Cancel now</button><button onClick={flow.keep}>Keep</button></>
+ * flow.stage === 'scheduled'  && <button onClick={flow.resume}>Take the cancellation back</button>
+ * ```
+ */
+export declare const useSubscriptionCancel: (input: {
+    readonly subscription: CancelableSubscription;
+    readonly cancel: SubscriptionActionRpc;
+    readonly resume: SubscriptionActionRpc;
+}) => UseSubscriptionCancelResult;
+
+export declare interface UseSubscriptionCancelResult {
+    /**
+     * - `active`     — nothing scheduled; show the entry ("cancel your subscription here")
+     * - `confirming` — the separate confirmation step; show `endsOn`, "cancel now" and "keep"
+     * - `scheduled`  — cancelled, ends on `endsOn`; show "take it back"
+     * - `ended`      — the subscription has ended; nothing to offer
+     */
+    readonly stage: 'active' | 'confirming' | 'scheduled' | 'ended';
+    /** When the subscription ends (scheduled) or would end (confirming), ISO. */
+    readonly endsOn: string | null;
+    /** Open the confirmation step. Calls nothing. */
+    readonly begin: () => void;
+    /** Leave the confirmation step. Calls nothing. */
+    readonly keep: () => void;
+    /** The confirmed cancellation — at period end, reversible until then. */
+    readonly confirm: () => Promise<void>;
+    /** Take a scheduled cancellation back. */
+    readonly resume: () => Promise<void>;
+    readonly pending: boolean;
+    /** The last failure, or null. The subscription is unchanged when set. */
+    readonly error: Error | null;
+}
+
 export { }

package/dist/web/index.js

@@ -17,6 +17,31 @@ var n = () => globalThis.window, r = (r) => {
 		pending: i,
 		error: o
 	};
+}, i = (n) => {
+	let [r, i] = t(!1), [a, o] = t(!1), [s, c] = t(null), { subscription: l, cancel: u, resume: d } = n, f = e(async (e) => {
+		o(!0), c(null);
+		try {
+			await e(), i(!1);
+		} catch (e) {
+			c(e instanceof Error ? e : Error(String(e)));
+		} finally {
+			o(!1);
+		}
+	}, []), p = e(() => f(() => u({})), [f, u]), m = e(() => f(() => d({})), [f, d]), h = e(() => {
+		c(null), i(!0);
+	}, []), g = e(() => {
+		i(!1);
+	}, []);
+	return {
+		stage: l.status === "canceled" ? "ended" : l.cancelAt === null ? r ? "confirming" : "active" : "scheduled",
+		endsOn: l.cancelAt ?? l.currentPeriodEnd,
+		begin: h,
+		keep: g,
+		confirm: p,
+		resume: m,
+		pending: a,
+		error: s
+	};
 };
 //#endregion
-export { r as useStartCheckout };
+export { r as useStartCheckout, i as useSubscriptionCancel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-billing",
-  "version": "0.81.0",
+  "version": "0.82.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.81.0",
-    "@voltro/env": "0.81.0",
-    "@voltro/logger": "0.81.0",
-    "@voltro/plugin-webhooks": "0.81.0",
-    "@voltro/protocol": "0.81.0"
+    "@voltro/database": "0.82.0",
+    "@voltro/env": "0.82.0",
+    "@voltro/logger": "0.82.0",
+    "@voltro/plugin-webhooks": "0.82.0",
+    "@voltro/protocol": "0.82.0"
   },
   "peerDependencies": {
     "effect": "^3.22.2",