@querypanel/node-sdk 1.0.43 → 1.0.44

package/dist/index.d.cts

@@ -169,6 +169,47 @@ declare class PostgresAdapter implements DatabaseAdapter {
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
 }
 
+/**
+ * Error codes for the query pipeline
+ * These match the server-side error codes returned in API responses
+ */
+declare const QueryErrorCode: {
+    readonly MODERATION_FAILED: "MODERATION_FAILED";
+    readonly RELEVANCE_CHECK_FAILED: "RELEVANCE_CHECK_FAILED";
+    readonly SECURITY_CHECK_FAILED: "SECURITY_CHECK_FAILED";
+    readonly SQL_GENERATION_FAILED: "SQL_GENERATION_FAILED";
+    readonly SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED";
+    readonly CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+};
+type QueryErrorCode = (typeof QueryErrorCode)[keyof typeof QueryErrorCode];
+/**
+ * Error thrown when the query pipeline fails
+ */
+declare class QueryPipelineError extends Error {
+    readonly code: QueryErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: QueryErrorCode, details?: Record<string, unknown> | undefined);
+    /**
+     * Check if this is a moderation error
+     */
+    isModeration(): boolean;
+    /**
+     * Check if this is a relevance error (question not related to database)
+     */
+    isRelevanceError(): boolean;
+    /**
+     * Check if this is a security error (SQL injection, prompt injection, etc.)
+     */
+    isSecurityError(): boolean;
+    /**
+     * Check if this is any guardrail error (relevance or security)
+     */
+    isGuardrailError(): boolean;
+}
+
 type ParamValue = string | number | boolean | string[] | number[];
 type ParamRecord = Record<string, ParamValue>;
 
@@ -381,7 +422,7 @@ interface ContextDocument {
 interface ChartEnvelope {
     vegaLiteSpec?: Record<string, unknown> | null;
     vizSpec?: VizSpec | null;
-    specType: 'vega-lite' | 'vizspec';
+    specType: "vega-lite" | "vizspec";
     notes: string | null;
 }
 interface AskOptions {
@@ -393,7 +434,7 @@ interface AskOptions {
     previousSql?: string;
     maxRetry?: number;
     chartMaxRetries?: number;
-    chartType?: 'vega-lite' | 'vizspec';
+    chartType?: "vega-lite" | "vizspec";
 }
 interface AskResponse {
     sql: string;
@@ -977,4 +1018,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<void>;
 }
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type FieldRef, type FieldRefInput, 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 SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };
+export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type FieldRef, type FieldRefInput, 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, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };

package/dist/index.d.ts

@@ -169,6 +169,47 @@ declare class PostgresAdapter implements DatabaseAdapter {
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
 }
 
+/**
+ * Error codes for the query pipeline
+ * These match the server-side error codes returned in API responses
+ */
+declare const QueryErrorCode: {
+    readonly MODERATION_FAILED: "MODERATION_FAILED";
+    readonly RELEVANCE_CHECK_FAILED: "RELEVANCE_CHECK_FAILED";
+    readonly SECURITY_CHECK_FAILED: "SECURITY_CHECK_FAILED";
+    readonly SQL_GENERATION_FAILED: "SQL_GENERATION_FAILED";
+    readonly SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED";
+    readonly CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+};
+type QueryErrorCode = (typeof QueryErrorCode)[keyof typeof QueryErrorCode];
+/**
+ * Error thrown when the query pipeline fails
+ */
+declare class QueryPipelineError extends Error {
+    readonly code: QueryErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: QueryErrorCode, details?: Record<string, unknown> | undefined);
+    /**
+     * Check if this is a moderation error
+     */
+    isModeration(): boolean;
+    /**
+     * Check if this is a relevance error (question not related to database)
+     */
+    isRelevanceError(): boolean;
+    /**
+     * Check if this is a security error (SQL injection, prompt injection, etc.)
+     */
+    isSecurityError(): boolean;
+    /**
+     * Check if this is any guardrail error (relevance or security)
+     */
+    isGuardrailError(): boolean;
+}
+
 type ParamValue = string | number | boolean | string[] | number[];
 type ParamRecord = Record<string, ParamValue>;
 
@@ -381,7 +422,7 @@ interface ContextDocument {
 interface ChartEnvelope {
     vegaLiteSpec?: Record<string, unknown> | null;
     vizSpec?: VizSpec | null;
-    specType: 'vega-lite' | 'vizspec';
+    specType: "vega-lite" | "vizspec";
     notes: string | null;
 }
 interface AskOptions {
@@ -393,7 +434,7 @@ interface AskOptions {
     previousSql?: string;
     maxRetry?: number;
     chartMaxRetries?: number;
-    chartType?: 'vega-lite' | 'vizspec';
+    chartType?: "vega-lite" | "vizspec";
 }
 interface AskResponse {
     sql: string;
@@ -977,4 +1018,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<void>;
 }
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type FieldRef, type FieldRefInput, 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 SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };
+export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type FieldRef, type FieldRefInput, 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, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };

package/dist/index.js

@@ -842,6 +842,57 @@ var QueryEngine = class {
   }
 };
 
+// src/errors.ts
+var QueryErrorCode = {
+  // Moderation errors
+  MODERATION_FAILED: "MODERATION_FAILED",
+  // Guardrail errors
+  RELEVANCE_CHECK_FAILED: "RELEVANCE_CHECK_FAILED",
+  SECURITY_CHECK_FAILED: "SECURITY_CHECK_FAILED",
+  // SQL generation errors
+  SQL_GENERATION_FAILED: "SQL_GENERATION_FAILED",
+  // SQL validation errors
+  SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED",
+  // Context retrieval errors
+  CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED",
+  // General errors
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED",
+  VALIDATION_ERROR: "VALIDATION_ERROR"
+};
+var QueryPipelineError = class extends Error {
+  constructor(message, code, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "QueryPipelineError";
+  }
+  /**
+   * Check if this is a moderation error
+   */
+  isModeration() {
+    return this.code === QueryErrorCode.MODERATION_FAILED;
+  }
+  /**
+   * Check if this is a relevance error (question not related to database)
+   */
+  isRelevanceError() {
+    return this.code === QueryErrorCode.RELEVANCE_CHECK_FAILED;
+  }
+  /**
+   * Check if this is a security error (SQL injection, prompt injection, etc.)
+   */
+  isSecurityError() {
+    return this.code === QueryErrorCode.SECURITY_CHECK_FAILED;
+  }
+  /**
+   * Check if this is any guardrail error (relevance or security)
+   */
+  isGuardrailError() {
+    return this.isRelevanceError() || this.isSecurityError();
+  }
+};
+
 // src/routes/charts.ts
 async function createChart(client, body, options, signal) {
   const tenantId = resolveTenantId(client, options?.tenantId);
@@ -878,15 +929,10 @@ async function listCharts(client, queryEngine, options, signal) {
   );
   if (options?.includeData) {
     response.data = await Promise.all(
-      response.data.map(async (chart) => ({
-        ...chart,
-        vega_lite_spec: {
-          ...chart.vega_lite_spec,
-          data: {
-            values: await executeChartQuery(queryEngine, chart, tenantId)
-          }
-        }
-      }))
+      response.data.map(async (chart) => {
+        const rows = await executeChartQuery(queryEngine, chart, tenantId);
+        return hydrateChartWithData(chart, rows);
+      })
     );
   }
   return response;
@@ -900,15 +946,8 @@ async function getChart(client, queryEngine, id, options, signal) {
     options?.scopes,
     signal
   );
-  return {
-    ...chart,
-    vega_lite_spec: {
-      ...chart.vega_lite_spec,
-      data: {
-        values: await executeChartQuery(queryEngine, chart, tenantId)
-      }
-    }
-  };
+  const rows = await executeChartQuery(queryEngine, chart, tenantId);
+  return hydrateChartWithData(chart, rows);
 }
 async function updateChart(client, id, body, options, signal) {
   const tenantId = resolveTenantId(client, options?.tenantId);
@@ -959,6 +998,31 @@ async function executeChartQuery(queryEngine, chart, tenantId) {
     return [];
   }
 }
+function hydrateChartWithData(chart, rows) {
+  const spec = chart.vega_lite_spec;
+  if (chart.spec_type === "vizspec") {
+    const existingData = spec.data ?? {};
+    return {
+      ...chart,
+      vega_lite_spec: {
+        ...spec,
+        data: {
+          ...existingData,
+          values: rows
+        }
+      }
+    };
+  }
+  return {
+    ...chart,
+    vega_lite_spec: {
+      ...spec,
+      data: {
+        values: rows
+      }
+    }
+  };
+}
 
 // src/routes/active-charts.ts
 async function createActiveChart(client, body, options, signal) {
@@ -1166,6 +1230,13 @@ async function ask(client, queryEngine, question, options, signal) {
       signal,
       sessionId
     );
+    if (!queryResponse.success) {
+      throw new QueryPipelineError(
+        queryResponse.error || "Query generation failed",
+        queryResponse.code || "INTERNAL_ERROR",
+        queryResponse.details
+      );
+    }
     const dbName = queryResponse.database ?? options.database ?? queryEngine.getDefaultDatabase();
     if (!dbName) {
       throw new Error(
@@ -2009,7 +2080,9 @@ var QueryPanelSdkAPI = class {
 export {
   ClickHouseAdapter,
   PostgresAdapter,
+  QueryErrorCode,
   QueryPanelSdkAPI,
+  QueryPipelineError,
   anonymizeResults
 };
 //# sourceMappingURL=index.js.map