@civitai/app-sdk 0.73.0 → 0.75.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
@@ -109,7 +116,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, 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';
+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, BlockMediaKind, BlockMediaUploadInfo, 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/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

@@ -8,7 +8,8 @@
  * Wire format: `window.postMessage({ type, payload }, targetOrigin)`.
  */
 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 { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockImagePickerSource, BlockPickedImageInfo, BlockMediaKind, BlockMediaUploadInfo, 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: {
@@ -577,6 +592,13 @@ export type ParentToBlockMessage = {
         selectedImages?: BlockPickedImageInfo[];
         error?: string;
     };
+} | {
+    type: 'MEDIA_UPLOAD_RESULT';
+    payload: {
+        requestId: string;
+        selected?: BlockMediaUploadInfo;
+        error?: string;
+    };
 } | {
     type: 'USER_CHECKPOINT_SET';
     payload: {
@@ -958,6 +980,19 @@ export type BlockToParentMessage = {
          */
         publicOnly?: boolean;
     };
+} | {
+    type: 'OPEN_MEDIA_UPLOAD';
+    payload: {
+        requestId: string;
+        /** What kind of media to upload. The host refuses any other value. */
+        kind: BlockMediaKind;
+        /** Required. The only accepted value today. */
+        purpose: 'generationSource';
+        /** In-tab bytes: present = bytes mode (no picker), absent = picker mode. */
+        bytes?: ArrayBuffer;
+        /** Bytes mode only: the type the app believes it is sending; must match the content. */
+        mimeType?: string;
+    };
 } | {
     type: 'SET_USER_CHECKPOINT';
     payload: {
@@ -1112,6 +1147,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 +1214,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", "OPEN_MEDIA_UPLOAD", "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

@@ -79,6 +79,7 @@ export const BLOCK_TO_PARENT_MESSAGE_TYPES = [
     'OPEN_RESOURCE_PICKER',
     'OPEN_IMAGE_UPLOAD',
     'OPEN_IMAGE_PICKER',
+    'OPEN_MEDIA_UPLOAD',
     'SET_USER_CHECKPOINT',
     'NAVIGATE',
     'REQUEST_SIGN_IN',
@@ -101,6 +102,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/dist/blocks/types.d.ts

@@ -372,6 +372,51 @@ export interface BlockPickedImageInfo {
      */
     imageId?: number;
 }
+/**
+ * What kind of media `OPEN_MEDIA_UPLOAD` (via `useMediaUpload`) uploads. The
+ * host decides the file's real type from its MAGIC BYTES, never from a declared
+ * MIME type, and accepts per kind:
+ *  - `'image'`: PNG, JPEG or WebP;
+ *  - `'video'`: MP4 or WebM;
+ *  - `'audio'`: MP3, WAV or WebM.
+ */
+export type BlockMediaKind = 'image' | 'video' | 'audio';
+/**
+ * One media file the host uploaded for the block as a GENERATION INPUT
+ * (`MEDIA_UPLOAD_RESULT.selected`, via `useMediaUpload`).
+ *
+ * `url` is a PRIVATE generation-input URL: pass it into a workflow step input
+ * (an image, video or audio input). It is not a public Civitai image and has no
+ * `imageId`. The host refuses data URIs and inline
+ * base64 in step inputs, so this is how a block gets media it holds (a picked
+ * file, a canvas, a recording) into a step.
+ *
+ * Per kind:
+ *  - `'image'`: the host RESIZES the picture so both sides are within 64–2048
+ *    pixels and RE-ENCODES it as JPEG. `mimeType` is always `'image/jpeg'`,
+ *    and `sizeBytes`, `width` and `height` describe that JPEG.
+ *  - `'video'`: uploaded as sent. `width` / `height` are always set (the host
+ *    refuses a file with no video track); `durationMs` is set when the browser
+ *    reports a finite duration.
+ *  - `'audio'`: uploaded as sent. No `width` / `height`; `durationMs` as for
+ *    video. A `MediaRecorder` WebM can report no duration, so do not rely on it.
+ */
+export interface BlockMediaUploadInfo {
+    /** The private generation-input URL. Pass it into a step input. */
+    url: string;
+    /** The kind that was requested. */
+    kind: BlockMediaKind;
+    /** The type actually uploaded. Always `'image/jpeg'` for `'image'`. */
+    mimeType: string;
+    /** Bytes actually uploaded (for `'image'`, the re-encoded JPEG's size). */
+    sizeBytes: number;
+    /** Pixel width. Always set for `'image'` and `'video'`; absent for `'audio'`. */
+    width?: number;
+    /** Pixel height. Always set for `'image'` and `'video'`; absent for `'audio'`. */
+    height?: number;
+    /** Duration in milliseconds, for `'video'` / `'audio'` when known. Never set for `'image'`. */
+    durationMs?: number;
+}
 /**
  * One of the model version's curated preview images, with the standard
  * gen params extracted from its source meta. Block UIs use these to let
@@ -1295,8 +1340,14 @@ export type WorkflowBodyPassThroughStep = {
      *
      * Consequently the orchestrator's per-`$type` schema is the ONLY authority for
      * what a given `$type` accepts; nothing in this package or on the host mirrors
-     * it. Bounded only by size: at most **262144 bytes** (256 KB) serialized, which
-     * is a payload-DoS bound and not a shape gate.
+     * it. Its shape is not checked; its size is: at most **262144 bytes** (256 KB)
+     * serialized, which is a payload-DoS bound and not a shape gate.
+     *
+     * 🔴 **No inline media.** The host refuses a `data:image|video|audio` URI or a
+     * long raw base64 string anywhere in here: upload the image, video or audio
+     * with `useMediaUpload()` (an image also works with
+     * `useImageUpload({ purpose: 'generationSource' })` or `useImagePicker()`)
+     * and pass the returned `url`.
      */
     input: Record<string, unknown>;
     /**

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
- *    180 symbols and that side effect into the root would make every OAuth app
+ *    198 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 180 is ASSERTED, not merely quoted — by
+ *    🔴 That 198 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
- *    180 symbols and that side effect into the root would make every OAuth app
+ *    198 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 180 is ASSERTED, not merely quoted — by
+ *    🔴 That 198 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/orchestrator/index.d.ts

@@ -430,11 +430,14 @@ export interface BuildImageGenBodyOptions {
  *
  * @example  Nano Banana 2 with a reference image
  * ```ts
+ * // Pass a hosted image URL, not a data URI or raw base64. In an App Block, the
+ * // `url` from `useImageUpload({ purpose: 'generationSource' })` or `useImagePicker()`;
+ * // the block host refuses inline media in a step input.
  * const body = buildImageGenBody({
  *   engine: 'google',
  *   model: 'nano-banana-2',
  *   prompt: 'turn this into a cartoon sticker',
- *   images: ['data:image/png;base64,...'],
+ *   images: [source.url],
  *   aspectRatio: '1:1',
  *   numImages: 1,
  *   resolution: '1K',

package/dist/orchestrator/index.js

@@ -393,11 +393,14 @@ export function buildTextToImageBody(input, opts = {}) {
  *
  * @example  Nano Banana 2 with a reference image
  * ```ts
+ * // Pass a hosted image URL, not a data URI or raw base64. In an App Block, the
+ * // `url` from `useImageUpload({ purpose: 'generationSource' })` or `useImagePicker()`;
+ * // the block host refuses inline media in a step input.
  * const body = buildImageGenBody({
  *   engine: 'google',
  *   model: 'nano-banana-2',
  *   prompt: 'turn this into a cartoon sticker',
- *   images: ['data:image/png;base64,...'],
+ *   images: [source.url],
  *   aspectRatio: '1:1',
  *   numImages: 1,
  *   resolution: '1K',

package/package.json

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