react-semaphor 0.1.381 → 0.1.383

package/dist/types/data-app-sdk-validation.d.ts

@@ -27,6 +27,14 @@ declare type CalendarContext = {
     };
 };
 
+export declare function fieldWithSelectedProjectionRole(field: SemaphorFieldRef, selectedField?: SemaphorFieldRef): SemaphorFieldRef;
+
+export declare function findMatchingRelatedProjectionField(selectedFields: SemaphorFieldRef[], requestedField: SemaphorFieldRef): SemaphorFieldRef | undefined;
+
+export declare function isAllowedRelatedProjectionRole(role: SemaphorFieldRef['role'] | undefined, allowedRelatedRoles: SemaphorRelatedProjectionRole[]): role is SemaphorRelatedProjectionRole;
+
+export declare function matrixAxisFieldsForPolicy(intent: SemaphorMatrixIntent): SemaphorFieldRef[];
+
 declare type MatrixAxisLevelDescriptor = {
     instanceId: string;
     fieldKey: string;
@@ -252,6 +260,12 @@ export declare function normalizeSemaphorAnalysisQueryOptions(value: unknown, op
     validateTimezone?: SemaphorAnalysisTimezoneValidator;
 }): SemaphorAnalysisQueryOptionsValidationResult;
 
+export declare function normalizeSemaphorFieldRole(field: SemaphorFieldRef): SemaphorFieldRef['role'] | undefined;
+
+export declare function relatedProjectionFieldCandidatesForIntent(intent: RelationshipAwareProjectionIntent): SemaphorRelatedProjectionFieldCandidate[];
+
+declare type RelationshipAwareProjectionIntent = SemaphorRecordsIntent | SemaphorMetricIntent | SemaphorMatrixIntent;
+
 declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -371,7 +385,7 @@ declare type SemaphorAnalyticsExecutionResult = {
 
 declare type SemaphorAnalyticsExecutionStatus = 'answered' | 'partial' | 'failed';
 
-declare type SemaphorAnalyticsFieldRole = 'metric' | 'dateField' | 'dimension' | 'input' | 'source' | 'sql';
+declare type SemaphorAnalyticsFieldRole = 'measure' | 'date' | 'dimension' | 'input' | 'source' | 'sql';
 
 declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
 
@@ -401,7 +415,7 @@ declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
 
 declare type SemaphorAnalyticsPopulation = {
     scope: 'filtered_query';
-    metrics: Record<string, number | string | null>;
+    measures: Record<string, number | string | null>;
 };
 
 declare type SemaphorAnalyticsRepairHint = {
@@ -409,7 +423,7 @@ declare type SemaphorAnalyticsRepairHint = {
     message?: string;
     invalidField?: string;
     fieldRole?: SemaphorAnalyticsFieldRole;
-    validMetricCandidates?: string[];
+    validMeasureCandidates?: string[];
     validDateCandidates?: string[];
     validDimensionCandidates?: string[];
     recommendedNextStep: string;
@@ -427,7 +441,7 @@ declare type SemaphorAnalyticsResultBase = {
     pagination?: SemaphorPaginationMetadata;
 };
 
-declare type SemaphorAnalyticsValidationCode = 'missing_source' | 'invalid_source_kind' | 'missing_semantic_domain' | 'missing_dataset_name' | 'missing_connection_id' | 'missing_table_name' | 'missing_sql' | 'missing_metric' | 'missing_record_fields' | 'missing_input_options_field' | 'invalid_metric' | 'invalid_metric_list' | 'invalid_date_field' | 'invalid_dimension' | 'invalid_metric_dimensions' | 'conflicting_sql' | 'sql_policy_violation' | 'unsupported_intent_for_adapter' | 'invalid_analytics_kind' | 'invalid_analytics_intent';
+declare type SemaphorAnalyticsValidationCode = 'missing_source' | 'invalid_source_kind' | 'missing_semantic_domain' | 'missing_dataset_name' | 'missing_connection_id' | 'missing_table_name' | 'missing_sql' | 'missing_measure' | 'missing_record_fields' | 'missing_input_options_input_id' | 'missing_input_options_label_field' | 'missing_input_options_value_field' | 'invalid_input_options_dependencies' | 'invalid_input_options_population' | 'invalid_measure' | 'invalid_measure_list' | 'invalid_date_field' | 'invalid_dimension' | 'invalid_measure_dimensions' | 'conflicting_sql' | 'sql_policy_violation' | 'unsupported_intent_for_adapter' | 'invalid_analytics_kind' | 'invalid_analytics_intent';
 
 declare type SemaphorAnalyticsValidationIssue = SemaphorProtocolIssue & {
     code: SemaphorAnalyticsValidationCode | string;
@@ -485,7 +499,7 @@ declare type SemaphorControlInputSpec<TValue extends SemaphorInputValue = Semaph
     role: SemaphorControlRole;
 };
 
-declare type SemaphorControlRole = 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+declare type SemaphorControlRole = 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
 
 export declare type SemaphorDataAppFieldCatalog = {
     source: SemaphorSourceRef;
@@ -554,15 +568,9 @@ declare type SemaphorDerivedFieldInput = {
     kind: 'field';
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
-} | {
-    kind: 'metric';
-    metric: SemaphorFieldRef;
-} | {
-    kind: 'dimension';
-    dimension: SemaphorFieldRef;
 };
 
-declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'dimension' | 'date' | 'id' | 'unknown';
 
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
@@ -593,7 +601,8 @@ declare type SemaphorFieldRef = {
 declare type SemaphorFilterInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
     kind: 'filter';
     field: SemaphorQueryField;
-    operator?: SemaphorInputOperatorInput;
+    operator?: SemaphorInputOperator;
+    relationshipHint?: SemaphorInputBinding['relationshipHint'];
     multi?: boolean;
 };
 
@@ -611,9 +620,14 @@ declare type SemaphorInputBase<TValue extends SemaphorInputValue> = {
 declare type SemaphorInputBinding = {
     inputId: string;
     kind?: 'filter' | 'control';
-    controlRole?: 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+    controlRole?: 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
     operator?: SemaphorInputOperator;
     field?: SemaphorFieldRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+
+declare type SemaphorInputBindingReference<TValue extends SemaphorInputValue = SemaphorInputValue> = {
+    toAnalyticsInput(): SemaphorActiveInput<TValue>;
 };
 
 declare type SemaphorInputHandle<TValue extends SemaphorInputValue = SemaphorInputValue> = {
@@ -622,6 +636,7 @@ declare type SemaphorInputHandle<TValue extends SemaphorInputValue = SemaphorInp
     label?: string;
     field?: SemaphorFieldRef;
     operator?: SemaphorInputOperator;
+    relationshipHint?: SemaphorInputBinding['relationshipHint'];
     controlRole?: SemaphorControlRole;
     value: TValue | undefined;
     options: SemaphorInputOption[];
@@ -633,14 +648,11 @@ declare type SemaphorInputHandle<TValue extends SemaphorInputValue = SemaphorInp
 
 declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
 
-declare type SemaphorInputOperatorAlias = 'eq' | 'equals' | 'not_equals' | 'neq' | 'not equal' | 'not equals' | 'not in' | 'like' | 'not_contains' | 'not contains' | 'not_like' | 'not like' | 'not_between' | 'not between';
-
-declare type SemaphorInputOperatorInput = SemaphorInputOperator | SemaphorInputOperatorAlias;
-
 declare type SemaphorInputOption = {
     label: string;
     value: SemaphorOptionValue;
     count?: number;
+    disambiguation?: string[];
 };
 
 declare type SemaphorInputOptionsIntent = {
@@ -648,10 +660,17 @@ declare type SemaphorInputOptionsIntent = {
     version?: SemaphorProtocolVersion;
     id?: string;
     label?: string;
+    inputId: string;
     source: SemaphorSourceRef;
-    field: SemaphorFieldRef;
+    labelField: SemaphorFieldRef;
+    valueField: SemaphorFieldRef;
+    searchField?: SemaphorFieldRef;
+    disambiguationFields?: SemaphorFieldRef[];
+    population?: SemaphorOptionPopulation;
+    dependencies?: SemaphorOptionDependencies;
     search?: string;
     limit?: number;
+    inputs?: SemaphorInputBinding[];
     derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
@@ -662,7 +681,14 @@ declare type SemaphorInputOptionsQueryDefinition = SemaphorInputOptionsQuerySpec
 declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
-    field: SemaphorQueryField;
+    inputId: string;
+    labelField: SemaphorQueryField;
+    valueField: SemaphorQueryField;
+    searchField?: SemaphorQueryField;
+    disambiguationFields?: SemaphorQueryField[];
+    population?: SemaphorOptionPopulation;
+    dependencies?: SemaphorOptionDependencies;
+    inputs?: SemaphorInputReference[];
     search?: string;
     limit?: number;
 };
@@ -673,10 +699,11 @@ declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
         label: string;
         value: unknown;
         count?: number;
+        disambiguation?: string[];
     }>;
 };
 
-declare type SemaphorInputReference = SemaphorInputSpec | SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle;
+declare type SemaphorInputReference = SemaphorInputSpec | SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle | SemaphorInputBindingReference;
 
 declare type SemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorFilterInputSpec<TValue> | SemaphorControlInputSpec<TValue>;
 
@@ -742,6 +769,7 @@ declare type SemaphorMatrixIntent = {
     values: SemaphorMatrixValueField[];
     filters?: SemaphorAnalyticsFilter[];
     inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
     totals?: SemaphorMatrixTotalOptions;
     sort?: SemaphorMatrixSortRule[];
     expansion?: SemaphorMatrixExpansionOptions;
@@ -890,8 +918,8 @@ declare type SemaphorMetricIntent = {
     version?: SemaphorProtocolVersion;
     id?: string;
     source: SemaphorSourceRef;
-    metrics: SemaphorFieldRef[];
-    primaryMetric?: SemaphorFieldRef;
+    measures: SemaphorFieldRef[];
+    primaryMeasure?: SemaphorFieldRef;
     label?: string;
     dateField?: SemaphorFieldRef;
     timeGrain?: SemaphorTimeGrain;
@@ -908,6 +936,7 @@ declare type SemaphorMetricIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
     limit?: number;
     derivedFields?: SemaphorDerivedFieldDefinition[];
 };
@@ -919,14 +948,15 @@ declare type SemaphorMetricQueryDefinition = SemaphorMetricQuerySpec & {
 declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
     id?: string;
     label?: string;
-    metrics: SemaphorNonEmptyArray<SemaphorQueryField>;
-    primaryMetric?: SemaphorQueryField;
+    measures: SemaphorNonEmptyArray<SemaphorQueryField>;
+    primaryMeasure?: SemaphorQueryField;
     dateField?: SemaphorQueryField;
     timeGrain?: SemaphorTimeGrain;
     dimensions?: SemaphorQueryField[];
     comparison?: SemaphorMetricComparison;
     orderBy?: SemaphorQueryOrderBy;
     inputs?: SemaphorInputReference[];
+    relationshipHint?: SemaphorRelationshipHint;
     limit?: number;
 };
 
@@ -943,6 +973,21 @@ declare type SemaphorMetricResult = SemaphorAnalyticsResultBase & {
 
 declare type SemaphorNonEmptyArray<T> = [T, ...T[]];
 
+declare type SemaphorOptionDependencies = {
+    mode?: 'auto' | 'independent' | 'explicit';
+    includeInputIds?: string[];
+    excludeInputIds?: string[];
+};
+
+declare type SemaphorOptionPopulation = {
+    kind: 'option_source';
+    baseSource?: never;
+} | {
+    kind: 'related_population';
+    baseSource: SemaphorSourceRef;
+    relationshipHint?: SemaphorRelationshipHint;
+};
+
 declare type SemaphorOptionValue = string | number | boolean;
 
 declare type SemaphorPaginationMetadata = {
@@ -991,6 +1036,7 @@ declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & SemaphorAp
     filters?: SemaphorAnalyticsFilter[];
     orderBy?: SemaphorRecordsOrderBy;
     inputs?: SemaphorInputReference[];
+    relationshipHint?: SemaphorRelationshipHint;
     limit?: number;
     pagination?: SemaphorPaginationRequest;
 };
@@ -1017,6 +1063,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
     derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
@@ -1038,6 +1085,15 @@ declare type SemaphorRecordsSelectorSpec = {
     fields: SemaphorNonEmptyArray<SemaphorRecordsField>;
 };
 
+export declare type SemaphorRelatedProjectionFieldCandidate = {
+    field: SemaphorFieldRef;
+    allowedRelatedRoles: SemaphorRelatedProjectionRole[];
+    unsupportedRelatedRoleMessage?: string;
+    recommendedNextStep?: string;
+};
+
+export declare type SemaphorRelatedProjectionRole = Extract<NonNullable<SemaphorFieldRef['role']>, 'dimension' | 'date' | 'id'>;
+
 declare type SemaphorRelationshipDiagnostics = {
     status: SemaphorRelationshipDiagnosticStatus;
     requiredSources?: SemaphorSourceRef[];
@@ -1059,6 +1115,10 @@ declare type SemaphorRelationshipDiagnostics = {
 
 declare type SemaphorRelationshipDiagnosticStatus = 'not_required' | 'resolved' | 'missing' | 'ambiguous' | 'fanout_risk' | 'unknown';
 
+declare type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
     unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';