@agents24/embed-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talmudpedia
+
+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/README.md

@@ -0,0 +1,203 @@
+# `@agents24/embed-sdk`
+
+Last Updated: 2026-03-17
+
+`@agents24/embed-sdk` is the canonical server-only TypeScript SDK for Talmudpedia embedded-agent runtime.
+
+Use it when a customer already has its own application and wants its backend to call a published Talmudpedia agent directly through the embed API.
+
+## Product Split
+
+This package is not the published-app runtime SDK.
+
+- `@talmudpedia/runtime-sdk`: browser/client SDK for published-app runtime
+- `@agents24/embed-sdk`: Node/server SDK for embedded-agent runtime
+
+## Supported Runtime
+
+V1 is server-only.
+
+- Node `>=18.17`
+- ESM and CommonJS package exports
+- built on top of native `fetch` and Web Streams
+
+Do not use this package in browser bundles. Keep your Talmudpedia tenant API key only on your backend.
+
+## Installation
+
+After the first public npm release is cut:
+
+```bash
+npm install @agents24/embed-sdk
+```
+
+Until that release exists, validate the package from this repo with `npm pack` or `npm run smoke:pack`.
+
+## Required Environment Variables
+
+- `TALMUDPEDIA_BASE_URL`
+- `TALMUDPEDIA_EMBED_API_KEY`
+- published `agent_id`
+
+The API key must have the `agents.embed` scope.
+
+## Quickstart
+
+```ts
+import { EmbeddedAgentClient } from "@agents24/embed-sdk";
+
+const client = new EmbeddedAgentClient({
+  baseUrl: process.env.TALMUDPEDIA_BASE_URL!,
+  apiKey: process.env.TALMUDPEDIA_EMBED_API_KEY!,
+});
+
+const result = await client.streamAgent(
+  process.env.TALMUDPEDIA_AGENT_ID!,
+  {
+    input: "Summarize today’s thread.",
+    external_user_id: "customer-user-123",
+  },
+  (event) => {
+    console.log(event.event, event.payload);
+  },
+);
+
+console.log(result.threadId);
+```
+
+## Architecture
+
+Supported v1 architecture:
+
+- customer frontend
+- customer backend
+- `@agents24/embed-sdk`
+- Talmudpedia embed API
+- published agent
+
+The frontend talks only to the customer backend. The backend talks to Talmudpedia.
+
+## API Reference
+
+### `new EmbeddedAgentClient(options)`
+
+```ts
+const client = new EmbeddedAgentClient({
+  baseUrl: "https://api.talmudpedia.example",
+  apiKey: "tpk_live_xxx",
+});
+```
+
+Options:
+
+- `baseUrl`: base platform URL, for example `https://api.example.com`
+- `apiKey`: tenant API key with `agents.embed`
+- `fetchImpl`: optional custom fetch implementation for tests or custom runtimes
+
+### `streamAgent(agentId, payload, onEvent?)`
+
+Wraps:
+
+- `POST /public/embed/agents/{agent_id}/chat/stream`
+
+Payload keeps backend field names exactly:
+
+```ts
+type EmbeddedAgentStreamRequest = {
+  input?: string;
+  messages?: Array<Record<string, unknown>>;
+  thread_id?: string;
+  external_user_id: string;
+  external_session_id?: string;
+  metadata?: Record<string, unknown>;
+  client?: Record<string, unknown>;
+};
+```
+
+Returns:
+
+```ts
+type StreamAgentResult = {
+  threadId: string | null;
+};
+```
+
+`onEvent` receives typed `run-stream.v2` envelopes.
+
+### `listAgentThreads(agentId, options)`
+
+Wraps:
+
+- `GET /public/embed/agents/{agent_id}/threads`
+
+Options:
+
+- `externalUserId`
+- `externalSessionId?`
+- `skip?`
+- `limit?`
+
+### `getAgentThread(agentId, threadId, options)`
+
+Wraps:
+
+- `GET /public/embed/agents/{agent_id}/threads/{thread_id}`
+
+Options:
+
+- `externalUserId`
+- `externalSessionId?`
+
+## Thread And History Usage
+
+Pass your own application user identity as `external_user_id` on every call.
+
+- `external_user_id` is required
+- `external_session_id` is optional
+- `threadId` returned from `streamAgent(...)` should be persisted by your backend and reused for resume/history
+
+Example:
+
+```ts
+const threads = await client.listAgentThreads(agentId, {
+  externalUserId: "customer-user-123",
+});
+
+const thread = await client.getAgentThread(agentId, "thread-id", {
+  externalUserId: "customer-user-123",
+});
+```
+
+## Error Handling
+
+The SDK throws `EmbeddedAgentSDKError` with:
+
+- `kind: "http" | "network" | "protocol"`
+- `status` for HTTP failures
+- `details` when the response body includes structured error information
+
+```ts
+import { EmbeddedAgentSDKError } from "@agents24/embed-sdk";
+
+try {
+  await client.listAgentThreads(agentId, { externalUserId: "customer-user-123" });
+} catch (error) {
+  if (error instanceof EmbeddedAgentSDKError) {
+    console.error(error.kind, error.status, error.details);
+  }
+}
+```
+
+## Server-Only Warning
+
+- Do not put the Talmudpedia API key in frontend code
+- Do not store the API key in localStorage, cookies, or public env vars
+- Do not call the embed API directly from the browser
+
+## Example App
+
+See [`examples/express-typescript/`](./examples/express-typescript/) for a minimal customer-backend integration example.
+
+## Release Notes
+
+This package is released through GitHub Actions using release-please and npm trusted publishing. Local `npm pack` and `npm run smoke:pack` are the expected pre-release verification commands.

package/dist/index.cjs

@@ -0,0 +1,348 @@
+'use strict';
+
+// src/errors.ts
+var EmbeddedAgentSDKError = class extends Error {
+  kind;
+  status;
+  details;
+  constructor(message, options) {
+    super(message, "cause" in Error.prototype ? { cause: options.cause } : void 0);
+    this.name = "EmbeddedAgentSDKError";
+    this.kind = options.kind;
+    this.status = options.status;
+    this.details = options.details;
+    if (!("cause" in this) && options.cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        configurable: true,
+        enumerable: false,
+        value: options.cause,
+        writable: true
+      });
+    }
+  }
+};
+
+// src/http.ts
+var SERVER_ONLY_MESSAGE = "EmbeddedAgentClient is server-only. Keep your Talmudpedia API key on your backend and call the SDK from Node.";
+function assertServerRuntime() {
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    throw new EmbeddedAgentSDKError(SERVER_ONLY_MESSAGE, { kind: "protocol" });
+  }
+}
+function normalizeBaseUrl(baseUrl) {
+  const normalized = String(baseUrl || "").trim().replace(/\/+$/, "");
+  if (!normalized) {
+    throw new EmbeddedAgentSDKError("EmbeddedAgentClient requires a non-empty baseUrl.", {
+      kind: "protocol"
+    });
+  }
+  try {
+    return new URL(normalized).toString().replace(/\/+$/, "");
+  } catch (cause) {
+    throw new EmbeddedAgentSDKError("EmbeddedAgentClient received an invalid baseUrl.", {
+      kind: "protocol",
+      cause,
+      details: { baseUrl }
+    });
+  }
+}
+function resolveFetchImpl(fetchImpl) {
+  if (fetchImpl) {
+    return fetchImpl;
+  }
+  if (typeof fetch === "function") {
+    return fetch;
+  }
+  throw new EmbeddedAgentSDKError(
+    "No fetch implementation is available. Use Node 18.17+ or pass fetchImpl explicitly.",
+    { kind: "protocol" }
+  );
+}
+function buildStreamHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    Accept: "text/event-stream",
+    "Content-Type": "application/json"
+  };
+}
+function buildJsonHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    Accept: "application/json"
+  };
+}
+function extractMessageFromDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    return void 0;
+  }
+  const detail = details.detail;
+  return typeof detail === "string" && detail.trim() ? detail.trim() : void 0;
+}
+async function parseErrorDetails(response) {
+  if (typeof response.text === "function") {
+    try {
+      const raw = await response.text();
+      if (!raw) {
+        return null;
+      }
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return raw;
+      }
+    } catch {
+      return null;
+    }
+  }
+  if (typeof response.json === "function") {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+async function assertOk(response) {
+  if (response.ok) {
+    return;
+  }
+  const details = await parseErrorDetails(response);
+  const message = extractMessageFromDetails(details) || typeof details === "string" && details.trim() || response.statusText || "Request failed";
+  throw new EmbeddedAgentSDKError(message, {
+    kind: "http",
+    status: response.status,
+    details
+  });
+}
+function wrapNetworkError(message, cause) {
+  if (cause instanceof EmbeddedAgentSDKError) {
+    return cause;
+  }
+  return new EmbeddedAgentSDKError(message, {
+    kind: "network",
+    cause,
+    details: cause instanceof Error ? { name: cause.name } : void 0
+  });
+}
+
+// src/sse.ts
+function parseSSEBlock(block) {
+  const dataLines = [];
+  const lines = block.split("\n");
+  for (const line of lines) {
+    if (!line || line.startsWith(":")) {
+      continue;
+    }
+    const separatorIndex = line.indexOf(":");
+    const field = separatorIndex === -1 ? line : line.slice(0, separatorIndex);
+    let value = separatorIndex === -1 ? "" : line.slice(separatorIndex + 1);
+    if (value.startsWith(" ")) {
+      value = value.slice(1);
+    }
+    if (field === "data") {
+      dataLines.push(value);
+    }
+  }
+  if (dataLines.length === 0) {
+    return null;
+  }
+  return dataLines.join("\n");
+}
+function assertDiagnostics(value) {
+  if (!Array.isArray(value)) {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: diagnostics must be an array.", {
+      kind: "protocol",
+      details: value
+    });
+  }
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: diagnostics entries must be objects.", {
+        kind: "protocol",
+        details: item
+      });
+    }
+    return item;
+  });
+}
+function assertPayload(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: payload must be an object.", {
+      kind: "protocol",
+      details: value
+    });
+  }
+  return value;
+}
+function parseRuntimeEvent(rawPayload) {
+  let parsed;
+  try {
+    parsed = JSON.parse(rawPayload);
+  } catch (cause) {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: invalid JSON payload.", {
+      kind: "protocol",
+      cause,
+      details: rawPayload
+    });
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: expected an object envelope.", {
+      kind: "protocol",
+      details: parsed
+    });
+  }
+  const candidate = parsed;
+  if (candidate.version !== "run-stream.v2") {
+    throw new EmbeddedAgentSDKError(
+      "Embedded-agent SSE protocol mismatch: expected run-stream.v2 event envelopes.",
+      {
+        kind: "protocol",
+        details: candidate
+      }
+    );
+  }
+  if (typeof candidate.seq !== "number" || !Number.isFinite(candidate.seq) || typeof candidate.ts !== "string" || typeof candidate.event !== "string" || typeof candidate.run_id !== "string" || typeof candidate.stage !== "string") {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: missing required envelope fields.", {
+      kind: "protocol",
+      details: candidate
+    });
+  }
+  return {
+    version: "run-stream.v2",
+    seq: candidate.seq,
+    ts: candidate.ts,
+    event: candidate.event,
+    run_id: candidate.run_id,
+    stage: candidate.stage,
+    payload: assertPayload(candidate.payload ?? {}),
+    diagnostics: assertDiagnostics(candidate.diagnostics ?? [])
+  };
+}
+async function consumeEventStream(response, onEvent) {
+  if (!response.body) {
+    throw new EmbeddedAgentSDKError("Embedded-agent stream response did not include a readable body.", {
+      kind: "protocol"
+    });
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    buffer += decoder.decode(value ?? new Uint8Array(), { stream: !done }).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    let separatorIndex = buffer.indexOf("\n\n");
+    while (separatorIndex !== -1) {
+      const block = buffer.slice(0, separatorIndex);
+      buffer = buffer.slice(separatorIndex + 2);
+      const payload = parseSSEBlock(block);
+      if (payload) {
+        const event = parseRuntimeEvent(payload);
+        if (onEvent) {
+          await onEvent(event);
+        }
+      }
+      separatorIndex = buffer.indexOf("\n\n");
+    }
+    if (done) {
+      break;
+    }
+  }
+  const trailingPayload = parseSSEBlock(buffer.trim());
+  if (trailingPayload) {
+    const event = parseRuntimeEvent(trailingPayload);
+    if (onEvent) {
+      await onEvent(event);
+    }
+  }
+}
+
+// src/client.ts
+var EmbeddedAgentClient = class {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  constructor({ baseUrl, apiKey, fetchImpl }) {
+    assertServerRuntime();
+    const normalizedApiKey = String(apiKey || "").trim();
+    if (!normalizedApiKey) {
+      throw new EmbeddedAgentSDKError("EmbeddedAgentClient requires a non-empty apiKey.", {
+        kind: "protocol"
+      });
+    }
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    this.apiKey = normalizedApiKey;
+    this.fetchImpl = resolveFetchImpl(fetchImpl);
+  }
+  async streamAgent(agentId, payload, onEvent) {
+    const response = await this.fetchOrThrow(
+      `${this.baseUrl}/public/embed/agents/${agentId}/chat/stream`,
+      {
+        method: "POST",
+        headers: buildStreamHeaders(this.apiKey),
+        body: JSON.stringify(payload)
+      },
+      "Failed to connect to the embedded-agent stream endpoint."
+    );
+    await assertOk(response);
+    const threadId = response.headers.get("X-Thread-ID");
+    await consumeEventStream(response, onEvent);
+    return { threadId };
+  }
+  async listAgentThreads(agentId, {
+    externalUserId,
+    externalSessionId,
+    skip = 0,
+    limit = 20
+  }) {
+    const search = new URLSearchParams({
+      external_user_id: externalUserId,
+      skip: String(skip),
+      limit: String(limit)
+    });
+    if (externalSessionId) {
+      search.set("external_session_id", externalSessionId);
+    }
+    return this.requestJson(
+      `${this.baseUrl}/public/embed/agents/${agentId}/threads?${search.toString()}`
+    );
+  }
+  async getAgentThread(agentId, threadId, {
+    externalUserId,
+    externalSessionId
+  }) {
+    const search = new URLSearchParams({
+      external_user_id: externalUserId
+    });
+    if (externalSessionId) {
+      search.set("external_session_id", externalSessionId);
+    }
+    return this.requestJson(
+      `${this.baseUrl}/public/embed/agents/${agentId}/threads/${threadId}?${search.toString()}`
+    );
+  }
+  async requestJson(url) {
+    const response = await this.fetchOrThrow(
+      url,
+      {
+        method: "GET",
+        headers: buildJsonHeaders(this.apiKey)
+      },
+      "Failed to connect to the embedded-agent API."
+    );
+    await assertOk(response);
+    return await response.json();
+  }
+  async fetchOrThrow(url, init, networkMessage) {
+    try {
+      return await this.fetchImpl(url, init);
+    } catch (cause) {
+      throw wrapNetworkError(networkMessage, cause);
+    }
+  }
+};
+
+exports.EmbeddedAgentClient = EmbeddedAgentClient;
+exports.EmbeddedAgentSDKError = EmbeddedAgentSDKError;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/http.ts","../src/sse.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["export type EmbeddedAgentSDKErrorKind = \"http\" | \"network\" | \"protocol\";\n\ntype EmbeddedAgentSDKErrorOptions = {\n  kind: EmbeddedAgentSDKErrorKind;\n  status?: number;\n  details?: unknown;\n  cause?: unknown;\n};\n\nexport class EmbeddedAgentSDKError extends Error {\n  public readonly kind: EmbeddedAgentSDKErrorKind;\n  public readonly status?: number;\n  public readonly details?: unknown;\n\n  constructor(message: string, options: EmbeddedAgentSDKErrorOptions) {\n    super(message, \"cause\" in Error.prototype ? { cause: options.cause } : undefined);\n    this.name = \"EmbeddedAgentSDKError\";\n    this.kind = options.kind;\n    this.status = options.status;\n    this.details = options.details;\n    if (!(\"cause\" in this) && options.cause !== undefined) {\n      Object.defineProperty(this, \"cause\", {\n        configurable: true,\n        enumerable: false,\n        value: options.cause,\n        writable: true,\n      });\n    }\n  }\n}\n","import { EmbeddedAgentSDKError } from \"./errors\";\n\nconst SERVER_ONLY_MESSAGE =\n  \"EmbeddedAgentClient is server-only. Keep your Talmudpedia API key on your backend and call the SDK from Node.\";\n\nexport function assertServerRuntime(): void {\n  if (typeof window !== \"undefined\" && typeof document !== \"undefined\") {\n    throw new EmbeddedAgentSDKError(SERVER_ONLY_MESSAGE, { kind: \"protocol\" });\n  }\n}\n\nexport function normalizeBaseUrl(baseUrl: string): string {\n  const normalized = String(baseUrl || \"\").trim().replace(/\\/+$/, \"\");\n  if (!normalized) {\n    throw new EmbeddedAgentSDKError(\"EmbeddedAgentClient requires a non-empty baseUrl.\", {\n      kind: \"protocol\",\n    });\n  }\n  try {\n    return new URL(normalized).toString().replace(/\\/+$/, \"\");\n  } catch (cause) {\n    throw new EmbeddedAgentSDKError(\"EmbeddedAgentClient received an invalid baseUrl.\", {\n      kind: \"protocol\",\n      cause,\n      details: { baseUrl },\n    });\n  }\n}\n\nexport function resolveFetchImpl(fetchImpl?: typeof fetch): typeof fetch {\n  if (fetchImpl) {\n    return fetchImpl;\n  }\n  if (typeof fetch === \"function\") {\n    return fetch;\n  }\n  throw new EmbeddedAgentSDKError(\n    \"No fetch implementation is available. Use Node 18.17+ or pass fetchImpl explicitly.\",\n    { kind: \"protocol\" },\n  );\n}\n\nexport function buildStreamHeaders(apiKey: string): HeadersInit {\n  return {\n    Authorization: `Bearer ${apiKey}`,\n    Accept: \"text/event-stream\",\n    \"Content-Type\": \"application/json\",\n  };\n}\n\nexport function buildJsonHeaders(apiKey: string): HeadersInit {\n  return {\n    Authorization: `Bearer ${apiKey}`,\n    Accept: \"application/json\",\n  };\n}\n\nfunction extractMessageFromDetails(details: unknown): string | undefined {\n  if (!details || typeof details !== \"object\" || Array.isArray(details)) {\n    return undefined;\n  }\n  const detail = (details as { detail?: unknown }).detail;\n  return typeof detail === \"string\" && detail.trim() ? detail.trim() : undefined;\n}\n\nasync function parseErrorDetails(response: Response): Promise<unknown> {\n  if (typeof response.text === \"function\") {\n    try {\n      const raw = await response.text();\n      if (!raw) {\n        return null;\n      }\n      try {\n        return JSON.parse(raw) as unknown;\n      } catch {\n        return raw;\n      }\n    } catch {\n      return null;\n    }\n  }\n  if (typeof response.json === \"function\") {\n    try {\n      return await response.json();\n    } catch {\n      return null;\n    }\n  }\n  return null;\n}\n\nexport async function assertOk(response: Response): Promise<void> {\n  if (response.ok) {\n    return;\n  }\n  const details = await parseErrorDetails(response);\n  const message =\n    extractMessageFromDetails(details) ||\n    (typeof details === \"string\" && details.trim()) ||\n    response.statusText ||\n    \"Request failed\";\n  throw new EmbeddedAgentSDKError(message, {\n    kind: \"http\",\n    status: response.status,\n    details,\n  });\n}\n\nexport function wrapNetworkError(message: string, cause: unknown): EmbeddedAgentSDKError {\n  if (cause instanceof EmbeddedAgentSDKError) {\n    return cause;\n  }\n  return new EmbeddedAgentSDKError(message, {\n    kind: \"network\",\n    cause,\n    details: cause instanceof Error ? { name: cause.name } : undefined,\n  });\n}\n","import { EmbeddedAgentSDKError } from \"./errors\";\nimport type { EmbeddedAgentRuntimeDiagnostic, EmbeddedAgentRuntimeEvent } from \"./types\";\n\nfunction parseSSEBlock(block: string): string | null {\n  const dataLines: string[] = [];\n  const lines = block.split(\"\\n\");\n  for (const line of lines) {\n    if (!line || line.startsWith(\":\")) {\n      continue;\n    }\n    const separatorIndex = line.indexOf(\":\");\n    const field = separatorIndex === -1 ? line : line.slice(0, separatorIndex);\n    let value = separatorIndex === -1 ? \"\" : line.slice(separatorIndex + 1);\n    if (value.startsWith(\" \")) {\n      value = value.slice(1);\n    }\n    if (field === \"data\") {\n      dataLines.push(value);\n    }\n  }\n  if (dataLines.length === 0) {\n    return null;\n  }\n  return dataLines.join(\"\\n\");\n}\n\nfunction assertDiagnostics(value: unknown): EmbeddedAgentRuntimeDiagnostic[] {\n  if (!Array.isArray(value)) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: diagnostics must be an array.\", {\n      kind: \"protocol\",\n      details: value,\n    });\n  }\n  return value.map((item) => {\n    if (!item || typeof item !== \"object\" || Array.isArray(item)) {\n      throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: diagnostics entries must be objects.\", {\n        kind: \"protocol\",\n        details: item,\n      });\n    }\n    return item as EmbeddedAgentRuntimeDiagnostic;\n  });\n}\n\nfunction assertPayload(value: unknown): Record<string, unknown> {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: payload must be an object.\", {\n      kind: \"protocol\",\n      details: value,\n    });\n  }\n  return value as Record<string, unknown>;\n}\n\nexport function parseRuntimeEvent(rawPayload: string): EmbeddedAgentRuntimeEvent {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(rawPayload) as unknown;\n  } catch (cause) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: invalid JSON payload.\", {\n      kind: \"protocol\",\n      cause,\n      details: rawPayload,\n    });\n  }\n\n  if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: expected an object envelope.\", {\n      kind: \"protocol\",\n      details: parsed,\n    });\n  }\n\n  const candidate = parsed as Record<string, unknown>;\n  if (candidate.version !== \"run-stream.v2\") {\n    throw new EmbeddedAgentSDKError(\n      \"Embedded-agent SSE protocol mismatch: expected run-stream.v2 event envelopes.\",\n      {\n        kind: \"protocol\",\n        details: candidate,\n      },\n    );\n  }\n\n  if (\n    typeof candidate.seq !== \"number\" ||\n    !Number.isFinite(candidate.seq) ||\n    typeof candidate.ts !== \"string\" ||\n    typeof candidate.event !== \"string\" ||\n    typeof candidate.run_id !== \"string\" ||\n    typeof candidate.stage !== \"string\"\n  ) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: missing required envelope fields.\", {\n      kind: \"protocol\",\n      details: candidate,\n    });\n  }\n\n  return {\n    version: \"run-stream.v2\",\n    seq: candidate.seq,\n    ts: candidate.ts,\n    event: candidate.event,\n    run_id: candidate.run_id,\n    stage: candidate.stage,\n    payload: assertPayload(candidate.payload ?? {}),\n    diagnostics: assertDiagnostics(candidate.diagnostics ?? []),\n  };\n}\n\nexport async function consumeEventStream(\n  response: Response,\n  onEvent?: (event: EmbeddedAgentRuntimeEvent) => void | Promise<void>,\n): Promise<void> {\n  if (!response.body) {\n    throw new EmbeddedAgentSDKError(\"Embedded-agent stream response did not include a readable body.\", {\n      kind: \"protocol\",\n    });\n  }\n\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = \"\";\n\n  while (true) {\n    const { done, value } = await reader.read();\n    buffer += decoder.decode(value ?? new Uint8Array(), { stream: !done }).replace(/\\r\\n/g, \"\\n\").replace(/\\r/g, \"\\n\");\n\n    let separatorIndex = buffer.indexOf(\"\\n\\n\");\n    while (separatorIndex !== -1) {\n      const block = buffer.slice(0, separatorIndex);\n      buffer = buffer.slice(separatorIndex + 2);\n      const payload = parseSSEBlock(block);\n      if (payload) {\n        const event = parseRuntimeEvent(payload);\n        if (onEvent) {\n          await onEvent(event);\n        }\n      }\n      separatorIndex = buffer.indexOf(\"\\n\\n\");\n    }\n\n    if (done) {\n      break;\n    }\n  }\n\n  const trailingPayload = parseSSEBlock(buffer.trim());\n  if (trailingPayload) {\n    const event = parseRuntimeEvent(trailingPayload);\n    if (onEvent) {\n      await onEvent(event);\n    }\n  }\n}\n","import { EmbeddedAgentSDKError } from \"./errors\";\nimport {\n  assertOk,\n  assertServerRuntime,\n  buildJsonHeaders,\n  buildStreamHeaders,\n  normalizeBaseUrl,\n  resolveFetchImpl,\n  wrapNetworkError,\n} from \"./http\";\nimport { consumeEventStream } from \"./sse\";\nimport type {\n  EmbeddedAgentClientOptions,\n  EmbeddedAgentRuntimeEvent,\n  EmbeddedAgentStreamRequest,\n  EmbeddedAgentThreadDetail,\n  EmbeddedAgentThreadDetailOptions,\n  EmbeddedAgentThreadListOptions,\n  EmbeddedAgentThreadsResponse,\n  StreamAgentResult,\n} from \"./types\";\n\nexport class EmbeddedAgentClient {\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor({ baseUrl, apiKey, fetchImpl }: EmbeddedAgentClientOptions) {\n    assertServerRuntime();\n    const normalizedApiKey = String(apiKey || \"\").trim();\n    if (!normalizedApiKey) {\n      throw new EmbeddedAgentSDKError(\"EmbeddedAgentClient requires a non-empty apiKey.\", {\n        kind: \"protocol\",\n      });\n    }\n    this.baseUrl = normalizeBaseUrl(baseUrl);\n    this.apiKey = normalizedApiKey;\n    this.fetchImpl = resolveFetchImpl(fetchImpl);\n  }\n\n  async streamAgent(\n    agentId: string,\n    payload: EmbeddedAgentStreamRequest,\n    onEvent?: (event: EmbeddedAgentRuntimeEvent) => void | Promise<void>,\n  ): Promise<StreamAgentResult> {\n    const response = await this.fetchOrThrow(\n      `${this.baseUrl}/public/embed/agents/${agentId}/chat/stream`,\n      {\n        method: \"POST\",\n        headers: buildStreamHeaders(this.apiKey),\n        body: JSON.stringify(payload),\n      },\n      \"Failed to connect to the embedded-agent stream endpoint.\",\n    );\n\n    await assertOk(response);\n    const threadId = response.headers.get(\"X-Thread-ID\");\n    await consumeEventStream(response, onEvent);\n    return { threadId };\n  }\n\n  async listAgentThreads(\n    agentId: string,\n    {\n      externalUserId,\n      externalSessionId,\n      skip = 0,\n      limit = 20,\n    }: EmbeddedAgentThreadListOptions,\n  ): Promise<EmbeddedAgentThreadsResponse> {\n    const search = new URLSearchParams({\n      external_user_id: externalUserId,\n      skip: String(skip),\n      limit: String(limit),\n    });\n    if (externalSessionId) {\n      search.set(\"external_session_id\", externalSessionId);\n    }\n    return this.requestJson<EmbeddedAgentThreadsResponse>(\n      `${this.baseUrl}/public/embed/agents/${agentId}/threads?${search.toString()}`,\n    );\n  }\n\n  async getAgentThread(\n    agentId: string,\n    threadId: string,\n    {\n      externalUserId,\n      externalSessionId,\n    }: EmbeddedAgentThreadDetailOptions,\n  ): Promise<EmbeddedAgentThreadDetail> {\n    const search = new URLSearchParams({\n      external_user_id: externalUserId,\n    });\n    if (externalSessionId) {\n      search.set(\"external_session_id\", externalSessionId);\n    }\n    return this.requestJson<EmbeddedAgentThreadDetail>(\n      `${this.baseUrl}/public/embed/agents/${agentId}/threads/${threadId}?${search.toString()}`,\n    );\n  }\n\n  private async requestJson<T>(url: string): Promise<T> {\n    const response = await this.fetchOrThrow(\n      url,\n      {\n        method: \"GET\",\n        headers: buildJsonHeaders(this.apiKey),\n      },\n      \"Failed to connect to the embedded-agent API.\",\n    );\n    await assertOk(response);\n    return (await response.json()) as T;\n  }\n\n  private async fetchOrThrow(url: string, init: RequestInit, networkMessage: string): Promise<Response> {\n    try {\n      return await this.fetchImpl(url, init);\n    } catch (cause) {\n      throw wrapNetworkError(networkMessage, cause);\n    }\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,106 @@
+type EmbeddedAgentSDKErrorKind = "http" | "network" | "protocol";
+type EmbeddedAgentSDKErrorOptions = {
+    kind: EmbeddedAgentSDKErrorKind;
+    status?: number;
+    details?: unknown;
+    cause?: unknown;
+};
+declare class EmbeddedAgentSDKError extends Error {
+    readonly kind: EmbeddedAgentSDKErrorKind;
+    readonly status?: number;
+    readonly details?: unknown;
+    constructor(message: string, options: EmbeddedAgentSDKErrorOptions);
+}
+
+type EmbeddedAgentStreamRequest = {
+    input?: string;
+    messages?: Array<Record<string, unknown>>;
+    thread_id?: string;
+    external_user_id: string;
+    external_session_id?: string;
+    metadata?: Record<string, unknown>;
+    client?: Record<string, unknown>;
+};
+type EmbeddedAgentThreadSummary = {
+    id: string;
+    agent_id: string | null;
+    external_user_id: string | null;
+    external_session_id: string | null;
+    title: string | null;
+    status: string;
+    surface: string;
+    last_run_id: string | null;
+    last_activity_at: string | null;
+    created_at: string;
+    updated_at: string;
+};
+type EmbeddedAgentThreadTurn = {
+    id: string;
+    run_id: string;
+    turn_index: number;
+    user_input_text: string | null;
+    assistant_output_text: string | null;
+    status: string;
+    usage_tokens: number;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    completed_at: string | null;
+};
+type EmbeddedAgentThreadDetail = EmbeddedAgentThreadSummary & {
+    turns: EmbeddedAgentThreadTurn[];
+};
+type EmbeddedAgentThreadsResponse = {
+    items: EmbeddedAgentThreadSummary[];
+    total: number;
+};
+type EmbeddedAgentRuntimeDiagnostic = {
+    message?: string;
+} & Record<string, unknown>;
+type EmbeddedAgentRuntimeEvent = {
+    version: "run-stream.v2";
+    seq: number;
+    ts: string;
+    event: string;
+    run_id: string;
+    stage: string;
+    payload: Record<string, unknown>;
+    diagnostics: EmbeddedAgentRuntimeDiagnostic[];
+};
+type StreamAgentResult = {
+    threadId: string | null;
+};
+type EmbeddedAgentThreadListOptions = {
+    externalUserId: string;
+    externalSessionId?: string;
+    skip?: number;
+    limit?: number;
+};
+type EmbeddedAgentThreadDetailOptions = {
+    externalUserId: string;
+    externalSessionId?: string;
+};
+type EmbeddedAgentClientOptions = {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+};
+type EmbeddedAgentSDKSerializedError = {
+    message: string;
+    kind: EmbeddedAgentSDKErrorKind;
+    status?: number;
+    details?: unknown;
+};
+
+declare class EmbeddedAgentClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor({ baseUrl, apiKey, fetchImpl }: EmbeddedAgentClientOptions);
+    streamAgent(agentId: string, payload: EmbeddedAgentStreamRequest, onEvent?: (event: EmbeddedAgentRuntimeEvent) => void | Promise<void>): Promise<StreamAgentResult>;
+    listAgentThreads(agentId: string, { externalUserId, externalSessionId, skip, limit, }: EmbeddedAgentThreadListOptions): Promise<EmbeddedAgentThreadsResponse>;
+    getAgentThread(agentId: string, threadId: string, { externalUserId, externalSessionId, }: EmbeddedAgentThreadDetailOptions): Promise<EmbeddedAgentThreadDetail>;
+    private requestJson;
+    private fetchOrThrow;
+}
+
+export { EmbeddedAgentClient, type EmbeddedAgentClientOptions, type EmbeddedAgentRuntimeDiagnostic, type EmbeddedAgentRuntimeEvent, EmbeddedAgentSDKError, type EmbeddedAgentSDKErrorKind, type EmbeddedAgentSDKSerializedError, type EmbeddedAgentStreamRequest, type EmbeddedAgentThreadDetail, type EmbeddedAgentThreadDetailOptions, type EmbeddedAgentThreadListOptions, type EmbeddedAgentThreadSummary, type EmbeddedAgentThreadTurn, type EmbeddedAgentThreadsResponse, type StreamAgentResult };

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+type EmbeddedAgentSDKErrorKind = "http" | "network" | "protocol";
+type EmbeddedAgentSDKErrorOptions = {
+    kind: EmbeddedAgentSDKErrorKind;
+    status?: number;
+    details?: unknown;
+    cause?: unknown;
+};
+declare class EmbeddedAgentSDKError extends Error {
+    readonly kind: EmbeddedAgentSDKErrorKind;
+    readonly status?: number;
+    readonly details?: unknown;
+    constructor(message: string, options: EmbeddedAgentSDKErrorOptions);
+}
+
+type EmbeddedAgentStreamRequest = {
+    input?: string;
+    messages?: Array<Record<string, unknown>>;
+    thread_id?: string;
+    external_user_id: string;
+    external_session_id?: string;
+    metadata?: Record<string, unknown>;
+    client?: Record<string, unknown>;
+};
+type EmbeddedAgentThreadSummary = {
+    id: string;
+    agent_id: string | null;
+    external_user_id: string | null;
+    external_session_id: string | null;
+    title: string | null;
+    status: string;
+    surface: string;
+    last_run_id: string | null;
+    last_activity_at: string | null;
+    created_at: string;
+    updated_at: string;
+};
+type EmbeddedAgentThreadTurn = {
+    id: string;
+    run_id: string;
+    turn_index: number;
+    user_input_text: string | null;
+    assistant_output_text: string | null;
+    status: string;
+    usage_tokens: number;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    completed_at: string | null;
+};
+type EmbeddedAgentThreadDetail = EmbeddedAgentThreadSummary & {
+    turns: EmbeddedAgentThreadTurn[];
+};
+type EmbeddedAgentThreadsResponse = {
+    items: EmbeddedAgentThreadSummary[];
+    total: number;
+};
+type EmbeddedAgentRuntimeDiagnostic = {
+    message?: string;
+} & Record<string, unknown>;
+type EmbeddedAgentRuntimeEvent = {
+    version: "run-stream.v2";
+    seq: number;
+    ts: string;
+    event: string;
+    run_id: string;
+    stage: string;
+    payload: Record<string, unknown>;
+    diagnostics: EmbeddedAgentRuntimeDiagnostic[];
+};
+type StreamAgentResult = {
+    threadId: string | null;
+};
+type EmbeddedAgentThreadListOptions = {
+    externalUserId: string;
+    externalSessionId?: string;
+    skip?: number;
+    limit?: number;
+};
+type EmbeddedAgentThreadDetailOptions = {
+    externalUserId: string;
+    externalSessionId?: string;
+};
+type EmbeddedAgentClientOptions = {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+};
+type EmbeddedAgentSDKSerializedError = {
+    message: string;
+    kind: EmbeddedAgentSDKErrorKind;
+    status?: number;
+    details?: unknown;
+};
+
+declare class EmbeddedAgentClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor({ baseUrl, apiKey, fetchImpl }: EmbeddedAgentClientOptions);
+    streamAgent(agentId: string, payload: EmbeddedAgentStreamRequest, onEvent?: (event: EmbeddedAgentRuntimeEvent) => void | Promise<void>): Promise<StreamAgentResult>;
+    listAgentThreads(agentId: string, { externalUserId, externalSessionId, skip, limit, }: EmbeddedAgentThreadListOptions): Promise<EmbeddedAgentThreadsResponse>;
+    getAgentThread(agentId: string, threadId: string, { externalUserId, externalSessionId, }: EmbeddedAgentThreadDetailOptions): Promise<EmbeddedAgentThreadDetail>;
+    private requestJson;
+    private fetchOrThrow;
+}
+
+export { EmbeddedAgentClient, type EmbeddedAgentClientOptions, type EmbeddedAgentRuntimeDiagnostic, type EmbeddedAgentRuntimeEvent, EmbeddedAgentSDKError, type EmbeddedAgentSDKErrorKind, type EmbeddedAgentSDKSerializedError, type EmbeddedAgentStreamRequest, type EmbeddedAgentThreadDetail, type EmbeddedAgentThreadDetailOptions, type EmbeddedAgentThreadListOptions, type EmbeddedAgentThreadSummary, type EmbeddedAgentThreadTurn, type EmbeddedAgentThreadsResponse, type StreamAgentResult };

package/dist/index.js

@@ -0,0 +1,345 @@
+// src/errors.ts
+var EmbeddedAgentSDKError = class extends Error {
+  kind;
+  status;
+  details;
+  constructor(message, options) {
+    super(message, "cause" in Error.prototype ? { cause: options.cause } : void 0);
+    this.name = "EmbeddedAgentSDKError";
+    this.kind = options.kind;
+    this.status = options.status;
+    this.details = options.details;
+    if (!("cause" in this) && options.cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        configurable: true,
+        enumerable: false,
+        value: options.cause,
+        writable: true
+      });
+    }
+  }
+};
+
+// src/http.ts
+var SERVER_ONLY_MESSAGE = "EmbeddedAgentClient is server-only. Keep your Talmudpedia API key on your backend and call the SDK from Node.";
+function assertServerRuntime() {
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    throw new EmbeddedAgentSDKError(SERVER_ONLY_MESSAGE, { kind: "protocol" });
+  }
+}
+function normalizeBaseUrl(baseUrl) {
+  const normalized = String(baseUrl || "").trim().replace(/\/+$/, "");
+  if (!normalized) {
+    throw new EmbeddedAgentSDKError("EmbeddedAgentClient requires a non-empty baseUrl.", {
+      kind: "protocol"
+    });
+  }
+  try {
+    return new URL(normalized).toString().replace(/\/+$/, "");
+  } catch (cause) {
+    throw new EmbeddedAgentSDKError("EmbeddedAgentClient received an invalid baseUrl.", {
+      kind: "protocol",
+      cause,
+      details: { baseUrl }
+    });
+  }
+}
+function resolveFetchImpl(fetchImpl) {
+  if (fetchImpl) {
+    return fetchImpl;
+  }
+  if (typeof fetch === "function") {
+    return fetch;
+  }
+  throw new EmbeddedAgentSDKError(
+    "No fetch implementation is available. Use Node 18.17+ or pass fetchImpl explicitly.",
+    { kind: "protocol" }
+  );
+}
+function buildStreamHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    Accept: "text/event-stream",
+    "Content-Type": "application/json"
+  };
+}
+function buildJsonHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    Accept: "application/json"
+  };
+}
+function extractMessageFromDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    return void 0;
+  }
+  const detail = details.detail;
+  return typeof detail === "string" && detail.trim() ? detail.trim() : void 0;
+}
+async function parseErrorDetails(response) {
+  if (typeof response.text === "function") {
+    try {
+      const raw = await response.text();
+      if (!raw) {
+        return null;
+      }
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return raw;
+      }
+    } catch {
+      return null;
+    }
+  }
+  if (typeof response.json === "function") {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+async function assertOk(response) {
+  if (response.ok) {
+    return;
+  }
+  const details = await parseErrorDetails(response);
+  const message = extractMessageFromDetails(details) || typeof details === "string" && details.trim() || response.statusText || "Request failed";
+  throw new EmbeddedAgentSDKError(message, {
+    kind: "http",
+    status: response.status,
+    details
+  });
+}
+function wrapNetworkError(message, cause) {
+  if (cause instanceof EmbeddedAgentSDKError) {
+    return cause;
+  }
+  return new EmbeddedAgentSDKError(message, {
+    kind: "network",
+    cause,
+    details: cause instanceof Error ? { name: cause.name } : void 0
+  });
+}
+
+// src/sse.ts
+function parseSSEBlock(block) {
+  const dataLines = [];
+  const lines = block.split("\n");
+  for (const line of lines) {
+    if (!line || line.startsWith(":")) {
+      continue;
+    }
+    const separatorIndex = line.indexOf(":");
+    const field = separatorIndex === -1 ? line : line.slice(0, separatorIndex);
+    let value = separatorIndex === -1 ? "" : line.slice(separatorIndex + 1);
+    if (value.startsWith(" ")) {
+      value = value.slice(1);
+    }
+    if (field === "data") {
+      dataLines.push(value);
+    }
+  }
+  if (dataLines.length === 0) {
+    return null;
+  }
+  return dataLines.join("\n");
+}
+function assertDiagnostics(value) {
+  if (!Array.isArray(value)) {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: diagnostics must be an array.", {
+      kind: "protocol",
+      details: value
+    });
+  }
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: diagnostics entries must be objects.", {
+        kind: "protocol",
+        details: item
+      });
+    }
+    return item;
+  });
+}
+function assertPayload(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: payload must be an object.", {
+      kind: "protocol",
+      details: value
+    });
+  }
+  return value;
+}
+function parseRuntimeEvent(rawPayload) {
+  let parsed;
+  try {
+    parsed = JSON.parse(rawPayload);
+  } catch (cause) {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: invalid JSON payload.", {
+      kind: "protocol",
+      cause,
+      details: rawPayload
+    });
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: expected an object envelope.", {
+      kind: "protocol",
+      details: parsed
+    });
+  }
+  const candidate = parsed;
+  if (candidate.version !== "run-stream.v2") {
+    throw new EmbeddedAgentSDKError(
+      "Embedded-agent SSE protocol mismatch: expected run-stream.v2 event envelopes.",
+      {
+        kind: "protocol",
+        details: candidate
+      }
+    );
+  }
+  if (typeof candidate.seq !== "number" || !Number.isFinite(candidate.seq) || typeof candidate.ts !== "string" || typeof candidate.event !== "string" || typeof candidate.run_id !== "string" || typeof candidate.stage !== "string") {
+    throw new EmbeddedAgentSDKError("Malformed embedded-agent SSE event: missing required envelope fields.", {
+      kind: "protocol",
+      details: candidate
+    });
+  }
+  return {
+    version: "run-stream.v2",
+    seq: candidate.seq,
+    ts: candidate.ts,
+    event: candidate.event,
+    run_id: candidate.run_id,
+    stage: candidate.stage,
+    payload: assertPayload(candidate.payload ?? {}),
+    diagnostics: assertDiagnostics(candidate.diagnostics ?? [])
+  };
+}
+async function consumeEventStream(response, onEvent) {
+  if (!response.body) {
+    throw new EmbeddedAgentSDKError("Embedded-agent stream response did not include a readable body.", {
+      kind: "protocol"
+    });
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    buffer += decoder.decode(value ?? new Uint8Array(), { stream: !done }).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    let separatorIndex = buffer.indexOf("\n\n");
+    while (separatorIndex !== -1) {
+      const block = buffer.slice(0, separatorIndex);
+      buffer = buffer.slice(separatorIndex + 2);
+      const payload = parseSSEBlock(block);
+      if (payload) {
+        const event = parseRuntimeEvent(payload);
+        if (onEvent) {
+          await onEvent(event);
+        }
+      }
+      separatorIndex = buffer.indexOf("\n\n");
+    }
+    if (done) {
+      break;
+    }
+  }
+  const trailingPayload = parseSSEBlock(buffer.trim());
+  if (trailingPayload) {
+    const event = parseRuntimeEvent(trailingPayload);
+    if (onEvent) {
+      await onEvent(event);
+    }
+  }
+}
+
+// src/client.ts
+var EmbeddedAgentClient = class {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  constructor({ baseUrl, apiKey, fetchImpl }) {
+    assertServerRuntime();
+    const normalizedApiKey = String(apiKey || "").trim();
+    if (!normalizedApiKey) {
+      throw new EmbeddedAgentSDKError("EmbeddedAgentClient requires a non-empty apiKey.", {
+        kind: "protocol"
+      });
+    }
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    this.apiKey = normalizedApiKey;
+    this.fetchImpl = resolveFetchImpl(fetchImpl);
+  }
+  async streamAgent(agentId, payload, onEvent) {
+    const response = await this.fetchOrThrow(
+      `${this.baseUrl}/public/embed/agents/${agentId}/chat/stream`,
+      {
+        method: "POST",
+        headers: buildStreamHeaders(this.apiKey),
+        body: JSON.stringify(payload)
+      },
+      "Failed to connect to the embedded-agent stream endpoint."
+    );
+    await assertOk(response);
+    const threadId = response.headers.get("X-Thread-ID");
+    await consumeEventStream(response, onEvent);
+    return { threadId };
+  }
+  async listAgentThreads(agentId, {
+    externalUserId,
+    externalSessionId,
+    skip = 0,
+    limit = 20
+  }) {
+    const search = new URLSearchParams({
+      external_user_id: externalUserId,
+      skip: String(skip),
+      limit: String(limit)
+    });
+    if (externalSessionId) {
+      search.set("external_session_id", externalSessionId);
+    }
+    return this.requestJson(
+      `${this.baseUrl}/public/embed/agents/${agentId}/threads?${search.toString()}`
+    );
+  }
+  async getAgentThread(agentId, threadId, {
+    externalUserId,
+    externalSessionId
+  }) {
+    const search = new URLSearchParams({
+      external_user_id: externalUserId
+    });
+    if (externalSessionId) {
+      search.set("external_session_id", externalSessionId);
+    }
+    return this.requestJson(
+      `${this.baseUrl}/public/embed/agents/${agentId}/threads/${threadId}?${search.toString()}`
+    );
+  }
+  async requestJson(url) {
+    const response = await this.fetchOrThrow(
+      url,
+      {
+        method: "GET",
+        headers: buildJsonHeaders(this.apiKey)
+      },
+      "Failed to connect to the embedded-agent API."
+    );
+    await assertOk(response);
+    return await response.json();
+  }
+  async fetchOrThrow(url, init, networkMessage) {
+    try {
+      return await this.fetchImpl(url, init);
+    } catch (cause) {
+      throw wrapNetworkError(networkMessage, cause);
+    }
+  }
+};
+
+export { EmbeddedAgentClient, EmbeddedAgentSDKError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/http.ts","../src/sse.ts","../src/client.ts"],"names":[],"mappings":";AASO,IAAM,qBAAA,GAAN,cAAoC,KAAA,CAAM;AAAA,EAC/B,IAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EAEhB,WAAA,CAAY,SAAiB,OAAA,EAAuC;AAClE,IAAA,KAAA,CAAM,OAAA,EAAS,WAAW,KAAA,CAAM,SAAA,GAAY,EAAE,KAAA,EAAO,OAAA,CAAQ,KAAA,EAAM,GAAI,MAAS,CAAA;AAChF,IAAA,IAAA,CAAK,IAAA,GAAO,uBAAA;AACZ,IAAA,IAAA,CAAK,OAAO,OAAA,CAAQ,IAAA;AACpB,IAAA,IAAA,CAAK,SAAS,OAAA,CAAQ,MAAA;AACtB,IAAA,IAAA,CAAK,UAAU,OAAA,CAAQ,OAAA;AACvB,IAAA,IAAI,EAAE,OAAA,IAAW,IAAA,CAAA,IAAS,OAAA,CAAQ,UAAU,MAAA,EAAW;AACrD,MAAA,MAAA,CAAO,cAAA,CAAe,MAAM,OAAA,EAAS;AAAA,QACnC,YAAA,EAAc,IAAA;AAAA,QACd,UAAA,EAAY,KAAA;AAAA,QACZ,OAAO,OAAA,CAAQ,KAAA;AAAA,QACf,QAAA,EAAU;AAAA,OACX,CAAA;AAAA,IACH;AAAA,EACF;AACF;;;AC3BA,IAAM,mBAAA,GACJ,+GAAA;AAEK,SAAS,mBAAA,GAA4B;AAC1C,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,IAAe,OAAO,aAAa,WAAA,EAAa;AACpE,IAAA,MAAM,IAAI,qBAAA,CAAsB,mBAAA,EAAqB,EAAE,IAAA,EAAM,YAAY,CAAA;AAAA,EAC3E;AACF;AAEO,SAAS,iBAAiB,OAAA,EAAyB;AACxD,EAAA,MAAM,UAAA,GAAa,OAAO,OAAA,IAAW,EAAE,EAAE,IAAA,EAAK,CAAE,OAAA,CAAQ,MAAA,EAAQ,EAAE,CAAA;AAClE,EAAA,IAAI,CAAC,UAAA,EAAY;AACf,IAAA,MAAM,IAAI,sBAAsB,mDAAA,EAAqD;AAAA,MACnF,IAAA,EAAM;AAAA,KACP,CAAA;AAAA,EACH;AACA,EAAA,IAAI;AACF,IAAA,OAAO,IAAI,IAAI,UAAU,CAAA,CAAE,UAAS,CAAE,OAAA,CAAQ,QAAQ,EAAE,CAAA;AAAA,EAC1D,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAI,sBAAsB,kDAAA,EAAoD;AAAA,MAClF,IAAA,EAAM,UAAA;AAAA,MACN,KAAA;AAAA,MACA,OAAA,EAAS,EAAE,OAAA;AAAQ,KACpB,CAAA;AAAA,EACH;AACF;AAEO,SAAS,iBAAiB,SAAA,EAAwC;AACvE,EAAA,IAAI,SAAA,EAAW;AACb,IAAA,OAAO,SAAA;AAAA,EACT;AACA,EAAA,IAAI,OAAO,UAAU,UAAA,EAAY;AAC/B,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,MAAM,IAAI,qBAAA;AAAA,IACR,qFAAA;AAAA,IACA,EAAE,MAAM,UAAA;AAAW,GACrB;AACF;AAEO,SAAS,mBAAmB,MAAA,EAA6B;AAC9D,EAAA,OAAO;AAAA,IACL,aAAA,EAAe,UAAU,MAAM,CAAA,CAAA;AAAA,IAC/B,MAAA,EAAQ,mBAAA;AAAA,IACR,cAAA,EAAgB;AAAA,GAClB;AACF;AAEO,SAAS,iBAAiB,MAAA,EAA6B;AAC5D,EAAA,OAAO;AAAA,IACL,aAAA,EAAe,UAAU,MAAM,CAAA,CAAA;AAAA,IAC/B,MAAA,EAAQ;AAAA,GACV;AACF;AAEA,SAAS,0BAA0B,OAAA,EAAsC;AACvE,EAAA,IAAI,CAAC,WAAW,OAAO,OAAA,KAAY,YAAY,KAAA,CAAM,OAAA,CAAQ,OAAO,CAAA,EAAG;AACrE,IAAA,OAAO,MAAA;AAAA,EACT;AACA,EAAA,MAAM,SAAU,OAAA,CAAiC,MAAA;AACjD,EAAA,OAAO,OAAO,WAAW,QAAA,IAAY,MAAA,CAAO,MAAK,GAAI,MAAA,CAAO,MAAK,GAAI,MAAA;AACvE;AAEA,eAAe,kBAAkB,QAAA,EAAsC;AACrE,EAAA,IAAI,OAAO,QAAA,CAAS,IAAA,KAAS,UAAA,EAAY;AACvC,IAAA,IAAI;AACF,MAAA,MAAM,GAAA,GAAM,MAAM,QAAA,CAAS,IAAA,EAAK;AAChC,MAAA,IAAI,CAAC,GAAA,EAAK;AACR,QAAA,OAAO,IAAA;AAAA,MACT;AACA,MAAA,IAAI;AACF,QAAA,OAAO,IAAA,CAAK,MAAM,GAAG,CAAA;AAAA,MACvB,CAAA,CAAA,MAAQ;AACN,QAAA,OAAO,GAAA;AAAA,MACT;AAAA,IACF,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF;AACA,EAAA,IAAI,OAAO,QAAA,CAAS,IAAA,KAAS,UAAA,EAAY;AACvC,IAAA,IAAI;AACF,MAAA,OAAO,MAAM,SAAS,IAAA,EAAK;AAAA,IAC7B,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF;AACA,EAAA,OAAO,IAAA;AACT;AAEA,eAAsB,SAAS,QAAA,EAAmC;AAChE,EAAA,IAAI,SAAS,EAAA,EAAI;AACf,IAAA;AAAA,EACF;AACA,EAAA,MAAM,OAAA,GAAU,MAAM,iBAAA,CAAkB,QAAQ,CAAA;AAChD,EAAA,MAAM,OAAA,GACJ,yBAAA,CAA0B,OAAO,CAAA,IAChC,OAAO,OAAA,KAAY,QAAA,IAAY,OAAA,CAAQ,IAAA,EAAK,IAC7C,QAAA,CAAS,UAAA,IACT,gBAAA;AACF,EAAA,MAAM,IAAI,sBAAsB,OAAA,EAAS;AAAA,IACvC,IAAA,EAAM,MAAA;AAAA,IACN,QAAQ,QAAA,CAAS,MAAA;AAAA,IACjB;AAAA,GACD,CAAA;AACH;AAEO,SAAS,gBAAA,CAAiB,SAAiB,KAAA,EAAuC;AACvF,EAAA,IAAI,iBAAiB,qBAAA,EAAuB;AAC1C,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,OAAO,IAAI,sBAAsB,OAAA,EAAS;AAAA,IACxC,IAAA,EAAM,SAAA;AAAA,IACN,KAAA;AAAA,IACA,SAAS,KAAA,YAAiB,KAAA,GAAQ,EAAE,IAAA,EAAM,KAAA,CAAM,MAAK,GAAI;AAAA,GAC1D,CAAA;AACH;;;AClHA,SAAS,cAAc,KAAA,EAA8B;AACnD,EAAA,MAAM,YAAsB,EAAC;AAC7B,EAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,KAAA,CAAM,IAAI,CAAA;AAC9B,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,IAAI,CAAC,IAAA,IAAQ,IAAA,CAAK,UAAA,CAAW,GAAG,CAAA,EAAG;AACjC,MAAA;AAAA,IACF;AACA,IAAA,MAAM,cAAA,GAAiB,IAAA,CAAK,OAAA,CAAQ,GAAG,CAAA;AACvC,IAAA,MAAM,QAAQ,cAAA,KAAmB,EAAA,GAAK,OAAO,IAAA,CAAK,KAAA,CAAM,GAAG,cAAc,CAAA;AACzE,IAAA,IAAI,QAAQ,cAAA,KAAmB,EAAA,GAAK,KAAK,IAAA,CAAK,KAAA,CAAM,iBAAiB,CAAC,CAAA;AACtE,IAAA,IAAI,KAAA,CAAM,UAAA,CAAW,GAAG,CAAA,EAAG;AACzB,MAAA,KAAA,GAAQ,KAAA,CAAM,MAAM,CAAC,CAAA;AAAA,IACvB;AACA,IAAA,IAAI,UAAU,MAAA,EAAQ;AACpB,MAAA,SAAA,CAAU,KAAK,KAAK,CAAA;AAAA,IACtB;AAAA,EACF;AACA,EAAA,IAAI,SAAA,CAAU,WAAW,CAAA,EAAG;AAC1B,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,OAAO,SAAA,CAAU,KAAK,IAAI,CAAA;AAC5B;AAEA,SAAS,kBAAkB,KAAA,EAAkD;AAC3E,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACzB,IAAA,MAAM,IAAI,sBAAsB,mEAAA,EAAqE;AAAA,MACnG,IAAA,EAAM,UAAA;AAAA,MACN,OAAA,EAAS;AAAA,KACV,CAAA;AAAA,EACH;AACA,EAAA,OAAO,KAAA,CAAM,GAAA,CAAI,CAAC,IAAA,KAAS;AACzB,IAAA,IAAI,CAAC,QAAQ,OAAO,IAAA,KAAS,YAAY,KAAA,CAAM,OAAA,CAAQ,IAAI,CAAA,EAAG;AAC5D,MAAA,MAAM,IAAI,sBAAsB,0EAAA,EAA4E;AAAA,QAC1G,IAAA,EAAM,UAAA;AAAA,QACN,OAAA,EAAS;AAAA,OACV,CAAA;AAAA,IACH;AACA,IAAA,OAAO,IAAA;AAAA,EACT,CAAC,CAAA;AACH;AAEA,SAAS,cAAc,KAAA,EAAyC;AAC9D,EAAA,IAAI,CAAC,SAAS,OAAO,KAAA,KAAU,YAAY,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AAC/D,IAAA,MAAM,IAAI,sBAAsB,gEAAA,EAAkE;AAAA,MAChG,IAAA,EAAM,UAAA;AAAA,MACN,OAAA,EAAS;AAAA,KACV,CAAA;AAAA,EACH;AACA,EAAA,OAAO,KAAA;AACT;AAEO,SAAS,kBAAkB,UAAA,EAA+C;AAC/E,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,IAAA,CAAK,MAAM,UAAU,CAAA;AAAA,EAChC,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAI,sBAAsB,2DAAA,EAA6D;AAAA,MAC3F,IAAA,EAAM,UAAA;AAAA,MACN,KAAA;AAAA,MACA,OAAA,EAAS;AAAA,KACV,CAAA;AAAA,EACH;AAEA,EAAA,IAAI,CAAC,UAAU,OAAO,MAAA,KAAW,YAAY,KAAA,CAAM,OAAA,CAAQ,MAAM,CAAA,EAAG;AAClE,IAAA,MAAM,IAAI,sBAAsB,kEAAA,EAAoE;AAAA,MAClG,IAAA,EAAM,UAAA;AAAA,MACN,OAAA,EAAS;AAAA,KACV,CAAA;AAAA,EACH;AAEA,EAAA,MAAM,SAAA,GAAY,MAAA;AAClB,EAAA,IAAI,SAAA,CAAU,YAAY,eAAA,EAAiB;AACzC,IAAA,MAAM,IAAI,qBAAA;AAAA,MACR,+EAAA;AAAA,MACA;AAAA,QACE,IAAA,EAAM,UAAA;AAAA,QACN,OAAA,EAAS;AAAA;AACX,KACF;AAAA,EACF;AAEA,EAAA,IACE,OAAO,SAAA,CAAU,GAAA,KAAQ,QAAA,IACzB,CAAC,OAAO,QAAA,CAAS,SAAA,CAAU,GAAG,CAAA,IAC9B,OAAO,SAAA,CAAU,OAAO,QAAA,IACxB,OAAO,SAAA,CAAU,KAAA,KAAU,QAAA,IAC3B,OAAO,SAAA,CAAU,MAAA,KAAW,QAAA,IAC5B,OAAO,SAAA,CAAU,KAAA,KAAU,QAAA,EAC3B;AACA,IAAA,MAAM,IAAI,sBAAsB,uEAAA,EAAyE;AAAA,MACvG,IAAA,EAAM,UAAA;AAAA,MACN,OAAA,EAAS;AAAA,KACV,CAAA;AAAA,EACH;AAEA,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,eAAA;AAAA,IACT,KAAK,SAAA,CAAU,GAAA;AAAA,IACf,IAAI,SAAA,CAAU,EAAA;AAAA,IACd,OAAO,SAAA,CAAU,KAAA;AAAA,IACjB,QAAQ,SAAA,CAAU,MAAA;AAAA,IAClB,OAAO,SAAA,CAAU,KAAA;AAAA,IACjB,OAAA,EAAS,aAAA,CAAc,SAAA,CAAU,OAAA,IAAW,EAAE,CAAA;AAAA,IAC9C,WAAA,EAAa,iBAAA,CAAkB,SAAA,CAAU,WAAA,IAAe,EAAE;AAAA,GAC5D;AACF;AAEA,eAAsB,kBAAA,CACpB,UACA,OAAA,EACe;AACf,EAAA,IAAI,CAAC,SAAS,IAAA,EAAM;AAClB,IAAA,MAAM,IAAI,sBAAsB,iEAAA,EAAmE;AAAA,MACjG,IAAA,EAAM;AAAA,KACP,CAAA;AAAA,EACH;AAEA,EAAA,MAAM,MAAA,GAAS,QAAA,CAAS,IAAA,CAAK,SAAA,EAAU;AACvC,EAAA,MAAM,OAAA,GAAU,IAAI,WAAA,EAAY;AAChC,EAAA,IAAI,MAAA,GAAS,EAAA;AAEb,EAAA,OAAO,IAAA,EAAM;AACX,IAAA,MAAM,EAAE,IAAA,EAAM,KAAA,EAAM,GAAI,MAAM,OAAO,IAAA,EAAK;AAC1C,IAAA,MAAA,IAAU,QAAQ,MAAA,CAAO,KAAA,IAAS,IAAI,UAAA,EAAW,EAAG,EAAE,MAAA,EAAQ,CAAC,IAAA,EAAM,EAAE,OAAA,CAAQ,OAAA,EAAS,IAAI,CAAA,CAAE,OAAA,CAAQ,OAAO,IAAI,CAAA;AAEjH,IAAA,IAAI,cAAA,GAAiB,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA;AAC1C,IAAA,OAAO,mBAAmB,EAAA,EAAI;AAC5B,MAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,cAAc,CAAA;AAC5C,MAAA,MAAA,GAAS,MAAA,CAAO,KAAA,CAAM,cAAA,GAAiB,CAAC,CAAA;AACxC,MAAA,MAAM,OAAA,GAAU,cAAc,KAAK,CAAA;AACnC,MAAA,IAAI,OAAA,EAAS;AACX,QAAA,MAAM,KAAA,GAAQ,kBAAkB,OAAO,CAAA;AACvC,QAAA,IAAI,OAAA,EAAS;AACX,UAAA,MAAM,QAAQ,KAAK,CAAA;AAAA,QACrB;AAAA,MACF;AACA,MAAA,cAAA,GAAiB,MAAA,CAAO,QAAQ,MAAM,CAAA;AAAA,IACxC;AAEA,IAAA,IAAI,IAAA,EAAM;AACR,MAAA;AAAA,IACF;AAAA,EACF;AAEA,EAAA,MAAM,eAAA,GAAkB,aAAA,CAAc,MAAA,CAAO,IAAA,EAAM,CAAA;AACnD,EAAA,IAAI,eAAA,EAAiB;AACnB,IAAA,MAAM,KAAA,GAAQ,kBAAkB,eAAe,CAAA;AAC/C,IAAA,IAAI,OAAA,EAAS;AACX,MAAA,MAAM,QAAQ,KAAK,CAAA;AAAA,IACrB;AAAA,EACF;AACF;;;ACpIO,IAAM,sBAAN,MAA0B;AAAA,EACd,OAAA;AAAA,EACA,MAAA;AAAA,EACA,SAAA;AAAA,EAEjB,WAAA,CAAY,EAAE,OAAA,EAAS,MAAA,EAAQ,WAAU,EAA+B;AACtE,IAAA,mBAAA,EAAoB;AACpB,IAAA,MAAM,gBAAA,GAAmB,MAAA,CAAO,MAAA,IAAU,EAAE,EAAE,IAAA,EAAK;AACnD,IAAA,IAAI,CAAC,gBAAA,EAAkB;AACrB,MAAA,MAAM,IAAI,sBAAsB,kDAAA,EAAoD;AAAA,QAClF,IAAA,EAAM;AAAA,OACP,CAAA;AAAA,IACH;AACA,IAAA,IAAA,CAAK,OAAA,GAAU,iBAAiB,OAAO,CAAA;AACvC,IAAA,IAAA,CAAK,MAAA,GAAS,gBAAA;AACd,IAAA,IAAA,CAAK,SAAA,GAAY,iBAAiB,SAAS,CAAA;AAAA,EAC7C;AAAA,EAEA,MAAM,WAAA,CACJ,OAAA,EACA,OAAA,EACA,OAAA,EAC4B;AAC5B,IAAA,MAAM,QAAA,GAAW,MAAM,IAAA,CAAK,YAAA;AAAA,MAC1B,CAAA,EAAG,IAAA,CAAK,OAAO,CAAA,qBAAA,EAAwB,OAAO,CAAA,YAAA,CAAA;AAAA,MAC9C;AAAA,QACE,MAAA,EAAQ,MAAA;AAAA,QACR,OAAA,EAAS,kBAAA,CAAmB,IAAA,CAAK,MAAM,CAAA;AAAA,QACvC,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,OAAO;AAAA,OAC9B;AAAA,MACA;AAAA,KACF;AAEA,IAAA,MAAM,SAAS,QAAQ,CAAA;AACvB,IAAA,MAAM,QAAA,GAAW,QAAA,CAAS,OAAA,CAAQ,GAAA,CAAI,aAAa,CAAA;AACnD,IAAA,MAAM,kBAAA,CAAmB,UAAU,OAAO,CAAA;AAC1C,IAAA,OAAO,EAAE,QAAA,EAAS;AAAA,EACpB;AAAA,EAEA,MAAM,iBACJ,OAAA,EACA;AAAA,IACE,cAAA;AAAA,IACA,iBAAA;AAAA,IACA,IAAA,GAAO,CAAA;AAAA,IACP,KAAA,GAAQ;AAAA,GACV,EACuC;AACvC,IAAA,MAAM,MAAA,GAAS,IAAI,eAAA,CAAgB;AAAA,MACjC,gBAAA,EAAkB,cAAA;AAAA,MAClB,IAAA,EAAM,OAAO,IAAI,CAAA;AAAA,MACjB,KAAA,EAAO,OAAO,KAAK;AAAA,KACpB,CAAA;AACD,IAAA,IAAI,iBAAA,EAAmB;AACrB,MAAA,MAAA,CAAO,GAAA,CAAI,uBAAuB,iBAAiB,CAAA;AAAA,IACrD;AACA,IAAA,OAAO,IAAA,CAAK,WAAA;AAAA,MACV,CAAA,EAAG,KAAK,OAAO,CAAA,qBAAA,EAAwB,OAAO,CAAA,SAAA,EAAY,MAAA,CAAO,UAAU,CAAA;AAAA,KAC7E;AAAA,EACF;AAAA,EAEA,MAAM,cAAA,CACJ,OAAA,EACA,QAAA,EACA;AAAA,IACE,cAAA;AAAA,IACA;AAAA,GACF,EACoC;AACpC,IAAA,MAAM,MAAA,GAAS,IAAI,eAAA,CAAgB;AAAA,MACjC,gBAAA,EAAkB;AAAA,KACnB,CAAA;AACD,IAAA,IAAI,iBAAA,EAAmB;AACrB,MAAA,MAAA,CAAO,GAAA,CAAI,uBAAuB,iBAAiB,CAAA;AAAA,IACrD;AACA,IAAA,OAAO,IAAA,CAAK,WAAA;AAAA,MACV,CAAA,EAAG,IAAA,CAAK,OAAO,CAAA,qBAAA,EAAwB,OAAO,YAAY,QAAQ,CAAA,CAAA,EAAI,MAAA,CAAO,QAAA,EAAU,CAAA;AAAA,KACzF;AAAA,EACF;AAAA,EAEA,MAAc,YAAe,GAAA,EAAyB;AACpD,IAAA,MAAM,QAAA,GAAW,MAAM,IAAA,CAAK,YAAA;AAAA,MAC1B,GAAA;AAAA,MACA;AAAA,QACE,MAAA,EAAQ,KAAA;AAAA,QACR,OAAA,EAAS,gBAAA,CAAiB,IAAA,CAAK,MAAM;AAAA,OACvC;AAAA,MACA;AAAA,KACF;AACA,IAAA,MAAM,SAAS,QAAQ,CAAA;AACvB,IAAA,OAAQ,MAAM,SAAS,IAAA,EAAK;AAAA,EAC9B;AAAA,EAEA,MAAc,YAAA,CAAa,GAAA,EAAa,IAAA,EAAmB,cAAA,EAA2C;AACpG,IAAA,IAAI;AACF,MAAA,OAAO,MAAM,IAAA,CAAK,SAAA,CAAU,GAAA,EAAK,IAAI,CAAA;AAAA,IACvC,SAAS,KAAA,EAAO;AACd,MAAA,MAAM,gBAAA,CAAiB,gBAAgB,KAAK,CAAA;AAAA,IAC9C;AAAA,EACF;AACF","file":"index.js","sourcesContent":["export type EmbeddedAgentSDKErrorKind = \"http\" | \"network\" | \"protocol\";\n\ntype EmbeddedAgentSDKErrorOptions = {\n  kind: EmbeddedAgentSDKErrorKind;\n  status?: number;\n  details?: unknown;\n  cause?: unknown;\n};\n\nexport class EmbeddedAgentSDKError extends Error {\n  public readonly kind: EmbeddedAgentSDKErrorKind;\n  public readonly status?: number;\n  public readonly details?: unknown;\n\n  constructor(message: string, options: EmbeddedAgentSDKErrorOptions) {\n    super(message, \"cause\" in Error.prototype ? { cause: options.cause } : undefined);\n    this.name = \"EmbeddedAgentSDKError\";\n    this.kind = options.kind;\n    this.status = options.status;\n    this.details = options.details;\n    if (!(\"cause\" in this) && options.cause !== undefined) {\n      Object.defineProperty(this, \"cause\", {\n        configurable: true,\n        enumerable: false,\n        value: options.cause,\n        writable: true,\n      });\n    }\n  }\n}\n","import { EmbeddedAgentSDKError } from \"./errors\";\n\nconst SERVER_ONLY_MESSAGE =\n  \"EmbeddedAgentClient is server-only. Keep your Talmudpedia API key on your backend and call the SDK from Node.\";\n\nexport function assertServerRuntime(): void {\n  if (typeof window !== \"undefined\" && typeof document !== \"undefined\") {\n    throw new EmbeddedAgentSDKError(SERVER_ONLY_MESSAGE, { kind: \"protocol\" });\n  }\n}\n\nexport function normalizeBaseUrl(baseUrl: string): string {\n  const normalized = String(baseUrl || \"\").trim().replace(/\\/+$/, \"\");\n  if (!normalized) {\n    throw new EmbeddedAgentSDKError(\"EmbeddedAgentClient requires a non-empty baseUrl.\", {\n      kind: \"protocol\",\n    });\n  }\n  try {\n    return new URL(normalized).toString().replace(/\\/+$/, \"\");\n  } catch (cause) {\n    throw new EmbeddedAgentSDKError(\"EmbeddedAgentClient received an invalid baseUrl.\", {\n      kind: \"protocol\",\n      cause,\n      details: { baseUrl },\n    });\n  }\n}\n\nexport function resolveFetchImpl(fetchImpl?: typeof fetch): typeof fetch {\n  if (fetchImpl) {\n    return fetchImpl;\n  }\n  if (typeof fetch === \"function\") {\n    return fetch;\n  }\n  throw new EmbeddedAgentSDKError(\n    \"No fetch implementation is available. Use Node 18.17+ or pass fetchImpl explicitly.\",\n    { kind: \"protocol\" },\n  );\n}\n\nexport function buildStreamHeaders(apiKey: string): HeadersInit {\n  return {\n    Authorization: `Bearer ${apiKey}`,\n    Accept: \"text/event-stream\",\n    \"Content-Type\": \"application/json\",\n  };\n}\n\nexport function buildJsonHeaders(apiKey: string): HeadersInit {\n  return {\n    Authorization: `Bearer ${apiKey}`,\n    Accept: \"application/json\",\n  };\n}\n\nfunction extractMessageFromDetails(details: unknown): string | undefined {\n  if (!details || typeof details !== \"object\" || Array.isArray(details)) {\n    return undefined;\n  }\n  const detail = (details as { detail?: unknown }).detail;\n  return typeof detail === \"string\" && detail.trim() ? detail.trim() : undefined;\n}\n\nasync function parseErrorDetails(response: Response): Promise<unknown> {\n  if (typeof response.text === \"function\") {\n    try {\n      const raw = await response.text();\n      if (!raw) {\n        return null;\n      }\n      try {\n        return JSON.parse(raw) as unknown;\n      } catch {\n        return raw;\n      }\n    } catch {\n      return null;\n    }\n  }\n  if (typeof response.json === \"function\") {\n    try {\n      return await response.json();\n    } catch {\n      return null;\n    }\n  }\n  return null;\n}\n\nexport async function assertOk(response: Response): Promise<void> {\n  if (response.ok) {\n    return;\n  }\n  const details = await parseErrorDetails(response);\n  const message =\n    extractMessageFromDetails(details) ||\n    (typeof details === \"string\" && details.trim()) ||\n    response.statusText ||\n    \"Request failed\";\n  throw new EmbeddedAgentSDKError(message, {\n    kind: \"http\",\n    status: response.status,\n    details,\n  });\n}\n\nexport function wrapNetworkError(message: string, cause: unknown): EmbeddedAgentSDKError {\n  if (cause instanceof EmbeddedAgentSDKError) {\n    return cause;\n  }\n  return new EmbeddedAgentSDKError(message, {\n    kind: \"network\",\n    cause,\n    details: cause instanceof Error ? { name: cause.name } : undefined,\n  });\n}\n","import { EmbeddedAgentSDKError } from \"./errors\";\nimport type { EmbeddedAgentRuntimeDiagnostic, EmbeddedAgentRuntimeEvent } from \"./types\";\n\nfunction parseSSEBlock(block: string): string | null {\n  const dataLines: string[] = [];\n  const lines = block.split(\"\\n\");\n  for (const line of lines) {\n    if (!line || line.startsWith(\":\")) {\n      continue;\n    }\n    const separatorIndex = line.indexOf(\":\");\n    const field = separatorIndex === -1 ? line : line.slice(0, separatorIndex);\n    let value = separatorIndex === -1 ? \"\" : line.slice(separatorIndex + 1);\n    if (value.startsWith(\" \")) {\n      value = value.slice(1);\n    }\n    if (field === \"data\") {\n      dataLines.push(value);\n    }\n  }\n  if (dataLines.length === 0) {\n    return null;\n  }\n  return dataLines.join(\"\\n\");\n}\n\nfunction assertDiagnostics(value: unknown): EmbeddedAgentRuntimeDiagnostic[] {\n  if (!Array.isArray(value)) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: diagnostics must be an array.\", {\n      kind: \"protocol\",\n      details: value,\n    });\n  }\n  return value.map((item) => {\n    if (!item || typeof item !== \"object\" || Array.isArray(item)) {\n      throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: diagnostics entries must be objects.\", {\n        kind: \"protocol\",\n        details: item,\n      });\n    }\n    return item as EmbeddedAgentRuntimeDiagnostic;\n  });\n}\n\nfunction assertPayload(value: unknown): Record<string, unknown> {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: payload must be an object.\", {\n      kind: \"protocol\",\n      details: value,\n    });\n  }\n  return value as Record<string, unknown>;\n}\n\nexport function parseRuntimeEvent(rawPayload: string): EmbeddedAgentRuntimeEvent {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(rawPayload) as unknown;\n  } catch (cause) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: invalid JSON payload.\", {\n      kind: \"protocol\",\n      cause,\n      details: rawPayload,\n    });\n  }\n\n  if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: expected an object envelope.\", {\n      kind: \"protocol\",\n      details: parsed,\n    });\n  }\n\n  const candidate = parsed as Record<string, unknown>;\n  if (candidate.version !== \"run-stream.v2\") {\n    throw new EmbeddedAgentSDKError(\n      \"Embedded-agent SSE protocol mismatch: expected run-stream.v2 event envelopes.\",\n      {\n        kind: \"protocol\",\n        details: candidate,\n      },\n    );\n  }\n\n  if (\n    typeof candidate.seq !== \"number\" ||\n    !Number.isFinite(candidate.seq) ||\n    typeof candidate.ts !== \"string\" ||\n    typeof candidate.event !== \"string\" ||\n    typeof candidate.run_id !== \"string\" ||\n    typeof candidate.stage !== \"string\"\n  ) {\n    throw new EmbeddedAgentSDKError(\"Malformed embedded-agent SSE event: missing required envelope fields.\", {\n      kind: \"protocol\",\n      details: candidate,\n    });\n  }\n\n  return {\n    version: \"run-stream.v2\",\n    seq: candidate.seq,\n    ts: candidate.ts,\n    event: candidate.event,\n    run_id: candidate.run_id,\n    stage: candidate.stage,\n    payload: assertPayload(candidate.payload ?? {}),\n    diagnostics: assertDiagnostics(candidate.diagnostics ?? []),\n  };\n}\n\nexport async function consumeEventStream(\n  response: Response,\n  onEvent?: (event: EmbeddedAgentRuntimeEvent) => void | Promise<void>,\n): Promise<void> {\n  if (!response.body) {\n    throw new EmbeddedAgentSDKError(\"Embedded-agent stream response did not include a readable body.\", {\n      kind: \"protocol\",\n    });\n  }\n\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = \"\";\n\n  while (true) {\n    const { done, value } = await reader.read();\n    buffer += decoder.decode(value ?? new Uint8Array(), { stream: !done }).replace(/\\r\\n/g, \"\\n\").replace(/\\r/g, \"\\n\");\n\n    let separatorIndex = buffer.indexOf(\"\\n\\n\");\n    while (separatorIndex !== -1) {\n      const block = buffer.slice(0, separatorIndex);\n      buffer = buffer.slice(separatorIndex + 2);\n      const payload = parseSSEBlock(block);\n      if (payload) {\n        const event = parseRuntimeEvent(payload);\n        if (onEvent) {\n          await onEvent(event);\n        }\n      }\n      separatorIndex = buffer.indexOf(\"\\n\\n\");\n    }\n\n    if (done) {\n      break;\n    }\n  }\n\n  const trailingPayload = parseSSEBlock(buffer.trim());\n  if (trailingPayload) {\n    const event = parseRuntimeEvent(trailingPayload);\n    if (onEvent) {\n      await onEvent(event);\n    }\n  }\n}\n","import { EmbeddedAgentSDKError } from \"./errors\";\nimport {\n  assertOk,\n  assertServerRuntime,\n  buildJsonHeaders,\n  buildStreamHeaders,\n  normalizeBaseUrl,\n  resolveFetchImpl,\n  wrapNetworkError,\n} from \"./http\";\nimport { consumeEventStream } from \"./sse\";\nimport type {\n  EmbeddedAgentClientOptions,\n  EmbeddedAgentRuntimeEvent,\n  EmbeddedAgentStreamRequest,\n  EmbeddedAgentThreadDetail,\n  EmbeddedAgentThreadDetailOptions,\n  EmbeddedAgentThreadListOptions,\n  EmbeddedAgentThreadsResponse,\n  StreamAgentResult,\n} from \"./types\";\n\nexport class EmbeddedAgentClient {\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor({ baseUrl, apiKey, fetchImpl }: EmbeddedAgentClientOptions) {\n    assertServerRuntime();\n    const normalizedApiKey = String(apiKey || \"\").trim();\n    if (!normalizedApiKey) {\n      throw new EmbeddedAgentSDKError(\"EmbeddedAgentClient requires a non-empty apiKey.\", {\n        kind: \"protocol\",\n      });\n    }\n    this.baseUrl = normalizeBaseUrl(baseUrl);\n    this.apiKey = normalizedApiKey;\n    this.fetchImpl = resolveFetchImpl(fetchImpl);\n  }\n\n  async streamAgent(\n    agentId: string,\n    payload: EmbeddedAgentStreamRequest,\n    onEvent?: (event: EmbeddedAgentRuntimeEvent) => void | Promise<void>,\n  ): Promise<StreamAgentResult> {\n    const response = await this.fetchOrThrow(\n      `${this.baseUrl}/public/embed/agents/${agentId}/chat/stream`,\n      {\n        method: \"POST\",\n        headers: buildStreamHeaders(this.apiKey),\n        body: JSON.stringify(payload),\n      },\n      \"Failed to connect to the embedded-agent stream endpoint.\",\n    );\n\n    await assertOk(response);\n    const threadId = response.headers.get(\"X-Thread-ID\");\n    await consumeEventStream(response, onEvent);\n    return { threadId };\n  }\n\n  async listAgentThreads(\n    agentId: string,\n    {\n      externalUserId,\n      externalSessionId,\n      skip = 0,\n      limit = 20,\n    }: EmbeddedAgentThreadListOptions,\n  ): Promise<EmbeddedAgentThreadsResponse> {\n    const search = new URLSearchParams({\n      external_user_id: externalUserId,\n      skip: String(skip),\n      limit: String(limit),\n    });\n    if (externalSessionId) {\n      search.set(\"external_session_id\", externalSessionId);\n    }\n    return this.requestJson<EmbeddedAgentThreadsResponse>(\n      `${this.baseUrl}/public/embed/agents/${agentId}/threads?${search.toString()}`,\n    );\n  }\n\n  async getAgentThread(\n    agentId: string,\n    threadId: string,\n    {\n      externalUserId,\n      externalSessionId,\n    }: EmbeddedAgentThreadDetailOptions,\n  ): Promise<EmbeddedAgentThreadDetail> {\n    const search = new URLSearchParams({\n      external_user_id: externalUserId,\n    });\n    if (externalSessionId) {\n      search.set(\"external_session_id\", externalSessionId);\n    }\n    return this.requestJson<EmbeddedAgentThreadDetail>(\n      `${this.baseUrl}/public/embed/agents/${agentId}/threads/${threadId}?${search.toString()}`,\n    );\n  }\n\n  private async requestJson<T>(url: string): Promise<T> {\n    const response = await this.fetchOrThrow(\n      url,\n      {\n        method: \"GET\",\n        headers: buildJsonHeaders(this.apiKey),\n      },\n      \"Failed to connect to the embedded-agent API.\",\n    );\n    await assertOk(response);\n    return (await response.json()) as T;\n  }\n\n  private async fetchOrThrow(url: string, init: RequestInit, networkMessage: string): Promise<Response> {\n    try {\n      return await this.fetchImpl(url, init);\n    } catch (cause) {\n      throw wrapNetworkError(networkMessage, cause);\n    }\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@agents24/embed-sdk",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Server-only TypeScript SDK for Talmudpedia embedded-agent runtime.",
+  "keywords": [
+    "talmudpedia",
+    "agent",
+    "embed",
+    "sdk",
+    "sse",
+    "node"
+  ],
+  "author": "Talmudpedia",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daniel5426/talmudpedia.git",
+    "directory": "packages/embed-sdk"
+  },
+  "homepage": "https://github.com/daniel5426/talmudpedia/tree/main/packages/embed-sdk",
+  "bugs": {
+    "url": "https://github.com/daniel5426/talmudpedia/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsup",
+    "prepack": "npm run build",
+    "smoke:pack": "node ./scripts/smoke-pack.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  }
+}