@clawvard/sdk 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# @clawvard/sdk
+
+Typed TypeScript client for **Clawvard's non-LLM service layer** —
+composed workflows, video / image / data jobs, third-party API
+integrations. Same `sk-xxx` key works for the OpenAI SDK against
+[token.clawvard.school](https://token.clawvard.school) and for this
+SDK against [clawvard.school](https://clawvard.school).
+
+```bash
+pnpm add @clawvard/sdk
+# or: npm i @clawvard/sdk / yarn add @clawvard/sdk
+```
+
+## Quick start
+
+```ts
+import { Clawvard } from "@clawvard/sdk";
+
+const cv = new Clawvard({ apiKey: "sk-xxx" });
+
+// Local services (instant, charged per call)
+const { hex } = await cv.text.hash({ text: "hello", algorithm: "sha256" });
+const { dataUri } = await cv.url.qrCode({ text: "https://clawvard.school" });
+
+// Long-running jobs (auto-poll, refundable on failure)
+const result = await cv.video.removeSilence({ inputUrl: "https://…" })
+  .onProgress((pct, note) => console.log(`${(pct * 100).toFixed(0)}% — ${note}`))
+  .wait();
+
+// Untyped escape hatch — call any registered service by id
+const out = await cv.workflow.run<MyOutput>("my.service", input).wait();
+```
+
+For LLM calls (chat / embeddings / Whisper / DALL·E), point the
+OpenAI SDK at Token Relay with the same `sk-xxx`:
+
+```ts
+import { OpenAI } from "openai";
+const ai = new OpenAI({
+  apiKey:  "sk-xxx",
+  baseURL: "https://token.clawvard.school/v1",
+});
+await ai.chat.completions.create({ model: "claude-opus-4-7", messages });
+```
+
+## What's in the box
+
+| Class | Purpose |
+|---|---|
+| `Clawvard` | Main client — composes generated namespaces with platform helpers |
+| `Job<T>` | Handle for long-running jobs — `.wait()`, `.onProgress(cb)`, `.cancel()`, `.id()` |
+| `HttpClient` | Lower-level: `.invoke()`, `.invokeJob()`, raw `.raw()` — exposed via `cv.client` |
+| Generated namespaces | One per service group (`cv.util.*`, `cv.text.*`, `cv.url.*`, `cv.video.*`, …) |
+| `cv.workflow.run(id, input)` | Untyped invoker — works for any registered service without bumping the SDK |
+| `cv.catalog()` | Public catalog with pricing per service |
+| `cv.usage()` / `cv.usageFor(g, m)` | Caller's usage stats per service |
+
+## Per-call options
+
+```ts
+// Idempotency: same key → server returns the original outcome (no double-charge)
+await cv.client.invoke("video", "render", input, {
+  idempotencyKey: crypto.randomUUID(),
+});
+
+// Webhooks (job services only): platform POSTs the terminal state
+//   to your URL with HMAC signature header `X-Clawvard-Signature`
+await cv.client.invokeJob("video", "removeSilence", input, {
+  idempotencyKey: "...",
+  webhookUrl: "https://you.com/webhook",
+});
+```
+
+## Configuration
+
+```ts
+const cv = new Clawvard({
+  apiKey: "sk-xxx",                     // Required for remote calls
+  baseUrl: "https://clawvard.school",  // Default; override for staging
+  pollIntervalMs: 2000,                 // Job polling cadence
+  retry: { maxRetries: 3, baseDelayMs: 250 },
+  fetch: customFetch,                   // For testing / edge runtimes
+  plugins: [],                          // School / capability plugins
+});
+```
+
+### Auto-retry policy
+
+- **GET**: always retry on 5xx + network errors
+- **POST/PUT/DELETE**: only retry on 5xx if `Idempotency-Key` is set;
+  always retry on network errors (request never reached the server)
+- **4xx**: never retry (caller's bug)
+
+## Errors
+
+```ts
+import { ClawvardError, MissingApiKeyError } from "@clawvard/sdk";
+
+try {
+  await cv.video.render(input);
+} catch (err) {
+  if (err instanceof MissingApiKeyError) { /* config issue */ }
+  // Server errors carry .status + .hint:
+  // (err as Error & { status?: number; hint?: string }).status
+}
+```
+
+## Plugins
+
+Capability packages can attach namespaces:
+
+```ts
+import { Clawvard } from "@clawvard/sdk";
+import { mediaPlugin } from "@clawvard/sdk-media";
+
+const cv = new Clawvard({
+  apiKey: "sk-xxx",
+  plugins: [mediaPlugin()],
+});
+await cv.video.extractFrames({ url, every: "1s" });
+```
+
+## Resources
+
+- Docs: [clawvard.school/docs](https://clawvard.school/docs)
+- Service catalog: [clawvard.school/services](https://clawvard.school/services)
+- Get an API key: [clawvard.school/token-relay](https://clawvard.school/token-relay)
+- Issues: [github.com/THEZIONLABS/clawvard](https://github.com/THEZIONLABS/clawvard)
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SDK-side error classes. Server-side `error: "..."` strings come back
+ * via `toApiError` in http-client.ts; these are for client-side preflight
+ * errors raised before any HTTP call goes out.
+ */
+export declare class ClawvardError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Raised when a remote method is called but no API key was supplied at
+ * construction. Local-only methods (e.g., `cv.video.extractFrames()`) do
+ * not raise this — they don't need a key.
+ */
+export declare class MissingApiKeyError extends ClawvardError {
+    constructor(operation: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,aAAc,SAAQ,KAAK;aACO,IAAI,EAAE,MAAM;gBAA7C,OAAO,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAI1D;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACvC,SAAS,EAAE,MAAM;CAS9B"}

package/dist/errors.js

@@ -0,0 +1,27 @@
+/**
+ * SDK-side error classes. Server-side `error: "..."` strings come back
+ * via `toApiError` in http-client.ts; these are for client-side preflight
+ * errors raised before any HTTP call goes out.
+ */
+export class ClawvardError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "ClawvardError";
+    }
+}
+/**
+ * Raised when a remote method is called but no API key was supplied at
+ * construction. Local-only methods (e.g., `cv.video.extractFrames()`) do
+ * not raise this — they don't need a key.
+ */
+export class MissingApiKeyError extends ClawvardError {
+    constructor(operation) {
+        super(`Clawvard: apiKey is required to call \`${operation}\`. Pass it to ` +
+            `\`new Clawvard({ apiKey: "sk-xxx" })\` or call only local ` +
+            `helpers (e.g. \`cv.video.*\`, \`cv.subtitle.*\`).`, "missing_api_key");
+        this.name = "MissingApiKeyError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACO;IAA7C,YAAY,OAAe,EAAkB,IAAY;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,SAAI,GAAJ,IAAI,CAAQ;QAEvD,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IACnD,YAAY,SAAiB;QAC3B,KAAK,CACH,0CAA0C,SAAS,iBAAiB;YAClE,4DAA4D;YAC5D,mDAAmD,EACrD,iBAAiB,CAClB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/generated.d.ts

@@ -0,0 +1,39 @@
+/**
+ * AUTO-GENERATED — do not edit by hand.
+ *
+ * Run `pnpm sdk:gen` to regenerate from `src/lib/services/registry.ts`.
+ */
+import type { HttpClient } from "./http-client";
+import type { Job } from "./job";
+import type { InputArgs, OutputOf } from "./service-types";
+export declare class TextNamespace {
+    private readonly c;
+    constructor(c: HttpClient);
+    /** text.word-count (local) — generated. */
+    wordCount(...args: InputArgs<"text.word-count">): Promise<OutputOf<"text.word-count">>;
+    /** text.hash (local) — generated. */
+    hash(...args: InputArgs<"text.hash">): Promise<OutputOf<"text.hash">>;
+}
+export declare class UrlNamespace {
+    private readonly c;
+    constructor(c: HttpClient);
+    /** url.qr-code (local) — generated. */
+    qrCode(...args: InputArgs<"url.qr-code">): Promise<OutputOf<"url.qr-code">>;
+    /** url.preview (local) — generated. */
+    preview(...args: InputArgs<"url.preview">): Promise<OutputOf<"url.preview">>;
+}
+export declare class UtilNamespace {
+    private readonly c;
+    constructor(c: HttpClient);
+    /** util.ip-check (proxy) — generated. */
+    ipCheck(...args: InputArgs<"util.ip-check">): Promise<OutputOf<"util.ip-check">>;
+    /** util.delay-echo (job) — generated. */
+    delayEcho(...args: InputArgs<"util.delay-echo">): Job<OutputOf<"util.delay-echo">>;
+}
+export declare class GeneratedClient {
+    readonly text: TextNamespace;
+    readonly url: UrlNamespace;
+    readonly util: UtilNamespace;
+    constructor(client: HttpClient);
+}
+//# sourceMappingURL=generated.d.ts.map

package/dist/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../src/generated.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAG3D,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,UAAU;IAE1C,2CAA2C;IAC3C,SAAS,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAItF,qCAAqC;IACrC,IAAI,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;CAGtE;AAED,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,UAAU;IAE1C,uCAAuC;IACvC,MAAM,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IAI3E,uCAAuC;IACvC,OAAO,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;CAG7E;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,UAAU;IAE1C,yCAAyC;IACzC,OAAO,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;IAIhF,yCAAyC;IACzC,SAAS,CAAC,GAAG,IAAI,EAAE,SAAS,CAAC,iBAAiB,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;CAGnF;AAED,qBAAa,eAAe;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBAEjB,MAAM,EAAE,UAAU;CAK/B"}

package/dist/generated.js

@@ -0,0 +1,58 @@
+/**
+ * AUTO-GENERATED — do not edit by hand.
+ *
+ * Run `pnpm sdk:gen` to regenerate from `src/lib/services/registry.ts`.
+ */
+export class TextNamespace {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** text.word-count (local) — generated. */
+    wordCount(...args) {
+        return this.c.invoke("text", "wordCount", args[0]);
+    }
+    /** text.hash (local) — generated. */
+    hash(...args) {
+        return this.c.invoke("text", "hash", args[0]);
+    }
+}
+export class UrlNamespace {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** url.qr-code (local) — generated. */
+    qrCode(...args) {
+        return this.c.invoke("url", "qrCode", args[0]);
+    }
+    /** url.preview (local) — generated. */
+    preview(...args) {
+        return this.c.invoke("url", "preview", args[0]);
+    }
+}
+export class UtilNamespace {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** util.ip-check (proxy) — generated. */
+    ipCheck(...args) {
+        return this.c.invoke("util", "ipCheck", args[0]);
+    }
+    /** util.delay-echo (job) — generated. */
+    delayEcho(...args) {
+        return this.c.invokeJob("util", "delayEcho", args[0]);
+    }
+}
+export class GeneratedClient {
+    text;
+    url;
+    util;
+    constructor(client) {
+        this.text = new TextNamespace(client);
+        this.url = new UrlNamespace(client);
+        this.util = new UtilNamespace(client);
+    }
+}
+//# sourceMappingURL=generated.js.map

package/dist/generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.js","sourceRoot":"","sources":["../src/generated.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,CAAa;QAAb,MAAC,GAAD,CAAC,CAAY;IAAG,CAAC;IAE9C,2CAA2C;IAC3C,SAAS,CAAC,GAAG,IAAkC;QAC7C,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAA8B,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;IAED,qCAAqC;IACrC,IAAI,CAAC,GAAG,IAA4B;QAClC,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAwB,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,CAAC;CACF;AAED,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,CAAa;QAAb,MAAC,GAAD,CAAC,CAAY;IAAG,CAAC;IAE9C,uCAAuC;IACvC,MAAM,CAAC,GAAG,IAA8B;QACtC,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAA0B,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,uCAAuC;IACvC,OAAO,CAAC,GAAG,IAA8B;QACvC,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAA0B,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,CAAC;CACF;AAED,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,CAAa;QAAb,MAAC,GAAD,CAAC,CAAY;IAAG,CAAC;IAE9C,yCAAyC;IACzC,OAAO,CAAC,GAAG,IAAgC;QACzC,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAA4B,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,yCAAyC;IACzC,SAAS,CAAC,GAAG,IAAkC;QAC7C,OAAO,IAAI,CAAC,CAAC,CAAC,SAAS,CAA8B,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,CAAC;CACF;AAED,MAAM,OAAO,eAAe;IACjB,IAAI,CAAgB;IACpB,GAAG,CAAe;IAClB,IAAI,CAAgB;IAE7B,YAAY,MAAkB;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;CACF"}

package/dist/http-client.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Internal HTTP client used by every namespace method.
+ * Not part of the public surface — exported only so the
+ * auto-generated client can construct one.
+ */
+import { Job } from "./job";
+export interface ClawvardHttpConfig {
+    /** Optional — local-only callers (e.g. `cv.video.extractFrames`) work without it. */
+    apiKey?: string;
+    baseUrl: string;
+    pollIntervalMs: number;
+    fetchImpl: typeof globalThis.fetch;
+    /** Auto-retry policy for transient failures (5xx + network errors).
+     *  Default is 3 attempts with exponential backoff. Set `maxRetries:0`
+     *  to disable. */
+    retry?: {
+        maxRetries: number;
+        baseDelayMs: number;
+    };
+}
+export declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly retry;
+    readonly pollIntervalMs: number;
+    constructor(config: ClawvardHttpConfig);
+    /** Throws `MissingApiKeyError` if no key was supplied. Used by every
+     *  remote method before issuing the HTTP call. Local-only callers
+     *  (e.g. cv.video.extractFrames) skip this check entirely. */
+    requireApiKey(operation: string): string;
+    /** Fetch wrapper with optional bearer auth + transparent retry on
+     *  5xx + network errors. Retries are only safe for idempotent
+     *  operations: GET/HEAD always retried; POST/PUT/DELETE only when the
+     *  caller provides an `Idempotency-Key` header (the dispatcher dedups
+     *  on the server side). Non-idempotent POSTs without the header are
+     *  retried only on network errors (where we know the request never
+     *  reached the server).
+     *
+     *  Authorization header is added only when an `apiKey` was configured;
+     *  endpoints that need auth respond 401 and the caller surfaces that. */
+    raw(path: string, init?: RequestInit): Promise<Response>;
+    invoke<T>(group: string, method: string, body: unknown, options?: InvokeOptions): Promise<T>;
+    invokeJob<T>(group: string, method: string, body: unknown, options?: InvokeOptions): Job<T>;
+}
+/** Per-call overrides passed to namespace methods. Most callers can
+ *  ignore this — it's used by `cv.client.invoke(...)` and the
+ *  retry-friendly forms. */
+export interface InvokeOptions {
+    /** Sent as the `Idempotency-Key` header. Same key + same caller =
+     *  the dispatcher returns the original invocation's outcome instead
+     *  of re-charging / re-creating. Setting this also unlocks SDK auto-
+     *  retry on 5xx for the call (otherwise only network errors retry). */
+    idempotencyKey?: string;
+    /** (Job services only) Sent as the `X-Webhook-Url` header. The
+     *  platform POSTs the terminal job state to this URL so callers
+     *  don't have to poll. Body is HMAC-signed with the server's
+     *  webhook secret — verify via the `X-Clawvard-Signature` header. */
+    webhookUrl?: string;
+}
+export declare function toApiError(res: Response): Promise<Error>;
+//# sourceMappingURL=http-client.d.ts.map

package/dist/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAE5B,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACnC;;sBAEkB;IAClB,KAAK,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8C;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;gBAEpB,MAAM,EAAE,kBAAkB;IAQtC;;kEAE8D;IAC9D,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAKxC;;;;;;;;;6EASyE;IACnE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IA4BxD,MAAM,CAAC,CAAC,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,CAAC,CAAC;IAcb,SAAS,CAAC,CAAC,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,GAAG,CAAC,CAAC,CAAC;CAIV;AAED;;4BAE4B;AAC5B,MAAM,WAAW,aAAa;IAC5B;;;2EAGuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;yEAGqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAW9D"}

package/dist/http-client.js

@@ -0,0 +1,107 @@
+/**
+ * Internal HTTP client used by every namespace method.
+ * Not part of the public surface — exported only so the
+ * auto-generated client can construct one.
+ */
+import { MissingApiKeyError } from "./errors";
+import { Job } from "./job";
+export class HttpClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    retry;
+    pollIntervalMs;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.apiKey = config.apiKey;
+        this.fetchImpl = config.fetchImpl;
+        this.pollIntervalMs = config.pollIntervalMs;
+        this.retry = config.retry ?? { maxRetries: 3, baseDelayMs: 250 };
+    }
+    /** Throws `MissingApiKeyError` if no key was supplied. Used by every
+     *  remote method before issuing the HTTP call. Local-only callers
+     *  (e.g. cv.video.extractFrames) skip this check entirely. */
+    requireApiKey(operation) {
+        if (!this.apiKey)
+            throw new MissingApiKeyError(operation);
+        return this.apiKey;
+    }
+    /** Fetch wrapper with optional bearer auth + transparent retry on
+     *  5xx + network errors. Retries are only safe for idempotent
+     *  operations: GET/HEAD always retried; POST/PUT/DELETE only when the
+     *  caller provides an `Idempotency-Key` header (the dispatcher dedups
+     *  on the server side). Non-idempotent POSTs without the header are
+     *  retried only on network errors (where we know the request never
+     *  reached the server).
+     *
+     *  Authorization header is added only when an `apiKey` was configured;
+     *  endpoints that need auth respond 401 and the caller surfaces that. */
+    async raw(path, init) {
+        const method = (init?.method || "GET").toUpperCase();
+        const headersIn = (init?.headers || {});
+        const hasIdemKey = "Idempotency-Key" in headersIn || "idempotency-key" in headersIn;
+        const isReadOnly = method === "GET" || method === "HEAD";
+        const fullySafe = isReadOnly || hasIdemKey;
+        const url = `${this.baseUrl}${path}`;
+        const headers = { ...headersIn };
+        if (this.apiKey)
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        const merged = { ...init, headers };
+        let lastError;
+        for (let attempt = 0; attempt <= this.retry.maxRetries; attempt++) {
+            try {
+                const res = await this.fetchImpl(url, merged);
+                if (res.status < 500)
+                    return res;
+                if (!fullySafe)
+                    return res;
+                if (attempt === this.retry.maxRetries)
+                    return res;
+            }
+            catch (err) {
+                lastError = err;
+                if (attempt === this.retry.maxRetries)
+                    throw err;
+            }
+            await sleep(this.retry.baseDelayMs * 2 ** attempt);
+        }
+        throw lastError ?? new Error("retry exhausted");
+    }
+    async invoke(group, method, body, options) {
+        this.requireApiKey(`${group}.${method}`);
+        const headers = { "Content-Type": "application/json" };
+        if (options?.idempotencyKey)
+            headers["Idempotency-Key"] = options.idempotencyKey;
+        if (options?.webhookUrl)
+            headers["X-Webhook-Url"] = options.webhookUrl;
+        const res = await this.raw(`/api/services/invoke/${group}/${method}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body ?? {}),
+        });
+        if (!res.ok)
+            throw await toApiError(res);
+        return (await res.json());
+    }
+    invokeJob(group, method, body, options) {
+        this.requireApiKey(`${group}.${method}`);
+        return new Job(this, group, method, body, options);
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export async function toApiError(res) {
+    let payload = {};
+    try {
+        payload = await res.json();
+    }
+    catch {
+        /* non-JSON body */
+    }
+    const err = new Error(payload.error || res.statusText);
+    err.status = res.status;
+    err.hint = payload.hint;
+    return err;
+}
+//# sourceMappingURL=http-client.js.map

package/dist/http-client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @clawvard/sdk — unified service client for Clawvard's composed /
+ * long-running / external-API-integrated services.
+ *
+ * ⚠️  NOT FOR LLM PASSTHROUGHS. Chat, embeddings, Whisper, TTS, DALL·E
+ * etc. are served by Token Relay at `https://token.clawvard.school`
+ * with `sk-xxx` keys. Use the OpenAI SDK (or any OpenAI-compatible
+ * client) pointed at that base URL for those.
+ *
+ * This SDK covers:
+ *   - Composed workflows (multi-step recipes)
+ *   - Long-running jobs (video render, batch processing)
+ *   - External-API integrations (Shotstack, Mux, Replicate, ...)
+ *
+ * @example
+ *   import { Clawvard } from "@clawvard/sdk";
+ *
+  *   const cv = new Clawvard({ apiKey: "sk-xxx" });
+ *
+ *   // Smoke test (proxy)
+ *   const { ip } = await cv.util.ipCheck();
+ *
+ *   // Job — auto-polls to completion with progress callback
+ *   const result = await cv.util.delayEcho({ seconds: 5 })
+ *     .onProgress((pct, note) => console.log(`${(pct * 100).toFixed(0)}% — ${note}`))
+ *     .wait();
+ *
+ *   // Arbitrary registered service by id (untyped escape hatch)
+ *   const post = await cv.workflow.run("workflow.podcast2blog", { audioUrl: "..." }).wait();
+ */
+import { HttpClient } from "./http-client";
+import { Job } from "./job";
+import { GeneratedClient } from "./generated";
+import type { ClawvardPlugin } from "./plugin";
+export { Job } from "./job";
+export { HttpClient } from "./http-client";
+export type { InvokeOptions } from "./http-client";
+export type { ServiceTypeMap, InputOf, OutputOf, InputArgs, } from "./service-types";
+export type { ClawvardPlugin, ClawvardInstance } from "./plugin";
+export { ClawvardError, MissingApiKeyError } from "./errors";
+export interface ClawvardConfig {
+    /** Token Relay-issued `sk-xxx` API key. Mint or list yours at
+     *  https://clawvard.school/token-relay. The same key works for the
+     *  OpenAI SDK pointed at `https://token.clawvard.school` AND for
+     *  this SDK — there's no separate "Clawvard key" any more.
+     *
+     *  Optional — local-only methods (e.g. `cv.video.extractFrames` from
+     *  `@clawvard/sdk-media`) work without it. Remote calls throw
+     *  `MissingApiKeyError` when no key is configured. */
+    apiKey?: string;
+    /** Override base URL. Defaults to production. */
+    baseUrl?: string;
+    /** Poll interval for jobs, ms. Defaults to 2000. */
+    pollIntervalMs?: number;
+    /** Fetch implementation override (for testing / edge runtimes). */
+    fetch?: typeof globalThis.fetch;
+    /** Auto-retry policy for transient failures. Default = 3 attempts
+     *  with exponential backoff (250ms base). Set `{maxRetries: 0}` to
+     *  disable. POST/PUT/DELETE only retry on 5xx when the call carries
+     *  an Idempotency-Key, but ALL methods retry on network errors. */
+    retry?: {
+        maxRetries: number;
+        baseDelayMs?: number;
+    };
+    /** School / capability plugins. Each plugin's `install()` runs once
+     *  at construction and may attach namespaces to the instance. */
+    plugins?: ClawvardPlugin[];
+}
+/** The main SDK client. Composes the auto-generated namespace methods
+ *  (one per registered service `group`) with hand-written platform
+ *  helpers (`catalog`, `usage`, `usageFor`, `workflow.run`).
+ *
+ *  When backend adds a new service to `src/lib/services/registry.ts`
+ *  and runs `pnpm sdk:gen`, a new typed method appears on the
+ *  appropriate namespace automatically. */
+export declare class Clawvard extends GeneratedClient {
+    /** Untyped invocation by id — escape hatch for newly-registered
+     *  services not yet in `ServiceTypeMap`, or for callers that don't
+     *  want to bump their SDK version. */
+    readonly workflow: WorkflowNamespace;
+    /** Lower-level HTTP client. Use this when you need per-call options
+     *  the generated namespace methods don't expose, e.g. an
+     *  `Idempotency-Key` header:
+     *
+     *    cv.client.invoke("video", "render", input, { idempotencyKey: "..." })
+     *    cv.client.invokeJob("video", "removeSilence", input, { idempotencyKey: "..." })
+     *  */
+    readonly client: HttpClient;
+    constructor(config?: ClawvardConfig);
+    /**
+     * Fetch the service catalog. Each entry carries pricing + runtime +
+     * access flags — enough to render a marketplace tile without any
+     * other request. Public endpoint, no auth required.
+     */
+    catalog(): Promise<ServiceCatalogEntry[]>;
+    /**
+     * Caller's usage across every registered service. Auth required.
+     * Services never called show zero stats so the UI can render a
+     * complete table.
+     */
+    usage(): Promise<UsageReport>;
+    /**
+     * Caller's usage of a single service. Pass `includeHistory: true`
+     * to also get the N most recent invocation rows.
+     */
+    usageFor(group: string, method: string, options?: {
+        includeHistory?: boolean;
+        limit?: number;
+    }): Promise<SingleServiceUsage>;
+}
+/** Untyped invocation by service id — for services not yet in
+ *  `ServiceTypeMap` or for callers who prefer string-keyed access. */
+declare class WorkflowNamespace {
+    private readonly c;
+    constructor(c: HttpClient);
+    /** Composable workflow / generic invoke. Returns a `Job<T>` so the
+     *  caller can await `.wait()` for both proxy and job services
+     *  (proxy services complete on the first poll). */
+    run<T>(id: string, input: unknown): Job<T>;
+}
+/** Price display bundled with every catalog entry. */
+export interface PriceDisplay {
+    /** Authoritative price — what gets deducted on success. */
+    credits: number;
+    /** ¥ at the published rate (10 credits = ¥1). 2dp. */
+    cny: number;
+    /** $ at the published rate (100 credits = $1). 4dp. */
+    usd: number;
+}
+export interface ServiceCatalogEntry {
+    id: string;
+    group: string;
+    method: string;
+    summary: string;
+    description?: string;
+    costCredits: number;
+    approxCostHintUsd?: number;
+    runtime: "proxy" | "job" | "local";
+    pricing: PriceDisplay;
+    access?: {
+        beta?: boolean;
+        requiresCoursePurchase?: string;
+        minAccountTier?: string;
+    };
+    rateLimit?: {
+        perMinute?: number;
+        perHour?: number;
+        perDay?: number;
+    };
+}
+/** One row of per-service usage for a specific user. */
+export interface ServiceUsage {
+    serviceId: string;
+    calls: number;
+    refunded: number;
+    netCalls: number;
+    creditsSpent: number;
+    lastCalledAt: string | null;
+}
+/** Shape of `GET /api/services/usage`. */
+export interface UsageReport {
+    version: 1;
+    totals: {
+        calls: number;
+        refunded: number;
+        netCalls: number;
+        creditsSpent: number;
+    };
+    services: ServiceUsage[];
+}
+/** One row of invocation history. */
+export interface InvocationRecord {
+    invocationId: string;
+    creditsSpent: number;
+    createdAt: string;
+    refunded: boolean;
+}
+/** Shape of `GET /api/services/usage/:group/:method`. */
+export interface SingleServiceUsage {
+    version: 1;
+    serviceId: string;
+    summary: ServiceUsage;
+    history?: InvocationRecord[];
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,129 @@
+/**
+ * @clawvard/sdk — unified service client for Clawvard's composed /
+ * long-running / external-API-integrated services.
+ *
+ * ⚠️  NOT FOR LLM PASSTHROUGHS. Chat, embeddings, Whisper, TTS, DALL·E
+ * etc. are served by Token Relay at `https://token.clawvard.school`
+ * with `sk-xxx` keys. Use the OpenAI SDK (or any OpenAI-compatible
+ * client) pointed at that base URL for those.
+ *
+ * This SDK covers:
+ *   - Composed workflows (multi-step recipes)
+ *   - Long-running jobs (video render, batch processing)
+ *   - External-API integrations (Shotstack, Mux, Replicate, ...)
+ *
+ * @example
+ *   import { Clawvard } from "@clawvard/sdk";
+ *
+  *   const cv = new Clawvard({ apiKey: "sk-xxx" });
+ *
+ *   // Smoke test (proxy)
+ *   const { ip } = await cv.util.ipCheck();
+ *
+ *   // Job — auto-polls to completion with progress callback
+ *   const result = await cv.util.delayEcho({ seconds: 5 })
+ *     .onProgress((pct, note) => console.log(`${(pct * 100).toFixed(0)}% — ${note}`))
+ *     .wait();
+ *
+ *   // Arbitrary registered service by id (untyped escape hatch)
+ *   const post = await cv.workflow.run("workflow.podcast2blog", { audioUrl: "..." }).wait();
+ */
+import { HttpClient } from "./http-client";
+import { GeneratedClient } from "./generated";
+export { Job } from "./job";
+export { HttpClient } from "./http-client";
+export { ClawvardError, MissingApiKeyError } from "./errors";
+const DEFAULT_BASE_URL = "https://clawvard.school";
+const DEFAULT_POLL_MS = 2000;
+/** The main SDK client. Composes the auto-generated namespace methods
+ *  (one per registered service `group`) with hand-written platform
+ *  helpers (`catalog`, `usage`, `usageFor`, `workflow.run`).
+ *
+ *  When backend adds a new service to `src/lib/services/registry.ts`
+ *  and runs `pnpm sdk:gen`, a new typed method appears on the
+ *  appropriate namespace automatically. */
+export class Clawvard extends GeneratedClient {
+    /** Untyped invocation by id — escape hatch for newly-registered
+     *  services not yet in `ServiceTypeMap`, or for callers that don't
+     *  want to bump their SDK version. */
+    workflow;
+    /** Lower-level HTTP client. Use this when you need per-call options
+     *  the generated namespace methods don't expose, e.g. an
+     *  `Idempotency-Key` header:
+     *
+     *    cv.client.invoke("video", "render", input, { idempotencyKey: "..." })
+     *    cv.client.invokeJob("video", "removeSilence", input, { idempotencyKey: "..." })
+     *  */
+    client;
+    constructor(config = {}) {
+        const http = new HttpClient({
+            ...(config.apiKey ? { apiKey: config.apiKey } : {}),
+            baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+            pollIntervalMs: config.pollIntervalMs ?? DEFAULT_POLL_MS,
+            fetchImpl: config.fetch || globalThis.fetch.bind(globalThis),
+            retry: config.retry
+                ? { maxRetries: config.retry.maxRetries, baseDelayMs: config.retry.baseDelayMs ?? 250 }
+                : { maxRetries: 3, baseDelayMs: 250 },
+        });
+        super(http);
+        this.client = http;
+        this.workflow = new WorkflowNamespace(http);
+        // Run plugins last so they can inspect / wrap previously-installed
+        // namespaces if needed. Each plugin attaches its own namespaces;
+        // declaration merging in the plugin's own package types them.
+        if (config.plugins) {
+            for (const plugin of config.plugins) {
+                plugin.install(this, http);
+            }
+        }
+    }
+    /**
+     * Fetch the service catalog. Each entry carries pricing + runtime +
+     * access flags — enough to render a marketplace tile without any
+     * other request. Public endpoint, no auth required.
+     */
+    async catalog() {
+        const res = await this.client.raw("/api/services/catalog", { method: "GET" });
+        const json = (await res.json());
+        return json.services;
+    }
+    /**
+     * Caller's usage across every registered service. Auth required.
+     * Services never called show zero stats so the UI can render a
+     * complete table.
+     */
+    async usage() {
+        const res = await this.client.raw("/api/services/usage", { method: "GET" });
+        return (await res.json());
+    }
+    /**
+     * Caller's usage of a single service. Pass `includeHistory: true`
+     * to also get the N most recent invocation rows.
+     */
+    async usageFor(group, method, options) {
+        const qs = new URLSearchParams();
+        if (options?.includeHistory)
+            qs.set("history", "1");
+        if (options?.limit)
+            qs.set("limit", String(options.limit));
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        const res = await this.client.raw(`/api/services/usage/${group}/${method}${suffix}`, { method: "GET" });
+        return (await res.json());
+    }
+}
+/** Untyped invocation by service id — for services not yet in
+ *  `ServiceTypeMap` or for callers who prefer string-keyed access. */
+class WorkflowNamespace {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** Composable workflow / generic invoke. Returns a `Job<T>` so the
+     *  caller can await `.wait()` for both proxy and job services
+     *  (proxy services complete on the first poll). */
+    run(id, input) {
+        const [group, method] = id.includes(".") ? id.split(".", 2) : ["workflow", id];
+        return this.c.invokeJob(group, method, input);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/job.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Job — handle for a long-running service invocation. Auto-starts on
+ * construction, exposes `.onProgress(cb)` for incremental updates,
+ * `.wait()` to poll to completion, and `.cancel()` to abort.
+ */
+import { HttpClient, type InvokeOptions } from "./http-client";
+export declare class Job<T> {
+    private readonly client;
+    private readonly group;
+    private readonly method;
+    private readonly input;
+    private readonly options?;
+    private jobId;
+    private progressCallback;
+    private readonly started;
+    constructor(client: HttpClient, group: string, method: string, input: unknown, options?: InvokeOptions | undefined);
+    private start;
+    /** Register a callback for each progress tick. Chain before `.wait()`. */
+    onProgress(cb: (pct: number, note?: string) => void): this;
+    /** Poll until the job reaches a terminal state. Throws on failure. */
+    wait(): Promise<T>;
+    /** Fire-and-forget: get the job ID without waiting. */
+    id(): Promise<string>;
+    /** Cancel the job. If still pending/running, the platform refunds
+     *  the credits that were charged on creation. Returns the new
+     *  status; resolves to `"cancelled"` if the cancel landed before a
+     *  terminal state, or the existing terminal state if the worker
+     *  already finished. */
+    cancel(): Promise<{
+        status: "cancelled" | "completed" | "failed";
+        refunded: boolean;
+    }>;
+}
+//# sourceMappingURL=job.d.ts.map

package/dist/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../src/job.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAc,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAE3E,qBAAa,GAAG,CAAC,CAAC;IAMd,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAT3B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,gBAAgB,CAAuD;IAC/E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAGrB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,aAAa,YAAA;YAK5B,KAAK;IAcnB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAK1D,sEAAsE;IAChE,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC;IA0BxB,uDAAuD;IACjD,EAAE,IAAI,OAAO,CAAC,MAAM,CAAC;IAM3B;;;;4BAIwB;IAClB,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;CAO7F"}

package/dist/job.js

@@ -0,0 +1,96 @@
+/**
+ * Job — handle for a long-running service invocation. Auto-starts on
+ * construction, exposes `.onProgress(cb)` for incremental updates,
+ * `.wait()` to poll to completion, and `.cancel()` to abort.
+ */
+import { toApiError } from "./http-client";
+export class Job {
+    client;
+    group;
+    method;
+    input;
+    options;
+    jobId = null;
+    progressCallback = null;
+    started;
+    constructor(client, group, method, input, options) {
+        this.client = client;
+        this.group = group;
+        this.method = method;
+        this.input = input;
+        this.options = options;
+        this.started = this.start();
+    }
+    async start() {
+        const headers = { "Content-Type": "application/json" };
+        if (this.options?.idempotencyKey)
+            headers["Idempotency-Key"] = this.options.idempotencyKey;
+        if (this.options?.webhookUrl)
+            headers["X-Webhook-Url"] = this.options.webhookUrl;
+        const res = await this.client.raw(`/api/services/invoke/${this.group}/${this.method}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(this.input ?? {}),
+        });
+        if (!res.ok)
+            throw await toApiError(res);
+        const body = (await res.json());
+        this.jobId = body.jobId;
+    }
+    /** Register a callback for each progress tick. Chain before `.wait()`. */
+    onProgress(cb) {
+        this.progressCallback = cb;
+        return this;
+    }
+    /** Poll until the job reaches a terminal state. Throws on failure. */
+    async wait() {
+        await this.started;
+        if (!this.jobId)
+            throw new Error("Job: never started");
+        let lastPct = -1;
+        for (;;) {
+            const res = await this.client.raw(`/api/services/jobs/${this.jobId}`, { method: "GET" });
+            if (!res.ok)
+                throw await toApiError(res);
+            const status = (await res.json());
+            if (status.progress && status.progress.pct !== lastPct) {
+                lastPct = status.progress.pct;
+                this.progressCallback?.(status.progress.pct, status.progress.note);
+            }
+            if (status.status === "completed")
+                return status.result;
+            if (status.status === "failed") {
+                const msg = status.error?.message ?? "job failed";
+                throw new Error(msg);
+            }
+            if (status.status === "cancelled")
+                throw new Error("job cancelled");
+            await sleep(this.client.pollIntervalMs);
+        }
+    }
+    /** Fire-and-forget: get the job ID without waiting. */
+    async id() {
+        await this.started;
+        if (!this.jobId)
+            throw new Error("Job: never started");
+        return this.jobId;
+    }
+    /** Cancel the job. If still pending/running, the platform refunds
+     *  the credits that were charged on creation. Returns the new
+     *  status; resolves to `"cancelled"` if the cancel landed before a
+     *  terminal state, or the existing terminal state if the worker
+     *  already finished. */
+    async cancel() {
+        await this.started;
+        if (!this.jobId)
+            throw new Error("Job: never started");
+        const res = await this.client.raw(`/api/services/jobs/${this.jobId}`, { method: "DELETE" });
+        if (!res.ok)
+            throw await toApiError(res);
+        return (await res.json());
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=job.js.map

package/dist/job.js.map

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

package/dist/plugin.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Plugin protocol — lets `@clawvard/sdk-<school>` packages register
+ * additional namespaces (and types via declaration merging) onto a
+ * `Clawvard` instance.
+ *
+ * @example
+ *   import { Clawvard } from "@clawvard/sdk";
+ *   import { mediaPlugin } from "@clawvard/sdk-media";
+ *
+ *   const cv = new Clawvard({ apiKey, plugins: [mediaPlugin] });
+ *   cv.media.translateSubtitles({...});  // typed via declaration merging
+ *   cv.video.extractFrames({...});       // local helper, no apiKey needed
+ */
+import type { HttpClient } from "./http-client";
+export interface ClawvardPlugin {
+    /** Stable name — for diagnostics / dedup. */
+    name: string;
+    /** Called once at construction. Mutate `cv` to add namespaces. */
+    install(cv: ClawvardInstance, http: HttpClient): void;
+}
+/**
+ * The shape plugins see — `cv` is mutated to receive new namespace
+ * properties. Sub-packages declaration-merge their namespaces into
+ * `Clawvard` itself in their `index.ts` so end-user code sees a typed
+ * `cv.media.*` / `cv.video.*`.
+ */
+export interface ClawvardInstance {
+    [namespace: string]: unknown;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CACvD;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAG/B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B"}

package/dist/plugin.js

@@ -0,0 +1,15 @@
+/**
+ * Plugin protocol — lets `@clawvard/sdk-<school>` packages register
+ * additional namespaces (and types via declaration merging) onto a
+ * `Clawvard` instance.
+ *
+ * @example
+ *   import { Clawvard } from "@clawvard/sdk";
+ *   import { mediaPlugin } from "@clawvard/sdk-media";
+ *
+ *   const cv = new Clawvard({ apiKey, plugins: [mediaPlugin] });
+ *   cv.media.translateSubtitles({...});  // typed via declaration merging
+ *   cv.video.extractFrames({...});       // local helper, no apiKey needed
+ */
+export {};
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/service-types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * ServiceTypeMap — typed input/output per registered service id.
+ *
+ * Core SDK declares its own services here (util.*, plus any future
+ * shared text/audio/image entries). School sub-packages
+ * (`@clawvard/sdk-media`, etc.) extend this interface via
+ * declaration merging:
+ *
+ *   declare module "@clawvard/sdk" {
+ *     interface ServiceTypeMap {
+ *       "media.translate-subtitles": { input: ...; output: ... };
+ *     }
+ *   }
+ *
+ * Services not in the map still work via the generated client, but
+ * their `input`/`output` fall back to `unknown`.
+ *
+ * Typical workflow when adding a service to **core**:
+ *   1. Add the entry to `SERVICES[]` in `src/lib/services/registry.ts`
+ *   2. Define the `Input`/`Output` interfaces below
+ *   3. Add `"<id>": { input: ...; output: ... }` to `ServiceTypeMap`
+ *   4. Run `pnpm sdk:gen`
+ *
+ * For a **school sub-package**: see `docs/services-onboarding.md`
+ * → "Adding a school sub-package".
+ */
+export interface UtilDelayEchoInput {
+    /** Seconds to sleep before echoing. Default 3, max 30. */
+    seconds?: number;
+    /** Arbitrary payload echoed back in the result. */
+    payload?: unknown;
+}
+export interface UtilDelayEchoOutput {
+    echoed: unknown;
+    sleptSeconds: number;
+    jobId: string;
+}
+export interface UtilIpCheckOutput {
+    ip: string;
+}
+export interface TextWordCountInput {
+    text: string;
+}
+export interface TextWordCountOutput {
+    chars: number;
+    charsNoWhitespace: number;
+    words: number;
+    lines: number;
+    sentences: number;
+    longestLineChars: number;
+}
+export interface TextHashInput {
+    text: string;
+    algorithm?: "sha256" | "sha1" | "md5";
+}
+export interface TextHashOutput {
+    algorithm: string;
+    hex: string;
+}
+export interface UrlQrCodeInput {
+    /** Text or URL to encode. Max 2000 chars. */
+    text: string;
+    /** Pixel size of one side (64-1024). Default 256. */
+    size?: number;
+}
+export interface UrlQrCodeOutput {
+    /** PNG data URI ready to drop into an <img src="…">. */
+    dataUri: string;
+    byteLength: number;
+}
+export interface UrlPreviewInput {
+    url: string;
+}
+export interface UrlPreviewOutput {
+    url: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    siteName?: string;
+    type?: string;
+}
+export interface VideoRemoveSilenceInput {
+    inputUrl: string;
+    silenceThresholdDb?: number;
+    minSilenceMs?: number;
+}
+export interface VideoRemoveSilenceOutput {
+    outputUrl: string;
+    cutSeconds: number;
+    segmentsRemoved: number;
+}
+export interface ServiceTypeMap {
+    "util.ip-check": {
+        input: void;
+        output: UtilIpCheckOutput;
+    };
+    "util.delay-echo": {
+        input: UtilDelayEchoInput;
+        output: UtilDelayEchoOutput;
+    };
+    "text.word-count": {
+        input: TextWordCountInput;
+        output: TextWordCountOutput;
+    };
+    "text.hash": {
+        input: TextHashInput;
+        output: TextHashOutput;
+    };
+    "url.qr-code": {
+        input: UrlQrCodeInput;
+        output: UrlQrCodeOutput;
+    };
+    "url.preview": {
+        input: UrlPreviewInput;
+        output: UrlPreviewOutput;
+    };
+    "video.remove-silence": {
+        input: VideoRemoveSilenceInput;
+        output: VideoRemoveSilenceOutput;
+    };
+}
+/** Helper: resolve the input type for a given service id, or `unknown`. */
+export type InputOf<Id extends string> = Id extends keyof ServiceTypeMap ? ServiceTypeMap[Id]["input"] : unknown;
+/** Helper: resolve the output type for a given service id, or `unknown`. */
+export type OutputOf<Id extends string> = Id extends keyof ServiceTypeMap ? ServiceTypeMap[Id]["output"] : unknown;
+/** Helper: turn `InputOf<Id>` into a rest-parameter tuple. Services
+ *  declared with `input: void` become callable with NO arguments
+ *  (`cv.util.ipCheck()`); everything else takes one positional arg.
+ *  The tuple always has length 1 so the generated code can read
+ *  `args[0]` unconditionally — for void inputs that's `undefined`. */
+export type InputArgs<Id extends string> = InputOf<Id> extends void ? [input?: undefined] : [input: InputOf<Id>];
+//# sourceMappingURL=service-types.d.ts.map

package/dist/service-types.d.ts.map

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

package/dist/service-types.js

@@ -0,0 +1,28 @@
+/**
+ * ServiceTypeMap — typed input/output per registered service id.
+ *
+ * Core SDK declares its own services here (util.*, plus any future
+ * shared text/audio/image entries). School sub-packages
+ * (`@clawvard/sdk-media`, etc.) extend this interface via
+ * declaration merging:
+ *
+ *   declare module "@clawvard/sdk" {
+ *     interface ServiceTypeMap {
+ *       "media.translate-subtitles": { input: ...; output: ... };
+ *     }
+ *   }
+ *
+ * Services not in the map still work via the generated client, but
+ * their `input`/`output` fall back to `unknown`.
+ *
+ * Typical workflow when adding a service to **core**:
+ *   1. Add the entry to `SERVICES[]` in `src/lib/services/registry.ts`
+ *   2. Define the `Input`/`Output` interfaces below
+ *   3. Add `"<id>": { input: ...; output: ... }` to `ServiceTypeMap`
+ *   4. Run `pnpm sdk:gen`
+ *
+ * For a **school sub-package**: see `docs/services-onboarding.md`
+ * → "Adding a school sub-package".
+ */
+export {};
+//# sourceMappingURL=service-types.js.map

package/dist/service-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-types.js","sourceRoot":"","sources":["../src/service-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@clawvard/sdk",
+  "version": "0.1.0",
+  "description": "Clawvard unified service SDK — call every Clawvard service with one typed client.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "clawvard",
+    "ai",
+    "llm",
+    "agent",
+    "video",
+    "sdk"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}