@civitai/app-sdk 0.55.0 → 0.56.1

package/dist/blocks/types.d.ts

@@ -1453,8 +1453,24 @@ export interface BlockManifestGood {
      * 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.
+     *
+     * 🔴 `app_unlock` carries THREE extra rules the platform validator enforces and
+     * this schema does not express: `priceBuzz` at most 5000 (not the 50000 the
+     * `priceBuzz` bound allows), at most ONE `app_unlock` good per manifest, and a
+     * mandatory `justification`. Local validation passing is necessary, not
+     * sufficient — see the canonical schema's `kind` description.
      */
     kind?: 'good' | 'app_unlock';
+    /**
+     * Why this good exists, shown to the moderator at review and never to the
+     * viewer. REQUIRED when `kind` is `'app_unlock'`: adding an unlock turns a free
+     * app into a paid one, and because an unlock does not require the sensitive
+     * `goods:purchase:self` scope, this is what makes that a reviewed decision
+     * rather than a diff nobody was pointed at. Optional for an ordinary good.
+     * Review metadata only — unlike `payload` it is never copied onto an
+     * entitlement, and the platform does not verify the claim. At most 500 chars.
+     */
+    justification?: string;
     /** Opaque app payload, carried verbatim onto the entitlement. Never interpreted by the platform. */
     payload?: Record<string, unknown>;
 }

package/package.json

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

@@ -252,15 +252,21 @@
           },
           "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.",
+            "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.",
             "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.",
+            "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; the ACCESS GATE is a later change that will read this value, so today an app_unlock entitlement is recorded like any other and the platform does not yet refuse entry on it. Declaring it is NOT free, however, and it is not merely a label: set it only when you intend to charge for access. THREE EXTRA RULES APPLY TO \"app_unlock\" AND ARE ENFORCED BY THE PLATFORM VALIDATOR, NOT BY THIS SCHEMA (which declares that validator authoritative): priceBuzz may be at most 5000 Buzz, not the 50000 the priceBuzz bound below allows — an unlock is bought before the viewer has used the app, so it is capped at the same ceiling as a single Buzz tip and at the smallest Buzz top-up ($5); at most ONE app_unlock good may be declared per manifest, so \"is this viewer admitted?\" has exactly one answer; and the good MUST carry a `justification`, because adding one turns a free app into a paid app and a moderator has to be told why.",
             "enum": ["good", "app_unlock"]
           },
+          "justification": {
+            "type": "string",
+            "description": "Why this good exists, shown to the moderator at review and never to the viewer. REQUIRED when kind is \"app_unlock\", because adding an unlock means your app starts charging for access and a moderator has to be told why. Note that declaring any `goods` catalog ALSO requires the `goods:purchase:self` scope — including a catalog whose only entry is an app_unlock — so do not read this field as a substitute for that scope. It exists because the scope is declared once and does not change when a later version adds an unlock: an app that already sells ordinary items can start charging for admission without its permission set moving at all, and this is what makes that visible at review. Optional for an ordinary good. Review metadata only: unlike `payload` it is never copied onto an entitlement, and the platform records your claim without verifying it. The server measures the TRIMMED length, so this maxLength is never more permissive than the server.",
+            "minLength": 1,
+            "maxLength": 500
+          },
           "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."