@civitai/app-sdk 0.62.0 → 0.64.0

package/README.md

@@ -85,12 +85,13 @@ over `window.postMessage({ type, payload }, targetOrigin)`, discriminated by
 `type`. The full union is exported:
 
 - **parent → block**: `BLOCK_INIT`, `TOKEN_REFRESH`, `TOKEN_REFRESH_RESPONSE`,
-  `ESTIMATE_RESULT`, `WORKFLOW_SUBMITTED`, `WORKFLOW_STATUS`,
+  `ESTIMATE_RESULT`, `ESTIMATE_BATCH_RESULT`, `WORKFLOW_SUBMITTED`, `WORKFLOW_STATUS`,
   `BUZZ_PURCHASE_RESULT`, `CHECKPOINT_PICKER_RESULT`, `USER_CHECKPOINT_SET`,
   `APP_STORAGE_*_RESULT`, `SUSPEND`, `RESUME`, `THEME_CHANGE`, `ROUTE_CHANGED`,
   `CONSENT_UNAVAILABLE` (`ParentToBlockMessage`).
 - **block → parent**: `BLOCK_READY`, `BLOCK_ERROR`, `REQUEST_TOKEN`,
-  `RESIZE_IFRAME`, `SUBMIT_WORKFLOW`, `ESTIMATE_WORKFLOW`, `POLL_WORKFLOW`,
+  `RESIZE_IFRAME`, `SUBMIT_WORKFLOW`, `ESTIMATE_WORKFLOW`,
+  `ESTIMATE_WORKFLOW_BATCH`, `POLL_WORKFLOW`,
   `QUERY_APP_WORKFLOWS`, `CANCEL_APP_WORKFLOW`, `OPEN_BUZZ_PURCHASE`,
   `OPEN_CHECKPOINT_PICKER`, `SET_USER_CHECKPOINT`, `NAVIGATE`, `TRACK_EVENT`,
   `APP_STORAGE_*` (`BlockToParentMessage`).

package/dist/blocks/index.d.ts

@@ -96,7 +96,7 @@ export type { AppStorageRejectionReason } from './appStorageErrors.js';
 export { BLOCK_INIT_FRAGMENT_MARKER_KEY, BLOCK_INIT_FRAGMENT_VERSION, BLOCK_INIT_FRAGMENT_KEYS, encodeBlockInitFragment, parseBlockInitFragment, stripBlockInitFragment, } from './initFragment.js';
 export type { BlockInitFragment } from './initFragment.js';
 export { isMessage, BLOCK_TO_PARENT_MESSAGE_TYPES, OTHER_MESSAGE_TYPE_LABEL, boundBlockToParentMessageType, } from './messages.js';
-export type { BlockInitPayload, BlockToParentMessage, BlockToParentMessageType, ConsentUnavailablePayload, ConsentUnavailableReason, ParentToBlockMessage, ParentToBlockMessageType, SharedStorageItemWire, SharedStorageValue, WrappedToken, BlockBuzzTransactionsParams, BlockDailyCompensationParams, AppWorkflowsParams, } from './messages.js';
+export type { BlockInitPayload, BlockToParentMessage, BlockToParentMessageType, ConsentUnavailablePayload, ConsentUnavailableReason, ParentToBlockMessage, ParentToBlockMessageType, SharedStorageItemWire, SharedStorageRateLimit, SharedStorageValue, WrappedToken, BlockBuzzTransactionsParams, BlockDailyCompensationParams, AppWorkflowsParams, } from './messages.js';
 /**
  * Runtime narrowing for the `slotId`-discriminated {@link BlockContext} union.
  * Values, not types — a slot context crosses a `postMessage` boundary, so its
@@ -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, 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, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockModelSubstitution, ModelSubstitutionReason, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, 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, } 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, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockEstimateBatchAggregate, BlockModelSubstitution, ModelSubstitutionReason, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, 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, } from './types.js';
 /**
  * Host bounds for the App Blocks `kind: 'training'` flow, mirrored from
  * civitai/civitai's zod — see `WorkflowBodyTraining`.

package/dist/blocks/messages.d.ts

@@ -8,7 +8,7 @@
  * Wire format: `window.postMessage({ type, payload }, targetOrigin)`.
  */
 import type { ColorDomain } from './browsingLevel.js';
-import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult, BlockTrainingDatasetItem, BlockTrainingDatasetResult, WorkflowBodyTraining } from './types.js';
+import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, 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 } from './types.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
@@ -239,6 +239,27 @@ export interface SharedStorageValue {
      */
     data?: unknown;
 }
+/**
+ * Retry metadata on a RATE-LIMITED shared-storage refusal. The host adds it
+ * beside `error` on the six write replies (`SHARED_APPEND_RESULT`,
+ * `SHARED_UPDATE_RESULT`, `SHARED_VOTE_RESULT`, `SHARED_UNVOTE_RESULT`,
+ * `SHARED_WITHDRAW_RESULT`, `SHARED_REPORT_RESULT`) when the server refused the
+ * write because a per-(viewer, app) budget is empty, so a block can render the
+ * wait instead of parsing it out of the prose `error`.
+ *
+ * Its PRESENCE marks the refusal as rate-limited; every other refusal omits it.
+ * ADDITIVE + OPTIONAL: a host that predates it never sends it, so a block must
+ * treat "absent" as "not known to be rate-limited", never as "retry now".
+ *
+ * Same shape as the platform's tRPC `error.data.rateLimit` and the REST 429
+ * body's `rateLimit` (which also comes with a `Retry-After` header).
+ */
+export interface SharedStorageRateLimit {
+    /** Whole seconds until a retry can succeed. An integer, at least 1. */
+    retryAfterSeconds: number;
+    /** ISO-8601 instant at which a retry can succeed. */
+    retryAt: string;
+}
 /**
  * One SHARED-storage entry as it appears on the wire in `SHARED_LIST_RESULT`.
  * `createdAt`/`updatedAt` are ISO-8601 strings; the block-side hook rehydrates
@@ -360,6 +381,14 @@ export type ParentToBlockMessage = {
         requestId: string;
         snapshot: BlockWorkflowSnapshot;
     };
+} | {
+    type: 'ESTIMATE_BATCH_RESULT';
+    payload: {
+        requestId: string;
+        snapshots?: BlockWorkflowSnapshot[];
+        aggregate?: BlockEstimateBatchAggregate;
+        error?: string;
+    };
 } | {
     type: 'WORKFLOW_SUBMITTED';
     payload: {
@@ -515,6 +544,8 @@ export type ParentToBlockMessage = {
     payload: {
         requestId: string;
         selected?: BlockResourceInfo;
+        selectedResources?: BlockResourceInfo[];
+        error?: string;
     };
 } | {
     type: 'IMAGE_UPLOAD_RESULT';
@@ -610,6 +641,7 @@ export type ParentToBlockMessage = {
         requestId: string;
         key: string;
         error?: string;
+        rateLimit?: SharedStorageRateLimit;
     };
 } | {
     type: 'SHARED_VOTE_RESULT';
@@ -617,6 +649,7 @@ export type ParentToBlockMessage = {
         requestId: string;
         count: number;
         error?: string;
+        rateLimit?: SharedStorageRateLimit;
     };
 } | {
     type: 'SHARED_UNVOTE_RESULT';
@@ -624,6 +657,7 @@ export type ParentToBlockMessage = {
         requestId: string;
         count: number;
         error?: string;
+        rateLimit?: SharedStorageRateLimit;
     };
 } | {
     type: 'SHARED_WITHDRAW_RESULT';
@@ -632,6 +666,7 @@ export type ParentToBlockMessage = {
         ok?: boolean;
         deleted?: boolean;
         error?: string;
+        rateLimit?: SharedStorageRateLimit;
     };
 } | {
     type: 'SHARED_UPDATE_RESULT';
@@ -639,6 +674,7 @@ export type ParentToBlockMessage = {
         requestId: string;
         ok?: boolean;
         error?: string;
+        rateLimit?: SharedStorageRateLimit;
     };
 } | {
     type: 'SHARED_GET_RESULT';
@@ -653,6 +689,7 @@ export type ParentToBlockMessage = {
         requestId: string;
         ok?: boolean;
         error?: string;
+        rateLimit?: SharedStorageRateLimit;
     };
 } | {
     type: 'SAVE_IMAGE_RESULT';
@@ -712,6 +749,12 @@ export type BlockToParentMessage = {
         requestId: string;
         body: WorkflowBody;
     };
+} | {
+    type: 'ESTIMATE_WORKFLOW_BATCH';
+    payload: {
+        requestId: string;
+        bodies: WorkflowBody[];
+    };
 } | {
     type: 'POLL_WORKFLOW';
     payload: {
@@ -831,6 +874,16 @@ export type BlockToParentMessage = {
         resourceType: BlockResourcePickerType;
         /** Optional base-model family hint (ecosystem key or baseModel name). */
         baseModelGroup?: string;
+        /**
+         * Ask for SEVERAL resources in one picker session. LoRA only — the host
+         * refuses it with a Checkpoint. `max` is a whole number ≥ 1; the host
+         * clamps anything above 5 (the `additionalResources` cap) to 5. The
+         * reply is then `selectedResources`, not `selected`. OMIT the key for
+         * a single pick: its absence is what keeps that path unchanged.
+         */
+        multiple?: {
+            max: number;
+        };
     };
 } | {
     type: 'OPEN_IMAGE_UPLOAD';
@@ -1040,7 +1093,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", "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", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_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"];
+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", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_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"];
 /**
  * The bucket a message type falls into when the protocol does not declare it.
  *

package/dist/blocks/messages.js

@@ -57,6 +57,7 @@ export const BLOCK_TO_PARENT_MESSAGE_TYPES = [
     'RESIZE_IFRAME',
     'SUBMIT_WORKFLOW',
     'ESTIMATE_WORKFLOW',
+    'ESTIMATE_WORKFLOW_BATCH',
     'POLL_WORKFLOW',
     'CANCEL_WORKFLOW',
     'OPEN_BUZZ_PURCHASE',

package/dist/blocks/types.d.ts

@@ -1468,7 +1468,27 @@ export interface BlockWorkflowSnapshot {
     workflowId: string;
     status: 'pending' | 'processing' | 'succeeded' | 'failed' | 'expired' | 'canceled';
     cost?: {
+        /** Whole Buzz. Includes {@link authorFee} whenever that field is present. */
         total: number;
+        /**
+         * The part of `total` that is the app author's per-generation fee, in whole
+         * Buzz — so `total - authorFee` is the generation's own price. Display only:
+         * it is the amount the host added into `total` for this reply.
+         *
+         * - **A number** wherever `total` was built from a fee quote: the
+         *   `estimate()` result for a `textToImage` or registered-`step` body, and
+         *   the refusal `submit()` resolves for those kinds when a budget, spend cap
+         *   or rate limit refuses the quoted price. **`0` means a fee was looked up
+         *   and none applies** to this request.
+         * - **Absent** when the total is not itemised: a host that predates the
+         *   field; every snapshot of a submitted workflow (`submit` success, `poll`,
+         *   `cancel` — its total is the realized generation cost and the fee is a
+         *   separate charge); the registered-`step` `submit()` refusal for a missing
+         *   orchestrator price quote, which refuses before any fee is looked up; and
+         *   the kinds that price no fee (`customComfy`, pass-through `step`,
+         *   `training`). **Do not read absent as `0`** — show `total` on its own.
+         */
+        authorFee?: number;
     };
     imageUrls?: string[];
     error?: string;
@@ -1674,6 +1694,27 @@ export interface BlockWorkflowSnapshot {
      */
     trainingQuote?: BlockTrainingQuote;
 }
+/**
+ * The run total a BATCH estimate reports beside its per-cell snapshots
+ * (`ESTIMATE_BATCH_RESULT`, sent in reply to `ESTIMATE_WORKFLOW_BATCH`).
+ *
+ * `total` is the sum of `cost.total` over the cells that PRICED: a snapshot that
+ * is not `'failed'` and carries a numeric `cost.total`, the same rule one
+ * estimate is held to. It is the total for the whole list only when
+ * `pricedCells === cellCount`. Otherwise it is a partial sum; show it as one.
+ *
+ * 🔴 IT IS A QUOTE, NOT A LOCK, exactly as each cell is. Nothing reserves it. The
+ * host creates no workflow and no batch for the list, and each cell is priced
+ * again when the app submits it.
+ */
+export interface BlockEstimateBatchAggregate {
+    /** Sum of `cost.total` over the priced cells, in Buzz. `0` when none priced. */
+    total: number;
+    /** How many cells priced and are therefore in `total`. */
+    pricedCells: number;
+    /** How many cells the host answered — the length of the list it was sent. */
+    cellCount: number;
+}
 /** {@link BlockWorkflowSnapshot.trainingQuote}. */
 export interface BlockTrainingQuote {
     /** `tq_` + 32 hex characters. Opaque — pass it back verbatim. */
@@ -1859,6 +1900,57 @@ export interface ManifestPreview {
     description: string;
     screenshots?: string[];
 }
+/**
+ * One declared property of a custom event — see {@link BlockManifestV1.analytics}.
+ *
+ * Exactly three types, and deliberately NO free-text string:
+ *
+ * - `enum` — a string drawn from `values`: 1 to 50 distinct, non-empty strings of
+ *   at most 64 characters (Unicode code points) each. A string that is not one of
+ *   the declared values will never be recorded.
+ * - `number` — not range-limited, so do not use one to carry an identifier.
+ * - `boolean`.
+ *
+ * No other key is allowed on a declaration (`values` only on an `enum`).
+ * Mirrors the canonical schema's `analytics.events.*.properties.*`.
+ */
+export type BlockAnalyticsPropertyDeclaration = {
+    type: 'enum';
+    values: string[];
+} | {
+    type: 'number';
+} | {
+    type: 'boolean';
+};
+/**
+ * One declared custom event — see {@link BlockManifestV1.analytics}. Mirrors the
+ * canonical schema's `analytics.events.*`.
+ */
+export interface BlockAnalyticsEventDeclaration {
+    /**
+     * Optional human-readable meaning of the event, shown to reviewers and in
+     * your analytics. At most 200 characters (Unicode code points).
+     */
+    description?: string;
+    /**
+     * Property name → declaration. At most 10 properties per event. A property
+     * name follows the same rule as an event name: lowercase snake_case, a letter
+     * then up to 63 of `a-z`, `0-9` or `_` (`^[a-z][a-z0-9_]{0,63}$`).
+     */
+    properties?: Record<string, BlockAnalyticsPropertyDeclaration>;
+}
+/**
+ * The manifest's `analytics` object — see {@link BlockManifestV1.analytics}.
+ * Mirrors the canonical schema's `analytics`; no other key is allowed.
+ */
+export interface BlockAnalyticsDeclaration {
+    /**
+     * Event name → declaration. At most 50 events. An event name is lowercase
+     * snake_case: a letter, then up to 63 of `a-z`, `0-9` or `_`
+     * (`^[a-z][a-z0-9_]{0,63}$`).
+     */
+    events?: Record<string, BlockAnalyticsEventDeclaration>;
+}
 /**
  * One entry of a manifest's `goods[]`. Mirrors the canonical schema exactly;
  * `id`, `title` and `priceBuzz` are required there and so are they here.
@@ -1978,6 +2070,26 @@ export interface BlockManifestV1 {
      * Kept in lockstep with the canonical schema's `goods`.
      */
     goods?: BlockManifestGood[];
+    /**
+     * Optional CUSTOM EVENTS declaration. `events` names every event the app may
+     * send and the properties each event may carry. Manifest-governed and
+     * REVIEW-GATED: the declaration a moderator approves is the only one the
+     * platform accepts events against, so a reviewer can see what the app tracks.
+     *
+     * Properties are typed `enum` (a declared list of string values), `number` or
+     * `boolean` ONLY — free-text strings are deliberately not supported, so a
+     * string that is not one of an enum's declared values will never be recorded.
+     * That is what keeps prompts, emails and usernames out of string properties.
+     * Owners see aggregates only, never individual events.
+     *
+     * Limits (the canonical schema's, which this type cannot express): event and
+     * property names match `^[a-z][a-z0-9_]{0,63}$`; at most 50 events and 10
+     * properties per event; an enum declares 1 to 50 distinct non-empty values of
+     * at most 64 code points; a `description` is at most 200 code points. The
+     * platform's manifest validator is authoritative. Kept in lockstep with the
+     * canonical schema's `analytics`.
+     */
+    analytics?: BlockAnalyticsDeclaration;
     /** 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
- *    154 symbols and that side effect into the root would make every OAuth app
+ *    159 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 154 is ASSERTED, not merely quoted — by
+ *    🔴 That 159 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
- *    154 symbols and that side effect into the root would make every OAuth app
+ *    159 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 154 is ASSERTED, not merely quoted — by
+ *    🔴 That 159 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.js

@@ -45,6 +45,7 @@ import { readFileSync } from 'node:fs';
 import Ajv2020 from 'ajv/dist/2020.js';
 import { BlockManifestError } from '../blocks/manifestError.js';
 import { BLOCK_SCOPES } from '../blocks/scopes.js';
+import { preferDiscriminatedBranch } from './discriminatedBranch.js';
 /**
  * Rules `defineBlock` applies that the canonical schema does NOT express in
  * machine-checkable form.
@@ -173,7 +174,11 @@ function canonicalValidator() {
     // scaffold. The gap is recorded in KNOWN_GAPS, not shouted at the author on
     // every boot. NOTE this silences Ajv's own diagnostics only; validation
     // errors are returned in `validate.errors`, never logged.
-    const ajv = new Ajv2020({ allErrors: true, strict: false, logger: false });
+    //
+    // `verbose: true` puts the failed keyword's own `schema` and the offending
+    // `data` on each error. `preferDiscriminatedBranch` reads both off a failed
+    // `oneOf` / `anyOf`; it changes which error is REPORTED, never the verdict.
+    const ajv = new Ajv2020({ allErrors: true, strict: false, logger: false, verbose: true });
     compiled = ajv.compile(loadCanonicalSchema());
     return compiled;
 }
@@ -194,12 +199,14 @@ function toDotPath(instancePath) {
 }
 const PASCAL_CASE_PATTERN = /^[A-Z][A-Za-z0-9]*$/;
 /**
- * Turns the FIRST Ajv error into a `BlockManifestError`. Ajv's own wording is
- * kept (it is derived from the schema, so it cannot drift); only the field path
- * is reshaped, and one case gets an extra hint because it is the mistake the
+ * Turns ONE Ajv error (the one {@link preferDiscriminatedBranch} picked) into a
+ * `BlockManifestError`. Ajv's own wording is kept (it is derived from the
+ * schema, so it cannot drift); only the field path is reshaped, and two cases
+ * get extra wording: an unknown key inside a discriminated branch says which
+ * branch, and a PascalCase scope gets a hint because it is the mistake the
  * docs see most.
  */
-function toManifestError(error, manifest) {
+function toManifestError(error, manifest, discriminator) {
     const base = toDotPath(error.instancePath);
     if (error.keyword === 'required') {
         const missing = error.params.missingProperty;
@@ -216,7 +223,10 @@ function toManifestError(error, manifest) {
     }
     if (error.keyword === 'additionalProperties') {
         const extra = error.params.additionalProperty;
-        message = `${shown}.${extra} is not a known property here`;
+        message = discriminator
+            ? `${shown}.${extra} is not a known property when \`${discriminator.key}\` is ` +
+                JSON.stringify(discriminator.value)
+            : `${shown}.${extra} is not a known property here`;
         return new BlockManifestError(message, field === '' ? extra : `${field}.${extra}`);
     }
     // The one hint worth adding: block scopes are colon-separated lowercase, and
@@ -281,12 +291,11 @@ export function defineBlock(config) {
     // whatever Ajv rejects, this rejects.
     const validate = canonicalValidator();
     if (!validate(manifest)) {
-        const errors = validate.errors ?? [];
-        const first = errors[0];
+        const picked = preferDiscriminatedBranch(validate.errors ?? []);
         /* c8 ignore next */
-        if (!first)
+        if (!picked)
             throw new BlockManifestError('manifest failed schema validation');
-        throw toManifestError(first, manifest);
+        throw toManifestError(picked.error, manifest, picked.discriminator);
     }
     // (2) The prose-only server rejections. Strictly additive, one per
     // SCHEMA_DIVERGENCES entry, in the table's order.

package/dist/manifest/discriminatedBranch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which validation error to REPORT when a `oneOf` / `anyOf` fails.
+ *
+ * INTERNAL to `./defineBlock` — not re-exported from `./index`, and typed
+ * structurally (no Ajv import) so it can be exercised against small synthetic
+ * schemas in `test/manifest/discriminated-branch.test.ts`.
+ */
+/** The fields of an Ajv `ErrorObject` this reads. `schema` and `data` need Ajv's `verbose: true`. */
+export interface ValidationErrorLike {
+    keyword: string;
+    instancePath: string;
+    schemaPath: string;
+    schema?: unknown;
+    data?: unknown;
+}
+/** The discriminator that selected the member an error is reported from. */
+export interface Discriminator {
+    key: string;
+    value: unknown;
+}
+/**
+ * Picks the error to REPORT. Ajv (with `allErrors`) validates every member of
+ * a failed `oneOf` / `anyOf` and lists all their errors in member order, so
+ * the plain first error is the FIRST MEMBER's complaint whichever member the
+ * author was writing: a `{ type: 'number', min: 0 }` property declaration used
+ * to be reported as "`values` is required", the `enum` member's rule.
+ *
+ * Where the members discriminate on a `const` (see {@link discriminatorKey})
+ * and the instance's value for that key equals exactly one member's, that
+ * member is the one the author meant: errors from the OTHER members, on that
+ * instance, are skipped, and the first error left is returned. (The summary
+ * `oneOf` / `anyOf` error needs no handling: Ajv lists it after the members'
+ * own errors.) `discriminator` is set when the returned error is on the
+ * discriminated object itself, so the message can say which member it is from.
+ *
+ * Any other failed composition — no shared `const` property, or a value no
+ * member names, or more than one member naming it — is left exactly as it
+ * was: the first error wins.
+ *
+ * 🔴 SELECTION ONLY. It is given the errors of a manifest Ajv has already
+ * rejected and returns one of them (the plain first if it would otherwise skip
+ * everything; `undefined` only for an empty list), so it cannot turn a
+ * rejection into an acceptance or the reverse.
+ *
+ * Members reached through `$ref` report a `schemaPath` relative to the
+ * referenced schema, so their errors are not recognised as a member's and are
+ * never skipped — that site degrades to "first error not from a recognised
+ * other member". The canonical uses no `$ref` today.
+ */
+export declare function preferDiscriminatedBranch<E extends ValidationErrorLike>(errors: E[]): {
+    error: E;
+    discriminator?: Discriminator;
+} | undefined;
+//# sourceMappingURL=discriminatedBranch.d.ts.map

package/dist/manifest/discriminatedBranch.js

@@ -0,0 +1,100 @@
+/**
+ * Which validation error to REPORT when a `oneOf` / `anyOf` fails.
+ *
+ * INTERNAL to `./defineBlock` — not re-exported from `./index`, and typed
+ * structurally (no Ajv import) so it can be exercised against small synthetic
+ * schemas in `test/manifest/discriminated-branch.test.ts`.
+ */
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** `{ value }` when `member.properties[key]` pins a primitive `const`, else `null`. */
+function constOf(member, key) {
+    const prop = isRecord(member) && isRecord(member.properties) ? member.properties[key] : undefined;
+    if (!isRecord(prop) || !('const' in prop))
+        return null;
+    return typeof prop.const === 'object' && prop.const !== null ? null : { value: prop.const };
+}
+/**
+ * The property every member of a `oneOf` / `anyOf` pins to its own `const` —
+ * `type` in `[{ properties: { type: { const: 'enum' } } }, { … 'number' }, …]` —
+ * or `undefined` when the members do not discriminate that way. Read from the
+ * schema, so nothing here names a manifest field.
+ */
+function discriminatorKey(members) {
+    const first = members[0];
+    if (!isRecord(first) || !isRecord(first.properties))
+        return undefined;
+    return Object.keys(first.properties).find((key) => members.every((member) => constOf(member, key) !== null));
+}
+/**
+ * Picks the error to REPORT. Ajv (with `allErrors`) validates every member of
+ * a failed `oneOf` / `anyOf` and lists all their errors in member order, so
+ * the plain first error is the FIRST MEMBER's complaint whichever member the
+ * author was writing: a `{ type: 'number', min: 0 }` property declaration used
+ * to be reported as "`values` is required", the `enum` member's rule.
+ *
+ * Where the members discriminate on a `const` (see {@link discriminatorKey})
+ * and the instance's value for that key equals exactly one member's, that
+ * member is the one the author meant: errors from the OTHER members, on that
+ * instance, are skipped, and the first error left is returned. (The summary
+ * `oneOf` / `anyOf` error needs no handling: Ajv lists it after the members'
+ * own errors.) `discriminator` is set when the returned error is on the
+ * discriminated object itself, so the message can say which member it is from.
+ *
+ * Any other failed composition — no shared `const` property, or a value no
+ * member names, or more than one member naming it — is left exactly as it
+ * was: the first error wins.
+ *
+ * 🔴 SELECTION ONLY. It is given the errors of a manifest Ajv has already
+ * rejected and returns one of them (the plain first if it would otherwise skip
+ * everything; `undefined` only for an empty list), so it cannot turn a
+ * rejection into an acceptance or the reverse.
+ *
+ * Members reached through `$ref` report a `schemaPath` relative to the
+ * referenced schema, so their errors are not recognised as a member's and are
+ * never skipped — that site degrades to "first error not from a recognised
+ * other member". The canonical uses no `$ref` today.
+ */
+export function preferDiscriminatedBranch(errors) {
+    // One entry per member of each discriminated composition that failed: where
+    // its errors live (`prefix`), on which instance, and — for the member the
+    // instance's discriminator names — the discriminator (`chosen`).
+    const scopes = [];
+    for (const error of errors) {
+        if (error.keyword !== 'oneOf' && error.keyword !== 'anyOf')
+            continue;
+        const members = error.schema;
+        if (!Array.isArray(members) || !isRecord(error.data))
+            continue;
+        const key = discriminatorKey(members);
+        if (key === undefined)
+            continue;
+        const value = error.data[key];
+        const matching = members.flatMap((member, index) => constOf(member, key)?.value === value ? [index] : []);
+        if (matching.length !== 1)
+            continue;
+        members.forEach((_member, index) => {
+            scopes.push({
+                prefix: `${error.schemaPath}/${index}/`,
+                instancePath: error.instancePath,
+                ...(index === matching[0] ? { chosen: { key, value } } : {}),
+            });
+        });
+    }
+    for (const error of errors) {
+        // Compositions nest, so an error can sit inside several members at once.
+        const within = scopes.filter((s) => error.schemaPath.startsWith(s.prefix) &&
+            (error.instancePath === s.instancePath ||
+                error.instancePath.startsWith(`${s.instancePath}/`)));
+        // Inside a member, at any level, that its instance's discriminator does not name.
+        if (within.some((s) => !s.chosen))
+            continue;
+        // The member is named in the message only for an error ON the discriminated
+        // object itself (the innermost one), not for one on something nested inside it.
+        const innermost = within.reduce((a, b) => (a && a.prefix.length >= b.prefix.length ? a : b), undefined);
+        return innermost?.chosen && error.instancePath === innermost.instancePath
+            ? { error, discriminator: innermost.chosen }
+            : { error };
+    }
+    return errors[0] ? { error: errors[0] } : undefined;
+}
+//# sourceMappingURL=discriminatedBranch.js.map

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 { BlockManifest, BlockManifestGood, BlockManifestV1 } from '../blocks/types.js';
+export type { BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, } from '../blocks/types.js';
 //# sourceMappingURL=index.d.ts.map

package/package.json

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

@@ -275,6 +275,104 @@
         }
       }
     },
+    "analytics": {
+      "type": "object",
+      "description": "Optional CUSTOM EVENTS declaration. `events` names every event your app may send with `useBlockAnalytics().track(name, properties)` and the properties each event may carry. Manifest-governed and REVIEW-GATED: the declaration a moderator approves is the only one the platform will accept events against, so a reviewer can see what your app tracks. Properties are typed `enum` (a declared list of string values), `number` or `boolean` ONLY — free-text strings are deliberately not supported, so a string that is not one of an enum's declared values will never be recorded. That is what keeps prompts, emails and usernames out of string properties (a `number` property is not range-limited, so do not use one to carry an identifier). Owners will see aggregates only, never individual events. The platform's manifest validator is authoritative.",
+      "additionalProperties": false,
+      "properties": {
+        "events": {
+          "type": "object",
+          "description": "Map of event name → declaration. At most 50 events. An event name is lowercase snake_case: a letter, then up to 63 of a-z, 0-9 or _.",
+          "maxProperties": 50,
+          "additionalProperties": false,
+          "patternProperties": {
+            "^[a-z][a-z0-9_]{0,63}$": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "description": {
+                  "type": "string",
+                  "description": "Optional human-readable meaning of the event, shown to reviewers and in your analytics.",
+                  "maxLength": 200
+                },
+                "properties": {
+                  "type": "object",
+                  "description": "Map of property name → declaration. At most 10 properties per event. A property name follows the same rule as an event name.",
+                  "maxProperties": 10,
+                  "additionalProperties": false,
+                  "patternProperties": {
+                    "^[a-z][a-z0-9_]{0,63}$": {
+                      "type": "object",
+                      "allOf": [
+                        {
+                          "$comment": "Checked FIRST, before the oneOf below, so a wrong type is reported as such rather than as a missing `values`.",
+                          "required": ["type"],
+                          "properties": {
+                            "type": {
+                              "description": "The property's type. There is no free-text string type: declare an enum.",
+                              "enum": ["enum", "number", "boolean"]
+                            }
+                          }
+                        },
+                        {
+                          "oneOf": [
+                            {
+                              "type": "object",
+                              "description": "A string drawn from a declared list. A string outside `values` will not be recorded.",
+                              "additionalProperties": false,
+                              "required": ["type", "values"],
+                              "properties": {
+                                "type": {
+                                  "const": "enum"
+                                },
+                                "values": {
+                                  "type": "array",
+                                  "description": "The allowed values: 1 to 50 distinct non-empty strings of at most 64 characters (Unicode code points) each.",
+                                  "minItems": 1,
+                                  "maxItems": 50,
+                                  "uniqueItems": true,
+                                  "items": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "maxLength": 64
+                                  }
+                                }
+                              }
+                            },
+                            {
+                              "type": "object",
+                              "description": "A number.",
+                              "additionalProperties": false,
+                              "required": ["type"],
+                              "properties": {
+                                "type": {
+                                  "const": "number"
+                                }
+                              }
+                            },
+                            {
+                              "type": "object",
+                              "description": "A boolean.",
+                              "additionalProperties": false,
+                              "required": ["type"],
+                              "properties": {
+                                "type": {
+                                  "const": "boolean"
+                                }
+                              }
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "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.",