@civitai/sdk 0.10.1 → 0.11.0

package/BREAKING.md

@@ -25,13 +25,22 @@ messages have no destination yet.
 | `CREATE_POST_FROM_APP` | — | No v1 route, **and deliberately staying on the bridge** — see below |
 | `PUBLISH_GENERATION_OUTPUTS` | `app.host.publishGenerationOutputs` | Same reasoning: it raises host UI, so it stays on the bridge — **carried** rather than replaced |
 | `SET_COLLECTION_FOLLOW` | `POST /api/v1/blocks/collections/{id}/follow` | **Route exists** (scope `collections:write:self`). This row previously said "No v1 route"; that was wrong |
-| `GET_DAILY_COMPENSATION`, `GET_WILDCARD_PACK`, `TRACK_EVENT` | — | Not carried |
-
-⚠ `TRACK_EVENT` is filed above beside two one-consumer capabilities, which understates it: it is emitted by
-`useBlockAnalytics`, which the fleet apps call widely. It is listed as *not carried* because **it has
-no host handler today either** — `hostHandlerParity.ts` marks both hosts N/A, *"analytics fire-and-forget; no
-host-side sink wired (dropped, never hangs)"*. So those call sites are already no-ops; this is net-new
-capability rather than a migration gap.
+| `GET_DAILY_COMPENSATION`, `GET_WILDCARD_PACK` | — | Not carried |
+| `TRACK_EVENT` | `app.host.track(eventName, properties)` | **Carried**, same wire as `useBlockAnalytics().track`. 🔴 Only events and properties DECLARED under the manifest's `analytics.events` are recorded — see below |
+
+⚠ **`TRACK_EVENT` used to be listed here as *not carried*, because no host handled it — every
+`useBlockAnalytics` call was a no-op.** Both hosts now forward it, so the calls an app already makes start
+counting — but only against the declaration. What is recorded:
+
+- **Declared events only.** An event name the approved manifest does not declare under `analytics.events` is
+  counted as a drop; its name and properties are not stored. An app that never declared its events records
+  nothing but that count.
+- **Declared properties of the declared type only.** Types are `enum` (one of the declared strings), `number`
+  and `boolean`. There is no free-text string, so an id, a prompt or a username sent as a string is dropped.
+  An undeclared property, or a value of the wrong type, is dropped and the rest of the event kept.
+- **Budgets.** Each mount may send 10 events a second and 500 in all, in bodies of at most 32 KiB; an event
+  over a limit is dropped in the browser and counted nowhere. Signed-out viewers are counted, never identified.
+- **Fire-and-forget.** No reply, no acknowledgement. Owners see aggregates in the app's analytics panel.
 
 ## Scope binding is per-route
 
@@ -299,7 +308,7 @@ iframe, and nothing about the call site looks different.
 On `app.host`: `requestSignIn`, `download` (was `SAVE_IMAGE`),
 `openResourcePicker`, `openBuzzPurchase`, `openImageUpload`,
 `publishGenerationOutputs`, `resize`, **`autoResize`**, `reportError`, `navigate`
-and `onVisibilityChange`. Reach for `autoResize(element)` over bare `resize` —
+and `onVisibilityChange` — plus `track`, which raises no UI (see `TRACK_EVENT` above). Reach for `autoResize(element)` over bare `resize` —
 it wires the `ResizeObserver` for you and returns a stop function. Consent is `app.requestGrants` (was `requestConsent`).
 
 `publishGenerationOutputs` keeps `usePublishGenerationOutputs`'s wire exactly —

package/README.md

@@ -71,7 +71,11 @@ observed two ways is two values that can disagree.
 A block opts in by declaring `auth: "oauth"` in its `block.manifest.json`. The
 host then hands it a real OAuth access token that `/api/v1`, the orchestrator
 and the MCP accept, and consent — including `requestGrants` — goes through the
-host's consent dialog.
+host's consent dialog. The manifest must also declare `user:read:self`, which
+every OAuth token carries: on civitai.com the host never mints one without it
+and hands back the block token. The dev tunnel mints one regardless, so a
+missing `user:read:self` only shows up after approval. And `auth: "oauth"` cannot be declared alongside any
+`apps:storage:*` scope: such a manifest is refused at submit.
 
 ### When the token is the block-scoped one
 
@@ -290,6 +294,28 @@ 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`.
 
+**Writes are rate-limited per (viewer, app)**; the limits are listed once, in
+[the `@civitai/blocks-react` README](https://github.com/civitai/civitai-app-starters/blob/main/packages/civitai-blocks-react/README.md#shared-storage-write-limits). A write refused for a limit is an `ApiError` with
+`status === 429`, a `Retry-After` header the client does not expose, and a body
+of `{ code: 'TOO_MANY_REQUESTS', message, error, rateLimit: { retryAfterSeconds,
+retryAt } }`. This client does not validate `body.rateLimit`, so check it before
+you render it:
+
+```ts
+import { ApiError } from '@civitai/sdk';
+
+try {
+  await app.sharedStorage.append({ title: 'My deck' });
+} catch (error) {
+  const rateLimit =
+    error instanceof ApiError && error.status === 429
+      ? (error.body as { rateLimit?: { retryAt?: unknown } } | null)?.rateLimit
+      : undefined;
+  if (typeof rateLimit?.retryAt === 'string') showRetryAt(new Date(rateLimit.retryAt));
+  else throw error;
+}
+```
+
 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.
@@ -349,6 +375,7 @@ wider scope — and refuses without one.
 | `navigate(path, { scope, target })` | Deep-links within this app's own sub-paths; `scope: 'site'` asks to leave the app for a civitai.com page instead. `scope` defaults to `'app'` |
 | `onVisibilityChange(handler)` | Reports the page hiding and returning |
 | `requestSignIn({ returnUrl })` | Starts sign-in; the block re-initialises signed in |
+| `track(eventName, properties)` | Sends a custom event to your app's analytics, fire-and-forget. Only events and properties declared under `analytics.events` in the manifest are recorded — see *Custom events* below |
 | `download({ url, filename })` | Saves to the viewer's device — a sandboxed frame cannot |
 | `openResourcePicker({ resourceType })` | civitai's own picker; resolves the one pick, or `null` |
 | `openBuzzPurchase({ suggestedAmount })` | The purchase flow; resolves `{ purchased }` |
@@ -452,6 +479,38 @@ than failing the call, so `imageIds` can be **shorter** than what you selected
 and nothing says which index dropped. Compare lengths; do not pair ids to
 indexes.
 
+### Custom events
+
+```ts
+app.host.track('generate_clicked', { mode: 'txt2img', batch: 4 });
+```
+
+🔴 **Only what the manifest declares is recorded.** Declare each event, and each
+property it carries, under `analytics.events` in `block.manifest.json`; events
+are accepted against the approved manifest:
+
+```json
+"analytics": {
+  "events": {
+    "generate_clicked": {
+      "properties": {
+        "mode": { "type": "enum", "values": ["txt2img", "img2img"] },
+        "batch": { "type": "number" }
+      }
+    }
+  }
+}
+```
+
+- An undeclared event is counted as dropped; its name and properties are not stored.
+- A declared event keeps only its declared properties, each only when the value
+  has the declared type. Types are `enum`, `number` and `boolean`; there is no
+  free-text string, so a string is kept only when it is one of the enum's values.
+- Each mount may send 10 events a second and 500 in all, in bodies of at most
+  32 KiB. An event over a limit is dropped in the browser and counted nowhere.
+- Fire-and-forget: there is no reply. Owners see aggregates in the app's
+  analytics panel, never individual events.
+
 ## Parent origins
 
 Messages are accepted only from an allowlisted parent origin. The allowlist is

package/dist/host/index.d.ts

@@ -50,6 +50,20 @@ export interface Host {
     requestSignIn(args?: {
         returnUrl?: string;
     }): void;
+    /**
+     * Sends one custom event to the app's analytics. Fire-and-forget: no reply
+     * and no acknowledgement. The wire is `useBlockAnalytics().track`'s.
+     *
+     * 🔴 Only what the manifest DECLARES under `analytics.events` is recorded,
+     * against the approved manifest. An undeclared event is counted as dropped and
+     * its name is not stored. A declared event keeps only its declared
+     * properties, each only when the value has the declared type — `enum` (one of
+     * the declared strings), `number` or `boolean`; there is no free-text string.
+     * Each mount may send 10 events a second and 500 in all; an event over a
+     * limit is dropped in the browser and counted nowhere. Owners see aggregates
+     * in the app's analytics panel, never individual events.
+     */
+    track(eventName: string, properties?: Record<string, unknown>): void;
     /**
      * Saves to the viewer's device through the host, because a sandboxed frame
      * cannot. The host fetches only from origins it allowlists.

package/dist/host/index.js

@@ -40,6 +40,10 @@ export function createHost(transport) {
             };
         },
         requestSignIn: (args = {}) => notify('REQUEST_SIGN_IN', args, { transport }),
+        // `properties` is OMITTED when not given, so the payload is byte-identical
+        // to what `useBlockAnalytics().track(name)` sends after JSON drops the
+        // `undefined`.
+        track: (eventName, properties) => notify('TRACK_EVENT', { eventName, ...(properties !== undefined ? { properties } : {}) }, { transport }),
         async download(request, opts = {}) {
             await call('SAVE_IMAGE', request, { ...opts, transport });
         },

package/dist/host/protocol.d.ts

@@ -175,6 +175,10 @@ export type HostNotifications = {
     REQUEST_CONSENT: {
         scopes?: string[];
     };
+    TRACK_EVENT: {
+        eventName: string;
+        properties?: Record<string, unknown>;
+    };
 };
 export type HostPushes = {
     /** The page is hidden; stop timers and polling until `RESUME`. */

package/package.json

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