react-semaphor 0.1.369 → 0.1.371

package/dist/types/analytics-protocol.d.ts

@@ -76,6 +76,289 @@ export declare function isAnalyticsMetricIdentifierField(field: AnalyticsCatalog
 
 export declare function isAnalyticsTechnicalIdentifierField(field: AnalyticsCatalogField): boolean;
 
+export declare type MatrixAxisLevelDescriptor = {
+    instanceId: string;
+    fieldKey: string;
+    label: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    subtotal?: SemaphorMatrixSubtotalOptions;
+};
+
+export declare type MatrixAxisPayload = {
+    id: 'rows' | 'columns';
+    levels: MatrixAxisLevelDescriptor[];
+    nodes: MatrixNode[];
+};
+
+export declare type MatrixCapability = 'rowHierarchy' | 'columnHierarchy' | 'rowSubtotals' | 'columnSubtotals' | 'grandTotals' | 'lazyRows' | 'lazyColumns' | 'conditionalFormatting' | 'visualExport' | (string & {});
+
+export declare type MatrixCell = {
+    id: string;
+    rowNodeId: string;
+    columnNodeId?: string;
+    measureInstanceId: string;
+    rowPath: MatrixMemberPathSegment[];
+    columnPath: MatrixMemberPathSegment[];
+    rawValue: unknown;
+    presence: MatrixCellPresence;
+    formattedValue?: string;
+    role: MatrixCellRole;
+    aggregateFunction?: SemaphorAggregateFunction;
+    formattingScope: MatrixCellFormattingScope;
+    actions?: MatrixCellAction[];
+};
+
+export declare type MatrixCellAction = {
+    kind: 'requestSubgoal' | 'filter' | 'copyValue' | 'explainCalculation' | 'inspectContributingRows' | 'drillThrough' | (string & {});
+    label?: string;
+    payload?: Record<string, unknown>;
+};
+
+export declare type MatrixCellFormattingScope = {
+    rowNodeId: string;
+    columnNodeId?: string;
+    measureInstanceId: string;
+    role: MatrixCellRole;
+    rowPath: MatrixMemberPathSegment[];
+    columnPath: MatrixMemberPathSegment[];
+};
+
+export declare type MatrixCellPresence = 'present' | 'presentNull' | 'missing' | 'densified';
+
+export declare type MatrixCellRole = 'value' | 'rowSubtotal' | 'columnSubtotal' | 'subtotalIntersection' | 'rowGrandTotal' | 'columnGrandTotal' | 'matrixGrandTotal';
+
+export declare type MatrixExecutionMetadata = {
+    strategy?: MatrixQueryStrategy;
+    dialect?: SemaphorDialect;
+    rowNodeCount?: number;
+    columnNodeCount?: number;
+    cellCount?: number;
+    groupingSetCount?: number;
+    queryDurationMs?: number;
+    budgetRejected?: boolean;
+    cacheStatus?: 'hit' | 'miss' | 'bypass';
+    [key: string]: unknown;
+};
+
+export declare type MatrixExpansionRequest = {
+    axis: 'row' | 'column';
+    path: MatrixMemberPathSegment[];
+    depth?: number;
+};
+
+export declare type MatrixExpansionResponseHints = {
+    rowLazyLoading?: boolean;
+    columnLazyLoading?: boolean;
+    expandableRowNodeIds?: string[];
+    expandableColumnNodeIds?: string[];
+    nextRequests?: MatrixExpansionRequest[];
+};
+
+export declare type MatrixFieldDescriptor = {
+    instanceId: string;
+    fieldKey: string;
+    field: SemaphorFieldRef;
+    role: 'row' | 'column' | 'measure' | 'sort' | 'filter';
+    label?: string;
+};
+
+export declare type MatrixFieldDirectory = {
+    fieldsByInstanceId: Record<string, MatrixFieldDescriptor>;
+};
+
+export declare type MatrixFormattingContext = {
+    domains?: Record<string, {
+        min?: number;
+        max?: number;
+    }>;
+    rules?: Array<Record<string, unknown>>;
+};
+
+export declare type MatrixGridCell = {
+    id: string;
+    columnId: string;
+    cellId?: string;
+    rawValue: unknown;
+    formattedValue?: string;
+    presence: MatrixCellPresence;
+    role: MatrixCellRole;
+    measureInstanceId: string;
+    rowPath: MatrixMemberPathSegment[];
+    columnPath: MatrixMemberPathSegment[];
+};
+
+export declare type MatrixGridColumn = {
+    id: string;
+    label: string;
+    columnNodeId?: string;
+    columnPath: MatrixMemberPathSegment[];
+    measureInstanceId: string;
+    role: 'value' | 'columnSubtotal' | 'columnGrandTotal';
+};
+
+export declare type MatrixGridHeaderCell = {
+    id: string;
+    label: string;
+    role: 'rowHeader' | 'columnHeader' | 'measureHeader' | 'subtotal' | 'grandTotal';
+    colSpan: number;
+    rowSpan: number;
+    columnPath: MatrixMemberPathSegment[];
+    measureInstanceId?: string;
+};
+
+export declare type MatrixGridHeaderRow = {
+    id: string;
+    cells: MatrixGridHeaderCell[];
+};
+
+export declare type MatrixGridProjection = {
+    schemaVersion: 1;
+    shape: MatrixShape;
+    rowHeaderLevels: MatrixGridRowHeaderLevel[];
+    columnHeaderRows: MatrixGridHeaderRow[];
+    columns: MatrixGridColumn[];
+    rows: MatrixGridRow[];
+};
+
+export declare type MatrixGridRow = {
+    id: string;
+    rowNodeId: string;
+    rowPath: MatrixMemberPathSegment[];
+    depth: number;
+    label: string;
+    role: 'value' | 'rowSubtotal' | 'rowGrandTotal';
+    isExpanded?: boolean;
+    hasChildren?: boolean;
+    cells: MatrixGridCell[];
+};
+
+export declare type MatrixGridRowHeaderLevel = {
+    id: string;
+    label: string;
+    fieldInstanceId: string;
+};
+
+export declare type MatrixMeasureDescriptor = {
+    instanceId: string;
+    fieldKey: string;
+    label: string;
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
+export declare type MatrixMeasureSemantics = {
+    kind: 'additive';
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'semiAdditive';
+    aggregate?: SemaphorAggregateFunction;
+    grain?: SemaphorTimeGrain;
+} | {
+    kind: 'nonAdditive';
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'ratio';
+    numeratorMeasureInstanceId?: string;
+    denominatorMeasureInstanceId?: string;
+} | {
+    kind: 'custom';
+    expressionId?: string;
+};
+
+export declare type MatrixMemberPathSegment = {
+    instanceId: string;
+    fieldKey: string;
+    value: unknown;
+    label: string;
+};
+
+export declare type MatrixNode = {
+    id: string;
+    axis: 'row' | 'column';
+    path: MatrixMemberPathSegment[];
+    level: number;
+    label: string;
+    value: unknown;
+    parentId?: string;
+    hasChildren: boolean;
+    isExpanded?: boolean;
+    isSubtotal?: boolean;
+    isGrandTotal?: boolean;
+    subtotalFunction?: SemaphorAggregateFunction;
+    childCount?: number;
+    actions?: MatrixNodeAction[];
+};
+
+export declare type MatrixNodeAction = {
+    kind: 'expand' | 'collapse' | 'requestSubgoal' | 'filter' | 'drillThrough' | 'openRelatedRecords' | (string & {});
+    label?: string;
+    payload?: Record<string, unknown>;
+};
+
+export declare type MatrixPageInfo = {
+    rowOffset?: number;
+    rowLimit?: number;
+    columnOffset?: number;
+    columnLimit?: number;
+    hasMoreRows?: boolean;
+    hasMoreColumns?: boolean;
+};
+
+export declare type MatrixPayload = {
+    kind: 'matrixPayload';
+    schemaVersion: 1;
+    shape: MatrixShape;
+    capabilities: MatrixCapability[];
+    executionMetadata: MatrixExecutionMetadata;
+    axes: {
+        rows: MatrixAxisPayload;
+        columns: MatrixAxisPayload;
+    };
+    measures: MatrixMeasureDescriptor[];
+    measureSemantics: Record<string, MatrixMeasureSemantics>;
+    fieldDirectory: MatrixFieldDirectory;
+    rowNodes: MatrixNode[];
+    columnNodes: MatrixNode[];
+    cells: MatrixCell[];
+    totals: MatrixTotals;
+    sort: MatrixResolvedSort[];
+    formattingContext: MatrixFormattingContext;
+    pageInfo?: MatrixPageInfo;
+    warnings?: MatrixWarning[];
+};
+
+export declare type MatrixQueryStrategy = 'tall' | 'wide' | 'lazy' | 'export';
+
+export declare type MatrixResolvedSort = {
+    id: string;
+    axis: 'row' | 'column';
+    targetInstanceId?: string;
+    direction: 'asc' | 'desc';
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+    by: SemaphorMatrixSortRule['by'];
+};
+
+export declare type MatrixShape = 'hierarchical' | 'pivot';
+
+export declare type MatrixTotals = {
+    rows?: boolean;
+    columns?: boolean;
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+};
+
+export declare type MatrixWarning = {
+    code: string;
+    message: string;
+    path?: string;
+    severity?: 'info' | 'warning' | 'error';
+};
+
 export declare function normalizeAnalyticsCatalogDataType(value: unknown): AnalyticsCatalogDataType;
 
 export declare function normalizeAnalyticsCatalogName(value: unknown): string;
@@ -351,7 +634,7 @@ export declare type SemaphorAnalyticsFilterBase = {
 
 export declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
 
-export declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
+export declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent | SemaphorMatrixIntent;
 
 export declare type SemaphorAnalyticsIntentFixtureName = keyof typeof SEMAPHOR_ANALYTICS_INTENT_FIXTURES;
 
@@ -410,7 +693,7 @@ export declare type SemaphorAnalyticsRepairHint = {
     recommendedNextStep: string;
 };
 
-export declare type SemaphorAnalyticsResult = SemaphorMetricResult | SemaphorRecordsResult | SemaphorInputOptionsResult | SemaphorSqlResult;
+export declare type SemaphorAnalyticsResult = SemaphorMetricResult | SemaphorRecordsResult | SemaphorInputOptionsResult | SemaphorSqlResult | SemaphorMatrixResult;
 
 export declare type SemaphorAnalyticsResultBase = {
     intentId?: string;
@@ -506,16 +789,63 @@ export declare type SemaphorDashboardViewIntent = {
     text?: string;
 };
 
+export declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+export declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+export declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+export declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+export declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+export declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 export declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
 export declare type SemaphorExecutionFieldRef = SemaphorFieldRef & {
     semanticAggregate?: SemaphorAggregateFunction;
     effectiveAggregate?: SemaphorAggregateFunction;
     aggregateSource?: SemaphorMetricAggregateSource;
+    derivedField?: SemaphorDerivedFieldDefinition;
 };
 
 export declare type SemaphorExperienceIntent = SemaphorDashboardIntent;
 
+/**
+ * Explorer-backed table source. This is intentionally distinct from raw SQL:
+ * matrix planning needs stable source metadata, fields, and dialect context.
+ */
+export declare type SemaphorExplorerSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'physical';
+}>;
+
 export declare type SemaphorFieldRef = {
     name: string;
     label?: string;
@@ -550,6 +880,7 @@ export declare type SemaphorInputOptionsIntent = {
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 export declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
@@ -584,6 +915,157 @@ export declare type SemaphorInputSpec = {
     scope?: SemaphorInputScope;
 };
 
+export declare type SemaphorMatrixAxisExpansionOptions = {
+    defaultDepth?: number;
+    lazy?: boolean;
+    expandedPaths?: SemaphorMatrixMemberPathSegment[][];
+};
+
+export declare type SemaphorMatrixAxisLevel = {
+    id?: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    label?: string;
+    subtotal?: boolean | SemaphorMatrixSubtotalOptions;
+    sortBy?: SemaphorMatrixAxisSortRule;
+};
+
+export declare type SemaphorMatrixAxisSortRule = {
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+export declare type SemaphorMatrixDisplayLimitOptions = {
+    rows?: SemaphorMatrixDisplayLimitRule;
+    columns?: SemaphorMatrixDisplayLimitRule;
+};
+
+export declare type SemaphorMatrixDisplayLimitRule = {
+    limit: number;
+    by?: 'label' | 'value';
+    direction?: 'top' | 'bottom';
+    others?: boolean | {
+        label?: string;
+    };
+};
+
+export declare type SemaphorMatrixExpansionOptions = {
+    rows?: SemaphorMatrixAxisExpansionOptions;
+    columns?: SemaphorMatrixAxisExpansionOptions;
+};
+
+export declare type SemaphorMatrixIntent = {
+    kind: 'matrix';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorMatrixSourceRef;
+    rows: SemaphorMatrixAxisLevel[];
+    columns?: SemaphorMatrixAxisLevel[];
+    values: SemaphorMatrixValueField[];
+    filters?: SemaphorAnalyticsFilter[];
+    inputs?: SemaphorInputBinding[];
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: SemaphorMatrixLayoutOptions;
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+export declare type SemaphorMatrixLayoutOptions = {
+    hierarchy?: 'compact' | 'tabular' | 'outline';
+    valuesPlacement?: 'columns' | 'rows';
+    stickyRowHeaders?: boolean;
+    stickyColumnHeaders?: boolean;
+};
+
+export declare type SemaphorMatrixMemberPathSegment = {
+    levelId: string;
+    value: unknown;
+};
+
+export declare type SemaphorMatrixResult = SemaphorAnalyticsResultBase & {
+    kind: 'matrix';
+    intent: SemaphorMatrixIntent;
+    payload: MatrixPayload;
+    grid: MatrixGridProjection;
+    expansion?: MatrixExpansionResponseHints;
+};
+
+export declare type SemaphorMatrixSortRule = {
+    axis: 'row' | 'column';
+    targetId?: string;
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    } | {
+        kind: 'value';
+        valueId: string;
+        rowPath?: SemaphorMatrixMemberPathSegment[];
+        columnPath?: SemaphorMatrixMemberPathSegment[];
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+export declare type SemaphorMatrixSourceRef = SemaphorSemanticSourceRef | SemaphorExplorerSourceRef;
+
+export declare type SemaphorMatrixSubtotalOptions = {
+    enabled?: boolean;
+    position?: 'before' | 'after';
+    label?: string;
+};
+
+export declare type SemaphorMatrixTotalCalculation = {
+    kind: 'defaultAggregate';
+} | {
+    kind: 'blank';
+} | {
+    kind: 'labelOnly';
+    label?: string;
+} | {
+    kind: 'customAggregate';
+    aggregate: SemaphorAggregateFunction;
+} | {
+    kind: 'percentOfParent';
+} | {
+    kind: 'percentOfGrandTotal';
+} | {
+    kind: 'customExpression';
+    expressionId: string;
+};
+
+export declare type SemaphorMatrixTotalOptions = {
+    rows?: boolean | 'perLevel';
+    columns?: boolean | 'perLevel';
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+    rowPosition?: 'top' | 'bottom';
+    columnPosition?: 'left' | 'right';
+};
+
+export declare type SemaphorMatrixValueField = {
+    id?: string;
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+    label?: string;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
 export declare type SemaphorMetricAggregateSource = 'semantic_model' | 'caller_override' | 'default_sum';
 
 export declare type SemaphorMetricAnalysis = {
@@ -617,6 +1099,7 @@ export declare type SemaphorMetricIntent = {
     };
     inputs?: SemaphorInputBinding[];
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 export declare type SemaphorMetricResult = SemaphorAnalyticsResultBase & {
@@ -693,6 +1176,7 @@ export declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 export declare type SemaphorRecordsResult = SemaphorAnalyticsResultBase & {
@@ -738,6 +1222,44 @@ export declare type SemaphorRelativeTimeWindow = {
     completeness?: 'include_partial' | 'complete_periods';
 };
 
+export declare type SemaphorResultCalculation = {
+    id: string;
+    label: string;
+    kind: 'percent_of_total';
+    input: SemaphorResultColumnRef;
+    denominator?: SemaphorResultCalculationDenominator;
+    output: SemaphorResultCalculationOutput;
+} | {
+    id: string;
+    label: string;
+    kind: 'rank';
+    input: SemaphorResultColumnRef;
+    order?: 'asc' | 'desc';
+    output: SemaphorResultCalculationOutput;
+} | {
+    id: string;
+    label: string;
+    kind: 'running_total' | 'previous_row_delta';
+    input: SemaphorResultColumnRef;
+    orderBy?: SemaphorResultColumnRef;
+    output: SemaphorResultCalculationOutput;
+};
+
+export declare type SemaphorResultCalculationDenominator = {
+    scope: 'returned_result';
+} | {
+    scope: 'population';
+    metric: SemaphorFieldRef;
+    filters?: SemaphorAnalyticsFilter[];
+};
+
+export declare type SemaphorResultCalculationOutput = {
+    key: string;
+    label?: string;
+    dataType?: SemaphorFieldRef['dataType'];
+    format?: unknown;
+};
+
 export declare type SemaphorResultColumn = {
     /**
      * Stable row accessor for this result. Consumers should read values with
@@ -756,8 +1278,19 @@ export declare type SemaphorResultColumn = {
     dataType?: SemaphorFieldRef['dataType'];
     aggregate?: SemaphorFieldRef['aggregate'];
     source?: SemaphorFieldRef['source'];
+    derivedField?: SemaphorDerivedFieldDefinition;
+};
+
+export declare type SemaphorResultColumnRef = {
+    columnKey: string;
+} | {
+    field: SemaphorFieldRef;
 };
 
+export declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
 export declare type SemaphorSourceCoordinateInput = {
     databaseName?: string;
     schemaName?: string;
@@ -847,6 +1380,9 @@ export declare type SemaphorViewPresentation = {
 } | {
     kind: 'table';
     columns?: string[];
+} | {
+    kind: 'matrixTable';
+    mode?: 'auto' | 'pivot' | 'hierarchical';
 } | {
     kind: 'text';
 };
@@ -857,6 +1393,10 @@ export declare function validateSemaphorAnalyticsRecoveryPlan(plan: SemaphorAnal
 
 export declare function validateSemaphorDashboardIntent(intent: SemaphorDashboardIntent): SemaphorValidationResult;
 
+export declare function validateSemaphorDerivedFieldDefinition(definition: SemaphorDerivedFieldDefinition): SemaphorValidationResult;
+
 export declare function validateSemaphorOperationIntent(intent: SemaphorOperationIntent): SemaphorAnalyticsValidationResult;
 
+export declare function validateSemaphorResultCalculation(calculation: SemaphorResultCalculation): SemaphorValidationResult;
+
 export { }