@querypanel/node-sdk 1.0.44 → 1.0.45

package/README.md

@@ -80,6 +80,54 @@ console.table(response.rows);
 console.log(response.chart.vegaLiteSpec);
 ```
 
+## 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.
+
+```ts
+const first = await qp.ask("Revenue by country", {
+  tenantId: "tenant_123",
+  database: "analytics",
+});
+
+const querypanelSessionId = first.querypanelSessionId;
+
+const followUp = await qp.ask("Now filter that to Europe", {
+  tenantId: "tenant_123",
+  database: "analytics",
+  querypanelSessionId, // same QueryPanel session keeps context
+});
+
+console.log(followUp.sql);
+```
+
+### Managing Session History
+
+```ts
+// List sessions
+const sessions = await qp.listSessions({
+  tenantId: "tenant_123",
+  pagination: { page: 1, limit: 20 },
+  sortBy: "updated_at",
+});
+
+// Get a session with its turns
+const session = await qp.getSession("session_abc123", {
+  tenantId: "tenant_123",
+  includeTurns: true,
+});
+
+// Update session title
+await qp.updateSession(
+  "session_abc123",
+  { title: "Q4 Revenue Analysis" },
+  { tenantId: "tenant_123" },
+);
+
+// Delete a session
+await qp.deleteSession("session_abc123", { tenantId: "tenant_123" });
+```
+
 ## Saving & Managing Charts
 
 The SDK allows you to save generated charts to the QueryPanel system.

package/dist/index.cjs

@@ -628,6 +628,22 @@ var ApiClient = class {
       signal
     });
   }
+  async postWithHeaders(path, body, tenantId, userId, scopes, signal, sessionId) {
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: await this.buildHeaders(
+        tenantId,
+        userId,
+        scopes,
+        true,
+        sessionId
+      ),
+      body: JSON.stringify(body ?? {}),
+      signal
+    });
+    const data = await this.parseResponse(response);
+    return { data, headers: response.headers };
+  }
   async put(path, body, tenantId, userId, scopes, signal, sessionId) {
     return await this.request(path, {
       method: "PUT",
@@ -642,6 +658,20 @@ var ApiClient = class {
       signal
     });
   }
+  async patch(path, body, tenantId, userId, scopes, signal, sessionId) {
+    return await this.request(path, {
+      method: "PATCH",
+      headers: await this.buildHeaders(
+        tenantId,
+        userId,
+        scopes,
+        true,
+        sessionId
+      ),
+      body: JSON.stringify(body ?? {}),
+      signal
+    });
+  }
   async delete(path, tenantId, userId, scopes, signal, sessionId) {
     return await this.request(path, {
       method: "DELETE",
@@ -657,6 +687,9 @@ var ApiClient = class {
   }
   async request(path, init) {
     const response = await this.fetchImpl(`${this.baseUrl}${path}`, init);
+    return await this.parseResponse(response);
+  }
+  async parseResponse(response) {
     const text = await response.text();
     let json;
     try {
@@ -1238,6 +1271,7 @@ var import_node_crypto3 = __toESM(require("crypto"), 1);
 async function ask(client, queryEngine, question, options, signal) {
   const tenantId = resolveTenantId4(client, options.tenantId);
   const sessionId = import_node_crypto3.default.randomUUID();
+  const querypanelSessionId = options.querypanelSessionId ?? sessionId;
   const maxRetry = options.maxRetry ?? 0;
   let attempt = 0;
   let lastError = options.lastError;
@@ -1254,10 +1288,11 @@ async function ask(client, queryEngine, question, options, signal) {
         enforceTenantIsolation: metadata.enforceTenantIsolation
       };
     }
-    const queryResponse = await client.post(
+    const queryResponse = await client.postWithHeaders(
       "/query",
       {
         question,
+        ...querypanelSessionId ? { session_id: querypanelSessionId } : {},
         ...lastError ? { last_error: lastError } : {},
         ...previousSql ? { previous_sql: previousSql } : {},
         ...options.maxRetry ? { max_retry: options.maxRetry } : {},
@@ -1271,24 +1306,30 @@ async function ask(client, queryEngine, question, options, signal) {
       signal,
       sessionId
     );
-    if (!queryResponse.success) {
+    const responseSessionId = queryResponse.headers.get("x-querypanel-session-id") ?? querypanelSessionId;
+    if (!queryResponse.data.success) {
       throw new QueryPipelineError(
-        queryResponse.error || "Query generation failed",
-        queryResponse.code || "INTERNAL_ERROR",
-        queryResponse.details
+        queryResponse.data.error || "Query generation failed",
+        queryResponse.data.code || "INTERNAL_ERROR",
+        queryResponse.data.details
       );
     }
-    const dbName = queryResponse.database ?? options.database ?? queryEngine.getDefaultDatabase();
+    const sql = queryResponse.data.sql;
+    const dialect = queryResponse.data.dialect;
+    if (!sql || !dialect) {
+      throw new Error("Query response missing required SQL or dialect");
+    }
+    const dbName = queryResponse.data.database ?? options.database ?? queryEngine.getDefaultDatabase();
     if (!dbName) {
       throw new Error(
         "No database attached. Call attachPostgres/attachClickhouse first."
       );
     }
-    const paramMetadata = Array.isArray(queryResponse.params) ? queryResponse.params : [];
+    const paramMetadata = Array.isArray(queryResponse.data.params) ? queryResponse.data.params : [];
     const paramValues = queryEngine.mapGeneratedParams(paramMetadata);
     try {
       const execution = await queryEngine.validateAndExecute(
-        queryResponse.sql,
+        sql,
         paramValues,
         dbName,
         tenantId
@@ -1305,12 +1346,12 @@ async function ask(client, queryEngine, question, options, signal) {
             "/vizspec",
             {
               question,
-              sql: queryResponse.sql,
-              rationale: queryResponse.rationale,
+              sql,
+              rationale: queryResponse.data.rationale,
               fields: execution.fields,
               rows: anonymizeResults(rows),
               max_retries: options.chartMaxRetries ?? 3,
-              query_id: queryResponse.queryId
+              query_id: queryResponse.data.queryId
             },
             tenantId,
             options.userId,
@@ -1328,12 +1369,12 @@ async function ask(client, queryEngine, question, options, signal) {
             "/chart",
             {
               question,
-              sql: queryResponse.sql,
-              rationale: queryResponse.rationale,
+              sql,
+              rationale: queryResponse.data.rationale,
               fields: execution.fields,
               rows: anonymizeResults(rows),
               max_retries: options.chartMaxRetries ?? 3,
-              query_id: queryResponse.queryId
+              query_id: queryResponse.data.queryId
             },
             tenantId,
             options.userId,
@@ -1352,18 +1393,19 @@ async function ask(client, queryEngine, question, options, signal) {
         }
       }
       return {
-        sql: queryResponse.sql,
+        sql,
         params: paramValues,
         paramMetadata,
-        rationale: queryResponse.rationale,
-        dialect: queryResponse.dialect,
-        queryId: queryResponse.queryId,
+        rationale: queryResponse.data.rationale,
+        dialect,
+        queryId: queryResponse.data.queryId,
         rows,
         fields: execution.fields,
         chart,
-        context: queryResponse.context,
+        context: queryResponse.data.context,
         attempts: attempt + 1,
-        target_db: dbName
+        target_db: dbName,
+        querypanelSessionId: responseSessionId ?? void 0
       };
     } catch (error) {
       attempt++;
@@ -1371,7 +1413,7 @@ async function ask(client, queryEngine, question, options, signal) {
         throw error;
       }
       lastError = error instanceof Error ? error.message : String(error);
-      previousSql = queryResponse.sql;
+      previousSql = queryResponse.data.sql ?? previousSql;
       console.warn(
         `SQL execution failed (attempt ${attempt}/${maxRetry + 1}): ${lastError}. Retrying...`
       );
@@ -1606,10 +1648,79 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   };
 }
 
+// src/routes/sessions.ts
+async function listSessions(client, options, signal) {
+  const tenantId = resolveTenantId6(client, options?.tenantId);
+  const params = new URLSearchParams();
+  if (options?.pagination?.page)
+    params.set("page", `${options.pagination.page}`);
+  if (options?.pagination?.limit)
+    params.set("limit", `${options.pagination.limit}`);
+  if (options?.sortBy) params.set("sort_by", options.sortBy);
+  if (options?.sortDir) params.set("sort_dir", options.sortDir);
+  if (options?.title) params.set("title", options.title);
+  if (options?.userFilter) params.set("user_id", options.userFilter);
+  if (options?.createdFrom) params.set("created_from", options.createdFrom);
+  if (options?.createdTo) params.set("created_to", options.createdTo);
+  if (options?.updatedFrom) params.set("updated_from", options.updatedFrom);
+  if (options?.updatedTo) params.set("updated_to", options.updatedTo);
+  return await client.get(
+    `/sessions${params.toString() ? `?${params.toString()}` : ""}`,
+    tenantId,
+    options?.userId,
+    options?.scopes,
+    signal
+  );
+}
+async function getSession(client, sessionId, options, signal) {
+  const tenantId = resolveTenantId6(client, options?.tenantId);
+  const params = new URLSearchParams();
+  if (options?.includeTurns !== void 0) {
+    params.set("include_turns", `${options.includeTurns}`);
+  }
+  return await client.get(
+    `/sessions/${encodeURIComponent(sessionId)}${params.toString() ? `?${params.toString()}` : ""}`,
+    tenantId,
+    options?.userId,
+    options?.scopes,
+    signal
+  );
+}
+async function updateSession(client, sessionId, body, options, signal) {
+  const tenantId = resolveTenantId6(client, options?.tenantId);
+  return await client.patch(
+    `/sessions/${encodeURIComponent(sessionId)}`,
+    body,
+    tenantId,
+    options?.userId,
+    options?.scopes,
+    signal
+  );
+}
+async function deleteSession(client, sessionId, options, signal) {
+  const tenantId = resolveTenantId6(client, options?.tenantId);
+  await client.delete(
+    `/sessions/${encodeURIComponent(sessionId)}`,
+    tenantId,
+    options?.userId,
+    options?.scopes,
+    signal
+  );
+}
+function resolveTenantId6(client, tenantId) {
+  const resolved = tenantId ?? client.getDefaultTenantId();
+  if (!resolved) {
+    throw new Error(
+      "tenantId is required. Provide it per request or via defaultTenantId option."
+    );
+  }
+  return resolved;
+}
+
 // src/routes/vizspec.ts
 var import_node_crypto5 = __toESM(require("crypto"), 1);
 async function generateVizSpec(client, input, options, signal) {
-  const tenantId = resolveTenantId6(client, options?.tenantId);
+  const tenantId = resolveTenantId7(client, options?.tenantId);
   const sessionId = import_node_crypto5.default.randomUUID();
   const response = await client.post(
     "/vizspec",
@@ -1630,7 +1741,7 @@ async function generateVizSpec(client, input, options, signal) {
   );
   return response;
 }
-function resolveTenantId6(client, tenantId) {
+function resolveTenantId7(client, tenantId) {
   const resolved = tenantId ?? client.getDefaultTenantId();
   if (!resolved) {
     throw new Error(
@@ -1743,6 +1854,7 @@ var QueryPanelSdkAPI = class {
    * console.log(result.sql);      // Generated SQL
    * console.log(result.rows);     // Query results
    * console.log(result.chart);    // Vega-Lite chart spec
+   * console.log(result.querypanelSessionId); // Use for follow-ups
    *
    * // With automatic SQL repair on failure
    * const result = await qp.ask("Show monthly trends", {
@@ -1918,6 +2030,92 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  // Session history CRUD operations
+  /**
+   * Lists query sessions with pagination and filtering.
+   *
+   * @param options - Filtering, pagination, and sort options
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Paginated list of sessions
+   *
+   * @example
+   * ```typescript
+   * const sessions = await qp.listSessions({
+   *   tenantId: "tenant_123",
+   *   pagination: { page: 1, limit: 20 },
+   *   sortBy: "updated_at",
+   * });
+   * ```
+   */
+  async listSessions(options, signal) {
+    return await listSessions(this.client, options, signal);
+  }
+  /**
+   * Retrieves a session by session_id with optional turn history.
+   *
+   * @param sessionId - QueryPanel session identifier used in ask()
+   * @param options - Tenant, user, scopes, and includeTurns flag
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Session metadata with optional turns
+   *
+   * @example
+   * ```typescript
+   * const session = await qp.getSession("session_123", {
+   *   tenantId: "tenant_123",
+   *   includeTurns: true,
+   * });
+   * ```
+   */
+  async getSession(sessionId, options, signal) {
+    return await getSession(
+      this.client,
+      sessionId,
+      options,
+      signal
+    );
+  }
+  /**
+   * Updates session metadata (title).
+   *
+   * @param sessionId - QueryPanel session identifier to update
+   * @param body - Fields to update
+   * @param options - Tenant, user, and scope options
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Updated session
+   *
+   * @example
+   * ```typescript
+   * const updated = await qp.updateSession(
+   *   "session_123",
+   *   { title: "Q4 Revenue Analysis" },
+   *   { tenantId: "tenant_123" },
+   * );
+   * ```
+   */
+  async updateSession(sessionId, body, options, signal) {
+    return await updateSession(
+      this.client,
+      sessionId,
+      body,
+      options,
+      signal
+    );
+  }
+  /**
+   * Deletes a session and its turn history.
+   *
+   * @param sessionId - QueryPanel session identifier to delete
+   * @param options - Tenant, user, and scope options
+   * @param signal - Optional AbortSignal for cancellation
+   *
+   * @example
+   * ```typescript
+   * await qp.deleteSession("session_123", { tenantId: "tenant_123" });
+   * ```
+   */
+  async deleteSession(sessionId, options, signal) {
+    await deleteSession(this.client, sessionId, options, signal);
+  }
   /**
    * Retrieves a single chart by ID with live data.
    *