@frankieai/react 0.1.0 → 0.1.4

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes, TextareaHTMLAttributes } from 'react';
-import { PublicWidgetConfig, CreateSessionResponse, FrankieServerEvent, WidgetTheme } from '@frankieai/core';
+import { PublicWidgetConfig, CreateSessionResponse, ChatAttachment, FrankieServerEvent, WidgetTheme } from '@frankieai/core';
 export { FrankieServerEvent, PublicWidgetConfig, WidgetTheme } from '@frankieai/core';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
@@ -30,6 +30,16 @@ 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;
+}
+interface ChatConversation {
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
 }
 declare class FrankieApiError extends Error {
     readonly status: number;
@@ -43,41 +53,39 @@ declare class FrankieClient {
     private session?;
     constructor(options: FrankieClientOptions);
     get sessionId(): string | undefined;
+    get conversationId(): string | undefined;
     /** Whether this client persists across reloads (browser only, opt-out via `persist:false`). */
     get persist(): boolean;
-    /** localStorage namespace for this tenant, shared with the chat hook. */
+    /** localStorage namespace for this tenant/conversation, shared with the chat hook. */
     get namespace(): string;
     private readStored;
     private writeStored;
     getConfig(signal?: AbortSignal): Promise<PublicWidgetConfig>;
-    /** Opens (or reuses) a chat session. */
     ensureSession(context?: PageContext): Promise<CreateSessionResponse>;
-    /** Forget the current session so the next send starts a fresh conversation. */
+    listConversations(): Promise<ChatConversation[]>;
+    resumeConversation(id?: string | undefined): Promise<{
+        messages: unknown[];
+        title: string;
+    } | undefined>;
+    syncConversation(messages: unknown[], title?: string): Promise<void>;
+    deleteConversation(id: string): Promise<void>;
+    private requireUserToken;
     resetSession(): void;
-    /**
-     * Sends a message and invokes `onEvent` for each server event as it arrives.
-     * Resolves when the turn ends.
-     */
     send(input: {
         message: string;
         context?: PageContext;
+        model?: string;
+        attachments?: ChatAttachment[];
         signal?: AbortSignal;
     }, onEvent: (event: FrankieServerEvent) => void): Promise<void>;
     private unwrap;
 }
-/** Parse the server's `data:`-only SSE stream into typed events. */
 declare function readEventStream(body: ReadableStream<Uint8Array>): AsyncGenerator<FrankieServerEvent>;
 
 interface FrankieProviderProps extends FrankieClientOptions {
     children: ReactNode;
-    /**
-     * Page context sent with every turn — current route, plan tier, whatever the
-     * agent should know. Treated as data by the server, never as instructions.
-     */
     context?: PageContext;
-    /** Overrides for the server-side theme, so a host can restyle without a redeploy. */
     theme?: WidgetTheme;
-    /** Skip the `/v1/config` fetch by supplying the config yourself. */
     config?: PublicWidgetConfig;
 }
 interface FrankieContextValue {
@@ -90,7 +98,6 @@ interface FrankieContextValue {
 }
 declare function FrankieProvider({ children, context, theme, config: providedConfig, ...clientOptions }: FrankieProviderProps): react.JSX.Element;
 declare function useFrankie(): FrankieContextValue;
-/** The theme actually in effect: provider override wins over server config. */
 declare function useFrankieTheme(): WidgetTheme | undefined;
 
 interface ToolActivity {
@@ -100,10 +107,16 @@ interface ToolActivity {
     status: "running" | "done" | "failed" | "denied";
     detail?: string;
 }
+/** A file shown on a user message (name/type only — the bytes aren't kept in the transcript). */
+interface MessageAttachment {
+    name: string;
+    mimeType: string;
+}
 interface UserChatMessage {
     id: string;
     role: "user";
     text: string;
+    attachments?: MessageAttachment[];
     createdAt: number;
 }
 interface AssistantChatMessage {
@@ -125,15 +138,20 @@ type ChatMessage = UserChatMessage | AssistantChatMessage;
  */
 declare function applyEvent(message: AssistantChatMessage, event: FrankieServerEvent): AssistantChatMessage;
 declare function newAssistantMessage(id: string): AssistantChatMessage;
-declare function newUserMessage(id: string, text: string): UserChatMessage;
+declare function newUserMessage(id: string, text: string, attachments?: MessageAttachment[]): UserChatMessage;
 
+/** Extra inputs a turn can carry: attached files and a chosen model. */
+interface SendOptions {
+    attachments?: ChatAttachment[];
+    model?: string;
+}
 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>;
+    send: (text: string, opts?: SendOptions) => 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. */
@@ -200,15 +218,47 @@ interface FrankieInlineProps extends ChatPanelProps {
  */
 declare function FrankieInline({ className, style, ...panelProps }: FrankieInlineProps): react.JSX.Element;
 
+/**
+ * A complete chat route in one component. This is the simplest way to add a
+ * dedicated /chat page to an app while keeping the existing floating widget.
+ */
+interface FrankieChatPageProps extends Omit<FrankieProviderProps, "children">, Pick<ChatPanelProps, "header" | "footer" | "emptyState" | "renderMessage" | "renderTool" | "placeholder" | "autoFocus"> {
+    className?: string;
+    style?: CSSProperties;
+}
+declare function FrankieChatPage({ className, style, header, footer, emptyState, renderMessage, renderTool, placeholder, autoFocus, ...providerProps }: FrankieChatPageProps): react.JSX.Element;
+
+interface ComposerAttachmentsConfig {
+    enabled: boolean;
+    /** Accepted MIME patterns, e.g. "image/*". */
+    accept: string[];
+    maxCount: number;
+    maxMb: number;
+}
+interface ComposerModelPicker {
+    models: {
+        id: string;
+        label: string;
+    }[];
+    value?: string;
+    onChange: (id: string) => void;
+}
 interface ComposerProps {
-    onSend: (text: string) => void;
+    onSend: (text: string, opts?: {
+        attachments?: ChatAttachment[];
+        model?: string;
+    }) => void;
     onStop: () => void;
     busy: boolean;
     placeholder?: string;
     disabled?: boolean;
     autoFocus?: boolean;
+    /** Enables the attach button when provided and `enabled`. */
+    attachments?: ComposerAttachmentsConfig;
+    /** Enables a model dropdown when provided with at least one model. */
+    modelPicker?: ComposerModelPicker;
 }
-declare function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus }: ComposerProps): react.JSX.Element;
+declare function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus, attachments, modelPicker }: ComposerProps): react.JSX.Element;
 
 interface MessageBubbleProps {
     message: ChatMessage;
@@ -307,4 +357,4 @@ declare function resolveMode(mode: WidgetTheme["mode"]): "light" | "dark";
 /** shadcn/ui's class helper: conditional classes with Tailwind conflict resolution. */
 declare function cn(...inputs: ClassValue[]): string;
 
-export { type AssistantChatMessage, Avatar, Badge, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ChatMessage, ChatPanel, type ChatPanelProps, Composer, FRANKIE_CLOUD_URL, FrankieApiError, FrankieClient, type FrankieClientOptions, FrankieInline, type FrankieInlineProps, FrankieProvider, type FrankieProviderProps, FrankieWidget, type FrankieWidgetProps, Markdown, MessageBubble, type PageContext, ScrollArea, Separator, SuggestedPrompts, Textarea, type ToolActivity, ToolActivityList, ToolActivityRow, TypingDots, type UseFrankieChatResult, type UserChatMessage, applyEvent, buttonVariants, cn, newAssistantMessage, newUserMessage, readEventStream, resolveMode, themeToCssVars, useFrankie, useFrankieChat, useFrankieTheme };
+export { type AssistantChatMessage, Avatar, Badge, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ChatMessage, ChatPanel, type ChatPanelProps, Composer, FRANKIE_CLOUD_URL, FrankieApiError, FrankieChatPage, type FrankieChatPageProps, FrankieClient, type FrankieClientOptions, FrankieInline, type FrankieInlineProps, FrankieProvider, type FrankieProviderProps, FrankieWidget, type FrankieWidgetProps, Markdown, type MessageAttachment, MessageBubble, type PageContext, ScrollArea, type SendOptions, Separator, SuggestedPrompts, Textarea, type ToolActivity, ToolActivityList, ToolActivityRow, TypingDots, type UseFrankieChatResult, type UserChatMessage, applyEvent, buttonVariants, cn, newAssistantMessage, newUserMessage, readEventStream, resolveMode, themeToCssVars, useFrankie, useFrankieChat, useFrankieTheme };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes, TextareaHTMLAttributes } from 'react';
-import { PublicWidgetConfig, CreateSessionResponse, FrankieServerEvent, WidgetTheme } from '@frankieai/core';
+import { PublicWidgetConfig, CreateSessionResponse, ChatAttachment, FrankieServerEvent, WidgetTheme } from '@frankieai/core';
 export { FrankieServerEvent, PublicWidgetConfig, WidgetTheme } from '@frankieai/core';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
@@ -30,6 +30,16 @@ 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;
+}
+interface ChatConversation {
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
 }
 declare class FrankieApiError extends Error {
     readonly status: number;
@@ -43,41 +53,39 @@ declare class FrankieClient {
     private session?;
     constructor(options: FrankieClientOptions);
     get sessionId(): string | undefined;
+    get conversationId(): string | undefined;
     /** Whether this client persists across reloads (browser only, opt-out via `persist:false`). */
     get persist(): boolean;
-    /** localStorage namespace for this tenant, shared with the chat hook. */
+    /** localStorage namespace for this tenant/conversation, shared with the chat hook. */
     get namespace(): string;
     private readStored;
     private writeStored;
     getConfig(signal?: AbortSignal): Promise<PublicWidgetConfig>;
-    /** Opens (or reuses) a chat session. */
     ensureSession(context?: PageContext): Promise<CreateSessionResponse>;
-    /** Forget the current session so the next send starts a fresh conversation. */
+    listConversations(): Promise<ChatConversation[]>;
+    resumeConversation(id?: string | undefined): Promise<{
+        messages: unknown[];
+        title: string;
+    } | undefined>;
+    syncConversation(messages: unknown[], title?: string): Promise<void>;
+    deleteConversation(id: string): Promise<void>;
+    private requireUserToken;
     resetSession(): void;
-    /**
-     * Sends a message and invokes `onEvent` for each server event as it arrives.
-     * Resolves when the turn ends.
-     */
     send(input: {
         message: string;
         context?: PageContext;
+        model?: string;
+        attachments?: ChatAttachment[];
         signal?: AbortSignal;
     }, onEvent: (event: FrankieServerEvent) => void): Promise<void>;
     private unwrap;
 }
-/** Parse the server's `data:`-only SSE stream into typed events. */
 declare function readEventStream(body: ReadableStream<Uint8Array>): AsyncGenerator<FrankieServerEvent>;
 
 interface FrankieProviderProps extends FrankieClientOptions {
     children: ReactNode;
-    /**
-     * Page context sent with every turn — current route, plan tier, whatever the
-     * agent should know. Treated as data by the server, never as instructions.
-     */
     context?: PageContext;
-    /** Overrides for the server-side theme, so a host can restyle without a redeploy. */
     theme?: WidgetTheme;
-    /** Skip the `/v1/config` fetch by supplying the config yourself. */
     config?: PublicWidgetConfig;
 }
 interface FrankieContextValue {
@@ -90,7 +98,6 @@ interface FrankieContextValue {
 }
 declare function FrankieProvider({ children, context, theme, config: providedConfig, ...clientOptions }: FrankieProviderProps): react.JSX.Element;
 declare function useFrankie(): FrankieContextValue;
-/** The theme actually in effect: provider override wins over server config. */
 declare function useFrankieTheme(): WidgetTheme | undefined;
 
 interface ToolActivity {
@@ -100,10 +107,16 @@ interface ToolActivity {
     status: "running" | "done" | "failed" | "denied";
     detail?: string;
 }
+/** A file shown on a user message (name/type only — the bytes aren't kept in the transcript). */
+interface MessageAttachment {
+    name: string;
+    mimeType: string;
+}
 interface UserChatMessage {
     id: string;
     role: "user";
     text: string;
+    attachments?: MessageAttachment[];
     createdAt: number;
 }
 interface AssistantChatMessage {
@@ -125,15 +138,20 @@ type ChatMessage = UserChatMessage | AssistantChatMessage;
  */
 declare function applyEvent(message: AssistantChatMessage, event: FrankieServerEvent): AssistantChatMessage;
 declare function newAssistantMessage(id: string): AssistantChatMessage;
-declare function newUserMessage(id: string, text: string): UserChatMessage;
+declare function newUserMessage(id: string, text: string, attachments?: MessageAttachment[]): UserChatMessage;
 
+/** Extra inputs a turn can carry: attached files and a chosen model. */
+interface SendOptions {
+    attachments?: ChatAttachment[];
+    model?: string;
+}
 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>;
+    send: (text: string, opts?: SendOptions) => 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. */
@@ -200,15 +218,47 @@ interface FrankieInlineProps extends ChatPanelProps {
  */
 declare function FrankieInline({ className, style, ...panelProps }: FrankieInlineProps): react.JSX.Element;
 
+/**
+ * A complete chat route in one component. This is the simplest way to add a
+ * dedicated /chat page to an app while keeping the existing floating widget.
+ */
+interface FrankieChatPageProps extends Omit<FrankieProviderProps, "children">, Pick<ChatPanelProps, "header" | "footer" | "emptyState" | "renderMessage" | "renderTool" | "placeholder" | "autoFocus"> {
+    className?: string;
+    style?: CSSProperties;
+}
+declare function FrankieChatPage({ className, style, header, footer, emptyState, renderMessage, renderTool, placeholder, autoFocus, ...providerProps }: FrankieChatPageProps): react.JSX.Element;
+
+interface ComposerAttachmentsConfig {
+    enabled: boolean;
+    /** Accepted MIME patterns, e.g. "image/*". */
+    accept: string[];
+    maxCount: number;
+    maxMb: number;
+}
+interface ComposerModelPicker {
+    models: {
+        id: string;
+        label: string;
+    }[];
+    value?: string;
+    onChange: (id: string) => void;
+}
 interface ComposerProps {
-    onSend: (text: string) => void;
+    onSend: (text: string, opts?: {
+        attachments?: ChatAttachment[];
+        model?: string;
+    }) => void;
     onStop: () => void;
     busy: boolean;
     placeholder?: string;
     disabled?: boolean;
     autoFocus?: boolean;
+    /** Enables the attach button when provided and `enabled`. */
+    attachments?: ComposerAttachmentsConfig;
+    /** Enables a model dropdown when provided with at least one model. */
+    modelPicker?: ComposerModelPicker;
 }
-declare function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus }: ComposerProps): react.JSX.Element;
+declare function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus, attachments, modelPicker }: ComposerProps): react.JSX.Element;
 
 interface MessageBubbleProps {
     message: ChatMessage;
@@ -307,4 +357,4 @@ declare function resolveMode(mode: WidgetTheme["mode"]): "light" | "dark";
 /** shadcn/ui's class helper: conditional classes with Tailwind conflict resolution. */
 declare function cn(...inputs: ClassValue[]): string;
 
-export { type AssistantChatMessage, Avatar, Badge, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ChatMessage, ChatPanel, type ChatPanelProps, Composer, FRANKIE_CLOUD_URL, FrankieApiError, FrankieClient, type FrankieClientOptions, FrankieInline, type FrankieInlineProps, FrankieProvider, type FrankieProviderProps, FrankieWidget, type FrankieWidgetProps, Markdown, MessageBubble, type PageContext, ScrollArea, Separator, SuggestedPrompts, Textarea, type ToolActivity, ToolActivityList, ToolActivityRow, TypingDots, type UseFrankieChatResult, type UserChatMessage, applyEvent, buttonVariants, cn, newAssistantMessage, newUserMessage, readEventStream, resolveMode, themeToCssVars, useFrankie, useFrankieChat, useFrankieTheme };
+export { type AssistantChatMessage, Avatar, Badge, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type ChatMessage, ChatPanel, type ChatPanelProps, Composer, FRANKIE_CLOUD_URL, FrankieApiError, FrankieChatPage, type FrankieChatPageProps, FrankieClient, type FrankieClientOptions, FrankieInline, type FrankieInlineProps, FrankieProvider, type FrankieProviderProps, FrankieWidget, type FrankieWidgetProps, Markdown, type MessageAttachment, MessageBubble, type PageContext, ScrollArea, type SendOptions, Separator, SuggestedPrompts, Textarea, type ToolActivity, ToolActivityList, ToolActivityRow, TypingDots, type UseFrankieChatResult, type UserChatMessage, applyEvent, buttonVariants, cn, newAssistantMessage, newUserMessage, readEventStream, resolveMode, themeToCssVars, useFrankie, useFrankieChat, useFrankieTheme };