@civitai/sdk 0.2.0

package/dist/sign-in/index.js

@@ -0,0 +1,209 @@
+import { CivitaiError } from '../core/errors.js';
+export const DEFAULT_AUTH_URL = 'https://auth.civitai.com';
+// The site's own table (BLOCK_SCOPE_TO_OAUTH_BIT). Storage and collection scopes have no OAuth bit.
+const OAUTH_BITS = {
+    'user:read:self': 1 << 0,
+    'posts:write:self': 1 << 6,
+    'ai:write:budgeted': 1 << 15,
+    'buzz:read:self': 1 << 16,
+    'social:tip:self': 1 << 20,
+    'models:read:self': 1 << 2,
+};
+/** Refreshed this long before it expires, so a request never carries a token that dies in flight. */
+const EXPIRY_MARGIN_MS = 60_000;
+export class SignInError extends CivitaiError {
+    status;
+    constructor(message, status, options) {
+        super(message, options);
+        this.name = 'SignInError';
+        this.status = status;
+    }
+}
+export function scopeBitmask(scopes) {
+    let mask = 0;
+    for (const scope of scopes) {
+        const bit = OAUTH_BITS[scope];
+        if (bit === undefined)
+            throw new SignInError(`${scope} is only granted to apps running inside civitai.com`);
+        mask |= bit;
+    }
+    return mask;
+}
+function scopesIn(mask) {
+    return Object.keys(OAUTH_BITS).filter((scope) => (mask & OAUTH_BITS[scope]) !== 0);
+}
+function base64Url(bytes) {
+    return btoa(String.fromCharCode(...bytes))
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+const randomString = () => base64Url(crypto.getRandomValues(new Uint8Array(32)));
+async function challengeFor(verifier) {
+    return base64Url(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))));
+}
+function readJson(storage, key) {
+    try {
+        const raw = storage.getItem(key);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(storage, key, value) {
+    try {
+        if (value === null)
+            storage.removeItem(key);
+        else
+            storage.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // Private windows can refuse storage; the viewer then signs in again next visit.
+    }
+}
+/**
+ * Sign-in with Civitai for an app outside civitai.com. Completes the return
+ * from Civitai when the page has just come back from it.
+ */
+export async function createSignIn(options) {
+    const win = options.window ?? window;
+    const storage = options.storage ?? win.localStorage;
+    const doFetch = options.fetch ?? fetch.bind(globalThis);
+    const authUrl = options.authUrl ?? DEFAULT_AUTH_URL;
+    const key = `civitai.sign-in.${options.clientId}`;
+    const pendingKey = `${key}.pending`;
+    const returningKey = `${key}.returning`;
+    const requested = scopeBitmask(options.scopes);
+    let tokens = null;
+    let error = null;
+    let refreshing = null;
+    const save = (next) => {
+        tokens = next;
+        writeJson(storage, returningKey, next ? true : null);
+    };
+    const tokenRequest = async (body, fallbackScope) => {
+        const res = await doFetch(`${authUrl}/api/auth/oauth/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ ...body, client_id: options.clientId }),
+        });
+        const json = (await res.json().catch(() => ({})));
+        if (!res.ok || !json.access_token) {
+            throw new SignInError(json.error_description ?? json.error ?? `token request failed: ${res.status}`, res.status);
+        }
+        const scope = Number(json.scope);
+        return {
+            accessToken: json.access_token,
+            refreshToken: json.refresh_token ?? body.refresh_token,
+            expiresAt: Date.now() + (json.expires_in ?? 3600) * 1000,
+            // The hub may omit scope when it granted exactly what was asked (RFC 6749 §5.1).
+            scope: Number.isSafeInteger(scope) && scope >= 0 ? scope : fallbackScope,
+        };
+    };
+    const refresh = () => {
+        refreshing ??= (async () => {
+            const held = tokens;
+            if (!held?.refreshToken) {
+                save(null);
+                throw new SignInError('not signed in', 401);
+            }
+            try {
+                const next = await tokenRequest({ grant_type: 'refresh_token', refresh_token: held.refreshToken }, held.scope);
+                save(next);
+                return next.accessToken;
+            }
+            catch (err) {
+                if (err instanceof SignInError && err.status !== undefined && err.status < 500)
+                    save(null);
+                throw err;
+            }
+        })().finally(() => {
+            refreshing = null;
+        });
+        return refreshing;
+    };
+    const signIn = async ({ scopes } = {}) => {
+        const verifier = randomString();
+        const pending = {
+            state: randomString(),
+            verifier,
+            redirectUri: options.redirectUri ?? `${win.location.origin}${win.location.pathname}`,
+            scope: requested | (scopes ? scopeBitmask(scopes) : 0) | (tokens?.scope ?? 0),
+        };
+        writeJson(storage, pendingKey, pending);
+        const url = new URL('/api/auth/oauth/authorize', authUrl);
+        url.search = new URLSearchParams({
+            client_id: options.clientId,
+            redirect_uri: pending.redirectUri,
+            response_type: 'code',
+            state: pending.state,
+            scope: String(pending.scope),
+            code_challenge: await challengeFor(verifier),
+            code_challenge_method: 'S256',
+        }).toString();
+        win.location.assign(url.toString());
+        return new Promise(() => { });
+    };
+    const params = new URLSearchParams(win.location.search);
+    const pending = readJson(storage, pendingKey);
+    if (pending && params.get('state') === pending.state) {
+        writeJson(storage, pendingKey, null);
+        const code = params.get('code');
+        const clean = new URL(win.location.href);
+        for (const key of ['code', 'state', 'error', 'error_description'])
+            clean.searchParams.delete(key);
+        win.history.replaceState(win.history.state, '', clean.toString());
+        try {
+            if (!code)
+                throw new SignInError(params.get('error_description') ?? params.get('error') ?? 'sign-in was declined');
+            save(await tokenRequest({
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: pending.redirectUri,
+                code_verifier: pending.verifier,
+            }, pending.scope));
+        }
+        catch (err) {
+            error = err instanceof SignInError ? err : new SignInError('sign-in failed', undefined, { cause: err });
+        }
+    }
+    return {
+        get signedIn() {
+            return tokens !== null;
+        },
+        get returning() {
+            return tokens === null && readJson(storage, returningKey) === true;
+        },
+        get grantedScopes() {
+            return tokens ? scopesIn(tokens.scope) : [];
+        },
+        get error() {
+            return error;
+        },
+        token: async () => {
+            if (!tokens)
+                throw new SignInError('not signed in', 401);
+            return tokens.expiresAt - EXPIRY_MARGIN_MS > Date.now() ? tokens.accessToken : refresh();
+        },
+        refresh,
+        requestGrants: async (scopes) => {
+            const wanted = scopeBitmask(scopes);
+            if (tokens && (tokens.scope & wanted) === wanted)
+                return true;
+            return signIn({ scopes });
+        },
+        signIn,
+        signOut: async () => {
+            const held = tokens;
+            save(null);
+            if (!held)
+                return;
+            await doFetch(`${authUrl}/api/auth/oauth/revoke`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({ token: held.refreshToken ?? held.accessToken, client_id: options.clientId }),
+            }).catch(() => undefined);
+        },
+    };
+}

package/dist/site/index.d.ts

@@ -0,0 +1,12 @@
+import type { Http, RequestOptions } from '../http/index.js';
+export declare const DEFAULT_SITE_URL = "https://civitai.com/api/v1";
+/**
+ * The public Civitai REST API. Routes are addressed by path, so a route the
+ * API gains needs no release here.
+ */
+export interface SiteClient {
+    get<T = unknown>(path: string, opts?: Omit<RequestOptions, 'body'>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: Omit<RequestOptions, 'body'>): Promise<T>;
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+}
+export declare function createSiteClient(http: Http): SiteClient;

package/dist/site/index.js

@@ -0,0 +1,8 @@
+export const DEFAULT_SITE_URL = 'https://civitai.com/api/v1';
+export function createSiteClient(http) {
+    return {
+        get: (path, opts) => http('GET', path, opts),
+        post: (path, body, opts) => http('POST', path, { ...opts, body }),
+        request: (method, path, opts) => http(method, path, opts),
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1,36 @@
+import { type BlockSnapshot, type BlockTransport } from './core/transport.js';
+import { type BridgeFailureCode } from './core/errors.js';
+export { __resetTransport } from './core/get-transport.js';
+export interface FakeTransport extends BlockTransport {
+    /** Every request sent, in order. */
+    readonly sent: {
+        type: string;
+        payload: unknown;
+    }[];
+    /**
+     * Answer every request of this type from its params. Throw from the handler
+     * to fail the call. A queued `reply`/`fail` is used first, so one call can
+     * depart from the standing answer.
+     */
+    handle(type: string, handler: (params: unknown) => unknown): void;
+    /** Answer the next request of this type with the value it resolves to. */
+    reply(type: string, result: unknown): void;
+    /** Answer the next request of this type with a failure the host classified. */
+    fail(type: string, error: {
+        code: BridgeFailureCode;
+        message: string;
+    }): void;
+    /** Never answer requests of this type; for deadline and abort tests. */
+    stall(type: string): void;
+    /** Deliver an unsolicited host push to `on` subscribers. */
+    push(type: string, payload: unknown): void;
+    /** Subscribers to a push, so a test can assert one stopped listening. */
+    listenerCount(type: string): number;
+    setSnapshot(next: Partial<BlockSnapshot>): void;
+}
+/**
+ * An in-memory `BlockTransport` for testing a service against a scripted host.
+ * Replaces driving a full mock host through `postMessage` when the thing under
+ * test is one operation.
+ */
+export declare function createFakeTransport(snapshot?: Partial<BlockSnapshot>): FakeTransport;

package/dist/testing.js

@@ -0,0 +1,108 @@
+import { EMPTY_SNAPSHOT } from './core/transport.js';
+import { BridgeError } from './core/errors.js';
+export { __resetTransport } from './core/get-transport.js';
+/**
+ * An in-memory `BlockTransport` for testing a service against a scripted host.
+ * Replaces driving a full mock host through `postMessage` when the thing under
+ * test is one operation.
+ */
+export function createFakeTransport(snapshot = {}) {
+    let current = {
+        ...EMPTY_SNAPSHOT,
+        ready: true,
+        hostOrigin: 'https://civitai.com',
+        ...snapshot,
+    };
+    const listeners = new Set();
+    const sent = [];
+    const queued = new Map();
+    const stalled = new Set();
+    const pending = new Map();
+    const handlers = new Map();
+    const pushListeners = new Map();
+    const emit = () => {
+        for (const l of [...listeners])
+            l();
+    };
+    /** A queued answer is either the value or the failure the host reported. */
+    const settle = (answer) => answer instanceof BridgeError ? Promise.reject(answer) : Promise.resolve(answer);
+    const answer = (type, outcome) => {
+        const waiting = pending.get(type);
+        if (waiting?.length) {
+            waiting.shift()(outcome);
+            return;
+        }
+        queued.set(type, [...(queued.get(type) ?? []), outcome]);
+    };
+    return {
+        sent,
+        snapshot: {
+            get: () => current,
+            subscribe(listener) {
+                listeners.add(listener);
+                return () => listeners.delete(listener);
+            },
+        },
+        notify(message) {
+            sent.push({ type: message.type, payload: message.payload });
+        },
+        request(type, params, opts = {}) {
+            sent.push({ type, payload: params });
+            const responseType = type;
+            const { signal } = opts;
+            if (signal?.aborted)
+                return Promise.reject(signal.reason);
+            if (stalled.has(responseType)) {
+                return new Promise((_resolve, reject) => {
+                    signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
+                });
+            }
+            const ready = queued.get(responseType);
+            if (ready?.length)
+                return settle(ready.shift());
+            const standing = handlers.get(responseType);
+            if (standing)
+                return (async () => standing(params))();
+            return new Promise((resolve, reject) => {
+                signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
+                const waiting = pending.get(responseType) ?? [];
+                waiting.push((outcome) => {
+                    if (outcome instanceof BridgeError)
+                        reject(outcome);
+                    else
+                        resolve(outcome);
+                });
+                pending.set(responseType, waiting);
+            });
+        },
+        on(type, handler) {
+            const set = pushListeners.get(type) ?? new Set();
+            set.add(handler);
+            pushListeners.set(type, set);
+            return () => set.delete(handler);
+        },
+        push(type, payload) {
+            for (const handler of [...(pushListeners.get(type) ?? [])])
+                handler(payload);
+        },
+        listenerCount(type) {
+            return pushListeners.get(type)?.size ?? 0;
+        },
+        handle(type, handler) {
+            handlers.set(type, handler);
+        },
+        reply(type, result) {
+            answer(type, result);
+        },
+        fail(type, error) {
+            answer(type, new BridgeError(error.code, type, error.message));
+        },
+        stall(type) {
+            stalled.add(type);
+        },
+        setSnapshot(next) {
+            current = { ...current, ...next };
+            emit();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@civitai/sdk",
+  "version": "0.2.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",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "BREAKING.md",
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "api": "node scripts/api-report.mjs",
+    "api:check": "node scripts/api-report.mjs --check",
+    "check:layering": "node scripts/check-layering.mjs",
+    "check:parity": "node scripts/check-host-parity.mjs",
+    "gen:steps": "node scripts/gen-step-types.mjs",
+    "check:steps": "node scripts/gen-step-types.mjs --check",
+    "snapshot:host": "node scripts/snapshot-host-messages.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json && tsc -p tsconfig.examples.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "civitai",
+    "sdk",
+    "api",
+    "orchestration",
+    "iframe",
+    "postmessage"
+  ],
+  "homepage": "https://github.com/civitai/civitai-app-starters/tree/main/packages/civitai-sdk#readme",
+  "bugs": "https://github.com/civitai/civitai-app-starters/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/civitai/civitai-app-starters.git",
+    "directory": "packages/civitai-sdk"
+  },
+  "dependencies": {
+    "@civitai/orchestration-client": "0.2.0-beta.101"
+  }
+}