@querypanel/node-sdk 1.0.38 → 1.0.40

package/dist/index.d.cts

@@ -179,6 +179,7 @@ interface SdkChart {
     sql: string;
     sql_params: Record<string, unknown> | null;
     vega_lite_spec: Record<string, unknown>;
+    spec_type?: 'vega-lite' | 'vizspec';
     query_id: string | null;
     organization_id: string | null;
     tenant_id: string | null;
@@ -194,6 +195,7 @@ interface ChartCreateInput {
     sql: string;
     sql_params?: Record<string, unknown>;
     vega_lite_spec: Record<string, unknown>;
+    spec_type?: 'vega-lite' | 'vizspec';
     query_id?: string;
     target_db?: string;
 }
@@ -203,6 +205,7 @@ interface ChartUpdateInput {
     sql?: string;
     sql_params?: Record<string, unknown>;
     vega_lite_spec?: Record<string, unknown>;
+    spec_type?: 'vega-lite' | 'vizspec';
     target_db?: string;
 }
 interface PaginationQuery {
@@ -281,6 +284,94 @@ interface SchemaSyncOptions {
     forceReindex?: boolean;
 }
 
+/**
+ * VizSpec types for flexible visualization specifications
+ * Supports chart, table, and metric visualizations
+ */
+type FieldType = 'quantitative' | 'temporal' | 'ordinal' | 'nominal' | 'boolean';
+interface ValueFormat {
+    style?: 'number' | 'currency' | 'percent' | 'date' | 'time' | 'datetime';
+    currency?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    dateStyle?: 'short' | 'medium' | 'long';
+}
+interface FieldRef {
+    field: string;
+    label?: string;
+    type?: FieldType;
+    format?: ValueFormat;
+}
+type AggregateOp = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'distinct';
+type TimeUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute';
+interface AxisField extends FieldRef {
+    aggregate?: AggregateOp;
+    timeUnit?: TimeUnit;
+}
+interface MetricField extends FieldRef {
+    aggregate?: AggregateOp;
+}
+interface SortSpec {
+    field: string;
+    direction?: 'asc' | 'desc';
+}
+interface VizSpecBase {
+    version: '1.0';
+    kind: 'chart' | 'table' | 'metric';
+    title?: string;
+    description?: string;
+    data: {
+        sourceId: string;
+    };
+}
+type ChartType = 'line' | 'bar' | 'area' | 'scatter' | 'pie';
+type StackingMode = 'none' | 'stacked' | 'percent';
+interface ChartEncoding {
+    chartType: ChartType;
+    x?: AxisField;
+    y?: AxisField | AxisField[];
+    series?: FieldRef;
+    stacking?: StackingMode;
+    sort?: SortSpec;
+    limit?: number;
+    tooltips?: FieldRef[];
+}
+interface ChartSpec extends VizSpecBase {
+    kind: 'chart';
+    encoding: ChartEncoding;
+}
+type TextAlign = 'left' | 'right' | 'center';
+interface TableColumn extends FieldRef {
+    width?: number;
+    align?: TextAlign;
+    isHidden?: boolean;
+}
+interface TableEncoding {
+    columns: TableColumn[];
+    sort?: SortSpec;
+    limit?: number;
+}
+interface TableSpec extends VizSpecBase {
+    kind: 'table';
+    encoding: TableEncoding;
+}
+type ComparisonMode = 'delta' | 'deltaPercent' | 'ratio';
+interface MetricTrend {
+    timeField: AxisField;
+    valueField: MetricField;
+}
+interface MetricEncoding {
+    valueField: MetricField;
+    comparisonField?: MetricField;
+    comparisonMode?: ComparisonMode;
+    trend?: MetricTrend;
+}
+interface MetricSpec extends VizSpecBase {
+    kind: 'metric';
+    encoding: MetricEncoding;
+}
+type VizSpec = ChartSpec | TableSpec | MetricSpec;
+
 interface ContextDocument {
     source?: string;
     pageContent: string;
@@ -288,7 +379,9 @@ interface ContextDocument {
     score?: number;
 }
 interface ChartEnvelope {
-    vegaLiteSpec: Record<string, unknown> | null;
+    vegaLiteSpec?: Record<string, unknown> | null;
+    vizSpec?: VizSpec | null;
+    specType: 'vega-lite' | 'vizspec';
     notes: string | null;
 }
 interface AskOptions {
@@ -300,6 +393,7 @@ interface AskOptions {
     previousSql?: string;
     maxRetry?: number;
     chartMaxRetries?: number;
+    chartType?: 'vega-lite' | 'vizspec';
 }
 interface AskResponse {
     sql: string;
@@ -317,6 +411,26 @@ interface AskResponse {
 }
 declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
 
+interface VizSpecGenerateInput {
+    question: string;
+    sql: string;
+    rationale?: string;
+    fields: string[];
+    rows: Array<Record<string, unknown>>;
+    max_retries?: number;
+    query_id?: string;
+}
+interface VizSpecGenerateOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+    maxRetries?: number;
+}
+interface VizSpecResponse {
+    spec: VizSpec;
+    notes: string | null;
+}
+
 /**
  * Main SDK class - Thin orchestrator
  * Delegates to deep modules (ApiClient, QueryEngine, route modules)
@@ -347,6 +461,7 @@ declare class QueryPanelSdkAPI {
     introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
     syncSchema(databaseName: string, options: SchemaSyncOptions, signal?: AbortSignal): Promise<IngestResponse>;
     ask(question: string, options: AskOptions, signal?: AbortSignal): Promise<AskResponse>;
+    generateVizSpec(input: VizSpecGenerateInput, options?: VizSpecGenerateOptions, signal?: AbortSignal): Promise<VizSpecResponse>;
     createChart(body: ChartCreateInput, options?: {
         tenantId?: string;
         userId?: string;
@@ -387,4 +502,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<void>;
 }
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AskOptions, type AskResponse, type ChartCreateInput, type ChartEnvelope, type ChartListOptions, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type IngestResponse, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryPanelSdkAPI, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, anonymizeResults };
+export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AskOptions, type AskResponse, type AxisField, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type FieldRef, type FieldType, type IngestResponse, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryPanelSdkAPI, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type TableColumn, type TableEncoding, type TableSpec, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };

package/dist/index.d.ts

@@ -179,6 +179,7 @@ interface SdkChart {
     sql: string;
     sql_params: Record<string, unknown> | null;
     vega_lite_spec: Record<string, unknown>;
+    spec_type?: 'vega-lite' | 'vizspec';
     query_id: string | null;
     organization_id: string | null;
     tenant_id: string | null;
@@ -194,6 +195,7 @@ interface ChartCreateInput {
     sql: string;
     sql_params?: Record<string, unknown>;
     vega_lite_spec: Record<string, unknown>;
+    spec_type?: 'vega-lite' | 'vizspec';
     query_id?: string;
     target_db?: string;
 }
@@ -203,6 +205,7 @@ interface ChartUpdateInput {
     sql?: string;
     sql_params?: Record<string, unknown>;
     vega_lite_spec?: Record<string, unknown>;
+    spec_type?: 'vega-lite' | 'vizspec';
     target_db?: string;
 }
 interface PaginationQuery {
@@ -281,6 +284,94 @@ interface SchemaSyncOptions {
     forceReindex?: boolean;
 }
 
+/**
+ * VizSpec types for flexible visualization specifications
+ * Supports chart, table, and metric visualizations
+ */
+type FieldType = 'quantitative' | 'temporal' | 'ordinal' | 'nominal' | 'boolean';
+interface ValueFormat {
+    style?: 'number' | 'currency' | 'percent' | 'date' | 'time' | 'datetime';
+    currency?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    dateStyle?: 'short' | 'medium' | 'long';
+}
+interface FieldRef {
+    field: string;
+    label?: string;
+    type?: FieldType;
+    format?: ValueFormat;
+}
+type AggregateOp = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'distinct';
+type TimeUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute';
+interface AxisField extends FieldRef {
+    aggregate?: AggregateOp;
+    timeUnit?: TimeUnit;
+}
+interface MetricField extends FieldRef {
+    aggregate?: AggregateOp;
+}
+interface SortSpec {
+    field: string;
+    direction?: 'asc' | 'desc';
+}
+interface VizSpecBase {
+    version: '1.0';
+    kind: 'chart' | 'table' | 'metric';
+    title?: string;
+    description?: string;
+    data: {
+        sourceId: string;
+    };
+}
+type ChartType = 'line' | 'bar' | 'area' | 'scatter' | 'pie';
+type StackingMode = 'none' | 'stacked' | 'percent';
+interface ChartEncoding {
+    chartType: ChartType;
+    x?: AxisField;
+    y?: AxisField | AxisField[];
+    series?: FieldRef;
+    stacking?: StackingMode;
+    sort?: SortSpec;
+    limit?: number;
+    tooltips?: FieldRef[];
+}
+interface ChartSpec extends VizSpecBase {
+    kind: 'chart';
+    encoding: ChartEncoding;
+}
+type TextAlign = 'left' | 'right' | 'center';
+interface TableColumn extends FieldRef {
+    width?: number;
+    align?: TextAlign;
+    isHidden?: boolean;
+}
+interface TableEncoding {
+    columns: TableColumn[];
+    sort?: SortSpec;
+    limit?: number;
+}
+interface TableSpec extends VizSpecBase {
+    kind: 'table';
+    encoding: TableEncoding;
+}
+type ComparisonMode = 'delta' | 'deltaPercent' | 'ratio';
+interface MetricTrend {
+    timeField: AxisField;
+    valueField: MetricField;
+}
+interface MetricEncoding {
+    valueField: MetricField;
+    comparisonField?: MetricField;
+    comparisonMode?: ComparisonMode;
+    trend?: MetricTrend;
+}
+interface MetricSpec extends VizSpecBase {
+    kind: 'metric';
+    encoding: MetricEncoding;
+}
+type VizSpec = ChartSpec | TableSpec | MetricSpec;
+
 interface ContextDocument {
     source?: string;
     pageContent: string;
@@ -288,7 +379,9 @@ interface ContextDocument {
     score?: number;
 }
 interface ChartEnvelope {
-    vegaLiteSpec: Record<string, unknown> | null;
+    vegaLiteSpec?: Record<string, unknown> | null;
+    vizSpec?: VizSpec | null;
+    specType: 'vega-lite' | 'vizspec';
     notes: string | null;
 }
 interface AskOptions {
@@ -300,6 +393,7 @@ interface AskOptions {
     previousSql?: string;
     maxRetry?: number;
     chartMaxRetries?: number;
+    chartType?: 'vega-lite' | 'vizspec';
 }
 interface AskResponse {
     sql: string;
@@ -317,6 +411,26 @@ interface AskResponse {
 }
 declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
 
+interface VizSpecGenerateInput {
+    question: string;
+    sql: string;
+    rationale?: string;
+    fields: string[];
+    rows: Array<Record<string, unknown>>;
+    max_retries?: number;
+    query_id?: string;
+}
+interface VizSpecGenerateOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+    maxRetries?: number;
+}
+interface VizSpecResponse {
+    spec: VizSpec;
+    notes: string | null;
+}
+
 /**
  * Main SDK class - Thin orchestrator
  * Delegates to deep modules (ApiClient, QueryEngine, route modules)
@@ -347,6 +461,7 @@ declare class QueryPanelSdkAPI {
     introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
     syncSchema(databaseName: string, options: SchemaSyncOptions, signal?: AbortSignal): Promise<IngestResponse>;
     ask(question: string, options: AskOptions, signal?: AbortSignal): Promise<AskResponse>;
+    generateVizSpec(input: VizSpecGenerateInput, options?: VizSpecGenerateOptions, signal?: AbortSignal): Promise<VizSpecResponse>;
     createChart(body: ChartCreateInput, options?: {
         tenantId?: string;
         userId?: string;
@@ -387,4 +502,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<void>;
 }
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AskOptions, type AskResponse, type ChartCreateInput, type ChartEnvelope, type ChartListOptions, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type IngestResponse, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryPanelSdkAPI, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, anonymizeResults };
+export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AskOptions, type AskResponse, type AxisField, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type FieldRef, type FieldType, type IngestResponse, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryPanelSdkAPI, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type TableColumn, type TableEncoding, type TableSpec, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };

package/dist/index.js

@@ -1162,35 +1162,62 @@ async function ask(client, queryEngine, question, options, signal) {
         tenantId
       );
       const rows = execution.rows ?? [];
+      const chartType = options.chartType ?? "vega-lite";
       let chart = {
-        vegaLiteSpec: null,
+        specType: chartType,
         notes: rows.length === 0 ? "Query returned no rows." : null
       };
       if (rows.length > 0) {
-        const chartResponse = await client.post(
-          "/chart",
-          {
-            question,
-            sql: queryResponse.sql,
-            rationale: queryResponse.rationale,
-            fields: execution.fields,
-            rows: anonymizeResults(rows),
-            max_retries: options.chartMaxRetries ?? 3,
-            query_id: queryResponse.queryId
-          },
-          tenantId,
-          options.userId,
-          options.scopes,
-          signal,
-          sessionId
-        );
-        chart = {
-          vegaLiteSpec: chartResponse.chart ? {
-            ...chartResponse.chart,
-            data: { values: rows }
-          } : null,
-          notes: chartResponse.notes
-        };
+        if (chartType === "vizspec") {
+          const vizspecResponse = await client.post(
+            "/vizspec",
+            {
+              question,
+              sql: queryResponse.sql,
+              rationale: queryResponse.rationale,
+              fields: execution.fields,
+              rows: anonymizeResults(rows),
+              max_retries: options.chartMaxRetries ?? 3,
+              query_id: queryResponse.queryId
+            },
+            tenantId,
+            options.userId,
+            options.scopes,
+            signal,
+            sessionId
+          );
+          chart = {
+            vizSpec: vizspecResponse.spec,
+            specType: "vizspec",
+            notes: vizspecResponse.notes
+          };
+        } else {
+          const chartResponse = await client.post(
+            "/chart",
+            {
+              question,
+              sql: queryResponse.sql,
+              rationale: queryResponse.rationale,
+              fields: execution.fields,
+              rows: anonymizeResults(rows),
+              max_retries: options.chartMaxRetries ?? 3,
+              query_id: queryResponse.queryId
+            },
+            tenantId,
+            options.userId,
+            options.scopes,
+            signal,
+            sessionId
+          );
+          chart = {
+            vegaLiteSpec: chartResponse.chart ? {
+              ...chartResponse.chart,
+              data: { values: rows }
+            } : null,
+            specType: "vega-lite",
+            notes: chartResponse.notes
+          };
+        }
       }
       return {
         sql: queryResponse.sql,
@@ -1242,6 +1269,39 @@ function anonymizeResults(rows) {
   });
 }
 
+// src/routes/vizspec.ts
+async function generateVizSpec(client, input, options, signal) {
+  const tenantId = resolveTenantId5(client, options?.tenantId);
+  const sessionId = crypto.randomUUID();
+  const response = await client.post(
+    "/vizspec",
+    {
+      question: input.question,
+      sql: input.sql,
+      rationale: input.rationale,
+      fields: input.fields,
+      rows: input.rows,
+      max_retries: options?.maxRetries ?? input.max_retries ?? 3,
+      query_id: input.query_id
+    },
+    tenantId,
+    options?.userId,
+    options?.scopes,
+    signal,
+    sessionId
+  );
+  return response;
+}
+function resolveTenantId5(client, tenantId) {
+  const resolved = tenantId ?? client.getDefaultTenantId();
+  if (!resolved) {
+    throw new Error(
+      "tenantId is required. Provide it per request or via defaultTenantId option."
+    );
+  }
+  return resolved;
+}
+
 // src/index.ts
 var QueryPanelSdkAPI = class {
   client;
@@ -1307,6 +1367,15 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  // VizSpec generation
+  async generateVizSpec(input, options, signal) {
+    return await generateVizSpec(
+      this.client,
+      input,
+      options,
+      signal
+    );
+  }
   // Chart CRUD operations
   async createChart(body, options, signal) {
     return await createChart(this.client, body, options, signal);