@frankieai/react 0.1.0 → 0.1.4

package/src/index.ts

@@ -1,12 +1,14 @@
 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 type { UseFrankieChatResult, SendOptions } 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 { FrankieChatPage } from "./components/chat/FrankieChatPage.js";
+export type { FrankieChatPageProps } from "./components/chat/FrankieChatPage.js";
 export { ChatPanel } from "./components/chat/ChatPanel.js";
 export type { ChatPanelProps } from "./components/chat/ChatPanel.js";
 export { Composer } from "./components/chat/Composer.js";
@@ -27,7 +29,7 @@ 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 type { AssistantChatMessage, ChatMessage, MessageAttachment, ToolActivity, UserChatMessage } from "./lib/messages.js";
 export { resolveMode, themeToCssVars } from "./lib/theme.js";
 export { cn } from "./lib/utils.js";
 

package/src/lib/client.ts

@@ -1,4 +1,5 @@
 import type {
+  ChatAttachment,
   ChatRequestBody,
   CreateSessionResponse,
   FrankieServerEvent,
@@ -31,6 +32,17 @@ export interface FrankieClientOptions {
    * set false for an ephemeral chat that starts fresh every load.
    */
   persist?: boolean;
+  /** Override localStorage namespace for session and transcript. */
+  storageNamespace?: string;
+  /** Stable id for a server-backed conversation. */
+  conversationId?: string;
+}
+
+export interface ChatConversation {
+  id: string;
+  title: string;
+  createdAt: number;
+  updatedAt: number;
 }
 
 export class FrankieApiError extends Error {
@@ -58,14 +70,18 @@ export class FrankieClient {
     return this.session?.sessionId;
   }
 
+  get conversationId(): string | undefined {
+    return this.options.conversationId;
+  }
+
   /** 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. */
+  /** localStorage namespace for this tenant/conversation, shared with the chat hook. */
   get namespace(): string {
-    return `frankie.${this.options.publishableKey}`;
+    return this.options.storageNamespace ?? `frankie.${this.options.publishableKey}`;
   }
 
   private readStored(): CreateSessionResponse | undefined {
@@ -74,7 +90,6 @@ export class FrankieClient {
       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;
@@ -99,34 +114,95 @@ export class FrankieClient {
     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;
-    }
+    if (this.session && new Date(this.session.expiresAt).getTime() > Date.now() + 30_000) return this.session;
     const userToken = await this.options.getUserToken?.();
+    if (this.options.getUserToken && !userToken) {
+      throw new FrankieApiError(
+        "Your signed-in Frankie session could not be verified. Refresh the page and sign in again.",
+        401,
+        "user_token_unavailable",
+      );
+    }
     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 } : {}) }),
+      body: JSON.stringify({
+        ...(userToken ? { userToken } : {}),
+        ...(context ? { context } : {}),
+        ...(this.options.conversationId ? { conversationId: this.options.conversationId } : {}),
+      }),
     });
     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. */
+  async listConversations(): Promise<ChatConversation[]> {
+    const userToken = await this.requireUserToken();
+    const response = await this.doFetch(`${this.baseUrl}/v1/conversations`, {
+      headers: { "x-frankie-key": this.options.publishableKey, authorization: `Bearer ${userToken}` },
+    });
+    const body = (await this.unwrap(response)) as { conversations?: ChatConversation[] };
+    return Array.isArray(body.conversations) ? body.conversations : [];
+  }
+
+  async resumeConversation(id = this.options.conversationId): Promise<{ messages: unknown[]; title: string } | undefined> {
+    if (!id) return undefined;
+    const userToken = await this.requireUserToken();
+    const response = await this.doFetch(`${this.baseUrl}/v1/conversations/${encodeURIComponent(id)}/resume`, {
+      method: "POST",
+      headers: { "x-frankie-key": this.options.publishableKey, authorization: `Bearer ${userToken}` },
+    });
+    if (response.status === 404) return undefined;
+    const body = (await this.unwrap(response)) as { session: CreateSessionResponse; messages?: unknown[]; title?: string };
+    this.session = body.session;
+    this.writeStored();
+    return { messages: Array.isArray(body.messages) ? body.messages : [], title: body.title ?? "New chat" };
+  }
+
+  async syncConversation(messages: unknown[], title?: string): Promise<void> {
+    if (!this.session || !this.options.conversationId) return;
+    const response = await this.doFetch(`${this.baseUrl}/v1/conversations/${encodeURIComponent(this.options.conversationId)}`, {
+      method: "PUT",
+      headers: {
+        "content-type": "application/json",
+        "x-frankie-key": this.options.publishableKey,
+        authorization: `Bearer ${this.session.sessionToken}`,
+      },
+      body: JSON.stringify({ messages, ...(title ? { title } : {}) }),
+    });
+    await this.unwrap(response);
+  }
+
+  async deleteConversation(id: string): Promise<void> {
+    const userToken = await this.requireUserToken();
+    const response = await this.doFetch(`${this.baseUrl}/v1/conversations/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+      headers: { "x-frankie-key": this.options.publishableKey, authorization: `Bearer ${userToken}` },
+    });
+    if (response.status !== 404) await this.unwrap(response);
+  }
+
+  private async requireUserToken(): Promise<string> {
+    const token = await this.options.getUserToken?.();
+    if (!token) throw new FrankieApiError("Sign in to access your chat history.", 401, "unauthorized");
+    return token;
+  }
+
   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 },
+    input: {
+      message: string;
+      context?: PageContext;
+      model?: string;
+      attachments?: ChatAttachment[];
+      signal?: AbortSignal;
+    },
     onEvent: (event: FrankieServerEvent) => void,
   ): Promise<void> {
     const session = await this.ensureSession(input.context);
@@ -134,6 +210,8 @@ export class FrankieClient {
       sessionId: session.sessionId,
       message: input.message,
       ...(input.context ? { context: input.context } : {}),
+      ...(input.model ? { model: input.model } : {}),
+      ...(input.attachments?.length ? { attachments: input.attachments } : {}),
     };
 
     const response = await this.doFetch(`${this.baseUrl}/v1/chat`, {
@@ -148,7 +226,6 @@ export class FrankieClient {
     });
 
     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;
@@ -174,7 +251,6 @@ export class FrankieClient {
   }
 }
 
-/** Parse the server's `data:`-only SSE stream into typed events. */
 export async function* readEventStream(
   body: ReadableStream<Uint8Array>,
 ): AsyncGenerator<FrankieServerEvent> {

package/src/lib/messages.ts

@@ -8,10 +8,17 @@ export interface ToolActivity {
   detail?: string;
 }
 
+/** A file shown on a user message (name/type only — the bytes aren't kept in the transcript). */
+export interface MessageAttachment {
+  name: string;
+  mimeType: string;
+}
+
 export interface UserChatMessage {
   id: string;
   role: "user";
   text: string;
+  attachments?: MessageAttachment[];
   createdAt: number;
 }
 
@@ -116,6 +123,6 @@ 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() };
+export function newUserMessage(id: string, text: string, attachments?: MessageAttachment[]): UserChatMessage {
+  return { id, role: "user", text, ...(attachments?.length ? { attachments } : {}), createdAt: Date.now() };
 }

package/src/styles/frankie.css

@@ -7,15 +7,23 @@
  * a CSS variable scoped to `.frankie-root`, so a host can restyle the widget
  * without touching this file.
  *
- * Hosts that already run Tailwind v4 can skip this file entirely and instead
- * add `@source "../node_modules/@frankieai/react/dist";` to their own CSS: the
- * widget then compiles against their design tokens.
+ * This stylesheet is self-contained. Widget utilities are compiled ahead of
+ * time and prefixed with `.frankie-root`, so they cannot style the host app.
  */
 
 @layer theme, components, utilities;
 
 @import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/utilities.css" layer(utilities) source(none);
+
+/*
+ * The widget is embedded inside arbitrary applications. Native CSS scoping
+ * keeps Tailwind's generated utilities inside the widget instead of relying on
+ * Tailwind's invalid selector-important import syntax (which made the whole
+ * utility layer disappear in production).
+ */
+@scope (.frankie-root) {
+  @tailwind utilities;
+}
 
 @source "../";
 

package/src/widget.test.tsx

@@ -16,6 +16,10 @@ const config: PublicWidgetConfig = {
   theme: { mode: "light" },
   allowAnonymous: true,
   showToolActivity: true,
+  features: {
+    attachments: { enabled: false, accept: ["image/*"], maxMb: 10, maxCount: 4 },
+    modelPicker: { enabled: false, models: [] },
+  },
 };
 
 function sseStream(events: FrankieServerEvent[]): ReadableStream<Uint8Array> {