@supernovae-st/nika-client 0.63.0

package/dist/index.cjs

@@ -0,0 +1,675 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Jobs: () => Jobs,
+  Nika: () => Nika,
+  NikaAPIError: () => NikaAPIError,
+  NikaConnectionError: () => NikaConnectionError,
+  NikaError: () => NikaError,
+  NikaJobCancelledError: () => NikaJobCancelledError,
+  NikaJobError: () => NikaJobError,
+  NikaTimeoutError: () => NikaTimeoutError,
+  Workflows: () => Workflows,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var NikaError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NikaError";
+  }
+};
+var NikaAPIError = class extends NikaError {
+  status;
+  body;
+  requestId;
+  constructor(message, status, body, requestId) {
+    super(message);
+    this.name = "NikaAPIError";
+    this.status = status;
+    this.body = body;
+    this.requestId = requestId;
+  }
+};
+var NikaConnectionError = class extends NikaError {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "NikaConnectionError";
+    this.cause = cause;
+  }
+};
+var NikaTimeoutError = class extends NikaError {
+  constructor(message) {
+    super(message);
+    this.name = "NikaTimeoutError";
+  }
+};
+var NikaJobError = class extends NikaError {
+  job;
+  exitCode;
+  constructor(job) {
+    super(`Job ${job.job_id} ${job.status}: ${job.output ?? "unknown error"}`);
+    this.name = "NikaJobError";
+    this.job = job;
+    this.exitCode = job.exit_code;
+  }
+};
+var NikaJobCancelledError = class extends NikaJobError {
+  constructor(job) {
+    super(job);
+    this.name = "NikaJobCancelledError";
+  }
+};
+
+// src/lib/semaphore.ts
+var Semaphore = class {
+  constructor(max) {
+    this.max = max;
+  }
+  max;
+  current = 0;
+  queue = [];
+  async acquire() {
+    if (this.current < this.max) {
+      this.current++;
+      return;
+    }
+    return new Promise((resolve) => this.queue.push(resolve));
+  }
+  release() {
+    const next = this.queue.shift();
+    if (next) {
+      next();
+    } else {
+      this.current--;
+    }
+  }
+};
+
+// src/lib/api-client.ts
+var ApiClient = class {
+  url;
+  timeout;
+  retries;
+  logger;
+  token;
+  _fetch;
+  semaphore;
+  constructor(url, token, timeout, retries, fetchFn, concurrency, logger) {
+    this.url = url;
+    this.token = token;
+    this.timeout = timeout;
+    this.retries = retries;
+    this._fetch = fetchFn;
+    this.semaphore = new Semaphore(concurrency);
+    this.logger = logger;
+  }
+  // ── Standard request: auth + retry + timeout ──────────────
+  async request(path, init) {
+    await this.semaphore.acquire();
+    try {
+      return await this._request(path, init);
+    } finally {
+      this.semaphore.release();
+    }
+  }
+  async _request(path, init) {
+    const url = `${this.url}${path}`;
+    const headers = {
+      "Authorization": `Bearer ${this.token}`,
+      ...init?.headers ?? {}
+    };
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      let abortListener;
+      if (init?.signal) {
+        if (init.signal.aborted) {
+          clearTimeout(timer);
+          throw new NikaConnectionError("Request aborted by caller");
+        }
+        abortListener = () => controller.abort(init.signal.reason);
+        init.signal.addEventListener("abort", abortListener, { once: true });
+      }
+      try {
+        this.logger?.debug(`${init?.method ?? "GET"} ${path} (attempt ${attempt + 1})`);
+        const res = await this._fetch(url, {
+          ...init,
+          headers,
+          signal: controller.signal
+        });
+        if (res.ok) {
+          this.logger?.debug(`${res.status} ${path}`);
+          return res;
+        }
+        const body = await res.text().catch(() => "");
+        const requestId = res.headers.get("x-request-id") ?? void 0;
+        if ((res.status === 429 || res.status >= 500) && attempt < this.retries) {
+          const retryAfter = res.headers.get("Retry-After");
+          const parsed = retryAfter ? parseInt(retryAfter, 10) : NaN;
+          const delay = Number.isFinite(parsed) ? parsed * 1e3 : 1e3 * (attempt + 1);
+          this.logger?.warn(`${res.status} ${path} \u2014 retrying in ${delay}ms`);
+          await sleep(delay, init?.signal ?? void 0);
+          continue;
+        }
+        throw new NikaAPIError(
+          `${res.status} ${res.statusText}: ${body}`.trim(),
+          res.status,
+          body,
+          requestId
+        );
+      } catch (err) {
+        if (err instanceof NikaAPIError) throw err;
+        if (err instanceof NikaConnectionError) throw err;
+        if (err instanceof Error && err.name === "AbortError") {
+          if (init?.signal?.aborted) {
+            throw new NikaConnectionError("Request aborted by caller");
+          }
+          throw new NikaTimeoutError(`Request timed out after ${this.timeout}ms`);
+        }
+        if (err instanceof TypeError) {
+          throw new NikaConnectionError(`Connection failed: ${err.message}`, err);
+        }
+        throw err;
+      } finally {
+        clearTimeout(timer);
+        if (abortListener && init?.signal) {
+          init.signal.removeEventListener("abort", abortListener);
+        }
+      }
+    }
+    throw new NikaAPIError("Max retries exceeded", 503, "");
+  }
+  // ── JSON shorthand ────────────────────────────────────────
+  async json(path, init) {
+    const res = await this.request(path, init);
+    return res.json();
+  }
+  // ── SSE connect: auth but no retry/timeout (stream has its own idle timeout) ──
+  async connectSSE(path, signal, extraHeaders) {
+    const url = `${this.url}${path}`;
+    const res = await this._fetch(url, {
+      headers: {
+        "Authorization": `Bearer ${this.token}`,
+        "Accept": "text/event-stream",
+        ...extraHeaders
+      },
+      signal
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new NikaAPIError(
+        `SSE connection failed: ${res.status} ${res.statusText}`,
+        res.status,
+        body
+      );
+    }
+    return res;
+  }
+  // ── Health fetch: no auth, with timeout ───────────────────
+  async fetchHealth() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await this._fetch(`${this.url}/health`, {
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new NikaTimeoutError(`Health check timed out after ${this.timeout}ms`);
+      }
+      if (err instanceof TypeError) {
+        throw new NikaConnectionError(`Health check failed: ${err.message}`, err);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new NikaConnectionError("Request aborted by caller"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(new NikaConnectionError("Request aborted by caller"));
+    }, { once: true });
+  });
+}
+
+// src/lib/polling.ts
+async function pollUntilDone(fetchStatus, opts) {
+  const deadline = Date.now() + opts.timeout;
+  let delay = opts.interval;
+  while (true) {
+    if (opts.signal?.aborted) {
+      throw new NikaConnectionError("Poll aborted by caller");
+    }
+    const job = await fetchStatus();
+    if (job.status === "completed") return job;
+    if (job.status === "failed") throw new NikaJobError(job);
+    if (job.status === "cancelled") throw new NikaJobCancelledError(job);
+    if (Date.now() + delay > deadline) {
+      throw new NikaTimeoutError(`Job ${job.job_id} timed out after ${opts.timeout}ms`);
+    }
+    await sleep2(delay, opts.signal);
+    delay = Math.min(delay * opts.backoff, 1e4);
+  }
+}
+function sleep2(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new NikaConnectionError("Poll aborted by caller"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(new NikaConnectionError("Poll aborted by caller"));
+    }, { once: true });
+  });
+}
+
+// src/lib/streaming.ts
+var DEFAULT_IDLE_TIMEOUT = 6e4;
+async function* streamEvents(client, jobId, options) {
+  const maxReconnects = options?.maxReconnects ?? 3;
+  const reconnectDelay = options?.reconnectDelay ?? 1e3;
+  let lastEventId;
+  let reconnects = 0;
+  while (true) {
+    try {
+      const extraHeaders = {};
+      if (lastEventId) extraHeaders["Last-Event-Id"] = lastEventId;
+      yield* streamOnce(client, jobId, options, extraHeaders, (id) => {
+        lastEventId = id;
+      });
+      return;
+    } catch (err) {
+      if (options?.signal?.aborted) throw err;
+      if (err instanceof NikaTimeoutError) throw err;
+      if (err instanceof NikaError && !(err instanceof NikaConnectionError)) throw err;
+      if (reconnects >= maxReconnects) throw err;
+      reconnects++;
+      await sleep3(reconnectDelay * reconnects, options?.signal);
+      continue;
+    }
+  }
+}
+async function* streamOnce(client, jobId, options, extraHeaders, onEventId) {
+  const idleTimeout = options?.idleTimeout ?? DEFAULT_IDLE_TIMEOUT;
+  const res = await client.connectSSE(
+    `/v1/events/${jobId}`,
+    options?.signal,
+    extraHeaders
+  );
+  if (!res.body) {
+    throw new NikaError("SSE response has no body");
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let receivedTerminal = false;
+  let timedOut = false;
+  let idleTimer;
+  function resetIdleTimer() {
+    if (idleTimer !== void 0) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      timedOut = true;
+      reader.cancel("idle timeout").catch(() => {
+      });
+    }, idleTimeout);
+  }
+  resetIdleTimer();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        if (timedOut) {
+          throw new NikaTimeoutError(
+            `SSE stream idle for ${idleTimeout}ms \u2014 connection assumed dead`
+          );
+        }
+        if (!receivedTerminal) {
+          throw new NikaConnectionError(
+            "SSE stream closed without terminal event (completed/failed/cancelled)"
+          );
+        }
+        break;
+      }
+      resetIdleTimer();
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split("\n\n");
+      buffer = parts.pop();
+      for (const part of parts) {
+        const lines = part.split("\n");
+        let data;
+        let eventId;
+        for (const line of lines) {
+          if (line.startsWith("data:")) {
+            data = line[5] === " " ? line.slice(6) : line.slice(5);
+          }
+          if (line.startsWith("id:")) {
+            eventId = line[3] === " " ? line.slice(4) : line.slice(3);
+          }
+        }
+        if (eventId) {
+          onEventId(eventId);
+        }
+        if (data) {
+          try {
+            const event = JSON.parse(data);
+            yield event;
+            if (event.type === "completed" || event.type === "failed" || event.type === "cancelled") {
+              receivedTerminal = true;
+              return;
+            }
+          } catch {
+          }
+        }
+      }
+    }
+  } finally {
+    if (idleTimer !== void 0) clearTimeout(idleTimer);
+    await reader.cancel().catch(() => {
+    });
+    reader.releaseLock();
+  }
+}
+function sleep3(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new NikaConnectionError("Request aborted by caller"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(new NikaConnectionError("Request aborted by caller"));
+    }, { once: true });
+  });
+}
+
+// src/resources/jobs.ts
+var Jobs = class {
+  constructor(api, poll) {
+    this.api = api;
+    this.poll = poll;
+  }
+  api;
+  poll;
+  /** Submit a workflow and return immediately with job ID. */
+  async submit(workflow, inputs, options) {
+    return this.api.json("/v1/run", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        workflow,
+        ...inputs !== void 0 ? { inputs } : {},
+        ...options?.resumeFrom ? { resume_from: options.resumeFrom } : {}
+      }),
+      signal: options?.signal
+    });
+  }
+  /** Get current job status. */
+  async status(jobId) {
+    return this.api.json(`/v1/status/${jobId}`);
+  }
+  /** Cancel a running job. */
+  async cancel(jobId) {
+    return this.api.json(`/v1/cancel/${jobId}`, { method: "POST" });
+  }
+  /** Run a workflow and wait for completion (polling). */
+  async run(workflow, inputs, options) {
+    const { job_id } = await this.submit(workflow, inputs, options);
+    return pollUntilDone(
+      () => this.status(job_id),
+      {
+        interval: this.poll.pollInterval,
+        timeout: this.poll.pollTimeout,
+        backoff: this.poll.pollBackoff,
+        signal: options?.signal
+      }
+    );
+  }
+  /** Stream job events via SSE (AsyncIterable). */
+  stream(jobId, options) {
+    return streamEvents(this.api, jobId, options);
+  }
+  /** List artifacts for a job. */
+  async artifacts(jobId) {
+    const res = await this.api.json(`/v1/jobs/${jobId}/artifacts`);
+    return res.artifacts;
+  }
+  /** Download a specific artifact as string. */
+  async artifact(jobId, name) {
+    const res = await this.api.request(
+      `/v1/jobs/${jobId}/artifacts/${encodeURIComponent(name)}`
+    );
+    return res.text();
+  }
+  /** Download a specific artifact as parsed JSON. */
+  async artifactJson(jobId, name) {
+    const res = await this.api.request(
+      `/v1/jobs/${jobId}/artifacts/${encodeURIComponent(name)}`
+    );
+    return res.json();
+  }
+  /** Download a specific artifact as raw bytes. */
+  async artifactBinary(jobId, name) {
+    const res = await this.api.request(
+      `/v1/jobs/${jobId}/artifacts/${encodeURIComponent(name)}`
+    );
+    const buffer = await res.arrayBuffer();
+    return new Uint8Array(buffer);
+  }
+  /** Stream an artifact as a ReadableStream (for large files). */
+  async artifactStream(jobId, name) {
+    const res = await this.api.request(
+      `/v1/jobs/${jobId}/artifacts/${encodeURIComponent(name)}`
+    );
+    if (!res.body) {
+      throw new NikaError("Artifact response has no body");
+    }
+    return res.body;
+  }
+  /** Run workflow, wait, and collect all non-binary artifacts into a map. */
+  async runAndCollect(workflow, inputs, options) {
+    const job = await this.run(workflow, inputs, options);
+    const artifactList = await this.artifacts(job.job_id);
+    const downloadable = artifactList.filter((art) => art.format !== "binary");
+    const batchSize = 6;
+    const entries = [];
+    for (let i = 0; i < downloadable.length; i += batchSize) {
+      const batch = downloadable.slice(i, i + batchSize);
+      const results = await Promise.all(
+        batch.map(async (art) => {
+          if (art.format === "json") {
+            return [art.name, await this.artifactJson(job.job_id, art.name)];
+          }
+          return [art.name, await this.artifact(job.job_id, art.name)];
+        })
+      );
+      entries.push(...results);
+    }
+    return Object.fromEntries(entries);
+  }
+};
+
+// src/resources/workflows.ts
+var Workflows = class {
+  constructor(api) {
+    this.api = api;
+  }
+  api;
+  /**
+   * List all workflows. Auto-paginates if server supports it.
+   * For large lists, use `listPage()` for manual pagination.
+   */
+  async list() {
+    const all = [];
+    let after;
+    const MAX_PAGES = 1e3;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const params = new URLSearchParams();
+      params.set("limit", "200");
+      if (after) params.set("after", after);
+      const res = await this.api.json(
+        `/v1/workflows?${params}`
+      );
+      all.push(...res.workflows);
+      if (!res.has_more || res.workflows.length === 0) break;
+      after = res.workflows[res.workflows.length - 1].name;
+    }
+    return all;
+  }
+  /** List a single page of workflows (manual pagination). */
+  async listPage(options) {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.after) params.set("after", options.after);
+    const qs = params.toString();
+    return this.api.json(
+      `/v1/workflows${qs ? `?${qs}` : ""}`
+    );
+  }
+  /** Reload workflows from disk and return the refreshed list. */
+  async reload() {
+    const res = await this.api.json("/v1/reload", {
+      method: "POST"
+    });
+    return res.workflows;
+  }
+  /** Get the raw YAML source of a workflow. */
+  async source(name) {
+    const res = await this.api.request(
+      `/v1/workflows/${encodeURIComponent(name)}/source`
+    );
+    return res.text();
+  }
+};
+
+// src/webhook.ts
+async function verifyWebhookSignature(payload, signatureHeader, secret, tolerance = 300) {
+  const parts = signatureHeader.split(",");
+  const timestampStr = parts.find((p) => p.startsWith("t="))?.slice(2);
+  const signature = parts.find((p) => p.startsWith("v1="))?.slice(3);
+  if (!timestampStr || !signature) return false;
+  const timestamp = parseInt(timestampStr, 10);
+  if (!Number.isFinite(timestamp)) return false;
+  const now = Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - timestamp) > tolerance) return false;
+  const signedPayload = `${timestampStr}.${payload}`;
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(signedPayload)
+  );
+  const expected = Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  if (expected.length !== signature.length) return false;
+  let result = 0;
+  for (let i = 0; i < expected.length; i++) {
+    result |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+  }
+  return result === 0;
+}
+
+// src/index.ts
+var Nika = class {
+  /** Job operations: submit, status, cancel, run, stream, artifacts. */
+  jobs;
+  /** Workflow operations: list, reload. */
+  workflows;
+  api;
+  constructor(config) {
+    if (!config.url.startsWith("http://") && !config.url.startsWith("https://")) {
+      throw new TypeError(`NikaConfig.url must be an http(s) URL, got: ${config.url}`);
+    }
+    if (!config.token) {
+      throw new TypeError("NikaConfig.token must not be empty");
+    }
+    this.api = new ApiClient(
+      config.url.replace(/\/$/, ""),
+      config.token,
+      config.timeout ?? 3e4,
+      config.retries ?? 2,
+      config.fetch ?? globalThis.fetch.bind(globalThis),
+      config.concurrency ?? 24,
+      config.logger
+    );
+    this.jobs = new Jobs(this.api, {
+      pollInterval: config.pollInterval ?? 2e3,
+      pollTimeout: config.pollTimeout ?? 3e5,
+      pollBackoff: config.pollBackoff ?? 1.5
+    });
+    this.workflows = new Workflows(this.api);
+  }
+  /** Health check (no auth required, uses timeout). */
+  async health() {
+    const res = await this.api.fetchHealth();
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new NikaAPIError(
+        `Health check failed: ${res.status} ${body}`.trim(),
+        res.status,
+        body
+      );
+    }
+    return res.json();
+  }
+  /**
+   * Verify a webhook signature from nika serve.
+   *
+   * @param payload — raw request body string
+   * @param signature — value of X-Nika-Signature header
+   * @param secret — shared webhook secret (NIKA_WEBHOOK_SECRET)
+   * @param tolerance — max age in seconds (default: 300)
+   */
+  static verifyWebhook = verifyWebhookSignature;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Jobs,
+  Nika,
+  NikaAPIError,
+  NikaConnectionError,
+  NikaError,
+  NikaJobCancelledError,
+  NikaJobError,
+  NikaTimeoutError,
+  Workflows,
+  verifyWebhookSignature
+});