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

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

@@ -24,6 +24,8 @@ export declare const RESUBSCRIBE_ROUTE = "/billing/subscription/resubscribe";
 export declare const CANCEL_SUBSCRIPTION_ROUTE = "/billing/subscription/cancel";
 export declare const PAYMENT_PORTAL_ROUTE = "/billing/payment-portal";
 export declare const PREVIEW_SUBSCRIBE_ROUTE = "/billing/preview-subscribe";
+export declare function cancelOperationRoute(operationId: string): string;
+declare const CANCEL_REFUSAL_SERVER_CODES: readonly ["NOT_CANCELABLE", "PAYMENT_IN_FLIGHT"];
 export type SubscribeInput = z.infer<typeof zSubscribeRequest>;
 export type TerminalBillingOperation = Exclude<BillingOperationState, PendingBillingOperation>;
 /** Outcomes a subscription command adds to the shared `BillingErrorCode` set. */
@@ -64,6 +66,23 @@ export type SubscriptionCommandResult = {
     readonly status: 'ok';
     readonly value: SubscriptionCommandOutcome;
 } | SubscriptionCommandFailure;
+/**
+ * Why the server kept a payment it was asked to cancel. `PAYMENT_IN_FLIGHT`:
+ * the payment won the race and the operation will settle on its own.
+ * `NOT_CANCELABLE`: the operation is not one waiting on authentication.
+ */
+export type CancelRefusalCode = (typeof CANCEL_REFUSAL_SERVER_CODES)[number];
+/**
+ * The server's answer to cancelling a pending operation. `canceled`: dropped,
+ * nothing charged, also for one already discarded. `cancel_requested`: the
+ * cancel was delivered but has not settled; asking again is safe.
+ */
+export type CancelOperationResult = {
+    readonly status: 'canceled' | 'cancel_requested';
+} | {
+    readonly status: 'not_canceled';
+    readonly code: CancelRefusalCode;
+} | BillingFailure;
 export type PaymentPortalResult = {
     readonly status: 'ok';
     readonly value: {
@@ -90,6 +109,8 @@ declare const PreviewSchema: z.ZodObject<{
     cost_today_cents: z.ZodNumber;
     credits_next_period_cents: z.ZodNumber;
     credits_today_cents: z.ZodNumber;
+    credits_today: z.ZodOptional<z.ZodNumber>;
+    credits_next_period: z.ZodOptional<z.ZodNumber>;
     renewal_amount_cents: z.ZodOptional<z.ZodNumber>;
     subtotal_cents: z.ZodOptional<z.ZodNumber>;
     balance_applied_cents: z.ZodOptional<z.ZodNumber>;
@@ -218,6 +239,7 @@ declare const PreviewSchema: 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>;
@@ -228,6 +250,7 @@ declare const PreviewSchema: 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";
@@ -235,6 +258,7 @@ declare const PreviewSchema: 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;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     effective_at: string;
@@ -263,6 +287,7 @@ declare const PreviewSchema: z.ZodObject<{
     };
     transition_type: "new_subscription" | "upgrade" | "downgrade" | "duration_change";
     currency?: string | undefined;
+    reason?: string | undefined;
     promotion_code?: string | undefined;
     proration_at?: string | undefined;
     quote_id?: string | undefined;
@@ -293,15 +318,17 @@ declare const PreviewSchema: 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;
     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;
+    credits_today?: number | undefined;
+    credits_next_period?: number | undefined;
 }, {
     effective_at: string;
     allowed: boolean;
@@ -329,6 +356,7 @@ declare const PreviewSchema: z.ZodObject<{
     };
     transition_type: "new_subscription" | "upgrade" | "downgrade" | "duration_change";
     currency?: string | undefined;
+    reason?: string | undefined;
     promotion_code?: string | undefined;
     proration_at?: string | undefined;
     quote_id?: string | undefined;
@@ -359,15 +387,17 @@ declare const PreviewSchema: 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;
     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;
+    credits_today?: number | undefined;
+    credits_next_period?: number | undefined;
 }>;
 /**
  * The quote the server returns for a plan change, in the generated field names.
@@ -412,6 +442,12 @@ export interface BillingCommands {
     previewSubscribe: (input: PreviewSubscribeInput, options?: PreviewSubscribeOptions) => Promise<PreviewSubscribeResult>;
     resubscribe: () => Promise<SubscriptionCommandResult>;
     cancelSubscription: () => Promise<SubscriptionCommandResult>;
+    /**
+     * Asks the server to drop an operation still waiting on the customer's
+     * authentication. Any answer that names the operation's fate wakes the
+     * lifecycle, so the operation it follows catches up with the server.
+     */
+    cancelOperation: (operationId: string) => Promise<CancelOperationResult>;
     /** Returns the portal URL; the host decides how to open it. */
     openPaymentPortal: (input: {
         readonly returnUrl?: string;

package/dist/core/billing/subscriptionCommands.js

@@ -11,17 +11,22 @@
  * against the closed set named here; a code outside it reaches the caller only
  * as the transport's coded failure.
  */
-import { zCancelSubscriptionResponse2, zPaymentPortalResponse, zPreviewPlanInfo, zPreviewSubscribeRequest, zPreviewSubscribeResponse, zResubscribeResponse, zSubscribeRequest, zSubscribeResponse, zSubscriptionDiscount } from '@comfyorg/ingest-types/zod';
+import { zCancelBillingOpResponse, zCancelSubscriptionResponse2, zPaymentPortalResponse, zPreviewPlanInfo, zPreviewSubscribeRequest, zPreviewSubscribeResponse, zResubscribeResponse, zSubscribeRequest, zSubscribeResponse } from '@comfyorg/ingest-types/zod';
 import { z } from 'zod';
 import { matchesServerCode } from './billingContracts.js';
+import { operationRoute } from './operationLifecycle.js';
 import { validateActionUrl } from './operationState.js';
 import { readValidatedBillingResponse } from './sharedRead.js';
+import { SubscriptionDiscountSchema } from './subscriptionDiscount.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';
 export const PAYMENT_PORTAL_ROUTE = '/billing/payment-portal';
 export const PREVIEW_SUBSCRIBE_ROUTE = '/billing/preview-subscribe';
+export function cancelOperationRoute(operationId) {
+    return `${operationRoute(operationId)}/cancel`;
+}
 /** The closed set of `serverCode` values these commands act on. */
 const NO_ACTIVE_SUBSCRIPTION_SERVER_CODE = 'NO_ACTIVE_SUBSCRIPTION';
 const REACTIVATION_CONFIRMATION_REQUIRED_SERVER_CODE = 'REACTIVATION_CONFIRMATION_REQUIRED';
@@ -29,6 +34,10 @@ const NOT_SCHEDULED_FOR_CANCELLATION_SERVER_CODE = 'NOT_SCHEDULED_FOR_CANCELLATI
 const ALREADY_CANCELED_SERVER_CODE = 'ALREADY_CANCELED';
 const SUBSCRIPTION_QUOTE_STALE_SERVER_CODE = 'SUBSCRIPTION_QUOTE_STALE';
 const SUBSCRIPTION_CHANGE_IN_PROGRESS_SERVER_CODE = 'SUBSCRIPTION_CHANGE_IN_PROGRESS';
+const CANCEL_REFUSAL_SERVER_CODES = [
+    'NOT_CANCELABLE',
+    'PAYMENT_IN_FLIGHT'
+];
 const PlanInfoSchema = zPreviewPlanInfo.extend({
     credits_cents: wireCents,
     price_cents: wireCents,
@@ -46,6 +55,9 @@ const PreviewSchema = zPreviewSubscribeResponse.extend({
     cost_today_cents: wireCents,
     credits_next_period_cents: wireCents,
     credits_today_cents: wireCents,
+    /** Whole credits as granted. Not in ingest-types until cloud PR 11905 syncs. */
+    credits_today: wireCents.nonnegative().optional(),
+    credits_next_period: wireCents.nonnegative().optional(),
     renewal_amount_cents: wireCents.optional(),
     subtotal_cents: wireCents.optional(),
     balance_applied_cents: wireCents.optional(),
@@ -53,12 +65,7 @@ const PreviewSchema = zPreviewSubscribeResponse.extend({
     proration_unused_cents: wireCents.optional(),
     current_plan: PlanInfoSchema.optional(),
     new_plan: PlanInfoSchema,
-    discounts: z
-        .array(zSubscriptionDiscount.extend({
-        amount_off_cents: wireCents.optional(),
-        duration_in_months: wireCents.optional()
-    }))
-        .optional()
+    discounts: z.array(SubscriptionDiscountSchema).optional()
 });
 const ALREADY_HELD = {
     status: 'ok',
@@ -269,11 +276,24 @@ export function createBillingCommands(options) {
         }
         return { status: 'ok', value: { url } };
     }
+    async function cancelOperation(operationId) {
+        const response = await post(cancelOperationRoute(operationId), undefined, (body) => zCancelBillingOpResponse.safeParse(body));
+        if (response.status === 'error') {
+            const refusal = CANCEL_REFUSAL_SERVER_CODES.find((code) => refusedWith(response, code));
+            if (refusal === undefined)
+                return response;
+            lifecycle.wake();
+            return { status: 'not_canceled', code: refusal };
+        }
+        lifecycle.wake();
+        return { status: response.value.data.status };
+    }
     return {
         subscribe,
         previewSubscribe,
         resubscribe,
         cancelSubscription: () => settle('cancel', issueCancel),
+        cancelOperation,
         openPaymentPortal
     };
 }

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

@@ -0,0 +1,26 @@
+export declare const SubscriptionDiscountSchema: import("zod").ZodObject<{
+    code: import("zod").ZodString;
+    duration: import("zod").ZodOptional<import("zod").ZodEnum<["once", "repeating", "forever"]>>;
+    kind: import("zod").ZodEnum<["plan", "promotion"]>;
+    name: import("zod").ZodOptional<import("zod").ZodString>;
+    term: import("zod").ZodOptional<import("zod").ZodEnum<["this_payment", "first_month", "first_year", "months", "ongoing"]>>;
+} & {
+    amount_off_cents: import("zod").ZodOptional<import("zod").ZodNumber>;
+    duration_in_months: import("zod").ZodOptional<import("zod").ZodNumber>;
+}, "strip", import("zod").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;
+}>;

package/dist/core/billing/subscriptionDiscount.js

@@ -0,0 +1,6 @@
+import { zSubscriptionDiscount } from '@comfyorg/ingest-types/zod';
+import { wireCents } from './wireCents.js';
+export const SubscriptionDiscountSchema = zSubscriptionDiscount.extend({
+    amount_off_cents: wireCents.optional(),
+    duration_in_months: wireCents.optional()
+});

package/dist/core/billing/telemetry/billingTelemetryEvent.d.ts

@@ -0,0 +1,25 @@
+import type { CancelBillingEvent } from './cancelEvent.js';
+import type { CapabilityReadBillingEvent } from './capabilityReadEvent.js';
+import type { CheckoutChallengeBillingEvent } from './checkoutChallengeEvent.js';
+import type { CheckoutRedirectBillingEvent } from './checkoutRedirectEvent.js';
+import type { DowngradeToPersonalBillingEvent } from './downgradeToPersonalEvent.js';
+import type { EntryBillingEvent } from './entryEvent.js';
+import type { BillingOperationBillingEvent } from './operationEvent.js';
+import type { PortalBillingEvent } from './portalEvent.js';
+import type { ResubscribeBillingEvent } from './resubscribeEvent.js';
+import type { SubscriptionCheckoutBillingEvent } from './subscriptionCheckoutEvent.js';
+import type { TopupBillingEvent } from './topupEvent.js';
+import type { WebEntryBillingEvent } from './webEntryEvent.js';
+import type { WebHandoffBillingEvent } from './webHandoffEvent.js';
+import type { WebReturnBillingEvent } from './webReturnEvent.js';
+import type { WebSessionBillingEvent } from './webSessionEvent.js';
+export type BillingSurface = 'cloud_app' | 'billing_web';
+export type BillingClient = 'sdk' | 'legacy';
+export type BillingTelemetryEvent = {
+    /** The rail of the code that emitted the event; absent when the emitter does not know it. */
+    billing_client?: BillingClient;
+} & (CapabilityReadBillingEvent | SubscriptionCheckoutBillingEvent | BillingOperationBillingEvent | ResubscribeBillingEvent | TopupBillingEvent | DowngradeToPersonalBillingEvent | WebEntryBillingEvent | WebHandoffBillingEvent | WebReturnBillingEvent | WebSessionBillingEvent | EntryBillingEvent | CancelBillingEvent | PortalBillingEvent | CheckoutChallengeBillingEvent | CheckoutRedirectBillingEvent);
+type BillingTelemetryEventNameFor<T extends BillingTelemetryEvent> = T extends BillingTelemetryEvent ? `billing.${T['operation']}.${T['stage']}` : never;
+export type BillingTelemetryEventName = BillingTelemetryEventNameFor<BillingTelemetryEvent>;
+export declare function getBillingTelemetryEventName(event: BillingTelemetryEvent): BillingTelemetryEventName;
+export {};

package/dist/core/billing/telemetry/billingTelemetryEvent.js

@@ -0,0 +1,3 @@
+export function getBillingTelemetryEventName(event) {
+    return `billing.${event.operation}.${event.stage}`;
+}

package/dist/core/billing/telemetry/cancelEvent.d.ts

@@ -0,0 +1,19 @@
+import type { BillingFailed, BillingIntent } from './stages.js';
+import type { BillingCycle, SubscriptionCheckoutTier } from './vocabulary.js';
+type CancelAbandoned = {
+    stage: 'abandoned';
+    outcome: 'pending';
+};
+/**
+ * The customer's journey through a cancel flow, on any surface. The cancel
+ * request itself is `operation` events with `operation_type: 'cancel'`, so a
+ * flow ends in exactly one of those terminals, `abandoned`, or `failed` for a
+ * refusal before any operation exists.
+ */
+export type CancelBillingEvent = {
+    operation: 'cancel';
+    /** The plan being cancelled; absent when unknown. */
+    current_tier?: SubscriptionCheckoutTier;
+    cycle?: BillingCycle;
+} & (BillingIntent | CancelAbandoned | BillingFailed);
+export {};

package/dist/core/billing/telemetry/cancelEvent.js

@@ -0,0 +1 @@
+export {};

package/dist/core/billing/telemetry/capabilityReadEvent.d.ts

@@ -0,0 +1,4 @@
+import type { BillingFailed, BillingSucceeded } from './stages.js';
+export type CapabilityReadBillingEvent = {
+    operation: 'capability_read';
+} & (BillingSucceeded | Pick<BillingFailed, 'stage' | 'outcome'>);

package/dist/core/billing/telemetry/capabilityReadEvent.js

@@ -0,0 +1 @@
+export {};

package/dist/core/billing/telemetry/checkoutChallengeEvent.d.ts

@@ -0,0 +1,25 @@
+import type { BillingDeclineReason, BillingOperationKind, BillingPresentation } from '../operationState.js';
+/**
+ * Payment friction inside one operation: a bank challenge the customer must
+ * complete, the verdict this tab saw, and each retryable decline the server
+ * reports while the operation stays open. None of these settle the
+ * operation, so every stage stays `pending`. A failure with a
+ * `decline_reason` is the server's retryable decline; one without is this
+ * tab's own challenge verdict.
+ */
+export type CheckoutChallengeBillingEvent = {
+    operation: 'checkout';
+    outcome: 'pending';
+    billing_op_id: string;
+    operation_type: BillingOperationKind;
+    presentation: BillingPresentation;
+    /** True when this tab reattached to an operation it did not issue. */
+    resumed?: boolean;
+} & ({
+    stage: 'challenge_required';
+} | {
+    stage: 'challenge_completed';
+} | {
+    stage: 'challenge_failed';
+    decline_reason?: BillingDeclineReason;
+});

package/dist/core/billing/telemetry/checkoutChallengeEvent.js

@@ -0,0 +1 @@
+export {};

package/dist/core/billing/telemetry/checkoutJourney.d.ts

@@ -0,0 +1,176 @@
+import type { CapabilityDenialReason } from '../capabilityDenials.js';
+import type { BillingSurface } from './billingTelemetryEvent.js';
+import type { BillingTelemetryErrorCode, BillingTelemetryFailureCategory } from './stages.js';
+import type { PaymentIntentSource } from './vocabulary.js';
+/**
+ * Checkout-journey lifecycle events for the embedded-checkout rollout.
+ *
+ * These intermediate stages are kept deliberately separate from the terminal
+ * billing taxonomy above (`billing.<operation>.<stage>`): entry, preview, and
+ * Payment Element observations are client observations of progress, never
+ * business success/failure/timeout. They share one frozen journey context so
+ * the two rollout arms can be compared on the same denominator.
+ */
+export declare const CHECKOUT_JOURNEY_SCHEMA_VERSION = 1;
+export type CheckoutJourneyArm = 'control' | 'treatment';
+export type CheckoutAssignmentStatus = 'resolved' | 'unavailable';
+export type CheckoutUiMode = 'embedded' | 'full_page' | 'hosted' | 'unknown';
+export type CheckoutEntryFlow = 'initial_subscription' | 'paid_upgrade' | 'topup' | 'other' | 'unknown';
+export type CheckoutEntrySource = 'pricing' | 'deep_link' | 'recovery' | 'settings_billing' | 'other' | 'unknown' | 'agent_paywall';
+type CheckoutElementPhase = 'init' | 'mount' | 'update';
+/** Which Stripe element in the shared group the observation came from. */
+type CheckoutElementKind = 'payment' | 'address';
+type CheckoutSubmitPhase = 'validation' | 'token_creation';
+/**
+ * The frozen arm assignment. A resolved assignment always carries an arm; an
+ * unavailable one never does, so an unknown assignment cannot masquerade as a
+ * resolved `control`. Encoded as a discriminated union so the invariant is a
+ * compile-time guarantee rather than a convention.
+ */
+type CheckoutJourneyAssignment = {
+    assignment_status: 'resolved';
+    assigned_arm: CheckoutJourneyArm;
+} | {
+    assignment_status: 'unavailable';
+    assigned_arm?: never;
+};
+/**
+ * Non-sensitive entry context frozen at journey creation and replayed on every
+ * journey event.
+ */
+export type CheckoutJourneyContext = {
+    checkout_journey_id: string;
+    /** UTC ISO-8601 timestamp captured at common intent, preserved across reload. */
+    checkout_entered_at: string;
+    ui_mode?: CheckoutUiMode;
+    entry_flow: CheckoutEntryFlow;
+    entry_source: CheckoutEntrySource;
+    billing_op_id?: string;
+} & CheckoutJourneyAssignment;
+type CheckoutJourneyEntered = {
+    phase: 'entered';
+    /** The click-time entry the link carried, at the shared source grain. */
+    payment_intent_source?: PaymentIntentSource;
+};
+type CheckoutJourneyPreviewReady = {
+    phase: 'preview_ready';
+    preview_revision?: string;
+};
+/** Refusals the checkout names itself, beside the codes the billing events share. */
+type CheckoutPreviewErrorCode = 'quote_not_allowed' | 'plan_unavailable';
+type CheckoutJourneyPreviewFailed = {
+    phase: 'preview_failed';
+    failure_category: BillingTelemetryFailureCategory;
+    error_code?: BillingTelemetryErrorCode | CheckoutPreviewErrorCode;
+    /** Why the capabilities read refused this checkout. */
+    denial_reason?: CapabilityDenialReason;
+    preview_revision?: string;
+};
+type CheckoutJourneyPaymentElementReady = {
+    phase: 'payment_element_ready';
+    element: CheckoutElementKind;
+};
+type CheckoutJourneyPaymentElementFailed = {
+    phase: 'payment_element_failed';
+    element: CheckoutElementKind;
+    element_phase: CheckoutElementPhase;
+    error_code?: string;
+};
+type CheckoutJourneyPaymentSubmitAttempted = {
+    phase: 'payment_submit_attempted';
+};
+type CheckoutJourneyPaymentSubmitFailed = {
+    phase: 'payment_submit_failed';
+    submit_phase: CheckoutSubmitPhase;
+    error_code?: string;
+};
+type CheckoutPaymentRail = 'saved' | 'new' | 'on_file';
+export type CheckoutMethodKind = 'card' | 'alipay' | 'other';
+type CheckoutPromoResult = 'applied' | 'rejected' | 'removed' | 'expired';
+type CheckoutPayBlockedReason = 'reactivation_unconfirmed' | 'promo_unapplied';
+type CheckoutJourneyMethodSelected = {
+    phase: 'method_selected';
+    rail: CheckoutPaymentRail;
+    method_kind?: CheckoutMethodKind;
+};
+type CheckoutJourneyPromo = {
+    phase: 'promo';
+    result: CheckoutPromoResult;
+    /** Whether the entry link carried the code; the code itself is never reported. */
+    prefilled: boolean;
+};
+type CheckoutJourneyPayBlocked = {
+    phase: 'pay_blocked';
+    reason: CheckoutPayBlockedReason;
+};
+type CheckoutJourneySubmitted = {
+    phase: 'submitted';
+};
+type CheckoutJourneyOperationLinked = {
+    phase: 'operation_linked';
+    billing_op_id: string;
+};
+type CheckoutJourneyProgressEvent = CheckoutJourneyEntered | CheckoutJourneyPreviewReady | CheckoutJourneyPreviewFailed | CheckoutJourneyPaymentElementReady | CheckoutJourneyPaymentElementFailed | CheckoutJourneyPaymentSubmitAttempted | CheckoutJourneyPaymentSubmitFailed | CheckoutJourneyMethodSelected | CheckoutJourneyPromo | CheckoutJourneyPayBlocked | CheckoutJourneySubmitted | CheckoutJourneyOperationLinked;
+/** How the customer left: the page went away, a control of this page led out, or the cloud app's checkout dialog closed. */
+export type CheckoutExit = 'page_exit' | 'back' | 'close' | 'host_link' | 'dialog_close';
+/** The ending screens of the full-page checkout. */
+export type CheckoutEndingKind = 'success' | 'completed' | 'already_completed' | 'in_progress' | 'received' | 'unconfirmed' | 'refused' | 'plan_unavailable' | 'link_invalid' | 'load_failed';
+/** Whose payment an ending shows: this page's Pay, a return, one it followed, or one already settled. */
+export type CheckoutEndingAttribution = 'started' | 'returned' | 'followed' | 'settled';
+/** The customer left before the checkout reached an ending. */
+type CheckoutJourneyAbandoned = {
+    phase: 'abandoned';
+    last_phase: CheckoutJourneyProgressEvent['phase'];
+    exit: CheckoutExit;
+};
+type CheckoutJourneyEnded = {
+    phase: 'ended';
+    ending_kind: CheckoutEndingKind;
+    attribution?: CheckoutEndingAttribution;
+};
+export type CheckoutJourneyPhaseEvent = CheckoutJourneyProgressEvent | CheckoutJourneyAbandoned | CheckoutJourneyEnded;
+export type CheckoutJourneyPhase = CheckoutJourneyPhaseEvent['phase'];
+export type CheckoutJourneyTelemetryEvent = CheckoutJourneyContext & CheckoutJourneyPhaseEvent;
+export type CheckoutJourneyTelemetryEventName = `billing.checkout.${CheckoutJourneyPhase}`;
+/**
+ * The wire name for every phase. Typed as a total `Record` over the phase
+ * union, so a phase added to the union without a name here fails to compile —
+ * and so the runtime list below can never drift from the emitted names.
+ */
+export declare const CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE: Record<CheckoutJourneyPhase, CheckoutJourneyTelemetryEventName>;
+export declare function getCheckoutJourneyTelemetryEventName(event: CheckoutJourneyTelemetryEvent): CheckoutJourneyTelemetryEventName;
+export declare function getCheckoutJourneyTelemetryEventPayload(event: CheckoutJourneyTelemetryEvent): {
+    attribution?: CheckoutEndingAttribution | undefined;
+    ending_kind?: CheckoutEndingKind | undefined;
+    exit?: CheckoutExit | undefined;
+    last_phase?: "entered" | "preview_ready" | "preview_failed" | "payment_element_ready" | "payment_element_failed" | "payment_submit_attempted" | "payment_submit_failed" | "method_selected" | "promo" | "pay_blocked" | "submitted" | "operation_linked" | undefined;
+    reason?: CheckoutPayBlockedReason | undefined;
+    prefilled?: boolean | undefined;
+    result?: CheckoutPromoResult | undefined;
+    method_kind?: CheckoutMethodKind | undefined;
+    rail?: CheckoutPaymentRail | undefined;
+    payment_intent_source?: PaymentIntentSource | undefined;
+    submit_phase?: CheckoutSubmitPhase | undefined;
+    element_phase?: CheckoutElementPhase | undefined;
+    element?: CheckoutElementKind | undefined;
+    denial_reason?: CapabilityDenialReason | undefined;
+    error_code?: string | undefined;
+    failure_category?: BillingTelemetryFailureCategory | undefined;
+    preview_revision?: string | undefined;
+    billing_op_id?: string | undefined;
+    ui_mode?: CheckoutUiMode | undefined;
+    assigned_arm?: CheckoutJourneyArm | undefined;
+    schema_version: number;
+    phase: "ended" | "abandoned" | "entered" | "preview_ready" | "preview_failed" | "payment_element_ready" | "payment_element_failed" | "payment_submit_attempted" | "payment_submit_failed" | "method_selected" | "promo" | "pay_blocked" | "submitted" | "operation_linked";
+    checkout_journey_id: string;
+    checkout_entered_at: string;
+    assignment_status: "unavailable" | "resolved";
+    entry_flow: CheckoutEntryFlow;
+    entry_source: CheckoutEntrySource;
+};
+export type CheckoutJourneyTelemetryEventPayload = ReturnType<typeof getCheckoutJourneyTelemetryEventPayload>;
+/** Only the cloud build registers the sinks that call this. */
+export declare function getCloudAppCheckoutJourneyTelemetryEventPayload(event: CheckoutJourneyTelemetryEvent): CheckoutJourneyTelemetryEventPayload & {
+    billing_surface: BillingSurface;
+};
+export {};

package/dist/core/billing/telemetry/checkoutJourney.js

@@ -0,0 +1,115 @@
+/**
+ * Checkout-journey lifecycle events for the embedded-checkout rollout.
+ *
+ * These intermediate stages are kept deliberately separate from the terminal
+ * billing taxonomy above (`billing.<operation>.<stage>`): entry, preview, and
+ * Payment Element observations are client observations of progress, never
+ * business success/failure/timeout. They share one frozen journey context so
+ * the two rollout arms can be compared on the same denominator.
+ */
+export const CHECKOUT_JOURNEY_SCHEMA_VERSION = 1;
+/**
+ * The wire name for every phase. Typed as a total `Record` over the phase
+ * union, so a phase added to the union without a name here fails to compile —
+ * and so the runtime list below can never drift from the emitted names.
+ */
+export const CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE = {
+    entered: 'billing.checkout.entered',
+    preview_ready: 'billing.checkout.preview_ready',
+    preview_failed: 'billing.checkout.preview_failed',
+    payment_element_ready: 'billing.checkout.payment_element_ready',
+    payment_element_failed: 'billing.checkout.payment_element_failed',
+    payment_submit_attempted: 'billing.checkout.payment_submit_attempted',
+    payment_submit_failed: 'billing.checkout.payment_submit_failed',
+    method_selected: 'billing.checkout.method_selected',
+    promo: 'billing.checkout.promo',
+    pay_blocked: 'billing.checkout.pay_blocked',
+    submitted: 'billing.checkout.submitted',
+    operation_linked: 'billing.checkout.operation_linked',
+    abandoned: 'billing.checkout.abandoned',
+    ended: 'billing.checkout.ended'
+};
+export function getCheckoutJourneyTelemetryEventName(event) {
+    return CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE[event.phase];
+}
+function getContextPayload(event) {
+    return {
+        schema_version: CHECKOUT_JOURNEY_SCHEMA_VERSION,
+        phase: event.phase,
+        checkout_journey_id: event.checkout_journey_id,
+        checkout_entered_at: event.checkout_entered_at,
+        assignment_status: event.assignment_status,
+        entry_flow: event.entry_flow,
+        entry_source: event.entry_source,
+        ...(event.assigned_arm !== undefined && {
+            assigned_arm: event.assigned_arm
+        }),
+        ...(event.ui_mode !== undefined && { ui_mode: event.ui_mode }),
+        ...(event.billing_op_id !== undefined && {
+            billing_op_id: event.billing_op_id
+        })
+    };
+}
+function getPreviewPayload(event) {
+    return {
+        ...('preview_revision' in event &&
+            event.preview_revision !== undefined && {
+            preview_revision: event.preview_revision
+        }),
+        ...('failure_category' in event && {
+            failure_category: event.failure_category
+        }),
+        ...('error_code' in event &&
+            event.error_code !== undefined && { error_code: event.error_code }),
+        ...('denial_reason' in event &&
+            event.denial_reason !== undefined && {
+            denial_reason: event.denial_reason
+        })
+    };
+}
+function getPaymentFormPayload(event) {
+    return {
+        ...('element' in event && { element: event.element }),
+        ...('element_phase' in event && { element_phase: event.element_phase }),
+        ...('submit_phase' in event && { submit_phase: event.submit_phase })
+    };
+}
+function getChoicePayload(event) {
+    return {
+        ...('payment_intent_source' in event &&
+            event.payment_intent_source !== undefined && {
+            payment_intent_source: event.payment_intent_source
+        }),
+        ...('rail' in event && { rail: event.rail }),
+        ...('method_kind' in event &&
+            event.method_kind !== undefined && { method_kind: event.method_kind }),
+        ...('result' in event && { result: event.result }),
+        ...('prefilled' in event && { prefilled: event.prefilled }),
+        ...('reason' in event && { reason: event.reason })
+    };
+}
+function getExitPayload(event) {
+    return {
+        ...('last_phase' in event && { last_phase: event.last_phase }),
+        ...('exit' in event && { exit: event.exit }),
+        ...('ending_kind' in event && { ending_kind: event.ending_kind }),
+        ...('attribution' in event &&
+            event.attribution !== undefined && { attribution: event.attribution })
+    };
+}
+export function getCheckoutJourneyTelemetryEventPayload(event) {
+    return {
+        ...getContextPayload(event),
+        ...getPreviewPayload(event),
+        ...getPaymentFormPayload(event),
+        ...getChoicePayload(event),
+        ...getExitPayload(event)
+    };
+}
+/** Only the cloud build registers the sinks that call this. */
+export function getCloudAppCheckoutJourneyTelemetryEventPayload(event) {
+    return {
+        ...getCheckoutJourneyTelemetryEventPayload(event),
+        billing_surface: 'cloud_app'
+    };
+}