@civitai/app-sdk 0.64.0 → 0.65.0

package/dist/blocks/index.d.ts

@@ -109,7 +109,7 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } from './types.js';
-export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, 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';
+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, KnownBlockWorkflowErrorCode, 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/types.d.ts

@@ -1492,6 +1492,35 @@ export interface BlockWorkflowSnapshot {
     };
     imageUrls?: string[];
     error?: string;
+    /**
+     * A stable, machine-readable companion to {@link error}, for a block to
+     * branch on instead of matching the prose. OPTIONAL: set only on the refusals
+     * that define a code, absent everywhere else (and on every reply from a host
+     * that predates the field).
+     *
+     * WHERE IT APPEARS today: the refusal for a pass-through `step` body
+     * ({@link WorkflowBodyPassThroughStep}) whose `$type` is a training type
+     * (`'training'` or `'imageResourceTraining'`) when the host could not get a
+     * price quote for it. That refusal is `{ workflowId: 'failed', status:
+     * 'failed', error, errorCode }` with no `cost`, and it is the reply to
+     * `estimate()` (which rejects with `WorkflowEstimateError`), to `submit()`
+     * (which rejects with `WorkflowSubmitError`, before anything is reserved or
+     * charged), and to that body's cell in a batch estimate. Read it from the
+     * error's `.snapshot.errorCode`. The `kind: 'training'` arm does NOT set it.
+     *
+     * The values the host sends today ({@link KnownBlockWorkflowErrorCode}):
+     *  - `'training-quote-rejected'` — the orchestrator refused the request
+     *    itself; resending the same body will not help. `error` then reads
+     *    `Training could not be priced: <reason>` when the reason is safe to show.
+     *  - `'training-quote-unavailable'` — no usable answer (an outage, a timeout,
+     *    a rate limit, insufficient funds, …). Retrying later may succeed.
+     *  - `'training-quote-unpriced'` — the orchestrator answered without a price.
+     *
+     * 🔴 AN UNKNOWN VALUE IS POSSIBLE: the host may add codes, and the SDK's
+     * inbound validator accepts any string here. Handle an unrecognised code as a
+     * generic failure and show `error`.
+     */
+    errorCode?: KnownBlockWorkflowErrorCode | (string & {});
     /**
      * The Buzz pool that was the PRIMARY FUNDER of this generation — i.e. the
      * account with the LARGEST debit, which the host stamps onto the workflow
@@ -1743,6 +1772,16 @@ export interface BlockTrainingQuote {
  * generic substitution rather than assuming the list is closed.
  */
 export type ModelSubstitutionReason = 'wrong-workflow' | 'unrecognized' | 'gated';
+/**
+ * The {@link BlockWorkflowSnapshot.errorCode} values the host sends today — see
+ * that field for what each means and which replies carry it.
+ *
+ * NOT a closed list: the field itself is typed `KnownBlockWorkflowErrorCode |
+ * (string & {})` (the union is an autocomplete nudge), the host may add codes,
+ * and the SDK's inbound validator accepts any string. Handle an unrecognised
+ * code as a generic failure.
+ */
+export type KnownBlockWorkflowErrorCode = 'training-quote-rejected' | 'training-quote-unavailable' | 'training-quote-unpriced';
 /** One entry of {@link BlockWorkflowSnapshot.modelSubstitutions}. */
 export interface BlockModelSubstitution {
     /** The checkpoint version id the block asked for. */

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
- *    159 symbols and that side effect into the root would make every OAuth app
+ *    160 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 159 is ASSERTED, not merely quoted — by
+ *    🔴 That 160 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
- *    159 symbols and that side effect into the root would make every OAuth app
+ *    160 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 159 is ASSERTED, not merely quoted — by
+ *    🔴 That 160 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/package.json

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

@@ -37,7 +37,7 @@
     },
     "repository": {
       "type": "string",
-      "description": "Optional PUBLIC SOURCE-REPOSITORY link for an open-source app, rendered as a `Source` row on the app's `/apps` store DETAIL page (never on a store grid card). Manifest-governed: it flows to the store listing on moderator-approve and is re-synced from the manifest on every subsequent approved version; remove the key and the link is cleared. This is NOT your app's internal Civitai repository — it is a link you publish. Must be an `https://` URL, carrying no embedded credentials and no port, whose host is EXACTLY one of github.com, gitlab.com or codeberg.org (an exact-host allowlist — `www.github.com`, `gist.github.com` and `raw.githubusercontent.com` are all rejected), and whose path is exactly `/<owner>/<repo>`, the repository ROOT (a deep link such as `/owner/repo/tree/main` is rejected). A trailing `/` or `.git`, a query string and a fragment are accepted and STRIPPED — the stored value is normalised to `https://<host>/<owner>/<repo>`. Capped at 200 characters, kept in lockstep with MAX_REPOSITORY_URL_LENGTH in src/server/schema/blocks/external-app.schema.ts (a drift-guard test enforces equality, and enforces that this description names exactly the hosts REPOSITORY_HOST_ALLOWLIST contains). NOTE: as with `tagline`, the server measures the TRIMMED string while this maxLength counts the raw one, so the LENGTH bound here is never looser than the server's. The `pattern`, however, is a coarse SHAPE check and NOT the whole rule, so unlike `tagline` this field CAN pass local validation and still be rejected at submit. The server additionally requires each of the two path segments to begin with an ASCII letter or digit and to contain only letters, digits, `.`, `-` and `_`, and it strips a trailing `.git` BEFORE applying that test. Values such as a repository segment that is only `.git`, one starting with a dash, one containing a percent-escape, and one containing a non-ASCII character all match this pattern and are refused by the server. The pattern is deliberately left coarse rather than tightened: the CLI and the starter templates byte-mirror this file, and a stricter regex would be a compatibility change for every vendored copy. Treat passing local validation as necessary, not sufficient — `validateRepositoryUrl` in src/server/schema/blocks/external-app.schema.ts is authoritative.",
+      "description": "Optional PUBLIC SOURCE-REPOSITORY link for an open-source app, rendered as a `Source` row on the app's `/apps` store DETAIL page (never on a store grid card). Manifest-governed: it flows to the store listing on moderator-approve and is re-synced from the manifest on every subsequent approved version; remove the key and the link is cleared. This is NOT your app's internal Civitai repository — it is a link you publish. Must be an `https://` URL, carrying no embedded credentials and no port, whose host is EXACTLY one of github.com, gitlab.com or codeberg.org (an exact-host allowlist — `www.github.com`, `gist.github.com` and `raw.githubusercontent.com` are all rejected), and whose path is exactly `/<owner>/<repo>`, the repository ROOT (a deep link such as `/owner/repo/tree/main` is rejected). A trailing `/` or `.git`, a query string and a fragment are accepted and STRIPPED — the stored value is normalised to `https://<host>/<owner>/<repo>`. Capped at 200 characters, kept in lockstep with MAX_REPOSITORY_URL_LENGTH in src/server/schema/blocks/external-app.schema.ts (a drift-guard test enforces equality, and enforces that this description names exactly the hosts REPOSITORY_HOST_ALLOWLIST contains). NOTE: as with `tagline`, the server measures the TRIMMED string while this maxLength counts the raw one, so the LENGTH bound here is never looser than the server's. The `pattern`, however, is a coarse SHAPE check and NOT the whole rule, so unlike `tagline` this field CAN pass local validation and still be rejected by the server's manifest validation. The server additionally requires each of the two path segments to begin with an ASCII letter or digit and to contain only letters, digits, `.`, `-` and `_`, and it strips a trailing `.git` BEFORE applying that test. Values such as a repository segment that is only `.git`, one starting with a dash, one containing a percent-escape, and one containing a non-ASCII character all match this pattern and are refused by the server. The pattern is deliberately left coarse rather than tightened: the CLI and the starter templates byte-mirror this file, and a stricter regex would be a compatibility change for every vendored copy. Treat passing local validation as necessary, not sufficient — `validateRepositoryUrl` in src/server/schema/blocks/external-app.schema.ts is authoritative.",
       "minLength": 1,
       "maxLength": 200,
       "pattern": "^https://(github\\.com|gitlab\\.com|codeberg\\.org)/[^/]+/[^/]+/?$"
@@ -72,7 +72,7 @@
     },
     "auth": {
       "type": "string",
-      "description": "Which credential the host hands the block: \"block-token\" (default when omitted) is the block-scoped JWT; \"oauth\" asks for an opaque OAuth access token for the block's own OauthClient, which ordinary /api/v1 routes accept as a viewer bearer. Minting it is gated on a server flag that is not generally enabled, and also requires a signed-in viewer and a declared \"user:read:self\" scope; when any of those is unmet the host hands back a block JWT instead of failing, so branch on the token kind the host reports rather than on this field. An OAuth token is refused by the postMessage bridge procedures, which verify a block JWT only, and declaring \"oauth\" alongside any \"apps:storage:*\" scope is refused at submit time.",
+      "description": "Which credential the host hands the block: \"block-token\" (default when omitted) is the block-scoped JWT; \"oauth\" asks for an opaque OAuth access token for the block's own OauthClient, which ordinary /api/v1 routes accept as a viewer bearer. Minting it is gated on a server flag that is not generally enabled, and also requires a signed-in viewer and a declared \"user:read:self\" scope; when any of those is unmet the host hands back a block JWT instead of failing, so branch on the token kind the host reports rather than on this field. An OAuth token is refused by the postMessage bridge procedures, which verify a block JWT only, and a manifest declaring \"oauth\" alongside any \"apps:storage:*\" scope is rejected by manifest validation.",
       "enum": ["block-token", "oauth"]
     },
     "trustTier": {
@@ -253,7 +253,7 @@
           },
           "priceBuzz": {
             "type": "integer",
-            "description": "Price in whole Buzz. Buzz has no sub-unit, so this must be a whole number, and the minimum is 2 rather than 1 because the app owner's 70% share is floored — a 1 Buzz item would earn its owner nothing, permanently. Capped so a single purchase can never drain an account; a viewer also has a daily ceiling across every app they have installed, so a purchase can be refused with a clean 4xx even at a legal price. Both bounds are kept in lockstep with BLOCK_GOOD_MIN_PRICE_BUZZ / BLOCK_GOOD_MAX_PRICE_BUZZ in src/shared/constants/block-goods.constants.ts by a drift-guard test. \u26a0\ufe0f THE MAXIMUM HERE IS THE WIDEST ANY KIND MAY CHARGE, NOT THE LIMIT FOR YOUR GOOD: a good with kind \"app_unlock\" is capped at 5000 Buzz by the platform validator, which this schema deliberately does not restate (it declares that validator authoritative). See the `kind` description. A value above that validates offline and is rejected at submit.",
+            "description": "Price in whole Buzz. Buzz has no sub-unit, so this must be a whole number, and the minimum is 2 rather than 1 because the app owner's 70% share is floored — a 1 Buzz item would earn its owner nothing, permanently. Capped so a single purchase can never drain an account; a viewer also has a daily ceiling across every app they have installed, so a purchase can be refused with a clean 4xx even at a legal price. Both bounds are kept in lockstep with BLOCK_GOOD_MIN_PRICE_BUZZ / BLOCK_GOOD_MAX_PRICE_BUZZ in src/shared/constants/block-goods.constants.ts by a drift-guard test. \u26a0\ufe0f THE MAXIMUM HERE IS THE WIDEST ANY KIND MAY CHARGE, NOT THE LIMIT FOR YOUR GOOD: a good with kind \"app_unlock\" is capped at 5000 Buzz by the platform validator, which this schema deliberately does not restate (it declares that validator authoritative). See the `kind` description. A value above that validates offline and is rejected by the server's manifest validation.",
             "minimum": 2,
             "maximum": 50000
           },