@smithers-orchestrator/gateway-client 0.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@smithers-orchestrator/gateway-client",
+  "version": "0.18.0",
+  "description": "Browser-first client SDK for the Smithers Gateway RPC and event stream APIs",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "import": "./src/*.ts",
+      "default": "./src/*.ts"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@smithers-orchestrator/gateway": "0.18.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "node ../../node_modules/tsup/dist/cli-default.js --dts-only",
+    "typecheck": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
+    "test": "bun test tests"
+  }
+}

package/src/GatewayEventFrame.ts

@@ -0,0 +1,8 @@
+export type GatewayEventFrame<Payload = unknown> = {
+  type: "event";
+  event: string;
+  payload?: Payload;
+  seq: number;
+  stateVersion: number;
+  apiVersion?: "v1";
+};

package/src/GatewayRequestFrame.ts

@@ -0,0 +1,6 @@
+export type GatewayRequestFrame = {
+  type: "req";
+  id: string;
+  method: string;
+  params?: unknown;
+};

package/src/GatewayResponseFrame.ts

@@ -0,0 +1,22 @@
+export type GatewayResponseFrame<Payload = unknown> =
+  | {
+      type: "res";
+      id: string;
+      ok: true;
+      apiVersion?: "v1";
+      payload: Payload;
+    }
+  | {
+      type: "res";
+      id: string;
+      ok: false;
+      apiVersion?: "v1";
+      error: {
+        version?: "v1";
+        code: string;
+        message: string;
+        requiredScope?: string;
+        refresh?: string;
+        details?: unknown;
+      };
+    };

package/src/GatewayRpcError.ts

@@ -0,0 +1,27 @@
+export class GatewayRpcError extends Error {
+  readonly code: string;
+  readonly method: string;
+  readonly status?: number;
+  readonly requiredScope?: string;
+  readonly refresh?: string;
+  readonly details?: unknown;
+
+  constructor(input: {
+    method: string;
+    code: string;
+    message: string;
+    status?: number;
+    requiredScope?: string;
+    refresh?: string;
+    details?: unknown;
+  }) {
+    super(input.message);
+    this.name = "GatewayRpcError";
+    this.method = input.method;
+    this.code = input.code;
+    this.status = input.status;
+    this.requiredScope = input.requiredScope;
+    this.refresh = input.refresh;
+    this.details = input.details;
+  }
+}

package/src/GatewayRpcTypeMap.ts

@@ -0,0 +1,77 @@
+import type {
+  CancelRunRequest,
+  CancelRunResponse,
+  CronCreateRequest,
+  CronDeleteRequest,
+  CronListRequest,
+  CronRunRequest,
+  GatewayRpcMethod,
+  HijackRunRequest,
+  HijackRunResponse,
+  LaunchRunRequest,
+  LaunchRunResponse,
+  ListApprovalsRequest,
+  ListApprovalsResponse,
+  ListRunsRequest,
+  ListWorkflowsRequest,
+  ListWorkflowsResponse,
+  NodeRequest,
+  RewindRunRequest,
+  ResumeRunRequest,
+  ResumeRunResponse,
+  StreamDevToolsRequest,
+  StreamRunEventsRequest,
+  StreamRunEventsResponse,
+  SubmitApprovalRequest,
+  SubmitApprovalResponse,
+  SubmitSignalRequest,
+  GetRunRequest,
+} from "@smithers-orchestrator/gateway/rpc";
+
+export type GatewayRpcRequestMap = {
+  launchRun: LaunchRunRequest;
+  resumeRun: ResumeRunRequest;
+  cancelRun: CancelRunRequest;
+  hijackRun: HijackRunRequest;
+  rewindRun: RewindRunRequest;
+  submitApproval: SubmitApprovalRequest;
+  submitSignal: SubmitSignalRequest;
+  getRun: GetRunRequest;
+  listRuns: ListRunsRequest;
+  listWorkflows: ListWorkflowsRequest;
+  listApprovals: ListApprovalsRequest;
+  streamRunEvents: StreamRunEventsRequest;
+  streamDevTools: StreamDevToolsRequest;
+  getNodeOutput: NodeRequest;
+  getNodeDiff: NodeRequest;
+  cronList: CronListRequest;
+  cronCreate: CronCreateRequest;
+  cronDelete: CronDeleteRequest;
+  cronRun: CronRunRequest;
+};
+
+export type GatewayRpcResponseMap = {
+  launchRun: LaunchRunResponse;
+  resumeRun: ResumeRunResponse;
+  cancelRun: CancelRunResponse;
+  hijackRun: HijackRunResponse;
+  rewindRun: Record<string, unknown>;
+  submitApproval: SubmitApprovalResponse;
+  submitSignal: Record<string, unknown>;
+  getRun: Record<string, unknown>;
+  listRuns: Array<Record<string, unknown>>;
+  listWorkflows: ListWorkflowsResponse;
+  listApprovals: ListApprovalsResponse;
+  streamRunEvents: StreamRunEventsResponse;
+  streamDevTools: Record<string, unknown>;
+  getNodeOutput: Record<string, unknown>;
+  getNodeDiff: Record<string, unknown>;
+  cronList: Array<Record<string, unknown>>;
+  cronCreate: Record<string, unknown>;
+  cronDelete: Record<string, unknown>;
+  cronRun: LaunchRunResponse;
+};
+
+export type GatewayRpcParams<Method extends GatewayRpcMethod> = GatewayRpcRequestMap[Method];
+
+export type GatewayRpcPayload<Method extends GatewayRpcMethod> = GatewayRpcResponseMap[Method];

package/src/GatewayUiBootConfig.ts

@@ -0,0 +1,10 @@
+export type GatewayUiBootConfig = {
+  apiVersion: "v1";
+  kind: "gateway" | "workflow";
+  workflowKey: string | null;
+  mountPath: string;
+  rpcPath: string;
+  wsPath: string;
+  assetBasePath: string;
+  props: Record<string, unknown>;
+};

package/src/SmithersGatewayClient.ts

@@ -0,0 +1,227 @@
+import type { GatewayRpcMethod } from "@smithers-orchestrator/gateway/rpc";
+import { GatewayRpcError } from "./GatewayRpcError.ts";
+import type { GatewayEventFrame } from "./GatewayEventFrame.ts";
+import type { GatewayResponseFrame } from "./GatewayResponseFrame.ts";
+import type { GatewayUiBootConfig } from "./GatewayUiBootConfig.ts";
+import { SmithersGatewayConnection } from "./SmithersGatewayConnection.ts";
+import type { SmithersGatewayClientOptions } from "./SmithersGatewayClientOptions.ts";
+import type { GatewayRpcParams, GatewayRpcPayload } from "./GatewayRpcTypeMap.ts";
+
+type StreamRunEventPayload = {
+  streamId?: string;
+  runId?: string;
+  seq?: number;
+  event?: string;
+  payload?: unknown;
+};
+
+declare global {
+  var __SMITHERS_GATEWAY_UI__: GatewayUiBootConfig | undefined;
+}
+
+function defaultBaseUrl() {
+  if (typeof globalThis.location !== "undefined") {
+    return globalThis.location.origin;
+  }
+  return "http://127.0.0.1:7331";
+}
+
+function normalizeBaseUrl(baseUrl: string) {
+  return baseUrl.replace(/\/+$/, "");
+}
+
+function toWebSocketUrl(baseUrl: string, wsPath = "/") {
+  const url = new URL(wsPath, baseUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.toString();
+}
+
+function randomId(method: string) {
+  const cryptoApi = globalThis.crypto;
+  const suffix = typeof cryptoApi?.randomUUID === "function"
+    ? cryptoApi.randomUUID()
+    : Math.random().toString(36).slice(2);
+  return `${method}-${suffix}`;
+}
+
+function headersFromOptions(options: SmithersGatewayClientOptions) {
+  const headers = new Headers(options.headers);
+  headers.set("content-type", "application/json");
+  if (options.token) {
+    headers.set("authorization", `Bearer ${options.token}`);
+  }
+  return headers;
+}
+
+function rpcError(frame: Extract<GatewayResponseFrame, { ok: false }>, method: string, status?: number) {
+  return new GatewayRpcError({
+    method,
+    status,
+    code: frame.error.code,
+    message: frame.error.message,
+    requiredScope: frame.error.requiredScope,
+    refresh: frame.error.refresh,
+    details: frame.error.details,
+  });
+}
+
+export class SmithersGatewayClient {
+  readonly baseUrl: string;
+  readonly token?: string;
+  readonly fetchImpl: typeof fetch;
+  readonly WebSocketImpl: typeof WebSocket;
+  readonly headers: HeadersInit | undefined;
+  readonly client: Required<NonNullable<SmithersGatewayClientOptions["client"]>>;
+  readonly boot: GatewayUiBootConfig | undefined;
+
+  constructor(options: SmithersGatewayClientOptions = {}) {
+    this.boot = globalThis.__SMITHERS_GATEWAY_UI__;
+    this.baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultBaseUrl());
+    this.token = options.token;
+    this.headers = options.headers;
+    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.WebSocketImpl = options.WebSocket ?? globalThis.WebSocket;
+    this.client = {
+      id: options.client?.id ?? "smithers-gateway-client",
+      version: options.client?.version ?? "0.17.0",
+      platform: options.client?.platform ?? "browser",
+    };
+  }
+
+  rpc<Method extends GatewayRpcMethod>(
+    method: Method,
+    params: GatewayRpcParams<Method>,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<GatewayRpcPayload<Method>> {
+    return this.rpcRaw(method, params, options) as Promise<GatewayRpcPayload<Method>>;
+  }
+
+  async rpcRaw(method: string, params?: unknown, options: { signal?: AbortSignal } = {}) {
+    const response = await this.fetchImpl(`${this.baseUrl}/v1/rpc/${method}`, {
+      method: "POST",
+      headers: headersFromOptions(this),
+      body: JSON.stringify(params ?? {}),
+      signal: options.signal,
+    });
+    const frame = (await response.json()) as GatewayResponseFrame;
+    if (!response.ok && !("ok" in frame)) {
+      throw new GatewayRpcError({
+        method,
+        status: response.status,
+        code: "HTTP_ERROR",
+        message: `Gateway HTTP ${response.status}`,
+      });
+    }
+    if (!frame.ok) {
+      throw rpcError(frame, method, response.status);
+    }
+    return frame.payload;
+  }
+
+  async connect(options: { subscribe?: string[]; signal?: AbortSignal } = {}) {
+    if (!this.WebSocketImpl) {
+      throw new Error("WebSocket is not available in this environment.");
+    }
+    const ws = new this.WebSocketImpl(toWebSocketUrl(this.baseUrl, this.boot?.wsPath));
+    await new Promise<void>((resolve, reject) => {
+      const onOpen = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = () => {
+        cleanup();
+        reject(new Error("Gateway WebSocket failed to open."));
+      };
+      const cleanup = () => {
+        ws.removeEventListener("open", onOpen);
+        ws.removeEventListener("error", onError);
+      };
+      ws.addEventListener("open", onOpen);
+      ws.addEventListener("error", onError);
+      options.signal?.addEventListener("abort", () => {
+        cleanup();
+        ws.close();
+        reject(new Error("Gateway WebSocket open aborted."));
+      }, { once: true });
+    });
+    const connection = new SmithersGatewayConnection(ws);
+    await connection.requestRaw("connect", {
+      minProtocol: 1,
+      maxProtocol: 1,
+      client: this.client,
+      ...(this.token ? { auth: { token: this.token } } : {}),
+      ...(options.subscribe ? { subscribe: options.subscribe } : {}),
+    });
+    return connection;
+  }
+
+  async *streamRunEvents(
+    params: GatewayRpcParams<"streamRunEvents">,
+    options: { signal?: AbortSignal } = {},
+  ): AsyncGenerator<GatewayEventFrame<StreamRunEventPayload>> {
+    const connection = await this.connect({ subscribe: [params.runId], signal: options.signal });
+    try {
+      const subscribed = await connection.request("streamRunEvents", params);
+      for await (const frame of connection.events(options.signal)) {
+        if (
+          (frame.event === "run.event" ||
+            frame.event === "run.gap_resync" ||
+            frame.event === "run.heartbeat" ||
+            frame.event === "run.error") &&
+          typeof frame.payload === "object" &&
+          frame.payload !== null &&
+          "streamId" in frame.payload &&
+          frame.payload.streamId === subscribed.streamId
+        ) {
+          yield frame as GatewayEventFrame<StreamRunEventPayload>;
+        }
+      }
+    } finally {
+      connection.close();
+    }
+  }
+
+  launchRun(params: GatewayRpcParams<"launchRun">) {
+    return this.rpc("launchRun", params);
+  }
+
+  resumeRun(params: GatewayRpcParams<"resumeRun">) {
+    return this.rpc("resumeRun", params);
+  }
+
+  cancelRun(params: GatewayRpcParams<"cancelRun">) {
+    return this.rpc("cancelRun", params);
+  }
+
+  submitApproval(params: GatewayRpcParams<"submitApproval">) {
+    return this.rpc("submitApproval", params);
+  }
+
+  submitSignal(params: GatewayRpcParams<"submitSignal">) {
+    return this.rpc("submitSignal", params);
+  }
+
+  getRun(params: GatewayRpcParams<"getRun">) {
+    return this.rpc("getRun", params);
+  }
+
+  listRuns(params: GatewayRpcParams<"listRuns"> = {}) {
+    return this.rpc("listRuns", params);
+  }
+
+  listWorkflows(params: GatewayRpcParams<"listWorkflows"> = {}) {
+    return this.rpc("listWorkflows", params);
+  }
+
+  listApprovals(params: GatewayRpcParams<"listApprovals"> = {}) {
+    return this.rpc("listApprovals", params);
+  }
+
+  getNodeOutput(params: GatewayRpcParams<"getNodeOutput">) {
+    return this.rpc("getNodeOutput", params);
+  }
+
+  getNodeDiff(params: GatewayRpcParams<"getNodeDiff">) {
+    return this.rpc("getNodeDiff", params);
+  }
+}

package/src/SmithersGatewayClientOptions.ts

@@ -0,0 +1,12 @@
+export type SmithersGatewayClientOptions = {
+  baseUrl?: string;
+  token?: string;
+  headers?: HeadersInit;
+  fetch?: typeof fetch;
+  WebSocket?: typeof WebSocket;
+  client?: {
+    id?: string;
+    version?: string;
+    platform?: string;
+  };
+};

package/src/SmithersGatewayConnection.ts

@@ -0,0 +1,154 @@
+import type { GatewayRpcMethod } from "@smithers-orchestrator/gateway/rpc";
+import { GatewayRpcError } from "./GatewayRpcError.ts";
+import type { GatewayEventFrame } from "./GatewayEventFrame.ts";
+import type { GatewayResponseFrame } from "./GatewayResponseFrame.ts";
+import type { GatewayRpcParams, GatewayRpcPayload } from "./GatewayRpcTypeMap.ts";
+
+type PendingRequest = {
+  resolve: (payload: unknown) => void;
+  reject: (error: Error) => void;
+  method: string;
+};
+
+type QueuedEvent =
+  | { kind: "event"; frame: GatewayEventFrame }
+  | { kind: "error"; error: Error }
+  | { kind: "close" };
+
+function randomId(method: string) {
+  const cryptoApi = globalThis.crypto;
+  const suffix = typeof cryptoApi?.randomUUID === "function"
+    ? cryptoApi.randomUUID()
+    : Math.random().toString(36).slice(2);
+  return `${method}-${suffix}`;
+}
+
+function frameError(frame: Extract<GatewayResponseFrame, { ok: false }>, method: string) {
+  return new GatewayRpcError({
+    method,
+    code: frame.error.code,
+    message: frame.error.message,
+    requiredScope: frame.error.requiredScope,
+    refresh: frame.error.refresh,
+    details: frame.error.details,
+  });
+}
+
+export class SmithersGatewayConnection {
+  readonly ws: WebSocket;
+  readonly pending = new Map<string, PendingRequest>();
+  readonly queue: QueuedEvent[] = [];
+  readonly waiters: Array<() => void> = [];
+  closed = false;
+
+  constructor(ws: WebSocket) {
+    this.ws = ws;
+    ws.addEventListener("message", (message) => {
+      this.handleMessage(message.data);
+    });
+    ws.addEventListener("error", () => {
+      this.push({ kind: "error", error: new Error("Gateway WebSocket error") });
+    });
+    ws.addEventListener("close", () => {
+      this.closed = true;
+      for (const pending of this.pending.values()) {
+        pending.reject(new Error("Gateway WebSocket closed"));
+      }
+      this.pending.clear();
+      this.push({ kind: "close" });
+    });
+  }
+
+  request<Method extends GatewayRpcMethod>(
+    method: Method,
+    params: GatewayRpcParams<Method>,
+  ): Promise<GatewayRpcPayload<Method>> {
+    const id = randomId(method);
+    const frame = { type: "req", id, method, params };
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, {
+        method,
+        resolve: (payload) => resolve(payload as GatewayRpcPayload<Method>),
+        reject,
+      });
+      this.ws.send(JSON.stringify(frame));
+    });
+  }
+
+  requestRaw(method: string, params?: unknown): Promise<unknown> {
+    const id = randomId(method);
+    const frame = { type: "req", id, method, params };
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { method, resolve, reject });
+      this.ws.send(JSON.stringify(frame));
+    });
+  }
+
+  async *events(signal?: AbortSignal): AsyncGenerator<GatewayEventFrame> {
+    const abort = () => this.close();
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+      while (!this.closed || this.queue.length > 0) {
+        const next = await this.shift();
+        if (!next || next.kind === "close") {
+          return;
+        }
+        if (next.kind === "error") {
+          throw next.error;
+        }
+        yield next.frame;
+      }
+    } finally {
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+
+  close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.ws.close();
+  }
+
+  private handleMessage(raw: unknown) {
+    const text = typeof raw === "string" ? raw : String(raw);
+    const frame = JSON.parse(text) as GatewayResponseFrame | GatewayEventFrame;
+    if (frame.type === "res") {
+      const pending = this.pending.get(frame.id);
+      if (!pending) {
+        return;
+      }
+      this.pending.delete(frame.id);
+      if (frame.ok) {
+        pending.resolve(frame.payload);
+        return;
+      }
+      pending.reject(frameError(frame, pending.method));
+      return;
+    }
+    if (frame.type === "event") {
+      this.push({ kind: "event", frame });
+    }
+  }
+
+  private push(event: QueuedEvent) {
+    this.queue.push(event);
+    const waiters = this.waiters.splice(0);
+    for (const waiter of waiters) {
+      waiter();
+    }
+  }
+
+  private async shift(): Promise<QueuedEvent | undefined> {
+    while (this.queue.length === 0) {
+      if (this.closed) {
+        return { kind: "close" };
+      }
+      await new Promise<void>((resolve) => {
+        this.waiters.push(resolve);
+      });
+    }
+    return this.queue.shift();
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/src/index.ts

@@ -0,0 +1,9 @@
+export { GatewayRpcError } from "./GatewayRpcError.ts";
+export { SmithersGatewayClient } from "./SmithersGatewayClient.ts";
+export { SmithersGatewayConnection } from "./SmithersGatewayConnection.ts";
+export type { GatewayEventFrame } from "./GatewayEventFrame.ts";
+export type { GatewayRequestFrame } from "./GatewayRequestFrame.ts";
+export type { GatewayResponseFrame } from "./GatewayResponseFrame.ts";
+export type { GatewayRpcParams, GatewayRpcPayload, GatewayRpcRequestMap, GatewayRpcResponseMap } from "./GatewayRpcTypeMap.ts";
+export type { GatewayUiBootConfig } from "./GatewayUiBootConfig.ts";
+export type { SmithersGatewayClientOptions } from "./SmithersGatewayClientOptions.ts";