drizzle-cube 0.6.0 → 0.6.2

package/dist/cjs/adapters/utils.d.ts

@@ -0,0 +1,354 @@
+import { SemanticLayerCompiler, SemanticQuery, SecurityContext, QuerySuggestion, AIValidationResult } from '../server/index.js';
+import { normalizeQueryFields } from '../server/query-handlers.js';
+import { MCPPromptResolver, MCPResourceResolver, MCPInstructionsResolver } from './mcp-transport.js';
+export { handleDiscover, handleLoad } from '../server/query-handlers.js';
+export type { DiscoverRequest, LoadRequest, DiscoverResponse } from '../server/query-handlers.js';
+export { formatSqlString } from '../server/sql-format.js';
+export { normalizeQueryFields };
+/**
+ * Calculate query complexity based on query structure
+ */
+export declare function calculateQueryComplexity(query: SemanticQuery): string;
+/**
+ * Generate a unique request ID
+ */
+export declare function generateRequestId(): string;
+/**
+ * Build transformed query metadata for Cube.js compatibility
+ */
+export declare function buildTransformedQuery(query: SemanticQuery): any;
+/**
+ * Get database type from semantic layer
+ */
+export declare function getDatabaseType(semanticLayer: SemanticLayerCompiler): string;
+/**
+ * Helper function to handle dry-run logic for all adapters
+ */
+export declare function handleDryRun(query: SemanticQuery, securityContext: SecurityContext, semanticLayer: SemanticLayerCompiler): Promise<any>;
+/**
+ * Format standard Cube.js API response
+ */
+export declare function formatCubeResponse(query: SemanticQuery, result: {
+    data: any[];
+    annotation?: any;
+    cache?: {
+        hit: boolean;
+        cachedAt?: string;
+        ttlMs?: number;
+        ttlRemainingMs?: number;
+    };
+    warnings?: Array<{
+        code: string;
+        message: string;
+        severity: string;
+        cubes?: string[];
+        measures?: string[];
+        suggestion?: string;
+    }>;
+}, semanticLayer: SemanticLayerCompiler): {
+    queryType: string;
+    results: {
+        warnings?: {
+            code: string;
+            message: string;
+            severity: string;
+            cubes?: string[];
+            measures?: string[];
+            suggestion?: string;
+        }[] | undefined;
+        cache?: {
+            hit: boolean;
+            cachedAt?: string;
+            ttlMs?: number;
+            ttlRemainingMs?: number;
+        } | undefined;
+        query: SemanticQuery;
+        lastRefreshTime: string;
+        usedPreAggregations: {};
+        transformedQuery: any;
+        requestId: string;
+        annotation: any;
+        dataSource: string;
+        dbType: string;
+        extDbType: string;
+        external: boolean;
+        slowQuery: boolean;
+        data: any[];
+    }[];
+    pivotQuery: {
+        queryType: string;
+        measures?: string[];
+        dimensions?: string[];
+        filters?: Array<import('../server/index.js').Filter>;
+        timeDimensions?: Array<import('../server/index.js').TimeDimension>;
+        limit?: number;
+        offset?: number;
+        order?: Record<string, "asc" | "desc">;
+        fillMissingDatesValue?: number | null;
+        ungrouped?: boolean;
+        funnel?: import('../server/index.js').FunnelQueryConfig;
+        flow?: import('../server/types/flow.js').FlowQueryConfig;
+        retention?: import('../server/index.js').RetentionQueryConfig;
+    };
+    slowQuery: boolean;
+};
+/**
+ * Format SQL generation response
+ */
+export declare function formatSqlResponse(query: SemanticQuery, sqlResult: {
+    sql: string;
+    params?: any[];
+}): {
+    sql: string;
+    params: any[];
+    query: SemanticQuery;
+};
+/**
+ * Format metadata response with query guidance for AI consumers
+ */
+export declare function formatMetaResponse(metadata: any): {
+    cubes: any;
+    queryGuidance: {
+        dateHandling: {
+            critical: string;
+            forAggregatedTotals: {
+                description: string;
+                example: {
+                    filters: {
+                        member: string;
+                        operator: string;
+                        values: string[];
+                    }[];
+                };
+                useCase: string;
+            };
+            forTimeSeries: {
+                description: string;
+                example: {
+                    timeDimensions: {
+                        dimension: string;
+                        granularity: string;
+                        dateRange: string;
+                    }[];
+                };
+                useCase: string;
+            };
+            warning: string;
+        };
+        crossCubeQueries: {
+            description: string;
+            example: string;
+            howToFind: string;
+        };
+        topNPattern: {
+            description: string;
+            example: {
+                measures: string[];
+                dimensions: string[];
+                filters: {
+                    member: string;
+                    operator: string;
+                    values: string[];
+                }[];
+                order: {
+                    'Cube.total': string;
+                };
+                limit: number;
+            };
+        };
+        filterSyntax: {
+            description: string;
+            operators: string[];
+            dateRangeValues: {
+                relative: string[];
+                absolute: string[];
+            };
+        };
+    };
+};
+/**
+ * Standard error response format
+ */
+export declare function formatErrorResponse(error: string | Error, status?: number): {
+    error: string;
+    status: number;
+};
+/**
+ * Options for batch request handling
+ */
+export interface BatchRequestOptions {
+    /**
+     * Whether to bypass server-side cache for all queries in the batch
+     * When true, all queries will be executed fresh without cache
+     */
+    skipCache?: boolean;
+}
+/**
+ * Handle batch query requests - wrapper around existing single query execution
+ * Executes multiple queries in parallel and returns partial success results
+ *
+ * @param queries - Array of semantic queries to execute
+ * @param securityContext - Security context (extracted once, shared across all queries)
+ * @param semanticLayer - Semantic layer compiler instance
+ * @param options - Optional batch request options (e.g., skipCache)
+ * @returns Array of results matching input query order (successful or error results)
+ */
+export declare function handleBatchRequest(queries: SemanticQuery[], securityContext: SecurityContext, semanticLayer: SemanticLayerCompiler, options?: BatchRequestOptions): Promise<{
+    results: ({
+        queryType: string;
+        results: {
+            warnings?: {
+                code: string;
+                message: string;
+                severity: string;
+                cubes?: string[];
+                measures?: string[];
+                suggestion?: string;
+            }[] | undefined;
+            cache?: {
+                hit: boolean;
+                cachedAt?: string;
+                ttlMs?: number;
+                ttlRemainingMs?: number;
+            } | undefined;
+            query: SemanticQuery;
+            lastRefreshTime: string;
+            usedPreAggregations: {};
+            transformedQuery: any;
+            requestId: string;
+            annotation: any;
+            dataSource: string;
+            dbType: string;
+            extDbType: string;
+            external: boolean;
+            slowQuery: boolean;
+            data: any[];
+        }[];
+        pivotQuery: {
+            queryType: string;
+            measures?: string[];
+            dimensions?: string[];
+            filters?: Array<import('../server/index.js').Filter>;
+            timeDimensions?: Array<import('../server/index.js').TimeDimension>;
+            limit?: number;
+            offset?: number;
+            order?: Record<string, "asc" | "desc">;
+            fillMissingDatesValue?: number | null;
+            ungrouped?: boolean;
+            funnel?: import('../server/index.js').FunnelQueryConfig;
+            flow?: import('../server/types/flow.js').FlowQueryConfig;
+            retention?: import('../server/index.js').RetentionQueryConfig;
+        };
+        slowQuery: boolean;
+        success: boolean;
+        error?: undefined;
+        query?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        query: SemanticQuery;
+    })[];
+}>;
+/**
+ * Locale configuration for the MCP App visualization.
+ */
+export interface McpAppConfig {
+    /**
+     * Default locale to use when the browser locale is unavailable or detection is disabled.
+     * BCP-47 format (e.g. 'en-GB', 'nl-NL', 'en-US'). Defaults to 'en-GB'.
+     */
+    defaultLocale?: string;
+    /**
+     * When true (default), the MCP App will prefer the browser/runtime locale over defaultLocale.
+     * Set to false to force defaultLocale regardless of the browser setting.
+     */
+    detectBrowserLocale?: boolean;
+}
+/**
+ * MCP Endpoint Options
+ */
+export interface MCPOptions {
+    /** Enable MCP endpoints (default: true) */
+    enabled?: boolean;
+    /** Which MCP tools to expose (default: all) */
+    tools?: ('discover' | 'suggest' | 'validate' | 'load')[];
+    /** Base path for MCP endpoints (default: '/mcp') */
+    basePath?: string;
+    /**
+     * Allowed origins for MCP requests (for Origin header validation per MCP 2025-11-25).
+     * If not provided, all origins are allowed (permissive mode).
+     * Set this to restrict access to specific origins for production security.
+     * Example: ['http://localhost:3000', 'https://myapp.com']
+     */
+    allowedOrigins?: string[];
+    /**
+     * Enable MCP App visualization for load tool results.
+     * Pass `true` to enable with defaults, or a config object to set locale options.
+     * @example app: { defaultLocale: 'nl-NL', detectBrowserLocale: false }
+     */
+    app?: boolean | McpAppConfig;
+    /**
+     * Override the MCP prompt set exposed by the built-in endpoint.
+     * Pass an array to replace the defaults, or a function to derive from them.
+     */
+    prompts?: MCPPromptResolver;
+    /**
+     * Override the MCP resources exposed by the built-in endpoint.
+     * Pass an array to replace the defaults, or a function to derive from them.
+     * The live schema resource is always appended automatically.
+     */
+    resources?: MCPResourceResolver;
+    /**
+     * Override the `InitializeResult.instructions` string returned by the
+     * MCP `initialize` handshake. Per the MCP spec, this is the only
+     * server-authored guidance that clients are expected to surface to the
+     * model (it is typically merged into the system prompt).
+     *
+     * Pass a string to replace the defaults entirely, or a function to
+     * derive from / extend them. Use this to append project-specific
+     * guidance (e.g. cube semantics, naming conventions) without losing
+     * the built-in workflow rules.
+     */
+    instructions?: MCPInstructionsResolver;
+    /**
+     * OAuth 2.1 Protected Resource Metadata URL (RFC 9728).
+     * When set, MCP endpoints require a Bearer token in the Authorization header.
+     * Unauthenticated requests receive 401 with WWW-Authenticate pointing to this URL.
+     * Token validation is the responsibility of extractSecurityContext.
+     */
+    resourceMetadataUrl?: string;
+    /**
+     * Optional name to use in the MCP serverInfo.name field (initialize response).
+     * Defaults to 'drizzle-cube'. Override to match your product branding.
+     */
+    serverName?: string;
+}
+/**
+ * Suggest request body
+ */
+export interface SuggestRequest {
+    /** Natural language query */
+    naturalLanguage: string;
+    /** Optional target cube name */
+    cube?: string;
+}
+/**
+ * Validate request body
+ */
+export interface ValidateRequest {
+    /** Query to validate */
+    query: SemanticQuery;
+}
+/**
+ * Handle /suggest endpoint - generate query from natural language
+ */
+export declare function handleSuggest(semanticLayer: SemanticLayerCompiler, body: SuggestRequest): Promise<QuerySuggestion>;
+/**
+ * Handle /validate endpoint - validate query with corrections
+ */
+export declare function handleValidate(semanticLayer: SemanticLayerCompiler, body: ValidateRequest, securityContext?: SecurityContext): Promise<AIValidationResult & {
+    sql?: {
+        sql: string;
+        params?: any[];
+    };
+}>;

package/dist/cjs/client/adapters/adapterRegistry.d.ts

@@ -0,0 +1,44 @@
+import { ModeAdapter } from './modeAdapter.js';
+import { AnalysisType } from '../types/analysisConfig.js';
+/**
+ * Adapter registry - manages mode adapters
+ */
+export declare const adapterRegistry: {
+    /**
+     * Register an adapter for a specific analysis type.
+     * Should be called once at app initialization.
+     *
+     * @param adapter - The adapter to register
+     */
+    register<T>(adapter: ModeAdapter<T>): void;
+    /**
+     * Get the adapter for a specific analysis type.
+     * Built-in adapters (query, funnel) are initialized automatically.
+     *
+     * @param type - The analysis type to get adapter for
+     * @returns The registered adapter
+     * @throws Error if no adapter is registered for the type
+     */
+    get<T>(type: AnalysisType): ModeAdapter<T>;
+    /**
+     * Check if an adapter is registered for a specific type.
+     * Built-in adapters (query, funnel) are initialized automatically.
+     *
+     * @param type - The analysis type to check
+     * @returns True if an adapter is registered
+     */
+    has(type: AnalysisType): boolean;
+    /**
+     * Get all registered analysis types.
+     * Built-in adapters (query, funnel) are initialized automatically.
+     *
+     * @returns Array of registered types
+     */
+    getRegisteredTypes(): AnalysisType[];
+    /**
+     * Clear all registered adapters.
+     * Primarily useful for testing.
+     * Note: Built-in adapters will be re-initialized on next access.
+     */
+    clear(): void;
+};

package/dist/cjs/client/adapters/flowModeAdapter.d.ts

@@ -0,0 +1,3 @@
+import { ModeAdapter } from './modeAdapter.js';
+import { FlowSliceState } from '../types/flow.js';
+export declare const flowModeAdapter: ModeAdapter<FlowSliceState>;

package/dist/cjs/client/adapters/funnelModeAdapter.d.ts

@@ -0,0 +1,19 @@
+import { ModeAdapter } from './modeAdapter.js';
+import { FunnelStepState, FunnelBindingKey } from '../types.js';
+/**
+ * The shape of funnel mode state in the store.
+ * This is what the adapter's load() returns and save() receives.
+ */
+export interface FunnelSliceState {
+    /** The cube all funnel steps use (single-cube mode) */
+    funnelCube: string | null;
+    /** Funnel step definitions */
+    funnelSteps: FunnelStepState[];
+    /** Currently selected step index */
+    activeFunnelStepIndex: number;
+    /** Time dimension for temporal ordering */
+    funnelTimeDimension: string | null;
+    /** Binding key that links entities across steps */
+    funnelBindingKey: FunnelBindingKey | null;
+}
+export declare const funnelModeAdapter: ModeAdapter<FunnelSliceState>;

package/dist/cjs/client/adapters/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Adapters Index
+ *
+ * Barrel export for all adapter-related modules.
+ * Also handles adapter registration.
+ */
+export type { ModeAdapter, ValidationResult } from './modeAdapter.js';
+export { adapterRegistry } from './adapterRegistry.js';
+export { queryModeAdapter } from './queryModeAdapter.js';
+export type { QuerySliceState } from './queryModeAdapter.js';
+export { funnelModeAdapter } from './funnelModeAdapter.js';
+export type { FunnelSliceState } from './funnelModeAdapter.js';
+export { flowModeAdapter } from './flowModeAdapter.js';
+export { retentionModeAdapter } from './retentionModeAdapter.js';
+export type { RetentionSliceState } from '../types/retention.js';
+/**
+ * Manually initialize and register all adapters.
+ *
+ * Note: This function is no longer required to be called. Built-in adapters
+ * (query, funnel) are now automatically initialized on first access to the
+ * registry. This function is kept for backward compatibility and for cases
+ * where explicit early initialization is preferred.
+ *
+ * @example
+ * // Optional - adapters auto-initialize on first use
+ * import { initializeAdapters } from './adapters'
+ * initializeAdapters()
+ */
+export declare function initializeAdapters(): void;

package/dist/cjs/client/adapters/modeAdapter.d.ts

@@ -0,0 +1,117 @@
+import { AnalysisConfig, AnalysisType, ChartConfig } from '../types/analysisConfig.js';
+/**
+ * Result from adapter validation
+ */
+export interface ValidationResult {
+    /** Whether the state is valid for execution */
+    isValid: boolean;
+    /** Errors that prevent execution */
+    errors: string[];
+    /** Warnings that don't prevent execution but should be shown */
+    warnings: string[];
+}
+/**
+ * Mode adapter interface - owns all mode-specific logic
+ *
+ * TUIState is the shape of the UI state for this mode. For example:
+ * - Query mode: { queryStates, activeQueryIndex, mergeStrategy }
+ * - Funnel mode: { funnelCube, funnelSteps, funnelBindingKey, ... }
+ *
+ * The adapter handles conversion between this UI state and the
+ * persisted AnalysisConfig format.
+ */
+export interface ModeAdapter<TUIState> {
+    /**
+     * The analysis type this adapter handles.
+     * Must match one of the AnalysisType union values.
+     */
+    readonly type: AnalysisType;
+    /**
+     * Create initial empty UI state for this mode.
+     * Called on store initialization and when clearing state.
+     */
+    createInitial(): TUIState;
+    /**
+     * Extract this mode's state from the full store state.
+     * This replaces the need for hardcoded property access in the store.
+     *
+     * Called when:
+     * - Saving state to AnalysisConfig
+     * - Getting validation for current mode
+     *
+     * @param storeState - The full store state object
+     * @returns The extracted UI state for this mode
+     */
+    extractState(storeState: Record<string, unknown>): TUIState;
+    /**
+     * Convert AnalysisConfig → UI state (loading).
+     *
+     * Called when:
+     * - Loading from portlet (editing a dashboard widget)
+     * - Loading from share URL
+     * - Loading from localStorage
+     *
+     * @param config - The AnalysisConfig to load
+     * @returns The UI state for this mode's slice
+     * @throws Error if config cannot be loaded (malformed data)
+     */
+    load(config: AnalysisConfig): TUIState;
+    /**
+     * Check if this adapter can load the given config.
+     * Used for graceful error handling before attempting load.
+     *
+     * Should return false for:
+     * - Wrong analysis type
+     * - Missing required fields
+     * - Invalid version
+     *
+     * @param config - Unknown value to check
+     * @returns Type guard indicating if config is valid for this adapter
+     */
+    canLoad(config: unknown): config is AnalysisConfig;
+    /**
+     * Convert UI state → AnalysisConfig (saving).
+     *
+     * Builds the executable query from UI state. Called when:
+     * - Saving a portlet
+     * - Creating a share URL
+     * - Persisting to localStorage
+     *
+     * @param state - The current UI state for this mode
+     * @param charts - The charts config map from store
+     * @param activeView - Current active view ('table' or 'chart')
+     * @returns The persisted AnalysisConfig
+     */
+    save(state: TUIState, charts: Partial<Record<AnalysisType, ChartConfig>>, activeView: 'table' | 'chart'): AnalysisConfig;
+    /**
+     * Validate UI state before execution.
+     *
+     * Returns validation errors/warnings that can be displayed to user.
+     * A query with errors should not be executed.
+     *
+     * @param state - The current UI state to validate
+     * @returns Validation result with errors and warnings
+     */
+    validate(state: TUIState): ValidationResult;
+    /**
+     * Reset UI state to initial (optionally preserve cube selection).
+     *
+     * Called when user clicks "Clear" in the mode.
+     * May preserve certain selections like the current cube.
+     *
+     * @param state - Current state to clear
+     * @returns New cleared state
+     */
+    clear(state: TUIState): TUIState;
+    /**
+     * Default chart config for this mode.
+     *
+     * Called when:
+     * - Mode switch with no existing chart config for this mode
+     * - Load with missing chart config in the AnalysisConfig
+     * - Initial store creation
+     *
+     * @returns Default ChartConfig for this mode
+     */
+    getDefaultChartConfig(): ChartConfig;
+}

package/dist/cjs/client/adapters/queryModeAdapter.d.ts

@@ -0,0 +1,16 @@
+import { ModeAdapter } from './modeAdapter.js';
+import { QueryMergeStrategy } from '../types.js';
+import { AnalysisBuilderState } from '../components/AnalysisBuilder/types.js';
+/**
+ * The shape of query mode state in the store.
+ * This is what the adapter's load() returns and save() receives.
+ */
+export interface QuerySliceState {
+    /** Array of query states (one per query tab) */
+    queryStates: AnalysisBuilderState[];
+    /** Index of the active query tab */
+    activeQueryIndex: number;
+    /** Strategy for combining multiple queries */
+    mergeStrategy: QueryMergeStrategy;
+}
+export declare const queryModeAdapter: ModeAdapter<QuerySliceState>;

package/dist/cjs/client/adapters/retentionModeAdapter.d.ts

@@ -0,0 +1,3 @@
+import { ModeAdapter } from './modeAdapter.js';
+import { RetentionSliceState } from '../types/retention.js';
+export declare const retentionModeAdapter: ModeAdapter<RetentionSliceState>;

package/dist/cjs/client/charts/ChartLoader.d.ts

@@ -0,0 +1,69 @@
+import { ReactNode } from 'react';
+import { ChartType, ChartProps } from '../types.js';
+export { registerChartComponent, unregisterChartComponent } from './chartComponentRegistry.js';
+/**
+ * Check if a chart type is supported (built-in or custom plugin)
+ */
+export declare function isValidChartType(chartType: string): chartType is ChartType;
+export interface LazyChartProps extends ChartProps {
+    chartType: ChartType;
+    fallback?: ReactNode;
+}
+/**
+ * Lazy Chart Component
+ *
+ * Renders a chart component with React.lazy dynamic loading.
+ * The chart type determines which chart component is loaded.
+ *
+ * @example
+ * ```tsx
+ * <LazyChart
+ *   chartType="bar"
+ *   data={chartData}
+ *   chartConfig={{ yAxis: ['value'] }}
+ *   height={300}
+ * />
+ * ```
+ */
+export declare function LazyChart({ chartType, fallback, height, ...chartProps }: LazyChartProps): import("react").JSX.Element;
+/**
+ * Preload a chart type
+ *
+ * Triggers the dynamic import without rendering.
+ * Useful for prefetching charts that will likely be needed.
+ *
+ * @example
+ * ```tsx
+ * // Preload bar chart on hover
+ * onMouseEnter={() => preloadChart('bar')}
+ * ```
+ */
+export declare function preloadChart(chartType: ChartType): void;
+/**
+ * Preload multiple chart types
+ *
+ * @example
+ * ```tsx
+ * // Preload common charts on app init
+ * useEffect(() => {
+ *   preloadCharts(['bar', 'line', 'pie'])
+ * }, [])
+ * ```
+ */
+export declare function preloadCharts(chartTypes: ChartType[]): void;
+/**
+ * Get all available chart types (built-in + custom plugins)
+ */
+export declare function getAvailableChartTypes(): ChartType[];
+/**
+ * Check if a chart type has loaded successfully.
+ * Returns false if the chart failed to load due to missing dependencies.
+ *
+ * Note: This only returns accurate results after the chart has been attempted to load.
+ * Use this for conditional UI logic (e.g., hiding unavailable chart types).
+ */
+export declare function isChartTypeAvailable(chartType: ChartType): boolean;
+/**
+ * Get list of chart types that failed to load due to missing dependencies.
+ */
+export declare function getUnavailableChartTypes(): ChartType[];