@civitai/app-sdk 0.73.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.js

@@ -93,9 +93,10 @@ export const BLOCK_SCOPES = {
     // 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. Listed here because the
-    // canonical schema's `scopes` enum carries it; the server ships the feature
-    // behind a dark flag, and this package has no reaction helper yet.
+    // `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',
 };
 /**

package/package.json

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