react-semaphor 0.1.324 → 0.1.326

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

@@ -0,0 +1,495 @@
+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';
+    title: string;
+    description?: string;
+    inputs?: SemaphorInputSpec[];
+    sections: SemaphorDashboardSectionIntent[];
+};
+
+export declare type SemaphorDashboardSectionIntent = {
+    id?: string;
+    title: string;
+    description?: string;
+    views: SemaphorDashboardViewIntent[];
+};
+
+export declare type SemaphorDashboardViewIntent = {
+    id?: string;
+    title: string;
+    description?: string;
+    presentation: SemaphorViewPresentation;
+    analytics?: SemaphorAnalyticsIntent;
+    text?: string;
+};
+
+export declare type SemaphorDialect = 'semantic' | 'postgres' | 'mysql' | 'snowflake' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+
+export declare type SemaphorExperienceIntent = SemaphorDashboardIntent;
+
+export declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+};
+
+export declare type SemaphorInputBinding = {
+    inputId: string;
+    field?: SemaphorFieldRef;
+};
+
+export declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'between' | '>' | '>=' | '<' | '<=';
+
+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[];
+} | {
+    level: 'section';
+    sectionId: string;
+    excludeViewIds?: string[];
+} | {
+    level: 'view';
+    viewIds: string[];
+};
+
+export declare type SemaphorInputSpec = {
+    id: string;
+    kind: 'filter' | 'control';
+    label: string;
+    field: SemaphorFieldRef;
+    operator?: SemaphorInputOperator;
+    multi?: boolean;
+    defaultValue?: unknown;
+    source?: SemaphorSourceRef;
+    scope?: SemaphorInputScope;
+};
+
+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 = {
+    code: string;
+    message: string;
+    path?: string;
+};
+
+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;
+    timeGrain?: SemaphorTimeGrain;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    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;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    sql: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
+export declare type SemaphorSqlIntent = {
+    kind: 'sql';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: Extract<SemaphorSourceRef, {
+        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 = {
+    ok: boolean;
+    errors: SemaphorProtocolIssue[];
+    warnings: SemaphorProtocolIssue[];
+};
+
+export declare type SemaphorViewPresentation = {
+    kind: 'kpi';
+    format?: 'number' | 'currency' | 'percent' | 'duration';
+} | {
+    kind: 'lineChart' | 'barChart' | 'areaChart';
+    x?: string;
+    y?: string[];
+} | {
+    kind: 'table';
+    columns?: string[];
+} | {
+    kind: 'text';
+};
+
+export declare function validateSemaphorAnalyticsIntent(intent: SemaphorAnalyticsIntent): SemaphorAnalyticsValidationResult;
+
+export declare function validateSemaphorDashboardIntent(intent: SemaphorDashboardIntent): SemaphorValidationResult;
+
+export { }

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;
 };
 
@@ -739,10 +740,18 @@ export declare type DashboardPlanFilterInput = {
     id: string;
     label: string;
     variableName: string;
+    scope?: DashboardInputScope;
     filter: TFilter;
     defaultValue?: unknown;
 };
 
+export declare type DashboardPlanFromProtocolResult = {
+    plan: DashboardPlan;
+    warnings: DashboardPlanWarning[];
+};
+
+export declare function dashboardPlanFromSemaphorDashboardIntent(intent: SemaphorDashboardIntent): DashboardPlanFromProtocolResult;
+
 export declare type DashboardPlanSheet = {
     id: string;
     title: string;
@@ -792,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;
@@ -1751,6 +1761,179 @@ declare type SelectedEntities = SelectedEntity[];
 
 declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
 
+declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
+
+declare type SemaphorDashboardIntent = {
+    version: SemaphorProtocolVersion;
+    kind: 'dashboard';
+    title: string;
+    description?: string;
+    inputs?: SemaphorInputSpec[];
+    sections: SemaphorDashboardSectionIntent[];
+};
+
+declare type SemaphorDashboardSectionIntent = {
+    id?: string;
+    title: string;
+    description?: string;
+    views: SemaphorDashboardViewIntent[];
+};
+
+declare type SemaphorDashboardViewIntent = {
+    id?: string;
+    title: string;
+    description?: string;
+    presentation: SemaphorViewPresentation;
+    analytics?: SemaphorAnalyticsIntent;
+    text?: string;
+};
+
+declare type SemaphorDialect = 'semantic' | 'postgres' | 'mysql' | 'snowflake' | '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';
+};
+
+declare type SemaphorInputBinding = {
+    inputId: string;
+    field?: SemaphorFieldRef;
+};
+
+declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'between' | '>' | '>=' | '<' | '<=';
+
+declare type SemaphorInputOptionsIntent = {
+    kind: 'inputOptions';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorSourceRef;
+    field: SemaphorFieldRef;
+    search?: string;
+    limit?: number;
+};
+
+declare type SemaphorInputScope = {
+    level: 'dashboard';
+    excludeViewIds?: string[];
+} | {
+    level: 'section';
+    sectionId: string;
+    excludeViewIds?: string[];
+} | {
+    level: 'view';
+    viewIds: string[];
+};
+
+declare type SemaphorInputSpec = {
+    id: string;
+    kind: 'filter' | 'control';
+    label: string;
+    field: SemaphorFieldRef;
+    operator?: SemaphorInputOperator;
+    multi?: boolean;
+    defaultValue?: unknown;
+    source?: SemaphorSourceRef;
+    scope?: SemaphorInputScope;
+};
+
+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;
+    timeGrain?: SemaphorTimeGrain;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    inputs?: SemaphorInputBinding[];
+};
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    sql: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
+declare type SemaphorSqlIntent = {
+    kind: 'sql';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: Extract<SemaphorSourceRef, {
+        kind: 'sql' | 'physical';
+    }>;
+    sql?: string;
+    parameters?: Record<string, unknown>;
+    pythonCode?: string;
+    limit?: number;
+    rationale?: string;
+    fields?: SemaphorFieldRef[];
+    inputs?: SemaphorInputBinding[];
+};
+
+declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+declare type SemaphorViewPresentation = {
+    kind: 'kpi';
+    format?: 'number' | 'currency' | 'percent' | 'duration';
+} | {
+    kind: 'lineChart' | 'barChart' | 'areaChart';
+    x?: string;
+    y?: string[];
+} | {
+    kind: 'table';
+    columns?: string[];
+} | {
+    kind: 'text';
+};
+
 declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';