@frankieai/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties, ButtonHTMLAttributes, HTMLAttributes, TextareaHTMLAttributes } from 'react';
+import { PublicWidgetConfig, CreateSessionResponse, 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';
+import { ClassValue } from 'clsx';
+
+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.
+ */
+declare const FRANKIE_CLOUD_URL = "https://frankie-data-gq5o5syq2q-uc.a.run.app";
+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;
+}
+declare class FrankieApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+declare class FrankieClient {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly doFetch;
+    private session?;
+    constructor(options: FrankieClientOptions);
+    get sessionId(): 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. */
+    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. */
+    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;
+        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 {
+    client: FrankieClient;
+    config?: PublicWidgetConfig;
+    configError?: string;
+    loading: boolean;
+    context?: PageContext;
+    theme?: WidgetTheme;
+}
+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 {
+    id: string;
+    name: string;
+    label: string;
+    status: "running" | "done" | "failed" | "denied";
+    detail?: string;
+}
+interface UserChatMessage {
+    id: string;
+    role: "user";
+    text: string;
+    createdAt: number;
+}
+interface AssistantChatMessage {
+    id: string;
+    role: "assistant";
+    text: string;
+    thinking: string;
+    tools: ToolActivity[];
+    status: "streaming" | "done" | "error";
+    error?: string;
+    createdAt: number;
+}
+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.
+ */
+declare function applyEvent(message: AssistantChatMessage, event: FrankieServerEvent): AssistantChatMessage;
+declare function newAssistantMessage(id: string): AssistantChatMessage;
+declare function newUserMessage(id: string, text: string): UserChatMessage;
+
+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;
+}
+declare function useFrankieChat(): UseFrankieChatResult;
+
+interface ChatPanelProps {
+    className?: string;
+    /** Replace the header entirely, or pass `false` to drop it. */
+    header?: ReactNode | false;
+    /** Rendered under the composer — good for a "powered by" or a privacy note. */
+    footer?: ReactNode;
+    /** Shown before the first message, in place of the default greeting block. */
+    emptyState?: ReactNode;
+    /** Take over message rendering completely. */
+    renderMessage?: (message: ChatMessage) => ReactNode;
+    /** Take over the tool-activity rows. */
+    renderTool?: (tool: ToolActivity) => ReactNode;
+    placeholder?: string;
+    /** Shows a close button in the header when provided. */
+    onClose?: () => void;
+    autoFocus?: boolean;
+    /** Fill the parent instead of the fixed floating size — for full-page use. */
+    fill?: boolean;
+}
+declare function ChatPanel({ className, header, footer, emptyState, renderMessage, renderTool, placeholder, onClose, autoFocus, fill, }: ChatPanelProps): react.JSX.Element;
+
+interface FrankieWidgetProps extends ChatPanelProps {
+    position?: "bottom-right" | "bottom-left";
+    /** Distance from the viewport edges, in pixels. */
+    offset?: number;
+    defaultOpen?: boolean;
+    /** Controlled mode: pass both to drive open state from the host app. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Replace the floating launcher button. */
+    renderLauncher?: (props: {
+        open: boolean;
+        toggle: () => void;
+        label: string;
+    }) => React.ReactNode;
+}
+/**
+ * The drop-in embed: a floating launcher plus the chat panel.
+ *
+ * Renders `position: fixed` at the document level, so it does not care what
+ * layout the host page uses.
+ */
+declare function FrankieWidget({ position, offset, defaultOpen, open: controlledOpen, onOpenChange, renderLauncher, ...panelProps }: FrankieWidgetProps): react.JSX.Element;
+
+interface FrankieInlineProps extends ChatPanelProps {
+    /** Extra styles on the filling wrapper — e.g. a `maxWidth` to centre the column. */
+    style?: CSSProperties;
+}
+/**
+ * Full-page (or any-container) chat: the panel fills its parent instead of
+ * floating in a corner. Drop it into a route or a sized element — it brings its
+ * own theme root, so it styles correctly wherever it lands.
+ *
+ *   <div style={{ height: "100dvh" }}>
+ *     <FrankieProvider …><FrankieInline /></FrankieProvider>
+ *   </div>
+ */
+declare function FrankieInline({ className, style, ...panelProps }: FrankieInlineProps): react.JSX.Element;
+
+interface ComposerProps {
+    onSend: (text: string) => void;
+    onStop: () => void;
+    busy: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    autoFocus?: boolean;
+}
+declare function Composer({ onSend, onStop, busy, placeholder, disabled, autoFocus }: ComposerProps): react.JSX.Element;
+
+interface MessageBubbleProps {
+    message: ChatMessage;
+    assistantName: string;
+    avatarUrl?: string;
+    showToolActivity: boolean;
+    renderTool?: (tool: ToolActivity) => ReactNode;
+}
+declare function MessageBubble({ message, assistantName, avatarUrl, showToolActivity, renderTool, }: MessageBubbleProps): react.JSX.Element;
+declare function TypingDots(): react.JSX.Element;
+
+/**
+ * A deliberately small Markdown subset — paragraphs, lists, fenced code, bold,
+ * italic, inline code and links.
+ *
+ * Everything is rendered as React elements; nothing goes through
+ * `dangerouslySetInnerHTML`. Model output lands in someone else's production
+ * page, so it is never trusted as markup.
+ */
+declare function Markdown({ text, className }: {
+    text: string;
+    className?: string;
+}): react.JSX.Element;
+
+declare function SuggestedPrompts({ prompts, onPick, disabled, }: {
+    prompts: string[];
+    onPick: (prompt: string) => void;
+    disabled?: boolean;
+}): react.JSX.Element | null;
+
+interface ToolActivityListProps {
+    tools: ToolActivity[];
+    /** Replace the default row rendering entirely. */
+    renderTool?: (tool: ToolActivity) => React.ReactNode;
+}
+/** The "what the assistant is doing" strip under a streaming answer. */
+declare function ToolActivityList({ tools, renderTool }: ToolActivityListProps): react.JSX.Element | null;
+declare function ToolActivityRow({ tool }: {
+    tool: ToolActivity;
+}): react.JSX.Element;
+
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "default" | "secondary" | "outline" | "ghost" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+declare function Button({ className, variant, size, asChild, ...props }: ButtonProps): react.JSX.Element;
+
+declare const badgeVariants: (props?: ({
+    variant?: "default" | "outline" | "success" | "danger" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Badge({ className, variant, ...props }: HTMLAttributes<HTMLSpanElement> & VariantProps<typeof badgeVariants>): react.JSX.Element;
+
+interface AvatarProps {
+    src?: string;
+    name: string;
+    className?: string;
+}
+/** Image avatar with an initials fallback — no image request when `src` is absent. */
+declare function Avatar({ src, name, className }: AvatarProps): react.JSX.Element;
+
+declare function Card({ className, ...props }: HTMLAttributes<HTMLDivElement>): react.JSX.Element;
+declare function CardHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>): react.JSX.Element;
+declare function CardTitle({ className, ...props }: HTMLAttributes<HTMLDivElement>): react.JSX.Element;
+declare function CardDescription({ className, ...props }: HTMLAttributes<HTMLDivElement>): react.JSX.Element;
+declare function CardContent({ className, ...props }: HTMLAttributes<HTMLDivElement>): react.JSX.Element;
+declare function CardFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>): react.JSX.Element;
+
+/**
+ * A plain overflow container rather than Radix's ScrollArea: the widget lives
+ * inside someone else's page, and a native scroller inherits their scrollbar
+ * behaviour instead of fighting it.
+ */
+declare const ScrollArea: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+
+declare function Separator({ className }: {
+    className?: string;
+}): react.JSX.Element;
+
+/** `forwardRef` rather than React 19's ref-as-prop, so React 18 hosts work too. */
+declare const Textarea: react.ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & react.RefAttributes<HTMLTextAreaElement>>;
+
+/**
+ * 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.
+ */
+declare function themeToCssVars(theme: WidgetTheme | undefined): CSSProperties;
+/** Resolve `mode: "system"` against the browser, so the widget can hard-set a class. */
+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 };