@civitai/sdk 0.14.1 → 0.16.0

package/README.md

@@ -96,6 +96,7 @@ the refusal sits at the surface, not at startup:
 |---|---|
 | `app.storage.*` | Works. This is the token app storage requires |
 | `app.sharedStorage.*` | Reads work, anonymous included. Writes additionally need a signed-in viewer past the server's minimum-trust gate, so a `403` there is about the VIEWER, not the token |
+| `app.subListings.*` | Works for a signed-in viewer when the token carries `apps:store:items:write` — never in a dev-token, dev-tunnel or review session |
 | `app.site` on `blocks/…` | Works. These are the routes the token was minted for |
 | `app.site.get('me')` and the rest of `/api/v1` | The API's own 401/403, with `auth: "oauth"` named in the message. `status` and `body` are untouched, so a caller can still branch on them |
 | `app.workflows.*` | Works. Generation for a block goes here, with the `ai:write:budgeted` scope |
@@ -273,7 +274,12 @@ Anonymous viewers may read `shared` collections and nothing else
 (`sign_in_required`). Creating or editing a document in a viewer-written shared
 collection needs the consent-gated `apps:storage:publish`; deleting your own, marks
 and counters need only `apps:storage`. Shared writes pass a minimum-trust gate and
-moderation. Only phase-one operations exist: no batch writes, change feed, TTL or
+moderation. A shared `write: "own"` collection whose manifest declares
+`ownedModelVersions` (pointers such as `/workflow/modelVersionId`) refuses a create
+or `put` whose `data` holds, at one of those fields, anything but a model version
+the viewer owns: `resource_not_owned` (403), `details.pointer` naming the field,
+before moderation and before any write budget. An absent field is allowed;
+ownership is checked only when the document is written. Only phase-one operations exist: no batch writes, change feed, TTL or
 owner-written documents yet.
 
 The legacy stores below keep working, unchanged, while apps move; their methods are
@@ -428,6 +434,62 @@ an existence oracle, so do not report that as "someone else owns this". Put ever
 string other viewers will read in `title`/`body`, which the server moderates;
 `data` is unmoderated app structure.
 
+## Store sub-listings
+
+`app.subListings` publishes an item a viewer made in your app — a row they
+authored in [shared storage](#shared-storage) — as its **own App Store card**,
+under the viewer's name, badged "in ‹your app›". Three methods over
+`/api/v1/blocks/sub-listings/*`: `upsert`, `withdraw`, `mine`.
+
+```ts
+import { SubListingError } from '@civitai/sdk';
+
+try {
+  const { id, status, pendingEdit } = await app.subListings.upsert({
+    itemKey: 'preset-7f3a',   // the key of the viewer's own shared-storage row
+    title: 'Moody film portraits',
+    subPath: 'p/preset-7f3a', // opens /apps/run/<your-app-slug>/p/preset-7f3a
+    tagline: null,            // a left-out optional is CLEARED: re-send what you want to keep
+  });
+} catch (error) {
+  if (error instanceof SubListingError && error.code === 'insufficient_scope') {
+    // dev-token, dev-tunnel and review sessions never carry the scope: hide the control
+  } else throw error;
+}
+
+const { withdrawn } = await app.subListings.withdraw('preset-7f3a');
+const { items } = await app.subListings.mine(); // oldest first, with review status
+```
+
+- **`upsert` replaces the whole item, it does not patch it.** An optional that is
+  `null` or `undefined` is left out of the request, and the server stores a
+  left-out optional as empty — so an edit that sends only `title` clears the
+  item's tagline and image and resets its rating to the app's. Re-send every
+  field you want to keep.
+- **The server body is strict** — an unknown key is `400 invalid_body` — so the
+  client sends only `itemKey`, `title`, `subPath`, `tagline`, `imageId` and
+  `contentRating`, whatever else the object you pass carries. Every other rule (lengths, the `subPath` shape, the rating floor, the image
+  checks) is the server's and comes back as a refusal.
+- **A refusal is a `SubListingError`** — an `ApiError` with a typed `code`
+  (`not_enabled`, `untrusted`, `item_not_found`, `not_your_item`, `text_rejected`,
+  `image_not_public`, `image_not_yours`, `rating_too_loose`, `rate_limited`,
+  `author_cap`, `conflict`, `unavailable`, …). Branch on `code`; the message is a
+  server sentence, not UI copy. A refusal with no `code` stays a plain `ApiError`.
+  A `429`'s `Retry-After` header is not exposed.
+- **Every item waits for a moderator.** `status` is `pending`, `approved`,
+  `hidden` or `withdrawn`; an `upsert` answered `hidden` changed nothing, and the
+  app cannot lift it. Editing an approved item stages the edit
+  (`pendingEdit: true`) while the card keeps serving the approved version.
+- `withdraw` answering `withdrawn: false` is a success: nothing of the viewer's was
+  active under that key, or a moderator has hidden it.
+
+🔴 It needs the scope `apps:store:items:write` in the manifest (with a
+`scopeJustifications` entry), and that scope is consent-exempt, refused to an
+anonymous viewer, and **never minted for dev-token, dev-tunnel or review
+sessions** — so these calls only succeed from an approved version of your app,
+and Civitai must also enable your app for sub-listings (`not_enabled` until then).
+Build the publish path to degrade quietly.
+
 ## Multi-step workflows
 
 `app.workflows` is how a **block** generates. It goes through the host's
@@ -917,6 +979,13 @@ Where it differs from the server on purpose:
   not a manifest validator otherwise; `civitai app validate` is.
 - A list `nextCursor` is an opaque token, refused for any other collection, sort or
   filter than the query that issued it. Treat it as opaque against the server too.
+- It has no model versions of its own, so a collection's `ownedModelVersions` rule
+  checks writes against the viewer's `modelVersions` — the ids that viewer owns,
+  none by default (so every id is refused, as the server refuses one that is not
+  the writer's):
+  `fake.as({ viewer: { username: 'bob', modelVersions: [4317] } })`. It does not
+  model the server's ownership lookup failing (a retryable 503
+  `service_unavailable`).
 
 `fake.calls` records every request and answer. Options also cover smaller `limits`,
 `consent` (revoked scopes, or `'unavailable'`), `appStatus`, `disabled` and a custom

package/dist/app/index.d.ts

@@ -7,6 +7,7 @@ import { type SharedStorageClient } from '../shared-storage/index.js';
 import { type DocumentStorage } from '../doc-store/index.js';
 import { type SiteClient } from '../site/index.js';
 import { type StorageClient } from '../storage/index.js';
+import { type SubListingsClient } from '../sub-listings/index.js';
 import { type WorkflowsClient } from '../workflows/index.js';
 export interface AppClient {
     /**
@@ -52,6 +53,16 @@ export interface AppClient {
      * clear a server-side minimum-trust gate.
      */
     readonly sharedStorage: SharedStorageClient;
+    /**
+     * The viewer's own App Store items for this app: `upsert`, `withdraw`, `mine`
+     * over the `blocks/sub-listings/*` routes. A refusal the server explained is a
+     * `SubListingError` with a typed `code`.
+     *
+     * 🔴 Requires the block token and `apps:store:items:write`, which is never
+     * minted for dev-token, dev-tunnel or review sessions and is refused to an
+     * anonymous viewer — so build the publish path to degrade quietly.
+     */
+    readonly subListings: SubListingsClient;
     /**
      * Generation for a BLOCK: estimate, submit, watch and cancel through the
      * host's `blocks/workflows/*` routes, which price, budget and attribute the

package/dist/app/index.js

@@ -8,6 +8,7 @@ import { createSharedStorageClient, } from '../shared-storage/index.js';
 import { createDocumentStorage } from '../doc-store/index.js';
 import { createSiteClient, DEFAULT_SITE_URL } from '../site/index.js';
 import { createStorageClient } from '../storage/index.js';
+import { createSubListingsClient } from '../sub-listings/index.js';
 import { createWorkflowsClient } from '../workflows/index.js';
 /** Long enough for a slow host page; short enough that a block opened on its own says so. */
 const DEFAULT_INIT_TIMEOUT_MS = 10_000;
@@ -82,16 +83,17 @@ const OAUTH_OPT_IN = 'declare `auth: "oauth"` in block.manifest.json';
 const BLOCK_NAMESPACE = /^\/*blocks\//;
 function createAppClient(session, options, holdsBlockTokenNow = () => false, holdsOAuthTokenNow = () => false) {
     const http = (baseUrl) => createHttp({ session, baseUrl, fetch: options.fetch });
-    // One instance for all four site-hosted surfaces: the storage and workflows
-    // clients' routes live under the same base URL, so a `siteUrl` override
-    // redirects them together.
+    // One instance for every site-hosted surface: the storage, sub-listings and
+    // workflows clients' routes live under the same base URL, so a `siteUrl`
+    // override redirects them together.
     // Wrapped once, so `BLOCK_NAMESPACE` is the single place that decides where the
-    // diagnosis applies. None of the four `blocks/*` clients needs an exemption
+    // diagnosis applies. None of the five `blocks/*` clients needs an exemption
     // of its own: their routes are `blocks/app-storage/*`, `blocks/shared-storage/*`,
-    // `blocks/storage/*` and `blocks/workflows/*`, which that namespace already excludes, and
-    // `test/storage/seam.test.ts`, `test/shared-storage/seam.test.ts`,
-    // `test/doc-store/client.test.ts` and `test/workflows/seam.test.ts` pin the four
-    // `BASE` values there textually.
+    // `blocks/storage/*`, `blocks/sub-listings/*` and `blocks/workflows/*`, which that
+    // namespace already excludes, and `test/storage/seam.test.ts`,
+    // `test/shared-storage/seam.test.ts`, `test/doc-store/client.test.ts`,
+    // `test/sub-listings/sub-listings.test.ts` and `test/workflows/seam.test.ts` pin the
+    // five `BASE` values there textually.
     const siteHttp = explainApiRefusal(http(options.siteUrl ?? DEFAULT_SITE_URL), holdsBlockTokenNow);
     return {
         site: createSiteClient(siteHttp),
@@ -100,6 +102,7 @@ function createAppClient(session, options, holdsBlockTokenNow = () => false, hol
         // reference to the other.
         storage: { ...createStorageClient(siteHttp), ...createDocumentStorage(siteHttp) },
         sharedStorage: createSharedStorageClient(siteHttp),
+        subListings: createSubListingsClient(siteHttp),
         workflows: createWorkflowsClient(explainWorkflowRefusal(siteHttp, holdsOAuthTokenNow)),
         orchestration: createOrchestrationClient(refuseBlockToken(http(options.orchestrationUrl ?? DEFAULT_ORCHESTRATION_URL), holdsBlockTokenNow)),
         requestGrants: (scopes, opts) => session.requestGrants(scopes, opts),

package/dist/doc-store/fake.d.ts

@@ -25,6 +25,13 @@ export interface FakeStorageViewer {
     trusted?: boolean;
     /** `details.reason` when untrusted. Default `account_too_new`. */
     untrustedReason?: string;
+    /**
+     * Ids of the model versions whose model this viewer owns — what a collection's
+     * `ownedModelVersions` rule checks a write against. Default: none, so every id
+     * at a declared field is refused `resource_not_owned`, as the server refuses a
+     * version that is not the writer's (or does not exist).
+     */
+    modelVersions?: readonly number[];
 }
 /** Who is calling: a viewer (or `null`, anonymous) holding a token of some kind and scopes. */
 export interface FakeStorageCaller {

package/dist/doc-store/fake.js

@@ -18,10 +18,15 @@ import { createDocumentStorage } from './index.js';
  * the fake is CREATED rather than per request; and a list cursor is an opaque token
  * bound to its whole query, not the server's sort-bound keyset string.
  *
+ * A collection's `ownedModelVersions` rule is enforced; the fake has no model
+ * versions of its own, so which ones a viewer owns is `FakeStorageViewer.modelVersions`
+ * (default none).
+ *
  * NOT MODELLED: moderator hides (a hidden document reads as not found on the server;
  * nothing here hides one), moderator exemption from the scanner, the review-preview
- * namespace, and the token middleware's other refusals (revoked instance, context
- * binding, an approval read that fails).
+ * namespace, the token middleware's other refusals (revoked instance, context
+ * binding, an approval read that fails), and a failed ownership lookup (the
+ * server's retryable 503 `service_unavailable`).
  */
 // ---------------------------------------------------------------------------
 // Bounds — the server's, one copy here (the contract run pins the ones it reaches)
@@ -85,6 +90,7 @@ const STATUS = {
     not_eligible: 403,
     not_author: 403,
     write_policy: 403,
+    resource_not_owned: 403,
     not_found: 404,
     collection_not_declared: 404,
     method_not_allowed: 405,
@@ -97,6 +103,11 @@ const STATUS = {
     moderation_unavailable: 503,
     consent_unavailable: 503,
 };
+/** The manifest's `ownedModelVersions` pointer: 1 to 4 plain identifier segments. */
+const OWNED_POINTER = /^(\/[A-Za-z_][A-Za-z0-9_]{0,63}){1,4}$/u;
+const MAX_OWNED_POINTERS = 4;
+/** Postgres `integer`: the server refuses a larger id before querying for it. */
+const INT4_MAX = 2_147_483_647;
 const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 /** Declarations the platform does not serve yet, each with what to do instead. */
 const PHASED = [
@@ -144,12 +155,30 @@ function parseManifest(manifest) {
             else
                 errors.push(`${at}.indexes.${path}: type must be one of ${INDEX_TYPES.join(', ')}`);
         }
+        const ownedModelVersions = [];
+        if (raw.ownedModelVersions !== undefined) {
+            const list = raw.ownedModelVersions;
+            if (!shared || raw.write !== 'own') {
+                errors.push(`${at}.ownedModelVersions: applies only to shared collections with write "own"`);
+            }
+            else if (!Array.isArray(list) ||
+                list.length < 1 ||
+                list.length > MAX_OWNED_POINTERS ||
+                !list.every((p) => typeof p === 'string' && OWNED_POINTER.test(p)) ||
+                new Set(list).size !== list.length) {
+                errors.push(`${at}.ownedModelVersions: must be 1 to ${MAX_OWNED_POINTERS} distinct pointers such as "/workflow/modelVersionId"`);
+            }
+            else {
+                ownedModelVersions.push(...list);
+            }
+        }
         const decl = {
             visibility: raw.visibility,
             counters: shared ? names(raw.counters) : [],
             marks: shared ? names(raw.marks) : [],
             indexes,
             showAuthor: shared && raw.showAuthor === true,
+            ownedModelVersions,
         };
         if (shared && (raw.write === 'own' || raw.write === 'none'))
             decl.write = raw.write;
@@ -893,6 +922,41 @@ export function createFakeStorage(options) {
             });
         }
     }
+    /**
+     * The collection's `ownedModelVersions` rule, as the server's
+     * `doc-store-ownership.ts` applies it: a pointer that resolves to nothing is
+     * allowed; every value found must be a positive `integer` id — all of them are
+     * checked before any ownership — and then the writer's own version. One code
+     * and message for every reason, so a refusal reveals nothing about whether a
+     * version exists.
+     */
+    function assertOwnedModelVersions(decl, data, viewer) {
+        if (decl.ownedModelVersions.length === 0)
+            return;
+        const notOwned = (pointer) => refuse('resource_not_owned', 'the model version at this field is not one the author owns', { pointer });
+        const claimed = [];
+        for (const pointer of decl.ownedModelVersions) {
+            let cur = data;
+            let found = true;
+            for (const seg of pointer.split('/').slice(1)) {
+                if (!isObject(cur) || !Object.prototype.hasOwnProperty.call(cur, seg)) {
+                    found = false;
+                    break;
+                }
+                cur = cur[seg];
+            }
+            if (!found)
+                continue;
+            if (typeof cur !== 'number' || !Number.isInteger(cur) || cur < 1 || cur > INT4_MAX)
+                throw notOwned(pointer);
+            claimed.push({ pointer, id: cur });
+        }
+        const owned = new Set(viewer.modelVersions ?? []);
+        for (const { pointer, id } of claimed) {
+            if (!owned.has(id))
+                throw notOwned(pointer);
+        }
+    }
     /** The server's refusals that are ITS fault: refunded without a rejection charge. */
     const isOurFault = (err) => !(err instanceof Refusal) ||
         (err.code === 'rate_limited' ? err.details?.reason === 'contention' : ['storage_disabled', 'moderation_unavailable', 'consent_unavailable'].includes(err.code));
@@ -1032,6 +1096,11 @@ export function createFakeStorage(options) {
                         throw invalid('ifVersion must be a non-negative integer');
                     deleteVersion = Number(raw);
                 }
+                // Every write that sets `data`, before the trust gate, the write budget and the
+                // moderation scan (and so before the store's own checks), as the server orders it.
+                const newData = created?.data ?? putIn?.data;
+                if (newData)
+                    assertOwnedModelVersions(decl, newData, viewer);
                 const write = (moderated, landed) => {
                     if (created) {
                         if (moderated)

package/dist/doc-store/index.d.ts

@@ -171,7 +171,7 @@ export interface DocumentStorage {
  * Every code the server documents for these routes. The type stays open
  * (`string & {}`) so a code a later server adds still reaches the caller.
  */
-export type StorageErrorCode = 'invalid_request' | 'index_not_declared' | 'unauthenticated' | 'sign_in_required' | 'insufficient_scope' | 'consent_required' | 'not_eligible' | 'not_author' | 'write_policy' | 'not_found' | 'collection_not_declared' | 'method_not_allowed' | 'version_conflict' | 'index_building' | 'cursor_expired' | 'too_large' | 'quota_exceeded' | 'content_rejected' | 'rate_limited' | 'internal_error' | 'storage_disabled' | 'moderation_unavailable' | 'consent_unavailable' | 'service_unavailable' | (string & {});
+export type StorageErrorCode = 'invalid_request' | 'index_not_declared' | 'unauthenticated' | 'sign_in_required' | 'insufficient_scope' | 'consent_required' | 'not_eligible' | 'not_author' | 'write_policy' | 'resource_not_owned' | 'not_found' | 'collection_not_declared' | 'method_not_allowed' | 'version_conflict' | 'index_building' | 'cursor_expired' | 'too_large' | 'quota_exceeded' | 'content_rejected' | 'rate_limited' | 'internal_error' | 'storage_disabled' | 'moderation_unavailable' | 'consent_unavailable' | 'service_unavailable' | (string & {});
 /**
  * A refusal from the document store, in its one envelope `{ code, message, error, details? }`.
  * Branch on `code`; `status` and `body` are {@link ApiError}'s, as sent.

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { GrantOptions, Scope, TokenOptions, TokenSource } from './session/i
 export type { SiteClient } from './site/index.js';
 export type { SharedItem, SharedListQuery, SharedListResult, SharedStorageCallOptions, SharedStorageClient, SharedValue, } from './shared-storage/index.js';
 export type { StorageCallOptions, StorageClient, StorageKeyEntry, StorageListQuery, StorageListResult, StorageQuota, } from './storage/index.js';
+export { SubListingError } from './sub-listings/index.js';
+export type { MySubListing, SubListingCallOptions, SubListingContentRating, SubListingErrorCode, SubListingStatus, SubListingsClient, SubListingUpsertInput, SubListingUpsertResult, SubListingWithdrawResult, } from './sub-listings/index.js';
 export { StorageError } from './doc-store/index.js';
 export type { DocumentAuthor, DocumentCallOptions, DocumentListQuery, DocumentPage, DocumentStorage, DocumentWhereValue, StorageCollection, StorageCollectionInfo, StorageDocument, StorageErrorCode, StorageIndexType, StorageInfo, StorageLimits, StorageUsage, WriteOptions, } from './doc-store/index.js';
 export { SubmissionUnconfirmedError } from './workflows/index.js';

package/dist/index.js

@@ -16,6 +16,7 @@
 export { initialize } from './app/index.js';
 export { createSignIn, SignInError } from './sign-in/index.js';
 export { SCOPES } from './session/index.js';
+export { SubListingError } from './sub-listings/index.js';
 export { StorageError } from './doc-store/index.js';
 export { SubmissionUnconfirmedError } from './workflows/index.js';
 export { isTerminal, isTerminalStatus } from './orchestration/index.js';

package/dist/sub-listings/index.d.ts

@@ -0,0 +1,137 @@
+import { ApiError, type Http } from '../http/index.js';
+export interface SubListingCallOptions {
+    signal?: AbortSignal;
+}
+/** A sub-listing's review state. Only `approved` items are in the store. */
+export type SubListingStatus = 'pending' | 'approved' | 'hidden' | 'withdrawn';
+/** The listing rating ladder, least to most mature. */
+export type SubListingContentRating = 'g' | 'pg' | 'pg13' | 'r' | 'x';
+/**
+ * What `upsert` publishes: one item the VIEWER made in this app, as its own
+ * App Store card under the viewer's name.
+ *
+ * The server owns every rule (lengths, the `subPath` shape, the rating floor)
+ * and answers a breach with a {@link SubListingError}; nothing is pre-checked
+ * here, so the rules have one home.
+ */
+export interface SubListingUpsertInput {
+    /**
+     * The key of a row in this app's SHARED storage (`app.sharedStorage`) that the
+     * viewer authored and that is not hidden. One sub-listing per key: publishing
+     * the same key again edits it, and every call REPLACES the whole item — an
+     * optional you leave out is cleared, so re-send the ones you want to keep.
+     */
+    itemKey: string;
+    title: string;
+    /** Optional. Left out (`null`/`undefined`), the item has no tagline. */
+    tagline?: string | null;
+    /**
+     * An image the viewer uploaded and that is publicly visible. Left out
+     * (`null`/`undefined`), the card shows the app's cover.
+     */
+    imageId?: number | null;
+    /**
+     * Where the card opens your app: `/apps/run/<your-app-slug>/<subPath>`. One to
+     * four `/`-separated segments of letters, digits, `_` and `-`.
+     */
+    subPath: string;
+    /**
+     * No less mature than the app's own rating. Left out (`null`/`undefined`), the
+     * item inherits the app's rating.
+     */
+    contentRating?: SubListingContentRating | null;
+}
+export interface SubListingUpsertResult {
+    id: string;
+    /**
+     * 🔴 `hidden` is an ANSWER, not a failure: a moderator took the item down, the
+     * app cannot lift it, and the upsert changed nothing.
+     */
+    status: SubListingStatus;
+    /** True while an edit to an approved item waits for a moderator; the card keeps serving the approved version. */
+    pendingEdit: boolean;
+}
+export interface SubListingWithdrawResult {
+    ok: true;
+    /**
+     * 🔴 `false` is a SUCCESS: nothing of this viewer's was active under that key —
+     * or a moderator has hidden it, which the app cannot change.
+     */
+    withdrawn: boolean;
+}
+/** One of the viewer's own items for this app, as `mine` lists it. */
+export interface MySubListing {
+    id: string;
+    itemKey: string;
+    status: SubListingStatus;
+    title: string;
+    pendingEdit: boolean;
+    /** Why a moderator hid it, when one said. */
+    statusReason: string | null;
+    /** Why a moderator rejected the last staged edit, when one said. */
+    editRejectionReason: string | null;
+    /** The wire's ISO string, revived once. */
+    updatedAt: Date;
+}
+/**
+ * The `code` of a sub-listing refusal.
+ *
+ * The named codes are the ones the three sub-listing routes raise themselves,
+ * plus the two token refusals an app should expect here: `insufficient_scope`
+ * (the token lacks `apps:store:items:write` — every dev-token, dev-tunnel and
+ * review session) and `context_binding` (an anonymous viewer). Any other wire
+ * code still arrives, as a plain string.
+ */
+export type SubListingErrorCode = 'invalid_body' | 'anonymous' | 'not_enabled' | 'untrusted' | 'item_not_found' | 'not_your_item' | 'text_rejected' | 'image_not_yours' | 'image_not_public' | 'rating_too_loose' | 'rate_limited' | 'author_cap' | 'conflict' | 'unavailable' | 'insufficient_scope' | 'context_binding' | (string & {});
+/**
+ * A refusal from a sub-listing route, whose body is `{ error, code }`. Branch on
+ * `code`: `error` (this error's `message`) is a server sentence, not UI copy.
+ * `status` and `body` are {@link ApiError}'s, as sent.
+ *
+ * ⚠ A `429` carries a `Retry-After` header this client does not expose
+ * (`ApiError` keeps no headers).
+ */
+export declare class SubListingError extends ApiError {
+    readonly code: SubListingErrorCode;
+    constructor(status: number, code: SubListingErrorCode, message: string, body: unknown, options?: ErrorOptions);
+}
+/**
+ * The viewer's own App Store items for THIS app — sub-listings of the app's
+ * listing, each published by the viewer under their name and reviewed by a
+ * moderator before it shows in the store.
+ *
+ * 🔴 Requires the block token and the scope `apps:store:items:write`, which is
+ * consent-exempt, signed-in viewers only, and never minted for dev-token,
+ * dev-tunnel or review sessions — so a refusal here is a normal outcome, and the
+ * publish path must degrade quietly. The app must also be enabled for
+ * sub-listings by Civitai (`not_enabled` until it is).
+ *
+ * 🔴 EVERY FAILURE REJECTS: a refusal the server explained is a
+ * {@link SubListingError}; any other failure is the {@link ApiError} or
+ * `CivitaiError` it was.
+ */
+export interface SubListingsClient {
+    /**
+     * Publishes, or edits, the item at `itemKey`. `POST blocks/sub-listings/upsert`.
+     *
+     * 🔴 The server's body is STRICT — an unknown key is `400 invalid_body` — so
+     * only the six fields of {@link SubListingUpsertInput} are sent. An optional
+     * that is `null` or `undefined` is left out rather than sent; the server stores
+     * either as empty.
+     *
+     * 🔴 It REPLACES, it does not patch: an edit that leaves out `tagline`,
+     * `imageId` or `contentRating` clears it (on an approved item, the cleared
+     * version is what goes to the moderator). Re-send every field you want to keep.
+     */
+    upsert(input: SubListingUpsertInput, opts?: SubListingCallOptions): Promise<SubListingUpsertResult>;
+    /** Takes the viewer's item at `itemKey` out of the store. `POST blocks/sub-listings/withdraw`. */
+    withdraw(itemKey: string, opts?: SubListingCallOptions): Promise<SubListingWithdrawResult>;
+    /**
+     * The viewer's items for this app, oldest first, at most 200, with their
+     * review state. `GET blocks/sub-listings/mine`.
+     */
+    mine(opts?: SubListingCallOptions): Promise<{
+        items: MySubListing[];
+    }>;
+}
+export declare function createSubListingsClient(http: Http): SubListingsClient;

package/dist/sub-listings/index.js

@@ -0,0 +1,122 @@
+import { CivitaiError } from '../core/errors.js';
+import { ApiError } from '../http/index.js';
+/** Where the three routes this client wraps live under the site base URL. */
+const BASE = 'blocks/sub-listings';
+/**
+ * A refusal from a sub-listing route, whose body is `{ error, code }`. Branch on
+ * `code`: `error` (this error's `message`) is a server sentence, not UI copy.
+ * `status` and `body` are {@link ApiError}'s, as sent.
+ *
+ * ⚠ A `429` carries a `Retry-After` header this client does not expose
+ * (`ApiError` keeps no headers).
+ */
+export class SubListingError extends ApiError {
+    code;
+    constructor(status, code, message, body, options) {
+        super(status, message, body);
+        if (options?.cause !== undefined)
+            Object.defineProperty(this, 'cause', { value: options.cause });
+        this.name = 'SubListingError';
+        this.code = code;
+    }
+}
+export function createSubListingsClient(http) {
+    const call = async (method, op, body, signal) => {
+        try {
+            return await http(method, `${BASE}/${op}`, { body, signal });
+        }
+        catch (error) {
+            throw toSubListingError(error);
+        }
+    };
+    return {
+        async upsert(input, { signal } = {}) {
+            const res = await call('POST', 'upsert', upsertBody(input), signal);
+            if (typeof res?.id !== 'string' ||
+                typeof res.status !== 'string' ||
+                typeof res.pendingEdit !== 'boolean') {
+                throw new CivitaiError('sub-listings upsert: malformed reply');
+            }
+            return {
+                id: res.id,
+                status: res.status,
+                pendingEdit: res.pendingEdit,
+            };
+        },
+        async withdraw(itemKey, { signal } = {}) {
+            const res = await call('POST', 'withdraw', { itemKey }, signal);
+            if (typeof res?.withdrawn !== 'boolean') {
+                throw new CivitaiError('sub-listings withdraw: reply carried no `withdrawn` flag');
+            }
+            return { ok: true, withdrawn: res.withdrawn };
+        },
+        async mine({ signal } = {}) {
+            const res = await call('GET', 'mine', undefined, signal);
+            // 🔴 NO `?? []`. An empty list is a real answer ("nothing in the store"),
+            // and a reply without `items` must not be dressed up as it.
+            if (!Array.isArray(res?.items)) {
+                throw new CivitaiError('sub-listings mine: reply carried no `items` array');
+            }
+            return { items: res.items.map(toMySubListing) };
+        },
+    };
+}
+/**
+ * The request body: the six fields, named rather than spread, so an extra
+ * property on the caller's object never reaches the strict server body; and each
+ * optional one only when it holds a value.
+ */
+function upsertBody(input) {
+    const body = {
+        itemKey: input.itemKey,
+        title: input.title,
+        subPath: input.subPath,
+    };
+    if (input.tagline != null)
+        body.tagline = input.tagline;
+    if (input.imageId != null)
+        body.imageId = input.imageId;
+    if (input.contentRating != null)
+        body.contentRating = input.contentRating;
+    return body;
+}
+/** An {@link ApiError} whose body carries a string `code` becomes a {@link SubListingError}; anything else passes through. */
+function toSubListingError(error) {
+    if (!(error instanceof ApiError) || error instanceof SubListingError)
+        return error;
+    const body = error.body;
+    if (body == null || typeof body !== 'object' || Array.isArray(body))
+        return error;
+    const { code } = body;
+    if (typeof code !== 'string')
+        return error;
+    return new SubListingError(error.status, code, error.message, body, { cause: error });
+}
+function toMySubListing(row) {
+    const r = (row ?? {});
+    const nullableString = (v) => v === null || typeof v === 'string';
+    if (typeof r.id !== 'string' ||
+        typeof r.itemKey !== 'string' ||
+        typeof r.status !== 'string' ||
+        typeof r.title !== 'string' ||
+        typeof r.pendingEdit !== 'boolean' ||
+        !nullableString(r.statusReason) ||
+        !nullableString(r.editRejectionReason) ||
+        typeof r.updatedAt !== 'string') {
+        throw new CivitaiError('sub-listings mine: malformed item');
+    }
+    const updatedAt = new Date(r.updatedAt);
+    if (Number.isNaN(updatedAt.getTime())) {
+        throw new CivitaiError('sub-listings mine: malformed item timestamp');
+    }
+    return {
+        id: r.id,
+        itemKey: r.itemKey,
+        status: r.status,
+        title: r.title,
+        pendingEdit: r.pendingEdit,
+        statusReason: r.statusReason,
+        editRejectionReason: r.editRejectionReason,
+        updatedAt,
+    };
+}

package/dist/version.generated.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export declare const VERSION = "0.14.1";
+export declare const VERSION = "0.16.0";

package/dist/version.generated.js

@@ -1,3 +1,3 @@
 /* AUTOGENERATED from package.json by scripts/gen-version.mjs. DO NOT EDIT. */
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export const VERSION = "0.14.1";
+export const VERSION = "0.16.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "The Civitai SDK: an app holds a token and calls the Civitai API and the orchestrator; a block asks its host only to show host UI.",
   "license": "MIT",
   "type": "module",