@hlix/sdk 0.2.0

package/dist/index.js

@@ -0,0 +1,693 @@
+// ../api-client/src/client.ts
+import createClient from "openapi-fetch";
+function createHlixClient(options) {
+  return createClient({
+    baseUrl: options.baseUrl,
+    headers: options.headers,
+    fetch: options.fetch
+  });
+}
+
+// src/auth.ts
+var apiKeyCredential = (apiKey) => ({
+  kind: "apiKey",
+  apiKey
+});
+var sessionCredential = (cookie) => ({
+  kind: "session",
+  cookie
+});
+function credentialHeaders(credential) {
+  return credential.kind === "apiKey" ? { "x-api-key": credential.apiKey } : { cookie: credential.cookie };
+}
+function organizationHeaders(organizationId) {
+  return organizationId ? { "X-Organization-Id": organizationId } : {};
+}
+function authHeaders(credential, organizationId) {
+  return {
+    ...credentialHeaders(credential),
+    ...organizationHeaders(organizationId)
+  };
+}
+
+// src/errors.ts
+function errorMessageOf(body) {
+  if (typeof body !== "object" || body === null) return null;
+  const { error } = body;
+  return typeof error === "string" ? error : null;
+}
+var HlixError = class extends Error {
+  status;
+  body;
+  requestId;
+  method;
+  url;
+  constructor(message, init) {
+    super(message);
+    this.name = new.target.name;
+    this.status = init.status;
+    this.body = init.body;
+    this.requestId = init.requestId ?? null;
+    this.method = init.method;
+    this.url = init.url;
+  }
+};
+var HlixValidationError = class extends HlixError {
+  /** The decoded `ZodIssue[]`; empty when the server sent a plain message. */
+  issues;
+  constructor(message, init, issues) {
+    super(message, init);
+    this.issues = issues;
+  }
+};
+var HlixBadRequestError = class extends HlixError {
+};
+var HlixAuthenticationError = class extends HlixError {
+};
+var HlixPermissionError = class extends HlixError {
+};
+var HlixNotFoundError = class extends HlixError {
+};
+var HlixConflictError = class extends HlixError {
+};
+var HlixRateLimitError = class extends HlixError {
+  retryAfter;
+  constructor(message, init, retryAfter) {
+    super(message, init);
+    this.retryAfter = retryAfter;
+  }
+};
+var HlixNotImplementedError = class extends HlixError {
+};
+var HlixServerError = class extends HlixError {
+};
+var HlixTransportError = class extends Error {
+  method;
+  url;
+  constructor(message, init) {
+    super(message, { cause: init.cause });
+    this.name = "HlixTransportError";
+    this.method = init.method;
+    this.url = init.url;
+  }
+};
+function validationIssues(body) {
+  if (typeof body !== "object" || body === null) return null;
+  const candidate = body;
+  if (candidate.success !== false) return null;
+  const raw = candidate.error?.message;
+  if (typeof raw !== "string") return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function retryAfterSeconds(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+}
+function errorForResponse(response, body, request) {
+  const init = {
+    status: response.status,
+    body,
+    requestId: response.headers.get("x-request-id"),
+    method: request.method,
+    url: request.url
+  };
+  const stated = errorMessageOf(body);
+  const fallback = `${request.method} ${request.url} failed with ${response.status}`;
+  const issues = validationIssues(body);
+  if (issues) {
+    return new HlixValidationError(
+      `${request.method} ${request.url}: request body failed validation`,
+      init,
+      issues
+    );
+  }
+  const message = stated ?? fallback;
+  switch (response.status) {
+    case 400:
+      return new HlixBadRequestError(message, init);
+    case 401:
+      return new HlixAuthenticationError(message, init);
+    case 403:
+      return new HlixPermissionError(message, init);
+    case 404:
+      return new HlixNotFoundError(message, init);
+    case 409:
+      return new HlixConflictError(message, init);
+    case 429:
+      return new HlixRateLimitError(message, init, retryAfterSeconds(response.headers));
+    case 501:
+      return new HlixNotImplementedError(message, init);
+    default:
+      return response.status >= 500 ? new HlixServerError(message, init) : new HlixError(message, init);
+  }
+}
+
+// src/retry.ts
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "HEAD",
+  "PUT",
+  "DELETE",
+  "OPTIONS",
+  "TRACE"
+]);
+function isIdempotent(method) {
+  return IDEMPOTENT_METHODS.has(method.toUpperCase());
+}
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+  429,
+  500,
+  502,
+  503,
+  504
+]);
+function isRetryableStatus(status) {
+  return RETRYABLE_STATUSES.has(status);
+}
+var DEFAULT_RETRY = {
+  attempts: 3,
+  baseDelayMs: 200,
+  maxDelayMs: 5e3
+};
+function backoffDelayMs(attempt, policy, retryAfterSeconds3, random = Math.random) {
+  if (retryAfterSeconds3 !== null) {
+    return Math.min(retryAfterSeconds3 * 1e3, policy.maxDelayMs);
+  }
+  const ceiling = Math.min(policy.baseDelayMs * 2 ** attempt, policy.maxDelayMs);
+  return Math.round(random() * ceiling);
+}
+function shouldRetry(input) {
+  if (!isIdempotent(input.method)) return false;
+  if (input.attempt + 1 >= input.policy.attempts) return false;
+  return input.status === null || isRetryableStatus(input.status);
+}
+
+// src/http.ts
+var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function retryAfterSeconds2(response) {
+  const raw = response.headers.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+}
+function retryingFetch(options) {
+  const { base, policy } = options;
+  const sleep = options.sleep ?? wait;
+  const random = options.random ?? Math.random;
+  return async (input) => {
+    const method = input.method.toUpperCase();
+    const replayable = isIdempotent(method) ? input.clone() : null;
+    for (let attempt = 0; ; attempt += 1) {
+      const request = attempt === 0 ? input : replayable.clone();
+      let response;
+      try {
+        response = await base(request);
+      } catch (cause) {
+        if (!replayable || !shouldRetry({ method, attempt, policy, status: null })) {
+          throw new HlixTransportError(
+            `${method} ${input.url}: ${cause instanceof Error ? cause.message : String(cause)}`,
+            { method, url: input.url, cause }
+          );
+        }
+        await sleep(backoffDelayMs(attempt, policy, null, random));
+        continue;
+      }
+      if (!shouldRetry({ method, attempt, policy, status: response.status })) {
+        return response;
+      }
+      if (!replayable) return response;
+      await sleep(backoffDelayMs(attempt, policy, retryAfterSeconds2(response), random));
+    }
+  };
+}
+function unwrap(result, request) {
+  if (result.response.ok) return result.data;
+  throw errorForResponse(result.response, result.error ?? result.data, request);
+}
+
+// src/streaming.ts
+var emptyFrame = () => ({ event: null, data: [], id: null, retry: null });
+function applyField(frame, name, value) {
+  switch (name) {
+    case "event":
+      frame.event = value;
+      return;
+    case "data":
+      frame.data.push(value);
+      return;
+    case "id":
+      if (!value.includes("\0")) frame.id = value;
+      return;
+    case "retry": {
+      if (/^\d+$/.test(value)) frame.retry = Number(value);
+      return;
+    }
+    default:
+      return;
+  }
+}
+function dispatch(frame) {
+  const data = frame.data.join("\n");
+  const event = frame.event;
+  const id = frame.id;
+  frame.data = [];
+  frame.event = null;
+  if (data === "") return null;
+  return { event, data, id, retry: frame.retry };
+}
+function consumeLine(frame, line) {
+  if (line === "") return dispatch(frame);
+  if (line.startsWith(":")) return null;
+  const colon = line.indexOf(":");
+  if (colon === -1) {
+    applyField(frame, line, "");
+    return null;
+  }
+  const name = line.slice(0, colon);
+  let value = line.slice(colon + 1);
+  if (value.startsWith(" ")) value = value.slice(1);
+  applyField(frame, name, value);
+  return null;
+}
+function splitLines(buffer) {
+  const lines = [];
+  let start = 0;
+  for (let i = 0; i < buffer.length; i += 1) {
+    const ch = buffer[i];
+    if (ch !== "\n" && ch !== "\r") continue;
+    lines.push(buffer.slice(start, i));
+    if (ch === "\r" && buffer[i + 1] === "\n") i += 1;
+    start = i + 1;
+  }
+  return { lines, rest: buffer.slice(start) };
+}
+async function* parseSseStream(body, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const frame = emptyFrame();
+  let buffer = "";
+  const abort = () => void reader.cancel().catch(() => {
+  });
+  signal?.addEventListener("abort", abort, { once: true });
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const { lines, rest } = splitLines(buffer);
+      buffer = rest;
+      for (const line of lines) {
+        const event = consumeLine(frame, line);
+        if (event) yield event;
+      }
+      if (signal?.aborted) return;
+    }
+    buffer += decoder.decode();
+    if (buffer !== "") {
+      const event = consumeLine(frame, buffer);
+      if (event) yield event;
+    }
+    const trailing = dispatch(frame);
+    if (trailing) yield trailing;
+  } finally {
+    signal?.removeEventListener("abort", abort);
+    reader.releaseLock();
+  }
+}
+
+// src/index.ts
+var Hlix = class {
+  /** The un-opinionated transport, for anything this facade does not wrap. */
+  raw;
+  baseUrl;
+  headers;
+  fetcher;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.headers = authHeaders(options.credential, options.organizationId);
+    const policy = { ...DEFAULT_RETRY, ...options.retry };
+    const base = options.fetch ?? ((input) => globalThis.fetch(input));
+    this.fetcher = retryingFetch({ base, policy });
+    this.raw = createHlixClient({
+      baseUrl: this.baseUrl,
+      headers: this.headers,
+      fetch: this.fetcher
+    });
+  }
+  at(method, path) {
+    return { method, url: `${this.baseUrl}${path}` };
+  }
+  projects = {
+    list: async () => unwrap(
+      await this.raw.GET("/v1/api/projects"),
+      this.at("GET", "/v1/api/projects")
+    ),
+    get: async (id) => unwrap(
+      await this.raw.GET("/v1/api/projects/{id}", { params: { path: { id } } }),
+      this.at("GET", `/v1/api/projects/${id}`)
+    ),
+    create: async (body) => unwrap(
+      await this.raw.POST("/v1/api/projects", { body }),
+      this.at("POST", "/v1/api/projects")
+    ),
+    delete: async (id) => unwrap(
+      await this.raw.DELETE("/v1/api/projects/{id}", {
+        params: { path: { id } }
+      }),
+      this.at("DELETE", `/v1/api/projects/${id}`)
+    ),
+    start: async (id, body) => unwrap(
+      await this.raw.POST("/v1/api/projects/{id}/start", {
+        params: { path: { id } },
+        body
+      }),
+      this.at("POST", `/v1/api/projects/${id}/start`)
+    )
+  };
+  imports = {
+    create: async (body) => {
+      const result = await this.raw.POST("/v1/api/imports", { body });
+      return unwrap(result, this.at("POST", "/v1/api/imports"));
+    },
+    get: async (id) => unwrap(
+      await this.raw.GET("/v1/api/imports/{id}", {
+        params: { path: { id } }
+      }),
+      this.at("GET", `/v1/api/imports/${id}`)
+    ),
+    finalize: async (id, body) => {
+      const result = await this.raw.POST("/v1/api/imports/{id}/finalize", {
+        params: { path: { id } },
+        body
+      });
+      return unwrap(
+        result,
+        this.at("POST", `/v1/api/imports/${id}/finalize`)
+      );
+    },
+    uploadBundle: async (upload, bundle, options = {}) => {
+      const chunkSize = options.chunkSize ?? 8 * 1024 * 1024;
+      if (chunkSize <= 0 || chunkSize % (256 * 1024) !== 0) {
+        throw new Error("Import upload chunkSize must be a positive multiple of 256 KiB");
+      }
+      const url = upload.url.startsWith("/") ? `${this.baseUrl}${upload.url}` : upload.url;
+      if (upload.kind === "hlix-stream") {
+        const request = new Request(url, {
+          method: "PUT",
+          headers: {
+            ...this.headers,
+            "content-type": "application/x-git-bundle",
+            "content-length": String(bundle.size)
+          },
+          body: bundle,
+          signal: options.signal
+        });
+        const response = await this.fetcher(request);
+        if (!response.ok) await this.throwUploadError(response, url);
+        options.onProgress?.(bundle.size, bundle.size);
+        return;
+      }
+      let offset = 0;
+      while (offset < bundle.size) {
+        const end = Math.min(offset + chunkSize, bundle.size);
+        const request = new Request(url, {
+          method: "PUT",
+          headers: {
+            "content-type": "application/x-git-bundle",
+            "content-length": String(end - offset),
+            "content-range": `bytes ${offset}-${end - 1}/${bundle.size}`
+          },
+          body: bundle.slice(offset, end),
+          signal: options.signal
+        });
+        const response = await this.fetcher(request);
+        if (response.status !== 308 && !response.ok) {
+          await this.throwUploadError(response, url);
+        }
+        const acknowledged = response.headers.get("range")?.match(/bytes=0-(\d+)/)?.[1];
+        offset = acknowledged ? Number(acknowledged) + 1 : end;
+        if (!Number.isSafeInteger(offset) || offset < end || offset > bundle.size) {
+          throw new Error("Import upload server returned an invalid acknowledged range");
+        }
+        options.onProgress?.(offset, bundle.size);
+      }
+    }
+  };
+  revisions = {
+    head: async (projectId) => unwrap(
+      await this.raw.GET("/v1/api/projects/{id}/revisions/head", {
+        params: { path: { id: projectId } }
+      }),
+      this.at("GET", `/v1/api/projects/${projectId}/revisions/head`)
+    ),
+    protectedFiles: async (projectId) => unwrap(
+      await this.raw.GET("/v1/api/projects/{id}/protected-files", {
+        params: { path: { id: projectId } }
+      }),
+      this.at("GET", `/v1/api/projects/${projectId}/protected-files`)
+    ),
+    createUpload: async (projectId, body) => {
+      const result = await this.raw.POST("/v1/api/projects/{id}/revisions/uploads", {
+        params: { path: { id: projectId } },
+        body
+      });
+      return unwrap(result, this.at("POST", `/v1/api/projects/${projectId}/revisions/uploads`));
+    },
+    finalize: async (projectId, uploadId, body) => {
+      const result = await this.raw.POST(
+        "/v1/api/projects/{id}/revisions/uploads/{uploadId}/finalize",
+        { params: { path: { id: projectId, uploadId } }, body }
+      );
+      return unwrap(
+        result,
+        this.at("POST", `/v1/api/projects/${projectId}/revisions/uploads/${uploadId}/finalize`)
+      );
+    },
+    uploadBundle: async (upload, bundle, options = {}) => this.imports.uploadBundle(upload, bundle, options),
+    downloadBundle: async (projectId, revisionId) => {
+      const path = `/v1/api/projects/${projectId}/revisions/${revisionId}/bundle`;
+      const request = new Request(`${this.baseUrl}${path}`, {
+        method: "GET",
+        headers: this.headers
+      });
+      const response = await this.fetcher(request);
+      if (!response.ok) await this.throwUploadError(response, `${this.baseUrl}${path}`);
+      return response.blob();
+    }
+  };
+  resources = {
+    importSkill: async (projectId, body) => unwrap(
+      await this.raw.POST("/v1/api/projects/{id}/resources/skill", {
+        params: { path: { id: projectId } },
+        body
+      }),
+      this.at("POST", `/v1/api/projects/${projectId}/resources/skill`)
+    ),
+    importAgent: async (projectId, body) => unwrap(
+      await this.raw.POST("/v1/api/projects/{id}/resources/agent", {
+        params: { path: { id: projectId } },
+        body
+      }),
+      this.at("POST", `/v1/api/projects/${projectId}/resources/agent`)
+    ),
+    importMcp: async (projectId, body) => unwrap(
+      await this.raw.POST("/v1/api/projects/{id}/resources/mcp", {
+        params: { path: { id: projectId } },
+        body
+      }),
+      this.at("POST", `/v1/api/projects/${projectId}/resources/mcp`)
+    )
+  };
+  async throwUploadError(response, url) {
+    let body = null;
+    try {
+      body = await response.json();
+    } catch {
+      body = await response.text().catch(() => null);
+    }
+    throw errorForResponse(response, body, { method: "PUT", url });
+  }
+  tasks = {
+    list: async (query) => unwrap(
+      await this.raw.GET("/v1/api/tasks", { params: { query: query ?? {} } }),
+      this.at("GET", "/v1/api/tasks")
+    ),
+    get: async (id) => unwrap(
+      await this.raw.GET("/v1/api/tasks/{id}", { params: { path: { id } } }),
+      this.at("GET", `/v1/api/tasks/${id}`)
+    ),
+    create: async (body) => unwrap(
+      await this.raw.POST("/v1/api/tasks", { body }),
+      this.at("POST", "/v1/api/tasks")
+    ),
+    update: async (id, body) => unwrap(
+      await this.raw.PATCH("/v1/api/tasks/{id}", {
+        params: { path: { id } },
+        body
+      }),
+      this.at("PATCH", `/v1/api/tasks/${id}`)
+    ),
+    listComments: async (id) => unwrap(
+      await this.raw.GET("/v1/api/tasks/{id}/comments", {
+        params: { path: { id } }
+      }),
+      this.at("GET", `/v1/api/tasks/${id}/comments`)
+    ),
+    addComment: async (id, body) => unwrap(
+      await this.raw.POST("/v1/api/tasks/{id}/comments", {
+        params: { path: { id } },
+        body
+      }),
+      this.at("POST", `/v1/api/tasks/${id}/comments`)
+    ),
+    /** The verified review evidence — the same observation QA reviews. */
+    review: async (id) => unwrap(
+      await this.raw.GET("/v1/api/tasks/{id}/review", {
+        params: { path: { id } }
+      }),
+      this.at("GET", `/v1/api/tasks/${id}/review`)
+    ),
+    /** Live status frames. A terminal status closes the stream server-side. */
+    stream: (id, init) => this.stream(`/v1/api/tasks/${id}/stream`, init)
+  };
+  cycles = {
+    list: async (query) => unwrap(
+      await this.raw.GET("/v1/api/cycles", {
+        params: { query: query ?? {} }
+      }),
+      this.at("GET", "/v1/api/cycles")
+    ),
+    get: async (id) => unwrap(
+      await this.raw.GET("/v1/api/cycles/{id}", {
+        params: { path: { id } }
+      }),
+      this.at("GET", `/v1/api/cycles/${id}`)
+    ),
+    /** Creation is a PROPOSAL — the orchestrator owns the roadmap. */
+    propose: async (body) => unwrap(
+      await this.raw.POST("/v1/api/cycles", { body }),
+      this.at("POST", "/v1/api/cycles")
+    ),
+    stream: (id, init) => this.stream(`/v1/api/cycles/${id}/stream`, init)
+  };
+  /**
+   * Invoices the agency issues to its own customer.
+   *
+   * NOT the hlix subscription — that is Polar's, and the two never meet.
+   *
+   * There is no `update`, because there is no route that could edit an issued
+   * invoice: a correction is `void` plus a new draft naming it through
+   * `replacesInvoiceId`. And `create` names no customer — the customer is
+   * derived from the billables being invoiced.
+   */
+  clientInvoices = {
+    list: async (query) => unwrap(
+      await this.raw.GET("/v1/api/client-billing/invoices", {
+        params: { query: query ?? {} }
+      }),
+      this.at("GET", "/v1/api/client-billing/invoices")
+    ),
+    get: async (id) => unwrap(
+      await this.raw.GET("/v1/api/client-billing/invoices/{id}", {
+        params: { path: { id } }
+      }),
+      this.at("GET", `/v1/api/client-billing/invoices/${id}`)
+    ),
+    createDraft: async (body) => unwrap(
+      await this.raw.POST("/v1/api/client-billing/invoices", { body }),
+      this.at("POST", "/v1/api/client-billing/invoices")
+    ),
+    /** The number is assigned by the server, gapless per workspace. */
+    issue: async (id) => unwrap(
+      await this.raw.POST("/v1/api/client-billing/invoices/{id}/issue", {
+        params: { path: { id } },
+        body: {}
+      }),
+      this.at("POST", `/v1/api/client-billing/invoices/${id}/issue`)
+    ),
+    void: async (id, reason) => unwrap(
+      await this.raw.POST("/v1/api/client-billing/invoices/{id}/void", {
+        params: { path: { id } },
+        body: { reason }
+      }),
+      this.at("POST", `/v1/api/client-billing/invoices/${id}/void`)
+    ),
+    pay: async (id) => unwrap(
+      await this.raw.POST("/v1/api/client-billing/invoices/{id}/pay", {
+        params: { path: { id } },
+        body: {}
+      }),
+      this.at("POST", `/v1/api/client-billing/invoices/${id}/pay`)
+    ),
+    /**
+     * Open a PROVIDER-HOSTED checkout. Returns a URL and nothing else — no card
+     * field and no payment credential ever passes through hlix or this client.
+     * It does not mark the invoice paid: that happens only when the provider's
+     * signed webhook reconciles.
+     */
+    paymentLink: async (id, body = {}) => unwrap(
+      await this.raw.POST(
+        "/v1/api/client-billing/invoices/{id}/payment-link",
+        { params: { path: { id } }, body }
+      ),
+      this.at("POST", `/v1/api/client-billing/invoices/${id}/payment-link`)
+    )
+  };
+  /**
+   * Consume any `text/event-stream` route.
+   *
+   * Deliberately NOT routed through the typed client: `openapi-fetch` parses
+   * the body, and a stream must not be parsed — it has to be read as it
+   * arrives. Retry does not apply either; a stream that drops mid-flight has
+   * already delivered events, and silently restarting it would replay them.
+   */
+  async *stream(path, init) {
+    const url = `${this.baseUrl}${path}`;
+    const request = new Request(url, {
+      headers: { ...this.headers, accept: "text/event-stream" },
+      signal: init?.signal
+    });
+    const response = await globalThis.fetch(request);
+    if (!response.ok || !response.body) {
+      let body = null;
+      try {
+        body = await response.json();
+      } catch {
+        body = null;
+      }
+      throw errorForResponse(response, body, { method: "GET", url });
+    }
+    yield* parseSseStream(response.body, init?.signal);
+  }
+};
+function createHlix(options) {
+  return new Hlix(options);
+}
+export {
+  DEFAULT_RETRY,
+  Hlix,
+  HlixAuthenticationError,
+  HlixBadRequestError,
+  HlixConflictError,
+  HlixError,
+  HlixNotFoundError,
+  HlixNotImplementedError,
+  HlixPermissionError,
+  HlixRateLimitError,
+  HlixServerError,
+  HlixTransportError,
+  HlixValidationError,
+  IDEMPOTENT_METHODS,
+  apiKeyCredential,
+  createHlix,
+  isIdempotent,
+  parseSseStream,
+  sessionCredential
+};