@comfyorg/account-core 1.0.0-alpha.0 → 1.0.0-alpha.2

package/dist/core/billing/paymentProjection.js

@@ -3,9 +3,35 @@ const PROCESSING_REASONS = new Set([
     'processing_error',
     'generic'
 ]);
+const RECOVERY_ACTIONS = {
+    retry: true,
+    replace_payment_method: true,
+    authenticate_payment: true,
+    contact_support: true
+};
+/** A recovery action this build cannot act on reads as none named. */
+function knownRecoveryAction(action) {
+    return action !== undefined && isRecoveryAction(action) ? action : undefined;
+}
+function isRecoveryAction(action) {
+    return Object.hasOwn(RECOVERY_ACTIONS, action);
+}
 function stepForReason(reason) {
     return PROCESSING_REASONS.has(reason) ? 'processing_error' : 'declined';
 }
+/** A completed challenge waits on the server, not on the customer. */
+function awaitsVerification(state) {
+    const challengeOpen = state.challenge !== undefined && state.challenge.status !== 'completed';
+    return challengeOpen || state.actionUrl !== undefined;
+}
+/**
+ * Whether a pending payment's progress reads as a prompt rather than a
+ * spinner: only a hosted page the customer still has to visit asks them for
+ * anything. An in-page challenge is driven by the host itself.
+ */
+export function awaitsHostedAction(state) {
+    return state.actionUrl !== undefined;
+}
 function projectPending(state, hostStep) {
     const base = { operationId: state.id, noChargeConfirmed: false };
     if (hostStep === 'canceled')
@@ -13,17 +39,18 @@ function projectPending(state, hostStep) {
     const reason = state.declineReason ??
         (state.challenge?.status === 'failed' ? 'authentication_failed' : undefined);
     if (reason !== undefined) {
+        const recoveryAction = knownRecoveryAction(state.recoveryAction);
         return {
             ...base,
             step: stepForReason(reason),
             reasonKey: reason,
-            ...(state.recoveryAction === undefined
-                ? {}
-                : { recoveryAction: state.recoveryAction })
+            ...(recoveryAction === undefined ? {} : { recoveryAction })
         };
     }
-    const parked = state.challenge !== undefined || state.actionUrl !== undefined;
-    return { ...base, step: parked ? 'verifying' : 'preview' };
+    return {
+        ...base,
+        step: awaitsVerification(state) ? 'verifying' : 'preview'
+    };
 }
 export function projectPaymentStep(operation, hostStep) {
     if (operation === undefined) {
@@ -35,15 +62,16 @@ export function projectPaymentStep(operation, hostStep) {
             return projectPending(operation, hostStep);
         case 'succeeded':
             return { ...base, step: 'success' };
-        case 'failed':
+        case 'failed': {
+            const recoveryAction = knownRecoveryAction(operation.recoveryAction) ??
+                (operation.retryable ? undefined : 'contact_support');
             return {
                 ...base,
                 step: stepForReason(operation.declineReason),
                 reasonKey: operation.declineReason,
-                ...(operation.recoveryAction === undefined
-                    ? {}
-                    : { recoveryAction: operation.recoveryAction })
+                ...(recoveryAction === undefined ? {} : { recoveryAction })
             };
+        }
         case 'reconciliation_needed':
             return { ...base, step: 'processing_error', reasonKey: 'generic' };
         case 'timed_out':

package/dist/core/billing/scopedReader.d.ts

@@ -5,10 +5,10 @@
  * between reads, so only those live in the readers.
  *
  * What the skeleton owns is what a reader therefore cannot get wrong on its
- * own: one shared request per scope, a caller's signal releasing only that
- * caller, the publish fence that reports a late answer as `SUPERSEDED`, and
- * the denial that drops a published snapshot unless it predates a change the
- * host reported.
+ * own: one shared request per scope and route, a caller's signal releasing
+ * only that caller, the publish fence that reports a late answer as
+ * `SUPERSEDED`, and the denial that drops a published snapshot unless it
+ * predates a change the host reported.
  */
 import type { BillingResult, BillingTransport } from './billingContracts.js';
 import type { BillingScope, BillingScopeSource } from './billingScope.js';
@@ -21,7 +21,13 @@ export interface ScopedReaderDefinition<TData, TSnapshot, TOptions extends Scope
     readonly transport: BillingTransport;
     /** Where the core learns which user, workspace, and role it runs as. */
     readonly scopeSource: BillingScopeSource;
-    readonly route: string;
+    /**
+     * The route to request, as a function for a read whose query varies per
+     * call. The resolved route joins the scope in identifying an in-flight
+     * read, so two callers asking for different pages each get their own answer
+     * rather than the first one's.
+     */
+    readonly route: string | ((options: TOptions | undefined) => string);
     readonly parse: (body: unknown) => ParsedBillingBody<TData>;
     /**
      * The reader's own reading of a validated response. Returning a failure is

package/dist/core/billing/scopedReader.js

@@ -5,6 +5,7 @@ function publishAsRead(value) {
 }
 export function createScopedReader(definition) {
     const { transport, scopeSource, route, parse, project, timeoutMs, cached, publish = publishAsRead } = definition;
+    const resolveRoute = typeof route === 'string' ? () => route : route;
     let snapshot;
     let inFlight;
     const lifetime = { disposed: false };
@@ -12,11 +13,11 @@ export function createScopedReader(definition) {
         snapshot = undefined;
         inFlight = undefined;
     });
-    async function request(scope, options) {
+    async function request(scope, options, resolvedRoute) {
         const budget = timeoutMs?.(options);
         const billingRequest = {
             method: 'GET',
-            route,
+            route: resolvedRoute,
             ...(budget === undefined ? {} : { timeoutMs: budget })
         };
         const response = await readValidatedBillingResponse(transport, billingRequest, parse);
@@ -30,8 +31,8 @@ export function createScopedReader(definition) {
             snapshot = published;
         return { status: 'ok', value: published ?? value };
     }
-    async function settle(context, pending, options) {
-        const result = await request(context.scope, options);
+    async function settle(context, pending, options, resolvedRoute) {
+        const result = await request(context.scope, options, resolvedRoute);
         // The publish guard. Between issuing the request and settling it the host
         // may have changed workspace or signed out, so an answer cached now would
         // be attributed to whoever is signed in next, and a failure says nothing
@@ -60,10 +61,19 @@ export function createScopedReader(definition) {
         const served = cached?.(snapshot, context.scope, options);
         if (served !== undefined)
             return { status: 'ok', value: served };
-        // One read per scope. A caller arriving mid-flight for the same scope
-        // joins rather than issuing a second identical request; a caller for a
-        // different scope starts its own, and the older one can no longer publish.
-        if (matchesScopedRead(inFlight, context)) {
+        // Resolved once, then used both to issue the request and to identify it,
+        // so the answer a joining caller is served is the one its own route asked
+        // for.
+        const resolvedRoute = resolveRoute(options);
+        // A caller arriving mid-flight joins only a read of the same scope and
+        // route, rather than issuing a second identical request. A caller for a
+        // different scope starts its own, and the older one can no longer
+        // publish. A caller for a different route on the same scope also starts
+        // its own and takes the slot, so the displaced read still settles and
+        // publishes — the snapshot carries which page it is — but nobody can join
+        // it any more. One slot is enough for a feed read one page at a time.
+        if (matchesScopedRead(inFlight, context) &&
+            inFlight.route === resolvedRoute) {
             return releaseOnAbort(inFlight.promise, options?.signal);
         }
         // No caller signal reaches the shared request: it is bounded by its own
@@ -72,7 +82,8 @@ export function createScopedReader(definition) {
         const pending = { fenced: false };
         const attempt = {
             context,
-            promise: settle(context, pending, options),
+            route: resolvedRoute,
+            promise: settle(context, pending, options, resolvedRoute),
             pending
         };
         inFlight = attempt;

package/dist/core/billing/sharedRead.js

@@ -1,5 +1,5 @@
 import { sameBillingScope } from './billingScope.js';
-import { readBillingErrorCode } from './billingErrorBody.js';
+import { readBillingErrorCode, readBillingErrorMessage } from './billingErrorBody.js';
 import { codeForHttpStatus } from './httpStatus.js';
 /**
  * An abandoned wait is transient, the same bucket the transport reports an
@@ -22,11 +22,13 @@ export async function readValidatedBillingResponse(transport, request, parse) {
     const { httpStatus, body } = response.value;
     if (httpStatus < 200 || httpStatus >= 300) {
         const serverCode = readBillingErrorCode(body);
+        const serverMessage = readBillingErrorMessage(body);
         return {
             status: 'error',
             code: codeForHttpStatus(response.value),
             httpStatus,
-            ...(serverCode === undefined ? {} : { serverCode })
+            ...(serverCode === undefined ? {} : { serverCode }),
+            ...(serverMessage === undefined ? {} : { serverMessage })
         };
     }
     const parsed = parse(body);

package/dist/core/billing/subscriptionCommands.d.ts

@@ -35,7 +35,9 @@ export type SubscriptionCommandCode =
 /** The server wants the host to re-preview and resend with `confirm_reactivation`. */
  | 'REACTIVATION_CONFIRMATION_REQUIRED' | 'NO_ACTIVE_SUBSCRIPTION'
 /** The server asked for a hosted payment step but offered no page for it. */
- | 'MISSING_PAYMENT_METHOD_URL';
+ | 'MISSING_PAYMENT_METHOD_URL'
+/** The quote no longer matches what the server would charge; re-preview. */
+ | 'QUOTE_STALE';
 export type SubscriptionCommandFailure = BillingFailure | {
     readonly status: 'error';
     readonly code: SubscriptionCommandCode;
@@ -89,6 +91,10 @@ declare const PreviewSchema: z.ZodObject<{
     credits_next_period_cents: z.ZodNumber;
     credits_today_cents: z.ZodNumber;
     renewal_amount_cents: z.ZodOptional<z.ZodNumber>;
+    subtotal_cents: z.ZodOptional<z.ZodNumber>;
+    balance_applied_cents: z.ZodOptional<z.ZodNumber>;
+    proration_remaining_cents: z.ZodOptional<z.ZodNumber>;
+    proration_unused_cents: z.ZodOptional<z.ZodNumber>;
     current_plan: z.ZodOptional<z.ZodObject<{
         duration: z.ZodEnum<["MONTHLY", "ANNUAL"]>;
         period_end: z.ZodOptional<z.ZodString>;
@@ -98,6 +104,9 @@ declare const PreviewSchema: z.ZodObject<{
     } & {
         credits_cents: z.ZodNumber;
         price_cents: z.ZodNumber;
+        list_price_cents: z.ZodOptional<z.ZodNumber>;
+        monthly_list_price_cents: z.ZodOptional<z.ZodNumber>;
+        monthly_price_cents: z.ZodOptional<z.ZodNumber>;
         seat_summary: z.ZodObject<{
             seat_count: z.ZodNumber;
         } & {
@@ -114,8 +123,8 @@ declare const PreviewSchema: z.ZodObject<{
         }>;
     }, "strip", z.ZodTypeAny, {
         price_cents: number;
-        credits_cents: number;
         duration: "MONTHLY" | "ANNUAL";
+        credits_cents: number;
         seat_summary: {
             seat_count: number;
             total_cost_cents: number;
@@ -125,10 +134,13 @@ declare const PreviewSchema: z.ZodObject<{
         tier: "FREE" | "STANDARD" | "CREATOR" | "PRO" | "FOUNDERS_EDITION" | "TEAM" | "ENTERPRISE";
         period_end?: string | undefined;
         period_start?: string | undefined;
+        list_price_cents?: number | undefined;
+        monthly_list_price_cents?: number | undefined;
+        monthly_price_cents?: number | undefined;
     }, {
         price_cents: number;
-        credits_cents: number;
         duration: "MONTHLY" | "ANNUAL";
+        credits_cents: number;
         seat_summary: {
             seat_count: number;
             total_cost_cents: number;
@@ -138,6 +150,9 @@ declare const PreviewSchema: z.ZodObject<{
         tier: "FREE" | "STANDARD" | "CREATOR" | "PRO" | "FOUNDERS_EDITION" | "TEAM" | "ENTERPRISE";
         period_end?: string | undefined;
         period_start?: string | undefined;
+        list_price_cents?: number | undefined;
+        monthly_list_price_cents?: number | undefined;
+        monthly_price_cents?: number | undefined;
     }>>;
     new_plan: z.ZodObject<{
         duration: z.ZodEnum<["MONTHLY", "ANNUAL"]>;
@@ -148,6 +163,9 @@ declare const PreviewSchema: z.ZodObject<{
     } & {
         credits_cents: z.ZodNumber;
         price_cents: z.ZodNumber;
+        list_price_cents: z.ZodOptional<z.ZodNumber>;
+        monthly_list_price_cents: z.ZodOptional<z.ZodNumber>;
+        monthly_price_cents: z.ZodOptional<z.ZodNumber>;
         seat_summary: z.ZodObject<{
             seat_count: z.ZodNumber;
         } & {
@@ -164,8 +182,8 @@ declare const PreviewSchema: z.ZodObject<{
         }>;
     }, "strip", z.ZodTypeAny, {
         price_cents: number;
-        credits_cents: number;
         duration: "MONTHLY" | "ANNUAL";
+        credits_cents: number;
         seat_summary: {
             seat_count: number;
             total_cost_cents: number;
@@ -175,10 +193,13 @@ declare const PreviewSchema: z.ZodObject<{
         tier: "FREE" | "STANDARD" | "CREATOR" | "PRO" | "FOUNDERS_EDITION" | "TEAM" | "ENTERPRISE";
         period_end?: string | undefined;
         period_start?: string | undefined;
+        list_price_cents?: number | undefined;
+        monthly_list_price_cents?: number | undefined;
+        monthly_price_cents?: number | undefined;
     }, {
         price_cents: number;
-        credits_cents: number;
         duration: "MONTHLY" | "ANNUAL";
+        credits_cents: number;
         seat_summary: {
             seat_count: number;
             total_cost_cents: number;
@@ -188,23 +209,32 @@ declare const PreviewSchema: z.ZodObject<{
         tier: "FREE" | "STANDARD" | "CREATOR" | "PRO" | "FOUNDERS_EDITION" | "TEAM" | "ENTERPRISE";
         period_end?: string | undefined;
         period_start?: string | undefined;
+        list_price_cents?: number | undefined;
+        monthly_list_price_cents?: number | undefined;
+        monthly_price_cents?: number | undefined;
     }>;
     discounts: z.ZodOptional<z.ZodArray<z.ZodObject<{
         code: z.ZodString;
+        duration: z.ZodOptional<z.ZodEnum<["once", "repeating", "forever"]>>;
         kind: z.ZodEnum<["plan", "promotion"]>;
         name: z.ZodOptional<z.ZodString>;
     } & {
         amount_off_cents: z.ZodOptional<z.ZodNumber>;
+        duration_in_months: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         code: string;
         kind: "plan" | "promotion";
         name?: string | undefined;
         amount_off_cents?: number | undefined;
+        duration?: "once" | "repeating" | "forever" | undefined;
+        duration_in_months?: number | undefined;
     }, {
         code: string;
         kind: "plan" | "promotion";
         name?: string | undefined;
         amount_off_cents?: number | undefined;
+        duration?: "once" | "repeating" | "forever" | undefined;
+        duration_in_months?: number | undefined;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     effective_at: string;
@@ -216,8 +246,8 @@ declare const PreviewSchema: z.ZodObject<{
     is_immediate: boolean;
     new_plan: {
         price_cents: number;
-        credits_cents: number;
         duration: "MONTHLY" | "ANNUAL";
+        credits_cents: number;
         seat_summary: {
             seat_count: number;
             total_cost_cents: number;
@@ -227,6 +257,9 @@ declare const PreviewSchema: z.ZodObject<{
         tier: "FREE" | "STANDARD" | "CREATOR" | "PRO" | "FOUNDERS_EDITION" | "TEAM" | "ENTERPRISE";
         period_end?: string | undefined;
         period_start?: string | undefined;
+        list_price_cents?: number | undefined;
+        monthly_list_price_cents?: number | undefined;
+        monthly_price_cents?: number | undefined;
     };
     transition_type: "new_subscription" | "upgrade" | "downgrade" | "duration_change";
     currency?: string | undefined;
@@ -235,10 +268,11 @@ declare const PreviewSchema: z.ZodObject<{
     quote_id?: string | undefined;
     quote_version?: number | undefined;
     amount_due_cents?: number | undefined;
+    balance_applied_cents?: number | undefined;
     current_plan?: {
         price_cents: number;
-        credits_cents: number;
         duration: "MONTHLY" | "ANNUAL";
+        credits_cents: number;
         seat_summary: {
             seat_count: number;
             total_cost_cents: number;
@@ -248,18 +282,26 @@ declare const PreviewSchema: z.ZodObject<{
         tier: "FREE" | "STANDARD" | "CREATOR" | "PRO" | "FOUNDERS_EDITION" | "TEAM" | "ENTERPRISE";
         period_end?: string | undefined;
         period_start?: string | undefined;
+        list_price_cents?: number | undefined;
+        monthly_list_price_cents?: number | undefined;
+        monthly_price_cents?: number | undefined;
     } | undefined;
     discounts?: {
         code: string;
         kind: "plan" | "promotion";
         name?: string | undefined;
         amount_off_cents?: number | undefined;
+        duration?: "once" | "repeating" | "forever" | undefined;
+        duration_in_months?: number | undefined;
     }[] | undefined;
     payment_method_configuration_id?: string | undefined;
+    proration_remaining_cents?: number | undefined;
+    proration_unused_cents?: number | undefined;
     reason?: string | undefined;
     renewal_amount_cents?: number | undefined;
     renewal_at?: string | undefined;
     requires_reactivation_confirmation?: boolean | undefined;
+    subtotal_cents?: number | undefined;
 }, {
     effective_at: string;
     allowed: boolean;
@@ -270,8 +312,8 @@ declare const PreviewSchema: z.ZodObject<{
     is_immediate: boolean;
     new_plan: {
         price_cents: number;
-        credits_cents: number;
         duration: "MONTHLY" | "ANNUAL";
+        credits_cents: number;
         seat_summary: {
             seat_count: number;
             total_cost_cents: number;
@@ -281,6 +323,9 @@ declare const PreviewSchema: z.ZodObject<{
         tier: "FREE" | "STANDARD" | "CREATOR" | "PRO" | "FOUNDERS_EDITION" | "TEAM" | "ENTERPRISE";
         period_end?: string | undefined;
         period_start?: string | undefined;
+        list_price_cents?: number | undefined;
+        monthly_list_price_cents?: number | undefined;
+        monthly_price_cents?: number | undefined;
     };
     transition_type: "new_subscription" | "upgrade" | "downgrade" | "duration_change";
     currency?: string | undefined;
@@ -289,10 +334,11 @@ declare const PreviewSchema: z.ZodObject<{
     quote_id?: string | undefined;
     quote_version?: number | undefined;
     amount_due_cents?: number | undefined;
+    balance_applied_cents?: number | undefined;
     current_plan?: {
         price_cents: number;
-        credits_cents: number;
         duration: "MONTHLY" | "ANNUAL";
+        credits_cents: number;
         seat_summary: {
             seat_count: number;
             total_cost_cents: number;
@@ -302,18 +348,26 @@ declare const PreviewSchema: z.ZodObject<{
         tier: "FREE" | "STANDARD" | "CREATOR" | "PRO" | "FOUNDERS_EDITION" | "TEAM" | "ENTERPRISE";
         period_end?: string | undefined;
         period_start?: string | undefined;
+        list_price_cents?: number | undefined;
+        monthly_list_price_cents?: number | undefined;
+        monthly_price_cents?: number | undefined;
     } | undefined;
     discounts?: {
         code: string;
         kind: "plan" | "promotion";
         name?: string | undefined;
         amount_off_cents?: number | undefined;
+        duration?: "once" | "repeating" | "forever" | undefined;
+        duration_in_months?: number | undefined;
     }[] | undefined;
     payment_method_configuration_id?: string | undefined;
+    proration_remaining_cents?: number | undefined;
+    proration_unused_cents?: number | undefined;
     reason?: string | undefined;
     renewal_amount_cents?: number | undefined;
     renewal_at?: string | undefined;
     requires_reactivation_confirmation?: boolean | undefined;
+    subtotal_cents?: number | undefined;
 }>;
 /**
  * The quote the server returns for a plan change, in the generated field names.

package/dist/core/billing/subscriptionCommands.js

@@ -16,6 +16,7 @@ import { z } from 'zod';
 import { matchesServerCode } from './billingContracts.js';
 import { validateActionUrl } from './operationState.js';
 import { readValidatedBillingResponse } from './sharedRead.js';
+import { wireCents } from './wireCents.js';
 export const SUBSCRIBE_ROUTE = '/billing/subscribe';
 export const RESUBSCRIBE_ROUTE = '/billing/subscription/resubscribe';
 export const CANCEL_SUBSCRIPTION_ROUTE = '/billing/subscription/cancel';
@@ -26,35 +27,37 @@ const NO_ACTIVE_SUBSCRIPTION_SERVER_CODE = 'NO_ACTIVE_SUBSCRIPTION';
 const REACTIVATION_CONFIRMATION_REQUIRED_SERVER_CODE = 'REACTIVATION_CONFIRMATION_REQUIRED';
 const NOT_SCHEDULED_FOR_CANCELLATION_SERVER_CODE = 'NOT_SCHEDULED_FOR_CANCELLATION';
 const ALREADY_CANCELED_SERVER_CODE = 'ALREADY_CANCELED';
-/**
- * The generated schema coerces every int64 to a `bigint`, which no caller can
- * add to a price or hand to a currency formatter — and the generated *type*
- * for the same field is a `number`. Money on this route is bounded to cents
- * well inside the JavaScript-safe range, so the cents are read as numbers, the
- * way `capabilities` reads `revision` — as whole units of currency that
- * survive arithmetic, since these amounts are displayed as prices and
- * confirmed as charges.
- */
-const cents = z.number().int().safe();
+const SUBSCRIPTION_QUOTE_STALE_SERVER_CODE = 'SUBSCRIPTION_QUOTE_STALE';
+const SUBSCRIPTION_CHANGE_IN_PROGRESS_SERVER_CODE = 'SUBSCRIPTION_CHANGE_IN_PROGRESS';
 const PlanInfoSchema = zPreviewPlanInfo.extend({
-    credits_cents: cents,
-    price_cents: cents,
+    credits_cents: wireCents,
+    price_cents: wireCents,
+    list_price_cents: wireCents.optional(),
+    monthly_list_price_cents: wireCents.optional(),
+    monthly_price_cents: wireCents.optional(),
     seat_summary: zPreviewPlanInfo.shape.seat_summary.extend({
-        total_cost_cents: cents,
-        total_credits_cents: cents
+        total_cost_cents: wireCents,
+        total_credits_cents: wireCents
     })
 });
 const PreviewSchema = zPreviewSubscribeResponse.extend({
-    amount_due_cents: cents.optional(),
-    cost_next_period_cents: cents,
-    cost_today_cents: cents,
-    credits_next_period_cents: cents,
-    credits_today_cents: cents,
-    renewal_amount_cents: cents.optional(),
+    amount_due_cents: wireCents.optional(),
+    cost_next_period_cents: wireCents,
+    cost_today_cents: wireCents,
+    credits_next_period_cents: wireCents,
+    credits_today_cents: wireCents,
+    renewal_amount_cents: wireCents.optional(),
+    subtotal_cents: wireCents.optional(),
+    balance_applied_cents: wireCents.optional(),
+    proration_remaining_cents: wireCents.optional(),
+    proration_unused_cents: wireCents.optional(),
     current_plan: PlanInfoSchema.optional(),
     new_plan: PlanInfoSchema,
     discounts: z
-        .array(zSubscriptionDiscount.extend({ amount_off_cents: cents.optional() }))
+        .array(zSubscriptionDiscount.extend({
+        amount_off_cents: wireCents.optional(),
+        duration_in_months: wireCents.optional()
+    }))
         .optional()
 });
 const ALREADY_HELD = {
@@ -65,23 +68,33 @@ function coded(code) {
     return { status: 'error', code };
 }
 /**
- * A server code the caller's request already satisfies is a success, but
- * only from a 4xx: a 5xx echoing the code is an upstream failure that
- * happens to carry it, and the requested state cannot be assumed to hold.
+ * A server code is trusted as state only from a 4xx: a 5xx echoing the code
+ * is an upstream failure that happens to carry it, and the state it names
+ * cannot be assumed to hold.
  */
-function alreadyInRequestedState(failure, serverCode) {
+function refusedWith(failure, serverCode) {
     return (matchesServerCode(failure, serverCode) &&
         failure.httpStatus !== undefined &&
         failure.httpStatus >= 400 &&
         failure.httpStatus < 500);
 }
+/**
+ * The server's refusal because another subscription operation is still open
+ * is the same answer the lifecycle gives when it sees that operation first.
+ */
+function refusedWhilePending(failure) {
+    return refusedWith(failure, SUBSCRIPTION_CHANGE_IN_PROGRESS_SERVER_CODE)
+        ? { ...failure, code: 'OPERATION_ALREADY_PENDING' }
+        : failure;
+}
 function mapServerCode(failure, alreadyHeldCode) {
-    if (alreadyInRequestedState(failure, alreadyHeldCode)) {
+    // A server code the caller's request already satisfies is a success.
+    if (refusedWith(failure, alreadyHeldCode)) {
         return { status: 'already_held' };
     }
     return matchesServerCode(failure, NO_ACTIVE_SUBSCRIPTION_SERVER_CODE)
         ? coded('NO_ACTIVE_SUBSCRIPTION')
-        : failure;
+        : refusedWhilePending(failure);
 }
 function dropEmpty(value) {
     return value === '' ? undefined : value;
@@ -159,9 +172,12 @@ export function createBillingCommands(options) {
         const key = idempotencyKey();
         const response = await post(SUBSCRIBE_ROUTE, { ...input, idempotency_key: key }, (body) => zSubscribeResponse.safeParse(body), key);
         if (response.status === 'error') {
-            return matchesServerCode(response, REACTIVATION_CONFIRMATION_REQUIRED_SERVER_CODE)
-                ? coded('REACTIVATION_CONFIRMATION_REQUIRED')
-                : response;
+            if (matchesServerCode(response, REACTIVATION_CONFIRMATION_REQUIRED_SERVER_CODE)) {
+                return coded('REACTIVATION_CONFIRMATION_REQUIRED');
+            }
+            return refusedWith(response, SUBSCRIPTION_QUOTE_STALE_SERVER_CODE)
+                ? coded('QUOTE_STALE')
+                : refusedWhilePending(response);
         }
         const { billing_op_id, status, payment_method_url } = response.value.data;
         if (status !== 'needs_payment_method') {

package/dist/core/billing/topup.d.ts

@@ -11,6 +11,26 @@ export declare const TOPUP_ROUTE = "/billing/topup";
  * through a webhook, so completion is the host's return plus a balance watch.
  */
 export declare const TOPUP_CHECKOUT_ROUTE = "/billing/topup/checkout";
+/** A read the backend shapes as a POST: nothing is charged or reserved. */
+export declare const TOPUP_QUOTE_ROUTE = "/billing/topup/quote";
+/**
+ * What the server says an amount buys. `credits` is the server's display
+ * count; `expiresAt` is when the grant would lapse, which the server may
+ * move, so a host never states the expiry policy itself.
+ */
+export interface TopupQuote {
+    readonly amountCents: number;
+    readonly credits: number;
+    readonly expiresAt: string;
+}
+export type TopupQuoteResult = {
+    readonly status: 'ok';
+    readonly value: TopupQuote;
+} | BillingFailure | TopupNotAvailable | TopupInvalidAmount;
+export interface QuoteTopupInput {
+    readonly amountCents: number;
+    readonly signal?: AbortSignal;
+}
 type OperationIn<P extends BillingOperationState['phase']> = Extract<BillingOperationState, {
     readonly phase: P;
 }>;
@@ -101,6 +121,12 @@ export interface TopupCommandOptions {
     readonly idempotencyKey?: () => string;
 }
 export interface TopupCommand {
+    /**
+     * Quotes an amount without starting anything. It does not check the plan
+     * tier or the payment method, so a quote does not promise the top-up will
+     * go through.
+     */
+    quoteTopup: (input: QuoteTopupInput) => Promise<TopupQuoteResult>;
     createTopupCheckout: (input: CreateTopupCheckoutInput) => Promise<TopupResult>;
     /**
      * The route Workshop and Platform ship on today. Unlike