@curvet/sdk 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to `@curvet/sdk` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-06-27
+
+### Added
+- **Pollable workflow runs** for long workflows (video/audio/3D nodes) — no more
+  one long-lived HTTP call:
+  - `workflows.submit(id, params)` — start a run, returns a `runId` immediately.
+  - `workflows.runs.retrieve(runId)` — live status: `currentNode`, `progress`,
+    per-node history, and the final `result`.
+  - `workflows.runAndPoll(id, params, { onProgress })` — submit + auto-poll to
+    completion (mirrors `video.generate`).
+- `WorkflowRunFailedError` and `WorkflowRunTimeoutError` (both carry `runId`).
+- `examples/pollable-workflow.ts`.
+
+### Notes
+- `workflows.run()` (synchronous) is unchanged.
+- Requires the matching backend (media-node execution + pollable run endpoints).
+
+## [0.2.1] - 2026-06-20
+
+### Added
+- Additional resources: `audio.generate`/`submit`, `threeD.generate`/`submit`,
+  `analytics.get`, `workflows.run` (JSON or multipart file inputs), `food.*`
+  (list/search/recommendations), and `voice.stt`.
+- `FormData` (multipart) support in the HTTP layer for file uploads.
+
+## [0.1.0] - 2026-06-19
+
+### Added
+- Initial release. One typed client over the Curvet Playground API:
+  `chat.create`, `image.generate`, `video.generate`/`submit` with **async
+  auto-polling**, `jobs.retrieve`, `models.list`, `balance.get`.
+- Typed error taxonomy (`AuthError`, `InsufficientBalanceError`, `RateLimitError`,
+  `JobFailedError`, …) and automatic retry/backoff on 429/5xx.
+- Live model catalog (never hardcoded). Ships ESM + CJS + type declarations.
+
+[0.3.0]: https://github.com/Curvet-in/curvet-sdk/releases/tag/v0.3.0
+[0.2.1]: https://github.com/Curvet-in/curvet-sdk/releases/tag/v0.2.1
+[0.1.0]: https://github.com/Curvet-in/curvet-sdk/releases/tag/v0.1.0

package/README.md

@@ -83,11 +83,57 @@ if (job.status !== "completed") {
 const status = await curvet.jobs.retrieve(job.jobId!);
 ```
 
-### Models & balance
+### Audio & 3D (async, same as video)
+
+```ts
+const audio = await curvet.audio.generate({ model: "fish-audio", prompt: "Hello there" });
+const mesh = await curvet.threeD.generate({ model: "meshy-3d", prompt: "a ceramic mug" });
+console.log(audio.mediaUrl, mesh.mediaUrl);
+```
+
+### Models, balance & analytics
 
 ```ts
 const chatModels = await curvet.models.list({ type: "chat" });
 const balance = await curvet.balance.get();
+const analytics = await curvet.analytics.get({ startDate: "2026-01-01", endDate: "2026-02-01" });
+```
+
+### Workflows
+
+```ts
+// JSON inputs:
+const out = await curvet.workflows.run("workflowId", { inputs: { topic: "ai" } });
+
+// With file inputs (multipart, handled for you):
+await curvet.workflows.run("workflowId", {
+  inputs: { caption: "hello" },
+  files: { image: new Blob([bytes], { type: "image/png" }) },
+});
+```
+
+For long workflows (video/audio/3D nodes), use the **pollable** API — submit
+and auto-poll to completion with live progress, instead of one long HTTP call:
+
+```ts
+const run = await curvet.workflows.runAndPoll(
+  "workflowId",
+  { inputs: { topic: "ai" } },
+  { onProgress: (r) => console.log(r.status, r.progress + "%", r.currentNode?.label) },
+);
+console.log(run.result);
+
+// Or fire-and-forget + poll yourself:
+const { runId } = await curvet.workflows.submit("workflowId", { inputs: {} });
+const status = await curvet.workflows.runs.retrieve(runId);
+```
+
+### Food & speech-to-text
+
+```ts
+const dishes = await curvet.food.search("paneer", { limit: 5 });
+const stt = await curvet.voice.stt({ audio: audioBytes, filename: "clip.wav" });
+console.log(stt.text);
 ```
 
 ## Errors
@@ -155,6 +201,32 @@ npm run build   # ESM + CJS + d.ts via tsup
 CURVET_TEST_APP_KEY=cvt_app_xxx npm test
 ```
 
+## Releasing
+
+Publishing happens locally with the release script — no npm token, no CI.
+`npm publish` prompts for your passkey/2FA, which you approve in the browser.
+
+```bash
+./scripts/release.sh            # publish the current package.json version
+./scripts/release.sh patch      # bump patch, then publish  (0.2.0 -> 0.2.1)
+./scripts/release.sh minor      # bump minor, then publish
+./scripts/release.sh major      # bump major, then publish
+```
+
+The script validates (typecheck + tests + build) before bumping, tags the
+version, publishes (you approve the passkey prompt), then pushes the tag and
+commit to GitHub. The order is deliberate — if the publish is cancelled,
+nothing is pushed; just re-run `npm publish && git push --follow-tags origin main`
+to finish.
+
+> A tokenless CI alternative using npm Trusted Publishing (OIDC) is also included
+> at [`.github/workflows/publish.yml`](.github/workflows/publish.yml) for when
+> GitHub Actions is available.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   APIError: () => APIError,
+  Analytics: () => Analytics,
+  Audio: () => Audio,
   AuthError: () => AuthError,
   BadRequestError: () => BadRequestError,
   Balance: () => Balance,
@@ -29,17 +31,25 @@ __export(index_exports, {
   Curvet: () => Curvet,
   CurvetError: () => CurvetError,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  Food: () => Food,
   Images: () => Images,
   InsufficientBalanceError: () => InsufficientBalanceError,
   Job: () => Job,
   JobFailedError: () => JobFailedError,
   JobTimeoutError: () => JobTimeoutError,
   Jobs: () => Jobs,
+  MediaResource: () => MediaResource,
   Models: () => Models,
   NotFoundError: () => NotFoundError,
   PermissionError: () => PermissionError,
   RateLimitError: () => RateLimitError,
-  Video: () => Video
+  ThreeD: () => ThreeD,
+  Video: () => Video,
+  Voice: () => Voice,
+  WorkflowRunFailedError: () => WorkflowRunFailedError,
+  WorkflowRunTimeoutError: () => WorkflowRunTimeoutError,
+  WorkflowRuns: () => WorkflowRuns,
+  Workflows: () => Workflows
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -82,6 +92,18 @@ var JobTimeoutError = class extends CurvetError {
     this.jobId = jobId;
   }
 };
+var WorkflowRunFailedError = class extends CurvetError {
+  constructor(message, runId, opts = {}) {
+    super(message, opts);
+    this.runId = runId;
+  }
+};
+var WorkflowRunTimeoutError = class extends CurvetError {
+  constructor(message, runId, opts = {}) {
+    super(message, opts);
+    this.runId = runId;
+  }
+};
 function errorFromResponse(status, body, requestId, headers) {
   const b = body ?? {};
   const message = typeof b.error === "string" ? b.error : `HTTP ${status}`;
@@ -170,8 +192,12 @@ var HttpClient = class {
     };
     let payload;
     if (body !== void 0) {
-      headers["content-type"] = "application/json";
-      payload = JSON.stringify(body);
+      if (typeof FormData !== "undefined" && body instanceof FormData) {
+        payload = body;
+      } else {
+        headers["content-type"] = "application/json";
+        payload = JSON.stringify(body);
+      }
     }
     let attempt = 0;
     for (; ; ) {
@@ -405,20 +431,17 @@ var Job = class {
   }
 };
 
-// src/resources/video.ts
-var Video = class {
-  constructor(client, defaults, path = "/video") {
+// src/resources/media.ts
+var MediaResource = class {
+  constructor(client, defaults, path) {
     this.client = client;
     this.defaults = defaults;
     this.path = path;
   }
   /**
-   * Submit a job WITHOUT polling. Returns once the server responds — either the
-   * 200 fast-path (already done) or a 202 with a jobId.
-   *
-   * The media POST long-polls server-side and can block well past a normal
-   * request timeout, so we default its timeout to the poll budget and disable
-   * auto-retry (a retried POST would enqueue a duplicate, double-charged job).
+   * Submit WITHOUT polling. The media POST long-polls server-side and can block
+   * well past a normal request timeout, so we default its timeout to the poll
+   * budget and disable auto-retry (a retried POST would enqueue a duplicate job).
    */
   async submit(params, options) {
     const reqOptions = {
@@ -434,10 +457,7 @@ var Video = class {
     });
     return normalizeMediaPost(body);
   }
-  /**
-   * Submit and resolve to the finished media. Handles the 200-vs-202 split and
-   * polls `/jobs/:id` internally. Throws JobFailedError / JobTimeoutError.
-   */
+  /** Submit and resolve to the finished media (auto-polls /jobs/:id). */
   async generate(params, options) {
     const submitted = await this.submit(params, options);
     if (submitted.status === "completed" || submitted.status === "failed") {
@@ -458,6 +478,27 @@ var Video = class {
   }
 };
 
+// src/resources/video.ts
+var Video = class extends MediaResource {
+  constructor(client, defaults) {
+    super(client, defaults, "/video");
+  }
+};
+
+// src/resources/audio.ts
+var Audio = class extends MediaResource {
+  constructor(client, defaults) {
+    super(client, defaults, "/audio");
+  }
+};
+
+// src/resources/threeD.ts
+var ThreeD = class extends MediaResource {
+  constructor(client, defaults) {
+    super(client, defaults, "/3d");
+  }
+};
+
 // src/resources/models.ts
 var Models = class {
   constructor(client, cacheTtlMs = 6e4) {
@@ -510,6 +551,227 @@ var Balance = class {
   }
 };
 
+// src/resources/analytics.ts
+var Analytics = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Usage analytics for the app, optionally bounded by a date range. */
+  async get(params = {}) {
+    const { startDate, endDate, ...options } = params;
+    const body = await this.client.request({
+      method: "GET",
+      path: "/analytics",
+      query: { startDate, endDate },
+      options
+    });
+    return body.analytics;
+  }
+};
+
+// src/resources/workflows.ts
+function normalizeRun(body) {
+  const b = body ?? {};
+  return {
+    runId: b.runId,
+    status: b.status,
+    progress: b.progress,
+    totalNodes: b.totalNodes,
+    completedNodeCount: b.completedNodeCount,
+    currentNode: b.currentNode ?? null,
+    nodesExecuted: b.nodesExecuted,
+    result: b.result,
+    error: b.error ?? null,
+    startTime: b.startTime,
+    endTime: b.endTime,
+    raw: body
+  };
+}
+function buildBody(params, extra = {}) {
+  const hasFiles = params.files && Object.keys(params.files).length > 0;
+  if (hasFiles) {
+    const form = new FormData();
+    form.append("inputs", JSON.stringify(params.inputs ?? {}));
+    if (params.includeFullState !== void 0) {
+      form.append("includeFullState", String(params.includeFullState));
+    }
+    for (const [k, v] of Object.entries(extra)) form.append(k, String(v));
+    for (const [field, file] of Object.entries(params.files)) {
+      form.append(field, file);
+    }
+    return form;
+  }
+  return {
+    inputs: params.inputs ?? {},
+    includeFullState: params.includeFullState,
+    ...extra
+  };
+}
+var WorkflowRuns = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Fetch the current status of an async run once (no polling). */
+  async retrieve(runId, options) {
+    const body = await this.client.request({
+      method: "GET",
+      path: `/workflows/runs/${encodeURIComponent(runId)}`,
+      options
+    });
+    return normalizeRun(body);
+  }
+};
+var Workflows = class {
+  constructor(client) {
+    this.client = client;
+    this.runs = new WorkflowRuns(client);
+  }
+  /**
+   * Execute a workflow synchronously (blocks until it finishes). Best for short
+   * workflows; for long ones (video/audio/3D nodes) prefer `runAndPoll`.
+   * Sends JSON, or multipart/form-data when file inputs are provided.
+   */
+  async run(id, params = {}, options) {
+    const reqOptions = { ...options, maxRetries: options?.maxRetries ?? 0 };
+    return this.client.request({
+      method: "POST",
+      path: `/workflows/${encodeURIComponent(id)}/run`,
+      body: buildBody(params),
+      options: reqOptions
+    });
+  }
+  /**
+   * Submit a workflow in async (pollable) mode — returns immediately with a
+   * runId. Poll `runs.retrieve(runId)` for status, or use `runAndPoll`.
+   */
+  async submit(id, params = {}, options) {
+    const reqOptions = { ...options, maxRetries: options?.maxRetries ?? 0 };
+    const res = await this.client.request({
+      method: "POST",
+      path: `/workflows/${encodeURIComponent(id)}/run`,
+      body: buildBody(params, { async: true }),
+      options: reqOptions
+    });
+    return { runId: res?.runId, status: res?.status ?? "running", raw: res };
+  }
+  /**
+   * Submit and poll to completion. Resolves with the completed run (including
+   * `result`), reporting progress via `onProgress`. Throws WorkflowRunFailedError
+   * on failure, WorkflowRunTimeoutError on timeout.
+   */
+  async runAndPoll(id, params = {}, opts = {}) {
+    const submitted = await this.submit(id, params, opts);
+    if (!submitted.runId) {
+      throw new CurvetError("Workflow submit did not return a runId", {
+        raw: submitted.raw
+      });
+    }
+    const intervalMs = opts.pollIntervalMs ?? 2500;
+    const timeoutMs = opts.pollTimeoutMs ?? 3e5;
+    let run;
+    try {
+      run = await pollUntil(
+        () => this.runs.retrieve(submitted.runId, { signal: opts.signal }),
+        {
+          intervalMs,
+          timeoutMs,
+          signal: opts.signal,
+          isTerminal: (r) => r.status === "completed" || r.status === "failed" || r.status === "stopped",
+          onTick: (r) => opts.onProgress?.(r)
+        }
+      );
+    } catch (e) {
+      if (e instanceof PollTimeoutError) {
+        throw new WorkflowRunTimeoutError(
+          `Workflow run ${submitted.runId} did not finish within ${timeoutMs}ms`,
+          submitted.runId
+        );
+      }
+      throw e;
+    }
+    if (run.status === "failed" || run.status === "stopped") {
+      throw new WorkflowRunFailedError(
+        run.error || `Workflow run ${submitted.runId} ${run.status}`,
+        submitted.runId,
+        { raw: run.raw }
+      );
+    }
+    return run;
+  }
+};
+
+// src/resources/food.ts
+var Food = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List dishes (default limit 20). */
+  async list(opts) {
+    const { limit, ...options } = opts ?? {};
+    const body = await this.client.request({
+      method: "GET",
+      path: "/food",
+      query: { limit },
+      options
+    });
+    return body.data;
+  }
+  /** Full-text search for dishes. */
+  async search(query, opts) {
+    const { limit, ...options } = opts ?? {};
+    const body = await this.client.request({
+      method: "GET",
+      path: "/food/search",
+      query: { q: query, limit },
+      options
+    });
+    return body.data;
+  }
+  /** Natural-language dish recommendations. */
+  async recommendations(prompt, options) {
+    const body = await this.client.request({
+      method: "POST",
+      path: "/food/recommendations",
+      body: { prompt },
+      options
+    });
+    return body.data;
+  }
+};
+
+// src/resources/voice.ts
+var Voice = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async stt(params, options) {
+    const form = new FormData();
+    form.append("audio", toBlob(params.audio), params.filename ?? "audio");
+    if (params.provider) form.append("provider", params.provider);
+    if (params.model) form.append("model", params.model);
+    if (params.prompt) form.append("prompt", params.prompt);
+    if (params.languageCode) form.append("languageCode", params.languageCode);
+    if (params.allowFallback !== void 0) {
+      form.append("allowFallback", String(params.allowFallback));
+    }
+    const reqOptions = {
+      ...options,
+      timeout: options?.timeout ?? 12e4,
+      maxRetries: options?.maxRetries ?? 0
+    };
+    return this.client.request({
+      method: "POST",
+      path: "/voice/stt/public",
+      body: form,
+      options: reqOptions
+    });
+  }
+};
+function toBlob(audio) {
+  if (typeof Blob !== "undefined" && audio instanceof Blob) return audio;
+  return new Blob([audio]);
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://curvet.ai/api/v1/playground";
 var Curvet = class {
@@ -526,13 +788,16 @@ var Curvet = class {
         "No fetch implementation available. Use Node 18+ or pass { fetch }."
       );
     }
-    const client = new HttpClient({
+    const playgroundBase = options.baseURL ?? DEFAULT_BASE_URL;
+    const v1Base = playgroundBase.replace(/\/playground\/?$/, "");
+    const shared = {
       appKey,
-      baseURL: options.baseURL ?? DEFAULT_BASE_URL,
       timeout: options.timeout ?? 6e4,
       maxRetries: options.maxRetries ?? 2,
       fetch: fetchImpl
-    });
+    };
+    const client = new HttpClient({ ...shared, baseURL: playgroundBase });
+    const v1Client = new HttpClient({ ...shared, baseURL: v1Base });
     const jobDefaults = {
       pollIntervalMs: options.defaultPollIntervalMs ?? 2500,
       pollTimeoutMs: options.defaultPollTimeoutMs ?? 18e4
@@ -541,8 +806,14 @@ var Curvet = class {
     this.image = new Images(client);
     this.jobs = new Jobs(client, jobDefaults);
     this.video = new Video(client, jobDefaults);
+    this.audio = new Audio(client, jobDefaults);
+    this.threeD = new ThreeD(client, jobDefaults);
     this.models = new Models(client);
     this.balance = new Balance(client);
+    this.analytics = new Analytics(client);
+    this.workflows = new Workflows(client);
+    this.food = new Food(v1Client);
+    this.voice = new Voice(v1Client);
   }
 };
 function envKey() {
@@ -555,6 +826,8 @@ function defaultFetch() {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,
+  Analytics,
+  Audio,
   AuthError,
   BadRequestError,
   Balance,
@@ -563,16 +836,24 @@ function defaultFetch() {
   Curvet,
   CurvetError,
   DEFAULT_BASE_URL,
+  Food,
   Images,
   InsufficientBalanceError,
   Job,
   JobFailedError,
   JobTimeoutError,
   Jobs,
+  MediaResource,
   Models,
   NotFoundError,
   PermissionError,
   RateLimitError,
-  Video
+  ThreeD,
+  Video,
+  Voice,
+  WorkflowRunFailedError,
+  WorkflowRunTimeoutError,
+  WorkflowRuns,
+  Workflows
 });
 //# sourceMappingURL=index.cjs.map