@frankieai/react 0.1.0

package/src/hooks/useFrankieChat.ts

@@ -0,0 +1,148 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { FrankieApiError } from "../lib/client.js";
+import {
+  applyEvent,
+  newAssistantMessage,
+  newUserMessage,
+  type AssistantChatMessage,
+  type ChatMessage,
+} from "../lib/messages.js";
+import { useFrankie } from "./FrankieProvider.jsx";
+
+export interface UseFrankieChatResult {
+  messages: ChatMessage[];
+  /** True from the moment a message is sent until the turn ends. */
+  busy: boolean;
+  /** Set when the turn failed outright (network, auth, rate limit). */
+  error?: string;
+  send: (text: string) => Promise<void>;
+  /** Abort the in-flight turn. The partial answer stays in the transcript. */
+  stop: () => void;
+  /** Clear the transcript and start a brand-new server session. */
+  reset: () => void;
+}
+
+let counter = 0;
+const nextId = (prefix: string) => `${prefix}_${Date.now().toString(36)}_${(counter += 1)}`;
+
+export function useFrankieChat(): UseFrankieChatResult {
+  const { client, context } = useFrankie();
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | undefined>(undefined);
+  const abortRef = useRef<AbortController | null>(null);
+  const mounted = useRef(true);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      abortRef.current?.abort();
+    };
+  }, []);
+
+  const storageKey = `${client.namespace}.messages`;
+
+  // Restore the transcript on mount, so a page reload keeps the conversation.
+  // The client resumes the matching server session, so context is kept too.
+  useEffect(() => {
+    if (!client.persist) return;
+    try {
+      const raw = window.localStorage.getItem(storageKey);
+      const stored = raw ? (JSON.parse(raw) as ChatMessage[]) : [];
+      if (Array.isArray(stored) && stored.length) setMessages(stored);
+    } catch {
+      /* storage unavailable; start empty */
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [storageKey]);
+
+  // Persist once a turn settles — never mid-stream — so the saved copy is clean.
+  useEffect(() => {
+    if (!client.persist || busy) return;
+    try {
+      if (messages.length) window.localStorage.setItem(storageKey, JSON.stringify(messages));
+      else window.localStorage.removeItem(storageKey);
+    } catch {
+      /* ignore */
+    }
+  }, [messages, busy, client, storageKey]);
+
+  const patchAssistant = useCallback((id: string, update: (m: AssistantChatMessage) => AssistantChatMessage) => {
+    setMessages((current) =>
+      current.map((message) =>
+        message.id === id && message.role === "assistant" ? update(message) : message,
+      ),
+    );
+  }, []);
+
+  const send = useCallback(
+    async (text: string) => {
+      const trimmed = text.trim();
+      if (!trimmed || busy) return;
+
+      const assistantId = nextId("a");
+      setError(undefined);
+      setBusy(true);
+      setMessages((current) => [
+        ...current,
+        newUserMessage(nextId("u"), trimmed),
+        newAssistantMessage(assistantId),
+      ]);
+
+      const abort = new AbortController();
+      abortRef.current = abort;
+
+      try {
+        await client.send({ message: trimmed, ...(context ? { context } : {}), signal: abort.signal }, (event) => {
+          if (event.type === "ping" || event.type === "session") return;
+          patchAssistant(assistantId, (message) => applyEvent(message, event));
+        });
+      } catch (caught) {
+        if (abort.signal.aborted) {
+          patchAssistant(assistantId, (message) => ({
+            ...message,
+            status: "done",
+            text: message.text || "Stopped.",
+          }));
+        } else {
+          const message =
+            caught instanceof FrankieApiError
+              ? caught.message
+              : "Could not reach the assistant. Check your connection and try again.";
+          if (mounted.current) setError(message);
+          patchAssistant(assistantId, (current) => ({ ...current, status: "error", error: message }));
+        }
+      } finally {
+        if (mounted.current) {
+          setBusy(false);
+          // A turn that ended without a `turn_end` event still has to settle.
+          patchAssistant(assistantId, (message) =>
+            message.status === "streaming" ? { ...message, status: "done" } : message,
+          );
+        }
+        abortRef.current = null;
+      }
+    },
+    [busy, client, context, patchAssistant],
+  );
+
+  const stop = useCallback(() => abortRef.current?.abort(), []);
+
+  const reset = useCallback(() => {
+    abortRef.current?.abort();
+    client.resetSession();
+    setMessages([]);
+    setError(undefined);
+    setBusy(false);
+    try {
+      if (client.persist) window.localStorage.removeItem(`${client.namespace}.messages`);
+    } catch {
+      /* ignore */
+    }
+  }, [client]);
+
+  return { messages, busy, ...(error ? { error } : {}), send, stop, reset };
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+export { FrankieProvider, useFrankie, useFrankieTheme } from "./hooks/FrankieProvider.jsx";
+export type { FrankieProviderProps } from "./hooks/FrankieProvider.jsx";
+export { useFrankieChat } from "./hooks/useFrankieChat.js";
+export type { UseFrankieChatResult } from "./hooks/useFrankieChat.js";
+
+export { FrankieWidget } from "./components/chat/FrankieWidget.js";
+export type { FrankieWidgetProps } from "./components/chat/FrankieWidget.js";
+export { FrankieInline } from "./components/chat/FrankieInline.js";
+export type { FrankieInlineProps } from "./components/chat/FrankieInline.js";
+export { ChatPanel } from "./components/chat/ChatPanel.js";
+export type { ChatPanelProps } from "./components/chat/ChatPanel.js";
+export { Composer } from "./components/chat/Composer.js";
+export { MessageBubble, TypingDots } from "./components/chat/MessageBubble.js";
+export { Markdown } from "./components/chat/Markdown.js";
+export { SuggestedPrompts } from "./components/chat/SuggestedPrompts.js";
+export { ToolActivityList, ToolActivityRow } from "./components/chat/ToolActivityList.js";
+
+export { Button, buttonVariants } from "./components/ui/button.js";
+export type { ButtonProps } from "./components/ui/button.js";
+export { Badge } from "./components/ui/badge.js";
+export { Avatar } from "./components/ui/avatar.js";
+export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "./components/ui/card.js";
+export { ScrollArea } from "./components/ui/scroll-area.js";
+export { Separator } from "./components/ui/separator.js";
+export { Textarea } from "./components/ui/textarea.js";
+
+export { FrankieClient, FrankieApiError, readEventStream, FRANKIE_CLOUD_URL } from "./lib/client.js";
+export type { FrankieClientOptions, PageContext } from "./lib/client.js";
+export { applyEvent, newAssistantMessage, newUserMessage } from "./lib/messages.js";
+export type { AssistantChatMessage, ChatMessage, ToolActivity, UserChatMessage } from "./lib/messages.js";
+export { resolveMode, themeToCssVars } from "./lib/theme.js";
+export { cn } from "./lib/utils.js";
+
+export type { PublicWidgetConfig, WidgetTheme, FrankieServerEvent } from "@frankieai/core";

package/src/lib/client.ts

@@ -0,0 +1,217 @@
+import type {
+  ChatRequestBody,
+  CreateSessionResponse,
+  FrankieServerEvent,
+  PublicWidgetConfig,
+} from "@frankieai/core";
+
+export type PageContext = Record<string, string | number | boolean | null>;
+
+/**
+ * The hosted Frankie data plane. Embedding needs only a publishable key, so
+ * `baseUrl` defaults here — override it only when self-hosting the server.
+ */
+export const FRANKIE_CLOUD_URL = "https://frankie-data-gq5o5syq2q-uc.a.run.app";
+
+export interface FrankieClientOptions {
+  /** Where the Frankie server is mounted. Defaults to the hosted cloud. */
+  baseUrl?: string;
+  /** Safe to ship to the browser; the origin allowlist is what authorises it. */
+  publishableKey: string;
+  /**
+   * Fetches a short-lived JWT for the signed-in user from the host's own
+   * backend. Called once per session, and again when a session expires.
+   * Omit only for tenants that allow anonymous chat.
+   */
+  getUserToken?: () => Promise<string | undefined> | string | undefined;
+  fetchImpl?: typeof fetch;
+  /**
+   * Remember the session (and, in the hook, the transcript) in localStorage so a
+   * page reload resumes the same conversation. On by default in the browser;
+   * set false for an ephemeral chat that starts fresh every load.
+   */
+  persist?: boolean;
+}
+
+export class FrankieApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code: string,
+  ) {
+    super(message);
+  }
+}
+
+export class FrankieClient {
+  private readonly baseUrl: string;
+  private readonly doFetch: typeof fetch;
+  private session?: CreateSessionResponse;
+
+  constructor(private readonly options: FrankieClientOptions) {
+    this.baseUrl = (options.baseUrl ?? FRANKIE_CLOUD_URL).replace(/\/+$/, "");
+    this.doFetch = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.session = this.readStored();
+  }
+
+  get sessionId(): string | undefined {
+    return this.session?.sessionId;
+  }
+
+  /** Whether this client persists across reloads (browser only, opt-out via `persist:false`). */
+  get persist(): boolean {
+    return this.options.persist !== false && typeof window !== "undefined";
+  }
+
+  /** localStorage namespace for this tenant, shared with the chat hook. */
+  get namespace(): string {
+    return `frankie.${this.options.publishableKey}`;
+  }
+
+  private readStored(): CreateSessionResponse | undefined {
+    if (!this.persist) return undefined;
+    try {
+      const raw = window.localStorage.getItem(`${this.namespace}.session`);
+      if (!raw) return undefined;
+      const session = JSON.parse(raw) as CreateSessionResponse;
+      // A stored session past its expiry is useless; drop it.
+      return new Date(session.expiresAt).getTime() > Date.now() + 30_000 ? session : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private writeStored(): void {
+    if (!this.persist) return;
+    try {
+      if (this.session) window.localStorage.setItem(`${this.namespace}.session`, JSON.stringify(this.session));
+      else window.localStorage.removeItem(`${this.namespace}.session`);
+    } catch {
+      /* storage may be unavailable (private mode); the chat still works in memory */
+    }
+  }
+
+  async getConfig(signal?: AbortSignal): Promise<PublicWidgetConfig> {
+    const response = await this.doFetch(`${this.baseUrl}/v1/config`, {
+      headers: { "x-frankie-key": this.options.publishableKey },
+      ...(signal ? { signal } : {}),
+    });
+    return (await this.unwrap(response)) as PublicWidgetConfig;
+  }
+
+  /** Opens (or reuses) a chat session. */
+  async ensureSession(context?: PageContext): Promise<CreateSessionResponse> {
+    if (this.session && new Date(this.session.expiresAt).getTime() > Date.now() + 30_000) {
+      return this.session;
+    }
+    const userToken = await this.options.getUserToken?.();
+    const response = await this.doFetch(`${this.baseUrl}/v1/session`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-frankie-key": this.options.publishableKey },
+      body: JSON.stringify({ ...(userToken ? { userToken } : {}), ...(context ? { context } : {}) }),
+    });
+    this.session = (await this.unwrap(response)) as CreateSessionResponse;
+    this.writeStored();
+    return this.session;
+  }
+
+  /** Forget the current session so the next send starts a fresh conversation. */
+  resetSession(): void {
+    this.session = undefined;
+    this.writeStored();
+  }
+
+  /**
+   * Sends a message and invokes `onEvent` for each server event as it arrives.
+   * Resolves when the turn ends.
+   */
+  async send(
+    input: { message: string; context?: PageContext; signal?: AbortSignal },
+    onEvent: (event: FrankieServerEvent) => void,
+  ): Promise<void> {
+    const session = await this.ensureSession(input.context);
+    const body: ChatRequestBody = {
+      sessionId: session.sessionId,
+      message: input.message,
+      ...(input.context ? { context: input.context } : {}),
+    };
+
+    const response = await this.doFetch(`${this.baseUrl}/v1/chat`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-frankie-key": this.options.publishableKey,
+        authorization: `Bearer ${session.sessionToken}`,
+      },
+      body: JSON.stringify(body),
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+
+    if (!response.ok || !response.body) {
+      // A dropped session is recoverable: clear it so the next send re-auths.
+      if (response.status === 401 || response.status === 404) this.resetSession();
+      await this.unwrap(response);
+      return;
+    }
+
+    for await (const event of readEventStream(response.body)) {
+      onEvent(event);
+    }
+  }
+
+  private async unwrap(response: Response): Promise<unknown> {
+    if (response.ok) return response.json();
+    let code = "internal";
+    let message = `Request failed with status ${response.status}.`;
+    try {
+      const body = (await response.json()) as { error?: { code?: string; message?: string } };
+      code = body.error?.code ?? code;
+      message = body.error?.message ?? message;
+    } catch {
+      /* keep the default message */
+    }
+    throw new FrankieApiError(message, response.status, code);
+  }
+}
+
+/** Parse the server's `data:`-only SSE stream into typed events. */
+export async function* readEventStream(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<FrankieServerEvent> {
+  const reader = 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 split = buffer.indexOf("\n\n");
+      while (split !== -1) {
+        const frame = buffer.slice(0, split);
+        buffer = buffer.slice(split + 2);
+        const event = parseFrame(frame);
+        if (event) yield event;
+        split = buffer.indexOf("\n\n");
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function parseFrame(frame: string): FrankieServerEvent | null {
+  const data = frame
+    .split("\n")
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => line.slice(5).replace(/^ /, ""))
+    .join("\n");
+  if (!data) return null;
+  try {
+    return JSON.parse(data) as FrankieServerEvent;
+  } catch {
+    return null;
+  }
+}

package/src/lib/messages.ts

@@ -0,0 +1,121 @@
+import type { FrankieServerEvent } from "@frankieai/core";
+
+export interface ToolActivity {
+  id: string;
+  name: string;
+  label: string;
+  status: "running" | "done" | "failed" | "denied";
+  detail?: string;
+}
+
+export interface UserChatMessage {
+  id: string;
+  role: "user";
+  text: string;
+  createdAt: number;
+}
+
+export interface AssistantChatMessage {
+  id: string;
+  role: "assistant";
+  text: string;
+  thinking: string;
+  tools: ToolActivity[];
+  status: "streaming" | "done" | "error";
+  error?: string;
+  createdAt: number;
+}
+
+export type ChatMessage = UserChatMessage | AssistantChatMessage;
+
+/**
+ * Fold one server event into the assistant message being built.
+ *
+ * Kept pure and separate from React so the streaming logic is testable without
+ * a DOM, and so a host writing its own UI can reuse it.
+ */
+export function applyEvent(message: AssistantChatMessage, event: FrankieServerEvent): AssistantChatMessage {
+  switch (event.type) {
+    case "text_delta":
+      return { ...message, text: message.text + event.text };
+
+    case "thinking_delta":
+      return { ...message, thinking: message.thinking + event.text };
+
+    case "tool_start":
+      return {
+        ...message,
+        tools: [
+          ...message.tools,
+          { id: event.toolUseId, name: event.name, label: event.label, status: "running" },
+        ],
+      };
+
+    case "tool_end":
+      return {
+        ...message,
+        tools: message.tools.map((tool) =>
+          tool.id === event.toolUseId
+            ? {
+                ...tool,
+                status: event.ok ? "done" : "failed",
+                ...(event.preview ? { detail: event.preview } : {}),
+              }
+            : tool,
+        ),
+      };
+
+    case "tool_denied":
+      return {
+        ...message,
+        tools: upsertTool(message.tools, {
+          id: event.toolUseId,
+          name: event.name,
+          label: event.name,
+          status: "denied",
+          detail: event.reason,
+        }),
+      };
+
+    case "turn_end":
+      return {
+        ...message,
+        status: message.status === "error" ? "error" : "done",
+        // A turn that produced nothing still needs to say something.
+        text: message.text || fallbackText(event.stopReason),
+      };
+
+    case "error":
+      return { ...message, status: "error", error: event.message };
+
+    default:
+      return message;
+  }
+}
+
+function upsertTool(tools: ToolActivity[], next: ToolActivity): ToolActivity[] {
+  return tools.some((tool) => tool.id === next.id)
+    ? tools.map((tool) => (tool.id === next.id ? { ...tool, ...next } : tool))
+    : [...tools, next];
+}
+
+function fallbackText(stopReason: string): string {
+  switch (stopReason) {
+    case "max_turns":
+      return "I got stuck working on that. Could you narrow it down a little?";
+    case "aborted":
+      return "Stopped.";
+    case "error":
+      return "Something went wrong before I could answer. Try again?";
+    default:
+      return "";
+  }
+}
+
+export function newAssistantMessage(id: string): AssistantChatMessage {
+  return { id, role: "assistant", text: "", thinking: "", tools: [], status: "streaming", createdAt: Date.now() };
+}
+
+export function newUserMessage(id: string, text: string): UserChatMessage {
+  return { id, role: "user", text, createdAt: Date.now() };
+}

package/src/lib/theme.ts

@@ -0,0 +1,30 @@
+import type { WidgetTheme } from "@frankieai/core";
+import type { CSSProperties } from "react";
+
+/**
+ * Map a theme to the CSS custom properties the widget's styles read.
+ *
+ * Anything not set falls through to the defaults in `frankie.css`, which are
+ * themselves shadcn/ui token names — so a host that already runs shadcn can
+ * drop the stylesheet and the widget inherits their design system instead.
+ */
+export function themeToCssVars(theme: WidgetTheme | undefined): CSSProperties {
+  if (!theme) return {};
+  const vars: Record<string, string> = {};
+  if (theme.primary) vars["--frankie-primary"] = theme.primary;
+  if (theme.primaryForeground) vars["--frankie-primary-foreground"] = theme.primaryForeground;
+  if (theme.background) vars["--frankie-background"] = theme.background;
+  if (theme.foreground) vars["--frankie-foreground"] = theme.foreground;
+  if (theme.muted) vars["--frankie-muted"] = theme.muted;
+  if (theme.border) vars["--frankie-border"] = theme.border;
+  if (theme.radius) vars["--frankie-radius"] = `${theme.radius}rem`;
+  if (theme.fontFamily) vars["--frankie-font"] = theme.fontFamily;
+  return vars as CSSProperties;
+}
+
+/** Resolve `mode: "system"` against the browser, so the widget can hard-set a class. */
+export function resolveMode(mode: WidgetTheme["mode"]): "light" | "dark" {
+  if (mode === "light" || mode === "dark") return mode;
+  if (typeof window === "undefined" || !window.matchMedia) return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}

package/src/lib/utils.ts

@@ -0,0 +1,7 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/** shadcn/ui's class helper: conditional classes with Tailwind conflict resolution. */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}