drizzle-cube 0.6.0 → 0.6.2

package/dist/cjs/client/types/funnel.d.ts

@@ -0,0 +1,288 @@
+import { CubeQuery } from '../types.js';
+/**
+ * Binding key configuration - the dimension that links funnel steps together.
+ * Can be a simple dimension name or cross-cube mapping for multi-cube funnels.
+ */
+export interface FunnelBindingKey {
+    /**
+     * The dimension field name that exists across all cubes in the funnel.
+     * For cross-cube funnels where the binding key has different names,
+     * specify a mapping array instead.
+     *
+     * @example Simple: "Employees.userId"
+     * @example Cross-cube: [{ cube: "Signups", dimension: "Signups.userId" }, { cube: "Purchases", dimension: "Purchases.customerId" }]
+     */
+    dimension: string | FunnelBindingKeyMapping[];
+}
+/**
+ * Mapping for cross-cube funnels where the binding key has different names
+ * in different cubes.
+ */
+export interface FunnelBindingKeyMapping {
+    /** The cube name (e.g., "Signups", "Purchases") */
+    cube: string;
+    /** The full dimension field in that cube (e.g., "Signups.userId") */
+    dimension: string;
+}
+/**
+ * Configuration for a single funnel step.
+ * Each step has its own query and optional time constraints.
+ */
+export interface FunnelStep {
+    /** Unique identifier for this step */
+    id: string;
+    /** Display name for the step (e.g., "Signup", "First Purchase") */
+    name: string;
+    /** The cube query for this step */
+    query: CubeQuery;
+    /**
+     * Time window constraint - maximum time allowed between this step
+     * and the previous step. Optional - if not set, no time constraint.
+     * Format: ISO 8601 duration (e.g., "P7D" for 7 days, "PT1H" for 1 hour)
+     */
+    timeToConvert?: string;
+    /**
+     * Time dimension field to use for time window filtering.
+     * Required if timeToConvert is specified.
+     */
+    timeDimension?: string;
+}
+/**
+ * Complete funnel configuration
+ */
+export interface FunnelConfig {
+    /** Unique identifier for the funnel */
+    id: string;
+    /** Display name for the funnel */
+    name: string;
+    /** The binding key that links steps together */
+    bindingKey: FunnelBindingKey;
+    /** Ordered array of funnel steps */
+    steps: FunnelStep[];
+    /**
+     * Global time window for the entire funnel.
+     * All steps must complete within this window from the first step.
+     */
+    globalTimeWindow?: string;
+    /**
+     * Whether to count unique entities (true) or events (false).
+     * Default: true
+     */
+    countUnique?: boolean;
+    /**
+     * Maximum number of binding key values to pass between steps.
+     * Limits the size of the IN clause to prevent performance issues.
+     * Default: 500
+     */
+    bindingKeyLimit?: number;
+}
+/**
+ * Result for a single funnel step execution
+ */
+export interface FunnelStepResult {
+    /** Step index (0-based) */
+    stepIndex: number;
+    /** Step name */
+    stepName: string;
+    /** Step ID */
+    stepId: string;
+    /** Raw data from the query */
+    data: unknown[];
+    /** Binding key values extracted from this step */
+    bindingKeyValues: (string | number)[];
+    /**
+     * Total number of unique binding key values before limit was applied.
+     * If this differs from bindingKeyValues.length, values were truncated.
+     */
+    bindingKeyTotalCount: number;
+    /** Count at this step (unique entities if countUnique=true, else rows) */
+    count: number;
+    /** Conversion rate from previous step (null for first step) */
+    conversionRate: number | null;
+    /** Cumulative conversion rate from first step */
+    cumulativeConversionRate: number;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Error if this step failed */
+    error: Error | null;
+}
+/**
+ * Complete funnel execution result
+ */
+export interface FunnelExecutionResult {
+    /** Funnel configuration */
+    config: FunnelConfig;
+    /** Per-step results */
+    steps: FunnelStepResult[];
+    /** Overall funnel metrics */
+    summary: {
+        /** Count at first step */
+        totalEntries: number;
+        /** Count at last step */
+        totalCompletions: number;
+        /** Overall conversion rate (completions / entries) */
+        overallConversionRate: number;
+        /** Total execution time for all steps */
+        totalExecutionTime: number;
+    };
+    /** Formatted data for funnel chart visualization */
+    chartData: FunnelChartData[];
+    /** Execution status */
+    status: 'idle' | 'executing' | 'success' | 'error' | 'partial';
+    /** First error encountered, if any */
+    error: Error | null;
+    /** Index of current step being executed (null when not executing) */
+    currentStepIndex: number | null;
+}
+/**
+ * Data format for funnel chart visualization
+ */
+export interface FunnelChartData {
+    /** Step name */
+    name: string;
+    /** Count at this step */
+    value: number;
+    /** Percentage of first step (cumulative conversion) */
+    percentage: number;
+    /** Conversion rate from previous step (null for first step) */
+    conversionRate: number | null;
+    /** Step index for ordering */
+    stepIndex: number;
+    /** Optional fill color */
+    fill?: string;
+    /** Average seconds to reach this step from previous step (from server) */
+    avgSecondsToConvert?: number | null;
+    /** Median seconds to reach this step from previous step (from server) */
+    medianSecondsToConvert?: number | null;
+    /** 90th percentile seconds to reach this step (from server) */
+    p90SecondsToConvert?: number | null;
+}
+/**
+ * Validation error for funnel configuration
+ */
+export interface FunnelValidationError {
+    /** Error type */
+    type: 'binding_key' | 'cross_cube' | 'time_window' | 'step_query' | 'general';
+    /** Error message */
+    message: string;
+    /** Step index if error is step-specific */
+    stepIndex?: number;
+}
+/**
+ * Validation result for funnel configuration
+ */
+export interface FunnelValidationResult {
+    /** Whether the configuration is valid */
+    isValid: boolean;
+    /** Validation errors (block execution) */
+    errors: FunnelValidationError[];
+    /** Validation warnings (notify but allow) */
+    warnings: FunnelValidationError[];
+}
+/**
+ * Options for funnel query hook
+ */
+export interface UseFunnelQueryOptions {
+    /** Skip execution */
+    skip?: boolean;
+    /** Debounce delay in milliseconds */
+    debounceMs?: number;
+    /** Callback when a step completes */
+    onStepComplete?: (stepResult: FunnelStepResult) => void;
+    /** Callback when all steps complete */
+    onComplete?: (result: FunnelExecutionResult) => void;
+    /** Callback when execution fails */
+    onError?: (error: Error, stepIndex: number) => void;
+    /**
+     * Pre-built server funnel query. When provided, skips building
+     * the server query from FunnelConfig and uses this directly.
+     * Use this with the new dedicated funnel mode (analysisType === 'funnel').
+     */
+    prebuiltServerQuery?: ServerFunnelQuery | null;
+}
+/**
+ * Result from funnel query hook
+ */
+export interface UseFunnelQueryResult {
+    /** Funnel execution result */
+    result: FunnelExecutionResult | null;
+    /** Current execution status */
+    status: 'idle' | 'executing' | 'success' | 'error' | 'partial';
+    /** Whether currently executing */
+    isExecuting: boolean;
+    /** Whether waiting for debounce */
+    isDebouncing: boolean;
+    /** Index of step currently being executed */
+    currentStepIndex: number | null;
+    /** Per-step loading states */
+    stepLoadingStates: boolean[];
+    /** Per-step results (for progressive rendering) */
+    stepResults: FunnelStepResult[];
+    /** Chart-ready data */
+    chartData: FunnelChartData[];
+    /** Cache metadata when served from cache */
+    cacheInfo?: {
+        hit: true;
+        cachedAt: string;
+        ttlMs: number;
+        ttlRemainingMs: number;
+    } | null;
+    /** Error if execution failed */
+    error: Error | null;
+    /** Execute the funnel. Pass { bustCache: true } to bypass client and server caches. */
+    execute: (options?: {
+        bustCache?: boolean;
+    }) => Promise<FunnelExecutionResult | null>;
+    /** Cancel current execution */
+    cancel: () => void;
+    /** Reset to initial state */
+    reset: () => void;
+    /**
+     * The actually executed queries (with binding key dimension and IN filters).
+     * These differ from the original queries in the following ways:
+     * - Binding key dimension is automatically added if not present
+     * - For steps 2+, an IN filter is added with binding key values from the previous step
+     * Use these for debug/inspection to see what was actually sent to the server.
+     * @deprecated Server-side funnel execution doesn't use per-step queries. Use serverQuery instead.
+     */
+    executedQueries: CubeQuery[];
+    /**
+     * The actual server query sent to the API with { funnel: {...} }.
+     * This is a single unified query, not per-step queries.
+     * Use this for debug panel display to show what's actually executed.
+     */
+    serverQuery: ServerFunnelQuery | null;
+    /**
+     * Whether the query needs to be refreshed (manual refresh mode only).
+     * True when the current funnel config differs from the last executed query.
+     */
+    needsRefresh: boolean;
+}
+/**
+ * Server-side funnel query format
+ * This is the { funnel: {...} } object sent to the server API
+ */
+export interface ServerFunnelQuery {
+    funnel: {
+        bindingKey: string | {
+            cube: string;
+            dimension: string;
+        }[];
+        timeDimension: string | {
+            cube: string;
+            dimension: string;
+        }[];
+        steps: ServerFunnelStep[];
+        includeTimeMetrics?: boolean;
+        globalTimeWindow?: string;
+    };
+}
+/**
+ * Server-side funnel step format
+ */
+export interface ServerFunnelStep {
+    name: string;
+    cube?: string;
+    filter?: unknown;
+    timeToConvert?: string;
+}

package/dist/cjs/client/types/retention.d.ts

@@ -0,0 +1,301 @@
+import { Filter } from '../types.js';
+import { FunnelBindingKey } from './funnel.js';
+/**
+ * Date range for cohort analysis (REQUIRED)
+ * Matches server's RetentionDateRange interface
+ */
+export interface DateRange {
+    /** Start date (inclusive), ISO 8601 format (YYYY-MM-DD) */
+    start: string;
+    /** End date (inclusive), ISO 8601 format (YYYY-MM-DD) */
+    end: string;
+}
+/**
+ * Preset date range type
+ */
+export type DateRangePreset = 'last_30_days' | 'last_3_months' | 'last_6_months' | 'last_12_months' | 'this_year' | 'last_year' | 'custom';
+/**
+ * Preset date range options for the UI
+ */
+export declare const RETENTION_DATE_RANGE_PRESETS: {
+    value: DateRangePreset;
+    label: string;
+}[];
+/**
+ * Default preset for retention date range
+ */
+export declare const DEFAULT_DATE_RANGE_PRESET: DateRangePreset;
+/**
+ * Calculate date range from a preset value
+ * Returns ISO date strings (YYYY-MM-DD)
+ */
+export declare function getDateRangeFromPreset(preset: DateRangePreset): DateRange;
+/**
+ * Detect which preset a date range matches, if any
+ */
+export declare function detectDateRangePreset(range: DateRange): DateRangePreset;
+/**
+ * Server retention query format
+ * This is the shape sent to the server for execution
+ * Wrapped in { retention: {...} } similar to funnel queries
+ */
+export interface ServerRetentionQuery {
+    retention: RetentionQueryConfig;
+}
+/**
+ * Retention query configuration
+ * Contains all parameters needed for server-side retention analysis
+ *
+ * Simplified Mixpanel-style format:
+ * - Single cube and timestamp dimension
+ * - Single cohort (date range defines the cohort, not granularity)
+ * - Optional breakdown dimension for segmentation
+ */
+export interface RetentionQueryConfig {
+    /**
+     * Single timestamp dimension for the analysis.
+     * String format (e.g., 'Events.timestamp'),
+     * Object format for multi-cube with explicit cube reference.
+     */
+    timeDimension: string | {
+        cube: string;
+        dimension: string;
+    };
+    /**
+     * Binding key - dimension that links users across events.
+     * This is typically a user ID or other entity identifier.
+     * String for single-cube (e.g., 'Events.userId'),
+     * Array for multi-cube with different column names per cube.
+     */
+    bindingKey: string | {
+        cube: string;
+        dimension: string;
+    }[];
+    /**
+     * Date range for cohort analysis (REQUIRED).
+     * Users who first performed the cohort action within this range are included.
+     */
+    dateRange: DateRange;
+    /**
+     * Granularity for viewing retention periods.
+     * Determines how retention periods are measured (day/week/month).
+     */
+    granularity: RetentionGranularity;
+    /**
+     * Number of periods to calculate (e.g., 12 for 12 weeks).
+     * Period 0 is always the cohort entry period.
+     */
+    periods: number;
+    /**
+     * Retention type:
+     * - 'classic': User returned exactly in period N (bounded)
+     * - 'rolling': User returned in period N or any later period (unbounded)
+     */
+    retentionType: RetentionType;
+    /**
+     * Optional filters on cohort entry events.
+     * Applied when identifying which users enter the cohort.
+     */
+    cohortFilters?: Filter | Filter[];
+    /**
+     * Optional filters on return activity events.
+     * Applied when checking for user activity in each period.
+     */
+    activityFilters?: Filter | Filter[];
+    /**
+     * Optional breakdown dimensions for segmenting the cohort.
+     * When provided, retention is calculated per breakdown value combination.
+     * e.g., ["Events.country"] or ["Events.country", "Events.plan"]
+     */
+    breakdownDimensions?: string[];
+}
+/**
+ * Supported granularity levels for retention analysis
+ */
+export type RetentionGranularity = 'day' | 'week' | 'month';
+/**
+ * Retention calculation types
+ * - classic: User active exactly in period N
+ * - rolling: User active in period N or any later period
+ */
+export type RetentionType = 'classic' | 'rolling';
+/**
+ * Single retention data point returned from server
+ * Results are returned as a flat array; client transforms to matrix if needed
+ */
+export interface RetentionResultRow {
+    /** Period number (0 = cohort entry, 1 = first retention period, etc.) */
+    period: number;
+    /** Number of users in the cohort */
+    cohortSize: number;
+    /** Number of users retained in this period */
+    retainedUsers: number;
+    /** Retention rate as decimal (0-1), e.g., 0.45 for 45% */
+    retentionRate: number;
+    /** Breakdown value when breakdown dimension is specified (e.g., "US", "UK") */
+    breakdownValue?: string | null;
+}
+/**
+ * Retention chart data format for visualization
+ * Supports both heatmap and line chart modes
+ */
+export interface RetentionChartData {
+    rows: RetentionResultRow[];
+    /** Period numbers (0 to periods) */
+    periods: number[];
+    /** Breakdown values when breakdown dimension is specified */
+    breakdownValues?: string[];
+    /** Summary statistics */
+    summary?: RetentionSummary;
+    /** Granularity of retention periods (day/week/month) for period label formatting */
+    granularity?: RetentionGranularity;
+    /** Human-readable label extracted from the binding key dimension (e.g., "userId" from "Users.userId") */
+    bindingKeyLabel?: string;
+}
+/**
+ * Summary statistics for retention analysis
+ */
+export interface RetentionSummary {
+    /** Total unique users in the cohort */
+    totalUsers: number;
+    /** Average retention rate across all periods for period 1 */
+    avgPeriod1Retention: number;
+    /** Highest retention rate for period 1 */
+    maxPeriod1Retention: number;
+    /** Lowest retention rate for period 1 */
+    minPeriod1Retention: number;
+    /** Number of breakdown segments (1 if no breakdown) */
+    segmentCount?: number;
+}
+/**
+ * Breakdown item for retention analysis (single dimension)
+ * Follows Mixpanel pattern - one breakdown dimension only
+ */
+export interface RetentionBreakdownItem {
+    /** Full dimension name (e.g., "Events.country") */
+    field: string;
+    /** Display label for the dimension */
+    label?: string;
+}
+/**
+ * Retention mode state for the AnalysisBuilder store
+ * Simplified Mixpanel-style with single global configuration
+ *
+ * Key simplifications from previous version:
+ * - Single cube for all (no separate cohort/activity cubes)
+ * - Single timestamp dimension
+ * - Single cohort with breakdown support (no cohort explosion)
+ * - Granularity = viewing periods only
+ */
+export interface RetentionSliceState {
+    /** Single cube for retention analysis */
+    retentionCube: string | null;
+    /** Binding key that identifies entities (reuses funnel binding key type) */
+    retentionBindingKey: FunnelBindingKey | null;
+    /** Single timestamp dimension for both cohort entry and activity */
+    retentionTimeDimension: string | null;
+    /** Date range for cohort analysis (REQUIRED) */
+    retentionDateRange: DateRange;
+    /** Filters that define who enters the cohort */
+    retentionCohortFilters: Filter[];
+    /** Filters that define what counts as a return */
+    retentionActivityFilters: Filter[];
+    /** Optional breakdown dimensions for segmenting the cohort */
+    retentionBreakdowns: RetentionBreakdownItem[];
+    /** Granularity for viewing retention periods (day/week/month) */
+    retentionViewGranularity: RetentionGranularity;
+    /** Number of periods to analyze (1-52) */
+    retentionPeriods: number;
+    /** Type of retention calculation */
+    retentionType: RetentionType;
+}
+/**
+ * Retention slice actions for the store
+ */
+export interface RetentionSliceActions {
+    /** Set the single cube for retention analysis */
+    setRetentionCube: (cube: string | null) => void;
+    /** Set the retention binding key */
+    setRetentionBindingKey: (key: FunnelBindingKey | null) => void;
+    /** Set the single timestamp dimension */
+    setRetentionTimeDimension: (dim: string | null) => void;
+    /** Set the date range (REQUIRED) */
+    setRetentionDateRange: (range: DateRange) => void;
+    /** Set all cohort filters at once */
+    setRetentionCohortFilters: (filters: Filter[]) => void;
+    /** Add a cohort filter */
+    addRetentionCohortFilter: (filter: Filter) => void;
+    /** Remove a cohort filter by index */
+    removeRetentionCohortFilter: (index: number) => void;
+    /** Update a cohort filter by index */
+    updateRetentionCohortFilter: (index: number, filter: Filter) => void;
+    /** Set all activity filters at once */
+    setRetentionActivityFilters: (filters: Filter[]) => void;
+    /** Add an activity filter */
+    addRetentionActivityFilter: (filter: Filter) => void;
+    /** Remove an activity filter by index */
+    removeRetentionActivityFilter: (index: number) => void;
+    /** Update an activity filter by index */
+    updateRetentionActivityFilter: (index: number, filter: Filter) => void;
+    /** Set all breakdown dimensions */
+    setRetentionBreakdowns: (breakdowns: RetentionBreakdownItem[]) => void;
+    /** Add a breakdown dimension */
+    addRetentionBreakdown: (breakdown: RetentionBreakdownItem) => void;
+    /** Remove a breakdown dimension by field name */
+    removeRetentionBreakdown: (field: string) => void;
+    /** Set the view granularity */
+    setRetentionViewGranularity: (granularity: RetentionGranularity) => void;
+    /** Set the number of periods */
+    setRetentionPeriods: (periods: number) => void;
+    /** Set the retention type */
+    setRetentionType: (type: RetentionType) => void;
+    /** Check if in retention mode (analysisType === 'retention') */
+    isRetentionMode: () => boolean;
+    /** Check if retention mode is properly configured and ready for execution */
+    isRetentionModeEnabled: () => boolean;
+    /** Build ServerRetentionQuery from retention state */
+    buildRetentionQuery: () => ServerRetentionQuery | null;
+    /** Get validation errors explaining why retention query cannot be built */
+    getRetentionValidation: () => {
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+}
+/**
+ * Type guard to check if data is retention chart data
+ */
+export declare function isRetentionData(data: unknown): data is RetentionChartData;
+/**
+ * Type guard to detect server retention query format
+ * Used to distinguish { retention: {...} } from CubeQuery, etc.
+ */
+export declare function isServerRetentionQuery(obj: unknown): obj is ServerRetentionQuery;
+/**
+ * Type guard for retention result row
+ */
+export declare function isRetentionResultRow(row: unknown): row is RetentionResultRow;
+/**
+ * Default retention slice state for store initialization
+ */
+export declare const defaultRetentionSliceState: RetentionSliceState;
+/**
+ * Minimum and maximum values for retention periods
+ */
+export declare const RETENTION_MIN_PERIODS = 1;
+export declare const RETENTION_MAX_PERIODS = 52;
+/**
+ * Available granularity options
+ */
+export declare const RETENTION_GRANULARITY_OPTIONS: {
+    value: RetentionGranularity;
+    label: string;
+}[];
+/**
+ * Available retention type options
+ */
+export declare const RETENTION_TYPE_OPTIONS: {
+    value: RetentionType;
+    label: string;
+    description: string;
+}[];