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

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 {};

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

@@ -0,0 +1,23 @@
+import type { SubscribeResponse } from '@comfyorg/ingest-types';
+import type { BillingDeclineReason } from '../operationState.js';
+import type { BillingCheckoutReceived, BillingFailed, BillingIntent, BillingRecoveredSucceeded, BillingRequestSent, BillingStarted, BillingTimedOut } from './stages.js';
+import type { BillingCycle, PaymentIntentSource, SubscriptionCheckoutTier, SubscriptionCheckoutType } from './vocabulary.js';
+/** The two checkouts billing web serves; the cloud app's events name neither. */
+export type SubscriptionCheckoutUi = 'embedded' | 'full_page';
+export type SubscriptionCheckoutBillingEvent = {
+    operation: 'subscription_checkout';
+    billing_op_id?: string;
+    checkout_attempt_id?: string;
+    tier?: SubscriptionCheckoutTier;
+    cycle?: BillingCycle;
+    checkout_type?: SubscriptionCheckoutType;
+    checkout_ui?: SubscriptionCheckoutUi;
+    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;
+} & (BillingIntent | BillingCheckoutReceived<SubscribeResponse['status']> | BillingRequestSent | BillingStarted | BillingRecoveredSucceeded | (BillingFailed & {
+    decline_reason?: BillingDeclineReason;
+}) | BillingTimedOut);

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

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

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

@@ -0,0 +1,30 @@
+import type { CreateTopupResponse } from '@comfyorg/ingest-types';
+import type { BillingCheckoutReceived, BillingFailed, BillingIntent, BillingRequestSent, BillingStarted, BillingSucceeded } from './stages.js';
+import type { PaymentIntentSource } from './vocabulary.js';
+/** The fixed amounts, in USD, a top-up dialog offers as one-click choices. */
+export declare const TOPUP_AMOUNT_PRESETS_USD: readonly [10, 25, 50, 100];
+/** The preset the customer picked, or `custom` for any typed amount. */
+export type TopupAmountPreset = `${(typeof TOPUP_AMOUNT_PRESETS_USD)[number]}` | 'custom';
+export declare function getTopupAmountPreset(pickedPresetUsd: number | null): TopupAmountPreset;
+type TopupStarted = BillingStarted & {
+    /** The amount being bought, in whole cents. */
+    amount_cents?: number;
+    amount_preset?: TopupAmountPreset;
+};
+export type TopupBillingEvent = {
+    operation: 'topup';
+    billing_op_id?: string;
+    /**
+     * Surface the top-up was opened from. Absent when the caller named none,
+     * exactly as on the subscription rail's events — absent is no claim, never
+     * an implied default. Named `payment_intent_source` to match its siblings
+     * above; the journey's own `entry_source` is a separate, smaller enum.
+     */
+    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;
+} & (BillingIntent | BillingCheckoutReceived<CreateTopupResponse['status']> | BillingRequestSent | TopupStarted | BillingSucceeded | BillingFailed);
+export {};

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

@@ -0,0 +1,6 @@
+/** The fixed amounts, in USD, a top-up dialog offers as one-click choices. */
+export const TOPUP_AMOUNT_PRESETS_USD = [10, 25, 50, 100];
+export function getTopupAmountPreset(pickedPresetUsd) {
+    const preset = TOPUP_AMOUNT_PRESETS_USD.find((usd) => usd === pickedPresetUsd);
+    return preset === undefined ? 'custom' : `${preset}`;
+}

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

@@ -0,0 +1,9 @@
+export type BillingTierKey = 'free' | 'standard' | 'creator' | 'pro' | 'founder';
+export type BillingCycle = 'monthly' | 'yearly';
+export type SubscriptionCheckoutType = 'new' | 'change';
+export type SubscriptionCheckoutTier = BillingTierKey | 'team';
+export type ResubscribeSource = 'pricing_dialog' | 'settings_billing_panel' | 'billing_web_subscription';
+/** Mirrors `BillingSource` in `@comfyorg/billing-contract`; a type test there fails when the two drift. */
+export type PaymentIntentSource = 'subscription_required' | 'out_of_credits' | 'top_up_blocked' | 'deep_link' | 'subscribe_to_run' | 'subscribe_now_button' | 'upgrade_to_add_credits' | 'settings_billing_panel' | 'avatar_menu_plans' | 'team_members_panel' | 'invite_member_upsell' | 'upload_model_upgrade' | 'team_upgrade_resume' | 'free_tier_quota' | 'agent_paywall';
+/** Mirrors `BillingIntent` in `@comfyorg/billing-contract`; a type test there fails when the two drift. */
+export type HostedBillingIntent = 'pricing' | 'checkout' | 'top-up' | 'subscription' | 'payment-methods' | 'invoices' | 'result';

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

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

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

@@ -0,0 +1,27 @@
+import type { HostedBillingIntent, PaymentIntentSource } from './vocabulary.js';
+/** Mirrors `BillingProduct` in `@comfyorg/billing-contract`; a type test there fails when the two drift. */
+export type WebEntryProduct = 'comfyui' | 'platform' | 'workshop' | 'models';
+/** Mirrors `BillingEntryErrorCode` in `@comfyorg/billing-contract`; a type test there fails when the two drift. */
+export type WebEntryErrorCode = 'UNSUPPORTED_VERSION' | 'UNKNOWN_INTENT' | 'UNKNOWN_PRODUCT' | 'UNKNOWN_RETURN_TARGET' | 'INVALID_AMOUNT' | 'INVALID_PLAN' | 'INVALID_CORRELATION_ID' | 'INVALID_WORKSPACE_ID' | 'INVALID_TEAM_CREDIT_STOP_ID' | 'INVALID_PROMOTION_CODE';
+export type WebEntryBounceReason = 'pricing_link' | 'planless_checkout' | 'return_target_rewritten';
+/** A `ReturnTarget` of `@comfyorg/billing-contract` (a type test there pins them) or the host's pricing table. */
+export type WebEntryBounceTarget = 'comfyui_workspace' | 'comfyui_credits' | 'platform_account' | 'platform_billing' | 'pricing_table';
+export type WebEntryBillingEvent = {
+    operation: 'web_entry';
+    outcome: 'pending';
+} & ({
+    stage: 'received';
+    intent: HostedBillingIntent;
+    product: WebEntryProduct;
+    has_plan: boolean;
+    payment_intent_source?: PaymentIntentSource;
+    /** The cloud journey id the entry link carries; links from other products carry none. */
+    correlation_id?: string;
+} | {
+    stage: 'rejected';
+    error_code: WebEntryErrorCode;
+} | {
+    stage: 'bounced';
+    reason: WebEntryBounceReason;
+    to: WebEntryBounceTarget;
+});

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

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