@civitai/sdk 0.2.0

package/BREAKING.md

@@ -0,0 +1,69 @@
+# Breaking changes
+
+What an app gives up or rewrites moving from `@civitai/app-sdk` 0.x (with
+`@civitai/blocks-react`) to this package. Keep it current as the host and the
+API catch up.
+
+## Data moved from the bridge to the API
+
+A block used to ask the host for data over `postMessage`. It now calls the
+public `/api/v1` API (`app.site`) and the orchestrator (`app.orchestration`)
+itself, with the token `initialize()` gives it. Routes are added to `/api/v1` as apps need them, so several old
+messages have no destination yet.
+
+| Old message(s) | Now | Status |
+|---|---|---|
+| `GET_VIEWER` | `app.site.get('me')` | Route exists |
+| `SUBMIT_WORKFLOW`, `ESTIMATE_WORKFLOW`, `POLL_WORKFLOW`, `CANCEL_WORKFLOW`, `QUERY_APP_WORKFLOWS`, `CANCEL_APP_WORKFLOW` | `app.orchestration` | Works with an OAuth token |
+| `GET_IMAGES_BY_IDS` | `GET /api/v1/images` | Takes one `imageId`, not a list |
+| `APP_STORAGE_*` | — | No v1 route |
+| `SHARED_*` | — | No v1 route |
+| `GET_BUZZ_BALANCE`, `GET_BUZZ_ACCOUNTS`, `GET_BUZZ_TRANSACTIONS` | — | No v1 route |
+| `CREATE_POST_FROM_APP`, `PUBLISH_GENERATION_OUTPUTS` | — | No v1 route; both also showed a host confirmation per post, which an API call does not |
+| `SET_COLLECTION_FOLLOW` | — | No v1 route |
+| `GET_DAILY_COMPENSATION`, `GET_WILDCARD_PACK`, `TRACK_EVENT` | — | Not carried |
+
+## What a direct orchestrator call loses
+
+Submitting through the host went through civitai's own `blocks.submitWorkflow`,
+which added controls a direct call does not get:
+
+- **Spend caps.** A per-call `buzzBudget`, a per-viewer daily cap and a per-app
+  daily cap, all enforced by civitai. A direct call has only the orchestrator's
+  per-token budget, taken from the viewer's consent.
+- **Attribution.** civitai tagged each workflow with the app and block it came
+  from. The orchestrator records the token's OAuth client internally but not on
+  the workflow, so per-app reporting needs an orchestrator change.
+
+## Host UI still carried
+
+On `app.host`: `requestSignIn`, `download` (was `SAVE_IMAGE`),
+`openResourcePicker`, `openBuzzPurchase`, `resize`, `reportError`, `navigate`
+and `onVisibilityChange`. Consent is `app.requestGrants` (was `requestConsent`).
+
+Not carried: `OPEN_CHECKPOINT_PICKER` (use `openResourcePicker` with
+`resourceType: 'Checkpoint'`), `SET_USER_CHECKPOINT` (inert on a page),
+`OPEN_IMAGE_UPLOAD` (image-only; the site's upload takes media).
+
+## Behaviour
+
+| What | Before | Now |
+|---|---|---|
+| Host failures | free-text `error` on each reply | `BridgeError` with a `code` |
+| Request deadlines | per-message client timeouts | none; pass an `AbortSignal` |
+| A refused grant | rejected | resolves `false` |
+| React hooks | 38 | none — plain functions; bind them in your framework |
+
+## Waiting on the host
+
+For a block to use the API at all, civitai has to:
+
+1. Mint an OAuth access token for the app's own client (`appblk-<slug>`) and
+   send it in `BLOCK_INIT` and `TOKEN_REFRESH`, instead of or beside the block
+   JWT. The auth hub currently bars `appblk-*` clients from its flows.
+2. Let a browser send `Authorization` to `/api/v1` from the app's registered
+   origins; the public routes answer with a wildcard that does not cover it.
+3. Add the `/api/v1` routes above as apps need them, and scope checks.
+
+And the orchestrator has to check that a workflow belongs to the caller before
+reading, changing or deleting it, which it does not today.

package/README.md

@@ -0,0 +1,186 @@
+# `@civitai/sdk`
+
+The Civitai SDK: one client for the public API, the orchestrator and, inside a
+civitai.com page, the host. The same code serves a block app and an app of your
+own. It succeeds `@civitai/app-sdk`, whose 0.x releases continue from this repo
+as a separate codebase.
+
+```ts
+import { initialize } from '@civitai/sdk';
+
+const app = await initialize();
+
+const picked = await app.host.openResourcePicker({ resourceType: 'Checkpoint' });
+if (!picked) return;
+
+const { air } = await app.site.get<{ air: string }>(`model-versions/mini/${picked.versionId}`);
+
+if (!(await app.requestGrants(['ai:write:budgeted']))) return;
+
+const submitted = await app.orchestration.submitWorkflow({
+  steps: [{ $type: 'textToImage', input: { model: air, prompt: 'A lighthouse at dusk' } }],
+});
+const workflow = await app.orchestration.waitForWorkflow(submitted.id!);
+```
+
+An app calls the Civitai API and the orchestrator as the viewer, with a token.
+Reading images, creating posts, running a workflow — all of it is an API call.
+A block additionally asks its host page to show the host's own UI.
+
+## `initialize()`
+
+| Call | Where | Resolves |
+|---|---|---|
+| `initialize()` | A block on civitai.com | Once the host hands over the viewer, the slot and a token. Rejects with `BridgeError` `unavailable` if no host answers within `timeoutMs` (10s) |
+| `initialize({ token, refresh?, requestGrants? })` | Anywhere else, typically your server | At once, with the OAuth access token you hold |
+| `initialize(await createSignIn(...))` | A web app outside civitai.com | At once, as the viewer who signed in; see below |
+
+Both give you:
+
+| Member | What it is |
+|---|---|
+| `app.site` | The public REST API at `/api/v1`: `get`, `post`, `request` |
+| `app.orchestration` | Workflows: `submitWorkflow`, `estimateWorkflow`, `getWorkflow`, `watchWorkflow`, `waitForWorkflow`, `cancelWorkflow`, `queryWorkflows` |
+| `app.requestGrants(scopes)` | Asks for more scopes; resolves `false` when they cannot be granted |
+| `app.getToken()` | For a call this client does not make |
+
+A block's `app` also has `host`, `viewer`, `context`, `settings`, `theme` and
+`onChange(listener)`. Outside a block they do not exist, and the types say so.
+
+> **Not yet end to end for blocks.** The host still mints a block-scoped JWT,
+> which `/api/v1` and the orchestrator do not accept; they take API keys and
+> OAuth tokens. Apps with one of those work today, from a browser or a server.
+
+## Signing in outside civitai.com
+
+A browser app signs the viewer in with Civitai itself: PKCE against
+`auth.civitai.com`, no server and no client secret. Register the app as a
+public OAuth client with its origins and redirect URL.
+
+```ts
+import { createSignIn, initialize } from '@civitai/sdk';
+
+const auth = await createSignIn({ clientId, scopes: ['user:read:self', 'ai:write:budgeted'] });
+if (!auth.signedIn) {
+  button.onclick = () => auth.signIn();
+  if (auth.returning) auth.signIn();
+} else {
+  const app = await initialize(auth);
+}
+```
+
+`createSignIn` finishes the return from Civitai when the page has just come
+back from it, and takes `code` and `state` out of the address bar. Tokens live
+in memory only and refresh themselves; storage holds only the sign-in in flight
+and a flag that the viewer signed in before (`returning`). Signing in again is
+a quick round trip, since Civitai remembers the consent. `requestGrants` goes
+back to Civitai for anything not yet granted.
+
+Only scopes with an OAuth equivalent can be asked for: `user:read:self`,
+`models:read:self`, `ai:write:budgeted`, `buzz:read:self`, `posts:write:self`
+and `social:tip:self`. The storage and collection scopes belong to blocks.
+`/api/v1` and the orchestrator both accept these tokens from any origin.
+
+## The API
+
+Routes are addressed by path, so a route `/api/v1` gains needs no release here:
+
+```ts
+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.
+
+## The orchestrator
+
+Steps are typed by `$type`: `input` is checked against that step's own input,
+and narrowing a returned step on `$type` types its `output`. The union is
+generated from `@civitai/orchestration-client` (`npm run gen:steps`), so a step
+type the orchestrator gains arrives with a client update and no code here.
+
+An output is listed before it exists — check `available` before showing it.
+
+```ts
+for await (const workflow of app.orchestration.watchWorkflow(id)) {
+  render(workflow); // now, then each time it changes, until a final status
+}
+```
+
+`watchWorkflow` reads the workflow, then holds each further read open on the
+orchestrator until something changes (`?until=change`), and yields only when
+it did. `waitForWorkflow` is its last value — a failed workflow resolves, it
+does not throw. Both wait out a brief outage and give up on a refusal; break out
+of the loop or pass a `signal` to stop.
+
+> An orchestrator without `until=change` holds each read until the workflow
+> finishes or 20s pass, so mid-run progress arrives up to 20s late.
+
+[`examples/generate.ts`](./examples/generate.ts) runs all of it from a server:
+`pnpm build && CIVITAI_TOKEN=… node examples/generate.ts [modelVersionId] [prompt]`,
+with `ORCHESTRATION_URL` / `CIVITAI_SITE_URL` to point it at a local stack.
+
+## Grants
+
+Scopes are typed (`Scope`, and the list as `SCOPES`), so a misspelt scope fails
+to compile rather than being quietly refused.
+
+In a block, `requestGrants` opens the host's consent dialog and resolves once
+the re-minted token carries the scopes. A viewer who closes the dialog sends
+nothing, so pass a `signal` to bound the wait. Given a token, `requestGrants`
+is yours to supply — typically re-running your OAuth authorize flow with the
+wider scope — and refuses without one.
+
+## The host
+
+| Call | What the host does |
+|---|---|
+| `resize(height)` | Resizes the frame, clamped to the manifest |
+| `autoResize(element?)` | Keeps the frame as tall as the body (or `element`); returns a stop function |
+| `reportError(message, { fatal })` | `fatal` swaps the block for the host's fallback |
+| `navigate(path, { target })` | Deep-links within this app's own sub-paths |
+| `onVisibilityChange(handler)` | Reports the page hiding and returning |
+| `requestSignIn({ returnUrl })` | Starts sign-in; the block re-initialises signed in |
+| `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 }` |
+
+Host failures reject with a `BridgeError` carrying a `code` (`forbidden`,
+`unauthenticated`, `rate-limited`, …). Timeouts are the host's to set; pass a
+`signal` to cancel. `ApiError` and `BridgeError` both extend `CivitaiError`, so
+one `catch` can tell a refusal from a bug.
+
+## Parent origins
+
+Messages are accepted only from an allowlisted parent origin. The allowlist is
+read from `VITE_` / `NEXT_PUBLIC_` / `PUBLIC_BLOCK_ALLOWED_PARENT_ORIGINS` at
+build time, falling back to the canonical civitai.com origins when there is no
+build step. To override at runtime, call `getTransport({ allowedParentOrigins })`
+before `initialize()`; options apply on first use only.
+
+Wildcards take the form `https://*.example.com` and match subdomains on a dot
+boundary. A port never matches a wildcard — list a ported parent as an exact
+entry.
+
+## Testing
+
+`@civitai/sdk/testing` has `createFakeTransport()`: pass it as
+`initialize({ transport })` and script the host's answers.
+
+## Checks
+
+- `npm run api` regenerates [`api/public-api.md`](./api/public-api.md) from the
+  compiler's own declarations; CI fails when it is stale.
+- `npm run check:parity` fails when a message sent here has no handler in the
+  host, checked against a committed snapshot of civitai's handler inventory.
+  Refresh it with `npm run snapshot:host`.
+- `npm run check:layering` keeps `core` free of any domain.
+- `npm run check:steps` fails when the step unions no longer match the
+  installed `@civitai/orchestration-client`.
+
+See [`BREAKING.md`](./BREAKING.md) for what an app gives up moving from
+`@civitai/app-sdk` 0.x and `@civitai/blocks-react`.
+
+## License
+
+MIT

package/dist/app/index.d.ts

@@ -0,0 +1,50 @@
+import type { BlockContext, BlockSettings, Theme, ViewerInfo } from '../core/handshake.js';
+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 SiteClient } from '../site/index.js';
+export interface AppClient {
+    /** The public Civitai REST API (`/api/v1`), as the viewer. */
+    readonly site: SiteClient;
+    /** The orchestrator's workflows, as the viewer. */
+    readonly orchestration: OrchestrationClient;
+    /** Asks for more scopes. `false` when they cannot be granted — a refusal is an answer. */
+    requestGrants(scopes: readonly Scope[], opts?: GrantOptions): Promise<boolean>;
+    /** For a call this client does not make itself. */
+    getToken(opts?: TokenOptions): Promise<string>;
+}
+/** An app running as a block inside a civitai.com page. */
+export interface BlockAppClient extends AppClient {
+    readonly host: Host;
+    /** `null` for an anonymous viewer. */
+    readonly viewer: ViewerInfo | null;
+    readonly context: BlockContext;
+    readonly settings: BlockSettings;
+    readonly theme: Theme;
+    /** Fires when anything above changes, e.g. the viewer switches theme. */
+    onChange(listener: () => void): () => void;
+}
+interface ClientOptions {
+    /** Defaults to `https://civitai.com/api/v1`. */
+    siteUrl?: string;
+    /** Defaults to `https://orchestration.civitai.com`. */
+    orchestrationUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface BlockInitializeOptions extends ClientOptions {
+    /** How long to wait for the host before rejecting. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Replaces the page's own bridge, e.g. with `createFakeTransport()` in a test. */
+    transport?: BlockTransport;
+}
+export interface TokenInitializeOptions extends ClientOptions, TokenSessionOptions {
+}
+/**
+ * Starts the app. Inside a civitai.com page it waits for the host to hand over
+ * the viewer, the slot and a token; given a token, it is ready at once.
+ */
+export declare function initialize(options?: BlockInitializeOptions): Promise<BlockAppClient>;
+export declare function initialize(options: TokenInitializeOptions): Promise<AppClient>;
+export {};

package/dist/app/index.js

@@ -0,0 +1,64 @@
+import { BridgeError } from '../core/errors.js';
+import { getTransport } from '../core/get-transport.js';
+import { createHost, createHostSession } from '../host/index.js';
+import { createHttp } from '../http/index.js';
+import { createOrchestrationClient, DEFAULT_ORCHESTRATION_URL, } from '../orchestration/index.js';
+import { createTokenSession, } from '../session/index.js';
+import { createSiteClient, DEFAULT_SITE_URL } from '../site/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;
+export async function initialize(options = {}) {
+    if ('token' in options)
+        return createAppClient(createTokenSession(options), options);
+    const transport = options.transport ?? getTransport();
+    await ready(transport, options.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS, options.signal);
+    const snapshot = () => transport.snapshot.get();
+    return {
+        ...createAppClient(createHostSession(transport), options),
+        host: createHost(transport),
+        get viewer() {
+            return snapshot().viewer;
+        },
+        get context() {
+            return snapshot().context;
+        },
+        get settings() {
+            return snapshot().settings;
+        },
+        get theme() {
+            return snapshot().theme;
+        },
+        onChange: (listener) => transport.snapshot.subscribe(listener),
+    };
+}
+function createAppClient(session, options) {
+    const http = (baseUrl) => createHttp({ session, baseUrl, fetch: options.fetch });
+    return {
+        site: createSiteClient(http(options.siteUrl ?? DEFAULT_SITE_URL)),
+        orchestration: createOrchestrationClient(http(options.orchestrationUrl ?? DEFAULT_ORCHESTRATION_URL)),
+        requestGrants: (scopes, opts) => session.requestGrants(scopes, opts),
+        getToken: (opts) => session.getToken(opts),
+    };
+}
+function ready(transport, timeoutMs, signal) {
+    if (transport.snapshot.get().ready)
+        return Promise.resolve();
+    if (signal?.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const finish = (settle) => {
+            clearTimeout(timer);
+            off();
+            signal?.removeEventListener('abort', onAbort);
+            settle();
+        };
+        const onAbort = () => finish(() => reject(signal.reason));
+        const timer = setTimeout(() => finish(() => reject(new BridgeError('unavailable', 'BLOCK_INIT', `No Civitai host responded within ${timeoutMs}ms. Outside a civitai.com page, ` +
+            'pass a token: initialize({ token }).'))), timeoutMs);
+        const off = transport.snapshot.subscribe(() => {
+            if (transport.snapshot.get().ready)
+                finish(resolve);
+        });
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,19 @@
+/** Every failure the host classifies, so a caller branches on a code not a string. */
+export type BridgeFailureCode = 'forbidden'
+/** The host gave up waiting on something it called. */
+ | 'timeout' | 'unauthenticated' | 'insufficient' | 'rate-limited' | 'unavailable' | 'invalid';
+/** Every failure a service can surface, so a caller can branch without string matching. */
+export type BridgeErrorCode = BridgeFailureCode
+/** The transport got an answer it could not read as a result. */
+ | 'malformed';
+/** Anything this package throws on purpose, so one `catch` can tell it from a bug. */
+export declare class CivitaiError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class BridgeError extends CivitaiError {
+    readonly code: BridgeErrorCode;
+    /** The message type that failed, e.g. `SAVE_IMAGE`. */
+    readonly operation: string;
+    constructor(code: BridgeErrorCode, operation: string, message: string, options?: ErrorOptions);
+}
+export declare function classifyHostError(message: string): BridgeFailureCode;

package/dist/core/errors.js

@@ -0,0 +1,42 @@
+/** Anything this package throws on purpose, so one `catch` can tell it from a bug. */
+export class CivitaiError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'CivitaiError';
+    }
+}
+export class BridgeError extends CivitaiError {
+    code;
+    /** The message type that failed, e.g. `SAVE_IMAGE`. */
+    operation;
+    constructor(code, operation, message, options) {
+        super(message, options);
+        this.name = 'BridgeError';
+        this.code = code;
+        this.operation = operation;
+    }
+}
+/**
+ * The messages this bridge already had report failure as the server's own
+ * sentence — the host holds the tRPC code and drops it. Unmatched text is
+ * `unavailable`; `message` still carries what the host said.
+ */
+const HOST_FAILURES = [
+    [/authenticated viewer|no block token/i, 'unauthenticated'],
+    [
+        /(requires|lacks) .+ scope|not approved|revoked|invalid block token|not enabled|review preview|^banned$/i,
+        'forbidden',
+    ],
+    [/rate limit|^busy$/i, 'rate-limited'],
+    // A few of the host's older replies carry a code of their own in `error`.
+    [/^(forbidden|review-mode|declined)$/i, 'forbidden'],
+    [/^sign-in-required$/i, 'unauthenticated'],
+    [/^too-large$/i, 'insufficient'],
+    [/^(not-found|parse-failed|invalid-request|collection-unavailable)$/i, 'invalid'],
+];
+export function classifyHostError(message) {
+    for (const [pattern, code] of HOST_FAILURES)
+        if (pattern.test(message))
+            return code;
+    return 'unavailable';
+}

package/dist/core/get-transport.d.ts

@@ -0,0 +1,11 @@
+import type { BlockTransport } from './transport.js';
+export interface DetectOptions {
+    /** Overrides the env-derived allowlist and the built-in default. */
+    allowedParentOrigins?: string[];
+    /** Override `globalThis.window`. Tests use this with `happy-dom`'s window. */
+    window?: Window;
+}
+/** Options apply on first call only; `__resetTransport()` to re-detect. */
+export declare function getTransport(opts?: DetectOptions): BlockTransport;
+/** Test-only. */
+export declare function __resetTransport(): void;

package/dist/core/get-transport.js

@@ -0,0 +1,101 @@
+import { IframeTransport } from './transports/iframe-transport.js';
+/** First match wins across the VITE_ / NEXT_PUBLIC_ / PUBLIC_ spellings. */
+function readAllowedOriginsFromEnv() {
+    const raw = readViteVar() ?? readNextPublicVar() ?? readPublicVar();
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+// Every key is spelled as a literal member access. Bundlers substitute only that
+// form: a computed `import.meta.env[key]` makes Vite inline the whole env object,
+// every VITE_* secret included, and `process.env[key]` is never replaced at all.
+// The try/catch is what makes a bare `process` safe in a browser.
+function readViteVar() {
+    try {
+        const v = import.meta.env?.VITE_BLOCK_ALLOWED_PARENT_ORIGINS;
+        if (v)
+            return v;
+    }
+    catch { }
+    try {
+        return process.env.VITE_BLOCK_ALLOWED_PARENT_ORIGINS || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readNextPublicVar() {
+    try {
+        const v = import.meta.env?.NEXT_PUBLIC_BLOCK_ALLOWED_PARENT_ORIGINS;
+        if (v)
+            return v;
+    }
+    catch { }
+    try {
+        return process.env.NEXT_PUBLIC_BLOCK_ALLOWED_PARENT_ORIGINS || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPublicVar() {
+    try {
+        const v = import.meta.env?.PUBLIC_BLOCK_ALLOWED_PARENT_ORIGINS;
+        if (v)
+            return v;
+    }
+    catch { }
+    try {
+        return process.env.PUBLIC_BLOCK_ALLOWED_PARENT_ORIGINS || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fallback for consumers with no build step to read env from (a CDN bundle).
+ * `*.civit.ai` is deliberately absent — blocks are *served* there, so allowing
+ * it as a parent would let one block drive another's bridge.
+ */
+const DEFAULT_ALLOWED_PARENT_ORIGINS = [
+    'https://civitai.com',
+    'https://civitai.red',
+    'https://civitai.green',
+    'https://*.civitai.com',
+    'https://*.civitaic.com',
+];
+function detectTransport(opts = {}) {
+    // An explicit `[]` from the caller is an assertion, not an omission — leave
+    // it empty so IframeTransport still throws.
+    const fromEnv = readAllowedOriginsFromEnv();
+    const allowedParentOrigins = opts.allowedParentOrigins ??
+        (fromEnv.length ? fromEnv : [...DEFAULT_ALLOWED_PARENT_ORIGINS]);
+    return new IframeTransport({ allowedParentOrigins, window: opts.window });
+}
+// On globalThis, not a module `let`: a CDN copy and a bundled copy are separate
+// module instances, and one transport each means a duplicate BLOCK_READY.
+const CACHE_KEY = Symbol.for('civitai.blocks.transport');
+function slot() {
+    return globalThis;
+}
+/** Options apply on first call only; `__resetTransport()` to re-detect. */
+export function getTransport(opts) {
+    const g = slot();
+    const cached = g[CACHE_KEY];
+    if (cached)
+        return cached;
+    const created = detectTransport(opts);
+    g[CACHE_KEY] = created;
+    return created;
+}
+/** Test-only. */
+export function __resetTransport() {
+    const g = slot();
+    // Some transports allocate listeners; dispose if possible.
+    const disposable = g[CACHE_KEY];
+    disposable?.dispose?.();
+    g[CACHE_KEY] = null;
+}

package/dist/core/handshake.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The host's side of the handshake, as it arrives on the wire. The shapes are
+ * the host's and must track it.
+ */
+export type Theme = 'light' | 'dark';
+/** Informational only — derive SFW from a browsing level, never from this. */
+export type ColorDomain = 'green' | 'blue' | 'red';
+export interface ViewerInfo {
+    signedIn?: true;
+    id: number;
+    username: string | null;
+    status?: 'active' | 'banned' | 'muted';
+}
+export type ModelSlotId = 'model.sidebar_top' | 'model.below_images' | 'model.actions_extra';
+export type PageSlotId = 'app.page';
+export interface ShowcaseImage {
+    id: number;
+    url: string;
+    width: number;
+    height: number;
+    prompt: string | null;
+    negativePrompt: string | null;
+    cfgScale: number | null;
+    steps: number | null;
+    seed: number | null;
+    sampler: string | null;
+    /** Per-resource CLIP layer skip count (SD1/SDXL). Flux ignores it. */
+    clipSkip: number | null;
+}
+export interface BlockCheckpointInfo {
+    versionId: number;
+    modelId: number;
+    modelName: string;
+    versionName: string;
+    baseModel: string;
+}
+export interface ModelSlotContext {
+    slotId: ModelSlotId;
+    modelId: number;
+    modelVersionId: number;
+    modelName: string;
+    modelType: string;
+    modelNsfwLevel: number;
+    theme?: Theme;
+    checkpoint?: BlockCheckpointInfo | null;
+    showcaseImages?: ShowcaseImage[];
+}
+export interface PageSlotContext {
+    slotId: PageSlotId;
+    entityType?: 'none';
+    slug: string;
+    subPath: string;
+    viewerUserId: number | null;
+    viewerUsername?: string | null;
+    theme?: Theme;
+}
+/** A slot this package does not know; `slotId` is all that is guaranteed. */
+export interface UnknownSlotContext {
+    slotId: string;
+}
+export type BlockContext = ModelSlotContext | PageSlotContext | UnknownSlotContext;
+export interface BlockSettings {
+    publisherSettings: Record<string, unknown>;
+    userSettings: Record<string, unknown>;
+}
+/** A token on the wire; `expiresAt` is ISO-8601 until the transport parses it. */
+export interface WrappedToken {
+    raw: string;
+    scopes: string[];
+    expiresAt: string;
+    buzzBudget?: number;
+}
+export interface BlockToken {
+    raw: string;
+    scopes: string[];
+    expiresAt: Date;
+    buzzBudget?: number;
+}
+/**
+ * The host still sends `blockId` and `appId`; they are build-time identity a
+ * block reads from its own manifest, so they are not declared here.
+ */
+export interface BlockInitPayload {
+    blockInstanceId: string;
+    token: WrappedToken;
+    context: BlockContext;
+    settings: BlockSettings;
+    /** `null` for anonymous viewers. */
+    viewer: ViewerInfo | null;
+    theme: Theme;
+    renderMode: 'iframe' | 'inline';
+    domain?: ColorDomain | null;
+    /** Domain ceiling bitmask; `undefined` means fail closed to SFW. */
+    maxBrowsingLevel?: number;
+    /** The domain ceiling narrowed to this viewer. Always a subset of the above. */
+    effectiveBrowsingLevel?: number;
+}
+/** Host messages the transport itself acts on. Domains own everything else. */
+export type HostMessage = {
+    type: 'BLOCK_INIT';
+    payload: BlockInitPayload;
+} | {
+    type: 'TOKEN_REFRESH';
+    payload: {
+        token: WrappedToken;
+    };
+} | {
+    type: 'TOKEN_REFRESH_RESPONSE';
+    payload: {
+        requestId: string;
+        token: WrappedToken;
+    };
+} | {
+    type: 'THEME_CHANGE';
+    payload: {
+        theme: Theme;
+    };
+};
+/** Discriminator only — the payload is still unvalidated wire data. */
+export declare function isHostMessage<K extends HostMessage['type']>(data: unknown, type: K): data is Extract<HostMessage, {
+    type: K;
+}>;
+export interface BlockInitFragment {
+    theme?: Theme;
+    renderMode?: 'iframe' | 'inline';
+    blockInstanceId?: string;
+}
+/**
+ * The theme and render mode the host put in the URL so a block can paint before
+ * `BLOCK_INIT` arrives. Frozen at mount — a later toggle arrives as
+ * `THEME_CHANGE`, never as a re-navigation of a third-party frame.
+ */
+export declare function parseBlockInitFragment(hash: string | null | undefined): BlockInitFragment;
+/** The hash with the host's own keys removed, or `null` when it wrote none. */
+export declare function stripBlockInitFragment(hash: string | null | undefined): string | null;