@xsai/shared 0.5.1 → 1.0.0-beta.2

package/README.md

@@ -0,0 +1,28 @@
+# @xsai/shared
+
+<!-- automd:file src="/docs/snippets/shared.md" -->
+
+```sh
+pnpm add @xsai/shared
+```
+
+```ts
+import { HttpError, sendRequest } from '@xsai/shared'
+
+try {
+  await sendRequest({ method: 'GET', path: 'models' }, {
+    baseURL: 'https://example.com/v1/',
+    fetch: async () => new Response('Try again later', { status: 429 }),
+  })
+}
+catch (error) {
+  if (HttpError.isInstance(error))
+    console.log(error.status, error.body)
+  else
+    throw error
+}
+```
+
+<!-- /automd -->
+
+Read the [documentation](https://xsai.js.org/shared).

package/dist/index.d.ts

@@ -1,144 +1,157 @@
-interface APICallErrorOptions extends ErrorOptions {
-    requestBody?: string;
-    response: Response;
-    responseBody?: string;
-}
-interface InvalidResponseErrorOptions extends ErrorOptions {
-    body?: unknown;
-    contentType?: null | string;
-    reason: InvalidResponseReason;
-    response?: Response;
-    responseBody?: string;
-}
-type InvalidResponseReason = 'empty_body' | 'invalid_body' | 'no_choices';
-interface InvalidToolCallErrorOptions extends ErrorOptions {
-    availableTools?: string[];
-    reason: InvalidToolCallReason;
-    toolCall: unknown;
-    toolName?: string;
-}
-type InvalidToolCallReason = 'missing_arguments' | 'missing_name' | 'tool_call_id_mismatch' | 'unknown_tool';
-interface InvalidToolInputErrorOptions extends ErrorOptions {
-    toolInput: unknown;
-    toolName: string;
-}
-interface JSONParseErrorOptions extends ErrorOptions {
-    text: string;
-}
-interface RemoteAPIErrorOptions extends ErrorOptions {
-    response?: Response;
-    responseBody: string;
-}
-interface ToolExecutionErrorOptions extends InvalidToolInputErrorOptions {
-    toolCallId?: string;
-}
-type XSAIErrorCode = 'api_call_error' | 'invalid_response' | 'invalid_tool_call' | 'invalid_tool_input' | 'json_parse_error' | 'remote_api_error' | 'tool_execution_error';
-declare class XSAIError extends Error {
-    code: (string & {}) | XSAIErrorCode;
-    constructor(message: string, code: (string & {}) | XSAIErrorCode, options?: ErrorOptions);
-    static isInstance<T extends abstract new (...args: any[]) => XSAIError>(this: T, error: unknown): error is InstanceType<T>;
-}
-declare class APICallError extends XSAIError {
-    requestBody?: string;
-    response: Response;
-    responseBody?: string;
-    responseHeaders: Record<string, string>;
-    statusCode: number;
-    statusText: string;
-    url: string;
-    constructor(message: string, options: APICallErrorOptions);
-}
-declare class InvalidResponseError extends XSAIError {
-    body?: unknown;
-    contentType?: null | string;
-    reason: InvalidResponseErrorOptions['reason'];
-    response?: Response;
-    responseBody?: string;
-    constructor(message: string, options: InvalidResponseErrorOptions);
-}
-declare class InvalidToolCallError extends XSAIError {
-    availableTools?: string[];
-    reason: InvalidToolCallErrorOptions['reason'];
-    toolCall: unknown;
-    toolName?: string;
-    constructor(message: string, options: InvalidToolCallErrorOptions);
-}
-declare class InvalidToolInputError extends XSAIError {
-    toolInput: unknown;
-    toolName: string;
-    constructor(message: string, options: InvalidToolInputErrorOptions);
-}
-declare class JSONParseError extends XSAIError {
-    text: string;
-    constructor(message: string, options: JSONParseErrorOptions);
-}
-declare class RemoteAPIError extends XSAIError {
-    response?: Response;
-    responseBody: string;
-    constructor(message: string, options: RemoteAPIErrorOptions);
-}
-declare class ToolExecutionError extends XSAIError {
-    toolCallId?: string;
-    toolInput: unknown;
-    toolName: string;
-    constructor(message: string, options: ToolExecutionErrorOptions);
-}
-
-type Fetch = (input: URL, init: RequestInit) => Promise<Response>;
-
-interface CommonRequestOptions {
-    abortSignal?: AbortSignal;
+interface HttpOptions {
     apiKey?: string;
     /** @example `https://api.openai.com/v1/` */
     baseURL: string | URL;
-    fetch?: Fetch | typeof globalThis.fetch;
-    /** @default `undefined` */
-    headers?: Headers | Record<string, string>;
-    /** @example `gpt-4o` */
+    fetch?: (request: Request) => Promise<Response>;
+    headers?: Record<string, string | undefined>;
     model: string;
 }
 
-type WithUnknown<T> = T & {
-    [key: string]: unknown;
-};
-
-declare const strCamelToSnake: (str: string) => string;
-declare const objCamelToSnake: (obj: Record<string, unknown>) => {
-    [k: string]: unknown;
-};
+type Promisable<T> = Promise<T> | T;
 
+type XSAIErrorCause<T extends XSAIErrorCode> = Exclude<XSAIErrorCauseMap[T], undefined>;
 /**
- * Clean all undefined values.
- * @param obj object
- * @returns cleaned object
- *
- * @example
- * ```ts
- * import { clean } from '@xsai/shared'
- *
- * // { a: 'a' }
- * const obj = clean({
- *   a: 'a',
- *   b: undefined
- * })
- * ```
+ * Per-code `cause` contract: `undefined` forbids a cause, `unknown` makes it
+ * optional, `NonNullable<unknown>` requires one. Packages augment this
+ * interface to register their own codes.
  */
-declare const clean: <T extends Record<string, undefined | unknown>>(obj: T) => Record<keyof T, Exclude<T[keyof T], unknown>>;
-
-declare const postJSON: (path: string, options: WithUnknown<CommonRequestOptions>) => Promise<Response>;
-
-declare const requestBody: (body: Record<string, unknown>) => string;
-
-declare const requestHeaders: (headers?: CommonRequestOptions["headers"], apiKey?: CommonRequestOptions["apiKey"]) => Record<"Authorization", never>;
+interface XSAIErrorCauseMap {
+    'http-error': undefined;
+    'invalid-input': undefined;
+    'invalid-response': unknown;
+    'network-error': NonNullable<unknown>;
+    'truncated-stream': undefined;
+}
+type XSAIErrorCode = keyof XSAIErrorCauseMap;
+type XSAIErrorOptions<T extends XSAIErrorCode> = undefined extends XSAIErrorCauseMap[T] ? [options?: {
+    cause?: XSAIErrorCause<T>;
+}] : [options: {
+    cause: XSAIErrorCause<T>;
+}];
+declare class XSAIError<T extends XSAIErrorCode = XSAIErrorCode> extends Error {
+    readonly code: T;
+    constructor(code: T, message: string, ...[options]: XSAIErrorOptions<T>);
+    static isInstance<T extends XSAIError>(this: new (...args: never[]) => T, error: unknown): error is T;
+}
+declare class HttpError extends XSAIError<'http-error'> {
+    readonly body: string;
+    /** The raw response headers, for debugging (e.g. `x-request-id`, `retry-after`). */
+    readonly headers: Headers;
+    readonly status: number;
+    constructor({ body, headers, status }: {
+        body: string;
+        headers: Headers;
+        status: number;
+    }, ...options: XSAIErrorOptions<'http-error'>);
+}
 
+interface SendRequestOptions {
+    body?: FormData | Record<string, unknown>;
+    headers?: Record<string, string | undefined>;
+    method?: 'GET' | 'POST';
+    path: string;
+    signal?: AbortSignal;
+}
 declare const requestURL: (path: string, baseURL: string | URL) => URL;
+declare const sendRequest: (options: SendRequestOptions, httpOptions: Omit<HttpOptions, "model">) => Promise<Response & {
+    body: NonNullable<Response["body"]>;
+}>;
 
-declare const responseCatch: (res: Response) => Promise<Response>;
-
-declare const responseJSON: <T>(res: Response) => Promise<T>;
+/**
+ * A parsed EventSource message event
+ *
+ * @public
+ */
+interface EventSourceMessage {
+    /**
+     * The event type sent from the server. Note that this differs from the browser `EventSource`
+     * implementation in that browsers will default this to `message`, whereas this parser will
+     * leave this as `undefined` if not explicitly declared.
+     */
+    event?: string | undefined;
+    /**
+     * ID of the message, if any was provided by the server. Can be used by clients to keep the
+     * last received message ID in sync when reconnecting.
+     */
+    id?: string | undefined;
+    /**
+     * The data received for this message
+     */
+    data: string;
+}
 
-type TrampolineFn<T> = (() => Promise<TrampolineFn<T>> | TrampolineFn<T>) | Promise<T> | T;
-declare const trampoline: <T>(fn: () => Promise<TrampolineFn<T>> | TrampolineFn<T>) => Promise<T>;
+/**
+ * Options for the EventSourceParserStream.
+ *
+ * @public
+ */
+interface StreamOptions {
+    /**
+     * Callback for an `id` field when a blank line ends an event block.
+     *
+     * Called once with the last valid `id` value in the block, whether or not the block contains a
+     * `data` field. When the block produces an event, `onId` is called before the event is enqueued.
+     * An empty `id` field is reported as an empty string. An `id` field containing U+0000 is ignored.
+     *
+     * @param id - The value of the last valid `id` field in the block
+     */
+    onId?: ((id: string) => void) | undefined;
+    /**
+     * Behavior when a parsing error occurs.
+     *
+     * - A custom function can be provided to handle the error.
+     * - `'terminate'` will error the stream and stop parsing.
+     * - Any other value will ignore the error and continue parsing.
+     *
+     * @defaultValue `undefined`
+     */
+    onError?: ('terminate' | ((error: Error) => void)) | undefined;
+    /**
+     * Callback for when a reconnection interval is sent from the server.
+     *
+     * @param retry - The number of milliseconds to wait before reconnecting.
+     */
+    onRetry?: ((retry: number) => void) | undefined;
+    /**
+     * Callback for when a comment is encountered in the stream.
+     *
+     * @param comment - The comment encountered in the stream.
+     */
+    onComment?: ((comment: string) => void) | undefined;
+    /**
+     * Maximum number of characters the parser is allowed to buffer across calls to `feed()`.
+     *
+     * When the limit is exceeded, the stream is always errored (regardless of the `onError`
+     * setting) since the underlying parser is unrecoverable without a `reset()`.
+     *
+     * @defaultValue `undefined` (unbounded)
+     */
+    maxBufferSize?: number | undefined;
+}
+/**
+ * A TransformStream that ingests a stream of strings and produces a stream of `EventSourceMessage`.
+ *
+ * @example Basic usage
+ * ```
+ * const eventStream =
+ *   response.body
+ *     .pipeThrough(new TextDecoderStream())
+ *     .pipeThrough(new EventSourceParserStream())
+ * ```
+ *
+ * @example Terminate stream on parsing errors
+ * ```
+ * const eventStream =
+ *  response.body
+ *   .pipeThrough(new TextDecoderStream())
+ *   .pipeThrough(new EventSourceParserStream({onError: 'terminate'}))
+ * ```
+ *
+ * @public
+ */
+declare class EventSourceParserStream extends TransformStream<string, EventSourceMessage> {
+    constructor({ onError, onRetry, onComment, onId, maxBufferSize }?: StreamOptions);
+}
 
-export { APICallError, InvalidResponseError, InvalidToolCallError, InvalidToolInputError, JSONParseError, RemoteAPIError, ToolExecutionError, XSAIError, clean, objCamelToSnake, postJSON, requestBody, requestHeaders, requestURL, responseCatch, responseJSON, strCamelToSnake, trampoline };
-export type { APICallErrorOptions, CommonRequestOptions, Fetch, InvalidResponseErrorOptions, InvalidResponseReason, InvalidToolCallErrorOptions, InvalidToolCallReason, InvalidToolInputErrorOptions, JSONParseErrorOptions, RemoteAPIErrorOptions, ToolExecutionErrorOptions, TrampolineFn, WithUnknown, XSAIErrorCode };
+export { EventSourceParserStream, HttpError, XSAIError, requestURL, sendRequest };
+export type { EventSourceMessage, HttpOptions, Promisable, SendRequestOptions, XSAIErrorCause, XSAIErrorCauseMap, XSAIErrorCode, XSAIErrorOptions };

package/dist/index.js

@@ -1,6 +1,7 @@
 class XSAIError extends Error {
-  constructor(message, code, options = {}) {
-    super(message, { cause: options.cause });
+  code;
+  constructor(code, message, ...[options]) {
+    super(message, options);
     this.code = code;
     this.name = new.target.name;
   }
@@ -8,134 +9,418 @@ class XSAIError extends Error {
     return error instanceof this;
   }
 }
-class APICallError extends XSAIError {
-  constructor(message, options) {
-    super(message, "api_call_error", options);
-    this.requestBody = options.requestBody;
-    this.response = options.response;
-    this.responseBody = options.responseBody;
-    this.responseHeaders = Object.fromEntries(options.response.headers.entries());
-    this.statusCode = options.response.status;
-    this.statusText = options.response.statusText;
-    this.url = options.response.url;
+class HttpError extends XSAIError {
+  body;
+  /** The raw response headers, for debugging (e.g. `x-request-id`, `retry-after`). */
+  headers;
+  status;
+  constructor({ body, headers, status }, ...options) {
+    super("http-error", `HTTP ${status}: ${body}`, ...options);
+    this.body = body;
+    this.headers = headers;
+    this.status = status;
   }
 }
-class InvalidResponseError extends XSAIError {
+
+const requestURL = (path, baseURL) => {
+  const base = baseURL.toString();
+  return new URL(path, base.endsWith("/") ? base : `${base}/`);
+};
+const sendRequest = async (options, httpOptions) => {
+  const url = requestURL(options.path, httpOptions.baseURL);
+  const headers = options.headers ?? {
+    ...httpOptions.headers,
+    "Authorization": httpOptions.apiKey == null ? httpOptions.headers?.Authorization : `Bearer ${httpOptions.apiKey}`,
+    "Content-Type": options.body instanceof FormData ? void 0 : options.body == null ? httpOptions.headers?.["Content-Type"] : "application/json"
+  };
+  const responseCatch = async (res) => {
+    if (!res.ok)
+      throw new HttpError({ body: await res.text(), headers: res.headers, status: res.status });
+    if (res.body == null)
+      throw new XSAIError("invalid-response", "Response body is empty");
+    return res;
+  };
+  const requestCatch = (cause) => {
+    options.signal?.throwIfAborted();
+    throw new XSAIError("network-error", `request to ${url.toString()} failed`, {
+      cause: cause ?? new Error("fetch rejected without a reason")
+    });
+  };
+  const request = new Request(url, {
+    body: options.body == null ? void 0 : options.body instanceof FormData ? options.body : JSON.stringify(options.body),
+    headers: Object.fromEntries(Object.entries(headers).filter(
+      ([name, value]) => value !== void 0 && (!(options.body instanceof FormData) || name.toLowerCase() !== "content-type")
+    )),
+    method: options.method ?? "POST",
+    signal: options.signal
+  });
+  return (httpOptions.fetch ?? fetch)(request).then(responseCatch, requestCatch);
+};
+
+class ParseError extends Error {
   constructor(message, options) {
-    super(message, "invalid_response", options);
-    Object.assign(this, options);
+    super(message);
+    this.name = "ParseError";
+    this.type = options.type;
+    this.field = options.field;
+    this.value = options.value;
+    this.line = options.line;
   }
 }
-class InvalidToolCallError extends XSAIError {
-  constructor(message, options) {
-    super(message, "invalid_tool_call", options);
-    Object.assign(this, options);
+
+const LF = 10;
+const CR = 13;
+const SPACE = 32;
+const MAX_FIELD_PREFIX_LENGTH = 6;
+function createParser(config) {
+  if (typeof config === "function") {
+    throw new TypeError("`config` must be an object, got a function instead. Did you mean `createParser({onEvent: fn})`?");
   }
-}
-class InvalidToolInputError extends XSAIError {
-  constructor(message, options) {
-    super(message, "invalid_tool_input", options);
-    Object.assign(this, options);
+  const { maxBufferSize, onComment, onError, onEvent, onId, onRetry } = config;
+  const pendingFragments = [];
+  let pendingFragmentsLength = 0;
+  let bomPrefix = "";
+  let id;
+  let data = "";
+  let dataLines = 0;
+  let eventType;
+  let terminated = false;
+  let skippingLine = false;
+  let skipNextLineFeed = false;
+  function feed(chunk) {
+    if (terminated) {
+      throw new Error("Cannot feed parser: it was terminated after exceeding the configured max buffer size. Call `reset()` to resume parsing.");
+    }
+    if (bomPrefix !== void 0) {
+      chunk = bomPrefix + chunk;
+      if (chunk === "" || chunk === "\xEF" || chunk === "\xEF\xBB") {
+        bomPrefix = chunk;
+        return;
+      }
+      bomPrefix = void 0;
+      chunk = chunk.replace(/^(?:\uFEFF|\xEF\xBB\xBF)/, "");
+    }
+    if (skippingLine || skipNextLineFeed) {
+      chunk = resumeAfterSkip(chunk);
+      if (!chunk) {
+        return;
+      }
+    }
+    if (!pendingFragments.length) {
+      const trailing = processLines(chunk);
+      if (trailing !== "") {
+        storeTrailing(trailing);
+      }
+      checkBufferSize();
+      return;
+    }
+    if (chunk.indexOf("\n") === -1 && chunk.indexOf("\r") === -1) {
+      if (pendingFragmentsLength < MAX_FIELD_PREFIX_LENGTH) {
+        const head = pendingFragments.join("") + chunk.slice(0, MAX_FIELD_PREFIX_LENGTH - pendingFragmentsLength);
+        if (!shouldBufferTrailing(head)) {
+          pendingFragments.length = 0;
+          pendingFragmentsLength = 0;
+          skippingLine = true;
+          return;
+        }
+      }
+      pendingFragments.push(chunk);
+      pendingFragmentsLength += chunk.length;
+      checkBufferSize();
+      return;
+    }
+    pendingFragments.push(chunk);
+    const input = pendingFragments.join("");
+    pendingFragments.length = 0;
+    pendingFragmentsLength = 0;
+    storeTrailing(processLines(input));
+    checkBufferSize();
   }
-}
-class JSONParseError extends XSAIError {
-  constructor(message, options) {
-    super(message, "json_parse_error", options);
-    this.text = options.text;
+  function resumeAfterSkip(chunk) {
+    if (chunk.length === 0) {
+      return chunk;
+    }
+    if (skipNextLineFeed) {
+      skipNextLineFeed = false;
+      return chunk.charCodeAt(0) === LF ? chunk.slice(1) : chunk;
+    }
+    const crIndex = chunk.indexOf("\r");
+    const lfIndex = chunk.indexOf("\n");
+    const lineEnd = crIndex === -1 ? lfIndex : lfIndex === -1 ? crIndex : crIndex < lfIndex ? crIndex : lfIndex;
+    if (lineEnd === -1) {
+      return "";
+    }
+    if (lineEnd === chunk.length - 1 && chunk.charCodeAt(lineEnd) === CR) {
+      skippingLine = false;
+      skipNextLineFeed = true;
+      return "";
+    }
+    skippingLine = false;
+    return chunk.slice(lineEnd + (chunk.charCodeAt(lineEnd) === CR && chunk.charCodeAt(lineEnd + 1) === LF ? 2 : 1));
   }
-}
-class RemoteAPIError extends XSAIError {
-  constructor(message, options) {
-    super(message, "remote_api_error", options);
-    Object.assign(this, options);
+  function storeTrailing(trailing) {
+    if (!trailing)
+      return;
+    if (trailing.charCodeAt(trailing.length - 1) === CR) {
+      parseLine(trailing, 0, trailing.length - 1);
+      skipNextLineFeed = true;
+      return;
+    }
+    if (shouldBufferTrailing(trailing)) {
+      pendingFragments.push(trailing);
+      pendingFragmentsLength = trailing.length;
+      return;
+    }
+    skippingLine = true;
   }
-}
-class ToolExecutionError extends XSAIError {
-  constructor(message, options) {
-    super(message, "tool_execution_error", options);
-    Object.assign(this, options);
+  function shouldBufferTrailing(trailing) {
+    const firstCharCode = trailing.charCodeAt(0);
+    return firstCharCode === 58 && !!onComment || firstCharCode === 100 && isPotentialField(trailing, "data") || firstCharCode === 101 && isPotentialField(trailing, "event") || firstCharCode === 105 && isPotentialField(trailing, "id") || firstCharCode === 114 && isPotentialField(trailing, "retry");
   }
-}
-
-const strCamelToSnake = (str) => str.replace(/[A-Z]/g, (s) => `_${s.toLowerCase()}`);
-const objCamelToSnake = (obj) => Object.fromEntries(Object.entries(obj).map(([k, v]) => [strCamelToSnake(k), v]));
-
-const clean = (obj) => Object.fromEntries(
-  Object.entries(obj).filter(([, v]) => v !== void 0)
-);
-
-const requestBody = (body) => JSON.stringify(objCamelToSnake(clean({
-  ...body,
-  abortSignal: void 0,
-  apiKey: void 0,
-  baseURL: void 0,
-  fetch: void 0,
-  headers: void 0
-})));
-
-const requestHeaders = (headers, apiKey) => clean({
-  Authorization: apiKey !== void 0 ? `Bearer ${apiKey}` : void 0,
-  ...headers
-});
-
-const requestURL = (path, baseURL) => {
-  const base = baseURL.toString();
-  return new URL(path, base.endsWith("/") ? base : `${base}/`);
-};
-
-const responseCatch = async (res) => {
-  if (!res.ok) {
-    const responseBody = await res.text();
-    throw new APICallError(`Remote sent ${res.status} response: ${responseBody}`, {
-      response: res,
-      responseBody
-    });
+  function checkBufferSize() {
+    if (maxBufferSize === void 0)
+      return;
+    if (pendingFragmentsLength + data.length <= maxBufferSize)
+      return;
+    terminated = true;
+    pendingFragments.length = 0;
+    pendingFragmentsLength = 0;
+    id = void 0;
+    data = "";
+    dataLines = 0;
+    eventType = void 0;
+    skippingLine = false;
+    skipNextLineFeed = false;
+    onError === null || onError === void 0 ? void 0 : onError(new ParseError(`Buffered data exceeded max buffer size of ${maxBufferSize} characters`, {
+      type: "max-buffer-size-exceeded"
+    }));
   }
-  if (!res.body) {
-    throw new InvalidResponseError("Response body is empty from remote server", {
-      reason: "empty_body",
-      response: res
-    });
+  function processLines(chunk) {
+    let searchIndex = 0;
+    if (chunk.indexOf("\r") === -1) {
+      let lfIndex = chunk.indexOf("\n", searchIndex);
+      while (lfIndex !== -1) {
+        if (searchIndex === lfIndex) {
+          if (id !== void 0) {
+            onId === null || onId === void 0 ? void 0 : onId(id);
+          }
+          if (dataLines > 0) {
+            onEvent === null || onEvent === void 0 ? void 0 : onEvent({ id, event: eventType, data });
+          }
+          id = void 0;
+          data = "";
+          dataLines = 0;
+          eventType = void 0;
+          searchIndex = lfIndex + 1;
+          lfIndex = chunk.indexOf("\n", searchIndex);
+          continue;
+        }
+        const firstCharCode = chunk.charCodeAt(searchIndex);
+        if (isDataPrefix(chunk, searchIndex, firstCharCode)) {
+          const valueStart = chunk.charCodeAt(searchIndex + 5) === SPACE ? searchIndex + 6 : searchIndex + 5;
+          const value = chunk.slice(valueStart, lfIndex);
+          if (dataLines === 0 && chunk.charCodeAt(lfIndex + 1) === LF) {
+            if (id !== void 0) {
+              onId === null || onId === void 0 ? void 0 : onId(id);
+            }
+            onEvent === null || onEvent === void 0 ? void 0 : onEvent({ id, event: eventType, data: value });
+            id = void 0;
+            data = "";
+            eventType = void 0;
+            searchIndex = lfIndex + 2;
+            lfIndex = chunk.indexOf("\n", searchIndex);
+            continue;
+          }
+          data = dataLines === 0 ? value : `${data}
+${value}`;
+          dataLines++;
+        } else if (isEventPrefix(chunk, searchIndex, firstCharCode)) {
+          eventType = chunk.slice(chunk.charCodeAt(searchIndex + 6) === SPACE ? searchIndex + 7 : searchIndex + 6, lfIndex) || void 0;
+        } else {
+          parseLine(chunk, searchIndex, lfIndex);
+        }
+        searchIndex = lfIndex + 1;
+        lfIndex = chunk.indexOf("\n", searchIndex);
+      }
+      return chunk.slice(searchIndex);
+    }
+    while (searchIndex < chunk.length) {
+      const crIndex = chunk.indexOf("\r", searchIndex);
+      const lfIndex = chunk.indexOf("\n", searchIndex);
+      let lineEnd = -1;
+      if (crIndex !== -1 && lfIndex !== -1) {
+        lineEnd = crIndex < lfIndex ? crIndex : lfIndex;
+      } else if (crIndex !== -1) {
+        if (crIndex === chunk.length - 1) {
+          lineEnd = -1;
+        } else {
+          lineEnd = crIndex;
+        }
+      } else if (lfIndex !== -1) {
+        lineEnd = lfIndex;
+      }
+      if (lineEnd === -1) {
+        break;
+      }
+      parseLine(chunk, searchIndex, lineEnd);
+      searchIndex = lineEnd + 1;
+      if (chunk.charCodeAt(searchIndex - 1) === CR && chunk.charCodeAt(searchIndex) === LF) {
+        searchIndex++;
+      }
+    }
+    return chunk.slice(searchIndex);
   }
-  if (!(res.body instanceof ReadableStream)) {
-    const contentType = res.headers.get("Content-Type");
-    throw new InvalidResponseError(`Expected Response body to be a ReadableStream, but got ${String(res.body)}; Content Type is ${contentType}`, {
-      body: res.body,
-      contentType,
-      reason: "invalid_body",
-      response: res
-    });
+  function parseLine(chunk, start, end) {
+    if (start === end) {
+      dispatchEvent();
+      return;
+    }
+    const firstCharCode = chunk.charCodeAt(start);
+    if (isDataPrefix(chunk, start, firstCharCode)) {
+      const valueStart = chunk.charCodeAt(start + 5) === SPACE ? start + 6 : start + 5;
+      const value2 = chunk.slice(valueStart, end);
+      data = dataLines === 0 ? value2 : `${data}
+${value2}`;
+      dataLines++;
+      return;
+    }
+    if (isEventPrefix(chunk, start, firstCharCode)) {
+      eventType = chunk.slice(chunk.charCodeAt(start + 6) === SPACE ? start + 7 : start + 6, end) || void 0;
+      return;
+    }
+    if (firstCharCode === 105 && chunk.charCodeAt(start + 1) === 100 && chunk.charCodeAt(start + 2) === 58) {
+      const value2 = chunk.slice(chunk.charCodeAt(start + 3) === SPACE ? start + 4 : start + 3, end);
+      if (!value2.includes("\0"))
+        id = value2;
+      return;
+    }
+    if (firstCharCode === 58) {
+      if (onComment) {
+        const line2 = chunk.slice(start, end);
+        onComment(line2.slice(chunk.charCodeAt(start + 1) === SPACE ? 2 : 1));
+      }
+      return;
+    }
+    const line = chunk.slice(start, end);
+    const fieldSeparatorIndex = line.indexOf(":");
+    if (fieldSeparatorIndex === -1) {
+      processField(line, "", line);
+      return;
+    }
+    const field = line.slice(0, fieldSeparatorIndex);
+    const offset = line.charCodeAt(fieldSeparatorIndex + 1) === SPACE ? 2 : 1;
+    const value = line.slice(fieldSeparatorIndex + offset);
+    processField(field, value, line);
   }
-  return res;
-};
-
-const postJSON = async (path, options) => (options.fetch ?? globalThis.fetch)(requestURL(path, options.baseURL), {
-  body: requestBody(options),
-  headers: requestHeaders({
-    "Content-Type": "application/json",
-    ...options.headers
-  }, options.apiKey),
-  method: "POST",
-  signal: options.abortSignal
-}).then(responseCatch);
+  function processField(field, value, line) {
+    switch (field) {
+      case "event":
+        eventType = value || void 0;
+        break;
+      case "data":
+        data = dataLines === 0 ? value : `${data}
+${value}`;
+        dataLines++;
+        break;
+      case "id":
+        if (!value.includes("\0"))
+          id = value;
+        break;
+      case "retry":
+        if (/^\d+$/.test(value)) {
+          onRetry === null || onRetry === void 0 ? void 0 : onRetry(parseInt(value, 10));
+        } else {
+          onError === null || onError === void 0 ? void 0 : onError(new ParseError(`Invalid \`retry\` value: "${value}"`, {
+            type: "invalid-retry",
+            value,
+            line
+          }));
+        }
+        break;
+      default:
+        onError === null || onError === void 0 ? void 0 : onError(new ParseError(`Unknown field "${field.length > 20 ? `${field.slice(0, 20)}\u2026` : field}"`, { type: "unknown-field", field, value, line }));
+        break;
+    }
+  }
+  function dispatchEvent() {
+    if (id !== void 0) {
+      onId === null || onId === void 0 ? void 0 : onId(id);
+    }
+    if (dataLines > 0) {
+      onEvent === null || onEvent === void 0 ? void 0 : onEvent({
+        id,
+        event: eventType,
+        data
+      });
+    }
+    id = void 0;
+    data = "";
+    dataLines = 0;
+    eventType = void 0;
+  }
+  function reset(options = {}) {
+    if (options.consume && pendingFragments.length > 0) {
+      const incompleteLine = pendingFragments.join("");
+      parseLine(incompleteLine, 0, incompleteLine.length);
+    }
+    bomPrefix = "";
+    id = void 0;
+    data = "";
+    dataLines = 0;
+    eventType = void 0;
+    pendingFragments.length = 0;
+    pendingFragmentsLength = 0;
+    terminated = false;
+    skippingLine = false;
+    skipNextLineFeed = false;
+  }
+  return { feed, reset };
+}
+function isDataPrefix(chunk, i, firstCharCode) {
+  return firstCharCode === 100 && chunk.charCodeAt(i + 1) === 97 && chunk.charCodeAt(i + 2) === 116 && chunk.charCodeAt(i + 3) === 97 && chunk.charCodeAt(i + 4) === 58;
+}
+function isEventPrefix(chunk, i, firstCharCode) {
+  return firstCharCode === 101 && chunk.charCodeAt(i + 1) === 118 && chunk.charCodeAt(i + 2) === 101 && chunk.charCodeAt(i + 3) === 110 && chunk.charCodeAt(i + 4) === 116 && chunk.charCodeAt(i + 5) === 58;
+}
+function isPotentialField(line, field) {
+  let i = 1;
+  while (i < line.length && i < field.length) {
+    if (line.charCodeAt(i) !== field.charCodeAt(i)) {
+      return false;
+    }
+    i++;
+  }
+  return line.length <= field.length || line.charCodeAt(field.length) === 58;
+}
 
-const responseJSON = async (res) => {
-  const text = await res.text();
-  try {
-    return JSON.parse(text);
-  } catch (cause) {
-    throw new JSONParseError(`Failed to parse response, response body: ${text}`, {
-      cause,
-      text
+class EventSourceParserStream extends TransformStream {
+  constructor({ onError, onRetry, onComment, onId, maxBufferSize } = {}) {
+    let parser;
+    super({
+      start(controller) {
+        parser = createParser({
+          onEvent: (event) => {
+            controller.enqueue(event);
+          },
+          onError(error) {
+            if (typeof onError === "function") {
+              onError(error);
+            }
+            if (onError === "terminate" || error.type === "max-buffer-size-exceeded") {
+              controller.error(error);
+            }
+          },
+          onRetry,
+          onComment,
+          onId,
+          maxBufferSize
+        });
+      },
+      transform(chunk) {
+        parser.feed(chunk);
+      }
     });
   }
-};
-
-const trampoline = async (fn) => {
-  let result = await fn();
-  while (result instanceof Function)
-    result = await result();
-  return result;
-};
+}
 
-export { APICallError, InvalidResponseError, InvalidToolCallError, InvalidToolInputError, JSONParseError, RemoteAPIError, ToolExecutionError, XSAIError, clean, objCamelToSnake, postJSON, requestBody, requestHeaders, requestURL, responseCatch, responseJSON, strCamelToSnake, trampoline };
+export { EventSourceParserStream, HttpError, XSAIError, requestURL, sendRequest };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@xsai/shared",
   "type": "module",
-  "version": "0.5.1",
-  "description": "extra-small AI SDK.",
+  "version": "1.0.0-beta.2",
+  "description": "extra-small AI SDK: shared utilities for xsAI packages.",
   "author": "Moeru AI",
   "license": "MIT",
   "homepage": "https://xsai.js.org",
@@ -14,8 +14,10 @@
   "bugs": "https://github.com/moeru-ai/xsai/issues",
   "keywords": [
     "xsai",
+    "ai",
     "openai",
-    "ai"
+    "shared",
+    "utils"
   ],
   "sideEffects": false,
   "exports": {
@@ -28,11 +30,15 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=26"
+  },
   "devDependencies": {
-    "@moeru/std": "^0.1.0-beta.20"
+    "eventsource-parser": "^4.1.1"
   },
   "scripts": {
-    "build": "pkgroll"
+    "build": "pkgroll --clean-dist",
+    "test": "vitest run"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"