react-semaphor 0.1.504 → 0.1.506

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

@@ -0,0 +1,34 @@
+import { SemaphorAnalyticsIntent, SemaphorFieldRef, SemaphorInputBinding, SemaphorInputOperator, SemaphorMatrixIntent, SemaphorMetricIntent, SemaphorRecordsIntent, SemaphorSqlIntent } from '../shared/analytics-protocol/index.js';
+import { SemaphorInputOptionsQuerySpec, SemaphorInputReference, SemaphorActiveInput, SemaphorInputSpec, SemaphorInputValue, SemaphorAnalysisQueryOptions, SemaphorAnalysisQuerySpec, SemaphorControlRole, SemaphorMatrixQuerySpec, SemaphorMetricQuerySpec, SemaphorOptionValue, SemaphorRecordsQuerySpec, SemaphorSqlQuerySpec } from './contracts.js';
+export declare function toSemaphorMetricIntent(spec: SemaphorMetricQuerySpec): SemaphorMetricIntent;
+export declare function toSemaphorAnalysisIntent(spec: SemaphorAnalysisQuerySpec): SemaphorMetricIntent;
+export declare function toSemaphorAnalysisQueryOptions(spec: SemaphorAnalysisQuerySpec): SemaphorAnalysisQueryOptions;
+export declare function toSemaphorRecordsIntent(spec: SemaphorRecordsQuerySpec): SemaphorRecordsIntent;
+export declare function toSemaphorInputOptionsIntent(spec: SemaphorInputOptionsQuerySpec): Extract<SemaphorAnalyticsIntent, {
+    kind: 'inputOptions';
+}>;
+export declare function toSemaphorSqlIntent(spec: SemaphorSqlQuerySpec): SemaphorSqlIntent;
+export declare function toSemaphorMatrixIntent(spec: SemaphorMatrixQuerySpec): SemaphorMatrixIntent;
+export declare function toSemaphorInputBinding(input: SemaphorInputReference): SemaphorInputBinding;
+export declare function toSemaphorInputBindings(inputs: SemaphorInputReference[] | undefined): SemaphorInputBinding[] | undefined;
+export declare function toSemaphorInputSnapshots(inputs: SemaphorInputReference[] | undefined): SemaphorActiveInput[];
+export declare function toSemaphorActiveInputSnapshots(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 normalizeSemaphorInputOptions(options?: Array<{
+    label: string;
+    value: SemaphorOptionValue;
+    count?: number;
+    disambiguation?: string[];
+} | SemaphorOptionValue>): {
+    label: string;
+    value: SemaphorOptionValue;
+    count?: number;
+    disambiguation?: string[];
+}[];
+export declare function hasSemaphorInputValue(value: unknown): boolean;

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

@@ -0,0 +1,2 @@
+import { SemaphorAnalysisPayload } from './contracts.js';
+export declare function normalizeSemaphorAnalysisPayload(payload: SemaphorAnalysisPayload | undefined | null): SemaphorAnalysisPayload;

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

@@ -0,0 +1,61 @@
+import { SemaphorAnalysisQueryDefinition, SemaphorAnalysisQuerySpec, SemaphorControlInputSpec, SemaphorControlRole, SemaphorDataAppDefinition, SemaphorDerivedFieldDefinition, SemaphorFilterInputSpec, SemaphorInputOptionsQueryDefinition, SemaphorInputOptionsQuerySpec, SemaphorInputBinding, SemaphorInputBindingReference, SemaphorInputReference, SemaphorInputSpec, SemaphorInputValue, SemaphorMatrixQueryDefinition, SemaphorMatrixQuerySpec, SemaphorMetricQueryDefinition, SemaphorMetricQuerySpec, SemaphorRecordsQueryDefinition, SemaphorRecordsQuerySpec, SemaphorSqlParameterValue, SemaphorSqlQueryDefinition, SemaphorSqlQuerySpec } from './contracts.js';
+import { SemaphorFieldRef, SemaphorSemanticSourceRef, SemaphorSourceRef } from '../shared/analytics-protocol/index.js';
+export type SemaphorSqlParamInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = Omit<SemaphorControlInputSpec<TValue>, 'kind' | 'role'> & {
+    defaultValue?: TValue;
+};
+export type SemaphorControlBuilderSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = Omit<SemaphorControlInputSpec<TValue>, 'kind'> & {
+    role: SemaphorControlRole;
+};
+export type SemaphorSemanticSourceBuilderSpec = {
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    connectionId?: string;
+    label?: string;
+};
+export type SemaphorSqlSourceBuilderSpec = Extract<SemaphorSourceRef, {
+    kind: 'sql';
+}>;
+export type SemaphorFieldBuilderSpec = Omit<SemaphorFieldRef, 'name' | 'role'>;
+export type SemaphorBindInputSpec = Omit<SemaphorInputBinding, 'inputId'> & {
+    inputId?: string;
+};
+export declare function defineSemaphorDataApp<TDefinition extends SemaphorDataAppDefinition>(definition: TDefinition): TDefinition;
+export declare function defineSemaphorInput<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputSpec<TValue>;
+export declare const semaphor: {
+    source: {
+        semantic(spec: SemaphorSemanticSourceBuilderSpec): SemaphorSemanticSourceRef;
+        sql(spec: Omit<SemaphorSqlSourceBuilderSpec, "kind">): SemaphorSqlSourceBuilderSpec;
+    };
+    field: {
+        measure<const TSpec extends SemaphorFieldBuilderSpec = {}>(name: string, spec?: TSpec): TSpec & {
+            name: string;
+            role: "measure";
+        };
+        dimension<const TSpec extends SemaphorFieldBuilderSpec = {}>(name: string, spec?: TSpec): TSpec & {
+            name: string;
+            role: "dimension";
+        };
+        date<const TSpec extends SemaphorFieldBuilderSpec = {}>(name: string, spec?: TSpec): TSpec & {
+            name: string;
+            role: "date";
+        };
+        id<const TSpec extends SemaphorFieldBuilderSpec = {}>(name: string, spec?: TSpec): TSpec & {
+            name: string;
+            role: "id";
+        };
+    };
+    filter<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: Omit<SemaphorFilterInputSpec<TValue>, "kind">): SemaphorFilterInputSpec<TValue>;
+    bindInput(input: SemaphorInputReference, binding: SemaphorBindInputSpec): SemaphorInputBindingReference;
+    control<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorControlBuilderSpec<TValue>): SemaphorControlInputSpec<TValue>;
+    sqlParam<TValue extends SemaphorSqlParameterValue = SemaphorSqlParameterValue>(spec: SemaphorSqlParamInputSpec<TValue>): SemaphorControlInputSpec<TValue>;
+    derivedField(spec: Omit<SemaphorDerivedFieldDefinition, "kind"> & {
+        kind?: "derived_field";
+    }): SemaphorDerivedFieldDefinition;
+    metric(spec: SemaphorMetricQuerySpec): SemaphorMetricQueryDefinition;
+    analysis(spec: SemaphorAnalysisQuerySpec): SemaphorAnalysisQueryDefinition;
+    records(spec: SemaphorRecordsQuerySpec): SemaphorRecordsQueryDefinition;
+    inputOptions(spec: SemaphorInputOptionsQuerySpec): SemaphorInputOptionsQueryDefinition;
+    sql(spec: SemaphorSqlQuerySpec): SemaphorSqlQueryDefinition;
+    matrix(spec: SemaphorMatrixQuerySpec): SemaphorMatrixQueryDefinition;
+};

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

@@ -0,0 +1,523 @@
+import { MatrixSpec, MatrixWindowRequest, MatrixWindow, MatrixOperationRequest, MatrixExecutionResult, SemaphorAnalyticsFilter, SemaphorOptionDependencyOutcome, SemaphorOptionMatchResult, SemaphorAnalyticsExecutionResult, SemaphorAnalyticsExecutionStatus, SemaphorAnalyticsIntent, SemaphorAnalyticsValidationIssue, SemaphorAnalyticsValidationResult, SemaphorDerivedFieldDefinition, SemaphorFieldRef, SemaphorInputBinding, SemaphorInputOptionSource, SemaphorInputOperator, SemaphorMetricIntent, SemaphorRelationshipHint, SemaphorMatrixIntent, SemaphorOptionDependencies, SemaphorOptionPopulation, SemaphorPaginationMetadata, SemaphorPaginationRequest, SemaphorRecordsIntent, SemaphorResultColumn, SemaphorSqlIntent, SemaphorSourceRef, SemaphorTimeGrain, SemaphorTimeWindow } from '../shared/analytics-protocol/index.js';
+import { CalendarContext } from '../lib/types/token-types.js';
+export type { SemaphorAnalyticsFilter, SemaphorDerivedFieldDefinition, SemaphorFieldRef, SemaphorInputBinding, SemaphorInputOptionSource, SemaphorInputOperator, SemaphorPaginationMetadata, SemaphorPaginationRequest, SemaphorOptionDependencies, SemaphorOptionPopulation, SemaphorResultColumn, SemaphorMatrixIntent, SemaphorSourceRef, SemaphorTimeWindow, } from '../shared/analytics-protocol/index.js';
+export type SemaphorScalar = string | number | boolean | null;
+export type SemaphorInputValue = SemaphorScalar | SemaphorScalar[];
+export type SemaphorOptionValue = string | number | boolean;
+export type SemaphorInputOption = {
+    label: string;
+    value: SemaphorOptionValue;
+    count?: number;
+    disambiguation?: string[];
+};
+export type SemaphorQuerySourceSpec = {
+    source: SemaphorSourceRef;
+};
+export type SemaphorAppDerivedFieldsSpec = {
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+export type SemaphorSqlSourceSpec = {
+    source: Extract<SemaphorSourceRef, {
+        kind: 'sql';
+    }>;
+};
+export type SemaphorQueryField = SemaphorFieldRef;
+export type SemaphorRecordsField = SemaphorFieldRef & {
+    role: NonNullable<SemaphorFieldRef['role']>;
+};
+export type SemaphorNonEmptyArray<T> = [T, ...T[]];
+export type SemaphorControlRole = 'grain' | 'measure' | 'dimension' | 'aggregation' | 'sqlParam';
+type SemaphorInputBase<TValue extends SemaphorInputValue> = {
+    id: string;
+    label?: string;
+    value?: TValue;
+    defaultValue?: TValue;
+    onValueChange?: {
+        bivarianceHack(value: TValue | undefined): void;
+    }['bivarianceHack'];
+    options?: Array<SemaphorInputOption | SemaphorOptionValue>;
+};
+export type SemaphorFilterInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
+    kind: 'filter';
+    field: SemaphorQueryField;
+    operator?: SemaphorInputOperator;
+    relationshipHint?: SemaphorInputBinding['relationshipHint'];
+    multi?: boolean;
+};
+export type SemaphorControlInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
+    kind: 'control';
+    role: SemaphorControlRole;
+};
+export type SemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorFilterInputSpec<TValue> | SemaphorControlInputSpec<TValue>;
+export 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>;
+};
+export type SemaphorInputBindingReference<TValue extends SemaphorInputValue = SemaphorInputValue> = {
+    toAnalyticsInput(): SemaphorActiveInput<TValue>;
+};
+export type SemaphorActiveInput<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBinding & {
+    kind: 'filter' | 'control';
+    label?: string;
+    value?: TValue;
+    isActive: boolean;
+    operator?: SemaphorInputOperator;
+    controlRole?: SemaphorControlRole;
+};
+export type SemaphorMetricComparison = {
+    kind: 'previous_period' | 'previous_year' | 'target';
+    targetValue?: number;
+};
+export type SemaphorQueryOrderBy = {
+    field: SemaphorQueryField;
+    direction: 'asc' | 'desc';
+};
+export type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & SemaphorAppDerivedFieldsSpec & {
+    id?: string;
+    label?: string;
+    measures: SemaphorNonEmptyArray<SemaphorQueryField>;
+    primaryMeasure?: SemaphorQueryField;
+    dateField?: SemaphorQueryField;
+    timeGrain?: SemaphorTimeGrain;
+    dimensions?: SemaphorQueryField[];
+    comparison?: SemaphorMetricComparison;
+    orderBy?: SemaphorQueryOrderBy;
+    filters?: SemaphorAnalyticsFilter[];
+    inputs?: SemaphorInputReference[];
+    relationshipHint?: SemaphorRelationshipHint;
+    limit?: number;
+};
+export type SemaphorAnalysisDriverMode = 'absolute_delta' | 'largest_negative' | 'largest_positive' | 'positive_and_negative' | 'all';
+export type SemaphorAnalysisQueryOptions = {
+    chartTitle?: string;
+    chartType?: string;
+    driverMode?: SemaphorAnalysisDriverMode;
+    includePopulation?: boolean;
+    calendarContext?: CalendarContext;
+};
+export type SemaphorAnalysisQuerySpec = SemaphorMetricQuerySpec & SemaphorAnalysisQueryOptions & {
+    analysis?: SemaphorMetricIntent['analysis'];
+    timeWindow?: SemaphorMetricIntent['timeWindow'];
+};
+export type SemaphorRecordsOrderBy = SemaphorQueryOrderBy;
+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;
+    totals?: SemaphorRecordsIntent['totals'];
+};
+type SemaphorRecordsSelectorSpec = {
+    fields: SemaphorNonEmptyArray<SemaphorRecordsField>;
+};
+export type SemaphorRecordsQuerySpec = SemaphorRecordsBaseQuerySpec & SemaphorRecordsSelectorSpec;
+export type SemaphorInputOptionsQuerySpec = Omit<SemaphorQuerySourceSpec, 'source'> & {
+    /** Option lists are governed from semantic or physical sources only. */
+    source: Extract<SemaphorSourceRef, {
+        kind: 'semantic' | 'physical';
+    }>;
+} & Omit<SemaphorInputOptionSource, 'source'> & SemaphorAppDerivedFieldsSpec & {
+    id?: string;
+    label?: string;
+    inputId: string;
+    population?: SemaphorOptionPopulation;
+    dependencies?: SemaphorOptionDependencies;
+    inputs?: SemaphorInputReference[];
+    search?: string;
+    limit?: number;
+};
+export type SemaphorSqlParameterValue = SemaphorScalar | SemaphorScalar[];
+export 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;
+};
+export type SemaphorMatrixQuerySpec = MatrixSpec & {
+    id?: string;
+    label?: string;
+    inputs?: SemaphorInputReference[];
+    matrixWindowRequest: MatrixWindowRequest;
+};
+export type SemaphorMetricQueryDefinition = SemaphorMetricQuerySpec & {
+    queryKind: 'metric';
+};
+export type SemaphorAnalysisQueryDefinition = SemaphorAnalysisQuerySpec & {
+    queryKind: 'analysis';
+};
+export type SemaphorRecordsQueryDefinition = SemaphorRecordsQuerySpec & {
+    queryKind: 'records';
+};
+export type SemaphorInputOptionsQueryDefinition = SemaphorInputOptionsQuerySpec & {
+    queryKind: 'inputOptions';
+};
+export type SemaphorSqlQueryDefinition = SemaphorSqlQuerySpec & {
+    queryKind: 'sql';
+};
+export type SemaphorMatrixQueryDefinition = SemaphorMatrixQuerySpec & {
+    queryKind: 'matrix';
+};
+export type SemaphorQueryDefinition = SemaphorMetricQueryDefinition | SemaphorAnalysisQueryDefinition | SemaphorRecordsQueryDefinition | SemaphorInputOptionsQueryDefinition | SemaphorSqlQueryDefinition | SemaphorMatrixQueryDefinition;
+export type SemaphorInputReference = SemaphorInputSpec | SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle | SemaphorInputBindingReference;
+export type SemaphorDataAppViewDefinition<TQuery extends SemaphorQueryDefinition = SemaphorQueryDefinition> = {
+    id: string;
+    title?: string;
+    description?: string;
+    query: TQuery;
+    inputs?: SemaphorInputReference[];
+};
+export type SemaphorDataAppDefinition = {
+    id?: string;
+    title?: string;
+    description?: string;
+    inputs?: Record<string, SemaphorInputSpec> | SemaphorInputSpec[];
+    queries?: Record<string, SemaphorQueryDefinition>;
+    views: SemaphorDataAppViewDefinition[];
+};
+export type SemaphorDataAppDevtoolsUiConfig = {
+    buttonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'relative';
+    initialIsOpen?: boolean;
+    panelPosition?: 'bottom' | 'right';
+};
+export type SemaphorDataAppDebugConfig = boolean | {
+    enabled?: boolean;
+    exposeWindowBridge?: boolean;
+    autoRenderDevtools?: boolean | SemaphorDataAppDevtoolsUiConfig;
+    requestServerDebug?: boolean;
+    maxQueries?: number;
+    maxEventsPerQuery?: number;
+};
+export type SemaphorDataAppSourceHint = {
+    file?: string;
+    line?: number;
+    column?: number;
+    exportName?: string;
+    component?: string;
+    note?: string;
+};
+export type SemaphorQueryDebugOptions = {
+    viewId?: string;
+    viewTitle?: string;
+    visualType?: string;
+    sectionTitle?: string;
+    title?: string;
+    sourceHint?: SemaphorDataAppSourceHint;
+    sourceHints?: SemaphorDataAppSourceHint[];
+};
+export type SemaphorQueryRuntimeOptions = {
+    inputs?: SemaphorInputReference[];
+    debug?: SemaphorQueryDebugOptions;
+};
+export type SemaphorQueryStatus = 'idle' | 'loading' | 'success' | 'error';
+export type SemaphorDataAppQueryError = Error & {
+    kind: 'data_app_query_error';
+    requestId?: string;
+    details?: unknown;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+    validation?: SemaphorAnalyticsValidationResult;
+    validationIssues?: SemaphorAnalyticsValidationIssue[];
+};
+export type SemaphorDataAppTraceEvent = {
+    type: 'query_started';
+    queryId: string;
+    requestId?: string;
+    at: string;
+} | {
+    type: 'query_succeeded';
+    queryId: string;
+    requestId?: string;
+    at: string;
+    rowCount?: number;
+    durationMs?: number;
+} | {
+    type: 'query_failed';
+    queryId: string;
+    requestId?: string;
+    at: string;
+    errorMessage: string;
+} | {
+    type: 'query_ignored_stale';
+    queryId: string;
+    requestId?: string;
+    at: string;
+    reason: 'newer_inputs' | 'unmounted' | 'superseded';
+} | {
+    type: 'input_changed';
+    inputId: string;
+    at: string;
+    valuePreview?: string;
+};
+export type SemaphorDataAppTrace = {
+    traceId: string;
+    viewId?: string;
+    viewTitle?: string;
+    visualType?: string;
+    sectionTitle?: string;
+    queryId: string;
+    queryLabel?: string;
+    queryKind: SemaphorQueryDefinition['queryKind'];
+    builder: 'semaphor.metric' | 'semaphor.records' | 'semaphor.matrix' | 'semaphor.analysis' | 'semaphor.inputOptions' | 'semaphor.sql';
+    sourceRefs: SemaphorSourceRef[];
+    sourceHints?: SemaphorDataAppSourceHint[];
+    projectionFieldRefs?: SemaphorFieldRef[];
+    inputFieldRefs?: SemaphorFieldRef[];
+    fieldRefs: SemaphorFieldRef[];
+    inputsApplied: Array<{
+        inputId: string;
+        inputLabel?: string;
+        fieldRef?: SemaphorFieldRef;
+        operator?: string;
+        valuePreview?: string;
+    }>;
+    latestAttempt?: {
+        requestId?: string;
+        status: SemaphorQueryStatus;
+        durationMs?: number;
+        rowCount?: number;
+        columnCount?: number;
+        cacheStatus?: 'hit' | 'miss' | 'unknown';
+        metricCoverage?: {
+            populatedMetricKeys?: string[];
+            missingMeasures?: string[];
+        };
+        resultPreview?: SemaphorDataAppResultPreview;
+        executionResult?: SemaphorAnalyticsExecutionResult;
+        errorMessage?: string;
+    };
+    recentEvents: SemaphorDataAppTraceEvent[];
+    server?: {
+        compiledSql?: string;
+        dialect?: string;
+        sqlHash?: string;
+        executionPlanSummary?: string;
+    };
+    clientWarnings: string[];
+};
+export type SemaphorDataAppResultPreviewColumn = {
+    key: string;
+    label: string;
+};
+export type SemaphorDataAppResultPreview = {
+    title: string;
+    summary: string;
+    columns: SemaphorDataAppResultPreviewColumn[];
+    rows: Array<Record<string, unknown>>;
+    truncatedRows: boolean;
+    truncatedColumns: boolean;
+};
+export type SemaphorDataAppDevtoolsIssue = {
+    traceId: string;
+    queryId: string;
+    viewId?: string;
+    viewTitle?: string;
+    queryLabel?: string;
+    severity: 'error' | 'warning';
+    title: string;
+    message: string;
+    code?: string;
+    path?: string;
+};
+export type SemaphorDataAppDevtoolsState = {
+    enabled: boolean;
+    queries: SemaphorDataAppTrace[];
+    issues: SemaphorDataAppDevtoolsIssue[];
+    getQuery(queryId: string): SemaphorDataAppTrace | undefined;
+    getQueries(queryId: string): SemaphorDataAppTrace[];
+};
+export type SemaphorDataAppDevtoolsWindowBridge = {
+    snapshot(): SemaphorDataAppDevtoolsState;
+    getQuery(queryId: string): SemaphorDataAppTrace | undefined;
+    getQueries(queryId: string): SemaphorDataAppTrace[];
+    getIssues(): SemaphorDataAppDevtoolsIssue[];
+};
+declare global {
+    interface Window {
+        __SEMAPHOR_DEVTOOLS__?: SemaphorDataAppDevtoolsWindowBridge;
+    }
+}
+export type SemaphorQueryState = {
+    status: SemaphorQueryStatus;
+    executionStatus?: SemaphorAnalyticsExecutionStatus;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+    validation?: SemaphorAnalyticsValidationResult;
+    coverage?: SemaphorAnalyticsExecutionResult['coverage'];
+    diagnosticFeedback?: SemaphorAnalyticsExecutionResult['diagnosticFeedback'];
+    isLoading: boolean;
+    isEmpty: boolean;
+    isPartial: boolean;
+    isFiltered: boolean;
+    isStale: boolean;
+    isValidated: boolean;
+    error: SemaphorDataAppQueryError | null;
+    trace?: SemaphorDataAppTrace;
+};
+export type SemaphorMetricPayload = {
+    primaryValue: number | string | null;
+    measures?: Record<string, number | string | null>;
+    measureBindings?: Record<string, string>;
+    missingMeasures?: string[];
+    comparisonValue?: number | string | null;
+    comparisonKind?: NonNullable<SemaphorMetricIntent['comparison']>['kind'];
+    delta?: number | null;
+    deltaPercent?: number | null;
+    records?: Array<Record<string, unknown>>;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+};
+export type SemaphorMetricQueryResult = SemaphorQueryState & SemaphorMetricPayload & {
+    id?: string;
+    intent?: SemaphorMetricIntent;
+};
+export type SemaphorAnalysisResultSet = {
+    id?: SemaphorAnalysisResultSetKey | string;
+    role?: SemaphorAnalysisResultSetKey | string;
+    records: Array<Record<string, unknown>>;
+    columns: SemaphorResultColumn[];
+    rowCount?: number;
+    warnings?: SemaphorAnalysisWarning[];
+};
+export type SemaphorAnalysisResultSetKey = 'primary' | 'comparisons' | 'contributors' | 'segments' | 'periodChanges' | 'records' | 'changes' | 'drivers' | 'absoluteDeltaDrivers' | 'largestNegativeChanges' | 'largestPositiveChanges' | 'largestNegativeDrivers' | 'largestPositiveDrivers';
+export type SemaphorAnalysisResultSetWarning = {
+    code: 'missing_analysis_result_key';
+    severity: 'warning';
+    message: string;
+    resultSetKey: SemaphorAnalysisResultSetKey | string;
+    rowIndex: number;
+    columnKey: string;
+    columnName?: string;
+    columnLabel?: string;
+    availableKeys: string[];
+};
+export type SemaphorAnalysisWarning = SemaphorAnalysisResultSetWarning | {
+    code: string;
+    severity?: string;
+    message?: string;
+    [key: string]: unknown;
+};
+export type SemaphorAnalysisPayload = {
+    answerSummary?: string;
+    mode?: string;
+    data?: Record<string, unknown>;
+    resultSets?: Partial<Record<SemaphorAnalysisResultSetKey, SemaphorAnalysisResultSet>> & Record<string, SemaphorAnalysisResultSet>;
+    analysisWarnings?: SemaphorAnalysisWarning[];
+    warnings?: unknown[];
+    columns?: SemaphorResultColumn[];
+    records?: Array<Record<string, unknown>>;
+    rowCount?: number;
+    primary?: Array<Record<string, unknown>>;
+    comparison?: unknown;
+    comparisons?: Array<Record<string, unknown>>;
+    contributors?: Array<Record<string, unknown>>;
+    segments?: Array<Record<string, unknown>>;
+    periodChanges?: Array<Record<string, unknown>>;
+    changes?: Array<Record<string, unknown>>;
+    drivers?: Array<Record<string, unknown>>;
+    absoluteDeltaDrivers?: Array<Record<string, unknown>>;
+    largestNegativeChanges?: Array<Record<string, unknown>>;
+    largestPositiveChanges?: Array<Record<string, unknown>>;
+    largestNegativeDrivers?: Array<Record<string, unknown>>;
+    largestPositiveDrivers?: Array<Record<string, unknown>>;
+    fieldsUsed?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    querySpec?: Record<string, unknown>;
+    sql?: Record<string, unknown>;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+    [key: string]: unknown;
+};
+export type SemaphorAnalysisQueryResult = SemaphorQueryState & SemaphorAnalysisPayload & {
+    id?: string;
+    intent?: SemaphorMetricIntent;
+};
+export type SemaphorRecordsPayload<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
+    records: TRecord[];
+    columns?: SemaphorResultColumn[];
+    rowCount?: number;
+    pagination?: SemaphorPaginationMetadata;
+    totals?: Extract<NonNullable<SemaphorAnalyticsExecutionResult['result']>, {
+        kind: 'records';
+    }>['totals'];
+    executionResult?: SemaphorAnalyticsExecutionResult;
+};
+export type SemaphorRecordsQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryState & SemaphorRecordsPayload<TRecord> & {
+    id?: string;
+    intent?: SemaphorRecordsIntent;
+};
+export type SemaphorSqlPayload<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
+    records: TRecord[];
+    columns?: SemaphorResultColumn[];
+    rowCount?: number;
+    pagination?: SemaphorPaginationMetadata;
+    output?: string;
+    rowLimitExceeded?: boolean;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+};
+export type SemaphorSqlQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryState & SemaphorSqlPayload<TRecord> & {
+    id?: string;
+    intent?: SemaphorSqlIntent;
+};
+export type SemaphorMatrixPayload = {
+    window?: MatrixWindow;
+    executionResult?: MatrixExecutionResult;
+};
+export type SemaphorMatrixQueryResult = SemaphorQueryState & SemaphorMatrixPayload & {
+    id?: string;
+    intent?: SemaphorMatrixIntent;
+};
+export type SemaphorInputOptionsPayload = {
+    options: SemaphorInputOption[];
+    /** Per-dependency classification for the option query; see
+     * `SemaphorOptionDependencyOutcome`. Absent when no dependencies applied. */
+    dependencyOutcomes?: SemaphorOptionDependencyOutcome[];
+    /** Authoritative exact-value relevance result when the request asked for it. */
+    match?: SemaphorOptionMatchResult;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+};
+export type SemaphorInputOptionsQueryResult = SemaphorQueryState & SemaphorInputOptionsPayload & {
+    id?: string;
+    intent?: Extract<SemaphorAnalyticsIntent, {
+        kind: 'inputOptions';
+    }>;
+};
+export type SemaphorRowsQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorRecordsQueryResult<TRecord> | SemaphorSqlQueryResult<TRecord>;
+export type SemaphorQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorMetricQueryResult | SemaphorAnalysisQueryResult | SemaphorRowsQueryResult<TRecord> | SemaphorInputOptionsQueryResult | SemaphorMatrixQueryResult;
+export type SemaphorAnyQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryResult<TRecord>;
+export type SemaphorQueryResultFor<TQuery extends SemaphorQueryDefinition, TRecord extends Record<string, unknown> = Record<string, unknown>> = TQuery extends SemaphorMetricQueryDefinition ? SemaphorMetricQueryResult : TQuery extends SemaphorAnalysisQueryDefinition ? SemaphorAnalysisQueryResult : TQuery extends SemaphorRecordsQueryDefinition ? SemaphorRecordsQueryResult<TRecord> : TQuery extends SemaphorInputOptionsQueryDefinition ? SemaphorInputOptionsQueryResult : TQuery extends SemaphorSqlQueryDefinition ? SemaphorSqlQueryResult<TRecord> : TQuery extends SemaphorMatrixQueryDefinition ? SemaphorMatrixQueryResult : never;
+export type SemaphorQueryExecutorContext = {
+    token?: string;
+    apiBaseUrl?: string;
+    activeInputs?: SemaphorActiveInput[];
+    debug?: SemaphorDataAppDebugConfig;
+};
+export type SemaphorQueryExecutor = {
+    executeAnalysis?(intent: SemaphorMetricIntent, context: SemaphorQueryExecutorContext, options?: SemaphorAnalysisQueryOptions): Promise<SemaphorAnalysisPayload>;
+    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>;
+    executeSql?<TRecord extends Record<string, unknown> = Record<string, unknown>>(intent: SemaphorSqlIntent, context: SemaphorQueryExecutorContext): Promise<SemaphorSqlPayload<TRecord>>;
+    executeMatrix?(input: MatrixOperationRequest, context: SemaphorQueryExecutorContext): Promise<SemaphorMatrixPayload>;
+};

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

@@ -0,0 +1,49 @@
+import { CSSProperties, ReactElement, ReactNode } from 'react';
+import { SemaphorActiveInput, SemaphorDataAppDebugConfig, SemaphorDataAppDevtoolsState, SemaphorDataAppTrace, SemaphorQueryDebugOptions, SemaphorQueryDefinition } from '../contracts.js';
+import { SemaphorAnalyticsIntent } from '../../shared/analytics-protocol/index.js';
+export type SemaphorDataAppQueryTraceController<TData> = {
+    enabled: boolean;
+    queryId: string;
+    trace?: SemaphorDataAppTrace;
+    start(): void;
+    success(data: TData, durationMs: number): void;
+    failure(error: unknown, durationMs: number): void;
+    ignored(reason: 'newer_inputs' | 'unmounted' | 'superseded'): void;
+    validationFailure(error: Error): void;
+};
+type UseSemaphorQueryTraceOptions = {
+    spec: SemaphorQueryDefinition;
+    queryKind: SemaphorQueryDefinition['queryKind'];
+    queryKey: string;
+    intent?: SemaphorAnalyticsIntent;
+    activeInputs?: SemaphorActiveInput[];
+    debug?: SemaphorQueryDebugOptions;
+};
+export type SemaphorDevtoolsProps = {
+    buttonPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'relative';
+    initialIsOpen?: boolean;
+    panelPosition?: 'bottom' | 'right';
+    className?: string;
+    style?: CSSProperties;
+};
+export type SemaphorDevtoolsInspectButtonProps = {
+    queryId?: string;
+    viewId?: string;
+    label?: string;
+    className?: string;
+    style?: CSSProperties;
+};
+export declare function SemaphorDataAppDevtoolsProvider({ debug, children, }: {
+    debug?: SemaphorDataAppDebugConfig;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function SemaphorViewBoundary({ id, title, children, }: {
+    id: string;
+    title?: string;
+    children: ReactNode;
+}): ReactElement;
+export declare function SemaphorDevtools({ buttonPosition, initialIsOpen, panelPosition, className, style, }?: SemaphorDevtoolsProps): ReactElement | null;
+export declare function SemaphorDevtoolsInspectButton({ queryId, viewId, label, className, style, }?: SemaphorDevtoolsInspectButtonProps): ReactElement | null;
+export declare function useSemaphorDevtools(): SemaphorDataAppDevtoolsState;
+export declare function useSemaphorQueryTrace<TData>({ spec, queryKind, queryKey, intent, activeInputs, debug, }: UseSemaphorQueryTraceOptions): SemaphorDataAppQueryTraceController<TData>;
+export {};