@bikdotai/bik-component-library 0.0.856 → 0.0.857-beta.0

package/dist/esm/components/bik-copilot/model.d.ts

@@ -0,0 +1,674 @@
+import { CSSProperties, ReactNode, PointerEvent as ReactPointerEvent } from 'react';
+import { ChatMessage, IceBreaker } from '../bik-chatbot/types';
+/**
+ * Corner of the viewport the ball is parked in before the user drags it.
+ */
+export type CopilotCorner = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+/**
+ * Absolute viewport coordinates (px) of the ball's top-left corner.
+ */
+export interface CopilotBallPosition {
+    x: number;
+    y: number;
+}
+/**
+ * Viewport size the ball and panel are positioned against.
+ */
+export interface CopilotViewport {
+    width: number;
+    height: number;
+}
+/**
+ * Presentation and behaviour props shared by every copilot entry point.
+ */
+export interface CopilotShellProps {
+    /**
+     * Diameter of the draggable ball in px.
+     * @default 56
+     */
+    ballSize?: number;
+    /**
+     * Viewport corner the ball starts in. Ignored when `initialPosition` is set.
+     * @default 'bottom-right'
+     */
+    corner?: CopilotCorner;
+    /**
+     * Distance in px kept between the ball and the viewport edges it is parked
+     * against.
+     * @default 24
+     */
+    offset?: number;
+    /**
+     * Exact starting coordinates of the ball's top-left corner. Takes precedence
+     * over `corner` and is clamped into the viewport.
+     */
+    initialPosition?: CopilotBallPosition;
+    /**
+     * Allows the user to drag the ball anywhere in the viewport. When `false` the
+     * ball stays parked and only acts as a button.
+     * @default true
+     */
+    draggable?: boolean;
+    /**
+     * Animates the ball back to the nearest left/right edge after a drag ends,
+     * keeping the vertical position the user chose.
+     * @default true
+     */
+    snapToEdge?: boolean;
+    /** Fired after a drag gesture settles, with the ball's final position. */
+    onPositionChange?: (position: CopilotBallPosition) => void;
+    /** Icon rendered inside the ball while the panel is closed. */
+    ballIcon?: ReactNode;
+    /** Icon rendered inside the ball while the panel is open. */
+    ballOpenIcon?: ReactNode;
+    /**
+     * Background of the ball. Accepts any CSS background value, so gradients work.
+     * @default COLORS.background.brand
+     */
+    ballColor?: string;
+    /**
+     * Stacking order for both the ball and the panel.
+     * @default 1200
+     */
+    zIndex?: number;
+    /** Accessible label announced for the ball. */
+    ballAriaLabel?: string;
+    /**
+     * Panel width in px. Shrinks automatically on narrow viewports.
+     * @default 380
+     */
+    panelWidth?: number;
+    /**
+     * Panel height in px. Shrinks automatically on short viewports.
+     * @default 540
+     */
+    panelHeight?: number;
+    /**
+     * Gap in px between the ball and the panel.
+     * @default 12
+     */
+    panelGap?: number;
+    /**
+     * Title shown in the panel header.
+     * @default 'Copilot'
+     */
+    title?: string;
+    /** Optional pill rendered next to the title, e.g. `"New"`. */
+    badge?: string;
+    /** Secondary line rendered under the title. */
+    subtitle?: string;
+    /** Custom node rendered as the header avatar. */
+    avatar?: ReactNode;
+    /**
+     * Placeholder for the message input.
+     * @default 'Write your message...'
+     */
+    placeholder?: string;
+    /**
+     * Fine print rendered under the input. Pass an empty string to hide it.
+     * @default 'AI can make mistakes, Verify the responses.'
+     */
+    disclaimer?: string;
+    /**
+     * Headline of the empty state shown before the first message.
+     * @default the `title` value
+     */
+    emptyStateTitle?: string;
+    /**
+     * Sub-headline of the empty state shown before the first message.
+     * @default 'Here are some things you can try'
+     */
+    emptyStateSubtitle?: string;
+    /**
+     * Quick-start prompts shown in the empty state. Clicking one sends it as a
+     * user message.
+     */
+    suggestions?: IceBreaker[];
+    /** Fired when a suggestion is clicked, before the message is sent. */
+    onSuggestionClick?: (suggestion: IceBreaker) => void;
+    /**
+     * Shows the reset button in the header. Only rendered when `onRefresh` is
+     * also provided.
+     * @default true
+     */
+    showRefresh?: boolean;
+    /** Fired when the header reset button is clicked. */
+    onRefresh?: () => void;
+    /**
+     * Disables the input and suggestions without hiding them.
+     * @default false
+     */
+    inputDisabled?: boolean;
+    /**
+     * Label rendered beside the animated dots while a reply is pending. Pass an
+     * empty string for dots only.
+     * @default 'Thinking'
+     */
+    thinkingLabel?: string;
+    /**
+     * Note shown in place of — or under — a reply the reader stopped. Pass an
+     * empty string to hide it.
+     * @default 'This message was interrupted'
+     */
+    interruptedLabel?: string;
+    /**
+     * Caption above the follow-up chips the backend suggests. Pass an empty
+     * string to show the chips with no caption.
+     * @default 'Follow ups'
+     */
+    followUpsLabel?: string;
+    /**
+     * Caption shown above the transcript while an older page is being fetched.
+     * @default 'Loading earlier messages'
+     */
+    historyLoadingLabel?: string;
+    /**
+     * Controls the panel from the outside. When set, the component stops managing
+     * its own open state and `onOpenChange` must apply the change.
+     */
+    open?: boolean;
+    /**
+     * Whether the panel starts open. Ignored when `open` is provided.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Fired whenever the panel is opened or closed. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Closes the panel when the user clicks anywhere outside it.
+     * @default false
+     */
+    closeOnClickOutside?: boolean;
+    /** Class applied to the panel. */
+    className?: string;
+    /** Inline styles merged onto the panel. */
+    style?: CSSProperties;
+}
+/**
+ * Props for the fully controlled copilot: the host owns the transcript and the
+ * send handler, so it works with any backend.
+ */
+export interface ControlledCopilotProps extends CopilotShellProps {
+    /** Conversation rendered in the panel, oldest message first. */
+    messages: CopilotMessage[];
+    /** Called with the trimmed message text when the user sends or picks a suggestion. */
+    onSendMessage: (message: string) => void;
+    /**
+     * Renders the thinking indicator and blocks sending while a reply is pending.
+     * @default false
+     */
+    isThinking?: boolean;
+    /**
+     * True for the whole turn, from send until the answer is complete. Turns the
+     * send button into a stop button while `onStop` is provided.
+     * @default false
+     */
+    isStreaming?: boolean;
+    /**
+     * Called when the reader presses stop. Without it the button stays a send
+     * button, since there would be nothing to stop.
+     */
+    onStop?: () => void;
+    /**
+     * Offers older messages when the reader scrolls to the top. Without
+     * `onLoadOlderMessages` nothing is requested, however this is set.
+     * @default false
+     */
+    hasMoreHistory?: boolean;
+    /** Shows the loading row above the transcript. @default false */
+    isLoadingHistory?: boolean;
+    /**
+     * Called when the reader scrolls to the top and there is more history. Fires
+     * on scroll, so the handler must tolerate being called again while a page is
+     * already on its way.
+     */
+    onLoadOlderMessages?: () => void;
+    /** Error banner rendered above the input. */
+    errorMessage?: string;
+}
+/**
+ * Agents the merchant agent factory can resolve. The backend validates this
+ * against its own enum and rejects anything else, so a new agent has to be added
+ * here and there.
+ */
+export type CopilotAgent = 'BIK_ASSISTANT_AGENT';
+/**
+ * One SSE payload from `/bik-ai/copilot-chatbot`.
+ *
+ * The endpoint sends `data: {json}` frames with no `event:` name — `type` is the
+ * discriminator. `STOP` is never a frame: the server ends the HTTP stream
+ * instead, so completion is "the stream closed".
+ */
+/**
+ * Structured `content` of a `TEXT` event. `STREAM` and `ERROR` still carry a
+ * bare string, and so did `TEXT` before the backend wrapped it, so both shapes
+ * have to be read — see `readCopilotEventContent`.
+ */
+export interface CopilotAnswerPayload {
+    /** `'ANSWER'` today. Unknown kinds are read for their `message` all the same. */
+    type?: string;
+    /** The reply itself, as markdown. */
+    message?: string;
+    /** Suggested next prompts, rendered as chips under the reply. */
+    followUps?: string[];
+}
+export interface CopilotStreamEvent {
+    /**
+     * `STREAM` for an incremental chunk, `TEXT` for the final full message,
+     * `ERROR` when the turn failed. `TOOL_STATUS` is reserved by the backend but
+     * not emitted yet.
+     */
+    type: 'STREAM' | 'TEXT' | 'ERROR' | 'TOOL_STATUS' | string;
+    /**
+     * Chunk text on `STREAM`, the complete answer on `TEXT`, the reason on
+     * `ERROR`. `TEXT` wraps it in a `CopilotAnswerPayload`.
+     */
+    content?: string | CopilotAnswerPayload;
+    /** Server-side id of the message being streamed; stable across its chunks. */
+    messageId?: string;
+    /**
+     * OpenAI's response id, present on `TEXT` only. Echo it back as
+     * `previousResponseId` next turn to keep the thread's context. Absent when
+     * the turn broke halfway — the backend drops the thread on purpose then.
+     */
+    responseId?: string;
+    storeId?: string;
+    sessionId?: string;
+}
+/** Body of one streaming copilot turn. */
+export interface CopilotStreamRequest {
+    storeId: string;
+    agent: CopilotAgent;
+    /** Dashboard route the merchant is on, e.g. `'campaigns/overview'`. */
+    route: string;
+    userPrompt: string;
+    sessionId: string;
+    /** Signed-in merchant user, sent as `email`. Omitted when the host has none. */
+    email?: string;
+    /** Omitted on the first turn, then the previous turn's `responseId`. */
+    previousResponseId?: string;
+    /** Overrides the agent's server-side system prompt. */
+    systemPrompt?: string;
+    model?: string;
+    maxOutputTokens?: number;
+}
+/** How to reach the endpoint. */
+export interface CopilotTransportOptions {
+    /** Origin of the AI backend, e.g. `'http://localhost:5001'`. */
+    baseUrl: string;
+    /**
+     * Path appended to `baseUrl`.
+     * @default '/bik-ai/copilot-chatbot'
+     */
+    endpointPath?: string;
+    /**
+     * Extra headers merged into the request — this is where `bik-referer` goes.
+     */
+    headers?: Record<string, string>;
+    /** Value of the `authorization` header. */
+    authToken?: string;
+    /**
+     * Resolves the `authorization` header per request. Prefer this over
+     * `authToken` when the token can be refreshed, since it is read on every turn.
+     */
+    getAuthToken?: () => string | Promise<string>;
+    /** Injectable `fetch`, for tests and for hosts with their own instrumentation. */
+    fetchImpl?: typeof fetch;
+}
+export type StreamCopilotChatOptions = CopilotStreamRequest & CopilotTransportOptions;
+/** Options for `fetchCopilotIcebreakers`. */
+export interface FetchCopilotIcebreakersOptions extends Omit<CopilotTransportOptions, 'endpointPath'> {
+    /**
+     * Path appended to `baseUrl`.
+     * @default '/bik-ai/copilot-icebreakers'
+     */
+    endpointPath?: string;
+    agent: CopilotAgent;
+    route: string;
+    /** Sent as `store_id`. Not used to resolve prompts today, but accepted. */
+    storeId?: string;
+    signal?: AbortSignal;
+}
+/** What the ice-breaker endpoint answers with. */
+export interface CopilotIcebreakersResult {
+    agent: string;
+    /** The route the backend actually matched, normalized. */
+    route: string;
+    /** Human-readable page name behind the matched route, when it has one. */
+    pageName?: string;
+    /** Empty when no knowledge file covers the route — a valid answer. */
+    icebreakers: string[];
+}
+/** Options for `useCopilotIcebreakers`. */
+export interface UseCopilotIcebreakersOptions extends Omit<CopilotTransportOptions, 'endpointPath'> {
+    /**
+     * Path appended to `baseUrl`.
+     * @default '/bik-ai/copilot-icebreakers'
+     */
+    icebreakersPath?: string;
+    /**
+     * @default 'BIK_ASSISTANT_AGENT'
+     */
+    agent?: CopilotAgent;
+    /**
+     * @default 'campaigns/overview'
+     */
+    route?: string;
+    storeId?: string;
+    /**
+     * Gates the request. The copilot passes `false` until the panel has been
+     * opened, so a merchant who never opens it costs no call.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/** Return value of `useCopilotIcebreakers`. */
+export interface UseCopilotIcebreakersResult {
+    /** Prompts as the panel wants them, ready for `suggestions`. */
+    icebreakers: IceBreaker[];
+    /** Page name behind the matched route, when the backend supplied one. */
+    pageName?: string;
+    /** The normalized route the backend matched. */
+    matchedRoute?: string;
+    isLoading: boolean;
+    /** Set when the request failed. An empty result is not an error. */
+    error?: string;
+    /** Refetches for the current agent + route. */
+    refresh: () => void;
+}
+/** Callbacks driven by `streamCopilotChat`. */
+export interface CopilotStreamHandlers {
+    onEvent: (event: CopilotStreamEvent) => void;
+    /** The server closed the stream — the turn is done. */
+    onComplete?: () => void;
+    onError?: (error: Error) => void;
+    onAbort?: () => void;
+}
+/** A chat message, plus the streaming state the copilot needs. */
+export interface CopilotMessage extends ChatMessage {
+    /** True while this assistant bubble is still being streamed into. */
+    isStreaming?: boolean;
+    /** `messageId` of the stream events that produced this bubble. */
+    messageId?: string;
+    /**
+     * True when the reader stopped this turn before the answer finished. Survives
+     * a reload, so the transcript still says the reply is incomplete.
+     */
+    wasInterrupted?: boolean;
+    /**
+     * Prompts the backend suggests as the next question. Only the newest reply's
+     * are offered — older ones stay in the transcript but are not rendered.
+     */
+    followUps?: string[];
+}
+/**
+ * One row of `/bik-ai/copilot-messages`, as the backend serializes it. Mapped
+ * onto `CopilotMessage` by `fetchCopilotMessages`.
+ */
+export interface CopilotStoredMessageRow {
+    message_id?: string;
+    session_id?: string;
+    /** Page the merchant was on when they sent the prompt, normalized. */
+    route?: string | null;
+    agent?: string | null;
+    /** Who sent it. Read case-insensitively, so the enum can grow. */
+    owner?: string;
+    message?: string;
+    /**
+     * When the row was created. Declared as epoch millis, but real responses have
+     * also carried a numeric string or an ISO timestamp, so readers coerce it
+     * rather than trust the number — see `fetchCopilotMessages`.
+     */
+    created_at?: number | string;
+    /** Staff member the turn belongs to; null on older rows. */
+    email?: string | null;
+}
+/** One page of server-side history, newest page first. */
+export interface CopilotMessagesPage {
+    /** Oldest first within the page, so it can be prepended as-is. */
+    messages: CopilotMessage[];
+    page: number;
+    pageSize: number;
+    /** False once there is nothing older left to fetch. */
+    hasMore: boolean;
+}
+/** Options for `fetchCopilotMessages`. */
+export interface FetchCopilotMessagesOptions extends Omit<CopilotTransportOptions, 'endpointPath'> {
+    /**
+     * Path appended to `baseUrl`.
+     * @default '/bik-ai/copilot-messages'
+     */
+    endpointPath?: string;
+    storeId: string;
+    sessionId: string;
+    /** 1 is the newest page; 2 is the 20 before that. @default 1 */
+    page?: number;
+    /** @default 20, which is also the cap on what IndexedDB keeps. */
+    pageSize?: number;
+    signal?: AbortSignal;
+}
+/** What is persisted in IndexedDB for one conversation. */
+export interface CopilotSessionRecord {
+    sessionId: string;
+    createdAt: number;
+    updatedAt: number;
+    /**
+     * When this record stops being readable: last write + 24h, restamped on every
+     * write. Absent on records written before the TTL existed, which are read as
+     * `updatedAt + 24h`.
+     */
+    expiresAt?: number;
+    messages: CopilotMessage[];
+    /** Last `responseId` seen, so a reload can continue the same OpenAI thread. */
+    previousResponseId?: string;
+    storeId?: string;
+    agent?: string;
+    route?: string;
+}
+/** Options for `useCopilotStreamChat`. */
+export interface UseCopilotStreamChatOptions extends CopilotTransportOptions {
+    storeId: string;
+    /**
+     * @default 'BIK_ASSISTANT_AGENT'
+     */
+    agent?: CopilotAgent;
+    /**
+     * Route the merchant is on; sent every turn, so it can change
+     * mid-conversation. The backend resolves the turn's page knowledge from it, so
+     * the default is a placeholder to replace with the real route.
+     * @default 'campaigns/overview'
+     */
+    route?: string;
+    /**
+     * Signed-in merchant user, sent with every turn as `email`. Left out of the
+     * body entirely when the host has no email to give.
+     */
+    email?: string;
+    /**
+     * Path of the stored-history endpoint, appended to `baseUrl`.
+     * @default '/bik-ai/copilot-messages'
+     */
+    messagesPath?: string;
+    /**
+     * Reads older messages back from `/bik-ai/copilot-messages` — page 1 when
+     * nothing is cached locally, and the page before that each time the reader
+     * scrolls to the top. Turn it off to keep the copilot on local history alone.
+     * @default true
+     */
+    loadHistory?: boolean;
+    systemPrompt?: string;
+    model?: string;
+    maxOutputTokens?: number;
+    /**
+     * Pins the conversation to a session id. Omit it and the hook restores the
+     * last session from IndexedDB, or creates one on first use.
+     */
+    sessionId?: string;
+    /**
+     * Persists the transcript and the thread's `responseId` to IndexedDB.
+     * @default true
+     */
+    persist?: boolean;
+    /** Fired when a turn fails. The message is also surfaced in `error`. */
+    onError?: (error: Error) => void;
+    /** Fired once a turn's final `TEXT` event has arrived. */
+    onResponseComplete?: (payload: {
+        text: string;
+        responseId?: string;
+        followUps?: string[];
+    }) => void;
+    /** Fired when the active session id changes, including on restore. */
+    onSessionIdChange?: (sessionId: string) => void;
+}
+/** Return value of `useCopilotStreamChat`. */
+export interface UseCopilotStreamChatResult {
+    messages: CopilotMessage[];
+    /** `null` until the session has been restored or created. */
+    sessionId: string | null;
+    /** Id threaded into the next turn to keep OpenAI's context. */
+    previousResponseId?: string;
+    /** True from send until the stream closes. */
+    isStreaming: boolean;
+    /** True while waiting for the first chunk — what drives the thinking bubble. */
+    isThinking: boolean;
+    /** True while the transcript is being read back from IndexedDB. */
+    isRestoring: boolean;
+    /** True while an older page of history is on its way. */
+    isLoadingHistory: boolean;
+    /** False once the endpoint reports there is nothing older left. */
+    hasMoreHistory: boolean;
+    error?: string;
+    sendMessage: (message: string) => void;
+    /**
+     * Fetches the page before the oldest message on screen and prepends it. Safe
+     * to call on every scroll event: it no-ops while a page is in flight and once
+     * the history runs out.
+     */
+    loadOlderMessages: () => void;
+    /** Aborts the in-flight turn, keeping whatever text already arrived. */
+    stopStreaming: () => void;
+    /** Starts a fresh session id, clearing the transcript and the thread. */
+    startNewConversation: () => void;
+}
+/**
+ * Props for the copilot wired to the streaming `/bik-ai/copilot-chatbot`
+ * endpoint, with IndexedDB-backed history and route-aware ice breakers.
+ */
+export interface BIKCopilotProps extends CopilotShellProps, UseCopilotStreamChatOptions {
+    /**
+     * Path of the ice-breaker endpoint, appended to `baseUrl`.
+     * @default '/bik-ai/copilot-icebreakers'
+     */
+    icebreakersPath?: string;
+    /**
+     * Loads the route's suggested prompts from `/bik-ai/copilot-icebreakers` and
+     * shows them in the empty state. The request only fires once the panel has
+     * been opened. Passing `suggestions` explicitly wins over whatever is fetched.
+     * @default true
+     */
+    loadIcebreakers?: boolean;
+}
+/**
+ * Props of the presentational panel. Rendered by `ControlledCopilot`, exported so a
+ * host can build its own shell around it.
+ */
+export interface CopilotPanelProps {
+    messages: CopilotMessage[];
+    onSend: (message: string) => void;
+    onClose: () => void;
+    title?: string;
+    badge?: string;
+    subtitle?: string;
+    avatar?: ReactNode;
+    placeholder?: string;
+    disclaimer?: string;
+    emptyStateTitle?: string;
+    emptyStateSubtitle?: string;
+    suggestions?: IceBreaker[];
+    onSuggestionClick?: (suggestion: IceBreaker) => void;
+    showRefresh?: boolean;
+    onRefresh?: () => void;
+    isThinking?: boolean;
+    thinkingLabel?: string;
+    isStreaming?: boolean;
+    onStop?: () => void;
+    interruptedLabel?: string;
+    followUpsLabel?: string;
+    hasMoreHistory?: boolean;
+    isLoadingHistory?: boolean;
+    onLoadOlderMessages?: () => void;
+    historyLoadingLabel?: string;
+    inputDisabled?: boolean;
+    errorMessage?: string;
+    width?: number;
+    height?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Props of the draggable ball. Rendered by `ControlledCopilot`, exported so a host can
+ * attach it to something other than the copilot panel.
+ */
+export interface CopilotBallProps {
+    isOpen: boolean;
+    onToggle: () => void;
+    position: CopilotBallPosition;
+    size: number;
+    isDragging: boolean;
+    draggable: boolean;
+    color: string;
+    zIndex: number;
+    icon?: ReactNode;
+    openIcon?: ReactNode;
+    ariaLabel?: string;
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerMove: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerUp: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerCancel: (event: ReactPointerEvent<HTMLElement>) => void;
+}
+/**
+ * Pointer handlers produced by `useDraggableFloater`, spread onto the ball.
+ */
+export interface CopilotDragHandlers {
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerMove: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerUp: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerCancel: (event: ReactPointerEvent<HTMLElement>) => void;
+}
+/**
+ * Options accepted by `useDraggableFloater`.
+ */
+export interface UseDraggableFloaterOptions {
+    /** Diameter of the dragged element in px, used for viewport clamping. */
+    size: number;
+    /** Corner the element is parked in when no `initialPosition` is given. */
+    corner: CopilotCorner;
+    /** Distance kept from the viewport edges the element is parked against. */
+    offset: number;
+    /** Whether drag gestures are accepted at all. */
+    enabled: boolean;
+    /** Whether the element returns to the nearest horizontal edge on release. */
+    snapToEdge: boolean;
+    /** Exact starting coordinates, clamped into the viewport. */
+    initialPosition?: CopilotBallPosition;
+    /** Fired once a drag gesture settles. */
+    onPositionChange?: (position: CopilotBallPosition) => void;
+}
+/**
+ * Return value of `useDraggableFloater`.
+ */
+export interface UseDraggableFloaterResult {
+    /** Current top-left coordinates of the element. */
+    position: CopilotBallPosition;
+    /** True while a gesture has moved past the drag threshold. */
+    isDragging: boolean;
+    /** Latest known viewport size, updated on resize. */
+    viewport: CopilotViewport;
+    /** Handlers to spread onto the dragged element. */
+    dragHandlers: CopilotDragHandlers;
+    /**
+     * Reads and clears the "the last gesture was a drag" flag. Call it at the top
+     * of the element's click handler so a drag does not also fire a click.
+     */
+    shouldIgnoreClick: () => boolean;
+}