@querypanel/node-sdk 1.0.43 → 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

@@ -32,7 +32,9 @@ var index_exports = {};
 __export(index_exports, {
   ClickHouseAdapter: () => ClickHouseAdapter,
   PostgresAdapter: () => PostgresAdapter,
+  QueryErrorCode: () => QueryErrorCode,
   QueryPanelSdkAPI: () => QueryPanelSdkAPI,
+  QueryPipelineError: () => QueryPipelineError,
   anonymizeResults: () => anonymizeResults
 });
 module.exports = __toCommonJS(index_exports);
@@ -626,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",
@@ -640,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",
@@ -655,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 {
@@ -881,6 +916,57 @@ var QueryEngine = class {
   }
 };
 
+// src/errors.ts
+var QueryErrorCode = {
+  // Moderation errors
+  MODERATION_FAILED: "MODERATION_FAILED",
+  // Guardrail errors
+  RELEVANCE_CHECK_FAILED: "RELEVANCE_CHECK_FAILED",
+  SECURITY_CHECK_FAILED: "SECURITY_CHECK_FAILED",
+  // SQL generation errors
+  SQL_GENERATION_FAILED: "SQL_GENERATION_FAILED",
+  // SQL validation errors
+  SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED",
+  // Context retrieval errors
+  CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED",
+  // General errors
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED",
+  VALIDATION_ERROR: "VALIDATION_ERROR"
+};
+var QueryPipelineError = class extends Error {
+  constructor(message, code, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "QueryPipelineError";
+  }
+  /**
+   * Check if this is a moderation error
+   */
+  isModeration() {
+    return this.code === QueryErrorCode.MODERATION_FAILED;
+  }
+  /**
+   * Check if this is a relevance error (question not related to database)
+   */
+  isRelevanceError() {
+    return this.code === QueryErrorCode.RELEVANCE_CHECK_FAILED;
+  }
+  /**
+   * Check if this is a security error (SQL injection, prompt injection, etc.)
+   */
+  isSecurityError() {
+    return this.code === QueryErrorCode.SECURITY_CHECK_FAILED;
+  }
+  /**
+   * Check if this is any guardrail error (relevance or security)
+   */
+  isGuardrailError() {
+    return this.isRelevanceError() || this.isSecurityError();
+  }
+};
+
 // src/routes/charts.ts
 async function createChart(client, body, options, signal) {
   const tenantId = resolveTenantId(client, options?.tenantId);
@@ -917,15 +1003,10 @@ async function listCharts(client, queryEngine, options, signal) {
   );
   if (options?.includeData) {
     response.data = await Promise.all(
-      response.data.map(async (chart) => ({
-        ...chart,
-        vega_lite_spec: {
-          ...chart.vega_lite_spec,
-          data: {
-            values: await executeChartQuery(queryEngine, chart, tenantId)
-          }
-        }
-      }))
+      response.data.map(async (chart) => {
+        const rows = await executeChartQuery(queryEngine, chart, tenantId);
+        return hydrateChartWithData(chart, rows);
+      })
     );
   }
   return response;
@@ -939,15 +1020,8 @@ async function getChart(client, queryEngine, id, options, signal) {
     options?.scopes,
     signal
   );
-  return {
-    ...chart,
-    vega_lite_spec: {
-      ...chart.vega_lite_spec,
-      data: {
-        values: await executeChartQuery(queryEngine, chart, tenantId)
-      }
-    }
-  };
+  const rows = await executeChartQuery(queryEngine, chart, tenantId);
+  return hydrateChartWithData(chart, rows);
 }
 async function updateChart(client, id, body, options, signal) {
   const tenantId = resolveTenantId(client, options?.tenantId);
@@ -998,6 +1072,31 @@ async function executeChartQuery(queryEngine, chart, tenantId) {
     return [];
   }
 }
+function hydrateChartWithData(chart, rows) {
+  const spec = chart.vega_lite_spec;
+  if (chart.spec_type === "vizspec") {
+    const existingData = spec.data ?? {};
+    return {
+      ...chart,
+      vega_lite_spec: {
+        ...spec,
+        data: {
+          ...existingData,
+          values: rows
+        }
+      }
+    };
+  }
+  return {
+    ...chart,
+    vega_lite_spec: {
+      ...spec,
+      data: {
+        values: rows
+      }
+    }
+  };
+}
 
 // src/routes/active-charts.ts
 async function createActiveChart(client, body, options, signal) {
@@ -1172,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;
@@ -1188,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 } : {},
@@ -1205,17 +1306,30 @@ async function ask(client, queryEngine, question, options, signal) {
       signal,
       sessionId
     );
-    const dbName = queryResponse.database ?? options.database ?? queryEngine.getDefaultDatabase();
+    const responseSessionId = queryResponse.headers.get("x-querypanel-session-id") ?? querypanelSessionId;
+    if (!queryResponse.data.success) {
+      throw new QueryPipelineError(
+        queryResponse.data.error || "Query generation failed",
+        queryResponse.data.code || "INTERNAL_ERROR",
+        queryResponse.data.details
+      );
+    }
+    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
@@ -1232,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,
@@ -1255,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,
@@ -1279,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++;
@@ -1298,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...`
       );
@@ -1533,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",
@@ -1557,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(
@@ -1670,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", {
@@ -1845,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.
    *
@@ -2049,7 +2320,9 @@ var QueryPanelSdkAPI = class {
 0 && (module.exports = {
   ClickHouseAdapter,
   PostgresAdapter,
+  QueryErrorCode,
   QueryPanelSdkAPI,
+  QueryPipelineError,
   anonymizeResults
 });
 //# sourceMappingURL=index.cjs.map