@civitai/app-sdk 0.72.0 → 0.74.0

package/dist/blocks/index.d.ts

@@ -28,6 +28,13 @@ export type { BlockScope, BlockScopeKey, BlockCategory } from './scopes.js';
 export { BrowsingLevel, SFW_LEVELS, NSFW_LEVELS, isSfwCeiling, isLevelAllowed, effectiveBrowsingCeiling, } from './browsingLevel.js';
 export type { BrowsingLevelKey, BrowsingLevelBit, ColorDomain } from './browsingLevel.js';
 export { APP_STORAGE_MAX_VALUE_BYTES, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, } from './appStorageLimits.js';
+/**
+ * App reactions (`SET_ENTITY_REACTION` / `GET_ENTITY_REACTIONS`, scope
+ * `social:react:self`). The vocabulary mirrors civitai's
+ * `block-reaction.constants.ts`; see `reactions.ts`.
+ */
+export { APP_REACTIONS, STORED_REACTIONS, REACTION_ENTITY_TYPES, REACTION_READ_MAX_IDS, REACT_TICKET_MAX_LENGTH, ENTITY_REACTION_ERROR_CODES, isEntityReactionErrorCode, isAppReaction, } from './reactions.js';
+export type { BlockAppReaction, BlockStoredReaction, BlockReactionEntityType, BlockEntityReactionErrorCode, BlockReactionCounts, BlockEntityReactionState, BlockEntityReactionResult, BlockEntityReactionsResult, } from './reactions.js';
 export { BLOCK_IDEMPOTENCY_KEY_REGEX, BLOCK_IDEMPOTENCY_KEY_MAX_LENGTH, isValidBlockIdempotencyKey, blockIdempotencyKeyRejection, } from './idempotency.js';
 /**
  * The `srcdoc` escape hatch for embedding one of your own bundled documents

package/dist/blocks/index.js

@@ -31,6 +31,12 @@ export { BlockManifestError } from './manifestError.js';
 export { BLOCK_SCOPES, BLOCK_SCOPE_PATTERN, BLOCK_CATEGORIES, BLOCK_TAGLINE_MAX_LENGTH, } from './scopes.js';
 export { BrowsingLevel, SFW_LEVELS, NSFW_LEVELS, isSfwCeiling, isLevelAllowed, effectiveBrowsingCeiling, } from './browsingLevel.js';
 export { APP_STORAGE_MAX_VALUE_BYTES, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, } from './appStorageLimits.js';
+/**
+ * App reactions (`SET_ENTITY_REACTION` / `GET_ENTITY_REACTIONS`, scope
+ * `social:react:self`). The vocabulary mirrors civitai's
+ * `block-reaction.constants.ts`; see `reactions.ts`.
+ */
+export { APP_REACTIONS, STORED_REACTIONS, REACTION_ENTITY_TYPES, REACTION_READ_MAX_IDS, REACT_TICKET_MAX_LENGTH, ENTITY_REACTION_ERROR_CODES, isEntityReactionErrorCode, isAppReaction, } from './reactions.js';
 export { BLOCK_IDEMPOTENCY_KEY_REGEX, BLOCK_IDEMPOTENCY_KEY_MAX_LENGTH, isValidBlockIdempotencyKey, blockIdempotencyKeyRejection, } from './idempotency.js';
 /**
  * The `srcdoc` escape hatch for embedding one of your own bundled documents

package/dist/blocks/messages.d.ts

@@ -9,6 +9,7 @@
  */
 import type { ColorDomain } from './browsingLevel.js';
 import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockImagePickerSource, BlockPickedImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockEstimateBatchAggregate, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult, BlockTrainingDatasetItem, BlockTrainingDatasetResult, WorkflowBodyTraining, WorkflowBodyPassThroughStep } from './types.js';
+import type { BlockAppReaction, BlockEntityReactionErrorCode, BlockEntityReactionResult, BlockEntityReactionsResult, BlockReactionEntityType } from './reactions.js';
 /**
  * Filter params for `GET_BUZZ_TRANSACTIONS`. All optional; the host validates
  * them server-side (they are NEVER trusted for auth — the account is self-bound
@@ -531,6 +532,20 @@ export type ParentToBlockMessage = {
         result?: BlockCollectionFollowResult;
         error?: BlockCollectionFollowErrorCode | string;
     };
+} | {
+    type: 'ENTITY_REACTION_RESULT';
+    payload: {
+        requestId: string;
+        result?: BlockEntityReactionResult;
+        error?: BlockEntityReactionErrorCode | string;
+    };
+} | {
+    type: 'ENTITY_REACTIONS_RESULT';
+    payload: {
+        requestId: string;
+        result?: BlockEntityReactionsResult;
+        error?: BlockEntityReactionErrorCode | string;
+    };
 } | {
     type: 'CANCEL_APP_WORKFLOW_RESULT';
     payload: {
@@ -1112,6 +1127,30 @@ export type BlockToParentMessage = {
         /** `true` ⇒ follow, `false` ⇒ unfollow. */
         follow: boolean;
     };
+} | {
+    type: 'SET_ENTITY_REACTION';
+    payload: {
+        requestId: string;
+        entityType: BlockReactionEntityType;
+        /** Positive integer. A numeric STRING is refused, never coerced. */
+        entityId: number;
+        /** One of `APP_REACTIONS`. `Dislike` is refused as `invalid-request`. */
+        reaction: BlockAppReaction;
+        /** `true` ⇒ the reaction exists afterwards; `false` ⇒ it does not. */
+        reacted: boolean;
+        /** 1 to `REACT_TICKET_MAX_LENGTH` characters. */
+        ticket?: string;
+    };
+} | {
+    type: 'GET_ENTITY_REACTIONS';
+    payload: {
+        requestId: string;
+        entityType: BlockReactionEntityType;
+        /** 1 to `REACTION_READ_MAX_IDS` positive integers. Duplicates are collapsed. */
+        ids: number[];
+        /** A ticket per id, keyed by the id as a string. */
+        tickets?: Record<string, string>;
+    };
 };
 export type BlockToParentMessageType = BlockToParentMessage['type'];
 /**
@@ -1155,7 +1194,7 @@ export type BlockToParentMessageType = BlockToParentMessage['type'];
  * it is a measurement, not an invariant, and civitai's own compile-time gate
  * (published SDK union ⊆ `keyof INVENTORY`) is what holds one direction of it.
  */
-export declare const BLOCK_TO_PARENT_MESSAGE_TYPES: readonly ["BLOCK_HELLO", "BLOCK_READY", "BLOCK_ERROR", "BLOCK_MESSAGE_REJECTED", "REQUEST_TOKEN", "RESIZE_IFRAME", "SUBMIT_WORKFLOW", "ESTIMATE_WORKFLOW", "ESTIMATE_WORKFLOW_BATCH", "POLL_WORKFLOW", "CANCEL_WORKFLOW", "OPEN_BUZZ_PURCHASE", "GET_BUZZ_BALANCE", "GET_VIEWER", "GET_BUZZ_TRANSACTIONS", "GET_BUZZ_ACCOUNTS", "GET_DAILY_COMPENSATION", "GET_WILDCARD_PACK", "QUERY_APP_WORKFLOWS", "PUBLISH_GENERATION_OUTPUTS", "CREATE_POST_FROM_APP", "PREPARE_TRAINING_DATASET", "RUN_TRAINING", "RUN_CONFIRMED_STEP", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_UPLOAD", "OPEN_IMAGE_PICKER", "SET_USER_CHECKPOINT", "NAVIGATE", "REQUEST_SIGN_IN", "REQUEST_CONSENT", "TRACK_EVENT", "APP_STORAGE_GET", "APP_STORAGE_SET", "APP_STORAGE_DELETE", "APP_STORAGE_LIST", "APP_STORAGE_QUOTA", "SHARED_LIST", "SHARED_GET_COUNT", "SHARED_GET_COUNTS", "SHARED_APPEND", "SHARED_VOTE", "SHARED_UNVOTE", "SHARED_WITHDRAW", "SHARED_UPDATE", "SHARED_GET", "SHARED_REPORT", "SAVE_IMAGE", "SET_COLLECTION_FOLLOW"];
+export declare const BLOCK_TO_PARENT_MESSAGE_TYPES: readonly ["BLOCK_HELLO", "BLOCK_READY", "BLOCK_ERROR", "BLOCK_MESSAGE_REJECTED", "REQUEST_TOKEN", "RESIZE_IFRAME", "SUBMIT_WORKFLOW", "ESTIMATE_WORKFLOW", "ESTIMATE_WORKFLOW_BATCH", "POLL_WORKFLOW", "CANCEL_WORKFLOW", "OPEN_BUZZ_PURCHASE", "GET_BUZZ_BALANCE", "GET_VIEWER", "GET_BUZZ_TRANSACTIONS", "GET_BUZZ_ACCOUNTS", "GET_DAILY_COMPENSATION", "GET_WILDCARD_PACK", "QUERY_APP_WORKFLOWS", "PUBLISH_GENERATION_OUTPUTS", "CREATE_POST_FROM_APP", "PREPARE_TRAINING_DATASET", "RUN_TRAINING", "RUN_CONFIRMED_STEP", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_UPLOAD", "OPEN_IMAGE_PICKER", "SET_USER_CHECKPOINT", "NAVIGATE", "REQUEST_SIGN_IN", "REQUEST_CONSENT", "TRACK_EVENT", "APP_STORAGE_GET", "APP_STORAGE_SET", "APP_STORAGE_DELETE", "APP_STORAGE_LIST", "APP_STORAGE_QUOTA", "SHARED_LIST", "SHARED_GET_COUNT", "SHARED_GET_COUNTS", "SHARED_APPEND", "SHARED_VOTE", "SHARED_UNVOTE", "SHARED_WITHDRAW", "SHARED_UPDATE", "SHARED_GET", "SHARED_REPORT", "SAVE_IMAGE", "SET_COLLECTION_FOLLOW", "SET_ENTITY_REACTION", "GET_ENTITY_REACTIONS"];
 /**
  * The bucket a message type falls into when the protocol does not declare it.
  *

package/dist/blocks/messages.js

@@ -101,6 +101,8 @@ export const BLOCK_TO_PARENT_MESSAGE_TYPES = [
     'SHARED_REPORT',
     'SAVE_IMAGE',
     'SET_COLLECTION_FOLLOW',
+    'SET_ENTITY_REACTION',
+    'GET_ENTITY_REACTIONS',
 ];
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const _messageTypesGate = true;

package/dist/blocks/reactions.d.ts

@@ -0,0 +1,126 @@
+/**
+ * App reactions — the block side of `SET_ENTITY_REACTION` / `GET_ENTITY_REACTIONS`
+ * (scope `social:react:self`, civitai/civitai#6144).
+ *
+ * A block may set, or read, the VIEWER'S reaction on an image a block endpoint
+ * served it. The host calls `blocks.setReactionFromApp` /
+ * `blocks.getReactionsForApp`, which run the SAME handler as the site's own
+ * reaction button: rewards, metrics and notifications are the site's. What the
+ * app path adds is an audit row per change, a provenance ticket per image and a
+ * fail-closed kill switch.
+ *
+ * Every constant here MIRRORS civitai/civitai's
+ * `src/shared/constants/block-reaction.constants.ts`. The host's copy is the
+ * definition and this is the copy; `test/blocks/reactions.test.ts` pins each
+ * value literally, so a change on either side is a visible diff here.
+ *
+ * The scope is `BLOCK_SCOPES.SOCIAL_REACT_SELF`: consent-gated (a token carries
+ * it only after the viewer granted it) and sensitive (the manifest must justify
+ * it in `scopeJustifications`).
+ *
+ * Zero dependencies, like the rest of `./blocks`.
+ */
+/**
+ * The reactions an app may SET on an image.
+ *
+ * 🔴 `Dislike` IS DELIBERATELY ABSENT, and the host and the server both refuse
+ * it. Image stats hardcode the dislike count to 0, so a Dislike is invisible on
+ * the site, yet it is stored and still pays the reactor's encouragement reward.
+ */
+export declare const APP_REACTIONS: readonly ["Like", "Heart", "Laugh", "Cry"];
+export type BlockAppReaction = (typeof APP_REACTIONS)[number];
+/**
+ * Every reaction the site STORES. A viewer's existing reactions are reported in
+ * this wider set: a viewer who disliked an image on the site still holds that
+ * Dislike, and the read says so, even though an app may not set one.
+ */
+export declare const STORED_REACTIONS: readonly ["Like", "Dislike", "Laugh", "Cry", "Heart"];
+export type BlockStoredReaction = (typeof STORED_REACTIONS)[number];
+/** Entity types the host accepts. Image only in v1: nothing else is ticketed yet. */
+export declare const REACTION_ENTITY_TYPES: readonly ["image"];
+export type BlockReactionEntityType = (typeof REACTION_ENTITY_TYPES)[number];
+/** Most ids one `GET_ENTITY_REACTIONS` may carry. More is refused as `invalid-request`. */
+export declare const REACTION_READ_MAX_IDS = 100;
+/** Longest ticket the host accepts. A real one is about 60 characters. */
+export declare const REACT_TICKET_MAX_LENGTH = 256;
+/**
+ * The CLOSED set of errors `ENTITY_REACTION_RESULT` and `ENTITY_REACTIONS_RESULT`
+ * carry. Unlike the follow and post bridges, the host maps EVERY failure,
+ * its own refusals and every server error alike, onto one of these
+ * (`classifyEntityReactionError` in civitai's `reactionGate.ts`), so a block can
+ * branch on the code.
+ *
+ * - `invalid-request`: a malformed payload, or a reaction apps may not set
+ *   (`Dislike`). A block bug, not a viewer outcome.
+ * - `sign-in-required`: no session. Route it into `useRequestSignIn()`.
+ * - `review-mode`: the app is running in a moderator's review sandbox, where
+ *   the scope is never granted.
+ * - `not-ready`: the host has not finished the handshake, or holds no token yet.
+ *   Retry after `ready`.
+ * - `needs-consent`: the viewer has not granted `social:react:self`. Ask with
+ *   `useRequestConsent()`.
+ * - `entity-unavailable`: everything else. A missing, expired or foreign
+ *   ticket, an image the viewer may not react to, an owner who blocked the
+ *   viewer, the kill switch, or a network failure. Deliberately one code: the
+ *   block can retry or give up, and there is no truthful finer answer.
+ * - `rate-limited`: the viewer's reaction quota is spent. It is the SAME quota
+ *   the site's own reaction button draws on.
+ */
+export declare const ENTITY_REACTION_ERROR_CODES: readonly ["invalid-request", "sign-in-required", "review-mode", "not-ready", "needs-consent", "entity-unavailable", "rate-limited"];
+export type BlockEntityReactionErrorCode = (typeof ENTITY_REACTION_ERROR_CODES)[number];
+/** `true` when `value` is one of the closed {@link ENTITY_REACTION_ERROR_CODES}. */
+export declare function isEntityReactionErrorCode(value: unknown): value is BlockEntityReactionErrorCode;
+/** `true` when `value` is a reaction an app may set ({@link APP_REACTIONS}). */
+export declare function isAppReaction(value: unknown): value is BlockAppReaction;
+/** Reaction counts for one image, as the site's own feeds show them. */
+export type BlockReactionCounts = Record<BlockAppReaction, number>;
+/** One image's reaction state, as the read reports it. */
+export interface BlockEntityReactionState {
+    counts: BlockReactionCounts;
+    /** Every reaction the viewer holds on the image. A viewer may hold several. */
+    viewerReactions: BlockStoredReaction[];
+    /**
+     * `true` when the metric store could not answer for this image. `counts` are
+     * then zeros, and must not be shown as "nobody reacted".
+     */
+    statsUnknown: boolean;
+}
+/** The success payload of `ENTITY_REACTION_RESULT`. */
+export interface BlockEntityReactionResult extends BlockEntityReactionState {
+    entityType: BlockReactionEntityType;
+    entityId: number;
+    reaction: BlockAppReaction;
+    /**
+     * Whether the viewer holds `reaction` NOW, read on the primary after the
+     * write. 🔴 When this differs from the `reacted` the block asked for, a
+     * concurrent change (a double tap, the viewer's own click elsewhere) won and
+     * this request did not apply.
+     */
+    reacted: boolean;
+    /**
+     * Did THIS request write a change? `false` when the viewer was already in the
+     * requested state: nothing was toggled, so nothing was paid and no metric
+     * moved.
+     */
+    changed: boolean;
+    /**
+     * 🔴 `counts` CAN LAG `reacted`. They come from the metric store, which
+     * updates asynchronously, so right after a change they may not include it yet.
+     * `reacted` and `viewerReactions` are the truth.
+     */
+    counts: BlockReactionCounts;
+}
+/** The success payload of `ENTITY_REACTIONS_RESULT`. */
+export interface BlockEntityReactionsResult {
+    entityType: BlockReactionEntityType;
+    /** One entry per ticketed id, keyed by the id as a string (it crossed JSON). */
+    byId: Record<string, BlockEntityReactionState>;
+    /**
+     * Ids the host did not answer, because their ticket was missing, expired, or
+     * issued to another app or viewer. 🔴 Not "the viewer has not reacted": an
+     * unanswered id has NO known state, and a block must not offer a fresh
+     * reaction on the assumption that there is none.
+     */
+    unavailable: number[];
+}
+//# sourceMappingURL=reactions.d.ts.map

package/dist/blocks/reactions.js

@@ -0,0 +1,85 @@
+/**
+ * App reactions — the block side of `SET_ENTITY_REACTION` / `GET_ENTITY_REACTIONS`
+ * (scope `social:react:self`, civitai/civitai#6144).
+ *
+ * A block may set, or read, the VIEWER'S reaction on an image a block endpoint
+ * served it. The host calls `blocks.setReactionFromApp` /
+ * `blocks.getReactionsForApp`, which run the SAME handler as the site's own
+ * reaction button: rewards, metrics and notifications are the site's. What the
+ * app path adds is an audit row per change, a provenance ticket per image and a
+ * fail-closed kill switch.
+ *
+ * Every constant here MIRRORS civitai/civitai's
+ * `src/shared/constants/block-reaction.constants.ts`. The host's copy is the
+ * definition and this is the copy; `test/blocks/reactions.test.ts` pins each
+ * value literally, so a change on either side is a visible diff here.
+ *
+ * The scope is `BLOCK_SCOPES.SOCIAL_REACT_SELF`: consent-gated (a token carries
+ * it only after the viewer granted it) and sensitive (the manifest must justify
+ * it in `scopeJustifications`).
+ *
+ * Zero dependencies, like the rest of `./blocks`.
+ */
+/**
+ * The reactions an app may SET on an image.
+ *
+ * 🔴 `Dislike` IS DELIBERATELY ABSENT, and the host and the server both refuse
+ * it. Image stats hardcode the dislike count to 0, so a Dislike is invisible on
+ * the site, yet it is stored and still pays the reactor's encouragement reward.
+ */
+export const APP_REACTIONS = ['Like', 'Heart', 'Laugh', 'Cry'];
+/**
+ * Every reaction the site STORES. A viewer's existing reactions are reported in
+ * this wider set: a viewer who disliked an image on the site still holds that
+ * Dislike, and the read says so, even though an app may not set one.
+ */
+export const STORED_REACTIONS = ['Like', 'Dislike', 'Laugh', 'Cry', 'Heart'];
+/** Entity types the host accepts. Image only in v1: nothing else is ticketed yet. */
+export const REACTION_ENTITY_TYPES = ['image'];
+/** Most ids one `GET_ENTITY_REACTIONS` may carry. More is refused as `invalid-request`. */
+export const REACTION_READ_MAX_IDS = 100;
+/** Longest ticket the host accepts. A real one is about 60 characters. */
+export const REACT_TICKET_MAX_LENGTH = 256;
+/**
+ * The CLOSED set of errors `ENTITY_REACTION_RESULT` and `ENTITY_REACTIONS_RESULT`
+ * carry. Unlike the follow and post bridges, the host maps EVERY failure,
+ * its own refusals and every server error alike, onto one of these
+ * (`classifyEntityReactionError` in civitai's `reactionGate.ts`), so a block can
+ * branch on the code.
+ *
+ * - `invalid-request`: a malformed payload, or a reaction apps may not set
+ *   (`Dislike`). A block bug, not a viewer outcome.
+ * - `sign-in-required`: no session. Route it into `useRequestSignIn()`.
+ * - `review-mode`: the app is running in a moderator's review sandbox, where
+ *   the scope is never granted.
+ * - `not-ready`: the host has not finished the handshake, or holds no token yet.
+ *   Retry after `ready`.
+ * - `needs-consent`: the viewer has not granted `social:react:self`. Ask with
+ *   `useRequestConsent()`.
+ * - `entity-unavailable`: everything else. A missing, expired or foreign
+ *   ticket, an image the viewer may not react to, an owner who blocked the
+ *   viewer, the kill switch, or a network failure. Deliberately one code: the
+ *   block can retry or give up, and there is no truthful finer answer.
+ * - `rate-limited`: the viewer's reaction quota is spent. It is the SAME quota
+ *   the site's own reaction button draws on.
+ */
+export const ENTITY_REACTION_ERROR_CODES = [
+    'invalid-request',
+    'sign-in-required',
+    'review-mode',
+    'not-ready',
+    'needs-consent',
+    'entity-unavailable',
+    'rate-limited',
+];
+const ERROR_CODE_SET = new Set(ENTITY_REACTION_ERROR_CODES);
+const APP_REACTION_SET = new Set(APP_REACTIONS);
+/** `true` when `value` is one of the closed {@link ENTITY_REACTION_ERROR_CODES}. */
+export function isEntityReactionErrorCode(value) {
+    return typeof value === 'string' && ERROR_CODE_SET.has(value);
+}
+/** `true` when `value` is a reaction an app may set ({@link APP_REACTIONS}). */
+export function isAppReaction(value) {
+    return typeof value === 'string' && APP_REACTION_SET.has(value);
+}
+//# sourceMappingURL=reactions.js.map

package/dist/blocks/scopes.d.ts

@@ -29,6 +29,7 @@ export declare const BLOCK_SCOPES: {
     readonly GOODS_READ_SELF: "goods:read:self";
     readonly GOODS_PURCHASE_SELF: "goods:purchase:self";
     readonly APPS_STORE_ITEMS_WRITE: "apps:store:items:write";
+    readonly SOCIAL_REACT_SELF: "social:react:self";
 };
 export type BlockScopeKey = keyof typeof BLOCK_SCOPES;
 export type BlockScope = (typeof BLOCK_SCOPES)[BlockScopeKey];

package/dist/blocks/scopes.js

@@ -90,6 +90,14 @@ export const BLOCK_SCOPES = {
     // Requires a signed-in (non-anonymous) subject. 4-segment, like the shared
     // storage scopes — see BLOCK_SCOPE_PATTERN below.
     APPS_STORE_ITEMS_WRITE: 'apps:store:items:write',
+    // social:react:self — set the VIEWER'S reaction on an image a block endpoint
+    // served the app (civitai/civitai#6144). SENSITIVE (a public, reward-paying
+    // reaction under the viewer's name, so a declaring manifest MUST carry a
+    // `scopeJustifications` entry) and CONSENT-GATED. The bridge is
+    // SET_ENTITY_REACTION / GET_ENTITY_REACTIONS (see `reactions.ts`), and
+    // `useReactions` in `@civitai/blocks-react` drives it. The server gates it
+    // behind a fail-closed flag as well as the grant.
+    SOCIAL_REACT_SELF: 'social:react:self',
 };
 /**
  * Format helper for the block-scope shape — 2, 3 OR 4 colon-separated

package/dist/blocks/types.d.ts

@@ -2573,7 +2573,8 @@ export interface BlockStorageIndexes {
 /**
  * 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
+ * `counters`, `marks`, `showAuthor`, `dailyWritesPerAuthor`,
+ * `ownedModelVersions`); the canonical
  * forbids them here. See {@link BlockStorageSharedCollectionDeclaration} for
  * the fields both kinds share.
  */
@@ -2656,6 +2657,32 @@ export interface BlockStorageSharedCollectionDeclaration {
      * collection viewers write (`write` `'own'` or `'anyone'` only).
      */
     dailyWritesPerAuthor?: number;
+    /**
+     * `write` `'own'` collections only — the canonical refuses it under
+     * `'anyone'`, `'owner'` and `'none'`, and on private collections. Fields of a
+     * document's `data` that, when present, must hold the id of a Civitai model
+     * version owned by the viewer writing the document — for example
+     * `['/workflow/modelVersionId']` for a collection where viewers publish their
+     * own workflows.
+     *
+     * 1 to 4 distinct pointers, each 1 to 4 segments of `/` then a letter or `_`
+     * followed by up to 63 letters, digits or `_` (pattern
+     * `^(/[A-Za-z_][A-Za-z0-9_]{0,63}){1,4}$`). A pointer names one field of
+     * nested objects: it never indexes into an array, and a step through an
+     * array or any other non-object finds nothing.
+     *
+     * On every create and update the server resolves each pointer in the new
+     * `data`. An absent field is allowed. A present one must be a positive
+     * integer naming a model version whose model the writer owns; anything else
+     * — someone else's version, a missing or deleted one, a value that is not a
+     * positive integer — is refused 403 `resource_not_owned`, with
+     * `details.pointer` naming the field, before moderation and before any
+     * write budget is spent. If the ownership lookup itself fails, the write is
+     * refused 503 `service_unavailable` (retryable). Ownership is checked only
+     * when a document is written: documents already stored keep the id if the
+     * model later changes hands or is deleted.
+     */
+    ownedModelVersions?: string[];
 }
 /**
  * One collection declaration — see {@link BlockManifestV1.storage}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/app-sdk",
-  "version": "0.72.0",
+  "version": "0.74.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

@@ -104,13 +104,14 @@
           "posts:write:self",
           "goods:read:self",
           "goods:purchase:self",
-          "apps:store:items:write"
+          "apps:store:items:write",
+          "social:react:self"
         ]
       }
     },
     "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`, `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.",
+      "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`, `social:react:self`) 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,
@@ -468,6 +469,17 @@
                   "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
+                },
+                "ownedModelVersions": {
+                  "type": "array",
+                  "description": "Shared collections with `write` \"own\" only. Fields of a document's `data` that, when present, must hold a Civitai model version id owned by the viewer writing the document — for example [\"/workflow/modelVersionId\"] for a collection where viewers publish their own workflows. Each entry is a pointer of 1 to 4 segments, each \"/\" then a letter or _ followed by up to 63 letters, digits or _; 1 to 4 distinct pointers. A pointer names one field of nested objects: it never indexes into an array, and a step through an array or any other non-object finds nothing. On every create and update the server resolves each pointer in the new `data`: a field that is absent is allowed; a field that is present must be a positive integer naming a model version whose model the writer owns, and is otherwise refused with 403 `resource_not_owned` — a version that is someone else's, missing or deleted, and a value that is not a positive integer, are all refused the same way. The check runs before moderation and before any write budget is spent. Ownership is checked when a document is written, not afterwards: if the model later changes hands or is deleted, documents already stored keep the id.",
+                  "minItems": 1,
+                  "maxItems": 4,
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "pattern": "^(/[A-Za-z_][A-Za-z0-9_]{0,63}){1,4}$"
+                  }
                 }
               },
               "allOf": [
@@ -484,7 +496,8 @@
                       "counters": false,
                       "marks": false,
                       "showAuthor": false,
-                      "dailyWritesPerAuthor": false
+                      "dailyWritesPerAuthor": false,
+                      "ownedModelVersions": false
                     }
                   }
                 },
@@ -504,6 +517,14 @@
                   },
                   "then": { "properties": { "dailyWritesPerAuthor": false } }
                 },
+                {
+                  "$comment": "ownedModelVersions checks the version against the viewer WRITING the document, so it is declared only where that viewer is always the author: shared collections with write:\"own\" (private collections are refused above).",
+                  "if": {
+                    "required": ["write"],
+                    "properties": { "write": { "enum": ["anyone", "owner", "none"] } }
+                  },
+                  "then": { "properties": { "ownedModelVersions": false } }
+                },
                 {
                   "$comment": "A write:\"none\" collection is written only through counters and marks, so it must declare at least one.",
                   "if": {