@civitai/sdk 0.12.0 → 0.13.0

package/README.md

@@ -492,15 +492,15 @@ Do **one of two things, and never mint a new key for that press**:
 🔴 **For a `kind: 'training'` body and a step body carrying a `quoteId`, the
 key is not the run's identity.** The host does not use the client key on those
 two; the run is identified by the confirmed quote (a step) or by the training
-run itself. A submit that names a **new** quote is a new run, whatever key it
-carries. So after an unknown outcome on one of these, check
+run itself. So after an unknown outcome on one of these, check
 `app.workflows.list()` **before** asking the viewer to confirm another quote.
 
 What this client can promise stops there. Matching a repeated key to an
 existing run is done by the host and the orchestrator, not here; it is not
-guaranteed to match, and the host remembers a key only for a limited time. So
-`list()` is the check that does not depend on it: when a retry is late, or
-fails again, look there before telling the viewer nothing ran.
+guaranteed to match, and the host remembers a key only for a limited time.
+`list()` does not settle it either: a listed workflow carries no idempotency
+key, so it cannot be tied to a press for certain, and a run missing from it is
+not proof that nothing ran.
 
 ```ts
 import { ApiError, SubmissionUnconfirmedError } from '@civitai/sdk';
@@ -565,7 +565,7 @@ server text — log it and show your own copy.
 without one. The key is what lets the host recognise a submit that was sent
 twice — a retry after a dropped connection, a double press — as one request
 (for a `kind: 'training'` body or a step with a `quoteId`, see the note above:
-there the quote, not the key, identifies the run).
+there the key is not the run's identity).
 
 - Mint it **once per thing the viewer asked for**, keep it until that press has
   a known outcome, and reuse it on every retry. A key minted inside the retry

package/dist/core/transport.d.ts

@@ -9,7 +9,10 @@ export interface BlockSnapshot {
     context: BlockContext;
     token: BlockToken;
     settings: BlockSettings;
-    /** `null` for anonymous viewers. For identity, read `/me` from the API rather than this. */
+    /**
+     * `null` for anonymous viewers. For identity, read `app.site.get('blocks/me')`
+     * rather than this — not `site.get('me')`, which does not accept a block token.
+     */
     viewer: ViewerInfo | null;
     theme: Theme;
     blockInstanceId: string;

package/dist/core/transports/host-replies.generated.d.ts

@@ -0,0 +1,18 @@
+export interface HostReply {
+    /** The message type the host answers with. */
+    readonly reply: string;
+    /** `legacy`: fields straight in the payload, failure as a string. */
+    readonly framing: 'envelope' | 'legacy';
+    /** The keys a success carries besides `requestId`; `null` where the host's literal could not be read. */
+    readonly keys: readonly string[] | null;
+}
+/** The civitai commit this ledger was read from. A request the host added after it is refused too. */
+export declare const HOST_SNAPSHOT = "464b2023e8";
+/**
+ * Every request the host answered at {@link HOST_SNAPSHOT}. A type absent here is refused.
+ * Reply names and framing are fixed at publish time: if the host renames a reply or moves a
+ * type to envelope framing, builds on this version stop receiving it until they upgrade.
+ */
+export declare const HOST_REPLIES: Readonly<Record<string, HostReply>>;
+/** The host's fire-and-forget messages: it handles them and never replies. */
+export declare const HOST_NOTIFICATIONS: ReadonlySet<string>;

package/dist/core/transports/host-replies.generated.js

@@ -0,0 +1,66 @@
+// Generated by scripts/gen-host-replies.mjs from snapshots/host-messages.json
+// (civitai/civitai 464b2023e8, 2026-10-14). Do not edit.
+/** The civitai commit this ledger was read from. A request the host added after it is refused too. */
+export const HOST_SNAPSHOT = "464b2023e8";
+/**
+ * Every request the host answered at {@link HOST_SNAPSHOT}. A type absent here is refused.
+ * Reply names and framing are fixed at publish time: if the host renames a reply or moves a
+ * type to envelope framing, builds on this version stop receiving it until they upgrade.
+ */
+export const HOST_REPLIES = {
+    "APP_STORAGE_DELETE": { "reply": "APP_STORAGE_DELETE_RESULT", "framing": "legacy", "keys": ["deleted", "ok"] },
+    "APP_STORAGE_GET": { "reply": "APP_STORAGE_GET_RESULT", "framing": "legacy", "keys": ["value"] },
+    "APP_STORAGE_LIST": { "reply": "APP_STORAGE_LIST_RESULT", "framing": "legacy", "keys": ["keys", "nextCursor"] },
+    "APP_STORAGE_QUOTA": { "reply": "APP_STORAGE_QUOTA_RESULT", "framing": "legacy", "keys": ["limitBytes", "limitRows", "rowCount", "usedBytes"] },
+    "APP_STORAGE_SET": { "reply": "APP_STORAGE_SET_RESULT", "framing": "legacy", "keys": ["ok", "sizeBytes"] },
+    "CANCEL_APP_WORKFLOW": { "reply": "CANCEL_APP_WORKFLOW_RESULT", "framing": "legacy", "keys": ["result"] },
+    "CANCEL_WORKFLOW": { "reply": "WORKFLOW_CANCELED", "framing": "legacy", "keys": ["snapshot"] },
+    "CREATE_POST_FROM_APP": { "reply": "CREATE_POST_RESULT", "framing": "legacy", "keys": ["result"] },
+    "ESTIMATE_WORKFLOW": { "reply": "ESTIMATE_RESULT", "framing": "legacy", "keys": ["snapshot"] },
+    "ESTIMATE_WORKFLOW_BATCH": { "reply": "ESTIMATE_BATCH_RESULT", "framing": "legacy", "keys": ["aggregate", "snapshots"] },
+    "GET_BUZZ_ACCOUNTS": { "reply": "BUZZ_ACCOUNTS_RESULT", "framing": "legacy", "keys": ["result"] },
+    "GET_BUZZ_BALANCE": { "reply": "BUZZ_BALANCE_RESULT", "framing": "legacy", "keys": ["balance"] },
+    "GET_BUZZ_TRANSACTIONS": { "reply": "BUZZ_TRANSACTIONS_RESULT", "framing": "legacy", "keys": ["result"] },
+    "GET_DAILY_COMPENSATION": { "reply": "DAILY_COMPENSATION_RESULT", "framing": "legacy", "keys": ["result"] },
+    "GET_IMAGES_BY_IDS": { "reply": "IMAGES_RESULT", "framing": "legacy", "keys": ["result"] },
+    "GET_VIEWER": { "reply": "VIEWER_RESULT", "framing": "legacy", "keys": ["viewer"] },
+    "GET_WILDCARD_PACK": { "reply": "WILDCARD_PACK_RESULT", "framing": "legacy", "keys": ["pack"] },
+    "OPEN_BUZZ_PURCHASE": { "reply": "BUZZ_PURCHASE_RESULT", "framing": "legacy", "keys": ["purchased"] },
+    "OPEN_CHECKPOINT_PICKER": { "reply": "CHECKPOINT_PICKER_RESULT", "framing": "legacy", "keys": ["selected"] },
+    "OPEN_IMAGE_PICKER": { "reply": "IMAGE_PICKER_RESULT", "framing": "legacy", "keys": ["selected", "selectedImages"] },
+    "OPEN_IMAGE_UPLOAD": { "reply": "IMAGE_UPLOAD_RESULT", "framing": "legacy", "keys": ["selected"] },
+    "OPEN_RESOURCE_PICKER": { "reply": "RESOURCE_PICKER_RESULT", "framing": "legacy", "keys": ["selected", "selectedResources"] },
+    "POLL_WORKFLOW": { "reply": "WORKFLOW_STATUS", "framing": "legacy", "keys": ["snapshot"] },
+    "PREPARE_TRAINING_DATASET": { "reply": "TRAINING_DATASET_RESULT", "framing": "legacy", "keys": ["result"] },
+    "PUBLISH_GENERATION_OUTPUTS": { "reply": "PUBLISH_RESULT", "framing": "legacy", "keys": ["result"] },
+    "QUERY_APP_WORKFLOWS": { "reply": "APP_WORKFLOWS_RESULT", "framing": "legacy", "keys": ["result"] },
+    "REQUEST_TOKEN": { "reply": "TOKEN_REFRESH_RESPONSE", "framing": "legacy", "keys": ["token"] },
+    "RUN_CONFIRMED_STEP": { "reply": "CONFIRMED_STEP_RESULT", "framing": "legacy", "keys": ["snapshot"] },
+    "RUN_TRAINING": { "reply": "TRAINING_RESULT", "framing": "legacy", "keys": ["snapshot"] },
+    "SAVE_IMAGE": { "reply": "SAVE_IMAGE_RESULT", "framing": "legacy", "keys": ["ok"] },
+    "SET_COLLECTION_FOLLOW": { "reply": "COLLECTION_FOLLOW_RESULT", "framing": "legacy", "keys": ["result"] },
+    "SET_USER_CHECKPOINT": { "reply": "USER_CHECKPOINT_SET", "framing": "legacy", "keys": ["ok"] },
+    "SHARED_APPEND": { "reply": "SHARED_APPEND_RESULT", "framing": "legacy", "keys": ["key"] },
+    "SHARED_GET": { "reply": "SHARED_GET_RESULT", "framing": "legacy", "keys": ["item"] },
+    "SHARED_GET_COUNT": { "reply": "SHARED_GET_COUNT_RESULT", "framing": "legacy", "keys": ["count"] },
+    "SHARED_GET_COUNTS": { "reply": "SHARED_GET_COUNTS_RESULT", "framing": "legacy", "keys": ["counts"] },
+    "SHARED_LIST": { "reply": "SHARED_LIST_RESULT", "framing": "legacy", "keys": ["items", "nextCursor"] },
+    "SHARED_REPORT": { "reply": "SHARED_REPORT_RESULT", "framing": "legacy", "keys": ["ok"] },
+    "SHARED_UNVOTE": { "reply": "SHARED_UNVOTE_RESULT", "framing": "legacy", "keys": ["count"] },
+    "SHARED_UPDATE": { "reply": "SHARED_UPDATE_RESULT", "framing": "legacy", "keys": ["ok"] },
+    "SHARED_VOTE": { "reply": "SHARED_VOTE_RESULT", "framing": "legacy", "keys": ["count"] },
+    "SHARED_WITHDRAW": { "reply": "SHARED_WITHDRAW_RESULT", "framing": "legacy", "keys": ["deleted", "ok"] },
+    "SUBMIT_WORKFLOW": { "reply": "WORKFLOW_SUBMITTED", "framing": "legacy", "keys": ["snapshot"] },
+};
+/** The host's fire-and-forget messages: it handles them and never replies. */
+export const HOST_NOTIFICATIONS = new Set([
+    "BLOCK_ERROR",
+    "BLOCK_HELLO",
+    "BLOCK_MESSAGE_REJECTED",
+    "BLOCK_READY",
+    "NAVIGATE",
+    "REQUEST_CONSENT",
+    "REQUEST_SIGN_IN",
+    "RESIZE_IFRAME",
+    "TRACK_EVENT",
+]);

package/dist/core/transports/iframe-transport.d.ts

@@ -1,4 +1,10 @@
 import { type BlockSnapshot, type BlockTransport, type RequestOptions } from '../transport.js';
+import { BridgeError } from '../errors.js';
+import { type HostReply } from './host-replies.generated.js';
+/** Why `request(type)` cannot settle, and what to call instead. */
+export declare function unanswerable(type: string): BridgeError;
+/** Turns a reply into the value it carries, or the failure it reports. */
+export declare function unwrap(type: string, reply: unknown, expected: HostReply): unknown;
 export interface IframeTransportOptions {
     /** At least one entry. Other origins — including the local one — drop silently. */
     allowedParentOrigins: string[];

package/dist/core/transports/iframe-transport.js

@@ -2,48 +2,63 @@ import { isHostMessage, parseBlockInitFragment, stripBlockInitFragment, } from '
 import { EMPTY_SNAPSHOT, snapshotFromInit, tokenFromWrapped, } from '../transport.js';
 import { BridgeError, classifyHostError } from '../errors.js';
 import { OriginMatcher } from '../origin-matcher.js';
+import { HOST_NOTIFICATIONS, HOST_REPLIES, HOST_SNAPSHOT } from './host-replies.generated.js';
 import { VERSION } from '../../version.generated.js';
 /**
  * The framing the host had before this package owned the protocol: fields
  * straight in the payload, and failure as the server's own sentence. Converting
  * it here is what keeps the rest of this file — and every domain — speaking one
- * shape; when the host modernises a message, its domain drops the declaration
- * and this stops being reached.
+ * shape; when the host modernises a message, the snapshot reports it as
+ * `envelope` and this stops being reached for it.
  */
-function fromLegacyReply(reply) {
+function fromLegacyReply(reply, keys) {
     const { requestId, error, ...fields } = reply;
     // An empty string is how the host spells "no failure" on these replies.
     if (typeof error === 'string' && error !== '') {
         return { requestId, error: { code: classifyHostError(error), message: error } };
     }
     // Some of these replies nest their value under `result` and others put its
-    // fields straight in the payload; the host was never consistent about it.
-    return { requestId, result: 'result' in fields ? fields.result : fields };
+    // fields straight in the payload. The snapshot says which; where the host's
+    // reply could not be read (`keys` null), the payload itself decides.
+    const nested = keys === null ? 'result' in fields : keys.length === 1 && keys[0] === 'result';
+    return { requestId, result: nested ? fields.result : fields };
 }
 /**
- * The host's pre-protocol messages, each with the reply it answers with —
- * `<REQUEST>_RESULT` holds across most of them but not all. It is the migration
- * ledger for this protocol: an entry leaves the day the host modernises that
- * reply, and when it empties `fromLegacyReply` goes with it.
+ * Where a caller should go instead of a bridge message, from BREAKING.md. Only
+ * read when the host does not answer the type, so it is what a request the
+ * host dropped (or never had) says instead of hanging.
  */
-const LEGACY_REPLIES = {
-    OPEN_BUZZ_PURCHASE: 'BUZZ_PURCHASE_RESULT',
-    OPEN_IMAGE_UPLOAD: 'IMAGE_UPLOAD_RESULT',
-    OPEN_RESOURCE_PICKER: 'RESOURCE_PICKER_RESULT',
-    PUBLISH_GENERATION_OUTPUTS: 'PUBLISH_RESULT',
-    REQUEST_TOKEN: 'TOKEN_REFRESH_RESPONSE',
-    SAVE_IMAGE: 'SAVE_IMAGE_RESULT',
-};
-function replyTypeFor(type) {
-    return LEGACY_REPLIES[type] ?? `${type}_RESULT`;
+const REPLACED_BY = [
+    [/^GET_VIEWER$/, "app.site.get('blocks/me')"],
+    [/^(SUBMIT|ESTIMATE|POLL|CANCEL)_WORKFLOW$|^QUERY_APP_WORKFLOWS$|^CANCEL_APP_WORKFLOW$/, 'app.workflows'],
+    [/^GET_IMAGES_BY_IDS$/, 'GET /api/v1/blocks/images?ids=… (app.site)'],
+    [/^APP_STORAGE_/, 'POST /api/v1/blocks/app-storage/* (app.site)'],
+    [/^SHARED_/, 'app.sharedStorage'],
+    [/^GET_BUZZ_BALANCE$/, "app.site.get('blocks/buzz')"],
+    [/^SET_COLLECTION_FOLLOW$/, 'POST /api/v1/blocks/collections/{id}/follow (app.site)'],
+    [/^TRACK_EVENT$/, 'app.host.track(eventName, properties)'],
+    [/^PUBLISH_GENERATION_OUTPUTS$/, 'app.host.publishGenerationOutputs'],
+];
+/** Why `request(type)` cannot settle, and what to call instead. */
+export function unanswerable(type) {
+    const instead = REPLACED_BY.find(([pattern]) => pattern.test(type))?.[1];
+    const message = HOST_NOTIFICATIONS.has(type)
+        ? `${type} is fire-and-forget: the host never answers it, so request() would wait forever. ` +
+            `Send it with notify()${instead ? `, or use ${instead}` : ''}.`
+        : `${type} is not a request the host answered at civitai ${HOST_SNAPSHOT}, ` +
+            `the host snapshot @civitai/sdk ${VERSION} was built from, so request() would wait forever. ` +
+            (instead
+                ? `Use ${instead} instead.`
+                : 'If the host has added it since, upgrade @civitai/sdk; otherwise see BREAKING.md for where bridge messages moved.');
+    return new BridgeError('invalid', type, message);
 }
 /** Turns a reply into the value it carries, or the failure it reports. */
-function unwrap(type, reply, framing) {
+export function unwrap(type, reply, expected) {
     if (reply == null || typeof reply !== 'object') {
         throw new BridgeError('malformed', type, `${type} replied with no payload`);
     }
-    const envelope = framing === 'legacy'
-        ? fromLegacyReply(reply)
+    const envelope = expected.framing === 'legacy'
+        ? fromLegacyReply(reply, expected.keys)
         : reply;
     if (envelope.error !== undefined) {
         throw new BridgeError(envelope.error.code, type, envelope.error.message || `${type} failed`);
@@ -187,11 +202,14 @@ export class IframeTransport {
         this.#dispatch(message.type, message.payload);
     }
     async request(type, params, opts = {}) {
-        const framing = type in LEGACY_REPLIES ? 'legacy' : 'envelope';
-        return unwrap(type, await this.#exchange(type, params, opts), framing);
+        // Own keys only: `HOST_REPLIES['toString']` must not read as an answer.
+        const expected = Object.hasOwn(HOST_REPLIES, type) ? HOST_REPLIES[type] : undefined;
+        // Nothing would ever answer it, so say so now rather than wait forever.
+        if (!expected)
+            throw unanswerable(type);
+        return unwrap(type, await this.#exchange(type, expected.reply, params, opts), expected);
     }
-    #exchange(type, params, opts) {
-        const responseType = replyTypeFor(type);
+    #exchange(type, responseType, params, opts) {
         const { signal } = opts;
         if (signal?.aborted)
             return Promise.reject(signal.reason);

package/dist/host/index.js

@@ -60,10 +60,12 @@ export function createHost(transport) {
                 transport,
             });
             // The host spells "no failure" as `error: ''`, which the transport reads
-            // as a success — so a reply carrying neither the ids nor a message gets
-            // this far, and returning it would resolve `undefined` from a promise
-            // that says `number[]`. A caller reading that as "nothing published"
-            // would be guessing: images may well have been.
+            // as a success. A reply with no `result` at all is refused by the
+            // transport (the ledger says this reply nests under `result`), but one
+            // whose `result` lacks the ids gets this far, and returning it would
+            // resolve `undefined` from a promise that says `number[]`. A caller
+            // reading that as "nothing published" would be guessing: images may well
+            // have been.
             if (!Array.isArray(imageIds) || !imageIds.every((id) => typeof id === 'number')) {
                 throw new BridgeError('malformed', 'PUBLISH_GENERATION_OUTPUTS', 'PUBLISH_GENERATION_OUTPUTS reply carried no image ids. Whether anything ' +
                     'was published is unknown; read the workflow back rather than assuming.');

package/dist/session/index.d.ts

@@ -1,5 +1,5 @@
 /** Every scope an app can hold, as the site names them. */
-export declare const SCOPES: readonly ['ai:write:budgeted', 'apps:storage:read', 'apps:storage:shared:read', 'apps:storage:shared:write', 'apps:storage:write', 'buzz:read:self', 'collections:read:private', 'collections:read:self', 'collections:write:self', 'models:read:self', 'posts:write:self', 'social:tip:self', 'user:read:self'];
+export declare const SCOPES: readonly ['ai:write:budgeted', 'apps:storage', 'apps:storage:publish', 'apps:storage:read', 'apps:storage:shared:read', 'apps:storage:shared:write', 'apps:storage:write', 'apps:store:items:write', 'buzz:read:self', 'collections:read:private', 'collections:read:self', 'collections:write:self', 'goods:purchase:self', 'goods:read:self', 'models:read:self', 'posts:write:self', 'social:tip:self', 'user:read:self'];
 export type Scope = (typeof SCOPES)[number];
 export interface TokenOptions {
     /** Skip the held token and get a new one, e.g. after the API refused it. */

package/dist/session/index.js

@@ -1,14 +1,19 @@
 /** Every scope an app can hold, as the site names them. */
 export const SCOPES = [
     'ai:write:budgeted',
+    'apps:storage',
+    'apps:storage:publish',
     'apps:storage:read',
     'apps:storage:shared:read',
     'apps:storage:shared:write',
     'apps:storage:write',
+    'apps:store:items:write',
     'buzz:read:self',
     'collections:read:private',
     'collections:read:self',
     'collections:write:self',
+    'goods:purchase:self',
+    'goods:read:self',
     'models:read:self',
     'posts:write:self',
     'social:tip:self',

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.12.0";
+export declare const VERSION = "0.13.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.12.0";
+export const VERSION = "0.13.0";

package/dist/workflows/index.d.ts

@@ -138,13 +138,15 @@ export interface WorkflowsClient {
      * {@link WorkflowsClient.list}. Never mint a new key for the same viewer
      * action: to the host a new key is a new generation. That matching is the
      * host's and the orchestrator's, is not guaranteed, and is not something
-     * this client can verify; `list` is the check that does not depend on it.
+     * this client can verify. Nor does `list` settle it: a listed workflow
+     * carries no idempotency key, and a run missing from it is not proof that
+     * nothing ran.
      *
      * 🔴 For a `kind: 'training'` body and a step body carrying a `quoteId` the
      * key is NOT the run's identity: the host does not use it there, and
-     * identifies the run by the confirmed quote or the training run. A submit
-     * naming a new quote is a new run. After an unknown outcome on one of
-     * these, check `list` before asking the viewer to confirm another quote.
+     * identifies the run by the confirmed quote or the training run. After an
+     * unknown outcome on one of these, check `list` before asking the viewer to
+     * confirm another quote.
      *
      * This client does not retry a failed submit itself; it only re-sends once
      * after refreshing an expired token, as every call does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.12.0",
+  "version": "0.13.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",
@@ -69,6 +69,8 @@
     "gen:steps": "node scripts/gen-step-types.mjs",
     "check:steps": "node scripts/gen-step-types.mjs --check",
     "gen:workflow-types": "node scripts/gen-workflow-types.mjs",
+    "gen:host-replies": "node scripts/gen-host-replies.mjs",
+    "check:host-replies": "node scripts/gen-host-replies.mjs --check",
     "snapshot:host": "node scripts/snapshot-host-messages.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json && tsc -p tsconfig.examples.json",
     "test": "vitest run",