@querypanel/node-sdk 1.2.9 → 1.3.0-beta.0

package/dist/index.d.cts

@@ -220,11 +220,8 @@ declare class PostgresAdapter implements DatabaseAdapter {
     execute(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<DatabaseExecutionResult>;
     private validateQueryTables;
     /**
-     * Convert params to positional array for PostgreSQL.
-     * PostgreSQL expects $1, $2, $3 in SQL and an array of values [val1, val2, val3].
-     * When the record has numeric keys ("1", "2", "3") — e.g. from mapGeneratedParams —
-     * use only those in order so placeholder order matches SQL. Otherwise fall back to
-     * named keys in alphabetical order for backward compatibility.
+     * Convert params to positional array for PostgreSQL ($1, $2, …).
+     * Values must align with v2 generation order via numeric keys from mapGeneratedParams.
      */
     private convertNamedToPositionalParams;
     validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
@@ -288,6 +285,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 +299,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 +321,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[];
@@ -717,7 +730,7 @@ interface AskOptions {
      */
     pipeline?: "v1" | "v2";
     /**
-     * Optional OpenAI model id for v2 SQL generation. Omit to use server default.
+     * Optional model id for v2 SQL generation (e.g. OpenAI or `gemini-*` when the API uses Gemini). Omit for server default.
      */
     model?: string;
     /**
@@ -1122,6 +1135,16 @@ declare class CallbackApiClient implements IQueryPanelApi {
     delete<T = void>(path: string, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
 }
 
+/**
+ * Maps v2-style param metadata (array order = $1, $2, $3 in SQL) to a ParamRecord.
+ * Numeric keys preserve placeholder order for PostgreSQL; named keys support tenant lookups.
+ */
+declare function mapGeneratedParams(params: Array<Record<string, unknown>>): ParamRecord;
+/**
+ * Normalizes run-sql / dashboard request params into a ParamRecord.
+ */
+declare function normalizeSqlParamsInput(params: unknown[] | Record<string, unknown> | null | undefined): ParamRecord;
+
 /** Options when constructing the SDK with HTTP (default) or with a custom API implementation. */
 interface QueryPanelSdkAPIOptions {
     defaultTenantId?: string;
@@ -1934,4 +1957,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<SdkDashboard[]>;
 }
 
-export { ALL_VIZ_CHART_TYPES, type ActiveChartBulkGetResponse, type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryClientFn, type BigQueryQueryRequest, type BigQueryQueryResult, CallbackApiClient, type ChartBulkGetResponse, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListAllOptions, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DashboardCreateInput, type DashboardForkInput, type DashboardForkUpdateInput, type DashboardListOptions, type DashboardUpdateInput, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IQueryPanelApi, type IngestResponse, type IntentResult, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, type QueryPanelSdkAPIOptions, QueryPipelineError, type RequestHandler, type RequestHandlerOptions, type RequestHandlerResult, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkDashboard, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults };
+export { ALL_VIZ_CHART_TYPES, type ActiveChartBulkGetResponse, type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryClientFn, type BigQueryQueryRequest, type BigQueryQueryResult, CallbackApiClient, type ChartBulkGetResponse, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListAllOptions, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DashboardCreateInput, type DashboardForkInput, type DashboardForkUpdateInput, type DashboardListOptions, type DashboardUpdateInput, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IQueryPanelApi, type IngestResponse, type IntentResult, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, type QueryPanelSdkAPIOptions, QueryPipelineError, type RequestHandler, type RequestHandlerOptions, type RequestHandlerResult, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkDashboard, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults, mapGeneratedParams, normalizeSqlParamsInput };

package/dist/index.d.ts

@@ -220,11 +220,8 @@ declare class PostgresAdapter implements DatabaseAdapter {
     execute(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<DatabaseExecutionResult>;
     private validateQueryTables;
     /**
-     * Convert params to positional array for PostgreSQL.
-     * PostgreSQL expects $1, $2, $3 in SQL and an array of values [val1, val2, val3].
-     * When the record has numeric keys ("1", "2", "3") — e.g. from mapGeneratedParams —
-     * use only those in order so placeholder order matches SQL. Otherwise fall back to
-     * named keys in alphabetical order for backward compatibility.
+     * Convert params to positional array for PostgreSQL ($1, $2, …).
+     * Values must align with v2 generation order via numeric keys from mapGeneratedParams.
      */
     private convertNamedToPositionalParams;
     validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
@@ -288,6 +285,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 +299,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 +321,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[];
@@ -717,7 +730,7 @@ interface AskOptions {
      */
     pipeline?: "v1" | "v2";
     /**
-     * Optional OpenAI model id for v2 SQL generation. Omit to use server default.
+     * Optional model id for v2 SQL generation (e.g. OpenAI or `gemini-*` when the API uses Gemini). Omit for server default.
      */
     model?: string;
     /**
@@ -1122,6 +1135,16 @@ declare class CallbackApiClient implements IQueryPanelApi {
     delete<T = void>(path: string, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
 }
 
+/**
+ * Maps v2-style param metadata (array order = $1, $2, $3 in SQL) to a ParamRecord.
+ * Numeric keys preserve placeholder order for PostgreSQL; named keys support tenant lookups.
+ */
+declare function mapGeneratedParams(params: Array<Record<string, unknown>>): ParamRecord;
+/**
+ * Normalizes run-sql / dashboard request params into a ParamRecord.
+ */
+declare function normalizeSqlParamsInput(params: unknown[] | Record<string, unknown> | null | undefined): ParamRecord;
+
 /** Options when constructing the SDK with HTTP (default) or with a custom API implementation. */
 interface QueryPanelSdkAPIOptions {
     defaultTenantId?: string;
@@ -1934,4 +1957,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<SdkDashboard[]>;
 }
 
-export { ALL_VIZ_CHART_TYPES, type ActiveChartBulkGetResponse, type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryClientFn, type BigQueryQueryRequest, type BigQueryQueryResult, CallbackApiClient, type ChartBulkGetResponse, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListAllOptions, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DashboardCreateInput, type DashboardForkInput, type DashboardForkUpdateInput, type DashboardListOptions, type DashboardUpdateInput, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IQueryPanelApi, type IngestResponse, type IntentResult, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, type QueryPanelSdkAPIOptions, QueryPipelineError, type RequestHandler, type RequestHandlerOptions, type RequestHandlerResult, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkDashboard, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults };
+export { ALL_VIZ_CHART_TYPES, type ActiveChartBulkGetResponse, type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryClientFn, type BigQueryQueryRequest, type BigQueryQueryResult, CallbackApiClient, type ChartBulkGetResponse, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListAllOptions, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DashboardCreateInput, type DashboardForkInput, type DashboardForkUpdateInput, type DashboardListOptions, type DashboardUpdateInput, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IQueryPanelApi, type IngestResponse, type IntentResult, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as PaginationQuery, type ParamRecord, type ParamValue, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, type QueryPanelSdkAPIOptions, QueryPipelineError, type RequestHandler, type RequestHandlerOptions, type RequestHandlerResult, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkDashboard, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults, mapGeneratedParams, normalizeSqlParamsInput };

package/dist/index.js

@@ -453,6 +453,37 @@ function toNumber(value) {
 }
 
 // src/adapters/postgres.ts
+function maxPostgresPlaceholderIndex(sql) {
+  let max = 0;
+  for (const match of sql.matchAll(/\$(\d+)\b/g)) {
+    const index = Number.parseInt(match[1], 10);
+    if (Number.isFinite(index) && index > max) {
+      max = index;
+    }
+  }
+  return max;
+}
+function filterParamsForPostgresSql(sql, params) {
+  if (!params || Object.keys(params).length === 0) {
+    return void 0;
+  }
+  const placeholderCount = maxPostgresPlaceholderIndex(sql);
+  if (placeholderCount === 0) {
+    return void 0;
+  }
+  const hasNumericKeys = Object.keys(params).some((key) => /^\d+$/.test(key));
+  if (hasNumericKeys) {
+    const filtered = {};
+    for (let index = 1; index <= placeholderCount; index += 1) {
+      const key = String(index);
+      if (key in params) {
+        filtered[key] = params[key];
+      }
+    }
+    return Object.keys(filtered).length > 0 ? filtered : void 0;
+  }
+  return params;
+}
 var PostgresAdapter = class {
   constructor(clientFn, options = {}) {
     this.clientFn = clientFn;
@@ -470,9 +501,10 @@ var PostgresAdapter = class {
     if (this.allowedTables) {
       this.validateQueryTables(sql);
     }
+    const boundParams = filterParamsForPostgresSql(sql, params);
     let paramArray;
-    if (params) {
-      paramArray = this.convertNamedToPositionalParams(params);
+    if (boundParams) {
+      paramArray = this.convertNamedToPositionalParams(sql, boundParams);
     }
     const result = await this.clientFn(sql, paramArray);
     const fields = result.fields.map((f) => f.name);
@@ -502,36 +534,43 @@ var PostgresAdapter = class {
     }
   }
   /**
-   * Convert params to positional array for PostgreSQL.
-   * PostgreSQL expects $1, $2, $3 in SQL and an array of values [val1, val2, val3].
-   * When the record has numeric keys ("1", "2", "3") — e.g. from mapGeneratedParams —
-   * use only those in order so placeholder order matches SQL. Otherwise fall back to
-   * named keys in alphabetical order for backward compatibility.
+   * Convert params to positional array for PostgreSQL ($1, $2, …).
+   * Values must align with v2 generation order via numeric keys from mapGeneratedParams.
    */
-  convertNamedToPositionalParams(params) {
-    const numericKeys = Object.keys(params).filter((k) => /^\d+$/.test(k)).map((k) => Number.parseInt(k, 10)).sort((a, b) => a - b);
-    if (numericKeys.length > 0) {
-      const positionalParams = [];
-      for (const key of numericKeys) {
-        let val = params[String(key)];
-        if (typeof val === "string") {
-          const match = val.match(/^<([a-zA-Z0-9_]+)>$/);
-          const namedKey = match?.[1];
-          if (namedKey && namedKey in params) {
-            val = params[namedKey];
-          }
+  convertNamedToPositionalParams(sql, params) {
+    const placeholderCount = maxPostgresPlaceholderIndex(sql);
+    if (placeholderCount === 0) {
+      return [];
+    }
+    const positionalParams = [];
+    for (let index = 1; index <= placeholderCount; index += 1) {
+      const key = String(index);
+      let val = params[key];
+      if (val === void 0 && placeholderCount === 1) {
+        const namedKeys = Object.keys(params).filter((k) => !/^\d+$/.test(k));
+        if (namedKeys.length === 1) {
+          val = params[namedKeys[0]];
+        }
+      }
+      if (val === void 0) {
+        throw new Error(`Missing value for PostgreSQL parameter $${index}`);
+      }
+      if (typeof val === "string") {
+        const match = val.match(/^<([a-zA-Z0-9_]+)>$/);
+        const namedKey = match?.[1];
+        if (namedKey && namedKey in params) {
+          val = params[namedKey];
         }
-        positionalParams.push(val);
       }
-      return positionalParams;
+      positionalParams.push(val);
     }
-    const namedKeys = Object.keys(params).filter((k) => !/^\d+$/.test(k)).sort();
-    return namedKeys.map((key) => params[key]);
+    return positionalParams;
   }
   async validate(sql, params) {
+    const boundParams = filterParamsForPostgresSql(sql, params);
     let paramArray;
-    if (params) {
-      paramArray = this.convertNamedToPositionalParams(params);
+    if (boundParams) {
+      paramArray = this.convertNamedToPositionalParams(sql, boundParams);
     }
     await this.clientFn(`EXPLAIN ${sql}`, paramArray);
   }
@@ -705,6 +744,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 +987,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;
     }
@@ -1054,6 +1213,45 @@ var CallbackApiClient = class {
   }
 };
 
+// src/core/map-generated-params.ts
+function mapGeneratedParams(params) {
+  const record = {};
+  params.forEach((param, index) => {
+    const value = param.value;
+    if (value === void 0) {
+      return;
+    }
+    record[String(index + 1)] = value;
+    const nameCandidate = typeof param.name === "string" && param.name.trim() || typeof param.placeholder === "string" && param.placeholder.trim() || typeof param.position === "number" && String(param.position) || String(index + 1);
+    const key = nameCandidate.replace(/[{}:$]/g, "").trim();
+    record[key] = value;
+  });
+  return record;
+}
+function normalizeSqlParamsInput(params) {
+  if (params == null) {
+    return {};
+  }
+  if (Array.isArray(params)) {
+    if (params.length === 0) {
+      return {};
+    }
+    const first = params[0];
+    if (first && typeof first === "object" && "value" in first) {
+      return mapGeneratedParams(params);
+    }
+    const positional = {};
+    params.forEach((value, index) => {
+      positional[String(index + 1)] = value;
+    });
+    return positional;
+  }
+  if (typeof params === "object") {
+    return params;
+  }
+  return {};
+}
+
 // src/core/query-engine.ts
 var QueryEngine = class {
   constructor() {
@@ -1124,18 +1322,7 @@ var QueryEngine = class {
    * - Named keys remain for tenant isolation / other lookups.
    */
   mapGeneratedParams(params) {
-    const record = {};
-    params.forEach((param, index) => {
-      const value = param.value;
-      if (value === void 0) {
-        return;
-      }
-      record[String(index + 1)] = value;
-      const nameCandidate = typeof param.name === "string" && param.name.trim() || typeof param.placeholder === "string" && param.placeholder.trim() || typeof param.position === "number" && String(param.position) || String(index + 1);
-      const key = nameCandidate.replace(/[{}:$]/g, "").trim();
-      record[key] = value;
-    });
-    return record;
+    return mapGeneratedParams(params);
   }
   ensureTenantIsolation(sql, params, metadata, tenantId) {
     if (!metadata.tenantFieldName || metadata.enforceTenantIsolation === false) {
@@ -1155,8 +1342,10 @@ var QueryEngine = class {
       params[tenantField] = tenantId;
       tenantPredicate = `${tenantField} = @${tenantField}`;
     } else {
-      const escapedId = tenantId.replace(/'/g, "''");
-      tenantPredicate = `${tenantField} = '${escapedId}'`;
+      const paramIndex = this.nextPostgresPlaceholderIndex(sql, params);
+      params[String(paramIndex)] = tenantId;
+      params[tenantField] = tenantId;
+      tenantPredicate = `${tenantField} = $${paramIndex}`;
     }
     if (/\bwhere\b/i.test(sql)) {
       return sql.replace(
@@ -1166,64 +1355,22 @@ var QueryEngine = class {
     }
     return `${sql} WHERE ${tenantPredicate}`;
   }
-};
-
-// 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;
+  nextPostgresPlaceholderIndex(sql, params) {
+    let max = 0;
+    for (const match of sql.matchAll(/\$(\d+)\b/g)) {
+      const index = Number.parseInt(match[1], 10);
+      if (Number.isFinite(index) && index > max) {
+        max = index;
+      }
+    }
+    if (max > 0) {
+      return max + 1;
+    }
+    const numericKeys = Object.keys(params).filter((key) => /^\d+$/.test(key)).map((key) => Number.parseInt(key, 10)).filter((index) => Number.isFinite(index));
+    if (numericKeys.length > 0) {
+      return Math.max(...numericKeys) + 1;
+    }
+    return 1;
   }
 };
 
@@ -1759,6 +1906,7 @@ function resolveTenantId4(client, tenantId) {
 function buildSchemaRequest(databaseName, adapter, introspection, metadata) {
   const dialect = adapter.getDialect();
   const tables = introspection.tables.map((table) => ({
+    schema_name: table.schema,
     table_name: table.name,
     description: table.comment ?? `Table ${table.name}`,
     columns: table.columns.map((column) => ({
@@ -1884,6 +2032,7 @@ async function ask(client, queryEngine, question, options, signal) {
           signal,
           sessionId
         );
+        throwIfGenerationErrorResponse(vizspecResponse);
         chart = {
           vizSpec: vizspecResponse.spec,
           specType: "vizspec",
@@ -1907,6 +2056,7 @@ async function ask(client, queryEngine, question, options, signal) {
           signal,
           sessionId
         );
+        throwIfGenerationErrorResponse(chartResponse);
         chart = {
           vegaLiteSpec: chartResponse.chart ? {
             ...chartResponse.chart,
@@ -1934,6 +2084,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;
@@ -2230,6 +2387,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       signal,
       sessionId
     );
+    throwIfGenerationErrorResponse(vizspecResponse);
     chart = {
       vizSpec: vizspecResponse.spec,
       specType: "vizspec",
@@ -2255,6 +2413,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       signal,
       sessionId
     );
+    throwIfGenerationErrorResponse(chartResponse);
     chart = {
       vegaLiteSpec: chartResponse.chart ? {
         ...chartResponse.chart,
@@ -3423,6 +3582,8 @@ export {
   QueryErrorCode,
   QueryPanelSdkAPI,
   QueryPipelineError,
-  anonymizeResults
+  anonymizeResults,
+  mapGeneratedParams,
+  normalizeSqlParamsInput
 };
 //# sourceMappingURL=index.js.map