@querypanel/node-sdk 1.0.23 → 1.0.25

package/README.md

@@ -1,323 +1,95 @@
 # QueryPanel Node SDK
 
-A lightweight Node.js client for QueryPanel's NL-to-SQL APIs. The SDK manages JWT auth, exposes helper methods for common endpoints, and provides database adapters with execution, validation, and schema introspection utilities for ClickHouse and Postgres.
+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).
 
 ## Installation
 
 ```bash
-npm install @querypanel/node-sdk @clickhouse/client
+bun add @querypanel/sdk
+# or
+npm install @querypanel/sdk
 ```
 
-- Requires **Node 18+**.
-- `@clickhouse/client` is a peer dependency for ClickHouse integrations.
+> **Runtime:** Node.js 18+ (or Bun). The SDK relies on the native `fetch` API.
 
-## Quick start
+## Quickstart
 
 ```ts
-import { QueryPanelSdkAPI } from "@querypanel/node-sdk";
-import { createClient } from "@clickhouse/client";
+import { QueryPanelSdkAPI } from "@querypanel/sdk";
+import { Pool } from "pg";
 
 const qp = new QueryPanelSdkAPI(
   process.env.QUERYPANEL_URL!,
-  process.env.QUERYPANEL_SERVICE_TOKEN!,
-);
-
-// Attach a ClickHouse database (use the SDK-supplied adapter)
-const clickhouse = createClient({
-  url: process.env.CLICKHOUSE_URL!,
-  username: process.env.CLICKHOUSE_USER,
-  password: process.env.CLICKHOUSE_PASSWORD,
-  database: "analytics",
-});
-
-qp.attachClickhouse(
-  "analytics",
-  (params) => clickhouse.query(params),
+  process.env.PRIVATE_KEY!,
+  process.env.ORGANIZATION_ID!,
   {
-    database: "analytics",
-    tenantFieldName: "customer_id",     // Enable tenant isolation
-    tenantFieldType: "String",          // ClickHouse type
+    defaultTenantId: process.env.DEFAULT_TENANT_ID,
   },
 );
 
-// Ask a question - tenant isolation is automatic
-const response = await qp.ask("Top countries by revenue", { tenantId: "tenant_123" });
-console.log(response.sql);    // Includes WHERE customer_id = {customer_id:String}
-console.log(response.params); // { customer_id: "tenant_123", ... }
-console.table(response.rows);
-```
-
-## Authentication modes
-
-The constructor accepts either an already-signed JWT or a private key/organization pair for on-the-fly token generation:
-
-```ts
-// Mode 1: pass a pre-signed JWT for legacy integrations
-const qpLegacy = new QueryPanelSdkAPI(baseUrl, signedJwt);
-
-// Mode 2: provide an RSA private key and organization ID (recommended)
-const qp = new QueryPanelSdkAPI(baseUrl, privateKeyPem, organizationId);
-```
-
-## V3 Bedrock Integration
-
-The SDK provides methods to generate schema exports compatible with AWS Bedrock knowledge bases:
-
-### introspectV3
-
-Generate a simplified schema export format suitable for Bedrock ingestion:
-
-```ts
-const schema = await qp.introspectV3("analytics", {
-  tenantId: "tenant-123",
-  tables: ["orders", "customers"], // Optional: filter specific tables
-});
-
-// Output matches schema_export.json format
-console.log(JSON.stringify(schema, null, 2));
-```
-
-### ingestSchemaV3
-
-Introspect and ingest directly to Bedrock knowledge base:
+const pool = new Pool({ connectionString: process.env.POSTGRES_URL });
 
-```ts
-const result = await qp.ingestSchemaV3("analytics", {
-  tenantId: "tenant-123",
-  tables: ["orders", "customers"], // Optional
-});
-
-console.log(`Ingested ${result.total_documents} documents`);
-console.log(`Failed: ${result.failed.length}`);
-```
-
-The V3 format includes:
-- Table overviews with column summaries and statistics
-- Individual column metadata documents
-- Foreign key relationships
-- Primary key indicators
-
-This data powers the Bedrock-backed `/v3/generate-sql` endpoint using Claude Haiku 4.5.
-
-## Working with databases
-
-Adapters mediate between the SDK and your data sources. Two helpers are bundled:
-
-### ClickHouse
-
-```ts
-import {
-  ClickHouseAdapter,
-  type ClickHouseClientFn,
-} from "@querypanel/node-sdk";
-import { createClient } from "@clickhouse/client";
-
-const clickhouseClient = createClient({ url: "https://ch.example.com", database: "analytics" });
-const clickhouseFn: ClickHouseClientFn = (params) => clickhouseClient.query(params);
-const clickhouseAdapter = new ClickHouseAdapter(clickhouseFn, { database: "analytics" });
-
-// Optional introspection before attaching
-const schema = await clickhouseAdapter.introspect();
-console.log(schema.tables.map((t) => t.name));
-
-qp.attachDatabase("analytics", clickhouseAdapter);
-```
-
-### Postgres
-
-```ts
-import { Pool } from "pg";
-import {
-  PostgresAdapter,
-  type PostgresClientFn,
-} from "@querypanel/node-sdk";
-
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-const pgFn: PostgresClientFn = async (sql) => {
+const createPostgresClient = () => async (sql: string, params?: unknown[]) => {
   const client = await pool.connect();
   try {
-    const result = await client.query(sql);
+    const result = await client.query(sql, params);
     return {
       rows: result.rows,
-      fields: result.fields.map((f) => ({ name: f.name })),
+      fields: result.fields.map((field) => ({ name: field.name })),
     };
   } finally {
     client.release();
   }
 };
 
-const pgAdapter = new PostgresAdapter(pgFn, {
-  database: "app",
-  defaultSchema: "public",
+qp.attachPostgres("analytics", createPostgresClient(), {
+  description: "Primary analytics warehouse",
+  tenantFieldName: "tenant_id",
 });
 
-await pgAdapter.introspect({ tables: ["public.users"] });
-qp.attachDatabase("app", pgAdapter);
-```
-
-Adapters expose three core methods:
-
-- `execute(sql)` – runs the query and returns `{ fields, rows }`.
-- `validate(sql)` – runs an `EXPLAIN` to verify syntax before execution.
-- `introspect(options?)` – returns structured schema metadata (`SchemaIntrospection`).
-
-## SDK helpers
-
-Once at least one adapter is attached you can call:
-
-- `ask(question, options)` – generate SQL, validate it, execute through the adapter, and retrieve a matching Vega-Lite chart spec.
-- `train(payload, { tenantId, userId, scopes })` – submit curated glossary entries, metric docs, and gold SQL examples.
-- `stats({ tenantId, userId, scopes })` – fetch ingestion statistics.
-- Chart helpers: `listCharts`, `getChart`, `createChart`, `updateChart`, `deleteChart`, `listActiveCharts`, `getActiveChart`, `createActiveChart`, `updateActiveChart`, `deleteActiveChart`.
-
-Every SDK call automatically attaches the correct authentication headers and forwards optional `tenantId`, `userId`, and `scopes` when provided.
-
-### Using V3 SQL generation
+qp.attachClickhouse(
+  "clicks",
+  (params) => clickhouse.query(params),
+  {
+    database: "analytics",
+    tenantFieldName: "customer_id",
+    tenantFieldType: "String",
+  },
+);
 
-By default, `ask()` uses the `/v2/generate-sql` endpoint (OpenAI + pgvector). To use the Bedrock-powered `/v3/generate-sql` endpoint (Claude Haiku 4.5), set `useV3: true`:
+await qp.syncSchema("analytics", { tenantId: "tenant_123" });
 
-```ts
 const response = await qp.ask("Top countries by revenue", {
   tenantId: "tenant_123",
-  useV3: true, // Use Bedrock + Claude instead of OpenAI
-});
-```
-
-**Important**: The `useV3` flag controls both:
-1. **SQL generation endpoint**: Uses `/v3/generate-sql` instead of `/v2/generate-sql`
-2. **Schema introspection**: On first use, auto-syncs schema via `/v3/ingest` (Bedrock knowledge base) instead of `/v2/vectorize-schema` (pgvector)
-
-Both endpoints support the same request/response format, making migration seamless.
-
-### Manual sync control
-
-By default, the SDK automatically syncs your database schema on the first `ask()` call. You can disable this and sync manually:
-
-```ts
-// Manual sync workflow
-await qp.ingestSchemaV3("analytics", {
-  tenantId: "tenant_123",
-  tables: ["orders", "customers"], // Optional: sync specific tables
-});
-
-// Now ask questions with auto-sync disabled
-const response = await qp.ask("Top revenue by country", {
-  tenantId: "tenant_123",
-  useV3: true,
-  disableAutoSync: true, // ⚠️ Requires manual sync first
-});
-```
-
-**Why disable auto-sync?**
-- 🎯 Control when schema updates happen
-- ⚡ Faster `ask()` calls (no sync overhead)
-- 💰 Reduce API calls to Bedrock
-- 🔧 Better for production deployments (sync on app startup, not on every request)
-
-**Recommended pattern for production:**
-
-```ts
-// On app startup (once)
-await qp.ingestSchemaV3("analytics", { tenantId: "..." });
-
-// In request handlers (many times)
-app.post("/query", async (req, res) => {
-  const result = await qp.ask(req.body.question, {
-    tenantId: req.user.tenantId,
-    useV3: true,
-    disableAutoSync: true, // Already synced at startup
-  });
-  res.json(result);
-});
-```
-
-## Multi-database support
-
-The SDK keeps a registry of adapters. The first attached database becomes the default, but you can switch per request:
-
-```ts
-qp.attachPostgres("users", pgFn, { database: "users" });
-qp.attachClickhouse("analytics", clickhouseFn);
-
-await qp.ask("Top spenders", {
-  tenantId: "tenant_123",
-  database: "analytics", // override default database for this request
+  database: "analytics",
 });
-```
-
-The `available_databases` array is forwarded to the `/v2/generate-sql` endpoint so the service can pick the right dialect when it suggests queries.
-
-## Schema introspection
-
-Both adapters can produce consistent metadata that matches `node-sdk/src/schema/types.ts`:
-
-```ts
-const snapshot = await pgAdapter.introspect({ tables: ["public.orders"] });
-for (const table of snapshot.tables) {
-  console.log(table.name, table.columns.length);
-}
-```
 
-Use introspection to feed the training endpoint or to drive documentation for the AI planner.
-
-## Local introspection script
-
-Test V3 introspection locally without calling the API:
-
-```bash
-# Quick start
-npm run introspect:local
-
-# With custom database
-CLICKHOUSE_URL=http://localhost:8123 \
-CLICKHOUSE_DATABASE=analytics \
-TENANT_ID=my-tenant \
-npm run introspect:local
-
-# Filter specific tables
-TABLES="orders,customers" npm run introspect:local
+console.log(response.sql);
+console.log(response.params);
+console.table(response.rows);
+console.log(response.chart.vegaLiteSpec);
 ```
 
-This generates `schema_export.json` that you can:
-1. Review locally before ingestion
-2. Upload manually via `/v3/ingest`
-3. Use for testing and CI/CD
-
-See `node-sdk/scripts/README.md` for full documentation.
-
-## Testing and building
+## Building locally
 
 ```bash
-# run unit tests
-npm --prefix node-sdk test
-
-# build CommonJS and ESM artifacts
-npm --prefix node-sdk run build
+cd node-sdk
+bun install
+bun run build
 ```
 
-## Tenant Isolation
+This runs `tsup` which emits dual ESM/CJS bundles plus type declarations to `dist/`.
 
-The SDK provides automatic tenant isolation enforcement to prevent data leaks in multi-tenant environments. When configured, the SDK will automatically:
+## Authentication model
 
-- ✅ Inject tenant parameters into all queries
-- ✅ Validate that generated SQL includes tenant filters
-- ✅ Auto-fix SQL missing tenant isolation by adding WHERE clauses
-- ✅ Support ClickHouse typed parameters (`{customer_id:String}`)
-
-```typescript
-sdk.attachClickhouse('analytics', clickhouseFn, {
-  tenantFieldName: 'customer_id',      // Required field in your schema
-  tenantFieldType: 'String',           // ClickHouse type (String, UUID, Int64, etc.)
-  enforceTenantIsolation: true,        // Default: true (auto-fix missing filters)
-});
-```
+Every request is signed with `RS256` using the private key you pass to the constructor. The payload always includes `organizationId` and `tenantId`; `userId` and `scopes` are added when provided per call. If you still need service tokens or custom middleware, pass additional headers via the constructor.
 
-See [TENANT_ISOLATION.md](./TENANT_ISOLATION.md) for complete documentation.
+## Error handling
 
-## Additional resources
+- HTTP errors propagate as thrown `Error` instances that include `status` (and `details` when available).
+- Schema ingestion failures are logged to `console.warn` during auto-sync, but you can call `syncSchema(..., { force: true })` to surface them directly.
+- `ask()` raises immediately for guardrail/moderation errors because `/query` responds with 4xx/5xx.
 
-- `TENANT_ISOLATION.md` – Complete guide to automatic tenant isolation enforcement
-- `SDK-API.md` – REST endpoint reference used by the SDK
-- `MULTI_DATABASE.md` – Notes on attaching multiple adapters
+## Need more?
 
-If you hit an integration bug or need support for an additional database engine, open an issue or reach out to the QueryPanel team.
+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.