@convosite/client 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Convosite
+
+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

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# @convosite/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic JavaScript and TypeScript client for building Convosite conversational experiences. It has no runtime dependencies and uses the platform `fetch` API, so it works in browsers, Node 18+, React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, Bun and other modern JavaScript runtimes.
+
+Convosite's client-side runtime is intentionally small: developers define **blocks** and **endpoints** through the CLI, content is managed as **knowledge** inside Convosite, and applications consume conversations and invoke public endpoint actions. Knowledge is retrieved internally by the conversation runtime and is not exposed as a headless CMS API.
+
+## Install
+
+```bash
+npm install @convosite/client
+```
+
+## Quick start
+
+```ts
+import { createConvosite } from '@convosite/client';
+
+const convosite = createConvosite({
+  site: 'YOUR_SITE_ULID',
+});
+
+const conversation = convosite.conversations.create();
+
+for await (const event of conversation.send('What services do you offer?')) {
+  console.log(event);
+}
+```
+
+Production defaults to `https://app.convosite.io/api`. No API token belongs in frontend code. Protected site variables remain server-side and can be used by endpoint actions without being exposed to the browser.
+
+## Conversations
+
+Conversations are streamed from the Convosite runtime as NDJSON. The SDK parses the stream and manages the `X-Conversation-Session` header automatically.
+
+```ts
+const conversation = convosite.conversations.create();
+
+for await (const event of conversation.send('Help me choose the right service.')) {
+  if (event.type === 'field_delta') {
+    console.log(event.path, event.delta);
+  }
+
+  if (event.type === 'field_complete') {
+    console.log(event.path, event.value);
+  }
+
+  if (event.type === 'conversation_usage') {
+    console.log(event.user_turns, event.max_user_turns);
+  }
+
+  if (event.type === 'complete') {
+    console.log('Turn complete');
+  }
+}
+
+// Continues the same server-side conversation.
+for await (const event of conversation.send('Tell me more.')) {
+  console.log(event);
+}
+
+await conversation.end();
+```
+
+Use `conversation.sessionId` to inspect the current session. `conversation.reset()` forgets the session locally without ending it on the server.
+
+### Manage session IDs yourself
+
+```ts
+for await (const event of convosite.conversations.send('Hello', {
+  sessionId: 'SESSION_UUID',
+})) {
+  console.log(event);
+}
+
+await convosite.conversations.end('SESSION_UUID');
+```
+
+## Actions
+
+Invoke an endpoint defined by the developer and pushed through `@convosite/cli`:
+
+```ts
+await convosite.actions.run('ENDPOINT_ULID', {
+  name: 'Joe',
+  email: 'joe@example.com',
+  message: 'Hello',
+});
+```
+
+Only public input is sent by the client. Site variables such as API tokens remain server-side and are resolved by Convosite when the endpoint action runs.
+
+## Knowledge
+
+Knowledge is intentionally not exposed by this package. Knowledge and Knowledge Items are managed in Convosite and indexed for retrieval. The conversation runtime uses that knowledge when generating conversational experiences.
+
+This keeps application code focused on conversations rather than turning Knowledge into another public content API.
+
+## Cancellation
+
+Actions and conversation streams accept an `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+
+for await (const event of convosite.conversations.send('Hello', {
+  signal: controller.signal,
+})) {
+  console.log(event);
+}
+
+controller.abort();
+```
+
+## SSR and custom fetch
+
+A custom `fetch` can be supplied for framework runtimes, instrumentation or tests:
+
+```ts
+const convosite = createConvosite({
+  site: 'YOUR_SITE_ULID',
+  fetch: customFetch,
+});
+```
+
+## Errors
+
+```ts
+import { ConvositeError } from '@convosite/client';
+
+try {
+  await convosite.actions.run('ENDPOINT_ULID', {});
+} catch (error) {
+  if (error instanceof ConvositeError) {
+    console.log(error.status);
+    console.log(error.code);
+    console.log(error.message);
+    console.log(error.details);
+    console.log(error.requestId);
+  }
+}
+```
+
+Validation errors are available through `details`. Conversation error codes such as `conversation_ended` and `conversation_limit_reached` are exposed through `code` when returned by the runtime.
+
+## Raw request escape hatch
+
+For public Laravel API endpoints that are not yet wrapped by the SDK:
+
+```ts
+const data = await convosite.request('/some/runtime/endpoint');
+```
+
+The path is relative to `baseUrl` and uses the same error handling, timeout and configured headers as actions.
+
+## Configuration
+
+```ts
+const convosite = createConvosite({
+  site: 'YOUR_SITE_ULID',
+  baseUrl: 'https://app.convosite.io/api',
+  conversationUrl: 'https://app.convosite.io/api',
+  timeout: 30_000,
+  headers: {},
+  fetch: globalThis.fetch,
+});
+```
+
+`baseUrl` is used for actions and raw requests. `conversationUrl` is used for streamed conversations and defaults to `baseUrl`.
+
+The timeout applies to normal JSON requests. Conversation streams intentionally have no fixed SDK timeout; use an `AbortSignal` when needed.

package/dist/index.cjs

@@ -0,0 +1,317 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConvositeError: () => ConvositeError,
+  createConvosite: () => createConvosite
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var ConvositeError = class extends Error {
+  status;
+  code;
+  details;
+  requestId;
+  constructor(options) {
+    super(options.message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "ConvositeError";
+    this.status = options.status ?? 0;
+    this.code = options.code ?? null;
+    this.details = options.details ?? null;
+    this.requestId = options.requestId ?? null;
+  }
+};
+
+// src/http.ts
+function normalizeBaseUrl(value) {
+  return value.replace(/\/+$/, "");
+}
+function joinUrl(base, path) {
+  if (/^https?:\/\//i.test(path)) return path;
+  return `${normalizeBaseUrl(base)}/${path.replace(/^\/+/, "")}`;
+}
+function encodeSegment(value) {
+  return encodeURIComponent(value);
+}
+function timeoutSignal(signal, timeout) {
+  if (timeout <= 0) return signal ? { signal, cleanup: () => void 0 } : { cleanup: () => void 0 };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new DOMException("Request timed out.", "TimeoutError")), timeout);
+  const abort = () => controller.abort(signal?.reason);
+  if (signal) {
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+    }
+  };
+}
+async function responseBody(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function errorFrom(response, body) {
+  const object = body && typeof body === "object" ? body : {};
+  const message = typeof object.message === "string" ? object.message : `Convosite request failed with status ${response.status}.`;
+  const code = typeof object.error === "string" ? object.error : null;
+  const details = object.errors ?? body;
+  return new ConvositeError({
+    message,
+    status: response.status,
+    code,
+    details,
+    requestId: response.headers.get("X-Request-ID")
+  });
+}
+var HttpClient = class {
+  constructor(fetcher, baseUrl, headers, timeout) {
+    this.fetcher = fetcher;
+    this.baseUrl = baseUrl;
+    this.headers = headers;
+    this.timeout = timeout;
+  }
+  fetcher;
+  baseUrl;
+  headers;
+  timeout;
+  async api(path, init = {}) {
+    const response = await this.fetch(path, init, true);
+    const body = await responseBody(response);
+    if (!response.ok) throw errorFrom(response, body);
+    if (!body || typeof body !== "object" || !("success" in body)) {
+      throw new ConvositeError({ message: "Convosite returned an invalid API response.", status: response.status, details: body });
+    }
+    const envelope = body;
+    if (envelope.success !== true) {
+      throw new ConvositeError({ message: envelope.message || "Convosite request failed.", status: response.status, details: envelope.errors });
+    }
+    return envelope.data;
+  }
+  async raw(path, options = {}) {
+    const { parseAs = "json", ...init } = options;
+    const response = await this.fetch(path, init, true);
+    if (!response.ok) throw errorFrom(response, await responseBody(response));
+    if (parseAs === "response") return response;
+    if (parseAs === "text") return await response.text();
+    if (response.status === 204) return void 0;
+    return await response.json();
+  }
+  async fetch(path, init = {}, useTimeout = false) {
+    const headers = new Headers(this.headers);
+    new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+    const timed = useTimeout ? timeoutSignal(init.signal ?? void 0, this.timeout) : timeoutSignal(init.signal ?? void 0, 0);
+    try {
+      const requestInit = { ...init, headers };
+      if (timed.signal) requestInit.signal = timed.signal;
+      return await this.fetcher(joinUrl(this.baseUrl, path), requestInit);
+    } catch (cause) {
+      if (cause instanceof ConvositeError) throw cause;
+      const aborted = timed.signal?.aborted;
+      throw new ConvositeError({
+        message: aborted ? "Convosite request was aborted." : "Unable to connect to Convosite.",
+        code: aborted ? "request_aborted" : "network_error",
+        cause
+      });
+    } finally {
+      timed.cleanup();
+    }
+  }
+};
+async function workerError(response) {
+  return errorFrom(response, await responseBody(response));
+}
+
+// src/conversations.ts
+async function* parseNdjson(response) {
+  if (!response.body) throw new ConvositeError({ message: "Conversation response did not contain a stream.", status: response.status });
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done });
+      let newline;
+      while ((newline = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line) yield parseEvent(line);
+      }
+      if (done) break;
+    }
+    const tail = buffer.trim();
+    if (tail) yield parseEvent(tail);
+  } finally {
+    reader.releaseLock();
+  }
+}
+function parseEvent(line) {
+  try {
+    const event = JSON.parse(line);
+    if (!event || typeof event !== "object" || typeof event.type !== "string") {
+      throw new Error("Event has no type.");
+    }
+    return event;
+  } catch (cause) {
+    throw new ConvositeError({ message: "Conversation stream contained an invalid event.", code: "invalid_stream", details: line, cause });
+  }
+}
+var ConversationsClient = class {
+  constructor(fetcher, baseUrl, siteId) {
+    this.fetcher = fetcher;
+    this.baseUrl = baseUrl;
+    this.siteId = siteId;
+  }
+  fetcher;
+  baseUrl;
+  siteId;
+  create(sessionId) {
+    let currentSession = sessionId?.trim() || null;
+    const client = this;
+    return {
+      get sessionId() {
+        return currentSession;
+      },
+      async *send(query, options = {}) {
+        const stream = client.send(query, { ...options, ...currentSession ? { sessionId: currentSession } : {} }, (id) => {
+          currentSession = id;
+        });
+        yield* stream;
+      },
+      async end(options = {}) {
+        if (!currentSession) return { ended: false };
+        const result = await client.end(currentSession, options);
+        if (result.ended) currentSession = null;
+        return result;
+      },
+      reset() {
+        currentSession = null;
+      }
+    };
+  }
+  async *send(query, options = {}, onSession) {
+    const trimmed = query.trim();
+    if (!trimmed) throw new ConvositeError({ message: "Conversation query is required.", code: "validation_error" });
+    const headers = new Headers({ "Content-Type": "application/json", "Accept": "application/x-ndjson" });
+    if (options.sessionId) headers.set("X-Conversation-Session", options.sessionId);
+    let response;
+    try {
+      const init = { method: "POST", headers, body: JSON.stringify({ query: trimmed }) };
+      if (options.signal) init.signal = options.signal;
+      response = await this.fetcher(joinUrl(this.baseUrl, `/conversations/${encodeSegment(this.siteId)}`), init);
+    } catch (cause) {
+      throw new ConvositeError({ message: options.signal?.aborted ? "Conversation request was aborted." : "Unable to connect to Convosite conversations.", code: options.signal?.aborted ? "request_aborted" : "network_error", cause });
+    }
+    if (!response.ok) throw await workerError(response);
+    const session = response.headers.get("X-Conversation-Session");
+    if (session) onSession?.(session);
+    yield* parseNdjson(response);
+  }
+  async end(sessionId, options = {}) {
+    const headers = new Headers({ "Accept": "application/json", "X-Conversation-Session": sessionId });
+    let response;
+    try {
+      const init = { method: "POST", headers };
+      if (options.signal) init.signal = options.signal;
+      response = await this.fetcher(joinUrl(this.baseUrl, `/conversations/${encodeSegment(this.siteId)}/end`), init);
+    } catch (cause) {
+      throw new ConvositeError({ message: options.signal?.aborted ? "Conversation request was aborted." : "Unable to connect to Convosite conversations.", code: options.signal?.aborted ? "request_aborted" : "network_error", cause });
+    }
+    if (!response.ok) throw await workerError(response);
+    return await response.json();
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://app.convosite.io/api";
+function createConvosite(config) {
+  if (!config || typeof config.site !== "string" || !config.site.trim()) {
+    throw new ConvositeError({
+      message: "A Convosite site ID is required.",
+      code: "invalid_config"
+    });
+  }
+  const fetcher = config.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (!fetcher) {
+    throw new ConvositeError({
+      message: "No fetch implementation is available.",
+      code: "invalid_config"
+    });
+  }
+  const siteId = config.site.trim();
+  const site = encodeSegment(siteId);
+  const baseUrl = normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL);
+  const conversationUrl = normalizeBaseUrl(config.conversationUrl ?? baseUrl);
+  const http = new HttpClient(
+    fetcher,
+    baseUrl,
+    config.headers ?? {},
+    config.timeout ?? 3e4
+  );
+  const conversations = new ConversationsClient(fetcher, conversationUrl, siteId);
+  const requestOptions = (options) => options?.signal ? { signal: options.signal } : {};
+  return {
+    actions: {
+      run: (endpointId, input, options) => {
+        if (typeof endpointId !== "string" || !endpointId.trim()) {
+          throw new ConvositeError({
+            message: "An endpoint ID is required.",
+            code: "validation_error"
+          });
+        }
+        return http.api(
+          `/actions/${site}/${encodeSegment(endpointId.trim())}`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Accept: "application/json"
+            },
+            body: JSON.stringify(input),
+            ...requestOptions(options)
+          }
+        );
+      }
+    },
+    conversations: {
+      create: (sessionId) => conversations.create(sessionId),
+      send: (query, options) => conversations.send(query, options),
+      end: (sessionId, options) => conversations.end(sessionId, options)
+    },
+    request: (path, options = {}) => http.raw(path, options)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConvositeError,
+  createConvosite
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/http.ts","../src/conversations.ts","../src/client.ts"],"sourcesContent":["export { createConvosite } from './client';\nexport { ConvositeError } from './errors';\nexport type {\n  ActionResponse,\n  Conversation,\n  ConversationCompleteEvent,\n  ConversationEndResponse,\n  ConversationErrorEvent,\n  ConversationEvent,\n  ConversationFieldEvent,\n  ConversationSendOptions,\n  ConversationUsageEvent,\n  ConvositeClient,\n  ConvositeConfig,\n  Fetch,\n  JsonPrimitive,\n  JsonValue,\n  RawRequestOptions,\n  RequestOptions,\n} from './types';\n","export class ConvositeError extends Error {\n  readonly status: number;\n  readonly code: string | null;\n  readonly details: unknown;\n  readonly requestId: string | null;\n\n  constructor(options: {\n    message: string;\n    status?: number;\n    code?: string | null;\n    details?: unknown;\n    requestId?: string | null;\n    cause?: unknown;\n  }) {\n    super(options.message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = 'ConvositeError';\n    this.status = options.status ?? 0;\n    this.code = options.code ?? null;\n    this.details = options.details ?? null;\n    this.requestId = options.requestId ?? null;\n  }\n}\n","import { ConvositeError } from './errors';\nimport type { Fetch, RawRequestOptions } from './types';\n\ninterface ApiEnvelope<T> {\n  success: boolean;\n  message: string;\n  data: T;\n  errors: unknown;\n}\n\nexport function normalizeBaseUrl(value: string): string {\n  return value.replace(/\\/+$/, '');\n}\n\nexport function joinUrl(base: string, path: string): string {\n  if (/^https?:\\/\\//i.test(path)) return path;\n  return `${normalizeBaseUrl(base)}/${path.replace(/^\\/+/, '')}`;\n}\n\nexport function encodeSegment(value: string): string {\n  return encodeURIComponent(value);\n}\n\nfunction timeoutSignal(signal: AbortSignal | undefined, timeout: number): { signal?: AbortSignal; cleanup: () => void } {\n  if (timeout <= 0) return signal ? { signal, cleanup: () => undefined } : { cleanup: () => undefined };\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(new DOMException('Request timed out.', 'TimeoutError')), timeout);\n  const abort = () => controller.abort(signal?.reason);\n  if (signal) {\n    if (signal.aborted) abort();\n    else signal.addEventListener('abort', abort, { once: true });\n  }\n  return {\n    signal: controller.signal,\n    cleanup: () => {\n      clearTimeout(timer);\n      signal?.removeEventListener('abort', abort);\n    },\n  };\n}\n\nasync function responseBody(response: Response): Promise<unknown> {\n  const text = await response.text();\n  if (!text) return null;\n  try { return JSON.parse(text); } catch { return text; }\n}\n\nfunction errorFrom(response: Response, body: unknown): ConvositeError {\n  const object = body && typeof body === 'object' ? body as Record<string, unknown> : {};\n  const message = typeof object.message === 'string' ? object.message : `Convosite request failed with status ${response.status}.`;\n  const code = typeof object.error === 'string' ? object.error : null;\n  const details = object.errors ?? body;\n  return new ConvositeError({\n    message,\n    status: response.status,\n    code,\n    details,\n    requestId: response.headers.get('X-Request-ID'),\n  });\n}\n\nexport class HttpClient {\n  constructor(\n    private readonly fetcher: Fetch,\n    private readonly baseUrl: string,\n    private readonly headers: HeadersInit,\n    private readonly timeout: number,\n  ) {}\n\n  async api<T>(path: string, init: RequestInit = {}): Promise<T> {\n    const response = await this.fetch(path, init, true);\n    const body = await responseBody(response);\n    if (!response.ok) throw errorFrom(response, body);\n    if (!body || typeof body !== 'object' || !('success' in body)) {\n      throw new ConvositeError({ message: 'Convosite returned an invalid API response.', status: response.status, details: body });\n    }\n    const envelope = body as ApiEnvelope<T>;\n    if (envelope.success !== true) {\n      throw new ConvositeError({ message: envelope.message || 'Convosite request failed.', status: response.status, details: envelope.errors });\n    }\n    return envelope.data;\n  }\n\n  async raw<T>(path: string, options: RawRequestOptions = {}): Promise<T> {\n    const { parseAs = 'json', ...init } = options;\n    const response = await this.fetch(path, init, true);\n    if (!response.ok) throw errorFrom(response, await responseBody(response));\n    if (parseAs === 'response') return response as T;\n    if (parseAs === 'text') return await response.text() as T;\n    if (response.status === 204) return undefined as T;\n    return await response.json() as T;\n  }\n\n  async fetch(path: string, init: RequestInit = {}, useTimeout = false): Promise<Response> {\n    const headers = new Headers(this.headers);\n    new Headers(init.headers).forEach((value, key) => headers.set(key, value));\n    const timed = useTimeout ? timeoutSignal(init.signal ?? undefined, this.timeout) : timeoutSignal(init.signal ?? undefined, 0);\n    try {\n      const requestInit: RequestInit = { ...init, headers };\n      if (timed.signal) requestInit.signal = timed.signal;\n      return await this.fetcher(joinUrl(this.baseUrl, path), requestInit);\n    } catch (cause) {\n      if (cause instanceof ConvositeError) throw cause;\n      const aborted = timed.signal?.aborted;\n      throw new ConvositeError({\n        message: aborted ? 'Convosite request was aborted.' : 'Unable to connect to Convosite.',\n        code: aborted ? 'request_aborted' : 'network_error',\n        cause,\n      });\n    } finally {\n      timed.cleanup();\n    }\n  }\n}\n\nexport async function workerError(response: Response): Promise<ConvositeError> {\n  return errorFrom(response, await responseBody(response));\n}\n","import { ConvositeError } from './errors';\nimport { encodeSegment, joinUrl, workerError } from './http';\nimport type {\n  Conversation,\n  ConversationEndResponse,\n  ConversationEvent,\n  ConversationSendOptions,\n  Fetch,\n  RequestOptions,\n} from './types';\n\nasync function* parseNdjson(response: Response): AsyncGenerator<ConversationEvent> {\n  if (!response.body) throw new ConvositeError({ message: 'Conversation response did not contain a stream.', status: response.status });\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = '';\n  try {\n    while (true) {\n      const { value, done } = await reader.read();\n      buffer += decoder.decode(value, { stream: !done });\n      let newline: number;\n      while ((newline = buffer.indexOf('\\n')) !== -1) {\n        const line = buffer.slice(0, newline).trim();\n        buffer = buffer.slice(newline + 1);\n        if (line) yield parseEvent(line);\n      }\n      if (done) break;\n    }\n    const tail = buffer.trim();\n    if (tail) yield parseEvent(tail);\n  } finally {\n    reader.releaseLock();\n  }\n}\n\nfunction parseEvent(line: string): ConversationEvent {\n  try {\n    const event = JSON.parse(line) as unknown;\n    if (!event || typeof event !== 'object' || typeof (event as { type?: unknown }).type !== 'string') {\n      throw new Error('Event has no type.');\n    }\n    return event as ConversationEvent;\n  } catch (cause) {\n    throw new ConvositeError({ message: 'Conversation stream contained an invalid event.', code: 'invalid_stream', details: line, cause });\n  }\n}\n\nexport class ConversationsClient {\n  constructor(\n    private readonly fetcher: Fetch,\n    private readonly baseUrl: string,\n    private readonly siteId: string,\n  ) {}\n\n  create(sessionId?: string): Conversation {\n    let currentSession = sessionId?.trim() || null;\n    const client = this;\n    return {\n      get sessionId() { return currentSession; },\n      async *send(query: string, options: RequestOptions = {}) {\n        const stream = client.send(query, { ...options, ...(currentSession ? { sessionId: currentSession } : {}) }, (id) => { currentSession = id; });\n        yield* stream;\n      },\n      async end(options: RequestOptions = {}) {\n        if (!currentSession) return { ended: false };\n        const result = await client.end(currentSession, options);\n        if (result.ended) currentSession = null;\n        return result;\n      },\n      reset() { currentSession = null; },\n    };\n  }\n\n  async *send(\n    query: string,\n    options: ConversationSendOptions = {},\n    onSession?: (sessionId: string) => void,\n  ): AsyncGenerator<ConversationEvent> {\n    const trimmed = query.trim();\n    if (!trimmed) throw new ConvositeError({ message: 'Conversation query is required.', code: 'validation_error' });\n    const headers = new Headers({ 'Content-Type': 'application/json', 'Accept': 'application/x-ndjson' });\n    if (options.sessionId) headers.set('X-Conversation-Session', options.sessionId);\n    let response: Response;\n    try {\n      const init: RequestInit = { method: 'POST', headers, body: JSON.stringify({ query: trimmed }) };\n      if (options.signal) init.signal = options.signal;\n      response = await this.fetcher(joinUrl(this.baseUrl, `/conversations/${encodeSegment(this.siteId)}`), init);\n    } catch (cause) {\n      throw new ConvositeError({ message: options.signal?.aborted ? 'Conversation request was aborted.' : 'Unable to connect to Convosite conversations.', code: options.signal?.aborted ? 'request_aborted' : 'network_error', cause });\n    }\n    if (!response.ok) throw await workerError(response);\n    const session = response.headers.get('X-Conversation-Session');\n    if (session) onSession?.(session);\n    yield* parseNdjson(response);\n  }\n\n  async end(sessionId: string, options: RequestOptions = {}): Promise<ConversationEndResponse> {\n    const headers = new Headers({ 'Accept': 'application/json', 'X-Conversation-Session': sessionId });\n    let response: Response;\n    try {\n      const init: RequestInit = { method: 'POST', headers };\n      if (options.signal) init.signal = options.signal;\n      response = await this.fetcher(joinUrl(this.baseUrl, `/conversations/${encodeSegment(this.siteId)}/end`), init);\n    } catch (cause) {\n      throw new ConvositeError({ message: options.signal?.aborted ? 'Conversation request was aborted.' : 'Unable to connect to Convosite conversations.', code: options.signal?.aborted ? 'request_aborted' : 'network_error', cause });\n    }\n    if (!response.ok) throw await workerError(response);\n    return await response.json() as ConversationEndResponse;\n  }\n}\n","import { ConversationsClient } from './conversations';\nimport { ConvositeError } from './errors';\nimport { encodeSegment, HttpClient, normalizeBaseUrl } from './http';\nimport type {\n  ActionResponse,\n  ConvositeClient,\n  ConvositeConfig,\n  RawRequestOptions,\n  RequestOptions,\n} from './types';\n\nconst DEFAULT_BASE_URL = 'https://app.convosite.io/api';\n\nexport function createConvosite(config: ConvositeConfig): ConvositeClient {\n  if (!config || typeof config.site !== 'string' || !config.site.trim()) {\n    throw new ConvositeError({\n      message: 'A Convosite site ID is required.',\n      code: 'invalid_config',\n    });\n  }\n\n  const fetcher = config.fetch ?? globalThis.fetch?.bind(globalThis);\n  if (!fetcher) {\n    throw new ConvositeError({\n      message: 'No fetch implementation is available.',\n      code: 'invalid_config',\n    });\n  }\n\n  const siteId = config.site.trim();\n  const site = encodeSegment(siteId);\n  const baseUrl = normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL);\n  const conversationUrl = normalizeBaseUrl(config.conversationUrl ?? baseUrl);\n  const http = new HttpClient(\n    fetcher,\n    baseUrl,\n    config.headers ?? {},\n    config.timeout ?? 30_000,\n  );\n  const conversations = new ConversationsClient(fetcher, conversationUrl, siteId);\n\n  const requestOptions = (options?: RequestOptions): RequestInit =>\n    options?.signal ? { signal: options.signal } : {};\n\n  return {\n    actions: {\n      run: (endpointId, input, options) => {\n        if (typeof endpointId !== 'string' || !endpointId.trim()) {\n          throw new ConvositeError({\n            message: 'An endpoint ID is required.',\n            code: 'validation_error',\n          });\n        }\n\n        return http.api<ActionResponse>(\n          `/actions/${site}/${encodeSegment(endpointId.trim())}`,\n          {\n            method: 'POST',\n            headers: {\n              'Content-Type': 'application/json',\n              Accept: 'application/json',\n            },\n            body: JSON.stringify(input),\n            ...requestOptions(options),\n          },\n        );\n      },\n    },\n    conversations: {\n      create: (sessionId) => conversations.create(sessionId),\n      send: (query, options) => conversations.send(query, options),\n      end: (sessionId, options) => conversations.end(sessionId, options),\n    },\n    request: <T = unknown>(path: string, options: RawRequestOptions = {}) =>\n      http.raw<T>(path, options),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,110 @@
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+interface ActionResponse {
+    message: string;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+}
+interface RawRequestOptions extends RequestInit {
+    /** Parse successful responses as JSON by default. */
+    parseAs?: 'json' | 'text' | 'response';
+}
+interface ConversationSendOptions extends RequestOptions {
+    sessionId?: string;
+}
+type ConversationFieldEvent = {
+    type: 'field_delta';
+    path: string;
+    delta: string;
+    value?: unknown;
+    [key: string]: unknown;
+} | {
+    type: 'field_complete';
+    path: string;
+    value: unknown;
+    [key: string]: unknown;
+} | {
+    type: 'field';
+    path: string;
+    value?: unknown;
+    delta?: string;
+    [key: string]: unknown;
+};
+interface ConversationUsageEvent {
+    type: 'conversation_usage';
+    user_turns: number;
+    max_user_turns: number;
+    reached_limit: boolean;
+    [key: string]: unknown;
+}
+interface ConversationCompleteEvent {
+    type: 'complete';
+    [key: string]: unknown;
+}
+interface ConversationErrorEvent {
+    type: 'error';
+    message: string;
+    request_id?: string;
+    [key: string]: unknown;
+}
+type ConversationEvent = ConversationFieldEvent | ConversationUsageEvent | ConversationCompleteEvent | ConversationErrorEvent | ({
+    type: string;
+} & Record<string, unknown>);
+interface ConversationEndResponse {
+    ended: boolean;
+}
+interface Conversation {
+    readonly sessionId: string | null;
+    send(query: string, options?: RequestOptions): AsyncIterable<ConversationEvent>;
+    end(options?: RequestOptions): Promise<ConversationEndResponse>;
+    reset(): void;
+}
+type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+interface ConvositeConfig {
+    /** Site ULID used by the Convosite runtime. */
+    site: string;
+    /** Laravel public API base. Defaults to https://app.convosite.io/api. */
+    baseUrl?: string;
+    /** Conversations Worker base. Defaults to baseUrl. */
+    conversationUrl?: string;
+    /** Custom fetch implementation for SSR runtimes, tests, proxies, etc. */
+    fetch?: Fetch;
+    /** Headers applied to Laravel API requests. */
+    headers?: HeadersInit;
+    /** Timeout for non-streaming requests in milliseconds. Defaults to 30000. Set 0 to disable. */
+    timeout?: number;
+}
+interface ConvositeClient {
+    readonly actions: {
+        run<TInput extends Record<string, unknown> = Record<string, unknown>>(endpointId: string, input: TInput, options?: RequestOptions): Promise<ActionResponse>;
+    };
+    readonly conversations: {
+        create(sessionId?: string): Conversation;
+        send(query: string, options?: ConversationSendOptions): AsyncIterable<ConversationEvent>;
+        end(sessionId: string, options?: RequestOptions): Promise<ConversationEndResponse>;
+    };
+    /** Escape hatch for public Laravel API endpoints not yet wrapped by the SDK. */
+    request<T = unknown>(path: string, options?: RawRequestOptions): Promise<T>;
+}
+
+declare function createConvosite(config: ConvositeConfig): ConvositeClient;
+
+declare class ConvositeError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly details: unknown;
+    readonly requestId: string | null;
+    constructor(options: {
+        message: string;
+        status?: number;
+        code?: string | null;
+        details?: unknown;
+        requestId?: string | null;
+        cause?: unknown;
+    });
+}
+
+export { type ActionResponse, type Conversation, type ConversationCompleteEvent, type ConversationEndResponse, type ConversationErrorEvent, type ConversationEvent, type ConversationFieldEvent, type ConversationSendOptions, type ConversationUsageEvent, type ConvositeClient, type ConvositeConfig, ConvositeError, type Fetch, type JsonPrimitive, type JsonValue, type RawRequestOptions, type RequestOptions, createConvosite };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+interface ActionResponse {
+    message: string;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+}
+interface RawRequestOptions extends RequestInit {
+    /** Parse successful responses as JSON by default. */
+    parseAs?: 'json' | 'text' | 'response';
+}
+interface ConversationSendOptions extends RequestOptions {
+    sessionId?: string;
+}
+type ConversationFieldEvent = {
+    type: 'field_delta';
+    path: string;
+    delta: string;
+    value?: unknown;
+    [key: string]: unknown;
+} | {
+    type: 'field_complete';
+    path: string;
+    value: unknown;
+    [key: string]: unknown;
+} | {
+    type: 'field';
+    path: string;
+    value?: unknown;
+    delta?: string;
+    [key: string]: unknown;
+};
+interface ConversationUsageEvent {
+    type: 'conversation_usage';
+    user_turns: number;
+    max_user_turns: number;
+    reached_limit: boolean;
+    [key: string]: unknown;
+}
+interface ConversationCompleteEvent {
+    type: 'complete';
+    [key: string]: unknown;
+}
+interface ConversationErrorEvent {
+    type: 'error';
+    message: string;
+    request_id?: string;
+    [key: string]: unknown;
+}
+type ConversationEvent = ConversationFieldEvent | ConversationUsageEvent | ConversationCompleteEvent | ConversationErrorEvent | ({
+    type: string;
+} & Record<string, unknown>);
+interface ConversationEndResponse {
+    ended: boolean;
+}
+interface Conversation {
+    readonly sessionId: string | null;
+    send(query: string, options?: RequestOptions): AsyncIterable<ConversationEvent>;
+    end(options?: RequestOptions): Promise<ConversationEndResponse>;
+    reset(): void;
+}
+type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+interface ConvositeConfig {
+    /** Site ULID used by the Convosite runtime. */
+    site: string;
+    /** Laravel public API base. Defaults to https://app.convosite.io/api. */
+    baseUrl?: string;
+    /** Conversations Worker base. Defaults to baseUrl. */
+    conversationUrl?: string;
+    /** Custom fetch implementation for SSR runtimes, tests, proxies, etc. */
+    fetch?: Fetch;
+    /** Headers applied to Laravel API requests. */
+    headers?: HeadersInit;
+    /** Timeout for non-streaming requests in milliseconds. Defaults to 30000. Set 0 to disable. */
+    timeout?: number;
+}
+interface ConvositeClient {
+    readonly actions: {
+        run<TInput extends Record<string, unknown> = Record<string, unknown>>(endpointId: string, input: TInput, options?: RequestOptions): Promise<ActionResponse>;
+    };
+    readonly conversations: {
+        create(sessionId?: string): Conversation;
+        send(query: string, options?: ConversationSendOptions): AsyncIterable<ConversationEvent>;
+        end(sessionId: string, options?: RequestOptions): Promise<ConversationEndResponse>;
+    };
+    /** Escape hatch for public Laravel API endpoints not yet wrapped by the SDK. */
+    request<T = unknown>(path: string, options?: RawRequestOptions): Promise<T>;
+}
+
+declare function createConvosite(config: ConvositeConfig): ConvositeClient;
+
+declare class ConvositeError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly details: unknown;
+    readonly requestId: string | null;
+    constructor(options: {
+        message: string;
+        status?: number;
+        code?: string | null;
+        details?: unknown;
+        requestId?: string | null;
+        cause?: unknown;
+    });
+}
+
+export { type ActionResponse, type Conversation, type ConversationCompleteEvent, type ConversationEndResponse, type ConversationErrorEvent, type ConversationEvent, type ConversationFieldEvent, type ConversationSendOptions, type ConversationUsageEvent, type ConvositeClient, type ConvositeConfig, ConvositeError, type Fetch, type JsonPrimitive, type JsonValue, type RawRequestOptions, type RequestOptions, createConvosite };

package/dist/index.js

@@ -0,0 +1,289 @@
+// src/errors.ts
+var ConvositeError = class extends Error {
+  status;
+  code;
+  details;
+  requestId;
+  constructor(options) {
+    super(options.message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "ConvositeError";
+    this.status = options.status ?? 0;
+    this.code = options.code ?? null;
+    this.details = options.details ?? null;
+    this.requestId = options.requestId ?? null;
+  }
+};
+
+// src/http.ts
+function normalizeBaseUrl(value) {
+  return value.replace(/\/+$/, "");
+}
+function joinUrl(base, path) {
+  if (/^https?:\/\//i.test(path)) return path;
+  return `${normalizeBaseUrl(base)}/${path.replace(/^\/+/, "")}`;
+}
+function encodeSegment(value) {
+  return encodeURIComponent(value);
+}
+function timeoutSignal(signal, timeout) {
+  if (timeout <= 0) return signal ? { signal, cleanup: () => void 0 } : { cleanup: () => void 0 };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new DOMException("Request timed out.", "TimeoutError")), timeout);
+  const abort = () => controller.abort(signal?.reason);
+  if (signal) {
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+    }
+  };
+}
+async function responseBody(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function errorFrom(response, body) {
+  const object = body && typeof body === "object" ? body : {};
+  const message = typeof object.message === "string" ? object.message : `Convosite request failed with status ${response.status}.`;
+  const code = typeof object.error === "string" ? object.error : null;
+  const details = object.errors ?? body;
+  return new ConvositeError({
+    message,
+    status: response.status,
+    code,
+    details,
+    requestId: response.headers.get("X-Request-ID")
+  });
+}
+var HttpClient = class {
+  constructor(fetcher, baseUrl, headers, timeout) {
+    this.fetcher = fetcher;
+    this.baseUrl = baseUrl;
+    this.headers = headers;
+    this.timeout = timeout;
+  }
+  fetcher;
+  baseUrl;
+  headers;
+  timeout;
+  async api(path, init = {}) {
+    const response = await this.fetch(path, init, true);
+    const body = await responseBody(response);
+    if (!response.ok) throw errorFrom(response, body);
+    if (!body || typeof body !== "object" || !("success" in body)) {
+      throw new ConvositeError({ message: "Convosite returned an invalid API response.", status: response.status, details: body });
+    }
+    const envelope = body;
+    if (envelope.success !== true) {
+      throw new ConvositeError({ message: envelope.message || "Convosite request failed.", status: response.status, details: envelope.errors });
+    }
+    return envelope.data;
+  }
+  async raw(path, options = {}) {
+    const { parseAs = "json", ...init } = options;
+    const response = await this.fetch(path, init, true);
+    if (!response.ok) throw errorFrom(response, await responseBody(response));
+    if (parseAs === "response") return response;
+    if (parseAs === "text") return await response.text();
+    if (response.status === 204) return void 0;
+    return await response.json();
+  }
+  async fetch(path, init = {}, useTimeout = false) {
+    const headers = new Headers(this.headers);
+    new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+    const timed = useTimeout ? timeoutSignal(init.signal ?? void 0, this.timeout) : timeoutSignal(init.signal ?? void 0, 0);
+    try {
+      const requestInit = { ...init, headers };
+      if (timed.signal) requestInit.signal = timed.signal;
+      return await this.fetcher(joinUrl(this.baseUrl, path), requestInit);
+    } catch (cause) {
+      if (cause instanceof ConvositeError) throw cause;
+      const aborted = timed.signal?.aborted;
+      throw new ConvositeError({
+        message: aborted ? "Convosite request was aborted." : "Unable to connect to Convosite.",
+        code: aborted ? "request_aborted" : "network_error",
+        cause
+      });
+    } finally {
+      timed.cleanup();
+    }
+  }
+};
+async function workerError(response) {
+  return errorFrom(response, await responseBody(response));
+}
+
+// src/conversations.ts
+async function* parseNdjson(response) {
+  if (!response.body) throw new ConvositeError({ message: "Conversation response did not contain a stream.", status: response.status });
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done });
+      let newline;
+      while ((newline = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line) yield parseEvent(line);
+      }
+      if (done) break;
+    }
+    const tail = buffer.trim();
+    if (tail) yield parseEvent(tail);
+  } finally {
+    reader.releaseLock();
+  }
+}
+function parseEvent(line) {
+  try {
+    const event = JSON.parse(line);
+    if (!event || typeof event !== "object" || typeof event.type !== "string") {
+      throw new Error("Event has no type.");
+    }
+    return event;
+  } catch (cause) {
+    throw new ConvositeError({ message: "Conversation stream contained an invalid event.", code: "invalid_stream", details: line, cause });
+  }
+}
+var ConversationsClient = class {
+  constructor(fetcher, baseUrl, siteId) {
+    this.fetcher = fetcher;
+    this.baseUrl = baseUrl;
+    this.siteId = siteId;
+  }
+  fetcher;
+  baseUrl;
+  siteId;
+  create(sessionId) {
+    let currentSession = sessionId?.trim() || null;
+    const client = this;
+    return {
+      get sessionId() {
+        return currentSession;
+      },
+      async *send(query, options = {}) {
+        const stream = client.send(query, { ...options, ...currentSession ? { sessionId: currentSession } : {} }, (id) => {
+          currentSession = id;
+        });
+        yield* stream;
+      },
+      async end(options = {}) {
+        if (!currentSession) return { ended: false };
+        const result = await client.end(currentSession, options);
+        if (result.ended) currentSession = null;
+        return result;
+      },
+      reset() {
+        currentSession = null;
+      }
+    };
+  }
+  async *send(query, options = {}, onSession) {
+    const trimmed = query.trim();
+    if (!trimmed) throw new ConvositeError({ message: "Conversation query is required.", code: "validation_error" });
+    const headers = new Headers({ "Content-Type": "application/json", "Accept": "application/x-ndjson" });
+    if (options.sessionId) headers.set("X-Conversation-Session", options.sessionId);
+    let response;
+    try {
+      const init = { method: "POST", headers, body: JSON.stringify({ query: trimmed }) };
+      if (options.signal) init.signal = options.signal;
+      response = await this.fetcher(joinUrl(this.baseUrl, `/conversations/${encodeSegment(this.siteId)}`), init);
+    } catch (cause) {
+      throw new ConvositeError({ message: options.signal?.aborted ? "Conversation request was aborted." : "Unable to connect to Convosite conversations.", code: options.signal?.aborted ? "request_aborted" : "network_error", cause });
+    }
+    if (!response.ok) throw await workerError(response);
+    const session = response.headers.get("X-Conversation-Session");
+    if (session) onSession?.(session);
+    yield* parseNdjson(response);
+  }
+  async end(sessionId, options = {}) {
+    const headers = new Headers({ "Accept": "application/json", "X-Conversation-Session": sessionId });
+    let response;
+    try {
+      const init = { method: "POST", headers };
+      if (options.signal) init.signal = options.signal;
+      response = await this.fetcher(joinUrl(this.baseUrl, `/conversations/${encodeSegment(this.siteId)}/end`), init);
+    } catch (cause) {
+      throw new ConvositeError({ message: options.signal?.aborted ? "Conversation request was aborted." : "Unable to connect to Convosite conversations.", code: options.signal?.aborted ? "request_aborted" : "network_error", cause });
+    }
+    if (!response.ok) throw await workerError(response);
+    return await response.json();
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://app.convosite.io/api";
+function createConvosite(config) {
+  if (!config || typeof config.site !== "string" || !config.site.trim()) {
+    throw new ConvositeError({
+      message: "A Convosite site ID is required.",
+      code: "invalid_config"
+    });
+  }
+  const fetcher = config.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (!fetcher) {
+    throw new ConvositeError({
+      message: "No fetch implementation is available.",
+      code: "invalid_config"
+    });
+  }
+  const siteId = config.site.trim();
+  const site = encodeSegment(siteId);
+  const baseUrl = normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL);
+  const conversationUrl = normalizeBaseUrl(config.conversationUrl ?? baseUrl);
+  const http = new HttpClient(
+    fetcher,
+    baseUrl,
+    config.headers ?? {},
+    config.timeout ?? 3e4
+  );
+  const conversations = new ConversationsClient(fetcher, conversationUrl, siteId);
+  const requestOptions = (options) => options?.signal ? { signal: options.signal } : {};
+  return {
+    actions: {
+      run: (endpointId, input, options) => {
+        if (typeof endpointId !== "string" || !endpointId.trim()) {
+          throw new ConvositeError({
+            message: "An endpoint ID is required.",
+            code: "validation_error"
+          });
+        }
+        return http.api(
+          `/actions/${site}/${encodeSegment(endpointId.trim())}`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Accept: "application/json"
+            },
+            body: JSON.stringify(input),
+            ...requestOptions(options)
+          }
+        );
+      }
+    },
+    conversations: {
+      create: (sessionId) => conversations.create(sessionId),
+      send: (query, options) => conversations.send(query, options),
+      end: (sessionId, options) => conversations.end(sessionId, options)
+    },
+    request: (path, options = {}) => http.raw(path, options)
+  };
+}
+export {
+  ConvositeError,
+  createConvosite
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/http.ts","../src/conversations.ts","../src/client.ts"],"sourcesContent":["export class ConvositeError extends Error {\n  readonly status: number;\n  readonly code: string | null;\n  readonly details: unknown;\n  readonly requestId: string | null;\n\n  constructor(options: {\n    message: string;\n    status?: number;\n    code?: string | null;\n    details?: unknown;\n    requestId?: string | null;\n    cause?: unknown;\n  }) {\n    super(options.message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = 'ConvositeError';\n    this.status = options.status ?? 0;\n    this.code = options.code ?? null;\n    this.details = options.details ?? null;\n    this.requestId = options.requestId ?? null;\n  }\n}\n","import { ConvositeError } from './errors';\nimport type { Fetch, RawRequestOptions } from './types';\n\ninterface ApiEnvelope<T> {\n  success: boolean;\n  message: string;\n  data: T;\n  errors: unknown;\n}\n\nexport function normalizeBaseUrl(value: string): string {\n  return value.replace(/\\/+$/, '');\n}\n\nexport function joinUrl(base: string, path: string): string {\n  if (/^https?:\\/\\//i.test(path)) return path;\n  return `${normalizeBaseUrl(base)}/${path.replace(/^\\/+/, '')}`;\n}\n\nexport function encodeSegment(value: string): string {\n  return encodeURIComponent(value);\n}\n\nfunction timeoutSignal(signal: AbortSignal | undefined, timeout: number): { signal?: AbortSignal; cleanup: () => void } {\n  if (timeout <= 0) return signal ? { signal, cleanup: () => undefined } : { cleanup: () => undefined };\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(new DOMException('Request timed out.', 'TimeoutError')), timeout);\n  const abort = () => controller.abort(signal?.reason);\n  if (signal) {\n    if (signal.aborted) abort();\n    else signal.addEventListener('abort', abort, { once: true });\n  }\n  return {\n    signal: controller.signal,\n    cleanup: () => {\n      clearTimeout(timer);\n      signal?.removeEventListener('abort', abort);\n    },\n  };\n}\n\nasync function responseBody(response: Response): Promise<unknown> {\n  const text = await response.text();\n  if (!text) return null;\n  try { return JSON.parse(text); } catch { return text; }\n}\n\nfunction errorFrom(response: Response, body: unknown): ConvositeError {\n  const object = body && typeof body === 'object' ? body as Record<string, unknown> : {};\n  const message = typeof object.message === 'string' ? object.message : `Convosite request failed with status ${response.status}.`;\n  const code = typeof object.error === 'string' ? object.error : null;\n  const details = object.errors ?? body;\n  return new ConvositeError({\n    message,\n    status: response.status,\n    code,\n    details,\n    requestId: response.headers.get('X-Request-ID'),\n  });\n}\n\nexport class HttpClient {\n  constructor(\n    private readonly fetcher: Fetch,\n    private readonly baseUrl: string,\n    private readonly headers: HeadersInit,\n    private readonly timeout: number,\n  ) {}\n\n  async api<T>(path: string, init: RequestInit = {}): Promise<T> {\n    const response = await this.fetch(path, init, true);\n    const body = await responseBody(response);\n    if (!response.ok) throw errorFrom(response, body);\n    if (!body || typeof body !== 'object' || !('success' in body)) {\n      throw new ConvositeError({ message: 'Convosite returned an invalid API response.', status: response.status, details: body });\n    }\n    const envelope = body as ApiEnvelope<T>;\n    if (envelope.success !== true) {\n      throw new ConvositeError({ message: envelope.message || 'Convosite request failed.', status: response.status, details: envelope.errors });\n    }\n    return envelope.data;\n  }\n\n  async raw<T>(path: string, options: RawRequestOptions = {}): Promise<T> {\n    const { parseAs = 'json', ...init } = options;\n    const response = await this.fetch(path, init, true);\n    if (!response.ok) throw errorFrom(response, await responseBody(response));\n    if (parseAs === 'response') return response as T;\n    if (parseAs === 'text') return await response.text() as T;\n    if (response.status === 204) return undefined as T;\n    return await response.json() as T;\n  }\n\n  async fetch(path: string, init: RequestInit = {}, useTimeout = false): Promise<Response> {\n    const headers = new Headers(this.headers);\n    new Headers(init.headers).forEach((value, key) => headers.set(key, value));\n    const timed = useTimeout ? timeoutSignal(init.signal ?? undefined, this.timeout) : timeoutSignal(init.signal ?? undefined, 0);\n    try {\n      const requestInit: RequestInit = { ...init, headers };\n      if (timed.signal) requestInit.signal = timed.signal;\n      return await this.fetcher(joinUrl(this.baseUrl, path), requestInit);\n    } catch (cause) {\n      if (cause instanceof ConvositeError) throw cause;\n      const aborted = timed.signal?.aborted;\n      throw new ConvositeError({\n        message: aborted ? 'Convosite request was aborted.' : 'Unable to connect to Convosite.',\n        code: aborted ? 'request_aborted' : 'network_error',\n        cause,\n      });\n    } finally {\n      timed.cleanup();\n    }\n  }\n}\n\nexport async function workerError(response: Response): Promise<ConvositeError> {\n  return errorFrom(response, await responseBody(response));\n}\n","import { ConvositeError } from './errors';\nimport { encodeSegment, joinUrl, workerError } from './http';\nimport type {\n  Conversation,\n  ConversationEndResponse,\n  ConversationEvent,\n  ConversationSendOptions,\n  Fetch,\n  RequestOptions,\n} from './types';\n\nasync function* parseNdjson(response: Response): AsyncGenerator<ConversationEvent> {\n  if (!response.body) throw new ConvositeError({ message: 'Conversation response did not contain a stream.', status: response.status });\n  const reader = response.body.getReader();\n  const decoder = new TextDecoder();\n  let buffer = '';\n  try {\n    while (true) {\n      const { value, done } = await reader.read();\n      buffer += decoder.decode(value, { stream: !done });\n      let newline: number;\n      while ((newline = buffer.indexOf('\\n')) !== -1) {\n        const line = buffer.slice(0, newline).trim();\n        buffer = buffer.slice(newline + 1);\n        if (line) yield parseEvent(line);\n      }\n      if (done) break;\n    }\n    const tail = buffer.trim();\n    if (tail) yield parseEvent(tail);\n  } finally {\n    reader.releaseLock();\n  }\n}\n\nfunction parseEvent(line: string): ConversationEvent {\n  try {\n    const event = JSON.parse(line) as unknown;\n    if (!event || typeof event !== 'object' || typeof (event as { type?: unknown }).type !== 'string') {\n      throw new Error('Event has no type.');\n    }\n    return event as ConversationEvent;\n  } catch (cause) {\n    throw new ConvositeError({ message: 'Conversation stream contained an invalid event.', code: 'invalid_stream', details: line, cause });\n  }\n}\n\nexport class ConversationsClient {\n  constructor(\n    private readonly fetcher: Fetch,\n    private readonly baseUrl: string,\n    private readonly siteId: string,\n  ) {}\n\n  create(sessionId?: string): Conversation {\n    let currentSession = sessionId?.trim() || null;\n    const client = this;\n    return {\n      get sessionId() { return currentSession; },\n      async *send(query: string, options: RequestOptions = {}) {\n        const stream = client.send(query, { ...options, ...(currentSession ? { sessionId: currentSession } : {}) }, (id) => { currentSession = id; });\n        yield* stream;\n      },\n      async end(options: RequestOptions = {}) {\n        if (!currentSession) return { ended: false };\n        const result = await client.end(currentSession, options);\n        if (result.ended) currentSession = null;\n        return result;\n      },\n      reset() { currentSession = null; },\n    };\n  }\n\n  async *send(\n    query: string,\n    options: ConversationSendOptions = {},\n    onSession?: (sessionId: string) => void,\n  ): AsyncGenerator<ConversationEvent> {\n    const trimmed = query.trim();\n    if (!trimmed) throw new ConvositeError({ message: 'Conversation query is required.', code: 'validation_error' });\n    const headers = new Headers({ 'Content-Type': 'application/json', 'Accept': 'application/x-ndjson' });\n    if (options.sessionId) headers.set('X-Conversation-Session', options.sessionId);\n    let response: Response;\n    try {\n      const init: RequestInit = { method: 'POST', headers, body: JSON.stringify({ query: trimmed }) };\n      if (options.signal) init.signal = options.signal;\n      response = await this.fetcher(joinUrl(this.baseUrl, `/conversations/${encodeSegment(this.siteId)}`), init);\n    } catch (cause) {\n      throw new ConvositeError({ message: options.signal?.aborted ? 'Conversation request was aborted.' : 'Unable to connect to Convosite conversations.', code: options.signal?.aborted ? 'request_aborted' : 'network_error', cause });\n    }\n    if (!response.ok) throw await workerError(response);\n    const session = response.headers.get('X-Conversation-Session');\n    if (session) onSession?.(session);\n    yield* parseNdjson(response);\n  }\n\n  async end(sessionId: string, options: RequestOptions = {}): Promise<ConversationEndResponse> {\n    const headers = new Headers({ 'Accept': 'application/json', 'X-Conversation-Session': sessionId });\n    let response: Response;\n    try {\n      const init: RequestInit = { method: 'POST', headers };\n      if (options.signal) init.signal = options.signal;\n      response = await this.fetcher(joinUrl(this.baseUrl, `/conversations/${encodeSegment(this.siteId)}/end`), init);\n    } catch (cause) {\n      throw new ConvositeError({ message: options.signal?.aborted ? 'Conversation request was aborted.' : 'Unable to connect to Convosite conversations.', code: options.signal?.aborted ? 'request_aborted' : 'network_error', cause });\n    }\n    if (!response.ok) throw await workerError(response);\n    return await response.json() as ConversationEndResponse;\n  }\n}\n","import { ConversationsClient } from './conversations';\nimport { ConvositeError } from './errors';\nimport { encodeSegment, HttpClient, normalizeBaseUrl } from './http';\nimport type {\n  ActionResponse,\n  ConvositeClient,\n  ConvositeConfig,\n  RawRequestOptions,\n  RequestOptions,\n} from './types';\n\nconst DEFAULT_BASE_URL = 'https://app.convosite.io/api';\n\nexport function createConvosite(config: ConvositeConfig): ConvositeClient {\n  if (!config || typeof config.site !== 'string' || !config.site.trim()) {\n    throw new ConvositeError({\n      message: 'A Convosite site ID is required.',\n      code: 'invalid_config',\n    });\n  }\n\n  const fetcher = config.fetch ?? globalThis.fetch?.bind(globalThis);\n  if (!fetcher) {\n    throw new ConvositeError({\n      message: 'No fetch implementation is available.',\n      code: 'invalid_config',\n    });\n  }\n\n  const siteId = config.site.trim();\n  const site = encodeSegment(siteId);\n  const baseUrl = normalizeBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL);\n  const conversationUrl = normalizeBaseUrl(config.conversationUrl ?? baseUrl);\n  const http = new HttpClient(\n    fetcher,\n    baseUrl,\n    config.headers ?? {},\n    config.timeout ?? 30_000,\n  );\n  const conversations = new ConversationsClient(fetcher, conversationUrl, siteId);\n\n  const requestOptions = (options?: RequestOptions): RequestInit =>\n    options?.signal ? { signal: options.signal } : {};\n\n  return {\n    actions: {\n      run: (endpointId, input, options) => {\n        if (typeof endpointId !== 'string' || !endpointId.trim()) {\n          throw new ConvositeError({\n            message: 'An endpoint ID is required.',\n            code: 'validation_error',\n          });\n        }\n\n        return http.api<ActionResponse>(\n          `/actions/${site}/${encodeSegment(endpointId.trim())}`,\n          {\n            method: 'POST',\n            headers: {\n              'Content-Type': 'application/json',\n              Accept: 'application/json',\n            },\n            body: JSON.stringify(input),\n            ...requestOptions(options),\n          },\n        );\n      },\n    },\n    conversations: {\n      create: (sessionId) => conversations.create(sessionId),\n      send: (query, options) => conversations.send(query, options),\n      end: (sessionId, options) => conversations.end(sessionId, options),\n    },\n    request: <T = unknown>(path: string, options: RawRequestOptions = {}) =>\n      http.raw<T>(path, options),\n  };\n}\n"],"mappings":";AAAO,IAAM,iBAAN,cAA6B,MAAM;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,SAOT;AACD,UAAM,QAAQ,SAAS,QAAQ,UAAU,SAAY,SAAY,EAAE,OAAO,QAAQ,MAAM,CAAC;AACzF,SAAK,OAAO;AACZ,SAAK,SAAS,QAAQ,UAAU;AAChC,SAAK,OAAO,QAAQ,QAAQ;AAC5B,SAAK,UAAU,QAAQ,WAAW;AAClC,SAAK,YAAY,QAAQ,aAAa;AAAA,EACxC;AACF;;;ACXO,SAAS,iBAAiB,OAAuB;AACtD,SAAO,MAAM,QAAQ,QAAQ,EAAE;AACjC;AAEO,SAAS,QAAQ,MAAc,MAAsB;AAC1D,MAAI,gBAAgB,KAAK,IAAI,EAAG,QAAO;AACvC,SAAO,GAAG,iBAAiB,IAAI,CAAC,IAAI,KAAK,QAAQ,QAAQ,EAAE,CAAC;AAC9D;AAEO,SAAS,cAAc,OAAuB;AACnD,SAAO,mBAAmB,KAAK;AACjC;AAEA,SAAS,cAAc,QAAiC,SAAgE;AACtH,MAAI,WAAW,EAAG,QAAO,SAAS,EAAE,QAAQ,SAAS,MAAM,OAAU,IAAI,EAAE,SAAS,MAAM,OAAU;AACpG,QAAM,aAAa,IAAI,gBAAgB;AACvC,QAAM,QAAQ,WAAW,MAAM,WAAW,MAAM,IAAI,aAAa,sBAAsB,cAAc,CAAC,GAAG,OAAO;AAChH,QAAM,QAAQ,MAAM,WAAW,MAAM,QAAQ,MAAM;AACnD,MAAI,QAAQ;AACV,QAAI,OAAO,QAAS,OAAM;AAAA,QACrB,QAAO,iBAAiB,SAAS,OAAO,EAAE,MAAM,KAAK,CAAC;AAAA,EAC7D;AACA,SAAO;AAAA,IACL,QAAQ,WAAW;AAAA,IACnB,SAAS,MAAM;AACb,mBAAa,KAAK;AAClB,cAAQ,oBAAoB,SAAS,KAAK;AAAA,IAC5C;AAAA,EACF;AACF;AAEA,eAAe,aAAa,UAAsC;AAChE,QAAM,OAAO,MAAM,SAAS,KAAK;AACjC,MAAI,CAAC,KAAM,QAAO;AAClB,MAAI;AAAE,WAAO,KAAK,MAAM,IAAI;AAAA,EAAG,QAAQ;AAAE,WAAO;AAAA,EAAM;AACxD;AAEA,SAAS,UAAU,UAAoB,MAA+B;AACpE,QAAM,SAAS,QAAQ,OAAO,SAAS,WAAW,OAAkC,CAAC;AACrF,QAAM,UAAU,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU,wCAAwC,SAAS,MAAM;AAC7H,QAAM,OAAO,OAAO,OAAO,UAAU,WAAW,OAAO,QAAQ;AAC/D,QAAM,UAAU,OAAO,UAAU;AACjC,SAAO,IAAI,eAAe;AAAA,IACxB;AAAA,IACA,QAAQ,SAAS;AAAA,IACjB;AAAA,IACA;AAAA,IACA,WAAW,SAAS,QAAQ,IAAI,cAAc;AAAA,EAChD,CAAC;AACH;AAEO,IAAM,aAAN,MAAiB;AAAA,EACtB,YACmB,SACA,SACA,SACA,SACjB;AAJiB;AACA;AACA;AACA;AAAA,EAChB;AAAA,EAJgB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAGnB,MAAM,IAAO,MAAc,OAAoB,CAAC,GAAe;AAC7D,UAAM,WAAW,MAAM,KAAK,MAAM,MAAM,MAAM,IAAI;AAClD,UAAM,OAAO,MAAM,aAAa,QAAQ;AACxC,QAAI,CAAC,SAAS,GAAI,OAAM,UAAU,UAAU,IAAI;AAChD,QAAI,CAAC,QAAQ,OAAO,SAAS,YAAY,EAAE,aAAa,OAAO;AAC7D,YAAM,IAAI,eAAe,EAAE,SAAS,+CAA+C,QAAQ,SAAS,QAAQ,SAAS,KAAK,CAAC;AAAA,IAC7H;AACA,UAAM,WAAW;AACjB,QAAI,SAAS,YAAY,MAAM;AAC7B,YAAM,IAAI,eAAe,EAAE,SAAS,SAAS,WAAW,6BAA6B,QAAQ,SAAS,QAAQ,SAAS,SAAS,OAAO,CAAC;AAAA,IAC1I;AACA,WAAO,SAAS;AAAA,EAClB;AAAA,EAEA,MAAM,IAAO,MAAc,UAA6B,CAAC,GAAe;AACtE,UAAM,EAAE,UAAU,QAAQ,GAAG,KAAK,IAAI;AACtC,UAAM,WAAW,MAAM,KAAK,MAAM,MAAM,MAAM,IAAI;AAClD,QAAI,CAAC,SAAS,GAAI,OAAM,UAAU,UAAU,MAAM,aAAa,QAAQ,CAAC;AACxE,QAAI,YAAY,WAAY,QAAO;AACnC,QAAI,YAAY,OAAQ,QAAO,MAAM,SAAS,KAAK;AACnD,QAAI,SAAS,WAAW,IAAK,QAAO;AACpC,WAAO,MAAM,SAAS,KAAK;AAAA,EAC7B;AAAA,EAEA,MAAM,MAAM,MAAc,OAAoB,CAAC,GAAG,aAAa,OAA0B;AACvF,UAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,QAAI,QAAQ,KAAK,OAAO,EAAE,QAAQ,CAAC,OAAO,QAAQ,QAAQ,IAAI,KAAK,KAAK,CAAC;AACzE,UAAM,QAAQ,aAAa,cAAc,KAAK,UAAU,QAAW,KAAK,OAAO,IAAI,cAAc,KAAK,UAAU,QAAW,CAAC;AAC5H,QAAI;AACF,YAAM,cAA2B,EAAE,GAAG,MAAM,QAAQ;AACpD,UAAI,MAAM,OAAQ,aAAY,SAAS,MAAM;AAC7C,aAAO,MAAM,KAAK,QAAQ,QAAQ,KAAK,SAAS,IAAI,GAAG,WAAW;AAAA,IACpE,SAAS,OAAO;AACd,UAAI,iBAAiB,eAAgB,OAAM;AAC3C,YAAM,UAAU,MAAM,QAAQ;AAC9B,YAAM,IAAI,eAAe;AAAA,QACvB,SAAS,UAAU,mCAAmC;AAAA,QACtD,MAAM,UAAU,oBAAoB;AAAA,QACpC;AAAA,MACF,CAAC;AAAA,IACH,UAAE;AACA,YAAM,QAAQ;AAAA,IAChB;AAAA,EACF;AACF;AAEA,eAAsB,YAAY,UAA6C;AAC7E,SAAO,UAAU,UAAU,MAAM,aAAa,QAAQ,CAAC;AACzD;;;AC1GA,gBAAgB,YAAY,UAAuD;AACjF,MAAI,CAAC,SAAS,KAAM,OAAM,IAAI,eAAe,EAAE,SAAS,mDAAmD,QAAQ,SAAS,OAAO,CAAC;AACpI,QAAM,SAAS,SAAS,KAAK,UAAU;AACvC,QAAM,UAAU,IAAI,YAAY;AAChC,MAAI,SAAS;AACb,MAAI;AACF,WAAO,MAAM;AACX,YAAM,EAAE,OAAO,KAAK,IAAI,MAAM,OAAO,KAAK;AAC1C,gBAAU,QAAQ,OAAO,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;AACjD,UAAI;AACJ,cAAQ,UAAU,OAAO,QAAQ,IAAI,OAAO,IAAI;AAC9C,cAAM,OAAO,OAAO,MAAM,GAAG,OAAO,EAAE,KAAK;AAC3C,iBAAS,OAAO,MAAM,UAAU,CAAC;AACjC,YAAI,KAAM,OAAM,WAAW,IAAI;AAAA,MACjC;AACA,UAAI,KAAM;AAAA,IACZ;AACA,UAAM,OAAO,OAAO,KAAK;AACzB,QAAI,KAAM,OAAM,WAAW,IAAI;AAAA,EACjC,UAAE;AACA,WAAO,YAAY;AAAA,EACrB;AACF;AAEA,SAAS,WAAW,MAAiC;AACnD,MAAI;AACF,UAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,QAAI,CAAC,SAAS,OAAO,UAAU,YAAY,OAAQ,MAA6B,SAAS,UAAU;AACjG,YAAM,IAAI,MAAM,oBAAoB;AAAA,IACtC;AACA,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,IAAI,eAAe,EAAE,SAAS,mDAAmD,MAAM,kBAAkB,SAAS,MAAM,MAAM,CAAC;AAAA,EACvI;AACF;AAEO,IAAM,sBAAN,MAA0B;AAAA,EAC/B,YACmB,SACA,SACA,QACjB;AAHiB;AACA;AACA;AAAA,EAChB;AAAA,EAHgB;AAAA,EACA;AAAA,EACA;AAAA,EAGnB,OAAO,WAAkC;AACvC,QAAI,iBAAiB,WAAW,KAAK,KAAK;AAC1C,UAAM,SAAS;AACf,WAAO;AAAA,MACL,IAAI,YAAY;AAAE,eAAO;AAAA,MAAgB;AAAA,MACzC,OAAO,KAAK,OAAe,UAA0B,CAAC,GAAG;AACvD,cAAM,SAAS,OAAO,KAAK,OAAO,EAAE,GAAG,SAAS,GAAI,iBAAiB,EAAE,WAAW,eAAe,IAAI,CAAC,EAAG,GAAG,CAAC,OAAO;AAAE,2BAAiB;AAAA,QAAI,CAAC;AAC5I,eAAO;AAAA,MACT;AAAA,MACA,MAAM,IAAI,UAA0B,CAAC,GAAG;AACtC,YAAI,CAAC,eAAgB,QAAO,EAAE,OAAO,MAAM;AAC3C,cAAM,SAAS,MAAM,OAAO,IAAI,gBAAgB,OAAO;AACvD,YAAI,OAAO,MAAO,kBAAiB;AACnC,eAAO;AAAA,MACT;AAAA,MACA,QAAQ;AAAE,yBAAiB;AAAA,MAAM;AAAA,IACnC;AAAA,EACF;AAAA,EAEA,OAAO,KACL,OACA,UAAmC,CAAC,GACpC,WACmC;AACnC,UAAM,UAAU,MAAM,KAAK;AAC3B,QAAI,CAAC,QAAS,OAAM,IAAI,eAAe,EAAE,SAAS,mCAAmC,MAAM,mBAAmB,CAAC;AAC/G,UAAM,UAAU,IAAI,QAAQ,EAAE,gBAAgB,oBAAoB,UAAU,uBAAuB,CAAC;AACpG,QAAI,QAAQ,UAAW,SAAQ,IAAI,0BAA0B,QAAQ,SAAS;AAC9E,QAAI;AACJ,QAAI;AACF,YAAM,OAAoB,EAAE,QAAQ,QAAQ,SAAS,MAAM,KAAK,UAAU,EAAE,OAAO,QAAQ,CAAC,EAAE;AAC9F,UAAI,QAAQ,OAAQ,MAAK,SAAS,QAAQ;AAC1C,iBAAW,MAAM,KAAK,QAAQ,QAAQ,KAAK,SAAS,kBAAkB,cAAc,KAAK,MAAM,CAAC,EAAE,GAAG,IAAI;AAAA,IAC3G,SAAS,OAAO;AACd,YAAM,IAAI,eAAe,EAAE,SAAS,QAAQ,QAAQ,UAAU,sCAAsC,iDAAiD,MAAM,QAAQ,QAAQ,UAAU,oBAAoB,iBAAiB,MAAM,CAAC;AAAA,IACnO;AACA,QAAI,CAAC,SAAS,GAAI,OAAM,MAAM,YAAY,QAAQ;AAClD,UAAM,UAAU,SAAS,QAAQ,IAAI,wBAAwB;AAC7D,QAAI,QAAS,aAAY,OAAO;AAChC,WAAO,YAAY,QAAQ;AAAA,EAC7B;AAAA,EAEA,MAAM,IAAI,WAAmB,UAA0B,CAAC,GAAqC;AAC3F,UAAM,UAAU,IAAI,QAAQ,EAAE,UAAU,oBAAoB,0BAA0B,UAAU,CAAC;AACjG,QAAI;AACJ,QAAI;AACF,YAAM,OAAoB,EAAE,QAAQ,QAAQ,QAAQ;AACpD,UAAI,QAAQ,OAAQ,MAAK,SAAS,QAAQ;AAC1C,iBAAW,MAAM,KAAK,QAAQ,QAAQ,KAAK,SAAS,kBAAkB,cAAc,KAAK,MAAM,CAAC,MAAM,GAAG,IAAI;AAAA,IAC/G,SAAS,OAAO;AACd,YAAM,IAAI,eAAe,EAAE,SAAS,QAAQ,QAAQ,UAAU,sCAAsC,iDAAiD,MAAM,QAAQ,QAAQ,UAAU,oBAAoB,iBAAiB,MAAM,CAAC;AAAA,IACnO;AACA,QAAI,CAAC,SAAS,GAAI,OAAM,MAAM,YAAY,QAAQ;AAClD,WAAO,MAAM,SAAS,KAAK;AAAA,EAC7B;AACF;;;AClGA,IAAM,mBAAmB;AAElB,SAAS,gBAAgB,QAA0C;AACxE,MAAI,CAAC,UAAU,OAAO,OAAO,SAAS,YAAY,CAAC,OAAO,KAAK,KAAK,GAAG;AACrE,UAAM,IAAI,eAAe;AAAA,MACvB,SAAS;AAAA,MACT,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AAEA,QAAM,UAAU,OAAO,SAAS,WAAW,OAAO,KAAK,UAAU;AACjE,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,eAAe;AAAA,MACvB,SAAS;AAAA,MACT,MAAM;AAAA,IACR,CAAC;AAAA,EACH;AAEA,QAAM,SAAS,OAAO,KAAK,KAAK;AAChC,QAAM,OAAO,cAAc,MAAM;AACjC,QAAM,UAAU,iBAAiB,OAAO,WAAW,gBAAgB;AACnE,QAAM,kBAAkB,iBAAiB,OAAO,mBAAmB,OAAO;AAC1E,QAAM,OAAO,IAAI;AAAA,IACf;AAAA,IACA;AAAA,IACA,OAAO,WAAW,CAAC;AAAA,IACnB,OAAO,WAAW;AAAA,EACpB;AACA,QAAM,gBAAgB,IAAI,oBAAoB,SAAS,iBAAiB,MAAM;AAE9E,QAAM,iBAAiB,CAAC,YACtB,SAAS,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;AAElD,SAAO;AAAA,IACL,SAAS;AAAA,MACP,KAAK,CAAC,YAAY,OAAO,YAAY;AACnC,YAAI,OAAO,eAAe,YAAY,CAAC,WAAW,KAAK,GAAG;AACxD,gBAAM,IAAI,eAAe;AAAA,YACvB,SAAS;AAAA,YACT,MAAM;AAAA,UACR,CAAC;AAAA,QACH;AAEA,eAAO,KAAK;AAAA,UACV,YAAY,IAAI,IAAI,cAAc,WAAW,KAAK,CAAC,CAAC;AAAA,UACpD;AAAA,YACE,QAAQ;AAAA,YACR,SAAS;AAAA,cACP,gBAAgB;AAAA,cAChB,QAAQ;AAAA,YACV;AAAA,YACA,MAAM,KAAK,UAAU,KAAK;AAAA,YAC1B,GAAG,eAAe,OAAO;AAAA,UAC3B;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,IACA,eAAe;AAAA,MACb,QAAQ,CAAC,cAAc,cAAc,OAAO,SAAS;AAAA,MACrD,MAAM,CAAC,OAAO,YAAY,cAAc,KAAK,OAAO,OAAO;AAAA,MAC3D,KAAK,CAAC,WAAW,YAAY,cAAc,IAAI,WAAW,OAAO;AAAA,IACnE;AAAA,IACA,SAAS,CAAc,MAAc,UAA6B,CAAC,MACjE,KAAK,IAAO,MAAM,OAAO;AAAA,EAC7B;AACF;","names":[]}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@convosite/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Framework-agnostic JavaScript and TypeScript client for building Convosite conversational experiences.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "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"
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsup src/index.ts --format esm,cjs --dts --sourcemap --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "convosite",
+    "conversational-ui",
+    "conversational-ai",
+    "sdk",
+    "typescript"
+  ]
+}