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

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

@@ -3,15 +3,16 @@
  * by design, the same way `sessionContracts` is: the transport and the typed
  * operations depend on this module, never back on each other.
  *
- * Billing reports failures as coded results rather than thrown errors, so a
- * caller cannot accidentally surface a server or payment-provider string to a
- * user. The codes carry no server text; the copy that belongs to each code is
- * owned by the billing core and localized by the host. The one server value
- * that crosses this boundary is `serverCode`, a machine identifier and never
- * copy: a command matches it against its own closed set, and a host stores it
- * where it already keeps `WorkspaceApiError.code`. Its brand makes it
- * unforgeable: only the response decoder mints one, and `unwrapServerCode`
- * names the one sanctioned widening.
+ * Billing reports failures as coded results rather than thrown errors. The
+ * codes carry no text; the copy that belongs to each code is owned by the
+ * billing core and localized by the host. Two server values cross this
+ * boundary. `serverCode` is a machine identifier and never copy: a command
+ * matches it against its own closed set, and a host stores it where it
+ * already keeps `WorkspaceApiError.code`. Its brand makes it unforgeable:
+ * only the response decoder mints one, and `unwrapServerCode` names the one
+ * sanctioned widening. `serverMessage` is the sentence the server wrote for
+ * the customer, carried so a host can show it the way the legacy client does;
+ * nothing in the core branches on it.
  */
 import type { SessionClient } from '../session.js';
 /**
@@ -38,7 +39,16 @@ export type BillingErrorCode =
 /** The identity or workspace changed while the request was in flight. */
  | 'SUPERSEDED' | 'REQUEST_FAILED'
 /** A 2xx whose body does not match the generated contract. */
- | 'MALFORMED_RESPONSE';
+ | 'MALFORMED_RESPONSE'
+/**
+ * The server already had an operation of this kind pending that this
+ * attempt did not issue. Refusing is the only honest answer: the status
+ * response names no plan, so joining it would settle whatever the earlier
+ * attempt chose and report it as this caller's success. The command
+ * usually declines before it sends anything; a subscription command also
+ * reports it when the server refuses with `SUBSCRIPTION_CHANGE_IN_PROGRESS`.
+ */
+ | 'OPERATION_ALREADY_PENDING';
 declare const billingServerCodeBrand: unique symbol;
 /**
  * An unbounded server string that is only ever a machine identifier. Nothing
@@ -57,12 +67,17 @@ export type BillingFailure = {
     readonly httpStatus?: number;
     /**
      * The coded `code` of a generated `ErrorResponse` body, when the server
-     * sent one. Its `message` is dropped on purpose: a command acts on codes
-     * it names, never on server text. Compare it through `matchesServerCode`,
-     * and widen it through `unwrapServerCode` at a host's error-store
-     * boundary. Never render it.
+     * sent one. It is the only server value a command branches on. Compare it
+     * through `matchesServerCode`, and widen it through `unwrapServerCode` at
+     * a host's error-store boundary. Never render it.
      */
     readonly serverCode?: BillingServerCode;
+    /**
+     * The `message` of that same `ErrorResponse`, present when the server sent
+     * a non-empty one. This is what a host shows the customer; the legacy
+     * client shows the same string.
+     */
+    readonly serverMessage?: string;
 };
 /** Whether a failure carries the server code a command names. */
 export declare function matchesServerCode(failure: Pick<BillingFailure, 'serverCode'>, code: string): boolean;

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

@@ -1,8 +1,12 @@
 import type { BillingServerCode } from './billingContracts.js';
 /**
- * The `code` of a generated `ErrorResponse` body, or nothing. The body's
- * `message` is read by the schema and discarded here, so it cannot travel
- * further into the SDK. This decode is the only place a `BillingServerCode`
- * is minted, and the brand it carries is erased at runtime.
+ * The `code` of a generated `ErrorResponse` body, or nothing. This decode is
+ * the only place a `BillingServerCode` is minted, and the brand it carries is
+ * erased at runtime.
  */
 export declare function readBillingErrorCode(body: unknown): BillingServerCode | undefined;
+/**
+ * The `message` of a generated `ErrorResponse` body, or nothing when the body
+ * is not that contract or the message is blank.
+ */
+export declare function readBillingErrorMessage(body: unknown): string | undefined;

package/dist/core/billing/billingErrorBody.js

@@ -1,11 +1,21 @@
 import { zErrorResponse } from '@comfyorg/ingest-types/zod';
 /**
- * The `code` of a generated `ErrorResponse` body, or nothing. The body's
- * `message` is read by the schema and discarded here, so it cannot travel
- * further into the SDK. This decode is the only place a `BillingServerCode`
- * is minted, and the brand it carries is erased at runtime.
+ * The `code` of a generated `ErrorResponse` body, or nothing. This decode is
+ * the only place a `BillingServerCode` is minted, and the brand it carries is
+ * erased at runtime.
  */
 export function readBillingErrorCode(body) {
     const parsed = zErrorResponse.safeParse(body);
     return parsed.success ? parsed.data.code : undefined;
 }
+/**
+ * The `message` of a generated `ErrorResponse` body, or nothing when the body
+ * is not that contract or the message is blank.
+ */
+export function readBillingErrorMessage(body) {
+    const parsed = zErrorResponse.safeParse(body);
+    if (!parsed.success)
+        return undefined;
+    const message = parsed.data.message.trim();
+    return message === '' ? undefined : message;
+}

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

@@ -13,14 +13,19 @@
  * `authenticationRetrySkipped` stays unset; it means a replayable retry was
  * possible and skipped, which is never the case on this transport.
  *
- * No CSRF header is sent. What stands in for one is the JSON content type
- * `exchangeBillingRequest` always sends: it makes every request non-simple,
- * so a cross-site caller has to clear a preflight it cannot satisfy. That
- * rests on the cookie's `SameSite` attribute and the backend's CORS
- * allowlist, neither of which is enforced here — sending a form-encoded or
- * otherwise CORS-simple request from this transport removes the protection.
- * A CSRF header is added here when the backend names one.
+ * Without a web session no CSRF header is sent. What stands in for one is
+ * the JSON content type `exchangeBillingRequest` always sends: it makes
+ * every request non-simple, so a cross-site caller has to clear a preflight
+ * it cannot satisfy. That rests on the cookie's `SameSite` attribute and the
+ * backend's CORS allowlist, neither of which is enforced here — sending a
+ * form-encoded or otherwise CORS-simple request from this transport removes
+ * the protection.
+ * A host on the shared web session opts in through `webSession`: headers
+ * then come from `authorize`, and a `csrf_invalid` answer is retried once
+ * after re-reading the session, only while it still belongs to the same user.
  */
+import type { RequestAuthorizer } from '../requestAuth.js';
+import type { WebSession, WebSessionResult } from '../sessionContracts.js';
 import type { BillingTransport } from './billingContracts.js';
 import type { BillingScopeSource } from './billingScope.js';
 export interface CredentialedBillingTransportOptions {
@@ -31,5 +36,16 @@ export interface CredentialedBillingTransportOptions {
     readonly credentials?: RequestCredentials;
     readonly fetchImpl?: typeof fetch;
     readonly defaultTimeoutMs?: number;
+    /** Opt-in cookie-session headers; `credentials` is then ignored. */
+    readonly webSession?: CredentialedWebSession;
+}
+export interface CredentialedWebSession {
+    readonly authorize: RequestAuthorizer;
+    readonly getSession: () => WebSession | undefined;
+    /** `readWebSession` bound to the host's ingest options. */
+    readonly readSession: (request: {
+        readonly expectedUserId: string;
+        readonly signal: AbortSignal;
+    }) => Promise<WebSessionResult>;
 }
 export declare function createCredentialedBillingTransport(options: CredentialedBillingTransportOptions): BillingTransport;

package/dist/core/billing/credentialedTransport.js

@@ -1,4 +1,5 @@
 import { sameBillingScope } from './billingScope.js';
+import { readBillingErrorCode } from './billingErrorBody.js';
 import { DEFAULT_BILLING_TIMEOUT_MS, exchangeBillingRequest, startRequestBudget } from './transportExchange.js';
 /**
  * Any scope other than the captured one supersedes the response, undefined
@@ -21,21 +22,84 @@ function markSessionEnded(response) {
         return response;
     return { ...response, authenticationNotRenewable: true };
 }
+const SESSION_ENDED = new Set([
+    'NO_SESSION',
+    'SESSION_EXPIRED',
+    'SESSION_REVOKED'
+]);
+function isCsrfInvalid(response) {
+    return (response.httpStatus === 403 &&
+        readBillingErrorCode(response.body) === 'csrf_invalid');
+}
+function rereadFailure({ code }) {
+    if (code === 'IDENTITY_CHANGED')
+        return { status: 'error', code: 'SUPERSEDED' };
+    return {
+        status: 'error',
+        code: SESSION_ENDED.has(code) ? 'NOT_AUTHENTICATED' : 'REQUEST_FAILED'
+    };
+}
+/**
+ * `csrf_invalid` is the one refusal a fresh token can fix, and the server
+ * refused before acting, so the replay is safe for a write too. The re-read
+ * is pinned to the user the request started as, and the retry to the
+ * captured workspace: a changed user abandons the request rather than
+ * finishing it as someone else.
+ */
+async function exchangeWithSession(request, webSession, session, context) {
+    const sendAs = async (current) => {
+        const authorization = await webSession.authorize({ kind: 'session', session: current }, {
+            target: 'ingest',
+            method: request.method,
+            workspaceId: context.workspaceId
+        });
+        return context.send(authorization);
+    };
+    const first = await sendAs(session);
+    if (first.status === 'error' || !isCsrfInvalid(first.value))
+        return first;
+    if (!context.stillInScope())
+        return { status: 'error', code: 'SUPERSEDED' };
+    const reread = await webSession.readSession({
+        expectedUserId: session.user.id,
+        signal: context.signal
+    });
+    if (reread.status === 'error')
+        return rereadFailure(reread);
+    if (!context.stillInScope())
+        return { status: 'error', code: 'SUPERSEDED' };
+    return sendAs(reread.session);
+}
 export function createCredentialedBillingTransport(options) {
-    const { resolveUrl, scopeSource, credentials = 'include', fetchImpl = fetch, defaultTimeoutMs = DEFAULT_BILLING_TIMEOUT_MS } = options;
+    const { resolveUrl, scopeSource, credentials = 'include', fetchImpl = fetch, defaultTimeoutMs = DEFAULT_BILLING_TIMEOUT_MS, webSession } = options;
+    const exchange = (request, signal, auth) => exchangeBillingRequest(request, {
+        fetchImpl,
+        url: resolveUrl(request.route),
+        signal,
+        ...auth
+    });
+    const sendPlain = (request, _captured, signal) => exchange(request, signal, { credentials });
+    function sessionSender(session) {
+        if (webSession === undefined || session === undefined)
+            return undefined;
+        return (request, captured, signal) => exchangeWithSession(request, webSession, session, {
+            workspaceId: captured.workspaceId,
+            signal,
+            stillInScope: () => !movedOutOfScope(scopeSource, captured),
+            send: (authorization) => exchange(request, signal, authorization)
+        });
+    }
     return async function transport(request) {
         const captured = scopeSource.getScope();
-        if (captured === undefined) {
+        const send = webSession === undefined
+            ? sendPlain
+            : sessionSender(webSession.getSession());
+        if (captured === undefined || send === undefined) {
             return { status: 'error', code: 'NOT_AUTHENTICATED' };
         }
         const budget = startRequestBudget(request.signal, request.timeoutMs ?? defaultTimeoutMs);
         try {
-            const response = await exchangeBillingRequest(request, {
-                fetchImpl,
-                url: resolveUrl(request.route),
-                signal: budget.signal,
-                credentials
-            });
+            const response = await send(request, captured, budget.signal);
             if (response.status === 'error')
                 return response;
             if (movedOutOfScope(scopeSource, captured)) {

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

@@ -0,0 +1,47 @@
+/**
+ * The billing events read: one page of the workspace's history feed, the
+ * charges, credits and adjustments behind the usage log.
+ *
+ * It is the only billing read whose request varies per call, so the page it
+ * asks for is part of what identifies the read: two callers on different
+ * pages each get their own answer rather than sharing the first one's. The
+ * snapshot reports the page the server says it served, not the one that was
+ * asked for, because the endpoint clamps a page past the end.
+ */
+import { zGetBillingEventsResponse } 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 BILLING_EVENTS_ROUTE = "/billing/events";
+export type BillingEventsData = z.infer<typeof zGetBillingEventsResponse>;
+export type BillingEvent = BillingEventsData['events'][number];
+export type BillingEventsScope = BillingScope;
+export interface BillingEventsSnapshot {
+    readonly events: readonly BillingEvent[];
+    /** 1-indexed, as the endpoint counts. */
+    readonly page: number;
+    readonly limit: number;
+    readonly total: number;
+    readonly totalPages: number;
+    readonly scope: BillingEventsScope;
+    readonly readAt: number;
+}
+export interface BillingEventsReadOptions {
+    readonly signal?: AbortSignal;
+    /** 1-indexed; the endpoint's own default applies when omitted. */
+    readonly page?: number;
+    readonly limit?: number;
+}
+export interface BillingEventsReader {
+    read: (options?: BillingEventsReadOptions) => Promise<BillingResult<BillingEventsSnapshot>>;
+    /** The last page read for the current scope; it carries which page it is. */
+    getSnapshot: () => BillingEventsSnapshot | undefined;
+    dispose: () => void;
+}
+export interface BillingEventsReaderOptions {
+    readonly transport: BillingTransport;
+    /** Where the core learns which user, workspace, and role it runs as. */
+    readonly scopeSource: BillingScopeSource;
+    readonly now?: () => number;
+}
+export declare function createBillingEventsReader(options: BillingEventsReaderOptions): BillingEventsReader;

package/dist/core/billing/events.js

@@ -0,0 +1,43 @@
+/**
+ * The billing events read: one page of the workspace's history feed, the
+ * charges, credits and adjustments behind the usage log.
+ *
+ * It is the only billing read whose request varies per call, so the page it
+ * asks for is part of what identifies the read: two callers on different
+ * pages each get their own answer rather than sharing the first one's. The
+ * snapshot reports the page the server says it served, not the one that was
+ * asked for, because the endpoint clamps a page past the end.
+ */
+import { zGetBillingEventsResponse } from '@comfyorg/ingest-types/zod';
+import { createScopedReader } from './scopedReader.js';
+export const BILLING_EVENTS_ROUTE = '/billing/events';
+/** Stable key order, so the same page asked for twice is the same request. */
+function billingEventsRoute(options) {
+    const query = new URLSearchParams();
+    if (options?.page !== undefined)
+        query.set('page', String(options.page));
+    if (options?.limit !== undefined)
+        query.set('limit', String(options.limit));
+    const search = query.toString();
+    return search === ''
+        ? BILLING_EVENTS_ROUTE
+        : `${BILLING_EVENTS_ROUTE}?${search}`;
+}
+export function createBillingEventsReader(options) {
+    const { transport, scopeSource, now = Date.now } = options;
+    const reader = createScopedReader({
+        transport,
+        scopeSource,
+        route: billingEventsRoute,
+        parse: (body) => zGetBillingEventsResponse.safeParse(body),
+        project: ({ data }, scope) => ({
+            status: 'ok',
+            value: { ...data, scope, readAt: now() }
+        })
+    });
+    return {
+        read: reader.read,
+        getSnapshot: reader.getSnapshot,
+        dispose: reader.dispose
+    };
+}

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

@@ -11,7 +11,7 @@ export type { BillingErrorCode, BillingFailure, BillingHttpResponse, BillingRequ
 export { matchesServerCode, unwrapServerCode } from './billingContracts.js';
 export type { SessionBillingTransportOptions } from './transport.js';
 export { createSessionBillingTransport } from './transport.js';
-export type { CredentialedBillingTransportOptions } from './credentialedTransport.js';
+export type { CredentialedBillingTransportOptions, CredentialedWebSession } from './credentialedTransport.js';
 export { createCredentialedBillingTransport } from './credentialedTransport.js';
 export type { BillingScope, BillingScopeSource } from './billingScope.js';
 export { sessionBillingScopeSource } from './billingScope.js';
@@ -21,32 +21,37 @@ export type { CapabilityDenialReason, CapabilityDenials } from './capabilityDeni
 export { decodeCapabilityDenials } from './capabilityDenials.js';
 export type { BillingBalance, CreditsReadOptions, CreditsReader, CreditsReaderOptions, CreditsScope, CreditsSnapshot } from './credits.js';
 export { CREDITS_ROUTE, createCreditsReader } from './credits.js';
+export type { BillingEvent, BillingEventsData, BillingEventsReader, BillingEventsReaderOptions, BillingEventsReadOptions, BillingEventsScope, BillingEventsSnapshot } from './events.js';
+export { BILLING_EVENTS_ROUTE, createBillingEventsReader } from './events.js';
 export type { BillingPlansData, PlansReadOptions, PlansReader, PlansReaderOptions, PlansScope, PlansSnapshot } from './plans.js';
 export { PLANS_ROUTE, createPlansReader } from './plans.js';
+export type { WorkspaceInvite, WorkspaceInviteCommands } from './workspaceInvites.js';
+export { WORKSPACE_INVITES_ROUTE, createWorkspaceInviteCommands } from './workspaceInvites.js';
 export type { PaymentMethodsReadOptions, PaymentMethodsReader, PaymentMethodsReaderOptions, PaymentMethodsScope, PaymentMethodsSnapshot, SavedPaymentMethod } from './paymentMethods.js';
 export { PAYMENT_METHODS_ROUTE, createPaymentMethodsReader } from './paymentMethods.js';
 export type { BillingStatusData, BillingStatusReader, BillingStatusReaderOptions, BillingStatusReadOptions, BillingStatusScope, BillingStatusSnapshot } from './status.js';
 export { BILLING_STATUS_ROUTE, createBillingStatusReader } from './status.js';
-export type { BillingAuthenticationState, BillingDeclineReason, BillingOpStatus, BillingOperationEvent, BillingOperationIdentity, BillingOperationKind, BillingOperationPhase, BillingOperationServerPhase, BillingOperationState, BillingPresentation, BillingPresentationState, BillingRecoveryAction, EmbeddedChallenge, FailedBillingOperation, HostedBillingDestination, PendingBillingOperation } from './operationState.js';
-export { isBlockedOnCustomerPhase, isTerminal, reduceBillingOperation, validateActionUrl } from './operationState.js';
-export { OPERATION_POLL_BUDGET, OPERATION_POLL_TIMING, hasExhaustedPollBudget, isParkedOnCustomer, nextPollDelayMs, pollBudgetMs } from './operationPolicy.js';
+export type { BillingAuthenticationState, BillingDeclineReason, BillingOpStatus, BillingOperationEvent, BillingOperationIdentity, BillingOperationReceipt, BillingOperationKind, BillingOperationPhase, BillingOperationServerPhase, BillingOperationState, BillingPresentation, BillingPresentationState, BillingRecoveryAction, EmbeddedChallenge, FailedBillingOperation, HostedBillingDestination, PendingBillingOperation, SucceededBillingOperation } from './operationState.js';
+export { isBlockedOnCustomerPhase, isGrantLanding, isTerminal, reduceBillingOperation, validateActionUrl } from './operationState.js';
+export { OPERATION_POLL_BUDGET, OPERATION_POLL_TIMING, customerCanActHere, hasExhaustedPollBudget, isParkedOnCustomer, nextPollDelayMs, pendingOperationActionHold, pollBudgetMs } from './operationPolicy.js';
+export type { CustomerActionHold } from './operationPolicy.js';
 export type { BillingOperationPointer, BillingOperationPointerStorage, OperationPointerStore } from './operationPointer.js';
 export { OPERATION_POINTER_MAX_AGE_MS, createOperationPointerStore, operationPointerKey } from './operationPointer.js';
 export type { PresentationRoutingInput } from './presentation.js';
 export { selectBillingPresentation } from './presentation.js';
-export type { BillingOperationFailureCategory, BillingOperationLifecycle, BillingOperationLifecycleOptions, BillingOperationTelemetryEvent, IssuedBillingOperation, PresentationSwitchOutcome } from './operationLifecycle.js';
+export type { BillingOperationFailureCategory, BillingOperationLifecycle, BillingOperationLifecycleOptions, BillingOperationTelemetryEvent, BillingRecoverOptions, IssuedBillingOperation, PresentationSwitchOutcome } from './operationLifecycle.js';
 export { createBillingOperationLifecycle, operationRoute } from './operationLifecycle.js';
 export { BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
 export type { EmbeddedChallengeOutcome, EmbeddedChallengePort } from './challengeDriver.js';
 export { driveEmbeddedChallenge } from './challengeDriver.js';
-export { readBillingErrorCode } from './billingErrorBody.js';
+export { readBillingErrorCode, readBillingErrorMessage } from './billingErrorBody.js';
 export type { BillingCommands, BillingCommandsOptions, PaymentPortalResult, PreviewSubscribeInput, PreviewSubscribeOptions, PreviewSubscribeResult, SubscribeInput, SubscriptionCommandCode, SubscriptionCommandFailure, SubscriptionCommandOutcome, SubscriptionCommandResult, SubscriptionPreview, TerminalBillingOperation } from './subscriptionCommands.js';
 export { CANCEL_SUBSCRIPTION_ROUTE, PAYMENT_PORTAL_ROUTE, PREVIEW_SUBSCRIBE_ROUTE, RESUBSCRIBE_ROUTE, SUBSCRIBE_ROUTE, createBillingCommands } from './subscriptionCommands.js';
 export type { HostPaymentStep, PaymentProjection, PaymentReasonKey, PaymentStep } from './paymentProjection.js';
-export { projectPaymentStep } from './paymentProjection.js';
-export type { PaymentCopyKey, PaymentCopyKeys } from './paymentCopy.js';
-export { DEFAULT_PAYMENT_COPY, createPaymentCopy, paymentCopyKeys } from './paymentCopy.js';
-export type { CreateHostedTopupCheckoutInput, CreateTopupCheckoutInput, HostedTopupCheckout, HostedTopupCheckoutFailure, HostedTopupCheckoutResult, TopupCommand, TopupCommandOptions, TopupDeclined, TopupDenied, TopupFailure, TopupInvalidAmount, TopupInvalidReturnUrl, TopupNoPaymentMethod, TopupNotAvailable, TopupResult, TopupSucceeded, TopupUnsettled } from './topup.js';
-export { TOPUP_CHECKOUT_ROUTE, TOPUP_ROUTE, createTopupCommand } from './topup.js';
+export { awaitsHostedAction, projectPaymentStep } from './paymentProjection.js';
+export type { DeclineDetailKey, PaymentCopyKey, PaymentCopyKeys } from './paymentCopy.js';
+export { DEFAULT_PAYMENT_COPY, createPaymentCopy, declineDetailKey, paymentCopyKeys } from './paymentCopy.js';
+export type { CreateHostedTopupCheckoutInput, CreateTopupCheckoutInput, HostedTopupCheckout, HostedTopupCheckoutFailure, HostedTopupCheckoutResult, QuoteTopupInput, TopupCommand, TopupCommandOptions, TopupDeclined, TopupDenied, TopupFailure, TopupInvalidAmount, TopupInvalidReturnUrl, TopupNoPaymentMethod, TopupNotAvailable, TopupQuote, TopupQuoteResult, TopupResult, TopupSucceeded, TopupUnsettled } from './topup.js';
+export { TOPUP_CHECKOUT_ROUTE, TOPUP_QUOTE_ROUTE, TOPUP_ROUTE, createTopupCommand } from './topup.js';
 export type { BalanceWatch, BalanceWatchOptions, BalanceWatchOutcome } from './balanceWatch.js';
 export { BALANCE_WATCH_LIFETIME_MS, BALANCE_WATCH_MAX_SCHEDULED_RUNS, BALANCE_WATCH_RETRY_GAPS_MS, createBalanceWatch } from './balanceWatch.js';

package/dist/core/billing/index.js

@@ -5,19 +5,21 @@ export { sessionBillingScopeSource } from './billingScope.js';
 export { CAPABILITIES_ROUTE, CAPABILITY_REVISION_HEADER, createCapabilitiesReader, readCapabilityRevision } from './capabilities.js';
 export { decodeCapabilityDenials } from './capabilityDenials.js';
 export { CREDITS_ROUTE, createCreditsReader } from './credits.js';
+export { BILLING_EVENTS_ROUTE, createBillingEventsReader } from './events.js';
 export { PLANS_ROUTE, createPlansReader } from './plans.js';
+export { WORKSPACE_INVITES_ROUTE, createWorkspaceInviteCommands } from './workspaceInvites.js';
 export { PAYMENT_METHODS_ROUTE, createPaymentMethodsReader } from './paymentMethods.js';
 export { BILLING_STATUS_ROUTE, createBillingStatusReader } from './status.js';
-export { isBlockedOnCustomerPhase, isTerminal, reduceBillingOperation, validateActionUrl } from './operationState.js';
-export { OPERATION_POLL_BUDGET, OPERATION_POLL_TIMING, hasExhaustedPollBudget, isParkedOnCustomer, nextPollDelayMs, pollBudgetMs } from './operationPolicy.js';
+export { isBlockedOnCustomerPhase, isGrantLanding, isTerminal, reduceBillingOperation, validateActionUrl } from './operationState.js';
+export { OPERATION_POLL_BUDGET, OPERATION_POLL_TIMING, customerCanActHere, hasExhaustedPollBudget, isParkedOnCustomer, nextPollDelayMs, pendingOperationActionHold, pollBudgetMs } from './operationPolicy.js';
 export { OPERATION_POINTER_MAX_AGE_MS, createOperationPointerStore, operationPointerKey } from './operationPointer.js';
 export { selectBillingPresentation } from './presentation.js';
 export { createBillingOperationLifecycle, operationRoute } from './operationLifecycle.js';
 export { BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
 export { driveEmbeddedChallenge } from './challengeDriver.js';
-export { readBillingErrorCode } from './billingErrorBody.js';
+export { readBillingErrorCode, readBillingErrorMessage } from './billingErrorBody.js';
 export { CANCEL_SUBSCRIPTION_ROUTE, PAYMENT_PORTAL_ROUTE, PREVIEW_SUBSCRIBE_ROUTE, RESUBSCRIBE_ROUTE, SUBSCRIBE_ROUTE, createBillingCommands } from './subscriptionCommands.js';
-export { projectPaymentStep } from './paymentProjection.js';
-export { DEFAULT_PAYMENT_COPY, createPaymentCopy, paymentCopyKeys } from './paymentCopy.js';
-export { TOPUP_CHECKOUT_ROUTE, TOPUP_ROUTE, createTopupCommand } from './topup.js';
+export { awaitsHostedAction, projectPaymentStep } from './paymentProjection.js';
+export { DEFAULT_PAYMENT_COPY, createPaymentCopy, declineDetailKey, paymentCopyKeys } from './paymentCopy.js';
+export { TOPUP_CHECKOUT_ROUTE, TOPUP_QUOTE_ROUTE, TOPUP_ROUTE, createTopupCommand } from './topup.js';
 export { BALANCE_WATCH_LIFETIME_MS, BALANCE_WATCH_MAX_SCHEDULED_RUNS, BALANCE_WATCH_RETRY_GAPS_MS, createBalanceWatch } from './balanceWatch.js';

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

@@ -1,3 +1,21 @@
+/**
+ * The operation lifecycle every billing command sits on: adopt a
+ * `billing_op_id`, observe it to a terminal state, and reattach to it after a
+ * reload, a focus, or a return to the workspace — without ever creating a
+ * replacement operation. Commands issue the request; this owns everything
+ * that happens to the id afterwards.
+ *
+ * Framework-free by construction. Nothing here opens a URL, drives a
+ * payment-provider challenge, or listens to a document: a host renders the
+ * state (`actionUrl`, `challenge`), performs those effects itself, and
+ * reports back through `reportChallenge*` and `wake`.
+ *
+ * Behavior is ported from the cloud app's `billingOperationStore` — the
+ * cadence, the budgets, the parked-on-customer rules, the challenge echo
+ * suppression — and from the pending-checkout pointer's terminal rule; the
+ * wiring onto the scope source, the scope tracker, and the generated
+ * contract is new.
+ */
 import { BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js';
 import type { BillingResult, BillingTransport } from './billingContracts.js';
 import type { BillingScope, BillingScopeSource } from './billingScope.js';
@@ -39,6 +57,13 @@ export interface BillingOperationLifecycleOptions {
     readonly statusReader: BillingStatusReader;
     /** Tab-local storage for the operation pointer; absent means nothing survives a reload. */
     readonly pointerStorage?: BillingOperationPointerStorage;
+    /**
+     * Keep the pointer of an operation that succeeded or needs reconciliation,
+     * for a host whose page is the checkout itself: a revisit reads it back
+     * through `recover({ includeSettled: true })`. A plain `recover` never
+     * sees it, so every other caller recovers exactly what it did before.
+     */
+    readonly retainSettledPointer?: boolean;
     /** Whether the host can drive an in-page challenge right now. Absent routes everything hosted. */
     readonly embeddedCheckoutAvailable?: () => boolean;
     /** Which origin serves a hosted page right now. Absent keeps every hosted operation on the provider page. */
@@ -46,6 +71,14 @@ export interface BillingOperationLifecycleOptions {
     readonly onTelemetry?: (event: BillingOperationTelemetryEvent) => void;
     readonly now?: () => number;
 }
+export interface BillingRecoverOptions {
+    /**
+     * Also read back the operation a retained pointer says already settled, so
+     * the checkout that issued it can show it finished. Only a lifecycle with
+     * `retainSettledPointer` keeps one.
+     */
+    readonly includeSettled?: boolean;
+}
 export interface BillingOperationLifecycle {
     /**
      * Runs a command on the lifecycle: single-flight per kind, the backend's
@@ -59,7 +92,7 @@ export interface BillingOperationLifecycle {
      * pending operation first, then the tab-local pointer. Resolves undefined
      * when there is nothing to recover.
      */
-    recover: () => Promise<BillingResult<BillingOperationState | undefined>>;
+    recover: (options?: BillingRecoverOptions) => Promise<BillingResult<BillingOperationState | undefined>>;
     /** The host became visible or focused: poll every pending operation now. */
     wake: () => void;
     /** Moves the operation between presentations under the same id. */