@huynle/hub 0.6.1 → 0.7.2

package/packages/sdk/src/errors.ts

@@ -0,0 +1,107 @@
+// The hub's error envelope (design §8): every /api/agent failure answers {error: {code, message, hint?, ...extra}}.
+// The SDK turns it into a HubError; failures without an envelope (hub unreachable, a proxy's HTML, a body that is not
+// JSON, a broken stream) are HubTransportErrors. Neither ever carries the token.
+import type { Evaluation } from "./types.ts"
+
+/** The codes the hub answers with (src/central/agent/errors.ts); later phases may add more, so any string is kept. */
+export type ErrorCode =
+  | "invalid"
+  | "invalid_cursor"
+  | "unauthorized"
+  | "token_expired"
+  | "needs_user"
+  | "forbidden"
+  | "not_found"
+  | "ambiguous"
+  | "name_taken"
+  | "gone"
+  | "unsupported"
+  | "paused"
+  | "rate_limited"
+  | "internal"
+  | "offline"
+  | (string & {})
+
+export interface Envelope {
+  readonly code: ErrorCode
+  readonly message: string
+  readonly hint?: string
+  /**
+   * More fields, by code: candidates (ambiguous), retryAfter (rate_limited, seconds), feature/harness (unsupported),
+   * evaluation/decisionID (needs_user; see needsUserOf).
+   */
+  readonly [extra: string]: unknown
+}
+
+/** A failure the hub reported in its envelope. */
+export class HubError extends Error {
+  override readonly name = "HubError"
+  readonly code: ErrorCode
+  readonly hint?: string
+
+  constructor(
+    /** HTTP status of the answer. */
+    readonly status: number,
+    readonly envelope: Envelope,
+  ) {
+    super(envelope.message)
+    this.code = envelope.code
+    if (typeof envelope.hint === "string") this.hint = envelope.hint
+  }
+
+  /** Seconds to wait before retrying (rate_limited), when the hub said. */
+  get retryAfter(): number | undefined {
+    const value = this.envelope.retryAfter
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined
+  }
+}
+
+/**
+ * A failure without the hub's envelope: `unreachable` (no answer), `http` (a non-OK answer without the envelope, or
+ * a redirect), `bad_response` (an OK answer that is not what was expected), `stream` (a watch stream that broke).
+ */
+export type TransportKind = "unreachable" | "http" | "bad_response" | "stream"
+
+export class HubTransportError extends Error {
+  override readonly name = "HubTransportError"
+  /** HTTP status, for `http`. */
+  readonly status?: number
+
+  constructor(
+    readonly kind: TransportKind,
+    message: string,
+    options: { readonly status?: number; readonly cause?: unknown } = {},
+  ) {
+    super(message, options.cause !== undefined ? { cause: options.cause } : undefined)
+    if (options.status !== undefined) this.status = options.status
+  }
+}
+
+/** True for a HubError (with one of `codes`, when given). */
+export const isHubError = (error: unknown, ...codes: ErrorCode[]): error is HubError =>
+  error instanceof HubError && (codes.length === 0 || codes.includes(error.code))
+
+/** What a needs_user failure carries: why (the evaluation) and the Decision it opened for the user, if any. */
+export interface NeedsUser {
+  readonly evaluation?: Evaluation
+  readonly decisionID?: string
+}
+
+/** The needs_user details of an error (undefined for any other error). */
+export function needsUserOf(error: unknown): NeedsUser | undefined {
+  if (!isHubError(error, "needs_user")) return undefined
+  const { evaluation, decisionID } = error.envelope
+  return {
+    ...(typeof evaluation === "object" && evaluation !== null ? { evaluation: evaluation as Evaluation } : {}),
+    ...(typeof decisionID === "string" ? { decisionID } : {}),
+  }
+}
+
+/** The envelope inside a parsed body, if it is one (also the console routes' {error: message, code, hint?}). */
+export function envelopeOf(body: unknown): Envelope | undefined {
+  const raw = body as { error?: unknown; code?: unknown; hint?: unknown } | null
+  const error = raw?.error as Envelope | undefined
+  if (typeof error === "object" && error !== null && typeof error.code === "string" && typeof error.message === "string") return error
+  if (typeof raw?.error === "string" && typeof raw.code === "string") return { code: raw.code, message: raw.error, ...(typeof raw.hint === "string" ? { hint: raw.hint } : {}) }
+  return undefined
+}

package/packages/sdk/src/index.ts

@@ -0,0 +1,10 @@
+// The hub's API client (@huynle/hub-sdk): a typed client for /api/agent (HubClient), the error envelope as typed
+// errors (HubError, HubTransportError), the answer types, the SSE parser of the watch stream, and the pure
+// envelope renderer/sanitiser and address parser shared with the hub, launches, and webhook verification.
+export * from "./address.ts"
+export * from "./client.ts"
+export * from "./envelope.ts"
+export * from "./errors.ts"
+export * from "./sse.ts"
+export * from "./webhook.ts"
+export type * from "./types.ts"

package/packages/sdk/src/sse.ts

@@ -0,0 +1,70 @@
+// Server-sent events (GET /api/agent/watch): an incremental parser, and the event stream of a response.
+import { HubTransportError } from "./errors.ts"
+import type { WatchEvent } from "./types.ts"
+
+/** Parses SSE text incrementally: feed chunks, get complete events (events without data are skipped). */
+export class SseParser {
+  #buffer = ""
+  /** The last `id:` seen (it carries over to later events, as in EventSource). */
+  #id = ""
+
+  push(chunk: string): WatchEvent[] {
+    this.#buffer += chunk.replace(/\r\n?/g, "\n")
+    const out: WatchEvent[] = []
+    let end: number
+    while ((end = this.#buffer.indexOf("\n\n")) >= 0) {
+      const block = this.#buffer.slice(0, end)
+      this.#buffer = this.#buffer.slice(end + 2)
+      let event = "message"
+      const data: string[] = []
+      for (const line of block.split("\n")) {
+        if (line.startsWith(":")) continue
+        const colon = line.indexOf(":")
+        const field = colon < 0 ? line : line.slice(0, colon)
+        const value = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "")
+        if (field === "event") event = value
+        else if (field === "data") data.push(value)
+        else if (field === "id" && !value.includes("\0")) this.#id = value
+      }
+      if (data.length) out.push({ event, data: data.join("\n"), ...(this.#id ? { id: this.#id } : {}) })
+    }
+    return out
+  }
+}
+
+/** The named events of a heartbeat the hub sends to keep the stream open. */
+const HEARTBEAT = "ping"
+
+/**
+ * The events of an SSE response until it ends (heartbeats skipped). Ends quietly once `signal` aborts; a stream that
+ * breaks otherwise is a `stream` HubTransportError.
+ */
+export async function* sseEvents(response: Response, signal?: AbortSignal): AsyncGenerator<WatchEvent, void, undefined> {
+  if (!response.body) throw new HubTransportError("bad_response", "the hub sent no watch stream")
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  const parser = new SseParser()
+  const stop = () => void reader.cancel().catch(() => {})
+  signal?.addEventListener("abort", stop, { once: true })
+  try {
+    for (;;) {
+      if (signal?.aborted) return
+      let chunk: Awaited<ReturnType<typeof reader.read>>
+      try {
+        chunk = await reader.read()
+      } catch (cause) {
+        if (signal?.aborted) return
+        throw new HubTransportError("stream", `the watch stream failed (${cause instanceof Error ? cause.message : String(cause)})`, { cause })
+      }
+      if (chunk.done || signal?.aborted) return
+      for (const event of parser.push(decoder.decode(chunk.value, { stream: true }))) {
+        if (event.event === HEARTBEAT) continue
+        yield event
+        if (signal?.aborted) return
+      }
+    }
+  } finally {
+    signal?.removeEventListener("abort", stop)
+    stop()
+  }
+}