@opengeni/sdk 0.1.0

package/src/errors.ts

@@ -0,0 +1,40 @@
+/** Error for a non-2xx OpenGeni API response. */
+export class OpenGeniApiError extends Error {
+  readonly status: number;
+  readonly body: string;
+
+  constructor(status: number, body: string) {
+    super(`OpenGeni API ${status}: ${body || "(empty body)"}`);
+    this.name = "OpenGeniApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/** Error for an unrecoverable event-stream condition (not a transient drop). */
+export class OpenGeniStreamError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OpenGeniStreamError";
+  }
+}
+
+export function isAbortError(error: unknown): boolean {
+  return (
+    (error instanceof DOMException && error.name === "AbortError") ||
+    (error instanceof Error && error.name === "AbortError")
+  );
+}
+
+/**
+ * Transient conditions worth a reconnect: network-level failures (`fetch`
+ * rejects with `TypeError`) and HTTP statuses that signal a temporary server
+ * or contention condition. Auth/validation failures (401/403/404/...) are
+ * permanent and surface to the caller instead.
+ */
+export function isRetryableStreamError(error: unknown): boolean {
+  if (error instanceof OpenGeniApiError) {
+    return error.status === 408 || error.status === 409 || error.status === 425 || error.status === 429 || error.status >= 500;
+  }
+  return error instanceof TypeError;
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+export { OpenGeniClient } from "./client";
+export type { FetchLike, OpenGeniClientOptions, SendMessageInput, SteerMessageResult } from "./client";
+export { OpenGeniApiError, OpenGeniStreamError, isRetryableStreamError } from "./errors";
+export {
+  formatSseEvent,
+  proxySessionEventStream,
+  resumeSequenceFromRequest,
+  sessionEventsToSseResponse,
+  sessionEventsToSseStream,
+} from "./proxy";
+export type { ProxySessionEventStreamOptions, SseReStreamOptions } from "./proxy";
+export { parseSseStream } from "./sse";
+export type { SseMessage } from "./sse";
+export { streamSessionEvents } from "./stream";
+export type {
+  SessionEventStreamTransport,
+  StreamConnectionState,
+  StreamSessionEventsOptions,
+} from "./stream";
+export { KNOWN_PERMISSIONS, KNOWN_USAGE_EVENT_TYPES, SESSION_EVENT_TYPES } from "./types";
+export type {
+  AccessContext,
+  AccessGrant,
+  AccountGrant,
+  AccountRole,
+  AgentMessageCompletedPayload,
+  AgentTextDeltaPayload,
+  AgentToolCallCreatedPayload,
+  AgentToolCallOutputPayload,
+  ApiKey,
+  BillingBalance,
+  BillingEntitlementsResponse,
+  BillingMode,
+  BillingSummary,
+  BillingUsageResponse,
+  CapabilityCatalogItem,
+  CapabilityCatalogResponse,
+  CapabilityInstallation,
+  CapabilityInstallationStatus,
+  CapabilityKind,
+  CapabilityPack,
+  CapabilityPackConnector,
+  CapabilityPackConnectorAuthModel,
+  CapabilityPackEnvironmentSpec,
+  CapabilityPackKnowledge,
+  CapabilityPackScheduledTaskTemplate,
+  CapabilityPackSkill,
+  CapabilityPackSkillFile,
+  CapabilityRuntime,
+  CapabilitySource,
+  CompactSessionContextResult,
+  ClientSessionEventInput,
+  CompleteFileUploadResponse,
+  CreateApiKeyRequest,
+  CreateApiKeyResponse,
+  CreateCapabilityCatalogItemRequest,
+  CreateCheckoutRequest,
+  CreateCheckoutResponse,
+  CreateDocumentBaseRequest,
+  CreateFileUploadRequest,
+  CreateFileUploadResponse,
+  CreateGitHubAppManifestRequest,
+  CreateGitHubAppManifestResponse,
+  CreateScheduledTaskRequest,
+  CreateSessionRequest,
+  CreateWorkspaceEnvironmentRequest,
+  CreateWorkspaceRequest,
+  DiscoverMcpCapabilitiesResponse,
+  Document,
+  DocumentBase,
+  DocumentSearchRequest,
+  DocumentSearchResponse,
+  DocumentSearchResult,
+  DocumentStatus,
+  EnableCapabilityRequest,
+  EnablePackRequest,
+  Entitlements,
+  EntitlementValue,
+  EntitlementsMode,
+  FileAsset,
+  FileDownloadUrlResponse,
+  FileResourceRef,
+  FileStatus,
+  FileUploadData,
+  GetPackResponse,
+  GitHubAppInfo,
+  GitHubRepositoriesResponse,
+  GitHubRepository,
+  GoalSpec,
+  KnownPermission,
+  KnownSessionEventType,
+  KnownUsageEventType,
+  ListApiKeysResponse,
+  ListPacksResponse,
+  PackInstallation,
+  PackInstallationStatus,
+  Permission,
+  ProductAccessMode,
+  ReasoningEffort,
+  RegisterCapabilityPackRequest,
+  RepositoryResourceRef,
+  ResourceRef,
+  SandboxBackend,
+  ScheduledTask,
+  ScheduledTaskAgentConfig,
+  ScheduledTaskAgentConfigInput,
+  ScheduledTaskDayOfWeek,
+  ScheduledTaskOverlapPolicy,
+  ScheduledTaskRun,
+  ScheduledTaskRunMode,
+  ScheduledTaskRunStatus,
+  ScheduledTaskScheduleSpec,
+  ScheduledTaskStatus,
+  ScheduledTaskTriggerType,
+  Session,
+  SessionEvent,
+  SessionEventType,
+  SessionGoal,
+  SessionGoalCreatedBy,
+  SessionGoalStatus,
+  SessionStatus,
+  SessionStatusChangedPayload,
+  SessionTurn,
+  SessionTurnSource,
+  SessionTurnStatus,
+  ToolRef,
+  UpdateScheduledTaskRequest,
+  UpdateSessionGoalRequest,
+  UpdateSessionTurnRequest,
+  UpdateWorkspaceEnvironmentRequest,
+  UpdateWorkspaceRequest,
+  UploadFileInput,
+  UsageEvent,
+  UsageEventType,
+  UserApprovalDecisionEventInput,
+  UserInterruptEventInput,
+  UserMessageEventInput,
+  Workspace,
+  WorkspaceEnvironment,
+  WorkspaceEnvironmentVariableMetadata,
+  WorkspaceRegisteredPack,
+} from "./types";

package/src/proxy.ts

@@ -0,0 +1,171 @@
+import type { OpenGeniClient } from "./client";
+import type { StreamSessionEventsOptions } from "./stream";
+import type { SessionEvent } from "./types";
+
+/**
+ * Proxy-through-your-own-API helpers.
+ *
+ * The intended pattern: a customer's server consumes the OpenGeni event
+ * stream with its own API key (`client.streamEvents(...)`) and re-emits it to
+ * its browser clients over its own authenticated endpoint — the OpenGeni key
+ * never reaches the browser. The re-emitted wire format is identical to
+ * OpenGeni's own SSE stream (`id: <sequence>`, `event: <type>`,
+ * `data: <event JSON>`), so the browser side can consume it with this same
+ * SDK's streaming core (or a plain `EventSource`), including resume via
+ * `?after=` / `Last-Event-ID`.
+ */
+
+/** Format one event exactly as OpenGeni's API emits it over SSE. */
+export function formatSseEvent(event: SessionEvent): string {
+  return `id: ${event.sequence}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+
+export type SseReStreamOptions = {
+  /**
+   * Emit `: ping` comment lines at this interval, keeping intermediaries from
+   * idling the connection out. Disabled when omitted.
+   */
+  heartbeatMs?: number;
+  /**
+   * Called when the downstream consumer cancels (e.g. the browser
+   * disconnected). Use it to abort the upstream OpenGeni stream — an async
+   * iterator that is mid-`await` cannot be interrupted by `return()` alone.
+   */
+  onCancel?: () => void;
+};
+
+/**
+ * Re-emit a stream of session events as an SSE byte stream. Pull-based, so
+ * upstream consumption follows downstream demand; cancelling the returned
+ * stream fires `onCancel` and ends the upstream iterator.
+ */
+export function sessionEventsToSseStream(
+  events: AsyncIterable<SessionEvent>,
+  options: SseReStreamOptions = {},
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const iterator = events[Symbol.asyncIterator]();
+  let heartbeat: ReturnType<typeof setInterval> | undefined;
+  let cancelled = false;
+
+  const stopHeartbeat = (): void => {
+    if (heartbeat !== undefined) {
+      clearInterval(heartbeat);
+      heartbeat = undefined;
+    }
+  };
+
+  return new ReadableStream<Uint8Array>({
+    start: (controller) => {
+      if (options.heartbeatMs !== undefined) {
+        heartbeat = setInterval(() => {
+          try {
+            controller.enqueue(encoder.encode(": ping\n\n"));
+          } catch {
+            stopHeartbeat();
+          }
+        }, options.heartbeatMs);
+      }
+    },
+    pull: async (controller) => {
+      let result: IteratorResult<SessionEvent, unknown>;
+      try {
+        result = await iterator.next();
+      } catch (error) {
+        stopHeartbeat();
+        throw error;
+      }
+      if (cancelled) {
+        return;
+      }
+      if (result.done) {
+        stopHeartbeat();
+        controller.close();
+        return;
+      }
+      controller.enqueue(encoder.encode(formatSseEvent(result.value)));
+    },
+    cancel: () => {
+      cancelled = true;
+      stopHeartbeat();
+      options.onCancel?.();
+      // Fire-and-forget: if the iterator is suspended mid-await, return()
+      // settles only after onCancel unblocks it; cancel must not hang on it.
+      void Promise.resolve(iterator.return?.(undefined)).then(
+        () => undefined,
+        () => undefined,
+      );
+    },
+  });
+}
+
+/** Wrap an event stream in a ready-to-return SSE `Response`. */
+export function sessionEventsToSseResponse(
+  events: AsyncIterable<SessionEvent>,
+  options: SseReStreamOptions = {},
+): Response {
+  return new Response(sessionEventsToSseStream(events, options), {
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+    },
+  });
+}
+
+/**
+ * Read the resume cursor a reconnecting SSE client sent: the `after` query
+ * parameter, or the standard `Last-Event-ID` header (the re-emitted stream
+ * sets `id:` to the sequence). Returns 0 (full replay) when absent.
+ */
+export function resumeSequenceFromRequest(request: Request): number {
+  const url = new URL(request.url);
+  const raw = url.searchParams.get("after") ?? request.headers.get("Last-Event-ID");
+  const parsed = raw === null ? 0 : Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+}
+
+export type ProxySessionEventStreamOptions = Omit<StreamSessionEventsOptions, "after"> & {
+  /**
+   * Resume cursor. Pass a number, or the incoming browser `Request` to
+   * honor its `?after=` / `Last-Event-ID` automatically.
+   */
+  after?: number | Request;
+  /** See {@link SseReStreamOptions.heartbeatMs}. */
+  heartbeatMs?: number;
+};
+
+/**
+ * One-call proxy: consume the OpenGeni stream server-side and return an SSE
+ * `Response` for your own browser clients. Works anywhere WHATWG `Response`
+ * is the handler return type (Hono, Next.js route handlers, Bun.serve,
+ * Cloudflare Workers, ...).
+ *
+ * The upstream OpenGeni connection is torn down when the downstream client
+ * disconnects, and also when `options.signal` (e.g. the incoming request's
+ * signal) aborts.
+ */
+export function proxySessionEventStream(
+  client: OpenGeniClient,
+  workspaceId: string,
+  sessionId: string,
+  options: ProxySessionEventStreamOptions = {},
+): Response {
+  const { after, heartbeatMs, signal, ...streamOptions } = options;
+  const upstream = new AbortController();
+  if (signal?.aborted) {
+    upstream.abort();
+  } else {
+    signal?.addEventListener("abort", () => upstream.abort(), { once: true });
+  }
+  const resolvedAfter = after instanceof Request ? resumeSequenceFromRequest(after) : after ?? 0;
+  const events = client.streamEvents(workspaceId, sessionId, {
+    ...streamOptions,
+    after: resolvedAfter,
+    signal: upstream.signal,
+  });
+  return sessionEventsToSseResponse(events, {
+    ...(heartbeatMs !== undefined ? { heartbeatMs } : {}),
+    onCancel: () => upstream.abort(),
+  });
+}

package/src/sse.ts

@@ -0,0 +1,90 @@
+/**
+ * Minimal incremental Server-Sent Events parser over a byte stream.
+ *
+ * Implements the parts of the SSE wire format OpenGeni uses: `id`, `event`,
+ * and `data` fields, multi-line data, comment lines, and both LF and CRLF
+ * line endings. Messages without any `data` (comments, id-only blocks) are
+ * not emitted.
+ */
+export type SseMessage = {
+  id?: string;
+  event?: string;
+  data: string;
+};
+
+export async function* parseSseStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage, void, void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let id: string | undefined;
+  let event: string | undefined;
+  let dataLines: string[] | null = null;
+
+  const dispatch = (): SseMessage | null => {
+    const message = dataLines === null
+      ? null
+      : {
+        ...(id !== undefined ? { id } : {}),
+        ...(event !== undefined ? { event } : {}),
+        data: dataLines.join("\n"),
+      };
+    id = undefined;
+    event = undefined;
+    dataLines = null;
+    return message;
+  };
+
+  const handleLine = (line: string): SseMessage | null => {
+    if (line === "") {
+      return dispatch();
+    }
+    if (line.startsWith(":")) {
+      return null;
+    }
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) {
+      value = value.slice(1);
+    }
+    if (field === "data") {
+      (dataLines ??= []).push(value);
+    } else if (field === "event") {
+      event = value;
+    } else if (field === "id") {
+      id = value;
+    }
+    // Other fields (e.g. `retry`) are ignored; reconnect pacing is the
+    // streaming layer's concern.
+    return null;
+  };
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      let newline = buffer.indexOf("\n");
+      while (newline !== -1) {
+        let line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (line.endsWith("\r")) {
+          line = line.slice(0, -1);
+        }
+        const message = handleLine(line);
+        if (message) {
+          yield message;
+        }
+        newline = buffer.indexOf("\n");
+      }
+    }
+    // Per the SSE spec, a block is only dispatched on a blank line. Anything
+    // still pending at end-of-stream came from a truncated connection and is
+    // discarded — the streaming layer replays from its cursor on reconnect.
+  } finally {
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}

package/src/stream.ts

@@ -0,0 +1,192 @@
+import { isAbortError, isRetryableStreamError, OpenGeniStreamError } from "./errors";
+import { parseSseStream } from "./sse";
+import type { SessionEvent } from "./types";
+
+/**
+ * Transport boundary for the streaming core. The client implements it with
+ * `fetch`; unit tests script it directly.
+ */
+export type SessionEventStreamTransport = {
+  /** Open the SSE stream, replaying durable events after `after` first. */
+  openStream: (after: number, signal: AbortSignal | undefined) => Promise<ReadableStream<Uint8Array>>;
+  /** Replay durable events by sequence (`GET .../events?after=&limit=`). */
+  listEvents: (after: number, limit: number) => Promise<SessionEvent[]>;
+};
+
+export type StreamConnectionState = "connecting" | "live" | "reconnecting";
+
+export type StreamSessionEventsOptions = {
+  /** Resume after this sequence number (exclusive). Defaults to 0 (full replay). */
+  after?: number;
+  /** Aborting ends the stream gracefully (the generator returns). */
+  signal?: AbortSignal;
+  /** Reconnect on transient drops. Defaults to true. */
+  reconnect?: boolean;
+  /** Initial reconnect backoff. Defaults to 500ms. */
+  reconnectDelayMs?: number;
+  /** Backoff ceiling. Defaults to 10s. */
+  maxReconnectDelayMs?: number;
+  /**
+   * Give up after this many consecutive failed reconnect attempts (i.e. N
+   * reconnects = N+1 total open-stream calls). Defaults to unlimited.
+   */
+  maxReconnectAttempts?: number;
+  onStateChange?: (state: StreamConnectionState) => void;
+};
+
+/**
+ * Stream a session's events with exactly-once, in-order delivery.
+ *
+ * Guarantees, anchored on the per-session contiguous `sequence`:
+ * - **No duplicates**: events at or below the cursor are dropped, so server
+ *   replay overlap and reconnect overlap never re-yield.
+ * - **No gaps**: each reconnect resumes from the last seen sequence, and a
+ *   gap observed inside one connection is backfilled from the durable replay
+ *   endpoint before the newer event is yielded (events are durable before
+ *   they are published live, so the backfill always finds them).
+ * - **Ordered**: sequences are yielded strictly ascending.
+ *
+ * The generator ends when `signal` aborts, when the server closes and
+ * `reconnect` is false, or with an error for non-retryable failures.
+ */
+export async function* streamSessionEvents(
+  transport: SessionEventStreamTransport,
+  options: StreamSessionEventsOptions = {},
+): AsyncGenerator<SessionEvent, void, void> {
+  const signal = options.signal;
+  const reconnect = options.reconnect ?? true;
+  const baseDelayMs = options.reconnectDelayMs ?? 500;
+  const maxDelayMs = options.maxReconnectDelayMs ?? 10_000;
+  const maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
+  let cursor = options.after ?? 0;
+  let failedAttempts = 0;
+  let delayMs = baseDelayMs;
+  let everConnected = false;
+
+  while (!signal?.aborted) {
+    options.onStateChange?.(everConnected || failedAttempts > 0 ? "reconnecting" : "connecting");
+    const cursorAtOpen = cursor;
+    try {
+      const body = await transport.openStream(cursor, signal);
+      everConnected = true;
+      failedAttempts = 0;
+      delayMs = baseDelayMs;
+      options.onStateChange?.("live");
+      for await (const message of parseSseStream(body)) {
+        // Re-check after every yield resumption: an abort from the consumer
+        // must not let already-buffered events keep flowing.
+        if (signal?.aborted) {
+          return;
+        }
+        const event = parseSessionEvent(message.data);
+        if (!event || event.sequence <= cursor) {
+          continue;
+        }
+        if (event.sequence > cursor + 1) {
+          for await (const missed of backfillEvents(transport, cursor, event.sequence - 1)) {
+            cursor = missed.sequence;
+            yield missed;
+            if (signal?.aborted) {
+              return;
+            }
+          }
+        }
+        cursor = event.sequence;
+        yield event;
+      }
+      if (!reconnect) {
+        return;
+      }
+      // Clean server close: reconnect immediately when the connection made
+      // progress (servers legitimately cycle long SSE connections); pace
+      // empty closes so a misbehaving server is not hammered in a hot loop.
+      if (cursor === cursorAtOpen) {
+        await sleep(baseDelayMs, signal);
+      }
+      continue;
+    } catch (error) {
+      if (signal?.aborted || isAbortError(error)) {
+        return;
+      }
+      if (!reconnect || !isRetryableStreamError(error)) {
+        throw error;
+      }
+      failedAttempts += 1;
+      if (failedAttempts > maxAttempts) {
+        throw new OpenGeniStreamError(
+          `event stream gave up after ${maxAttempts} consecutive failed reconnect attempts: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+    await sleep(delayMs, signal);
+    delayMs = Math.min(Math.max(delayMs * 2, baseDelayMs), maxDelayMs);
+  }
+}
+
+/**
+ * Yield the durable events with `fromExclusive < sequence <= toInclusive`,
+ * in order. Sequences are contiguous, so every one of them must exist in the
+ * replay endpoint; if any is missing the function throws instead of skipping
+ * it — continuing would silently break the gap-free delivery guarantee.
+ */
+async function* backfillEvents(
+  transport: SessionEventStreamTransport,
+  fromExclusive: number,
+  toInclusive: number,
+): AsyncGenerator<SessionEvent, void, void> {
+  let cursor = fromExclusive;
+  while (cursor < toInclusive) {
+    const page = await transport.listEvents(cursor, Math.min(500, toInclusive - cursor));
+    const advancing = page
+      .filter((event) => event.sequence > cursor && event.sequence <= toInclusive)
+      .sort((a, b) => a.sequence - b.sequence);
+    if (advancing.length === 0) {
+      throw new OpenGeniStreamError(
+        `event replay backfill stalled: expected sequences ${cursor + 1}..${toInclusive} but the replay endpoint returned none of them`,
+      );
+    }
+    for (const event of advancing) {
+      if (event.sequence !== cursor + 1) {
+        throw new OpenGeniStreamError(
+          `event replay backfill is missing sequence ${cursor + 1} (replay endpoint skipped to ${event.sequence}); refusing to deliver with a gap`,
+        );
+      }
+      cursor = event.sequence;
+      yield event;
+    }
+  }
+}
+
+function parseSessionEvent(data: string): SessionEvent | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    typeof (parsed as { sequence?: unknown }).sequence !== "number" ||
+    typeof (parsed as { type?: unknown }).type !== "string" ||
+    typeof (parsed as { id?: unknown }).id !== "string"
+  ) {
+    return null;
+  }
+  return parsed as SessionEvent;
+}
+
+async function sleep(delayMs: number, signal: AbortSignal | undefined): Promise<void> {
+  if (signal?.aborted || delayMs <= 0) {
+    return;
+  }
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(done, delayMs);
+    function done(): void {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}