@civitai/app-sdk 0.1.0 → 0.7.0

package/schemas/app-block/v1.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://civitai.com/schemas/app-block/v1.json",
+  "title": "Civitai App Block Manifest v1",
+  "description": "Manifest shape for a Civitai App Block. Mirrors the runtime check performed by defineBlock() in @civitai/app-sdk/blocks.",
+  "type": "object",
+  "required": [
+    "$schema",
+    "appId",
+    "blockId",
+    "version",
+    "name",
+    "type",
+    "targets",
+    "scopes",
+    "iframe",
+    "contentRating",
+    "minApiVersion"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://civitai.com/schemas/app-block/v1.json"
+    },
+    "appId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "blockId": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]{3,64}$",
+      "description": "Immutable block identifier. Lowercase letters, digits, and hyphens; 3-64 characters."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+      "description": "Semver."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "type": {
+      "type": "string",
+      "enum": ["block", "embed"]
+    },
+    "targets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["slotId", "priority"],
+        "properties": {
+          "slotId": { "type": "string", "minLength": 1 },
+          "priority": { "type": "integer" },
+          "requiredContext": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "scopes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z]+:[a-z]+:[a-z]+$",
+        "description": "Colon-separated lowercase, e.g. models:read:self. PascalCase is rejected."
+      }
+    },
+    "iframe": {
+      "type": "object",
+      "required": ["src", "minHeight", "resizable", "sandbox"],
+      "properties": {
+        "src": {
+          "type": "string",
+          "description": "HTTPS URL of the block app. http://localhost or http://127.0.0.1 also accepted for local dev."
+        },
+        "minHeight": { "type": "integer", "exclusiveMinimum": 0 },
+        "maxHeight": { "type": ["integer", "null"] },
+        "resizable": { "type": "boolean" },
+        "sandbox": {
+          "type": "string",
+          "allOf": [
+            {
+              "not": { "pattern": "(^|\\s)allow-same-origin(\\s|$)" },
+              "description": "Must not contain allow-same-origin — combined with allow-scripts it defeats the sandbox."
+            },
+            {
+              "not": { "pattern": "(^|\\s)allow-top-navigation(\\s|$)" },
+              "description": "Must not contain allow-top-navigation — use the NAVIGATE postMessage instead."
+            },
+            {
+              "not": { "pattern": "(^|\\s)allow-top-navigation-by-user-activation(\\s|$)" },
+              "description": "Must not contain allow-top-navigation-by-user-activation — same threat as allow-top-navigation, gated on a user gesture."
+            },
+            {
+              "not": { "pattern": "(^|\\s)allow-top-navigation-to-custom-protocols(\\s|$)" },
+              "description": "Must not contain allow-top-navigation-to-custom-protocols — same threat as allow-top-navigation, restricted to non-fetch schemes."
+            }
+          ]
+        }
+      }
+    },
+    "assets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["url", "integrity"],
+        "properties": {
+          "url": { "type": "string" },
+          "integrity": {
+            "type": "string",
+            "pattern": "^sha(256|384|512)-[A-Za-z0-9+/=]+$"
+          }
+        }
+      }
+    },
+    "settings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "label"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "type": { "type": "string", "enum": ["string", "number", "boolean", "select"] },
+          "label": { "type": "string", "minLength": 1 },
+          "default": {},
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["value", "label"],
+              "properties": {
+                "value": { "type": "string" },
+                "label": { "type": "string" }
+              }
+            }
+          },
+          "min": { "type": "number" },
+          "max": { "type": "number" },
+          "required": { "type": "boolean" }
+        }
+      }
+    },
+    "contentRating": {
+      "type": "string",
+      "enum": ["g", "pg", "pg13", "r", "x"]
+    },
+    "preview": {
+      "type": "object",
+      "required": ["thumbnail", "description"],
+      "properties": {
+        "thumbnail": { "type": "string" },
+        "description": { "type": "string" },
+        "screenshots": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "promotionEligible": { "type": "boolean" },
+    "minApiVersion": { "type": "string" },
+    "renderMode": {
+      "type": "string",
+      "enum": ["iframe", "inline", "hybrid"],
+      "description": "Optional. Defaults to iframe. v1 manifests may omit."
+    },
+    "assetBundle": {
+      "type": "object",
+      "properties": {
+        "url": { "type": ["string", "null"] },
+        "sha256": { "type": ["string", "null"] }
+      }
+    },
+    "trustTier": {
+      "type": "string",
+      "enum": ["unverified", "verified", "internal"]
+    }
+  }
+}

package/dist/client/index.d.ts

@@ -1,23 +0,0 @@
-import { createCivitaiClient } from '@civitai/client';
-/** The orchestrator client returned by `createCivitaiClient`. */
-export type CivitaiClient = ReturnType<typeof createCivitaiClient>;
-export interface CreateAppClientOptions {
-    /** OAuth access token or personal API key. Used as Bearer credential. */
-    token: string;
-    /** Orchestrator base URL. Defaults to Civitai's prod orchestrator. */
-    baseUrl?: string;
-    /** SDK env mode. Defaults to 'prod'. */
-    env?: 'dev' | 'prod';
-}
-/**
- * Create a typed Civitai orchestrator client authenticated with the user's
- * OAuth access token (or a personal API key — same Bearer scheme).
- *
- * Wraps `@civitai/client`'s factory with sensible defaults. The returned
- * client is the same shape `@civitai/client` produces — pass it to the
- * SDK's standalone functions (`submitWorkflow({ client, body })`, etc.)
- * or to the wrappers in `@civitai/app-sdk/workflows`.
- */
-export declare function createAppClient(opts: CreateAppClientOptions): CivitaiClient;
-export type AppClient = CivitaiClient;
-//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEnE,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACtB;AAID;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,aAAa,CAM3E;AAED,MAAM,MAAM,SAAS,GAAG,aAAa,CAAC"}

package/dist/client/index.js

@@ -1,19 +0,0 @@
-import { createCivitaiClient } from '@civitai/client';
-const DEFAULT_ORCHESTRATOR_BASE_URL = 'https://orchestration-new.civitai.com';
-/**
- * Create a typed Civitai orchestrator client authenticated with the user's
- * OAuth access token (or a personal API key — same Bearer scheme).
- *
- * Wraps `@civitai/client`'s factory with sensible defaults. The returned
- * client is the same shape `@civitai/client` produces — pass it to the
- * SDK's standalone functions (`submitWorkflow({ client, body })`, etc.)
- * or to the wrappers in `@civitai/app-sdk/workflows`.
- */
-export function createAppClient(opts) {
-    return createCivitaiClient({
-        baseUrl: opts.baseUrl ?? DEFAULT_ORCHESTRATOR_BASE_URL,
-        env: opts.env ?? 'prod',
-        auth: opts.token,
-    });
-}
-//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AActD,MAAM,6BAA6B,GAAG,uCAAuC,CAAC;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC1D,OAAO,mBAAmB,CAAC;QACzB,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,6BAA6B;QACtD,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,MAAM;QACvB,IAAI,EAAE,IAAI,CAAC,KAAK;KACjB,CAAC,CAAC;AACL,CAAC"}

package/dist/workflows/index.d.ts

@@ -1,52 +0,0 @@
-import { type SubmitWorkflowData, type Workflow } from '@civitai/client';
-import type { AppClient } from '../client/index.js';
-/**
- * Thin wrappers around the orchestrator's workflow endpoints with conventions
- * suited to third-party app starters. All calls use the user's OAuth token
- * (or API key) carried by the `AppClient` — the orchestrator debits Buzz
- * from whoever owns that token.
- */
-export type WorkflowBody = NonNullable<SubmitWorkflowData['body']>;
-export interface CostEstimate {
-    /** Buzz cost. Pulled from the workflow's `cost.total` field. */
-    total: number;
-    /** Full workflow response (validation result, queue placement, etc.). */
-    raw: Workflow;
-}
-declare class WorkflowError extends Error {
-    readonly status: number | undefined;
-    readonly detail: unknown;
-    readonly name = "WorkflowError";
-    constructor(message: string, status: number | undefined, detail: unknown);
-}
-/**
- * Cost preview ("what if") — runs the workflow validation/pricing pipeline
- * without committing any Buzz. Use this to show the user "this will cost X
- * Buzz" before they confirm submission.
- *
- * NOTE: per Civitai's docs, `whatif=true` validates and prices but does not
- * apply per-app spending caps to the response — a successful whatif can still
- * be denied at submit time if the user has set tight caps or insufficient
- * funds. Treat `whatif` as "this is the price" not "this is approved."
- */
-export declare function estimateCost(client: AppClient, body: WorkflowBody): Promise<CostEstimate>;
-/** Submit a workflow for real execution. Debits the token-owner's Buzz. */
-export declare function submitWorkflow(client: AppClient, body: WorkflowBody): Promise<Workflow>;
-export declare function getWorkflow(client: AppClient, workflowId: string): Promise<Workflow>;
-export interface PollWorkflowOptions {
-    /** Polling interval in ms. Default 2000. */
-    intervalMs?: number;
-    /** Max total time to poll in ms. Default 5 minutes. */
-    timeoutMs?: number;
-    /** Optional progress callback fired on every poll tick. */
-    onTick?: (snapshot: Workflow) => void;
-    /** Optional abort signal. */
-    signal?: AbortSignal;
-}
-/**
- * Poll a workflow until it reaches a terminal status (`Succeeded`, `Failed`,
- * `Canceled`) or the timeout elapses. Returns the final snapshot.
- */
-export declare function pollWorkflow(client: AppClient, workflowId: string, opts?: PollWorkflowOptions): Promise<Workflow>;
-export { WorkflowError };
-//# sourceMappingURL=index.d.ts.map

package/dist/workflows/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;GAKG;AAEH,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;AAEnE,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,GAAG,EAAE,QAAQ,CAAC;CACf;AAED,cAAM,aAAc,SAAQ,KAAK;IAI7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO;IAJ1B,SAAkB,IAAI,mBAAmB;gBAEvC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,OAAO;CAI3B;AAkBD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAQ/F;AAED,2EAA2E;AAC3E,wBAAsB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAG7F;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAM1F;AAED,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IACtC,6BAA6B;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAID;;;GAGG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,QAAQ,CAAC,CAmBnB;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/workflows/index.js

@@ -1,77 +0,0 @@
-import { getWorkflow as sdkGetWorkflow, submitWorkflow as sdkSubmitWorkflow, } from '@civitai/client';
-class WorkflowError extends Error {
-    status;
-    detail;
-    name = 'WorkflowError';
-    constructor(message, status, detail) {
-        super(message);
-        this.status = status;
-        this.detail = detail;
-    }
-}
-function unwrap(result) {
-    if (result.error || !result.data) {
-        const status = result.response?.status;
-        const detail = result.error && typeof result.error === 'object' && 'detail' in result.error
-            ? result.error.detail
-            : result.error;
-        throw new WorkflowError(`Civitai workflow request failed${status ? ` (HTTP ${status})` : ''}`, status, detail);
-    }
-    return result.data;
-}
-/**
- * Cost preview ("what if") — runs the workflow validation/pricing pipeline
- * without committing any Buzz. Use this to show the user "this will cost X
- * Buzz" before they confirm submission.
- *
- * NOTE: per Civitai's docs, `whatif=true` validates and prices but does not
- * apply per-app spending caps to the response — a successful whatif can still
- * be denied at submit time if the user has set tight caps or insufficient
- * funds. Treat `whatif` as "this is the price" not "this is approved."
- */
-export async function estimateCost(client, body) {
-    const result = await sdkSubmitWorkflow({
-        client,
-        body,
-        query: { whatif: true },
-    });
-    const workflow = unwrap(result);
-    return { total: workflow?.cost?.total ?? 0, raw: workflow };
-}
-/** Submit a workflow for real execution. Debits the token-owner's Buzz. */
-export async function submitWorkflow(client, body) {
-    const result = await sdkSubmitWorkflow({ client, body });
-    return unwrap(result);
-}
-export async function getWorkflow(client, workflowId) {
-    const result = await sdkGetWorkflow({
-        client,
-        path: { workflowId },
-    });
-    return unwrap(result);
-}
-const TERMINAL_STATUSES = new Set(['Succeeded', 'Failed', 'Canceled']);
-/**
- * Poll a workflow until it reaches a terminal status (`Succeeded`, `Failed`,
- * `Canceled`) or the timeout elapses. Returns the final snapshot.
- */
-export async function pollWorkflow(client, workflowId, opts = {}) {
-    const interval = opts.intervalMs ?? 2000;
-    const timeout = opts.timeoutMs ?? 5 * 60 * 1000;
-    const deadline = Date.now() + timeout;
-    while (true) {
-        if (opts.signal?.aborted)
-            throw new Error('pollWorkflow aborted');
-        const snapshot = await getWorkflow(client, workflowId);
-        opts.onTick?.(snapshot);
-        if (snapshot.status && TERMINAL_STATUSES.has(String(snapshot.status))) {
-            return snapshot;
-        }
-        if (Date.now() >= deadline) {
-            throw new Error(`pollWorkflow timed out after ${timeout}ms (last status: ${String(snapshot.status)})`);
-        }
-        await new Promise((resolve) => setTimeout(resolve, interval));
-    }
-}
-export { WorkflowError };
-//# sourceMappingURL=index.js.map

package/dist/workflows/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"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"}