@convilyn/sdk 0.2.0

package/dist/chunk-UJHZKIP6.js

@@ -0,0 +1,1650 @@
+// src/errors.ts
+var ConvilynError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConvilynError";
+  }
+};
+var AuthError = class extends ConvilynError {
+  constructor(message) {
+    super(message);
+    this.name = "AuthError";
+  }
+};
+var APIError = class extends ConvilynError {
+  statusCode;
+  code;
+  details;
+  constructor(statusCode, code, message, details) {
+    super(message);
+    this.name = "APIError";
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details ?? {};
+  }
+};
+var RateLimitError = class extends APIError {
+  constructor(statusCode, code, message, details) {
+    super(statusCode, code, message, details);
+    this.name = "RateLimitError";
+  }
+};
+var PlanRequiredError = class extends APIError {
+  requiredPlan;
+  upgradeUrl;
+  constructor(statusCode, code, message, details, opts = {}) {
+    super(statusCode, code, message, details);
+    this.name = "PlanRequiredError";
+    this.requiredPlan = opts.requiredPlan ?? "pro";
+    this.upgradeUrl = opts.upgradeUrl ?? null;
+  }
+};
+var QuotaExceededError = class extends APIError {
+  costCredits;
+  balanceCredits;
+  topUpUrl;
+  constructor(statusCode, code, message, details, opts = {}) {
+    super(statusCode, code, message, details);
+    this.name = "QuotaExceededError";
+    this.costCredits = opts.costCredits ?? null;
+    this.balanceCredits = opts.balanceCredits ?? null;
+    this.topUpUrl = opts.topUpUrl ?? null;
+  }
+};
+var S3UploadError = class extends APIError {
+  constructor(statusCode, code, message, details) {
+    super(statusCode, code, message, details);
+    this.name = "S3UploadError";
+  }
+};
+var RetryExhaustedError = class extends APIError {
+  attemptCount;
+  constructor(statusCode, code, message, details, opts = {}) {
+    super(statusCode, code, message, details);
+    this.name = "RetryExhaustedError";
+    this.attemptCount = opts.attemptCount ?? 0;
+  }
+};
+var JobFailedError = class extends ConvilynError {
+  jobId;
+  processorType;
+  code;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "JobFailedError";
+    this.jobId = opts.jobId;
+    this.processorType = opts.processorType;
+    this.code = opts.code;
+  }
+};
+var JobTimeoutError = class extends ConvilynError {
+  jobId;
+  elapsed;
+  timeout;
+  constructor(opts) {
+    super(
+      `Job ${opts.jobId} did not reach a terminal status within ${opts.timeout}s (elapsed ${opts.elapsed.toFixed(1)}s)`
+    );
+    this.name = "JobTimeoutError";
+    this.jobId = opts.jobId;
+    this.elapsed = opts.elapsed;
+    this.timeout = opts.timeout;
+  }
+};
+var GoalJobFailedError = class extends ConvilynError {
+  jobSpecId;
+  code;
+  constructor(opts) {
+    super(opts.message ?? "Job failed without a structured error message");
+    this.name = "GoalJobFailedError";
+    this.jobSpecId = opts.jobSpecId;
+    this.code = opts.code ?? "GOAL_JOB_FAILED";
+  }
+};
+var GoalJobTimeoutError = class extends ConvilynError {
+  jobSpecId;
+  elapsed;
+  timeout;
+  constructor(opts) {
+    super(
+      `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;
+  }
+};
+var WebSocketError = class extends ConvilynError {
+  payload;
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "WebSocketError";
+    this.payload = opts.payload ?? null;
+  }
+};
+
+// src/types.ts
+var CONVERT_JOB_TERMINAL_STATUSES = ["completed", "failed"];
+function isConvertJobTerminal(job) {
+  return CONVERT_JOB_TERMINAL_STATUSES.includes(job.status);
+}
+var GOAL_JOB_TERMINAL_STATUSES = [
+  "completed",
+  "partial",
+  "failed",
+  "cancelled"
+];
+function isGoalJobTerminal(job) {
+  return GOAL_JOB_TERMINAL_STATUSES.includes(job.status);
+}
+function goalJobNeedsInput(job) {
+  return job.status === "slots_pending";
+}
+var GOAL_EVENT_TYPES = [
+  "tool_started",
+  "tool_finished",
+  "agent_step_started",
+  "agent_step_finished",
+  "orchestration_transition",
+  "status",
+  "progress",
+  "completed",
+  "failed",
+  "slot_needed",
+  "keepalive",
+  "agent_text",
+  "agent_text_done"
+];
+function isGoalEventType(value) {
+  return GOAL_EVENT_TYPES.includes(value);
+}
+var GOAL_EVENT_TERMINAL_TYPES = ["completed", "failed", "cancelled"];
+function isGoalEventTerminal(event) {
+  return GOAL_EVENT_TERMINAL_TYPES.includes(event.type);
+}
+
+// src/retry.ts
+var MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var DEFAULT_RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+  408,
+  429,
+  500,
+  502,
+  503,
+  504
+]);
+function parseRetryAfter(response) {
+  const raw = response.headers.get("Retry-After") ?? response.headers.get("retry-after");
+  if (raw == null) {
+    return null;
+  }
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    return null;
+  }
+  const seconds = Number(trimmed);
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    return null;
+  }
+  return seconds;
+}
+function generateIdempotencyKey() {
+  return crypto.randomUUID();
+}
+var ExponentialBackoffRetry = class {
+  maxAttempts;
+  baseDelay;
+  maxDelay;
+  jitter;
+  retryableStatuses;
+  #rng;
+  constructor(options = {}) {
+    this.maxAttempts = options.maxAttempts ?? 5;
+    this.baseDelay = options.baseDelay ?? 0.2;
+    this.maxDelay = options.maxDelay ?? 30;
+    this.jitter = options.jitter ?? 0.25;
+    this.retryableStatuses = options.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES;
+    this.#rng = options.rng ?? Math.random;
+  }
+  shouldRetry(response, error, attempt) {
+    if (attempt >= this.maxAttempts) {
+      return false;
+    }
+    if (error != null) {
+      return false;
+    }
+    if (response == null) {
+      return false;
+    }
+    return this.retryableStatuses.has(response.status);
+  }
+  nextDelay(response, attempt) {
+    const retryAfter = response ? parseRetryAfter(response) : null;
+    if (retryAfter != null) {
+      return Math.min(retryAfter, this.maxDelay);
+    }
+    const capped = Math.min(this.baseDelay * 2 ** attempt, this.maxDelay);
+    const spread = capped * this.jitter;
+    const jittered = capped + (-spread + this.#rng() * (2 * spread));
+    return Math.max(0, jittered);
+  }
+};
+var NoRetry = class {
+  shouldRetry() {
+    return false;
+  }
+  nextDelay() {
+    return 0;
+  }
+};
+
+// src/throttle.ts
+var SOFT_LIMIT_HEADER = "X-Quota-State";
+var SOFT_LIMIT_VALUE = "soft_limit";
+var DEFAULT_MAX_RETRIES = 1;
+var DEFAULT_MAX_SLEEP_SECONDS = 60;
+var DEFAULT_FALLBACK_SLEEP_SECONDS = 5;
+var AutoThrottleConfig = class {
+  maxRetries;
+  maxSleep;
+  fallbackSleep;
+  constructor(options = {}) {
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.maxSleep = options.maxSleep ?? DEFAULT_MAX_SLEEP_SECONDS;
+    this.fallbackSleep = options.fallbackSleep ?? DEFAULT_FALLBACK_SLEEP_SECONDS;
+    if (this.maxRetries < 0) {
+      throw new RangeError("autoThrottle.maxRetries must be >= 0");
+    }
+    if (this.maxSleep <= 0) {
+      throw new RangeError("autoThrottle.maxSleep must be > 0");
+    }
+    if (this.fallbackSleep < 0) {
+      throw new RangeError("autoThrottle.fallbackSleep must be >= 0");
+    }
+  }
+};
+function resolveAutoThrottle(value) {
+  if (value == null || value === false) {
+    return null;
+  }
+  if (value === true) {
+    return new AutoThrottleConfig();
+  }
+  return value;
+}
+function computeQuotaSleep(error, config) {
+  const details = error.details ?? {};
+  let sleepS = sleepFromRetryAfter(details);
+  if (sleepS == null) {
+    sleepS = sleepFromResetAt(details);
+  }
+  if (sleepS == null) {
+    sleepS = config.fallbackSleep;
+  }
+  if (sleepS > config.maxSleep) {
+    return null;
+  }
+  return Math.max(0, sleepS);
+}
+function sleepFromRetryAfter(details) {
+  const raw = details.retry_after_seconds;
+  if (raw == null) {
+    return null;
+  }
+  const seconds = typeof raw === "number" ? raw : Number(raw);
+  return Number.isFinite(seconds) ? seconds : null;
+}
+function sleepFromResetAt(details) {
+  const raw = details.reset_at;
+  if (typeof raw !== "string") {
+    return null;
+  }
+  const resetMs = Date.parse(raw);
+  if (Number.isNaN(resetMs)) {
+    return null;
+  }
+  return (resetMs - Date.now()) / 1e3;
+}
+function responseHasSoftLimitHeader(headers) {
+  const raw = headers.get(SOFT_LIMIT_HEADER);
+  if (!raw) {
+    return false;
+  }
+  return raw.trim().toLowerCase() === SOFT_LIMIT_VALUE;
+}
+function emitSoftLimitWarning(opts) {
+  let message = `Convilyn quota soft_limit reached (source=${opts.source})`;
+  if (opts.details) {
+    message = `${message}: ${opts.details}`;
+  }
+  if (typeof process !== "undefined" && typeof process.emitWarning === "function") {
+    process.emitWarning(message);
+  }
+}
+
+// src/version.ts
+var VERSION = "0.2.0";
+
+// src/internal/auth.ts
+var ENV_API_KEY = "CONVILYN_API_KEY";
+var CONSUMER_KEY_PREFIX = "ck_";
+var AUTHOR_KEY_PREFIXES = ["cvl_", "cvi_"];
+function isAuthorKey(key) {
+  return AUTHOR_KEY_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+function maskKey(key) {
+  if (key.length <= 8) {
+    return "***";
+  }
+  return `${key.slice(0, 4)}\u2026${key.slice(-2)}`;
+}
+var ApiKey = class {
+  #key;
+  constructor(key) {
+    if (!key || !key.trim()) {
+      throw new AuthError("API key must be a non-empty string");
+    }
+    if (isAuthorKey(key)) {
+      throw new AuthError(
+        `${maskKey(key)} looks like a Convilyn Author SDK / deploy token, not a consumer API key. The consumer SDK authenticates with a "${CONSUMER_KEY_PREFIX}" key \u2014 mint one under Settings \u2192 API. (Author tokens publish workflows / tools; they do not call the data-plane API.)`
+      );
+    }
+    this.#key = key;
+  }
+  headers() {
+    return { Authorization: `Bearer ${this.#key}` };
+  }
+  bearerToken() {
+    return this.#key;
+  }
+  /** Masked so the raw key never leaks via string interpolation. */
+  toString() {
+    return `ApiKey(${maskKey(this.#key)})`;
+  }
+  /** Node's `util.inspect` hook so `console.log(apiKey)` is masked too. */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+};
+function resolveAuth(apiKey, options = {}) {
+  const env = options.env ?? (typeof process !== "undefined" ? process.env : {});
+  const resolved = apiKey ?? env[ENV_API_KEY];
+  if (!resolved || !resolved.trim()) {
+    throw new AuthError(
+      `No API key provided. Pass { apiKey } or set the ${ENV_API_KEY} environment variable.`
+    );
+  }
+  return new ApiKey(resolved);
+}
+
+// src/internal/http.ts
+var DEFAULT_BASE_URL = "https://api.convilyn.corenovus.com";
+var DEFAULT_TIMEOUT = 30;
+function requireHttps(url) {
+  let scheme;
+  try {
+    scheme = new URL(url).protocol.replace(/:$/, "").toLowerCase();
+  } catch {
+    scheme = "";
+  }
+  if (scheme !== "https") {
+    throw new Error(
+      `Refusing to dial non-https URL (scheme=${JSON.stringify(scheme)}). The Convilyn SDK only follows https presigned URLs.`
+    );
+  }
+}
+var PLAN_REQUIRED_CODES = /* @__PURE__ */ new Set([
+  "TIER_REQUIRED",
+  "PRO_TIER_REQUIRED",
+  "BUSINESS_TIER_REQUIRED",
+  "ENTERPRISE_TIER_REQUIRED"
+]);
+var realSleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+var HttpClient = class {
+  #auth;
+  #baseUrl;
+  #timeout;
+  #userAgent;
+  #retryPolicy;
+  #idempotencyEnabled;
+  #autoThrottle;
+  #fetch;
+  #sleep;
+  constructor(options) {
+    this.#auth = options.auth;
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.#userAgent = options.userAgent ?? `convilyn-js/${VERSION}`;
+    this.#retryPolicy = options.retryPolicy ?? new ExponentialBackoffRetry();
+    this.#idempotencyEnabled = options.idempotencyEnabled ?? true;
+    this.#autoThrottle = options.autoThrottle ?? null;
+    if (options.fetch) {
+      this.#fetch = options.fetch;
+    } else if (typeof fetch !== "undefined") {
+      this.#fetch = (url, init) => fetch(url, init);
+    } else {
+      throw new Error("No global fetch available; pass options.fetch (Node 18+ or a polyfill)");
+    }
+    this.#sleep = options.sleep ?? realSleep;
+  }
+  get baseUrl() {
+    return this.#baseUrl;
+  }
+  /** Read-only handle to the auth strategy (used by the WS transport). */
+  get auth() {
+    return this.#auth;
+  }
+  /**
+   * Issue a request, applying the retry policy on transient failures and
+   * raising a typed error on a non-2xx final response.
+   */
+  async request(method, path, options = {}) {
+    const response = await this.#requestWithQuotaThrottle(
+      method,
+      path,
+      options,
+      this.#autoThrottle ? this.#autoThrottle.maxRetries : 0
+    );
+    maybeEmitSoftLimit(response);
+    return response;
+  }
+  /**
+   * Like {@link request} but never raises on HTTP status — returns the final
+   * response so callers (the `convilyn api` CLI escape hatch) can inspect it.
+   */
+  async rawRequest(method, path, options = {}) {
+    const { response } = await this.#doRequestWithRetry(method, path, options);
+    maybeEmitSoftLimit(response);
+    return response;
+  }
+  /**
+   * Run {@link #doRequestWithRetry}, re-issuing on a 402 {@link QuotaExceededError}
+   * up to `quotaAttemptsRemaining` times, sleeping {@link computeQuotaSleep}
+   * between attempts. Transport-level retries (5xx / 429 / 408) are handled
+   * inside `#doRequestWithRetry`; this shim targets the 402 quota envelope only.
+   */
+  async #requestWithQuotaThrottle(method, path, options, quotaAttemptsRemaining) {
+    const { response, attempts } = await this.#doRequestWithRetry(method, path, options);
+    if (response.status < 400) {
+      return response;
+    }
+    const decoded = attempts > 1 ? await toRetryExhausted(response, attempts) : await decodeError(response);
+    if (this.#autoThrottle != null && quotaAttemptsRemaining > 0 && decoded instanceof QuotaExceededError) {
+      const sleepSeconds = computeQuotaSleep(decoded, this.#autoThrottle);
+      if (sleepSeconds != null) {
+        await this.#sleep(sleepSeconds);
+        return this.#requestWithQuotaThrottle(method, path, options, quotaAttemptsRemaining - 1);
+      }
+    }
+    throw decoded;
+  }
+  async #doRequestWithRetry(method, path, options) {
+    const headers = this.#defaultHeaders();
+    if (options.headers) {
+      Object.assign(headers, options.headers);
+    }
+    this.#applyIdempotencyKey(method.toUpperCase(), headers);
+    let attempt = 0;
+    for (; ; ) {
+      const response = await this.#fetchOnce(method, path, headers, options);
+      if (response.status < 400) {
+        return { response, attempts: attempt + 1 };
+      }
+      const view = { status: response.status, headers: response.headers };
+      if (this.#retryPolicy.shouldRetry(view, null, attempt)) {
+        await this.#sleep(this.#retryPolicy.nextDelay(view, attempt));
+        attempt += 1;
+        continue;
+      }
+      return { response, attempts: attempt + 1 };
+    }
+  }
+  #defaultHeaders() {
+    return {
+      "User-Agent": this.#userAgent,
+      Accept: "application/json",
+      ...this.#auth.headers()
+    };
+  }
+  #applyIdempotencyKey(method, headers) {
+    if (!this.#idempotencyEnabled) {
+      return;
+    }
+    if (!MUTATING_METHODS.has(method)) {
+      return;
+    }
+    if ("Idempotency-Key" in headers) {
+      return;
+    }
+    headers["Idempotency-Key"] = generateIdempotencyKey();
+  }
+  async #fetchOnce(method, path, headers, options) {
+    const url = this.#buildUrl(path, options.params);
+    if (options.json !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const init = { method, headers };
+    if (options.json !== void 0) {
+      init.body = JSON.stringify(options.json);
+    } else if (options.content !== void 0) {
+      init.body = options.content;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.#timeout * 1e3);
+    init.signal = controller.signal;
+    try {
+      return await this.#fetch(url, init);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  #buildUrl(path, params) {
+    const absolute = /^https?:\/\//i.test(path);
+    const full = absolute ? path : `${this.#baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+    if (!params) {
+      return full;
+    }
+    const url = new URL(full);
+    for (const [key, value] of Object.entries(params)) {
+      if (value == null) {
+        continue;
+      }
+      url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+  /**
+   * PUT to an external absolute URL (e.g. a presigned upload URL). Sends NO
+   * Convilyn auth (the URL carries its own signature) and is NOT retried.
+   */
+  async externalPut(url, { content, headers }) {
+    requireHttps(url);
+    const response = await this.#fetch(url, {
+      method: "PUT",
+      body: content,
+      headers: headers ?? {}
+    });
+    if (response.status >= 400) {
+      throw new S3UploadError(
+        response.status,
+        `S3_HTTP_${response.status}`,
+        response.statusText || "External upload failed",
+        { url }
+      );
+    }
+    return response;
+  }
+  /** GET an external absolute URL (e.g. a presigned download). No auth. */
+  async externalGet(url, { headers } = {}) {
+    requireHttps(url);
+    const response = await this.#fetch(url, { method: "GET", headers: headers ?? {} });
+    if (response.status >= 400) {
+      throw new APIError(
+        response.status,
+        `DOWNLOAD_HTTP_${response.status}`,
+        response.statusText || "External download failed",
+        { url }
+      );
+    }
+    return response;
+  }
+  /** No persistent connection pool with `fetch`; provided for API symmetry. */
+  async close() {
+  }
+};
+function maybeEmitSoftLimit(response) {
+  if (responseHasSoftLimitHeader(response.headers)) {
+    emitSoftLimitWarning({ source: response.url || "request" });
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function coerceNumber(value) {
+  if (value == null) {
+    return null;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+async function readJson(response) {
+  try {
+    const payload = await response.json();
+    return isRecord(payload) ? payload : {};
+  } catch {
+    return {};
+  }
+}
+function flattenErrorEnvelope(payload) {
+  for (const key of ["detail", "error"]) {
+    const nested = payload[key];
+    if (isRecord(nested)) {
+      return nested;
+    }
+  }
+  return payload;
+}
+async function decodeError(response) {
+  const status = response.status;
+  const inner = flattenErrorEnvelope(await readJson(response));
+  const code = asString(inner.code) ?? `HTTP_${status}`;
+  const message = asString(inner.message) ?? (response.statusText || "Request failed");
+  const details = isRecord(inner.details) ? inner.details : void 0;
+  if (status === 429) {
+    return new RateLimitError(status, code, message, details);
+  }
+  if (status === 402) {
+    const upgradeUrl = asString(inner.upgrade_url ?? inner.upgradeUrl ?? inner.topUp ?? inner.top_up) ?? null;
+    if (PLAN_REQUIRED_CODES.has(code)) {
+      return new PlanRequiredError(status, code, message, details, { upgradeUrl });
+    }
+    if (code === "insufficient_balance" || code === "QUOTA_EXCEEDED") {
+      return new QuotaExceededError(status, code, message, details, {
+        costCredits: coerceNumber(inner.costCredits ?? inner.cost_credits),
+        balanceCredits: coerceNumber(inner.balanceCredits ?? inner.balance_credits),
+        topUpUrl: upgradeUrl
+      });
+    }
+  }
+  return new APIError(status, code, message, details);
+}
+async function toRetryExhausted(response, attemptCount) {
+  const status = response.status;
+  const payload = await readJson(response);
+  const code = asString(payload.code) ?? `HTTP_${status}`;
+  const message = asString(payload.message) ?? (response.statusText || "Request failed");
+  const details = isRecord(payload.details) ? payload.details : void 0;
+  return new RetryExhaustedError(status, code, message, details, { attemptCount });
+}
+
+// src/internal/parsers.ts
+var MICRO_U_PER_CREDIT = 1e4;
+function microUToCredits(value) {
+  return Number(value ?? 0) / MICRO_U_PER_CREDIT;
+}
+function toDate(value) {
+  return new Date(value);
+}
+function toDateOrNull(value) {
+  return value == null ? null : toDate(value);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseFile(wire) {
+  return {
+    fileId: String(wire.fileId),
+    filename: String(wire.fileName),
+    size: Number(wire.fileSize),
+    contentType: String(wire.mimeType),
+    createdAt: toDate(wire.createdAt),
+    jobId: wire.jobId ?? null,
+    isInput: wire.isInput == null ? true : Boolean(wire.isInput)
+  };
+}
+function parseResultFile(wire) {
+  return {
+    filename: String(wire.filename),
+    size: Number(wire.size),
+    mimetype: String(wire.mimetype),
+    url: String(wire.url)
+  };
+}
+function parseJobError(wire) {
+  return { code: String(wire.code), message: String(wire.message) };
+}
+function parseConvertJob(wire) {
+  const resultFiles = wire.resultFiles;
+  const error = wire.error;
+  return {
+    jobId: String(wire.jobId),
+    status: wire.status,
+    processorType: String(wire.processorType),
+    progress: Number(wire.progress ?? 0),
+    progressMessage: wire.progressMessage ?? null,
+    resultFiles: Array.isArray(resultFiles) ? resultFiles.map((row) => parseResultFile(row)) : null,
+    error: error != null ? parseJobError(error) : null,
+    retryCount: Number(wire.retryCount ?? 0),
+    createdAt: toDate(wire.createdAt),
+    updatedAt: toDate(wire.updatedAt),
+    startedAt: toDateOrNull(wire.startedAt),
+    completedAt: toDateOrNull(wire.completedAt),
+    estimatedDuration: wire.estimatedDuration ?? null
+  };
+}
+function parsePendingSlot(wire) {
+  return {
+    slotId: String(wire.slotId),
+    slotType: String(wire.slotType),
+    question: String(wire.question),
+    options: Array.isArray(wire.options) ? wire.options : null,
+    required: wire.required == null ? true : Boolean(wire.required),
+    isDisambiguation: Boolean(wire.isDisambiguation ?? false),
+    suggestedValue: wire.suggestedValue ?? null,
+    suggestedConfidence: wire.suggestedConfidence ?? null
+  };
+}
+function parseGoalJob(wire) {
+  return {
+    jobSpecId: String(wire.jobSpecId),
+    status: wire.status,
+    progress: Number(wire.progress ?? 0),
+    itemVersion: wire.itemVersion ?? null,
+    attemptId: wire.attemptId ?? null,
+    goalText: wire.goalText ?? null,
+    fileIds: Array.isArray(wire.fileIds) ? wire.fileIds.map(String) : [],
+    pendingSlots: Array.isArray(wire.pendingSlots) ? wire.pendingSlots.map((slot) => parsePendingSlot(slot)) : [],
+    filledSlots: isRecord2(wire.filledSlots) ? wire.filledSlots : {},
+    pendingInterrupts: Array.isArray(wire.pendingInterrupts) ? wire.pendingInterrupts : [],
+    agentMessage: wire.agentMessage ?? null,
+    errorMessage: wire.errorMessage ?? null,
+    errorCode: wire.errorCode ?? null,
+    createdAt: toDate(wire.createdAt),
+    updatedAt: toDate(wire.updatedAt),
+    startedAt: toDateOrNull(wire.startedAt),
+    completedAt: toDateOrNull(wire.completedAt)
+  };
+}
+function parseGoalEvent(wire) {
+  return {
+    type: wire.type,
+    schemaVersion: Number(wire.schemaVersion ?? 0),
+    jobSpecId: String(wire.jobSpecId),
+    emittedAt: toDate(wire.emittedAt),
+    seq: Number(wire.seq ?? 0),
+    data: isRecord2(wire.data) ? wire.data : {}
+  };
+}
+function parseWorkflowStats(wire) {
+  const stats = isRecord2(wire) ? wire : {};
+  return {
+    runCount: Number(stats.runCount ?? 0),
+    forkCount: Number(stats.forkCount ?? 0),
+    likeCount: Number(stats.likeCount ?? 0)
+  };
+}
+function parseWorkflow(wire) {
+  return {
+    workflowId: String(wire.workflowId),
+    ownerId: wire.ownerId ?? null,
+    specId: String(wire.specId),
+    sourceSpecId: wire.sourceSpecId ?? null,
+    sourceType: wire.sourceType ?? null,
+    name: String(wire.name),
+    description: wire.description ?? null,
+    visibility: wire.visibility,
+    tags: Array.isArray(wire.tags) ? wire.tags.map(String) : [],
+    stats: parseWorkflowStats(wire.stats),
+    itemVersion: Number(wire.itemVersion ?? 0)
+  };
+}
+function parseWorkflowSummary(wire) {
+  return {
+    workflowId: String(wire.workflowId),
+    specId: String(wire.specId),
+    ownerId: wire.ownerId ?? null,
+    name: String(wire.name),
+    description: wire.description ?? null,
+    visibility: wire.visibility,
+    tags: Array.isArray(wire.tags) ? wire.tags.map(String) : [],
+    stats: parseWorkflowStats(wire.stats)
+  };
+}
+function parseWorkflowSearchPage(wire) {
+  const items = wire.items;
+  return {
+    items: Array.isArray(items) ? items.map((row) => parseWorkflowSummary(row)) : [],
+    cursor: wire.cursor ?? null
+  };
+}
+function parseLikeResponse(wire) {
+  return {
+    liked: Boolean(wire.liked),
+    likeCount: Number(wire.likeCount ?? 0)
+  };
+}
+function parseToolCostEstimate(wire) {
+  return {
+    toolName: String(wire.toolName),
+    perInvocationCredits: microUToCredits(wire.perInvocationMicroU)
+  };
+}
+function parseQuotaCheck(wire) {
+  return {
+    state: wire.state,
+    tier: wire.tier,
+    estimatedCredits: microUToCredits(wire.estimatedMicroU),
+    thresholdCredits: microUToCredits(wire.thresholdMicroU),
+    upgradeUrl: wire.upgradeUrl ?? null
+  };
+}
+function parseCostEstimate(wire) {
+  const tools = wire.tools;
+  return {
+    estimatedCredits: microUToCredits(wire.estimatedMicroU),
+    estimatedUsd: Number(wire.estimatedUsd ?? 0),
+    estimatedTotalCredits: microUToCredits(wire.estimatedTotalMicroU),
+    estimatedMinCredits: microUToCredits(wire.estimatedMinMicroU),
+    estimatedMaxCredits: microUToCredits(wire.estimatedMaxMicroU),
+    tools: Array.isArray(tools) ? tools.map((row) => parseToolCostEstimate(row)) : [],
+    quotaCheck: parseQuotaCheck(isRecord2(wire.quotaCheck) ? wire.quotaCheck : {})
+  };
+}
+function planFromTier(tier) {
+  return { tier };
+}
+function parseUsageHistoryEntry(wire) {
+  return {
+    metric: String(wire.metric),
+    periodStart: toDate(wire.period_start ?? wire.periodStart),
+    periodEnd: toDate(wire.period_end ?? wire.periodEnd),
+    used: Number(wire.used ?? 0),
+    limit: wire.limit ?? null
+  };
+}
+
+// src/resources/account.ts
+var Account = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /** Estimate a workflow's cost (credits) + check the verdict against the plan. */
+  async getQuota(options = {}) {
+    const body = { toolNames: options.tools ?? [] };
+    if (options.maxIterations != null) {
+      body.maxIterations = options.maxIterations;
+    }
+    const response = await this.#http.request("POST", "/api/v1/workflows/cost-preview", {
+      json: body
+    });
+    return parseCostEstimate(await response.json());
+  }
+  /** Return the caller's current billing plan (derived from the cost-preview tier). */
+  async getPlan() {
+    const estimate = await this.getQuota({ tools: [], maxIterations: 1 });
+    return planFromTier(estimate.quotaCheck.tier);
+  }
+  /**
+   * List the caller's past usage periods (one row per metric+period). `since`
+   * filters client-side to entries whose `periodStart` is on or after it
+   * (the backend does not honour a query param today).
+   */
+  async usageHistory(options = {}) {
+    const response = await this.#http.request("GET", "/api/v1/payment/usage/history");
+    const rows = await response.json();
+    const entries = Array.isArray(rows) ? rows.map((row) => parseUsageHistoryEntry(row)) : [];
+    if (options.since == null) {
+      return entries;
+    }
+    const since = options.since;
+    return entries.filter((entry) => entry.periodStart >= since);
+  }
+};
+
+// src/resources/convert.ts
+var DEFAULT_POLL_INTERVAL = 1;
+var DEFAULT_POLL_TIMEOUT = 300;
+var MAX_POLL_INTERVAL = 5;
+var STALE_PROGRESS_BACKOFF_AFTER = 3;
+var BACKOFF_FACTOR = 1.5;
+var SOURCE_FORMAT_BY_SUFFIX = {
+  docx: "docx",
+  doc: "doc",
+  pdf: "pdf",
+  pptx: "pptx",
+  ppt: "ppt",
+  xlsx: "xlsx",
+  xls: "xls",
+  txt: "txt",
+  rtf: "rtf",
+  html: "html",
+  htm: "html",
+  md: "md",
+  odt: "odt"
+};
+function inferSourceFormat(filename) {
+  const dot = filename.lastIndexOf(".");
+  if (dot < 0) {
+    return null;
+  }
+  return SOURCE_FORMAT_BY_SUFFIX[filename.slice(dot + 1).toLowerCase()] ?? null;
+}
+var realSleep2 = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+var Convert = class {
+  #http;
+  #sleep;
+  #now;
+  constructor(http, options = {}) {
+    this.#http = http;
+    this.#sleep = options.sleep ?? realSleep2;
+    this.#now = options.now ?? (() => Date.now());
+  }
+  /** Create a conversion job and return immediately (queued/processing). */
+  async create(options) {
+    const { fileId, sourceFormat } = this.#resolveSource(options);
+    const params = {
+      source_file_id: fileId,
+      source_format: sourceFormat,
+      target_format: options.targetFormat,
+      quality: options.quality ?? "standard"
+    };
+    if (options.pageRange != null) {
+      params.page_range = options.pageRange;
+    }
+    const response = await this.#http.request("POST", "/api/v1/jobs", {
+      json: { processor_type: "document_conversion", params }
+    });
+    return parseConvertJob(await response.json());
+  }
+  /** Fetch the current state of a job (one-shot poll). */
+  async retrieve(jobId) {
+    return this.#pollOnce(jobId);
+  }
+  /**
+   * Poll until the job reaches a terminal status, the timeout expires, or the
+   * backend reports failure.
+   *
+   * @throws {@link JobFailedError} when the terminal status is `failed`.
+   * @throws {@link JobTimeoutError} when `timeout` elapses first.
+   */
+  async wait(jobId, options = {}) {
+    return this.#waitLoop(
+      jobId,
+      options.timeout ?? DEFAULT_POLL_TIMEOUT,
+      options.pollInterval ?? DEFAULT_POLL_INTERVAL
+    );
+  }
+  /** Shortcut: {@link create} then {@link wait}. */
+  async createAndWait(options) {
+    const job = await this.create(options);
+    return this.wait(job.jobId, { timeout: options.timeout, pollInterval: options.pollInterval });
+  }
+  /** Presigned download URL for the first result file. */
+  async downloadUrl(job) {
+    const resolved = await this.#ensureJob(job);
+    const first = resolved.resultFiles?.[0];
+    if (!first) {
+      throw new JobFailedError({
+        jobId: resolved.jobId,
+        processorType: resolved.processorType,
+        code: "NO_RESULT_FILES",
+        message: "Job is terminal but no result files were produced"
+      });
+    }
+    return first.url;
+  }
+  /** 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;
+  }
+  // ── private ────────────────────────────────────────────────────
+  #resolveSource(options) {
+    const { file, fileId, sourceFormat } = options;
+    if (file != null && fileId != null) {
+      throw new TypeError("create() accepts either `file` or `fileId`, not both");
+    }
+    if (file != null) {
+      const inferred = sourceFormat ?? inferSourceFormat(file.filename);
+      if (inferred == null) {
+        throw new Error(
+          `Could not infer sourceFormat from filename ${JSON.stringify(file.filename)}; pass sourceFormat explicitly`
+        );
+      }
+      return { fileId: file.fileId, sourceFormat: inferred };
+    }
+    if (fileId != null) {
+      if (sourceFormat == null) {
+        throw new Error("sourceFormat is required when only fileId is provided");
+      }
+      return { fileId, sourceFormat };
+    }
+    throw new TypeError("create() requires either `file` or `fileId`");
+  }
+  async #pollOnce(jobId) {
+    const response = await this.#http.request("GET", `/api/v1/jobs/${jobId}`);
+    return parseConvertJob(await response.json());
+  }
+  async #waitLoop(jobId, timeout, initialInterval) {
+    const start = this.#now() / 1e3;
+    let interval = initialInterval;
+    let staleCount = 0;
+    let lastProgress = -1;
+    for (; ; ) {
+      const job = await this.#pollOnce(jobId);
+      if (isConvertJobTerminal(job)) {
+        return this.#finalise(job);
+      }
+      if (job.progress === lastProgress) {
+        staleCount += 1;
+        if (staleCount >= STALE_PROGRESS_BACKOFF_AFTER) {
+          interval = Math.min(interval * BACKOFF_FACTOR, MAX_POLL_INTERVAL);
+          staleCount = 0;
+        }
+      } else {
+        lastProgress = job.progress;
+        staleCount = 0;
+      }
+      const elapsed = this.#now() / 1e3 - start;
+      if (elapsed + interval > timeout) {
+        throw new JobTimeoutError({ jobId, elapsed, timeout });
+      }
+      await this.#sleep(interval);
+    }
+  }
+  #finalise(job) {
+    if (job.status === "failed") {
+      const err = job.error;
+      throw new JobFailedError({
+        jobId: job.jobId,
+        processorType: job.processorType,
+        code: err ? err.code : "UNKNOWN",
+        message: err ? err.message : "Job failed without a structured error"
+      });
+    }
+    return job;
+  }
+  async #ensureJob(job) {
+    return typeof job === "string" ? this.#pollOnce(job) : job;
+  }
+};
+
+// src/resources/files.ts
+var DEFAULT_CONTENT_TYPE = "application/octet-stream";
+var MIME_BY_SUFFIX = {
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  txt: "text/plain",
+  csv: "text/csv",
+  html: "text/html",
+  htm: "text/html",
+  md: "text/markdown",
+  json: "application/json",
+  xml: "application/xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  mp4: "video/mp4",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  zip: "application/zip"
+};
+function basename(path) {
+  const parts = path.split(/[\\/]/);
+  return parts[parts.length - 1] || path;
+}
+function guessContentType(filename) {
+  const dot = filename.lastIndexOf(".");
+  if (dot < 0) {
+    return DEFAULT_CONTENT_TYPE;
+  }
+  const suffix = filename.slice(dot + 1).toLowerCase();
+  return MIME_BY_SUFFIX[suffix] ?? DEFAULT_CONTENT_TYPE;
+}
+function toBytes(content) {
+  if (typeof content === "string") {
+    return new TextEncoder().encode(content);
+  }
+  if (content instanceof ArrayBuffer) {
+    return new Uint8Array(content);
+  }
+  return content;
+}
+var Files = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * Upload a file and return its {@link File} record. Supply exactly one of
+   * `path` (Node) or `content` (bytes/string).
+   */
+  async upload(options) {
+    const { path, content } = options;
+    if (path == null && content == null) {
+      throw new TypeError("upload() requires either `path` or `content`");
+    }
+    if (path != null && content != null) {
+      throw new TypeError("upload() accepts either `path` or `content`, not both");
+    }
+    let bytes;
+    let filename = options.filename;
+    if (path != null) {
+      const { readFile } = await import('fs/promises');
+      const buffer = await readFile(path);
+      bytes = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+      filename ??= basename(path);
+    } else {
+      bytes = toBytes(content);
+    }
+    if (!filename) {
+      throw new Error("filename is required when uploading raw content");
+    }
+    const contentType = options.contentType ?? guessContentType(filename);
+    return this.#uploadWithBody(bytes, filename, contentType);
+  }
+  async #uploadWithBody(body, filename, contentType) {
+    const size = body.byteLength;
+    const presign = await this.#presign(filename, size, contentType);
+    await this.#http.externalPut(presign.uploadUrl, {
+      content: body,
+      headers: { "Content-Type": contentType }
+    });
+    const confirm = await this.#confirm(presign.fileId, filename, size, contentType, presign.s3Key);
+    return parseFile(confirm);
+  }
+  async #presign(filename, size, contentType) {
+    const response = await this.#http.request("POST", "/api/v1/upload/presign", {
+      json: { fileName: filename, fileSize: size, contentType }
+    });
+    const body = await response.json();
+    return {
+      uploadUrl: String(body.uploadUrl),
+      fileId: String(body.fileId),
+      s3Key: String(body.s3Key)
+    };
+  }
+  async #confirm(fileId, filename, size, contentType, s3Key) {
+    const response = await this.#http.request("POST", "/api/v1/upload/confirm", {
+      json: { fileId, fileName: filename, fileSize: size, contentType, s3Key }
+    });
+    return await response.json();
+  }
+};
+
+// src/internal/ws.ts
+var ENV_WS_URL = "CONVILYN_WS_URL";
+var WebSocketTransport = class {
+  #WebSocketImpl;
+  #ws = null;
+  #queue = [];
+  #waiters = [];
+  #ended = false;
+  #failure = null;
+  constructor(options = {}) {
+    const impl = options.WebSocketImpl ?? (typeof WebSocket !== "undefined" ? WebSocket : void 0);
+    if (!impl) {
+      throw new Error(
+        "No global WebSocket available; pass a WebSocket implementation (Node 22+ exposes one globally, or use the `ws` package)."
+      );
+    }
+    this.#WebSocketImpl = impl;
+  }
+  connect(url) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let socket;
+      try {
+        socket = new this.#WebSocketImpl(url);
+      } catch (err) {
+        reject(err);
+        return;
+      }
+      this.#ws = socket;
+      socket.addEventListener("open", () => {
+        settled = true;
+        resolve();
+      });
+      socket.addEventListener("message", (event) => this.#onMessage(event));
+      socket.addEventListener("error", () => {
+        const err = new Error("WebSocket connection error");
+        this.#failure = err;
+        this.#flushWaiters();
+        if (!settled) {
+          settled = true;
+          reject(err);
+        }
+      });
+      socket.addEventListener("close", () => {
+        this.#ended = true;
+        this.#flushWaiters();
+      });
+    });
+  }
+  send(payload) {
+    if (!this.#ws) {
+      return Promise.reject(new Error("WebSocketTransport.send called before connect"));
+    }
+    this.#ws.send(payload);
+    return Promise.resolve();
+  }
+  recv() {
+    const buffered = this.#queue.shift();
+    if (buffered !== void 0) {
+      return Promise.resolve(buffered);
+    }
+    if (this.#failure != null) {
+      return Promise.reject(this.#failure);
+    }
+    if (this.#ended) {
+      return Promise.reject(new Error("WebSocket closed"));
+    }
+    return new Promise((resolve, reject) => {
+      this.#waiters.push({ resolve, reject });
+    });
+  }
+  close() {
+    if (this.#ws) {
+      try {
+        this.#ws.close();
+      } catch {
+      }
+      this.#ws = null;
+    }
+    return Promise.resolve();
+  }
+  #onMessage(event) {
+    const data = typeof event.data === "string" ? event.data : event.data instanceof ArrayBuffer ? new TextDecoder().decode(event.data) : String(event.data);
+    const waiter = this.#waiters.shift();
+    if (waiter) {
+      waiter.resolve(data);
+    } else {
+      this.#queue.push(data);
+    }
+  }
+  #flushWaiters() {
+    const reason = this.#failure ?? new Error("WebSocket closed");
+    while (this.#waiters.length > 0) {
+      this.#waiters.shift().reject(reason);
+    }
+  }
+};
+function resolveWsUrl(options) {
+  const env = options.env ?? (typeof process !== "undefined" ? process.env : {});
+  for (const candidate of [options.explicit, options.fallback, env[ENV_WS_URL]]) {
+    if (candidate) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    "No WebSocket URL configured. Pass { wsUrl } to events(), set it on the client constructor, or set the CONVILYN_WS_URL environment variable."
+  );
+}
+function buildWsConnectUrl(baseUrl, token) {
+  const separator = baseUrl.includes("?") ? "&" : "?";
+  return `${baseUrl}${separator}token=${token}`;
+}
+
+// src/resources/goals.ts
+var DEFAULT_POLL_INTERVAL2 = 1;
+var DEFAULT_POLL_TIMEOUT2 = 300;
+var MAX_POLL_INTERVAL2 = 5;
+var STALE_PROGRESS_BACKOFF_AFTER2 = 3;
+var BACKOFF_FACTOR2 = 1.5;
+var realSleep3 = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var Goals = class {
+  #http;
+  #wsUrl;
+  #wsTransportFactory;
+  #sleep;
+  #now;
+  constructor(http, options = {}) {
+    this.#http = http;
+    this.#wsUrl = options.wsUrl ?? null;
+    this.#wsTransportFactory = options.wsTransportFactory ?? (() => new WebSocketTransport());
+    this.#sleep = options.sleep ?? realSleep3;
+    this.#now = options.now ?? (() => Date.now());
+  }
+  /** Create a goal job and return its initial {@link GoalJob} state. */
+  async start(options) {
+    validateStartInputs(options);
+    const payload = { fileIds: options.files ?? [] };
+    if (options.workflowId != null) {
+      payload.workflowId = options.workflowId;
+    }
+    if (options.goalText != null) {
+      payload.goalText = options.goalText;
+    }
+    if (options.slots != null) {
+      payload.slotAnswers = Object.entries(options.slots).map(([slotId, value]) => ({
+        slotId,
+        value
+      }));
+    }
+    if (options.llmConfigId != null) {
+      payload.llmConfigId = options.llmConfigId;
+    }
+    const response = await this.#http.request("POST", "/api/v1/jobs/goal", { json: payload });
+    return parseGoalJob(await response.json());
+  }
+  /** Fetch the current state of a goal job. */
+  async retrieve(jobSpecId) {
+    return this.#pollOnce(jobSpecId);
+  }
+  /**
+   * Poll until the job reaches a terminal state OR stops for HITL
+   * (`slots_pending`). `failed` raises {@link GoalJobFailedError}; an elapsed
+   * deadline raises {@link GoalJobTimeoutError}.
+   */
+  async wait(jobSpecId, options = {}) {
+    return this.#waitLoop(
+      jobSpecId,
+      options.timeout ?? DEFAULT_POLL_TIMEOUT2,
+      options.pollInterval ?? DEFAULT_POLL_INTERVAL2
+    );
+  }
+  /** Shortcut: {@link start} then {@link wait}. */
+  async run(options) {
+    const job = await this.start(options);
+    return this.wait(job.jobSpecId, {
+      timeout: options.timeout,
+      pollInterval: options.pollInterval
+    });
+  }
+  /** Answer a single slot the agent is waiting on (sugar over {@link fillSlots}). */
+  async fillSlot(jobSpecId, options) {
+    return this.fillSlots(
+      jobSpecId,
+      { [options.slotId]: options.value },
+      {
+        expectedVersion: options.expectedVersion
+      }
+    );
+  }
+  /** Answer one or more slots in a single PATCH (`{slotId: value}` → wire list). */
+  async fillSlots(jobSpecId, answers, options = {}) {
+    const entries = Object.entries(answers);
+    if (entries.length === 0) {
+      throw new Error("answers must contain at least one slot answer");
+    }
+    const body = {
+      answers: entries.map(([slotId, value]) => ({ slotId, value }))
+    };
+    if (options.expectedVersion != null) {
+      body.expectedVersion = options.expectedVersion;
+    }
+    const response = await this.#http.request("PATCH", `/api/v1/jobs/goal/${jobSpecId}/slots`, {
+      json: body
+    });
+    return parseGoalJob(await response.json());
+  }
+  /** Confirm a slots-filled job, queueing it for execution. */
+  async confirm(jobSpecId, options = {}) {
+    const json = options.expectedVersion != null ? { expectedVersion: options.expectedVersion } : void 0;
+    await this.#http.request("POST", `/api/v1/jobs/goal/${jobSpecId}/confirm`, { json });
+    return this.#pollOnce(jobSpecId);
+  }
+  /** Cancel a running or queued job. */
+  async cancel(jobSpecId) {
+    await this.#http.request("POST", `/api/v1/jobs/goal/${jobSpecId}/cancel`);
+    return this.#pollOnce(jobSpecId);
+  }
+  /** Retry a failed job (resume the thread or start a fresh rerun). */
+  async retry(jobSpecId, options = {}) {
+    const body = { rerunMode: options.rerunMode ?? "retry_same_thread" };
+    if (options.reason != null) {
+      body.reason = options.reason;
+    }
+    await this.#http.request("POST", `/api/v1/jobs/goal/${jobSpecId}/retry`, { json: body });
+    return this.#pollOnce(jobSpecId);
+  }
+  /**
+   * Stream goal execution events for a job. Opens a WebSocket, subscribes,
+   * then yields each {@link GoalEvent} in order; the iterator ends (and the
+   * socket closes) on a terminal event. No auto-reconnect — the backend does
+   * not replay missed events, so a silent reconnect would hide gaps.
+   *
+   * **WebSocket streaming is not available with a `ck_` consumer key in v1** —
+   * the backend WS gateway does not authenticate `ck_` keys, so the connection
+   * is denied. Use {@link wait} polling (standard HTTP auth, works today) for
+   * the supported real-time path. This method is wired and ready for when the
+   * gateway gains `ck_` support.
+   *
+   * @throws {@link WebSocketError} on connect/subscribe failure, a dropped
+   *   stream, or an unparseable/unrecognised envelope.
+   */
+  async *events(jobSpecId, options = {}) {
+    const url = buildWsConnectUrl(
+      resolveWsUrl({ explicit: options.wsUrl, fallback: this.#wsUrl }),
+      this.#http.auth.bearerToken()
+    );
+    const transport = this.#wsTransportFactory();
+    try {
+      try {
+        await transport.connect(url);
+        await transport.send(JSON.stringify({ action: "subscribe", jobSpecId }));
+      } catch (error) {
+        throw new WebSocketError(
+          `Failed to open event stream for job ${jobSpecId}: ${errorMessage(error)}. Note: the WebSocket gateway does not accept ck_ consumer keys in v1 \u2014 use wait() polling (HTTP auth) instead.`
+        );
+      }
+      for (; ; ) {
+        let raw;
+        try {
+          raw = await transport.recv();
+        } catch (error) {
+          throw new WebSocketError(
+            `Event stream dropped for job ${jobSpecId}: ${errorMessage(error)}`
+          );
+        }
+        const event = parseEvent(raw);
+        yield event;
+        if (isGoalEventTerminal(event)) {
+          return;
+        }
+      }
+    } finally {
+      await transport.close();
+    }
+  }
+  // ── private ────────────────────────────────────────────────────
+  async #pollOnce(jobSpecId) {
+    const response = await this.#http.request("GET", `/api/v1/jobs/goal/${jobSpecId}`);
+    return parseGoalJob(await response.json());
+  }
+  async #waitLoop(jobSpecId, timeout, initialInterval) {
+    const start = this.#now() / 1e3;
+    let interval = initialInterval;
+    let staleCount = 0;
+    let lastProgress = -1;
+    for (; ; ) {
+      const job = await this.#pollOnce(jobSpecId);
+      if (isGoalJobTerminal(job)) {
+        return this.#finalise(job);
+      }
+      if (goalJobNeedsInput(job)) {
+        return job;
+      }
+      if (job.progress === lastProgress) {
+        staleCount += 1;
+        if (staleCount >= STALE_PROGRESS_BACKOFF_AFTER2) {
+          interval = Math.min(interval * BACKOFF_FACTOR2, MAX_POLL_INTERVAL2);
+          staleCount = 0;
+        }
+      } else {
+        lastProgress = job.progress;
+        staleCount = 0;
+      }
+      const elapsed = this.#now() / 1e3 - start;
+      if (elapsed + interval > timeout) {
+        throw new GoalJobTimeoutError({ jobSpecId, elapsed, timeout });
+      }
+      await this.#sleep(interval);
+    }
+  }
+  #finalise(job) {
+    if (job.status === "failed") {
+      throw new GoalJobFailedError({
+        jobSpecId: job.jobSpecId,
+        code: job.errorCode,
+        message: job.errorMessage
+      });
+    }
+    return job;
+  }
+};
+function validateStartInputs(options) {
+  const { workflowId, goalText, files } = options;
+  if (workflowId == null && goalText == null) {
+    throw new TypeError("start() requires either `workflowId` or `goalText`");
+  }
+  if (workflowId != null && goalText != null) {
+    throw new TypeError("start() accepts either `workflowId` or `goalText`, not both");
+  }
+  if (workflowId == null && (!files || files.length === 0)) {
+    throw new Error("files is required when `workflowId` is not provided");
+  }
+}
+function parseEvent(raw) {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch (error) {
+    throw new WebSocketError(`Server sent non-JSON message: ${errorMessage(error)}`, {
+      payload: raw
+    });
+  }
+  if (typeof payload !== "object" || payload === null || typeof payload.type !== "string" || typeof payload.jobSpecId !== "string" || !isGoalEventType(payload.type)) {
+    throw new WebSocketError("Server sent an unrecognised event envelope", { payload: raw });
+  }
+  return parseGoalEvent(payload);
+}
+
+// src/resources/workflows.ts
+var Workflows = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /** Browse the public community listing (one page + a `cursor`). */
+  async search(options = {}) {
+    const params = {
+      sort: options.sort ?? "recent",
+      limit: options.limit ?? 20
+    };
+    if (options.tag != null) {
+      params.tag = options.tag;
+    }
+    if (options.cursor != null) {
+      params.cursor = options.cursor;
+    }
+    const response = await this.#http.request("GET", "/api/v1/workflows/community", { params });
+    return parseWorkflowSearchPage(await response.json());
+  }
+  /** Fetch a single workflow by id. */
+  async get(workflowId) {
+    const response = await this.#http.request("GET", `/api/v1/workflows/${workflowId}`);
+    return parseWorkflow(await response.json());
+  }
+  /** Fork a curated/user source into a new private workflow (Pro). */
+  async fork(options) {
+    const body = { sourceSpecId: options.sourceSpecId };
+    if (options.name != null) {
+      body.name = options.name;
+    }
+    const response = await this.#http.request("POST", "/api/v1/workflows/fork", { json: body });
+    return parseWorkflow(await response.json());
+  }
+  /** Flip an owned workflow's visibility to `public` (Pro; optimistic lock). */
+  async publish(workflowId, options) {
+    return this.patch(workflowId, { itemVersion: options.itemVersion, visibility: "public" });
+  }
+  /** Partial update of an owned workflow (the generic PATCH escape hatch). */
+  async patch(workflowId, options) {
+    const body = { itemVersion: options.itemVersion };
+    if (options.name != null) {
+      body.name = options.name;
+    }
+    if (options.description != null) {
+      body.description = options.description;
+    }
+    if (options.visibility != null) {
+      body.visibility = options.visibility;
+    }
+    if (options.tags != null) {
+      body.tags = [...options.tags];
+    }
+    const response = await this.#http.request("PATCH", `/api/v1/workflows/${workflowId}`, {
+      json: body
+    });
+    return parseWorkflow(await response.json());
+  }
+  /** Toggle the caller's like on a public workflow (idempotent toggle). */
+  async like(workflowId) {
+    const response = await this.#http.request("POST", `/api/v1/workflows/${workflowId}/like`);
+    return parseLikeResponse(await response.json());
+  }
+};
+
+// src/client.ts
+var Convilyn = class {
+  files;
+  convert;
+  goals;
+  workflows;
+  account;
+  #http;
+  constructor(options = {}) {
+    const auth = options.auth ?? resolveAuth(options.apiKey);
+    this.#http = new HttpClient({
+      auth,
+      baseUrl: options.baseUrl,
+      timeout: options.timeout,
+      retryPolicy: resolveRetryPolicy(options.maxRetries, options.retryPolicy),
+      idempotencyEnabled: !options.disableIdempotency,
+      autoThrottle: resolveAutoThrottle(options.autoThrottle)
+    });
+    this.files = new Files(this.#http);
+    this.convert = new Convert(this.#http);
+    this.goals = new Goals(this.#http, {
+      wsUrl: options.wsUrl,
+      wsTransportFactory: options.wsTransportFactory
+    });
+    this.workflows = new Workflows(this.#http);
+    this.account = new Account(this.#http);
+  }
+  get baseUrl() {
+    return this.#http.baseUrl;
+  }
+  async close() {
+    await this.#http.close();
+  }
+};
+function resolveRetryPolicy(maxRetries, retryPolicy) {
+  if (retryPolicy != null) {
+    return retryPolicy;
+  }
+  if (maxRetries == null) {
+    return new ExponentialBackoffRetry();
+  }
+  if (maxRetries <= 0) {
+    return new NoRetry();
+  }
+  return new ExponentialBackoffRetry({ maxAttempts: maxRetries });
+}
+
+export { APIError, AuthError, AutoThrottleConfig, CONVERT_JOB_TERMINAL_STATUSES, Convilyn, ConvilynError, DEFAULT_BASE_URL, ExponentialBackoffRetry, GOAL_EVENT_TERMINAL_TYPES, GOAL_EVENT_TYPES, GOAL_JOB_TERMINAL_STATUSES, GoalJobFailedError, GoalJobTimeoutError, HttpClient, JobFailedError, JobTimeoutError, NoRetry, PlanRequiredError, QuotaExceededError, RateLimitError, RetryExhaustedError, S3UploadError, VERSION, WebSocketError, goalJobNeedsInput, guessContentType, isConvertJobTerminal, isGoalEventTerminal, isGoalEventType, isGoalJobTerminal, resolveAuth };
+//# sourceMappingURL=chunk-UJHZKIP6.js.map
+//# sourceMappingURL=chunk-UJHZKIP6.js.map