@twentyfourg/chat-kit 1.0.0-beta.1

package/dist/types.d.ts

@@ -0,0 +1,389 @@
+/**
+ * Shared Base Camp + chat domain types.
+ *
+ * Shapes are derived from Base Camp's Zodios API definitions
+ * (packages/api/src/api/*.api.ts and packages/lib/src/schemas/* in the
+ * Base Camp repo), which generate the authoritative OpenAPI contract.
+ * SSE event names and the parsing loop live in services/streaming.service.ts;
+ * this file only defines the payload shapes those events carry.
+ */
+export type ConversationType = 'SINGLE_SHOT' | 'CONTINUOUS';
+/**
+ * Per-agent feature toggles the frontend should honor. Several are also
+ * enforced server-side (sources, knowledge-source visibility, single-shot locking).
+ */
+export interface AgentConfig {
+    /** Render the model's thinking inline as it streams. Display hint only; thinking events always arrive. */
+    showThinkingProcess: boolean;
+    /** Show an affordance to reveal the thinking process. Display hint only. */
+    showThinkingProcessButton: boolean;
+    /** Enable voice interaction UI (mic / audio controls). */
+    enableVoiceInteraction?: boolean;
+    /** Show the export locker UI. */
+    showExpertLocker: boolean;
+    /** Show knowledge sources in an information panel. */
+    showKnowledgeSources: boolean;
+    /** Show the sources button on assistant replies; also gates the used-sources stream event server-side. */
+    showSourcesButton: boolean;
+    /** Default the locker view to exports from this agent only. */
+    defaultLockerViewThisExpertOnly: boolean;
+    /** Display the token usage indicator in the chat interface. */
+    showTokenUsageIndicator: boolean;
+    /** Cumulative token budget for a thread's lifetime; server rejects messages past it. */
+    chatTokenLimit: number;
+    conversationType: ConversationType;
+}
+export type KnowledgeSourceKind = 'INTERNAL' | 'FILE' | 'DOWNLOAD';
+/** Public-safe knowledge source reference returned on agent detail (types and ids only). */
+export interface AgentKnowledgeSourceRef {
+    type: KnowledgeSourceKind;
+    uniqueExternalId: string | null;
+    baseCampId: string | null;
+}
+/** Public agent detail from GET /v1/agents/:agentId. */
+export interface AgentDetails {
+    id: string;
+    name: string;
+    description: string;
+    firstMessage: string;
+    config?: AgentConfig;
+    /** Names usable as {{placeholder}} variables in agent prompts, filled per thread. */
+    variableNames?: string[];
+    knowledgeSource: AgentKnowledgeSourceRef[];
+}
+export type ThreadStatus = 'ACTIVE' | 'ARCHIVED' | 'DELETED';
+/** User's resolved rate-limit tier, recorded on the thread at creation. */
+export type RateLimitTier = 'guest' | 'basic' | 'premium';
+/** Per-thread values for the agent's declared variables; keys must be in variableNames. */
+export type ThreadVariables = Record<string, string>;
+/** Opaque product-owned data bag; Base Camp stores it verbatim and never interprets it. */
+export type ThreadCustomData = Record<string, unknown>;
+export interface Thread {
+    id: string;
+    agentId: string;
+    status: ThreadStatus;
+    title?: string;
+    lastMessageAt?: string;
+    messageCount?: number;
+    createdAt?: string;
+    updatedAt?: string;
+    tier?: RateLimitTier;
+    /** True when a SINGLE_SHOT thread already has a completed turn and rejects new messages. */
+    locked?: boolean;
+    variables?: ThreadVariables;
+    customData?: ThreadCustomData;
+}
+/** Agent summary embedded in thread detail; firstMessage arrives pre-substituted with thread variables. */
+export interface ThreadAgentSummary {
+    id: string;
+    name: string;
+    description: string;
+    firstMessage: string;
+    config?: AgentConfig;
+}
+/** GET /v1/agents/:agentId/threads/:threadId response. */
+export interface ThreadDetail extends Thread {
+    agent: ThreadAgentSummary;
+}
+export interface CreateThreadBody {
+    variables?: ThreadVariables;
+    customData?: ThreadCustomData;
+}
+export interface CreateThreadResponse {
+    id: string;
+    agentId: string;
+    status: ThreadStatus;
+    createdAt: string;
+    variables?: ThreadVariables;
+    tier?: RateLimitTier;
+}
+export type ChatRole = 'user' | 'assistant';
+export type MessageFeedback = 'POSITIVE' | 'NEGATIVE';
+/** Per-message token counts as stored in message metadata. */
+export interface MessageTokens {
+    input: number;
+    output: number;
+    total: number;
+}
+export interface ChatMessageMetadata {
+    /** Reasoning text captured for this message. */
+    thinking?: string;
+    tokens?: MessageTokens;
+    /** True while the assistant reply is still being generated server-side (reconnect marker). */
+    streaming?: boolean;
+    /** Server marks the thread-opening welcome message with these. */
+    isWelcomeMessage?: boolean;
+    messageType?: string;
+    [key: string]: unknown;
+}
+/** Client-friendly attachment reference on a history message. */
+export interface MessageAttachment {
+    format: string;
+    name?: string;
+    url: string;
+}
+/** A message as returned by GET .../messages (chat history). */
+export interface ChatMessage {
+    id: string;
+    role: ChatRole;
+    text: string;
+    attachments?: MessageAttachment[];
+    createdAt: string;
+    stopReason?: string;
+    /** Grouped source citations persisted with the assistant message. */
+    sourceContext?: UsedSource[];
+    metadata?: ChatMessageMetadata;
+    /** Current user's explicit feedback on this message, not an aggregate. */
+    feedback?: MessageFeedback;
+    feedbackUpdatedAt?: string;
+}
+/** GET /v1/agents/:agentId/threads/:threadId/messages response. */
+export interface MessageListResponse {
+    threadId: string;
+    messages: ChatMessage[];
+    tokenUsage?: TokenUsage;
+    customData?: ThreadCustomData;
+}
+export interface SendMessageBody {
+    message: string;
+    stream?: boolean;
+    /**
+     * Tells Base Camp the text was dictated rather than typed, so the two can
+     * be told apart in reporting.
+     *
+     * Only ever 'dictation'. A typed message leaves the field out and takes the
+     * server's default of 'keyboard', and the kit has no voice-to-voice mode,
+     * which is the 'realtime' value the API also accepts.
+     */
+    inputMode?: 'dictation';
+}
+export interface StopMessageResponse {
+    success: boolean;
+    message: string;
+}
+/** POST .../messages/:messageId/feedback response; feedback is absent after a clear. */
+export interface FeedbackResponse {
+    messageId: string;
+    feedback?: MessageFeedback;
+    feedbackUpdatedAt?: string;
+}
+export interface SourceResultMetadata {
+    title?: string;
+    entityId?: string;
+    page?: number;
+    /** Prefer over `page` for a "text page N" display, when present. */
+    textPage?: number;
+    /** External source URL, when the document has one. */
+    link?: string;
+    /** Short-lived signed page-image URL; valid when displayed, not cacheable. */
+    screenshotUrl?: string;
+    [key: string]: unknown;
+}
+/** One retrieval hit inside a grouped source. */
+export interface SourceResult {
+    index?: number;
+    content?: string;
+    score?: number;
+    metadata?: SourceResultMetadata;
+}
+/**
+ * Source citations grouped by knowledge entity, as emitted by the used-sources
+ * stream event and persisted on messages as sourceContext. entityId is null
+ * for hits the server could not attribute to an entity.
+ */
+export interface UsedSource {
+    entityId: string | null;
+    metadata?: SourceResultMetadata;
+    /**
+     * The document's cover image as older threads persisted it. It moved into
+     * metadata since; readers should prefer metadata.screenshotUrl and fall
+     * back to this, so reopened old threads keep their covers.
+     */
+    screenshotUrl?: string;
+    results: SourceResult[];
+}
+/**
+ * How the chat presents its sources. 'inline' swaps [^N] markers in the answer
+ * for numbered chips that open a passage popover; 'list' shows the documents
+ * the answer drew on underneath it instead.
+ */
+export type CitationType = 'inline' | 'list';
+/**
+ * How the thinking indicator animates while an answer is being retrieved:
+ * 'ring' is a spinning arc, 'sparkles' is a cluster of pulsing stars, 'dots'
+ * is three dots rising in turn.
+ */
+export type ThinkingVariant = 'ring' | 'sparkles' | 'dots';
+/**
+ * How far the conversation follows an answer as it streams.
+ *
+ * 'reply' stops once the answer's own header reaches the top, so a long answer
+ * settles with its beginning in view and grows out of sight below. 'bottom'
+ * follows the newest text instead, keeping the last line in view. 'off' leaves
+ * the view entirely to the reader.
+ *
+ * Under 'reply' and 'bottom' alike, scrolling up stops following until the
+ * reader returns to the bottom.
+ */
+export type AutoScrollMode = 'off' | 'reply' | 'bottom';
+/**
+ * One passage-level citation, emitted by the citations stream event for agents
+ * configured with `citationMode: 'inline'`. The answer text carries matching
+ * `[^N]` markers where N is `ref`.
+ */
+export interface ChatCitation {
+    /** N from the `[^N]` marker in the answer text. Unique within the turn. */
+    ref: number;
+    /** Dense display number (1..N). Always show this, never `ref`. */
+    label: number;
+    /** The cited passage. */
+    passage: string;
+    entityId?: string;
+    variationId?: string;
+    title?: string;
+    /**
+     * Where to send a reader who opens this source. Once Base Camp's citation
+     * tracking is deployed this is a signed redirect that records the click,
+     * not the document's own address, so navigate with it but never share it.
+     */
+    link?: string;
+    /**
+     * The document's own URL, for sharing and for showing someone where a
+     * passage came from. Absent on replies from before citation tracking, where
+     * `link` was the plain URL and is the thing to fall back to.
+     */
+    canonicalLink?: string;
+    /**
+     * Base Camp's id for this citation within its message. Needed to report
+     * that the passage was opened, since the server resolves the document,
+     * page and thread from it rather than trusting the browser. Absent until
+     * Base Camp's citation tracking is deployed.
+     */
+    sourceId?: string;
+    /** Short-lived signed page-image URL. */
+    screenshotUrl?: string;
+    page?: number;
+    /** Prefer over `page` for a "p. X" display. */
+    textPage?: number;
+}
+/** How the user entered their question: typing, or voice dictation. */
+export type ChatInputMode = 'typed' | 'voice';
+/**
+ * A moment in the conversation the app may want to record, announced through
+ * the engine's onEvent option. The kit only describes what happened; whether
+ * and where it gets reported is the app's business.
+ */
+export type ChatEvent = {
+    type: 'turn';
+    /** The user's question as sent. */
+    query: string;
+    inputMode: ChatInputMode;
+    /** The assistant's full answer text. */
+    response: string;
+    isOutOfScope: boolean;
+    citations: ChatCitation[];
+    sources: UsedSource[];
+    threadId: string | null;
+    userMessageId?: string;
+    assistantMessageId?: string;
+} | {
+    type: 'citation-click';
+    citation: ChatCitation;
+    assistantMessageId?: string;
+    threadId: string | null;
+    /** The question and answer the citation belongs to. */
+    query: string;
+    response: string;
+} | {
+    type: 'feedback';
+    /** The rating now in effect; null means the user cleared their thumb. */
+    value: MessageFeedback | null;
+    assistantMessageId?: string;
+    threadId: string | null;
+    /** The question and answer the rating is about. */
+    query: string;
+    response: string;
+};
+/**
+ * POST /v1/analytics/events body. Base Camp stores the event for the
+ * project's analytics reports; eventType says which report it belongs to.
+ */
+export interface TrackEventBody {
+    /**
+     * Random visitor id the frontend may generate and store in the browser, to
+     * group one visitor's rows in the sheet. Optional, and better left out when
+     * Base Camp can identify the caller from the request itself, which a
+     * browser cannot forge.
+     */
+    sessionId?: string;
+    eventType: string;
+    /** The assistant message the event belongs to. */
+    messageId?: string;
+    /** Which citation within that message, from `ChatCitation.sourceId`. */
+    sourceId?: string;
+    /**
+     * Extra detail for events that need it. Base Camp resolves what it can
+     * from the ids above and ignores anything here it already knows.
+     */
+    payload?: Record<string, unknown>;
+}
+export interface TrackEventResponse {
+    success: boolean;
+}
+/** Thread-level token accounting returned with history and the token-usage stream event. */
+export interface TokenUsage {
+    /** Running totals across the thread lifecycle. */
+    cumulative: {
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalTokens: number;
+        percentOfContextLimit: number;
+        percentOfCumulativeLimit: number;
+    };
+    /** Tokens sent to the model for the current context window. */
+    active: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        messageCount: number;
+        percentOfContextLimit: number;
+    };
+    /** Context window limit for the AI model. */
+    contextLimit: number;
+    /** Total token cap across the thread lifecycle. */
+    cumulativeLimit: number;
+}
+/** GET /v1/agents/:agentId/quota response; reads without consuming quota. */
+export interface QuotaResponse {
+    limit: number | 'unlimited';
+    remaining: number | 'unlimited';
+    resetAt: string;
+}
+/** Payload of the message_id and assistant_message_id events. */
+export interface StreamMessageIdPayload {
+    messageId: string;
+}
+/** Payload of thinking_delta and response_delta events. */
+export interface StreamTextPayload {
+    text: string;
+}
+/** Payload of the text_complete event. */
+export interface StreamTextCompletePayload {
+    hasSourceContext: boolean;
+}
+/** Payload of the token_usage event. */
+export interface StreamTokenUsagePayload {
+    message: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    thread: TokenUsage;
+}
+/** Payload of the used_sources event. */
+export type StreamUsedSourcesPayload = UsedSource[];
+/** Payload of the error event; message is always server-sanitized. */
+export interface StreamErrorPayload {
+    error: string;
+    message?: string;
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@twentyfourg/chat-kit",
+  "version": "1.0.0-beta.1",
+  "description": "Base Camp chat frontend for Vue 3: the conversation and composer components, a typed client, SSE streaming, sanitized markdown, and a copy and theme contract.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@10.22.0",
+  "main": "./dist/chat-kit.js",
+  "module": "./dist/chat-kit.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/chat-kit.js"
+    },
+    "./theme.css": "./dist/theme.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/twentyfourg/chat-kit.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && vue-tsc -p tsconfig.build.json",
+    "lint": "oxlint .",
+    "test": "vitest run",
+    "type-check": "vue-tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "pnpm build"
+  },
+  "pnpm": {
+    "ignoredBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "peerDependencies": {
+    "mathlive": ">=0.104.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "mathlive": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "dompurify": "^3.4.12",
+    "marked": "^17.0.1"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^24.13.3",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "@vue/test-utils": "^2.5.0",
+    "@vue/tsconfig": "^0.9.1",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "jsdom": "^30.0.1",
+    "mathlive": "^0.110.0",
+    "oxlint": "~1.60.0",
+    "semantic-release": "^25.0.9",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.5",
+    "vite-plugin-lib-inject-css": "^2.2.2",
+    "vitest": "^3.2.4",
+    "vue": "^3.5.32",
+    "vue-tsc": "^3.2.6"
+  }
+}