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

package/dist/index.cjs

@@ -38,7 +38,9 @@ __export(index_exports, {
   QueryErrorCode: () => QueryErrorCode,
   QueryPanelSdkAPI: () => QueryPanelSdkAPI,
   QueryPipelineError: () => QueryPipelineError,
-  anonymizeResults: () => anonymizeResults
+  anonymizeResults: () => anonymizeResults,
+  mapGeneratedParams: () => mapGeneratedParams,
+  normalizeSqlParamsInput: () => normalizeSqlParamsInput
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -497,6 +499,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;
@@ -514,9 +547,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);
@@ -546,36 +580,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);
   }
@@ -749,6 +790,118 @@ function sanitize2(value) {
 
 // src/core/client.ts
 var import_node_crypto = __toESM(require("crypto"), 1);
+
+// 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;
@@ -880,10 +1033,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;
     }
@@ -1098,6 +1259,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() {
@@ -1168,18 +1368,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) {
@@ -1199,8 +1388,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(
@@ -1210,64 +1401,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;
   }
 };
 
@@ -1803,6 +1952,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) => ({
@@ -1928,6 +2078,7 @@ async function ask(client, queryEngine, question, options, signal) {
           signal,
           sessionId
         );
+        throwIfGenerationErrorResponse(vizspecResponse);
         chart = {
           vizSpec: vizspecResponse.spec,
           specType: "vizspec",
@@ -1951,6 +2102,7 @@ async function ask(client, queryEngine, question, options, signal) {
           signal,
           sessionId
         );
+        throwIfGenerationErrorResponse(chartResponse);
         chart = {
           vegaLiteSpec: chartResponse.chart ? {
             ...chartResponse.chart,
@@ -1978,6 +2130,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;
@@ -2274,6 +2433,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       signal,
       sessionId
     );
+    throwIfGenerationErrorResponse(vizspecResponse);
     chart = {
       vizSpec: vizspecResponse.spec,
       specType: "vizspec",
@@ -2299,6 +2459,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       signal,
       sessionId
     );
+    throwIfGenerationErrorResponse(chartResponse);
     chart = {
       vegaLiteSpec: chartResponse.chart ? {
         ...chartResponse.chart,
@@ -3468,6 +3629,8 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
   QueryErrorCode,
   QueryPanelSdkAPI,
   QueryPipelineError,
-  anonymizeResults
+  anonymizeResults,
+  mapGeneratedParams,
+  normalizeSqlParamsInput
 });
 //# sourceMappingURL=index.cjs.map