@magemetrics/ai 0.10.0 → 0.11.1

package/dist/react/index.d.ts

@@ -1,8 +1,5 @@
 import { AuthProvider } from '@magemetrics/core';
 import { AuthState } from '@magemetrics/core';
-import { Components } from './shared/context/MageMetricsContext';
-import { Components as Components_2 } from '../shared/context/MageMetricsContext';
-import { Components as Components_3 } from './MageMetricsContext';
 import { CreateFlowParam } from '@magemetrics/core';
 import { default as default_2 } from 'react';
 import { DirectAuthProvider } from '@magemetrics/core';
@@ -15,16 +12,11 @@ import { InfiniteQueryObserverResult } from '@tanstack/react-query';
 import { JSX } from 'react/jsx-runtime';
 import { MageMetricsClient } from '@magemetrics/core';
 import { MageMetricsClientConfig } from '@magemetrics/core';
-import { MageMetricsContextProvider } from './shared/context/MageMetricsContext';
-import { MageMetricsContextProviderProps } from './shared/context/MageMetricsContext';
-import { PersistenceOptions } from '../shared/context/MageMetricsContext';
 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 { useMageMetricsClient } from './shared/context/MageMetricsContext';
-import { useMageMetricsReady } from './shared/context/MageMetricsContext';
 import { UseMutateAsyncFunction } from '@tanstack/react-query';
 import { UseMutateFunction } from '@tanstack/react-query';
 import { UseMutationOptions } from '@tanstack/react-query';
@@ -102,6 +94,46 @@ export declare interface ChatContextValue {
     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;
@@ -128,7 +160,40 @@ declare interface ColumnSort {
     id: string;
 }
 
-export { Components }
+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;
 
@@ -236,8 +301,8 @@ declare type FormattedData = {
 declare type FrontendCanvas = z.infer<typeof FrontendCanvasSchema>;
 
 declare const FrontendCanvasSchema: z.ZodObject<{
-    id: z.ZodUUID;
     title: z.ZodNullable<z.ZodString>;
+    id: z.ZodUUID;
     nodes: z.ZodArray<z.ZodAny>;
     edges: z.ZodArray<z.ZodAny>;
     is_public: z.ZodBoolean;
@@ -245,8 +310,8 @@ declare const FrontendCanvasSchema: z.ZodObject<{
 
 declare const FrontendReportSchema: z.ZodObject<{
     status: z.ZodNullable<z.ZodString>;
-    id: z.ZodNumber;
     title: z.ZodString;
+    id: z.ZodNumber;
     request: z.ZodNullable<z.ZodString>;
     created_at: z.ZodString;
     data_summary: z.ZodObject<{
@@ -274,11 +339,68 @@ declare const FrontendReportSchema: z.ZodObject<{
     last_materialized_at: z.ZodNullable<z.ZodString>;
     materialized_error_message: z.ZodNullable<z.ZodString>;
     materialized_status: z.ZodNullable<z.ZodEnum<{
-        running: "running";
         completed: "completed";
         failed: "failed";
+        running: "running";
     }>>;
-    bookmarked: z.ZodBoolean;
+}, 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_id: z.ZodNumber;
+    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>>;
 }, z.core.$strip>;
 
 declare const InputContainer: default_2.FC<{
@@ -302,14 +424,28 @@ export { MageMetricsClient }
 
 export { MageMetricsClientConfig }
 
-export { MageMetricsContextProvider }
-
-export { MageMetricsContextProviderProps }
+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_3;
+    components?: Components;
 }>;
 
 export declare const ManagedModal: React.FC<ManagedModalProps>;
@@ -328,7 +464,7 @@ declare type ManagedModalBaseProps = ModalProps & {
     /** Where to persist modal state (localStorage, queryParam, or none) */
     persist?: PersistenceOptions;
     /** Custom component overrides for extending functionality */
-    components?: Components_2;
+    components?: Components;
     /** Application name to associate with flows created through this modal */
     applicationName?: string;
     /**
@@ -372,6 +508,8 @@ declare interface ModalProps {
     startOptions?: StartOptions;
 }
 
+declare type PersistenceOptions = "queryParam" | "none";
+
 /**
  * Primary color shade stops used in the UI.
  */
@@ -518,8 +656,8 @@ declare const TableFilterValueSchema: z.ZodObject<{
  * ```
  */
 export declare const useCanvas: (canvasId: string | undefined | null, options?: Omit<UseQueryOptions<FrontendCanvas, unknown>, "queryKey" | "queryFn">) => UseQueryResult<    {
-id: string;
 title: string | null;
+id: string;
 nodes: any[];
 edges: any[];
 is_public: boolean;
@@ -527,6 +665,12 @@ is_public: boolean;
 
 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<{
@@ -654,8 +798,8 @@ export declare const useDataReportColumnValue: (reportId: number, filters: Repor
 export declare const useDataTableContext: () => {
     report: {
         status: string | null;
-        id: number;
         title: string;
+        id: number;
         request: string | null;
         created_at: string;
         data_summary: {
@@ -685,7 +829,6 @@ export declare const useDataTableContext: () => {
         last_materialized_at: string | null;
         materialized_error_message: string | null;
         materialized_status: "completed" | "running" | "failed" | null;
-        bookmarked: boolean;
     };
     fetchNextPage: (options?: FetchNextPageOptions) => Promise<InfiniteQueryObserverResult<InfiniteData<    {
     [key: string]: unknown;
@@ -787,13 +930,13 @@ export declare const useDownloadReportData: (options?: UseMutationOptions<Export
 
 export declare const useMageMetricsApiUrl: () => string;
 
-export { useMageMetricsClient }
+export declare const useMageMetricsClient: () => MageMetricsClient;
 
-export { useMageMetricsReady }
+export declare const useMageMetricsReady: () => false | MageMetricsClient;
 
 export declare const useRecentFlows: (limit?: number) => UseQueryResult<    {
-id: string;
 title: string | null;
+id: string;
 request: string;
 created_at: string;
 user_id: string | null;
@@ -832,7 +975,6 @@ export declare const useReport: (reportId: number) => {
         } & {
             [key: string]: unknown;
         };
-        bookmarked: boolean;
         status: string | null;
         is_removed: boolean;
         is_materialized: boolean | null;
@@ -875,7 +1017,6 @@ export declare const useReport: (reportId: number) => {
     } & {
     [key: string]: unknown;
     };
-    bookmarked: boolean;
     status: string | null;
     is_removed: boolean;
     is_materialized: boolean | null;
@@ -889,6 +1030,57 @@ export declare const useReport: (reportId: number) => {
 
 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_id: z.ZodNumber;
+    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>>;
+}, z.core.$strip>;
+
 export declare const Visualization: ForwardRefExoticComponent<    {
 visualizationId: number;
 withTitle: boolean;