@gizmo-ai/client 0.2.2

package/src/__tests__/subscribe.test.ts

@@ -0,0 +1,333 @@
+import { describe, expect, test, mock, beforeEach, afterEach } from "bun:test";
+import { subscribe } from "../subscribe.ts";
+import type {
+  InitialStateEvent,
+  StateUpdateEvent,
+  ExecutionStatusEvent,
+  HeartbeatEvent,
+  CustomEvent,
+  StateSnapshot,
+} from "../types.ts";
+
+// ── Mock EventSource ───────────────────────────────────────────────
+
+type EventHandler = (event: MessageEvent) => void;
+
+class MockEventSource {
+  url: string;
+  listeners: Map<string, EventHandler[]> = new Map();
+  closed = false;
+
+  constructor(url: string) {
+    this.url = url;
+    // Make this instance accessible to tests
+    MockEventSource.instances.push(this);
+  }
+
+  addEventListener(event: string, handler: EventHandler) {
+    const handlers = this.listeners.get(event) ?? [];
+    handlers.push(handler);
+    this.listeners.set(event, handlers);
+  }
+
+  close() {
+    this.closed = true;
+  }
+
+  // Test helper: emit a named event
+  emit(eventType: string, data: unknown) {
+    const handlers = this.listeners.get(eventType) ?? [];
+    const messageEvent = new MessageEvent(eventType, {
+      data: JSON.stringify(data),
+    });
+    for (const handler of handlers) {
+      handler(messageEvent);
+    }
+  }
+
+  static instances: MockEventSource[] = [];
+  static reset() {
+    MockEventSource.instances = [];
+  }
+}
+
+// Install mock EventSource globally
+const OriginalEventSource = globalThis.EventSource;
+
+beforeEach(() => {
+  MockEventSource.reset();
+  (globalThis as unknown as Record<string, unknown>).EventSource = MockEventSource as unknown as typeof EventSource;
+});
+
+afterEach(() => {
+  (globalThis as unknown as Record<string, unknown>).EventSource = OriginalEventSource;
+});
+
+function lastES(): MockEventSource {
+  return MockEventSource.instances[MockEventSource.instances.length - 1];
+}
+
+// ── Tests ──────────────────────────────────────────────────────────
+
+describe("subscribe()", () => {
+  test("connects to the correct URL", () => {
+    subscribe("http://localhost:3001", () => {});
+    expect(lastES().url).toBe("http://localhost:3001/events");
+  });
+
+  test("uses custom endpoint from options", () => {
+    subscribe("http://localhost:3001", () => {}, { endpoint: "/stream/state" });
+    expect(lastES().url).toBe("http://localhost:3001/stream/state");
+  });
+
+  describe("state.initial", () => {
+    test("sets local state and fires callback with snapshot", () => {
+      const snapshots: StateSnapshot[] = [];
+      subscribe("http://localhost:3001", (s) => snapshots.push(s));
+
+      const event: InitialStateEvent = {
+        type: "state.initial",
+        slices: { agent: { conversation: [] }, execution: { id: null } },
+        timestamp: 1000,
+      };
+      lastES().emit("state.initial", event);
+
+      expect(snapshots).toHaveLength(1);
+      expect(snapshots[0].slices).toEqual({
+        agent: { conversation: [] },
+        execution: { id: null },
+      });
+      expect(snapshots[0].event).toEqual(event);
+    });
+
+    test("replaces previous state on new initial event", () => {
+      const snapshots: StateSnapshot[] = [];
+      subscribe("http://localhost:3001", (s) => snapshots.push(s));
+
+      // First initial
+      lastES().emit("state.initial", {
+        type: "state.initial",
+        slices: { agent: { conversation: ["a"] }, old: { data: true } },
+        timestamp: 1000,
+      });
+
+      // Second initial (reconnect scenario)
+      lastES().emit("state.initial", {
+        type: "state.initial",
+        slices: { agent: { conversation: [] } },
+        timestamp: 2000,
+      });
+
+      expect(snapshots).toHaveLength(2);
+      // Old slices should be gone
+      expect(snapshots[1].slices).toEqual({ agent: { conversation: [] } });
+      expect("old" in snapshots[1].slices).toBe(false);
+    });
+  });
+
+  describe("state.update with patches", () => {
+    test("applies JSON Patches correctly", () => {
+      const snapshots: StateSnapshot[] = [];
+      subscribe("http://localhost:3001", (s) => snapshots.push(s));
+
+      // Set initial state
+      lastES().emit("state.initial", {
+        type: "state.initial",
+        slices: { agent: { conversation: [], loopCount: 0 } },
+        timestamp: 1000,
+      });
+
+      // Apply patch
+      const updateEvent: StateUpdateEvent = {
+        type: "state.update",
+        slice: "agent",
+        patches: [
+          { op: "replace", path: "/loopCount", value: 1 },
+          { op: "add", path: "/conversation/-", value: "Hello" },
+        ],
+        timestamp: 2000,
+      };
+      lastES().emit("state.update", updateEvent);
+
+      expect(snapshots).toHaveLength(2);
+      const agentState = snapshots[1].slices.agent as Record<string, unknown>;
+      expect(agentState.loopCount).toBe(1);
+      expect(agentState.conversation).toEqual(["Hello"]);
+    });
+  });
+
+  describe("state.update with value replacement", () => {
+    test("replaces slice with value", () => {
+      const snapshots: StateSnapshot[] = [];
+      subscribe("http://localhost:3001", (s) => snapshots.push(s));
+
+      // Set initial state
+      lastES().emit("state.initial", {
+        type: "state.initial",
+        slices: { agent: { conversation: [] } },
+        timestamp: 1000,
+      });
+
+      // Full value replacement
+      const updateEvent: StateUpdateEvent = {
+        type: "state.update",
+        slice: "agent",
+        value: { conversation: ["msg1"], loopCount: 5 },
+        timestamp: 2000,
+      };
+      lastES().emit("state.update", updateEvent);
+
+      expect(snapshots).toHaveLength(2);
+      expect(snapshots[1].slices.agent).toEqual({ conversation: ["msg1"], loopCount: 5 });
+    });
+  });
+
+  describe("multiple updates accumulate state", () => {
+    test("state accumulates across multiple events", () => {
+      const snapshots: StateSnapshot[] = [];
+      subscribe("http://localhost:3001", (s) => snapshots.push(s));
+
+      // Initial
+      lastES().emit("state.initial", {
+        type: "state.initial",
+        slices: { counter: { value: 0 } },
+        timestamp: 1000,
+      });
+
+      // Update 1
+      lastES().emit("state.update", {
+        type: "state.update",
+        slice: "counter",
+        patches: [{ op: "replace", path: "/value", value: 1 }],
+        timestamp: 2000,
+      });
+
+      // Update 2
+      lastES().emit("state.update", {
+        type: "state.update",
+        slice: "counter",
+        patches: [{ op: "replace", path: "/value", value: 2 }],
+        timestamp: 3000,
+      });
+
+      // Update 3 — new slice via value
+      lastES().emit("state.update", {
+        type: "state.update",
+        slice: "execution",
+        value: { id: "exec-1", state: "running" },
+        timestamp: 4000,
+      });
+
+      expect(snapshots).toHaveLength(4);
+
+      // Final state should have both slices
+      const final = snapshots[3].slices;
+      expect(final.counter).toEqual({ value: 2 });
+      expect(final.execution).toEqual({ id: "exec-1", state: "running" });
+    });
+  });
+
+  describe("non-state events", () => {
+    test("execution.status fires callback without mutating state", () => {
+      const snapshots: StateSnapshot[] = [];
+      subscribe("http://localhost:3001", (s) => snapshots.push(s));
+
+      // Initial
+      lastES().emit("state.initial", {
+        type: "state.initial",
+        slices: { agent: { value: 1 } },
+        timestamp: 1000,
+      });
+
+      // Execution status
+      const statusEvent: ExecutionStatusEvent = {
+        type: "execution.status",
+        status: "started",
+        executionId: "exec-1",
+        timestamp: 2000,
+      };
+      lastES().emit("execution.status", statusEvent);
+
+      expect(snapshots).toHaveLength(2);
+      // State should be unchanged
+      expect(snapshots[1].slices).toEqual({ agent: { value: 1 } });
+      expect(snapshots[1].event).toEqual(statusEvent);
+    });
+
+    test("heartbeat fires callback without mutating state", () => {
+      const snapshots: StateSnapshot[] = [];
+      subscribe("http://localhost:3001", (s) => snapshots.push(s));
+
+      lastES().emit("state.initial", {
+        type: "state.initial",
+        slices: {},
+        timestamp: 1000,
+      });
+
+      const heartbeat: HeartbeatEvent = { type: "heartbeat", timestamp: 2000 };
+      lastES().emit("heartbeat", heartbeat);
+
+      expect(snapshots).toHaveLength(2);
+      expect(snapshots[1].event).toEqual(heartbeat);
+    });
+
+    test("custom-event fires callback without mutating state", () => {
+      const snapshots: StateSnapshot[] = [];
+      subscribe("http://localhost:3001", (s) => snapshots.push(s));
+
+      lastES().emit("state.initial", {
+        type: "state.initial",
+        slices: { x: 1 },
+        timestamp: 1000,
+      });
+
+      const custom: CustomEvent = {
+        type: "custom-event",
+        data: { foo: "bar" },
+        timestamp: 2000,
+      };
+      lastES().emit("custom-event", custom);
+
+      expect(snapshots).toHaveLength(2);
+      expect(snapshots[1].slices).toEqual({ x: 1 });
+      expect(snapshots[1].event).toEqual(custom);
+    });
+  });
+
+  describe("unsubscribe", () => {
+    test("closes EventSource", () => {
+      const unsub = subscribe("http://localhost:3001", () => {});
+      expect(lastES().closed).toBe(false);
+
+      unsub();
+      expect(lastES().closed).toBe(true);
+    });
+  });
+
+  describe("snapshot isolation", () => {
+    test("each callback receives a separate slices object", () => {
+      const snapshots: StateSnapshot[] = [];
+      subscribe("http://localhost:3001", (s) => snapshots.push(s));
+
+      lastES().emit("state.initial", {
+        type: "state.initial",
+        slices: { a: 1 },
+        timestamp: 1000,
+      });
+
+      lastES().emit("state.update", {
+        type: "state.update",
+        slice: "a",
+        value: 2,
+        timestamp: 2000,
+      });
+
+      // Mutating the first snapshot should not affect the second
+      expect(snapshots[0].slices.a).toBe(1);
+      expect(snapshots[1].slices.a).toBe(2);
+
+      // They should be different objects
+      expect(snapshots[0].slices).not.toBe(snapshots[1].slices);
+    });
+  });
+});

package/src/client.ts

@@ -0,0 +1,214 @@
+/**
+ * createClient — factory for the typed Gizmo agent SDK
+ *
+ * One dependency, one createClient(url) call, every operation becomes a
+ * thin typed wrapper over the HTTP/SSE API.
+ */
+
+import { GizmoClientError } from "./errors.ts";
+import { subscribe as sseSubscribe } from "./subscribe.ts";
+import type {
+  GizmoManifest,
+  InvokeResponse,
+  AbortResponse,
+  RunSummary,
+  RunDetails,
+  RunsResponse,
+  RunListParams,
+  HydrateOptions,
+  HydrateResponse,
+  HealthResponse,
+  DispatchRequest,
+  Approval,
+  ApprovalsListResponse,
+  ApprovalResponse,
+  HistoryResponse,
+  SubscribeCallback,
+  SubscribeOptions,
+  Unsubscribe,
+  ClientOptions,
+  GizmoClient,
+} from "./types.ts";
+
+/**
+ * Create a typed client for a Gizmo agent.
+ *
+ * @param baseUrl - The agent's base URL (e.g., "http://localhost:3001")
+ * @param options - Optional fetch implementation and default headers
+ */
+export function createClient(
+  baseUrl: string,
+  options?: ClientOptions,
+): GizmoClient {
+  const _fetch = options?.fetch ?? globalThis.fetch;
+  const _headers = options?.headers ?? {};
+
+  // Strip trailing slash from baseUrl
+  const base = baseUrl.replace(/\/$/, "");
+
+  // ── Internal helpers ───────────────────────────────────────────────
+
+  async function get<T>(path: string): Promise<T> {
+    const res = await _fetch(`${base}${path}`, {
+      method: "GET",
+      headers: { ...headers(), Accept: "application/json" },
+    });
+    if (!res.ok) {
+      const body = await safeJson(res);
+      throw new GizmoClientError(res.status, errorMessage(res, body), body);
+    }
+    return res.json() as Promise<T>;
+  }
+
+  async function post<T>(path: string, body?: unknown): Promise<T> {
+    const res = await _fetch(`${base}${path}`, {
+      method: "POST",
+      headers: { ...headers(), "Content-Type": "application/json", Accept: "application/json" },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+      const errBody = await safeJson(res);
+      throw new GizmoClientError(res.status, errorMessage(res, errBody), errBody);
+    }
+    return res.json() as Promise<T>;
+  }
+
+  function headers(): Record<string, string> {
+    return { ..._headers };
+  }
+
+  // ── Manifest caching ──────────────────────────────────────────────
+
+  let manifestCache: GizmoManifest | null = null;
+
+  // ── Runs namespace ────────────────────────────────────────────────
+
+  const runs = {
+    async list(params?: RunListParams): Promise<RunSummary[]> {
+      const qs = buildQuery(params as Record<string, unknown> | undefined);
+      const res = await get<RunsResponse>(`/runs${qs}`);
+      return res.runs;
+    },
+
+    async get(executionId: string): Promise<RunDetails> {
+      return get<RunDetails>(`/runs/${encodeURIComponent(executionId)}`);
+    },
+
+    async actions(executionId: string): Promise<RunDetails["actions"]> {
+      const run = await runs.get(executionId);
+      return run.actions;
+    },
+
+    async cancel(executionId: string): Promise<{ status: string; executionId: string }> {
+      return post<{ status: string; executionId: string }>(
+        `/runs/${encodeURIComponent(executionId)}/cancel`,
+      );
+    },
+
+    async hydrate(executionId: string, opts?: HydrateOptions): Promise<HydrateResponse> {
+      return post<HydrateResponse>("/hydrate", { executionId, ...opts });
+    },
+  };
+
+  // ── Approvals namespace ───────────────────────────────────────────
+
+  const approvals = {
+    async list(): Promise<Approval[]> {
+      const res = await get<ApprovalsListResponse>("/approvals");
+      return res.approvals;
+    },
+
+    async history(): Promise<Approval[]> {
+      const res = await get<HistoryResponse>("/approvals/history");
+      return res.history;
+    },
+
+    async get(id: string): Promise<Approval> {
+      const res = await get<ApprovalResponse>(`/approvals/${encodeURIComponent(id)}`);
+      return res.approval;
+    },
+
+    async approve(id: string, reason?: string): Promise<Approval> {
+      const res = await post<ApprovalResponse>(
+        `/approvals/${encodeURIComponent(id)}`,
+        { decision: "approve", reason },
+      );
+      return res.approval;
+    },
+
+    async reject(id: string, reason?: string): Promise<Approval> {
+      const res = await post<ApprovalResponse>(
+        `/approvals/${encodeURIComponent(id)}`,
+        { decision: "reject", reason },
+      );
+      return res.approval;
+    },
+  };
+
+  // ── Public API ────────────────────────────────────────────────────
+
+  return {
+    async discover(): Promise<GizmoManifest> {
+      if (manifestCache) return manifestCache;
+      manifestCache = await get<GizmoManifest>("/.well-known/manifest.json");
+      return manifestCache;
+    },
+
+    async invoke(input: string): Promise<InvokeResponse> {
+      return post<InvokeResponse>("/invoke", { input });
+    },
+
+    async abort(): Promise<AbortResponse> {
+      return post<AbortResponse>("/abort");
+    },
+
+    async state(slice?: string): Promise<unknown> {
+      const path = slice ? `/state/${encodeURIComponent(slice)}` : "/state";
+      return get<unknown>(path);
+    },
+
+    subscribe(callback: SubscribeCallback, opts?: SubscribeOptions): Unsubscribe {
+      return sseSubscribe(base, callback, opts);
+    },
+
+    async health(): Promise<HealthResponse> {
+      return get<HealthResponse>("/health");
+    },
+
+    async dispatch(action: DispatchRequest): Promise<unknown> {
+      return post<unknown>("/dispatch", action);
+    },
+
+    runs,
+    approvals,
+  };
+}
+
+// ── Utilities ──────────────────────────────────────────────────────
+
+function buildQuery(params?: Record<string, unknown>): string {
+  if (!params) return "";
+  const entries = Object.entries(params).filter(
+    ([, v]) => v !== undefined && v !== null,
+  );
+  if (entries.length === 0) return "";
+  const qs = entries
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+    .join("&");
+  return `?${qs}`;
+}
+
+async function safeJson(res: Response): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return undefined;
+  }
+}
+
+function errorMessage(res: Response, body: unknown): string {
+  if (body && typeof body === "object" && "error" in body) {
+    return String((body as { error: string }).error);
+  }
+  return `HTTP ${res.status}`;
+}

package/src/errors.ts

@@ -0,0 +1,16 @@
+/**
+ * GizmoClientError
+ *
+ * Thrown when the server returns a non-OK HTTP response.
+ */
+export class GizmoClientError extends Error {
+  readonly status: number;
+  readonly body?: unknown;
+
+  constructor(status: number, message: string, body?: unknown) {
+    super(message);
+    this.name = "GizmoClientError";
+    this.status = status;
+    this.body = body;
+  }
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * @gizmo-ai/client
+ *
+ * Typed SDK for Gizmo agents — discover, invoke, subscribe, and manage runs.
+ *
+ * Usage:
+ * ```typescript
+ * import { createClient } from "@gizmo-ai/client";
+ *
+ * const client = createClient("http://localhost:3001");
+ *
+ * const manifest = await client.discover();
+ * const { executionId } = await client.invoke("Hello!");
+ * const unsub = client.subscribe(({ slices, event }) => {
+ *   console.log(event.type, slices);
+ * });
+ * ```
+ */
+
+export { createClient } from "./client.ts";
+export { GizmoClientError } from "./errors.ts";
+
+export type {
+  // Client
+  GizmoClient,
+  ClientOptions,
+
+  // Manifest
+  GizmoManifest,
+
+  // SSE Events
+  SSEEvent,
+  InitialStateEvent,
+  StateUpdateEvent,
+  ExecutionStatusEvent,
+  HeartbeatEvent,
+  CustomEvent,
+
+  // API Types
+  InvokeResponse,
+  AbortResponse,
+  RunSummary,
+  RunDetails,
+  RunsResponse,
+  RunListParams,
+  HydrateOptions,
+  HydrateResponse,
+  HealthResponse,
+  DispatchRequest,
+
+  // Approvals
+  ApprovalStatus,
+  Approval,
+  ApprovalsListResponse,
+  ApprovalResponse,
+  HistoryResponse,
+
+  // Subscribe
+  StateSnapshot,
+  SubscribeCallback,
+  SubscribeOptions,
+  Unsubscribe,
+} from "./types.ts";