@querypanel/node-sdk 1.2.8 → 1.2.10

package/dist/index.d.cts

@@ -288,6 +288,9 @@ declare const QueryErrorCode: {
     readonly SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED";
     readonly CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED";
     readonly CLARIFICATION_NEEDED: "CLARIFICATION_NEEDED";
+    readonly AI_PROVIDER_AUTH_FAILED: "AI_PROVIDER_AUTH_FAILED";
+    readonly AI_PROVIDER_RATE_LIMITED: "AI_PROVIDER_RATE_LIMITED";
+    readonly AI_PROVIDER_UNAVAILABLE: "AI_PROVIDER_UNAVAILABLE";
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
     readonly AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED";
     readonly VALIDATION_ERROR: "VALIDATION_ERROR";
@@ -299,7 +302,8 @@ type QueryErrorCode = (typeof QueryErrorCode)[keyof typeof QueryErrorCode];
 declare class QueryPipelineError extends Error {
     readonly code: QueryErrorCode;
     readonly details?: Record<string, unknown> | undefined;
-    constructor(message: string, code: QueryErrorCode, details?: Record<string, unknown> | undefined);
+    readonly status?: number | undefined;
+    constructor(message: string, code: QueryErrorCode, details?: Record<string, unknown> | undefined, status?: number | undefined);
     /**
      * Check if this is a moderation error
      */
@@ -320,6 +324,18 @@ declare class QueryPipelineError extends Error {
      * Check if this is a clarification needed error (v2 pipeline)
      */
     isClarificationNeeded(): boolean;
+    /**
+     * Check if this is a BYOK / provider credential error
+     */
+    isAiProviderAuthError(): boolean;
+    /**
+     * Check if this is a BYOK / provider rate-limit error
+     */
+    isAiProviderRateLimited(): boolean;
+    /**
+     * Check if this is any BYOK / provider error (auth, rate limit, or unavailable)
+     */
+    isAiProviderError(): boolean;
 }
 
 type ParamValue = string | number | boolean | string[] | number[];

package/dist/index.d.ts

@@ -288,6 +288,9 @@ declare const QueryErrorCode: {
     readonly SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED";
     readonly CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED";
     readonly CLARIFICATION_NEEDED: "CLARIFICATION_NEEDED";
+    readonly AI_PROVIDER_AUTH_FAILED: "AI_PROVIDER_AUTH_FAILED";
+    readonly AI_PROVIDER_RATE_LIMITED: "AI_PROVIDER_RATE_LIMITED";
+    readonly AI_PROVIDER_UNAVAILABLE: "AI_PROVIDER_UNAVAILABLE";
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
     readonly AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED";
     readonly VALIDATION_ERROR: "VALIDATION_ERROR";
@@ -299,7 +302,8 @@ type QueryErrorCode = (typeof QueryErrorCode)[keyof typeof QueryErrorCode];
 declare class QueryPipelineError extends Error {
     readonly code: QueryErrorCode;
     readonly details?: Record<string, unknown> | undefined;
-    constructor(message: string, code: QueryErrorCode, details?: Record<string, unknown> | undefined);
+    readonly status?: number | undefined;
+    constructor(message: string, code: QueryErrorCode, details?: Record<string, unknown> | undefined, status?: number | undefined);
     /**
      * Check if this is a moderation error
      */
@@ -320,6 +324,18 @@ declare class QueryPipelineError extends Error {
      * Check if this is a clarification needed error (v2 pipeline)
      */
     isClarificationNeeded(): boolean;
+    /**
+     * Check if this is a BYOK / provider credential error
+     */
+    isAiProviderAuthError(): boolean;
+    /**
+     * Check if this is a BYOK / provider rate-limit error
+     */
+    isAiProviderRateLimited(): boolean;
+    /**
+     * Check if this is any BYOK / provider error (auth, rate limit, or unavailable)
+     */
+    isAiProviderError(): boolean;
 }
 
 type ParamValue = string | number | boolean | string[] | number[];

package/dist/index.js

@@ -705,6 +705,118 @@ function sanitize2(value) {
 
 // src/core/client.ts
 import crypto from "crypto";
+
+// 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",
+  // Clarification errors (v2)
+  CLARIFICATION_NEEDED: "CLARIFICATION_NEEDED",
+  // Bring-your-own-key / provider errors
+  AI_PROVIDER_AUTH_FAILED: "AI_PROVIDER_AUTH_FAILED",
+  AI_PROVIDER_RATE_LIMITED: "AI_PROVIDER_RATE_LIMITED",
+  AI_PROVIDER_UNAVAILABLE: "AI_PROVIDER_UNAVAILABLE",
+  // General errors
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED",
+  VALIDATION_ERROR: "VALIDATION_ERROR"
+};
+function isQueryErrorCode(code) {
+  return typeof code === "string" && Object.values(QueryErrorCode).includes(code);
+}
+function isAiProviderErrorCode(code) {
+  return code === QueryErrorCode.AI_PROVIDER_AUTH_FAILED || code === QueryErrorCode.AI_PROVIDER_RATE_LIMITED || code === QueryErrorCode.AI_PROVIDER_UNAVAILABLE;
+}
+function isAiProviderPipelineError(error) {
+  if (error instanceof QueryPipelineError) {
+    return isAiProviderErrorCode(error.code);
+  }
+  if (error && typeof error === "object" && "code" in error) {
+    return isAiProviderErrorCode(error.code);
+  }
+  return false;
+}
+function throwIfGenerationErrorResponse(response) {
+  if (!response || typeof response !== "object") {
+    return;
+  }
+  const record = response;
+  if (typeof record.error !== "string") {
+    return;
+  }
+  if (isQueryErrorCode(record.code)) {
+    throw new QueryPipelineError(record.error, record.code);
+  }
+  throw new Error(record.error);
+}
+var QueryPipelineError = class extends Error {
+  constructor(message, code, details, status) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.status = status;
+    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();
+  }
+  /**
+   * Check if this is a clarification needed error (v2 pipeline)
+   */
+  isClarificationNeeded() {
+    return this.code === QueryErrorCode.CLARIFICATION_NEEDED;
+  }
+  /**
+   * Check if this is a BYOK / provider credential error
+   */
+  isAiProviderAuthError() {
+    return this.code === QueryErrorCode.AI_PROVIDER_AUTH_FAILED;
+  }
+  /**
+   * Check if this is a BYOK / provider rate-limit error
+   */
+  isAiProviderRateLimited() {
+    return this.code === QueryErrorCode.AI_PROVIDER_RATE_LIMITED;
+  }
+  /**
+   * Check if this is any BYOK / provider error (auth, rate limit, or unavailable)
+   */
+  isAiProviderError() {
+    return isAiProviderErrorCode(this.code);
+  }
+};
+
+// src/core/client.ts
 var ApiClient = class {
   constructor(baseUrl, privateKey, organizationId, options) {
     this.cryptoKey = null;
@@ -836,10 +948,18 @@ var ApiClient = class {
       json = void 0;
     }
     if (!response.ok) {
-      const error = new Error(
-        json?.error || response.statusText || "Request failed"
-      );
+      const message = json?.error || response.statusText || "Request failed";
+      if (isQueryErrorCode(json?.code)) {
+        throw new QueryPipelineError(
+          message,
+          json.code,
+          json?.details,
+          response.status
+        );
+      }
+      const error = new Error(message);
       error.status = response.status;
+      if (json?.code) error.code = json.code;
       if (json?.details) error.details = json.details;
       throw error;
     }
@@ -1168,65 +1288,6 @@ 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",
-  // Clarification errors (v2)
-  CLARIFICATION_NEEDED: "CLARIFICATION_NEEDED",
-  // 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();
-  }
-  /**
-   * Check if this is a clarification needed error (v2 pipeline)
-   */
-  isClarificationNeeded() {
-    return this.code === QueryErrorCode.CLARIFICATION_NEEDED;
-  }
-};
-
 // src/routes/charts.ts
 async function createChart(client, body, options, signal) {
   const tenantId = resolveTenantId(client, options?.tenantId);
@@ -1863,60 +1924,60 @@ async function ask(client, queryEngine, question, options, signal) {
         specType: chartType,
         notes: rows.length === 0 ? "Query returned no rows." : null
       };
-      if (rows.length > 0) {
-        if (chartType === "vizspec") {
-          const vizspecResponse = await client.post(
-            "/vizspec",
-            {
-              question,
-              sql,
-              rationale: queryResponse.data.rationale,
-              fields: execution.fields,
-              rows: anonymizeResults(rows),
-              max_retries: options.chartMaxRetries ?? 3,
-              query_id: queryResponse.data.queryId,
-              ...options.supportedChartTypes?.length ? {
-                supported_chart_types: options.supportedChartTypes
-              } : {}
-            },
-            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,
-              rationale: queryResponse.data.rationale,
-              fields: execution.fields,
-              rows: anonymizeResults(rows),
-              max_retries: options.chartMaxRetries ?? 3,
-              query_id: queryResponse.data.queryId
-            },
-            tenantId,
-            options.userId,
-            options.scopes,
-            signal,
-            sessionId
-          );
-          chart = {
-            vegaLiteSpec: chartResponse.chart ? {
-              ...chartResponse.chart,
-              data: { values: rows }
-            } : null,
-            specType: "vega-lite",
-            notes: chartResponse.notes
-          };
-        }
+      if (chartType === "vizspec") {
+        const vizspecResponse = await client.post(
+          "/vizspec",
+          {
+            question,
+            sql,
+            rationale: queryResponse.data.rationale,
+            fields: execution.fields,
+            rows: anonymizeResults(rows),
+            max_retries: options.chartMaxRetries ?? 3,
+            query_id: queryResponse.data.queryId,
+            ...options.supportedChartTypes?.length ? {
+              supported_chart_types: options.supportedChartTypes
+            } : {}
+          },
+          tenantId,
+          options.userId,
+          options.scopes,
+          signal,
+          sessionId
+        );
+        throwIfGenerationErrorResponse(vizspecResponse);
+        chart = {
+          vizSpec: vizspecResponse.spec,
+          specType: "vizspec",
+          notes: rows.length === 0 ? vizspecResponse.notes ?? "Query returned no rows." : vizspecResponse.notes
+        };
+      } else {
+        const chartResponse = await client.post(
+          "/chart",
+          {
+            question,
+            sql,
+            rationale: queryResponse.data.rationale,
+            fields: execution.fields,
+            rows: anonymizeResults(rows),
+            max_retries: options.chartMaxRetries ?? 3,
+            query_id: queryResponse.data.queryId
+          },
+          tenantId,
+          options.userId,
+          options.scopes,
+          signal,
+          sessionId
+        );
+        throwIfGenerationErrorResponse(chartResponse);
+        chart = {
+          vegaLiteSpec: chartResponse.chart ? {
+            ...chartResponse.chart,
+            data: { values: rows }
+          } : null,
+          specType: "vega-lite",
+          notes: rows.length === 0 ? chartResponse.notes ?? "Query returned no rows." : chartResponse.notes
+        };
       }
       return {
         sql,
@@ -1936,6 +1997,13 @@ async function ask(client, queryEngine, question, options, signal) {
         trace: queryResponse.data.trace
       };
     } catch (error) {
+      if (isAiProviderPipelineError(error)) {
+        if (error instanceof QueryPipelineError) {
+          throw error;
+        }
+        const providerError = error;
+        throw new QueryPipelineError(providerError.message, providerError.code);
+      }
       attempt++;
       if (attempt > maxRetry) {
         throw error;
@@ -2209,64 +2277,64 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     specType: chartType,
     notes: rows.length === 0 ? "Query returned no rows." : null
   };
-  if (rows.length > 0) {
-    const vizHints = hasVizMods ? buildVizHints(input.vizModifications) : {};
-    const vizHintsForChart = chartType === "vizspec" ? vizHints : stripVizSpecOnlyHints(vizHints);
-    if (chartType === "vizspec") {
-      const vizspecResponse = await client.post(
-        "/vizspec",
-        {
-          question: finalQuestion,
-          sql: finalSql,
-          rationale,
-          fields: execution.fields,
-          rows: anonymizeResults(rows),
-          max_retries: options?.chartMaxRetries ?? 3,
-          query_id: queryId,
-          // Include viz hints for the chart generator
-          ...hasVizMods ? { encoding_hints: vizHintsForChart } : {},
-          ...options?.supportedChartTypes?.length ? { supported_chart_types: options.supportedChartTypes } : {}
-        },
-        tenantId,
-        options?.userId,
-        options?.scopes,
-        signal,
-        sessionId
-      );
-      chart = {
-        vizSpec: vizspecResponse.spec,
-        specType: "vizspec",
-        notes: vizspecResponse.notes
-      };
-    } else {
-      const chartResponse = await client.post(
-        "/chart",
-        {
-          question: finalQuestion,
-          sql: finalSql,
-          rationale,
-          fields: execution.fields,
-          rows: anonymizeResults(rows),
-          max_retries: options?.chartMaxRetries ?? 3,
-          query_id: queryId,
-          // Include viz hints for the chart generator
-          ...hasVizMods ? { encoding_hints: vizHintsForChart } : {}
-        },
-        tenantId,
-        options?.userId,
-        options?.scopes,
-        signal,
-        sessionId
-      );
-      chart = {
-        vegaLiteSpec: chartResponse.chart ? {
-          ...chartResponse.chart,
-          data: { values: rows }
-        } : null,
-        specType: "vega-lite",
-        notes: chartResponse.notes
-      };
-    }
+  const vizHints = hasVizMods ? buildVizHints(input.vizModifications) : {};
+  const vizHintsForChart = chartType === "vizspec" ? vizHints : stripVizSpecOnlyHints(vizHints);
+  if (chartType === "vizspec") {
+    const vizspecResponse = await client.post(
+      "/vizspec",
+      {
+        question: finalQuestion,
+        sql: finalSql,
+        rationale,
+        fields: execution.fields,
+        rows: anonymizeResults(rows),
+        max_retries: options?.chartMaxRetries ?? 3,
+        query_id: queryId,
+        // Include viz hints for the chart generator
+        ...hasVizMods ? { encoding_hints: vizHintsForChart } : {},
+        ...options?.supportedChartTypes?.length ? { supported_chart_types: options.supportedChartTypes } : {}
+      },
+      tenantId,
+      options?.userId,
+      options?.scopes,
+      signal,
+      sessionId
+    );
+    throwIfGenerationErrorResponse(vizspecResponse);
+    chart = {
+      vizSpec: vizspecResponse.spec,
+      specType: "vizspec",
+      notes: rows.length === 0 ? vizspecResponse.notes ?? "Query returned no rows." : vizspecResponse.notes
+    };
+  } else {
+    const chartResponse = await client.post(
+      "/chart",
+      {
+        question: finalQuestion,
+        sql: finalSql,
+        rationale,
+        fields: execution.fields,
+        rows: anonymizeResults(rows),
+        max_retries: options?.chartMaxRetries ?? 3,
+        query_id: queryId,
+        // Include viz hints for the chart generator
+        ...hasVizMods ? { encoding_hints: vizHintsForChart } : {}
+      },
+      tenantId,
+      options?.userId,
+      options?.scopes,
+      signal,
+      sessionId
+    );
+    throwIfGenerationErrorResponse(chartResponse);
+    chart = {
+      vegaLiteSpec: chartResponse.chart ? {
+        ...chartResponse.chart,
+        data: { values: rows }
+      } : null,
+      specType: "vega-lite",
+      notes: rows.length === 0 ? chartResponse.notes ?? "Query returned no rows." : chartResponse.notes
+    };
   }
   return {
     sql: finalSql,