@luzmo/analytics-components-kit 1.0.9-beta.6 → 1.0.9-beta.7

package/components/ai-chat/session/ai-chat-session-types.d.ts

@@ -1,119 +0,0 @@
-import type { PromptBoxAttachment } from '@luzmo/lucero';
-import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
-import type { AiSampleChart, ChatMessage, Dataset, LuzmoChart } from '../../../types';
-import type { AiChatCompleteEvent, AiChatStepEvent } from '../ai-chat-events';
-import type { AiPromptAgent, AiPromptCustomItemInput, AiPromptCreateBody, AiPromptDeleteBody, AiPromptItemTask, AiPromptScreenMode, BuildAiPromptRequestContext, DashboardStatePayload, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail } from '../ai-prompt-types';
-import type { StreamingRequestOptions, StreamingResponse } from '../stream/transport';
-import type { AiChatAgentConfig } from '../types';
-export interface AiChatSessionConfig {
-    /** Legacy agent selector. Defaults to item; agentConfig takes precedence. */
-    agent?: AiPromptAgent;
-    /** Typed agent selection and context. Omitted context preserves the same agent's context; null clears it. */
-    agentConfig?: AiChatAgentConfig;
-    /** Saved Agent override. Leave unset for custom-item sessions to preserve draft context and internal prompts. */
-    agentId?: string;
-    authKey: string;
-    authToken: string;
-    apiUrl?: string;
-    apiVersion?: string;
-    stream?: boolean;
-    conversationId?: string | null;
-    chart?: LuzmoChart | null;
-    dashboard?: DashboardStatePayload | null;
-    /** Draft context for `agent: 'custom-item'`, sent as its `custom-item` input. */
-    customItem?: AiPromptCustomItemInput['value'] | null;
-    currentScreenMode?: AiPromptScreenMode;
-    localeId?: string;
-    timezoneId?: string;
-    task?: AiPromptItemTask;
-    modelPreference?: 'performance' | 'quality';
-    /** Initial transcript when hydrating a saved conversation. */
-    messages?: ChatMessage[];
-    /** Datasets attached to the prompt input. */
-    selectedDatasets?: Dataset[];
-    /** When true, {@link AiChatSession.submit} requires at least one selected dataset or an `agentId` passed to it. */
-    requireDataset?: boolean;
-    /** Initial loading flag (e.g. Storybook or restored UI state). */
-    isGenerating?: boolean;
-    /** Initial progress tree. */
-    progress?: ProgressTreeNode | null;
-    /** Initial progress collapsed flag. */
-    progressCollapsed?: boolean;
-    /**
-     * Custom streaming HTTP client. Defaults to the built-in {@link fetchStreamingResponse}.
-     * Use for proxies, mocks, or alternate auth transport while keeping session state handling.
-     */
-    fetchStreaming?: (options: StreamingRequestOptions) => Promise<StreamingResponse>;
-}
-export interface AiChatSessionState {
-    messages: ChatMessage[];
-    selectedDatasets: Dataset[];
-    isGenerating: boolean;
-    progress: ProgressTreeNode | null;
-    progressCollapsed: boolean;
-    conversationId: string | null;
-    /** In-flight assistant message (streaming). Also present in `messages` while streaming. */
-    inflightMessage: ChatMessage | null;
-}
-export interface AiChatSessionCallbacks {
-    onStateChange?: (state: AiChatSessionState) => void;
-    onConversationIdChange?: (conversationId: string) => void;
-    /** Fired for every incremental, kit-assembled event during a streamed response. */
-    onStep?: (event: AiChatStepEvent) => void;
-    /** Fired exactly once per response with the authoritative final result (or error). */
-    onComplete?: (event: AiChatCompleteEvent) => void;
-    onMessageSent?: (message: ChatMessage, selectedDatasets: Dataset[]) => void;
-    onDatasetsChanged?: (selectedDatasets: Dataset[]) => void;
-    /**
-     * Host-owned submit: session updates transcript and loading state, then invokes this
-     * with the same payload shape as the former `luzmo-prompt-submitted` event plus an abort signal. No built-in fetch.
-     */
-    onPromptSubmitted?: (detail: LuzmoPromptSubmittedEventDetail) => void | Promise<void>;
-    /**
-     * Optional image upload override. When omitted, images upload via `POST /upload`.
-     * Return one signed URL per file (same order).
-     */
-    uploadAttachments?: (files: File[], options?: {
-        signal?: AbortSignal;
-    }) => Promise<string[]>;
-    /** Host-owned cleanup hook invoked for user-initiated prompt stops. */
-    onPromptStopped?: () => void | Promise<void>;
-    /**
-     * Host-owned restore (item agent): session invokes this with delete request + URL; no built-in fetch.
-     */
-    onRestoreRequested?: (detail: LuzmoRestoreRequestedEventDetail) => void | Promise<void>;
-}
-export interface AiChatSessionSubmitParams {
-    prompt: string;
-    /** Defaults to ids from {@link AiChatSessionState.selectedDatasets}. */
-    datasetIds?: string[];
-    /** Optional stable id for the in-flight AI message. */
-    aiMessageId?: string;
-    /** When true, does not append a user message (e.g. `initial-prompt` already in the transcript). */
-    skipUserMessage?: boolean;
-    /** Local prompt-box files; uploaded unless `attachmentUrls` is set. */
-    attachments?: PromptBoxAttachment[];
-    /** Signed image URLs already uploaded (`{ type: 'image', url }` inputs). Skips upload. */
-    attachmentUrls?: string[];
-    /**
-     * Saved Agent id for this prompt. Defaults to {@link AiChatSessionConfig.agentId}.
-     * Leave unset for custom-item sessions to preserve draft context and internal prompts.
-     */
-    agentId?: string;
-    /**
-     * Sends the prompt as `internal: true`, which keeps it out of the restored transcript.
-     * Only the custom-item agent supports it. Combine with `skipUserMessage` for a turn the
-     * host starts itself, such as an automatic fix.
-     */
-    internal?: boolean;
-}
-export interface AiChatSessionRestoreParams {
-    restoreToMessageId: string;
-    messageIndex: number;
-}
-export type AiChatSessionBuildContext = Omit<BuildAiPromptRequestContext, 'prompt' | 'datasetIds'>;
-export interface AiChatSessionRestoreResult {
-    chart?: AiSampleChart;
-    message?: string;
-}
-export type { AiPromptCreateBody, AiPromptDeleteBody, LuzmoPromptSubmittedEventDetail, LuzmoRestoreRequestedEventDetail };

package/components/ai-chat/session/ai-chat-session.d.ts

@@ -1,119 +0,0 @@
-import type { PromptBoxAttachment } from '@luzmo/lucero';
-import type { Dataset } from '../../../types';
-import type { AiPromptCreateBody, AiPromptDeleteBody, LuzmoPromptSubmittedEventDetail } from '../ai-prompt-types';
-import type { AiChatAgentConfig } from '../types';
-import type { AiChatSessionCallbacks, AiChatSessionConfig, AiChatSessionRestoreParams, AiChatSessionRestoreResult, AiChatSessionState, AiChatSessionSubmitParams } from './ai-chat-session-types';
-/**
- * Headless chat controller: transcript, datasets, streaming, and API calls without a DOM host.
- * Use with `luzmo-ai-chat` via `.chatSession` for the same simplicity as internal mode,
- * while keeping the session alive when the panel unmounts.
- *
- * @example
- * ```ts
- * const session = createAiChatSession(
- *   { agent: 'dashboard', authKey, authToken, dashboard, currentScreenMode },
- *   {
- *     onComplete: (e) => {
- *       if (e.dashboard) applyToEditor(e.dashboard, e.name);
- *     },
- *     onStateChange: (s) => persistConversation(s.messages),
- *   }
- * );
- *
- * html`<luzmo-ai-chat .chatSession=${session}></luzmo-ai-chat>`;
- * ```
- */
-export declare class AiChatSession {
-    private _config;
-    /** Callbacks passed to {@link createAiChatSession} (host application). */
-    private _hostCallbacks;
-    /** Optional bridge from `luzmo-ai-chat` (DOM events). Replaced on each bind, not chained. */
-    private _uiBridgeCallbacks;
-    private readonly _subscribers;
-    private _state;
-    private _abortController;
-    private _inflightMessage;
-    private _receivedProgress;
-    constructor(config: AiChatSessionConfig, callbacks?: AiChatSessionCallbacks);
-    get state(): Readonly<AiChatSessionState>;
-    get isGenerating(): boolean;
-    /** Effective built-in agent and context after applying typed configuration or legacy compatibility inputs. */
-    get agentConfig(): AiChatAgentConfig;
-    /**
-     * Subscribe to full session state (for `luzmo-ai-chat` rendering). Returns an unsubscribe function.
-     * The listener is invoked immediately with the current state.
-     */
-    subscribe(listener: (state: AiChatSessionState) => void): () => void;
-    /**
-     * Wire `luzmo-ai-chat` DOM event bridging. Safe to call again when hot-swapping the same
-     * session back onto the component — replaces the previous bridge instead of stacking it.
-     */
-    setUiBridge(bridge: AiChatSessionCallbacks): void;
-    /** Merge config (chart, conversationId, agent, …) without aborting an in-flight request. */
-    updateConfig(partial: Partial<AiChatSessionConfig>): void;
-    /** Replace the full dataset selection (e.g. when the dashboard context changes). */
-    setSelectedDatasets(datasets: Dataset[]): void;
-    addDataset(dataset: Dataset): void;
-    removeDataset(datasetId: string): void;
-    isDatasetRequirementMet(agentId?: string): boolean;
-    getAiPromptUrl(): string;
-    buildRequestBody(prompt: string, datasetIds: string[], attachmentUrls?: string[], agentId?: string | undefined, options?: {
-        internal?: boolean;
-    }): AiPromptCreateBody;
-    /** Same payload passed to {@link AiChatSessionCallbacks.onPromptSubmitted}. */
-    buildPromptSubmittedDetail(params: {
-        prompt: string;
-        selectedDatasets: Dataset[];
-        datasetIds: string[];
-        signal?: AbortSignal;
-        attachments?: PromptBoxAttachment[];
-        attachmentUrls?: string[];
-        agentId?: string;
-        internal?: boolean;
-    }): LuzmoPromptSubmittedEventDetail;
-    /** Prefer provided URLs; otherwise upload via host callback or built-in `/upload`. */
-    private _resolveAttachmentUrls;
-    private _normalizeUploadedUrls;
-    /**
-     * Append the user prompt (unless `skipUserMessage`), start streaming, and update {@link state}.
-     */
-    submit(params: AiChatSessionSubmitParams): Promise<void>;
-    /** {@link submit}, resolving to whether the request was sent (`false` when declined, aborted or superseded first). */
-    private _submit;
-    /**
-     * Answer the clarifying question on the last message and send the answer as the next prompt.
-     * Resolves to `false` without sending while a response is generating, when that message has no open
-     * question or another message follows it, when `answer` is not one of its options, when the dataset requirement is not met, or when
-     * the send is aborted or superseded before the request goes out; the answer is cleared again then.
-     */
-    answerElicitation(messageId: string, answer: string, params?: Omit<AiChatSessionSubmitParams, 'prompt'>): Promise<boolean>;
-    /** Item agent only — restore conversation to a prior API message. */
-    restore(params: AiChatSessionRestoreParams): Promise<AiChatSessionRestoreResult>;
-    buildRestoreRequest(restoreToMessageId: string): AiPromptDeleteBody;
-    /**
-     * Cancel the in-flight prompt.
-     * User-initiated stops (`notify`) leave a "response cancelled" placeholder where the assistant
-     * reply would have been; internal aborts discard any partial assistant output.
-     */
-    abort(options?: {
-        notify?: boolean;
-        cancelledMessage?: string;
-    }): void;
-    private _abortInflight;
-    private _createStreamCallbacks;
-    private _setConversationId;
-    private _upsertMessage;
-    private _finalizeInflightMessage;
-    private _removeInflightFromMessages;
-    private _markInflightCancelled;
-    private _discardInflightMessage;
-    private _handleSubmitError;
-    private _hasCallback;
-    private _emit;
-    private _invokeCallback;
-    private _patchState;
-    private _notifySubscribers;
-    private _areSelectedDatasetsEqual;
-    private _areChatMessagesEqual;
-}
-export declare function createAiChatSession(config: AiChatSessionConfig, callbacks?: AiChatSessionCallbacks): AiChatSession;

package/components/ai-chat/session/index.d.ts

@@ -1,2 +0,0 @@
-export { AiChatSession, createAiChatSession } from './ai-chat-session';
-export { AiChatSessionController } from './ai-chat-session-controller';

package/components/ai-chat/stream/chunk-extractors.d.ts

@@ -1,29 +0,0 @@
-/**
- * Pure field extractors for raw stream chunks.
- *
- * These read assistant text, chart, dashboard, and conversation-id values out of
- * the various shapes a chunk can take (inline fields, `aiMessageAssets`, or a
- * nested `result.assistant_message`). They are side-effect free, except
- * `applyConversationId`, which forwards the id through a callback.
- */
-import type { AiPromptCustomItemInput, DashboardStatePayload } from '../ai-prompt-types';
-import type { StreamHandlerContext } from './types';
-export declare function extractInlineStreamText(chunk: Record<string, unknown>): string;
-export declare function extractStreamText(chunk: Record<string, unknown>): string;
-/**
- * Authoritative assistant text from a terminal chunk's `result.assistant_message`.
- *
- * Unlike {@link extractStreamText}, this never falls back to inline delta fields, so
- * it is safe to use when finalizing the message: it yields the full answer to *set*
- * (not append), avoiding duplication when the same text was already streamed as deltas.
- */
-export declare function extractResultAssistantText(chunk: Record<string, unknown>): string;
-export declare function isStreamDone(chunk: Record<string, unknown>): boolean;
-export declare function applyConversationId(chunk: Record<string, unknown>, ctx: StreamHandlerContext): void;
-export declare function extractChartFromChunk(chunk: Record<string, unknown>): Record<string, unknown> | null;
-export declare function extractDashboardName(assets: unknown[]): Record<string, string> | undefined;
-export declare function extractDashboardFromChunk(chunk: Record<string, unknown>): DashboardStatePayload | null;
-/** Collect dashboard name from whichever asset array the chunk exposes. */
-export declare function extractDashboardNameFromChunk(chunk: Record<string, unknown>): Record<string, string> | undefined;
-/** Reads custom-item drafts from top-level or terminal assistant-message assets. */
-export declare function extractCustomItemFromChunk(chunk: Record<string, unknown>): AiPromptCustomItemInput['value'] | null;

package/components/ai-chat/stream/index.d.ts

@@ -1,53 +0,0 @@
-/**
- * AI chat streaming — public barrel for the stream pipeline.
- *
- * Orchestrated by `ai-chat-session.ts` when a prompt is submitted. The pipeline
- * has three layers: transport (HTTP + line parsing), processing (chunk → state +
- * events), and shared helpers (field extraction).
- *
- * ## End-to-end flow
- *
- * ```
- * submit prompt
- *   → createInitialProgress()              // "Thinking" progress tree in the UI
- *   → fetchStreamingResponse()             // POST to aiprompt API (or custom fetchStreaming)
- *   → readNdjsonStream(body, onChunk)      // decode NDJSON / SSE lines into JSON objects
- *        → createStreamHandler(agent)      // bound processStreamChunk per agent
- *             → processStreamChunk()       // map chunk → callbacks (onStep, onComplete, …)
- *   → session applies callbacks            // updates messages, progress, chart/dashboard
- * ```
- *
- * ## Modules
- *
- * | File                 | Responsibility                                              |
- * | -------------------- | ----------------------------------------------------------- |
- * | `transport`          | HTTP fetch + NDJSON/SSE line parsing                        |
- * | `progress`           | Initial progress tree + progress-chunk detection           |
- * | `registry`           | Agent wiring: `createStreamHandler`, initial stream state   |
- * | `stream-processor`   | Chunk routing, asset buffering, step/complete event emission  |
- * | `chunk-extractors`   | Chunk field extraction (text, chart, dashboard, conversation) |
- * | `types`              | `StreamHandlerContext`, callbacks, per-chunk state            |
- *
- * ## Agent mapping (`registry.ts`)
- *
- * - **dashboard** — `dashboardAssetType: 'dashboard'`; emits layout/title/item steps.
- * - **item** — `chartAssetType: 'item'`; final chart on `onComplete`.
- * - **custom-item** — `customItemAssetType: 'custom-item'`; updated draft on `onComplete`.
- * - **analyst** — text and progress only.
- *
- * ## Callbacks (`StreamHandlerCallbacks`)
- *
- * Each chunk drives incremental UI via `onStep` (typed stream events), `onProgress`,
- * `onMessageUpdate`, and `onProgressCollapsed`. The stream ends with a single
- * `onComplete` carrying the final message and optional chart/dashboard payload.
- *
- * See `stream-processor.ts` for the full chunk-handler priority order and mapping table.
- */
-export type { StreamingRequestOptions, StreamingResponse } from './transport';
-export { fetchStreamingResponse, parseStreamLine, readNdjsonStream } from './transport';
-export { createInitialProgress, hasProgressChunk } from './progress';
-export type { StreamChunkProcessor } from './registry';
-export { createInitialStreamState, createStreamHandler, getAgentStreamDefinition } from './registry';
-export type { AgentStreamDefinition, StreamHandlerCallbacks, StreamHandlerContext, StreamHandlerState } from './types';
-export { applyConversationId, extractChartFromChunk, extractDashboardFromChunk, extractDashboardName, extractDashboardNameFromChunk, extractInlineStreamText, extractResultAssistantText, extractStreamText, isStreamDone } from './chunk-extractors';
-export { processStreamChunk } from './stream-processor';

package/components/ai-chat/stream/progress.d.ts

@@ -1,3 +0,0 @@
-import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
-export declare function createInitialProgress(): ProgressTreeNode;
-export declare function hasProgressChunk(value: Record<string, unknown>): boolean;

package/components/ai-chat/stream/registry.d.ts

@@ -1,6 +0,0 @@
-import type { AiPromptAgent } from '../ai-prompt-types';
-import type { AgentStreamDefinition, StreamHandlerContext } from './types';
-export type StreamChunkProcessor = (chunk: Record<string, unknown>, ctx: StreamHandlerContext) => void;
-export declare function getAgentStreamDefinition(agent: AiPromptAgent): AgentStreamDefinition;
-export declare function createStreamHandler(agent: AiPromptAgent): StreamChunkProcessor;
-export declare function createInitialStreamState(): StreamHandlerContext['state'];

package/components/ai-chat/stream/stream-processor.d.ts

@@ -1,2 +0,0 @@
-import type { AgentStreamDefinition, StreamHandlerContext } from './types';
-export declare function processStreamChunk(chunk: Record<string, unknown>, ctx: StreamHandlerContext, def: AgentStreamDefinition): void;

package/components/ai-chat/stream/transport.d.ts

@@ -1,26 +0,0 @@
-/**
- * Transport layer for AI chat streaming.
- *
- * Owns the HTTP request to the aiprompt API and the wire-format decoding of the
- * response body. Knows nothing about chunk semantics — it produces raw JSON
- * objects that `stream-processor.ts` interprets.
- *
- * Supports both plain NDJSON (`{"type":"progress",...}`) and SSE (`data: {...}`).
- */
-export interface StreamingRequestOptions {
-    url: string;
-    body: Record<string, unknown>;
-    signal?: AbortSignal;
-}
-export interface StreamingResponse {
-    body: ReadableStream<Uint8Array>;
-    conversationId: string | null;
-}
-export declare function fetchStreamingResponse(options: StreamingRequestOptions): Promise<StreamingResponse>;
-/**
- * Parse one line from an aiprompt response stream.
- * Supports plain NDJSON (`{"type":"progress",...}`) and SSE (`data: {...}`).
- */
-export declare function parseStreamLine(line: string): Record<string, unknown> | null;
-/** Read NDJSON or SSE (`data:`) chunks from a streaming aiprompt response body. */
-export declare function readNdjsonStream(body: ReadableStream<Uint8Array>, onChunk: (chunk: Record<string, unknown>) => void): Promise<void>;

package/components/ai-chat/stream/types.d.ts

@@ -1,59 +0,0 @@
-import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
-import type { ChatMessage } from '../../../types';
-import type { AiChatCompleteEvent, AiChatStepEvent } from '../ai-chat-events';
-import type { AiPromptAgent, AiPromptCustomItemInput, DashboardStatePayload } from '../ai-prompt-types';
-export interface StreamHandlerCallbacks {
-    onConversationIdChange: (conversationId: string) => void;
-    onProgress: (progress: ProgressTreeNode) => void;
-    onProgressCollapsed: (collapsed: boolean) => void;
-    onMessageUpdate: (message: ChatMessage) => void;
-    getConversationId: () => string | null;
-    /** Fired for every incremental, assembled stream event. */
-    onStep: (event: AiChatStepEvent) => void;
-    /** Fired exactly once with the authoritative final result (or error). */
-    onComplete: (event: AiChatCompleteEvent) => void;
-}
-/** Per-asset accumulation buffer for the ASSET_START/DELTA/END channel. */
-export interface StreamAssetBuffer {
-    assetType: string;
-    snapshot: Record<string, unknown>;
-}
-export interface StreamHandlerState {
-    progressCollapsed: boolean;
-    /** Accumulated assistant text streamed so far. */
-    accumulatedText: string;
-    /** Latest classifier decision routed from the progress root node. */
-    decision: 'create' | 'edit' | 'question' | null;
-    /** In-flight asset buffers keyed by asset id (or asset type as fallback). */
-    assets: Record<string, StreamAssetBuffer>;
-    /** Authoritative dashboard snapshot (dashboard agent). */
-    dashboardSnapshot: DashboardStatePayload | null;
-    /** Dashboard name keyed by locale (dashboard agent). */
-    dashboardName: Record<string, string> | undefined;
-    /** Authoritative chart snapshot (item agent). */
-    chartSnapshot: Record<string, unknown> | null;
-    /** Authoritative custom item draft (custom-item agent). */
-    customItemSnapshot: AiPromptCustomItemInput['value'] | null;
-    /** Pending clarification question, when the agent interrupted. */
-    interruptQuestion: string | null;
-    /** Guards against firing {@link StreamHandlerCallbacks.onComplete} more than once. */
-    completed: boolean;
-}
-export interface StreamHandlerContext {
-    aiMessage: ChatMessage;
-    callbacks: StreamHandlerCallbacks;
-    state: StreamHandlerState;
-}
-/**
- * Per-agent stream definition. The shared processor owns the envelope/emit logic;
- * the agent only declares which final `asset_type`s map to its authoritative result.
- */
-export interface AgentStreamDefinition {
-    agent: AiPromptAgent;
-    /** Final asset type whose payload becomes {@link AiChatCompleteEvent.chart}. */
-    chartAssetType?: string;
-    /** Final asset type whose payload becomes {@link AiChatCompleteEvent.dashboard}. */
-    dashboardAssetType?: string;
-    /** Final asset type whose payload becomes {@link AiChatCompleteEvent.customItem}. */
-    customItemAssetType?: string;
-}

package/components/ai-chat/types.d.ts

@@ -1,24 +0,0 @@
-import type { LuzmoChart } from '../../types';
-import type { AiPromptCustomItemInput, AiPromptItemTask, AiPromptScreenMode, DashboardStatePayload } from './ai-prompt-types';
-/** Configuration for one built-in agent. Omitted context preserves the same agent's context; null clears it. */
-export type AiChatAgentConfig = {
-    type: 'item';
-    context?: {
-        chart?: LuzmoChart | null;
-        task?: AiPromptItemTask;
-    } | null;
-} | {
-    type: 'dashboard';
-    context?: {
-        dashboard?: DashboardStatePayload | null;
-        currentScreenMode?: AiPromptScreenMode;
-    } | null;
-} | {
-    type: 'custom-item';
-    context?: {
-        customItem?: AiPromptCustomItemInput['value'] | null;
-    } | null;
-} | {
-    type: 'analyst';
-    context?: null;
-};