@civitai/app-sdk 0.51.1 → 0.52.0

package/README.md

@@ -134,7 +134,7 @@ interface BlockInitPayload {
 
 | Export | What |
 |---|---|
-| `BLOCK_SCOPES` / `BLOCK_SCOPE_PATTERN` | The 15 known block scope strings (the authoritative enum the canonical schema validates `scopes` against) + the `domain:verb:target` format-helper regex. A scope is valid only if it's a member of `BLOCK_SCOPES`, matching the [canonical schema](https://civitai.com/schemas/app-block/v1.json). |
+| `BLOCK_SCOPES` / `BLOCK_SCOPE_PATTERN` | Every known block scope string (the authoritative enum the canonical schema validates `scopes` against) + the `domain:verb:target` format-helper regex. Read the current set from `BLOCK_SCOPES` itself — scopes are added and retired, so no count is quoted here. A scope is valid only if it's a member of `BLOCK_SCOPES`, matching the [canonical schema](https://civitai.com/schemas/app-block/v1.json). |
 | `isMessage(data, type)` | Discriminator-only message narrowing (see above). |
 | `isModelSlotContext(ctx)` / `isPageSlotContext(ctx)` | Runtime narrowing for the `slotId`-discriminated `BlockContext` union. Real checks on a value that crossed a `postMessage` boundary — they verify every field they assert, not just `slotId`. |
 | `isSignedIn(viewer)` | **The sign-in gate.** `isSignedIn(useBlockContext().viewer)` — do not open-code it as `viewer !== null` or `viewer?.signedIn === true`. Which of those is correct has already changed once with the host contract, and this is the one place it is decided. It reads neither `viewer.id` nor `viewer.username` (both `@deprecated`), so nothing written through it changes when those are removed. Need the identity rather than the presence? `useViewer()` — scope-gated and audited per call. |

package/dist/blocks/browsingLevel.d.ts

@@ -3,9 +3,12 @@
  *
  * The host (civitai/civitai) projects an authoritative `maxBrowsingLevel`
  * BITMASK into `BLOCK_INIT` — the max NSFW levels the surrounding color-domain
- * allows (computed server-side from `domainBrowsingCeiling(color)`). A block
- * reads it via `useDomainMaturity()` to decide whether to surface mature
- * affordances.
+ * allows (computed server-side from `domainBrowsingCeiling(color)`) — and,
+ * alongside it, the viewer-narrowed `effectiveBrowsingLevel`. A block decides
+ * whether to surface mature affordances from the PAIR, via
+ * {@link effectiveBrowsingCeiling}; `@civitai/blocks-react`'s
+ * `useDomainMaturity()` is the React wrapper over exactly that. The domain
+ * ceiling alone is not the answer — see {@link ColorDomain}.
  *
  * The per-level bit VALUES below mirror civitai/civitai's server `NsfwLevel`
  * enum. They are STABLE wire values (a level's bit never changes), so it is
@@ -44,7 +47,7 @@ export declare const SFW_LEVELS: number;
  */
 export declare const NSFW_LEVELS: number;
 /**
- * True when the domain's browsing-level ceiling permits NO NSFW content.
+ * True when the given browsing-level ceiling permits NO NSFW content.
  *
  * Derived purely from the BITMASK: SFW ⇔ the ceiling has no NSFW bits set.
  *
@@ -54,7 +57,17 @@ export declare const NSFW_LEVELS: number;
  * block must therefore treat "unknown" as SFW and hide mature affordances
  * until proven otherwise.
  *
- * @param maxBrowsingLevel the domain ceiling bitmask from `BLOCK_INIT`.
+ * ⚠ A NEGATIVE ceiling is none of those three and fails OPEN:
+ * `isSfwCeiling(-1)` is `false` and `isLevelAllowed(XXX, -1)` is `true`, because
+ * two's complement sets every bit. {@link effectiveBrowsingCeiling} guards a
+ * negative VIEWER level but not a negative DOMAIN ceiling, so the recipe does
+ * not neutralise it either. Stated rather than fixed: adding the guard is a
+ * behaviour change and belongs in its own release.
+ *
+ * @param maxBrowsingLevel the ceiling to test — WHICHEVER you pass. Named for
+ * the domain mask because that was the only ceiling when this shipped; when
+ * gating for a viewer pass {@link effectiveBrowsingCeiling}'s result instead,
+ * or this answers "is the DOMAIN SFW?" and not "may I show THIS viewer".
  * @example
  * isSfwCeiling(BrowsingLevel.PG | BrowsingLevel.PG13); // true  (green/blue)
  * isSfwCeiling(BrowsingLevel.PG | BrowsingLevel.X);     // false (mature)
@@ -62,14 +75,24 @@ export declare const NSFW_LEVELS: number;
  */
 export declare function isSfwCeiling(maxBrowsingLevel?: number | null): boolean;
 /**
- * True when a specific browsing `level` bit is permitted by the domain ceiling.
+ * True when a specific browsing `level` bit is permitted by the given ceiling.
  *
  * **Fail-closed.** A missing / null / non-finite ceiling permits ONLY SFW
  * levels (PG / PG13) — same fail-closed posture as {@link isSfwCeiling}. A
  * non-finite / non-positive `level` returns `false`.
  *
+ * ⚠ A NEGATIVE ceiling is none of those three and fails OPEN:
+ * `isSfwCeiling(-1)` is `false` and `isLevelAllowed(XXX, -1)` is `true`, because
+ * two's complement sets every bit. {@link effectiveBrowsingCeiling} guards a
+ * negative VIEWER level but not a negative DOMAIN ceiling, so the recipe does
+ * not neutralise it either. Stated rather than fixed: adding the guard is a
+ * behaviour change and belongs in its own release.
+ *
  * @param level a single `BrowsingLevel` bit (e.g. `BrowsingLevel.R`).
- * @param maxBrowsingLevel the domain ceiling bitmask from `BLOCK_INIT`.
+ * @param maxBrowsingLevel the ceiling to test — WHICHEVER you pass. Named for
+ * the domain mask because that was the only ceiling when this shipped; when
+ * gating for a viewer pass {@link effectiveBrowsingCeiling}'s result instead,
+ * or this answers what the DOMAIN permits and not what THIS viewer may see.
  * @example
  * isLevelAllowed(BrowsingLevel.R, BrowsingLevel.PG | BrowsingLevel.PG13); // false
  * isLevelAllowed(BrowsingLevel.PG13, undefined);                          // true
@@ -126,10 +149,28 @@ export declare function isLevelAllowed(level: number, maxBrowsingLevel?: number
  */
 export declare function effectiveBrowsingCeiling(maxBrowsingLevel?: number | null, effectiveBrowsingLevel?: number | null): number;
 /**
- * The color-domain a block is rendered inside, as projected by the host. The
- * SFW policy is NOT derived from this — use {@link isSfwCeiling} on the
- * accompanying `maxBrowsingLevel` mask instead. `null` / absent means the host
- * did not project a domain (treat as unknown ⇒ fail-closed SFW).
+ * The color-domain a block is rendered inside, as projected by the host.
+ * Informational ONLY — the SFW policy is server-side, and this string is not
+ * it. `null` / absent means the host did not project a domain (treat as
+ * unknown ⇒ fail-closed SFW).
+ *
+ * 🔴 Never gate on this string, and never on `maxBrowsingLevel` alone. Resolve
+ * the ceiling with {@link effectiveBrowsingCeiling}, then test it with
+ * {@link isSfwCeiling} or {@link isLevelAllowed}:
+ *
+ * ```ts
+ * const eff = effectiveBrowsingCeiling(maxBrowsingLevel, effectiveBrowsingLevel);
+ * // 🔴 OPPOSITE POLARITIES — do not copy these two lines as a uniform pair.
+ * if (isSfwCeiling(eff)) hideMatureAffordances();     // true = SFW  ⇒ HIDE
+ * if (isLevelAllowed(BrowsingLevel.R, eff)) showR();  // true = allowed ⇒ SHOW
+ * ```
+ *
+ * This docblock used to say *"use `isSfwCeiling` on the accompanying
+ * `maxBrowsingLevel` mask instead"*. The predicate was never the problem — both
+ * predicates take WHATEVER CEILING YOU PASS — the problem was passing the
+ * domain one, which is identical for every viewer on `civitai.red` including
+ * one whose own NSFW setting is off, so it cannot answer "may I show THIS
+ * viewer mature content".
  */
 export type ColorDomain = 'green' | 'blue' | 'red';
 //# sourceMappingURL=browsingLevel.d.ts.map

package/dist/blocks/browsingLevel.js

@@ -3,9 +3,12 @@
  *
  * The host (civitai/civitai) projects an authoritative `maxBrowsingLevel`
  * BITMASK into `BLOCK_INIT` — the max NSFW levels the surrounding color-domain
- * allows (computed server-side from `domainBrowsingCeiling(color)`). A block
- * reads it via `useDomainMaturity()` to decide whether to surface mature
- * affordances.
+ * allows (computed server-side from `domainBrowsingCeiling(color)`) — and,
+ * alongside it, the viewer-narrowed `effectiveBrowsingLevel`. A block decides
+ * whether to surface mature affordances from the PAIR, via
+ * {@link effectiveBrowsingCeiling}; `@civitai/blocks-react`'s
+ * `useDomainMaturity()` is the React wrapper over exactly that. The domain
+ * ceiling alone is not the answer — see {@link ColorDomain}.
  *
  * The per-level bit VALUES below mirror civitai/civitai's server `NsfwLevel`
  * enum. They are STABLE wire values (a level's bit never changes), so it is
@@ -42,7 +45,7 @@ export const SFW_LEVELS = BrowsingLevel.PG | BrowsingLevel.PG13;
  */
 export const NSFW_LEVELS = BrowsingLevel.R | BrowsingLevel.X | BrowsingLevel.XXX;
 /**
- * True when the domain's browsing-level ceiling permits NO NSFW content.
+ * True when the given browsing-level ceiling permits NO NSFW content.
  *
  * Derived purely from the BITMASK: SFW ⇔ the ceiling has no NSFW bits set.
  *
@@ -52,7 +55,17 @@ export const NSFW_LEVELS = BrowsingLevel.R | BrowsingLevel.X | BrowsingLevel.XXX
  * block must therefore treat "unknown" as SFW and hide mature affordances
  * until proven otherwise.
  *
- * @param maxBrowsingLevel the domain ceiling bitmask from `BLOCK_INIT`.
+ * ⚠ A NEGATIVE ceiling is none of those three and fails OPEN:
+ * `isSfwCeiling(-1)` is `false` and `isLevelAllowed(XXX, -1)` is `true`, because
+ * two's complement sets every bit. {@link effectiveBrowsingCeiling} guards a
+ * negative VIEWER level but not a negative DOMAIN ceiling, so the recipe does
+ * not neutralise it either. Stated rather than fixed: adding the guard is a
+ * behaviour change and belongs in its own release.
+ *
+ * @param maxBrowsingLevel the ceiling to test — WHICHEVER you pass. Named for
+ * the domain mask because that was the only ceiling when this shipped; when
+ * gating for a viewer pass {@link effectiveBrowsingCeiling}'s result instead,
+ * or this answers "is the DOMAIN SFW?" and not "may I show THIS viewer".
  * @example
  * isSfwCeiling(BrowsingLevel.PG | BrowsingLevel.PG13); // true  (green/blue)
  * isSfwCeiling(BrowsingLevel.PG | BrowsingLevel.X);     // false (mature)
@@ -65,14 +78,24 @@ export function isSfwCeiling(maxBrowsingLevel) {
     return (maxBrowsingLevel & NSFW_LEVELS) === 0;
 }
 /**
- * True when a specific browsing `level` bit is permitted by the domain ceiling.
+ * True when a specific browsing `level` bit is permitted by the given ceiling.
  *
  * **Fail-closed.** A missing / null / non-finite ceiling permits ONLY SFW
  * levels (PG / PG13) — same fail-closed posture as {@link isSfwCeiling}. A
  * non-finite / non-positive `level` returns `false`.
  *
+ * ⚠ A NEGATIVE ceiling is none of those three and fails OPEN:
+ * `isSfwCeiling(-1)` is `false` and `isLevelAllowed(XXX, -1)` is `true`, because
+ * two's complement sets every bit. {@link effectiveBrowsingCeiling} guards a
+ * negative VIEWER level but not a negative DOMAIN ceiling, so the recipe does
+ * not neutralise it either. Stated rather than fixed: adding the guard is a
+ * behaviour change and belongs in its own release.
+ *
  * @param level a single `BrowsingLevel` bit (e.g. `BrowsingLevel.R`).
- * @param maxBrowsingLevel the domain ceiling bitmask from `BLOCK_INIT`.
+ * @param maxBrowsingLevel the ceiling to test — WHICHEVER you pass. Named for
+ * the domain mask because that was the only ceiling when this shipped; when
+ * gating for a viewer pass {@link effectiveBrowsingCeiling}'s result instead,
+ * or this answers what the DOMAIN permits and not what THIS viewer may see.
  * @example
  * isLevelAllowed(BrowsingLevel.R, BrowsingLevel.PG | BrowsingLevel.PG13); // false
  * isLevelAllowed(BrowsingLevel.PG13, undefined);                          // true

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/messages.d.ts

@@ -150,8 +150,21 @@ export interface BlockInitPayload {
     /**
      * The color-domain the block is rendered inside (`green` | `blue` | `red`),
      * or `null` when the host did not resolve one. Informational ONLY — the SFW
-     * policy is server-side; derive "is this SFW?" from {@link maxBrowsingLevel}
-     * (via `isSfwCeiling` / `useDomainMaturity`), never from this string.
+     * policy is server-side; never gate on this string. Resolve the ceiling
+     * first, then test it — in any runtime:
+     *
+     * ```ts
+     * const eff = effectiveBrowsingCeiling(maxBrowsingLevel, effectiveBrowsingLevel);
+     * // 🔴 OPPOSITE POLARITIES — do not copy these two lines as a uniform pair.
+     * if (isSfwCeiling(eff)) hideMatureAffordances();     // true = SFW  ⇒ HIDE
+     * if (isLevelAllowed(BrowsingLevel.R, eff)) showR();  // true = allowed ⇒ SHOW
+     * ```
+     *
+     * 🔴 `effectiveBrowsingCeiling` returns a BITMASK, not a boolean — an SFW
+     * ceiling is `3`, which is truthy, so branching on it directly shows mature
+     * content to a viewer who may not see it. It needs one of the two predicates
+     * above. In React, `@civitai/blocks-react`'s `useDomainMaturity()` returns
+     * `isSfw` / `isLevelAllowed` already composed this way.
      *
      * Sent by civitai/civitai PR #2670. A host that predates it omits this field
      * (reads `undefined`).
@@ -161,8 +174,9 @@ export interface BlockInitPayload {
      * Authoritative browsing-level BITMASK = the max NSFW levels the domain
      * allows, computed server-side from `domainBrowsingCeiling(color)` (green/
      * blue → SFW, red → all). Bits mirror the server `NsfwLevel` (see
-     * `browsingLevel.ts`). A block reads this to decide whether to surface mature
-     * affordances — `isSfwCeiling(maxBrowsingLevel)` is the canonical test.
+     * `browsingLevel.ts`). `isSfwCeiling(maxBrowsingLevel)` answers "is this
+     * DOMAIN SFW?" — not "may I show THIS viewer mature content"; for that, see
+     * the warning below and {@link effectiveBrowsingLevel}.
      *
      * Sent by civitai/civitai PR #2670. A host that predates it omits this field
      * (reads `undefined`); the SDK fail-closes to SFW when it is absent.
@@ -193,9 +207,13 @@ export interface BlockInitPayload {
      *      WIDER than the domain permits and is not permission for anything.
      *
      * ADDITIVE + OPTIONAL. A host that predates it omits the field, in which case
-     * `useDomainMaturity()` falls back to `maxBrowsingLevel` — i.e. exactly the
-     * behaviour that host already had. Read it through the hook rather than
-     * directly, so the fallback and the fail-closed defaults are applied for you.
+     * the ceiling falls back to {@link maxBrowsingLevel} — i.e. exactly the
+     * behaviour that host already had. Do not read this field directly: pass it
+     * through `effectiveBrowsingCeiling`, which applies that fallback and the
+     * fail-closed defaults for you. `@civitai/blocks-react`'s
+     * `useDomainMaturity()` is the React wrapper over the same thing — it is one
+     * way to get this right, not the only one, since this module is
+     * runtime-agnostic and two of the starters ship without React.
      */
     effectiveBrowsingLevel?: number;
 }

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];
@@ -33,7 +35,7 @@ export type BlockScope = (typeof BLOCK_SCOPES)[BlockScopeKey];
  *
  * NOTE: this regex is **not** the authoritative validity contract. The
  * canonical manifest schema (https://civitai.com/schemas/app-block/v1.json)
- * validates `scopes` by MEMBERSHIP in a fixed enum — i.e. the 12 values in
+ * validates `scopes` by MEMBERSHIP in a fixed enum — i.e. exactly the values in
  * {@link BLOCK_SCOPES}. `defineBlock` therefore gates on membership in
  * `BLOCK_SCOPES`; this pattern is kept only as a FORMAT HEURISTIC to give a
  * pointed error message (e.g. distinguishing a malformed/PascalCase scope from

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
@@ -55,7 +69,7 @@ export const BLOCK_SCOPES = {
  *
  * NOTE: this regex is **not** the authoritative validity contract. The
  * canonical manifest schema (https://civitai.com/schemas/app-block/v1.json)
- * validates `scopes` by MEMBERSHIP in a fixed enum — i.e. the 12 values in
+ * validates `scopes` by MEMBERSHIP in a fixed enum — i.e. exactly the values in
  * {@link BLOCK_SCOPES}. `defineBlock` therefore gates on membership in
  * `BLOCK_SCOPES`; this pattern is kept only as a FORMAT HEURISTIC to give a
  * pointed error message (e.g. distinguishing a malformed/PascalCase scope from

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/dist/safe-storage/index.d.ts

@@ -1,6 +1,12 @@
 /**
  * `@civitai/app-sdk/safe-storage` — survive an opaque-origin sandbox.
  *
+ * 🔴 `@civitai/sdk`'s `src/safe-storage/index.ts` is a deliberate independent
+ * COPY of this file (the successor must not depend on its predecessor). The two
+ * bodies are held byte-identical modulo comments by
+ * `tests/guards/safe-storage-copy-parity.test.mjs`, so a fix here goes red
+ * until it is applied there too.
+ *
  * Civitai Apps run in an iframe sandboxed as `allow-scripts allow-forms`,
  * deliberately WITHOUT `allow-same-origin`. The document therefore has an
  * **opaque origin**, and there is no origin to key web storage against, so the
@@ -54,8 +60,19 @@ export declare function createMemoryStorage(): Storage;
  * with an in-memory `Storage`, so third-party code that touches it unguarded
  * cannot throw.
  *
- * - **No-op where storage works.** A healthy `Storage` is never replaced, and
- *   its contents are never touched.
+ * - **No-op where storage works — but not a no-TOUCH.** A healthy `Storage` is
+ *   never replaced and its contents are unchanged, but it *is* written to:
+ *   classifying it means a real round trip, so each of `localStorage` and
+ *   `sessionStorage` gets `setItem('__civitai_app_sdk_storage_probe__', '1')`
+ *   immediately followed by `removeItem`. MEASURED against the built artifact
+ *   with instrumented healthy stores: exactly those four operations, the store
+ *   objects not replaced, contents identical before and after. Per the Web
+ *   Storage spec every one of those writes queues a `storage` event in the
+ *   *other* documents that share the store, so at a REAL origin a cross-tab
+ *   listener that does not filter by key sees spurious events (the two
+ *   `localStorage` writes are the ones another tab receives). At the opaque
+ *   origin this module exists for there is no other same-origin document, so
+ *   there is nothing to receive them.
  * - **No-op where storage is absent** (Node/SSR/workers). Nothing is invented.
  * - **Never loses readable data.** When the old store reads but refuses writes
  *   (full / disabled), its entries are copied into the fallback first, so the

package/dist/safe-storage/index.js

@@ -1,6 +1,12 @@
 /**
  * `@civitai/app-sdk/safe-storage` — survive an opaque-origin sandbox.
  *
+ * 🔴 `@civitai/sdk`'s `src/safe-storage/index.ts` is a deliberate independent
+ * COPY of this file (the successor must not depend on its predecessor). The two
+ * bodies are held byte-identical modulo comments by
+ * `tests/guards/safe-storage-copy-parity.test.mjs`, so a fix here goes red
+ * until it is applied there too.
+ *
  * Civitai Apps run in an iframe sandboxed as `allow-scripts allow-forms`,
  * deliberately WITHOUT `allow-same-origin`. The document therefore has an
  * **opaque origin**, and there is no origin to key web storage against, so the
@@ -272,8 +278,19 @@ function seedFrom(existing, into) {
  * with an in-memory `Storage`, so third-party code that touches it unguarded
  * cannot throw.
  *
- * - **No-op where storage works.** A healthy `Storage` is never replaced, and
- *   its contents are never touched.
+ * - **No-op where storage works — but not a no-TOUCH.** A healthy `Storage` is
+ *   never replaced and its contents are unchanged, but it *is* written to:
+ *   classifying it means a real round trip, so each of `localStorage` and
+ *   `sessionStorage` gets `setItem('__civitai_app_sdk_storage_probe__', '1')`
+ *   immediately followed by `removeItem`. MEASURED against the built artifact
+ *   with instrumented healthy stores: exactly those four operations, the store
+ *   objects not replaced, contents identical before and after. Per the Web
+ *   Storage spec every one of those writes queues a `storage` event in the
+ *   *other* documents that share the store, so at a REAL origin a cross-tab
+ *   listener that does not filter by key sees spurious events (the two
+ *   `localStorage` writes are the ones another tab receives). At the opaque
+ *   origin this module exists for there is no other same-origin document, so
+ *   there is nothing to receive them.
  * - **No-op where storage is absent** (Node/SSR/workers). Nothing is invented.
  * - **Never loses readable data.** When the old store reads but refuses writes
  *   (full / disabled), its entries are copied into the fallback first, so the

package/package.json

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

@@ -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\" opts the block into a real OAuth access token for its own OauthClient, accepted unchanged by /api/v1, the orchestrator and the MCP.",
+      "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.",
       "enum": ["block-token", "oauth"]
     },
     "trustTier": {
@@ -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.",