@querypanel/node-sdk 1.3.1 → 1.3.5

package/README.md

@@ -1,13 +1,28 @@
 # QueryPanel Node SDK
 
+`@querypanel/node-sdk` is the headless, server-side SDK for [QueryPanel](https://querypanel.io) embedded analytics. Use it in your Node.js (18+), Bun, or Deno backend to mint RS256 tenant JWTs, sync your Postgres, Amazon Redshift, ClickHouse, or BigQuery schema, and turn natural-language questions into SQL (natural-language-to-SQL / text-to-SQL) for multi-tenant SaaS products. The generated SQL runs against your database through a client function you provide, so database credentials and query results stay on your servers. For chart generation the SDK sends column names and value types, not row values (see `anonymizeResults`).
+
+- Docs: [querypanel.io/docs/node-sdk](https://querypanel.io/docs/node-sdk)
+- Tenant isolation: [querypanel.io/docs/tenant-isolation](https://querypanel.io/docs/tenant-isolation)
+- JWT setup: [querypanel.io/docs/jwt](https://querypanel.io/docs/jwt)
+
+## When to use the Node SDK vs the React SDK
+
+- **[React SDK](https://www.npmjs.com/package/@querypanel/react-sdk) (headful, start here for React apps):** `@querypanel/react-sdk` renders customer-facing dashboards with an AI assistant and per-tenant customization directly in your React tree, not an iframe ([why that matters](https://querypanel.io/blog/iframe-vs-native-react-embedded-analytics-2026)). It still needs this package on your server to mint the tenant JWT (`createJwt`).
+- **Node SDK (this package, headless):** use it alone when you build your own UI and want `ask()` to return SQL, rows, and a chart spec from your API routes.
+
+How it compares to other embedded analytics tools: [querypanel.io/compare](https://querypanel.io/compare).
+
+## Overview
+
 A TypeScript-first client for the QueryPanel Bun/Hono API. Its primary function is to **generate SQL from natural language**, but it also signs JWTs with your service private key, syncs database schemas, enforces tenant isolation, and wraps every public route under `src/routes/` (query, ingest, charts, active charts, and knowledge base).
 
 ## Installation
 
 ```bash
-bun add @querypanel/sdk
+bun add @querypanel/node-sdk
 # or
-npm install @querypanel/sdk
+npm install @querypanel/node-sdk
 ```
 
 > **Runtime:** Node.js 18+, Deno, or Bun. The SDK uses Web Crypto API for JWT signing and the native `fetch` API, making it compatible with modern JavaScript runtimes.
@@ -15,8 +30,9 @@ npm install @querypanel/sdk
 ## Quickstart
 
 ```ts
-import { QueryPanelSdkAPI } from "@querypanel/sdk";
+import { QueryPanelSdkAPI } from "@querypanel/node-sdk";
 import { Pool } from "pg";
+import { createClient } from "@clickhouse/client";
 
 const qp = new QueryPanelSdkAPI(
   process.env.QUERYPANEL_URL!,
@@ -42,21 +58,31 @@ const createPostgresClient = () => async (sql: string, params?: unknown[]) => {
   }
 };
 
-	// Attach PostgreSQL database using the SDK's PostgresAdapter
-	// The SDK will automatically handle tenant isolation when tenantFieldName is provided
-	qp.attachPostgres(
-  "pg_demo",  // a uniq identifier for QueryPanel
-  createPostgresClientFn(),
+// Attach PostgreSQL database using the SDK's PostgresAdapter
+// The SDK will automatically handle tenant isolation when tenantFieldName is provided
+qp.attachPostgres(
+  "pg_demo", // a unique identifier for QueryPanel
+  createPostgresClient(),
   {
-		database: "pg_demo", // database name
-		description: "PostgreSQL demo database", // some description that QueryPanel can use
-		tenantFieldName: "tenant_id", // SDK will automatically filter by tenant_id
-		enforceTenantIsolation: true, // Ensures all queries include tenant_id filter
-		allowedTables: ["orders"], // Only sync 'orders' table - 'users' will be excluded
-	});
+    database: "pg_demo", // database name
+    description: "PostgreSQL demo database", // some description that QueryPanel can use
+    tenantFieldName: "tenant_id", // SDK will automatically filter by tenant_id
+    enforceTenantIsolation: true, // Ensures all queries include tenant_id filter
+    allowedTables: ["orders"], // Only sync 'orders' table - 'users' will be excluded
+  },
+);
+
+// Amazon Redshift speaks the Postgres wire protocol, so a pg-based client works.
+// attachRedshift introspects via Redshift's svv_* views and generates Redshift SQL.
+qp.attachRedshift("warehouse", createPostgresClient(), {
+  database: "dev",
+  tenantFieldName: "tenant_id",
+});
+
+const clickhouse = createClient({ url: process.env.CLICKHOUSE_URL });
 
 qp.attachClickhouse(
-  "analytics", // uniq identifier for QueryPanel
+  "analytics", // unique identifier for QueryPanel
   (params) => clickhouse.query(params),
   {
     database: "analytics", // database name
@@ -143,7 +169,7 @@ const response = await qp.ask("Show order volume by week", {
 If your UI only supports a subset of chart kinds (for example no area or scatter), set **`supportedChartTypes`** on the SDK constructor or on each `ask` / `modifyChart` call (`line`, `bar`, `column`, `area`, `scatter`, `pie`).
 
 ```ts
-import { QueryPanelSdkAPI, ALL_VIZ_CHART_TYPES, type ChartType } from "@querypanel/sdk";
+import { QueryPanelSdkAPI, ALL_VIZ_CHART_TYPES, type ChartType } from "@querypanel/node-sdk";
 
 const allowed: ChartType[] = ["line", "bar", "column", "pie"];
 
@@ -512,7 +538,7 @@ The API accepts up to **100** UUIDs per request. Examples: `?ids=a&ids=b` or `?i
 The SDK is fully compatible with Deno (including Supabase Edge Functions) thanks to its use of Web Crypto API for JWT signing. No additional configuration needed:
 
 ```ts
-import { QueryPanelSdkAPI } from "https://esm.sh/@querypanel/sdk";
+import { QueryPanelSdkAPI } from "https://esm.sh/@querypanel/node-sdk";
 
 const qp = new QueryPanelSdkAPI(
   Deno.env.get("QUERYPANEL_URL")!,
@@ -526,10 +552,12 @@ const response = await qp.ask("Show top products", {
 });
 ```
 
+BigQuery is attached the same way with `attachBigQuery(name, clientFn, options)`. Any other engine can be plugged in with `attachDatabase(name, adapter)` and your own `DatabaseAdapter` implementation.
+
 ## Building locally
 
 ```bash
-cd node-sdk
+cd admin/packages/node-sdk
 bun install
 bun run build
 ```
@@ -571,4 +599,4 @@ Without `maxRetry`, execution errors throw immediately (default behavior).
 
 ## Need more?
 
-Open an issue or extend `node-sdk/src/index.ts`—every route lives in one file. Pull requests are welcome for additional adapters, richer param coercion, or convenience helpers around charts/annotations.
+Open an issue or extend the SDK: the public class is in `src/index.ts` and each API route has a module under `src/routes/`. Pull requests are welcome for additional adapters, richer param coercion, or convenience helpers around charts/annotations.

package/dist/index.cjs

@@ -548,7 +548,8 @@ var PostgresAdapter = class {
     this.clientFn = clientFn;
     this.databaseName = options.database ?? "postgres";
     this.defaultSchema = options.defaultSchema ?? "public";
-    this.kind = options.kind ?? "postgres";
+    this.dialect = options.dialect ?? "postgres";
+    this.kind = options.kind ?? this.dialect;
     if (options.allowedTables) {
       this.allowedTables = normalizeTableFilter3(
         options.allowedTables,
@@ -560,6 +561,7 @@ var PostgresAdapter = class {
   databaseName;
   defaultSchema;
   kind;
+  dialect;
   allowedTables;
   async execute(sql, params) {
     if (this.allowedTables) {
@@ -639,7 +641,7 @@ var PostgresAdapter = class {
     await this.clientFn(`EXPLAIN ${sql}`, paramArray);
   }
   getDialect() {
-    return "postgres";
+    return this.dialect;
   }
   /**
    * Simplified introspection: only collect table/column metadata for IngestRequest
@@ -648,12 +650,13 @@ var PostgresAdapter = class {
   async introspect(options) {
     const tablesToIntrospect = options?.tables ? normalizeTableFilter3(options.tables, this.defaultSchema) : this.allowedTables;
     const normalizedTables = tablesToIntrospect ?? [];
+    const isRedshift = this.dialect === "redshift";
     const tablesResult = await this.clientFn(
-      buildTablesQuery2(normalizedTables)
+      isRedshift ? buildRedshiftTablesQuery(normalizedTables) : buildTablesQuery2(normalizedTables)
     );
     const tableRows = tablesResult.rows;
     const columnsResult = await this.clientFn(
-      buildColumnsQuery2(normalizedTables)
+      isRedshift ? buildRedshiftColumnsQuery(normalizedTables) : buildColumnsQuery2(normalizedTables)
     );
     const columnRows = columnsResult.rows;
     const tablesByKey = /* @__PURE__ */ new Map();
@@ -767,10 +770,11 @@ function buildColumnsQuery2(tables) {
         AND kcu.column_name = cols.column_name
     ) AS is_primary_key
   FROM information_schema.columns cols
+  LEFT JOIN pg_catalog.pg_namespace n ON n.nspname = cols.table_schema
   LEFT JOIN pg_catalog.pg_class c
     ON c.relname = cols.table_name
+   AND c.relnamespace = n.oid
    AND c.relkind IN ('r', 'v', 'm')
-  LEFT JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
   LEFT JOIN pg_catalog.pg_attribute attr
     ON attr.attrelid = c.oid
    AND attr.attname = cols.column_name
@@ -780,6 +784,38 @@ function buildColumnsQuery2(tables) {
     ${filter}
   ORDER BY cols.table_schema, cols.table_name, cols.ordinal_position;`;
 }
+var REDSHIFT_EXCLUDED_SCHEMAS = "('pg_catalog', 'information_schema', 'pg_internal', 'pg_automv')";
+function buildRedshiftTablesQuery(tables) {
+  const filter = buildFilterClause(tables, "table_schema", "table_name");
+  return `SELECT
+    table_name,
+    table_schema AS schema_name,
+    table_type,
+    remarks AS comment
+  FROM svv_tables
+  WHERE table_catalog = current_database()
+    AND table_schema NOT IN ${REDSHIFT_EXCLUDED_SCHEMAS}
+    AND table_schema NOT LIKE 'pg_temp%'
+    ${filter}
+  ORDER BY table_schema, table_name;`;
+}
+function buildRedshiftColumnsQuery(tables) {
+  const filter = buildFilterClause(tables, "table_schema", "table_name");
+  return `SELECT
+    table_name,
+    table_schema,
+    column_name,
+    data_type,
+    NULL AS udt_name,
+    remarks AS description,
+    FALSE AS is_primary_key
+  FROM svv_columns
+  WHERE table_catalog = current_database()
+    AND table_schema NOT IN ${REDSHIFT_EXCLUDED_SCHEMAS}
+    AND table_schema NOT LIKE 'pg_temp%'
+    ${filter}
+  ORDER BY table_schema, table_name, ordinal_position;`;
+}
 function buildFilterClause(tables, schemaExpr, tableExpr) {
   if (!tables.length) return "";
   const clauses = tables.map(({ schema, table }) => {
@@ -2292,6 +2328,7 @@ function buildModifiedQuestion(originalQuestion, modifications, hasSessionContex
   }
   return `${originalQuestion} (${hints.join(", ")})`;
 }
+var REWRITE_DATEFILTER_ENDPOINT = "/v2/rewrite-datefilter";
 var START_PARAM_KEY_REGEX = /(^|_)(start|from)(_|$)/i;
 var END_PARAM_KEY_REGEX = /(^|_)(end|to)(_|$)/i;
 var ISO_DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z?$/;
@@ -2328,31 +2365,118 @@ function normalizeGeneratedParamKey(param, index) {
   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);
   return nameCandidate.replace(/[{}]/g, "").replace(/(.+):.*$/, "$1").replace(/^[:$]/, "").trim();
 }
-function applyDateRangeOverrides(dateRange, params, paramMetadata) {
+function collectParamKeys(params, paramMetadata) {
+  const keys = new Set(Object.keys(params));
+  for (let i = 0; i < paramMetadata.length; i++) {
+    const param = paramMetadata[i];
+    if (!param) continue;
+    keys.add(normalizeGeneratedParamKey(param, i));
+  }
+  return [...keys];
+}
+function placeholderKey(token) {
+  if (token.startsWith("$") || token.startsWith("@")) return token.slice(1);
+  return token.slice(1, -1).replace(/:.+$/, "").trim();
+}
+function isDateLike(value) {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value.trim());
+}
+function dateBoundKeysFromSql(sql) {
+  const start = /* @__PURE__ */ new Set();
+  const end = /* @__PURE__ */ new Set();
+  const comparison = /(>=|<=|>|<)\s*(\$\d+|\{[^}]+\}|@[A-Za-z_][\w]*)/g;
+  const between = /BETWEEN\s+(\$\d+|\{[^}]+\}|@[A-Za-z_][\w]*)\s+AND\s+(\$\d+|\{[^}]+\}|@[A-Za-z_][\w]*)/gi;
+  for (const match of sql.matchAll(comparison)) {
+    const key = placeholderKey(match[2] ?? "");
+    if (!key) continue;
+    if (match[1] === ">=" || match[1] === ">") start.add(key);
+    else end.add(key);
+  }
+  for (const match of sql.matchAll(between)) {
+    const startKey = placeholderKey(match[1] ?? "");
+    const endKey = placeholderKey(match[2] ?? "");
+    if (startKey) start.add(startKey);
+    if (endKey) end.add(endKey);
+  }
+  return { start, end };
+}
+function paramValueForKey(key, params, paramMetadata) {
+  if (key in params) return params[key];
+  for (let i = 0; i < paramMetadata.length; i++) {
+    const param = paramMetadata[i];
+    if (!param) continue;
+    if (normalizeGeneratedParamKey(param, i) === key) return param.value;
+  }
+  return void 0;
+}
+function dateBoundKeys(sql, params, paramMetadata, boundary) {
+  const fromSql = dateBoundKeysFromSql(sql)[boundary];
+  const keys = [];
+  for (const key of collectParamKeys(params, paramMetadata)) {
+    const named = keyLooksLikeDateBoundary(key, boundary);
+    if (!named && !fromSql.has(key)) continue;
+    if (!isDateLike(paramValueForKey(key, params, paramMetadata))) continue;
+    keys.push(key);
+  }
+  return keys;
+}
+function canSubstituteDateRangeParams(dateRange, sql, params, paramMetadata = []) {
+  if (!dateRange) return false;
+  const from = normalizeDateInput(dateRange.from);
+  const to = normalizeDateInput(dateRange.to);
+  if (!from && !to) return false;
+  if (from && dateBoundKeys(sql, params, paramMetadata, "start").length === 0) {
+    return false;
+  }
+  if (to && dateBoundKeys(sql, params, paramMetadata, "end").length === 0) {
+    return false;
+  }
+  return true;
+}
+function isDateRangeOnlySqlModification(modifications) {
+  if (!modifications?.dateRange) return false;
+  if (modifications.customSql) return false;
+  if (modifications.timeGranularity) return false;
+  if (typeof modifications.additionalInstructions === "string" && modifications.additionalInstructions.trim().length > 0) {
+    return false;
+  }
+  return true;
+}
+function applyDateRangeOverrides(dateRange, sql, params, paramMetadata) {
   if (!dateRange) return;
   const from = normalizeDateInput(dateRange.from);
   const to = normalizeDateInput(dateRange.to);
   if (!from && !to) return;
+  const startKeys = new Set(
+    from ? dateBoundKeys(sql, params, paramMetadata, "start") : []
+  );
+  const endKeys = new Set(
+    to ? dateBoundKeys(sql, params, paramMetadata, "end") : []
+  );
   for (const [key, value] of Object.entries(params)) {
-    if (from && keyLooksLikeDateBoundary(key, "start")) {
-      params[key] = formatDateOverride(from, "start", value);
+    if (startKeys.has(key)) {
+      params[key] = formatDateOverride(from ?? "", "start", value);
     }
-    if (to && keyLooksLikeDateBoundary(key, "end")) {
-      params[key] = formatDateOverride(to, "end", value);
+    if (endKeys.has(key)) {
+      params[key] = formatDateOverride(to ?? "", "end", value);
     }
   }
   for (let i = 0; i < paramMetadata.length; i++) {
     const param = paramMetadata[i];
     if (!param) continue;
     const key = normalizeGeneratedParamKey(param, i);
-    if (from && keyLooksLikeDateBoundary(key, "start")) {
-      param.value = formatDateOverride(from, "start", param.value);
+    if (startKeys.has(key)) {
+      param.value = formatDateOverride(from ?? "", "start", param.value);
     }
-    if (to && keyLooksLikeDateBoundary(key, "end")) {
-      param.value = formatDateOverride(to, "end", param.value);
+    if (endKeys.has(key)) {
+      param.value = formatDateOverride(to ?? "", "end", param.value);
     }
   }
 }
+function buildPreviousParams(params, paramMetadata) {
+  if (paramMetadata.length > 0) return paramMetadata;
+  return Object.entries(params).map(([name, value]) => ({ name, value }));
+}
 function buildVizHints(modifications) {
   const hints = {};
   if (modifications.kind) {
@@ -2403,6 +2527,9 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   const hasSqlMods = !!input.sqlModifications;
   const hasVizMods = !!input.vizModifications;
   const hasCustomSql = !!input.sqlModifications?.customSql;
+  const lightweight = options?.lightweight === true;
+  const dateOnly = lightweight && isDateRangeOnlySqlModification(input.sqlModifications);
+  const skipChartLlm = lightweight && !hasCustomSql && (dateOnly || hasVizMods && !hasSqlMods);
   resolveQueryPipeline(options?.pipeline);
   const queryEndpoint = "/v2/query";
   let currentSql = input.sql;
@@ -2456,6 +2583,20 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     paramMetadata = [];
     queryId = void 0;
     sqlChanged = true;
+  } else if (dateOnly && canSubstituteDateRangeParams(
+    input.sqlModifications?.dateRange,
+    finalSql,
+    finalParams,
+    paramMetadata
+  )) {
+    finalParams = { ...finalParams };
+    applyDateRangeOverrides(
+      input.sqlModifications?.dateRange,
+      finalSql,
+      finalParams,
+      paramMetadata
+    );
+    sqlChanged = false;
   } else if (hasSqlMods && !hasCustomSql) {
     const modifiedQuestion = buildModifiedQuestion(
       input.question,
@@ -2463,18 +2604,36 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       hasQuerypanelSessionContext
     );
     finalQuestion = modifiedQuestion;
-    const queryResponse = await client.post(
+    const sharedBody = {
+      session_id: querypanelSessionId,
+      previous_sql: currentSql,
+      ...tenantSettings ? { tenant_settings: tenantSettings } : {},
+      ...databaseName ? { database: databaseName } : {},
+      ...metadata?.dialect ? { dialect: metadata.dialect } : {},
+      debug: options?.debug ?? false
+    };
+    const [endpoint, body] = dateOnly ? [
+      REWRITE_DATEFILTER_ENDPOINT,
+      {
+        ...sharedBody,
+        question: input.question,
+        previous_params: buildPreviousParams(finalParams, paramMetadata),
+        date_range: {
+          from: normalizeDateInput(input.sqlModifications?.dateRange?.from),
+          to: normalizeDateInput(input.sqlModifications?.dateRange?.to)
+        }
+      }
+    ] : [
       queryEndpoint,
       {
+        ...sharedBody,
         question: modifiedQuestion,
-        session_id: querypanelSessionId,
-        previous_sql: currentSql,
-        ...options?.maxRetry ? { max_retry: options.maxRetry } : {},
-        ...tenantSettings ? { tenant_settings: tenantSettings } : {},
-        ...databaseName ? { database: databaseName } : {},
-        ...metadata?.dialect ? { dialect: metadata.dialect } : {},
-        debug: options?.debug ?? false
-      },
+        ...options?.maxRetry ? { max_retry: options.maxRetry } : {}
+      }
+    ];
+    const queryResponse = await client.post(
+      endpoint,
+      body,
       tenantId,
       options?.userId,
       options?.scopes,
@@ -2486,6 +2645,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     finalParams = queryEngine.mapGeneratedParams(paramMetadata);
     applyDateRangeOverrides(
       input.sqlModifications?.dateRange,
+      finalSql,
       finalParams,
       paramMetadata
     );
@@ -2506,7 +2666,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   };
   const vizHints = hasVizMods ? buildVizHints(input.vizModifications) : {};
   const vizHintsForChart = chartType === "vizspec" ? vizHints : stripVizSpecOnlyHints(vizHints);
-  if (chartType === "vizspec") {
+  if (!skipChartLlm && chartType === "vizspec") {
     const vizspecResponse = await client.post(
       "/vizspec",
       {
@@ -2533,7 +2693,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
       specType: "vizspec",
       notes: rows.length === 0 ? vizspecResponse.notes ?? "Query returned no rows." : vizspecResponse.notes
     };
-  } else {
+  } else if (!skipChartLlm) {
     const chartResponse = await client.post(
       "/chart",
       {
@@ -2789,7 +2949,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
     const adapter = new PostgresAdapter(clientFn, options);
     const metadata = {
       name,
-      dialect: "postgres",
+      dialect: adapter.getDialect(),
       description: options?.description,
       tags: options?.tags,
       tenantFieldName: options?.tenantFieldName,
@@ -2801,6 +2961,14 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
+  /**
+   * Attach an Amazon Redshift database. Redshift speaks the Postgres wire
+   * protocol, so `clientFn` can wrap a `pg` client; introspection uses
+   * Redshift's svv_* catalog views and SQL is generated for Redshift.
+   */
+  attachRedshift(name, clientFn, options) {
+    this.attachPostgres(name, clientFn, { ...options, dialect: "redshift" });
+  }
   attachBigQuery(name, clientFn, options) {
     const adapter = new BigQueryAdapter(clientFn, options);
     const metadata = {