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

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

@@ -31,7 +31,7 @@ export type { PaymentMethodsReadOptions, PaymentMethodsReader, PaymentMethodsRea
 export { PAYMENT_METHODS_ROUTE, createPaymentMethodsReader } from './paymentMethods.js';
 export type { BillingStatusData, BillingStatusReader, BillingStatusReaderOptions, BillingStatusReadOptions, BillingStatusScope, BillingStatusSnapshot } from './status.js';
 export { BILLING_STATUS_ROUTE, createBillingStatusReader } from './status.js';
-export type { BillingAuthenticationState, BillingDeclineReason, BillingOpStatus, BillingOperationEvent, BillingOperationIdentity, BillingOperationReceipt, BillingOperationKind, BillingOperationPhase, BillingOperationServerPhase, BillingOperationState, BillingPresentation, BillingPresentationState, BillingRecoveryAction, EmbeddedChallenge, FailedBillingOperation, HostedBillingDestination, PendingBillingOperation, SucceededBillingOperation } from './operationState.js';
+export type { BillingAuthenticationState, BillingChargeBreakdown, BillingChargeReason, BillingDeclineReason, BillingOpStatus, BillingOperationEvent, BillingOperationIdentity, BillingOperationReceipt, BillingOperationKind, BillingOperationPhase, BillingOperationServerPhase, BillingOperationState, BillingPresentation, BillingPresentationState, BillingRecoveryAction, EmbeddedChallenge, FailedBillingOperation, HostedBillingDestination, PendingBillingOperation, SucceededBillingOperation } from './operationState.js';
 export { isBlockedOnCustomerPhase, isGrantLanding, isTerminal, reduceBillingOperation, validateActionUrl } from './operationState.js';
 export { OPERATION_POLL_BUDGET, OPERATION_POLL_TIMING, customerCanActHere, hasExhaustedPollBudget, isParkedOnCustomer, nextPollDelayMs, pendingOperationActionHold, pollBudgetMs } from './operationPolicy.js';
 export type { CustomerActionHold } from './operationPolicy.js';
@@ -41,11 +41,12 @@ export type { PresentationRoutingInput } from './presentation.js';
 export { selectBillingPresentation } from './presentation.js';
 export type { BillingOperationFailureCategory, BillingOperationLifecycle, BillingOperationLifecycleOptions, BillingOperationTelemetryEvent, BillingRecoverOptions, IssuedBillingOperation, PresentationSwitchOutcome } from './operationLifecycle.js';
 export { createBillingOperationLifecycle, operationRoute } from './operationLifecycle.js';
-export { BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
+export { BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT, BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
+export * from './telemetry/index.js';
 export type { EmbeddedChallengeOutcome, EmbeddedChallengePort } from './challengeDriver.js';
 export { driveEmbeddedChallenge } from './challengeDriver.js';
 export { readBillingErrorCode, readBillingErrorMessage } from './billingErrorBody.js';
-export type { BillingCommands, BillingCommandsOptions, PaymentPortalResult, PreviewSubscribeInput, PreviewSubscribeOptions, PreviewSubscribeResult, SubscribeInput, SubscriptionCommandCode, SubscriptionCommandFailure, SubscriptionCommandOutcome, SubscriptionCommandResult, SubscriptionPreview, TerminalBillingOperation } from './subscriptionCommands.js';
+export type { BillingCommands, BillingCommandsOptions, CancelOperationResult, CancelRefusalCode, PaymentPortalResult, PreviewSubscribeInput, PreviewSubscribeOptions, PreviewSubscribeResult, SubscribeInput, SubscriptionCommandCode, SubscriptionCommandFailure, SubscriptionCommandOutcome, SubscriptionCommandResult, SubscriptionPreview, TerminalBillingOperation } from './subscriptionCommands.js';
 export { CANCEL_SUBSCRIPTION_ROUTE, PAYMENT_PORTAL_ROUTE, PREVIEW_SUBSCRIBE_ROUTE, RESUBSCRIBE_ROUTE, SUBSCRIBE_ROUTE, createBillingCommands } from './subscriptionCommands.js';
 export type { HostPaymentStep, PaymentProjection, PaymentReasonKey, PaymentStep } from './paymentProjection.js';
 export { awaitsHostedAction, projectPaymentStep } from './paymentProjection.js';

package/dist/core/billing/index.js

@@ -15,7 +15,8 @@ export { OPERATION_POLL_BUDGET, OPERATION_POLL_TIMING, customerCanActHere, hasEx
 export { OPERATION_POINTER_MAX_AGE_MS, createOperationPointerStore, operationPointerKey } from './operationPointer.js';
 export { selectBillingPresentation } from './presentation.js';
 export { createBillingOperationLifecycle, operationRoute } from './operationLifecycle.js';
-export { BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
+export { BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT, BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
+export * from './telemetry/index.js';
 export { driveEmbeddedChallenge } from './challengeDriver.js';
 export { readBillingErrorCode, readBillingErrorMessage } from './billingErrorBody.js';
 export { CANCEL_SUBSCRIPTION_ROUTE, PAYMENT_PORTAL_ROUTE, PREVIEW_SUBSCRIBE_ROUTE, RESUBSCRIBE_ROUTE, SUBSCRIBE_ROUTE, createBillingCommands } from './subscriptionCommands.js';

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

@@ -16,11 +16,13 @@
  * wiring onto the scope source, the scope tracker, and the generated
  * contract is new.
  */
-import { BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
+import { BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT, BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
 import type { BillingResult, BillingTransport } from './billingContracts.js';
 import type { BillingScope, BillingScopeSource } from './billingScope.js';
 import type { BillingOperationPointerStorage } from './operationPointer.js';
 import type { BillingDeclineReason, BillingOperationKind, BillingOperationState, BillingPresentation, HostedBillingDestination } from './operationState.js';
+import type { CheckoutHostedStep, CheckoutRedirectNavigation } from './telemetry/checkoutRedirectEvent.js';
+import type { CheckoutMethodKind } from './telemetry/checkoutJourney.js';
 import type { BillingStatusReader } from './status.js';
 export declare function operationRoute(operationId: string): string;
 /** What a command learned from the backend when it issued the operation. */
@@ -32,18 +34,31 @@ export interface IssuedBillingOperation {
     readonly clientSecret?: string;
 }
 export type BillingOperationFailureCategory = 'provider_decline' | 'api_rejected' | 'poll_timeout' | 'reconciliation_needed' | 'stale_operation';
-export interface BillingOperationTelemetryEvent {
-    readonly name: (typeof BILLING_OPERATION_TELEMETRY_EVENT)[keyof typeof BILLING_OPERATION_TELEMETRY_EVENT];
+type HostedStepEventName = typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.redirectStarted | typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned;
+type BillingOperationTelemetryEventName = Exclude<(typeof BILLING_OPERATION_TELEMETRY_EVENT)[keyof typeof BILLING_OPERATION_TELEMETRY_EVENT] | (typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT)[keyof typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT], HostedStepEventName>;
+/** A hosted step this tab handed the customer to. */
+interface HostedStepVisit {
+    readonly destination: HostedBillingDestination;
+    readonly step: CheckoutHostedStep;
+    readonly navigation: CheckoutRedirectNavigation;
+    readonly method_kind?: CheckoutMethodKind;
+}
+interface BillingOperationTelemetryBase {
     readonly billing_op_id: string;
     readonly operation_type: BillingOperationKind;
     readonly presentation: BillingPresentation;
     /** True when this tab reattached to an operation it did not issue. */
     readonly resumed: boolean;
+}
+export type BillingOperationTelemetryEvent = BillingOperationTelemetryBase & ({
+    readonly name: BillingOperationTelemetryEventName;
     readonly failure_category?: BillingOperationFailureCategory;
     readonly decline_reason?: BillingDeclineReason;
     /** From the attempt's start, so a resumed operation reports its whole life. */
     readonly duration_ms?: number;
-}
+} | (HostedStepVisit & {
+    readonly name: HostedStepEventName;
+}));
 export type PresentationSwitchOutcome = 'switched' | 'unchanged'
 /** The server has offered no hosted continuation yet. */
  | 'no_hosted_url'
@@ -97,6 +112,12 @@ export interface BillingOperationLifecycle {
     wake: () => void;
     /** Moves the operation between presentations under the same id. */
     switchPresentation: (operationId: string, presentation: BillingPresentation) => PresentationSwitchOutcome;
+    /**
+     * The host opened the operation's hosted step. A redirect is remembered in
+     * the pointer, so the page it returns to reports the return; a new tab
+     * reports it on the next wake.
+     */
+    reportHostedStepOpened: (operationId: string, navigation: CheckoutRedirectNavigation, methodKind?: CheckoutMethodKind) => void;
     /** The host began driving the operation's challenge; polling pauses until it settles. */
     reportChallengeStarted: (operationId: string) => void;
     reportChallengeSettled: (operationId: string, outcome: 'completed' | 'failed') => void;
@@ -108,3 +129,4 @@ export interface BillingOperationLifecycle {
     dispose: () => void;
 }
 export declare function createBillingOperationLifecycle(options: BillingOperationLifecycleOptions): BillingOperationLifecycle;
+export {};

package/dist/core/billing/operationLifecycle.js

@@ -16,11 +16,12 @@
  * wiring onto the scope source, the scope tracker, and the generated
  * contract is new.
  */
-import { BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
+import { BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT, BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
 import { createBillingScopeTracker } from './billingScope.js';
 import { NO_POINTER_STORE, createOperationPointerStore } from './operationPointer.js';
 import { hasExhaustedPollBudget, isWaitingOnCustomerWithoutAction, nextPollDelayMs } from './operationPolicy.js';
 import { BillingOpStatusSchema, isGrantLanding, isTerminal, reduceBillingOperation, validateActionUrl } from './operationState.js';
+import { paymentFrictionBetween } from './paymentFriction.js';
 import { selectBillingPresentation } from './presentation.js';
 import { readValidatedBillingResponse } from './sharedRead.js';
 /** Settled, but a later read may still change what the operation reports. */
@@ -42,6 +43,18 @@ const OPERATION_ALREADY_PENDING = {
     status: 'error',
     code: 'OPERATION_ALREADY_PENDING'
 };
+/** The attempt a pointer remembers, picked up again by this tab. */
+function resumedFrom(pointer) {
+    return {
+        presentation: pointer.presentation,
+        attemptStartedAt: pointer.attemptStartedAt,
+        resumed: true,
+        awaitedHere: pointer.awaited === true,
+        ...(pointer.redirect === undefined
+            ? {}
+            : { returnedFrom: pointer.redirect })
+    };
+}
 function continuationOf(issued) {
     return {
         ...(issued.actionUrl === undefined ? {} : { actionUrl: issued.actionUrl }),
@@ -95,6 +108,23 @@ function failureCategoryFor(state) {
             return 'stale_operation';
     }
 }
+const FRICTION_EVENT_NAME = {
+    challenge_required: BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeRequired,
+    challenge_completed: BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeCompleted,
+    challenge_failed: BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeFailed
+};
+/** What the hosted page asks of the customer, from what the server waits on. */
+function hostedStepOf(state) {
+    if (state.authenticationState === 'requires_action' ||
+        (state.presentation === 'embedded' && state.challenge !== undefined)) {
+        return 'authentication';
+    }
+    if (state.serverPhase === 'awaiting_payment_method')
+        return 'payment_method';
+    if (state.serverPhase === 'awaiting_invoice_payment')
+        return 'invoice_payment';
+    return 'checkout';
+}
 /** The pause is this tab's own challenge on screen; a hosted page never pauses. */
 function isDrivingChallenge(state) {
     return (state.presentation === 'embedded' &&
@@ -155,11 +185,28 @@ export function createBillingOperationLifecycle(options) {
             duration_ms: now() - state.attemptStartedAt
         });
     }
+    function emitFrictionTelemetry(record, before) {
+        const state = record.state;
+        for (const signal of paymentFrictionBetween(before, state)) {
+            onTelemetry?.({
+                name: FRICTION_EVENT_NAME[signal.stage],
+                billing_op_id: state.id,
+                operation_type: state.kind,
+                presentation: state.presentation,
+                resumed: record.resumed,
+                ...('declineReason' in signal && signal.declineReason !== undefined
+                    ? { decline_reason: signal.declineReason }
+                    : {})
+            });
+        }
+    }
     function dispatch(record, event) {
-        const next = reduceBillingOperation(record.state, event);
-        if (next === record.state)
+        const before = record.state;
+        const next = reduceBillingOperation(before, event);
+        if (next === before)
             return;
         record.state = next;
+        emitFrictionTelemetry(record, before);
         if (isTerminal(next)) {
             stopTimer(record);
             pointers.settle(next);
@@ -195,13 +242,28 @@ export function createBillingOperationLifecycle(options) {
         record.inFlightPoll = request;
         return request;
     }
-    function writePointer(scope, state) {
+    function savedRedirect(scope, operationId) {
+        const saved = pointers.read(scope);
+        return saved?.operationId === operationId ? saved.redirect : undefined;
+    }
+    function writePointer(scope, state, redirect) {
         pointers.write(scope, {
             operationId: state.id,
             kind: state.kind,
             presentation: state.presentation,
             attemptStartedAt: state.attemptStartedAt,
-            ...(state.awaitedHere ? { awaited: true } : {})
+            ...(state.awaitedHere ? { awaited: true } : {}),
+            ...(redirect === undefined ? {} : { redirect })
+        });
+    }
+    function emitHostedStepTelemetry(record, name, visit) {
+        onTelemetry?.({
+            name,
+            billing_op_id: record.state.id,
+            operation_type: record.state.kind,
+            presentation: record.state.presentation,
+            resumed: record.resumed,
+            ...visit
         });
     }
     function readOperation(operationId) {
@@ -292,6 +354,7 @@ export function createBillingOperationLifecycle(options) {
             waitingWithoutActionSince: undefined,
             timer: undefined,
             inFlightPoll: undefined,
+            awaitingReturn: undefined,
             settled,
             resolveSettled
         };
@@ -304,6 +367,13 @@ export function createBillingOperationLifecycle(options) {
             presentation: input.presentation,
             resumed: input.resumed
         });
+        emitFrictionTelemetry(record, undefined);
+        if (input.returnedFrom !== undefined) {
+            emitHostedStepTelemetry(record, BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned, {
+                ...input.returnedFrom,
+                navigation: 'redirect'
+            });
+        }
         startObserving(record, input, state);
         return record;
     }
@@ -450,10 +520,7 @@ export function createBillingOperationLifecycle(options) {
             id: pointer.operationId,
             kind: pointer.kind,
             context,
-            presentation: pointer.presentation,
-            attemptStartedAt: pointer.attemptStartedAt,
-            resumed: true,
-            awaitedHere: pointer.awaited === true
+            ...resumedFrom(pointer)
         };
     }
     // Unreachable is not "nothing pending": the pointer is the only evidence
@@ -470,10 +537,14 @@ export function createBillingOperationLifecycle(options) {
         const record = adopt({
             ...pending,
             context,
-            presentation: known?.presentation ?? routeFor(rail, pending),
-            attemptStartedAt: known?.attemptStartedAt ?? now(),
-            resumed: true,
-            awaitedHere: known?.awaited === true
+            ...(known === undefined
+                ? {
+                    presentation: routeFor(rail, pending),
+                    attemptStartedAt: now(),
+                    resumed: true,
+                    awaitedHere: false
+                }
+                : resumedFrom(known))
         }, includeSettled);
         return { status: 'ok', value: record.state };
     }
@@ -524,6 +595,7 @@ export function createBillingOperationLifecycle(options) {
     }
     function wake() {
         for (const record of operations.values()) {
+            reportReturnFromNewTab(record);
             if (record.state.phase !== 'pending')
                 continue;
             if (isDrivingChallenge(record.state))
@@ -561,11 +633,37 @@ export function createBillingOperationLifecycle(options) {
         if (refusal !== undefined)
             return refusal;
         dispatch(record, switchEvent(presentation));
-        writePointer(record.context.scope, record.state);
+        writePointer(record.context.scope, record.state, savedRedirect(record.context.scope, operationId));
         record.delayMs = undefined;
         schedule(record);
         return 'switched';
     }
+    function reportReturnFromNewTab(record) {
+        const visit = record.awaitingReturn;
+        if (visit === undefined)
+            return;
+        record.awaitingReturn = undefined;
+        emitHostedStepTelemetry(record, BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned, visit);
+    }
+    function reportHostedStepOpened(operationId, navigation, methodKind) {
+        const record = operations.get(operationId);
+        if (record === undefined || record.state.phase !== 'pending')
+            return;
+        const state = record.state;
+        const redirect = {
+            destination: state.presentation === 'hosted' ? state.hostedDestination : 'stripe',
+            step: hostedStepOf(state),
+            ...(methodKind === undefined ? {} : { method_kind: methodKind })
+        };
+        const visit = { ...redirect, navigation };
+        if (navigation === 'redirect') {
+            writePointer(record.context.scope, state, redirect);
+        }
+        else {
+            record.awaitingReturn = visit;
+        }
+        emitHostedStepTelemetry(record, BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.redirectStarted, visit);
+    }
     function reportChallengeStarted(operationId) {
         const record = operations.get(operationId);
         if (record === undefined)
@@ -594,6 +692,7 @@ export function createBillingOperationLifecycle(options) {
         recover,
         wake,
         switchPresentation,
+        reportHostedStepOpened,
         reportChallengeStarted,
         reportChallengeSettled,
         get: (operationId) => operations.get(operationId)?.state,

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

@@ -26,6 +26,20 @@ declare const PointerSchema: z.ZodObject<{
     awaited: z.ZodOptional<z.ZodLiteral<true>>;
     /** The end this tab saw it reach, kept only by a store that retains settled pointers. */
     settled: z.ZodOptional<z.ZodEnum<["succeeded", "reconciliation_needed"]>>;
+    /** The hosted step this page redirected to; the page it returns to reports the return. */
+    redirect: z.ZodOptional<z.ZodObject<{
+        destination: z.ZodEnum<["stripe", "billing_web"]>;
+        step: z.ZodEnum<["authentication", "payment_method", "invoice_payment", "checkout"]>;
+        method_kind: z.ZodOptional<z.ZodEnum<["card", "alipay", "other"]>>;
+    }, "strip", z.ZodTypeAny, {
+        step: "authentication" | "payment_method" | "invoice_payment" | "checkout";
+        destination: "stripe" | "billing_web";
+        method_kind?: "card" | "alipay" | "other" | undefined;
+    }, {
+        step: "authentication" | "payment_method" | "invoice_payment" | "checkout";
+        destination: "stripe" | "billing_web";
+        method_kind?: "card" | "alipay" | "other" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     kind: "cancel" | "subscription" | "topup";
     attemptStartedAt: number;
@@ -33,6 +47,11 @@ declare const PointerSchema: z.ZodObject<{
     operationId: string;
     awaited?: true | undefined;
     settled?: "succeeded" | "reconciliation_needed" | undefined;
+    redirect?: {
+        step: "authentication" | "payment_method" | "invoice_payment" | "checkout";
+        destination: "stripe" | "billing_web";
+        method_kind?: "card" | "alipay" | "other" | undefined;
+    } | undefined;
 }, {
     kind: "cancel" | "subscription" | "topup";
     attemptStartedAt: number;
@@ -40,6 +59,11 @@ declare const PointerSchema: z.ZodObject<{
     operationId: string;
     awaited?: true | undefined;
     settled?: "succeeded" | "reconciliation_needed" | undefined;
+    redirect?: {
+        step: "authentication" | "payment_method" | "invoice_payment" | "checkout";
+        destination: "stripe" | "billing_web";
+        method_kind?: "card" | "alipay" | "other" | undefined;
+    } | undefined;
 }>;
 export type BillingOperationPointer = z.infer<typeof PointerSchema>;
 export declare function operationPointerKey(scope: BillingScope): string;

package/dist/core/billing/operationPointer.js

@@ -19,7 +19,20 @@ const PointerSchema = z.object({
     /** This tab issued the operation and has not yet seen it succeed. */
     awaited: z.literal(true).optional(),
     /** The end this tab saw it reach, kept only by a store that retains settled pointers. */
-    settled: z.enum(['succeeded', 'reconciliation_needed']).optional()
+    settled: z.enum(['succeeded', 'reconciliation_needed']).optional(),
+    /** The hosted step this page redirected to; the page it returns to reports the return. */
+    redirect: z
+        .object({
+        destination: z.enum(['stripe', 'billing_web']),
+        step: z.enum([
+            'authentication',
+            'payment_method',
+            'invoice_payment',
+            'checkout'
+        ]),
+        method_kind: z.enum(['card', 'alipay', 'other']).optional()
+    })
+        .optional()
 });
 export function operationPointerKey(scope) {
     return `${POINTER_KEY_PREFIX}:${scope.userId}:${scope.workspaceId}`;

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

@@ -40,6 +40,7 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
                 duration: z.ZodOptional<z.ZodEnum<["once", "repeating", "forever"]>>;
                 kind: z.ZodEnum<["plan", "promotion"]>;
                 name: z.ZodOptional<z.ZodString>;
+                term: z.ZodOptional<z.ZodEnum<["this_payment", "first_month", "first_year", "months", "ongoing"]>>;
             } & {
                 amount_off_cents: z.ZodOptional<z.ZodNumber>;
                 duration_in_months: z.ZodOptional<z.ZodNumber>;
@@ -50,6 +51,7 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
                 amount_off_cents?: number | undefined;
                 duration?: "once" | "repeating" | "forever" | undefined;
                 duration_in_months?: number | undefined;
+                term?: "this_payment" | "first_month" | "first_year" | "months" | "ongoing" | undefined;
             }, {
                 code: string;
                 kind: "plan" | "promotion";
@@ -57,10 +59,11 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
                 amount_off_cents?: number | undefined;
                 duration?: "once" | "repeating" | "forever" | undefined;
                 duration_in_months?: number | undefined;
+                term?: "this_payment" | "first_month" | "first_year" | "months" | "ongoing" | undefined;
             }>>;
         }, "strip", z.ZodTypeAny, {
-            amount_cents: number;
             kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
             discount?: {
                 code: string;
                 kind: "plan" | "promotion";
@@ -68,10 +71,11 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
                 amount_off_cents?: number | undefined;
                 duration?: "once" | "repeating" | "forever" | undefined;
                 duration_in_months?: number | undefined;
+                term?: "this_payment" | "first_month" | "first_year" | "months" | "ongoing" | undefined;
             } | undefined;
         }, {
-            amount_cents: number;
             kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
             discount?: {
                 code: string;
                 kind: "plan" | "promotion";
@@ -79,6 +83,7 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
                 amount_off_cents?: number | undefined;
                 duration?: "once" | "repeating" | "forever" | undefined;
                 duration_in_months?: number | undefined;
+                term?: "this_payment" | "first_month" | "first_year" | "months" | "ongoing" | undefined;
             } | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
@@ -86,8 +91,8 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
         amount_charged_cents: number;
         prorated: boolean;
         reasons: {
-            amount_cents: number;
             kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
             discount?: {
                 code: string;
                 kind: "plan" | "promotion";
@@ -95,6 +100,7 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
                 amount_off_cents?: number | undefined;
                 duration?: "once" | "repeating" | "forever" | undefined;
                 duration_in_months?: number | undefined;
+                term?: "this_payment" | "first_month" | "first_year" | "months" | "ongoing" | undefined;
             } | undefined;
         }[];
     }, {
@@ -102,8 +108,8 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
         amount_charged_cents: number;
         prorated: boolean;
         reasons: {
-            amount_cents: number;
             kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
             discount?: {
                 code: string;
                 kind: "plan" | "promotion";
@@ -111,6 +117,7 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
                 amount_off_cents?: number | undefined;
                 duration?: "once" | "repeating" | "forever" | undefined;
                 duration_in_months?: number | undefined;
+                term?: "this_payment" | "first_month" | "first_year" | "months" | "ongoing" | undefined;
             } | undefined;
         }[];
     }>>;
@@ -133,8 +140,8 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
         amount_charged_cents: number;
         prorated: boolean;
         reasons: {
-            amount_cents: number;
             kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
             discount?: {
                 code: string;
                 kind: "plan" | "promotion";
@@ -142,6 +149,7 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
                 amount_off_cents?: number | undefined;
                 duration?: "once" | "repeating" | "forever" | undefined;
                 duration_in_months?: number | undefined;
+                term?: "this_payment" | "first_month" | "first_year" | "months" | "ongoing" | undefined;
             } | undefined;
         }[];
     } | undefined;
@@ -169,8 +177,8 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
         amount_charged_cents: number;
         prorated: boolean;
         reasons: {
-            amount_cents: number;
             kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
             discount?: {
                 code: string;
                 kind: "plan" | "promotion";
@@ -178,6 +186,7 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
                 amount_off_cents?: number | undefined;
                 duration?: "once" | "repeating" | "forever" | undefined;
                 duration_in_months?: number | undefined;
+                term?: "this_payment" | "first_month" | "first_year" | "months" | "ongoing" | undefined;
             } | undefined;
         }[];
     } | undefined;
@@ -188,6 +197,8 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
     retryable?: boolean | undefined;
 }>;
 export type BillingOpStatus = z.infer<typeof BillingOpStatusSchema>;
+export type BillingChargeBreakdown = NonNullable<BillingOpStatus['charge_breakdown']>;
+export type BillingChargeReason = BillingChargeBreakdown['reasons'][number];
 export type BillingOperationKind = 'subscription' | 'topup' | 'cancel';
 /**
  * Where the customer completes the operation: the challenge this tab drives
@@ -270,6 +281,7 @@ export type FailedBillingOperation = BillingOperationIdentity & {
  */
 export interface BillingOperationReceipt {
     readonly amountChargedCents?: number;
+    readonly chargeBreakdown?: BillingChargeBreakdown;
     readonly creditsAdded?: number;
     readonly plan?: NonNullable<BillingOpStatus['plan']>;
 }

package/dist/core/billing/operationState.js

@@ -11,26 +11,21 @@
  * so no server or payment-provider text can reach a consumer through this
  * state.
  */
-import { zBillingOpChargeBreakdown, zBillingOpChargeReason, zBillingOpStatusResponse, zSubscriptionDiscount } from '@comfyorg/ingest-types/zod';
+import { zBillingOpChargeBreakdown, zBillingOpChargeReason, zBillingOpStatusResponse } from '@comfyorg/ingest-types/zod';
 import { z } from 'zod';
+import { SubscriptionDiscountSchema } from './subscriptionDiscount.js';
 import { wireCents } from './wireCents.js';
+const ChargeBreakdownSchema = zBillingOpChargeBreakdown.extend({
+    amount_charged_cents: wireCents,
+    reasons: z.array(zBillingOpChargeReason.extend({
+        amount_cents: wireCents,
+        discount: SubscriptionDiscountSchema.optional()
+    }))
+});
 export const BillingOpStatusSchema = zBillingOpStatusResponse.extend({
     amount_charged_cents: wireCents.optional(),
     credits_added: wireCents.optional(),
-    charge_breakdown: zBillingOpChargeBreakdown
-        .extend({
-        amount_charged_cents: wireCents,
-        reasons: z.array(zBillingOpChargeReason.extend({
-            amount_cents: wireCents,
-            discount: zSubscriptionDiscount
-                .extend({
-                amount_off_cents: wireCents.optional(),
-                duration_in_months: wireCents.optional()
-            })
-                .optional()
-        }))
-    })
-        .optional()
+    charge_breakdown: ChargeBreakdownSchema.optional()
 });
 /**
  * The phases the contract defines as blocked on the customer. Neither advances
@@ -127,6 +122,9 @@ function receiptOf(status) {
         ...(status.amount_charged_cents === undefined
             ? {}
             : { amountChargedCents: status.amount_charged_cents }),
+        ...(status.charge_breakdown === undefined
+            ? {}
+            : { chargeBreakdown: status.charge_breakdown }),
         ...(status.credits_added === undefined
             ? {}
             : { creditsAdded: status.credits_added }),

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

@@ -0,0 +1,17 @@
+import type { BillingDeclineReason, BillingOperationState } from './operationState.js';
+export type PaymentFrictionSignal = {
+    readonly stage: 'challenge_required';
+} | {
+    readonly stage: 'challenge_completed';
+} | {
+    readonly stage: 'challenge_failed';
+    readonly declineReason?: BillingDeclineReason;
+};
+/**
+ * What one transition of a pending operation put in the customer's way: a
+ * challenge first required under a client secret, this tab's verdict on it,
+ * or a retryable decline with a reason the operation did not hold before.
+ * The first decline the server reports for a challenge this tab already saw
+ * fail is the same failure, so it is not reported twice.
+ */
+export declare function paymentFrictionBetween(before: BillingOperationState | undefined, after: BillingOperationState): readonly PaymentFrictionSignal[];

package/dist/core/billing/paymentFriction.js

@@ -0,0 +1,41 @@
+/**
+ * What one transition of a pending operation put in the customer's way: a
+ * challenge first required under a client secret, this tab's verdict on it,
+ * or a retryable decline with a reason the operation did not hold before.
+ * The first decline the server reports for a challenge this tab already saw
+ * fail is the same failure, so it is not reported twice.
+ */
+export function paymentFrictionBetween(before, after) {
+    if (after.phase !== 'pending')
+        return [];
+    const earlier = before?.phase === 'pending' ? before : undefined;
+    return [
+        ...challengeSignals(earlier?.challenge, after.challenge),
+        ...declineSignals(earlier, after)
+    ];
+}
+function challengeSignals(before, after) {
+    if (after === undefined)
+        return [];
+    if (after.clientSecret !== before?.clientSecret) {
+        return after.status === 'required' ? [{ stage: 'challenge_required' }] : [];
+    }
+    if (after.status === before.status)
+        return [];
+    if (after.status === 'completed')
+        return [{ stage: 'challenge_completed' }];
+    if (after.status === 'failed')
+        return [{ stage: 'challenge_failed' }];
+    return [];
+}
+function declineSignals(before, after) {
+    const reason = after.declineReason;
+    if (reason === undefined || reason === before?.declineReason)
+        return [];
+    const echoesFailedChallenge = after.presentation === 'embedded' &&
+        after.challenge?.status === 'failed' &&
+        before?.declineReason === undefined;
+    return echoesFailedChallenge
+        ? []
+        : [{ stage: 'challenge_failed', declineReason: reason }];
+}