@civitai/sdk 0.14.1 → 0.15.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 |
@@ -428,6 +429,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

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/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.15.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.15.0";

package/package.json

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