@voltro/plugin-billing 0.5.0 → 0.7.0

package/dist/rpc.d.ts

@@ -47,12 +47,40 @@ export declare const changeSeatsDescriptor: ActionProcedureDescriptor<"billing.c
     currency: 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<{
+    invoices: Schema.Array$<Schema.Struct<{
+        providerInvoiceId: typeof Schema.String;
+        amountMinor: typeof Schema.Number;
+        currency: typeof Schema.String;
+        status: typeof Schema.String;
+        createdAt: Schema.NullOr<typeof Schema.String>;
+        hostedUrl: Schema.NullOr<typeof Schema.String>;
+        pdfUrl: Schema.NullOr<typeof Schema.String>;
+    }>>;
+}>, typeof BillingError>;
+
 export declare const portalUrlDescriptor: ActionProcedureDescriptor<"billing.portalUrl", Schema.Struct<{
     returnUrl: typeof Schema.String;
 }>, Schema.Struct<{
     url: typeof Schema.String;
 }>, typeof BillingError>;
 
+/** What a plan/seat change would cost, from the provider's invoice preview.
+ *  Quote THIS in a confirmation dialog — a locally-estimated figure differs
+ *  from the charge by the provider's rounding, tax and credit balance. */
+export declare const previewChangeDescriptor: ActionProcedureDescriptor<"billing.previewChange", Schema.Struct<{
+    plan: Schema.optional<typeof Schema.String>;
+    quantity: Schema.optional<typeof Schema.Number>;
+}>, Schema.Struct<{
+    plan: typeof Schema.String;
+    quantity: typeof Schema.Number;
+    /** Integer minor-unit settlement: > 0 charge, < 0 credit, 0 at boundary. */
+    prorationMinor: typeof Schema.Number;
+    currency: typeof Schema.String;
+}>, typeof BillingError>;
+
 export declare const reportUsageDescriptor: ActionProcedureDescriptor<"billing.reportUsage", Schema.Struct<{
     key: typeof Schema.String;
     quantity: typeof Schema.Number;
@@ -64,6 +92,8 @@ export declare const startCheckoutDescriptor: ActionProcedureDescriptor<"billing
     plan: typeof Schema.String;
     successUrl: typeof Schema.String;
     cancelUrl: typeof Schema.String;
+    /** Seats to buy up front. Omit for 1. */
+    quantity: Schema.optional<typeof Schema.Number>;
 }>, Schema.Struct<{
     url: typeof Schema.String;
 }>, typeof BillingError>;

package/dist/rpc.js

@@ -7,7 +7,8 @@ var i = n({
 	input: t.Struct({
 		plan: t.String,
 		successUrl: t.String,
-		cancelUrl: t.String
+		cancelUrl: t.String,
+		quantity: t.optional(t.Number)
 	}),
 	output: t.Struct({ url: t.String }),
 	error: e
@@ -41,16 +42,37 @@ var i = n({
 	prorationMinor: t.Number,
 	currency: t.String
 }), l = n({
+	name: "billing.previewChange",
+	input: t.Struct({
+		plan: t.optional(t.String),
+		quantity: t.optional(t.Number)
+	}),
+	output: c,
+	error: e
+}), u = r({
+	name: "billing.invoices",
+	input: t.Struct({}),
+	output: t.Struct({ invoices: t.Array(t.Struct({
+		providerInvoiceId: t.String,
+		amountMinor: t.Number,
+		currency: t.String,
+		status: t.String,
+		createdAt: t.NullOr(t.String),
+		hostedUrl: t.NullOr(t.String),
+		pdfUrl: t.NullOr(t.String)
+	})) }),
+	error: e
+}), d = n({
 	name: "billing.changePlan",
 	input: t.Struct({ plan: t.String }),
 	output: c,
 	error: e
-}), u = n({
+}), f = n({
 	name: "billing.changeSeats",
 	input: t.Struct({ quantity: t.Number }),
 	output: c,
 	error: e
-}), d = [
+}), p = [
 	{
 		tag: "billing.startCheckout",
 		kind: "action",
@@ -98,7 +120,23 @@ var i = n({
 			module: "@voltro/plugin-billing/rpc",
 			name: "changeSeatsDescriptor"
 		}
+	},
+	{
+		tag: "billing.previewChange",
+		kind: "action",
+		import: {
+			module: "@voltro/plugin-billing/rpc",
+			name: "previewChangeDescriptor"
+		}
+	},
+	{
+		tag: "billing.invoices",
+		kind: "query",
+		import: {
+			module: "@voltro/plugin-billing/rpc",
+			name: "invoicesDescriptor"
+		}
 	}
 ];
 //#endregion
-export { d as billingRpcClientImports, l as changePlanDescriptor, u as changeSeatsDescriptor, a as portalUrlDescriptor, s as reportUsageDescriptor, i as startCheckoutDescriptor, o as subscriptionDescriptor };
+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 };

package/dist/types.d.ts

@@ -88,6 +88,39 @@ export declare interface BillingProvider {
         url: string;
     }, BillingError>;
     readonly reportUsage: (input: UsagePush) => Effect.Effect<void, BillingError>;
+    /**
+     * Apply a plan / seat change to the LIVE subscription.
+     *
+     * This is the call whose absence made `changeSeats` a lie: without it the
+     * service patched its own table and the provider went on billing the old
+     * quantity, so a customer could be granted seats nobody was charging for.
+     * The provider — not us — computes and bills the proration.
+     */
+    readonly updateSubscription: (input: SubscriptionUpdateInput) => Effect.Effect<SubscriptionChangeResult, BillingError>;
+    /**
+     * What WOULD a change cost, without applying it? Backed by the provider's
+     * own invoice preview, so the number quoted to the customer is the number
+     * they are charged — a locally-computed estimate can differ from the
+     * provider's rounding, its tax, and its credit balance, and any difference
+     * is a support ticket.
+     */
+    readonly previewSubscriptionChange: (input: SubscriptionUpdateInput) => Effect.Effect<SubscriptionChangeResult, BillingError>;
+    /** The provider's invoice history. We mirror it for listing but never
+     *  render an invoice ourselves — `hostedUrl` / `pdfUrl` are theirs. */
+    readonly listInvoices: (input: {
+        readonly providerCustomerId: string;
+        readonly limit?: number;
+    }) => Effect.Effect<ReadonlyArray<InvoiceRecord>, 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
+     * verification (the mount's generic check then stands alone).
+     */
+    readonly verifyWebhook?: (input: {
+        readonly rawBody: Uint8Array;
+        readonly signatureHeader: string;
+        readonly secret: string;
+    }) => Effect.Effect<unknown, BillingError>;
     /** Map a verified, decoded webhook payload to a `BillingEvent`, or
      *  `null` for an event type this provider doesn't model (handler
      *  no-ops, still 200). */
@@ -113,6 +146,15 @@ export declare interface BillingServiceShape {
     readonly reportUsage: (tenantId: string, key: string, qty: number) => Effect.Effect<void, BillingError>;
     /** Flush all pending local usage counters to the provider. */
     readonly flushUsage: () => Effect.Effect<void, BillingError>;
+    /** What a plan/seat change WOULD cost, from the provider's own invoice
+     *  preview. Quote this, not a local estimate — the two differ by the
+     *  provider's rounding, tax and credit balance. */
+    readonly previewChange: (tenantId: string, next: {
+        readonly plan?: PlanId;
+        readonly quantity?: number;
+    }) => Effect.Effect<SubscriptionChange, BillingError>;
+    /** The provider's invoice history for this tenant. */
+    readonly invoices: (tenantId: string) => Effect.Effect<ReadonlyArray<InvoiceRecord>, BillingError>;
     /** Mint a provider-hosted checkout URL for `plan`. */
     readonly startCheckout: (input: {
         readonly tenantId: string;
@@ -144,26 +186,6 @@ export declare interface BillingServiceShape {
      * positive integer. Fails `BillingError` on no subscription / bad quantity.
      */
     readonly changeSeats: (tenantId: string, quantity: number, changeAt?: Date) => Effect.Effect<SubscriptionChange, BillingError>;
-    /**
-     * Record a failed payment: schedule the first dunning retry (per the
-     * configured schedule) and transition the subscription `active → pastDue`.
-     * Idempotent — a replayed failure for a subscription already in dunning does
-     * not re-arm or double-schedule.
-     */
-    readonly recordPaymentFailure: (tenantId: string, at?: Date) => Effect.Effect<DunningState | null, BillingError>;
-    /**
-     * Record a recovered payment: clear any open dunning and transition the
-     * subscription back to `active`. Idempotent / a no-op when not in dunning.
-     */
-    readonly recordPaymentSuccess: (tenantId: string, at?: Date) => Effect.Effect<void, BillingError>;
-    /**
-     * Advance every due dunning entry: subscriptions whose next retry is due move
-     * to the next offset in the schedule; those that have exhausted the schedule
-     * transition `pastDue → canceled`. Idempotent per due-time (a claim gate
-     * makes a re-run over the same window a no-op). Driven by the self-scheduled
-     * interval, or call it from your own `*.cron.tsx`.
-     */
-    readonly runDunningCycle: (now?: Date) => Effect.Effect<DunningCycleResult, BillingError>;
 }
 
 export declare interface CheckoutInput {
@@ -174,31 +196,21 @@ export declare interface CheckoutInput {
     readonly cancelUrl: string;
     /** Optional existing provider customer id to attach the checkout to. */
     readonly providerCustomerId?: string;
+    /** Seats to buy up front. Defaults to 1. */
+    readonly quantity?: number;
+    /** Let the buyer change the seat count on the checkout page itself.
+     *  Stripe renders the stepper; we neither build nor validate it. */
+    readonly adjustableQuantity?: {
+        readonly min: number;
+        readonly max: number;
+    };
+    /** Days of free trial. Stripe runs the trial and emits `trialing`. */
+    readonly trialDays?: number;
 }
 
 /** The free/fallback plan id every app implicitly has. */
 export declare const DEFAULT_PLAN: PlanId;
 
-/** What one `runDunningCycle` did. */
-export declare interface DunningCycleResult {
-    /** Subscriptions advanced to the next retry offset. */
-    readonly retried: number;
-    /** Subscriptions that exhausted the schedule and were canceled. */
-    readonly canceled: number;
-}
-
-/** A tenant's live dunning record — a failed payment being retried. */
-export declare interface DunningState {
-    readonly tenantId: string;
-    readonly providerSubscriptionId: string;
-    /** 0-based index into the configured retry-offset schedule. */
-    readonly attempt: number;
-    /** When the current retry is due. */
-    readonly nextRetryAt: Date;
-    /** When dunning was first opened (the original failure). */
-    readonly startedAt: Date;
-}
-
 /** The result of a pure (non-mutating) entitlement check. */
 export declare interface EntitlementDecision {
     /** Whether the call would be allowed. */
@@ -239,6 +251,17 @@ declare const EntitlementExceeded_base: Schema.TaggedErrorClass<EntitlementExcee
 /** An entitlement limit: a finite quota or the unbounded `'unlimited'`. */
 export declare type EntitlementLimit = number | 'unlimited';
 
+export declare interface InvoiceRecord {
+    readonly providerInvoiceId: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly status: string;
+    readonly createdAt: Date | null;
+    /** Provider-hosted invoice page — we never render one ourselves. */
+    readonly hostedUrl: string | null;
+    readonly pdfUrl: string | null;
+}
+
 /** A monetary amount: integer minor units + ISO-4217 currency. */
 export declare interface Money {
     /** Integer minor units (cents). Never a float. */
@@ -302,8 +325,40 @@ export declare interface SubscriptionChange {
     readonly currency: string;
 }
 
+/** What a provider reports back after (or before) a subscription change. */
+export declare interface SubscriptionChangeResult {
+    readonly plan: PlanId;
+    readonly quantity: number;
+    /** The proration the PROVIDER computed — and, unless `proration: 'none'`,
+     *  will actually bill. Positive = owed, negative = credited. */
+    readonly prorationMinor: number;
+    readonly currency: string;
+    readonly currentPeriodStart: Date | null;
+    readonly currentPeriodEnd: Date | null;
+}
+
 export declare type SubscriptionStatus = 'active' | 'trialing' | 'pastDue' | 'canceled' | 'incomplete';
 
+/** Apply a plan / seat change to the LIVE subscription at the provider. */
+export declare interface SubscriptionUpdateInput {
+    readonly providerSubscriptionId: string;
+    /** New price to move to. Omit to keep the current one. */
+    readonly priceId?: string;
+    /** New seat quantity. Omit to keep the current one. */
+    readonly quantity?: number;
+    /**
+     * How the provider should handle the mid-period money.
+     *
+     *   - `'prorate'` — bill or credit the difference for the remaining period
+     *     (Stripe's `create_prorations`). The default, and the only option that
+     *     charges what the customer actually used.
+     *   - `'none'` — change takes effect with no adjustment.
+     *   - `'always_invoice'` — prorate AND invoice immediately rather than at
+     *     the next cycle.
+     */
+    readonly proration?: 'prorate' | 'none' | 'always_invoice';
+}
+
 export declare interface UsagePush {
     readonly tenantId: string;
     readonly entitlementKey: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@voltro/plugin-billing",
-  "version": "0.5.0",
-  "description": "Billing — subscriptions, plans, entitlements + usage metering on top of a pluggable BillingProvider (Stripe + mock). Ships billingPlugin() (provider-event webhook via @voltro/plugin-webhooks, the entitlement interceptor, typed BillingError + EntitlementExceeded errors, the _voltro_billing_* tables), the BillingService Context.Tag, the requireEntitlement() in-handler guard, and a browser-safe useStartCheckout() hook. Money is integer minor units end-to-end.",
+  "version": "0.7.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",
     "typescript",
@@ -47,11 +47,12 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/logger": "0.5.0",
-    "@voltro/plugin-webhooks": "0.5.0",
-    "@voltro/protocol": "0.5.0"
+    "@voltro/database": "0.7.0",
+    "@voltro/env": "0.7.0",
+    "@voltro/logger": "0.7.0",
+    "@voltro/plugin-webhooks": "0.7.0",
+    "@voltro/protocol": "0.7.0",
+    "stripe": "22.3.2"
   },
   "peerDependencies": {
     "effect": "^3.21.4",