@newbase-clawchat/openclaw-clawchat 2026.4.15

package/src/api-client.ts

@@ -0,0 +1,225 @@
+import {
+  ClawlingApiError,
+  type AgentConnectResult,
+  type FriendList,
+  type Profile,
+  type UploadResult,
+} from "./api-types.ts";
+import { CHANNEL_ID } from "./config.ts";
+
+export interface ApiClientOptions {
+  baseUrl: string;
+  token: string;
+  /**
+   * Logged-in agent's `user_id`. Required for `updateMyProfile`, which
+   * targets `/v1/agents/{userId}`. Safe to omit for unauthenticated /
+   * pre-login calls (e.g. `agentsConnect`).
+   */
+  userId?: string;
+  /** Test override only. Defaults to global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface OpenclawClawlingApiClient {
+  getMyProfile(): Promise<Profile>;
+  getUserInfo(userId: string): Promise<Profile>;
+  listFriends(params: { page?: number; pageSize?: number }): Promise<FriendList>;
+  updateMyProfile(patch: { nick_name?: string; avatar?: string }): Promise<Profile>;
+  uploadMedia(params: { buffer: Buffer; filename: string; mime?: string }): Promise<UploadResult>;
+  /**
+   * Exchange an invite code for an agent token.
+   * Request body shape: `{ code, platform, type }`.
+   */
+  agentsConnect(params: {
+    /** The invite code entered by the operator. */
+    inviteCode: string;
+    /** Platform the agent is attaching from (e.g. "openclaw"). */
+    platform: string;
+    /** Agent type tag (e.g. "bot"). */
+    type: string;
+  }): Promise<AgentConnectResult>;
+  /**
+   * Upload an avatar image via `POST /v1/files/upload-url`. Returns the
+   * same `UploadResult` shape as `uploadMedia` — the resulting `url` is
+   * what you then pass to `updateMyProfile({ avatar: url })`.
+   */
+  uploadAvatar(params: {
+    buffer: Buffer;
+    filename: string;
+    mime?: string;
+  }): Promise<UploadResult>;
+}
+
+export function createOpenclawClawlingApiClient(opts: ApiClientOptions): OpenclawClawlingApiClient {
+  if (!/^https?:\/\//i.test(opts.baseUrl)) {
+    throw new ClawlingApiError(
+      "validation",
+      `openclaw-clawchat baseUrl must start with http:// or https:// (got "${opts.baseUrl}")`,
+    );
+  }
+  const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+
+  function url(path: string): string {
+    return `${baseUrl}${path}`;
+  }
+
+  function authHeaders(extra: Record<string, string> = {}): Record<string, string> {
+    // `X-Device-Id` is sent on every request so the server can correlate
+    // activity back to this plugin instance. Callers may override via
+    // `extra` (e.g. tests) but the default is the channel id.
+    return {
+      authorization: `Bearer ${opts.token}`,
+      "x-device-id": CHANNEL_ID,
+      ...extra,
+    };
+  }
+
+  async function readEnvelope<T>(res: Response, path: string): Promise<T> {
+    if (res.status === 401 || res.status === 403) {
+      throw new ClawlingApiError("auth", `unauthorized (status ${res.status})`, {
+        status: res.status,
+        path,
+      });
+    }
+    if (!res.ok) {
+      const snippet = await res.text().catch(() => "");
+      throw new ClawlingApiError("transport", `http ${res.status} ${snippet.slice(0, 200)}`, {
+        status: res.status,
+        path,
+      });
+    }
+    let parsed: unknown;
+    try {
+      parsed = await res.json();
+    } catch (err) {
+      throw new ClawlingApiError(
+        "transport",
+        `non-JSON response: ${err instanceof Error ? err.message : String(err)}`,
+        { status: res.status, path },
+      );
+    }
+    // Unified envelope: `{ code: number, msg: string, data: T }`.
+    // `code === 0` means success; any other value is a business error whose
+    // `msg` is surfaced to callers and `code` is preserved on the error meta.
+    const env = parsed as { code?: unknown; msg?: unknown; data?: T };
+    const code = typeof env.code === "number" ? env.code : Number.NaN;
+    const msg = typeof env.msg === "string" ? env.msg : "";
+    if (!Number.isFinite(code)) {
+      throw new ClawlingApiError("transport", "invalid envelope: missing numeric `code`", {
+        status: res.status,
+        path,
+      });
+    }
+    if (code !== 0) {
+      throw new ClawlingApiError("api", msg || `code=${code}`, {
+        code,
+        status: res.status,
+        path,
+      });
+    }
+    return env.data as T;
+  }
+
+  async function call<T>(
+    method: string,
+    path: string,
+    init?: { body?: unknown; headers?: Record<string, string> },
+  ): Promise<T> {
+    let res: Response;
+    try {
+      const requestInit: RequestInit = {
+        method,
+        headers: authHeaders(init?.headers),
+      };
+      if (init?.body !== undefined) {
+        requestInit.body = init.body as BodyInit;
+      }
+      res = await fetchImpl(url(path), requestInit);
+    } catch (err) {
+      throw new ClawlingApiError(
+        "transport",
+        `fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+        { path },
+      );
+    }
+    return await readEnvelope<T>(res, path);
+  }
+
+  // All JSON API endpoints live under `/v1/...`. Media upload is the one
+  // intentional exception — the upstream server mounts it at `/media/upload`
+  // without the version prefix.
+  return {
+    async getMyProfile(): Promise<Profile> {
+      return await call<Profile>("GET", "/v1/users/me");
+    },
+    async getUserInfo(userId: string): Promise<Profile> {
+      return await call<Profile>("GET", `/v1/users/${encodeURIComponent(userId)}`);
+    },
+    async listFriends(params): Promise<FriendList> {
+      const sp = new URLSearchParams();
+      if (typeof params.page === "number") sp.set("page", String(params.page));
+      if (typeof params.pageSize === "number") sp.set("pageSize", String(params.pageSize));
+      const q = sp.toString();
+      return await call<FriendList>("GET", q ? `/v1/friends?${q}` : "/v1/friends");
+    },
+    async updateMyProfile(patch): Promise<Profile> {
+      if (!opts.userId?.trim()) {
+        throw new ClawlingApiError(
+          "validation",
+          "updateMyProfile: userId is required to target /v1/agents/{userId}",
+        );
+      }
+      return await call<Profile>(
+        "PATCH",
+        `/v1/agents/${encodeURIComponent(opts.userId.trim())}`,
+        {
+          body: JSON.stringify(patch),
+          headers: { "content-type": "application/json" },
+        },
+      );
+    },
+    async agentsConnect({ inviteCode, platform, type }): Promise<AgentConnectResult> {
+      if (!inviteCode?.trim()) {
+        throw new ClawlingApiError("validation", "agentsConnect: inviteCode is required");
+      }
+      if (!platform?.trim()) {
+        throw new ClawlingApiError("validation", "agentsConnect: platform is required");
+      }
+      if (!type?.trim()) {
+        throw new ClawlingApiError("validation", "agentsConnect: type is required");
+      }
+      return await call<AgentConnectResult>("POST", "/v1/agents/connect", {
+        // `X-Device-Id` is added globally via `authHeaders` on every request.
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          code: inviteCode.trim(),
+          platform: platform.trim(),
+          type: type.trim(),
+        }),
+      });
+    },
+    async uploadMedia(params): Promise<UploadResult> {
+      const blob = new Blob([new Uint8Array(params.buffer)], {
+        type: params.mime ?? "application/octet-stream",
+      });
+      const file = new File([blob], params.filename, {
+        type: params.mime ?? "application/octet-stream",
+      });
+      const fd = new FormData();
+      fd.set("file", file);
+      return await call<UploadResult>("POST", "/media/upload", { body: fd });
+    },
+    async uploadAvatar(params): Promise<UploadResult> {
+      const blob = new Blob([new Uint8Array(params.buffer)], {
+        type: params.mime ?? "application/octet-stream",
+      });
+      const file = new File([blob], params.filename, {
+        type: params.mime ?? "application/octet-stream",
+      });
+      const fd = new FormData();
+      fd.set("file", file);
+      return await call<UploadResult>("POST", "/v1/files/upload-url", { body: fd });
+    },
+  };
+}

package/src/api-types.ts

@@ -0,0 +1,71 @@
+/**
+ * Public-facing types for the Clawling Chat HTTP API.
+ *
+ * Field names mirror the upstream API (snake_case) so we don't lose
+ * fidelity on responses. Tool schemas accept camelCase externally and
+ * translate at the api-client boundary.
+ */
+
+export interface Profile {
+  user_id: string;
+  nick_name: string;
+  avatar?: string;
+  bio?: string;
+}
+
+export interface FriendList {
+  items: Profile[];
+  total?: number;
+  page: number;
+  pageSize: number;
+}
+
+export interface UploadResult {
+  url: string;
+  size: number;
+  mime: string;
+}
+
+export interface AgentProfile {
+  id: string;
+  owner_id: string;
+  user_id: string;
+  type: string;
+  nickname: string;
+  avatar_url: string;
+  bio: string;
+  visibility: string;
+  status: string;
+  platform: string;
+  created_at: string;
+}
+
+/**
+ * Response payload for `POST /v1/agents/connect` — the endpoint that exchanges
+ * an invite code for the credentials this account uses to open the
+ * streaming WebSocket. `access_token` is the bearer this agent uses for
+ * API + WebSocket auth; `agent.user_id` is the stable id the streaming
+ * protocol routes on.
+ */
+export interface AgentConnectResult {
+  agent: AgentProfile;
+  access_token: string;
+  refresh_token: string;
+}
+
+export type ClawlingApiErrorKind =
+  | "auth" // 401 / 403 — token bad or expired
+  | "api" // server-returned non-zero `code`
+  | "transport" // network failure / 5xx / non-JSON body
+  | "validation"; // local pre-check failure (e.g., file too large)
+
+export class ClawlingApiError extends Error {
+  constructor(
+    public readonly kind: ClawlingApiErrorKind,
+    message: string,
+    public readonly meta?: { code?: number; status?: number; path?: string },
+  ) {
+    super(message);
+    this.name = "ClawlingApiError";
+  }
+}

package/src/buffered-stream.test.ts

@@ -0,0 +1,201 @@
+import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import { describe, expect, it, vi } from "vitest";
+import { mergeStreamingText, openBufferedStreamingSession } from "./buffered-stream.ts";
+
+type Emitted = { event: string; payload: Record<string, unknown> };
+
+function mockClient() {
+  const sent: Emitted[] = [];
+  const typing: Array<[unknown, boolean]> = [];
+  const client = {
+    emitRaw: vi.fn((event: string, payload: Record<string, unknown>) => {
+      sent.push({ event, payload });
+    }),
+    typing: vi.fn((to: unknown, flag: boolean) => {
+      typing.push([to, flag]);
+    }),
+  } as unknown as ClawlingChatClient;
+  return { client, sent, typing };
+}
+
+describe("mergeStreamingText", () => {
+  it("returns incoming when base empty", () => {
+    expect(mergeStreamingText("", "hi")).toBe("hi");
+  });
+
+  it("returns incoming when incoming is a prefix-extension of base", () => {
+    expect(mergeStreamingText("Hel", "Hello")).toBe("Hello");
+  });
+
+  it("returns base when incoming is a substring of base", () => {
+    expect(mergeStreamingText("Hello, world", "Hello")).toBe("Hello, world");
+  });
+
+  it("joins at overlap when neither is a prefix", () => {
+    expect(mergeStreamingText("Hello w", "world")).toBe("Hello world");
+  });
+
+  it("concatenates when no overlap", () => {
+    expect(mergeStreamingText("abc", "xyz")).toBe("abcxyz");
+  });
+});
+
+describe("openBufferedStreamingSession", () => {
+  it("emits typing(true) + created immediately on open", () => {
+    const { client, sent, typing } = mockClient();
+    openBufferedStreamingSession({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      messageId: "m1",
+      flushIntervalMs: 50,
+      minChunkChars: 4,
+      maxBufferChars: 1000,
+    });
+    expect(typing).toEqual([[{ id: "u1", type: "direct" }, true]]);
+    expect(sent.map((s) => s.event)).toEqual(["message.created"]);
+  });
+
+  it("flushes as message.add with { text: cumulative, delta: new } on threshold", async () => {
+    const { client, sent } = mockClient();
+    const session = openBufferedStreamingSession({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      messageId: "m1",
+      flushIntervalMs: 60_000,
+      minChunkChars: 4,
+      maxBufferChars: 1000,
+    });
+    // 3 chars — below threshold, should NOT flush yet
+    await session.queueSnapshot("abc");
+    expect(sent.filter((s) => s.event === "message.add")).toHaveLength(0);
+    // Reaching 6 chars (>= 4 chars of unflushed delta) should flush
+    await session.queueSnapshot("abcdef");
+    const adds = sent.filter((s) => s.event === "message.add");
+    expect(adds).toHaveLength(1);
+    expect((adds[0]!.payload as { fragments: unknown }).fragments).toEqual([
+      { kind: "text", text: "abcdef", delta: "abcdef" },
+    ]);
+    expect(session.flushedText).toBe("abcdef");
+  });
+
+  it("queueDelta carries cumulative text with per-frame delta", async () => {
+    const { client, sent } = mockClient();
+    const session = openBufferedStreamingSession({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      messageId: "m1",
+      flushIntervalMs: 60_000,
+      minChunkChars: 1,
+      maxBufferChars: 1000,
+    });
+    await session.queueDelta("Hello ");
+    await session.queueDelta("world");
+    const adds = sent.filter((s) => s.event === "message.add");
+    const fragments = adds.map(
+      (a) => (a.payload as { fragments: Array<{ kind: string; text: string; delta: string }> }).fragments,
+    );
+    expect(fragments).toEqual([
+      [{ kind: "text", text: "Hello ", delta: "Hello " }],
+      [{ kind: "text", text: "Hello world", delta: "world" }],
+    ]);
+    expect(session.currentText).toBe("Hello world");
+  });
+
+  it("done() flushes remaining buffer, emits message.done and typing(false)", async () => {
+    const { client, sent, typing } = mockClient();
+    const session = openBufferedStreamingSession({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      messageId: "m1",
+      flushIntervalMs: 60_000,
+      minChunkChars: 999,
+      maxBufferChars: 999,
+    });
+    await session.queueSnapshot("Hello, world");
+    // No add yet (below threshold, no timer fired)
+    expect(sent.filter((s) => s.event === "message.add")).toHaveLength(0);
+    await session.done();
+    const events = sent.map((s) => s.event);
+    expect(events).toEqual(["message.created", "message.add", "message.done"]);
+    expect(typing).toEqual([
+      [{ id: "u1", type: "direct" }, true],
+      [{ id: "u1", type: "direct" }, false],
+    ]);
+  });
+
+  it("done() is idempotent", async () => {
+    const { client, sent } = mockClient();
+    const session = openBufferedStreamingSession({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      messageId: "m1",
+      flushIntervalMs: 60_000,
+      minChunkChars: 999,
+      maxBufferChars: 999,
+    });
+    await session.done();
+    await session.done();
+    const doneCount = sent.filter((s) => s.event === "message.done").length;
+    expect(doneCount).toBe(1);
+  });
+
+  it("fail() emits message.failed with reason and typing(false)", async () => {
+    const { client, sent, typing } = mockClient();
+    const session = openBufferedStreamingSession({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      messageId: "m1",
+      flushIntervalMs: 60_000,
+      minChunkChars: 999,
+      maxBufferChars: 999,
+    });
+    await session.fail("boom");
+    const failed = sent.find((s) => s.event === "message.failed")!;
+    expect(failed.payload.reason).toBe("boom");
+    expect(typing.at(-1)).toEqual([{ id: "u1", type: "direct" }, false]);
+  });
+
+  it("deduplicates a snapshot that is a substring of the buffered snapshot", async () => {
+    const { client, sent } = mockClient();
+    const session = openBufferedStreamingSession({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      messageId: "m1",
+      flushIntervalMs: 60_000,
+      minChunkChars: 1,
+      maxBufferChars: 1000,
+    });
+    await session.queueSnapshot("Hello, world");
+    await session.queueSnapshot("Hello"); // substring — no-op
+    const adds = sent.filter((s) => s.event === "message.add");
+    expect(adds).toHaveLength(1);
+    expect(session.currentText).toBe("Hello, world");
+  });
+
+  it("done() carries fragments: [{ text: finalMerged }] on message.done", async () => {
+    const { client, sent } = mockClient();
+    const session = openBufferedStreamingSession({
+      client,
+      to: { id: "u1", type: "direct" },
+      sender: { sender_id: "a1", type: "direct", display_name: "Bot" },
+      messageId: "m1",
+      flushIntervalMs: 60_000,
+      minChunkChars: 1,
+      maxBufferChars: 1000,
+    });
+    await session.queueDelta("Hel");
+    await session.queueDelta("lo");
+    await session.done();
+    const doneFrame = sent.find((s) => s.event === "message.done")!;
+    expect((doneFrame.payload as { fragments: unknown }).fragments).toEqual([
+      { kind: "text", text: "Hello" },
+    ]);
+  });
+});

package/src/buffered-stream.ts

@@ -0,0 +1,206 @@
+import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import {
+  emitStreamAdd,
+  emitStreamCreated,
+  emitStreamDone,
+  emitStreamFailed,
+  type EnvelopeRouting,
+  type StreamSender,
+} from "./client.ts";
+
+/**
+ * Merge two views of the same progressively-revealed text.
+ *
+ * The agent runner may give us either:
+ *   - full snapshots   ("Hel", "Hello", "Hello, world") where each item is
+ *     a superset of the previous; or
+ *   - overlapping slices ("hello ", "world hello ") that don't share a
+ *     prefix but share an overlap at the join.
+ *
+ * This helper returns a longest-sensible combined string. Ported from
+ * `clawling-channel/src/reply-dispatcher.ts`.
+ */
+export function mergeStreamingText(
+  previousText: string | undefined,
+  nextText: string | undefined,
+): string {
+  const currentSnapshot = typeof previousText === "string" ? previousText : "";
+  const incomingText = typeof nextText === "string" ? nextText : "";
+  if (!incomingText) return currentSnapshot;
+  if (!currentSnapshot || incomingText === currentSnapshot) return incomingText;
+  if (incomingText.startsWith(currentSnapshot)) return incomingText;
+  if (currentSnapshot.startsWith(incomingText)) return currentSnapshot;
+  if (incomingText.includes(currentSnapshot)) return incomingText;
+  if (currentSnapshot.includes(incomingText)) return currentSnapshot;
+  const maxOverlap = Math.min(currentSnapshot.length, incomingText.length);
+  for (let overlap = maxOverlap; overlap > 0; overlap -= 1) {
+    if (currentSnapshot.slice(-overlap) === incomingText.slice(0, overlap)) {
+      return `${currentSnapshot}${incomingText.slice(overlap)}`;
+    }
+  }
+  return `${currentSnapshot}${incomingText}`;
+}
+
+export interface BufferedStreamOptions {
+  client: ClawlingChatClient;
+  routing: EnvelopeRouting;
+  sender: StreamSender;
+  messageId: string;
+  flushIntervalMs: number;
+  minChunkChars: number;
+  maxBufferChars: number;
+  /** Emit typing(true/false) around the stream lifecycle. Default: true. */
+  emitTyping?: boolean;
+}
+
+export interface BufferedStreamSession {
+  /** The full accumulated text (even if not yet flushed to the wire). */
+  readonly currentText: string;
+  /** The last flushed snapshot (sent via message.add events so far). */
+  readonly flushedText: string;
+  /** Replace the snapshot with a longer-or-equal version. */
+  queueSnapshot: (snapshot: string) => Promise<void>;
+  /** Append `delta` to the running snapshot. */
+  queueDelta: (delta: string) => Promise<void>;
+  /** Force any buffered text to be emitted as message.add before resolving. */
+  flush: () => Promise<void>;
+  /** Emit message.done once (idempotent) and typing(false). */
+  done: () => Promise<void>;
+  /** Emit message.failed and typing(false). */
+  fail: (reason?: string) => Promise<void>;
+}
+
+/**
+ * Build a streaming session wrapper around message.created/add/done events.
+ *
+ * Usage pattern (matching clawling-channel):
+ *   const session = openBufferedStreamingSession({...});
+ *   await session.queueSnapshot("Hel");
+ *   await session.queueSnapshot("Hello");
+ *   await session.queueDelta(", world");
+ *   await session.done();
+ */
+export function openBufferedStreamingSession(
+  options: BufferedStreamOptions,
+): BufferedStreamSession {
+  const emitTyping = options.emitTyping !== false;
+  if (emitTyping)
+    options.client.typing(options.routing.chatId, true, options.routing.chatType);
+  emitStreamCreated(options.client, {
+    messageId: options.messageId,
+    routing: options.routing,
+  });
+
+  let bufferedSnapshot = "";
+  let flushedSnapshot = "";
+  let sequence = 0;
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  let pendingFlush: Promise<void> = Promise.resolve();
+  let closed = false;
+
+  const clearTimer = () => {
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+  };
+
+  const performFlush = async () => {
+    clearTimer();
+    if (closed) return;
+    if (bufferedSnapshot === flushedSnapshot) return;
+    const snapshot = bufferedSnapshot;
+    const delta = snapshot.slice(flushedSnapshot.length);
+    if (!delta) return;
+    sequence += 1;
+    emitStreamAdd(options.client, {
+      messageId: options.messageId,
+      routing: options.routing,
+      sequence,
+      fullText: snapshot,
+      textDelta: delta,
+    });
+    flushedSnapshot = snapshot;
+  };
+
+  const flush = async (): Promise<void> => {
+    pendingFlush = pendingFlush.then(performFlush);
+    await pendingFlush;
+  };
+
+  const scheduleFlush = () => {
+    if (flushTimer || closed) return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flush();
+    }, options.flushIntervalMs);
+  };
+
+  const queueSnapshot = async (snapshot: string): Promise<void> => {
+    if (closed || !snapshot) return;
+    const base = bufferedSnapshot.length >= flushedSnapshot.length ? bufferedSnapshot : flushedSnapshot;
+    const merged = mergeStreamingText(base, snapshot);
+    if (merged === bufferedSnapshot) return;
+    bufferedSnapshot = merged;
+    const deltaChars = Math.max(0, bufferedSnapshot.length - flushedSnapshot.length);
+    if (deltaChars >= options.minChunkChars || bufferedSnapshot.length >= options.maxBufferChars) {
+      await flush();
+    } else {
+      scheduleFlush();
+    }
+  };
+
+  const queueDelta = async (delta: string): Promise<void> => {
+    if (closed || !delta) return;
+    bufferedSnapshot = `${bufferedSnapshot}${delta}`;
+    const deltaChars = Math.max(0, bufferedSnapshot.length - flushedSnapshot.length);
+    if (deltaChars >= options.minChunkChars || bufferedSnapshot.length >= options.maxBufferChars) {
+      await flush();
+    } else {
+      scheduleFlush();
+    }
+  };
+
+  const done = async (): Promise<void> => {
+    if (closed) return;
+    await flush();
+    closed = true;
+    clearTimer();
+    emitStreamDone(options.client, {
+      messageId: options.messageId,
+      routing: options.routing,
+      finalSequence: sequence,
+      finalText: bufferedSnapshot,
+    });
+    if (emitTyping)
+      options.client.typing(options.routing.chatId, false, options.routing.chatType);
+  };
+
+  const fail = async (reason?: string): Promise<void> => {
+    if (closed) return;
+    closed = true;
+    clearTimer();
+    emitStreamFailed(options.client, {
+      messageId: options.messageId,
+      routing: options.routing,
+      sequence: sequence + 1,
+      ...(reason !== undefined ? { reason } : {}),
+    });
+    if (emitTyping)
+      options.client.typing(options.routing.chatId, false, options.routing.chatType);
+  };
+
+  return {
+    get currentText() {
+      return bufferedSnapshot;
+    },
+    get flushedText() {
+      return flushedSnapshot;
+    },
+    queueSnapshot,
+    queueDelta,
+    flush,
+    done,
+    fail,
+  };
+}