@campfire-interactive/ai-chat 0.0.0-stage → 0.1.0

package/dist/client-u2gNr000.d.ts

@@ -0,0 +1,275 @@
+/**
+ * The wire contract between the browser and the hub's assistant API.
+ *
+ * Copied exactly from the meta repo's plan
+ * (`docs/plans/2026-10-20-platform-ai-chat-phase-1.md`, "Wire contract"). A
+ * change here is a change in every repo that builds against it: the hub, its
+ * TS client, campfire-mcp and every host app. Do not edit one side alone.
+ */
+/** Where the user is. The host builds it on every navigation; every message carries the current one. */
+type AiPageContext = {
+    /** 'pm' */
+    app: string;
+    /** '/programs/8f…/risks' */
+    path: string;
+    /** Stable page key: 'program.risks'. Starters are keyed by it. */
+    page: string;
+    /** 'Risks' */
+    title: string;
+    /** ['Portfolio', 'P-1042', 'Risks'] */
+    breadcrumbs: string[];
+    /** program, task, gate, process… */
+    entities: Array<{
+        type: string;
+        id: string;
+        label: string;
+    }>;
+    /** e.g. /work query params */
+    filters?: Record<string, string>;
+};
+/** A destination in an app. `path` starts with '/'. */
+type AiLink = {
+    app: string;
+    path: string;
+};
+type AiTableColumnType = 'text' | 'number' | 'money' | 'percent' | 'date' | 'status';
+type AiValueFormat = 'number' | 'money' | 'percent';
+type AiBlock = {
+    kind: 'table';
+    title?: string;
+    columns: Array<{
+        key: string;
+        label: string;
+        type?: AiTableColumnType;
+    }>;
+    rows: Array<Record<string, string | number | boolean | null>>;
+    currency?: string;
+} | {
+    kind: 'chart';
+    title?: string;
+    chartType: 'line' | 'bar' | 'area' | 'scatter' | 'waterfall';
+    xKey: string;
+    series: Array<{
+        key: string;
+        label: string;
+    }>;
+    data: Array<Record<string, string | number | null>>;
+    xLabel?: string;
+    yLabel?: string;
+    valueFormat?: AiValueFormat;
+} | {
+    kind: 'kpis';
+    items: Array<{
+        label: string;
+        value: string | number;
+        format?: AiValueFormat;
+        change?: number;
+        tone?: 'good' | 'bad' | 'neutral';
+    }>;
+} | {
+    kind: 'entities';
+    items: Array<{
+        type: string;
+        id: string;
+        label: string;
+        sublabel?: string;
+        link: AiLink;
+    }>;
+} | {
+    kind: 'actions';
+    /**
+     * `openNow` (at most one item) is set when the user asked to be taken
+     * somewhere: the host opens it straight away, and the button stays for
+     * going back to it.
+     */
+    items: Array<{
+        label: string;
+        link: AiLink;
+        style?: 'navigate' | 'open_form';
+        openNow?: boolean;
+        primary?: boolean;
+    }>;
+} | {
+    kind: 'question';
+    question: string;
+    options?: string[];
+}
+/** Text to send elsewhere (an email, a message), shown as its own card with a copy button. */
+ | {
+    kind: 'draft';
+    title: string;
+    to?: string;
+    subject?: string;
+    body: string;
+} | {
+    kind: 'followups';
+    items: string[];
+    didYouMean?: boolean;
+} | {
+    kind: 'citation';
+    items: Array<{
+        title: string;
+        url: string;
+        section?: string;
+    }>;
+}
+/** One line restating the question, shown above the answer as "Understood as". */
+ | {
+    kind: 'understood';
+    summary: string;
+};
+/** A change the hub proposed and did not run. Confirm posts `token` back. */
+type PendingWrite = {
+    /** Signed; opaque to the browser. */
+    token: string;
+    tool: string;
+    /** "Change status of Tooling PO to Done" */
+    summary: string;
+    entity: {
+        type: string;
+        id: string;
+        label?: string;
+    };
+    before?: Record<string, unknown>;
+    after?: Record<string, unknown>;
+    file?: {
+        fileRef: string;
+        name: string;
+        size: number;
+        contentType: string;
+    };
+    /** The program the change belongs to, when it belongs to one — where an attach's upload is filed. */
+    programId?: string;
+    /** ISO */
+    expiresAt: string;
+};
+/** One `data:` line of the chat stream. */
+type AssistantEvent = {
+    type: 'text';
+    delta: string;
+}
+/** Plain words, never a tool name. */
+/**
+ * `source`: the page name for what was read ("Risks & issues"), shown as
+ * "Based on". `sourcePath`: that page in this app, when the lookup was about
+ * one record the hub could check; absent otherwise, and the chip is plain.
+ * `sourceApp`: set when that page is in another app than the one the chat
+ * is open in (the chat answers from every app the user is granted).
+ */
+ | {
+    type: 'step';
+    label: string;
+    source?: string;
+    sourcePath?: string;
+    sourceApp?: string;
+} | {
+    type: 'block';
+    block: AiBlock;
+} | {
+    type: 'write_pending';
+    write: PendingWrite;
+} | {
+    type: 'done';
+} | {
+    type: 'error';
+    code: string;
+    message: string;
+};
+/** A file dropped into the composer, as the model sees it: metadata only, never the bytes. */
+type AssistantAttachment = {
+    fileRef: string;
+    name: string;
+    contentType: string;
+    size: number;
+};
+/** `POST /api/v1/assistant/chat/stream` */
+type AssistantChatRequest = {
+    app: string;
+    /** Browser UUID. Groups this session's audit rows; never a key to stored chat. */
+    session_id: string;
+    /** This turn's question. */
+    message: string;
+    /** Recent turns, text only. */
+    history: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    page_context: AiPageContext;
+    attachments: AssistantAttachment[];
+};
+/** `POST /api/v1/assistant/writes/confirm` */
+type ConfirmWriteRequest = {
+    token: string;
+    documentId?: string;
+};
+type ConfirmWriteResponse = {
+    actionId: string;
+    outcome: 'succeeded' | 'failed';
+    result?: unknown;
+    error?: string;
+};
+/** One executed write, from the hub's append-only audit. */
+type AssistantAction = {
+    id: string;
+    tenantId: string;
+    userId: string;
+    userName: string | null;
+    app: string;
+    sessionId: string;
+    question: string;
+    page: string | null;
+    tool: string;
+    /** The card's own words ("Change status of Tooling PO to Complete"). */
+    summary: string | null;
+    args: Record<string, unknown>;
+    entityType: string | null;
+    entityId: string | null;
+    programId: string | null;
+    before: unknown;
+    after: unknown;
+    outcome: 'succeeded' | 'failed';
+    result: unknown;
+    error: string | null;
+    proposedAt: string;
+    confirmedAt: string;
+};
+/** `GET /api/v1/assistant/actions` filters. */
+type ListActionsQuery = {
+    sessionId?: string;
+    entityId?: string;
+    userId?: string;
+    limit?: number;
+};
+
+/**
+ * The three hub calls the panel makes, typed against the wire contract.
+ *
+ * Deliberately small and self-contained: the hub's own TS client
+ * (`cfi-ai-hub-client`) gains an assistant resource separately, and this
+ * package must not wait on it or drag its other resources into every host.
+ */
+interface AssistantClient {
+    chatStream(req: AssistantChatRequest, opts?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<AssistantEvent>;
+    confirmWrite(req: ConfirmWriteRequest): Promise<ConfirmWriteResponse>;
+    listActions(query: ListActionsQuery): Promise<{
+        items: AssistantAction[];
+    }>;
+}
+interface AssistantClientOptions {
+    /** The hub's base URL, without `/api/v1`. */
+    hubUrl: string;
+    /** The user's own identity JWT, the same token the app sends its own API. */
+    getToken: () => Promise<string | null>;
+    /** Test seam; defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** A non-2xx answer from the hub. `message` is the hub's own wording when it sent one. */
+declare class AssistantHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare function createAssistantClient({ hubUrl, getToken, fetch: fetchImpl }: AssistantClientOptions): AssistantClient;
+
+export { type AssistantEvent as A, type ConfirmWriteRequest as C, type ListActionsQuery as L, type PendingWrite as P, type AiBlock as a, type AiLink as b, type AiPageContext as c, type AiTableColumnType as d, type AiValueFormat as e, type AssistantAction as f, type AssistantAttachment as g, type AssistantChatRequest as h, type AssistantClient as i, type AssistantClientOptions as j, AssistantHttpError as k, type ConfirmWriteResponse as l, createAssistantClient as m };

package/dist/host/index.d.ts

@@ -0,0 +1,210 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { c as AiPageContext, g as AssistantAttachment, a as AiBlock, P as PendingWrite, b as AiLink, f as AssistantAction, i as AssistantClient } from '../client-u2gNr000.js';
+export { A as AssistantEvent, m as createAssistantClient } from '../client-u2gNr000.js';
+
+/** The page a question was asked on, as its card shows it. */
+type AskedOn = Pick<AiPageContext, 'page' | 'title' | 'breadcrumbs' | 'path'>;
+type WriteState = 'pending' | 'confirming' | 'succeeded' | 'failed' | 'canceled' | 'discarded' | 'expired';
+interface WriteItem {
+    write: PendingWrite;
+    state: WriteState;
+    /** The refusal, the upload failure, or what went wrong. */
+    error?: string;
+    actionId?: string;
+}
+/** An answer is an ordered run of parts: prose as it streams, typed blocks, and pending writes. */
+type AnswerPart = {
+    kind: 'markdown';
+    text: string;
+} | {
+    kind: 'block';
+    block: AiBlock;
+} | {
+    kind: 'write';
+    item: WriteItem;
+};
+type ExchangeStatus = 'streaming' | 'done' | 'error';
+/** One question and the answer to it. */
+interface Exchange {
+    id: string;
+    question: string;
+    askedOn: AskedOn;
+    attachments: AssistantAttachment[];
+    parts: AnswerPart[];
+    /** "Checked N things", in plain words. */
+    steps: string[];
+    /** What the answer read, by page name, each once: "Based on …". */
+    sources?: AnswerSource[];
+    status: ExchangeStatus;
+    error?: string;
+    /** `Confirmed: <summary> (succeeded|failed)` lines, sent back to the model in history. */
+    confirmations: string[];
+    /** Epoch ms the question was sent, and the answer finished. */
+    askedAt: number;
+    answeredAt?: number;
+}
+/**
+ * A question-and-answer card. Usually one exchange; a reply to the model's own
+ * clarifying question folds into the same card as a second one.
+ */
+interface Card {
+    id: string;
+    exchanges: Exchange[];
+}
+type AiStarter = string;
+/**
+ * Fills `{placeholders}` in a starter from the page: an entity of that type
+ * (its label; `{item}` is the page's focus, any type), then a filter of that
+ * name, then `{title}`.
+ * `ready` is false when any placeholder is left, and the chip then loads into
+ * the composer instead of sending something vague.
+ */
+declare function fillStarter(template: string, ctx: AiPageContext): {
+    text: string;
+    ready: boolean;
+};
+/** A "Based on" chip: the page name, and the page itself when there is exactly one. */
+type AnswerSource = {
+    label: string;
+    path?: string; /** Another app's page, when not the host's. */
+    app?: string;
+};
+
+/** A topic in the question catalog. Questions take the same {placeholders} as starters. */
+interface AiQuestionGroup {
+    label: string;
+    blurb?: string;
+    questions: string[];
+}
+interface ChangesState {
+    items: AssistantAction[];
+    loading: boolean;
+    loaded: boolean;
+    error?: string;
+}
+/** Everything the panel, the button and a host can read or do. */
+interface AiChatState {
+    app: string;
+    pageContext: AiPageContext;
+    /** The starters for the current page. */
+    starters: AiStarter[];
+    /** Everything the app can answer, grouped, for the "Browse by topic" view. */
+    catalog: AiQuestionGroup[];
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+    width: number;
+    setWidth: (width: number) => void;
+    /** Groups this session's audit rows. Never shown. */
+    sessionId: string;
+    cards: Card[];
+    /** An answer is streaming; the composer waits. */
+    busy: boolean;
+    draft: string;
+    setDraft: (text: string) => void;
+    /** Sends a message. `foldInto` puts it in an existing card (a reply to the model's question). */
+    send: (message: string, opts?: {
+        foldInto?: string;
+    }) => Promise<void>;
+    /**
+     * Opens the chat on a question: sent at once, or with `{ send: false }`
+     * loaded into the composer for the user to finish. For a page's own "ask"
+     * button, a tile, a notification. `?ask=` on any URL does the same on load.
+     */
+    ask: (question: string, opts?: {
+        send?: boolean;
+    }) => void;
+    /** Stops the answer that is streaming, keeping what arrived. */
+    stop: () => void;
+    /** Clears the thread, the dropped files and the session id. */
+    startOver: () => void;
+    /** Files dropped since the last message, shown in the composer. */
+    stagedFiles: AssistantAttachment[];
+    addFiles: (files: File[] | FileList) => void;
+    removeFile: (fileRef: string) => void;
+    confirmWrite: (exchangeId: string, token: string) => Promise<void>;
+    /** Confirms every change still pending in one answer. */
+    confirmAll: (exchangeId: string) => Promise<void>;
+    cancelWrite: (exchangeId: string, token: string) => void;
+    navigate: (link: AiLink) => void;
+    /** The panel covers the page area instead of docking beside it. */
+    expanded: boolean;
+    setExpanded: (expanded: boolean) => void;
+    /** "Changes made this session", from the hub's audit. */
+    changes: ChangesState;
+    /** The card summary of each write confirmed here, by audit id. */
+    summaries: Record<string, string>;
+    refreshChanges: () => Promise<void>;
+}
+/**
+ * The chat's state, or null when the chat is off (no provider, or a provider
+ * without a hub URL). The button and the surface render nothing then, so a
+ * host can place them unconditionally.
+ */
+declare function useAiChat(): AiChatState | null;
+
+interface AiChatProviderProps {
+    /** The app slug the hub knows: 'pm'. */
+    app: string;
+    /** The hub's base URL for this environment. Empty or undefined (and no `client`) = chat off; children render as-is. */
+    hubUrl?: string;
+    /** The user's own identity JWT, the same token the app sends its own API. */
+    getToken: () => Promise<string | null>;
+    /**
+     * Uploads a dropped file to DMS with the user's token and returns its id.
+     * Called only when the user confirms an attach, never at drop time. The host
+     * owns this (pm wires its dms-client); the package imports no service client.
+     */
+    uploadFile: (file: File, write: PendingWrite) => Promise<{
+        documentId: string;
+    }>;
+    /** Where the user is now. Rebuilt by the host on every navigation. */
+    pageContext: AiPageContext;
+    /** Everything the app can answer, grouped, shown as "Browse by topic". */
+    catalog?: AiQuestionGroup[];
+    /** Starter chips keyed by `pageContext.page`; `'*'` is the fallback for pages without their own. */
+    starters?: Record<string, AiStarter[]>;
+    /** Opens a link from an answer (entity cards, action buttons). The host decides how a cross-app link opens. */
+    navigate: (link: AiLink) => void;
+    /**
+     * Called after a confirmed change has run (succeeded or failed), so the host
+     * can refetch what the page shows — otherwise the screen beside the chat
+     * keeps the value the change just replaced. pm invalidates its query cache.
+     */
+    onChanged?: (write: PendingWrite, outcome: 'succeeded' | 'failed') => void;
+    /** Replaces the hub client built from `hubUrl`/`getToken`. For tests and the showcase. */
+    client?: AssistantClient;
+    children: ReactNode;
+}
+declare function AiChatProvider(props: AiChatProviderProps): react.JSX.Element;
+
+/**
+ * The docked chat panel. Place it INSIDE the app's layout, as a flex sibling
+ * of the main content column, beside `<CampfireHelpSurfaces />`:
+ *
+ *   <div className="flex flex-1 overflow-hidden">
+ *     <SideNav … />
+ *     <main className="min-w-0 flex-1 overflow-auto">…</main>
+ *     <CampfireHelpSurfaces />
+ *     <AiChatSurface />
+ *   </div>
+ *
+ * The page reflows beside it, which needs `min-width: 0` on `<main>`. Renders
+ * nothing while the panel is closed or the chat is off.
+ */
+declare function AiChatSurface(): react.JSX.Element | null;
+
+/**
+ * The header icon. Pass it into the shell header's `rightActions`, so every
+ * page has it with no shell-header change. Toggles the panel; Ctrl/Cmd+J does
+ * the same from anywhere (BOM's shortcut: Find Part owns Ctrl+K).
+ *
+ * Renders nothing when the chat is off, so a host can place it unconditionally
+ * and gate only the provider.
+ */
+declare function AiChatButton({ className }: {
+    className?: string;
+}): react.JSX.Element | null;
+
+export { AiBlock, AiChatButton, AiChatProvider, type AiChatProviderProps, type AiChatState, AiChatSurface, AiLink, AiPageContext, type AiQuestionGroup, type AiStarter, type AnswerPart, AssistantAction, AssistantClient, type Card, type ChangesState, type Exchange, PendingWrite, type WriteItem, type WriteState, fillStarter, useAiChat };