@nodaro/sdk 1.30.1 → 2.2.0

package/dist/index.cjs

@@ -1,7 +1,41 @@
 'use strict';
 
-var prompts = require('@nodaro/prompts');
 var shared = require('@nodaro/shared');
+var prompts = require('@nodaro/prompts');
+
+// src/binary-response.ts
+async function readBinaryResponse(response, maxBytes) {
+  const advertised = response.headers.get("content-length");
+  if (advertised !== null && (!/^\d+$/.test(advertised) || Number(advertised) > maxBytes)) {
+    await response.body?.cancel();
+    throw new Error("Binary response exceeds its declared size limit");
+  }
+  if (!response.body) return new ArrayBuffer(0);
+  const reader = response.body.getReader();
+  const chunks = [];
+  let length = 0;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) break;
+      length += next.value.byteLength;
+      if (length > maxBytes) {
+        await reader.cancel();
+        throw new Error("Binary response exceeds its declared size limit");
+      }
+      chunks.push(next.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes.buffer;
+}
 
 // src/errors.ts
 var NodaroError = class extends Error {
@@ -59,8 +93,8 @@ var StorageExceededError = class extends NodaroError {
   limitBytes;
 };
 var WorkflowConflictError = class extends NodaroError {
-  constructor(message = "Workflow was updated by another writer", currentUpdatedAt, currentVersion, currentRecord) {
-    super(message, "workflow_conflict", 409);
+  constructor(message = "Workflow was updated by another writer", currentUpdatedAt, currentVersion, currentRecord, code = "workflow_conflict") {
+    super(message, code, 409);
     this.currentUpdatedAt = currentUpdatedAt;
     this.currentVersion = currentVersion;
     this.currentRecord = currentRecord;
@@ -70,6 +104,14 @@ var WorkflowConflictError = class extends NodaroError {
   currentVersion;
   currentRecord;
 };
+var StudioOpError = class extends NodaroError {
+  constructor(message, code, status, opIndex) {
+    super(message, code, status);
+    this.opIndex = opIndex;
+    this.name = "StudioOpError";
+  }
+  opIndex;
+};
 var JobBlockedError = class extends NodaroError {
   constructor(message = "Blocked by this deployment's content policy") {
     super(message, "job_blocked", 422);
@@ -116,14 +158,18 @@ function throwFromResponse(status, body) {
   const code = body.error?.code ?? "internal_error";
   const message = body.error?.message ?? "Request failed";
   if (status === 401) throw new UnauthorizedError(message);
-  if (status === 409 && code === "workflow_conflict") {
+  if (status === 409 && (code === "workflow_conflict" || code === "production_busy")) {
     throw new WorkflowConflictError(
       message,
       body.error?.currentUpdatedAt,
       body.error?.currentVersion,
-      body.error?.currentRecord
+      body.error?.currentRecord,
+      code
     );
   }
+  if (status >= 400 && status < 500 && typeof body.error?.opIndex === "number") {
+    throw new StudioOpError(message, code, status, body.error.opIndex);
+  }
   if (status === 422 && code === "job_blocked") throw new JobBlockedError(message);
   if (status === 403 && code === "insufficient_scope") {
     throw new ForbiddenError(message, body.error?.missingScope);
@@ -492,13 +538,19 @@ var NodesResource = class {
   get(type) {
     return this.client.request("GET", `/v1/nodes/${encodeURIComponent(type)}`);
   }
-  run(type, params = {}) {
+  run(type, params = {}, options = {}) {
     const route = type === "generate-3d-scene" ? "/v1/3d-scene/generate" : type === "edit-3d-scene" ? "/v1/3d-scene/edit" : type === "render-video" && typeof params.planType === "string" ? "/v1/render-video/plan" : `/v1/${encodeURIComponent(type)}`;
-    return this.client.request("POST", route, { body: params });
+    return this.client.request("POST", route, {
+      body: params,
+      // Transport-level retry safety, opt-in per call. The platform reads the
+      // standard header, so a caller that reuses a key on a retry gets the
+      // same run back instead of a second charge.
+      ...options.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : {}
+    });
   }
   async runAndWait(type, params = {}, opts = {}) {
     if (opts.signal?.aborted) throw new JobAbortedError();
-    const result = await this.run(type, params);
+    const result = await this.run(type, params, { idempotencyKey: opts.idempotencyKey });
     const jobId = extractJobId(result, type);
     return this.pollJob(jobId, type, opts);
   }
@@ -559,6 +611,125 @@ var NodesResource = class {
     }
   }
 };
+function newIdempotencyKey() {
+  const random = globalThis.crypto?.randomUUID?.();
+  return `sdk-pro3d-${random ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`}`;
+}
+var Scene3DResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  capabilities() {
+    return this.client.request("GET", "/v1/3d-scene/capabilities");
+  }
+  /** Current access to both the delivery and its source is required on every read. */
+  getDelivery(jobId) {
+    return this.client.request("GET", `/v1/3d-scene/deliveries/${encodeURIComponent(jobId)}`);
+  }
+  deliveryAssetBytes(jobId, asset, options) {
+    if (asset.kind !== "poster" && asset.kind !== "validation-report" || asset.usage !== (asset.kind === "poster" ? "poster" : "validation")) {
+      throw new Error("This asset is not available through the delivery endpoint");
+    }
+    if (!Number.isSafeInteger(asset.byteLength) || asset.byteLength < 1 || asset.byteLength > shared.SCENE3D_V2_LIMITS.maxRendererAssetBytes) {
+      throw new Error("Invalid scene delivery asset byte length");
+    }
+    return this.client.requestBytes("GET", `/v1/3d-scene/deliveries/${encodeURIComponent(jobId)}/assets/${encodeURIComponent(asset.assetId)}`, {
+      signal: options?.signal,
+      maxBytes: asset.byteLength
+    });
+  }
+  /** Persist deterministic overlays without an LLM or a generation charge. */
+  applyEdits(revisionId, params) {
+    return this.client.request("POST", `/v1/3d-scene/revisions/${encodeURIComponent(revisionId)}/edits`, { body: params });
+  }
+  /** Asset access is scoped to an exact retained revision, with fresh authentication. */
+  assetBytes(revisionId, asset, options) {
+    if (!["glb", "camera-track-json", "poster", "validation-report"].includes(asset.kind)) {
+      throw new Error("This asset is not available through the playback endpoint");
+    }
+    if (!Number.isSafeInteger(asset.byteLength) || asset.byteLength < 1 || asset.byteLength > shared.SCENE3D_V2_LIMITS.maxRendererAssetBytes) {
+      throw new Error("Invalid scene asset byte length");
+    }
+    return this.client.requestBytes("GET", `/v1/3d-scene/revisions/${encodeURIComponent(revisionId)}/assets/${encodeURIComponent(asset.assetId)}`, {
+      signal: options?.signal,
+      maxBytes: asset.byteLength
+    });
+  }
+  /** The editable native file has its own authorization lane. */
+  sourceBytes(revisionId, options) {
+    return this.client.requestBytes("GET", `/v1/3d-scene/revisions/${encodeURIComponent(revisionId)}/source`, {
+      signal: options?.signal,
+      maxBytes: shared.SCENE3D_V2_LIMITS.maxBlendSourceBytes
+    });
+  }
+  generate(params) {
+    return this.client.nodes.run("generate-3d-scene", params);
+  }
+  generateAndWait(params, options) {
+    return this.client.nodes.runAndWait("generate-3d-scene", params, options);
+  }
+  edit(params) {
+    return this.client.nodes.run("edit-3d-scene", params);
+  }
+  editAndWait(params, options) {
+    return this.client.nodes.runAndWait("edit-3d-scene", params, options);
+  }
+  /**
+   * Price a 3D Render Pro request WITHOUT starting it.
+   *
+   * Takes the same body a run takes, minus the `quoteId`, and answers a
+   * ceiling (`maxCredits`), a `breakdown` to show, and the
+   * `normalizedInputHash` admission re-checks. It reserves nothing and spends
+   * nothing — a quote is a price, not a purchase.
+   */
+  quotePro(params) {
+    return this.client.request("POST", "/v1/pro-3d-render/quote", { body: params });
+  }
+  /**
+   * Submit a quoted 3D Render Pro run.
+   *
+   * Requires the `quoteId` from {@link quotePro}: no run starts at a price
+   * nobody showed. Sends an `Idempotency-Key` — a fresh one per call unless you
+   * supply your own, which you should when retrying a call that timed out.
+   *
+   * Availability is a property of the deployment: `capabilities().pro` says
+   * whether this install can serve it, and which controls you may offer.
+   */
+  runPro(params, options) {
+    return this.client.nodes.run("pro-3d-render", params, {
+      idempotencyKey: options?.idempotencyKey ?? newIdempotencyKey()
+    });
+  }
+  /**
+   * Quote if needed, run, and wait — the whole operation in one call.
+   *
+   * Two HTTP requests at most, still ONE paid job: when `quoteId` is absent
+   * this quotes the identical body first, so the run is admitted against a
+   * hash of exactly what was priced. Pass a `quoteId` to run against a quote
+   * you already showed the user.
+   *
+   * Resolves with the settled result — `videoUrl` (the MP4) and `scenePlan`
+   * (the exact composition it was rendered from), plus the revision, poster,
+   * validation and renderer metadata. Re-render that same `scenePlan` later
+   * with {@link render}, or with a `{kind:'scene'}` source; that costs no
+   * authoring.
+   */
+  async renderProAndWait(params, options) {
+    const quoteId = typeof params.quoteId === "string" ? params.quoteId : (await this.quotePro(params)).quoteId;
+    return this.client.nodes.runAndWait("pro-3d-render", { ...params, quoteId }, {
+      ...options,
+      idempotencyKey: options?.idempotencyKey ?? newIdempotencyKey()
+    });
+  }
+  /** Uses the supplied immutable revision; never starts authoring or a rebuild. */
+  render(params) {
+    return this.client.nodes.run("render-video", params);
+  }
+  renderAndWait(params, options) {
+    return this.client.nodes.runAndWait("render-video", params, options);
+  }
+};
 
 // src/resources/developer-apps.ts
 var DeveloperAppsResource = class {
@@ -2372,6 +2543,245 @@ var RecastResource = class {
   }
 };
 
+// src/resources/studio.ts
+function isStudioGenerateEstimate(result) {
+  return result.dryRun === true;
+}
+var StudioProductionsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  path(productionId, suffix = "") {
+    return `/v1/studio/productions/${encodeURIComponent(productionId)}${suffix}`;
+  }
+  // ── reads ────────────────────────────────────────────────────────────────
+  /**
+   * The authoring guide, the full catalog, the plan's JSON Schema and the
+   * operating guide — rendered server-side from the version that is live, so
+   * they describe the platform you are actually talking to. Free.
+   */
+  async skill() {
+    const res = await this.client.request(
+      "GET",
+      "/v1/studio/productions/skill"
+    );
+    return res.data;
+  }
+  /**
+   * Check a plan before it becomes anything. Free, persists nothing, and
+   * resolves cast names against YOUR library — loop on `errors` until
+   * `valid: true`, then `create({ plan })`.
+   */
+  async validatePlan(plan) {
+    const res = await this.client.request(
+      "POST",
+      "/v1/studio/productions/validate",
+      { body: { plan } }
+    );
+    return res.data;
+  }
+  /** Your productions, newest first. Archived rows are hidden unless asked for. */
+  async list(opts = {}) {
+    const res = await this.client.request(
+      "GET",
+      "/v1/studio/productions",
+      {
+        query: {
+          limit: opts.limit,
+          cursor: opts.cursor,
+          includeArchived: opts.includeArchived
+        }
+      }
+    );
+    return res.data;
+  }
+  /**
+   * One production. A pure read — it never lands a finished job, so call
+   * {@link reconcile} first if you are waiting on one.
+   */
+  async get(productionId, opts = {}) {
+    const res = await this.client.request(
+      "GET",
+      this.path(productionId),
+      { query: { detail: opts.detail, shot_id: opts.shotId } }
+    );
+    return res.data.production;
+  }
+  /**
+   * The ordered steps that assemble the film, with what they will cost. Run
+   * them yourself with the ordinary verbs — nothing here blocks for minutes,
+   * and nothing here spends.
+   */
+  async exportPlan(productionId, opts = {}) {
+    const res = await this.client.request(
+      "GET",
+      this.path(productionId, "/export-plan"),
+      { query: { upscale: opts.upscale } }
+    );
+    return res.data;
+  }
+  // ── writes ───────────────────────────────────────────────────────────────
+  /** A new production, optionally landed from a plan in the same call. */
+  async create(input = {}) {
+    const res = await this.client.request(
+      "POST",
+      "/v1/studio/productions",
+      { body: input }
+    );
+    return res.data;
+  }
+  /**
+   * Apply a batch of operations. Atomic: one bad operation refuses the whole
+   * batch with a `StudioOpError` naming its index, and nothing is written. On
+   * success adopt `production` wholesale and carry `version` forward as the
+   * next `baseVersion`.
+   */
+  async ops(productionId, input) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/ops"),
+      { body: input }
+    );
+    return res.data;
+  }
+  /**
+   * Land every generation that has finished since you last looked, and report
+   * what is still running. The one call that turns finished jobs into results
+   * without a browser open. It writes only when something actually landed.
+   */
+  async reconcile(productionId) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/reconcile")
+    );
+    return res.data;
+  }
+  /** Add a plan's scenes to a production that already exists. */
+  async importPlan(productionId, plan, opts = {}) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/import"),
+      { body: { plan, mode: opts.mode ?? "append" } }
+    );
+    return res.data;
+  }
+  /**
+   * Turn a brief into scenes. The run is a platform job: poll it, and its
+   * scenes land through {@link reconcile}. The production comes back with the
+   * run recorded on it as a pending draft.
+   */
+  async describe(productionId, input) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/describe"),
+      { body: input }
+    );
+    return res.data;
+  }
+  async generate(productionId, input) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/generate"),
+      { body: input }
+    );
+    return res.data;
+  }
+  generateStill(productionId, shotId, opts = {}) {
+    return this.generate(productionId, { ...opts, kind: "still", shotId });
+  }
+  generateClip(productionId, shotId, opts = {}) {
+    return this.generate(productionId, { ...opts, kind: "clip", shotId });
+  }
+  // ── media on one shot ────────────────────────────────────────────────────
+  /**
+   * Extract a frame from a shot's active clip and put it where `target` says —
+   * a new shot after this one (the default), this shot's sticky start or end
+   * frame, or another still of the same shot. Seconds, not minutes: this one
+   * waits for the job and answers with the changed production.
+   */
+  async frame(productionId, input) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/frame"),
+      { body: input }
+    );
+    return res.data;
+  }
+  /** Synthesize a shot's spoken line and record it. Waits for the job. */
+  async voice(productionId, input) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/voice"),
+      { body: input }
+    );
+    return res.data;
+  }
+  /**
+   * Recast the voices of a shot's active clip. Minutes of work, so it answers
+   * `jobId` and the new clip lands as a result through its own marker.
+   */
+  async revoice(productionId, input) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/revoice"),
+      { body: input }
+    );
+    return res.data;
+  }
+  /** Score the film. The finished track lands through its pending marker. */
+  async music(productionId, input) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/music"),
+      { body: input }
+    );
+    return res.data;
+  }
+  // ── audience and copies ──────────────────────────────────────────────────
+  /**
+   * Open the share-by-link read. Deliberately its own route rather than an
+   * operation: who may see the work is decided by the owner, never as a side
+   * effect of a batch that was editing something else.
+   */
+  async share(productionId) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/share"),
+      { body: { shared: true } }
+    );
+    return res.data.production;
+  }
+  /** Close it again. Sharing is opt-in AND reversible. */
+  async unshare(productionId) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/unshare")
+    );
+    return res.data.production;
+  }
+  /**
+   * Copy a production you own or can see into your own Studio project. The
+   * copy starts PRIVATE and visible — sharing and archiving never travel — and
+   * it is copied through YOUR view of the source, so somebody else's bin does
+   * not come with it.
+   */
+  async clone(productionId, input = {}) {
+    const res = await this.client.request(
+      "POST",
+      this.path(productionId, "/clone"),
+      { body: input }
+    );
+    return res.data.production;
+  }
+};
+var StudioResource = class {
+  productions;
+  constructor(client) {
+    this.productions = new StudioProductionsResource(client);
+  }
+};
+
 // src/resources/community.ts
 var CommunityResource = class {
   constructor(client) {
@@ -2753,7 +3163,7 @@ var WorkspacesResource = class {
     return this.client.requestText("GET", `/v1/workspaces/${encodeURIComponent(id)}/usage`, { query: { ...opts, format: "csv" } });
   }
 };
-var SDK_VERSION = "1.30.1" ;
+var SDK_VERSION = "2.2.0" ;
 var CLIENT_HEADER = "X-Nodaro-Client";
 var isBrowser = () => typeof window !== "undefined" && typeof window.document !== "undefined";
 var NodaroClient = class _NodaroClient {
@@ -2780,6 +3190,7 @@ var NodaroClient = class _NodaroClient {
   videoPro;
   executions;
   nodes;
+  scene3d;
   developerApps;
   oauth;
   apps;
@@ -2803,6 +3214,7 @@ var NodaroClient = class _NodaroClient {
   models;
   shots;
   recast;
+  studio;
   community;
   templates;
   tutorials;
@@ -2824,6 +3236,7 @@ var NodaroClient = class _NodaroClient {
     this.videoPro = new VideoProResource(this);
     this.executions = new ExecutionsResource(this);
     this.nodes = new NodesResource(this);
+    this.scene3d = new Scene3DResource(this);
     this.developerApps = new DeveloperAppsResource(this);
     this.oauth = new OAuthResource(this);
     this.apps = new AppsResource(this);
@@ -2847,6 +3260,7 @@ var NodaroClient = class _NodaroClient {
     this.models = new ModelsResource(this);
     this.shots = new ShotsResource(this);
     this.recast = new RecastResource(this);
+    this.studio = new StudioResource(this);
     this.community = new CommunityResource(this);
     this.templates = new TemplatesResource(this);
     this.tutorials = new TutorialsResource(this);
@@ -2896,10 +3310,11 @@ var NodaroClient = class _NodaroClient {
     if (token) headers["Authorization"] = `Bearer ${token}`;
     const ac = new AbortController();
     const timeoutId = setTimeout(() => ac.abort(), this.timeoutMs);
-    if (options.signal) {
-      options.signal.addEventListener("abort", () => ac.abort(), { once: true });
-    }
+    const abort = () => ac.abort(options.signal?.reason);
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted) abort();
     try {
+      ac.signal.throwIfAborted();
       const res = await this.fetch(url, {
         method,
         headers,
@@ -2917,8 +3332,14 @@ var NodaroClient = class _NodaroClient {
       return await read(res);
     } finally {
       clearTimeout(timeoutId);
+      options.signal?.removeEventListener("abort", abort);
     }
   }
+  /** Authenticated, bounded binary reads through the normal timeout/error transport. */
+  async requestBytes(method, path, options) {
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 1) throw new Error("maxBytes must be a positive integer");
+    return this.send(method, path, options, (response) => readBinaryResponse(response, options.maxBytes));
+  }
   async request(method, path, options = {}) {
     return this.send(
       method,
@@ -3001,22 +3422,6 @@ function supabaseAuth(supabase) {
   };
 }
 
-Object.defineProperty(exports, "PEOPLE", {
-  enumerable: true,
-  get: function () { return prompts.PEOPLE; }
-});
-Object.defineProperty(exports, "PERSON_DIMENSION_LABELS", {
-  enumerable: true,
-  get: function () { return prompts.PERSON_DIMENSION_LABELS; }
-});
-Object.defineProperty(exports, "PERSON_DIMENSION_ORDER", {
-  enumerable: true,
-  get: function () { return prompts.PERSON_DIMENSION_ORDER; }
-});
-Object.defineProperty(exports, "buildPersonHints", {
-  enumerable: true,
-  get: function () { return prompts.buildPersonHints; }
-});
 Object.defineProperty(exports, "CHARACTER_ASPECT_DEFAULTS", {
   enumerable: true,
   get: function () { return shared.CHARACTER_ASPECT_DEFAULTS; }
@@ -3085,6 +3490,22 @@ Object.defineProperty(exports, "WORKSPACE_HEADER", {
   enumerable: true,
   get: function () { return shared.WORKSPACE_HEADER; }
 });
+Object.defineProperty(exports, "PEOPLE", {
+  enumerable: true,
+  get: function () { return prompts.PEOPLE; }
+});
+Object.defineProperty(exports, "PERSON_DIMENSION_LABELS", {
+  enumerable: true,
+  get: function () { return prompts.PERSON_DIMENSION_LABELS; }
+});
+Object.defineProperty(exports, "PERSON_DIMENSION_ORDER", {
+  enumerable: true,
+  get: function () { return prompts.PERSON_DIMENSION_ORDER; }
+});
+Object.defineProperty(exports, "buildPersonHints", {
+  enumerable: true,
+  get: function () { return prompts.buildPersonHints; }
+});
 exports.AppsResource = AppsResource;
 exports.AudioResource = AudioResource;
 exports.CREATURE_ASSET_TYPES = CREATURE_ASSET_TYPES;
@@ -3124,9 +3545,13 @@ exports.PromptHelperResource = PromptHelperResource;
 exports.RateLimitedError = RateLimitedError;
 exports.RecastResource = RecastResource;
 exports.ReduceResource = ReduceResource;
+exports.Scene3DResource = Scene3DResource;
 exports.ShotsResource = ShotsResource;
 exports.StaticTokenAuth = StaticTokenAuth;
 exports.StorageExceededError = StorageExceededError;
+exports.StudioOpError = StudioOpError;
+exports.StudioProductionsResource = StudioProductionsResource;
+exports.StudioResource = StudioResource;
 exports.TemplatesResource = TemplatesResource;
 exports.TutorialsResource = TutorialsResource;
 exports.UnauthorizedError = UnauthorizedError;
@@ -3138,6 +3563,7 @@ exports.WorkflowsResource = WorkflowsResource;
 exports.WorkspacesResource = WorkspacesResource;
 exports.buildPersonSeedPrompt = buildPersonSeedPrompt;
 exports.createClient = createClient;
+exports.isStudioGenerateEstimate = isStudioGenerateEstimate;
 exports.supabaseAuth = supabaseAuth;
 exports.throwFromResponse = throwFromResponse;
 //# sourceMappingURL=index.cjs.map