@civitai/sdk 0.19.0 → 0.20.0

package/README.md

@@ -559,7 +559,7 @@ A `kind: 'workflow'` body runs several steps as **one** workflow, and a later
 step can consume an earlier step's result through a `{ $ref, path }` reference:
 
 ```ts
-import { initialize, type WorkflowBody } from '@civitai/sdk';
+import { estimatedCost, initialize, type WorkflowBody } from '@civitai/sdk';
 
 const app = await initialize();
 
@@ -587,11 +587,13 @@ const body: WorkflowBody = {
 
 // 1. Price it. Nothing is charged or reserved.
 const estimate = await app.workflows.estimate(body);
-if (estimate.status === 'failed') {
+// A priced estimate is not 'succeeded' ('pending' in practice): read the price, not the status.
+const price = estimatedCost(estimate);
+if (price === null) {
   // A refusal RESOLVES — see below.
   throw new Error(estimate.error ?? 'This workflow could not be priced.');
 }
-if (!(await confirmSpend(estimate.cost?.total))) throw new Error('Not confirmed.');
+if (!(await confirmSpend(price))) throw new Error('Not confirmed.');
 
 // 2. Run it. One key per press of the button, reused on every retry.
 const idempotencyKey = crypto.randomUUID();
@@ -617,7 +619,7 @@ submitted. `app.workflows` has no call for that confirmation step.
 
 | Call | Does |
 |---|---|
-| `estimate(body)` | Prices the body. `snapshot.cost.total` is whole Buzz |
+| `estimate(body)` | Prices the body. `estimatedCost(snapshot)` is the price in whole Buzz, or `null` when there is none |
 | `submit(body, { idempotencyKey })` | Runs it, spending the viewer's Buzz |
 | `get(workflowId)` | The workflow as it stands now |
 | `watch(workflowId)` | An async iterator: the workflow now, then each time it changes, until a final status |
@@ -633,13 +635,19 @@ branch on the snapshot rather than wrapping the call in `try`:
 
 ```ts
 const estimate = await app.workflows.estimate(body);
-if (estimate.status === 'failed') {
+if (estimatedCost(estimate) === null) {
   estimate.error; // a sentence for the viewer, e.g. which step is at fault
   estimate.errorCode; // a stable code to branch on, when the refusal defines one
-  estimate.cost; // absent: nothing was priced
 }
 ```
 
+`estimatedCost` is the check to use: the price when the estimate has one, else
+`null`. An estimate is priced when its `status` is not `'failed'` and it carries
+a numeric `cost.total`. 🔴 **Do not require `'succeeded'`**: nothing runs on an
+estimate, so a priced one comes back with a status that has not finished
+(`'pending'` in practice), and a check for `'succeeded'` treats every price as
+missing. `0` is a price.
+
 Three things follow from that shape:
 
 - **A refused estimate has no `cost`.** An estimate the host could not price

package/dist/app/index.d.ts

@@ -1,5 +1,5 @@
 import type { BlockContext, BlockSettings, Theme, ViewerInfo } from '../core/handshake.js';
-import type { BlockTransport } from '../core/transport.js';
+import { type BlockTransport } from '../core/transport.js';
 import { type Host } from '../host/index.js';
 import { type OrchestrationClient } from '../orchestration/index.js';
 import { type GrantOptions, type Scope, type TokenOptions, type TokenSessionOptions } from '../session/index.js';

package/dist/app/index.js

@@ -1,5 +1,6 @@
 import { BridgeError, CivitaiError } from '../core/errors.js';
 import { getTransport } from '../core/get-transport.js';
+import { isLocalPreviewStorage } from '../core/transport.js';
 import { createHost, createHostSession } from '../host/index.js';
 import { ApiError, createHttp } from '../http/index.js';
 import { createOrchestrationClient, DEFAULT_ORCHESTRATION_URL, } from '../orchestration/index.js';
@@ -26,13 +27,16 @@ export async function initialize(options = {}) {
     // from `token.scopes`. A published app whose manifest forgot `apps:storage`
     // holds a token that looks the same as a preview's, and must keep getting the
     // real route's `insufficient_scope` rather than a silent local store.
-    const local = snapshot().storageMode === 'local-preview'
+    const localPreview = isLocalPreviewStorage(snapshot());
+    // The same latched answer configures the session below, so `requestGrants`
+    // and the store agree on whether the document store is local.
+    const local = localPreview
         ? // The manifest arrives only from `blockManifestPlugin()`'s dev-server
             // global: there is deliberately no option to pass one.
             await createLocalPreviewStorage(readInjectedManifest(), snapshot().viewer)
         : undefined;
     return {
-        ...createAppClient(createHostSession(transport), options, holdsBlockTokenNow, holdsOAuthTokenNow, local),
+        ...createAppClient(createHostSession(transport, { localPreviewStorage: localPreview }), options, holdsBlockTokenNow, holdsOAuthTokenNow, local),
         host: createHost(transport),
         get viewer() {
             return snapshot().viewer;

package/dist/core/transport.d.ts

@@ -63,6 +63,15 @@ export interface BlockTransport {
     on(type: string, handler: (payload: unknown) => void): () => void;
 }
 export declare const EMPTY_SNAPSHOT: BlockSnapshot;
+/**
+ * Did the host mark this frame a dev-tunnel preview whose document store is
+ * served locally? THE predicate for that question. `initialize()` reads it once
+ * and the one latched answer selects the local document store AND tells the
+ * host session which scopes no grant can add (`requestGrants`), so the two
+ * cannot disagree. Never inferred from `token.scopes`: a published app whose
+ * token lacks `apps:storage` looks the same as a preview's.
+ */
+export declare function isLocalPreviewStorage(snapshot: Pick<BlockSnapshot, 'storageMode'>): boolean;
 /** Convert a wire `BlockInitPayload` (ISO string expiresAt) into a `BlockSnapshot`. */
 export declare function snapshotFromInit(payload: BlockInitPayload, hostOrigin: string): BlockSnapshot;
 /** Wire `WrappedToken` (ISO expiry) → runtime `BlockToken` (Date expiry). */

package/dist/core/transport.js

@@ -10,6 +10,17 @@ export const EMPTY_SNAPSHOT = {
     blockInstanceId: '',
     hostOrigin: null,
 };
+/**
+ * Did the host mark this frame a dev-tunnel preview whose document store is
+ * served locally? THE predicate for that question. `initialize()` reads it once
+ * and the one latched answer selects the local document store AND tells the
+ * host session which scopes no grant can add (`requestGrants`), so the two
+ * cannot disagree. Never inferred from `token.scopes`: a published app whose
+ * token lacks `apps:storage` looks the same as a preview's.
+ */
+export function isLocalPreviewStorage(snapshot) {
+    return snapshot.storageMode === LOCAL_PREVIEW_STORAGE;
+}
 /** Convert a wire `BlockInitPayload` (ISO string expiresAt) into a `BlockSnapshot`. */
 export function snapshotFromInit(payload, hostOrigin) {
     return {

package/dist/doc-store/local-preview.d.ts

@@ -1,4 +1,5 @@
 import type { ViewerInfo } from '../core/handshake.js';
+import type { Scope } from '../session/index.js';
 import { type DocumentStorage } from './index.js';
 /**
  * The document store for a DEV-TUNNEL PREVIEW: the host marked the frame
@@ -22,6 +23,15 @@ import { type DocumentStorage } from './index.js';
  * `tests/guards/local-preview-manifest-global.test.mjs`.
  */
 export declare const LOCAL_PREVIEW_MANIFEST_GLOBAL = "__CIVITAI_LOCAL_PREVIEW_MANIFEST__";
+/**
+ * The scopes the local document store serves: the two the server's document
+ * store checks (`fake.ts` enforces the same pair). A preview token never
+ * carries them and no grant can add them, so `requestGrants` treats them as
+ * held in a local preview instead of asking the host. Shared storage
+ * (`apps:storage:shared:*`) and the deprecated key/value scopes are NOT here:
+ * they keep the real routes in a preview.
+ */
+export declare const LOCAL_PREVIEW_STORAGE_SCOPES: ReadonlySet<Scope>;
 /** What a local preview reads from the manifest: the scopes it declares and its `storage` block. */
 export interface LocalPreviewManifest {
     scopes?: readonly string[];

package/dist/doc-store/local-preview.js

@@ -21,6 +21,18 @@ import { createDocumentStorage, StorageError } from './index.js';
  * `tests/guards/local-preview-manifest-global.test.mjs`.
  */
 export const LOCAL_PREVIEW_MANIFEST_GLOBAL = '__CIVITAI_LOCAL_PREVIEW_MANIFEST__';
+/**
+ * The scopes the local document store serves: the two the server's document
+ * store checks (`fake.ts` enforces the same pair). A preview token never
+ * carries them and no grant can add them, so `requestGrants` treats them as
+ * held in a local preview instead of asking the host. Shared storage
+ * (`apps:storage:shared:*`) and the deprecated key/value scopes are NOT here:
+ * they keep the real routes in a preview.
+ */
+export const LOCAL_PREVIEW_STORAGE_SCOPES = new Set([
+    'apps:storage',
+    'apps:storage:publish',
+]);
 /** The manifest the dev server injected, if any. */
 export function readInjectedManifest() {
     const value = globalThis[LOCAL_PREVIEW_MANIFEST_GLOBAL];

package/dist/host/index.d.ts

@@ -124,5 +124,13 @@ export interface Host {
     }, opts?: HostCallOptions): Promise<number[]>;
 }
 export declare function createHost(transport: BlockTransport): Host;
+export interface HostSessionOptions {
+    /**
+     * The document store is served by the in-tab local store (a dev-tunnel
+     * preview): the value `initialize()` latched from `isLocalPreviewStorage`.
+     * `requestGrants` then treats `LOCAL_PREVIEW_STORAGE_SCOPES` as held.
+     */
+    localPreviewStorage?: boolean;
+}
 /** The token the host minted for this block, kept current as the host rotates it. */
-export declare function createHostSession(transport: BlockTransport): Session;
+export declare function createHostSession(transport: BlockTransport, { localPreviewStorage }?: HostSessionOptions): Session;

package/dist/host/index.js

@@ -1,6 +1,7 @@
 import { BridgeError } from '../core/errors.js';
 import { createCaller, createListener, createNotifier } from '../core/messaging.js';
 import { tokenFromWrapped } from '../core/transport.js';
+import { LOCAL_PREVIEW_STORAGE_SCOPES } from '../doc-store/local-preview.js';
 const call = createCaller();
 const notify = createNotifier();
 const on = createListener();
@@ -254,7 +255,7 @@ function asScanResult(value) {
     return { status: 'error', ...(typeof v?.message === 'string' ? { message: v.message } : {}) };
 }
 /** The token the host minted for this block, kept current as the host rotates it. */
-export function createHostSession(transport) {
+export function createHostSession(transport, { localPreviewStorage = false } = {}) {
     return {
         async getToken({ fresh, signal } = {}) {
             if (!fresh)
@@ -263,7 +264,14 @@ export function createHostSession(transport) {
             const { token } = await call('REQUEST_TOKEN', { blockInstanceId }, { transport, signal });
             return tokenFromWrapped(token).raw;
         },
-        requestGrants: (scopes, opts = {}) => requestGrants(transport, scopes, opts),
+        requestGrants: (scopes, opts = {}) => requestGrants(transport, 
+        // A preview token never carries a document-store scope and no grant can
+        // add one, so asking the host for it could only be refused — and the
+        // refusal would take the rest of the request down with it. The local
+        // store serves them; ask only for the rest. Nothing on the token changes.
+        localPreviewStorage
+            ? scopes.filter((scope) => !LOCAL_PREVIEW_STORAGE_SCOPES.has(scope))
+            : scopes, opts),
     };
 }
 /**

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { SubListingError } from './sub-listings/index.js';
 export type { MySubListing, SubListingCallOptions, SubListingContentRating, SubListingErrorCode, SubListingStatus, SubListingsClient, SubListingUpsertInput, SubListingUpsertResult, SubListingWithdrawResult, } from './sub-listings/index.js';
 export { StorageError } from './doc-store/index.js';
 export type { DocumentAuthor, DocumentCallOptions, DocumentListQuery, DocumentPage, DocumentStorage, DocumentWhereValue, StorageCollection, StorageCollectionInfo, StorageDocument, StorageErrorCode, StorageIndexType, StorageInfo, StorageLimits, StorageUsage, WriteOptions, } from './doc-store/index.js';
-export { SubmissionUnconfirmedError } from './workflows/index.js';
+export { estimatedCost, SubmissionUnconfirmedError } from './workflows/index.js';
 export type { WorkflowCallOptions, WorkflowGetOptions, WorkflowListQuery, WorkflowListResult, WorkflowSubmitOptions, WorkflowWatchOptions, WorkflowsClient, } from './workflows/index.js';
 export type { AiToolkitLrScheduler, AiToolkitOptimizerType, AiToolkitPlainEcosystem, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AppWorkflow, AppWorkflowImage, BlockModel3dOutput, BlockModelSubstitution, BlockPublishedModel, BlockSourceImage, BlockStepQuote, BlockStepToolCall, BlockTextToImageParams, BlockTrainedEpoch, BlockTrainingDatasetItem, BlockTrainingQuote, BlockWorkflowSnapshot, BlockWorkflowStepSnapshot, BuzzAccountType, InlineComfyNode, KnownBlockWorkflowErrorCode, ModelSubstitutionReason, WithWorkflowStepRefs, WorkflowBody, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyInline, WorkflowBodyCustomComfyRecipe, WorkflowBodyPassThroughStep, WorkflowBodyStep, WorkflowBodyTextToImage, WorkflowBodyTraining, WorkflowBodyWorkflow, WorkflowBodyWorkflowStep, WorkflowStepRef, } from './workflows/types.generated.js';
 export { isTerminal, isTerminalStatus } from './orchestration/index.js';

package/dist/index.js

@@ -18,7 +18,7 @@ export { createSignIn, SignInError } from './sign-in/index.js';
 export { SCOPES } from './session/index.js';
 export { SubListingError } from './sub-listings/index.js';
 export { StorageError } from './doc-store/index.js';
-export { SubmissionUnconfirmedError } from './workflows/index.js';
+export { estimatedCost, SubmissionUnconfirmedError } from './workflows/index.js';
 export { isTerminal, isTerminalStatus } from './orchestration/index.js';
 export { createHost } from './host/index.js';
 export { ApiError } from './http/index.js';

package/dist/version.generated.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export declare const VERSION = "0.19.0";
+export declare const VERSION = "0.20.0";

package/dist/version.generated.js

@@ -1,3 +1,3 @@
 /* AUTOGENERATED from package.json by scripts/gen-version.mjs. DO NOT EDIT. */
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export const VERSION = "0.19.0";
+export const VERSION = "0.20.0";

package/dist/workflows/index.d.ts

@@ -28,6 +28,25 @@ export declare class SubmissionUnconfirmedError extends CivitaiError {
     readonly snapshot: BlockWorkflowSnapshot | undefined;
     constructor(snapshot: BlockWorkflowSnapshot | undefined);
 }
+/**
+ * The price an {@link WorkflowsClient.estimate} reply quotes, in whole Buzz, or
+ * `null` when it quotes none.
+ *
+ * An estimate is priced when its `status` is not `'failed'` AND it carries a
+ * numeric `cost.total`. That is the whole rule, and it is the one to branch on:
+ * - Do not require `'succeeded'`. Nothing runs on an estimate, so a priced one
+ *   comes back with a status that has not finished (`'pending'` in practice),
+ *   and a check for `'succeeded'` reads every price as missing.
+ * - `0` is a price.
+ * - A `'failed'` snapshot is never priced, even one carrying a `cost.total`: a
+ *   budget refusal carries the total it would not charge.
+ * - A snapshot with no numeric `cost.total` is not priced, whatever its status.
+ *
+ * `null` does not predict a refused {@link WorkflowsClient.submit}: a body the
+ * host cannot price can still be submitted. Read `error` / `errorCode` on the
+ * snapshot for why.
+ */
+export declare function estimatedCost(snapshot: Pick<BlockWorkflowSnapshot, 'status' | 'cost'>): number | null;
 export interface WorkflowCallOptions {
     signal?: AbortSignal;
 }
@@ -102,6 +121,16 @@ export interface WorkflowsClient {
      * The price is `snapshot.cost.total`. A refused estimate resolves with
      * `status: 'failed'` and no `cost`; a body the host cannot price fails this
      * way without that predicting a refused {@link WorkflowsClient.submit}.
+     *
+     * 🔴 DO NOT REQUIRE `'succeeded'`. Nothing runs on an estimate, so a priced
+     * one comes back with a status that has not finished (`'pending'` in
+     * practice). Read the price with {@link estimatedCost}, which is `null`
+     * exactly when there is none to show:
+     *
+     * ```ts
+     * const price = estimatedCost(await app.workflows.estimate(body));
+     * if (price === null) showMessage('This generation could not be priced.');
+     * ```
      */
     estimate(body: WorkflowBody, opts?: WorkflowCallOptions): Promise<BlockWorkflowSnapshot>;
     /**

package/dist/workflows/index.js

@@ -51,6 +51,28 @@ export class SubmissionUnconfirmedError extends CivitaiError {
         this.snapshot = snapshot;
     }
 }
+/**
+ * The price an {@link WorkflowsClient.estimate} reply quotes, in whole Buzz, or
+ * `null` when it quotes none.
+ *
+ * An estimate is priced when its `status` is not `'failed'` AND it carries a
+ * numeric `cost.total`. That is the whole rule, and it is the one to branch on:
+ * - Do not require `'succeeded'`. Nothing runs on an estimate, so a priced one
+ *   comes back with a status that has not finished (`'pending'` in practice),
+ *   and a check for `'succeeded'` reads every price as missing.
+ * - `0` is a price.
+ * - A `'failed'` snapshot is never priced, even one carrying a `cost.total`: a
+ *   budget refusal carries the total it would not charge.
+ * - A snapshot with no numeric `cost.total` is not priced, whatever its status.
+ *
+ * `null` does not predict a refused {@link WorkflowsClient.submit}: a body the
+ * host cannot price can still be submitted. Read `error` / `errorCode` on the
+ * snapshot for why.
+ */
+export function estimatedCost(snapshot) {
+    const total = snapshot.cost?.total;
+    return snapshot.status !== 'failed' && typeof total === 'number' ? total : null;
+}
 const isSnapshot = (value) => value != null && typeof value === 'object' && typeof value.status === 'string';
 /**
  * Asserted, not cast: every caller branches on `status`, and a reply without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "The Civitai SDK: an app holds a token and calls the Civitai API and the orchestrator; a block asks its host only to show host UI.",
   "license": "MIT",
   "type": "module",