@comfyorg/account-core 1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Comfy Org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,35 @@
+/**
+ * The fallback for a top-up whose `billing_op_id` this tab never observed:
+ * with nothing to poll, the balance itself is the only evidence that the
+ * purchase landed. Ported from the cloud app's `topupBalanceRefresh` minus
+ * its document listeners — a host calls `wake` from its own focus and
+ * visibility signals, the same way it wakes the lifecycle.
+ *
+ * A watch has no operation id at all; the SDK never fabricates one to poll
+ * instead. The top-up command reads the balance right before its POST, so
+ * `credits.getSnapshot()` after a malformed response is the baseline to arm
+ * this with.
+ */
+import type { CreditsReader } from './credits.js';
+/** Gaps between reads in one run: the webhook usually lands a beat after the return. */
+export declare const BALANCE_WATCH_RETRY_GAPS_MS: readonly [0, 2000, 5000, 10000, 20000];
+/** A host that never comes back must not keep a watch alive forever. */
+export declare const BALANCE_WATCH_LIFETIME_MS: number;
+/** Full retry schedules a returning host can trigger; later wakes read once. */
+export declare const BALANCE_WATCH_MAX_SCHEDULED_RUNS = 5;
+export type BalanceWatchOutcome = 'reconciled' | 'expired' | 'stopped';
+export interface BalanceWatchOptions {
+    readonly credits: Pick<CreditsReader, 'read'>;
+    /**
+     * The pre-purchase balance in micros. Absent, it is learned from the first
+     * successful read, which therefore can never count as the increase.
+     */
+    readonly baselineMicros?: number;
+}
+export interface BalanceWatch {
+    /** The host regained focus or visibility: run the read schedule. */
+    wake: () => void;
+    stop: () => void;
+    readonly outcome: Promise<BalanceWatchOutcome>;
+}
+export declare function createBalanceWatch(options: BalanceWatchOptions): BalanceWatch;

package/dist/core/billing/balanceWatch.js

@@ -0,0 +1,83 @@
+/** Gaps between reads in one run: the webhook usually lands a beat after the return. */
+export const BALANCE_WATCH_RETRY_GAPS_MS = [
+    0, 2_000, 5_000, 10_000, 20_000
+];
+/** A host that never comes back must not keep a watch alive forever. */
+export const BALANCE_WATCH_LIFETIME_MS = 15 * 60_000;
+/** Full retry schedules a returning host can trigger; later wakes read once. */
+export const BALANCE_WATCH_MAX_SCHEDULED_RUNS = 5;
+export function createBalanceWatch(options) {
+    const { credits } = options;
+    let baselineMicros = options.baselineMicros;
+    let runs = 0;
+    let running = false;
+    let finished;
+    const timers = new Set();
+    let resolveOutcome = () => { };
+    const outcome = new Promise((resolve) => {
+        resolveOutcome = resolve;
+    });
+    function finish(result) {
+        if (finished !== undefined)
+            return;
+        finished = result;
+        for (const timer of timers)
+            clearTimeout(timer);
+        timers.clear();
+        resolveOutcome(result);
+    }
+    function wait(ms) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                timers.delete(timer);
+                resolve();
+            }, ms);
+            timers.add(timer);
+        });
+    }
+    // A failed read is not a verdict: the next attempt covers it, and the
+    // purchase itself already went through.
+    async function balanceRose() {
+        const read = await credits.read();
+        if (read.status === 'error')
+            return false;
+        const amountMicros = read.value.balance.amount_micros;
+        if (baselineMicros === undefined) {
+            baselineMicros = amountMicros;
+            return false;
+        }
+        return amountMicros > baselineMicros;
+    }
+    // Past the run cap a wake still reads once — the return after the actual
+    // payment must read no matter how often the host glanced back beforehand.
+    const isFinished = () => finished !== undefined;
+    async function run() {
+        running = true;
+        runs += 1;
+        const gaps = runs > BALANCE_WATCH_MAX_SCHEDULED_RUNS
+            ? [0]
+            : BALANCE_WATCH_RETRY_GAPS_MS;
+        for (const gap of gaps) {
+            await wait(gap);
+            if (isFinished())
+                return;
+            if (await balanceRose()) {
+                finish('reconciled');
+                return;
+            }
+            if (isFinished())
+                return;
+        }
+        running = false;
+    }
+    timers.add(setTimeout(() => finish('expired'), BALANCE_WATCH_LIFETIME_MS));
+    return {
+        wake: () => {
+            if (running || finished !== undefined)
+                return;
+            void run();
+        },
+        stop: () => finish('stopped'),
+        outcome
+    };
+}

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

@@ -0,0 +1,123 @@
+/**
+ * The contracts the billing core shares with its hosts. Dependency-neutral
+ * 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.
+ */
+import type { SessionClient } from '../session.js';
+/**
+ * The session members the billing core reaches for. A host's client is typed
+ * for its own user, and the identity seam is contravariant in that user, so
+ * requiring the full client would reject every host whose user is more
+ * specific than the base.
+ */
+export type BillingSession = Pick<SessionClient, 'getSnapshot' | 'subscribe' | 'ensureFresh' | 'remint'>;
+/**
+ * The failure buckets a billing request can produce, extracted from what the
+ * cloud app's `workspaceApi` callers actually distinguish today.
+ * REQUEST_FAILED is the transient bucket: 5xx, a network failure, an abort,
+ * and a timeout are one failure for a caller, exactly as they are in the
+ * session client's `TOKEN_EXCHANGE_FAILED`.
+ */
+export type BillingErrorCode = 
+/** Nobody is signed in, or the identity could not produce a token. */
+'NOT_AUTHENTICATED'
+/** A 401 that survived the one re-mint retry, or a 403. */
+ | 'ACCESS_DENIED' | 'NOT_FOUND'
+/** A business-level 409 — never a missing customer, which self-heals. */
+ | 'CONFLICT'
+/** 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';
+declare const billingServerCodeBrand: unique symbol;
+/**
+ * An unbounded server string that is only ever a machine identifier. Nothing
+ * outside `readBillingErrorCode` mints one, so a command cannot invent a code
+ * to match. The value stays a `string` underneath: `matchesServerCode` and
+ * `unwrapServerCode` name the sanctioned uses rather than making the string
+ * unreadable.
+ */
+export type BillingServerCode = string & {
+    readonly [billingServerCodeBrand]: true;
+};
+export type BillingFailure = {
+    readonly status: 'error';
+    readonly code: BillingErrorCode;
+    /** Set only when the failure came from an HTTP response. */
+    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.
+     */
+    readonly serverCode?: BillingServerCode;
+};
+/** Whether a failure carries the server code a command names. */
+export declare function matchesServerCode(failure: Pick<BillingFailure, 'serverCode'>, code: string): boolean;
+/**
+ * The one widening back to `string`, for a host storing the code beside the
+ * codes it already keeps. Rendering it is still a contract violation.
+ */
+export declare function unwrapServerCode(code: BillingServerCode): string;
+export type BillingResult<T> = {
+    readonly status: 'ok';
+    readonly value: T;
+} | BillingFailure;
+interface BillingRequestBase {
+    /** Route below the host's billing base, e.g. `/billing/topup`. */
+    readonly route: string;
+    /**
+     * Present on a write whose replay the backend deduplicates. It is also
+     * what makes a 401 retry safe: see `createSessionBillingTransport`.
+     */
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+    /** Total budget for session minting, retries, and reading the response. */
+    readonly timeoutMs?: number;
+}
+export type BillingRequest = BillingRequestBase & ({
+    readonly method: 'GET';
+    readonly body?: never;
+} | {
+    readonly method: 'POST';
+    readonly body?: unknown;
+});
+export interface BillingHttpResponse {
+    readonly httpStatus: number;
+    readonly body: unknown;
+    /** True when a 401 could not be retried because the write was not replayable. */
+    readonly authenticationRetrySkipped?: true;
+    /**
+     * True when the transport holds no credential of its own to re-prove with,
+     * so a 401 is the host's session ending rather than a refusal.
+     */
+    readonly authenticationNotRenewable?: true;
+    /**
+     * Response header reader. The capability revision a mutation reports
+     * (`X-Capability-Revision`) reaches the capabilities cache through this,
+     * mirroring the cloud app's `attachCapabilityRevisionInterceptor`. It is
+     * absent whenever CORS is bypassed, so every reader treats a missing
+     * header as "no revision reported" rather than assuming presence.
+     */
+    readonly header: (name: string) => string | null;
+}
+/**
+ * One request, credentials included. An HTTP answer of any status is an `ok`
+ * result — only a failure that produced no response at all (no session,
+ * network, abort, timeout) is an `error`, so the typed operations above it
+ * own the status-to-code mapping in one place.
+ */
+export type BillingTransport = (request: BillingRequest) => Promise<BillingResult<BillingHttpResponse>>;
+export {};

package/dist/core/billing/billingContracts.js

@@ -0,0 +1,11 @@
+/** Whether a failure carries the server code a command names. */
+export function matchesServerCode(failure, code) {
+    return failure.serverCode === code;
+}
+/**
+ * The one widening back to `string`, for a host storing the code beside the
+ * codes it already keeps. Rendering it is still a contract violation.
+ */
+export function unwrapServerCode(code) {
+    return code;
+}

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

@@ -0,0 +1,8 @@
+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.
+ */
+export declare function readBillingErrorCode(body: unknown): BillingServerCode | undefined;

package/dist/core/billing/billingErrorBody.js

@@ -0,0 +1,11 @@
+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.
+ */
+export function readBillingErrorCode(body) {
+    const parsed = zErrorResponse.safeParse(body);
+    return parsed.success ? parsed.data.code : undefined;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The scope port: the one thing the billing core needs to know about the
+ * identity it runs as — which user, which workspace, which role — and when
+ * that changes. A host that holds a browser session client adapts it with
+ * `sessionBillingScopeSource`; a host whose credentials live on its own
+ * server reads the scope out of its bootstrap payload instead, and never
+ * hands the core a session client it does not have.
+ */
+import type { BillingSession } from './billingContracts.js';
+import type { AccountCredential } from '../sessionContracts.js';
+export interface BillingScope {
+    readonly userId: string;
+    readonly workspaceId: string;
+    readonly role: AccountCredential['role'];
+}
+export interface BillingScopeContext {
+    readonly scope: BillingScope;
+    readonly generation: number;
+}
+export interface BillingScopeTracker {
+    capture: () => BillingScopeContext | undefined;
+    isCurrent: (context: BillingScopeContext) => boolean;
+    dispose: () => void;
+}
+/**
+ * Where the core learns its scope. `getScope` is undefined whenever no scope
+ * is established — signed out, or not settled yet — and `subscribe` reports
+ * that anything about it may have changed.
+ */
+export interface BillingScopeSource {
+    readonly getScope: () => BillingScope | undefined;
+    readonly subscribe: (listener: () => void) => () => void;
+}
+export declare function sameBillingScope(a: BillingScope, b: BillingScope): boolean;
+type BillingScopeSession = Pick<BillingSession, 'getSnapshot' | 'subscribe'>;
+/** The scope a workspace session client is currently minted for. */
+export declare function sessionBillingScopeSource(session: BillingScopeSession): BillingScopeSource;
+export declare function createBillingScopeTracker(source: BillingScopeSource, onChange: () => void): BillingScopeTracker;
+export {};

package/dist/core/billing/billingScope.js

@@ -0,0 +1,45 @@
+export function sameBillingScope(a, b) {
+    return (a.userId === b.userId &&
+        a.workspaceId === b.workspaceId &&
+        a.role === b.role);
+}
+/** The scope a workspace session client is currently minted for. */
+export function sessionBillingScopeSource(session) {
+    return {
+        getScope: () => readSessionScope(session),
+        subscribe: (listener) => session.subscribe(listener)
+    };
+}
+export function createBillingScopeTracker(source, onChange) {
+    let scope = source.getScope();
+    let generation = 0;
+    const unsubscribe = source.subscribe(() => {
+        const next = source.getScope();
+        if ((scope === undefined && next === undefined) ||
+            (scope !== undefined &&
+                next !== undefined &&
+                sameBillingScope(scope, next))) {
+            return;
+        }
+        scope = next;
+        generation++;
+        onChange();
+    });
+    return {
+        capture: () => (scope === undefined ? undefined : { scope, generation }),
+        isCurrent: (context) => context.generation === generation &&
+            scope !== undefined &&
+            sameBillingScope(context.scope, scope),
+        dispose: unsubscribe
+    };
+}
+function readSessionScope(session) {
+    const state = session.getSnapshot();
+    if (state.user === null || state.session === undefined)
+        return undefined;
+    return {
+        userId: state.user.uid,
+        workspaceId: state.session.workspace.id,
+        role: state.session.role
+    };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * The capabilities read: a server-authoritative answer to "what may this actor
+ * be offered for this workspace", cached per scope.
+ *
+ * The SDK never derives a capability. It decodes what the server resolved and
+ * caches it under the scope it was resolved for, so no entitlement rule is
+ * reimplemented here and none can drift from the backend's.
+ *
+ * Freshness is pull-based on purpose: a snapshot carries the instant it stops
+ * being fresh, and a caller learns it is stale by asking. The production
+ * composable's timer, its visibility gating, and its retry backoff are all
+ * push concerns that need a document and a scheduler, so they belong to the
+ * view package that has both — not to a framework-free core.
+ */
+import { zBillingCapabilities, zBillingCapabilityRolloutDefaults } from '@comfyorg/ingest-types/zod';
+import { z } from 'zod';
+import type { BillingResult, BillingTransport } from './billingContracts.js';
+import type { BillingScope, BillingScopeSource } from './billingScope.js';
+import type { CapabilityDenials } from './capabilityDenials.js';
+export declare const CAPABILITIES_ROUTE = "/billing/capabilities";
+export declare const CAPABILITY_REVISION_HEADER = "X-Capability-Revision";
+export type BillingCapabilities = z.infer<typeof zBillingCapabilities>;
+export type CapabilityRolloutDefaults = z.infer<typeof zBillingCapabilityRolloutDefaults>;
+export type CapabilityScope = BillingScope;
+export interface CapabilitiesSnapshot {
+    readonly capabilities: BillingCapabilities;
+    /**
+     * Present only for a capability the server refused and explained. An absent
+     * key never implies the capability was granted — read `capabilities`.
+     */
+    readonly denials: CapabilityDenials;
+    /** True values are rollout guidance, not evidence a write will succeed. */
+    readonly rolloutDefaultsApplied: CapabilityRolloutDefaults;
+    readonly revision: number;
+    readonly scope: CapabilityScope;
+    /** ms since epoch, after which `read` refetches rather than serving this. */
+    readonly freshUntil: number;
+}
+export interface CapabilitiesReadOptions {
+    readonly signal?: AbortSignal;
+    /** Bypasses a fresh cached snapshot; still joins an in-flight read. */
+    readonly forceRefresh?: boolean;
+}
+export interface CapabilitiesReader {
+    read: (options?: CapabilitiesReadOptions) => Promise<BillingResult<CapabilitiesSnapshot>>;
+    /** The cached snapshot for the current scope, fresh or not. */
+    getSnapshot: () => CapabilitiesSnapshot | undefined;
+    /**
+     * Marks the cache stale for a revision a **mutation** reported. A read's own
+     * revision must never be fed back here: the capabilities response echoes the
+     * header it was built with, so republishing it would mark that read stale and
+     * refetch forever.
+     */
+    invalidate: (revision?: number) => void;
+    /** Detaches the scope subscription. */
+    dispose: () => void;
+}
+export interface CapabilitiesReaderOptions {
+    readonly transport: BillingTransport;
+    /** Where the core learns which user, workspace, and role it runs as. */
+    readonly scopeSource: BillingScopeSource;
+    readonly now?: () => number;
+}
+/**
+ * Reads the revision a mutation reported. Absent whenever CORS is bypassed
+ * (local desktop origins), so a missing header is "nothing reported" rather
+ * than a reason to invalidate.
+ */
+export declare function readCapabilityRevision(header: (name: string) => string | null): number | undefined;
+export declare function createCapabilitiesReader(options: CapabilitiesReaderOptions): CapabilitiesReader;

package/dist/core/billing/capabilities.js

@@ -0,0 +1,137 @@
+/**
+ * The capabilities read: a server-authoritative answer to "what may this actor
+ * be offered for this workspace", cached per scope.
+ *
+ * The SDK never derives a capability. It decodes what the server resolved and
+ * caches it under the scope it was resolved for, so no entitlement rule is
+ * reimplemented here and none can drift from the backend's.
+ *
+ * Freshness is pull-based on purpose: a snapshot carries the instant it stops
+ * being fresh, and a caller learns it is stale by asking. The production
+ * composable's timer, its visibility gating, and its retry backoff are all
+ * push concerns that need a document and a scheduler, so they belong to the
+ * view package that has both — not to a framework-free core.
+ */
+import { zBillingCapabilities, zBillingCapabilityRolloutDefaults, zBillingCapabilityScope } from '@comfyorg/ingest-types/zod';
+import { z } from 'zod';
+import { sameBillingScope } from './billingScope.js';
+import { decodeCapabilityDenials } from './capabilityDenials.js';
+import { createScopedReader } from './scopedReader.js';
+export const CAPABILITIES_ROUTE = '/billing/capabilities';
+/** Production's own budget for this read (`workspaceApi.getBillingCapabilities`). */
+const CAPABILITIES_TIMEOUT_MS = 10_000;
+/**
+ * A remaining lifetime below the floor means the client clock disagrees with
+ * the server's, so `expires_at` cannot pace anything and the fixed interval is
+ * used instead. The ceiling bounds the opposite skew, where a lagging clock
+ * reads `expires_at` as far in the future. Both bounds, and the fallback, are
+ * the production composable's.
+ */
+const MIN_FRESH_MS = 5_000;
+const MAX_FRESH_MS = 60 * 60 * 1000;
+const FALLBACK_FRESH_MS = 60_000;
+export const CAPABILITY_REVISION_HEADER = 'X-Capability-Revision';
+/**
+ * The generated contract minus `denied_reasons`, which is decoded separately
+ * and leniently. `revision` is read as a number rather than the generated
+ * bigint: the server bounds it to the JavaScript-safe range precisely so
+ * clients can compare it as one.
+ */
+const CapabilitiesBodySchema = z.object({
+    capabilities: zBillingCapabilities,
+    expires_at: z.string(),
+    resolved_for: zBillingCapabilityScope,
+    revision: z.number(),
+    rollout_defaults_applied: zBillingCapabilityRolloutDefaults
+});
+/**
+ * Reads the revision a mutation reported. Absent whenever CORS is bypassed
+ * (local desktop origins), so a missing header is "nothing reported" rather
+ * than a reason to invalidate.
+ */
+export function readCapabilityRevision(header) {
+    const raw = header(CAPABILITY_REVISION_HEADER);
+    if (raw === null)
+        return undefined;
+    const revision = Number(raw);
+    return Number.isSafeInteger(revision) && revision > 0 ? revision : undefined;
+}
+function freshUntilFrom(expiresAt, now) {
+    // Date.parse yields NaN on an unparseable value; NaN fails the comparison
+    // and lands on the fixed interval, which is the intended branch.
+    const remaining = Date.parse(expiresAt) - now;
+    if (remaining >= MIN_FRESH_MS) {
+        return now + Math.min(remaining, MAX_FRESH_MS);
+    }
+    return now + FALLBACK_FRESH_MS;
+}
+function freshSnapshot(snapshot, scope, forceRefresh, now) {
+    if (forceRefresh || snapshot === undefined)
+        return undefined;
+    if (!sameBillingScope(snapshot.scope, scope))
+        return undefined;
+    return snapshot.freshUntil > now ? snapshot : undefined;
+}
+function snapshotAfterInvalidation(snapshot, invalidated) {
+    return invalidated ? { ...snapshot, freshUntil: 0 } : snapshot;
+}
+export function createCapabilitiesReader(options) {
+    const { transport, scopeSource, now = Date.now } = options;
+    function projectCapabilities(response, scope) {
+        const { data, body, httpStatus } = response;
+        // Capabilities resolve per (user, workspace), so both halves have to
+        // match. Checking only the workspace would accept another member's answer
+        // for the workspace the caller is in and publish it as the caller's own —
+        // an actor with fewer or greater rights deciding what this one is offered.
+        // Either mismatch is a contract violation rather than an answer about this
+        // scope, so it joins the transient bucket instead of being cached. The
+        // ingest service makes the same two-part check against its own upstream
+        // before it forwards a response.
+        const resolved = data.resolved_for;
+        if (resolved.user_id !== scope.userId ||
+            resolved.workspace_id !== scope.workspaceId) {
+            return { status: 'error', code: 'REQUEST_FAILED', httpStatus };
+        }
+        const denials = decodeCapabilityDenials(body.denied_reasons);
+        return {
+            status: 'ok',
+            value: {
+                capabilities: data.capabilities,
+                denials,
+                rolloutDefaultsApplied: data.rollout_defaults_applied,
+                revision: data.revision,
+                scope,
+                freshUntil: freshUntilFrom(data.expires_at, now())
+            }
+        };
+    }
+    const reader = createScopedReader({
+        transport,
+        scopeSource,
+        route: CAPABILITIES_ROUTE,
+        parse: (body) => CapabilitiesBodySchema.safeParse(body),
+        timeoutMs: () => CAPABILITIES_TIMEOUT_MS,
+        cached: (snapshot, scope, readOptions) => freshSnapshot(snapshot, scope, readOptions?.forceRefresh === true, now()),
+        project: projectCapabilities,
+        // A mutation committed while this read was in flight, and the revision the
+        // read returns cannot rule out having missed it: the server mints that
+        // number when it serializes, not when it read. The value is still the best
+        // available, so it is published — as already stale, so the next read
+        // refetches instead of serving it.
+        publish: snapshotAfterInvalidation
+    });
+    return {
+        read: reader.read,
+        getSnapshot: reader.getSnapshot,
+        invalidate: (revision) => {
+            reader.fenceInFlight();
+            const snapshot = reader.getSnapshot();
+            if (snapshot === undefined)
+                return;
+            if (revision !== undefined && snapshot.revision === revision)
+                return;
+            reader.setSnapshot({ ...snapshot, freshUntil: 0 });
+        },
+        dispose: reader.dispose
+    };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * The policy branches the server names, plus the bucket this module adds for
+ * a value it does not recognize. `not_a_member` is unreachable through the
+ * ingest endpoint — a non-member is answered 403 before capabilities resolve —
+ * and is carried anyway because the billing-api endpoint can still emit it.
+ */
+export type CapabilityDenialReason = 'not_a_member' | 'not_workspace_owner' | 'tier_not_self_serve'
+/** A subscription row reserved before payment that never began. */
+ | 'subscription_not_started'
+/** The subscription already has a successor scheduled at a billing boundary. */
+ | 'subscription_change_in_progress'
+/** The server has no guidance for the row — distinct from a deliberate refusal. */
+ | 'subscription_status_unrecognized'
+/**
+ * A reason outside the set above. Kept as a reason rather than dropped so a
+ * refusal the server explained still reads as explained; the copy it maps to
+ * is the generic one.
+ */
+ | 'unspecified';
+/**
+ * Only `can_subscribe_self_serve` carries a reason today. The record is open
+ * because the server adds keys as policy grows, and a client that rejected an
+ * unknown key would fail the whole read over a field it does not use.
+ */
+export type CapabilityDenials = Readonly<Partial<Record<string, CapabilityDenialReason>>>;
+export declare function decodeCapabilityDenials(raw: unknown): CapabilityDenials;

package/dist/core/billing/capabilityDenials.js

@@ -0,0 +1,43 @@
+/**
+ * Why a capability resolved false, decoded from the capabilities read.
+ *
+ * The server's contract runs one way only, and every reader here depends on
+ * it: a reason is present only alongside `capabilities.<key> === false`, so
+ * presence implies refusal — but absence implies nothing at all. A capability
+ * with no reason may be granted, may be refused by a billing-api that predates
+ * the field, or may be refused for a reason the server declined to forward.
+ * `capabilities` stays the only authority for what a client may offer; these
+ * keys only ever choose the wording for a refusal already decided there.
+ */
+import { z } from 'zod';
+const KNOWN_REASONS = new Set([
+    'not_a_member',
+    'not_workspace_owner',
+    'tier_not_self_serve',
+    'subscription_not_started',
+    'subscription_change_in_progress',
+    'subscription_status_unrecognized'
+]);
+/**
+ * Deliberately lenient: values are read as plain strings and narrowed here,
+ * never as a generated enum. A strict enum parse would make the entire
+ * capabilities read malformed the first time the server names a policy branch
+ * this client predates — turning a copy detail into a total loss of the
+ * capability set, which is the one part of the response that gates UI.
+ *
+ * This mirrors what the ingest service already does on its own side, where an
+ * unrecognized reason is dropped rather than forwarded.
+ */
+const DeniedReasonsSchema = z.record(z.string(), z.string()).optional();
+export function decodeCapabilityDenials(raw) {
+    const parsed = DeniedReasonsSchema.safeParse(raw);
+    if (!parsed.success || parsed.data === undefined)
+        return {};
+    const denials = {};
+    for (const [capability, reason] of Object.entries(parsed.data)) {
+        denials[capability] = KNOWN_REASONS.has(reason)
+            ? reason
+            : 'unspecified';
+    }
+    return denials;
+}