@civitai/app-sdk 0.70.1 → 0.72.0

package/README.md

@@ -191,7 +191,9 @@ own key:
   `$type` cap, a 256 KB `input` cap, and the spend reservation. **Unlike the inline arm, `maxBuzz`
   is not always the timeout here**: on both `estimate` and `submit` the host asks the orchestrator
   for a `whatif` quote of the step. **Quoted** → it reserves `max(maxBuzz, quote)`, gated against
-  the token's per-call budget (`token.buzzBudget`, capped at 1000 on a production token — so the
+  the token's per-call budget (`token.buzzBudget`: a platform default when the manifest declares
+  none, clamped to a platform cap — current values in the
+  [limits table](https://developer.civitai.com/apps/guide/text-to-image.md#limits-table) — so the
   reservation can exceed the 1–250 `maxBuzz` range), and stamps **no** step timeout.
   **Unquoted** → `maxBuzz` is both the reservation and the step timeout in seconds; the timeout
   bounds wall-clock time, and spend only for a step billed by compute time — a step priced per

package/dist/blocks/index.d.ts

@@ -109,7 +109,7 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } from './types.js';
-export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockImagePickerSource, BlockPickedImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockEstimateBatchAggregate, BlockModelSubstitution, ModelSubstitutionReason, KnownBlockWorkflowErrorCode, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowBodyWorkflow, WorkflowBodyWorkflowStep, WorkflowStepRef, WithWorkflowStepRefs, BlockWorkflowStepSnapshot, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, WorkflowBodyTraining, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AiToolkitPlainEcosystem, AiToolkitLrScheduler, AiToolkitOptimizerType, BlockTrainingQuote, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, BlockPrepareTrainingDatasetHostError, BlockRunTrainingHostError, BlockStepQuote, BlockModel3dOutput, BlockRunConfirmedStepHostError, } from './types.js';
+export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockStorageCollectionDeclaration, BlockStorageDeclaration, BlockStorageIndexes, BlockStorageIndexType, BlockStoragePrivateCollectionDeclaration, BlockStorageSharedCollectionDeclaration, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockImagePickerSource, BlockPickedImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockEstimateBatchAggregate, BlockModelSubstitution, ModelSubstitutionReason, KnownBlockWorkflowErrorCode, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowBodyWorkflow, WorkflowBodyWorkflowStep, WorkflowStepRef, WithWorkflowStepRefs, BlockWorkflowStepSnapshot, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, WorkflowBodyTraining, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AiToolkitPlainEcosystem, AiToolkitLrScheduler, AiToolkitOptimizerType, BlockTrainingQuote, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, BlockPrepareTrainingDatasetHostError, BlockRunTrainingHostError, BlockStepQuote, BlockModel3dOutput, BlockRunConfirmedStepHostError, } from './types.js';
 /** Host bound for the App Blocks `kind: 'workflow'` body — see `WorkflowBodyWorkflow`. */
 export { BLOCK_WORKFLOW_MAX_STEPS, BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS } from './types.js';
 /**

package/dist/blocks/messages.d.ts

@@ -938,6 +938,25 @@ export type BlockToParentMessage = {
         multiple?: {
             max: number;
         };
+        /**
+         * Offer only images in a published, non-`Private` post: `true`
+         * narrows the `'posted'` library to those. It does not filter by
+         * rating or by any other post setting. The `'generated'` library is
+         * unaffected. OMIT it (or `false`) for today's behaviour, which also
+         * offers images in a `Private` post. Send a boolean or nothing: the
+         * host refuses any other value with `{ requestId, error }`.
+         *
+         * Set it when the pick becomes PUBLIC-FACING, e.g. an App Store
+         * sub-listing card image (`imageId` on
+         * `POST /api/v1/blocks/sub-listings/upsert`, `app.subListings.upsert`
+         * in `@civitai/sdk`), which the store refuses for a non-public image.
+         * Leave it off when the pick is a private input (a generation source).
+         *
+         * 🔴 A HOST THAT PREDATES THIS FIELD IGNORES IT and still offers
+         * `Private`-post images, so an app setting it must still handle the
+         * store's `image_not_public` refusal.
+         */
+        publicOnly?: boolean;
     };
 } | {
     type: 'SET_USER_CHECKPOINT';

package/dist/blocks/scopes.d.ts

@@ -20,6 +20,8 @@ export declare const BLOCK_SCOPES: {
     readonly APPS_STORAGE_WRITE: "apps:storage:write";
     readonly APPS_STORAGE_SHARED_READ: "apps:storage:shared:read";
     readonly APPS_STORAGE_SHARED_WRITE: "apps:storage:shared:write";
+    readonly APPS_STORAGE: "apps:storage";
+    readonly APPS_STORAGE_PUBLISH: "apps:storage:publish";
     readonly COLLECTIONS_READ_SELF: "collections:read:self";
     readonly COLLECTIONS_WRITE_SELF: "collections:write:self";
     readonly COLLECTIONS_READ_PRIVATE: "collections:read:private";
@@ -31,8 +33,9 @@ export declare const BLOCK_SCOPES: {
 export type BlockScopeKey = keyof typeof BLOCK_SCOPES;
 export type BlockScope = (typeof BLOCK_SCOPES)[BlockScopeKey];
 /**
- * Format helper for the block-scope shape — 3 OR 4 colon-separated lowercase
- * segments (`domain:verb:target` or `domain:area:verb:target`).
+ * Format helper for the block-scope shape — 2, 3 OR 4 colon-separated
+ * lowercase segments (`domain:area`, `domain:verb:target` or
+ * `domain:area:verb:target`).
  *
  * NOTE: this regex is **not** the authoritative validity contract. The
  * canonical manifest schema (https://civitai.com/schemas/app-block/v1.json)
@@ -48,6 +51,8 @@ export type BlockScope = (typeof BLOCK_SCOPES)[BlockScopeKey];
  * cross-user datastore); `apps:store:items:write` is the same shape. The SDK
  * now tracks the server's 4-segment scopes directly, so this is no longer a coordinated-major-bump situation — the
  * pattern just widened to accept the shapes the canonical enum already lists.
+ * It widened again, at the other end, for the 2-segment `apps:storage`
+ * (the document store's base scope).
  */
 export declare const BLOCK_SCOPE_PATTERN: RegExp;
 /**

package/dist/blocks/scopes.js

@@ -27,6 +27,18 @@ export const BLOCK_SCOPES = {
     // 4-segment (as is `apps:store:items:write`) — see BLOCK_SCOPE_PATTERN below.
     APPS_STORAGE_SHARED_READ: 'apps:storage:shared:read',
     APPS_STORAGE_SHARED_WRITE: 'apps:storage:shared:write',
+    // apps:storage / apps:storage:publish — the DOCUMENT STORE, declared per
+    // collection in the manifest's `storage` block, that succeeds the four
+    // scopes above (which stay live until apps migrate). Same no-OAuth-bit
+    // posture. `apps:storage` covers reads, the viewer's private collections,
+    // marks and counters, and is CONSENT-EXEMPT; any manifest declaring a
+    // collection must request it. `apps:storage:publish` writes documents in a
+    // SHARED collection under the viewer's identity — SENSITIVE (needs a
+    // `scopeJustifications` entry) and CONSENT-GATED. `apps:storage` is the one
+    // 2-segment scope — see BLOCK_SCOPE_PATTERN below. Server source:
+    // civitai/civitai `src/shared/constants/block-scope.constants.ts`.
+    APPS_STORAGE: 'apps:storage',
+    APPS_STORAGE_PUBLISH: 'apps:storage:publish',
     // collections:* — the App Blocks Collections surface. These have no OAuth bit
     // (they never touch the user's civitai resources via the OAuth surface); the
     // server gates them per-op server-side (collection visibility/ownership +
@@ -80,8 +92,9 @@ export const BLOCK_SCOPES = {
     APPS_STORE_ITEMS_WRITE: 'apps:store:items:write',
 };
 /**
- * Format helper for the block-scope shape — 3 OR 4 colon-separated lowercase
- * segments (`domain:verb:target` or `domain:area:verb:target`).
+ * Format helper for the block-scope shape — 2, 3 OR 4 colon-separated
+ * lowercase segments (`domain:area`, `domain:verb:target` or
+ * `domain:area:verb:target`).
  *
  * NOTE: this regex is **not** the authoritative validity contract. The
  * canonical manifest schema (https://civitai.com/schemas/app-block/v1.json)
@@ -97,8 +110,10 @@ export const BLOCK_SCOPES = {
  * cross-user datastore); `apps:store:items:write` is the same shape. The SDK
  * now tracks the server's 4-segment scopes directly, so this is no longer a coordinated-major-bump situation — the
  * pattern just widened to accept the shapes the canonical enum already lists.
+ * It widened again, at the other end, for the 2-segment `apps:storage`
+ * (the document store's base scope).
  */
-export const BLOCK_SCOPE_PATTERN = /^[a-z]+:[a-z]+:[a-z]+(?::[a-z]+)?$/;
+export const BLOCK_SCOPE_PATTERN = /^[a-z]+:[a-z]+(?::[a-z]+){0,2}$/;
 /**
  * Marketplace category taxonomy for the optional manifest `category` field —
  * the app's `/apps` store listing bucket. Mirrors `MARKETPLACE_CATEGORIES` in

package/dist/blocks/types.d.ts

@@ -304,6 +304,11 @@ export type BlockGenerationSourceImageInfo = BlockSourceImage;
  *
  * The request's `sources` narrows the picker to one of them; omitting it offers
  * both. Images only — neither library offers video through this picker.
+ *
+ * The request's `publicOnly: true` further narrows `'posted'` to images whose
+ * post is published and not `Private` (for a public-facing pick such as an App
+ * Store sub-listing card image); it does not change `'generated'`. A host that
+ * predates `publicOnly` ignores it.
  */
 export type BlockImagePickerSource = 'posted' | 'generated';
 /**
@@ -314,7 +319,8 @@ export type BlockImagePickerSource = 'posted' | 'generated';
  *
  * WHAT IS PICKABLE is decided by the host, never by the block:
  *  - `'posted'`: the viewer's own images that are in a published post, fully
- *    scanned, not flagged, and rated.
+ *    scanned, not flagged, and rated. A `Private` post counts as published
+ *    here unless the request set `publicOnly: true`, which leaves those out.
  *  - `'generated'`: the viewer's own succeeded generator outputs that carry a
  *    rating the host recognises.
  *  - Either way the image's rating has to be one the VIEWER'S OWN browsing
@@ -1305,9 +1311,12 @@ export type WorkflowBodyPassThroughStep = {
      *  - **Quoted** — the host reserves `max(maxBuzz, quote)` and stamps NO step
      *    timeout. That reservation can exceed 250: it is gated against the token's
      *    per-call budget (`token.buzzBudget` — the app's per-generation budget,
-     *    capped at 1000 when the host mints a production token), and a submit
-     *    whose reservation exceeds that budget comes back `failed` with an
-     *    `insufficient buzz budget` error before any Buzz is reserved.
+     *    i.e. `page.buzzBudgetPerGen` for a page app: a platform default when
+     *    nothing declares one, and clamped to a platform cap on every mint), and
+     *    a submit whose reservation exceeds that budget comes back `failed` with
+     *    an `insufficient buzz budget` error before any Buzz is reserved. The
+     *    current default and cap are in the pinned limits table,
+     *    https://developer.civitai.com/apps/guide/text-to-image.md#limits-table.
      *  - **Unquoted** (the orchestrator returned no price, or the quote could not
      *    be had) — the host reserves `maxBuzz` and stamps it as the step timeout,
      *    in seconds. `maxBuzz: 10` then buys a job that is KILLED after 10
@@ -2534,6 +2543,141 @@ export interface BlockAnalyticsDeclaration {
      */
     events?: Record<string, BlockAnalyticsEventDeclaration>;
 }
+/**
+ * The type of one storage index — see {@link BlockStorageIndexes}. A `string`
+ * index holds values of at most 128 bytes. Mirrors the canonical schema's
+ * `storage.collections.*.indexes.*` enum.
+ */
+export type BlockStorageIndexType = 'string' | 'number' | 'boolean' | 'time';
+/**
+ * A collection's `indexes`: fields of a document's `data` the app can filter and
+ * sort by, as a map of field PATH → {@link BlockStorageIndexType}. At most 4.
+ * A path is 1 to 3 segments joined by `.` (`status`, `datasetId`,
+ * `meta.round`), each a letter followed by up to 31 letters, digits or `_`; a
+ * field whose own name contains `.` cannot be indexed. Changing an index's
+ * type is not supported: remove it and add one under a new name.
+ *
+ * `key`, `createdAt` and `updatedAt` are built-in sort keys and cannot be index
+ * names — the canonical declares each as `false`, and they are typed `never`
+ * here so declaring one is a compile error. (That is also why the index
+ * signature admits `undefined`: TypeScript requires an optional property to be
+ * assignable to the signature.) Mirrors the canonical schema's
+ * `storage.collections.*.indexes`.
+ */
+export interface BlockStorageIndexes {
+    [path: string]: BlockStorageIndexType | undefined;
+    key?: never;
+    createdAt?: never;
+    updatedAt?: never;
+}
+/**
+ * A PRIVATE collection — a separate key space per viewer, read and written
+ * only by that viewer. Carries none of the shared-only fields (`write`,
+ * `counters`, `marks`, `showAuthor`, `dailyWritesPerAuthor`); the canonical
+ * forbids them here. See {@link BlockStorageSharedCollectionDeclaration} for
+ * the fields both kinds share.
+ */
+export interface BlockStoragePrivateCollectionDeclaration {
+    /** See {@link BlockStorageSharedCollectionDeclaration.kind}. */
+    kind?: 'docs' | 'log';
+    /** Cannot be changed later: declare a new collection instead. */
+    visibility: 'private';
+    /** See {@link BlockStorageIndexes}. */
+    indexes?: BlockStorageIndexes;
+    /** RESERVED — see {@link BlockStorageSharedCollectionDeclaration.ttlSeconds}. */
+    ttlSeconds?: number;
+    /** RESERVED — see {@link BlockStorageSharedCollectionDeclaration.maxEntries}. */
+    maxEntries?: number;
+}
+/**
+ * A SHARED collection — one key space for the whole app, read by every viewer
+ * of the app, signed-out viewers included. `write` is REQUIRED on it.
+ */
+export interface BlockStorageSharedCollectionDeclaration {
+    /**
+     * `'docs'` (the default): documents with app-chosen or server-assigned keys
+     * that can be updated in place. `'log'`: append-only entries, trimmed to
+     * `maxEntries` per key space. RESERVED: civitai.com refuses `'log'` until log
+     * collections are enabled, so declare `'docs'` or omit it.
+     */
+    kind?: 'docs' | 'log';
+    /** Cannot be changed later: declare a new collection instead. */
+    visibility: 'shared';
+    /**
+     * Who may create, update and delete documents.
+     *
+     * - `'own'` — eligible signed-in viewers create documents; only a document's
+     *   author updates or deletes it.
+     * - `'none'` — nobody writes documents; viewers only increment the declared
+     *   `counters` and set the declared `marks`. Must declare at least one
+     *   counter or mark.
+     * - `'anyone'` — RESERVED (refused at submit until enabled): eligible
+     *   signed-in viewers update or delete any document.
+     * - `'owner'` — RESERVED (refused at submit until enabled): only the app
+     *   owner writes documents; viewers can still mark and count.
+     *
+     * `'own'` and `'anyone'` require the `apps:storage:publish` scope.
+     */
+    write: 'own' | 'anyone' | 'owner' | 'none';
+    /**
+     * Names of the atomic counters each document carries (for example `plays`).
+     * At most 8 distinct lowercase snake_case names (`^[a-z][a-z0-9_]{0,31}$`),
+     * never `report`, and never a name also used by a mark.
+     */
+    counters?: string[];
+    /**
+     * Names of the per-viewer marks a viewer can set on a document (for example
+     * `vote`), at most one of each per viewer per document. A reader sees each
+     * mark's count and whether THEY set it, never who else did. At most 8
+     * distinct lowercase snake_case names. `report` is built in on every shared
+     * collection and must NOT be declared.
+     */
+    marks?: string[];
+    /** See {@link BlockStorageIndexes}. */
+    indexes?: BlockStorageIndexes;
+    /**
+     * When true, readers see each viewer-authored document's author USERNAME.
+     * Default false. The numeric user id is never exposed either way.
+     */
+    showAuthor?: boolean;
+    /**
+     * RESERVED — refused at submit until expiring documents are enabled. The
+     * default document lifetime in seconds, 60 to 31536000 (provisional bounds).
+     */
+    ttlSeconds?: number;
+    /**
+     * RESERVED — log collections are refused at submit. For `kind: 'log'` only:
+     * the most entries kept per key space, 1 to 10000 (omitted means 10000).
+     */
+    maxEntries?: number;
+    /**
+     * RESERVED — refused at submit until per-collection write budgets are
+     * enabled. The per-viewer daily create/update budget, 1 to 1000, for a
+     * collection viewers write (`write` `'own'` or `'anyone'` only).
+     */
+    dailyWritesPerAuthor?: number;
+}
+/**
+ * One collection declaration — see {@link BlockManifestV1.storage}.
+ * Discriminated on `visibility`, mirroring the canonical's `if visibility is
+ * "shared" then write is required, else no shared-only field` rule. Mirrors the
+ * canonical schema's `storage.collections.*`.
+ */
+export type BlockStorageCollectionDeclaration = BlockStoragePrivateCollectionDeclaration | BlockStorageSharedCollectionDeclaration;
+/**
+ * The manifest's `storage` object — see {@link BlockManifestV1.storage}.
+ * Mirrors the canonical schema's `storage`; no other key is allowed.
+ */
+export interface BlockStorageDeclaration {
+    /**
+     * Collection name → declaration. At least 1 and at most 16 collections. A
+     * collection name is lowercase snake_case: a letter, then up to 31 of `a-z`,
+     * `0-9` or `_` (`^[a-z][a-z0-9_]{0,31}$`). Renaming a collection, or changing
+     * its visibility, is a NEW collection: the old one's documents are not
+     * carried over.
+     */
+    collections: Record<string, BlockStorageCollectionDeclaration>;
+}
 /**
  * One entry of a manifest's `goods[]`. Mirrors the canonical schema exactly;
  * `id`, `title` and `priceBuzz` are required there and so are they here.
@@ -2673,6 +2817,26 @@ export interface BlockManifestV1 {
      * canonical schema's `analytics`.
      */
     analytics?: BlockAnalyticsDeclaration;
+    /**
+     * Optional APP STORAGE declaration — every collection of JSON documents the
+     * app keeps, and who may read and write each one. Manifest-governed and
+     * REVIEW-GATED: a collection not declared here does not exist at runtime.
+     *
+     * Declaring any collection requires the `apps:storage` scope; a shared
+     * collection viewers write (`write` `'own'` or `'anyone'`) also requires the
+     * sensitive, consent-gated `apps:storage:publish` scope with a
+     * `scopeJustifications` entry; and requesting either scope with nothing here
+     * for it to reach is rejected. Those couplings, and the RESERVED features
+     * (`kind: 'log'`, `ttlSeconds`, `dailyWritesPerAuthor`, `write` `'anyone'` /
+     * `'owner'`), are enforced by the platform's manifest validator at submit,
+     * not by `defineBlock` — see `KNOWN_GAPS['storage-server-only-rules']`.
+     *
+     * This TYPES the declaration only. Storage is not yet enabled on civitai.com
+     * (its routes answer `503 storage_disabled`); the published schema and the Go
+     * CLI already accept the field. Kept in lockstep with the canonical schema's
+     * `storage`.
+     */
+    storage?: BlockStorageDeclaration;
     /** Optional; the canonical declares no required sub-field. */
     iframe?: ManifestIframe;
     /** Full-page surface descriptor (W10). */

package/dist/index.d.ts

@@ -25,11 +25,11 @@
  *
  *  - **`./blocks`** — importing it RUNS `./safe-storage` for its side effect
  *    (repairing `localStorage`/`sessionStorage` at an opaque origin). Folding
- *    174 symbols and that side effect into the root would make every OAuth app
+ *    180 symbols and that side effect into the root would make every OAuth app
  *    that writes `import { exchangeCode } from '@civitai/app-sdk'` pay for the
  *    Civitai-Apps contract it does not use. Blocks and OAuth apps are disjoint
  *    audiences; see this package's README.
- *    🔴 That 174 is ASSERTED, not merely quoted — by
+ *    🔴 That 180 is ASSERTED, not merely quoted — by
  *    `packages/civitai-app-sdk/test/export-surface.test.ts`, which pins
  *    `surface.get('./blocks').size`. It said 119 here against a real 125 until
  *    2026-10-04, because the existing checks pin the root as an exact union and

package/dist/index.js

@@ -25,11 +25,11 @@
  *
  *  - **`./blocks`** — importing it RUNS `./safe-storage` for its side effect
  *    (repairing `localStorage`/`sessionStorage` at an opaque origin). Folding
- *    174 symbols and that side effect into the root would make every OAuth app
+ *    180 symbols and that side effect into the root would make every OAuth app
  *    that writes `import { exchangeCode } from '@civitai/app-sdk'` pay for the
  *    Civitai-Apps contract it does not use. Blocks and OAuth apps are disjoint
  *    audiences; see this package's README.
- *    🔴 That 174 is ASSERTED, not merely quoted — by
+ *    🔴 That 180 is ASSERTED, not merely quoted — by
  *    `packages/civitai-app-sdk/test/export-surface.test.ts`, which pins
  *    `surface.get('./blocks').size`. It said 119 here against a real 125 until
  *    2026-10-04, because the existing checks pin the root as an exact union and

package/dist/manifest/defineBlock.d.ts

@@ -96,6 +96,7 @@ export declare const KNOWN_GAPS: {
     readonly 'review-granted-scope-subset': "Which of the requested `scopes` review actually grants has no schema expression at all.";
     readonly 'slotId-registry': string;
     readonly 'settings-meta-schema-not-vendored': string;
+    readonly 'storage-server-only-rules': string;
     readonly 'format-uri-not-enforced': string;
 };
 /** The canonical schema object, parsed once. Exported for tests and tooling. */

package/dist/manifest/defineBlock.js

@@ -143,6 +143,13 @@ export const KNOWN_GAPS = {
     'settings-meta-schema-not-vendored': "civitai/civitai's `manifest-settings.meta.schema.ts` is not published at a URL and not " +
         'vendored here, so `settings` is the one surface still checked by a hand-written mirror. ' +
         'See SCHEMA_DIVERGENCES.settings.',
+    'storage-server-only-rules': 'The canonical `storage` description states rules it does not encode: declaring any ' +
+        'collection requires the `apps:storage` scope, a shared collection viewers write (`write` ' +
+        '"own" or "anyone") also requires `apps:storage:publish`, requesting either scope with no ' +
+        'collection for it to reach is rejected, a counter may not share a name with a mark, and the ' +
+        'RESERVED features (`kind` "log", `ttlSeconds`, `dailyWritesPerAuthor`, `write` "anyone" / ' +
+        '"owner") validate offline and are refused at submit. Ajv enforces the structural rules ' +
+        'exactly; these are server-side.',
     'format-uri-not-enforced': '`assetBundleUrl` carries `format: "uri"` in addition to `pattern: "^https://"`. Ajv ignores ' +
         'unknown formats unless `ajv-formats` is installed, which would be a second optional peer for ' +
         'one field whose pattern is already enforced. The pattern IS enforced; the `uri` format is ' +

package/dist/manifest/index.d.ts

@@ -15,5 +15,5 @@
 export { defineBlock, SCHEMA_DIVERGENCES, KNOWN_GAPS, loadCanonicalSchema } from './defineBlock.js';
 export type { DefineBlockConfig } from './defineBlock.js';
 export { BlockManifestError } from '../blocks/manifestError.js';
-export type { BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, } from '../blocks/types.js';
+export type { BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, BlockStorageCollectionDeclaration, BlockStorageDeclaration, BlockStorageIndexes, BlockStorageIndexType, BlockStoragePrivateCollectionDeclaration, BlockStorageSharedCollectionDeclaration, } from '../blocks/types.js';
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/app-sdk",
-  "version": "0.70.1",
+  "version": "0.72.0",
   "description": "OAuth + PKCE, encrypted-cookie sessions, scopes, and orchestrator helpers for building third-party Civitai apps.",
   "license": "MIT",
   "type": "module",

package/schemas/app-block/v1.json

@@ -72,7 +72,7 @@
     },
     "auth": {
       "type": "string",
-      "description": "Which credential the host hands the block: \"block-token\" (default when omitted) is the block-scoped JWT; \"oauth\" asks for an opaque OAuth access token for the block's own OauthClient, which ordinary /api/v1 routes accept as a viewer bearer. Minting it is gated on a server flag that is not generally enabled, and also requires a signed-in viewer and a declared \"user:read:self\" scope; when any of those is unmet the host hands back a block JWT instead of failing, so branch on the token kind the host reports rather than on this field. An OAuth token is refused by the postMessage bridge procedures, which verify a block JWT only, and a manifest declaring \"oauth\" alongside any \"apps:storage:*\" scope is rejected by manifest validation.",
+      "description": "Which credential the host hands the block: \"block-token\" (default when omitted) is the block-scoped JWT; \"oauth\" asks for an opaque OAuth access token for the block's own OauthClient, which ordinary /api/v1 routes accept as a viewer bearer. Minting it is gated on a server flag that is not generally enabled, and also requires a signed-in viewer and a declared \"user:read:self\" scope; when any of those is unmet the host hands back a block JWT instead of failing, so branch on the token kind the host reports rather than on this field. An OAuth token is refused by the postMessage bridge procedures, which verify a block JWT only, and a manifest declaring \"oauth\" alongside \"apps:storage\" or any \"apps:storage:*\" scope is rejected by manifest validation.",
       "enum": ["block-token", "oauth"]
     },
     "trustTier": {
@@ -96,6 +96,8 @@
           "apps:storage:write",
           "apps:storage:shared:read",
           "apps:storage:shared:write",
+          "apps:storage",
+          "apps:storage:publish",
           "collections:read:self",
           "collections:write:self",
           "collections:read:private",
@@ -108,7 +110,7 @@
     },
     "scopeJustifications": {
       "type": "object",
-      "description": "Per-scope justification: a map of scope-id → free-text rationale explaining WHY the app needs that permission, shown to the moderator during review. REQUIRED for SENSITIVE scopes — any declared scope that can spend or read the viewer's Buzz, read the viewer's private data, or write data other users see (e.g. `ai:write:budgeted`, `social:tip:self`, `goods:purchase:self`, `buzz:read:self`, `collections:read:private`, `apps:storage:shared:write`, `posts:write:self`, `apps:store:items:write`) MUST carry a non-empty justification here, or the manifest is rejected at submit time. OPTIONAL for non-sensitive scopes — omit those and the manifest stays valid. Every key MUST be a scope also present in `scopes` (justifications for scopes you don't request are rejected). Each value is a non-empty string of at most 500 characters. The requirement is enforced imperatively by the manifest validator (not expressed as JSON-Schema conditionals here). NOTE: the justification captures the developer's STATED rationale only; the platform does not verify the truth of the claims.",
+      "description": "Per-scope justification: a map of scope-id → free-text rationale explaining WHY the app needs that permission, shown to the moderator during review. REQUIRED for SENSITIVE scopes — any declared scope that can spend or read the viewer's Buzz, read the viewer's private data, or write data other users see (e.g. `ai:write:budgeted`, `social:tip:self`, `goods:purchase:self`, `buzz:read:self`, `collections:read:private`, `apps:storage:shared:write`, `apps:storage:publish`, `posts:write:self`, `apps:store:items:write`) MUST carry a non-empty justification here, or the manifest is rejected at submit time. OPTIONAL for non-sensitive scopes — omit those and the manifest stays valid. Every key MUST be a scope also present in `scopes` (justifications for scopes you don't request are rejected). Each value is a non-empty string of at most 500 characters. The requirement is enforced imperatively by the manifest validator (not expressed as JSON-Schema conditionals here). NOTE: the justification captures the developer's STATED rationale only; the platform does not verify the truth of the claims.",
       "additionalProperties": {
         "type": "string",
         "minLength": 1,
@@ -219,7 +221,7 @@
         },
         "buzzBudgetPerGen": {
           "type": "integer",
-          "description": "Optional per-generation Buzz SAFETY CEILING for `ai:write:budgeted` tokens — the most a SINGLE generation this app requests is allowed to cost. It is a ceiling against a malicious or compromised app draining the viewer's Buzz, NOT a cost forecast: size it WELL ABOVE your worst-case generation (a good rule of thumb is several times your expected cost — e.g. 1000 when a run costs ~100), never at your estimate. Setting it to an estimate is the common mistake. The server re-prices every submit and compares that real price against this budget BEFORE anything runs, so a generation that comes in over budget is REJECTED outright with `insufficient buzz budget` — no workflow is created and no Buzz is spent, but the user gets nothing, and it stays broken for EVERY user until you ship a new manifest version and it is re-approved. So any upward drift in real cost (more steps, a bigger resolution, a pricier model or recipe, a colder cache) turns a budget sized to today's estimate into a hard outage. Positive integer. Omit it and the token is minted with a 10 Buzz default, which is below almost any real generation. Server-clamped to the platform per-gen cap (1000 today), so a generous value is safe. This bounds ONE generation only — cumulative spend is separately capped per viewer per day and per app, so a high per-gen ceiling does not widen total exposure.",
+          "description": "Optional per-generation Buzz SAFETY CEILING for `ai:write:budgeted` tokens — the most a SINGLE generation this app requests is allowed to cost. It is a ceiling against a malicious or compromised app draining the viewer's Buzz, NOT a cost forecast: size it WELL ABOVE your worst-case generation (a good rule of thumb is several times your expected cost — e.g. 1000 when a run costs ~100), never at your estimate. Setting it to an estimate is the common mistake. The server re-prices every submit and compares that real price against this budget BEFORE anything runs, so a generation that comes in over budget is REJECTED outright with `insufficient buzz budget` — no workflow is created and no Buzz is spent, but the user gets nothing, and it stays broken for EVERY user until you ship a new manifest version and it is re-approved. So any upward drift in real cost (more steps, a bigger resolution, a pricier model or recipe, a colder cache) turns a budget sized to today's estimate into a hard outage. Positive integer. Omit it and the token is minted with the platform default budget. Server-clamped to the platform per-call cap, so a generous value is safe. The current default and cap are listed in the App Blocks developer docs (https://developer.civitai.com/apps). This bounds ONE generation only — cumulative spend is separately capped per viewer per day and per app, so a high per-gen ceiling does not widen total exposure.",
           "exclusiveMinimum": 0
         }
       }
@@ -373,6 +375,154 @@
         }
       }
     },
+    "storage": {
+      "type": "object",
+      "description": "Optional APP STORAGE declaration — every collection of JSON documents your app keeps, and who may read and write each one. Manifest-governed and REVIEW-GATED: a collection that is not declared here does not exist at runtime, and the moderator sees each collection's visibility, write policy, counters, marks and indexes. Declaring any collection also requires the `apps:storage` scope; declaring a shared collection that viewers write (`write` of \"own\" or \"anyone\") also requires the sensitive, consent-gated `apps:storage:publish` scope with a `scopeJustifications` entry; and requesting either scope with nothing here for it to reach is rejected. This schema describes the WHOLE declaration, including features the platform does not accept yet: today the server's manifest validation refuses `kind` \"log\", `ttlSeconds`, `dailyWritesPerAuthor`, `write` \"anyone\" and `write` \"owner\" with a message saying they are not available yet, so those validate offline and are rejected at submit. Kept in lockstep with src/shared/constants/block-storage.constants.ts (a drift-guard test enforces equality); the imperative validator in that module is authoritative.",
+      "additionalProperties": false,
+      "required": ["collections"],
+      "properties": {
+        "collections": {
+          "type": "object",
+          "description": "Map of collection name → declaration. At least 1 and at most 16 collections. A collection name is lowercase snake_case: a letter, then up to 31 of a-z, 0-9 or _. Renaming a collection, or changing its visibility, is a NEW collection: the old one's documents are not carried over.",
+          "minProperties": 1,
+          "maxProperties": 16,
+          "additionalProperties": false,
+          "patternProperties": {
+            "^[a-z][a-z0-9_]{0,31}$": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["visibility"],
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "description": "\"docs\" (the default): documents with app-chosen or server-assigned keys that can be updated in place. \"log\": append-only entries with server-assigned keys, never updated, trimmed to `maxEntries` per key space. RESERVED: civitai.com refuses \"log\" until log collections are enabled, so declare \"docs\" (or omit `kind`).",
+                  "enum": ["docs", "log"]
+                },
+                "visibility": {
+                  "type": "string",
+                  "description": "Who can read the collection. \"private\": a separate key space per viewer — only that viewer reads or writes their documents. \"shared\": one key space for the whole app — every viewer of the app reads it, including signed-out viewers. Cannot be changed later: declare a new collection instead.",
+                  "enum": ["private", "shared"]
+                },
+                "write": {
+                  "type": "string",
+                  "description": "Shared collections only, and REQUIRED on them. Who may create, update and delete documents. \"own\": eligible signed-in viewers create documents, and only a document's author updates or deletes it. \"anyone\": eligible signed-in viewers may update or delete any document — RESERVED: civitai.com refuses \"anyone\" until it is enabled. \"none\": nobody creates, updates or deletes documents — viewers may only increment the declared `counters` and set the declared `marks`, and incrementing a counter on a document that does not exist creates an empty one authored by no viewer; a \"none\" collection must declare at least one counter or mark. \"owner\": only the app owner writes documents; viewers can still mark and count. Only \"own\" and \"anyone\" require the `apps:storage:publish` scope. RESERVED: civitai.com refuses \"owner\" until owner-written documents are enabled. Available today: \"own\" and \"none\".",
+                  "enum": ["own", "anyone", "owner", "none"]
+                },
+                "counters": {
+                  "type": "array",
+                  "description": "Shared collections only. Names of the counters each document carries — atomic tallies the app increments (for example plays). At most 8 distinct names, each lowercase snake_case: a letter, then up to 31 of a-z, 0-9 or _. A counter may not share a name with a mark on the same collection, or with the built-in `report` mark.",
+                  "maxItems": 8,
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9_]{0,31}$",
+                    "not": { "enum": ["report"] }
+                  }
+                },
+                "marks": {
+                  "type": "array",
+                  "description": "Shared collections only. Names of the per-user marks a viewer can set on a document (for example vote) — at most one of each per viewer per document. A reader sees each mark's count and whether THEY set it, never who else did. At most 8 distinct names, each lowercase snake_case: a letter, then up to 31 of a-z, 0-9 or _. `report` is built in on every shared collection and must NOT be declared. A mark may not share a name with a counter on the same collection.",
+                  "maxItems": 8,
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9_]{0,31}$",
+                    "not": { "enum": ["report"] }
+                  }
+                },
+                "indexes": {
+                  "type": "object",
+                  "description": "Fields of a document's `data` the app can filter and sort by, as a map of field PATH → type. A path is 1 to 3 segments joined by `.` (for example status, datasetId or meta.round), each a letter followed by up to 31 letters, digits or _; a field whose own name contains `.` cannot be indexed. At most 4 indexes. Types: \"string\" (values up to 128 bytes), \"number\", \"boolean\", \"time\". `key`, `createdAt` and `updatedAt` are built-in sort keys and cannot be index names. Changing an index's type is not supported: remove it and add one under a new name.",
+                  "maxProperties": 4,
+                  "additionalProperties": false,
+                  "properties": {
+                    "key": false,
+                    "createdAt": false,
+                    "updatedAt": false
+                  },
+                  "patternProperties": {
+                    "^[A-Za-z][A-Za-z0-9_]{0,31}(\\.[A-Za-z][A-Za-z0-9_]{0,31}){0,2}$": {
+                      "type": "string",
+                      "enum": ["string", "number", "boolean", "time"]
+                    }
+                  }
+                },
+                "showAuthor": {
+                  "type": "boolean",
+                  "description": "Shared collections only. When true, readers see each viewer-authored document's author USERNAME. Default false: readers learn only whether they wrote a document themselves. The numeric user id is never exposed either way."
+                },
+                "ttlSeconds": {
+                  "type": "integer",
+                  "description": "RESERVED — civitai.com refuses this field until expiring documents are enabled, so do not declare it yet. Intended meaning: the default lifetime of a document in this collection, in seconds. The bounds (60 to 31536000, i.e. one minute to 365 days) are provisional and may change before the field is enabled.",
+                  "minimum": 60,
+                  "maximum": 31536000
+                },
+                "maxEntries": {
+                  "type": "integer",
+                  "description": "RESERVED — log collections are refused by civitai.com until enabled, so this field cannot be used yet. Intended meaning, for `kind` \"log\" only: the most entries kept per key space, the oldest trimmed beyond it, from 1 to 10000 (omitted means 10000). The default is provisional and may change before log collections are enabled.",
+                  "minimum": 1,
+                  "maximum": 10000
+                },
+                "dailyWritesPerAuthor": {
+                  "type": "integer",
+                  "description": "RESERVED — civitai.com refuses this field until per-collection write budgets are enabled, so do not declare it yet. Intended meaning: for a shared collection that viewers write (`write` \"own\" or \"anyone\"; refused with \"owner\" or \"none\"), the per-viewer daily budget for creating and updating documents in this collection in place of the platform default, from 1 to 1000, shown to the moderator at review. The bounds are provisional and may change before the field is enabled.",
+                  "minimum": 1,
+                  "maximum": 1000
+                }
+              },
+              "allOf": [
+                {
+                  "$comment": "A shared collection must state its write policy; a private one carries none of the shared-only fields.",
+                  "if": {
+                    "required": ["visibility"],
+                    "properties": { "visibility": { "const": "shared" } }
+                  },
+                  "then": { "required": ["write"] },
+                  "else": {
+                    "properties": {
+                      "write": false,
+                      "counters": false,
+                      "marks": false,
+                      "showAuthor": false,
+                      "dailyWritesPerAuthor": false
+                    }
+                  }
+                },
+                {
+                  "$comment": "maxEntries belongs to log collections only (kind defaults to docs).",
+                  "if": {
+                    "required": ["kind"],
+                    "properties": { "kind": { "const": "log" } }
+                  },
+                  "else": { "properties": { "maxEntries": false } }
+                },
+                {
+                  "$comment": "No viewer authors documents in a write:\"owner\" or write:\"none\" collection, so it has no per-author budget.",
+                  "if": {
+                    "required": ["write"],
+                    "properties": { "write": { "enum": ["owner", "none"] } }
+                  },
+                  "then": { "properties": { "dailyWritesPerAuthor": false } }
+                },
+                {
+                  "$comment": "A write:\"none\" collection is written only through counters and marks, so it must declare at least one.",
+                  "if": {
+                    "required": ["write"],
+                    "properties": { "write": { "const": "none" } }
+                  },
+                  "then": {
+                    "anyOf": [
+                      { "required": ["counters"], "properties": { "counters": { "minItems": 1 } } },
+                      { "required": ["marks"], "properties": { "marks": { "minItems": 1 } } }
+                    ]
+                  }
+                }
+              ]
+            }
+          }
+        }
+      }
+    },
     "targets": {
       "type": "array",
       "description": "Model-page slot targets. Each target's slotId must be a known registered model slot (not the page slot). Optional for page-only apps.",