react-semaphor 0.1.345 → 0.1.347

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

@@ -2,20 +2,29 @@ import { Context } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
-export declare function createSemaphorDataAppExecutor(): SemaphorDataAppExecutor;
+export declare function createSemaphorQueryExecutor(): SemaphorQueryExecutor;
 
 export declare function hasSemaphorInputValue(value: unknown): boolean;
 
 export declare function normalizeSemaphorInputOptions(options?: Array<{
     label: string;
-    value: SemaphorDataAppOptionValue;
-} | SemaphorDataAppOptionValue>): {
+    value: SemaphorOptionValue;
+} | SemaphorOptionValue>): {
     label: string;
-    value: SemaphorDataAppOptionValue;
+    value: SemaphorOptionValue;
 }[];
 
 export declare function readWindowRuntime(): SemaphorDataAppWindowRuntime | undefined;
 
+export 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 SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
@@ -43,108 +52,164 @@ declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
 
-export declare const SemaphorDataAppContext: Context<SemaphorDataAppRuntime>;
-
-export declare type SemaphorDataAppControlInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppInputBase<TValue> & {
+export declare type SemaphorControlInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
     kind: 'control';
-    role: SemaphorDataAppControlRole;
+    role: SemaphorControlRole;
 };
 
-export declare type SemaphorDataAppControlRole = 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+export declare type SemaphorControlRole = 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
 
-export declare type SemaphorDataAppExecutor = {
-    executeMetric(intent: SemaphorMetricIntent, context: SemaphorDataAppExecutorContext): Promise<SemaphorDataAppMetricData>;
-    executeRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(intent: SemaphorRecordsIntent, context: SemaphorDataAppExecutorContext): Promise<SemaphorDataAppRecordsData<TRecord>>;
-    executeInputOptions(intent: Extract<SemaphorAnalyticsIntent, {
-        kind: 'inputOptions';
-    }>, context: SemaphorDataAppExecutorContext): Promise<SemaphorDataAppInputOptionsData>;
+export declare const SemaphorDataAppContext: Context<SemaphorDataAppRuntime>;
+
+export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, children, }: SemaphorDataAppProviderProps): JSX.Element;
+
+export declare type SemaphorDataAppProviderProps = SemaphorQueryExecutorContext & {
+    executor?: SemaphorQueryExecutor;
+    children: ReactNode;
 };
 
-export declare type SemaphorDataAppExecutorContext = {
-    token?: string;
+export declare type SemaphorDataAppRuntime = SemaphorQueryExecutorContext & {
+    executor?: SemaphorQueryExecutor;
+};
+
+declare type SemaphorDataAppWindowRuntime = {
     apiBaseUrl?: string;
-    activeInputs?: SemaphorDataAppInputSnapshot[];
+    dataApiBaseUrl?: string;
+    authToken?: null | {
+        accessToken?: string;
+    };
 };
 
-export declare type SemaphorDataAppFieldSpec = SemaphorFieldRef;
+declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
-export declare type SemaphorDataAppFilterInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppInputBase<TValue> & {
+declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
+export declare type SemaphorFilterInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
     kind: 'filter';
-    field: SemaphorDataAppFieldSpec;
+    field: SemaphorQueryField;
     operator?: SemaphorInputOperator;
     multi?: boolean;
 };
 
-declare type SemaphorDataAppInputBase<TValue extends SemaphorDataAppInputValue> = {
+declare type SemaphorInputBase<TValue extends SemaphorInputValue> = {
     id: string;
     label?: string;
     value?: TValue;
     defaultValue?: TValue;
     onValueChange?: (value: TValue | undefined) => void;
-    options?: Array<SemaphorDataAppInputOption | SemaphorDataAppOptionValue>;
+    options?: Array<SemaphorInputOption | SemaphorOptionValue>;
 };
 
-export declare type SemaphorDataAppInputHandle<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = {
+declare type SemaphorInputBinding = {
+    inputId: string;
+    field?: SemaphorFieldRef;
+};
+
+export declare type SemaphorInputHandle<TValue extends SemaphorInputValue = SemaphorInputValue> = {
     id: string;
     kind: 'filter' | 'control';
     label?: string;
     field?: SemaphorFieldRef;
     operator?: SemaphorInputOperator;
-    controlRole?: SemaphorDataAppControlRole;
+    controlRole?: SemaphorControlRole;
     value: TValue | undefined;
-    options: SemaphorDataAppInputOption[];
+    options: SemaphorInputOption[];
     isActive: boolean;
     setValue(value: TValue | undefined): void;
     clear(): void;
-    toAnalyticsInput(): SemaphorDataAppInputSnapshot<TValue>;
+    toAnalyticsInput(): SemaphorActiveInput<TValue>;
 };
 
-export declare type SemaphorDataAppInputOption = {
+declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
+
+export declare type SemaphorInputOption = {
     label: string;
-    value: SemaphorDataAppOptionValue;
+    value: SemaphorOptionValue;
     count?: number;
 };
 
-export declare type SemaphorDataAppInputOptionsData = {
-    options: SemaphorDataAppInputOption[];
+declare type SemaphorInputOptionsIntent = {
+    kind: 'inputOptions';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorSourceRef;
+    field: SemaphorFieldRef;
+    search?: string;
+    limit?: number;
 };
 
-export declare type SemaphorDataAppInputOptionsResult = SemaphorDataAppQueryState & SemaphorDataAppInputOptionsData & {
+export declare type SemaphorInputOptionsPayload = {
+    options: SemaphorInputOption[];
+};
+
+export declare type SemaphorInputOptionsQueryResult = SemaphorQueryState & SemaphorInputOptionsPayload & {
     id?: string;
     intent?: Extract<SemaphorAnalyticsIntent, {
         kind: 'inputOptions';
     }>;
 };
 
-export declare type SemaphorDataAppInputOptionsSpec = SemaphorDataAppSourceSpec & {
+export declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & {
     id?: string;
     label?: string;
-    field: SemaphorDataAppFieldSpec;
+    field: SemaphorQueryField;
     search?: string;
     limit?: number;
 };
 
-export declare type SemaphorDataAppInputReference = SemaphorInputBinding | SemaphorDataAppInputSnapshot | SemaphorDataAppInputHandle;
+export declare type SemaphorInputReference = SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle;
 
-export declare type SemaphorDataAppInputSnapshot<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorInputBinding & {
-    kind: 'filter' | 'control';
-    label?: string;
-    value?: TValue;
-    isActive: boolean;
-    operator?: SemaphorInputOperator;
-    controlRole?: SemaphorDataAppControlRole;
-};
+export declare type SemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorFilterInputSpec<TValue> | SemaphorControlInputSpec<TValue>;
 
-export declare type SemaphorDataAppInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppFilterInputSpec<TValue> | SemaphorDataAppControlInputSpec<TValue>;
+export declare type SemaphorInputValue = SemaphorScalar | SemaphorScalar[];
 
-export declare type SemaphorDataAppInputValue = SemaphorDataAppScalar | SemaphorDataAppScalar[];
+declare type SemaphorMetricAnalysis = {
+    kind: 'period_change';
+    orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
+    direction?: 'increase' | 'decrease' | 'both';
+    timeWindow?: SemaphorTimeWindow;
+};
 
-export declare type SemaphorDataAppMetricComparison = {
+export declare type SemaphorMetricComparison = {
     kind: 'previous_period' | 'previous_year' | 'target';
     targetValue?: number;
 };
 
-export declare type SemaphorDataAppMetricData = {
+declare type SemaphorMetricIntent = {
+    kind: 'metric';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    source: SemaphorSourceRef;
+    metrics: SemaphorFieldRef[];
+    primaryMetric?: 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[];
+    limit?: number;
+};
+
+export declare type SemaphorMetricPayload = {
     value: number | string | null;
     metrics?: Record<string, number | string | null>;
     comparisonValue?: number | string | null;
@@ -153,168 +218,77 @@ export declare type SemaphorDataAppMetricData = {
     records?: Array<Record<string, unknown>>;
 };
 
-export declare type SemaphorDataAppMetricResult = SemaphorDataAppQueryState & SemaphorDataAppMetricData & {
+export declare type SemaphorMetricQueryResult = SemaphorQueryState & SemaphorMetricPayload & {
     id?: string;
     intent?: SemaphorMetricIntent;
 };
 
-export declare type SemaphorDataAppMetricSpec = SemaphorDataAppSourceSpec & {
+export declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & {
     id?: string;
     label?: string;
-    metrics: SemaphorDataAppNonEmptyArray<SemaphorDataAppFieldSpec>;
-    primaryMetric?: SemaphorDataAppFieldSpec;
-    dateField?: SemaphorDataAppFieldSpec;
+    metrics: SemaphorNonEmptyArray<SemaphorQueryField>;
+    primaryMetric?: SemaphorQueryField;
+    dateField?: SemaphorQueryField;
     timeGrain?: SemaphorTimeGrain;
-    dimensions?: SemaphorDataAppFieldSpec[];
-    comparison?: SemaphorDataAppMetricComparison;
-    orderBy?: SemaphorDataAppOrderBy;
-    inputs?: SemaphorDataAppInputReference[];
+    dimensions?: SemaphorQueryField[];
+    comparison?: SemaphorMetricComparison;
+    orderBy?: SemaphorQueryOrderBy;
+    inputs?: SemaphorInputReference[];
     limit?: number;
 };
 
-export declare type SemaphorDataAppNonEmptyArray<T> = [T, ...T[]];
-
-export declare type SemaphorDataAppOptionValue = string | number | boolean;
-
-export declare type SemaphorDataAppOrderBy = {
-    field: SemaphorDataAppFieldSpec;
-    direction: 'asc' | 'desc';
-};
-
-export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, children, }: SemaphorDataAppProviderProps): JSX.Element;
+export declare type SemaphorNonEmptyArray<T> = [T, ...T[]];
 
-export declare type SemaphorDataAppProviderProps = SemaphorDataAppExecutorContext & {
-    executor?: SemaphorDataAppExecutor;
-    children: ReactNode;
-};
+export declare type SemaphorOptionValue = string | number | boolean;
 
-export declare type SemaphorDataAppQueryState = {
-    status: SemaphorDataAppQueryStatus;
-    isLoading: boolean;
-    error: Error | null;
-};
-
-export declare type SemaphorDataAppQueryStatus = 'idle' | 'loading' | 'success' | 'error';
-
-declare type SemaphorDataAppRecordsBaseSpec = SemaphorDataAppSourceSpec & {
-    id?: string;
-    label?: string;
-    dateField?: SemaphorDataAppFieldSpec;
-    timeGrain?: SemaphorTimeGrain;
-    orderBy?: SemaphorDataAppRecordsOrderBy;
-    inputs?: SemaphorDataAppInputReference[];
-    limit?: number;
-};
-
-export declare type SemaphorDataAppRecordsData<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
-    records: TRecord[];
-    columns?: Array<{
-        name: string;
-        label?: string;
-        dataType?: SemaphorFieldRef['dataType'];
-        role?: SemaphorFieldRef['role'];
-    }>;
-    rowCount?: number;
-};
-
-export declare type SemaphorDataAppRecordsFieldSpec = SemaphorFieldRef & {
-    role: NonNullable<SemaphorFieldRef['role']>;
-};
-
-export declare type SemaphorDataAppRecordsOrderBy = SemaphorDataAppOrderBy;
-
-export declare type SemaphorDataAppRecordsResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorDataAppQueryState & SemaphorDataAppRecordsData<TRecord> & {
-    id?: string;
-    intent?: SemaphorRecordsIntent;
-};
-
-declare type SemaphorDataAppRecordsSelectorSpec = {
-    fields: SemaphorDataAppNonEmptyArray<SemaphorDataAppRecordsFieldSpec>;
-};
-
-export declare type SemaphorDataAppRecordsSpec = SemaphorDataAppRecordsBaseSpec & SemaphorDataAppRecordsSelectorSpec;
-
-export declare type SemaphorDataAppRuntime = SemaphorDataAppExecutorContext & {
-    executor?: SemaphorDataAppExecutor;
-};
-
-export declare type SemaphorDataAppScalar = string | number | boolean | null;
+declare type SemaphorProtocolVersion = 1;
 
-export declare type SemaphorDataAppSourceSpec = {
-    source: SemaphorSourceRef;
+export declare type SemaphorQueryExecutor = {
+    executeMetric(intent: SemaphorMetricIntent, context: SemaphorQueryExecutorContext): Promise<SemaphorMetricPayload>;
+    executeRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(intent: SemaphorRecordsIntent, context: SemaphorQueryExecutorContext): Promise<SemaphorRecordsPayload<TRecord>>;
+    executeInputOptions(intent: Extract<SemaphorAnalyticsIntent, {
+        kind: 'inputOptions';
+    }>, context: SemaphorQueryExecutorContext): Promise<SemaphorInputOptionsPayload>;
 };
 
-declare type SemaphorDataAppWindowRuntime = {
+export declare type SemaphorQueryExecutorContext = {
+    token?: string;
     apiBaseUrl?: string;
-    dataApiBaseUrl?: string;
-    authToken?: null | {
-        accessToken?: string;
-    };
+    activeInputs?: SemaphorActiveInput[];
 };
 
-declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
-
-declare type SemaphorFieldRef = {
-    name: string;
-    label?: string;
-    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
-    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
-    source?: SemaphorSourceRef;
-    aggregate?: SemaphorAggregateFunction;
-};
+export declare type SemaphorQueryField = SemaphorFieldRef;
 
-declare type SemaphorInputBinding = {
-    inputId: string;
-    field?: SemaphorFieldRef;
+export declare type SemaphorQueryOrderBy = {
+    field: SemaphorQueryField;
+    direction: 'asc' | 'desc';
 };
 
-declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
-
-declare type SemaphorInputOptionsIntent = {
-    kind: 'inputOptions';
-    version?: SemaphorProtocolVersion;
-    id?: string;
-    label?: string;
+export declare type SemaphorQuerySourceSpec = {
     source: SemaphorSourceRef;
-    field: SemaphorFieldRef;
-    search?: string;
-    limit?: number;
 };
 
-declare type SemaphorMetricAnalysis = {
-    kind: 'period_change';
-    orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
-    direction?: 'increase' | 'decrease' | 'both';
-    timeWindow?: SemaphorTimeWindow;
+export declare type SemaphorQueryState = {
+    status: SemaphorQueryStatus;
+    isLoading: boolean;
+    error: Error | null;
 };
 
-declare type SemaphorMetricIntent = {
-    kind: 'metric';
-    version?: SemaphorProtocolVersion;
+export declare type SemaphorQueryStatus = 'idle' | 'loading' | 'success' | 'error';
+
+declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & {
     id?: string;
-    source: SemaphorSourceRef;
-    metrics: SemaphorFieldRef[];
-    primaryMetric?: SemaphorFieldRef;
     label?: string;
-    dateField?: SemaphorFieldRef;
+    dateField?: SemaphorQueryField;
     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[];
+    orderBy?: SemaphorRecordsOrderBy;
+    inputs?: SemaphorInputReference[];
     limit?: number;
 };
 
-declare type SemaphorProtocolVersion = 1;
+export declare type SemaphorRecordsField = SemaphorFieldRef & {
+    role: NonNullable<SemaphorFieldRef['role']>;
+};
 
 declare type SemaphorRecordsIntent = {
     kind: 'records';
@@ -333,6 +307,47 @@ declare type SemaphorRecordsIntent = {
     inputs?: SemaphorInputBinding[];
 };
 
+export declare type SemaphorRecordsOrderBy = SemaphorQueryOrderBy;
+
+export declare type SemaphorRecordsPayload<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
+    records: TRecord[];
+    columns?: SemaphorResultColumn[];
+    rowCount?: number;
+};
+
+export declare type SemaphorRecordsQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryState & SemaphorRecordsPayload<TRecord> & {
+    id?: string;
+    intent?: SemaphorRecordsIntent;
+};
+
+export declare type SemaphorRecordsQuerySpec = SemaphorRecordsBaseQuerySpec & SemaphorRecordsSelectorSpec;
+
+declare type SemaphorRecordsSelectorSpec = {
+    fields: SemaphorNonEmptyArray<SemaphorRecordsField>;
+};
+
+export declare type SemaphorResultColumn = {
+    /**
+     * Stable row accessor for this result. Consumers should read values with
+     * `row[column.key]`; labels are display-only and may change.
+     */
+    key: string;
+    /**
+     * Semantic/source field name before result-key disambiguation.
+     */
+    name: string;
+    /**
+     * Human-facing display label.
+     */
+    label: string;
+    role?: SemaphorFieldRef['role'];
+    dataType?: SemaphorFieldRef['dataType'];
+    aggregate?: SemaphorFieldRef['aggregate'];
+    source?: SemaphorFieldRef['source'];
+};
+
+export declare type SemaphorScalar = string | number | boolean | null;
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -382,37 +397,37 @@ declare type SemaphorTimeWindow = {
     completeness?: 'include_partial' | 'complete_periods';
 };
 
-export declare function toSemaphorActiveInputSnapshots(inputs: SemaphorDataAppInputReference[] | undefined): SemaphorDataAppInputSnapshot[];
+export declare function toSemaphorActiveInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
 
-export declare function toSemaphorInputBinding(input: SemaphorDataAppInputReference): SemaphorInputBinding;
+export declare function toSemaphorInputBinding(input: SemaphorInputReference): SemaphorInputBinding;
 
-export declare function toSemaphorInputBindings(inputs: SemaphorDataAppInputReference[] | undefined): SemaphorInputBinding[] | undefined;
+export declare function toSemaphorInputBindings(inputs: SemaphorInputReference[] | undefined): SemaphorInputBinding[] | undefined;
 
-export declare function toSemaphorInputOptionsIntent(spec: SemaphorDataAppInputOptionsSpec): Extract<SemaphorAnalyticsIntent, {
+export declare function toSemaphorInputOptionsIntent(spec: SemaphorInputOptionsQuerySpec): Extract<SemaphorAnalyticsIntent, {
     kind: 'inputOptions';
 }>;
 
-export declare function toSemaphorInputSnapshots(inputs: SemaphorDataAppInputReference[] | undefined): SemaphorDataAppInputSnapshot[];
+export declare function toSemaphorInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
 
-export declare function toSemaphorInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue>(spec: SemaphorDataAppInputSpec<TValue>): SemaphorInputBinding & {
-    kind: SemaphorDataAppInputSpec['kind'];
+export declare function toSemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputBinding & {
+    kind: SemaphorInputSpec['kind'];
     label?: string;
     field?: SemaphorFieldRef;
     operator?: SemaphorInputOperator;
 };
 
-export declare function toSemaphorMetricIntent(spec: SemaphorDataAppMetricSpec): SemaphorMetricIntent;
+export declare function toSemaphorMetricIntent(spec: SemaphorMetricQuerySpec): SemaphorMetricIntent;
 
-export declare function toSemaphorRecordsIntent(spec: SemaphorDataAppRecordsSpec): SemaphorRecordsIntent;
+export declare function toSemaphorRecordsIntent(spec: SemaphorRecordsQuerySpec): SemaphorRecordsIntent;
 
 export declare function useSemaphorDataAppRuntime(): SemaphorDataAppRuntime;
 
-export declare function useSemaphorInput<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue>(spec: SemaphorDataAppInputSpec<TValue>): SemaphorDataAppInputHandle;
+export declare function useSemaphorInput<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputHandle;
 
-export declare function useSemaphorInputOptions(spec: SemaphorDataAppInputOptionsSpec): SemaphorDataAppInputOptionsResult;
+export declare function useSemaphorInputOptions(spec: SemaphorInputOptionsQuerySpec): SemaphorInputOptionsQueryResult;
 
-export declare function useSemaphorMetric(spec: SemaphorDataAppMetricSpec): SemaphorDataAppMetricResult;
+export declare function useSemaphorMetric(spec: SemaphorMetricQuerySpec): SemaphorMetricQueryResult;
 
-export declare function useSemaphorRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(spec: SemaphorDataAppRecordsSpec): SemaphorDataAppRecordsResult<TRecord>;
+export declare function useSemaphorRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(spec: SemaphorRecordsQuerySpec): SemaphorRecordsQueryResult<TRecord>;
 
 export { }

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.345",
+  "version": "0.1.347",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",

package/dist/chunks/validators-8R9pr2K9.js

@@ -1 +0,0 @@
-"use strict";function _(e){return e?e.kind==="semantic"?[e.kind,e.domainId,e.datasetId||"",e.datasetName].join(":"):e.kind==="physical"?[e.kind,e.connectionId,e.databaseName||"",e.schemaName||"",e.tableName].join(":"):[e.kind,e.connectionId,e.dialect||"",e.label||""].join(":"):""}function b(e,i){return!e||!i?e===i:e.kind!==i.kind?!1:e.kind==="semantic"&&i.kind==="semantic"?e.domainId!==i.domainId?!1:e.datasetId&&i.datasetId?e.datasetId===i.datasetId:e.datasetName===i.datasetName:_(e)===_(i)}function A(e,i){return e.kind!=="semantic"||i.kind!=="semantic"?e:{...e,datasetId:e.datasetId||i.datasetId,label:e.label||i.label,connectionId:e.connectionId||i.connectionId}}function I(e,i){return e.name===i.name&&b(e.source,i.source)}function F(e,i){return{...e,label:e.label||i.label,role:e.role||i.role,dataType:e.dataType||i.dataType,source:e.source&&i.source?A(e.source,i.source):e.source||i.source}}function a(e,i,n){return n?{code:e,message:i,path:n}:{code:e,message:i}}function j(e){for(let i=0;i<e.length;i+=1){const n=e[i];if(e.some((o,r)=>r!==i&&M(o,n)))return!1}return!0}function S(e,i){return I(e,i)}function M(e,i){return S(e,i)&&y(e)===y(i)}function T(e){return`Metric intent has duplicate metric "${e.name}" with the same aggregate (${y(e)}). Use different aggregates to request both, or remove one entry.`}function D(e,i){return h(e,i).length===1}function x(e,i){return h(e,i).length===1}function h(e,i){return i.filter(o=>q(e,o))}function q(e,i){return C(e,i)?e.source?S(i,e):!0:!1}function C(e,i){return!(i.name!==e.name||e.role!==void 0&&i.role!==void 0&&i.role!==e.role||E(e,i)&&y(i)!==y(e))}function E(e,i){return e.role==="measure"||i.role==="measure"||e.aggregate!==void 0||i.aggregate!==void 0}function y(e){return(e.aggregate||"SUM").toUpperCase()}function d(e){return typeof e=="string"&&e.trim().length>0}function c(e){return!!(e&&typeof e=="object"&&!Array.isArray(e))}function g(e){const i=new Set;for(const n of e){if(i.has(n))return n;i.add(n)}return null}const P=new Set(["SUM","COUNT","AVG","MIN","MAX","MEDIAN","DISTINCT"]);function k(e,i,n){if(!e||typeof e!="object"){n.push(a("missing_source","Analytics intent needs a source.",i));return}if(e.kind==="semantic"){d(e.domainId)||n.push(a("missing_semantic_domain","Semantic source needs a domainId.",`${i}.domainId`)),d(e.datasetName)||n.push(a("missing_dataset_name","Semantic source needs a datasetName.",`${i}.datasetName`));return}if(e.kind==="physical"){d(e.connectionId)||n.push(a("missing_connection_id","Physical source needs a connectionId.",`${i}.connectionId`)),d(e.tableName)||n.push(a("missing_table_name","Physical source needs a tableName.",`${i}.tableName`));return}if(e.kind==="sql"){d(e.connectionId)||n.push(a("missing_connection_id","SQL source needs a connectionId.",`${i}.connectionId`));return}n.push(a("invalid_source_kind","Source kind is not supported.",i))}function f(e,i,n,o={}){if(!e||!c(e)){o.required&&n.push(a("missing_field_ref","Field reference needs a name.",i));return}d(e.name)||n.push(a("missing_field_ref","Field reference needs a name.",`${i}.name`)),e.source!==void 0&&k(e.source,`${i}.source`,n),O(e.aggregate,`${i}.aggregate`,n)}function O(e,i,n){e!==void 0&&(typeof e!="string"||!P.has(e))&&n.push(a("invalid_aggregate","Field aggregate must be SUM, COUNT, AVG, MIN, MAX, MEDIAN, or DISTINCT.",i))}function H(e,i){if(e.analysis===void 0)return;if(!c(e.analysis)){i.push(a("invalid_metric_analysis","Metric analysis must be a structured object.","analysis"));return}if(e.analysis.kind!=="period_change"){i.push(a("invalid_metric_analysis","Metric analysis kind is not supported.","analysis.kind"));return}e.dateField||i.push(a("missing_analysis_date_field","Period-change analysis needs a dateField.","dateField")),e.timeGrain||i.push(a("missing_analysis_time_grain","Period-change analysis needs a timeGrain.","timeGrain")),e.analysis.orderBy!==void 0&&e.analysis.orderBy!=="absolute_change"&&e.analysis.orderBy!=="positive_change"&&e.analysis.orderBy!=="negative_change"&&e.analysis.orderBy!=="period"&&i.push(a("invalid_metric_analysis","Period-change analysis orderBy must be absolute_change, positive_change, negative_change, or period.","analysis.orderBy"));const{timeWindow:n}=e.analysis;n!==void 0&&w(n,"analysis.timeWindow",i)}function w(e,i,n){if(!c(e)){n.push(a("invalid_time_window","Time window must be a structured object.",i));return}e.unit!=="second"&&e.unit!=="minute"&&e.unit!=="hour"&&e.unit!=="day"&&e.unit!=="week"&&e.unit!=="month"&&e.unit!=="quarter"&&e.unit!=="year"&&n.push(a("invalid_time_window","Time window unit must be second, minute, hour, day, week, month, quarter, or year.",`${i}.unit`)),(typeof e.value!="number"||!Number.isFinite(e.value)||e.value<=0)&&n.push(a("invalid_time_window","Time window value must be a positive number.",`${i}.value`)),e.anchor!==void 0&&e.anchor!=="now"&&e.anchor!=="latest_available"&&n.push(a("invalid_time_window","Time window anchor must be now or latest_available.",`${i}.anchor`)),e.completeness!==void 0&&e.completeness!=="include_partial"&&e.completeness!=="complete_periods"&&n.push(a("invalid_time_window","Time window completeness must be include_partial or complete_periods.",`${i}.completeness`))}function U(e,i,n){if(e!==void 0){if(!Array.isArray(e)){n.push(a("invalid_analytics_filters","Analytics filters must be an array.",i));return}e.forEach((o,r)=>{const s=`${i}.${r}`;if(!c(o)){n.push(a("invalid_analytics_filter","Analytics filter must be a structured object.",s));return}const t=o;f(t.field,`${s}.field`,n,{required:!0});const p=t.operator==="is_null"||t.operator==="is_not_null";if(t.operator!==void 0&&t.operator!=="="&&t.operator!=="!="&&t.operator!=="in"&&t.operator!=="not_in"&&t.operator!=="contains"&&t.operator!=="not_contains"&&t.operator!=="between"&&t.operator!=="not_between"&&t.operator!==">"&&t.operator!==">="&&t.operator!=="<"&&t.operator!=="<="&&t.operator!=="is_null"&&t.operator!=="is_not_null"&&n.push(a("invalid_analytics_filter_operator","Analytics filter operator is not supported.",`${s}.operator`)),t.values===void 0&&!p&&n.push(a("missing_analytics_filter_value","Analytics filter needs values unless it is a null check.",s)),p&&t.values!==void 0){n.push(a("invalid_analytics_filter_values","Null-check analytics filters must not include values.",`${s}.values`));return}t.values!==void 0&&!Array.isArray(t.values)&&n.push(a("invalid_analytics_filter_values","Analytics filter values must be an array when provided.",`${s}.values`))})}}function v(e){var o;const i=[],n=[];if(!e||typeof e!="object")return{ok:!1,errors:[a("invalid_analytics_intent","Analytics intent must be a structured object.")],warnings:n,repairHints:[{code:"invalid_analytics_intent",recommendedNextStep:"Send one structured analytics intent object with kind, source, and required fields."}]};if(e.version!==void 0&&e.version!==1&&i.push(a("invalid_version","Analytics intent version must be 1.","version")),k(e.source,"source",i),e.kind==="metric"){const r=Array.isArray(e.metrics)?e.metrics.filter(s=>c(s)&&d(s.name)):[];if(!Array.isArray(e.metrics)||e.metrics.length===0?i.push(a("missing_metric","Metric intent needs at least one metric.","metrics")):e.metrics.some(s=>!c(s)||!d(s.name))&&i.push(a("invalid_metric_list","Metric intent metrics must be an array of field references with names.","metrics")),r.forEach((s,t)=>{f(s,`metrics.${t}`,i,{required:!0})}),r.length>0&&!j(r)){const s=r.find((t,p)=>r.some((u,l)=>l!==p&&M(u,t)));s&&i.push(a("duplicate_metric",T(s),"metrics"))}if(c(e.primaryMetric)&&d(e.primaryMetric.name)&&h(e.primaryMetric,r).length>1&&i.push(a("ambiguous_primary_metric","Metric intent primaryMetric must identify exactly one selected metric.","primaryMetric")),e.primaryMetric!==void 0&&(f(e.primaryMetric,"primaryMetric",i,{required:!0}),c(e.primaryMetric)&&d(e.primaryMetric.name)&&r.length>0&&!D(e.primaryMetric,r)&&i.push(a("invalid_primary_metric","Metric intent primaryMetric must match one metric field reference.","primaryMetric"))),e.dimensions!==void 0&&!Array.isArray(e.dimensions)?i.push(a("invalid_metric_dimensions","Metric intent dimensions must be an array of field references.","dimensions")):Array.isArray(e.dimensions)&&e.dimensions.some(s=>!c(s)||!d(s.name))&&i.push(a("invalid_metric_dimensions","Metric intent dimensions must be an array of field references with names.","dimensions")),e.dateField!==void 0&&f(e.dateField,"dateField",i),e.timeWindow!==void 0&&(w(e.timeWindow,"timeWindow",i),e.dateField||i.push(a("missing_time_window_date_field","Metric timeWindow needs a dateField.","dateField"))),U(e.filters,"filters",i),Array.isArray(e.dimensions)&&e.dimensions.forEach((s,t)=>{f(s,`dimensions.${t}`,i)}),e.orderBy!==void 0){if(!c(e.orderBy))i.push(a("invalid_metric_order_by","Metric intent orderBy must be a structured object.","orderBy"));else if(f(e.orderBy.field,"orderBy.field",i,{required:!0}),e.orderBy.direction!=="asc"&&e.orderBy.direction!=="desc"&&i.push(a("invalid_metric_order_direction","Metric intent orderBy direction must be asc or desc.","orderBy.direction")),c(e.orderBy.field)&&d(e.orderBy.field.name)){const s=[...r,...e.timeGrain&&e.dateField&&c(e.dateField)?[e.dateField]:[],...Array.isArray(e.dimensions)?e.dimensions.filter(t=>c(t)&&d(t.name)):[]];s.length>0&&!x(e.orderBy.field,s)&&i.push(a("invalid_metric_order_by","Metric intent orderBy.field must match one selected metric, grouped dateField, or dimension.","orderBy.field"))}}H(e,i)}else e.kind==="records"?(!Array.isArray(e.fields)||e.fields.length===0?i.push(a("missing_record_fields","Records intent needs at least one field.","fields")):e.fields.some(r=>!c(r)||!d(r.name))&&i.push(a("invalid_record_fields","Records intent fields must be field references with names.","fields")),Array.isArray(e.fields)&&e.fields.forEach((r,s)=>{f(r,`fields.${s}`,i)}),e.dateField!==void 0&&f(e.dateField,"dateField",i),e.orderBy!==void 0&&(c(e.orderBy)?(f(e.orderBy.field,"orderBy.field",i,{required:!0}),e.orderBy.direction!=="asc"&&e.orderBy.direction!=="desc"&&i.push(a("invalid_record_order_direction","Records intent orderBy direction must be asc or desc.","orderBy.direction"))):i.push(a("invalid_record_order_by","Records intent orderBy must be a structured object.","orderBy")))):e.kind==="inputOptions"?((!e.field||!d(e.field.name))&&i.push(a("missing_input_options_field","Input options intent needs a field.","field")),f(e.field,"field",i,{required:!0})):e.kind==="sql"?(((o=e.source)==null?void 0:o.kind)!=="sql"&&i.push(a("invalid_sql_source","SQL analytics intent must use a SQL execution source.","source")),d(e.sql)||i.push(a("missing_sql","SQL analytics intent needs SQL text.","sql")),Array.isArray(e.fields)&&e.fields.forEach((r,s)=>{f(r,`fields.${s}`,i)})):i.push(a("invalid_analytics_kind","Analytics kind is not supported.","kind"));return{ok:i.length===0,errors:i,warnings:n,repairHints:L(i)}}function $(e){const i=[],n=[];if(!e||typeof e!="object")return{ok:!1,errors:[a("invalid_operation_intent","Operation intent must be a structured object.")],warnings:n,repairHints:[{code:"invalid_operation_intent",recommendedNextStep:"Send one typed operation intent with version, kind, and required operation fields."}]};if(e.version!==1&&i.push(a("invalid_version","Operation intent version must be 1.","version")),e.kind==="answer_obligations")!Array.isArray(e.obligations)||e.obligations.length===0?i.push(a("missing_obligations","Answer-obligations operation intent needs at least one obligation.","obligations")):e.obligations.forEach((o,r)=>{d(o.id)||i.push(a("missing_obligation_id","Each analytics obligation needs an id.",`obligations.${r}.id`)),d(o.prompt)||i.push(a("missing_obligation_prompt","Each analytics obligation needs a prompt.",`obligations.${r}.prompt`))});else if(e.kind==="dashboard_change"||e.kind==="data_app_change"){if(d(e.instruction)||i.push(a("missing_instruction","Change operation intent needs an instruction.","instruction")),e.analyticsIntent){const o=v(e.analyticsIntent);i.push(...o.errors),n.push(...o.warnings)}}else i.push(a("invalid_operation_kind","Operation intent kind is not supported.","kind"));return{ok:i.length===0,errors:i,warnings:n,repairHints:N(i)}}function G(e){const i=[],n=[];if(!e||typeof e!="object")return{ok:!1,errors:[a("invalid_recovery_plan","Analytics recovery plan must be a structured object.")],warnings:n,repairHints:[{code:"invalid_recovery_plan",recommendedNextStep:"Return a typed recovery plan with operationIntent and plannedToolCalls."}]};e.version!==1&&i.push(a("invalid_version","Recovery plan version must be 1.","version")),e.kind!=="analytics_recovery_plan"&&i.push(a("invalid_recovery_plan_kind","Recovery plan kind must be analytics_recovery_plan.","kind"));const o=$(e.operationIntent);return i.push(...o.errors),n.push(...o.warnings),Array.isArray(e.plannedToolCalls)||i.push(a("invalid_planned_tool_calls","Recovery plan plannedToolCalls must be an array.","plannedToolCalls")),{ok:i.length===0,errors:i,warnings:n,repairHints:N(i)}}function N(e){return e.map(i=>({code:i.code,recommendedNextStep:i.code==="missing_obligations"?"Normalize the user request into one or more typed analytics obligations before recovery planning.":"Correct the operation/recovery contract shape before planning execution."}))}function L(e){return e.map(i=>{switch(i.code){case"missing_source":return{code:i.code,fieldRole:"source",recommendedNextStep:"Provide a semantic, physical, or SQL source before executing analytics."};case"missing_metric":return{code:i.code,fieldRole:"metric",recommendedNextStep:"Choose one exact metric from the grounded schema candidates."};case"missing_record_fields":return{code:i.code,fieldRole:"dimension",recommendedNextStep:"Provide at least one field for the records intent."};case"missing_input_options_field":return{code:i.code,fieldRole:"input",recommendedNextStep:"Provide the exact field whose option values should be listed."};case"missing_sql":return{code:i.code,fieldRole:"sql",recommendedNextStep:"Provide bounded read-only SQL with an explicit outer LIMIT."};case"conflicting_sql":return{code:i.code,fieldRole:"sql",recommendedNextStep:"Use one canonical SQL text location for the intent; prefer top-level sql."};case"missing_semantic_domain":case"missing_dataset_name":case"missing_connection_id":case"missing_table_name":return{code:i.code,fieldRole:"source",recommendedNextStep:"Use grounded catalog metadata to fill the missing source reference."};default:return}}).filter(i=>!!i)}function Q(e,i,n,o){if(!e||typeof e!="object"){n.push(a("invalid_view","Dashboard view must be an object.",i));return}if(d(e.title)||n.push(a("missing_view_title","Dashboard view needs a title.",i)),!e.presentation||typeof e.presentation!="object"){n.push(a("missing_presentation","Dashboard view needs a presentation.",`${i}.presentation`));return}if(e.presentation.kind==="text"){d(e.text)||o.push(a("missing_text_content","Text views should include text content.",`${i}.text`));return}if(!e.analytics){n.push(a("missing_view_analytics","Non-text dashboard views need analytics intent.",`${i}.analytics`));return}const r=v(e.analytics);for(const s of r.errors)n.push(a(s.code,s.message,`${i}.analytics${s.path?`.${s.path}`:""}`));for(const s of r.warnings)o.push(a(s.code,s.message,`${i}.analytics${s.path?`.${s.path}`:""}`))}function V(e){const i=[],n=[];if(!e||typeof e!="object")return{ok:!1,errors:[a("invalid_dashboard_intent","Dashboard intent must be a structured object.")],warnings:n};e.version!==1&&i.push(a("invalid_version","Dashboard intent version must be 1.")),e.kind!=="dashboard"&&i.push(a("invalid_kind","Experience intent kind must be dashboard.")),d(e.title)||i.push(a("missing_title","Dashboard intent needs a title.","title"));const o=Array.isArray(e.inputs)?e.inputs:[],r=g(o.filter(c).map(u=>u.id).filter(u=>typeof u=="string"));r&&i.push(a("duplicate_input_id",`Duplicate input id: ${r}.`,"inputs"));for(const[u,l]of o.entries()){const m=`inputs.${u}`;if(!c(l)){i.push(a("invalid_input","Dashboard input must be an object.",m));continue}d(l.id)||i.push(a("missing_input_id","Input needs an id.",`${m}.id`)),d(l.label)||i.push(a("missing_input_label","Input needs a label.",`${m}.label`)),!l.field||!d(l.field.name)?i.push(a("missing_input_field","Input needs a field.",`${m}.field`)):f(l.field,`${m}.field`,i)}const s=Array.isArray(e.sections)?e.sections:[];s.length===0&&i.push(a("missing_sections","Dashboard intent needs at least one section.","sections"));const t=s.flatMap(u=>u&&typeof u=="object"&&Array.isArray(u.views)?u.views.filter(c).map(l=>l.id).filter(l=>!!l):[]),p=g(t);p&&i.push(a("duplicate_view_id",`Duplicate dashboard view id: ${p}.`,"sections"));for(const[u,l]of s.entries()){const m=`sections.${u}`;if(!l||typeof l!="object"){i.push(a("invalid_section","Dashboard section must be an object.",m));continue}if(d(l.title)||i.push(a("missing_section_title","Dashboard section needs a title.",m)),!Array.isArray(l.views)||l.views.length===0){i.push(a("missing_section_views","Dashboard section needs at least one view.",`${m}.views`));continue}for(const[R,B]of l.views.entries())Q(B,`${m}.views.${R}`,i,n)}return{ok:i.length===0,errors:i,warnings:n}}exports.preferSemaphorFieldRefMetadata=F;exports.preferSemaphorSourceMetadata=A;exports.semaphorFieldRefsMatch=I;exports.semaphorSourceIdentityKey=_;exports.semaphorSourcesReferToSameDataset=b;exports.validateSemaphorAnalyticsIntent=v;exports.validateSemaphorAnalyticsRecoveryPlan=G;exports.validateSemaphorDashboardIntent=V;exports.validateSemaphorOperationIntent=$;