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

package/dist/core/billing/topup.js

@@ -10,10 +10,11 @@
  * own vocabulary, and the terminal operation is embedded whenever one was
  * observed so a host reads the coded decline and recovery action from it.
  */
-import { zCreateTopupCheckoutRequest, zCreateTopupCheckoutResponse, zCreateTopupRequest, zCreateTopupResponse } from '@comfyorg/ingest-types/zod';
+import { zCreateTopupCheckoutRequest, zCreateTopupCheckoutResponse, zCreateTopupRequest, zCreateTopupResponse, zTopupQuoteResponse } from '@comfyorg/ingest-types/zod';
 import { matchesServerCode } from './billingContracts.js';
 import { isTerminal, validateActionUrl } from './operationState.js';
 import { readValidatedBillingResponse } from './sharedRead.js';
+import { wireCents } from './wireCents.js';
 export const TOPUP_ROUTE = '/billing/topup';
 /**
  * The hosted variant: a provider-hosted Checkout session with no operation to
@@ -21,6 +22,14 @@ export const TOPUP_ROUTE = '/billing/topup';
  * through a webhook, so completion is the host's return plus a balance watch.
  */
 export const TOPUP_CHECKOUT_ROUTE = '/billing/topup/checkout';
+/** A read the backend shapes as a POST: nothing is charged or reserved. */
+export const TOPUP_QUOTE_ROUTE = '/billing/topup/quote';
+/** The server's own server code for an amount it will not sell. */
+const INVALID_AMOUNT_SERVER_CODE = 'INVALID_AMOUNT';
+const TopupQuoteSchema = zTopupQuoteResponse.extend({
+    amount_cents: wireCents,
+    credits: wireCents
+});
 /** The one coded error body this command acts on; every other code stays a `BillingFailure`. */
 const NO_PAYMENT_METHOD_SERVER_CODE = 'NO_PAYMENT_METHOD';
 const INVALID_AMOUNT = {
@@ -205,5 +214,30 @@ export function createTopupCommand(options) {
                 : {})
         };
     }
-    return { createTopupCheckout, createHostedTopupCheckout };
+    async function quoteTopup(input) {
+        const { amountCents, signal } = input;
+        if (!wireCents.positive().safeParse(amountCents).success)
+            return INVALID_AMOUNT;
+        const response = await readValidatedBillingResponse(transport, {
+            method: 'POST',
+            route: TOPUP_QUOTE_ROUTE,
+            body: { amount_cents: amountCents },
+            ...(signal === undefined ? {} : { signal })
+        }, (raw) => TopupQuoteSchema.safeParse(raw));
+        if (response.status === 'error') {
+            if (matchesServerCode(response, INVALID_AMOUNT_SERVER_CODE))
+                return INVALID_AMOUNT;
+            return response.httpStatus === 404 ? NOT_AVAILABLE : response;
+        }
+        const quote = response.value.data;
+        return {
+            status: 'ok',
+            value: {
+                amountCents: quote.amount_cents,
+                credits: quote.credits,
+                expiresAt: quote.expires_at
+            }
+        };
+    }
+    return { quoteTopup, createTopupCheckout, createHostedTopupCheckout };
 }

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

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/**
+ * The generated schemas coerce every int64 to a `bigint`, which no caller can
+ * add to a price or hand to a currency formatter, while the generated *type*
+ * for the same field is a `number`. Billing amounts and credit counts sit well
+ * inside the JavaScript-safe range, so they are read as safe integers.
+ */
+export declare const wireCents: z.ZodNumber;

package/dist/core/billing/wireCents.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/**
+ * The generated schemas coerce every int64 to a `bigint`, which no caller can
+ * add to a price or hand to a currency formatter, while the generated *type*
+ * for the same field is a `number`. Billing amounts and credit counts sit well
+ * inside the JavaScript-safe range, so they are read as safe integers.
+ */
+export const wireCents = z.number().int().safe();

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

@@ -0,0 +1,12 @@
+import type { zPendingInvite } from '@comfyorg/ingest-types/zod';
+import type { z } from 'zod';
+import type { BillingResult, BillingTransport } from './billingContracts.js';
+export declare const WORKSPACE_INVITES_ROUTE = "/workspace/invites";
+export type WorkspaceInvite = z.infer<typeof zPendingInvite>;
+export interface WorkspaceInviteCommands {
+    readonly listPendingInvites: () => Promise<BillingResult<readonly WorkspaceInvite[]>>;
+    readonly createInvite: (email: string) => Promise<BillingResult<WorkspaceInvite>>;
+}
+export declare function createWorkspaceInviteCommands(options: {
+    readonly transport: BillingTransport;
+}): WorkspaceInviteCommands;

package/dist/core/billing/workspaceInvites.js

@@ -0,0 +1,26 @@
+/**
+ * The workspace's pending invites, over the same session transport the
+ * billing commands use, so a host that checks out a team plan can invite the
+ * team without a second client. The workspace is the one the transport's
+ * token was minted for.
+ */
+import { zCreateWorkspaceInviteResponse, zListInvitesResponse } from '@comfyorg/ingest-types/zod';
+import { readValidatedBillingResponse } from './sharedRead.js';
+export const WORKSPACE_INVITES_ROUTE = '/workspace/invites';
+export function createWorkspaceInviteCommands(options) {
+    const { transport } = options;
+    async function listPendingInvites() {
+        const response = await readValidatedBillingResponse(transport, { method: 'GET', route: WORKSPACE_INVITES_ROUTE }, (body) => zListInvitesResponse.safeParse(body));
+        return response.status === 'error'
+            ? response
+            : { status: 'ok', value: response.value.data.invites };
+    }
+    async function createInvite(email) {
+        const body = { email };
+        const response = await readValidatedBillingResponse(transport, { method: 'POST', route: WORKSPACE_INVITES_ROUTE, body }, (raw) => zCreateWorkspaceInviteResponse.safeParse(raw));
+        return response.status === 'error'
+            ? response
+            : { status: 'ok', value: response.value.data };
+    }
+    return { listPendingInvites, createInvite };
+}

package/dist/core/identity.d.ts

@@ -2,20 +2,20 @@ import type { AccountUser } from './sessionContracts.js';
 /**
  * The identity boundary. An internal port, not a host adapter: real hosts
  * get their implementation from `@comfyorg/account-core/firebase`; tests brand a
- * fake through `@comfyorg/account-core/testing`. `attachIdentity` accepts only
- * the branded form.
+ * fake through `@comfyorg/account-core/testing`. `createSessionClient` accepts
+ * only the branded form.
  */
 export interface IdentityPort<TUser extends AccountUser = AccountUser> {
     onUserChanged: (callback: (user: TUser | null) => void) => () => void;
 }
 /**
- * Only the package's own identity entry (and the `./testing` seam) can mint
- * an identity the session client accepts. A host cannot hand in its own
- * provider: the symbol lives in a module the exports map never exposes.
+ * The brand is a compile-time gate only: `createSessionClient` rejects an
+ * unbranded port in the type system, and no runtime check remains. The
+ * package's own identity entries mint it, and `./testing` deliberately
+ * re-exports the minter as `createTestIdentity` so a suite can brand a fake.
  */
 export declare const identityBrand: unique symbol;
 export interface AccountIdentity<TUser extends AccountUser = AccountUser> extends IdentityPort<TUser> {
     readonly [identityBrand]: true;
 }
 export declare function brandIdentity<TUser extends AccountUser>(port: IdentityPort<TUser>): AccountIdentity<TUser>;
-export declare function isAccountIdentity(value: unknown): value is AccountIdentity;

package/dist/core/identity.js

@@ -1,16 +1,10 @@
 /**
- * Only the package's own identity entry (and the `./testing` seam) can mint
- * an identity the session client accepts. A host cannot hand in its own
- * provider: the symbol lives in a module the exports map never exposes.
+ * The brand is a compile-time gate only: `createSessionClient` rejects an
+ * unbranded port in the type system, and no runtime check remains. The
+ * package's own identity entries mint it, and `./testing` deliberately
+ * re-exports the minter as `createTestIdentity` so a suite can brand a fake.
  */
 export const identityBrand = Symbol('@comfyorg/account-core identity');
 export function brandIdentity(port) {
     return { ...port, [identityBrand]: true };
 }
-export function isAccountIdentity(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    const candidate = value;
-    return (candidate[identityBrand] === true &&
-        typeof candidate.onUserChanged === 'function');
-}

package/dist/core/lazyIdentity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * An identity port whose real identity is loaded and subscribed only on
+ * `activate()`, so a host can construct the session client at module load
+ * while the identity's module (and the SDK behind it) stays a lazy chunk.
+ */
+import type { AccountIdentity } from './identity.js';
+import type { AccountUser } from './sessionContracts.js';
+/**
+ * Single-owner: one driver calls `activate()` and `deactivate()`; a second
+ * consumer would share and tear down the same activation.
+ */
+export interface LazyIdentity<TUser extends AccountUser> extends AccountIdentity<TUser> {
+    /**
+     * Resolves once the loaded identity has delivered its current user, or at
+     * once when `deactivate()` interrupts the activation; the caller re-checks
+     * its own liveness after the await.
+     */
+    activate: () => Promise<void>;
+    /**
+     * Unsubscribes the real identity, signing subscribers out if it had
+     * delivered a signed-in user.
+     */
+    deactivate: () => void;
+}
+/**
+ * An identity that has already settled signed-out: for a `load` that
+ * legitimately has no source to resolve, so the port still delivers once and
+ * a subscriber reaches signed-out instead of hanging in `pending` forever.
+ */
+export declare function createUnavailableIdentity<TUser extends AccountUser>(): AccountIdentity<TUser>;
+export declare function createLazyIdentity<TUser extends AccountUser>(load: () => Promise<AccountIdentity<TUser>>): LazyIdentity<TUser>;

package/dist/core/lazyIdentity.js

@@ -0,0 +1,96 @@
+import { brandIdentity } from './identity.js';
+/**
+ * An identity that has already settled signed-out: for a `load` that
+ * legitimately has no source to resolve, so the port still delivers once and
+ * a subscriber reaches signed-out instead of hanging in `pending` forever.
+ */
+export function createUnavailableIdentity() {
+    return brandIdentity({
+        onUserChanged: (callback) => {
+            callback(null);
+            return () => undefined;
+        }
+    });
+}
+export function createLazyIdentity(load) {
+    const listeners = new Set();
+    let generation = 0;
+    let activation;
+    let settleActivation;
+    let unsubscribe;
+    let lastDelivered;
+    function deliver(user) {
+        lastDelivered = { user };
+        listeners.forEach((listener) => listener(user));
+    }
+    async function subscribe(started, resolve) {
+        const identity = await load();
+        if (started !== generation)
+            return;
+        unsubscribe = identity.onUserChanged((user) => {
+            if (started !== generation)
+                return;
+            resolve();
+            deliver(user);
+        });
+    }
+    function activate() {
+        if (activation)
+            return activation;
+        const started = ++generation;
+        activation = new Promise((resolve, reject) => {
+            settleActivation = resolve;
+            subscribe(started, resolve).catch((error) => {
+                if (started !== generation)
+                    return;
+                activation = undefined;
+                settleActivation = undefined;
+                // A load that can't produce an identity still owes subscribers an
+                // answer: deliver signed-out so nobody is left waiting on a promise
+                // this activation will never settle. A throwing listener must not
+                // swallow the loader's own error, so reject unconditionally; this
+                // runs inside an unawaited .catch(), so a listener's own exception
+                // is reported rather than left to become an unhandled rejection.
+                try {
+                    deliver(null);
+                }
+                catch (deliverError) {
+                    console.warn('lazyIdentity: a listener threw delivering signed-out after a load failure', deliverError);
+                }
+                finally {
+                    reject(error);
+                }
+            });
+        });
+        return activation;
+    }
+    function deactivate() {
+        if (!activation)
+            return;
+        generation += 1;
+        activation = undefined;
+        settleActivation?.();
+        settleActivation = undefined;
+        unsubscribe?.();
+        unsubscribe = undefined;
+        const wasSignedIn = lastDelivered !== undefined && lastDelivered.user !== null;
+        lastDelivered = undefined;
+        if (!wasSignedIn)
+            return;
+        listeners.forEach((listener) => listener(null));
+    }
+    return {
+        ...brandIdentity({
+            onUserChanged: (listener) => {
+                listeners.add(listener);
+                if (lastDelivered)
+                    listener(lastDelivered.user);
+                return () => {
+                    listeners.delete(listener);
+                };
+            }
+        }),
+        activate,
+        deactivate
+    };
+}

package/dist/core/requestAuth.d.ts

@@ -0,0 +1,30 @@
+import type { WebSession } from './sessionContracts.js';
+export type RequestTarget = 'ingest' | 'resource';
+export type RequestPrincipal = {
+    readonly kind: 'session';
+    readonly session: WebSession;
+} | {
+    readonly kind: 'firebase';
+    readonly getIdToken: () => Promise<string>;
+} | {
+    readonly kind: 'apiKey';
+    readonly apiKey: string;
+};
+export interface RequestAuthInput {
+    readonly target: RequestTarget;
+    readonly method: string;
+    /** Absent means the personal workspace. */
+    readonly workspaceId?: string;
+}
+export interface RequestAuthorization {
+    readonly headers: Readonly<Record<string, string>>;
+    /** Set only for a cookie request, which must carry the session cookie. */
+    readonly credentials?: 'include';
+}
+export type RequestAuthorizer = (principal: RequestPrincipal, input: RequestAuthInput) => Promise<RequestAuthorization>;
+export interface RequestAuthOptions {
+    /** A workspace token for a session principal; minting is the caller's. */
+    readonly getWorkspaceToken: (workspaceId: string | undefined) => Promise<string>;
+}
+export declare const COMFY_CLIENT: string;
+export declare function createRequestAuthorizer({ getWorkspaceToken }: RequestAuthOptions): RequestAuthorizer;

package/dist/core/requestAuth.js

@@ -0,0 +1,41 @@
+/**
+ * Decides the credential headers for one request, and nothing else: callers
+ * send, retry, and track scope. A cookie session authorizes ingest itself;
+ * every other service takes a Bearer workspace token. Firebase and API-key
+ * principals keep the single header they send today, whatever the target.
+ */
+import packageManifest from '../../package.json' with { type: 'json' };
+export const COMFY_CLIENT = `${packageManifest.name}/${packageManifest.version}`;
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+function sessionHeaders(session, { method, workspaceId }) {
+    return {
+        'X-Comfy-Client': COMFY_CLIENT,
+        ...(workspaceId === undefined
+            ? {}
+            : { 'X-Comfy-Workspace-ID': workspaceId }),
+        ...(SAFE_METHODS.has(method.toUpperCase())
+            ? {}
+            : { 'X-CSRF-Token': session.csrfToken })
+    };
+}
+export function createRequestAuthorizer({ getWorkspaceToken }) {
+    return async function authorize(principal, input) {
+        switch (principal.kind) {
+            case 'apiKey':
+                return { headers: { 'X-API-KEY': principal.apiKey } };
+            case 'firebase':
+                return {
+                    headers: { Authorization: `Bearer ${await principal.getIdToken()}` }
+                };
+            case 'session':
+                if (input.target === 'resource') {
+                    const token = await getWorkspaceToken(input.workspaceId);
+                    return { headers: { Authorization: `Bearer ${token}` } };
+                }
+                return {
+                    headers: sessionHeaders(principal.session, input),
+                    credentials: 'include'
+                };
+        }
+    };
+}

package/dist/core/requestTimeout.d.ts

@@ -0,0 +1,7 @@
+export interface TimedSignal {
+    readonly signal: AbortSignal | undefined;
+    /** Disarms the timer; call once the response body has been read. */
+    readonly release: () => void;
+}
+/** Joins the caller's signal with an abort after `timeoutMs`, if one is set. */
+export declare function timedSignal(signal: AbortSignal | undefined, timeoutMs: number | undefined): TimedSignal;

package/dist/core/requestTimeout.js

@@ -0,0 +1,13 @@
+/** Joins the caller's signal with an abort after `timeoutMs`, if one is set. */
+export function timedSignal(signal, timeoutMs) {
+    if (timeoutMs === undefined)
+        return { signal, release: () => undefined };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    return {
+        signal: signal
+            ? AbortSignal.any([signal, controller.signal])
+            : controller.signal,
+        release: () => clearTimeout(timer)
+    };
+}

package/dist/core/session.d.ts

@@ -53,13 +53,16 @@ export interface SessionClientOptions extends SessionRequestOptions {
     readonly storage: CredentialStorage;
     readonly freshMarginMs?: number;
     readonly refreshScheduler?: RefreshSchedulerOptions;
-    /** Applies to the identity passed at construction; see `AttachIdentityOptions.autoMint`. */
+    /**
+     * When false, an identity event sets the user and publishes without
+     * starting a warm-up mint — for hosts that drive every mint explicitly.
+     */
     readonly autoMint?: boolean;
 }
 /**
- * `pending` is the initial phase, before the attached identity has delivered
- * even once, so a host can tell "Firebase has not answered yet" (pending)
- * from "nobody is signed in" (a delivered null) without wrapping the port.
+ * `pending` is the initial phase, before the identity has delivered even
+ * once, so a host can tell "Firebase has not answered yet" (pending) from
+ * "nobody is signed in" (a delivered null) without wrapping the port.
  */
 export type SessionSnapshot<TUser extends AccountUser = AccountUser> = {
     readonly phase: 'pending';
@@ -83,21 +86,12 @@ export type SessionSnapshot<TUser extends AccountUser = AccountUser> = {
     readonly session: undefined;
     readonly failure: SessionFailure;
 };
-export interface AttachIdentityOptions {
-    /**
-     * When false, an identity event sets the user and publishes without
-     * starting a warm-up mint — for hosts that drive every mint explicitly.
-     */
-    readonly autoMint?: boolean;
-}
 export interface SessionClient<TUser extends AccountUser = AccountUser> {
-    /** @deprecated Transitional Pinia-adapter seam; pass the identity as `createSessionClient`'s second argument instead (FE-2171, PoC #16639). */
-    attachIdentity: (identity: AccountIdentity<TUser>, options?: AttachIdentityOptions) => () => void;
     /**
-     * Detaches the current identity; the persisted credential stays until
-     * `clearStoredCredential`. Not terminal, like a detach: an explicit-user
-     * mint issued after `dispose()` still commits and can re-arm the scheduler
-     * and cross-tab lease, so dispose and then stop calling the client.
+     * Detaches the constructed identity; the persisted credential stays until
+     * `clearStoredCredential`. Not terminal: an explicit-user mint issued after
+     * `dispose()` still commits and can re-arm the scheduler and cross-tab
+     * lease, so dispose and then stop calling the client.
      */
     dispose: () => void;
     getSnapshot: () => SessionSnapshot<TUser>;
@@ -133,7 +127,7 @@ export interface SessionClient<TUser extends AccountUser = AccountUser> {
     invalidate: () => void;
     /**
      * Drops only the persisted copy of the credential. The published session
-     * stays live; a host that must end it detaches or invalidates as well.
+     * stays live; a host that must end it disposes or invalidates as well.
      */
     clearStoredCredential: () => void;
 }

package/dist/core/session.js

@@ -1,5 +1,4 @@
 import { DEFAULT_FRESH_MARGIN_MS, createCredentialCache, decodeAdopted, isCredentialFresh, selectFreshCredential } from './credentialCache.js';
-import { isAccountIdentity } from './identity.js';
 import { abortable, exchangeToken } from './exchange.js';
 import { createMintCoordinator } from './mintCoordinator.js';
 import { createRefreshScheduler } from './refreshScheduler.js';
@@ -28,9 +27,8 @@ const DEFAULT_MINT_TIMEOUT_MS = 15_000;
  * production's default branch.
  */
 export function createSessionClient(clientOptions, identity) {
-    const { exchangeUrl, storage, freshMarginMs = DEFAULT_FRESH_MARGIN_MS } = clientOptions;
+    const { exchangeUrl, storage, freshMarginMs = DEFAULT_FRESH_MARGIN_MS, autoMint = true } = clientOptions;
     let state = initialSessionState();
-    let detachCurrent;
     const listeners = new Set();
     const cache = createCredentialCache(storage);
     const mints = createMintCoordinator();
@@ -245,38 +243,30 @@ export function createSessionClient(clientOptions, identity) {
         }, () => options.now?.() ?? hostNow());
         return result;
     }
-    function subscribeIdentity(port, autoMint) {
-        if (!isAccountIdentity(port)) {
-            throw new Error('the session client needs the identity from @comfyorg/account-core/firebase (or /testing)');
-        }
-        detachCurrent?.();
-        let unsubscribe = () => undefined;
-        const detach = () => {
-            if (detachCurrent !== detach)
-                return;
-            detachCurrent = undefined;
-            unsubscribe();
-            commit({ type: 'identity-detached' });
-        };
-        detachCurrent = detach;
-        unsubscribe = port.onUserChanged((next) => {
-            if (detachCurrent !== detach)
+    function subscribeIdentity(port) {
+        let active = true;
+        const unsubscribe = port.onUserChanged((next) => {
+            if (!active)
                 return;
             commit({ type: 'identity-changed', user: next });
-            if (detachCurrent === detach && next && autoMint) {
+            // A listener may dispose the client or deliver a newer user inside
+            // that publish; either makes state.user no longer this delivery's.
+            if (next && autoMint && state.user === next) {
                 void refreshWith(ensureCore, next);
             }
         });
-        if (detachCurrent !== detach)
+        return () => {
+            if (!active)
+                return;
+            active = false;
             unsubscribe();
-        return detach;
+            commit({ type: 'identity-detached' });
+        };
     }
-    if (identity)
-        subscribeIdentity(identity, clientOptions.autoMint !== false);
+    const detachIdentity = identity ? subscribeIdentity(identity) : undefined;
     return {
-        attachIdentity: (port, attachOptions) => subscribeIdentity(port, attachOptions?.autoMint !== false),
         dispose() {
-            detachCurrent?.();
+            detachIdentity?.();
         },
         getSnapshot,
         subscribe(listener) {

package/dist/core/sessionContracts.d.ts

@@ -85,14 +85,14 @@ export interface MintHandle {
  * (`createWebCrossTabRefreshPort` from `@comfyorg/account-core/web`); tests pass
  * fakes.
  */
-export interface CrossTabRefreshPort {
+export interface CrossTabRefreshPort<Message = AccountCredential> {
     /**
      * Queue for the key's lease. `onAcquired` fires if and when this tab
      * becomes leader; the returned function abandons the request or releases
      * held leadership.
      */
     requestLeadership: (key: string, onAcquired: () => void) => () => void;
-    publishCredential: (key: string, credential: AccountCredential) => void;
+    publishCredential: (key: string, credential: Message) => void;
     /** Messages cross a serialization boundary; the client validates them. */
     onCredential: (key: string, callback: (message: unknown) => void) => () => void;
 }
@@ -132,4 +132,41 @@ export interface RefreshSchedulerOptions {
      */
     readonly onScheduledOutcome?: (report: ScheduledRefreshReport) => void;
 }
+/** The signed-in principal behind the shared `__Host-comfy_session` cookie. */
+export interface WebSessionUser {
+    readonly id: string;
+    readonly email: string;
+    readonly name?: string;
+    readonly emailVerified: boolean;
+    readonly signInProvider?: string;
+}
+export interface WebSession {
+    readonly user: WebSessionUser;
+    readonly csrfToken: string;
+    /** ms since epoch; the sliding idle expiry */
+    readonly expiresAt: number;
+    /** ms since epoch; the hard cap regardless of activity */
+    readonly absoluteExpiresAt: number;
+}
+/**
+ * `SESSION_UNAVAILABLE` is the only transient code: 429, 5xx, network,
+ * abort, and unreadable bodies land there so an outage never reads as a
+ * sign-out. `SESSION_REQUEST_REFUSED` is a request no fresh session can fix.
+ */
+export type WebSessionErrorCode = 'NO_SESSION' | 'SESSION_EXPIRED' | 'SESSION_REVOKED' | 'CSRF_STALE' | 'IDENTITY_CHANGED' | 'WORKSPACE_ACCESS_DENIED' | 'SESSION_REQUEST_REFUSED' | 'SESSION_UNAVAILABLE';
+export interface WebSessionFailure {
+    readonly status: 'error';
+    readonly code: WebSessionErrorCode;
+    readonly retryable: boolean;
+    readonly httpStatus?: number;
+    /** The server's `ErrorResponse.code`, when the body carried one. */
+    readonly serverCode?: string;
+}
+export type WebSessionResult = {
+    readonly status: 'ok';
+    readonly session: WebSession;
+} | WebSessionFailure;
+export type WebSessionCommandResult = {
+    readonly status: 'ok';
+} | WebSessionFailure;
 export {};

package/dist/core/sessionTokenMint.d.ts

@@ -0,0 +1,35 @@
+import type { AccountCredential, WebSession, WebSessionFailure } from './sessionContracts.js';
+export interface SessionTokenMintOptions {
+    /** Ingest API root, e.g. `https://cloud.comfy.org/api`. */
+    readonly apiBaseUrl: string;
+    readonly fetchImpl: typeof fetch;
+    /** The live web session, or undefined when signed out. */
+    readonly getSession: () => WebSession | undefined;
+    readonly now?: () => number;
+    /** Re-mint once a cached token has this long left. Default 60s. */
+    readonly refreshBufferMs?: number;
+    /** Caps each mint, body included; a timeout is `SESSION_UNAVAILABLE`. Default: none. */
+    readonly timeoutMs?: number;
+}
+export interface SessionTokenFailure extends WebSessionFailure {
+    /** From a 429's `Retry-After`; no request is sent until it passes. */
+    readonly retryAfterMs?: number;
+}
+export type SessionTokenResult = {
+    readonly status: 'ok';
+    readonly credential: AccountCredential;
+} | SessionTokenFailure;
+export declare class SessionTokenError extends Error {
+    readonly failure: SessionTokenFailure;
+    constructor(failure: SessionTokenFailure);
+}
+export interface SessionTokenMint {
+    /** Never throws: every outcome is a result. */
+    readonly mint: (workspaceId?: string) => Promise<SessionTokenResult>;
+    /** Like `mint`, but never serves the cached token; for the one 401 retry. */
+    readonly remint: (workspaceId?: string) => Promise<SessionTokenResult>;
+    /** For `createRequestAuthorizer`; rejects with a `SessionTokenError`. */
+    readonly getWorkspaceToken: (workspaceId?: string) => Promise<string>;
+}
+export declare const DEFAULT_REFRESH_BUFFER_MS = 60000;
+export declare function createSessionTokenMint({ apiBaseUrl, fetchImpl, getSession, now, refreshBufferMs, timeoutMs }: SessionTokenMintOptions): SessionTokenMint;