@convilyn/sdk 0.2.0 → 0.4.0

package/dist/cli.cjs

@@ -6,10 +6,13 @@ var fs = require('fs');
 var path = require('path');
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 
 // src/errors.ts
+var CONVILYN_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@convilyn/sdk.ConvilynError");
 var ConvilynError = class extends Error {
+  /** @internal brand marker — see {@link isConvilynError} */
+  [CONVILYN_ERROR_BRAND] = true;
   constructor(message) {
     super(message);
     this.name = "ConvilynError";
@@ -115,14 +118,22 @@ var GoalJobTimeoutError = class extends ConvilynError {
   jobSpecId;
   elapsed;
   timeout;
+  /**
+   * `'total'` — the overall `timeout` budget lapsed; `'idle'` —
+   * `idleTimeout` lapsed with no status/progress change (the job may still
+   * be healthy on a long phase; `retrieve()` before assuming failure).
+   */
+  reason;
   constructor(opts) {
+    const reason = opts.reason ?? "total";
     super(
-      `GoalJob ${opts.jobSpecId} did not reach a terminal status within ${opts.timeout}s (elapsed ${opts.elapsed.toFixed(1)}s)`
+      reason === "idle" ? `GoalJob ${opts.jobSpecId} showed no status/progress change for ${opts.timeout}s (elapsed ${opts.elapsed.toFixed(1)}s total)` : `GoalJob ${opts.jobSpecId} did not reach a terminal status within ${opts.timeout}s (elapsed ${opts.elapsed.toFixed(1)}s)`
     );
     this.name = "GoalJobTimeoutError";
     this.jobSpecId = opts.jobSpecId;
     this.elapsed = opts.elapsed;
     this.timeout = opts.timeout;
+    this.reason = reason;
   }
 };
 var WebSocketError = class extends ConvilynError {
@@ -722,6 +733,29 @@ function parseGoalJob(wire) {
     completedAt: toDateOrNull(wire.completedAt)
   };
 }
+function parseArtifact(wire) {
+  return {
+    artifactId: String(wire.artifactId),
+    fileName: String(wire.fileName),
+    mimeType: String(wire.mimeType),
+    sizeBytes: Number(wire.sizeBytes ?? 0),
+    downloadUrl: wire.downloadUrl ?? null,
+    artifactType: wire.artifactType ?? null,
+    platform: wire.platform ?? null,
+    metadata: isRecord2(wire.metadata) ? wire.metadata : null,
+    isPrimary: Boolean(wire.isPrimary ?? false),
+    description: String(wire.description ?? "")
+  };
+}
+function parseArtifactDownload(wire) {
+  return {
+    downloadUrl: String(wire.downloadUrl),
+    fileName: String(wire.fileName),
+    sizeBytes: Number(wire.sizeBytes ?? 0),
+    mimeType: String(wire.mimeType),
+    expiresAt: toDate(wire.expiresAt)
+  };
+}
 function parseGoalEvent(wire) {
   return {
     type: wire.type,
@@ -774,6 +808,27 @@ function parseWorkflowSearchPage(wire) {
     cursor: wire.cursor ?? null
   };
 }
+function parseCatalogWorkflow(wire) {
+  return {
+    workflowId: String(wire.workflowId),
+    name: String(wire.name),
+    description: String(wire.description ?? ""),
+    icon: wire.icon ?? null,
+    supportedInputTypes: Array.isArray(wire.supportedInputTypes) ? wire.supportedInputTypes.map(String) : [],
+    supportedInputFormats: Array.isArray(wire.supportedInputFormats) ? wire.supportedInputFormats.map(String) : null,
+    category: String(wire.category ?? "goal_lane"),
+    requiredSlotCount: Number(wire.requiredSlotCount ?? 0),
+    subcategory: wire.subcategory ?? null,
+    skuGroup: wire.skuGroup ?? null,
+    status: String(wire.status ?? "active"),
+    supportedLocales: Array.isArray(wire.supportedLocales) ? wire.supportedLocales.map(String) : null,
+    maxInputSizeBytes: wire.maxInputSizeBytes ?? null,
+    minFileCount: wire.minFileCount ?? null,
+    tier: wire.tier ?? null,
+    // Tri-state: only an explicit false blocks a Free-tier run; absent stays null.
+    freeTierAllowed: wire.freeTierAllowed ?? null
+  };
+}
 function parseLikeResponse(wire) {
   return {
     liked: Boolean(wire.liked),
@@ -859,6 +914,52 @@ var Account = class {
   }
 };
 
+// src/internal/download.ts
+var MAX_DOWNLOAD_BYTES = 2 * 1024 ** 3;
+async function downloadUrlToPath(http, url, to, maxBytes = MAX_DOWNLOAD_BYTES) {
+  const { lstat, open, unlink } = await import('fs/promises');
+  const st = await lstat(to).catch(() => null);
+  if (st?.isSymbolicLink()) {
+    throw new Error(
+      `Refusing to write to ${JSON.stringify(to)}: target is a symlink. Remove it or choose a non-symlink destination.`
+    );
+  }
+  const response = await http.externalGet(url);
+  const body = response.body;
+  const handle = await open(to, "w");
+  let written = 0;
+  try {
+    if (body == null) {
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      written = bytes.byteLength;
+      if (written > maxBytes) {
+        throw new Error(`Download exceeds the ${maxBytes}-byte cap`);
+      }
+      await handle.write(bytes);
+    } else {
+      const reader = body.getReader();
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        written += value.byteLength;
+        if (written > maxBytes) {
+          await reader.cancel().catch(() => void 0);
+          throw new Error(`Download exceeds the ${maxBytes}-byte cap`);
+        }
+        await handle.write(value);
+      }
+    }
+  } catch (error) {
+    await handle.close().catch(() => void 0);
+    await unlink(to).catch(() => void 0);
+    throw error;
+  }
+  await handle.close();
+  return to;
+}
+
 // src/types.ts
 var CONVERT_JOB_TERMINAL_STATUSES = ["completed", "failed"];
 function isConvertJobTerminal(job) {
@@ -994,17 +1095,7 @@ var Convert = class {
   /** Download the first result file to `to` (Node) and return that path. */
   async downloadTo(job, { to }) {
     const url = await this.downloadUrl(job);
-    const { lstat, writeFile } = await import('fs/promises');
-    const st = await lstat(to).catch(() => null);
-    if (st?.isSymbolicLink()) {
-      throw new Error(
-        `Refusing to write to ${JSON.stringify(to)}: target is a symlink. Remove it or choose a non-symlink destination.`
-      );
-    }
-    const response = await this.#http.externalGet(url);
-    const bytes = new Uint8Array(await response.arrayBuffer());
-    await writeFile(to, bytes);
-    return to;
+    return downloadUrlToPath(this.#http, url, to);
   }
   // ── private ────────────────────────────────────────────────────
   #resolveSource(options) {
@@ -1159,6 +1250,19 @@ var Files = class {
     const contentType = options.contentType ?? guessContentType(filename);
     return this.#uploadWithBody(bytes, filename, contentType);
   }
+  /**
+   * Delete an uploaded file's cloud copy (storage object + metadata record).
+   *
+   * Only the uploader can delete; a missing or unowned `fileId` surfaces as
+   * a 404 `APIError` and a file attached to a still-running job as a 409
+   * (`FILE_IN_USE`). The platform deletes input files automatically ~1 hour
+   * after upload anyway — call this when you want the cloud copy gone
+   * deterministically the moment your workflow is done (e.g. privacy-
+   * sensitive documents on an edge device). Port of Python `files.delete`.
+   */
+  async delete(fileId) {
+    await this.#http.request("DELETE", `/api/v1/files/${fileId}`);
+  }
   async #uploadWithBody(body, filename, contentType) {
     const size = body.byteLength;
     const presign = await this.#presign(filename, size, contentType);
@@ -1359,7 +1463,8 @@ var Goals = class {
     return this.#waitLoop(
       jobSpecId,
       options.timeout ?? DEFAULT_POLL_TIMEOUT2,
-      options.pollInterval ?? DEFAULT_POLL_INTERVAL2
+      options.pollInterval ?? DEFAULT_POLL_INTERVAL2,
+      options.idleTimeout ?? null
     );
   }
   /** Shortcut: {@link start} then {@link wait}. */
@@ -1367,7 +1472,8 @@ var Goals = class {
     const job = await this.start(options);
     return this.wait(job.jobSpecId, {
       timeout: options.timeout,
-      pollInterval: options.pollInterval
+      pollInterval: options.pollInterval,
+      idleTimeout: options.idleTimeout
     });
   }
   /** Answer a single slot the agent is waiting on (sugar over {@link fillSlots}). */
@@ -1397,9 +1503,17 @@ var Goals = class {
     });
     return parseGoalJob(await response.json());
   }
-  /** Confirm a slots-filled job, queueing it for execution. */
+  /**
+   * Confirm a slots-filled job, queueing it for execution.
+   *
+   * `expectedVersion` is optional — the server re-reads the current version
+   * at submit time regardless, so most callers should simply omit it. The
+   * request always carries a JSON object (`{}` when empty): older backend
+   * builds declare the confirm body as a required parameter and reject a
+   * body-less POST with 422 before the handler runs.
+   */
   async confirm(jobSpecId, options = {}) {
-    const json = options.expectedVersion != null ? { expectedVersion: options.expectedVersion } : void 0;
+    const json = options.expectedVersion != null ? { expectedVersion: options.expectedVersion } : {};
     await this.#http.request("POST", `/api/v1/jobs/goal/${jobSpecId}/confirm`, { json });
     return this.#pollOnce(jobSpecId);
   }
@@ -1417,6 +1531,41 @@ var Goals = class {
     await this.#http.request("POST", `/api/v1/jobs/goal/${jobSpecId}/retry`, { json: body });
     return this.#pollOnce(jobSpecId);
   }
+  /**
+   * List a completed job's output artifacts with fresh download URLs.
+   *
+   * Available once the job is terminal-successful (`completed` or `partial`);
+   * any other status surfaces the backend's 400 as an `APIError`. Each
+   * artifact's `downloadUrl` is presigned and valid for one hour — re-call
+   * this method for fresh URLs rather than persisting one.
+   */
+  async artifacts(jobSpecId) {
+    const response = await this.#http.request("GET", `/api/v1/jobs/goal/${jobSpecId}/artifacts`);
+    const payload = await response.json();
+    const rows = Array.isArray(payload.artifacts) ? payload.artifacts : [];
+    return rows.map((row) => parseArtifact(row));
+  }
+  /**
+   * Mint a fresh presigned download URL for one artifact. Prefer this over
+   * reusing a stale {@link Artifact.downloadUrl} when more than an hour may
+   * have passed since {@link artifacts}.
+   */
+  async downloadArtifactUrl(jobSpecId, artifactId) {
+    const response = await this.#http.request(
+      "GET",
+      `/api/v1/jobs/goal/${jobSpecId}/artifacts/${artifactId}/download`
+    );
+    return parseArtifactDownload(await response.json());
+  }
+  /**
+   * Download one artifact to `to` (Node) and return that path. Mints a fresh
+   * presigned URL first, then streams the body to disk (shares the size-cap
+   * and symlink-refusal contract with `convert.downloadTo`).
+   */
+  async downloadArtifactTo(jobSpecId, artifactId, { to }) {
+    const info = await this.downloadArtifactUrl(jobSpecId, artifactId);
+    return downloadUrlToPath(this.#http, info.downloadUrl, to);
+  }
   /**
    * Stream goal execution events for a job. Opens a WebSocket, subscribes,
    * then yields each {@link GoalEvent} in order; the iterator ends (and the
@@ -1471,11 +1620,13 @@ var Goals = class {
     const response = await this.#http.request("GET", `/api/v1/jobs/goal/${jobSpecId}`);
     return parseGoalJob(await response.json());
   }
-  async #waitLoop(jobSpecId, timeout, initialInterval) {
+  async #waitLoop(jobSpecId, timeout, initialInterval, idleTimeout) {
     const start = this.#now() / 1e3;
     let interval = initialInterval;
     let staleCount = 0;
     let lastProgress = -1;
+    let lastStatus = null;
+    let lastChange = start;
     for (; ; ) {
       const job = await this.#pollOnce(jobSpecId);
       if (isGoalJobTerminal(job)) {
@@ -1484,6 +1635,10 @@ var Goals = class {
       if (goalJobNeedsInput(job)) {
         return job;
       }
+      if (job.status !== lastStatus) {
+        lastStatus = job.status;
+        lastChange = this.#now() / 1e3;
+      }
       if (job.progress === lastProgress) {
         staleCount += 1;
         if (staleCount >= STALE_PROGRESS_BACKOFF_AFTER2) {
@@ -1492,12 +1647,17 @@ var Goals = class {
         }
       } else {
         lastProgress = job.progress;
+        lastChange = this.#now() / 1e3;
         staleCount = 0;
       }
-      const elapsed = this.#now() / 1e3 - start;
+      const now = this.#now() / 1e3;
+      const elapsed = now - start;
       if (elapsed + interval > timeout) {
         throw new GoalJobTimeoutError({ jobSpecId, elapsed, timeout });
       }
+      if (idleTimeout != null && now - lastChange + interval > idleTimeout) {
+        throw new GoalJobTimeoutError({ jobSpecId, elapsed, timeout: idleTimeout, reason: "idle" });
+      }
       await this.#sleep(interval);
     }
   }
@@ -1545,6 +1705,20 @@ var Workflows = class {
   constructor(http) {
     this.#http = http;
   }
+  /**
+   * List the platform's built-in AI-workflow catalog.
+   *
+   * Distinct from {@link search}, which browses the user-published community
+   * marketplace — the catalog is the curated set of built-in workflows
+   * runnable directly via `goals.start({ workflowId })`. Anonymous callers
+   * are allowed; deprecated entries are filtered out server-side.
+   */
+  async catalog() {
+    const response = await this.#http.request("GET", "/api/v1/workflows/catalog");
+    const payload = await response.json();
+    const rows = Array.isArray(payload.workflows) ? payload.workflows : [];
+    return rows.map((row) => parseCatalogWorkflow(row));
+  }
   /** Browse the public community listing (one page + a `cursor`). */
   async search(options = {}) {
     const params = {
@@ -1615,6 +1789,9 @@ var Convilyn = class {
   #http;
   constructor(options = {}) {
     const auth = options.auth ?? resolveAuth(options.apiKey);
+    if (options.timeout !== void 0 && options.timeout <= 0) {
+      throw new TypeError(`timeout must be a positive number of seconds (got ${options.timeout})`);
+    }
     this.#http = new HttpClient({
       auth,
       baseUrl: options.baseUrl,
@@ -1646,7 +1823,10 @@ function resolveRetryPolicy(maxRetries, retryPolicy) {
   if (maxRetries == null) {
     return new ExponentialBackoffRetry();
   }
-  if (maxRetries <= 0) {
+  if (maxRetries < 0) {
+    throw new TypeError(`maxRetries must be >= 0 (got ${maxRetries})`);
+  }
+  if (maxRetries === 0) {
     return new NoRetry();
   }
   return new ExponentialBackoffRetry({ maxAttempts: maxRetries });