@civitai/sdk 0.13.1 → 0.14.1

package/dist/doc-store/index.d.ts

@@ -0,0 +1,187 @@
+import { ApiError, type Http } from '../http/index.js';
+export interface DocumentCallOptions {
+    signal?: AbortSignal;
+}
+/** Who wrote a document, as every reader sees it. Never a numeric user id. */
+export type DocumentAuthor = 
+/**
+ * A viewer. `isViewer` is whether that is the viewer reading it; `username` is
+ * present only when the collection declares `showAuthor` (and the user has one).
+ */
+{
+    kind: 'user';
+    isViewer: boolean;
+    username?: string;
+}
+/** Written by the app owner (a later phase; nothing writes one yet). */
+ | {
+    kind: 'app';
+}
+/** Created by the first increment of a counter in a `write: "none"` collection; nobody owns it. */
+ | {
+    kind: 'counter';
+};
+export interface StorageDocument<T extends object = Record<string, unknown>> {
+    key: string;
+    data: T;
+    /** +1 on every `data` write. Counter and mark changes do not move it. */
+    version: number;
+    /** Revived from the wire's ISO string, once, here. */
+    createdAt: Date;
+    updatedAt: Date;
+    author: DocumentAuthor;
+    /** Declared counters of a shared collection; `{}` on a private one. */
+    counters: Record<string, number>;
+    /** Declared mark counts of a shared collection (never `report`'s); `{}` on a private one. */
+    marks: Record<string, number>;
+    /** The viewer's own marks on this document; `null` for an anonymous viewer. */
+    viewer: {
+        marks: string[];
+    } | null;
+}
+/** A `time` index filters by an ISO-8601 string or epoch milliseconds; a `Date` is sent as ISO. */
+export type DocumentWhereValue = string | number | boolean | Date;
+export interface DocumentListQuery {
+    /**
+     * Equality on ONE declared index: `{ status: 'open' }`. An undeclared field is
+     * refused `index_not_declared`, more than one field `invalid_request`.
+     */
+    where?: Record<string, DocumentWhereValue>;
+    /**
+     * `[-]key | createdAt | updatedAt | <index> | counter:<name> | mark:<name>`; a
+     * leading `-` is descending. The server's default is `key`.
+     */
+    sort?: string;
+    /** Only documents the viewer authored. */
+    author?: 'me';
+    /** With {@link DocumentListQuery.mark}: only documents the viewer marked with it. */
+    markedBy?: 'me';
+    mark?: string;
+    keyPrefix?: string;
+    /** The server bounds it and applies its own default; this client sends none. */
+    limit?: number;
+    /** A `nextCursor` from the previous page of the SAME query. */
+    cursor?: string;
+}
+export interface DocumentPage<T extends object = Record<string, unknown>> {
+    items: StorageDocument<T>[];
+    /** `null` exactly when this was the last page. Passed through as the server sent it. */
+    nextCursor: string | null;
+}
+export interface WriteOptions extends DocumentCallOptions {
+    /**
+     * Write only if the document is at this version — `0` means only if it does not
+     * exist yet. A mismatch rejects with `version_conflict` and
+     * `details.currentVersion`.
+     */
+    ifVersion?: number;
+}
+export interface StorageCollection<T extends object = Record<string, unknown>> {
+    /** The document, or `null` when there is none (missing, hidden and absent read alike). */
+    get(key: string, opts?: DocumentCallOptions): Promise<StorageDocument<T> | null>;
+    /** One round trip; the result is in the order of `keys`, `null` for each miss. */
+    getMany(keys: readonly string[], opts?: DocumentCallOptions): Promise<(StorageDocument<T> | null)[]>;
+    /** Create or replace the document at `key`. */
+    put(key: string, data: T, opts?: WriteOptions): Promise<StorageDocument<T>>;
+    /** Create a document under a key the server chooses (a sortable id). */
+    create(data: T, opts?: DocumentCallOptions): Promise<StorageDocument<T>>;
+    /** Idempotent: `deleted: false` means there was nothing to delete. */
+    delete(key: string, opts?: WriteOptions): Promise<{
+        deleted: boolean;
+    }>;
+    /** One page. Follow `nextCursor` with the same query for the next one. */
+    list(query?: DocumentListQuery, opts?: DocumentCallOptions): Promise<DocumentPage<T>>;
+    /**
+     * Add `by` (the server's default when omitted) to a declared counter of a
+     * shared document. In a `write: "none"` collection the first increment of an
+     * absent key creates the document.
+     */
+    increment(key: string, counter: string, by?: number, opts?: DocumentCallOptions): Promise<{
+        value: number;
+    }>;
+    /**
+     * Set the viewer's mark on a shared document — a declared mark, or the
+     * built-in `report`. Idempotent. `count` is absent for `report`, whose count is
+     * never exposed.
+     */
+    mark(key: string, name: string, opts?: DocumentCallOptions): Promise<{
+        marked: true;
+        count?: number;
+    }>;
+    /**
+     * Remove the viewer's mark. Idempotent. A `report` cannot be withdrawn: the
+     * server refuses it `invalid_request` (400) for every caller.
+     */
+    unmark(key: string, name: string, opts?: DocumentCallOptions): Promise<{
+        marked: false;
+        count?: number;
+    }>;
+}
+export type StorageIndexType = 'string' | 'number' | 'boolean' | 'time';
+/** One declared collection, as the server reads the app's approved manifest. */
+export interface StorageCollectionInfo {
+    kind: string;
+    visibility: 'private' | 'shared';
+    /** Shared collections only. */
+    write?: string;
+    counters: string[];
+    marks: string[];
+    indexes: Record<string, StorageIndexType>;
+    showAuthor: boolean;
+}
+export interface StorageUsage {
+    /** The STORED unit (the database's own measure of the JSON), which the ceilings bind in. */
+    bytes: number;
+    docs: number;
+}
+/** Render these, never a compiled-in figure: they are the server's and can move. */
+export interface StorageLimits {
+    docBytes: number;
+    appBytes: number;
+    appDocs: number;
+    viewerBytes: number;
+    viewerDocs: number;
+    listLimitMax: number;
+    getManyMax: number;
+    rate: {
+        readsPerMinute: number;
+        privateWritesPerMinute: number;
+        marksAndCountersPerMinute: number;
+        reportsPerDay: number;
+        sharedWritesBurst: number;
+        sharedWritesPerDay: number;
+    };
+}
+export interface StorageInfo {
+    collections: Record<string, StorageCollectionInfo>;
+    limits: StorageLimits;
+    usage: {
+        app: StorageUsage;
+        viewer: StorageUsage;
+    };
+}
+/** The document store's surface on `app.storage`. */
+export interface DocumentStorage {
+    /** A declared collection. Nothing is sent until an operation is called. */
+    collection<T extends object = Record<string, unknown>>(name: string): StorageCollection<T>;
+    /** The declared collections, the limits and the usage so far. Signed-in viewers only. */
+    info(opts?: DocumentCallOptions): Promise<StorageInfo>;
+}
+/**
+ * Every code the server documents for these routes. The type stays open
+ * (`string & {}`) so a code a later server adds still reaches the caller.
+ */
+export type StorageErrorCode = 'invalid_request' | 'index_not_declared' | 'unauthenticated' | 'sign_in_required' | 'insufficient_scope' | 'consent_required' | 'not_eligible' | 'not_author' | 'write_policy' | 'not_found' | 'collection_not_declared' | 'method_not_allowed' | 'version_conflict' | 'index_building' | 'cursor_expired' | 'too_large' | 'quota_exceeded' | 'content_rejected' | 'rate_limited' | 'internal_error' | 'storage_disabled' | 'moderation_unavailable' | 'consent_unavailable' | 'service_unavailable' | (string & {});
+/**
+ * A refusal from the document store, in its one envelope `{ code, message, error, details? }`.
+ * Branch on `code`; `status` and `body` are {@link ApiError}'s, as sent.
+ */
+export declare class StorageError extends ApiError {
+    readonly code: StorageErrorCode;
+    /** E.g. `currentVersion`, `reason`, `category`, `ceiling`, `bucket`, `retryAfter`. */
+    readonly details?: Record<string, unknown>;
+    constructor(status: number, code: StorageErrorCode, message: string, body: unknown, details?: Record<string, unknown>, options?: ErrorOptions);
+    /** Seconds to wait before retrying, when the server named one (`rate_limited`, a retryable 503). */
+    get retryAfter(): number | undefined;
+}
+export declare function createDocumentStorage(http: Http): DocumentStorage;

package/dist/doc-store/index.js

@@ -0,0 +1,260 @@
+import { CivitaiError } from '../core/errors.js';
+import { ApiError } from '../http/index.js';
+/**
+ * The App Blocks DOCUMENT STORE: named collections of JSON documents, declared in
+ * the app's manifest under `storage.collections`, served by `/api/v1/blocks/storage/…`.
+ *
+ * It replaces the two key/value stores (`app.storage.get/set/…` and
+ * `app.sharedStorage`), which keep working, unchanged, until every app has moved.
+ *
+ * The rules — who may read or write which collection, the limits, the error codes
+ * — are the server's, and this client re-spells none of them. It sends a request,
+ * reads the reply, and turns a refusal into a {@link StorageError} carrying the
+ * server's own `code`. It refuses only what would reach a DIFFERENT route: a path
+ * segment a URL cannot carry (`''`, `.`, `..`), which `fetch` would rewrite, and a
+ * collection name outside the manifest's rule (`_get` is itself a route) — each with
+ * the code the server gives the same input.
+ */
+/** Where the routes live under the site base URL (`…/api/v1`). */
+const BASE = 'blocks/storage';
+/** The batch-get route sits at the collection position behind a `_`, which no collection name can start with. */
+const GET_MANY = '_get';
+/**
+ * A refusal from the document store, in its one envelope `{ code, message, error, details? }`.
+ * Branch on `code`; `status` and `body` are {@link ApiError}'s, as sent.
+ */
+export class StorageError extends ApiError {
+    code;
+    /** E.g. `currentVersion`, `reason`, `category`, `ceiling`, `bucket`, `retryAfter`. */
+    details;
+    constructor(status, code, message, body, details, options) {
+        super(status, message, body);
+        if (options?.cause !== undefined)
+            Object.defineProperty(this, 'cause', { value: options.cause });
+        this.name = 'StorageError';
+        this.code = code;
+        if (details !== undefined)
+            this.details = details;
+    }
+    /** Seconds to wait before retrying, when the server named one (`rate_limited`, a retryable 503). */
+    get retryAfter() {
+        const value = this.details?.retryAfter;
+        return typeof value === 'number' ? value : undefined;
+    }
+}
+/** An {@link ApiError} whose body is the store's envelope becomes a {@link StorageError}; anything else passes through. */
+function toStorageError(error) {
+    if (!(error instanceof ApiError) || error instanceof StorageError)
+        return error;
+    const body = error.body;
+    if (body == null || typeof body !== 'object' || Array.isArray(body))
+        return error;
+    const { code, message, details } = body;
+    if (typeof code !== 'string')
+        return error;
+    return new StorageError(error.status, code, typeof message === 'string' ? message : error.message, body, details != null && typeof details === 'object' && !Array.isArray(details)
+        ? details
+        : undefined, { cause: error });
+}
+/**
+ * The manifest's rule for a collection name. A name outside it can never be
+ * declared, and some of those (`_get`, `_drafts`) are ROUTES at that position, which
+ * the server answers with a route-level `not_found` — which `get` would read as "no
+ * such document". So such a name is refused here, before sending, with the code the
+ * server gives any undeclared collection.
+ */
+const COLLECTION_NAME = /^[a-z][a-z0-9_]{0,31}$/;
+function collectionSegment(name) {
+    if (typeof name !== 'string' || !COLLECTION_NAME.test(name)) {
+        const status = 404;
+        const message = `collection ${JSON.stringify(name)} is not a valid collection name (refused before sending)`;
+        const details = { collection: name };
+        throw new StorageError(status, 'collection_not_declared', message, { code: 'collection_not_declared', message, error: message, details }, details);
+    }
+    return name;
+}
+/**
+ * A path segment from caller input. Encoded, so `/`, `?`, `#` and spaces stay
+ * inside it; and refused when URL resolution would rewrite it — an empty segment
+ * collapses and `.`/`..` are path steps, so each would address a different route.
+ * Refused with the code the server gives the same key, so a caller branches once.
+ */
+function segment(what, value) {
+    if (typeof value !== 'string' || value === '' || value === '.' || value === '..') {
+        const status = 400;
+        const message = `${what} ${JSON.stringify(value)} cannot be addressed in a URL path (refused before sending)`;
+        throw new StorageError(status, 'invalid_request', message, { code: 'invalid_request', message, error: message });
+    }
+    return encodeURIComponent(value);
+}
+export function createDocumentStorage(http) {
+    const call = async (method, path, opts = {}) => {
+        try {
+            return await http(method, path, opts);
+        }
+        catch (error) {
+            throw toStorageError(error);
+        }
+    };
+    return {
+        collection(name) {
+            // Resolved per call, inside each async operation, so a bad name rejects that
+            // call rather than throwing from `collection()` itself.
+            const coll = () => collectionSegment(name);
+            const docPath = (key) => `${BASE}/${coll()}/${segment('key', key)}`;
+            const doc = (reply, op) => toDocument(reply, `${name}.${op}`);
+            return {
+                async get(key, { signal } = {}) {
+                    try {
+                        return doc(await call('GET', docPath(key), { signal }), 'get');
+                    }
+                    catch (error) {
+                        // Only THIS code is "no such document". `collection_not_declared` is a 404
+                        // too, and is a bug in the caller, never an empty answer.
+                        if (error instanceof StorageError && error.code === 'not_found')
+                            return null;
+                        throw error;
+                    }
+                },
+                async getMany(keys, { signal } = {}) {
+                    const reply = await call('POST', `${BASE}/${GET_MANY}/${coll()}`, {
+                        body: { keys: [...keys] },
+                        signal,
+                    });
+                    if (!Array.isArray(reply?.items) || reply.items.length !== keys.length) {
+                        throw new CivitaiError(`storage ${name}.getMany: reply carried no \`items\` array of ${keys.length}`);
+                    }
+                    return reply.items.map((item) => (item === null ? null : doc(item, 'getMany')));
+                },
+                async put(key, data, { ifVersion, signal } = {}) {
+                    // Named rather than spread: `JSON.stringify` drops an undefined `ifVersion`,
+                    // so an unconditional put sends `{ data }` and nothing else.
+                    return doc(await call('PUT', docPath(key), { body: { data, ifVersion }, signal }), 'put');
+                },
+                async create(data, { signal } = {}) {
+                    return doc(await call('POST', `${BASE}/${coll()}`, { body: { data }, signal }), 'create');
+                },
+                async delete(key, { ifVersion, signal } = {}) {
+                    const reply = await call('DELETE', docPath(key), {
+                        query: { ifVersion },
+                        signal,
+                    });
+                    if (typeof reply?.deleted !== 'boolean') {
+                        throw new CivitaiError(`storage ${name}.delete: reply carried no \`deleted\` flag`);
+                    }
+                    return { deleted: reply.deleted };
+                },
+                async list(query = {}, { signal } = {}) {
+                    const params = {
+                        sort: query.sort,
+                        author: query.author,
+                        markedBy: query.markedBy,
+                        mark: query.mark,
+                        keyPrefix: query.keyPrefix,
+                        limit: query.limit,
+                        cursor: query.cursor,
+                    };
+                    for (const [field, value] of Object.entries(query.where ?? {})) {
+                        params[`where[${field}]`] = value instanceof Date ? value.toISOString() : value;
+                    }
+                    const reply = await call('GET', `${BASE}/${coll()}`, {
+                        query: params,
+                        signal,
+                    });
+                    // 🔴 No `?? []` and no `?? null`: a malformed 200 must throw, never read as
+                    // "nothing here" or "last page".
+                    if (!Array.isArray(reply?.items)) {
+                        throw new CivitaiError(`storage ${name}.list: reply carried no \`items\` array`);
+                    }
+                    if (reply.nextCursor !== null && typeof reply.nextCursor !== 'string') {
+                        throw new CivitaiError(`storage ${name}.list: reply carried no \`nextCursor\``);
+                    }
+                    return { items: reply.items.map((item) => doc(item, 'list')), nextCursor: reply.nextCursor };
+                },
+                async increment(key, counter, by, { signal } = {}) {
+                    const reply = await call('POST', `${docPath(key)}/counters/${segment('counter', counter)}`, 
+                    // No body at all when `by` is omitted: the server's default applies.
+                    { body: by === undefined ? undefined : { by }, signal });
+                    if (typeof reply?.value !== 'number') {
+                        throw new CivitaiError(`storage ${name}.increment: reply carried no \`value\``);
+                    }
+                    return { value: reply.value };
+                },
+                async mark(key, markName, { signal } = {}) {
+                    const reply = await call('PUT', `${docPath(key)}/marks/${segment('mark', markName)}`, { signal });
+                    return toMarkResult(reply, true, `${name}.mark`);
+                },
+                async unmark(key, markName, { signal } = {}) {
+                    const reply = await call('DELETE', `${docPath(key)}/marks/${segment('mark', markName)}`, { signal });
+                    return toMarkResult(reply, false, `${name}.unmark`);
+                },
+            };
+        },
+        async info({ signal } = {}) {
+            const reply = await call('GET', BASE, { signal });
+            if (reply == null ||
+                typeof reply !== 'object' ||
+                typeof reply.collections !== 'object' ||
+                typeof reply.limits !== 'object' ||
+                typeof reply.usage !== 'object') {
+                throw new CivitaiError('storage info: reply carried no `collections`, `limits` and `usage`');
+            }
+            return reply;
+        },
+    };
+}
+function toMarkResult(reply, marked, op) {
+    const r = (reply ?? {});
+    if (r.marked !== marked || (r.count !== undefined && typeof r.count !== 'number')) {
+        throw new CivitaiError(`storage ${op}: malformed reply`);
+    }
+    return r.count === undefined ? { marked } : { marked, count: r.count };
+}
+const isRecord = (value) => value != null && typeof value === 'object' && !Array.isArray(value);
+function toDate(value, op, field) {
+    // `new Date(null)` is the epoch, not an Invalid Date: the type check is the gate.
+    const at = typeof value === 'string' ? new Date(value) : new Date(Number.NaN);
+    if (Number.isNaN(at.getTime()))
+        throw new CivitaiError(`storage ${op}: malformed \`${field}\``);
+    return at;
+}
+function toAuthor(value, op) {
+    if (isRecord(value)) {
+        // Every field copied by name, so nothing else the wire carries reaches a reader.
+        if (value.kind === 'app' || value.kind === 'counter')
+            return { kind: value.kind };
+        if (value.kind === 'user' && typeof value.isViewer === 'boolean') {
+            return typeof value.username === 'string'
+                ? { kind: 'user', isViewer: value.isViewer, username: value.username }
+                : { kind: 'user', isViewer: value.isViewer };
+        }
+    }
+    throw new CivitaiError(`storage ${op}: malformed \`author\``);
+}
+function toCounts(value, op, field) {
+    if (!isRecord(value) || Object.values(value).some((n) => typeof n !== 'number')) {
+        throw new CivitaiError(`storage ${op}: malformed \`${field}\``);
+    }
+    return { ...value };
+}
+function toDocument(reply, op) {
+    if (!isRecord(reply) || typeof reply.key !== 'string' || !isRecord(reply.data) || typeof reply.version !== 'number') {
+        throw new CivitaiError(`storage ${op}: reply is not a document`);
+    }
+    const viewer = reply.viewer;
+    if (viewer !== null &&
+        !(isRecord(viewer) && Array.isArray(viewer.marks) && viewer.marks.every((m) => typeof m === 'string'))) {
+        throw new CivitaiError(`storage ${op}: malformed \`viewer\``);
+    }
+    return {
+        key: reply.key,
+        data: reply.data,
+        version: reply.version,
+        createdAt: toDate(reply.createdAt, op, 'createdAt'),
+        updatedAt: toDate(reply.updatedAt, op, 'updatedAt'),
+        author: toAuthor(reply.author, op),
+        counters: toCounts(reply.counters, op, 'counters'),
+        marks: toCounts(reply.marks, op, 'marks'),
+        viewer: viewer === null ? null : { marks: [...viewer.marks] },
+    };
+}

package/dist/http/index.js

@@ -29,13 +29,30 @@ export function createHttp(options) {
         const { session } = options;
         let response = await send(method, path, opts, await session.getToken({ signal: opts.signal }));
         // One retry: a token that expired in flight is routine, a second refusal is not.
-        if (response.status === 401) {
+        // Not when the server says the VIEWER must sign in — a fresh token for the same
+        // anonymous viewer is refused identically, so the retry would only cost a
+        // re-mint and a second request.
+        if (response.status === 401 && !(await refusesTheViewer(response))) {
             const fresh = await session.getToken({ fresh: true, signal: opts.signal });
             response = await send(method, path, opts, fresh);
         }
         return read(response);
     };
 }
+/**
+ * A 401 about the viewer rather than the token: the storage routes' envelope code
+ * `sign_in_required`. Read from a clone, so the body is still there for `read`. A
+ * body that cannot be read is treated as a token refusal, i.e. retried as before.
+ */
+async function refusesTheViewer(response) {
+    try {
+        const body = (await response.clone().json());
+        return body?.code === 'sign_in_required';
+    }
+    catch {
+        return false;
+    }
+}
 function urlFor(baseUrl, path, query) {
     const url = new URL(`${baseUrl}/${path.replace(/^\/+/, '')}`);
     for (const [key, value] of Object.entries(query ?? {})) {

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { GrantOptions, Scope, TokenOptions, TokenSource } from './session/i
 export type { SiteClient } from './site/index.js';
 export type { SharedItem, SharedListQuery, SharedListResult, SharedStorageCallOptions, SharedStorageClient, SharedValue, } from './shared-storage/index.js';
 export type { StorageCallOptions, StorageClient, StorageKeyEntry, StorageListQuery, StorageListResult, StorageQuota, } from './storage/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 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, BlockTrainingQuote, BlockWorkflowSnapshot, BlockWorkflowStepSnapshot, BuzzAccountType, InlineComfyNode, KnownBlockWorkflowErrorCode, ModelSubstitutionReason, WithWorkflowStepRefs, WorkflowBody, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyInline, WorkflowBodyCustomComfyRecipe, WorkflowBodyPassThroughStep, WorkflowBodyStep, WorkflowBodyTextToImage, WorkflowBodyTraining, WorkflowBodyWorkflow, WorkflowBodyWorkflowStep, WorkflowStepRef, } from './workflows/types.generated.js';
@@ -19,7 +21,7 @@ export type { OrchestrationClient, Step, StepTemplate, WaitOptions, Workflow, Wo
 export { createHost } from './host/index.js';
 export type { ConsentRefusal, DownloadRequest, Host, HostCallOptions, ImageScanResult, NavigateScope, PendingImage, PickedResource, ResourcePickerType, SourceImage, UploadedImage, } from './host/index.js';
 export { ApiError } from './http/index.js';
-export type { Query, QueryValue, RequestOptions } from './http/index.js';
+export type { Http, Query, QueryValue, RequestOptions } from './http/index.js';
 export { BridgeError, CivitaiError } from './core/errors.js';
 export type { BridgeErrorCode, BridgeFailureCode } from './core/errors.js';
 export { getTransport } from './core/get-transport.js';

package/dist/index.js

@@ -16,6 +16,7 @@
 export { initialize } from './app/index.js';
 export { createSignIn, SignInError } from './sign-in/index.js';
 export { SCOPES } from './session/index.js';
+export { StorageError } from './doc-store/index.js';
 export { SubmissionUnconfirmedError } from './workflows/index.js';
 export { isTerminal, isTerminalStatus } from './orchestration/index.js';
 export { createHost } from './host/index.js';

package/dist/shared-storage/index.d.ts

@@ -51,7 +51,11 @@ export interface SharedItem {
     viewerVoted: boolean;
 }
 export interface SharedListQuery {
-    /** Narrows to keys starting with this. Escaped server-side against LIKE wildcards. */
+    /**
+     * Narrows to keys starting with this. Escaped server-side against LIKE wildcards.
+     * `append` mints every key as a ULID, so a prefix of your own choosing matches
+     * none of the rows it creates.
+     */
     prefix?: string;
     /** The server bounds this and applies its own default; this client sends none. */
     limit?: number;
@@ -94,12 +98,18 @@ export interface SharedListResult {
  *   write is refused by the scope binding before the handler runs, so it arrives
  *   as **403**, not the 401 a missing token gives.
  * - A signed-in viewer is not automatically a permitted writer: writes clear a
- *   minimum-trust gate (account age, paid tier, verified email or a linked OAuth
- *   account). Treat a write refusal as a normal outcome and say so in the UI.
+ *   minimum-trust gate (account age, completed onboarding, verified email or a
+ *   linked OAuth account, not banned or muted). Treat a write refusal as a
+ *   normal outcome and say so in the UI.
  *
  * 🔴 EVERY FAILURE REJECTS. No path here resolves to mean "not written" or
  * "could not read". A caller that must not act on a partial view branches on the
  * rejection, never on an empty result.
+ *
+ * @deprecated The legacy cross-user store. Declare a `shared` collection under
+ * `storage.collections` and use `app.storage.collection(name)`, which has counters,
+ * marks and authorship built in. This keeps working, unchanged, until the apps that
+ * use it have moved.
  */
 export interface SharedStorageClient {
     /**

package/dist/storage/index.d.ts

@@ -57,7 +57,13 @@ export interface StorageQuota {
  * not act on a partial view branches on the rejection, never on an empty result.
  */
 export interface StorageClient {
-    /** The value, or `null` when the key is unset. Rejects on any refusal. */
+    /**
+     * The value, or `null` when the key is unset. Rejects on any refusal.
+     *
+     * @deprecated The legacy per-viewer key/value store. Declare a `private`
+     * collection under `storage.collections` and use `app.storage.collection(name)`;
+     * this keeps working, unchanged, until the apps that use it have moved.
+     */
     get<T = unknown>(key: string, opts?: StorageCallOptions): Promise<T | null>;
     /**
      * Upsert one key. Resolves only when the write landed.
@@ -68,23 +74,43 @@ export interface StorageClient {
      *
      * A value of `undefined` is stored as `null`: it does not survive JSON, and
      * the server writes `null` for an absent value rather than refusing.
+     *
+     * @deprecated The legacy per-viewer key/value store. Declare a `private`
+     * collection under `storage.collections` and use `app.storage.collection(name)`;
+     * this keeps working, unchanged, until the apps that use it have moved.
      */
     set<T = unknown>(key: string, value: T, opts?: StorageCallOptions): Promise<{
         ok: true;
         sizeBytes: number;
     }>;
-    /** Idempotent. `deleted: false` means the key was already absent — a success. */
+    /**
+     * Idempotent. `deleted: false` means the key was already absent — a success.
+     *
+     * @deprecated The legacy per-viewer key/value store. Declare a `private`
+     * collection under `storage.collections` and use `app.storage.collection(name)`;
+     * this keeps working, unchanged, until the apps that use it have moved.
+     */
     delete(key: string, opts?: StorageCallOptions): Promise<{
         ok: true;
         deleted: boolean;
     }>;
-    /** One page of keys, ordered by key ascending. Values are not returned. */
+    /**
+     * One page of keys, ordered by key ascending. Values are not returned.
+     *
+     * @deprecated The legacy per-viewer key/value store. Declare a `private`
+     * collection under `storage.collections` and use `app.storage.collection(name)`;
+     * this keeps working, unchanged, until the apps that use it have moved.
+     */
     list(query?: StorageListQuery, opts?: StorageCallOptions): Promise<StorageListResult>;
     /**
      * This viewer's usage against this viewer's caps, in the stored unit.
      *
      * It reports neither the key-length cap nor the per-value cap, so a write
      * that fits the numbers here can still be refused.
+     *
+     * @deprecated The legacy per-viewer key/value store. Declare a `private`
+     * collection under `storage.collections` and use `app.storage.collection(name)`;
+     * this keeps working, unchanged, until the apps that use it have moved.
      */
     getQuota(opts?: StorageCallOptions): Promise<StorageQuota>;
 }

package/dist/testing.d.ts

@@ -1,6 +1,8 @@
 import { type BlockSnapshot, type BlockTransport } from './core/transport.js';
 import { type BridgeFailureCode } from './core/errors.js';
 export { __resetTransport } from './core/get-transport.js';
+export { createFakeStorage, FAKE_STORAGE_MODERATION } from './doc-store/fake.js';
+export type { FakeModerationVerdict, FakeStorage, FakeStorageCall, FakeStorageCaller, FakeStorageOptions, FakeStorageSession, FakeStorageViewer, } from './doc-store/fake.js';
 export interface FakeTransport extends BlockTransport {
     /** Every request sent, in order. */
     readonly sent: {

package/dist/testing.js

@@ -1,6 +1,7 @@
 import { EMPTY_SNAPSHOT } from './core/transport.js';
 import { BridgeError } from './core/errors.js';
 export { __resetTransport } from './core/get-transport.js';
+export { createFakeStorage, FAKE_STORAGE_MODERATION } from './doc-store/fake.js';
 /**
  * An in-memory `BlockTransport` for testing a service against a scripted host.
  * Replaces driving a full mock host through `postMessage` when the thing under

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.13.1";
+export declare const VERSION = "0.14.1";

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.13.1";
+export const VERSION = "0.14.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "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",