@civitai/app-sdk 0.51.2 → 0.52.0

package/dist/blocks/index.d.ts

@@ -77,5 +77,5 @@ 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, 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, BlockTextToImageParams, BlockWorkflowSnapshot, 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, } 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, BlockTextToImageParams, BlockWorkflowSnapshot, 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, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/scopes.d.ts

@@ -24,6 +24,8 @@ export declare const BLOCK_SCOPES: {
     readonly COLLECTIONS_WRITE_SELF: "collections:write:self";
     readonly COLLECTIONS_READ_PRIVATE: "collections:read:private";
     readonly POSTS_WRITE_SELF: "posts:write:self";
+    readonly GOODS_READ_SELF: "goods:read:self";
+    readonly GOODS_PURCHASE_SELF: "goods:purchase:self";
 };
 export type BlockScopeKey = keyof typeof BLOCK_SCOPES;
 export type BlockScope = (typeof BLOCK_SCOPES)[BlockScopeKey];

package/dist/blocks/scopes.js

@@ -48,6 +48,20 @@ export const BLOCK_SCOPES = {
     // per-post confirm rendering the SERVER'S resolution of the request, and the
     // server re-runs every guard.
     POSTS_WRITE_SELF: 'posts:write:self',
+    // goods:* — the DIGITAL GOODS rail (civitai/civitai#5171): the platform sells
+    // a manifest-declared entitlement to the viewer for Buzz, on the app's behalf.
+    // These were live on the SERVER and in the canonical schema while absent here,
+    // so `defineBlock` rejected both and no app scaffolded from this repo could
+    // DECLARE them — the hooks that call them were unreachable. Found by the
+    // round-0 reachability question on app-starters#489.
+    //
+    // `goods:read:self` is CONSENT-EXEMPT by design: the read is scoped
+    // server-side to the calling app's own appBlockId, so it can only ever return
+    // what that app itself sold and there is no third-party data to consent to.
+    // `goods:purchase:self` is CONSENT-GATED — money out of the viewer's balance
+    // always needs an explicit grant. Do not collapse the two.
+    GOODS_READ_SELF: 'goods:read:self',
+    GOODS_PURCHASE_SELF: 'goods:purchase:self',
 };
 /**
  * Format helper for the block-scope shape — 3 OR 4 colon-separated lowercase

package/dist/blocks/types.d.ts

@@ -1402,6 +1402,40 @@ export interface ManifestPreview {
     description: string;
     screenshots?: string[];
 }
+/**
+ * One entry of a manifest's `goods[]`. Mirrors the canonical schema exactly;
+ * `id`, `title` and `priceBuzz` are required there and so are they here.
+ *
+ * 🔴 DECLARED BEFORE `BlockManifestV1`'S DOCBLOCK ON PURPOSE. Inserting an
+ * interface BETWEEN a docblock and the declaration it documents does not just
+ * look untidy — `tsc` emits both comments onto THIS interface in
+ * `dist/blocks/types.d.ts` and leaves `BlockManifestV1` undocumented, so the
+ * published types told a reader that "only `blockId`, `version`, `name`,
+ * `contentRating` and `scopes` are required" about a type with three fields and
+ * different requirements. Keep any new sibling above this comment or below
+ * `BlockManifestV1`.
+ */
+export interface BlockManifestGood {
+    /** Lowercase alphanumeric with `-`/`_`, at most 64 chars. Colon-free, because it is composed into a redis key and a ledger external id. */
+    id: string;
+    /** At most 80 chars. */
+    title: string;
+    /** At most 500 chars. */
+    description?: string;
+    /**
+     * Whole Buzz, minimum 2 — at a price of 1 the owner's floored 70% share is
+     * ZERO, so the app would sell an item and earn nothing from it, permanently.
+     */
+    priceBuzz: number;
+    /**
+     * What the entitlement grants. `app_unlock` marks a one-time unlock of the app
+     * itself; it is RECORDED identically today and the platform does not yet act
+     * on it, so declaring it buys nothing unless you intend that later behaviour.
+     */
+    kind?: 'good' | 'app_unlock';
+    /** Opaque app payload, carried verbatim onto the entitlement. Never interpreted by the platform. */
+    payload?: Record<string, unknown>;
+}
 /**
  * v1 manifest shape. Mirrors `schemas/app-block/v1.json` — keep them in sync.
  *
@@ -1452,6 +1486,23 @@ export interface BlockManifestV1 {
      * with the canonical schema's `scopeJustifications` (civitai #3195).
      */
     scopeJustifications?: Record<string, string>;
+    /**
+     * Optional DIGITAL GOODS catalog — entitlements the platform sells to a viewer
+     * for Buzz on this app's behalf. Manifest-governed and REVIEW-GATED: the
+     * catalog a moderator approves is the catalog that can be sold, and changing a
+     * price means shipping a new version and being re-reviewed.
+     *
+     * Declaring goods is not by itself permission to sell — the manifest must also
+     * carry `goods:purchase:self` in `scopes`.
+     *
+     * 🔴 THE TYPE WAS ABSENT WHILE THE SCHEMA PROPERTY EXISTED, so `defineBlock`'s
+     * documented inline-literal form rejected a `goods` declaration with TS2353
+     * even though Ajv accepted the same manifest from a JSON file. Nothing could
+     * catch that: there is a vendored-schema↔`BLOCK_SCOPES` cross-check but no
+     * schema-properties↔interface-keys check, and the repo's manifest tests cast.
+     * Kept in lockstep with the canonical schema's `goods`.
+     */
+    goods?: BlockManifestGood[];
     /** Optional; the canonical declares no required sub-field. */
     iframe?: ManifestIframe;
     /** Full-page surface descriptor (W10). */

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, BlockManifestV1 } from '../blocks/types.js';
+export type { 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.51.2",
+  "version": "0.52.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

@@ -99,13 +99,15 @@
           "collections:read:self",
           "collections:write:self",
           "collections:read:private",
-          "posts:write:self"
+          "posts:write:self",
+          "goods:read:self",
+          "goods:purchase:self"
         ]
       }
     },
     "scopeJustifications": {
       "type": "object",
-      "description": "Per-scope justification: a map of scope-id → free-text rationale explaining WHY the app needs that permission, shown to the moderator during review. REQUIRED for SENSITIVE scopes — any declared scope that can spend or read the viewer's Buzz, read the viewer's private data, or write data other users see (e.g. `ai:write:budgeted`, `social:tip:self`, `buzz:read:self`, `collections:read:private`, `apps:storage:shared:write`, `posts:write:self`) MUST carry a non-empty justification here, or the manifest is rejected at submit time. OPTIONAL for non-sensitive scopes — omit those and the manifest stays valid. Every key MUST be a scope also present in `scopes` (justifications for scopes you don't request are rejected). Each value is a non-empty string of at most 500 characters. The requirement is enforced imperatively by the manifest validator (not expressed as JSON-Schema conditionals here). NOTE: the justification captures the developer's STATED rationale only; the platform does not verify the truth of the claims.",
+      "description": "Per-scope justification: a map of scope-id → free-text rationale explaining WHY the app needs that permission, shown to the moderator during review. REQUIRED for SENSITIVE scopes — any declared scope that can spend or read the viewer's Buzz, read the viewer's private data, or write data other users see (e.g. `ai:write:budgeted`, `social:tip:self`, `goods:purchase:self`, `buzz:read:self`, `collections:read:private`, `apps:storage:shared:write`, `posts:write:self`) MUST carry a non-empty justification here, or the manifest is rejected at submit time. OPTIONAL for non-sensitive scopes — omit those and the manifest stays valid. Every key MUST be a scope also present in `scopes` (justifications for scopes you don't request are rejected). Each value is a non-empty string of at most 500 characters. The requirement is enforced imperatively by the manifest validator (not expressed as JSON-Schema conditionals here). NOTE: the justification captures the developer's STATED rationale only; the platform does not verify the truth of the claims.",
       "additionalProperties": {
         "type": "string",
         "minLength": 1,
@@ -221,6 +223,51 @@
         }
       }
     },
+    "goods": {
+      "type": "array",
+      "description": "Optional DIGITAL GOODS catalog — entitlements the platform sells to a viewer on your app's behalf, for Buzz. Manifest-governed and REVIEW-GATED: the catalog a moderator approves is the catalog that can be sold, and changing a price means shipping a new version and being re-reviewed. The platform owns the ledger (who bought what, when, at what price, and its refund state); the good's MEANING is your app's business — read the viewer's entitlements from GET /api/v1/blocks/entitlements and keep the semantics in your own app storage. Declaring goods does not by itself let you sell: the app must also declare the `goods:purchase:self` scope (and `goods:read:self` to read entitlements back), and the viewer must consent. Sales split platform 30% / app owner 70%, paid immediately. Kept in lockstep with the bounds in src/shared/constants/block-goods.constants.ts (a drift-guard test enforces equality); the imperative validator in that same module is authoritative.",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "priceBuzz"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable identifier for this good, unique within the manifest. This is what a purchase and an entitlement are keyed by, so changing it in a later version orphans every entitlement already granted under the old id. Lowercase letters, digits, - and _, starting with a letter or digit.",
+            "minLength": 1,
+            "maxLength": 64,
+            "pattern": "^[a-z0-9][a-z0-9_-]*$"
+          },
+          "title": {
+            "type": "string",
+            "description": "Human-readable name shown to the viewer at purchase. Non-empty; the server measures the TRIMMED length, so this maxLength is never more permissive than the server.",
+            "minLength": 1,
+            "maxLength": 80
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional one-paragraph explanation of what the viewer gets.",
+            "maxLength": 500
+          },
+          "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.",
+            "minimum": 2,
+            "maximum": 50000
+          },
+          "kind": {
+            "type": "string",
+            "description": "What the entitlement grants, from the platform's point of view. \"good\" (the default) is an ordinary in-app purchase the platform records and does not interpret. \"app_unlock\" marks a one-time unlock of the app itself; it is RECORDED IDENTICALLY today and the platform does NOT yet act on it — the paid-app access gate is a later change that reads this value. Declaring it now buys nothing, so leave it unset unless you intend that later behaviour.",
+            "enum": ["good", "app_unlock"]
+          },
+          "payload": {
+            "type": "object",
+            "description": "Optional OPAQUE payload copied verbatim onto the entitlement at purchase and handed back to your app unchanged. The platform never reads or interprets it. It is manifest-sourced rather than client-supplied precisely so that what an entitlement carries is something a moderator saw. Must serialize to at most 2048 bytes."
+          }
+        }
+      }
+    },
     "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.",