@querypanel/node-sdk 1.0.57 → 1.0.59

package/README.md

@@ -21,7 +21,7 @@ import { Pool } from "pg";
 const qp = new QueryPanelSdkAPI(
   process.env.QUERYPANEL_URL!,
   process.env.PRIVATE_KEY!,
-  process.env.ORGANIZATION_ID!,
+  process.env.QUERYPANEL_WORKSPACE_ID!,
   {
     defaultTenantId: process.env.DEFAULT_TENANT_ID,
   },
@@ -80,6 +80,19 @@ console.table(response.rows);
 console.log(response.chart.vegaLiteSpec);
 ```
 
+### Custom system instructions (v2 pipeline)
+
+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:
+
+```ts
+const response = await qp.ask("Revenue by product", {
+  tenantId: "tenant_123",
+  database: "analytics",
+  pipeline: "v2",
+  systemPrompt: "Retention policy: only query data from the last 30 days.",
+});
+```
+
 ## Session History & Context-Aware Queries
 
 The SDK can link related questions into a session so follow-ups like “filter that to Europe” use prior context. The backend generates a QueryPanel session ID for every query and returns it in the response so you can reuse it.
@@ -338,7 +351,7 @@ import { QueryPanelSdkAPI } from "https://esm.sh/@querypanel/sdk";
 const qp = new QueryPanelSdkAPI(
   Deno.env.get("QUERYPANEL_URL")!,
   Deno.env.get("PRIVATE_KEY")!,
-  Deno.env.get("ORGANIZATION_ID")!,
+  Deno.env.get("QUERYPANEL_WORKSPACE_ID")!,
 );
 
 // Use the SDK as normal - JWT signing works automatically

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BigQueryAdapter: () => BigQueryAdapter,
   CallbackApiClient: () => CallbackApiClient,
   ClickHouseAdapter: () => ClickHouseAdapter,
   PostgresAdapter: () => PostgresAdapter,
@@ -40,6 +41,186 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/adapters/bigquery.ts
+var BigQueryAdapter = class {
+  constructor(clientFn, options) {
+    this.clientFn = clientFn;
+    this.projectId = options.projectId;
+    this.datasetProjectId = options.datasetProjectId ?? options.projectId;
+    this.defaultDataset = options.dataset;
+    this.databaseName = options.database ?? options.dataset;
+    this.kind = options.kind ?? "bigquery";
+    if (options.allowedTables) {
+      this.allowedTables = normalizeTableFilter(
+        options.allowedTables,
+        this.defaultDataset
+      );
+    }
+  }
+  projectId;
+  datasetProjectId;
+  defaultDataset;
+  databaseName;
+  kind;
+  allowedTables;
+  async execute(sql, params) {
+    if (this.allowedTables) {
+      this.validateQueryTables(sql);
+    }
+    const result = await this.clientFn({
+      query: sql,
+      params,
+      dryRun: false
+    });
+    return { fields: result.fields, rows: result.rows };
+  }
+  async validate(sql, params) {
+    await this.clientFn({
+      query: sql,
+      params,
+      dryRun: true
+    });
+  }
+  getDialect() {
+    return "bigquery";
+  }
+  /**
+   * Introspect using BigQuery INFORMATION_SCHEMA (TABLES and COLUMNS).
+   * Restricts to the default dataset (or allowedTables) and returns tables/columns only.
+   */
+  async introspect(options) {
+    const tablesToIntrospect = options?.tables ? normalizeTableFilter(options.tables, this.defaultDataset) : this.allowedTables;
+    const normalizedTables = tablesToIntrospect ?? [];
+    const tablesSql = buildTablesQuery(
+      this.datasetProjectId,
+      this.defaultDataset,
+      normalizedTables
+    );
+    const tablesResult = await this.clientFn({
+      query: tablesSql,
+      dryRun: false
+    });
+    const tableRows = tablesResult.rows;
+    const columnsSql = buildColumnsQuery(
+      this.datasetProjectId,
+      this.defaultDataset,
+      normalizedTables
+    );
+    const columnsResult = await this.clientFn({
+      query: columnsSql,
+      dryRun: false
+    });
+    const columnRows = columnsResult.rows;
+    const tablesByKey = /* @__PURE__ */ new Map();
+    for (const row of tableRows) {
+      const key = tableKey(row.table_schema, row.table_name);
+      const table = {
+        name: row.table_name,
+        schema: row.table_schema,
+        type: asTableType(row.table_type),
+        columns: []
+      };
+      tablesByKey.set(key, table);
+    }
+    for (const row of columnRows) {
+      const key = tableKey(row.table_schema, row.table_name);
+      const table = tablesByKey.get(key);
+      if (!table) continue;
+      const column = {
+        name: row.column_name,
+        type: row.data_type,
+        isPrimaryKey: false
+      };
+      table.columns.push(column);
+    }
+    const tables = Array.from(tablesByKey.values()).sort((a, b) => {
+      if (a.schema === b.schema) {
+        return a.name.localeCompare(b.name);
+      }
+      return a.schema.localeCompare(b.schema);
+    });
+    return {
+      db: {
+        kind: this.kind,
+        name: this.databaseName
+      },
+      tables,
+      introspectedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  validateQueryTables(sql) {
+    if (!this.allowedTables || this.allowedTables.length === 0) {
+      return;
+    }
+    const allowedSet = new Set(
+      this.allowedTables.map((t) => tableKey(t.dataset, t.table))
+    );
+    const tablePattern = /(?:FROM|JOIN)\s+`?(?:[\w-]+\.)?([\w-]+)\.([\w-]+)`?|(?:FROM|JOIN)\s+`?([\w-]+)`?/gi;
+    const matches = sql.matchAll(tablePattern);
+    for (const match of matches) {
+      const dataset = match[1] ?? match[3] ?? this.defaultDataset;
+      const table = match[2] ?? match[3];
+      if (table) {
+        const key = tableKey(dataset, table);
+        if (!allowedSet.has(key)) {
+          throw new Error(
+            `Query references table "${dataset}.${table}" which is not in the allowed tables list`
+          );
+        }
+      }
+    }
+  }
+};
+function normalizeTableFilter(tables, defaultDataset) {
+  if (!tables?.length) return [];
+  const normalized = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of tables) {
+    if (!raw?.trim()) continue;
+    const trimmed = raw.trim();
+    const parts = trimmed.split(".");
+    const table = parts.pop() ?? "";
+    const dataset = parts.pop() ?? defaultDataset;
+    const key = tableKey(dataset, table);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    normalized.push({ dataset, table });
+  }
+  return normalized;
+}
+function tableKey(dataset, table) {
+  return `${dataset}.${table}`;
+}
+function buildTablesQuery(datasetProjectId, dataset, tables) {
+  const qualifier = `\`${datasetProjectId}.${dataset}.INFORMATION_SCHEMA.TABLES\``;
+  const filter = tables.length > 0 ? ` AND table_name IN (${tables.map((t) => `'${escapeSql(t.table)}'`).join(", ")})` : "";
+  return `SELECT table_name, table_schema, table_type
+  FROM ${qualifier}
+  WHERE table_schema = '${escapeSql(dataset)}'${filter}
+  ORDER BY table_schema, table_name`;
+}
+function buildColumnsQuery(datasetProjectId, dataset, tables) {
+  const qualifier = `\`${datasetProjectId}.${dataset}.INFORMATION_SCHEMA.COLUMNS\``;
+  const filter = tables.length > 0 ? ` AND table_name IN (${tables.map((t) => `'${escapeSql(t.table)}'`).join(", ")})` : "";
+  return `SELECT table_name, table_schema, column_name, data_type, ordinal_position, is_nullable
+  FROM ${qualifier}
+  WHERE table_schema = '${escapeSql(dataset)}'${filter}
+  ORDER BY table_schema, table_name, ordinal_position`;
+}
+function escapeSql(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "''");
+}
+function asTableType(tableType) {
+  const normalized = tableType?.toLowerCase() ?? "";
+  if (normalized.includes("view")) {
+    return normalized.includes("materialized") ? "materialized_view" : "view";
+  }
+  if (normalized.includes("external") || normalized.includes("snapshot") || normalized.includes("clone")) {
+    return "table";
+  }
+  return "table";
+}
+
 // src/utils/clickhouse.ts
 var WRAPPER_REGEX = /^(Nullable|LowCardinality|SimpleAggregateFunction)\((.+)\)$/i;
 function unwrapTypeModifiers(type) {
@@ -109,7 +290,7 @@ var ClickHouseAdapter = class {
     this.defaultFormat = options.defaultFormat ?? "JSONEachRow";
     this.kind = options.kind ?? "clickhouse";
     if (options.allowedTables) {
-      this.allowedTables = normalizeTableFilter(options.allowedTables);
+      this.allowedTables = normalizeTableFilter2(options.allowedTables);
     }
   }
   databaseName;
@@ -147,7 +328,7 @@ var ClickHouseAdapter = class {
    * No indexes, constraints, or statistics
    */
   async introspect(options) {
-    const tablesToIntrospect = options?.tables ? normalizeTableFilter(options.tables) : this.allowedTables;
+    const tablesToIntrospect = options?.tables ? normalizeTableFilter2(options.tables) : this.allowedTables;
     const allowTables = tablesToIntrospect ?? [];
     const hasFilter = allowTables.length > 0;
     const queryParams = {
@@ -187,7 +368,7 @@ var ClickHouseAdapter = class {
       const base = {
         name: table.name,
         schema: this.databaseName,
-        type: asTableType(table.engine),
+        type: asTableType2(table.engine),
         columns: tableColumns
       };
       const comment = sanitize(table.comment);
@@ -265,7 +446,7 @@ function normalizePayload(payload) {
   }
   return [];
 }
-function normalizeTableFilter(tables) {
+function normalizeTableFilter2(tables) {
   if (!tables?.length) return [];
   const seen = /* @__PURE__ */ new Set();
   const normalized = [];
@@ -293,7 +474,7 @@ function transformColumnRow(row) {
   if (comment !== void 0) column.comment = comment;
   return column;
 }
-function asTableType(engine) {
+function asTableType2(engine) {
   if (typeof engine === "string") {
     const normalized = engine.toLowerCase();
     if (normalized.includes("view")) {
@@ -322,7 +503,7 @@ var PostgresAdapter = class {
     this.defaultSchema = options.defaultSchema ?? "public";
     this.kind = options.kind ?? "postgres";
     if (options.allowedTables) {
-      this.allowedTables = normalizeTableFilter2(
+      this.allowedTables = normalizeTableFilter3(
         options.allowedTables,
         this.defaultSchema
       );
@@ -349,7 +530,7 @@ var PostgresAdapter = class {
       return;
     }
     const allowedSet = new Set(
-      this.allowedTables.map((t) => tableKey(t.schema, t.table))
+      this.allowedTables.map((t) => tableKey2(t.schema, t.table))
     );
     const neutralizedSql = sql.replace(/EXTRACT\s*\([^)]*FROM\s+[^)]+\)/gi, "EXTRACT(/*neutralized*/)").replace(/SUBSTRING\s*\([^)]*FROM\s+[^)]+\)/gi, "SUBSTRING(/*neutralized*/)").replace(/TRIM\s*\([^)]*FROM\s+[^)]+\)/gi, "TRIM(/*neutralized*/)").replace(/POSITION\s*\([^)]*FROM\s+[^)]+\)/gi, "POSITION(/*neutralized*/)");
     const tablePattern = /(?:FROM|JOIN)\s+(?:ONLY\s+)?(?:([a-zA-Z_][a-zA-Z0-9_]*)\.)?(["']?[a-zA-Z_][a-zA-Z0-9_]*["']?)/gi;
@@ -358,7 +539,7 @@ var PostgresAdapter = class {
       const schema = match[1] ?? this.defaultSchema;
       const table = match[2]?.replace(/['"]/g, "");
       if (table) {
-        const key = tableKey(schema, table);
+        const key = tableKey2(schema, table);
         if (!allowedSet.has(key)) {
           throw new Error(
             `Query references table "${schema}.${table}" which is not in the allowed tables list`
@@ -409,23 +590,23 @@ var PostgresAdapter = class {
    * No indexes, constraints, or statistics
    */
   async introspect(options) {
-    const tablesToIntrospect = options?.tables ? normalizeTableFilter2(options.tables, this.defaultSchema) : this.allowedTables;
+    const tablesToIntrospect = options?.tables ? normalizeTableFilter3(options.tables, this.defaultSchema) : this.allowedTables;
     const normalizedTables = tablesToIntrospect ?? [];
     const tablesResult = await this.clientFn(
-      buildTablesQuery(normalizedTables)
+      buildTablesQuery2(normalizedTables)
     );
     const tableRows = tablesResult.rows;
     const columnsResult = await this.clientFn(
-      buildColumnsQuery(normalizedTables)
+      buildColumnsQuery2(normalizedTables)
     );
     const columnRows = columnsResult.rows;
     const tablesByKey = /* @__PURE__ */ new Map();
     for (const row of tableRows) {
-      const key = tableKey(row.schema_name, row.table_name);
+      const key = tableKey2(row.schema_name, row.table_name);
       const table = {
         name: row.table_name,
         schema: row.schema_name,
-        type: asTableType2(row.table_type),
+        type: asTableType3(row.table_type),
         columns: []
       };
       const comment = sanitize2(row.comment);
@@ -435,7 +616,7 @@ var PostgresAdapter = class {
       tablesByKey.set(key, table);
     }
     for (const row of columnRows) {
-      const key = tableKey(row.table_schema, row.table_name);
+      const key = tableKey2(row.table_schema, row.table_name);
       const table = tablesByKey.get(key);
       if (!table) continue;
       const column = {
@@ -465,7 +646,7 @@ var PostgresAdapter = class {
     };
   }
 };
-function normalizeTableFilter2(tables, defaultSchema) {
+function normalizeTableFilter3(tables, defaultSchema) {
   if (!tables?.length) return [];
   const normalized = [];
   const seen = /* @__PURE__ */ new Set();
@@ -479,14 +660,14 @@ function normalizeTableFilter2(tables, defaultSchema) {
     if (!isSafeIdentifier(schema) || !isSafeIdentifier(table)) {
       continue;
     }
-    const key = tableKey(schema, table);
+    const key = tableKey2(schema, table);
     if (seen.has(key)) continue;
     seen.add(key);
     normalized.push({ schema, table });
   }
   return normalized;
 }
-function buildTablesQuery(tables) {
+function buildTablesQuery2(tables) {
   const filter = buildFilterClause(tables, "n.nspname", "c.relname");
   return `SELECT
     c.relname AS table_name,
@@ -505,7 +686,7 @@ function buildTablesQuery(tables) {
     ${filter}
   ORDER BY n.nspname, c.relname;`;
 }
-function buildColumnsQuery(tables) {
+function buildColumnsQuery2(tables) {
   const filter = buildFilterClause(
     tables,
     "cols.table_schema",
@@ -550,13 +731,13 @@ function buildFilterClause(tables, schemaExpr, tableExpr) {
   });
   return `AND (${clauses.join(" OR ")})`;
 }
-function tableKey(schema, table) {
+function tableKey2(schema, table) {
   return `${schema}.${table}`;
 }
 function isSafeIdentifier(value) {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
 }
-function asTableType2(value) {
+function asTableType3(value) {
   const normalized = value.toLowerCase();
   if (normalized.includes("view")) {
     return normalized.includes("materialized") ? "materialized_view" : "view";
@@ -1024,6 +1205,9 @@ var QueryEngine = class {
       const paramKey = tenantField;
       params[paramKey] = tenantId;
       tenantPredicate = `${tenantField} = {${tenantField}:${metadata.tenantFieldType ?? "String"}}`;
+    } else if (metadata.dialect === "bigquery") {
+      params[tenantField] = tenantId;
+      tenantPredicate = `${tenantField} = @${tenantField}`;
     } else {
       const escapedId = tenantId.replace(/'/g, "''");
       tenantPredicate = `${tenantField} = '${escapedId}'`;
@@ -1580,7 +1764,9 @@ async function ask(client, queryEngine, question, options, signal) {
         ...options.maxRetry ? { max_retry: options.maxRetry } : {},
         ...tenantSettings ? { tenant_settings: tenantSettings } : {},
         ...databaseName ? { database: databaseName } : {},
-        ...metadata?.dialect ? { dialect: metadata.dialect } : {}
+        ...metadata?.dialect ? { dialect: metadata.dialect } : {},
+        ...options.model?.trim() ? { model: options.model.trim() } : {},
+        ...options.pipeline === "v2" && options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {}
       },
       tenantId,
       options.userId,
@@ -1604,7 +1790,7 @@ async function ask(client, queryEngine, question, options, signal) {
     const dbName = queryResponse.data.database ?? options.database ?? queryEngine.getDefaultDatabase();
     if (!dbName) {
       throw new Error(
-        "No database attached. Call attachPostgres/attachClickhouse first."
+        "No database attached. Call attachPostgres, attachClickhouse, or attachBigQuery first."
       );
     }
     const paramMetadata = Array.isArray(queryResponse.data.params) ? queryResponse.data.params : [];
@@ -2145,20 +2331,22 @@ function resolveTenantId8(client, tenantId) {
 var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
   client;
   queryEngine;
-  constructor(baseUrl, privateKey, organizationId, options) {
+  /**
+   * @param workspaceId - Workspace UUID (same value as your org in the dashboard). Passed to the API as JWT claim `organizationId`.
+   */
+  constructor(baseUrl, privateKey, workspaceId, options) {
     if (options?.api) {
       this.client = options.api;
     } else {
       if (!baseUrl) throw new Error("Base URL is required");
       if (!privateKey) throw new Error("Private key is required");
-      if (!organizationId) throw new Error("Organization ID is required");
-      this.client = new ApiClient(baseUrl, privateKey, organizationId, {
+      if (!workspaceId) throw new Error("Workspace ID is required");
+      this.client = new ApiClient(baseUrl, privateKey, workspaceId, {
         defaultTenantId: options?.defaultTenantId,
         additionalHeaders: options?.additionalHeaders,
         fetch: options?.fetch
       });
     }
-    if (!organizationId) throw new Error("Organization ID is required");
     this.queryEngine = new QueryEngine();
   }
   /**
@@ -2167,7 +2355,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
    * are handled in-process (e.g. by invoking querypanel-sdk services directly)
    * and do not cause recursion.
    *
-   * @param organizationId - Organization identifier
+   * @param workspaceId - Workspace identifier (sent as `organizationId` in JWTs and API auth)
    * @param requestHandler - Callback invoked for each logical API request (method, path, body, tenantId, etc.)
    * @param options - Optional defaultTenantId
    * @returns QueryPanelSdkAPI instance; attach databases and call ask(), syncSchema(), etc. as usual
@@ -2175,7 +2363,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
    * @example
    * ```ts
    * const qp = QueryPanelSdkAPI.withCallbacks(
-   *   process.env.ORGANIZATION_ID!,
+   *   process.env.QUERYPANEL_WORKSPACE_ID!,
    *   async (opts) => {
    *     // Call your in-process services (e.g. querypanel-sdk logic) instead of HTTP
    *     if (opts.path === '/query' || opts.path === '/v2/query') {
@@ -2192,11 +2380,11 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
    * const result = await qp.ask('Top 10 orders', { tenantId: 't1', database: 'db' });
    * ```
    */
-  static withCallbacks(organizationId, requestHandler, options) {
+  static withCallbacks(workspaceId, requestHandler, options) {
     const api = new CallbackApiClient(requestHandler, {
       defaultTenantId: options?.defaultTenantId
     });
-    return new _QueryPanelSdkAPI("", "", organizationId, { api });
+    return new _QueryPanelSdkAPI("", "", workspaceId, { api });
   }
   // Database attachment methods
   attachClickhouse(name, clientFn, options) {
@@ -2225,6 +2413,19 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
     };
     this.queryEngine.attachDatabase(name, adapter, metadata);
   }
+  attachBigQuery(name, clientFn, options) {
+    const adapter = new BigQueryAdapter(clientFn, options);
+    const metadata = {
+      name,
+      dialect: "bigquery",
+      description: options?.description,
+      tags: options?.tags,
+      tenantFieldName: options?.tenantFieldName,
+      tenantFieldType: options?.tenantFieldType ?? "String",
+      enforceTenantIsolation: options?.tenantFieldName ? options?.enforceTenantIsolation ?? true : void 0
+    };
+    this.queryEngine.attachDatabase(name, adapter, metadata);
+  }
   attachDatabase(name, adapter) {
     const metadata = {
       name,
@@ -3086,6 +3287,7 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BigQueryAdapter,
   CallbackApiClient,
   ClickHouseAdapter,
   PostgresAdapter,