@querypanel/node-sdk 1.0.35 → 1.0.37

package/README.md

@@ -1,6 +1,6 @@
 # QueryPanel Node SDK
 
-A TypeScript-first client for the QueryPanel Bun/Hono API. It 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).
+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
 
@@ -10,7 +10,7 @@ bun add @querypanel/sdk
 npm install @querypanel/sdk
 ```
 
-> **Runtime:** Node.js 18+ (or Bun). The SDK relies on the native `fetch` API.
+> **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.
 
 ## Quickstart
 
@@ -72,6 +72,86 @@ console.table(response.rows);
 console.log(response.chart.vegaLiteSpec);
 ```
 
+## Saving & Managing Charts
+
+The SDK allows you to save generated charts to the QueryPanel system.
+
+> **Privacy Note:** QueryPanel only stores the chart definition (SQL query, parameters, and Vega-Lite spec). We **never** store the actual result data rows. The data is fetched live from your database whenever the chart is rendered or refreshed.
+
+```ts
+// 1. Ask a question to generate a chart
+const response = await qp.ask("Show revenue by country", {
+  tenantId: "tenant_123",
+  database: "analytics",
+});
+
+if (response.chart.vegaLiteSpec) {
+  // 2. Save the chart (only stores SQL + metadata, no data)
+  const savedChart = await qp.createChart({
+    title: "Revenue by Country",
+    sql: response.sql,
+    sql_params: response.params,
+    vega_lite_spec: response.chart.vegaLiteSpec,
+    query_id: response.queryId,
+    target_db: response.target_db,
+  }, {
+    tenantId: "tenant_123",
+    userId: "user_456" // Optional: associate with a user
+  });
+
+  console.log(`Chart saved with ID: ${savedChart.id}`);
+}
+
+// 3. List saved charts (History)
+const charts = await qp.listCharts({ tenantId: "tenant_123" });
+```
+
+## Building a Dashboard (Active Charts)
+
+While `createChart` and `listCharts` manage your **history** of saved queries, "Active Charts" are designed for building **dashboards**. You can "pin" a saved chart to a dashboard, control its order, and fetch it with live data in a single call.
+
+```ts
+// 1. Pin a saved chart to the dashboard
+const activeChart = await qp.createActiveChart({
+  chart_id: "saved_chart_id_from_history",
+  order: 1, // Optional: for sorting in UI
+  meta: { width: "full", variant: "dark" } // Optional: UI layout hints
+}, {
+  tenantId: "tenant_123"
+});
+
+// 2. Load the dashboard with live data
+// Passing { withData: true } executes the SQL for each chart immediately
+const dashboard = await qp.listActiveCharts({
+  tenantId: "tenant_123",
+  withData: true
+});
+
+dashboard.data.forEach(item => {
+  console.log(`Chart: ${item.chart?.title}`);
+  console.log(`Data points: ${item.chart?.vega_lite_spec.data.values.length}`);
+});
+```
+
+## Deno Support
+
+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";
+
+const qp = new QueryPanelSdkAPI(
+  Deno.env.get("QUERYPANEL_URL")!,
+  Deno.env.get("PRIVATE_KEY")!,
+  Deno.env.get("ORGANIZATION_ID")!,
+);
+
+// Use the SDK as normal - JWT signing works automatically
+const response = await qp.ask("Show top products", {
+  tenantId: "tenant_123",
+});
+```
+
 ## Building locally
 
 ```bash

package/dist/index.cjs

@@ -554,7 +554,6 @@ function sanitize2(value) {
 }
 
 // src/core/client.ts
-var import_node_crypto = require("crypto");
 var ApiClient = class {
   baseUrl;
   privateKey;
@@ -562,6 +561,7 @@ var ApiClient = class {
   defaultTenantId;
   additionalHeaders;
   fetchImpl;
+  cryptoKey = null;
   constructor(baseUrl, privateKey, organizationId, options) {
     if (!baseUrl) {
       throw new Error("Base URL is required");
@@ -677,6 +677,66 @@ var ApiClient = class {
     }
     return headers;
   }
+  /**
+   * Base64URL encode a string (works in both Node.js 18+ and Deno)
+   */
+  base64UrlEncode(str) {
+    const bytes = new TextEncoder().encode(str);
+    let binary = "";
+    const chunkSize = 8192;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+      const chunk = bytes.slice(i, i + chunkSize);
+      binary += String.fromCharCode(...chunk);
+    }
+    const base64 = btoa(binary);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+  }
+  /**
+   * Base64URL encode from Uint8Array (for binary data like signatures)
+   */
+  base64UrlEncodeBytes(bytes) {
+    let binary = "";
+    const chunkSize = 8192;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+      const chunk = bytes.slice(i, i + chunkSize);
+      binary += String.fromCharCode(...chunk);
+    }
+    const base64 = btoa(binary);
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+  }
+  /**
+   * Import the private key into Web Crypto API format (cached after first import)
+   */
+  async getCryptoKey() {
+    if (this.cryptoKey) {
+      return this.cryptoKey;
+    }
+    this.cryptoKey = await crypto.subtle.importKey(
+      "pkcs8",
+      this.privateKeyToArrayBuffer(this.privateKey),
+      {
+        name: "RSASSA-PKCS1-v1_5",
+        hash: "SHA-256"
+      },
+      false,
+      ["sign"]
+    );
+    return this.cryptoKey;
+  }
+  /**
+   * Convert PEM private key to ArrayBuffer for Web Crypto API
+   */
+  privateKeyToArrayBuffer(pem) {
+    const pemHeader = "-----BEGIN PRIVATE KEY-----";
+    const pemFooter = "-----END PRIVATE KEY-----";
+    const pemContents = pem.replace(pemHeader, "").replace(pemFooter, "").replace(/\s/g, "");
+    const binaryString = atob(pemContents);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes.buffer;
+  }
   async generateJWT(tenantId, userId, scopes) {
     const header = {
       alg: "RS256",
@@ -688,19 +748,20 @@ var ApiClient = class {
     };
     if (userId) payload.userId = userId;
     if (scopes?.length) payload.scopes = scopes;
-    const encodeJson = (obj) => {
-      const json = JSON.stringify(obj);
-      const base64 = Buffer.from(json).toString("base64");
-      return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
-    };
-    const encodedHeader = encodeJson(header);
-    const encodedPayload = encodeJson(payload);
+    const encodedHeader = this.base64UrlEncode(JSON.stringify(header));
+    const encodedPayload = this.base64UrlEncode(JSON.stringify(payload));
     const data = `${encodedHeader}.${encodedPayload}`;
-    const signer = (0, import_node_crypto.createSign)("RSA-SHA256");
-    signer.update(data);
-    signer.end();
-    const signature = signer.sign(this.privateKey);
-    const encodedSignature = signature.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+    const key = await this.getCryptoKey();
+    const dataBytes = new TextEncoder().encode(data);
+    const signature = await crypto.subtle.sign(
+      {
+        name: "RSASSA-PKCS1-v1_5"
+      },
+      key,
+      dataBytes
+    );
+    const signatureBytes = new Uint8Array(signature);
+    const encodedSignature = this.base64UrlEncodeBytes(signatureBytes);
     return `${data}.${encodedSignature}`;
   }
 };
@@ -1025,7 +1086,6 @@ function resolveTenantId2(client, tenantId) {
 }
 
 // src/routes/ingest.ts
-var import_node_crypto2 = require("crypto");
 async function syncSchema(client, queryEngine, databaseName, options, signal) {
   const tenantId = resolveTenantId3(client, options.tenantId);
   const adapter = queryEngine.getDatabase(databaseName);
@@ -1037,7 +1097,7 @@ async function syncSchema(client, queryEngine, databaseName, options, signal) {
   if (options.forceReindex) {
     payload.force_reindex = true;
   }
-  const sessionId = (0, import_node_crypto2.randomUUID)();
+  const sessionId = crypto.randomUUID();
   const response = await client.post(
     "/ingest",
     payload,
@@ -1086,10 +1146,9 @@ function buildSchemaRequest(databaseName, adapter, introspection, metadata) {
 }
 
 // src/routes/query.ts
-var import_node_crypto3 = require("crypto");
 async function ask(client, queryEngine, question, options, signal) {
   const tenantId = resolveTenantId4(client, options.tenantId);
-  const sessionId = (0, import_node_crypto3.randomUUID)();
+  const sessionId = crypto.randomUUID();
   const maxRetry = options.maxRetry ?? 0;
   let attempt = 0;
   let lastError = options.lastError;