@civitai/sdk 0.7.0 → 0.8.0

package/BREAKING.md

@@ -19,7 +19,7 @@ messages have no destination yet.
 | `SUBMIT_WORKFLOW`, `ESTIMATE_WORKFLOW`, `POLL_WORKFLOW`, `CANCEL_WORKFLOW`, `QUERY_APP_WORKFLOWS`, `CANCEL_APP_WORKFLOW` | `POST /api/v1/blocks/workflows/{submit,estimate,poll,cancel,query}` | **Routes exist.** 🔴 Use these, **not** `app.orchestration` — see *What a direct orchestrator call loses* below |
 | `GET_IMAGES_BY_IDS` | `GET /api/v1/blocks/images?ids=1,2,3` | Batch, up to **100** ids per request. Misses are reported by OMISSION — see below. 🔴 **Not `/api/v1/images`** — that is a `PublicEndpoint`; it ignores your token and answers with anonymous public results rather than erroring |
 | `APP_STORAGE_*` | `POST /api/v1/blocks/app-storage/*` | **Routes exist** — five of them (`get`, `set`, `delete`, `list`, `quota`), civitai#5085. This row said "No v1 route"; that is no longer true. See *App storage* below |
-| `SHARED_*` | `GET\|POST /api/v1/blocks/shared-storage/*` | **Routes exist** — eleven of them; see *Shared storage* below |
+| `SHARED_*` | `app.sharedStorage`, over `GET\|POST /api/v1/blocks/shared-storage/*` | **Routes exist** — eleven of them. `app.sharedStorage` wraps the **five** key/value ones; the higher-level ops are deliberately app-layer. See *Shared storage* below |
 | `GET_BUZZ_BALANCE` | `GET /api/v1/blocks/buzz` | **Route exists.** Returns `{ blue, green, yellow }` — a bare object, three numbers |
 | `GET_BUZZ_ACCOUNTS`, `GET_BUZZ_TRANSACTIONS` | — | No v1 route |
 | `CREATE_POST_FROM_APP` | — | No v1 route, **and deliberately staying on the bridge** — see below |
@@ -57,6 +57,119 @@ first.
 Eleven routes under `/api/v1/blocks/shared-storage/`. Reads take `apps:storage:shared:read`, writes take
 `apps:storage:shared:write` — both scopes already existed; neither is new.
 
+### `app.sharedStorage` wraps FIVE of the eleven, on purpose
+
+`app.sharedStorage` is a **generic cross-user key/value store**: `list`, `get` (the `/item` route, matching its
+tRPC twin `apps.shared.get`), `append`, `update`, `withdraw`. An app no longer needs to hand-roll
+`app.site.get('blocks/shared-storage/…')`, and the shape traps below are handled for it.
+
+🔴 **`vote`, `unvote`, `counts`, `top`, `increment` and `report` are DELIBERATELY ABSENT from the client.**
+The platform serves all eleven routes and will keep doing so — this is a surface decision, not a gap, and not
+an oversight to be "fixed". Shared storage is scoped to generic key/value operations; the higher-level ops
+belong at the app layer, where an app that wants voting, counters or reporting builds them on top of these
+five. If demand shows up, the platform-side surface can be expanded again and the client can follow — but
+**the routes existing is not a reason to add a method here.** Do not add one back without that decision being
+revisited.
+
+What survives the cut, and why: `SharedItem` still carries **`count` and `viewerVoted`** exactly as the two
+read routes project them. Reading a tally is what makes an app-layer vote feature possible; only the
+vote-casting operation is out of scope.
+
+🔴 **It is not the per-viewer client's shape, in four ways.** Each is a real difference in the route table,
+not a stylistic one, and assuming otherwise produces a bug that type-checks:
+
+1. **The two reads are `GET` with a query string**; the three writes are `POST`. A read sent as POST is a `405`.
+2. **`list` is enveloped** — `{ items, metadata: { nextCursor } }`. The cursor sits one level deeper than
+   `app-storage/list`'s top-level `nextCursor`; read the wrong level and pagination is silently dead while
+   every page still parses.
+3. **`append` accepts no key** — the server mints a ULID, so one viewer cannot overwrite another's row.
+4. **Anonymous viewers read but never write** — the inverse of per-viewer storage, where a missing subject
+   refuses everything. See *Who may read, and who may write* below.
+
+### Porting off the bridge: `useSharedStorage` → `app.sharedStorage`
+
+`@civitai/blocks-react`'s `useSharedStorage` hook is what the fleet uses today, and it is **the left column of
+the table at the top of this document, not a rival client of the right one.** It sends `SHARED_LIST`,
+`SHARED_GET`, … over `postMessage` and never touches `/api/v1`; the host receives those messages and calls
+tRPC `apps.shared.*` on the block's behalf. Its own doc says the block *"never sees the datastore credentials
+and never sends its block token (the host injects both)"*.
+
+`app.sharedStorage` is the other side of that migration: the transport becomes a direct `fetch` of
+`/api/v1/blocks/shared-storage/*`, from the block's opaque origin, instead of a message to the host.
+
+**The credential and the CORS declaration are already handled — for both, by code that exists.** `initialize()`
+wires the host session into the client, `createHttp` puts `Authorization: Bearer <token>` on every request and
+retries once on a `401` with a freshly fetched token, and the token still comes **from the host** over the
+bridge (`REQUEST_TOKEN`) — the host continues to mint and rotate it. Scopes are unchanged between the two
+transports (see above). So there is no token plumbing, no CORS work and no manifest change to do.
+
+⚠ **The CORS mechanism differs by trust tier, though neither tier costs you any work.** An unverified block runs
+without `allow-same-origin`, so it fetches from an **opaque origin** and the five routes' `allowOpaqueOrigin`
+opt-in makes the server answer `ACAO: null`. An `internal`- or `verified`-tier block **does** get
+`allow-same-origin`, so it fetches from its **real origin**, where that arm does not apply — it clears CORS via
+the server's origin allowlist instead, which the platform populates itself from the publish-request approval
+rather than anything an author configures.
+
+The work that actually remains is four items, and it is all at the call sites:
+
+1. **Narrow `value` from `unknown`** at every read site — see below.
+2. **Move vote / counter / report logic into your app.** Those methods are not in this client at all; the
+   platform routes still exist. See the deliberate-omission note above.
+3. **Handle refusals as HTTP.** An `ApiError` carrying a `status`, where the bridge surfaced a rejected
+   message — and the anon-write case is a `403` from the scope binding rather than anything the handler said.
+   Read `message ?? error`; see *Error body* below.
+   🔴 **But not every failure is an `ApiError`.** A request the browser blocks — a CORS rejection, a DNS or
+   network failure — never reaches the response layer, so it surfaces as a **fetch `TypeError` with no
+   `status` and no body**. A `catch` that assumes `ApiError` will read `undefined` for the status and report the
+   wrong thing. The bridge had no such failure mode; this transport does. Branch on
+   `error instanceof ApiError` first and treat the rest as transport failure.
+4. **Audit every `limit` you pass** — the normalisation rules changed; see below.
+
+⚠ **This paragraph has had three framings; two claims are retracted.** Recorded so the ground is not re-walked,
+and scoped deliberately — each retraction covers only the words quoted, nothing adjacent:
+**(a)** *"a second client for these same routes"* — **false**: the hook is the bridge/tRPC path and never
+calls `/api/v1`, so the two are different transports, not two clients of one surface.
+**(b)** *"budget for the token/CORS work"* — **false**: both the credential and the CORS declaration are already
+handled, so that advice sent the reader's effort at finished infrastructure while demoting the real work.
+🔴 The *transport* change is NOT retracted — this document still asserts it, above. The list above is what is
+measured; nothing beyond it is claimed.
+
+| | `useSharedStorage` (bridge) | `app.sharedStorage` (HTTP) |
+|---|---|---|
+| Transport | `postMessage` → host → tRPC `apps.shared.*` | direct `fetch` of `/api/v1/blocks/shared-storage/*` |
+| Credential | host-injected | the SDK sends the host-minted token for you |
+| Methods | 10, including `vote`/`unvote`/`count`/`report` | 5, key/value only |
+| A listed row's `value` | `SharedAppendValue` — the typed write shape | `unknown` |
+| `update` resolves | `void` | `{ ok: true }` |
+| `list({ limit })`, out of range / non-integer / non-finite | **normalised**: clamped to 1…100, floored, or defaulted to 50 | **rejected — `400`** on all three |
+
+🔴 **`limit` is the one that bites silently, and it is three changes, not one.** The bridge HOST normalised;
+the REST route VALIDATES and refuses. Measured against the platform's own schema
+(`z.coerce.number().int().min(1).max(100)`), each of these used to succeed and now `400`s:
+
+- **Out of range** — `200` was clamped to 100, `0` was raised to 1. Both now reject.
+- **Non-integer** — `2.5` was floored to 2. Now rejects.
+- **Non-finite or not a number** — `NaN`, `Infinity`, `"abc"` and `""` all fell back to **50**. All now reject.
+  🔴 **This is the one to grep for**: `Number(searchParams.get('n'))` on a missing param is `NaN`, which used
+  to mean "just give me the default" and is now a failed request.
+
+⚠ The `400` body is `{ error: 'Invalid query', details }`, and the SDK reads `error` first — so
+`ApiError.message` is just **"Invalid query"**, naming neither the field nor the reason. The pointer is not
+missing, only moved: **`ApiError.body.details`** carries zod's flattened field errors. Look there, not at
+`.message`, when a read 400s.
+
+Pass a value in range, or omit it and take the server's default. This client deliberately does **not** re-clamp:
+the bounds are the server's, a second copy here is the thing that drifts, and a guard in this package enforces
+that the module carries no numeric literal at all.
+
+🔴 **The `value: unknown` is deliberate, and it is the wire-honest reading.** A row you list was written by some
+OTHER viewer's copy of the app — possibly an older version, possibly a newer one — so its shape is a fact about
+stored data, not a promise a client can keep. Typing it as the *write* shape asserts something nothing checked,
+and it is wrong the moment one viewer ships a schema change. Narrow it at the call site.
+
+Consequence: **a port is not an import swap** — but the cost is call-site work, not infrastructure. Narrow
+`value`, move the vote/counter/report logic into your app, branch on `ApiError.status`, and check every `limit`.
+
 | Method | Path | Scope |
 |---|---|---|
 | `GET` | `/list` | `…shared:read` |

package/README.md

@@ -71,13 +71,14 @@ host's consent dialog.
 **not** an error in itself: the host's OAuth mint is flag-gated, so an opted-in
 block can legitimately receive the block token, and that token serves the
 `/api/v1/blocks/*` routes it was minted for, `GET /api/v1/models/{id}`, and
-`app.storage` — which an OAuth token cannot reach at all. What it does not reach
-is the rest of `/api/v1`, the orchestrator or the MCP. So the refusal sits at the
-surface, not at startup:
+`app.storage` and `app.sharedStorage` — which an OAuth token cannot reach at all.
+What it does not reach is the rest of `/api/v1`, the orchestrator or the MCP. So
+the refusal sits at the surface, not at startup:
 
 | You call | Holding a block token, signed in |
 |---|---|
 | `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.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.orchestration.*` | Rejects **before** the request with a `CivitaiError` naming `auth: "oauth"` — the orchestrator accepts no block token on any route, so there is nothing to learn from making the call |
@@ -143,8 +144,11 @@ Routes are addressed by path, so a route `/api/v1` gains needs no release here:
 const images = await app.site.get('images', { query: { limit: 20, username: 'civitai' } });
 ```
 
-A `401` is retried once with a fresh token. Any other failure is an `ApiError`
-carrying `status`, the parsed `body`, and the server's own message.
+A `401` is retried once with a fresh token. Any failure the server answered is an
+`ApiError` carrying `status`, the parsed `body`, and the server's own message —
+while a request the browser never delivered (CORS, DNS, offline) surfaces as a
+fetch `TypeError` with no `status`, so test `error instanceof ApiError` before
+reading one.
 
 ## App storage
 
@@ -190,6 +194,81 @@ try {
 }
 ```
 
+## Shared storage
+
+`app.sharedStorage` is this app's **cross-user** key/value store — one namespace
+every viewer reads and writes, unlike `app.storage`, which is private per viewer.
+Five methods: `list`, `get`, `append`, `update`, `withdraw`.
+
+```ts
+const { items, nextCursor } = await app.sharedStorage.list({ prefix: 'deck:' });
+const { key } = await app.sharedStorage.append({ title: 'My deck', data: { cards } });
+const row = await app.sharedStorage.get(key);        // null when hidden or absent
+await app.sharedStorage.update(key, { title: 'Renamed' });
+const { deleted } = await app.sharedStorage.withdraw(key);
+```
+
+🔴 **Generic key/value on purpose — and deliberately smaller than the route
+table.** The platform serves eleven shared-storage routes; this client wraps the
+five that are key/value operations. `vote`, `unvote`, `counts`, `top`,
+`increment` and `report` are **intentionally absent**: an app that needs voting,
+counters or reporting builds them at its own layer on top of these five, and the
+platform surface expands only if demand shows up. The routes existing is not a
+reason to expect a method here.
+
+Reading a tally still works — `SharedItem` carries `count` and `viewerVoted` as
+the server projects them, which is exactly what makes an app-layer vote feature
+possible. You just cast the vote yourself.
+
+🔴 **Reads and writes have different audiences, and one does not imply the
+other.** This is the opposite of `app.storage`, so do not carry that gate over:
+
+- **An anonymous viewer MAY read** (`list`, `get`) — signed-out browsing is a
+  supported path — and may **never** write. An anon write is a `403` from the
+  scope binding, not the `401` a missing token gives.
+- **A signed-in viewer is not automatically a permitted writer.** Writes clear a
+  server-side minimum-trust gate (account age, paid tier, verified email or a
+  linked OAuth account). Treat a write refusal as a normal outcome with a real
+  message in the UI, not an unexpected error.
+
+So gate the write affordances on `app.viewer`, and render the reads regardless.
+
+Four shape differences from `app.storage`, each of which would otherwise be a bug
+that type-checks:
+
+- **The two reads are `GET`**; the three writes are `POST`. A read sent as `POST`
+  is a `405`.
+- **`list` returns `items` with values included** — so one request renders a page
+  rather than needing a `get` per key — and its `nextCursor` arrives nested under
+  the reply's `metadata`. The client lifts it for you; the rule is the same as
+  `app.storage`'s, absence proves the scan completed.
+- **`append` takes no key.** The server mints a ULID and returns it, so one
+  viewer cannot overwrite another's row. Use `update` for an in-place edit of a
+  row this viewer authored.
+- **`value` is `unknown` on the way out.** The row was written by some other
+  viewer's copy of your app, possibly an older version, so its shape is a fact
+  about the data rather than a promise the client can make. Narrow it yourself.
+
+⚠ **`limit` is validated, not normalised.** Out of range, non-integer, `NaN` and
+`Infinity` are each a `400` and a rejected promise — not a silently adjusted page.
+Pass a value inside the server's range, or omit it and take the server's default.
+🔴 The sharp edge: `Number(searchParams.get('n'))` on a missing param is `NaN`, so
+a pattern that used to fall through to a default is now a failed request.
+
+The `400` body is `{ error: 'Invalid query', details }` and the SDK reads `error`
+first, so `ApiError.message` says only "Invalid query" — the field-level reason is
+in `ApiError.body.details`.
+
+If you are porting from `@civitai/blocks-react`'s `useSharedStorage`, the bridge
+*host* normalised all of this for you and nothing normalises it here;
+[`BREAKING.md`](./BREAKING.md) covers what the port does and does not cost.
+
+`withdraw` answers `{ ok: true, deleted: false }` identically for another
+author's key, an already-withdrawn row and a key that never existed — it is not
+an existence oracle, so do not report that as "someone else owns this". Put every
+string other viewers will read in `title`/`body`, which the server moderates;
+`data` is unmoderated app structure.
+
 ## The orchestrator
 
 Steps are typed by `$type`: `input` is checked against that step's own input,

package/dist/app/index.d.ts

@@ -3,6 +3,7 @@ import type { BlockTransport } from '../core/transport.js';
 import { type Host } from '../host/index.js';
 import { type OrchestrationClient } from '../orchestration/index.js';
 import { type GrantOptions, type Scope, type TokenOptions, type TokenSessionOptions } from '../session/index.js';
+import { type SharedStorageClient } from '../shared-storage/index.js';
 import { type SiteClient } from '../site/index.js';
 import { type StorageClient } from '../storage/index.js';
 export interface AppClient {
@@ -26,6 +27,18 @@ export interface AppClient {
      * reading an empty result as "nothing stored".
      */
     readonly storage: StorageClient;
+    /**
+     * This app's CROSS-USER store — one namespace every viewer of this app reads
+     * and writes, which is what makes a shared feed or a "popular" rail possible.
+     *
+     * 🔴 Requires the block token, like {@link AppClient.storage}, but the audience
+     * is NOT the same: an ANONYMOUS viewer MAY read here and may never write. So
+     * `viewer === null` gates the write affordances, not the read — and an anon
+     * write surfaces as 403, refused by the scope binding before the handler runs.
+     * A signed-in viewer is not automatically a permitted writer either: writes
+     * clear a server-side minimum-trust gate.
+     */
+    readonly sharedStorage: SharedStorageClient;
     /**
      * The orchestrator's workflows, as the viewer.
      *

package/dist/app/index.js

@@ -4,6 +4,7 @@ import { createHost, createHostSession } from '../host/index.js';
 import { ApiError, createHttp } from '../http/index.js';
 import { createOrchestrationClient, DEFAULT_ORCHESTRATION_URL, } from '../orchestration/index.js';
 import { createTokenSession, } from '../session/index.js';
+import { createSharedStorageClient, } from '../shared-storage/index.js';
 import { createSiteClient, DEFAULT_SITE_URL } from '../site/index.js';
 import { createStorageClient } from '../storage/index.js';
 /** Long enough for a slow host page; short enough that a block opened on its own says so. */
@@ -77,16 +78,19 @@ const OAUTH_OPT_IN = 'declare `auth: "oauth"` in block.manifest.json';
 const BLOCK_NAMESPACE = /^\/*blocks\//;
 function createAppClient(session, options, holdsBlockTokenNow = () => false) {
     const http = (baseUrl) => createHttp({ session, baseUrl, fetch: options.fetch });
-    // One instance for both site-hosted surfaces: `storage`'s routes live under
-    // the same base URL, so a `siteUrl` override redirects them together.
+    // One instance for all three site-hosted surfaces: the two storage 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. `storage` needs no exemption of its own: every one of its
-    // routes is `blocks/app-storage/*`, which that namespace already excludes, and
-    // `test/storage/seam.test.ts` pins its `BASE` there textually.
+    // diagnosis applies. Neither storage client needs an exemption of its own:
+    // their routes are `blocks/app-storage/*` and `blocks/shared-storage/*`, which
+    // that namespace already excludes, and `test/storage/seam.test.ts` plus
+    // `test/shared-storage/seam.test.ts` pin both `BASE` values there textually.
     const siteHttp = explainApiRefusal(http(options.siteUrl ?? DEFAULT_SITE_URL), holdsBlockTokenNow);
     return {
         site: createSiteClient(siteHttp),
         storage: createStorageClient(siteHttp),
+        sharedStorage: createSharedStorageClient(siteHttp),
         orchestration: createOrchestrationClient(refuseBlockToken(http(options.orchestrationUrl ?? DEFAULT_ORCHESTRATION_URL), holdsBlockTokenNow)),
         requestGrants: (scopes, opts) => session.requestGrants(scopes, opts),
         getToken: (opts) => session.getToken(opts),

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export type { SignIn, SignInOptions } from './sign-in/index.js';
 export { SCOPES } from './session/index.js';
 export type { GrantOptions, Scope, TokenOptions, TokenSource } from './session/index.js';
 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 { isTerminal, isTerminalStatus } from './orchestration/index.js';
 export type { OrchestrationClient, Step, StepTemplate, WaitOptions, Workflow, WorkflowPage, WorkflowQuery, WorkflowStatus, WorkflowTemplate, } from './orchestration/index.js';

package/dist/shared-storage/index.d.ts

@@ -0,0 +1,153 @@
+import type { Http } from '../http/index.js';
+export interface SharedStorageCallOptions {
+    signal?: AbortSignal;
+}
+/**
+ * The moderated, user-visible text plus the opaque app-owned blob.
+ *
+ * 🔴 `title` and `body` run the server's BLOCKING content-safety belt on every
+ * write. `data` does NOT — it is unmoderated app structure. Put every string
+ * another viewer will read in `title`/`body`; a text surface smuggled into
+ * `data` reaches other users unmoderated, which is the one thing this split
+ * exists to prevent.
+ */
+export interface SharedValue {
+    title: string;
+    body?: string;
+    data?: unknown;
+}
+/**
+ * One row of the shared store, as `list` and `get` both project it.
+ *
+ * 🔴 `value` is `unknown`, NOT {@link SharedValue}, and that is deliberate: the
+ * row was written by some OTHER viewer's copy of this app — possibly an older
+ * version, possibly a newer one — so its shape is a fact about the data, not a
+ * promise this client can make. Narrow it at the call site. Declaring it
+ * `SharedValue` would assert a shape nothing checked about data we did not write.
+ */
+export interface SharedItem {
+    key: string;
+    /** The row's author. A caller renders "yours" by comparing it to the viewer's id. */
+    authorUserId: number;
+    value: unknown;
+    /**
+     * The row's aggregate up-vote tally, as the server projects it.
+     *
+     * ⚠ Reported, not writable from here: the vote OPERATIONS are deliberately not
+     * part of this client (see the module note). Reading the tally is what lets an
+     * app build voting at its own layer, which is why the field stays.
+     */
+    count: number;
+    /**
+     * The wire carries ISO strings; both stamps are revived here, once, so a
+     * caller can sort and diff without knowing the transport.
+     */
+    createdAt: Date;
+    updatedAt: Date;
+    /**
+     * Whether THIS viewer has voted. 🔴 Always `false` for an anonymous viewer —
+     * who may read this store — so it is not evidence that nobody voted.
+     */
+    viewerVoted: boolean;
+}
+export interface SharedListQuery {
+    /** Narrows to keys starting with this. Escaped server-side against LIKE wildcards. */
+    prefix?: string;
+    /** The server bounds this and applies its own default; this client sends none. */
+    limit?: number;
+    /** An opaque `nextCursor` from a previous page. */
+    cursor?: string;
+}
+export interface SharedListResult {
+    /** Newest-first on the server-generated ULID key. Hidden rows are excluded. */
+    items: SharedItem[];
+    /**
+     * 🔴 PRESENT EXACTLY WHEN THERE MAY BE MORE ROWS, and passed through
+     * untouched. The server sets it iff the page it returned was full, and it
+     * arrives nested under the reply's `metadata` — lifted here, never defaulted,
+     * never normalised, never re-derived from `items.length`. A caller uses its
+     * ABSENCE as proof a scan completed.
+     */
+    nextCursor?: string;
+}
+/**
+ * This app's CROSS-USER key/value store — every viewer of this app reads and
+ * writes one namespace, unlike {@link StorageClient}, which is private per viewer.
+ *
+ * 🔴 DELIBERATELY GENERIC KEY/VALUE, AND DELIBERATELY SMALLER THAN THE ROUTE
+ * TABLE. The platform serves eleven shared-storage routes; this client wraps the
+ * five that are key/value operations. The higher-level ops — `vote`, `unvote`,
+ * `counts`, `top`, `increment`, `report` — are intentionally absent: an app that
+ * needs voting, counters or reporting builds them at its own layer on top of
+ * these five, and the platform surface expands only if demand shows up. **The
+ * routes existing is not a reason to add a method here.** Do not "fix" this
+ * omission.
+ *
+ * 🔴 Requires the block token the host mints, plus the scopes: every read takes
+ * `apps:storage:shared:read` and every write takes `apps:storage:shared:write`.
+ * An app that authenticated with an OAuth access token has no shared storage.
+ *
+ * 🔴 READS AND WRITES HAVE DIFFERENT AUDIENCES, and a caller must not assume one
+ * implies the other:
+ *
+ * - An ANONYMOUS viewer MAY read (`list`, `get`) and may NEVER write. An anon
+ *   write is refused by the scope binding before the handler runs, so it arrives
+ *   as **403**, not the 401 a missing token gives.
+ * - A signed-in viewer is not automatically a permitted writer: writes clear a
+ *   minimum-trust gate (account age, paid tier, verified email or a linked OAuth
+ *   account). Treat a write refusal as a normal outcome and say so in the UI.
+ *
+ * 🔴 EVERY FAILURE REJECTS. No path here resolves to mean "not written" or
+ * "could not read". A caller that must not act on a partial view branches on the
+ * rejection, never on an empty result.
+ */
+export interface SharedStorageClient {
+    /**
+     * One page of rows, newest-first. `GET blocks/shared-storage/list`.
+     *
+     * Values ARE returned, unlike the per-viewer client's `list` — so one request
+     * renders a page rather than needing a `get` per key.
+     */
+    list(query?: SharedListQuery, opts?: SharedStorageCallOptions): Promise<SharedListResult>;
+    /**
+     * One row by key, or `null`. `GET blocks/shared-storage/item`.
+     *
+     * 🔴 `null` covers MISSING **and** HIDDEN, deliberately and identically — a
+     * withdrawn or moderator-hidden row is indistinguishable from one that never
+     * existed, so this is not an oracle for either. It is a 200, not a 404.
+     */
+    get(key: string, opts?: SharedStorageCallOptions): Promise<SharedItem | null>;
+    /**
+     * Files a new row and resolves its key. `POST blocks/shared-storage/append`.
+     *
+     * 🔴 THE KEY IS THE SERVER'S — a ULID it generates, returned here. This method
+     * takes no key and there is no create-at-key call, because a client-chosen key
+     * would let one viewer overwrite another's row.
+     */
+    append(value: SharedValue, opts?: SharedStorageCallOptions): Promise<{
+        key: string;
+    }>;
+    /**
+     * Edits a row the VIEWER AUTHORED, in place. `POST blocks/shared-storage/update`.
+     *
+     * Another author's key is a 403 and a missing or hidden one a 404 — neither is
+     * a silent no-op. Preserved: the key, the author, `createdAt`, and the row's
+     * votes, counters and reports. Replaced: the value.
+     */
+    update(key: string, value: SharedValue, opts?: SharedStorageCallOptions): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Deletes a row the VIEWER AUTHORED. `POST blocks/shared-storage/withdraw`.
+     *
+     * 🔴 `deleted: false` is a SUCCESS, and it is deliberately ambiguous: another
+     * author's key, an already-withdrawn row and a key that never existed all
+     * answer the same way, so this cannot probe for other viewers' rows. Do not
+     * report it to the viewer as "someone else owns this".
+     */
+    withdraw(key: string, opts?: SharedStorageCallOptions): Promise<{
+        ok: true;
+        deleted: boolean;
+    }>;
+}
+export declare function createSharedStorageClient(http: Http): SharedStorageClient;

package/dist/shared-storage/index.js

@@ -0,0 +1,107 @@
+import { CivitaiError } from '../core/errors.js';
+/** Where the five routes this client wraps live under the site base URL. */
+const BASE = 'blocks/shared-storage';
+export function createSharedStorageClient(http) {
+    // 🔴 GET for the reads, POST for the writes — the route table's own split, not
+    // the per-viewer client's uniform POST. A read sent as POST is a 405.
+    const get = (op, query, signal) => http('GET', `${BASE}/${op}`, { query, signal });
+    const post = (op, body, signal) => http('POST', `${BASE}/${op}`, { body, signal });
+    return {
+        async list(query = {}, { signal } = {}) {
+            const res = await get('list', 
+            // Named rather than spread: each of the three is a field a mutation can
+            // drop on its own, and an `undefined` is omitted from the query string,
+            // so the server's own default applies instead of a second copy here.
+            { prefix: query.prefix, limit: query.limit, cursor: query.cursor }, signal);
+            // 🔴 NO `?? []`. A malformed 200 must throw, never answer "no rows": a
+            // caller reads an empty page as "this store is empty" and renders that to
+            // every viewer, and a manufactured empty page is indistinguishable.
+            if (!Array.isArray(res?.items)) {
+                throw new CivitaiError('shared-storage list: reply carried no `items` array');
+            }
+            // 🔴 GUARDED SYMMETRICALLY WITH `items`, and for the same reason. `metadata`
+            // is where `nextCursor` lives, and this method's contract is that the
+            // cursor's ABSENCE proves a scan completed. A `?? {}` here would turn a
+            // malformed envelope into `nextCursor: undefined` — so a caller's
+            // `do…while (cursor)` loop stops after page one and renders 50 of 5,000 rows
+            // as the whole store, silently. The identical malformation of `items` throws;
+            // treating the container the cursor arrives in as optional would have made
+            // the louder half of this reply strict and the quieter half lenient.
+            if (res.metadata == null || typeof res.metadata !== 'object') {
+                throw new CivitaiError('shared-storage list: reply carried no `metadata` object');
+            }
+            const metadata = res.metadata;
+            return {
+                items: res.items.map(toItem),
+                // 🔴 Lifted out of `metadata` and passed through. Not defaulted, not
+                // normalised, not re-derived.
+                nextCursor: metadata.nextCursor,
+            };
+        },
+        async get(key, { signal } = {}) {
+            const res = await get('item', { key }, signal);
+            // 🔴 NO `res?.item ?? null`. `null` is this method's word for "no visible
+            // row", a real answer a caller acts on. A reply that never carried `item`
+            // is not that answer, and must not be dressed up as it.
+            if (res == null || typeof res !== 'object' || !('item' in res)) {
+                throw new CivitaiError('shared-storage get: reply carried no `item`');
+            }
+            return res.item == null ? null : toItem(res.item);
+        },
+        async append(value, { signal } = {}) {
+            const res = await post('append', { value }, signal);
+            // Asserted, not cast: this key is the ONLY handle the caller will ever have
+            // on the row it just created, and a cast would make the declared `string` a
+            // lie we cannot see.
+            if (typeof res?.key !== 'string') {
+                throw new CivitaiError('shared-storage append: reply carried no `key`');
+            }
+            return { key: res.key };
+        },
+        async update(key, value, { signal } = {}) {
+            await post('update', { key, value }, signal);
+            // The route answers `{ ok: true }` and every failure has already rejected,
+            // so there is no second field to check — resolving IS the answer.
+            return { ok: true };
+        },
+        async withdraw(key, { signal } = {}) {
+            const res = await post('withdraw', { key }, signal);
+            if (typeof res?.deleted !== 'boolean') {
+                throw new CivitaiError('shared-storage withdraw: reply carried no `deleted` flag');
+            }
+            return { ok: true, deleted: res.deleted };
+        },
+    };
+}
+function toItem(row) {
+    const r = (row ?? {});
+    if (typeof r.key !== 'string' ||
+        typeof r.authorUserId !== 'number' ||
+        typeof r.count !== 'number' ||
+        typeof r.viewerVoted !== 'boolean' ||
+        !('value' in r)) {
+        throw new CivitaiError('shared-storage: malformed item');
+    }
+    return {
+        key: r.key,
+        authorUserId: r.authorUserId,
+        value: r.value,
+        count: r.count,
+        createdAt: toDate(r.createdAt),
+        updatedAt: toDate(r.updatedAt),
+        viewerVoted: r.viewerVoted,
+    };
+}
+function toDate(raw) {
+    // `new Date(null)` is the epoch, not an Invalid Date, so the NaN check below
+    // cannot be the only gate — a null timestamp would sort and compare silently
+    // wrong forever.
+    if (!(typeof raw === 'string' || raw instanceof Date)) {
+        throw new CivitaiError('shared-storage: malformed item timestamp');
+    }
+    const at = new Date(raw);
+    if (Number.isNaN(at.getTime())) {
+        throw new CivitaiError('shared-storage: malformed item timestamp');
+    }
+    return at;
+}

package/package.json

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