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

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'
+    };
+}

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

@@ -0,0 +1,30 @@
+import type { BillingOperationKind, BillingPresentation, HostedBillingDestination } from '../operationState.js';
+import type { CheckoutMethodKind } from './checkoutJourney.js';
+/** What the hosted page asks of the customer, from what the server waits on. */
+export type CheckoutHostedStep = 'authentication' | 'payment_method' | 'invoice_payment' | 'checkout';
+/** The hosted page replaced this page, or opened beside it. */
+export type CheckoutRedirectNavigation = 'redirect' | 'new_tab';
+/**
+ * A hosted step this tab handed the customer to, and the customer back on the
+ * tab that handed it. Neither settles the operation; the pair joins on
+ * `billing_op_id`, and a start with no return is a customer who did not come
+ * back.
+ */
+export type CheckoutRedirectBillingEvent = {
+    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;
+    destination: HostedBillingDestination;
+    step: CheckoutHostedStep;
+    navigation: CheckoutRedirectNavigation;
+    /** The method the customer chose, when the host knows it. */
+    method_kind?: CheckoutMethodKind;
+} & ({
+    stage: 'redirect_started';
+} | {
+    stage: 'returned';
+});

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

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

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

@@ -0,0 +1,14 @@
+import type { BillingFailed, BillingStarted, BillingSucceeded } from './stages.js';
+import type { BillingTierKey, PaymentIntentSource } from './vocabulary.js';
+export type DowngradeToPersonalBillingEvent = {
+    operation: 'downgrade_to_personal';
+    member_removal_count: number;
+    member_removal_failures: number;
+    target_tier?: BillingTierKey;
+    payment_intent_source?: PaymentIntentSource;
+    /**
+     * Client-observed end-to-end wall time from this attempt's canonical
+     * `started` event through to this terminal event.
+     */
+    duration_ms?: number;
+} & (BillingStarted | BillingSucceeded | BillingFailed);

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

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

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

@@ -0,0 +1,16 @@
+import type { PaymentIntentSource, SubscriptionCheckoutTier } from './vocabulary.js';
+/**
+ * A cloud entry point that leads to billing. A client journey observation: it
+ * has no backend operation counterpart and never claims an operation outcome.
+ */
+export type EntryBillingEvent = {
+    operation: 'entry';
+    outcome: 'pending';
+    payment_intent_source?: PaymentIntentSource;
+} & ({
+    stage: 'paywall_shown';
+    /** The plan the customer is on when the paywall opens; absent when unknown. */
+    current_tier?: SubscriptionCheckoutTier;
+} | {
+    stage: 'add_credits_clicked';
+});

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

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

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

@@ -0,0 +1,36 @@
+export declare const BILLING_TELEMETRY_EVENTS: {
+    readonly BILLING_SUBSCRIPTION_CHECKOUT_RECEIVED: "billing.subscription_checkout.checkout_received";
+    readonly BILLING_TOPUP_CHECKOUT_RECEIVED: "billing.topup.checkout_received";
+    readonly BILLING_SUBSCRIPTION_CHECKOUT_REQUEST_SENT: "billing.subscription_checkout.request_sent";
+    readonly BILLING_TOPUP_REQUEST_SENT: "billing.topup.request_sent";
+    readonly BILLING_SUBSCRIPTION_CHECKOUT_INTENT: "billing.subscription_checkout.intent";
+    readonly BILLING_TOPUP_INTENT: "billing.topup.intent";
+    readonly BILLING_SUBSCRIPTION_CHECKOUT_STARTED: "billing.subscription_checkout.started";
+    readonly BILLING_SUBSCRIPTION_CHECKOUT_SUCCEEDED: "billing.subscription_checkout.succeeded";
+    readonly BILLING_SUBSCRIPTION_CHECKOUT_FAILED: "billing.subscription_checkout.failed";
+    readonly BILLING_SUBSCRIPTION_CHECKOUT_TIMEOUT: "billing.subscription_checkout.timeout";
+    readonly BILLING_OPERATION_STARTED: "billing.operation.started";
+    readonly BILLING_CAPABILITY_READ_SUCCEEDED: "billing.capability_read.succeeded";
+    readonly BILLING_CAPABILITY_READ_FAILED: "billing.capability_read.failed";
+    readonly BILLING_OPERATION_SUCCEEDED: "billing.operation.succeeded";
+    readonly BILLING_OPERATION_FAILED: "billing.operation.failed";
+    readonly BILLING_OPERATION_TIMEOUT: "billing.operation.timeout";
+    readonly BILLING_RESUBSCRIBE_STARTED: "billing.resubscribe.started";
+    readonly BILLING_RESUBSCRIBE_SUCCEEDED: "billing.resubscribe.succeeded";
+    readonly BILLING_RESUBSCRIBE_FAILED: "billing.resubscribe.failed";
+    readonly BILLING_TOPUP_STARTED: "billing.topup.started";
+    readonly BILLING_TOPUP_SUCCEEDED: "billing.topup.succeeded";
+    readonly BILLING_TOPUP_FAILED: "billing.topup.failed";
+    readonly BILLING_DOWNGRADE_TO_PERSONAL_STARTED: "billing.downgrade_to_personal.started";
+    readonly BILLING_DOWNGRADE_TO_PERSONAL_SUCCEEDED: "billing.downgrade_to_personal.succeeded";
+    readonly BILLING_DOWNGRADE_TO_PERSONAL_FAILED: "billing.downgrade_to_personal.failed";
+    readonly BILLING_WEB_HANDOFF_OPENED: "billing.web_handoff.opened";
+    readonly BILLING_ENTRY_PAYWALL_SHOWN: "billing.entry.paywall_shown";
+    readonly BILLING_ENTRY_ADD_CREDITS_CLICKED: "billing.entry.add_credits_clicked";
+    readonly BILLING_CANCEL_INTENT: "billing.cancel.intent";
+    readonly BILLING_CANCEL_ABANDONED: "billing.cancel.abandoned";
+    readonly BILLING_CANCEL_FAILED: "billing.cancel.failed";
+    readonly BILLING_PORTAL_OPENED: "billing.portal.opened";
+    readonly BILLING_PORTAL_FAILED: "billing.portal.failed";
+    readonly BILLING_PORTAL_RETURNED: "billing.portal.returned";
+};

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

@@ -0,0 +1,36 @@
+export const BILLING_TELEMETRY_EVENTS = {
+    BILLING_SUBSCRIPTION_CHECKOUT_RECEIVED: 'billing.subscription_checkout.checkout_received',
+    BILLING_TOPUP_CHECKOUT_RECEIVED: 'billing.topup.checkout_received',
+    BILLING_SUBSCRIPTION_CHECKOUT_REQUEST_SENT: 'billing.subscription_checkout.request_sent',
+    BILLING_TOPUP_REQUEST_SENT: 'billing.topup.request_sent',
+    BILLING_SUBSCRIPTION_CHECKOUT_INTENT: 'billing.subscription_checkout.intent',
+    BILLING_TOPUP_INTENT: 'billing.topup.intent',
+    BILLING_SUBSCRIPTION_CHECKOUT_STARTED: 'billing.subscription_checkout.started',
+    BILLING_SUBSCRIPTION_CHECKOUT_SUCCEEDED: 'billing.subscription_checkout.succeeded',
+    BILLING_SUBSCRIPTION_CHECKOUT_FAILED: 'billing.subscription_checkout.failed',
+    BILLING_SUBSCRIPTION_CHECKOUT_TIMEOUT: 'billing.subscription_checkout.timeout',
+    BILLING_OPERATION_STARTED: 'billing.operation.started',
+    BILLING_CAPABILITY_READ_SUCCEEDED: 'billing.capability_read.succeeded',
+    BILLING_CAPABILITY_READ_FAILED: 'billing.capability_read.failed',
+    BILLING_OPERATION_SUCCEEDED: 'billing.operation.succeeded',
+    BILLING_OPERATION_FAILED: 'billing.operation.failed',
+    BILLING_OPERATION_TIMEOUT: 'billing.operation.timeout',
+    BILLING_RESUBSCRIBE_STARTED: 'billing.resubscribe.started',
+    BILLING_RESUBSCRIBE_SUCCEEDED: 'billing.resubscribe.succeeded',
+    BILLING_RESUBSCRIBE_FAILED: 'billing.resubscribe.failed',
+    BILLING_TOPUP_STARTED: 'billing.topup.started',
+    BILLING_TOPUP_SUCCEEDED: 'billing.topup.succeeded',
+    BILLING_TOPUP_FAILED: 'billing.topup.failed',
+    BILLING_DOWNGRADE_TO_PERSONAL_STARTED: 'billing.downgrade_to_personal.started',
+    BILLING_DOWNGRADE_TO_PERSONAL_SUCCEEDED: 'billing.downgrade_to_personal.succeeded',
+    BILLING_DOWNGRADE_TO_PERSONAL_FAILED: 'billing.downgrade_to_personal.failed',
+    BILLING_WEB_HANDOFF_OPENED: 'billing.web_handoff.opened',
+    BILLING_ENTRY_PAYWALL_SHOWN: 'billing.entry.paywall_shown',
+    BILLING_ENTRY_ADD_CREDITS_CLICKED: 'billing.entry.add_credits_clicked',
+    BILLING_CANCEL_INTENT: 'billing.cancel.intent',
+    BILLING_CANCEL_ABANDONED: 'billing.cancel.abandoned',
+    BILLING_CANCEL_FAILED: 'billing.cancel.failed',
+    BILLING_PORTAL_OPENED: 'billing.portal.opened',
+    BILLING_PORTAL_FAILED: 'billing.portal.failed',
+    BILLING_PORTAL_RETURNED: 'billing.portal.returned'
+};

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

@@ -0,0 +1,17 @@
+export type { BillingOperationTerminal, BillingTelemetryErrorCode, BillingTelemetryFailure, BillingTelemetryFailureCategory } from './stages.js';
+export type { BillingClient, BillingSurface, BillingTelemetryEvent, BillingTelemetryEventName } from './billingTelemetryEvent.js';
+export { getBillingTelemetryEventName } from './billingTelemetryEvent.js';
+export { getBillingTelemetryEventPayload, getBillingWebTelemetryEventPayload, getCloudAppBillingTelemetryEventPayload } from './payload.js';
+export { BILLING_TELEMETRY_EVENTS } from './eventNames.js';
+export { toBillingTelemetryEvent } from './operationLifecycleEvent.js';
+export type { CheckoutHostedStep, CheckoutRedirectNavigation } from './checkoutRedirectEvent.js';
+export type { BillingPortalTarget } from './portalEvent.js';
+export type { SubscriptionCheckoutUi } from './subscriptionCheckoutEvent.js';
+export type { WebEntryBillingEvent, WebEntryBounceReason, WebEntryBounceTarget, WebEntryErrorCode, WebEntryProduct } from './webEntryEvent.js';
+export type { WebReturnBillingEvent, WebReturnControl } from './webReturnEvent.js';
+export type { WebSessionBillingEvent, WebSessionMode } from './webSessionEvent.js';
+export type { CheckoutAssignmentStatus, CheckoutEndingAttribution, CheckoutEndingKind, CheckoutEntryFlow, CheckoutExit, CheckoutEntrySource, CheckoutJourneyArm, CheckoutJourneyContext, CheckoutJourneyPhase, CheckoutJourneyPhaseEvent, CheckoutJourneyTelemetryEvent, CheckoutJourneyTelemetryEventName, CheckoutJourneyTelemetryEventPayload, CheckoutMethodKind, CheckoutUiMode } from './checkoutJourney.js';
+export { CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE, CHECKOUT_JOURNEY_SCHEMA_VERSION, getCheckoutJourneyTelemetryEventName, getCheckoutJourneyTelemetryEventPayload, getCloudAppCheckoutJourneyTelemetryEventPayload } from './checkoutJourney.js';
+export type { TopupAmountPreset } from './topupEvent.js';
+export { getTopupAmountPreset, TOPUP_AMOUNT_PRESETS_USD } from './topupEvent.js';
+export type { BillingCycle, BillingTierKey, HostedBillingIntent, PaymentIntentSource, ResubscribeSource, SubscriptionCheckoutTier, SubscriptionCheckoutType } from './vocabulary.js';

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

@@ -0,0 +1,6 @@
+export { getBillingTelemetryEventName } from './billingTelemetryEvent.js';
+export { getBillingTelemetryEventPayload, getBillingWebTelemetryEventPayload, getCloudAppBillingTelemetryEventPayload } from './payload.js';
+export { BILLING_TELEMETRY_EVENTS } from './eventNames.js';
+export { toBillingTelemetryEvent } from './operationLifecycleEvent.js';
+export { CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE, CHECKOUT_JOURNEY_SCHEMA_VERSION, getCheckoutJourneyTelemetryEventName, getCheckoutJourneyTelemetryEventPayload, getCloudAppCheckoutJourneyTelemetryEventPayload } from './checkoutJourney.js';
+export { getTopupAmountPreset, TOPUP_AMOUNT_PRESETS_USD } from './topupEvent.js';

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

@@ -0,0 +1,25 @@
+import type { BillingPresentation } from '../operationState.js';
+import type { BillingOperationTerminal, BillingStarted } from './stages.js';
+import type { BillingCycle, PaymentIntentSource, SubscriptionCheckoutTier, SubscriptionCheckoutType } from './vocabulary.js';
+export type BillingOperationBillingEvent = {
+    operation: 'operation';
+    /** Absent when the initiating call itself failed, before the backend returned one to poll. */
+    billing_op_id?: string;
+    operation_type: 'subscription' | 'topup' | 'cancel';
+    /** Set by the billing SDK rail, as is `resumed`; the poller never sets either. */
+    presentation?: BillingPresentation;
+    /** True when this tab reattached to an operation it did not issue. */
+    resumed?: boolean;
+    tier?: SubscriptionCheckoutTier;
+    cycle?: BillingCycle;
+    checkout_type?: SubscriptionCheckoutType;
+    payment_intent_source?: PaymentIntentSource;
+    /**
+     * Client-observed end-to-end wall time from this attempt's canonical
+     * `started` event through to this terminal event, including the
+     * initiating API call's latency (not just the poll-observation window).
+     * On `timeout` this is how long the client watched, not the operation's
+     * true duration.
+     */
+    duration_ms?: number;
+} & (BillingStarted | BillingOperationTerminal);

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

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

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

@@ -0,0 +1,9 @@
+import type { BillingOperationTelemetryEvent } from '../operationLifecycle.js';
+import type { BillingTelemetryEvent } from './billingTelemetryEvent.js';
+import type { PaymentIntentSource } from './vocabulary.js';
+/**
+ * The lifecycle's event onto the poller's `billing.operation.*` stages, so
+ * both rails count in one funnel; only this rail sets `presentation` and
+ * `resumed`. Friction inside the operation maps onto `billing.checkout.*`.
+ */
+export declare function toBillingTelemetryEvent(event: BillingOperationTelemetryEvent, paymentIntentSource?: PaymentIntentSource): BillingTelemetryEvent;

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

@@ -0,0 +1,79 @@
+import { BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT, BILLING_OPERATION_TELEMETRY_EVENT } from '../../../telemetry.js';
+/**
+ * The lifecycle's event onto the poller's `billing.operation.*` stages, so
+ * both rails count in one funnel; only this rail sets `presentation` and
+ * `resumed`. Friction inside the operation maps onto `billing.checkout.*`.
+ */
+export function toBillingTelemetryEvent(event, paymentIntentSource) {
+    const friction = {
+        operation: 'checkout',
+        outcome: 'pending',
+        billing_client: 'sdk',
+        operation_type: event.operation_type,
+        billing_op_id: event.billing_op_id,
+        presentation: event.presentation,
+        resumed: event.resumed
+    };
+    if (event.name === BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.redirectStarted ||
+        event.name === BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned) {
+        return {
+            ...friction,
+            stage: event.name === BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned
+                ? 'returned'
+                : 'redirect_started',
+            destination: event.destination,
+            step: event.step,
+            navigation: event.navigation,
+            ...(event.method_kind === undefined
+                ? {}
+                : { method_kind: event.method_kind })
+        };
+    }
+    const shared = {
+        operation: 'operation',
+        billing_client: 'sdk',
+        operation_type: event.operation_type,
+        billing_op_id: event.billing_op_id,
+        presentation: event.presentation,
+        resumed: event.resumed,
+        ...(paymentIntentSource === undefined
+            ? {}
+            : { payment_intent_source: paymentIntentSource }),
+        ...('duration_ms' in event && event.duration_ms !== undefined
+            ? { duration_ms: event.duration_ms }
+            : {})
+    };
+    switch (event.name) {
+        case BILLING_OPERATION_TELEMETRY_EVENT.started:
+            return { ...shared, stage: 'started', outcome: 'pending' };
+        case BILLING_OPERATION_TELEMETRY_EVENT.succeeded:
+            return { ...shared, stage: 'succeeded', outcome: 'success' };
+        case BILLING_OPERATION_TELEMETRY_EVENT.timeout:
+            return {
+                ...shared,
+                stage: 'timeout',
+                outcome: 'failure',
+                failure_category: 'poll_timeout'
+            };
+        case BILLING_OPERATION_TELEMETRY_EVENT.failed:
+            return {
+                ...shared,
+                stage: 'failed',
+                outcome: 'failure',
+                failure_category: event.failure_category ?? 'provider_decline',
+                decline_reason: event.decline_reason
+            };
+        case BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeRequired:
+            return { ...friction, stage: 'challenge_required' };
+        case BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeCompleted:
+            return { ...friction, stage: 'challenge_completed' };
+        case BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeFailed:
+            return {
+                ...friction,
+                stage: 'challenge_failed',
+                ...(event.decline_reason === undefined
+                    ? {}
+                    : { decline_reason: event.decline_reason })
+            };
+    }
+}

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

@@ -0,0 +1,55 @@
+import type { BillingSurface, BillingTelemetryEvent } from './billingTelemetryEvent.js';
+type BillingTelemetryPayload = Record<string, unknown>;
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+export type BillingPayloadFieldHandling<Event = BillingTelemetryEvent> = Record<Exclude<KeysOfUnion<Event>, 'operation' | 'stage' | 'outcome'>, 'optional' | 'required'>;
+export declare const BILLING_PAYLOAD_FIELD_HANDLING: {
+    readonly checkout_status: "required";
+    readonly control: "required";
+    readonly correlation_id: "required";
+    readonly destination: "required";
+    readonly failure_category: "required";
+    readonly has_plan: "required";
+    readonly intent: "required";
+    readonly member_removal_count: "required";
+    readonly member_removal_failures: "required";
+    readonly mode: "required";
+    readonly navigation: "required";
+    readonly operation_type: "required";
+    readonly origin: "required";
+    readonly product: "required";
+    readonly reason: "required";
+    readonly result: "required";
+    readonly source: "required";
+    readonly step: "required";
+    readonly target: "required";
+    readonly to: "required";
+    readonly amount_cents: "optional";
+    readonly amount_preset: "optional";
+    readonly billing_client: "optional";
+    readonly billing_op_id: "optional";
+    readonly checkout_attempt_id: "optional";
+    readonly checkout_type: "optional";
+    readonly checkout_ui: "optional";
+    readonly current_tier: "optional";
+    readonly cycle: "optional";
+    readonly decline_reason: "optional";
+    readonly duration_ms: "optional";
+    readonly error_code: "optional";
+    readonly method_kind: "optional";
+    readonly payment_intent_source: "optional";
+    readonly presentation: "optional";
+    readonly recovery_outcome: "optional";
+    readonly resumed: "optional";
+    readonly target_tier: "optional";
+    readonly tier: "optional";
+};
+export declare function getBillingTelemetryEventPayload(event: BillingTelemetryEvent): BillingTelemetryPayload;
+/** Only the cloud build registers the sinks that call this; the desktop host sink claims no surface. */
+export declare function getCloudAppBillingTelemetryEventPayload(event: BillingTelemetryEvent): BillingTelemetryPayload & {
+    billing_surface: BillingSurface;
+};
+/** The payload billing web reports: the same allowlist, claiming the billing web surface. */
+export declare function getBillingWebTelemetryEventPayload(event: BillingTelemetryEvent): BillingTelemetryPayload & {
+    billing_surface: BillingSurface;
+};
+export {};

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

@@ -0,0 +1,75 @@
+export const BILLING_PAYLOAD_FIELD_HANDLING = {
+    checkout_status: 'required',
+    control: 'required',
+    correlation_id: 'required',
+    destination: 'required',
+    failure_category: 'required',
+    has_plan: 'required',
+    intent: 'required',
+    member_removal_count: 'required',
+    member_removal_failures: 'required',
+    mode: 'required',
+    navigation: 'required',
+    operation_type: 'required',
+    origin: 'required',
+    product: 'required',
+    reason: 'required',
+    result: 'required',
+    source: 'required',
+    step: 'required',
+    target: 'required',
+    to: 'required',
+    amount_cents: 'optional',
+    amount_preset: 'optional',
+    billing_client: 'optional',
+    billing_op_id: 'optional',
+    checkout_attempt_id: 'optional',
+    checkout_type: 'optional',
+    checkout_ui: 'optional',
+    current_tier: 'optional',
+    cycle: 'optional',
+    decline_reason: 'optional',
+    duration_ms: 'optional',
+    error_code: 'optional',
+    method_kind: 'optional',
+    payment_intent_source: 'optional',
+    presentation: 'optional',
+    recovery_outcome: 'optional',
+    resumed: 'optional',
+    target_tier: 'optional',
+    tier: 'optional'
+};
+const OPTIONAL_BILLING_PAYLOAD_FIELDS = Object.entries(BILLING_PAYLOAD_FIELD_HANDLING).flatMap(([field, handling]) => (handling === 'optional' ? [field] : []));
+const REQUIRED_BILLING_PAYLOAD_FIELDS = Object.entries(BILLING_PAYLOAD_FIELD_HANDLING).flatMap(([field, handling]) => (handling === 'required' ? [field] : []));
+const optionalBillingPayloadFields = new Set(OPTIONAL_BILLING_PAYLOAD_FIELDS);
+const requiredBillingPayloadFields = new Set(REQUIRED_BILLING_PAYLOAD_FIELDS);
+export function getBillingTelemetryEventPayload(event) {
+    const payload = {
+        operation: event.operation,
+        stage: event.stage,
+        outcome: event.outcome
+    };
+    for (const [field, value] of Object.entries(event)) {
+        if (requiredBillingPayloadFields.has(field)) {
+            payload[field] = value;
+        }
+        else if (optionalBillingPayloadFields.has(field) && value !== undefined) {
+            payload[field] = value;
+        }
+    }
+    return payload;
+}
+/** Only the cloud build registers the sinks that call this; the desktop host sink claims no surface. */
+export function getCloudAppBillingTelemetryEventPayload(event) {
+    return {
+        ...getBillingTelemetryEventPayload(event),
+        billing_surface: 'cloud_app'
+    };
+}
+/** The payload billing web reports: the same allowlist, claiming the billing web surface. */
+export function getBillingWebTelemetryEventPayload(event) {
+    return {
+        ...getBillingTelemetryEventPayload(event),
+        billing_surface: 'billing_web'
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { BillingFailed } from './stages.js';
+/**
+ * The part of the provider's hosted portal the customer was sent to.
+ * `payment_recovery` is a checkout that stopped on a failed or outstanding
+ * payment and sent the customer to settle it.
+ */
+export type BillingPortalTarget = 'payment_methods' | 'invoices' | 'manage_subscription' | 'payment_recovery';
+/**
+ * A trip to the provider's hosted portal. What the customer does there (adding,
+ * removing or picking a default method, reading invoices) never reaches the
+ * browser, so the trip only records leaving for the portal, failing to, and
+ * coming back.
+ */
+export type PortalBillingEvent = {
+    operation: 'portal';
+    target: BillingPortalTarget;
+} & ({
+    stage: 'opened';
+    outcome: 'pending';
+} | BillingFailed | {
+    stage: 'returned';
+    outcome: 'pending';
+});

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

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

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

@@ -0,0 +1,13 @@
+import type { BillingDeclineReason } from '../operationState.js';
+import type { BillingFailed, BillingRecoveredSucceeded, BillingStarted } from './stages.js';
+import type { PaymentIntentSource, ResubscribeSource } from './vocabulary.js';
+export type ResubscribeBillingEvent = {
+    operation: 'resubscribe';
+    source: ResubscribeSource;
+    billing_op_id?: string;
+    checkout_attempt_id?: string;
+    payment_intent_source?: PaymentIntentSource;
+    duration_ms?: number;
+} & (BillingStarted | BillingRecoveredSucceeded | (BillingFailed & {
+    decline_reason?: BillingDeclineReason;
+}));

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

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

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

@@ -0,0 +1,45 @@
+import type { BillingDeclineReason } from '../operationState.js';
+export type BillingTelemetryFailureCategory = 'validation' | 'network' | 'api_rejected' | 'provider_decline' | 'redirect' | 'poll_timeout' | 'reconciliation_needed' | 'stale_operation' | 'rendering' | 'unknown';
+export type BillingTelemetryErrorCode = 'conflicting_payment_method' | 'downgrade_not_allowed' | 'invalid_request' | 'member_removal_failed' | 'missing_checkout_response' | 'missing_payment_method_url' | 'operation_already_pending' | 'payment_popup_blocked' | 'quote_stale' | 'reactivation_not_confirmed' | 'reactivation_amount_changed';
+export interface BillingTelemetryFailure {
+    failure_category: BillingTelemetryFailureCategory;
+    error_code?: BillingTelemetryErrorCode;
+}
+export type BillingIntent = {
+    stage: 'intent';
+    outcome: 'pending';
+};
+export type BillingRequestSent = {
+    stage: 'request_sent';
+    outcome: 'pending';
+};
+export type BillingCheckoutReceived<Status extends string> = {
+    stage: 'checkout_received';
+    outcome: 'pending';
+    billing_op_id: string;
+    checkout_status: Status;
+};
+export type BillingStarted = {
+    stage: 'started';
+    outcome: 'pending';
+};
+export type BillingSucceeded = {
+    stage: 'succeeded';
+    outcome: 'success';
+};
+export type BillingRecoveredSucceeded = BillingSucceeded & {
+    recovery_outcome?: 'late_success';
+};
+export type BillingFailed = BillingTelemetryFailure & {
+    stage: 'failed';
+    outcome: 'failure';
+};
+export type BillingTimedOut = {
+    stage: 'timeout';
+    outcome: 'failure';
+    failure_category: 'poll_timeout';
+};
+/** The stage one attempt at a billing operation settled on. */
+export type BillingOperationTerminal = BillingSucceeded | (BillingFailed & {
+    decline_reason?: BillingDeclineReason;
+}) | BillingTimedOut;

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

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