@comfyorg/account-core 1.0.0-alpha.0

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

@@ -0,0 +1,44 @@
+/**
+ * The plans read: the catalog a workspace may subscribe to, cached per scope.
+ *
+ * Availability, seat costs, and the credit-stop ladder are all resolved by the
+ * server for the actor that asked, so the response is cached under the scope it
+ * was resolved for and no plan is filtered, ranked, or priced here.
+ */
+import { zGetBillingPlansResponse } 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 PLANS_ROUTE = "/billing/plans";
+export type BillingPlansData = z.infer<typeof zGetBillingPlansResponse>;
+export type PlansScope = BillingScope;
+export interface PlansSnapshot {
+    readonly scope: PlansScope;
+    readonly data: BillingPlansData;
+    /** ms since epoch at which this read settled. */
+    readonly readAt: number;
+}
+export interface PlansReadOptions {
+    readonly signal?: AbortSignal;
+    /** Bounds the request, when this caller is the one that issues it. */
+    readonly timeoutMs?: number;
+}
+export interface PlansReader {
+    /**
+     * Always requests. The catalog changes rarely, but nothing in the response
+     * declares how long it stays valid, so the host decides when to re-read
+     * rather than the core inventing a freshness window nobody published.
+     * Concurrent callers for one scope still share a single request.
+     */
+    read: (options?: PlansReadOptions) => Promise<BillingResult<PlansSnapshot>>;
+    /** The last catalog published for the current scope. */
+    getSnapshot: () => PlansSnapshot | undefined;
+    dispose: () => void;
+}
+export interface PlansReaderOptions {
+    readonly transport: BillingTransport;
+    /** Where the core learns which user, workspace, and role it runs as. */
+    readonly scopeSource: BillingScopeSource;
+    readonly now?: () => number;
+}
+export declare function createPlansReader(options: PlansReaderOptions): PlansReader;

package/dist/core/billing/plans.js

@@ -0,0 +1,29 @@
+/**
+ * The plans read: the catalog a workspace may subscribe to, cached per scope.
+ *
+ * Availability, seat costs, and the credit-stop ladder are all resolved by the
+ * server for the actor that asked, so the response is cached under the scope it
+ * was resolved for and no plan is filtered, ranked, or priced here.
+ */
+import { zGetBillingPlansResponse } from '@comfyorg/ingest-types/zod';
+import { createScopedReader } from './scopedReader.js';
+export const PLANS_ROUTE = '/billing/plans';
+export function createPlansReader(options) {
+    const { transport, scopeSource, now = Date.now } = options;
+    const reader = createScopedReader({
+        transport,
+        scopeSource,
+        route: PLANS_ROUTE,
+        parse: (body) => zGetBillingPlansResponse.safeParse(body),
+        timeoutMs: (readOptions) => readOptions?.timeoutMs,
+        project: ({ data }, scope) => ({
+            status: 'ok',
+            value: { scope, data, readAt: now() }
+        })
+    });
+    return {
+        read: reader.read,
+        getSnapshot: reader.getSnapshot,
+        dispose: reader.dispose
+    };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * The one place a billing operation is routed to the embedded challenge or
+ * the hosted page. Hosts report whether they can drive an embedded challenge
+ * at all; they never choose the route.
+ *
+ * Every rule fails toward hosted, which works on every rail and needs
+ * nothing from the host but a way to open a URL.
+ */
+import type { BillingPresentation } from './operationState.js';
+import type { BillingStatusData } from './status.js';
+export interface PresentationRoutingInput {
+    /** The host can drive an in-page challenge: its provider adapter and key are present. */
+    readonly embeddedCheckoutAvailable: boolean;
+    readonly billingRail: BillingStatusData['billing_rail'];
+    /** A hosted continuation the command response already carried. */
+    readonly hostedUrl?: string;
+    /** An in-page challenge the command response already carried. */
+    readonly clientSecret?: string;
+}
+export declare function selectBillingPresentation(input: PresentationRoutingInput): BillingPresentation;

package/dist/core/billing/presentation.js

@@ -0,0 +1,10 @@
+export function selectBillingPresentation(input) {
+    // The backend answered with a page and no challenge: it has decided.
+    if (input.hostedUrl !== undefined && input.clientSecret === undefined) {
+        return 'hosted';
+    }
+    if (!input.embeddedCheckoutAvailable)
+        return 'hosted';
+    // Only the workspace Stripe rail exposes payment intents to the client.
+    return input.billingRail === 'stripe' ? 'embedded' : 'hosted';
+}

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

@@ -0,0 +1,61 @@
+/**
+ * The one shape every billing read has: capture the scope, issue a validated
+ * request, and refuse to attribute the answer to a scope that has since taken
+ * over. Only the route, the decoder, and the projection into a snapshot differ
+ * between reads, so only those live in the readers.
+ *
+ * What the skeleton owns is what a reader therefore cannot get wrong on its
+ * own: one shared request per scope, a caller's signal releasing only that
+ * caller, the publish fence that reports a late answer as `SUPERSEDED`, and
+ * the denial that drops a published snapshot unless it predates a change the
+ * host reported.
+ */
+import type { BillingResult, BillingTransport } from './billingContracts.js';
+import type { BillingScope, BillingScopeSource } from './billingScope.js';
+import type { ParsedBillingBody, ValidatedBillingResponse } from './sharedRead.js';
+/** Every reader's read options carry at least the caller's release signal. */
+export interface ScopedReadOptions {
+    readonly signal?: AbortSignal;
+}
+export interface ScopedReaderDefinition<TData, TSnapshot, TOptions extends ScopedReadOptions> {
+    readonly transport: BillingTransport;
+    /** Where the core learns which user, workspace, and role it runs as. */
+    readonly scopeSource: BillingScopeSource;
+    readonly route: string;
+    readonly parse: (body: unknown) => ParsedBillingBody<TData>;
+    /**
+     * The reader's own reading of a validated response. Returning a failure is
+     * how a reader refuses an answer its decoder alone cannot reject.
+     */
+    readonly project: (response: ValidatedBillingResponse<TData>, scope: BillingScope) => BillingResult<TSnapshot>;
+    /** The request budget, for a read that bounds itself or lets its caller. */
+    readonly timeoutMs?: (options: TOptions | undefined) => number | undefined;
+    /**
+     * The published snapshot this call may be served from instead of asking.
+     * Absent for a reader that always requests.
+     */
+    readonly cached?: (snapshot: TSnapshot | undefined, scope: BillingScope, options: TOptions | undefined) => TSnapshot | undefined;
+    /**
+     * What to publish once the read settles in scope, given whether the host
+     * fenced the request while it was in flight. `undefined` publishes nothing,
+     * and the callers waiting on the request are still served what it read.
+     */
+    readonly publish?: (value: TSnapshot, fenced: boolean) => TSnapshot | undefined;
+}
+export interface ScopedReader<TSnapshot, TOptions extends ScopedReadOptions> {
+    readonly read: (options?: TOptions) => Promise<BillingResult<TSnapshot>>;
+    readonly getSnapshot: () => TSnapshot | undefined;
+    /** Replaces what `getSnapshot` publishes; `undefined` drops it. */
+    readonly setSnapshot: (snapshot: TSnapshot | undefined) => void;
+    /**
+     * Marks a request already in flight as predating a change the host is
+     * reporting, leaving `publish` to decide what its answer is still worth.
+     * `detach` also frees the shared slot, so the read that follows issues its
+     * own request rather than joining the one that predates the change.
+     */
+    readonly fenceInFlight: (options?: {
+        readonly detach?: boolean;
+    }) => void;
+    readonly dispose: () => void;
+}
+export declare function createScopedReader<TData, TSnapshot, TOptions extends ScopedReadOptions>(definition: ScopedReaderDefinition<TData, TSnapshot, TOptions>): ScopedReader<TSnapshot, TOptions>;

package/dist/core/billing/scopedReader.js

@@ -0,0 +1,108 @@
+import { createBillingScopeTracker } from './billingScope.js';
+import { matchesScopedRead, readValidatedBillingResponse, releaseOnAbort } from './sharedRead.js';
+function publishAsRead(value) {
+    return value;
+}
+export function createScopedReader(definition) {
+    const { transport, scopeSource, route, parse, project, timeoutMs, cached, publish = publishAsRead } = definition;
+    let snapshot;
+    let inFlight;
+    const lifetime = { disposed: false };
+    const scopeTracker = createBillingScopeTracker(scopeSource, () => {
+        snapshot = undefined;
+        inFlight = undefined;
+    });
+    async function request(scope, options) {
+        const budget = timeoutMs?.(options);
+        const billingRequest = {
+            method: 'GET',
+            route,
+            ...(budget === undefined ? {} : { timeoutMs: budget })
+        };
+        const response = await readValidatedBillingResponse(transport, billingRequest, parse);
+        if (response.status === 'error')
+            return response;
+        return project(response.value, scope);
+    }
+    function publishSettled(value, fenced) {
+        const published = publish(value, fenced);
+        if (published !== undefined)
+            snapshot = published;
+        return { status: 'ok', value: published ?? value };
+    }
+    async function settle(context, pending, options) {
+        const result = await request(context.scope, options);
+        // The publish guard. Between issuing the request and settling it the host
+        // may have changed workspace or signed out, so an answer cached now would
+        // be attributed to whoever is signed in next, and a failure says nothing
+        // about the scope that has since taken over.
+        if (lifetime.disposed || !scopeTracker.isCurrent(context)) {
+            return { status: 'error', code: 'SUPERSEDED' };
+        }
+        if (result.status !== 'ok') {
+            // A denial that predates a fence is no evidence about what a later read
+            // published, and clearing on it would drop a fresh answer for a stale
+            // refusal.
+            if (result.code === 'ACCESS_DENIED' && !pending.fenced) {
+                snapshot = undefined;
+            }
+            return result;
+        }
+        return publishSettled(result.value, pending.fenced);
+    }
+    async function read(options) {
+        if (lifetime.disposed)
+            return { status: 'error', code: 'SUPERSEDED' };
+        const context = scopeTracker.capture();
+        if (context === undefined) {
+            return { status: 'error', code: 'NOT_AUTHENTICATED' };
+        }
+        const served = cached?.(snapshot, context.scope, options);
+        if (served !== undefined)
+            return { status: 'ok', value: served };
+        // One read per scope. A caller arriving mid-flight for the same scope
+        // joins rather than issuing a second identical request; a caller for a
+        // different scope starts its own, and the older one can no longer publish.
+        if (matchesScopedRead(inFlight, context)) {
+            return releaseOnAbort(inFlight.promise, options?.signal);
+        }
+        // No caller signal reaches the shared request: it is bounded by its own
+        // timeout, and one caller walking away must not fail the readers still
+        // waiting on it. Each caller's signal releases only that caller, below.
+        const pending = { fenced: false };
+        const attempt = {
+            context,
+            promise: settle(context, pending, options),
+            pending
+        };
+        inFlight = attempt;
+        // The slot is released when the request settles, not when this caller
+        // stops waiting, so an abandoned read still serves whoever joined it.
+        const release = () => {
+            if (inFlight === attempt)
+                inFlight = undefined;
+        };
+        attempt.promise.then(release, release);
+        return releaseOnAbort(attempt.promise, options?.signal);
+    }
+    return {
+        read,
+        getSnapshot: () => snapshot,
+        setSnapshot: (next) => {
+            snapshot = next;
+        },
+        fenceInFlight: (fenceOptions) => {
+            if (inFlight === undefined)
+                return;
+            inFlight.pending.fenced = true;
+            if (fenceOptions?.detach === true)
+                inFlight = undefined;
+        },
+        dispose: () => {
+            lifetime.disposed = true;
+            snapshot = undefined;
+            inFlight = undefined;
+            scopeTracker.dispose();
+        }
+    };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Joining a caller to a shared in-flight read without letting either one
+ * decide the other's fate.
+ *
+ * Deduplication and cancellation pull in opposite directions: if the request
+ * carries the first caller's signal, that caller aborting fails every reader
+ * that joined it, and a joiner aborting does nothing at all. So the shared
+ * request carries no caller signal — it is bounded by its own timeout — and
+ * each caller's signal releases only that caller's wait.
+ *
+ * This is the semantic `SessionClient.ensureFresh` already documents for its
+ * shared mint: concurrent callers share one request, and a later caller's
+ * signal releases that caller with a transient failure without cancelling the
+ * work the others are still waiting on.
+ */
+import type { BillingRequest, BillingResult, BillingTransport } from './billingContracts.js';
+import type { BillingScopeContext } from './billingScope.js';
+export type ParsedBillingBody<T> = {
+    readonly success: true;
+    readonly data: T;
+} | {
+    readonly success: false;
+};
+export interface ValidatedBillingResponse<T> {
+    readonly data: T;
+    readonly body: unknown;
+    readonly httpStatus: number;
+}
+export declare function matchesScopedRead<T extends {
+    readonly context: BillingScopeContext;
+}>(read: T | undefined, context: BillingScopeContext): read is T;
+export declare function readValidatedBillingResponse<T>(transport: BillingTransport, request: BillingRequest, parse: (body: unknown) => ParsedBillingBody<T>): Promise<BillingResult<ValidatedBillingResponse<T>>>;
+export declare function releaseOnAbort<T>(shared: Promise<BillingResult<T>>, signal: AbortSignal | undefined): Promise<BillingResult<T>>;

package/dist/core/billing/sharedRead.js

@@ -0,0 +1,59 @@
+import { sameBillingScope } from './billingScope.js';
+import { readBillingErrorCode } from './billingErrorBody.js';
+import { codeForHttpStatus } from './httpStatus.js';
+/**
+ * An abandoned wait is transient, the same bucket the transport reports an
+ * abort under: the caller stopped waiting, which says nothing about whether
+ * the read would have succeeded.
+ */
+const ABANDONED = {
+    status: 'error',
+    code: 'REQUEST_FAILED'
+};
+export function matchesScopedRead(read, context) {
+    return (read !== undefined &&
+        read.context.generation === context.generation &&
+        sameBillingScope(read.context.scope, context.scope));
+}
+export async function readValidatedBillingResponse(transport, request, parse) {
+    const response = await transport(request);
+    if (response.status === 'error')
+        return response;
+    const { httpStatus, body } = response.value;
+    if (httpStatus < 200 || httpStatus >= 300) {
+        const serverCode = readBillingErrorCode(body);
+        return {
+            status: 'error',
+            code: codeForHttpStatus(response.value),
+            httpStatus,
+            ...(serverCode === undefined ? {} : { serverCode })
+        };
+    }
+    const parsed = parse(body);
+    if (!parsed.success) {
+        return { status: 'error', code: 'MALFORMED_RESPONSE', httpStatus };
+    }
+    return { status: 'ok', value: { data: parsed.data, body, httpStatus } };
+}
+export function releaseOnAbort(shared, signal) {
+    if (signal === undefined)
+        return shared.catch(() => ABANDONED);
+    // An 'abort' listener never fires for a signal that is already aborted, so
+    // a caller who cancelled before joining would otherwise wait for the full
+    // shared read.
+    if (signal.aborted) {
+        void shared.catch(() => { });
+        return Promise.resolve(ABANDONED);
+    }
+    return new Promise((resolve) => {
+        const onAbort = () => resolve(ABANDONED);
+        signal.addEventListener('abort', onAbort, { once: true });
+        shared.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, () => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(ABANDONED);
+        });
+    });
+}

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

@@ -0,0 +1,27 @@
+import { zBillingStatusResponse } 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_STATUS_ROUTE = "/billing/status";
+export type BillingStatusData = z.infer<typeof zBillingStatusResponse>;
+export type BillingStatusScope = BillingScope;
+export interface BillingStatusSnapshot {
+    readonly status: BillingStatusData;
+    readonly scope: BillingStatusScope;
+    readonly readAt: number;
+}
+export interface BillingStatusReadOptions {
+    readonly signal?: AbortSignal;
+}
+export interface BillingStatusReader {
+    read: (options?: BillingStatusReadOptions) => Promise<BillingResult<BillingStatusSnapshot>>;
+    getSnapshot: () => BillingStatusSnapshot | undefined;
+    dispose: () => void;
+}
+export interface BillingStatusReaderOptions {
+    readonly transport: BillingTransport;
+    /** Where the core learns which user, workspace, and role it runs as. */
+    readonly scopeSource: BillingScopeSource;
+    readonly now?: () => number;
+}
+export declare function createBillingStatusReader(options: BillingStatusReaderOptions): BillingStatusReader;

package/dist/core/billing/status.js

@@ -0,0 +1,21 @@
+import { zBillingStatusResponse } from '@comfyorg/ingest-types/zod';
+import { createScopedReader } from './scopedReader.js';
+export const BILLING_STATUS_ROUTE = '/billing/status';
+export function createBillingStatusReader(options) {
+    const { transport, scopeSource, now = Date.now } = options;
+    const reader = createScopedReader({
+        transport,
+        scopeSource,
+        route: BILLING_STATUS_ROUTE,
+        parse: (body) => zBillingStatusResponse.safeParse(body),
+        project: ({ data }, scope) => ({
+            status: 'ok',
+            value: { status: data, scope, readAt: now() }
+        })
+    });
+    return {
+        read: reader.read,
+        getSnapshot: reader.getSnapshot,
+        dispose: reader.dispose
+    };
+}