@comfyorg/account-core 1.0.0-alpha.1 → 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

@@ -1,4 +1,4 @@
-import type { z } from 'zod';
+import { z } from 'zod';
 import type { BillingScope } from './billingScope.js';
 export declare const BillingOpStatusSchema: z.ZodObject<{
     action_url: z.ZodOptional<z.ZodString>;
@@ -26,6 +26,101 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
 } & {
     amount_charged_cents: z.ZodOptional<z.ZodNumber>;
     credits_added: z.ZodOptional<z.ZodNumber>;
+    charge_breakdown: z.ZodOptional<z.ZodObject<{
+        currency: z.ZodString;
+        prorated: z.ZodBoolean;
+    } & {
+        amount_charged_cents: z.ZodNumber;
+        reasons: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<["promo_code", "subscription_discount", "account_balance"]>;
+        } & {
+            amount_cents: z.ZodNumber;
+            discount: z.ZodOptional<z.ZodObject<{
+                code: z.ZodString;
+                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>;
+            }, "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;
+                term?: "this_payment" | "first_month" | "first_year" | "months" | "ongoing" | undefined;
+            }, {
+                code: string;
+                kind: "plan" | "promotion";
+                name?: string | undefined;
+                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, {
+            kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
+            discount?: {
+                code: string;
+                kind: "plan" | "promotion";
+                name?: string | undefined;
+                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;
+        }, {
+            kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
+            discount?: {
+                code: string;
+                kind: "plan" | "promotion";
+                name?: string | undefined;
+                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, {
+        currency: string;
+        amount_charged_cents: number;
+        prorated: boolean;
+        reasons: {
+            kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
+            discount?: {
+                code: string;
+                kind: "plan" | "promotion";
+                name?: string | undefined;
+                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;
+        }[];
+    }, {
+        currency: string;
+        amount_charged_cents: number;
+        prorated: boolean;
+        reasons: {
+            kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
+            discount?: {
+                code: string;
+                kind: "plan" | "promotion";
+                name?: string | undefined;
+                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;
+        }[];
+    }>>;
 }, "strip", z.ZodTypeAny, {
     status: "failed" | "pending" | "succeeded" | "reconciliation_needed";
     id: string;
@@ -40,6 +135,24 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
     payment_intent_client_secret?: string | undefined;
     amount_charged_cents?: number | undefined;
     authentication_state?: "requires_action" | "processing" | "failed_retryable" | "succeeded" | "reconciliation_needed" | undefined;
+    charge_breakdown?: {
+        currency: string;
+        amount_charged_cents: number;
+        prorated: boolean;
+        reasons: {
+            kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
+            discount?: {
+                code: string;
+                kind: "plan" | "promotion";
+                name?: string | undefined;
+                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;
     credits_added?: number | undefined;
     decline_reason?: "card_declined" | "insufficient_funds" | "expired_card" | "incorrect_cvc" | "authentication_required" | "authentication_failed" | "processing_error" | "payment_not_completed" | "generic" | undefined;
     phase?: "in_progress" | "awaiting_payment_method" | "awaiting_invoice_payment" | undefined;
@@ -59,6 +172,24 @@ export declare const BillingOpStatusSchema: z.ZodObject<{
     payment_intent_client_secret?: string | undefined;
     amount_charged_cents?: number | undefined;
     authentication_state?: "requires_action" | "processing" | "failed_retryable" | "succeeded" | "reconciliation_needed" | undefined;
+    charge_breakdown?: {
+        currency: string;
+        amount_charged_cents: number;
+        prorated: boolean;
+        reasons: {
+            kind: "promo_code" | "subscription_discount" | "account_balance";
+            amount_cents: number;
+            discount?: {
+                code: string;
+                kind: "plan" | "promotion";
+                name?: string | undefined;
+                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;
     credits_added?: number | undefined;
     decline_reason?: "card_declined" | "insufficient_funds" | "expired_card" | "incorrect_cvc" | "authentication_required" | "authentication_failed" | "processing_error" | "payment_not_completed" | "generic" | undefined;
     phase?: "in_progress" | "awaiting_payment_method" | "awaiting_invoice_payment" | undefined;
@@ -66,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
@@ -148,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,11 +11,21 @@
  * so no server or payment-provider text can reach a consumer through this
  * state.
  */
-import { zBillingOpStatusResponse } 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()
+    credits_added: wireCents.optional(),
+    charge_breakdown: ChargeBreakdownSchema.optional()
 });
 /**
  * The phases the contract defines as blocked on the customer. Neither advances
@@ -112,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[];