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

package/README.md

@@ -56,7 +56,7 @@ const createPostgresClient = () => async (sql: string, params?: unknown[]) => {
 	});
 
 qp.attachClickhouse(
-  "clicks", // uniq identifier for QueryPanel
+  "analytics", // uniq identifier for QueryPanel
   (params) => clickhouse.query(params),
   {
     database: "analytics", // database name
@@ -65,10 +65,6 @@ qp.attachClickhouse(
   },
 );
 
-// Syncs schema. Skips embedding if schema hasn't changed (no drift).
-// Pass { forceReindex: true } to force re-embedding.
-await qp.syncSchema("analytics", { tenantId: "tenant_123" });
-
 const response = await qp.ask("Top countries by revenue", {
   tenantId: "tenant_123",
   database: "analytics",
@@ -80,22 +76,71 @@ console.table(response.rows);
 console.log(response.chart.vegaLiteSpec);
 ```
 
-### Custom system instructions (v2 pipeline)
+Run `syncSchema` separately — see [Schema sync](#schema-sync).
+
+### Schema sync
 
-If you need to enforce tenant-specific policies that should apply to every query (for example, data retention windows), you can inject additional **system prompt** instructions into the v2 pipeline:
+`syncSchema` introspects an attached database and uploads table/column metadata so natural-language questions can generate accurate SQL. Treat it like a **migration**, not part of `ask()`:
+
+- Run it once when you first connect a database.
+- Run it again when tables or columns change.
+- Do not call it on every request — put it in a setup/deploy script instead.
 
 ```ts
-const response = await qp.ask("Revenue by product", {
+// scripts/sync-schema.ts — run once at setup, or after schema changes
+await qp.syncSchema("pg_demo", { tenantId: "tenant_123" });
+await qp.syncSchema("analytics", { tenantId: "tenant_123" });
+
+// Unchanged schemas skip re-embedding. Force a rebuild only when needed:
+await qp.syncSchema("analytics", {
   tenantId: "tenant_123",
+  forceReindex: true,
+});
+```
+
+Optionally limit the payload with `tables: ["orders"]`.
+
+### Custom system prompt (`systemPrompt`)
+
+Pass `systemPrompt` on `ask()` to inject extra instructions for SQL generation. Use it when a **client** needs policies QueryPanel does not know about — retention windows, a max date range, excluded event types, and similar product rules. Look up that client’s config in your backend and pass it on every question.
+
+The text is appended to the SQL generator (and reflection) prompts. When it conflicts with generic defaults (for example the usual 30-day trend window), the caller instructions win. It does **not** replace tenant isolation — still attach with `tenantFieldName` and pass `tenantId`. Max length is 8,000 characters. There is no constructor default; `modifyChart()` does not take `systemPrompt`.
+
+```ts
+function systemPromptForClient(client: { retentionDays: number }) {
+  return [
+    `Data retention: only query rows from the last ${client.retentionDays} days.`,
+    `Never return a date range longer than ${client.retentionDays} days, even if the user asks for all time or a wider window.`,
+    "Clamp any requested range to that maximum and bind start/end dates as parameters.",
+  ].join(" ");
+}
+
+const client = await loadClient(req); // your auth + billing/retention settings
+
+const response = await qp.ask("Revenue by product over all time", {
+  tenantId: client.tenantId,
+  database: "analytics",
+  systemPrompt: systemPromptForClient(client),
+});
+```
+
+Other per-client instructions:
+
+```ts
+const response = await qp.ask("Show order volume by week", {
+  tenantId: client.tenantId,
   database: "analytics",
-  pipeline: "v2",
-  systemPrompt: "Retention policy: only query data from the last 30 days.",
+  systemPrompt: [
+    "Default time range: last 90 days unless the user names a shorter window.",
+    "Maximum lookback: 90 days from today.",
+    "Exclude orders with status refunded or cancelled.",
+  ].join(" "),
 });
 ```
 
-### Restricting VizSpec chart types
+### Restricting chart types
 
-If your UI only supports a subset of VizSpec chart kinds (for example no area or scatter), set **`supportedChartTypes`** on the SDK constructor or on each `ask` / `modifyChart` call. The API’s `/vizspec` step then steers generation toward allowed types only (`line`, `bar`, `column`, `area`, `scatter`, `pie`). This applies whenever you use **`chartType: "vizspec"`** (including the default v2 flow after SQL runs).
+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";
@@ -110,8 +155,6 @@ const qp = new QueryPanelSdkAPI(url, privateKey, workspaceId, {
 await qp.ask("Revenue by month", {
   tenantId: "t1",
   database: "analytics",
-  chartType: "vizspec",
-  pipeline: "v2",
   supportedChartTypes: allowed,
 });
 ```

package/dist/index.cjs

@@ -40,7 +40,8 @@ __export(index_exports, {
   QueryPipelineError: () => QueryPipelineError,
   anonymizeResults: () => anonymizeResults,
   mapGeneratedParams: () => mapGeneratedParams,
-  normalizeSqlParamsInput: () => normalizeSqlParamsInput
+  normalizeSqlParamsInput: () => normalizeSqlParamsInput,
+  resolveQueryPipeline: () => resolveQueryPipeline
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1967,11 +1968,17 @@ function buildSchemaRequest(databaseName, adapter, introspection, metadata) {
     dialect,
     tables
   };
-  if (metadata?.tenantFieldName && metadata?.tenantFieldType && metadata?.enforceTenantIsolation !== void 0) {
+  if (metadata?.enforceTenantIsolation === false) {
+    request.tenant_settings = {
+      tenantFieldName: metadata.tenantFieldName ?? "",
+      tenantFieldType: metadata.tenantFieldType ?? "String",
+      enforceTenantIsolation: false
+    };
+  } else if (metadata?.tenantFieldName && metadata?.tenantFieldType) {
     request.tenant_settings = {
       tenantFieldName: metadata.tenantFieldName,
       tenantFieldType: metadata.tenantFieldType,
-      enforceTenantIsolation: metadata.enforceTenantIsolation
+      enforceTenantIsolation: true
     };
   }
   return request;
@@ -1982,6 +1989,9 @@ var import_node_crypto4 = __toESM(require("crypto"), 1);
 
 // src/routes/query.ts
 var import_node_crypto3 = __toESM(require("crypto"), 1);
+function resolveQueryPipeline(pipeline) {
+  return pipeline ?? "v2";
+}
 async function ask(client, queryEngine, question, options, signal) {
   const tenantId = resolveTenantId5(client, options.tenantId);
   const sessionId = import_node_crypto3.default.randomUUID();
@@ -1990,16 +2000,23 @@ async function ask(client, queryEngine, question, options, signal) {
   let attempt = 0;
   let lastError = options.lastError;
   let previousSql = options.previousSql;
-  const queryEndpoint = options.pipeline === "v2" ? "/v2/query" : "/query";
+  const pipeline = resolveQueryPipeline(options.pipeline);
+  const queryEndpoint = pipeline === "v2" ? "/v2/query" : "/query";
   while (attempt <= maxRetry) {
     const databaseName = options.database ?? queryEngine.getDefaultDatabase();
     const metadata = databaseName ? queryEngine.getDatabaseMetadata(databaseName) : void 0;
     let tenantSettings;
-    if (metadata?.tenantFieldName) {
+    if (metadata?.enforceTenantIsolation === false) {
+      tenantSettings = {
+        tenantFieldName: metadata.tenantFieldName ?? "",
+        tenantFieldType: metadata.tenantFieldType ?? "String",
+        enforceTenantIsolation: false
+      };
+    } else if (metadata?.tenantFieldName) {
       tenantSettings = {
         tenantFieldName: metadata.tenantFieldName,
         tenantFieldType: metadata.tenantFieldType,
-        enforceTenantIsolation: metadata.enforceTenantIsolation
+        enforceTenantIsolation: true
       };
     }
     const queryResponse = await client.postWithHeaders(
@@ -2014,7 +2031,7 @@ async function ask(client, queryEngine, question, options, signal) {
         ...databaseName ? { database: databaseName } : {},
         ...metadata?.dialect ? { dialect: metadata.dialect } : {},
         ...options.model?.trim() ? { model: options.model.trim() } : {},
-        ...options.pipeline === "v2" && options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {},
+        ...pipeline === "v2" && options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {},
         debug: options.debug ?? false
       },
       tenantId,
@@ -2329,7 +2346,8 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   const hasSqlMods = !!input.sqlModifications;
   const hasVizMods = !!input.vizModifications;
   const hasCustomSql = !!input.sqlModifications?.customSql;
-  const queryEndpoint = options?.pipeline === "v2" ? "/v2/query" : "/query";
+  const pipeline = resolveQueryPipeline(options?.pipeline);
+  const queryEndpoint = pipeline === "v2" ? "/v2/query" : "/query";
   let finalSql = input.sql;
   let finalParams = input.params ?? {};
   let paramMetadata = [];
@@ -2345,11 +2363,17 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   }
   const metadata = queryEngine.getDatabaseMetadata(databaseName);
   let tenantSettings;
-  if (metadata?.tenantFieldName) {
+  if (metadata?.enforceTenantIsolation === false) {
+    tenantSettings = {
+      tenantFieldName: metadata.tenantFieldName ?? "",
+      tenantFieldType: metadata.tenantFieldType ?? "String",
+      enforceTenantIsolation: false
+    };
+  } else if (metadata?.tenantFieldName) {
     tenantSettings = {
       tenantFieldName: metadata.tenantFieldName,
       tenantFieldType: metadata.tenantFieldType,
-      enforceTenantIsolation: metadata.enforceTenantIsolation
+      enforceTenantIsolation: true
     };
   }
   if (hasCustomSql) {
@@ -2361,10 +2385,10 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     const modifiedQuestion = buildModifiedQuestion(
       input.question,
       input.sqlModifications,
-      options?.pipeline,
+      pipeline,
       hasQuerypanelSessionContext
     );
-    if (options?.pipeline === "v2") {
+    if (pipeline === "v2") {
       finalQuestion = modifiedQuestion;
     }
     const queryResponse = await client.post(
@@ -2388,7 +2412,7 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     finalSql = queryResponse.sql;
     paramMetadata = Array.isArray(queryResponse.params) ? queryResponse.params : [];
     finalParams = queryEngine.mapGeneratedParams(paramMetadata);
-    if (options?.pipeline === "v2") {
+    if (pipeline === "v2") {
       applyDateRangeOverrides(
         input.sqlModifications?.dateRange,
         finalParams,
@@ -2605,6 +2629,12 @@ var ALL_VIZ_CHART_TYPES = [
 ];
 
 // src/index.ts
+function resolveAttachEnforceTenantIsolation(tenantFieldName, enforceTenantIsolation) {
+  if (enforceTenantIsolation !== void 0) {
+    return enforceTenantIsolation;
+  }
+  return tenantFieldName ? true : void 0;
+}
 var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
   /**
    * @param workspaceId - Workspace UUID (same value as your org in the dashboard). Passed to the API as JWT claim `organizationId`.
@@ -2675,7 +2705,10 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       tags: options?.tags,
       tenantFieldName: options?.tenantFieldName,
       tenantFieldType: options?.tenantFieldType ?? "String",
-      enforceTenantIsolation: options?.tenantFieldName ? options?.enforceTenantIsolation ?? true : void 0
+      enforceTenantIsolation: resolveAttachEnforceTenantIsolation(
+        options?.tenantFieldName,
+        options?.enforceTenantIsolation
+      )
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
@@ -2688,7 +2721,10 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       tags: options?.tags,
       tenantFieldName: options?.tenantFieldName,
       tenantFieldType: options?.tenantFieldType ?? "String",
-      enforceTenantIsolation: options?.tenantFieldName ? options?.enforceTenantIsolation ?? true : void 0
+      enforceTenantIsolation: resolveAttachEnforceTenantIsolation(
+        options?.tenantFieldName,
+        options?.enforceTenantIsolation
+      )
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
@@ -2701,7 +2737,10 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       tags: options?.tags,
       tenantFieldName: options?.tenantFieldName,
       tenantFieldType: options?.tenantFieldType ?? "String",
-      enforceTenantIsolation: options?.tenantFieldName ? options?.enforceTenantIsolation ?? true : void 0
+      enforceTenantIsolation: resolveAttachEnforceTenantIsolation(
+        options?.tenantFieldName,
+        options?.enforceTenantIsolation
+      )
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
@@ -3631,6 +3670,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
   QueryPipelineError,
   anonymizeResults,
   mapGeneratedParams,
-  normalizeSqlParamsInput
+  normalizeSqlParamsInput,
+  resolveQueryPipeline
 });
 //# sourceMappingURL=index.cjs.map