react-semaphor 0.1.359 → 0.1.360

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

@@ -2,10 +2,44 @@ import { Context } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
+/**
+ * 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 createSemaphorQueryExecutor(): SemaphorQueryExecutor;
 
 export declare function hasSemaphorInputValue(value: unknown): boolean;
 
+export declare function normalizeSemaphorAnalysisQueryOptions(value: unknown, options?: {
+    pathPrefix?: string;
+    validateTimezone?: SemaphorAnalysisTimezoneValidator;
+}): SemaphorAnalysisQueryOptionsValidationResult;
+
 export declare function normalizeSemaphorInputOptions(options?: Array<{
     label: string;
     value: SemaphorOptionValue;
@@ -33,6 +67,89 @@ export declare type SemaphorActiveInput<TValue extends SemaphorInputValue = Sema
 
 declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
 
+export declare type SemaphorAnalysisDriverMode = 'absolute_delta' | 'largest_negative' | 'largest_positive' | 'positive_and_negative' | 'all';
+
+export declare type SemaphorAnalysisPayload = {
+    answerSummary?: string;
+    mode?: string;
+    data?: Record<string, unknown>;
+    records?: Array<Record<string, unknown>>;
+    changes?: Array<Record<string, unknown>>;
+    drivers?: Array<Record<string, unknown>>;
+    largestNegativeChanges?: Array<Record<string, unknown>>;
+    largestPositiveChanges?: Array<Record<string, unknown>>;
+    largestNegativeDrivers?: Array<Record<string, unknown>>;
+    largestPositiveDrivers?: Array<Record<string, unknown>>;
+    comparison?: 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 declare type SemaphorAnalysisQueryOptions = {
+    chartTitle?: string;
+    chartType?: string;
+    driverMode?: SemaphorAnalysisDriverMode;
+    includePopulation?: boolean;
+    calendarContext?: CalendarContext;
+};
+
+export declare type SemaphorAnalysisQueryOptionsValidationIssue = {
+    code: 'invalid_analysis_option';
+    message: string;
+    path: string;
+};
+
+export declare type SemaphorAnalysisQueryOptionsValidationResult = {
+    ok: true;
+    analysisOptions?: SemaphorAnalysisQueryOptions;
+} | {
+    ok: false;
+    issues: SemaphorAnalysisQueryOptionsValidationIssue[];
+};
+
+export declare type SemaphorAnalysisQueryResult = SemaphorQueryState & SemaphorAnalysisPayload & {
+    id?: string;
+    intent?: SemaphorMetricIntent;
+};
+
+export declare type SemaphorAnalysisQuerySpec = SemaphorMetricQuerySpec & SemaphorAnalysisQueryOptions & {
+    analysis?: SemaphorMetricIntent['analysis'];
+    timeWindow?: SemaphorMetricIntent['timeWindow'];
+    filters?: SemaphorAnalyticsFilter[];
+};
+
+export declare type SemaphorAnalysisTimezoneValidator = (tz: string) => string | null;
+
+declare type SemaphorAnalyticsExecutionResult = {
+    intentId?: string;
+    queryId?: string;
+    status: SemaphorAnalyticsExecutionStatus;
+    resultShape?: SemaphorAnalyticsResult['kind'] | 'period_change';
+    intent?: SemaphorAnalyticsIntent;
+    compiledQuery?: SemaphorCompiledQuery;
+    fieldsUsed?: SemaphorExecutionFieldRef[];
+    result?: SemaphorAnalyticsResult;
+    validation: SemaphorAnalyticsValidationResult;
+    coverage?: {
+        answeredObligations: string[];
+        missingObligations: string[];
+        warnings?: SemaphorAnalyticsValidationIssue[];
+    };
+    missingFields?: string[];
+    warnings?: string[];
+    relationshipDiagnostics?: SemaphorRelationshipDiagnostics;
+    population?: SemaphorAnalyticsPopulation;
+    metadata?: Record<string, unknown>;
+};
+
+declare type SemaphorAnalyticsExecutionStatus = 'answered' | 'partial' | 'failed';
+
+declare type SemaphorAnalyticsFieldRole = 'metric' | 'dateField' | 'dimension' | 'input' | 'source' | 'sql';
+
 declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
 
 declare type SemaphorAnalyticsFilterBase = {
@@ -59,6 +176,48 @@ declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
 
+declare type SemaphorAnalyticsPopulation = {
+    scope: 'filtered_query';
+    metrics: Record<string, number | string | null>;
+};
+
+declare type SemaphorAnalyticsRepairHint = {
+    code: SemaphorAnalyticsValidationCode | string;
+    message?: string;
+    invalidField?: string;
+    fieldRole?: SemaphorAnalyticsFieldRole;
+    validMetricCandidates?: string[];
+    validDateCandidates?: string[];
+    validDimensionCandidates?: string[];
+    recommendedNextStep: string;
+};
+
+declare type SemaphorAnalyticsResult = SemaphorMetricResult | SemaphorRecordsResult | SemaphorInputOptionsResult | SemaphorSqlResult;
+
+declare type SemaphorAnalyticsResultBase = {
+    intentId?: string;
+    queryPath: SemaphorQueryPath;
+    warnings?: string[];
+    rowCount?: number;
+    rowLimitExceeded?: boolean;
+    limit?: number;
+};
+
+declare type SemaphorAnalyticsValidationCode = 'missing_source' | 'invalid_source_kind' | 'missing_semantic_domain' | 'missing_dataset_name' | 'missing_connection_id' | 'missing_table_name' | 'missing_sql' | 'missing_metric' | 'missing_record_fields' | 'missing_input_options_field' | 'invalid_metric' | 'invalid_metric_list' | 'invalid_date_field' | 'invalid_dimension' | 'invalid_metric_dimensions' | 'conflicting_sql' | 'sql_policy_violation' | 'unsupported_intent_for_adapter' | 'invalid_analytics_kind' | 'invalid_analytics_intent';
+
+declare type SemaphorAnalyticsValidationIssue = SemaphorProtocolIssue & {
+    code: SemaphorAnalyticsValidationCode | string;
+    fieldRole?: SemaphorAnalyticsFieldRole;
+    repairHint?: SemaphorAnalyticsRepairHint;
+};
+
+declare type SemaphorAnalyticsValidationResult = {
+    ok: boolean;
+    errors: SemaphorAnalyticsValidationIssue[];
+    warnings: SemaphorAnalyticsValidationIssue[];
+    repairHints: SemaphorAnalyticsRepairHint[];
+};
+
 declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
     operator?: SemaphorAnalyticsValueFilterOperator;
     values: unknown[];
@@ -66,6 +225,33 @@ declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
 
+declare type SemaphorCompiledQuery = {
+    kind: 'config';
+    queryId: string;
+    source: SemaphorSourceRef;
+    cardType: string;
+    connectionId: string;
+    cardConfig: unknown;
+    cardDataSource: unknown;
+    activeFilters?: SemaphorAnalyticsFilter[];
+    rowLimit: number;
+    analyticsIntent?: SemaphorAnalyticsIntent;
+} | {
+    kind: 'sql';
+    queryId: string;
+    source: Extract<SemaphorSourceRef, {
+        kind: 'sql';
+    }>;
+    connectionId: string;
+    dialect: SemaphorDialect;
+    sql: string;
+    parameters?: Record<string, unknown>;
+    pythonCode?: string;
+    activeFilters?: SemaphorAnalyticsFilter[];
+    rowLimit: number;
+    analyticsIntent?: SemaphorAnalyticsIntent;
+};
+
 export declare type SemaphorControlInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
     kind: 'control';
     role: SemaphorControlRole;
@@ -75,6 +261,34 @@ export declare type SemaphorControlRole = 'grain' | 'metric' | 'dimension' | 'ag
 
 export declare const SemaphorDataAppContext: Context<SemaphorDataAppRuntime>;
 
+export declare type SemaphorDataAppFieldCatalog = {
+    source: SemaphorSourceRef;
+    sourceAliases?: SemaphorSourceRef[];
+    fields: SemaphorFieldRef[];
+};
+
+export declare type SemaphorDataAppHookSpec = {
+    hook: 'useSemaphorAnalysis';
+    spec: SemaphorAnalysisQuerySpec;
+} | {
+    hook: 'useSemaphorMetric';
+    spec: SemaphorMetricQuerySpec;
+} | {
+    hook: 'useSemaphorRecords';
+    spec: SemaphorRecordsQuerySpec;
+} | {
+    hook: 'useSemaphorInputOptions';
+    spec: SemaphorInputOptionsQuerySpec;
+};
+
+export declare type SemaphorDataAppHookValidation = {
+    hook: SemaphorDataAppHookSpec['hook'];
+    hookId?: string;
+    intent?: SemaphorAnalyticsIntent;
+    diagnostics: SemaphorDataAppValidationDiagnostic[];
+    executionResult: SemaphorAnalyticsExecutionResult;
+};
+
 export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, children, }: SemaphorDataAppProviderProps): JSX.Element;
 
 export declare type SemaphorDataAppProviderProps = SemaphorQueryExecutorContext & {
@@ -86,6 +300,26 @@ export declare type SemaphorDataAppRuntime = SemaphorQueryExecutorContext & {
     executor?: SemaphorQueryExecutor;
 };
 
+export declare type SemaphorDataAppValidationDiagnostic = {
+    severity: 'error' | 'warning';
+    code: 'invalid_hook_spec' | 'invalid_analytics_intent' | 'invalid_source_ref' | 'missing_field' | 'unsupported_input_filter_composition' | string;
+    message: string;
+    path?: string;
+    hook?: SemaphorDataAppHookSpec['hook'];
+    hookId?: string;
+    intentId?: string;
+    source?: SemaphorSourceRef;
+    field?: SemaphorFieldRef;
+};
+
+export declare type SemaphorDataAppValidationResult = {
+    ok: boolean;
+    diagnostics: SemaphorDataAppValidationDiagnostic[];
+    hooks: SemaphorDataAppHookValidation[];
+    intents: SemaphorAnalyticsIntent[];
+    executionResults: SemaphorAnalyticsExecutionResult[];
+};
+
 declare type SemaphorDataAppWindowRuntime = {
     apiBaseUrl?: string;
     dataApiBaseUrl?: string;
@@ -96,6 +330,12 @@ declare type SemaphorDataAppWindowRuntime = {
 
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
+declare type SemaphorExecutionFieldRef = SemaphorFieldRef & {
+    semanticAggregate?: SemaphorAggregateFunction;
+    effectiveAggregate?: SemaphorAggregateFunction;
+    aggregateSource?: SemaphorMetricAggregateSource;
+};
+
 declare type SemaphorFieldRef = {
     name: string;
     label?: string;
@@ -162,6 +402,7 @@ declare type SemaphorInputOptionsIntent = {
 
 export declare type SemaphorInputOptionsPayload = {
     options: SemaphorInputOption[];
+    executionResult?: SemaphorAnalyticsExecutionResult;
 };
 
 export declare type SemaphorInputOptionsQueryResult = SemaphorQueryState & SemaphorInputOptionsPayload & {
@@ -179,12 +420,23 @@ export declare type SemaphorInputOptionsQuerySpec = SemaphorQuerySourceSpec & {
     limit?: number;
 };
 
+declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
+    kind: 'inputOptions';
+    options: Array<{
+        label: string;
+        value: unknown;
+        count?: number;
+    }>;
+};
+
 export declare type SemaphorInputReference = SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle;
 
 export declare type SemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorFilterInputSpec<TValue> | SemaphorControlInputSpec<TValue>;
 
 export declare type SemaphorInputValue = SemaphorScalar | SemaphorScalar[];
 
+declare type SemaphorMetricAggregateSource = 'semantic_model' | 'caller_override' | 'default_sum';
+
 declare type SemaphorMetricAnalysis = {
     kind: 'period_change';
     orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
@@ -230,6 +482,7 @@ export declare type SemaphorMetricPayload = {
     delta?: number | null;
     deltaPercent?: number | null;
     records?: Array<Record<string, unknown>>;
+    executionResult?: SemaphorAnalyticsExecutionResult;
 };
 
 export declare type SemaphorMetricQueryResult = SemaphorQueryState & SemaphorMetricPayload & {
@@ -251,13 +504,31 @@ export declare type SemaphorMetricQuerySpec = SemaphorQuerySourceSpec & {
     limit?: number;
 };
 
+declare type SemaphorMetricResult = SemaphorAnalyticsResultBase & {
+    kind: 'metric';
+    value: number | string | null;
+    comparison?: {
+        kind: NonNullable<SemaphorMetricIntent['comparison']>['kind'];
+        value?: number | string | null;
+        delta?: number | null;
+        deltaPercent?: number | null;
+    };
+};
+
 export declare type SemaphorNonEmptyArray<T> = [T, ...T[]];
 
 export declare type SemaphorOptionValue = string | number | boolean;
 
+declare type SemaphorProtocolIssue = {
+    code: string;
+    message: string;
+    path?: string;
+};
+
 declare type SemaphorProtocolVersion = 1;
 
 export declare 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, {
@@ -278,6 +549,8 @@ export declare type SemaphorQueryOrderBy = {
     direction: 'asc' | 'desc';
 };
 
+declare type SemaphorQueryPath = 'query_spec' | 'sql' | 'sql_python';
+
 export declare type SemaphorQuerySourceSpec = {
     source: SemaphorSourceRef;
 };
@@ -327,6 +600,7 @@ export declare type SemaphorRecordsPayload<TRecord extends Record<string, unknow
     records: TRecord[];
     columns?: SemaphorResultColumn[];
     rowCount?: number;
+    executionResult?: SemaphorAnalyticsExecutionResult;
 };
 
 export declare type SemaphorRecordsQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryState & SemaphorRecordsPayload<TRecord> & {
@@ -336,10 +610,37 @@ export declare type SemaphorRecordsQueryResult<TRecord extends Record<string, un
 
 export declare type SemaphorRecordsQuerySpec = SemaphorRecordsBaseQuerySpec & SemaphorRecordsSelectorSpec;
 
+declare type SemaphorRecordsResult = SemaphorAnalyticsResultBase & {
+    kind: 'records';
+    columns: SemaphorResultColumn[];
+    records: Array<Record<string, unknown>>;
+};
+
 declare type SemaphorRecordsSelectorSpec = {
     fields: SemaphorNonEmptyArray<SemaphorRecordsField>;
 };
 
+declare type SemaphorRelationshipDiagnostics = {
+    status: SemaphorRelationshipDiagnosticStatus;
+    requiredSources?: SemaphorSourceRef[];
+    relationshipsUsed?: string[];
+    missingSources?: string[];
+    warnings?: string[];
+    message?: string;
+    recommendedNextStep?: string;
+    joinPlanSummary?: {
+        baseSource?: SemaphorSourceRef;
+        joinedSources?: SemaphorSourceRef[];
+        joinCount?: number;
+    };
+    fanoutRisk?: {
+        status: 'none' | 'warning' | 'error' | 'unknown';
+        message?: string;
+    };
+};
+
+declare type SemaphorRelationshipDiagnosticStatus = 'not_required' | 'resolved' | 'missing' | 'ambiguous' | 'fanout_risk' | 'unknown';
+
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
     unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
@@ -410,12 +711,27 @@ declare type SemaphorSqlIntent = {
     inputs?: SemaphorInputBinding[];
 };
 
+declare type SemaphorSqlResult = SemaphorAnalyticsResultBase & {
+    kind: 'sql';
+    columns: SemaphorRecordsResult['columns'];
+    records: SemaphorRecordsResult['records'];
+    sqlShape?: {
+        statementType?: string;
+        explicitLimit?: number;
+        hasPythonCode?: boolean;
+    };
+};
+
 declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
 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;
@@ -437,6 +753,8 @@ export declare function toSemaphorMetricIntent(spec: SemaphorMetricQuerySpec): S
 
 export declare function toSemaphorRecordsIntent(spec: SemaphorRecordsQuerySpec): SemaphorRecordsIntent;
 
+export declare function useSemaphorAnalysis(spec: SemaphorAnalysisQuerySpec): SemaphorAnalysisQueryResult;
+
 export declare function useSemaphorDataAppRuntime(): SemaphorDataAppRuntime;
 
 export declare function useSemaphorInput<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputHandle;
@@ -447,4 +765,19 @@ export declare function useSemaphorMetric(spec: SemaphorMetricQuerySpec): Semaph
 
 export declare function useSemaphorRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(spec: SemaphorRecordsQuerySpec): SemaphorRecordsQueryResult<TRecord>;
 
+export declare function validateSemaphorDataAppHookSpecs(input: {
+    hooks: SemaphorDataAppHookSpec[];
+    fieldCatalogs?: SemaphorDataAppFieldCatalog[];
+    requireFieldCatalog?: boolean;
+    validateTimezone?: SemaphorAnalysisTimezoneValidator;
+}): SemaphorDataAppValidationResult;
+
+/**
+ * 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 { }

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.359",
+  "version": "0.1.360",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -72,6 +72,11 @@
       "import": "./dist/data-app-sdk/index.js",
       "require": "./dist/data-app-sdk/index.cjs"
     },
+    "./data-app-sdk/validation": {
+      "types": "./dist/types/data-app-sdk-validation.d.ts",
+      "import": "./dist/data-app-sdk-validation/index.js",
+      "require": "./dist/data-app-sdk-validation/index.cjs"
+    },
     "./data-app-builder": {
       "types": "./dist/types/data-app-builder.d.ts",
       "import": "./dist/data-app-builder/index.js",