react-semaphor 0.1.381 → 0.1.383

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

@@ -0,0 +1,733 @@
+/**
+ * Calendar context for timezone-aware date operations.
+ * Controls how dates are interpreted, grouped, and displayed.
+ */
+declare type CalendarContext = {
+    /**
+     * IANA timezone identifier.
+     * @example 'America/Chicago', 'Europe/London', 'Asia/Tokyo', 'UTC'
+     * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    tz: string;
+    /**
+     * Day the week starts on.
+     * 0 = Sunday (US, Canada, Japan)
+     * 1 = Monday (ISO standard, most of Europe)
+     * 6 = Saturday (Middle East)
+     * @default 1 (Monday) for backward compatibility
+     */
+    weekStart: WeekStart;
+    /**
+     * Date anchor for relative date calculations.
+     * - 'now': Use current time (default, live dashboards)
+     * - { iso: string }: Fixed ISO 8601 date for reproducible views
+     */
+    anchor: 'now' | {
+        iso: string;
+    };
+};
+
+export declare function hasSemaphorInputValue(value: unknown): boolean;
+
+export declare function normalizeSemaphorInputOptions(options?: Array<{
+    label: string;
+    value: SemaphorOptionValue;
+    count?: number;
+    disambiguation?: string[];
+} | SemaphorOptionValue>): {
+    label: string;
+    value: SemaphorOptionValue;
+    count?: number;
+    disambiguation?: string[];
+}[];
+
+declare type SemaphorAbsoluteTimeWindow = {
+    kind: 'absolute';
+    start: string;
+    end: string;
+};
+
+declare type SemaphorActiveInput<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBinding & {
+    kind: 'filter' | 'control';
+    label?: string;
+    value?: TValue;
+    isActive: boolean;
+    operator?: SemaphorInputOperator;
+    controlRole?: SemaphorControlRole;
+};
+
+declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+
+declare type SemaphorAnalysisDriverMode = 'absolute_delta' | 'largest_negative' | 'largest_positive' | 'positive_and_negative' | 'all';
+
+declare type SemaphorAnalysisQueryOptions = {
+    chartTitle?: string;
+    chartType?: string;
+    driverMode?: SemaphorAnalysisDriverMode;
+    includePopulation?: boolean;
+    calendarContext?: CalendarContext;
+};
+
+declare type SemaphorAnalysisQuerySpec = SemaphorMetricQuerySpec & SemaphorAnalysisQueryOptions & {
+    analysis?: SemaphorMetricIntent['analysis'];
+    timeWindow?: SemaphorMetricIntent['timeWindow'];
+    filters?: SemaphorAnalyticsFilter[];
+};
+
+declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
+
+declare type SemaphorAnalyticsFilterBase = {
+    id?: string;
+    field: SemaphorFieldRef;
+    /**
+     * Controls where the filter is applied in an aggregate query.
+     *
+     * `row` means pre-aggregation filtering (`WHERE`).
+     * `aggregate` means post-aggregation filtering (`HAVING`) and is valid only
+     * for measure fields the execution engine can aggregate safely.
+     */
+    scope?: 'row' | 'aggregate';
+};
+
+declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent | SemaphorMatrixIntent;
+
+declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
+    operator: SemaphorAnalyticsNullFilterOperator;
+    values?: never;
+};
+
+declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
+    operator?: SemaphorAnalyticsValueFilterOperator;
+    values: unknown[];
+};
+
+declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
+
+declare type SemaphorAppDerivedFieldsSpec = {
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+
+declare type SemaphorControlInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
+    kind: 'control';
+    role: SemaphorControlRole;
+};
+
+declare type SemaphorControlRole = 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
+
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+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?: SemaphorValueFormat;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'dimension' | 'date' | 'id' | 'unknown';
+
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+
+/**
+ * Explorer-backed table source. This is intentionally distinct from raw SQL:
+ * matrix planning needs stable source metadata, fields, and dialect context.
+ */
+declare type SemaphorExplorerSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'physical';
+}>;
+
+declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+declare type SemaphorFilterInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
+    kind: 'filter';
+    field: SemaphorQueryField;
+    operator?: SemaphorInputOperator;
+    relationshipHint?: SemaphorInputBinding['relationshipHint'];
+    multi?: boolean;
+};
+
+declare type SemaphorInputBase<TValue extends SemaphorInputValue> = {
+    id: string;
+    label?: string;
+    value?: TValue;
+    defaultValue?: TValue;
+    onValueChange?: {
+        bivarianceHack(value: TValue | undefined): void;
+    }['bivarianceHack'];
+    options?: Array<SemaphorInputOption | SemaphorOptionValue>;
+};
+
+declare type SemaphorInputBinding = {
+    inputId: string;
+    kind?: 'filter' | 'control';
+    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> = {
+    id: string;
+    kind: 'filter' | 'control';
+    label?: string;
+    field?: SemaphorFieldRef;
+    operator?: SemaphorInputOperator;
+    relationshipHint?: SemaphorInputBinding['relationshipHint'];
+    controlRole?: SemaphorControlRole;
+    value: TValue | undefined;
+    options: SemaphorInputOption[];
+    isActive: boolean;
+    setValue(value: TValue | undefined): void;
+    clear(): void;
+    toAnalyticsInput(): SemaphorActiveInput<TValue>;
+};
+
+declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
+
+declare type SemaphorInputOption = {
+    label: string;
+    value: SemaphorOptionValue;
+    count?: number;
+    disambiguation?: string[];
+};
+
+declare type SemaphorInputOptionsIntent = {
+    kind: 'inputOptions';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    inputId: string;
+    source: SemaphorSourceRef;
+    labelField: SemaphorFieldRef;
+    valueField: SemaphorFieldRef;
+    searchField?: SemaphorFieldRef;
+    disambiguationFields?: SemaphorFieldRef[];
+    population?: SemaphorOptionPopulation;
+    dependencies?: SemaphorOptionDependencies;
+    search?: string;
+    limit?: number;
+    inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+
+declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
+    id?: string;
+    label?: string;
+    inputId: string;
+    labelField: SemaphorQueryField;
+    valueField: SemaphorQueryField;
+    searchField?: SemaphorQueryField;
+    disambiguationFields?: SemaphorQueryField[];
+    population?: SemaphorOptionPopulation;
+    dependencies?: SemaphorOptionDependencies;
+    inputs?: SemaphorInputReference[];
+    search?: string;
+    limit?: number;
+};
+
+declare type SemaphorInputReference = SemaphorInputSpec | SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle | SemaphorInputBindingReference;
+
+declare type SemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorFilterInputSpec<TValue> | SemaphorControlInputSpec<TValue>;
+
+declare type SemaphorInputValue = SemaphorScalar | SemaphorScalar[];
+
+declare type SemaphorMatrixAxisExpansionOptions = {
+    defaultDepth?: number;
+    lazy?: boolean;
+    expandedPaths?: SemaphorMatrixMemberPathSegment[][];
+};
+
+declare type SemaphorMatrixAxisLevel = {
+    id?: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    label?: string;
+    subtotal?: boolean | SemaphorMatrixSubtotalOptions;
+    sortBy?: SemaphorMatrixAxisSortRule;
+};
+
+declare type SemaphorMatrixAxisLevelInput = SemaphorQueryField | SemaphorMatrixAxisLevel;
+
+declare type SemaphorMatrixAxisSortRule = {
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+declare type SemaphorMatrixDisplayLimitOptions = {
+    rows?: SemaphorMatrixDisplayLimitRule;
+    columns?: SemaphorMatrixDisplayLimitRule;
+};
+
+declare type SemaphorMatrixDisplayLimitRule = {
+    limit: number;
+    by?: 'label' | 'value';
+    direction?: 'top' | 'bottom';
+    others?: boolean | {
+        label?: string;
+    };
+};
+
+declare type SemaphorMatrixExpansionOptions = {
+    rows?: SemaphorMatrixAxisExpansionOptions;
+    columns?: SemaphorMatrixAxisExpansionOptions;
+};
+
+declare type SemaphorMatrixIntent = {
+    kind: 'matrix';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorMatrixSourceRef;
+    rows: SemaphorMatrixAxisLevel[];
+    columns?: SemaphorMatrixAxisLevel[];
+    values: SemaphorMatrixValueField[];
+    filters?: SemaphorAnalyticsFilter[];
+    inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: SemaphorMatrixLayoutOptions;
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+declare type SemaphorMatrixLayoutOptions = {
+    hierarchy?: 'compact' | 'tabular' | 'outline';
+    valuesPlacement?: 'columns' | 'rows';
+    stickyRowHeaders?: boolean;
+    stickyColumnHeaders?: boolean;
+};
+
+declare type SemaphorMatrixMemberPathSegment = {
+    levelId: string;
+    value: unknown;
+};
+
+declare type SemaphorMatrixQuerySpec = Omit<SemaphorMatrixIntent, 'kind' | 'version' | 'rows' | 'columns' | 'values' | 'source' | 'inputs'> & {
+    source: SemaphorMatrixSourceRef;
+    rows: SemaphorNonEmptyArray<SemaphorMatrixAxisLevelInput>;
+    columns?: SemaphorMatrixAxisLevelInput[];
+    values: SemaphorNonEmptyArray<SemaphorMatrixValueFieldInput>;
+    inputs?: SemaphorInputReference[];
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: SemaphorMatrixIntent['layout'];
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+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';
+};
+
+declare type SemaphorMatrixSourceRef = SemaphorSemanticSourceRef | SemaphorExplorerSourceRef;
+
+declare type SemaphorMatrixSubtotalOptions = {
+    enabled?: boolean;
+    position?: 'before' | 'after';
+    label?: string;
+};
+
+declare type SemaphorMatrixTotalCalculation = {
+    kind: 'defaultAggregate';
+} | {
+    kind: 'blank';
+} | {
+    kind: 'labelOnly';
+    label?: string;
+} | {
+    kind: 'customAggregate';
+    aggregate: SemaphorAggregateFunction;
+} | {
+    kind: 'percentOfParent';
+} | {
+    kind: 'percentOfGrandTotal';
+} | {
+    kind: 'customExpression';
+    expressionId: string;
+};
+
+declare type SemaphorMatrixTotalOptions = {
+    rows?: boolean | 'perLevel';
+    columns?: boolean | 'perLevel';
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+    rowPosition?: 'top' | 'bottom';
+    columnPosition?: 'left' | 'right';
+};
+
+declare type SemaphorMatrixValueField = {
+    id?: string;
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+    label?: string;
+    format?: SemaphorValueFormat;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
+declare type SemaphorMatrixValueFieldInput = SemaphorQueryField | SemaphorMatrixValueField;
+
+declare type SemaphorMetricAnalysis = {
+    kind: 'period_change';
+    orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
+    direction?: 'increase' | 'decrease' | 'both';
+    timeWindow?: SemaphorTimeWindow;
+};
+
+declare type SemaphorMetricComparison = {
+    kind: 'previous_period' | 'previous_year' | 'target';
+    targetValue?: number;
+};
+
+declare type SemaphorMetricIntent = {
+    kind: 'metric';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    source: SemaphorSourceRef;
+    measures: SemaphorFieldRef[];
+    primaryMeasure?: SemaphorFieldRef;
+    label?: string;
+    dateField?: SemaphorFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    timeWindow?: SemaphorTimeWindow;
+    dimensions?: SemaphorFieldRef[];
+    filters?: SemaphorAnalyticsFilter[];
+    comparison?: {
+        kind: 'previous_period' | 'previous_year' | 'target';
+        targetValue?: number;
+    };
+    analysis?: SemaphorMetricAnalysis;
+    orderBy?: {
+        field: SemaphorFieldRef;
+        direction: 'asc' | 'desc';
+    };
+    inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
+    limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+
+declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
+    id?: string;
+    label?: string;
+    measures: SemaphorNonEmptyArray<SemaphorQueryField>;
+    primaryMeasure?: SemaphorQueryField;
+    dateField?: SemaphorQueryField;
+    timeGrain?: SemaphorTimeGrain;
+    dimensions?: SemaphorQueryField[];
+    comparison?: SemaphorMetricComparison;
+    orderBy?: SemaphorQueryOrderBy;
+    inputs?: SemaphorInputReference[];
+    relationshipHint?: SemaphorRelationshipHint;
+    limit?: number;
+};
+
+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 SemaphorPaginationRequest = {
+    page: number;
+    pageSize: number;
+};
+
+declare type SemaphorProtocolVersion = 1;
+
+declare type SemaphorQueryField = SemaphorFieldRef;
+
+declare type SemaphorQueryOrderBy = {
+    field: SemaphorQueryField;
+    direction: 'asc' | 'desc';
+};
+
+declare type SemaphorQuerySourceSpec = {
+    source: SemaphorSourceRef;
+};
+
+declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
+    id?: string;
+    label?: string;
+    dateField?: SemaphorQueryField;
+    timeGrain?: SemaphorTimeGrain;
+    timeWindow?: SemaphorTimeWindow;
+    filters?: SemaphorAnalyticsFilter[];
+    orderBy?: SemaphorRecordsOrderBy;
+    inputs?: SemaphorInputReference[];
+    relationshipHint?: SemaphorRelationshipHint;
+    limit?: number;
+    pagination?: SemaphorPaginationRequest;
+};
+
+declare type SemaphorRecordsField = SemaphorFieldRef & {
+    role: NonNullable<SemaphorFieldRef['role']>;
+};
+
+declare type SemaphorRecordsIntent = {
+    kind: 'records';
+    version?: SemaphorProtocolVersion;
+    source: SemaphorSourceRef;
+    id?: string;
+    label?: string;
+    fields: SemaphorFieldRef[];
+    dateField?: SemaphorFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    timeWindow?: SemaphorTimeWindow;
+    filters?: SemaphorAnalyticsFilter[];
+    limit?: number;
+    pagination?: SemaphorPaginationRequest;
+    orderBy?: {
+        field: SemaphorFieldRef;
+        direction: 'asc' | 'desc';
+    };
+    inputs?: SemaphorInputBinding[];
+    relationshipHint?: SemaphorRelationshipHint;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+
+declare type SemaphorRecordsOrderBy = SemaphorQueryOrderBy;
+
+declare type SemaphorRecordsQuerySpec = SemaphorRecordsBaseQuerySpec & SemaphorRecordsSelectorSpec;
+
+declare type SemaphorRecordsSelectorSpec = {
+    fields: SemaphorNonEmptyArray<SemaphorRecordsField>;
+};
+
+declare type SemaphorRelationshipHint = {
+    relationshipIds?: string[];
+};
+
+declare type SemaphorRelativeTimeWindow = {
+    kind?: 'relative';
+    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    value: number;
+    anchor?: 'now' | 'latest_available';
+    completeness?: 'include_partial' | 'complete_periods';
+};
+
+declare type SemaphorScalar = string | number | boolean | null;
+
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    connectionType?: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
+declare type SemaphorSqlIntent = {
+    kind: 'sql';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: Extract<SemaphorSourceRef, {
+        kind: 'sql';
+    }>;
+    sql: string;
+    defaultParameters?: Record<string, unknown>;
+    pythonCode?: string;
+    limit?: number;
+    pagination?: SemaphorPaginationRequest;
+    rationale?: string;
+    fields?: SemaphorFieldRef[];
+    inputs?: SemaphorInputBinding[];
+};
+
+declare type SemaphorSqlParameterValue = SemaphorScalar | SemaphorScalar[];
+
+declare type SemaphorSqlQuerySpec = SemaphorSqlSourceSpec & {
+    id?: string;
+    label?: string;
+    sql: string;
+    defaultParameters?: Record<string, SemaphorSqlParameterValue>;
+    pythonCode?: string;
+    fields?: SemaphorFieldRef[];
+    inputs?: SemaphorInputReference[];
+    limit?: number;
+    pagination?: SemaphorPaginationRequest;
+    rationale?: string;
+};
+
+declare type SemaphorSqlSourceSpec = {
+    source: Extract<SemaphorSourceRef, {
+        kind: 'sql';
+    }>;
+};
+
+declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
+
+declare type SemaphorValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
+export declare function toSemaphorActiveInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
+
+export declare function toSemaphorAnalysisIntent(spec: SemaphorAnalysisQuerySpec): SemaphorMetricIntent;
+
+export declare function toSemaphorAnalysisQueryOptions(spec: SemaphorAnalysisQuerySpec): SemaphorAnalysisQueryOptions;
+
+export declare function toSemaphorInputBinding(input: SemaphorInputReference): SemaphorInputBinding;
+
+export declare function toSemaphorInputBindings(inputs: SemaphorInputReference[] | undefined): SemaphorInputBinding[] | undefined;
+
+export declare function toSemaphorInputOptionsIntent(spec: SemaphorInputOptionsQuerySpec): Extract<SemaphorAnalyticsIntent, {
+    kind: 'inputOptions';
+}>;
+
+export declare function toSemaphorInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
+
+export declare function toSemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputBinding & {
+    kind: SemaphorInputSpec['kind'];
+    label?: string;
+    field?: SemaphorFieldRef;
+    operator?: SemaphorInputOperator;
+    controlRole?: SemaphorControlRole;
+};
+
+export declare function toSemaphorMatrixIntent(spec: SemaphorMatrixQuerySpec): SemaphorMatrixIntent;
+
+export declare function toSemaphorMetricIntent(spec: SemaphorMetricQuerySpec): SemaphorMetricIntent;
+
+export declare function toSemaphorRecordsIntent(spec: SemaphorRecordsQuerySpec): SemaphorRecordsIntent;
+
+export declare function toSemaphorSqlIntent(spec: SemaphorSqlQuerySpec): SemaphorSqlIntent;
+
+/**
+ * Week start day type.
+ * 0 = Sunday (US, Canada, Japan)
+ * 1 = Monday (ISO standard, most of Europe)
+ * 6 = Saturday (Middle East)
+ */
+declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+export { }