@cms.ai/brand_brain 0.0.1

package/src/GuideClient.ts

@@ -0,0 +1,239 @@
+import type { LiveHttpClient } from "@navless/orpc/live/client";
+import { createApiClient, toApiBaseUrl } from "./api";
+import { extractIntegrationCookies, extractUTMParams, safeCookieString } from "./analytics";
+import { streamConversation } from "./chat-stream";
+import { EmbedTrackingEvent } from "./types";
+import type {
+  AskOptions,
+  ChatMessage,
+  ConsentLevels,
+  Conversation,
+  ConversationWithMessages,
+  GuideStreamEvent,
+  ImportSharedResult,
+  InitGuideConfig,
+  MarkSharedResult,
+  ResolvedGuide,
+  SelectDraftResult,
+  SkillHistoryGroup,
+  SkillInstance,
+  SubmitGateOptions,
+  SubmitGateResult,
+  TrackEventType,
+  UpdateSkillInstanceResult,
+  VisitorStatus,
+} from "./types";
+
+// Explicit shapes for the grouped API namespaces, annotated with locally-authored
+// types rather than the deep @orpc/client-derived client types — so the published
+// .d.ts stays self-contained and never inlines an external type across chunks.
+interface ConversationsApi {
+  getOrCreate(): Promise<Conversation>;
+  list(): Promise<Conversation[]>;
+  get(conversationId: string, options?: { cursor?: string; limit?: number }): Promise<ConversationWithMessages>;
+  delete(conversationId: string): Promise<Conversation>;
+}
+
+interface SkillsApi {
+  listHistory(): Promise<SkillHistoryGroup[]>;
+  get(skillInstanceId: string): Promise<SkillInstance>;
+  update(skillInstanceId: string, data: Record<string, unknown>): Promise<UpdateSkillInstanceResult>;
+  selectDraft(draftId: string): Promise<SelectDraftResult>;
+  markShared(skillInstanceId: string): Promise<MarkSharedResult>;
+  importShared(sourceSkillInstanceId: string): Promise<ImportSharedResult>;
+}
+
+function resolveDomain(config: InitGuideConfig): string {
+  if (config.domain) return config.domain;
+  if (typeof window !== "undefined") return window.location.hostname;
+  throw new Error("[brand_brain] `domain` is required when running without a browser `window`.");
+}
+
+interface GuideClientParams {
+  guide: ResolvedGuide;
+  apiBaseUrl: string;
+  domain: string;
+  fetchImpl: typeof globalThis.fetch;
+}
+
+/**
+ * The client returned by {@link initGuide}. Holds the resolved guide, the
+ * credentialed live API client, and the in-memory conversation history. Every
+ * method reuses an existing public endpoint — the SDK adds no server surface.
+ */
+export class GuideClient {
+  /** Resolved guide metadata (ids, theme, customization). */
+  readonly guide: ResolvedGuide;
+
+  private readonly apiBaseUrl: string;
+  private readonly domain: string;
+  private readonly fetchImpl: typeof globalThis.fetch;
+  // ECMAScript-private so the heavy LiveHttpClient type never reaches the .d.ts.
+  #api: LiveHttpClient;
+  private readonly history: ChatMessage[] = [];
+
+  private constructor(params: GuideClientParams) {
+    this.guide = params.guide;
+    this.apiBaseUrl = params.apiBaseUrl;
+    this.domain = params.domain;
+    this.fetchImpl = params.fetchImpl;
+    this.#api = createApiClient(this.apiBaseUrl, this.fetchImpl);
+  }
+
+  static async init(config: InitGuideConfig): Promise<GuideClient> {
+    const fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    const apiBaseUrl = toApiBaseUrl(config.baseUrl);
+    const domain = resolveDomain(config);
+
+    // First credentialed call — resolves the guide AND mints the visitor +
+    // session cookies via the live router middleware.
+    const api = createApiClient(apiBaseUrl, fetchImpl);
+    const guide = await api.guides.resolve({ domain, slug: config.slug });
+    const client = new GuideClient({ guide, apiBaseUrl, domain, fetchImpl });
+
+    await client.applyInitialConsent(config.consent ?? "auto", guide.gdprEnabled);
+    if (config.trackLoad ?? true) client.trackLoad();
+
+    return client;
+  }
+
+  /** The account this guide belongs to (used implicitly by history calls). */
+  get accountId(): string {
+    return this.guide.accountId;
+  }
+
+  /** The in-memory conversation history accumulated by {@link ask}. */
+  get messages(): readonly ChatMessage[] {
+    return this.history;
+  }
+
+  /**
+   * Send a message and stream the reply. Yields text deltas for the chat bubble
+   * plus every structured skill event; the full 7-skill surface flows through
+   * one stream. The user + assistant turns are appended to {@link messages}.
+   */
+  async *ask(message: string, options: AskOptions = {}): AsyncGenerator<GuideStreamEvent> {
+    this.history.push({ id: crypto.randomUUID(), role: "user", content: message });
+
+    let assistant: ChatMessage | null = null;
+    for await (const event of streamConversation({
+      apiBaseUrl: this.apiBaseUrl,
+      guideId: this.guide.id,
+      messages: this.history,
+      forcedSkill: options.forcedSkill,
+      fetchImpl: this.fetchImpl,
+      signal: options.signal,
+    })) {
+      if (event.type === "message-start") {
+        assistant = { id: event.messageId || crypto.randomUUID(), role: "assistant", content: "" };
+        this.history.push(assistant);
+      } else if (event.type === "text" && assistant) {
+        assistant.content += event.delta;
+      }
+      yield event;
+    }
+  }
+
+  /** Clear the in-memory conversation history (server-side history is unaffected). */
+  reset(): void {
+    this.history.length = 0;
+  }
+
+  /** Grant consent tiers. `essential` is always forced true server-side. */
+  async setConsent(levels: ConsentLevels): Promise<void> {
+    await this.#api.visitors.setConsent({ domain: this.domain, consent: levels });
+  }
+
+  /** Read the current visitor's tracking + consent + email status. */
+  getStatus(): Promise<VisitorStatus> {
+    return this.#api.visitors.getVisitorStatus();
+  }
+
+  /** Capture a lead email (sends a magic link when verification is required). */
+  submitGate(email: string, options: SubmitGateOptions = {}): Promise<SubmitGateResult> {
+    return this.#api.visitors.submitGate({ email, domain: this.domain, guideId: this.guide.id, ...options });
+  }
+
+  /**
+   * Fire an analytics event. Fire-and-forget — never throws into the host page.
+   * Uses a raw request (the same shape the embed script posts) so it stays
+   * decoupled from the typed client's event enum.
+   */
+  track(eventType: TrackEventType, properties?: Record<string, unknown>): void {
+    void this.fetchImpl(`${this.apiBaseUrl}/events/track`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      credentials: "include",
+      body: JSON.stringify({ json: { domain: this.domain, guideId: this.guide.id, eventType, properties: properties ?? {} } }),
+    }).catch(() => {
+      // Best-effort — analytics must not break the host page.
+    });
+  }
+
+  /** Fire the initial `embed_loaded` (with attribution) + first page view. */
+  trackLoad(): void {
+    const search = typeof window !== "undefined" ? window.location.search : "";
+    const parentUrl = typeof window !== "undefined" ? window.location.href : undefined;
+    const referrer = typeof document !== "undefined" ? document.referrer : undefined;
+    this.track(EmbedTrackingEvent.EmbedLoaded, {
+      referrer,
+      parentUrl,
+      utmParams: extractUTMParams(search),
+      integrationCookies: extractIntegrationCookies(safeCookieString()),
+    });
+    this.trackPageView();
+  }
+
+  /** Record a page view (call on client-side route changes in an SPA). */
+  trackPageView(url?: string): void {
+    const pageUrl = url ?? (typeof window !== "undefined" ? window.location.href : undefined);
+    this.track(EmbedTrackingEvent.EmbedPageView, { pageUrl });
+  }
+
+  /** End the current visit (best to call on `pagehide`). */
+  async endSession(): Promise<void> {
+    await this.#api.sessions.endSession();
+  }
+
+  /** Conversation history CRUD, scoped to this guide + account. */
+  readonly conversations: ConversationsApi = {
+    getOrCreate: () => this.#api.conversations.getOrCreate({ guideId: this.guide.id, accountId: this.guide.accountId }),
+    list: () => this.#api.conversations.list({ guideId: this.guide.id, accountId: this.guide.accountId }),
+    get: (conversationId: string, options?: { cursor?: string; limit?: number }) =>
+      this.#api.conversations.get({ conversationId, accountId: this.guide.accountId, ...options }),
+    delete: (conversationId: string) => this.#api.conversations.delete({ conversationId, accountId: this.guide.accountId }),
+  };
+
+  /** Persisted skill deliverables (how-to progress, diagnose answers, etc.). */
+  readonly skills: SkillsApi = {
+    listHistory: () => this.#api.skillInstances.listHistory({ accountId: this.guide.accountId, guideId: this.guide.id }),
+    get: (skillInstanceId: string) => this.#api.skillInstances.get({ skillInstanceId }),
+    update: (skillInstanceId: string, data: Record<string, unknown>) =>
+      this.#api.skillInstances.update({ skillInstanceId, data }),
+    selectDraft: (draftId: string) => this.#api.skillInstances.selectDraft({ draftId }),
+    markShared: (skillInstanceId: string) => this.#api.skillInstances.markShared({ skillInstanceId }),
+    importShared: (sourceSkillInstanceId: string) =>
+      this.#api.skillInstances.importShared({ sourceSkillInstanceId, accountId: this.guide.accountId }),
+  };
+
+  private async applyInitialConsent(consent: "auto" | ConsentLevels | false, gdprEnabled: boolean): Promise<void> {
+    if (consent === false) return;
+    try {
+      if (consent === "auto") {
+        // Non-GDPR guides auto-grant everything (mirrors the live app). GDPR
+        // guides wait for an explicit setConsent() from the host.
+        if (!gdprEnabled) await this.setConsent({ functional: true, analytical: true });
+        return;
+      }
+      await this.setConsent(consent);
+    } catch {
+      // Best-effort at init — the host can retry via setConsent() and inspect
+      // getStatus(). Don't fail init on a consent hiccup.
+    }
+  }
+}
+
+/** Bootstrap a guide session and return a ready-to-use {@link GuideClient}. */
+export async function initGuide(config: InitGuideConfig): Promise<GuideClient> {
+  return GuideClient.init(config);
+}

package/src/analytics.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { extractIntegrationCookies, extractUTMParams } from "./analytics";
+
+describe("extractUTMParams", () => {
+  it("returns the utm params present in the query string", () => {
+    expect(extractUTMParams("?utm_source=google&utm_medium=cpc")).toEqual({
+      utm_source: "google",
+      utm_medium: "cpc",
+    });
+  });
+
+  it("returns an empty object when no utm params are present", () => {
+    expect(extractUTMParams("?q=hello")).toEqual({});
+  });
+});
+
+describe("extractIntegrationCookies", () => {
+  it("extracts the hubspotutk value from a cookie string", () => {
+    expect(extractIntegrationCookies("foo=1; hubspotutk=abc123; bar=2")).toEqual({ hubspotutk: "abc123" });
+  });
+
+  it("returns an empty object when no integration cookies are present", () => {
+    expect(extractIntegrationCookies("foo=1; bar=2")).toEqual({});
+  });
+});

package/src/analytics.ts

@@ -0,0 +1,36 @@
+const UTM_KEYS = ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"] as const;
+const INTEGRATION_COOKIE_KEYS = ["hubspotutk", "_mkto_trk"] as const;
+
+/** Pull UTM attribution params out of a `location.search` string. */
+export function extractUTMParams(search: string): Record<string, string> {
+  const params = new URLSearchParams(search);
+  const result: Record<string, string> = {};
+  for (const key of UTM_KEYS) {
+    const value = params.get(key);
+    if (value) result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * Pull first-party integration cookies (HubSpot, Marketo) out of a
+ * `document.cookie` string so they can be forwarded for CRM stitching.
+ */
+export function extractIntegrationCookies(cookieString: string): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  for (const key of INTEGRATION_COOKIE_KEYS) {
+    const match = cookieString.match(new RegExp(`(?:^|;\\s*)${key}=([^;]*)`));
+    if (match?.[1]) cookies[key] = decodeURIComponent(match[1]);
+  }
+  return cookies;
+}
+
+/** Read `document.cookie`, swallowing the SecurityError thrown in opaque origins. */
+export function safeCookieString(): string {
+  if (typeof document === "undefined") return "";
+  try {
+    return document.cookie;
+  } catch {
+    return "";
+  }
+}

package/src/api.ts

@@ -0,0 +1,26 @@
+import { createLiveHttpClient, type LiveHttpClient } from "@navless/orpc/live/client";
+
+/**
+ * Normalize a branded-host origin into the `/api/v3` base the live API is served
+ * under. Accepts a bare origin ("https://guide.acme.com") or a URL that already
+ * ends with `/api/v3`.
+ */
+export function toApiBaseUrl(baseUrl: string): string {
+  const trimmed = baseUrl.replace(/\/+$/, "");
+  return trimmed.endsWith("/api/v3") ? trimmed : `${trimmed}/api/v3`;
+}
+
+/**
+ * Wrap a fetch implementation so every request carries the visitor cookies.
+ * This is the load-bearing piece: the branded host is same-site with the
+ * customer's page, so `credentials: "include"` lets the existing
+ * `navless-live-*` cookies attach in every browser.
+ */
+export function withCredentials(fetchImpl: typeof globalThis.fetch): typeof globalThis.fetch {
+  return (input, init) => fetchImpl(input, { ...init, credentials: "include" });
+}
+
+/** Build the typed live oRPC client, reusing @navless/orpc's client factory. */
+export function createApiClient(apiBaseUrl: string, fetchImpl: typeof globalThis.fetch): LiveHttpClient {
+  return createLiveHttpClient({ baseUrl: apiBaseUrl, fetch: withCredentials(fetchImpl) });
+}

package/src/chat-stream.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { streamConversation, type StreamConversationParams } from "./chat-stream";
+import type { GuideStreamEvent } from "./types";
+
+function sseFetch(payload: string): typeof globalThis.fetch {
+  return () => {
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(payload));
+        controller.close();
+      },
+    });
+    return Promise.resolve(new Response(stream, { status: 200 }));
+  };
+}
+
+async function collect(payload: string, overrides: Partial<StreamConversationParams> = {}): Promise<GuideStreamEvent[]> {
+  const events: GuideStreamEvent[] = [];
+  const stream = streamConversation({
+    apiBaseUrl: "https://guide.example.com/api/v3",
+    guideId: "guide-1",
+    messages: [{ id: "1", role: "user", content: "hi" }],
+    fetchImpl: sseFetch(payload),
+    ...overrides,
+  });
+  for await (const event of stream) events.push(event);
+  return events;
+}
+
+const frame = (obj: Record<string, unknown>): string => `data: ${JSON.stringify(obj)}\n\n`;
+const DONE = "data: [DONE]\n\n";
+
+describe("streamConversation", () => {
+  it("yields a text event for a TEXT_MESSAGE_CONTENT frame", async () => {
+    const events = await collect(frame({ type: "TEXT_MESSAGE_CONTENT", messageId: "m1", delta: "Hello" }) + DONE);
+    expect(events).toContainEqual({ type: "text", messageId: "m1", delta: "Hello" });
+  });
+
+  it("maps a skill_gate custom frame to a gate event", async () => {
+    const events = await collect(
+      frame({ type: "CUSTOM", name: "skill_gate", value: { skill: "businesscase", prompt: "email?" } }) + DONE,
+    );
+    expect(events).toContainEqual({ type: "gate", skill: "businesscase", prompt: "email?", skillInstanceId: undefined });
+  });
+
+  it("stops yielding at the [DONE] sentinel", async () => {
+    const events = await collect(DONE + frame({ type: "TEXT_MESSAGE_CONTENT", messageId: "m1", delta: "late" }));
+    expect(events).toEqual([]);
+  });
+
+  it("throws when the response is not ok", async () => {
+    const failing: typeof globalThis.fetch = () => Promise.resolve(new Response(null, { status: 500 }));
+    await expect(collect("", { fetchImpl: failing })).rejects.toThrow("status 500");
+  });
+});

package/src/chat-stream.ts

@@ -0,0 +1,130 @@
+import { GuideEvent, SSEMessageType } from "./types";
+import type { ChatMessage, GuideEventName, GuideStreamEvent, SkillResponseTypeType } from "./types";
+
+export interface StreamConversationParams {
+  apiBaseUrl: string;
+  guideId: string;
+  messages: ChatMessage[];
+  forcedSkill?: SkillResponseTypeType;
+  fetchImpl: typeof globalThis.fetch;
+  signal?: AbortSignal;
+}
+
+/** Raw SSE frame as written by the API's `toSSE` adapter. */
+interface SSEFrame {
+  type: string;
+  name?: string;
+  value?: Record<string, unknown>;
+  delta?: string;
+  messageId?: string;
+  role?: string;
+  runId?: string;
+  finishReason?: string;
+  error?: { message: string; code?: string };
+}
+
+const DATA_PREFIX = "data:";
+const DONE_SENTINEL = "[DONE]";
+
+/**
+ * Stream a guide chat turn. POSTs the conversation to the SSE route
+ * (`/api/v3/guide/conversation`) and yields normalized {@link GuideStreamEvent}s
+ * until the server writes `data: [DONE]`. This is the one endpoint that is not
+ * part of the typed oRPC router, so it is spoken by hand here.
+ */
+export async function* streamConversation(params: StreamConversationParams): AsyncGenerator<GuideStreamEvent> {
+  const { apiBaseUrl, guideId, messages, forcedSkill, fetchImpl, signal } = params;
+
+  const body: Record<string, unknown> = {
+    guideId,
+    messages: messages.map((m) => ({ role: m.role, content: m.content })),
+  };
+  if (forcedSkill) body.forcedSkill = forcedSkill;
+
+  const response = await fetchImpl(`${apiBaseUrl}/guide/conversation`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    credentials: "include",
+    body: JSON.stringify(body),
+    signal,
+  });
+
+  if (!response.ok || !response.body) {
+    throw new Error(`[brand_brain] Conversation request failed with status ${response.status}`);
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      let separatorIndex = buffer.indexOf("\n\n");
+      while (separatorIndex !== -1) {
+        const rawEvent = buffer.slice(0, separatorIndex);
+        buffer = buffer.slice(separatorIndex + 2);
+        separatorIndex = buffer.indexOf("\n\n");
+
+        const dataLine = rawEvent.split("\n").find((line) => line.startsWith(DATA_PREFIX));
+        if (!dataLine) continue;
+
+        const data = dataLine.slice(DATA_PREFIX.length).trim();
+        if (data === DONE_SENTINEL) return;
+
+        const mapped = mapFrame(JSON.parse(data) as SSEFrame);
+        if (mapped) yield mapped;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function mapFrame(frame: SSEFrame): GuideStreamEvent | null {
+  switch (frame.type) {
+    case SSEMessageType.RunStarted:
+      return { type: "run-started", runId: frame.runId ?? "" };
+    case SSEMessageType.RunFinished:
+      return { type: "run-finished", finishReason: frame.finishReason };
+    case SSEMessageType.RunError:
+      return { type: "error", message: frame.error?.message ?? "Unknown error", code: frame.error?.code };
+    case SSEMessageType.TextMessageStart:
+      return { type: "message-start", messageId: frame.messageId ?? "", role: frame.role ?? "assistant" };
+    case SSEMessageType.TextMessageContent:
+      return { type: "text", messageId: frame.messageId ?? "", delta: frame.delta ?? "" };
+    case SSEMessageType.TextMessageEnd:
+      return { type: "message-end", messageId: frame.messageId ?? "" };
+    case SSEMessageType.Custom:
+      return mapCustomFrame(frame);
+    default:
+      return null;
+  }
+}
+
+function mapCustomFrame(frame: SSEFrame): GuideStreamEvent | null {
+  if (!frame.name) return null;
+  const value = frame.value ?? {};
+
+  // Wire-boundary reads: `value` is untyped JSON from the SSE stream, so the
+  // fields below are asserted against the shapes the API's toSSE adapter writes.
+  if (frame.name === GuideEvent.SkillGate) {
+    return {
+      type: "gate",
+      skill: value.skill as SkillResponseTypeType,
+      prompt: value.prompt as string | undefined,
+      skillInstanceId: value.skillInstanceId as string | undefined,
+    };
+  }
+  if (frame.name === GuideEvent.SkillError) {
+    return {
+      type: "error",
+      message: (value.message as string | undefined) ?? "Skill error",
+      code: value.errorType as string | undefined,
+    };
+  }
+  return { type: "skill", name: frame.name as GuideEventName, value };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { GuideClient, initGuide } from "./GuideClient";
+export * from "./types";

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export { useGuide } from "./useGuide";
+export type { UseGuideResult } from "./useGuide";

package/src/react/useGuide.ts

@@ -0,0 +1,101 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { initGuide, type GuideClient } from "../GuideClient";
+import type { AskOptions, ChatMessage, InitGuideConfig, ResolvedGuide } from "../types";
+
+export interface UseGuideResult {
+  /** The client once bootstrapped, else `null`. */
+  client: GuideClient | null;
+  /** Resolved guide metadata once ready, else `null`. */
+  guide: ResolvedGuide | null;
+  /** Conversation history, kept in sync with the client. */
+  messages: ChatMessage[];
+  /** `true` once the client has finished initializing. */
+  isReady: boolean;
+  /** `true` while a reply is streaming. */
+  isStreaming: boolean;
+  /** Init or stream error, else `null`. */
+  error: Error | null;
+  /** Send a message and stream the reply into `messages`. */
+  ask: (message: string, options?: AskOptions) => Promise<void>;
+  /** Clear the in-memory conversation. */
+  reset: () => void;
+}
+
+/**
+ * React binding over {@link initGuide}. Bootstraps once per `baseUrl`+`slug`,
+ * mirrors the streamed reply into state, and ends the session on unmount —
+ * encapsulating the streaming/cleanup patterns so generated UIs stay correct.
+ */
+export function useGuide(config: InitGuideConfig): UseGuideResult {
+  const [client, setClient] = useState<GuideClient | null>(null);
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const { baseUrl, slug } = config;
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  useEffect(() => {
+    let active = true;
+    let created: GuideClient | null = null;
+
+    void initGuide(configRef.current)
+      .then((instance) => {
+        if (!active) {
+          void instance.endSession();
+          return;
+        }
+        created = instance;
+        setClient(instance);
+        setError(null);
+      })
+      .catch((err: unknown) => {
+        if (active) setError(err instanceof Error ? err : new Error(String(err)));
+      });
+
+    return () => {
+      active = false;
+      void created?.endSession();
+    };
+  }, [baseUrl, slug]);
+
+  const ask = useCallback(
+    async (message: string, options?: AskOptions) => {
+      if (!client) return;
+      setIsStreaming(true);
+      setError(null);
+      try {
+        for await (const event of client.ask(message, options)) {
+          if (event.type === "text" || event.type === "message-start") {
+            setMessages([...client.messages]);
+          }
+        }
+        setMessages([...client.messages]);
+      } catch (err: unknown) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      } finally {
+        setIsStreaming(false);
+      }
+    },
+    [client],
+  );
+
+  const reset = useCallback(() => {
+    client?.reset();
+    setMessages([]);
+  }, [client]);
+
+  return {
+    client,
+    guide: client?.guide ?? null,
+    messages,
+    isReady: client !== null,
+    isStreaming,
+    error,
+    ask,
+    reset,
+  };
+}