@comfyorg/account-core 1.0.0-alpha.0

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

@@ -0,0 +1,26 @@
+import type { PendingBillingOperation } from './operationState.js';
+export declare const OPERATION_POLL_TIMING: {
+    readonly initialMs: 1000;
+    readonly maxMs: 8000;
+    readonly multiplier: 1.5;
+    /** An operation parked on the customer is checked on a slow, flat cadence. */
+    readonly parkedMs: 30000;
+};
+export declare const OPERATION_POLL_BUDGET: {
+    readonly defaultMs: 120000;
+    /** A subscription may take minutes to discover that it needs the customer. */
+    readonly subscriptionDiscoveryMs: number;
+    /** Once the customer is involved, a bank challenge can idle for hours. */
+    readonly customerActionMs: number;
+};
+/**
+ * Waiting on the customer, not on the backend: a challenge to complete
+ * elsewhere, a hosted page to finish, a phase the server reports as blocked on
+ * them, or a declined attempt awaiting their retry. Once this tab's own
+ * challenge completes the state reads processing and nothing waits on the
+ * customer anymore.
+ */
+export declare function isParkedOnCustomer(state: PendingBillingOperation): boolean;
+export declare function nextPollDelayMs(state: PendingBillingOperation, previousDelayMs: number | undefined): number;
+export declare function pollBudgetMs(state: PendingBillingOperation): number;
+export declare function hasExhaustedPollBudget(state: PendingBillingOperation, now: number): boolean;

package/dist/core/billing/operationPolicy.js

@@ -0,0 +1,51 @@
+/**
+ * The cadence and budget for observing one operation, taken from the cloud
+ * app's `billingOperationStore` rather than invented, so a consumer moving
+ * onto the SDK sees the same request rate and the same give-up points.
+ */
+import { isBlockedOnCustomerPhase } from './operationState.js';
+export const OPERATION_POLL_TIMING = {
+    initialMs: 1_000,
+    maxMs: 8_000,
+    multiplier: 1.5,
+    /** An operation parked on the customer is checked on a slow, flat cadence. */
+    parkedMs: 30_000
+};
+export const OPERATION_POLL_BUDGET = {
+    defaultMs: 120_000,
+    /** A subscription may take minutes to discover that it needs the customer. */
+    subscriptionDiscoveryMs: 5 * 60_000,
+    /** Once the customer is involved, a bank challenge can idle for hours. */
+    customerActionMs: 23 * 60 * 60_000
+};
+/**
+ * Waiting on the customer, not on the backend: a challenge to complete
+ * elsewhere, a hosted page to finish, a phase the server reports as blocked on
+ * them, or a declined attempt awaiting their retry. Once this tab's own
+ * challenge completes the state reads processing and nothing waits on the
+ * customer anymore.
+ */
+export function isParkedOnCustomer(state) {
+    return (state.authenticationState === 'requires_action' ||
+        state.actionUrl !== undefined ||
+        isBlockedOnCustomerPhase(state.serverPhase) ||
+        (state.authenticationState === 'failed_retryable' &&
+            state.customerActionSeen));
+}
+export function nextPollDelayMs(state, previousDelayMs) {
+    if (isParkedOnCustomer(state))
+        return OPERATION_POLL_TIMING.parkedMs;
+    return Math.min((previousDelayMs ?? OPERATION_POLL_TIMING.initialMs) *
+        OPERATION_POLL_TIMING.multiplier, OPERATION_POLL_TIMING.maxMs);
+}
+export function pollBudgetMs(state) {
+    if (state.kind !== 'cancel' && state.customerActionSeen) {
+        return OPERATION_POLL_BUDGET.customerActionMs;
+    }
+    return state.kind === 'subscription'
+        ? OPERATION_POLL_BUDGET.subscriptionDiscoveryMs
+        : OPERATION_POLL_BUDGET.defaultMs;
+}
+export function hasExhaustedPollBudget(state, now) {
+    return now - state.observedAt > pollBudgetMs(state);
+}

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

@@ -0,0 +1,128 @@
+/**
+ * One billing operation as the SDK sees it: a discriminated union over the
+ * lifecycle a `billing_op_id` moves through, and the pure transition that
+ * advances it. The identity is fixed at adoption and survives every
+ * presentation change, so switching a checkout from the embedded challenge
+ * to the hosted page (or back) is a transition on the same operation, never
+ * a replacement one.
+ *
+ * The transition consumes the generated `BillingOpStatusResponse`. It reads
+ * the coded `decline_reason` and `recovery_action` and never `error_message`,
+ * so no server or payment-provider text can reach a consumer through this
+ * state.
+ */
+import type { zBillingOpStatusResponse } from '@comfyorg/ingest-types/zod';
+import type { z } from 'zod';
+import type { BillingScope } from './billingScope.js';
+export type BillingOpStatus = z.infer<typeof zBillingOpStatusResponse>;
+export type BillingOperationKind = 'subscription' | 'topup' | 'cancel';
+/**
+ * Where the customer completes the operation: the challenge this tab drives
+ * through the host's payment-provider adapter, or the page behind the
+ * server's `action_url`.
+ */
+export type BillingPresentation = 'embedded' | 'hosted';
+/**
+ * Which origin serves a hosted presentation: the provider page behind the
+ * server's `action_url`, or the hosted billing app.
+ */
+export type HostedBillingDestination = 'stripe' | 'billing_web';
+export type BillingDeclineReason = NonNullable<BillingOpStatus['decline_reason']>;
+export type BillingRecoveryAction = NonNullable<BillingOpStatus['recovery_action']>;
+export type BillingAuthenticationState = NonNullable<BillingOpStatus['authentication_state']>;
+export type BillingOperationServerPhase = NonNullable<BillingOpStatus['phase']>;
+/**
+ * The phases the contract defines as blocked on the customer. Neither advances
+ * on its own, so an operation reporting one waits on them even before it has a
+ * link to offer.
+ */
+export declare function isBlockedOnCustomerPhase(phase: BillingOperationServerPhase | null | undefined): boolean;
+export type BillingPresentationState = {
+    readonly presentation: 'embedded';
+    readonly hostedDestination?: never;
+} | {
+    readonly presentation: 'hosted';
+    readonly hostedDestination: HostedBillingDestination;
+};
+export type BillingOperationIdentity = BillingPresentationState & {
+    readonly id: string;
+    readonly kind: BillingOperationKind;
+    readonly scope: BillingScope;
+    /** When this tab began observing the operation; the poll budget counts from here. */
+    readonly observedAt: number;
+    /** When the attempt began, before the command was issued; telemetry durations count from here. */
+    readonly attemptStartedAt: number;
+};
+/**
+ * The in-page challenge for an embedded presentation. `completed` and
+ * `failed` are this tab's verdicts and outrank a server echo of the same
+ * challenge, so the presentation neither flaps back to "verify" after a
+ * failure nor reopens the pay step mid-payment after a success.
+ */
+export interface EmbeddedChallenge {
+    readonly clientSecret: string;
+    readonly status: 'required' | 'in_progress' | 'completed' | 'failed';
+}
+export type PendingBillingOperation = BillingOperationIdentity & {
+    readonly phase: 'pending';
+    /** The hosted continuation the server currently offers; https only. */
+    readonly actionUrl?: string;
+    readonly challenge?: EmbeddedChallenge;
+    readonly authenticationState?: BillingAuthenticationState;
+    readonly serverPhase?: BillingOperationServerPhase;
+    /** Set while the customer's last attempt was declined and they may try again. */
+    readonly declineReason?: BillingDeclineReason;
+    readonly recoveryAction?: BillingRecoveryAction;
+    /** True once the operation has ever waited on the customer; widens the poll budget. */
+    readonly customerActionSeen: boolean;
+};
+export type FailedBillingOperation = BillingOperationIdentity & {
+    readonly phase: 'failed';
+    readonly declineReason: BillingDeclineReason;
+    readonly recoveryAction?: BillingRecoveryAction;
+    readonly retryable: boolean;
+};
+export type BillingOperationState = PendingBillingOperation | (BillingOperationIdentity & {
+    readonly phase: 'succeeded';
+}) | FailedBillingOperation
+/** This tab's poll budget ran out; the server may still settle the operation. */
+ | (BillingOperationIdentity & {
+    readonly phase: 'timed_out';
+})
+/** The server cannot settle it without a human; surface the id to support. */
+ | (BillingOperationIdentity & {
+    readonly phase: 'reconciliation_needed';
+})
+/** The session or workspace changed underneath it; nothing here may be attributed to the new scope. */
+ | (BillingOperationIdentity & {
+    readonly phase: 'superseded';
+});
+export type BillingOperationPhase = BillingOperationState['phase'];
+export type BillingOperationEvent = {
+    readonly type: 'status_polled';
+    readonly status: BillingOpStatus;
+} | {
+    readonly type: 'timed_out';
+} | {
+    readonly type: 'superseded';
+}
+/** The operation could not be found under this scope. */
+ | {
+    readonly type: 'lost';
+} | {
+    readonly type: 'presentation_switched';
+    readonly presentation: 'hosted';
+    readonly hostedDestination: HostedBillingDestination;
+} | {
+    readonly type: 'presentation_switched';
+    readonly presentation: 'embedded';
+} | {
+    readonly type: 'challenge_started';
+} | {
+    readonly type: 'challenge_settled';
+    readonly outcome: 'completed' | 'failed';
+};
+export declare function isTerminal(state: BillingOperationState): state is Exclude<BillingOperationState, PendingBillingOperation>;
+/** A continuation link the SDK will hand to a host: absolute and https, nothing else. */
+export declare function validateActionUrl(value: string | undefined): string | undefined;
+export declare function reduceBillingOperation(state: BillingOperationState, event: BillingOperationEvent): BillingOperationState;

package/dist/core/billing/operationState.js

@@ -0,0 +1,187 @@
+/**
+ * The phases the contract defines as blocked on the customer. Neither advances
+ * on its own, so an operation reporting one waits on them even before it has a
+ * link to offer.
+ */
+export function isBlockedOnCustomerPhase(phase) {
+    return (phase === 'awaiting_payment_method' || phase === 'awaiting_invoice_payment');
+}
+export function isTerminal(state) {
+    return state.phase !== 'pending';
+}
+/** A continuation link the SDK will hand to a host: absolute and https, nothing else. */
+export function validateActionUrl(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return new URL(value).protocol === 'https:' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function presentationOf(state) {
+    return state.presentation === 'hosted'
+        ? { presentation: 'hosted', hostedDestination: state.hostedDestination }
+        : { presentation: 'embedded' };
+}
+function identityOf(state) {
+    return {
+        id: state.id,
+        kind: state.kind,
+        scope: state.scope,
+        observedAt: state.observedAt,
+        attemptStartedAt: state.attemptStartedAt,
+        ...presentationOf(state)
+    };
+}
+function withPhase(state, phase) {
+    return { ...identityOf(state), phase };
+}
+/**
+ * The server's `requires_action` is an echo of a challenge this tab already
+ * settled when it names the same client secret (or none). The tab's verdict
+ * stands until the intent actually moves.
+ */
+function echoesSettledChallenge(state, status) {
+    const challenge = state.challenge;
+    if (challenge === undefined)
+        return false;
+    if (status.authentication_state !== 'requires_action')
+        return false;
+    if (challenge.status !== 'completed' && challenge.status !== 'failed') {
+        return false;
+    }
+    return (status.payment_intent_client_secret === undefined ||
+        status.payment_intent_client_secret === challenge.clientSecret);
+}
+function nextChallenge(state, status) {
+    if (state.presentation !== 'embedded')
+        return state.challenge;
+    const secret = status.payment_intent_client_secret;
+    if (secret === undefined)
+        return state.challenge;
+    if (state.challenge?.clientSecret === secret)
+        return state.challenge;
+    if (status.authentication_state !== 'requires_action')
+        return state.challenge;
+    return { clientSecret: secret, status: 'required' };
+}
+function terminalFromStatus(state, status) {
+    if (status.status === 'succeeded')
+        return withPhase(state, 'succeeded');
+    if (status.status === 'failed') {
+        return {
+            ...identityOf(state),
+            phase: 'failed',
+            declineReason: status.decline_reason ?? 'generic',
+            ...(status.recovery_action === undefined
+                ? {}
+                : { recoveryAction: status.recovery_action }),
+            retryable: status.retryable === true
+        };
+    }
+    if (status.status === 'reconciliation_needed' ||
+        status.authentication_state === 'reconciliation_needed') {
+        return withPhase(state, 'reconciliation_needed');
+    }
+    return undefined;
+}
+/**
+ * A link echoed while this tab's completed challenge is still processing
+ * points at that same challenge; surfacing it would ask the customer to
+ * redo a step they just finished.
+ */
+function nextActionUrl(state, status, authenticationState) {
+    return state.challenge?.status === 'completed' &&
+        authenticationState !== 'requires_action'
+        ? state.actionUrl
+        : validateActionUrl(status.action_url);
+}
+function reducePending(state, status) {
+    if (status.id !== state.id)
+        return state;
+    const terminal = terminalFromStatus(state, status);
+    if (terminal !== undefined)
+        return terminal;
+    const authenticationState = echoesSettledChallenge(state, status)
+        ? state.authenticationState
+        : status.authentication_state;
+    const actionUrl = nextActionUrl(state, status, authenticationState);
+    const declineReason = authenticationState === 'failed_retryable'
+        ? (status.decline_reason ?? state.declineReason)
+        : undefined;
+    return {
+        ...state,
+        challenge: nextChallenge(state, status),
+        authenticationState,
+        actionUrl,
+        serverPhase: status.phase,
+        declineReason,
+        recoveryAction: status.recovery_action,
+        customerActionSeen: state.customerActionSeen ||
+            actionUrl !== undefined ||
+            isBlockedOnCustomerPhase(status.phase) ||
+            status.authentication_state === 'requires_action'
+    };
+}
+function settleChallenge(state, outcome) {
+    if (state.challenge === undefined)
+        return state;
+    const challenge = { ...state.challenge, status: outcome };
+    if (outcome === 'failed') {
+        return {
+            ...state,
+            challenge,
+            authenticationState: 'failed_retryable',
+            customerActionSeen: true
+        };
+    }
+    return {
+        ...state,
+        challenge,
+        authenticationState: 'processing',
+        actionUrl: undefined,
+        declineReason: undefined
+    };
+}
+export function reduceBillingOperation(state, event) {
+    if (state.phase !== 'pending')
+        return state;
+    switch (event.type) {
+        case 'status_polled':
+            return reducePending(state, event.status);
+        case 'timed_out':
+            return withPhase(state, 'timed_out');
+        case 'superseded':
+            return withPhase(state, 'superseded');
+        case 'lost':
+            return withPhase(state, 'reconciliation_needed');
+        case 'presentation_switched': {
+            if (event.presentation === state.presentation)
+                return state;
+            // The challenge record survives a hosted switch so a rollback keeps the
+            // client secret; a failed challenge becomes required again on return.
+            const { presentation, hostedDestination, ...rest } = state;
+            return event.presentation === 'hosted'
+                ? {
+                    ...rest,
+                    presentation: 'hosted',
+                    hostedDestination: event.hostedDestination
+                }
+                : {
+                    ...rest,
+                    presentation: 'embedded',
+                    ...(state.challenge?.status === 'failed'
+                        ? { challenge: { ...state.challenge, status: 'required' } }
+                        : {})
+                };
+        }
+        case 'challenge_started':
+            return state.challenge?.status === 'required'
+                ? { ...state, challenge: { ...state.challenge, status: 'in_progress' } }
+                : state;
+        case 'challenge_settled':
+            return settleChallenge(state, event.outcome);
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * The copy keys behind the payment projection, with a default English table
+ * a host may override — except the safety line, which only the projection's
+ * `noChargeConfirmed` may ever unlock.
+ */
+import type { PaymentProjection, PaymentReasonKey, PaymentStep } from './paymentProjection.js';
+export type PaymentCopyKey = `billing.step.${PaymentStep}.header` | `billing.step.${PaymentStep}.body` | `billing.reason.${PaymentReasonKey}` | 'billing.action.retry' | 'billing.action.continue_verification' | 'billing.safety.nothing_was_charged';
+declare const SAFETY_KEY = "billing.safety.nothing_was_charged";
+export declare const DEFAULT_PAYMENT_COPY: Readonly<Record<PaymentCopyKey, string>>;
+export declare function createPaymentCopy(overrides?: Partial<Record<PaymentCopyKey, string>>): Readonly<Record<PaymentCopyKey, string>>;
+export interface PaymentCopyKeys {
+    readonly header: PaymentCopyKey;
+    readonly body: PaymentCopyKey;
+    readonly reason?: PaymentCopyKey;
+    readonly safety?: typeof SAFETY_KEY;
+}
+export declare function paymentCopyKeys(projection: PaymentProjection): PaymentCopyKeys;
+export {};

package/dist/core/billing/paymentCopy.js

@@ -0,0 +1,47 @@
+const SAFETY_KEY = 'billing.safety.nothing_was_charged';
+export const DEFAULT_PAYMENT_COPY = {
+    'billing.step.select.header': 'Choose an option',
+    'billing.step.select.body': 'Select a plan or credit amount.',
+    'billing.step.preview.header': 'Review payment',
+    'billing.step.preview.body': 'Confirm your selection.',
+    'billing.step.verifying.header': 'Verify your payment',
+    'billing.step.verifying.body': 'Complete verification to continue.',
+    'billing.step.canceled.header': 'Payment canceled',
+    'billing.step.canceled.body': 'The payment was canceled.',
+    'billing.step.declined.header': 'Payment declined',
+    'billing.step.declined.body': 'Try another payment method.',
+    'billing.step.processing_error.header': 'Payment could not be processed',
+    'billing.step.processing_error.body': 'Please try again.',
+    'billing.step.payment_received_hold.header': 'Payment received',
+    'billing.step.payment_received_hold.body': 'We are finishing your account update.',
+    'billing.step.success.header': 'Payment complete',
+    'billing.step.success.body': 'Your account is updated.',
+    'billing.reason.generic': 'Something went wrong.',
+    'billing.reason.checkout_expired': 'This checkout expired. Start again when you are ready.',
+    'billing.reason.card_declined': 'Your bank declined the payment.',
+    'billing.reason.insufficient_funds': 'Your bank reported insufficient funds.',
+    'billing.reason.expired_card': 'This card has expired.',
+    'billing.reason.incorrect_cvc': 'The security code did not match.',
+    'billing.reason.authentication_required': 'Your bank requires authentication.',
+    'billing.reason.authentication_failed': 'Authentication with your bank did not complete.',
+    'billing.reason.processing_error': 'The payment could not be processed right now.',
+    'billing.action.retry': 'Try again',
+    'billing.action.continue_verification': 'Continue verification',
+    [SAFETY_KEY]: 'Nothing was charged.'
+};
+export function createPaymentCopy(overrides = {}) {
+    const { [SAFETY_KEY]: _protected, ...safe } = overrides;
+    return { ...DEFAULT_PAYMENT_COPY, ...safe };
+}
+export function paymentCopyKeys(projection) {
+    return {
+        header: `billing.step.${projection.step}.header`,
+        body: `billing.step.${projection.step}.body`,
+        ...(projection.reasonKey === undefined
+            ? {}
+            : { reason: `billing.reason.${projection.reasonKey}` }),
+        ...(projection.step === 'canceled' && projection.noChargeConfirmed
+            ? { safety: SAFETY_KEY }
+            : {})
+    };
+}

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

@@ -0,0 +1,40 @@
+import type { zSavedPaymentMethod } from '@comfyorg/ingest-types/zod';
+import type { z } from 'zod';
+import type { BillingResult, BillingTransport } from './billingContracts.js';
+import type { BillingScope, BillingScopeSource } from './billingScope.js';
+export declare const PAYMENT_METHODS_ROUTE = "/billing/payment-methods";
+export type SavedPaymentMethod = z.infer<typeof zSavedPaymentMethod>;
+export type PaymentMethodsScope = BillingScope;
+export interface PaymentMethodsSnapshot {
+    readonly scope: PaymentMethodsScope;
+    readonly methods: readonly SavedPaymentMethod[];
+    /** ms since epoch at which this read settled. */
+    readonly readAt: number;
+}
+export interface PaymentMethodsReadOptions {
+    readonly signal?: AbortSignal;
+    /** Bounds the request, when this caller is the one that issues it. */
+    readonly timeoutMs?: number;
+}
+export interface PaymentMethodsReader {
+    /**
+     * Always requests. Concurrent callers for one scope share a single request.
+     */
+    read: (options?: PaymentMethodsReadOptions) => Promise<BillingResult<PaymentMethodsSnapshot>>;
+    /** The last list published for the current scope. */
+    getSnapshot: () => PaymentMethodsSnapshot | undefined;
+    /**
+     * Drops the published list without a scope change. A payment-portal round
+     * trip adds or removes a card outside this reader, so the host that sent the
+     * user there is the only thing that knows the list it holds is now wrong.
+     */
+    invalidate: () => void;
+    dispose: () => void;
+}
+export interface PaymentMethodsReaderOptions {
+    readonly transport: BillingTransport;
+    /** Where the core learns which user, workspace, and role it runs as. */
+    readonly scopeSource: BillingScopeSource;
+    readonly now?: () => number;
+}
+export declare function createPaymentMethodsReader(options: PaymentMethodsReaderOptions): PaymentMethodsReader;

package/dist/core/billing/paymentMethods.js

@@ -0,0 +1,37 @@
+/**
+ * The saved payment methods read: the cards a workspace can charge, cached per
+ * scope.
+ *
+ * Card details never reach this core beyond what the server already publishes —
+ * brand, last four digits, and which one is the default — so nothing here has
+ * to be redacted before a host renders it.
+ */
+import { zListSavedPaymentMethodsResponse } from '@comfyorg/ingest-types/zod';
+import { createScopedReader } from './scopedReader.js';
+export const PAYMENT_METHODS_ROUTE = '/billing/payment-methods';
+export function createPaymentMethodsReader(options) {
+    const { transport, scopeSource, now = Date.now } = options;
+    const reader = createScopedReader({
+        transport,
+        scopeSource,
+        route: PAYMENT_METHODS_ROUTE,
+        parse: (body) => zListSavedPaymentMethodsResponse.safeParse(body),
+        timeoutMs: (readOptions) => readOptions?.timeoutMs,
+        project: ({ data }, scope) => ({
+            status: 'ok',
+            value: { scope, methods: data, readAt: now() }
+        }),
+        // A list resolved before the change the host is reporting may be served to
+        // the callers already waiting on it, but must not be published.
+        publish: (value, fenced) => (fenced ? undefined : value)
+    });
+    return {
+        read: reader.read,
+        getSnapshot: reader.getSnapshot,
+        invalidate: () => {
+            reader.setSnapshot(undefined);
+            reader.fenceInFlight({ detach: true });
+        },
+        dispose: reader.dispose
+    };
+}

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

@@ -0,0 +1,34 @@
+/**
+ * The eight public payment states as a pure projection of one lifecycle
+ * operation. A host renders the projection and reports where it is when no
+ * operation exists; it never advances the machine itself.
+ *
+ * A server verdict outranks anything the host reports: a customer who backed
+ * out of a page after the charge went through still sees the success.
+ */
+import type { BillingDeclineReason, BillingOperationState, BillingRecoveryAction } from './operationState.js';
+export type PaymentStep = 'select' | 'preview' | 'verifying' | 'canceled' | 'declined' | 'processing_error'
+/** Reserved: the contract cannot yet tell "paid, entitlement pending" from "needs a human". */
+ | 'payment_received_hold' | 'success';
+/** Where the host is when nothing is being observed, or the customer backed out. */
+export type HostPaymentStep = 'select' | 'preview' | 'canceled';
+/**
+ * The generated `decline_reason` values plus the two the SDK adds. Every key
+ * is a coded reason; raw server or provider text never becomes one.
+ * `checkout_expired` is reserved: the generated operation status has no
+ * expired state to produce it from.
+ */
+export type PaymentReasonKey = BillingDeclineReason | 'checkout_expired' | 'generic';
+export interface PaymentProjection {
+    readonly step: PaymentStep;
+    readonly reasonKey?: PaymentReasonKey;
+    readonly recoveryAction?: BillingRecoveryAction;
+    /** Present whenever an operation backs the projection; the id support can act on. */
+    readonly operationId?: string;
+    /**
+     * Permits "nothing was charged" only once a terminal backend result rules
+     * out any later charge; the contract has no such field yet, so always false.
+     */
+    readonly noChargeConfirmed: boolean;
+}
+export declare function projectPaymentStep(operation: BillingOperationState | undefined, hostStep: HostPaymentStep): PaymentProjection;

package/dist/core/billing/paymentProjection.js

@@ -0,0 +1,56 @@
+/** Reasons that describe a processing fault rather than the customer's card. */
+const PROCESSING_REASONS = new Set([
+    'processing_error',
+    'generic'
+]);
+function stepForReason(reason) {
+    return PROCESSING_REASONS.has(reason) ? 'processing_error' : 'declined';
+}
+function projectPending(state, hostStep) {
+    const base = { operationId: state.id, noChargeConfirmed: false };
+    if (hostStep === 'canceled')
+        return { ...base, step: 'canceled' };
+    const reason = state.declineReason ??
+        (state.challenge?.status === 'failed' ? 'authentication_failed' : undefined);
+    if (reason !== undefined) {
+        return {
+            ...base,
+            step: stepForReason(reason),
+            reasonKey: reason,
+            ...(state.recoveryAction === undefined
+                ? {}
+                : { recoveryAction: state.recoveryAction })
+        };
+    }
+    const parked = state.challenge !== undefined || state.actionUrl !== undefined;
+    return { ...base, step: parked ? 'verifying' : 'preview' };
+}
+export function projectPaymentStep(operation, hostStep) {
+    if (operation === undefined) {
+        return { step: hostStep, noChargeConfirmed: false };
+    }
+    const base = { operationId: operation.id, noChargeConfirmed: false };
+    switch (operation.phase) {
+        case 'pending':
+            return projectPending(operation, hostStep);
+        case 'succeeded':
+            return { ...base, step: 'success' };
+        case 'failed':
+            return {
+                ...base,
+                step: stepForReason(operation.declineReason),
+                reasonKey: operation.declineReason,
+                ...(operation.recoveryAction === undefined
+                    ? {}
+                    : { recoveryAction: operation.recoveryAction })
+            };
+        case 'reconciliation_needed':
+            return { ...base, step: 'processing_error', reasonKey: 'generic' };
+        case 'timed_out':
+            return hostStep === 'canceled'
+                ? { ...base, step: 'canceled' }
+                : { ...base, step: 'processing_error', reasonKey: 'generic' };
+        case 'superseded':
+            return { ...base, step: hostStep === 'canceled' ? 'canceled' : 'select' };
+    }
+}