react-semaphor 0.1.325 → 0.1.326

package/dist/types/analytics-protocol.d.ts

@@ -1,5 +1,265 @@
+export declare type AnalyticsCatalogDataType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+
+export declare type AnalyticsCatalogField = {
+    id?: unknown;
+    column_name?: unknown;
+    name?: unknown;
+    label?: unknown;
+    alias?: unknown;
+    qualifiedFieldName?: unknown;
+    data_type?: unknown;
+    dataType?: unknown;
+    role?: unknown;
+};
+
+export declare type AnalyticsCatalogFieldSummary = {
+    validMetricCandidates: string[];
+    validDateCandidates: string[];
+    validDimensionCandidates: string[];
+};
+
+export declare type AnalyticsMetricFormat = {
+    type: 'number' | 'currency' | 'percent' | 'scientific';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
+export declare function buildAnalyticsCatalogFieldSummary(fields: AnalyticsCatalogField[]): AnalyticsCatalogFieldSummary;
+
+export declare function getAnalyticsCatalogFieldCandidates(field: AnalyticsCatalogField): string[];
+
+export declare function getAnalyticsCatalogFieldName(field: AnalyticsCatalogField): string;
+
+export declare function inferAnalyticsMetricFormat(field: AnalyticsCatalogField): AnalyticsMetricFormat | undefined;
+
+export declare function isAnalyticsCatalogDateField(field: AnalyticsCatalogField): boolean;
+
+export declare function isAnalyticsCatalogDimensionField(field: AnalyticsCatalogField): boolean;
+
+export declare function isAnalyticsCatalogMetricField(field: AnalyticsCatalogField, options?: {
+    excludeIdentifiers?: boolean;
+}): boolean;
+
+export declare function isAnalyticsDateLikeDataType(value: unknown): boolean;
+
+export declare function isAnalyticsMetricIdentifierField(field: AnalyticsCatalogField): boolean;
+
+export declare function isAnalyticsTechnicalIdentifierField(field: AnalyticsCatalogField): boolean;
+
+export declare function normalizeAnalyticsCatalogDataType(value: unknown): AnalyticsCatalogDataType;
+
+export declare function normalizeAnalyticsCatalogName(value: unknown): string;
+
+export declare const SEMAPHOR_ANALYTICS_INTENT_FIXTURES: {
+    revenueKpi: {
+        version: 1;
+        kind: "metric";
+        id: string;
+        label: string;
+        source: {
+            readonly kind: "semantic";
+            readonly domainId: "domain_sales";
+            readonly datasetName: "orders";
+            readonly connectionId: "conn_sales";
+            readonly label: "Orders";
+        };
+        metric: string;
+        comparison: {
+            kind: "previous_period";
+        };
+        limit: number;
+    };
+    revenueTrend: {
+        version: 1;
+        kind: "records";
+        id: string;
+        label: string;
+        source: {
+            readonly kind: "semantic";
+            readonly domainId: "domain_sales";
+            readonly datasetName: "orders";
+            readonly connectionId: "conn_sales";
+            readonly label: "Orders";
+        };
+        fields: {
+            name: string;
+            role: "date";
+            dataType: "date";
+            label: string;
+        }[];
+        measures: string[];
+        dateField: {
+            name: string;
+            role: "date";
+            dataType: "date";
+        };
+        timeGrain: "month";
+        limit: number;
+    };
+    topCustomersRecords: {
+        version: 1;
+        kind: "records";
+        id: string;
+        label: string;
+        source: {
+            readonly kind: "semantic";
+            readonly domainId: "domain_sales";
+            readonly datasetName: "orders";
+            readonly connectionId: "conn_sales";
+            readonly label: "Orders";
+        };
+        fields: ({
+            name: string;
+            role: "dimension";
+            dataType: "string";
+        } | {
+            name: string;
+            role: "measure";
+            dataType: "number";
+        })[];
+        measures: string[];
+        orderBy: {
+            field: string;
+            direction: "desc";
+        };
+        limit: number;
+    };
+    regionInputOptions: {
+        version: 1;
+        kind: "inputOptions";
+        id: string;
+        label: string;
+        source: {
+            readonly kind: "semantic";
+            readonly domainId: "domain_sales";
+            readonly datasetName: "orders";
+            readonly connectionId: "conn_sales";
+            readonly label: "Orders";
+        };
+        field: {
+            name: string;
+            role: "dimension";
+            dataType: "string";
+        };
+        limit: number;
+    };
+    previousPeriodRevenueComparison: {
+        version: 1;
+        kind: "metric";
+        id: string;
+        label: string;
+        source: {
+            readonly kind: "semantic";
+            readonly domainId: "domain_sales";
+            readonly datasetName: "orders";
+            readonly connectionId: "conn_sales";
+            readonly label: "Orders";
+        };
+        metric: string;
+        dateField: {
+            name: string;
+            role: "date";
+            dataType: "date";
+        };
+        timeGrain: "week";
+        comparison: {
+            kind: "previous_period";
+        };
+        limit: number;
+    };
+    boundedSqlRanking: {
+        version: 1;
+        kind: "sql";
+        id: string;
+        label: string;
+        source: {
+            kind: "physical";
+            connectionId: string;
+            databaseName: string;
+            schemaName: string;
+            tableName: string;
+            dialect: "postgres";
+        };
+        sql: string;
+        limit: number;
+        rationale: string;
+        fields: ({
+            name: string;
+            role: "dimension";
+            dataType: "string";
+        } | {
+            name: string;
+            role: "measure";
+            dataType: "number";
+        })[];
+    };
+};
+
+export declare type SemaphorAnalyticsFieldRole = 'metric' | 'dateField' | 'dimension' | 'input' | 'source' | 'sql';
+
 export declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
 
+export declare type SemaphorAnalyticsIntentFixtureName = keyof typeof SEMAPHOR_ANALYTICS_INTENT_FIXTURES;
+
+export declare type SemaphorAnalyticsRepairHint = {
+    code: SemaphorAnalyticsValidationCode | string;
+    message?: string;
+    invalidField?: string;
+    fieldRole?: SemaphorAnalyticsFieldRole;
+    validMetricCandidates?: string[];
+    validDateCandidates?: string[];
+    validDimensionCandidates?: string[];
+    recommendedNextStep: string;
+};
+
+export declare type SemaphorAnalyticsResult = SemaphorMetricResult | SemaphorRecordsResult | SemaphorInputOptionsResult | SemaphorSqlResult;
+
+export declare type SemaphorAnalyticsResultBase = {
+    intentId?: string;
+    queryPath: SemaphorQueryPath;
+    warnings?: string[];
+    rowCount?: number;
+    rowLimitExceeded?: boolean;
+    limit?: number;
+};
+
+export 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';
+
+export declare type SemaphorAnalyticsValidationIssue = SemaphorProtocolIssue & {
+    code: SemaphorAnalyticsValidationCode | string;
+    fieldRole?: SemaphorAnalyticsFieldRole;
+    repairHint?: SemaphorAnalyticsRepairHint;
+};
+
+export declare type SemaphorAnalyticsValidationResult = {
+    ok: boolean;
+    errors: SemaphorAnalyticsValidationIssue[];
+    warnings: SemaphorAnalyticsValidationIssue[];
+    repairHints: SemaphorAnalyticsRepairHint[];
+};
+
 export declare type SemaphorDashboardIntent = {
     version: SemaphorProtocolVersion;
     kind: 'dashboard';
@@ -45,12 +305,24 @@ export declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'cont
 
 export declare type SemaphorInputOptionsIntent = {
     kind: 'inputOptions';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
     source: SemaphorSourceRef;
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
 };
 
+export declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
+    kind: 'inputOptions';
+    options: Array<{
+        label: string;
+        value: unknown;
+        count?: number;
+    }>;
+};
+
 export declare type SemaphorInputScope = {
     level: 'dashboard';
     excludeViewIds?: string[];
@@ -77,15 +349,32 @@ export declare type SemaphorInputSpec = {
 
 export declare type SemaphorMetricIntent = {
     kind: 'metric';
+    version?: SemaphorProtocolVersion;
+    id?: string;
     source: SemaphorSourceRef;
     metric: string;
+    metrics?: string[];
     label?: string;
     dateField?: SemaphorFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    dimensions?: SemaphorFieldRef[];
     comparison?: {
         kind: 'previous_period' | 'previous_year' | 'target';
         targetValue?: number;
     };
     inputs?: SemaphorInputBinding[];
+    limit?: number;
+};
+
+export 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 SemaphorProtocolIssue = {
@@ -96,9 +385,14 @@ export declare type SemaphorProtocolIssue = {
 
 export declare type SemaphorProtocolVersion = 1;
 
+export declare type SemaphorQueryPath = 'query_spec' | 'sql' | 'sql_python';
+
 export declare type SemaphorRecordsIntent = {
     kind: 'records';
+    version?: SemaphorProtocolVersion;
     source: SemaphorSourceRef;
+    id?: string;
+    label?: string;
     fields: SemaphorFieldRef[];
     measures?: string[];
     dateField?: SemaphorFieldRef;
@@ -111,6 +405,16 @@ export declare type SemaphorRecordsIntent = {
     inputs?: SemaphorInputBinding[];
 };
 
+export declare type SemaphorRecordsResult = SemaphorAnalyticsResultBase & {
+    kind: 'records';
+    columns: Array<{
+        name: string;
+        label?: string;
+        dataType?: SemaphorFieldRef['dataType'];
+    }>;
+    records: Array<Record<string, unknown>>;
+};
+
 export declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -136,13 +440,32 @@ export declare type SemaphorSourceRef = {
 
 export declare type SemaphorSqlIntent = {
     kind: 'sql';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
     source: Extract<SemaphorSourceRef, {
-        kind: 'sql';
+        kind: 'sql' | 'physical';
     }>;
+    sql?: string;
+    parameters?: Record<string, unknown>;
+    pythonCode?: string;
+    limit?: number;
+    rationale?: string;
     fields?: SemaphorFieldRef[];
     inputs?: SemaphorInputBinding[];
 };
 
+export declare type SemaphorSqlResult = SemaphorAnalyticsResultBase & {
+    kind: 'sql';
+    columns: SemaphorRecordsResult['columns'];
+    records: SemaphorRecordsResult['records'];
+    sqlShape?: {
+        statementType?: string;
+        explicitLimit?: number;
+        hasPythonCode?: boolean;
+    };
+};
+
 export declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
 
 export declare type SemaphorValidationResult = {
@@ -165,7 +488,7 @@ export declare type SemaphorViewPresentation = {
     kind: 'text';
 };
 
-export declare function validateSemaphorAnalyticsIntent(intent: SemaphorAnalyticsIntent): SemaphorValidationResult;
+export declare function validateSemaphorAnalyticsIntent(intent: SemaphorAnalyticsIntent): SemaphorAnalyticsValidationResult;
 
 export declare function validateSemaphorDashboardIntent(intent: SemaphorDashboardIntent): SemaphorValidationResult;
 

package/dist/types/dashboard-authoring.d.ts

@@ -732,6 +732,7 @@ export declare type DashboardPlanCard = {
     priority: number;
     section?: string;
     query?: DashboardCardQueryIntent;
+    analyticsIntent?: SemaphorAnalyticsIntent;
     text?: string;
 };
 
@@ -800,6 +801,7 @@ declare interface DataModelEntityReference extends DatabaseEntityReference {
 declare interface DatasetEntityReference extends DatabaseEntityReference {
     type: 'dataset';
     datasetType: 'physical' | 'virtual';
+    table?: string | null;
     datamodelId?: string | null;
     sql?: string | null;
     id: string;
@@ -1804,6 +1806,9 @@ declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' |
 
 declare type SemaphorInputOptionsIntent = {
     kind: 'inputOptions';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
     source: SemaphorSourceRef;
     field: SemaphorFieldRef;
     search?: string;
@@ -1836,22 +1841,31 @@ declare type SemaphorInputSpec = {
 
 declare type SemaphorMetricIntent = {
     kind: 'metric';
+    version?: SemaphorProtocolVersion;
+    id?: string;
     source: SemaphorSourceRef;
     metric: string;
+    metrics?: string[];
     label?: string;
     dateField?: SemaphorFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    dimensions?: SemaphorFieldRef[];
     comparison?: {
         kind: 'previous_period' | 'previous_year' | 'target';
         targetValue?: number;
     };
     inputs?: SemaphorInputBinding[];
+    limit?: number;
 };
 
 declare type SemaphorProtocolVersion = 1;
 
 declare type SemaphorRecordsIntent = {
     kind: 'records';
+    version?: SemaphorProtocolVersion;
     source: SemaphorSourceRef;
+    id?: string;
+    label?: string;
     fields: SemaphorFieldRef[];
     measures?: string[];
     dateField?: SemaphorFieldRef;
@@ -1889,9 +1903,17 @@ declare type SemaphorSourceRef = {
 
 declare type SemaphorSqlIntent = {
     kind: 'sql';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
     source: Extract<SemaphorSourceRef, {
-        kind: 'sql';
+        kind: 'sql' | 'physical';
     }>;
+    sql?: string;
+    parameters?: Record<string, unknown>;
+    pythonCode?: string;
+    limit?: number;
+    rationale?: string;
     fields?: SemaphorFieldRef[];
     inputs?: SemaphorInputBinding[];
 };

package/dist/types/dashboard.d.ts

@@ -812,6 +812,7 @@ declare interface DataModelEntityReference extends DatabaseEntityReference {
 declare interface DatasetEntityReference extends DatabaseEntityReference {
     type: 'dataset';
     datasetType: 'physical' | 'virtual';
+    table?: string | null;
     datamodelId?: string | null;
     sql?: string | null;
     id: string;
@@ -2500,7 +2501,11 @@ export declare type TDataColumn = {
     label?: string;
     description?: string;
     qualifiedFieldName?: string;
-    role?: 'metric';
+    qualifiedEntityName?: string;
+    entityId?: string;
+    entityName?: string;
+    entityType?: EntityType;
+    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
     format?: FormatSpec;