contree-client 0.1.0

package/lib/profiles.js

@@ -0,0 +1,159 @@
+/** Contree configuration profiles.
+ *
+ * The INI files under `$CONTREE_HOME`: `auth.ini`
+ * (secrets) merged over `$CONTREE_HOME/cli.ini` (non-secret defaults),
+ * where CONTREE_HOME defaults to `$XDG_CONFIG_HOME/contree` and
+ * finally `~/.config/contree`. Node-only: the filesystem modules are
+ * loaded lazily so browser bundlers never pull them in.
+ */
+
+import { ContreeError } from "./errors.js";
+import { DEFAULT_BASE_URL } from "./specInfo.js";
+
+export const AUTH_TYPE_IAM = "iam";
+export const AUTH_TYPE_JWT = "jwt";
+export const PROFILE_PREFIX = "profile:";
+export const DEFAULT_PROFILE = "default";
+
+export class ProfileError extends ContreeError {}
+
+function record() {
+  // a null-prototype object: keys come from an external file, and a
+  // key like "__proto__" must become plain data, never touch the
+  // prototype chain of anything process-wide
+  return Object.create(null);
+}
+
+/** A minimal INI parser covering the profile-file dialect: `[section]` headers, `key = value` pairs, `#`/`;` comments.
+ * `[DEFAULT]` and keys outside any section land in the "" (defaults)
+ * entry - exactly like ConfigParser's magic DEFAULT section. Returns
+ * a Map of section name to a null-prototype key/value object. */
+export function parseIni(text) {
+  const sections = new Map([["", record()]]);
+  let current = "";
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#") || line.startsWith(";")) {
+      continue;
+    }
+    if (line.startsWith("[") && line.endsWith("]")) {
+      const name = line.slice(1, -1).trim();
+      current = name === "DEFAULT" ? "" : name;
+      if (!sections.has(current)) {
+        sections.set(current, record());
+      }
+      continue;
+    }
+    const eq = line.indexOf("=");
+    if (eq < 0) {
+      continue;
+    }
+    const key = line.slice(0, eq).trim().toLowerCase();
+    sections.get(current)[key] = line.slice(eq + 1).trim();
+  }
+  return sections;
+}
+
+async function contreeHome() {
+  const { homedir } = await import("node:os");
+  const { join } = await import("node:path");
+  const home = process.env.CONTREE_HOME;
+  if (home) {
+    return home;
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(xdg, "contree");
+}
+
+async function readIni(path) {
+  const { readFile } = await import("node:fs/promises");
+  try {
+    return parseIni(await readFile(path, "utf-8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return new Map([["", record()]]);
+    }
+    // a permission or I/O failure must not masquerade as a missing
+    // profile - surface it
+    throw error;
+  }
+}
+
+/** Read all profiles; resolves to `{profiles, active}`.
+ *
+ * `cli.ini` is read first, then `auth.ini` - values from `auth.ini`
+ * win on conflicts. `[DEFAULT]` values are inherited by every profile
+ * section (ConfigParser semantics, like the Python client).
+ */
+export async function loadProfiles(path = null) {
+  const { dirname, join } = await import("node:path");
+  const authFile = path ?? join(await contreeHome(), "auth.ini");
+  const merged = new Map([["", record()]]);
+  for (const file of [join(dirname(authFile), "cli.ini"), authFile]) {
+    for (const [section, values] of await readIni(file)) {
+      const target = merged.get(section) ?? record();
+      Object.assign(target, values);
+      merged.set(section, target);
+    }
+  }
+  const defaults = merged.get("");
+  const active = defaults.profile ?? DEFAULT_PROFILE;
+  const profiles = record();
+  for (const [section, values] of merged) {
+    if (!section.startsWith(PROFILE_PREFIX)) {
+      continue;
+    }
+    const name = section.slice(PROFILE_PREFIX.length);
+    // ConfigParser exposes DEFAULT values through every section
+    const effective = record();
+    Object.assign(effective, defaults, values);
+    const authType = effective.type ?? AUTH_TYPE_JWT;
+    const defaultUrl = authType === AUTH_TYPE_IAM ? DEFAULT_BASE_URL : "";
+    profiles[name] = {
+      name,
+      token: effective.token ?? null,
+      url: (effective.url ?? defaultUrl).replace(/\/+$/, ""),
+      authType,
+      project: effective.project ?? null,
+    };
+  }
+  return { profiles, active };
+}
+
+/** Build a profile from the environment, bypassing config files.
+ *
+ * Reads the standard Contree variables: `CONTREE_TOKEN`
+ * (or `NEBIUS_API_KEY`), `CONTREE_URL` and optionally
+ * `CONTREE_PROJECT` (or `NEBIUS_AI_PROJECT`). Returns null unless
+ * both a token and a URL are present - a non-null result means the
+ * environment fully described a profile.
+ */
+export function fromEnv() {
+  const env = globalThis.process?.env ?? {};
+  const token = env.CONTREE_TOKEN || env.NEBIUS_API_KEY || null;
+  const url = env.CONTREE_URL || null;
+  if (!token || !url) {
+    return null;
+  }
+  return {
+    name: "environment",
+    token,
+    url: url.replace(/\/+$/, ""),
+    authType: AUTH_TYPE_JWT,
+    project: env.CONTREE_PROJECT ?? env.NEBIUS_AI_PROJECT ?? null,
+  };
+}
+
+/** Resolve the active profile by name.
+ *
+ * Priority: explicit *name* > `CONTREE_PROFILE` environment variable
+ * > the active profile recorded in the config file (`[DEFAULT]`).
+ */
+export async function resolveProfile(name = null, { path = null } = {}) {
+  const { profiles, active } = await loadProfiles(path);
+  const selected = name || process.env.CONTREE_PROFILE || active;
+  if (!(selected in profiles)) {
+    throw new ProfileError(`profile ${JSON.stringify(selected)} not found`);
+  }
+  return profiles[selected];
+}

package/lib/runtime.d.ts

@@ -0,0 +1,93 @@
+export declare const CHUNK_SIZE: number;
+export declare const PACKAGE_VERSION: string;
+export declare const UA_PRODUCT: string;
+export declare const IS_NODE: boolean;
+export declare const UA_RUNTIME: string;
+export declare const UA_PLATFORM: string;
+export declare const RETRY_DELAYS: number[];
+export declare const TIGHT_LOOP_FLOOR: number;
+
+export interface ResponseData {
+  status: number;
+  headers: Record<string, string>;
+  body: Uint8Array;
+  /** the final URL after redirects, when the transport reports it */
+  url?: string;
+}
+
+export type RequestBody =
+  Uint8Array | string | Blob | ReadableStream<Uint8Array> | null;
+
+export interface RequestSpec {
+  method: string;
+  path: string;
+  query?: Record<string, string>;
+  headers?: Record<string, string>;
+  body?: RequestBody;
+  contentType?: string | null;
+  accept?: string | null;
+  idempotent?: boolean;
+  redirect?: "manual" | "follow";
+  /** absolute deadline in monotonic seconds; bounds SSE idle waits */
+  deadline?: number | null;
+}
+
+export declare function retryDelays(delays?: number[]): Generator<number>;
+
+export declare class RetryPolicy {
+  statuses: number[];
+  serverErrors: boolean;
+  delays: number[];
+  maxAttempts: number | null;
+  retryUnsafe: boolean;
+  constructor(options?: {
+    statuses?: number[];
+    serverErrors?: boolean;
+    delays?: number[];
+    maxAttempts?: number | null;
+    retryUnsafe?: boolean;
+  });
+  retryableStatus(status: number): boolean;
+}
+
+export declare function parseRetryAfter(
+  value: string | null | undefined,
+): number | null;
+export declare function retryAfterDelay(response: ResponseData): number | null;
+export declare function sleep(seconds: number): Promise<void>;
+export declare function monotonic(): number;
+export declare function isUuid(ref: string): boolean;
+export declare function quotePath(value: unknown): string;
+export declare function encodeQuery(query: Record<string, string>): string;
+export declare function formatTimeParam(value: string | number | Date): string;
+export declare function parseDatetime(value: string): Date;
+export declare function bytesToText(bytes: Uint8Array): string;
+export declare function textToBytes(text: string): Uint8Array;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(value: string): Uint8Array;
+export declare function sha256(
+  content: Uint8Array | string | Blob | ReadableStream<Uint8Array>,
+): Promise<string | null>;
+export declare function jsonBody(response: ResponseData): unknown;
+export declare function jsonObject(
+  response: ResponseData,
+): Record<string, unknown>;
+export declare function jsonArray(response: ResponseData): unknown[];
+export declare function errorForResponse(response: ResponseData): Error;
+
+export interface SSEFrame {
+  id: number | null;
+  event: string | null;
+  data: string;
+}
+
+export declare class SSEParser {
+  static MAX_BUFFER: number;
+  feed(chunk: Uint8Array): SSEFrame[];
+  flush(): SSEFrame | null;
+}
+
+export declare function decodeFramePayload(
+  frame: SSEFrame,
+  lastEventId?: number | null,
+): Record<string, unknown> | null;

package/lib/runtime.js

@@ -0,0 +1,415 @@
+/** Transport-agnostic request/response plumbing and SSE parsing.
+ *
+ * A line-by-line port of contree_client/runtime.py adapted to the
+ * fetch platform: gzip decoding and connection pooling are handled by
+ * fetch itself, so only the protocol logic lives here.
+ */
+
+import {
+  ContreeAPIError,
+  ERROR_CLASSES,
+  ServerError,
+  SSEStreamError,
+} from "./errors.js";
+
+export const CHUNK_SIZE = 65536;
+
+export const PACKAGE_VERSION = "0.1.0";
+export const UA_PRODUCT = `contree-client-js/${PACKAGE_VERSION}`;
+
+const NODE_VERSION =
+  typeof process !== "undefined" && process.versions?.node
+    ? process.versions.node
+    : null;
+// browsers refuse to set the User-Agent header (a forbidden header
+// name): the composed string is only ATTACHED as a header in Node,
+// though userAgent() reports it everywhere
+export const IS_NODE = NODE_VERSION !== null;
+export const UA_RUNTIME =
+  NODE_VERSION !== null ? `Node.js/${NODE_VERSION}` : "browser";
+export const UA_PLATFORM =
+  NODE_VERSION !== null
+    ? `${process.platform}-${process.arch}`
+    : (globalThis.navigator?.userAgent ?? "");
+
+export const RETRY_DELAYS = Object.freeze([0.1, 0.2, 0.5, 1.0, 2.0, 5.0]);
+
+// floor for reconnect loops that made no forward progress, so a server
+// returning immediate empty streams does not spin the client
+export const TIGHT_LOOP_FLOOR = 0.5;
+
+/** An endless ladder of backoff delays: the ladder is walked once and
+ * then the tail delay repeats forever. */
+export function* retryDelays(delays = RETRY_DELAYS) {
+  yield* delays;
+  for (;;) {
+    yield delays[delays.length - 1];
+  }
+}
+
+/** Opt-in retries for transient failures of buffered requests. */
+export class RetryPolicy {
+  constructor({
+    statuses = [410, 425],
+    serverErrors = true,
+    delays = RETRY_DELAYS,
+    maxAttempts = 10,
+    retryUnsafe = false,
+  } = {}) {
+    if (!delays.length) {
+      throw new RangeError("RetryPolicy delays must not be empty");
+    }
+    for (const delay of delays) {
+      if (!Number.isFinite(delay) || delay < 0) {
+        throw new RangeError(
+          `RetryPolicy delays must be finite and non-negative, got ${delay}`,
+        );
+      }
+    }
+    if (
+      maxAttempts !== null &&
+      (!Number.isInteger(maxAttempts) || maxAttempts < 1)
+    ) {
+      throw new RangeError("RetryPolicy maxAttempts must be an integer >= 1");
+    }
+    // defensive copies, frozen: a policy shared between clients must
+    // not be mutable from the outside after validation
+    this.statuses = Object.freeze([...statuses]);
+    this.serverErrors = serverErrors;
+    this.delays = Object.freeze([...delays]);
+    this.maxAttempts = maxAttempts;
+    this.retryUnsafe = retryUnsafe;
+    Object.freeze(this);
+  }
+
+  retryableStatus(status) {
+    if (this.statuses.includes(status)) {
+      return true;
+    }
+    return this.serverErrors && status >= 500 && status < 600;
+  }
+}
+
+/** Parse a Retry-After header: delta-seconds or an HTTP-date.
+ * Negative values clamp to 0; anything unparsable reports null. */
+export function parseRetryAfter(value) {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  const seconds = Number(value);
+  // Number("Infinity") parses: an infinite Retry-After would sleep
+  // forever (or collapse into an immediate retry storm)
+  if (Number.isFinite(seconds) && value.trim() !== "") {
+    return Math.max(0, seconds);
+  }
+  const moment = Date.parse(value);
+  if (Number.isNaN(moment)) {
+    return null;
+  }
+  return Math.max(0, (moment - Date.now()) / 1000);
+}
+
+export function retryAfterDelay(response) {
+  return parseRetryAfter(response.headers["retry-after"] ?? null);
+}
+
+export function sleep(seconds) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
+
+export function monotonic() {
+  return performance.now() / 1000;
+}
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** True if *ref* looks like an image/operation UUID. */
+export function isUuid(ref) {
+  return UUID_RE.test(ref);
+}
+
+export function quotePath(value) {
+  return encodeURIComponent(String(value));
+}
+
+export function encodeQuery(query) {
+  return Object.entries(query)
+    .map(
+      ([key, value]) =>
+        `${encodeURIComponent(key)}=${encodeURIComponent(value).replaceAll("%2F", "/")}`,
+    )
+    .join("&");
+}
+
+export function formatTimeParam(value) {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return String(value);
+}
+
+/** Parse an ISO 8601 timestamp, tolerating nanosecond precision. */
+export function parseDatetime(value) {
+  // Date.parse only accepts millisecond precision: trim the tail
+  const trimmed = value.replace(/(\.\d{3})\d+/, "$1");
+  const moment = new Date(trimmed);
+  if (Number.isNaN(moment.getTime())) {
+    throw new RangeError(`unparsable datetime: ${value}`);
+  }
+  return moment;
+}
+
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+
+export function bytesToText(bytes) {
+  return textDecoder.decode(bytes);
+}
+
+export function textToBytes(text) {
+  return textEncoder.encode(text);
+}
+
+export function bytesToBase64(bytes) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+export function base64ToBytes(value) {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(value, "base64"));
+  }
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+/** The sha256 hexdigest of an upload payload.
+ *
+ * Accepts Uint8Array, string or Blob; a ReadableStream cannot be
+ * re-read for the subsequent upload, so it reports null (the caller
+ * skips deduplication). Blobs hash chunk by chunk in Node (10 GiB
+ * must not materialize); browsers fall back to one arrayBuffer().
+ */
+export async function sha256(content) {
+  if (typeof content === "string") {
+    content = textToBytes(content);
+  }
+  if (content instanceof Uint8Array) {
+    // the webcrypto global only appeared in Node 19: fall back to
+    // node:crypto on Node 18 (browsers always have globalThis.crypto)
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined) {
+      const { createHash } = await import("node:crypto");
+      return createHash("sha256").update(content).digest("hex");
+    }
+    const digest = await subtle.digest("SHA-256", content);
+    return hex(new Uint8Array(digest));
+  }
+  if (typeof Blob !== "undefined" && content instanceof Blob) {
+    if (NODE_VERSION !== null) {
+      // node-only module, loaded lazily so browser bundlers never see it
+      const { createHash } = await import("node:crypto");
+      const digest = createHash("sha256");
+      for await (const chunk of content.stream()) {
+        digest.update(chunk);
+      }
+      return digest.digest("hex");
+    }
+    const digest = await globalThis.crypto.subtle.digest(
+      "SHA-256",
+      await content.arrayBuffer(),
+    );
+    return hex(new Uint8Array(digest));
+  }
+  return null;
+}
+
+function hex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(
+    "",
+  );
+}
+
+export function jsonBody(response) {
+  return JSON.parse(bytesToText(response.body));
+}
+
+export function jsonObject(response) {
+  const data = jsonBody(response);
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    throw new ContreeAPIError(response.status, "expected a JSON object");
+  }
+  return data;
+}
+
+export function jsonArray(response) {
+  const data = jsonBody(response);
+  if (!Array.isArray(data)) {
+    throw new ContreeAPIError(response.status, "expected a JSON array");
+  }
+  return data;
+}
+
+/** Build the exception matching an error response. */
+export function errorForResponse(response) {
+  let error = bytesToText(response.body);
+  let traceback = null;
+  let payload = null;
+  try {
+    payload = JSON.parse(error);
+  } catch {
+    payload = null;
+  }
+  if (
+    payload !== null &&
+    typeof payload === "object" &&
+    !Array.isArray(payload)
+  ) {
+    error = payload.error ?? error;
+    if (Array.isArray(payload.traceback)) {
+      traceback = payload.traceback.map(String);
+    }
+  }
+  const parsedRetry = parseRetryAfter(response.headers["retry-after"] ?? null);
+  const retryAfter = parsedRetry === null ? null : Math.trunc(parsedRetry);
+  let cls = ERROR_CLASSES.get(response.status);
+  if (cls === undefined) {
+    cls = response.status >= 500 ? ServerError : ContreeAPIError;
+  }
+  return new cls(response.status, error, { traceback, retryAfter });
+}
+
+/** Incremental sans-io parser for `text/event-stream` bytes.
+ *
+ * Feed raw chunks, get complete frames `{id, event, data}` back.
+ * Comment lines (`: keepalive`) are discarded per the SSE spec.
+ */
+export class SSEParser {
+  // a single SSE line/frame has no business being this large; the
+  // cap keeps a misbehaving peer from growing the buffer unbounded
+  static MAX_BUFFER = 4 * 1024 * 1024;
+
+  constructor() {
+    this.decoder = new TextDecoder();
+    this.buffer = "";
+    this.event = null;
+    this.eventId = null;
+    this.dataLines = [];
+    this.pendingSize = 0;
+    this.dirty = false;
+  }
+
+  feed(chunk) {
+    this.buffer += this.decoder.decode(chunk, { stream: true });
+    // the cap covers BOTH the unterminated line and the frame
+    // accumulated so far: many short data lines must not grow the
+    // pending event unboundedly
+    if (this.buffer.length + this.pendingSize > SSEParser.MAX_BUFFER) {
+      throw new SSEStreamError(
+        `SSE frame exceeds ${SSEParser.MAX_BUFFER} bytes before completion`,
+      );
+    }
+    const frames = [];
+    for (;;) {
+      const newline = this.buffer.indexOf("\n");
+      if (newline < 0) {
+        break;
+      }
+      let line = this.buffer.slice(0, newline);
+      this.buffer = this.buffer.slice(newline + 1);
+      if (line.endsWith("\r")) {
+        line = line.slice(0, -1);
+      }
+      if (!line) {
+        const frame = this.flush();
+        if (frame !== null) {
+          frames.push(frame);
+        }
+        continue;
+      }
+      if (line.startsWith(":")) {
+        continue;
+      }
+      const colon = line.indexOf(":");
+      const name = colon < 0 ? line : line.slice(0, colon);
+      let value = colon < 0 ? "" : line.slice(colon + 1);
+      if (value.startsWith(" ")) {
+        value = value.slice(1);
+      }
+      this.dirty = true;
+      if (name === "id") {
+        const parsed = Number.parseInt(value, 10);
+        this.eventId = Number.isNaN(parsed) ? null : parsed;
+      } else if (name === "event") {
+        this.event = value;
+      } else if (name === "data") {
+        this.dataLines.push(value);
+        this.pendingSize += value.length;
+      }
+    }
+    return frames;
+  }
+
+  /** Return the pending frame, if any, and reset the state. */
+  flush() {
+    if (!this.dirty) {
+      return null;
+    }
+    const frame = {
+      id: this.eventId,
+      event: this.event,
+      data: this.dataLines.join("\n"),
+    };
+    this.event = null;
+    this.eventId = null;
+    this.dataLines = [];
+    this.pendingSize = 0;
+    this.dirty = false;
+    return frame;
+  }
+}
+
+/** Decode an SSE frame's JSON payload.
+ *
+ * Raises SSEStreamError for in-band `sse_error` frames, carrying
+ * *lastEventId* so the caller can reconnect from that point; returns
+ * null for frames that carry no event payload. The caller turns the
+ * plain object into a typed OperationEvent.
+ */
+export function decodeFramePayload(frame, lastEventId = null) {
+  if (frame.event === "sse_error") {
+    throw new SSEStreamError(frame.data, { lastEventId });
+  }
+  if (!frame.data) {
+    return null;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(frame.data);
+  } catch (error) {
+    // surface protocol corruption through the SSE error channel so
+    // followOperationEvents reconnects instead of crashing
+    throw new SSEStreamError(`malformed SSE event payload: ${error}`, {
+      lastEventId,
+    });
+  }
+  if (
+    payload === null ||
+    typeof payload !== "object" ||
+    Array.isArray(payload)
+  ) {
+    return null;
+  }
+  return payload;
+}

package/lib/specInfo.d.ts

@@ -0,0 +1,4 @@
+// Generated by codegen from the OpenAPI spec - do not edit.
+
+export declare const DEFAULT_BASE_URL: string;
+export declare const SPEC_SHA256: string;

package/lib/specInfo.js

@@ -0,0 +1,8 @@
+// Generated by codegen from the OpenAPI spec - do not edit.
+
+export const DEFAULT_BASE_URL = "https://api.tokenfactory.nebius.com/sandboxes";
+
+// sha256 of the exact OpenAPI document this package was built
+// from - the build input provenance
+export const SPEC_SHA256 =
+  "3782df855d7ae14556e221f4f37a67fb6aeb65121396cb009a5e7a0995abd06b";