@magemetrics/ai 0.11.3 → 0.11.4

package/dist/web-component/index.d.ts

@@ -1,1090 +1,121 @@
-import { AuthProvider } from '@magemetrics/core';
-import { AuthState } from '@magemetrics/core';
-import { CreateFlowParam } from '@magemetrics/core';
-import { default as default_2 } from 'react';
-import { DirectAuthProvider } from '@magemetrics/core';
-import { ExternalAuthProvider } from '@magemetrics/core';
-import { ExternalAuthProviderConfig } from '@magemetrics/core';
-import { FetchNextPageOptions } from '@tanstack/react-query';
-import { ForwardRefExoticComponent } from 'react';
-import { InfiniteData } from '@tanstack/react-query';
-import { InfiniteQueryObserverResult } from '@tanstack/react-query';
-import { JSX } from 'react/jsx-runtime';
-import { MageMetricsClient } from '@magemetrics/core';
-import { MageMetricsClientConfig } from '@magemetrics/core';
-import { PropsWithChildren } from 'react';
-import { QueryObserverResult } from '@tanstack/react-query';
-import { RefAttributes } from 'react';
-import { RefetchOptions } from '@tanstack/react-query';
-import { SortingState as SortingState_2 } from '@tanstack/react-table';
-import { UseMutateAsyncFunction } from '@tanstack/react-query';
-import { UseMutateFunction } from '@tanstack/react-query';
-import { UseMutationOptions } from '@tanstack/react-query';
-import { UseQueryOptions } from '@tanstack/react-query';
-import { UseQueryResult } from '@tanstack/react-query';
-import { z } from 'zod';
-
-/**
- * Appearance configuration for visual customization of the `@magemetrics/ai` package.
- */
-export declare type AppearanceConfig = {
-    /**
-     * Brand colors used throughout the UI (buttons, accents, interactive elements).
-     */
-    colors?: BrandColors;
-    /**
-     * Modal-specific appearance settings.
-     */
-    modal?: ModalAppearance;
-};
-
-declare type AssemblyAIMicrophoneController = {
-    status: "idle" | "starting" | "recording";
-    startRecording: (onTranscript: (text: string) => void) => Promise<void>;
-    stopRecording: () => Promise<void>;
-};
-
-export { AuthProvider }
-
-export { AuthState }
-
-/**
- * Brand colors configuration for the appearance prop.
- */
-export declare type BrandColors = PrimaryColorOption & SecondaryColorOption;
-
-/**
- * A standalone authenticated Canvas component that renders a canvas by its ID.
- * This is useful for displaying saved canvases without the chat interface.
- * @param root0 props for the component
- * @param root0.canvasId The UUID of the canvas to display
- * @returns the canvas component
- * @example
- * ```tsx
- * import { Canvas } from "@magemetrics/ai";
- *
- * const SavedCanvasView = ({ canvasId }: { canvasId: string }) => {
- *   return <Canvas canvasId={canvasId} />;
- * };
- * ```
- */
-export declare const Canvas: React.FC<{
-    canvasId: string;
-}>;
-
-export declare type CellContentProps = {
-    formattedValue: FormattedData | undefined;
-    unit?: string;
-    renderType?: string;
-};
-
-export declare const Chat: React.FC<PublicChatProps>;
-
-declare const Chat_2: ChatComponent;
-
-declare interface ChatComponent extends default_2.MemoExoticComponent<(props: ChatProps) => default_2.JSX.Element> {
-    Messages: typeof MessagesContainer;
-    Input: typeof InputContainer & {
-        Default: typeof ChatInputDefault;
-    };
-}
-
-export declare interface ChatContextValue {
-    flowId: string | undefined | null;
-    enableSpeechToText?: boolean;
-}
-
-/**
- * Optional provider that allows the host application to pass dynamic runtime hints
- * to the chat. The hints are sent with every message and injected ephemerally into
- * the LLM prompt — they are not persisted or shown in the UI.
- * Place this anywhere inside `MageMetricsContextProvider` and around the `Chat` component.
- * When the `value` prop changes, the next message sent will carry the updated hints.
- * If this provider is not used, no hints are sent — everything works as before.
- * @param props - The provider props
- * @param props.value - The chat hints value to provide
- * @param props.children - The child components
- * @returns The provider component wrapping children
- */
-export declare const ChatHintsProvider: default_2.FC<ChatHintsProviderProps>;
-
-declare interface ChatHintsProviderProps {
-    /**
-     * Arbitrary key-value hints from the host application.
-     * These are sent alongside every chat message and injected into the LLM prompt.
-     * @example
-     * ```tsx
-     * <ChatHintsProvider value={{
-     *   selectedLocation: { lat: 48.8566, lng: 2.3522, name: "Paris" },
-     *   activeFilters: ["revenue > 1M"],
-     * }}>
-     *   <Chat flowId="..." />
-     * </ChatHintsProvider>
-     * ```
-     */
-    value: ChatHintsValue;
-    children: default_2.ReactNode;
-}
-
-/**
- * The value type for chat hints — a free-form key-value object
- * that the host application can use to pass runtime information to the LLM.
- * These hints are injected ephemerally into each chat message (not persisted)
- * so the LLM is aware of the host application's current state.
- */
-export declare type ChatHintsValue = Record<string, unknown>;
-
-export declare interface ChatInputContextValue {
-    flowId: string | undefined;
-    isLoading: boolean;
-    isStreaming: boolean;
-    isError: boolean;
-    isAwaitingUserAnswer: boolean;
-    onRetry?: () => void;
-    onStop?: () => void;
-    sendMessage: (text: string, isEditing: boolean) => void;
-    lastUserMessage?: string;
-    enableSpeechToText?: boolean;
-}
-
-declare const ChatInputDefault: default_2.FC;
-
-declare interface ChatProps {
-    flowId: string | undefined | null;
-    enableSpeechToText?: boolean;
-    children?: default_2.ReactNode;
-}
-
-declare interface ColumnSort {
-    desc: boolean;
-    id: string;
-}
-
-export declare interface Components {
-    dataTableCells?: {
-        empty?: (props: CellContentProps) => default_2.ReactNode;
-        units?: {
-            [key: string]: (props: CellContentProps) => default_2.ReactNode;
-        };
-        renderTypes?: {
-            [key: string]: (props: CellContentProps) => default_2.ReactNode;
-        };
-    };
-    dataReportTable?: (props: {
-        report: Report_2;
-    }) => default_2.ReactNode;
-    dataReportMessageActions?: (props: {
-        report: Report_2;
-        isSelected: boolean;
-    }) => default_2.ReactNode;
-    visualizationMessageActions?: (props: {
-        visualization: FrontendVisualization | V1FrontendVisualization;
-        isSelected: boolean;
-    }) => default_2.ReactNode;
-    dataReportPanelActions?: (props: {
-        report: Report_2;
-    }) => default_2.ReactNode;
-    visualizationPanelActions?: (props: {
-        visualization: FrontendVisualization | V1FrontendVisualization;
-    }) => default_2.ReactNode;
-    avatar?: default_2.ReactNode;
-    getCanvasShareableLink?: (canvasId: string) => string;
-    canvasPanelActions?: (props: {
-        canvas: FrontendCanvas;
-        flowId: string;
-    }) => default_2.ReactNode;
-}
-
-export declare const ConfigurableChat: ConfigurableChatComponent;
-
-declare interface ConfigurableChatComponent extends default_2.FC<ConfigurableChatComponentProps> {
-    Messages: typeof Chat_2.Messages;
-    Input: typeof Chat_2.Input;
-}
-
-declare type ConfigurableChatComponentProps = {
-    flowId: string | undefined | null;
-    enableSpeechToText?: boolean;
-    disableCanvas?: boolean;
-    children?: default_2.ReactNode;
-    /**
-     * Appearance configuration for customizing the visual style.
-     * Includes brand colors and modal-specific styling options.
-     */
-    appearance?: AppearanceConfig;
-};
-
-/** @deprecated This type is no longer used and will be removed in a future version. */
-declare type ControlledModalProps = {
-    visible: boolean;
-    onClose: () => void;
-};
-
-declare interface ConversationContentProps {
-    flowId?: string;
-    className?: string;
-    style?: React.CSSProperties;
-    topBar?: React.ReactNode;
-    disableCanvas?: boolean;
-    enableSpeechToText?: boolean;
-    children?: React.ReactNode;
-}
-
-export { CreateFlowParam }
-
-export declare const DataTable: () => JSX.Element;
-
-declare type DataTableState = {
-    pageIndex?: number;
-    sorting?: SortingState;
-    filters?: TableFilters;
-    pageSize?: number;
-};
-
-export { DirectAuthProvider }
-
-declare type DisplayControlProps = {
-    /** Whether to display the recommendations section when the input is active */
-    showRecommendations?: boolean;
-    /** Whether to display recent chats when the input is active */
-    showRecentChats?: boolean;
-    /** Whether to display a backdrop overlay when the input is active */
-    showBackdrop?: boolean;
-};
-
-export declare const DomWrapper: React.FC<PropsWithChildren<DomWrapperProps>>;
-
-declare type DomWrapperProps = InternalColorSwatchProps;
-
-declare type ExportReportDataParams = {
-    reportId: number;
-    filename?: string;
-    format?: "text" | "blob";
-};
-
-declare type ExportReportDataResult = {
-    filename: string;
-    data: Blob | string;
-};
-
-export { ExternalAuthProvider }
-
-export { ExternalAuthProviderConfig }
-
-/**
- * This module handles the formatting and normalization of table cell values for display and sorting.
- *
- * Problem:
- * When displaying data in tables, we often receive values in various formats (strings, dates,
- * JSON objects, etc.). We need to:
- * 1. Display these values in a consistent, human-readable format
- * 2. Enable proper sorting of these values regardless of their original format
- *
- * Solution:
- * The FormattedData type and formatCellValue function transform any input value into a
- * standardized format with two properties:
- * - display: A string representation suitable for rendering
- * - sortValue: A normalized value (string/number/date) suitable for consistent sorting
- *
- * The module handles various special cases:
- * - JSON strings (parsing them to extract actual values)
- * - Date/time values (converting to consistent format)
- * - BigQuery-style objects with 'value' property
- * - Nested objects (pretty-printing them)
- * - Null/undefined values
- */
-declare type FormattedData = {
-    display: (string & {}) | "empty" | null;
-    sortValue: string | number | Date | null;
-};
-
-declare type FrontendCanvas = z.infer<typeof FrontendCanvasSchema>;
-
-declare const FrontendCanvasSchema: z.ZodObject<{
-    title: z.ZodNullable<z.ZodString>;
-    id: z.ZodUUID;
-    nodes: z.ZodArray<z.ZodAny>;
-    edges: z.ZodArray<z.ZodAny>;
-    is_public: z.ZodBoolean;
-}, z.core.$strip>;
-
-declare const FrontendReportSchema: z.ZodObject<{
-    status: z.ZodNullable<z.ZodString>;
-    title: z.ZodString;
-    id: z.ZodNumber;
-    request: z.ZodNullable<z.ZodString>;
-    created_at: z.ZodString;
-    data_summary: z.ZodObject<{
-        columns: z.ZodRecord<z.ZodString, z.ZodObject<{
-            position: z.ZodOptional<z.ZodNumber>;
-            data_type: z.ZodString;
-            null_count: z.ZodNullable<z.ZodNumber>;
-            unique_count: z.ZodNullable<z.ZodNumber>;
-            unique_percentage: z.ZodNullable<z.ZodNumber>;
-            min_value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-            max_value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-            avg_value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-            median_value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-            std_value: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-            min_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            max_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            min_length: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-            max_length: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-            avg_length: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        }, z.core.$loose>>;
-    }, z.core.$loose>;
-    flow_id: z.ZodString;
-    is_removed: z.ZodBoolean;
-    is_materialized: z.ZodNullable<z.ZodBoolean>;
-    last_materialized_at: z.ZodNullable<z.ZodString>;
-    materialized_error_message: z.ZodNullable<z.ZodString>;
-    materialized_status: z.ZodNullable<z.ZodEnum<{
-        completed: "completed";
-        failed: "failed";
-        running: "running";
-    }>>;
-}, z.core.$strip>;
-
-declare type FrontendVisualization = z.output<typeof FrontendVisualizationSchema>;
-
-declare const FrontendVisualizationSchema: z.ZodObject<{
-    id: z.ZodNumber;
-    configuration: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        config_version: z.ZodLiteral<2>;
-        xAxisLabel: z.ZodString;
-        yAxisLabel: z.ZodString;
-        categoryColumn: z.ZodString;
-        secondaryCategoryColumn: z.ZodOptional<z.ZodString>;
-        valueColumn: z.ZodString;
-        title: z.ZodString;
-        type: z.ZodLiteral<"bar">;
-    }, z.core.$strip>, z.ZodObject<{
-        xAxisColumn: z.ZodString;
-        valueColumns: z.ZodArray<z.ZodString>;
-        yAxisLabels: z.ZodArray<z.ZodString>;
-        title: z.ZodString;
-        type: z.ZodLiteral<"line/area">;
-        config_version: z.ZodLiteral<2>;
-    }, z.core.$strip>, z.ZodObject<{
-        config_version: z.ZodLiteral<2>;
-        valueColumn: z.ZodString;
-        xAxisColumn: z.ZodString;
-        xAxisLabel: z.ZodString;
-        yAxisLabel: z.ZodString;
-        categoryColumn: z.ZodString;
-        title: z.ZodString;
-        type: z.ZodLiteral<"line/area-categorical">;
-    }, z.core.$strip>, z.ZodObject<{
-        config_version: z.ZodLiteral<2>;
-        xAxisLabel: z.ZodString;
-        yAxisLabel: z.ZodString;
-        xAxisValueColumn: z.ZodString;
-        yAxisValueColumn: z.ZodString;
-        title: z.ZodString;
-        type: z.ZodLiteral<"scatter">;
-    }, z.core.$strip>, z.ZodObject<{
-        config_version: z.ZodLiteral<2>;
-        categoryColumn: z.ZodString;
-        valueColumn: z.ZodString;
-        title: z.ZodString;
-        type: z.ZodLiteral<"pie">;
-    }, z.core.$strip>], "type">;
-    created_at: z.ZodString;
-    flow_data: z.ZodOptional<z.ZodObject<{
-        is_materialized: z.ZodNullable<z.ZodBoolean>;
-        last_materialized_at: z.ZodNullable<z.ZodString>;
-        materialized_error_message: z.ZodNullable<z.ZodString>;
-        materialized_status: z.ZodNullable<z.ZodEnum<{
-            completed: "completed";
-            failed: "failed";
-            running: "running";
-        }>>;
-    }, z.core.$strip>>;
-    flow_data_id: z.ZodNumber;
-}, z.core.$strip>;
-
-declare const InputContainer: default_2.FC<{
-    children?: default_2.ReactNode | ((context: ChatInputContextValue) => default_2.ReactNode);
-}>;
-
-/**
- * Internal/relaxed type for passing color props through component trees.
- * Use this for internal components; use ColorSwatchOptions for external APIs.
- */
-declare type InternalColorSwatchProps = {
-    primaryColor?: string;
-    primarySwatch?: PrimaryColorSwatch;
-    secondaryColor?: string;
-    secondarySwatch?: SecondaryColorSwatch;
-};
-
-export declare const logout: () => void;
-
-export { MageMetricsClient }
-
-export { MageMetricsClientConfig }
-
-export declare const MageMetricsContextProvider: default_2.FC<MageMetricsContextProviderProps>;
-
-export declare type MageMetricsContextProviderProps = {
-    children: default_2.ReactNode;
-    components?: Components;
-} & ({
-    /** Provide an external MageMetricsClient instance. */
-    client: MageMetricsClient;
-    apiKey?: never;
-    apiUrl?: never;
-    externalJwt?: never;
-    additionalHeaders?: never;
-    applicationName?: never;
-} | ({
-    /** Configuration to create a new MageMetricsClient. */
-    client?: never;
-} & MageMetricsClientConfig));
-
-export declare const MageMetricsPublicContextProvider: React.FC<MageMetricsPublicContextProviderProps>;
-
-declare type MageMetricsPublicContextProviderProps = PropsWithChildren<Pick<MageMetricsClientConfig, "apiUrl" | "apiKey"> & {
-    components?: Components;
-}>;
-
-export declare const ManagedModal: React.FC<ManagedModalProps>;
-
-declare type ManagedModalBaseProps = ModalProps & {
-    /** API key for authenticating with the MageMetrics service */
-    apiKey: string;
-    /** External JWT token for user authentication */
-    externalJwt: string;
-    /** Base URL for the MageMetrics API */
-    apiUrl: string;
-    /** Whether to disable canvas functionality in conversations */
-    disableCanvas?: boolean;
-    /** Whether to render data freshness info in the conversation header */
-    showDataFreshness?: boolean;
-    /** Where to persist modal state (localStorage, queryParam, or none) */
-    persist?: PersistenceOptions;
-    /** Custom component overrides for extending functionality */
-    components?: Components;
-    /** Application name to associate with flows created through this modal */
-    applicationName?: string;
-    /**
-     * Appearance configuration for customizing the visual style.
-     * Includes brand colors and modal-specific styling options.
-     */
-    appearance?: AppearanceConfig;
-    /** Callbacks for various events */
-    callbacks?: {
-        /** Callback fired when the conversation modal is opened */
-        onConversationOpen?: () => void;
-    };
-};
-
-/**
- * Props for ManagedModal component.
- */
-declare type ManagedModalProps = ManagedModalBaseProps;
-
-declare const MessagesContainer: default_2.FC;
-
-/**
- * Modal-specific appearance configuration.
- */
-export declare type ModalAppearance = {
-    /**
-     * Primary color for modal background gradient.
-     * Used to customize the mesh gradient background in conversation modals.
-     * Can be any CSS color (hex, rgb, hsl, oklch, etc.).
-     */
-    backgroundPrimary?: string;
-};
-
-declare interface ModalProps {
-    /**
-     * @deprecated This prop is no longer used and will be removed in a future version.
-     * Control modal visibility and close behavior externally
-     */
-    modal?: ControlledModalProps;
-    /** Configuration options for the start modal (chat launcher, recommendations, etc.) */
-    startOptions?: StartOptions;
-}
-
-declare type PersistenceOptions = "queryParam" | "none";
-
-/**
- * Primary color shade stops used in the UI.
- */
-declare const PRIMARY_SHADE_STOPS: readonly ["50", "400", "500", "600", "650", "750", "900"];
-
-/**
- * Primary color options - mutually exclusive: use either primaryColor OR primarySwatch, not both.
- */
-declare type PrimaryColorOption = {
-    primaryColor: string;
-    primarySwatch?: never;
-} | {
-    primaryColor?: never;
-    primarySwatch: PrimaryColorSwatch;
-} | {
-    primaryColor?: never;
-    primarySwatch?: never;
-};
-
-declare type PrimaryColorShade = (typeof PRIMARY_SHADE_STOPS)[number];
-
-/** Complete primary swatch (7 shades required) */
-export declare type PrimaryColorSwatch = Record<PrimaryColorShade, string>;
-
-export declare const PublicCanvas: React.FC<React.ComponentProps<typeof PublicCanvasPanel>>;
-
-declare const PublicCanvasPanel: default_2.FC<{
-    canvasId: string;
-}>;
-
-export declare type PublicChatProps = Omit<ConversationContentProps, "children"> & {
-    /**
-     * Appearance configuration for customizing the visual style.
-     * Includes brand colors and modal-specific styling options.
-     */
-    appearance?: AppearanceConfig;
-};
-
-declare type Report_2 = z.infer<typeof FrontendReportSchema>;
-export { Report_2 as Report }
-
-declare type ReportDataFilters = {
-    columns?: string[];
-    limit: number;
-    sorting: SortingState;
-    filters: TableFilters;
-    cursor?: number;
-};
-
-/**
- * Secondary color shade stops used in the UI.
- */
-declare const SECONDARY_SHADE_STOPS: readonly ["500", "600", "700"];
-
-/**
- * Secondary color options - mutually exclusive: use either secondaryColor OR secondarySwatch, not both.
- */
-declare type SecondaryColorOption = {
-    secondaryColor: string;
-    secondarySwatch?: never;
-} | {
-    secondaryColor?: never;
-    secondarySwatch: SecondaryColorSwatch;
-} | {
-    secondaryColor?: never;
-    secondarySwatch?: never;
-};
-
-declare type SecondaryColorShade = (typeof SECONDARY_SHADE_STOPS)[number];
-
-/** Complete secondary swatch (3 shades required) */
-export declare type SecondaryColorSwatch = Record<SecondaryColorShade, string>;
-
-declare type SortingState = ColumnSort[];
-
-export declare const StandaloneConversationModal: default_2.FC<StandaloneConversationModalProps>;
-
-declare type StandaloneConversationModalProps = {
-    opened: boolean;
-    flowId: string;
-    disableCanvas?: boolean;
-    showDataFreshness?: boolean;
-    onOpenChange?: (open: boolean) => void;
-    appearance?: AppearanceConfig;
-};
-
-/**
- * This component is not bounded in height and must be wrapped in a container to properly work
- * @param props - props
- * @param props.report - The report to display
- * @param props.initialState - Initial state for the report
- * @param props.onStateChange - Callback function to handle state changes
- * @returns JSX.Element
- */
-export declare const StandaloneDataTable: React.FC<{
-    report: Report_2;
-    initialState?: DataTableState;
-    onStateChange?: (state: DataTableState) => void;
-}>;
-
-declare type StartOptions = DisplayControlProps & {
-    /** Label text displayed above the chat launcher input */
-    label?: string;
-    /** Label text displayed above the recommendations section */
-    recommendationsLabel?: string;
-    /** Whether the chat launcher input should auto-focus on mount */
-    autoFocus?: boolean;
-    /** Whether speech-to-text controls should be shown */
-    enableSpeechToText?: boolean;
-};
-
-declare type TableFilters = Record<string, TableFilterValue>;
-
-declare type TableFilterValue = z.infer<typeof TableFilterValueSchema>;
-
-declare const TableFilterValueSchema: z.ZodObject<{
-    operator: z.ZodEnum<{
-        contains: "contains";
-        eq: "eq";
-        gt: "gt";
-        gte: "gte";
-        lt: "lt";
-        lte: "lte";
-        endsWith: "endsWith";
-        startsWith: "startsWith";
-        neq: "neq";
-        regex: "regex";
-        between: "between";
-    }>;
-    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>]>;
-}, z.core.$strip>;
-
-/**
- * Hook to fetch a canvas by its ID.
- * @param canvasId - The UUID of the canvas to fetch
- * @param options - Optional react-query options
- * @returns Query result with the canvas data
- * @example
- * ```tsx
- * const { data: canvas, isLoading } = useCanvas(canvasId);
- * if (canvas) {
- *   console.log(canvas.title, canvas.is_public);
- * }
- * ```
- */
-export declare const useCanvas: (canvasId: string | undefined | null, options?: Omit<UseQueryOptions<FrontendCanvas, unknown>, "queryKey" | "queryFn">) => UseQueryResult<    {
-    title: string | null;
-    id: string;
-    nodes: any[];
-    edges: any[];
-    is_public: boolean;
-}, unknown>;
-
-export declare const useChatContext: () => ChatContextValue;
-
-/**
- * Returns the current chat hints value, or `null` if no `ChatHintsProvider` is present.
- * @returns The current chat hints value or null
- */
-export declare const useChatHints: () => ChatHintsValue | null;
-
-export declare const useChatInputContext: () => ChatInputContextValue;
-
-export declare const useCreateFlow: (options?: UseMutationOptions<{
-    flowId: string;
-}, Error, CreateFlowParam>) => {
-    createFlow: UseMutateFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    createFlowAsync: UseMutateAsyncFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    isCreatingFlow: boolean;
-    data: undefined;
-    variables: undefined;
-    error: null;
-    isError: false;
-    isIdle: true;
-    isPending: false;
-    isSuccess: false;
-    status: "idle";
-    mutate: UseMutateFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    reset: () => void;
-    context: unknown;
-    failureCount: number;
-    failureReason: Error | null;
-    isPaused: boolean;
-    submittedAt: number;
-    mutateAsync: UseMutateAsyncFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-} | {
-    createFlow: UseMutateFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    createFlowAsync: UseMutateAsyncFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    isCreatingFlow: boolean;
-    data: undefined;
-    variables: CreateFlowParam;
-    error: null;
-    isError: false;
-    isIdle: false;
-    isPending: true;
-    isSuccess: false;
-    status: "pending";
-    mutate: UseMutateFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    reset: () => void;
-    context: unknown;
-    failureCount: number;
-    failureReason: Error | null;
-    isPaused: boolean;
-    submittedAt: number;
-    mutateAsync: UseMutateAsyncFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-} | {
-    createFlow: UseMutateFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    createFlowAsync: UseMutateAsyncFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    isCreatingFlow: boolean;
-    data: undefined;
-    error: Error;
-    variables: CreateFlowParam;
-    isError: true;
-    isIdle: false;
-    isPending: false;
-    isSuccess: false;
-    status: "error";
-    mutate: UseMutateFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    reset: () => void;
-    context: unknown;
-    failureCount: number;
-    failureReason: Error | null;
-    isPaused: boolean;
-    submittedAt: number;
-    mutateAsync: UseMutateAsyncFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-} | {
-    createFlow: UseMutateFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    createFlowAsync: UseMutateAsyncFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    isCreatingFlow: boolean;
-    data: {
-        flowId: string;
-    };
-    error: null;
-    variables: CreateFlowParam;
-    isError: false;
-    isIdle: false;
-    isPending: false;
-    isSuccess: true;
-    status: "success";
-    mutate: UseMutateFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-    reset: () => void;
-    context: unknown;
-    failureCount: number;
-    failureReason: Error | null;
-    isPaused: boolean;
-    submittedAt: number;
-    mutateAsync: UseMutateAsyncFunction<    {
-        flowId: string;
-    }, Error, CreateFlowParam, unknown>;
-};
-
-export declare const useDataReportColumnValue: (reportId: number, filters: ReportDataFilters) => UseQueryResult<    {
-    [x: string]: unknown;
-}[], Error>;
-
-export declare const useDataTableContext: () => {
-    report: {
-        status: string | null;
-        title: string;
-        id: number;
-        request: string | null;
-        created_at: string;
-        data_summary: {
-            [x: string]: unknown;
-            columns: Record<string, {
-                [x: string]: unknown;
-                data_type: string;
-                null_count: number | null;
-                unique_count: number | null;
-                unique_percentage: number | null;
-                position?: number | undefined;
-                min_value?: number | null | undefined;
-                max_value?: number | null | undefined;
-                avg_value?: number | null | undefined;
-                median_value?: number | null | undefined;
-                std_value?: number | null | undefined;
-                min_date?: string | null | undefined;
-                max_date?: string | null | undefined;
-                min_length?: number | null | undefined;
-                max_length?: number | null | undefined;
-                avg_length?: number | null | undefined;
-            }>;
-        };
-        flow_id: string;
-        is_removed: boolean;
-        is_materialized: boolean | null;
-        last_materialized_at: string | null;
-        materialized_error_message: string | null;
-        materialized_status: "completed" | "running" | "failed" | null;
-    };
-    fetchNextPage: (options?: FetchNextPageOptions) => Promise<InfiniteQueryObserverResult<InfiniteData<    {
-        [x: string]: unknown;
-    }[], unknown>, Error>>;
-    pages: {
-        [x: string]: unknown;
-    }[][] | undefined;
-    columns: {
-        name: string;
-        data_type: string;
-        dataType: string;
-        renderType?: string | undefined;
-        unit?: string | undefined;
-        canonicalDataType?: "numeric" | "boolean" | "datetime" | "text" | "array" | "json" | "other" | undefined;
-    }[] | undefined;
-    isPendingColumns: boolean;
-    hasMoreData: boolean;
-    isFetching: boolean;
-    isPendingData: boolean;
-    totalRows: number | undefined;
-    totalPages: number | undefined;
-    sorting: SortingState_2;
-    filters: TableFilters;
-};
-
-export declare const useDownloadReportData: (options?: UseMutationOptions<ExportReportDataResult, Error, ExportReportDataParams>) => {
-    download: UseMutateFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-    data: undefined;
-    variables: undefined;
-    error: null;
-    isError: false;
-    isIdle: true;
-    isPending: false;
-    isSuccess: false;
-    status: "idle";
-    mutate: UseMutateFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-    reset: () => void;
-    context: unknown;
-    failureCount: number;
-    failureReason: Error | null;
-    isPaused: boolean;
-    submittedAt: number;
-    mutateAsync: UseMutateAsyncFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-} | {
-    download: UseMutateFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-    data: undefined;
-    variables: ExportReportDataParams;
-    error: null;
-    isError: false;
-    isIdle: false;
-    isPending: true;
-    isSuccess: false;
-    status: "pending";
-    mutate: UseMutateFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-    reset: () => void;
-    context: unknown;
-    failureCount: number;
-    failureReason: Error | null;
-    isPaused: boolean;
-    submittedAt: number;
-    mutateAsync: UseMutateAsyncFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-} | {
-    download: UseMutateFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-    data: undefined;
-    error: Error;
-    variables: ExportReportDataParams;
-    isError: true;
-    isIdle: false;
-    isPending: false;
-    isSuccess: false;
-    status: "error";
-    mutate: UseMutateFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-    reset: () => void;
-    context: unknown;
-    failureCount: number;
-    failureReason: Error | null;
-    isPaused: boolean;
-    submittedAt: number;
-    mutateAsync: UseMutateAsyncFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-} | {
-    download: UseMutateFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-    data: ExportReportDataResult;
-    error: null;
-    variables: ExportReportDataParams;
-    isError: false;
-    isIdle: false;
-    isPending: false;
-    isSuccess: true;
-    status: "success";
-    mutate: UseMutateFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-    reset: () => void;
-    context: unknown;
-    failureCount: number;
-    failureReason: Error | null;
-    isPaused: boolean;
-    submittedAt: number;
-    mutateAsync: UseMutateAsyncFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
-};
-
-export declare const useMageMetricsApiUrl: () => string;
-
-export declare const useMageMetricsClient: () => MageMetricsClient;
-
-export declare const useMageMetricsReady: () => false | MageMetricsClient;
-
-export declare const useRecentFlows: (limit?: number) => UseQueryResult<    {
-    title: string | null;
-    id: string;
-    request: string;
-    created_at: string;
-    user_id: string | null;
-    application_id?: number | null | undefined;
-}[], Error>;
-
-export declare const useReport: (reportId: number) => {
-    data: {
-        created_at: string;
-        flow_id: string;
-        id: number;
-        title: string;
-        request: string | null;
-        data_summary: {
-            [x: string]: unknown;
-            columns: {
-                [x: string]: {
-                    [x: string]: unknown;
-                    position?: number | undefined;
-                    data_type: string;
-                    null_count: number | null;
-                    unique_count: number | null;
-                    unique_percentage: number | null;
-                    min_value?: number | null | undefined;
-                    max_value?: number | null | undefined;
-                    avg_value?: number | null | undefined;
-                    median_value?: number | null | undefined;
-                    std_value?: number | null | undefined;
-                    min_date?: string | null | undefined;
-                    max_date?: string | null | undefined;
-                    min_length?: number | null | undefined;
-                    max_length?: number | null | undefined;
-                    avg_length?: number | null | undefined;
-                };
-            };
-        };
-        status: string | null;
-        is_removed: boolean;
-        is_materialized: boolean | null;
-        last_materialized_at: string | null;
-        materialized_error_message: string | null;
-        materialized_status: "completed" | "running" | "failed" | null;
-    } | null | undefined;
-    isLoading: boolean;
-    error: Error | null;
-    isError: boolean;
-    isSuccess: boolean;
-    refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<    {
-        created_at: string;
-        flow_id: string;
-        id: number;
-        title: string;
-        request: string | null;
-        data_summary: {
-            [x: string]: unknown;
-            columns: {
-                [x: string]: {
-                    [x: string]: unknown;
-                    position?: number | undefined;
-                    data_type: string;
-                    null_count: number | null;
-                    unique_count: number | null;
-                    unique_percentage: number | null;
-                    min_value?: number | null | undefined;
-                    max_value?: number | null | undefined;
-                    avg_value?: number | null | undefined;
-                    median_value?: number | null | undefined;
-                    std_value?: number | null | undefined;
-                    min_date?: string | null | undefined;
-                    max_date?: string | null | undefined;
-                    min_length?: number | null | undefined;
-                    max_length?: number | null | undefined;
-                    avg_length?: number | null | undefined;
-                };
-            };
-        };
-        status: string | null;
-        is_removed: boolean;
-        is_materialized: boolean | null;
-        last_materialized_at: string | null;
-        materialized_error_message: string | null;
-        materialized_status: "completed" | "running" | "failed" | null;
-    } | null, Error>>;
-    isRefetching: boolean;
-    isFetching: boolean;
-};
-
-export declare const useSpeechToText: () => AssemblyAIMicrophoneController;
-
-declare type V1FrontendVisualization = z.output<typeof V1FrontendVisualizationSchema>;
-
-declare const V1FrontendVisualizationSchema: z.ZodObject<{
-    id: z.ZodNumber;
-    configuration: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        xAxisLabel: z.ZodString;
-        yAxisLabel: z.ZodString;
-        xAxisDataKey: z.ZodOptional<z.ZodString>;
-        yAxisDataKey: z.ZodOptional<z.ZodString>;
-        dimensionDataKey: z.ZodOptional<z.ZodString>;
-        valueColumns: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        title: z.ZodString;
-        type: z.ZodLiteral<"bar">;
-    }, z.core.$strip>, z.ZodObject<{
-        xAxisLabel: z.ZodString;
-        yAxisLabel: z.ZodString;
-        xAxisDataKey: z.ZodOptional<z.ZodString>;
-        yAxisDataKey: z.ZodOptional<z.ZodString>;
-        dimensionDataKey: z.ZodOptional<z.ZodString>;
-        valueColumns: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        title: z.ZodString;
-        type: z.ZodLiteral<"line/area">;
-    }, z.core.$strip>, z.ZodObject<{
-        xAxisLabel: z.ZodString;
-        yAxisLabel: z.ZodString;
-        xAxisDataKey: z.ZodOptional<z.ZodString>;
-        yAxisDataKey: z.ZodOptional<z.ZodString>;
-        dimensionDataKey: z.ZodOptional<z.ZodString>;
-        valueColumns: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        title: z.ZodString;
-        type: z.ZodLiteral<"scatter">;
-    }, z.core.$strip>, z.ZodObject<{
-        nameKey: z.ZodString;
-        dataKey: z.ZodString;
-        title: z.ZodString;
-        type: z.ZodLiteral<"pie">;
-    }, z.core.$strip>], "type">;
-    created_at: z.ZodString;
-    flow_data: z.ZodOptional<z.ZodObject<{
-        is_materialized: z.ZodNullable<z.ZodBoolean>;
-        last_materialized_at: z.ZodNullable<z.ZodString>;
-        materialized_error_message: z.ZodNullable<z.ZodString>;
-        materialized_status: z.ZodNullable<z.ZodEnum<{
-            completed: "completed";
-            failed: "failed";
-            running: "running";
-        }>>;
-    }, z.core.$strip>>;
-    flow_data_id: z.ZodNumber;
-}, z.core.$strip>;
-
-export declare const Visualization: ForwardRefExoticComponent<    {
-    visualizationId: number;
-    withTitle: boolean;
-    exportingEnabled?: boolean;
-} & RefAttributes<HTMLDivElement>>;
-
-export declare type WebComponentManagedModalProps = ManagedModalProps & {
-    enableCsvDownload: boolean;
-};
-
-export { }
+/**
+ * Hand-written type declarations for the `@magemetrics/ai/web-component` entry point.
+ *
+ * WHY THIS FILE EXISTS:
+ * `vite-plugin-dts` with `rollupTypes: true` determines the api-extractor entry
+ * from `package.json` `exports["."].types`, which always resolves to the React
+ * entry's `.d.ts`. When the web-component build runs, it rolls up the React types
+ * instead of the web-component types. This is a known limitation when a single
+ * package.json serves multiple build entry points.
+ *
+ * MAINTENANCE:
+ * This file must be kept in sync with `src/web-component.tsx` exports.
+ * If you add, remove, or change exports in `web-component.tsx`, update this file.
+ */
+
+/** Registers the `<magemetrics-ai>` custom element. Safe to call multiple times. */
+export declare const createMagemetrics: () => void;
+
+/** Clears stored authentication tokens from localStorage. */
+export declare const logout: () => void;
+
+// ---------------------------------------------------------------------------
+// Props & element types
+// ---------------------------------------------------------------------------
+
+/**
+ * Appearance configuration for visual customization.
+ */
+export interface AppearanceConfig {
+  colors?: BrandColors;
+  modal?: ModalAppearance;
+}
+
+export interface ModalAppearance {
+  backgroundPrimary?: string;
+}
+
+export type BrandColors = PrimaryColorOption & SecondaryColorOption;
+
+type PrimaryColorOption =
+  | { primaryColor: string; primarySwatch?: never }
+  | { primaryColor?: never; primarySwatch: PrimaryColorSwatch }
+  | { primaryColor?: never; primarySwatch?: never };
+
+type SecondaryColorOption =
+  | { secondaryColor: string; secondarySwatch?: never }
+  | { secondaryColor?: never; secondarySwatch: SecondaryColorSwatch }
+  | { secondaryColor?: never; secondarySwatch?: never };
+
+type PrimaryColorSwatch = Record<
+  "50" | "400" | "500" | "600" | "650" | "750" | "900",
+  string
+>;
+type SecondaryColorSwatch = Record<"500" | "600" | "700", string>;
+
+/**
+ * Configuration options for the start modal (chat launcher, recommendations, etc.).
+ */
+export interface StartOptions {
+  showRecommendations?: boolean;
+  showRecentChats?: boolean;
+  showBackdrop?: boolean;
+  label?: string;
+  recommendationsLabel?: string;
+  autoFocus?: boolean;
+  enableSpeechToText?: boolean;
+}
+
+type PersistenceOptions = "queryParam" | "none";
+
+/**
+ * Props accepted by the `<magemetrics-ai>` web component.
+ *
+ * Extends the standalone managed-modal props with `enableCsvDownload`.
+ * Only the props listed in the `r2wc` definition are settable as HTML attributes.
+ */
+export interface WebComponentManagedModalProps {
+  /** API key for authenticating with the MageMetrics service. */
+  apiKey: string;
+  /** External JWT token for user authentication. */
+  externalJwt: string;
+  /** Base URL for the MageMetrics API. */
+  apiUrl: string;
+  /** Where to persist modal state. */
+  persist?: PersistenceOptions;
+  /** Configuration options for the start modal. */
+  startOptions?: StartOptions;
+  /** Whether to enable CSV download for data reports. */
+  enableCsvDownload: boolean;
+  /** Whether to render data freshness info in the conversation header. */
+  showDataFreshness?: boolean;
+  /** Application name to associate with flows created through this modal. */
+  applicationName?: string;
+  /**
+   * Appearance configuration for customizing the visual style.
+   */
+  appearance?: AppearanceConfig;
+}
+
+/**
+ * The `<magemetrics-ai>` custom element, typed for `querySelector` usage.
+ *
+ * @example
+ * ```ts
+ * const el = document.querySelector("magemetrics-ai") as SearchElement;
+ * el.apiKey = "...";
+ * ```
+ */
+export type SearchElement = HTMLElement & WebComponentManagedModalProps;
+
+// ---------------------------------------------------------------------------
+// JSX augmentation — enables `<magemetrics-ai .../>` in TSX files
+// ---------------------------------------------------------------------------
+
+declare module "react" {
+  namespace JSX {
+    interface IntrinsicElements {
+      "magemetrics-ai": WebComponentManagedModalProps;
+    }
+  }
+}