@opendray/sdk 2.6.0

package/dist/index.d.cts

@@ -0,0 +1,209 @@
+type Iso8601 = string;
+type IntegrationScope = string;
+interface Integration {
+    id: string;
+    name: string;
+    base_url?: string;
+    route_prefix: string;
+    scopes: IntegrationScope[];
+    version: string;
+    enabled: boolean;
+    created_at: Iso8601;
+    last_health_check?: Iso8601;
+    health_status?: "ok" | "degraded" | "down" | "unknown";
+}
+interface IntegrationRegistration {
+    name: string;
+    base_url?: string;
+    route_prefix: string;
+    scopes: IntegrationScope[];
+    version: string;
+}
+interface IntegrationCreated extends Integration {
+    /** Plaintext API key. Returned exactly once. */
+    api_key: string;
+}
+interface IntegrationUpdate {
+    base_url?: string;
+    scopes?: IntegrationScope[];
+    version?: string;
+    enabled?: boolean;
+}
+type SessionState = "starting" | "running" | "idle" | "ended" | "errored";
+interface Session {
+    id: string;
+    provider: string;
+    state: SessionState;
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+    created_at: Iso8601;
+    last_activity_at?: Iso8601;
+    ended_at?: Iso8601;
+    exit_code?: number;
+}
+interface SessionCreateRequest {
+    provider: string;
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+    env?: Record<string, string>;
+}
+interface SessionInputRequest {
+    /** Raw bytes to write to the PTY's stdin. */
+    data: string;
+}
+interface SessionResizeRequest {
+    cols: number;
+    rows: number;
+}
+interface SessionBuffer {
+    /** Ring-buffer replay of recent terminal output. */
+    data: string;
+    truncated: boolean;
+}
+interface Provider {
+    id: string;
+    name: string;
+    command: string;
+    config?: Record<string, unknown>;
+    available: boolean;
+}
+interface Channel {
+    id: string;
+    kind: string;
+    label: string;
+    enabled: boolean;
+}
+interface EventFrame<T = unknown> {
+    topic: string;
+    ts: Iso8601;
+    data: T;
+}
+interface SessionOutputData {
+    session_id: string;
+    data: string;
+}
+interface SessionEndedData {
+    session_id: string;
+    exit_code?: number;
+    reason?: string;
+}
+interface SessionIdleData {
+    session_id: string;
+    idle_for_ms: number;
+}
+
+interface ClientOptions {
+    /** Base URL of the gateway, e.g. `https://opendray.example.com`. */
+    baseUrl: string;
+    /** Admin bearer token or integration API key (`odk_live_…`). */
+    token: string;
+    /** Optional custom fetch (e.g. for proxying or instrumentation). */
+    fetch?: typeof fetch;
+    /** Default request timeout in ms. 30s if omitted. 0 disables. */
+    timeoutMs?: number;
+}
+declare class OpendrayError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message: string);
+}
+declare class Client {
+    readonly baseUrl: string;
+    readonly token: string;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: ClientOptions);
+    private request;
+    registerIntegration(input: IntegrationRegistration): Promise<IntegrationCreated>;
+    listIntegrations(): Promise<Integration[]>;
+    getIntegration(id: string): Promise<Integration>;
+    updateIntegration(id: string, patch: IntegrationUpdate): Promise<Integration>;
+    deleteIntegration(id: string): Promise<void>;
+    rotateIntegrationKey(id: string): Promise<IntegrationCreated>;
+    createSession(input: SessionCreateRequest): Promise<Session>;
+    listSessions(): Promise<Session[]>;
+    getSession(id: string): Promise<Session>;
+    deleteSession(id: string): Promise<void>;
+    sendInput(id: string, input: SessionInputRequest): Promise<void>;
+    resizeSession(id: string, size: SessionResizeRequest): Promise<void>;
+    getSessionBuffer(id: string): Promise<SessionBuffer>;
+    listProviders(): Promise<Provider[]>;
+    setProviderConfig(id: string, config: Record<string, unknown>): Promise<Provider>;
+    listChannels(): Promise<Channel[]>;
+    /**
+     * Compose the WS URL for the events stream. Used by `subscribeEvents`,
+     * exposed publicly for callers that want to manage the socket lifecycle
+     * themselves.
+     */
+    eventsUrl(topics: string[]): string;
+    sessionStreamUrl(id: string): string;
+}
+
+interface SubscribeOptions {
+    /** Topic patterns. Use `session.*` for prefix wildcards. */
+    topics: string[];
+    /** AbortSignal closes the socket and ends the iterator. */
+    signal?: AbortSignal;
+    /**
+     * Custom WebSocket implementation. Defaults to globalThis.WebSocket.
+     * On Node <22 you'll need to pass `ws`'s default export.
+     */
+    WebSocket?: typeof globalThis.WebSocket;
+    /** Reconnect on unexpected close. Defaults to true. */
+    reconnect?: boolean;
+    /** Initial backoff in ms (doubles up to 30s). Defaults to 1000. */
+    reconnectBaseMs?: number;
+}
+/**
+ * Returns an async iterable that yields one EventFrame per server message.
+ * Reconnects automatically on transient drops; an AbortSignal ends the
+ * stream cleanly.
+ *
+ * ```ts
+ * for await (const frame of subscribeEvents(client, { topics: ["session.*"] })) {
+ *   console.log(frame.topic, frame.data);
+ * }
+ * ```
+ */
+declare function subscribeEvents<T = unknown>(client: Client, opts: SubscribeOptions): AsyncGenerator<EventFrame<T>, void, void>;
+
+interface SessionStreamHandle {
+    /** Send raw bytes to the session's PTY stdin. */
+    send(data: string): void;
+    /** Close the stream. */
+    close(): void;
+    /** Resolves when the socket closes (cleanly or with an error). */
+    readonly closed: Promise<void>;
+}
+interface SessionStreamOptions {
+    /** Called with each chunk of terminal output. */
+    onOutput?: (data: string) => void;
+    /** Called when the server reports the session has ended. */
+    onEnded?: (info: {
+        exitCode?: number | undefined;
+        reason?: string | undefined;
+    }) => void;
+    /** AbortSignal closes the socket. */
+    signal?: AbortSignal;
+    /**
+     * Custom WebSocket implementation. Defaults to globalThis.WebSocket.
+     * On Node <22 pass `ws`'s default export.
+     */
+    WebSocket?: typeof globalThis.WebSocket;
+}
+/**
+ * Open a bidirectional terminal stream against the given session.
+ *
+ * The wire format is gateway-specific JSON frames:
+ *   { kind: "output", data: "<chunk>" }   (server → client)
+ *   { kind: "ended", exit_code?, reason? } (server → client)
+ *   { kind: "input",  data: "<chunk>" }    (client → server)
+ *
+ * The returned handle exposes `send()` and `close()`, and a `closed`
+ * promise that resolves when the socket finishes.
+ */
+declare function streamSession(client: Client, sessionId: string, opts?: SessionStreamOptions): SessionStreamHandle;
+
+export { type Channel, Client, type ClientOptions, type EventFrame, type Integration, type IntegrationCreated, type IntegrationRegistration, type IntegrationScope, type IntegrationUpdate, type Iso8601, OpendrayError, type Provider, type Session, type SessionBuffer, type SessionCreateRequest, type SessionEndedData, type SessionIdleData, type SessionInputRequest, type SessionOutputData, type SessionResizeRequest, type SessionState, type SessionStreamHandle, type SessionStreamOptions, type SubscribeOptions, streamSession, subscribeEvents };

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+type Iso8601 = string;
+type IntegrationScope = string;
+interface Integration {
+    id: string;
+    name: string;
+    base_url?: string;
+    route_prefix: string;
+    scopes: IntegrationScope[];
+    version: string;
+    enabled: boolean;
+    created_at: Iso8601;
+    last_health_check?: Iso8601;
+    health_status?: "ok" | "degraded" | "down" | "unknown";
+}
+interface IntegrationRegistration {
+    name: string;
+    base_url?: string;
+    route_prefix: string;
+    scopes: IntegrationScope[];
+    version: string;
+}
+interface IntegrationCreated extends Integration {
+    /** Plaintext API key. Returned exactly once. */
+    api_key: string;
+}
+interface IntegrationUpdate {
+    base_url?: string;
+    scopes?: IntegrationScope[];
+    version?: string;
+    enabled?: boolean;
+}
+type SessionState = "starting" | "running" | "idle" | "ended" | "errored";
+interface Session {
+    id: string;
+    provider: string;
+    state: SessionState;
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+    created_at: Iso8601;
+    last_activity_at?: Iso8601;
+    ended_at?: Iso8601;
+    exit_code?: number;
+}
+interface SessionCreateRequest {
+    provider: string;
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+    env?: Record<string, string>;
+}
+interface SessionInputRequest {
+    /** Raw bytes to write to the PTY's stdin. */
+    data: string;
+}
+interface SessionResizeRequest {
+    cols: number;
+    rows: number;
+}
+interface SessionBuffer {
+    /** Ring-buffer replay of recent terminal output. */
+    data: string;
+    truncated: boolean;
+}
+interface Provider {
+    id: string;
+    name: string;
+    command: string;
+    config?: Record<string, unknown>;
+    available: boolean;
+}
+interface Channel {
+    id: string;
+    kind: string;
+    label: string;
+    enabled: boolean;
+}
+interface EventFrame<T = unknown> {
+    topic: string;
+    ts: Iso8601;
+    data: T;
+}
+interface SessionOutputData {
+    session_id: string;
+    data: string;
+}
+interface SessionEndedData {
+    session_id: string;
+    exit_code?: number;
+    reason?: string;
+}
+interface SessionIdleData {
+    session_id: string;
+    idle_for_ms: number;
+}
+
+interface ClientOptions {
+    /** Base URL of the gateway, e.g. `https://opendray.example.com`. */
+    baseUrl: string;
+    /** Admin bearer token or integration API key (`odk_live_…`). */
+    token: string;
+    /** Optional custom fetch (e.g. for proxying or instrumentation). */
+    fetch?: typeof fetch;
+    /** Default request timeout in ms. 30s if omitted. 0 disables. */
+    timeoutMs?: number;
+}
+declare class OpendrayError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message: string);
+}
+declare class Client {
+    readonly baseUrl: string;
+    readonly token: string;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: ClientOptions);
+    private request;
+    registerIntegration(input: IntegrationRegistration): Promise<IntegrationCreated>;
+    listIntegrations(): Promise<Integration[]>;
+    getIntegration(id: string): Promise<Integration>;
+    updateIntegration(id: string, patch: IntegrationUpdate): Promise<Integration>;
+    deleteIntegration(id: string): Promise<void>;
+    rotateIntegrationKey(id: string): Promise<IntegrationCreated>;
+    createSession(input: SessionCreateRequest): Promise<Session>;
+    listSessions(): Promise<Session[]>;
+    getSession(id: string): Promise<Session>;
+    deleteSession(id: string): Promise<void>;
+    sendInput(id: string, input: SessionInputRequest): Promise<void>;
+    resizeSession(id: string, size: SessionResizeRequest): Promise<void>;
+    getSessionBuffer(id: string): Promise<SessionBuffer>;
+    listProviders(): Promise<Provider[]>;
+    setProviderConfig(id: string, config: Record<string, unknown>): Promise<Provider>;
+    listChannels(): Promise<Channel[]>;
+    /**
+     * Compose the WS URL for the events stream. Used by `subscribeEvents`,
+     * exposed publicly for callers that want to manage the socket lifecycle
+     * themselves.
+     */
+    eventsUrl(topics: string[]): string;
+    sessionStreamUrl(id: string): string;
+}
+
+interface SubscribeOptions {
+    /** Topic patterns. Use `session.*` for prefix wildcards. */
+    topics: string[];
+    /** AbortSignal closes the socket and ends the iterator. */
+    signal?: AbortSignal;
+    /**
+     * Custom WebSocket implementation. Defaults to globalThis.WebSocket.
+     * On Node <22 you'll need to pass `ws`'s default export.
+     */
+    WebSocket?: typeof globalThis.WebSocket;
+    /** Reconnect on unexpected close. Defaults to true. */
+    reconnect?: boolean;
+    /** Initial backoff in ms (doubles up to 30s). Defaults to 1000. */
+    reconnectBaseMs?: number;
+}
+/**
+ * Returns an async iterable that yields one EventFrame per server message.
+ * Reconnects automatically on transient drops; an AbortSignal ends the
+ * stream cleanly.
+ *
+ * ```ts
+ * for await (const frame of subscribeEvents(client, { topics: ["session.*"] })) {
+ *   console.log(frame.topic, frame.data);
+ * }
+ * ```
+ */
+declare function subscribeEvents<T = unknown>(client: Client, opts: SubscribeOptions): AsyncGenerator<EventFrame<T>, void, void>;
+
+interface SessionStreamHandle {
+    /** Send raw bytes to the session's PTY stdin. */
+    send(data: string): void;
+    /** Close the stream. */
+    close(): void;
+    /** Resolves when the socket closes (cleanly or with an error). */
+    readonly closed: Promise<void>;
+}
+interface SessionStreamOptions {
+    /** Called with each chunk of terminal output. */
+    onOutput?: (data: string) => void;
+    /** Called when the server reports the session has ended. */
+    onEnded?: (info: {
+        exitCode?: number | undefined;
+        reason?: string | undefined;
+    }) => void;
+    /** AbortSignal closes the socket. */
+    signal?: AbortSignal;
+    /**
+     * Custom WebSocket implementation. Defaults to globalThis.WebSocket.
+     * On Node <22 pass `ws`'s default export.
+     */
+    WebSocket?: typeof globalThis.WebSocket;
+}
+/**
+ * Open a bidirectional terminal stream against the given session.
+ *
+ * The wire format is gateway-specific JSON frames:
+ *   { kind: "output", data: "<chunk>" }   (server → client)
+ *   { kind: "ended", exit_code?, reason? } (server → client)
+ *   { kind: "input",  data: "<chunk>" }    (client → server)
+ *
+ * The returned handle exposes `send()` and `close()`, and a `closed`
+ * promise that resolves when the socket finishes.
+ */
+declare function streamSession(client: Client, sessionId: string, opts?: SessionStreamOptions): SessionStreamHandle;
+
+export { type Channel, Client, type ClientOptions, type EventFrame, type Integration, type IntegrationCreated, type IntegrationRegistration, type IntegrationScope, type IntegrationUpdate, type Iso8601, OpendrayError, type Provider, type Session, type SessionBuffer, type SessionCreateRequest, type SessionEndedData, type SessionIdleData, type SessionInputRequest, type SessionOutputData, type SessionResizeRequest, type SessionState, type SessionStreamHandle, type SessionStreamOptions, type SubscribeOptions, streamSession, subscribeEvents };

package/dist/index.js

@@ -0,0 +1,287 @@
+// src/client.ts
+var OpendrayError = class extends Error {
+  status;
+  body;
+  constructor(status, body, message) {
+    super(message);
+    this.name = "OpendrayError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var Client = class {
+  baseUrl;
+  token;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts) {
+    if (!opts.baseUrl) throw new Error("Client: baseUrl is required");
+    if (!opts.token) throw new Error("Client: token is required");
+    let trimmed = opts.baseUrl;
+    while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+    this.baseUrl = trimmed;
+    this.token = opts.token;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    if (!this.fetchImpl) {
+      throw new Error(
+        "Client: no fetch available \u2014 pass `fetch` in options on platforms older than Node 18."
+      );
+    }
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  // ── low level ──────────────────────────────────────────────────────
+  async request(method, path, body) {
+    const url = `${this.baseUrl}/api/v1${path}`;
+    const headers = {
+      Authorization: `Bearer ${this.token}`,
+      Accept: "application/json"
+    };
+    let payload;
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+    const ctrl = this.timeoutMs > 0 ? new AbortController() : null;
+    const timer = ctrl ? setTimeout(() => ctrl.abort(new Error("request timed out")), this.timeoutMs) : null;
+    const init = { method, headers };
+    if (payload !== void 0) init.body = payload;
+    if (ctrl) init.signal = ctrl.signal;
+    try {
+      const res = await this.fetchImpl(url, init);
+      const text = await res.text();
+      let parsed = void 0;
+      if (text.length > 0) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = text;
+        }
+      }
+      if (!res.ok) {
+        const msg = (parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : void 0) ?? `${method} ${path} -> ${res.status}`;
+        throw new OpendrayError(res.status, parsed, msg);
+      }
+      return parsed;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  // ── integrations (admin-only) ──────────────────────────────────────
+  registerIntegration(input) {
+    return this.request("POST", "/integrations", input);
+  }
+  listIntegrations() {
+    return this.request("GET", "/integrations");
+  }
+  getIntegration(id) {
+    return this.request("GET", `/integrations/${encodeURIComponent(id)}`);
+  }
+  updateIntegration(id, patch) {
+    return this.request("PATCH", `/integrations/${encodeURIComponent(id)}`, patch);
+  }
+  deleteIntegration(id) {
+    return this.request("DELETE", `/integrations/${encodeURIComponent(id)}`);
+  }
+  rotateIntegrationKey(id) {
+    return this.request("POST", `/integrations/${encodeURIComponent(id)}/rotate-key`);
+  }
+  // ── sessions (dual-auth) ───────────────────────────────────────────
+  createSession(input) {
+    return this.request("POST", "/sessions", input);
+  }
+  listSessions() {
+    return this.request("GET", "/sessions");
+  }
+  getSession(id) {
+    return this.request("GET", `/sessions/${encodeURIComponent(id)}`);
+  }
+  deleteSession(id) {
+    return this.request("DELETE", `/sessions/${encodeURIComponent(id)}`);
+  }
+  sendInput(id, input) {
+    return this.request("POST", `/sessions/${encodeURIComponent(id)}/input`, input);
+  }
+  resizeSession(id, size) {
+    return this.request("POST", `/sessions/${encodeURIComponent(id)}/resize`, size);
+  }
+  getSessionBuffer(id) {
+    return this.request("GET", `/sessions/${encodeURIComponent(id)}/buffer`);
+  }
+  // ── providers / channels (dual-auth) ───────────────────────────────
+  listProviders() {
+    return this.request("GET", "/providers");
+  }
+  setProviderConfig(id, config) {
+    return this.request(
+      "PATCH",
+      `/providers/${encodeURIComponent(id)}/config`,
+      config
+    );
+  }
+  listChannels() {
+    return this.request("GET", "/channels");
+  }
+  // ── ws helpers (URLs only — open via subscribeEvents / streamSession) ─
+  /**
+   * Compose the WS URL for the events stream. Used by `subscribeEvents`,
+   * exposed publicly for callers that want to manage the socket lifecycle
+   * themselves.
+   */
+  eventsUrl(topics) {
+    const u = new URL(`${this.baseUrl}/api/v1/integrations/_events`);
+    u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+    u.searchParams.set("token", this.token);
+    if (topics.length > 0) u.searchParams.set("topics", topics.join(","));
+    return u.toString();
+  }
+  sessionStreamUrl(id) {
+    const u = new URL(
+      `${this.baseUrl}/api/v1/sessions/${encodeURIComponent(id)}/stream`
+    );
+    u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+    u.searchParams.set("token", this.token);
+    return u.toString();
+  }
+};
+
+// src/events.ts
+async function* subscribeEvents(client, opts) {
+  const WS = opts.WebSocket ?? globalThis.WebSocket;
+  if (!WS) {
+    throw new Error(
+      "subscribeEvents: no WebSocket available. On Node <22 import 'ws' and pass it via `WebSocket`."
+    );
+  }
+  const url = client.eventsUrl(opts.topics);
+  const reconnect = opts.reconnect ?? true;
+  const baseDelay = opts.reconnectBaseMs ?? 1e3;
+  let attempt = 0;
+  while (true) {
+    if (opts.signal?.aborted) return;
+    const queue = [];
+    let resolve = null;
+    let closed = false;
+    let closeReason = null;
+    const ws = new WS(url);
+    ws.addEventListener("message", (ev) => {
+      try {
+        const frame = JSON.parse(String(ev.data));
+        queue.push(frame);
+        if (resolve) {
+          const r = resolve;
+          resolve = null;
+          r();
+        }
+      } catch (err) {
+        closeReason = err instanceof Error ? err : new Error(String(err));
+        try {
+          ws.close();
+        } catch {
+        }
+      }
+    });
+    ws.addEventListener("close", () => {
+      closed = true;
+      if (resolve) {
+        const r = resolve;
+        resolve = null;
+        r();
+      }
+    });
+    ws.addEventListener("error", (ev) => {
+      closeReason = new Error(`websocket error: ${ev.message ?? "unknown"}`);
+    });
+    const onAbort = () => {
+      try {
+        ws.close();
+      } catch {
+      }
+    };
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      while (!closed) {
+        while (queue.length > 0) {
+          const frame = queue.shift();
+          yield frame;
+          attempt = 0;
+        }
+        if (closed) break;
+        await new Promise((r) => {
+          resolve = r;
+        });
+      }
+    } finally {
+      opts.signal?.removeEventListener("abort", onAbort);
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+    if (opts.signal?.aborted) return;
+    if (closeReason) throw closeReason;
+    if (!reconnect) return;
+    attempt += 1;
+    const delay = Math.min(3e4, baseDelay * 2 ** (attempt - 1));
+    await new Promise((r) => setTimeout(r, delay));
+  }
+}
+
+// src/session.ts
+function streamSession(client, sessionId, opts = {}) {
+  const WS = opts.WebSocket ?? globalThis.WebSocket;
+  if (!WS) {
+    throw new Error(
+      "streamSession: no WebSocket available. On Node <22 import 'ws' and pass it via `WebSocket`."
+    );
+  }
+  const ws = new WS(client.sessionStreamUrl(sessionId));
+  let resolveClosed;
+  const closed = new Promise((r) => {
+    resolveClosed = r;
+  });
+  ws.addEventListener("message", (ev) => {
+    let frame;
+    try {
+      frame = JSON.parse(String(ev.data));
+    } catch {
+      return;
+    }
+    if (frame.kind === "output" && typeof frame.data === "string") {
+      opts.onOutput?.(frame.data);
+    } else if (frame.kind === "ended") {
+      opts.onEnded?.({ exitCode: frame.exit_code, reason: frame.reason });
+    }
+  });
+  ws.addEventListener("close", () => {
+    resolveClosed();
+  });
+  const onAbort = () => {
+    try {
+      ws.close();
+    } catch {
+    }
+  };
+  opts.signal?.addEventListener("abort", onAbort, { once: true });
+  return {
+    send(data) {
+      if (ws.readyState !== WS.OPEN) {
+        throw new Error("streamSession: socket not open");
+      }
+      ws.send(JSON.stringify({ kind: "input", data }));
+    },
+    close() {
+      try {
+        ws.close();
+      } catch {
+      }
+    },
+    closed
+  };
+}
+export {
+  Client,
+  OpendrayError,
+  streamSession,
+  subscribeEvents
+};
+//# sourceMappingURL=index.js.map