@querypanel/node-sdk 1.0.42 → 1.0.43

package/dist/index.js

@@ -1125,6 +1125,9 @@ function buildSchemaRequest(databaseName, adapter, introspection, metadata) {
   return request;
 }
 
+// src/routes/modify.ts
+import crypto4 from "crypto";
+
 // src/routes/query.ts
 import crypto3 from "crypto";
 async function ask(client, queryEngine, question, options, signal) {
@@ -1286,11 +1289,216 @@ function anonymizeResults(rows) {
   });
 }
 
-// src/routes/vizspec.ts
-import crypto4 from "crypto";
-async function generateVizSpec(client, input, options, signal) {
+// src/routes/modify.ts
+function buildModifiedQuestion(originalQuestion, modifications) {
+  const hints = [];
+  if (modifications.timeGranularity) {
+    hints.push(`group results by ${modifications.timeGranularity}`);
+  }
+  if (modifications.dateRange) {
+    const parts = [];
+    if (modifications.dateRange.from) {
+      parts.push(`from ${modifications.dateRange.from}`);
+    }
+    if (modifications.dateRange.to) {
+      parts.push(`to ${modifications.dateRange.to}`);
+    }
+    if (parts.length > 0) {
+      hints.push(`filter date range ${parts.join(" ")}`);
+    }
+  }
+  if (modifications.additionalInstructions) {
+    hints.push(modifications.additionalInstructions);
+  }
+  if (hints.length === 0) {
+    return originalQuestion;
+  }
+  return `${originalQuestion} (${hints.join(", ")})`;
+}
+function buildVizHints(modifications) {
+  const hints = {};
+  if (modifications.chartType) {
+    hints.chartType = modifications.chartType;
+  }
+  if (modifications.xAxis) {
+    hints.xAxis = modifications.xAxis;
+  }
+  if (modifications.yAxis) {
+    hints.yAxis = modifications.yAxis;
+  }
+  if (modifications.series) {
+    hints.series = modifications.series;
+  }
+  if (modifications.stacking) {
+    hints.stacking = modifications.stacking;
+  }
+  if (modifications.limit !== void 0) {
+    hints.limit = modifications.limit;
+  }
+  return hints;
+}
+function resolveTenantId5(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;
+}
+async function modifyChart(client, queryEngine, input, options, signal) {
   const tenantId = resolveTenantId5(client, options?.tenantId);
   const sessionId = crypto4.randomUUID();
+  const chartType = options?.chartType ?? "vega-lite";
+  const hasSqlMods = !!input.sqlModifications;
+  const hasVizMods = !!input.vizModifications;
+  const hasCustomSql = !!input.sqlModifications?.customSql;
+  let finalSql = input.sql;
+  let finalParams = input.params ?? {};
+  let paramMetadata = [];
+  let rationale;
+  let queryId;
+  let sqlChanged = false;
+  const databaseName = input.database ?? queryEngine.getDefaultDatabase();
+  if (!databaseName) {
+    throw new Error(
+      "No database specified. Provide database in input or attach a default database."
+    );
+  }
+  const metadata = queryEngine.getDatabaseMetadata(databaseName);
+  let tenantSettings;
+  if (metadata?.tenantFieldName) {
+    tenantSettings = {
+      tenantFieldName: metadata.tenantFieldName,
+      tenantFieldType: metadata.tenantFieldType,
+      enforceTenantIsolation: metadata.enforceTenantIsolation
+    };
+  }
+  if (hasCustomSql) {
+    finalSql = input.sqlModifications.customSql;
+    finalParams = {};
+    paramMetadata = [];
+    sqlChanged = true;
+  } else if (hasSqlMods && !hasCustomSql) {
+    const modifiedQuestion = buildModifiedQuestion(
+      input.question,
+      input.sqlModifications
+    );
+    const queryResponse = await client.post(
+      "/query",
+      {
+        question: modifiedQuestion,
+        previous_sql: input.sql,
+        ...options?.maxRetry ? { max_retry: options.maxRetry } : {},
+        ...tenantSettings ? { tenant_settings: tenantSettings } : {},
+        ...databaseName ? { database: databaseName } : {},
+        ...metadata?.dialect ? { dialect: metadata.dialect } : {}
+      },
+      tenantId,
+      options?.userId,
+      options?.scopes,
+      signal,
+      sessionId
+    );
+    finalSql = queryResponse.sql;
+    paramMetadata = Array.isArray(queryResponse.params) ? queryResponse.params : [];
+    finalParams = queryEngine.mapGeneratedParams(paramMetadata);
+    rationale = queryResponse.rationale;
+    queryId = queryResponse.queryId;
+    sqlChanged = finalSql !== input.sql;
+  }
+  const execution = await queryEngine.validateAndExecute(
+    finalSql,
+    finalParams,
+    databaseName,
+    tenantId
+  );
+  const rows = execution.rows ?? [];
+  let chart = {
+    specType: chartType,
+    notes: rows.length === 0 ? "Query returned no rows." : null
+  };
+  if (rows.length > 0) {
+    const vizHints = hasVizMods ? buildVizHints(input.vizModifications) : {};
+    if (chartType === "vizspec") {
+      const vizspecResponse = await client.post(
+        "/vizspec",
+        {
+          question: input.question,
+          sql: finalSql,
+          rationale,
+          fields: execution.fields,
+          rows: anonymizeResults(rows),
+          max_retries: options?.chartMaxRetries ?? 3,
+          query_id: queryId,
+          // Include viz hints for the chart generator
+          ...hasVizMods ? { encoding_hints: vizHints } : {}
+        },
+        tenantId,
+        options?.userId,
+        options?.scopes,
+        signal,
+        sessionId
+      );
+      chart = {
+        vizSpec: vizspecResponse.spec,
+        specType: "vizspec",
+        notes: vizspecResponse.notes
+      };
+    } else {
+      const chartResponse = await client.post(
+        "/chart",
+        {
+          question: input.question,
+          sql: finalSql,
+          rationale,
+          fields: execution.fields,
+          rows: anonymizeResults(rows),
+          max_retries: options?.chartMaxRetries ?? 3,
+          query_id: queryId,
+          // Include viz hints for the chart generator
+          ...hasVizMods ? { encoding_hints: vizHints } : {}
+        },
+        tenantId,
+        options?.userId,
+        options?.scopes,
+        signal,
+        sessionId
+      );
+      chart = {
+        vegaLiteSpec: chartResponse.chart ? {
+          ...chartResponse.chart,
+          data: { values: rows }
+        } : null,
+        specType: "vega-lite",
+        notes: chartResponse.notes
+      };
+    }
+  }
+  return {
+    sql: finalSql,
+    params: finalParams,
+    paramMetadata,
+    rationale,
+    dialect: metadata?.dialect ?? "unknown",
+    queryId,
+    rows,
+    fields: execution.fields,
+    chart,
+    attempts: 1,
+    target_db: databaseName,
+    modified: {
+      sqlChanged,
+      vizChanged: hasVizMods
+    }
+  };
+}
+
+// src/routes/vizspec.ts
+import crypto5 from "crypto";
+async function generateVizSpec(client, input, options, signal) {
+  const tenantId = resolveTenantId6(client, options?.tenantId);
+  const sessionId = crypto5.randomUUID();
   const response = await client.post(
     "/vizspec",
     {
@@ -1310,7 +1518,7 @@ async function generateVizSpec(client, input, options, signal) {
   );
   return response;
 }
-function resolveTenantId5(client, tenantId) {
+function resolveTenantId6(client, tenantId) {
   const resolved = tenantId ?? client.getDefaultTenantId();
   if (!resolved) {
     throw new Error(
@@ -1367,6 +1575,30 @@ var QueryPanelSdkAPI = class {
     const adapter = this.queryEngine.getDatabase(databaseName);
     return await adapter.introspect(tables ? { tables } : void 0);
   }
+  /**
+   * Syncs the database schema to QueryPanel for natural language query generation.
+   *
+   * This method introspects your database schema and uploads it to QueryPanel's
+   * vector store. The schema is used by the LLM to generate accurate SQL queries.
+   * Schema embedding is skipped if no changes are detected (drift detection).
+   *
+   * @param databaseName - Name of the attached database to sync
+   * @param options - Sync options including tenantId and forceReindex
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Response with sync status and chunk counts
+   *
+   * @example
+   * ```typescript
+   * // Basic schema sync (skips if no changes)
+   * await qp.syncSchema("analytics", { tenantId: "tenant_123" });
+   *
+   * // Force re-embedding even if schema hasn't changed
+   * await qp.syncSchema("analytics", {
+   *   tenantId: "tenant_123",
+   *   forceReindex: true,
+   * });
+   * ```
+   */
   async syncSchema(databaseName, options, signal) {
     return await syncSchema(
       this.client,
@@ -1377,6 +1609,36 @@ var QueryPanelSdkAPI = class {
     );
   }
   // Natural language query
+  /**
+   * Generates SQL from a natural language question and executes it.
+   *
+   * This is the primary method for converting user questions into data.
+   * It handles the complete flow: SQL generation → validation → execution → chart generation.
+   *
+   * @param question - Natural language question (e.g., "Show revenue by country")
+   * @param options - Query options including tenantId, database, and retry settings
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Response with SQL, executed data rows, and generated chart
+   * @throws {Error} When SQL generation or execution fails after all retries
+   *
+   * @example
+   * ```typescript
+   * // Basic query
+   * const result = await qp.ask("Top 10 customers by revenue", {
+   *   tenantId: "tenant_123",
+   *   database: "analytics",
+   * });
+   * console.log(result.sql);      // Generated SQL
+   * console.log(result.rows);     // Query results
+   * console.log(result.chart);    // Vega-Lite chart spec
+   *
+   * // With automatic SQL repair on failure
+   * const result = await qp.ask("Show monthly trends", {
+   *   tenantId: "tenant_123",
+   *   maxRetry: 3,  // Retry up to 3 times if SQL fails
+   * });
+   * ```
+   */
   async ask(question, options, signal) {
     return await ask(
       this.client,
@@ -1387,6 +1649,28 @@ var QueryPanelSdkAPI = class {
     );
   }
   // VizSpec generation
+  /**
+   * Generates a VizSpec visualization specification from query results.
+   *
+   * Use this when you have raw SQL results and want to generate a chart
+   * specification without going through the full ask() flow. Useful for
+   * re-generating charts with different settings.
+   *
+   * @param input - VizSpec generation input with question, SQL, and result data
+   * @param options - Optional settings for tenant and retries
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns VizSpec specification for chart, table, or metric visualization
+   *
+   * @example
+   * ```typescript
+   * const vizspec = await qp.generateVizSpec({
+   *   question: "Revenue by country",
+   *   sql: "SELECT country, SUM(revenue) FROM orders GROUP BY country",
+   *   fields: ["country", "revenue"],
+   *   rows: queryResults,
+   * }, { tenantId: "tenant_123" });
+   * ```
+   */
   async generateVizSpec(input, options, signal) {
     return await generateVizSpec(
       this.client,
@@ -1395,10 +1679,125 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  // Chart modification
+  /**
+   * Modifies a chart by regenerating SQL and/or applying visualization changes.
+   *
+   * This method supports three modes of operation:
+   *
+   * 1. **SQL Modifications**: When `sqlModifications` is provided, the SQL is
+   *    regenerated using the query endpoint with modification hints. If `customSql`
+   *    is set, it's used directly without regeneration.
+   *
+   * 2. **Visualization Modifications**: When only `vizModifications` is provided,
+   *    the existing SQL is re-executed and a new chart is generated with the
+   *    specified encoding preferences.
+   *
+   * 3. **Combined**: Both SQL and visualization modifications can be applied
+   *    together. SQL is regenerated first, then viz modifications are applied.
+   *
+   * @param input - Chart modification input with source data and modifications
+   * @param options - Optional settings for tenant, user, and chart generation
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Modified chart response with SQL, data, and chart specification
+   *
+   * @example
+   * ```typescript
+   * // Change chart type and axis from an ask() response
+   * const modified = await qp.modifyChart({
+   *   sql: response.sql,
+   *   question: "revenue by country",
+   *   database: "analytics",
+   *   vizModifications: {
+   *     chartType: "bar",
+   *     xAxis: { field: "country" },
+   *     yAxis: { field: "revenue", aggregate: "sum" },
+   *   },
+   * }, { tenantId: "tenant_123" });
+   *
+   * // Change time granularity (triggers SQL regeneration)
+   * const monthly = await qp.modifyChart({
+   *   sql: response.sql,
+   *   question: "revenue over time",
+   *   database: "analytics",
+   *   sqlModifications: {
+   *     timeGranularity: "month",
+   *     dateRange: { from: "2024-01-01", to: "2024-12-31" },
+   *   },
+   * }, { tenantId: "tenant_123" });
+   *
+   * // Direct SQL edit with chart regeneration
+   * const customized = await qp.modifyChart({
+   *   sql: response.sql,
+   *   question: "revenue by country",
+   *   database: "analytics",
+   *   sqlModifications: {
+   *     customSql: "SELECT country, SUM(revenue) FROM orders GROUP BY country",
+   *   },
+   * }, { tenantId: "tenant_123" });
+   * ```
+   */
+  async modifyChart(input, options, signal) {
+    return await modifyChart(
+      this.client,
+      this.queryEngine,
+      input,
+      options,
+      signal
+    );
+  }
   // Chart CRUD operations
+  /**
+   * Saves a chart to the QueryPanel system for later retrieval.
+   *
+   * Charts store the SQL query, parameters, and visualization spec - never the actual data.
+   * Data is fetched live when the chart is rendered or refreshed.
+   *
+   * @param body - Chart data including title, SQL, and Vega-Lite spec
+   * @param options - Tenant, user, and scope options
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns The saved chart with its generated ID
+   *
+   * @example
+   * ```typescript
+   * const savedChart = await qp.createChart({
+   *   title: "Revenue by Country",
+   *   sql: response.sql,
+   *   sql_params: response.params,
+   *   vega_lite_spec: response.chart.vegaLiteSpec,
+   *   target_db: "analytics",
+   * }, { tenantId: "tenant_123", userId: "user_456" });
+   * ```
+   */
   async createChart(body, options, signal) {
     return await createChart(this.client, body, options, signal);
   }
+  /**
+   * Lists saved charts with optional filtering and pagination.
+   *
+   * Use `includeData: true` to execute each chart's SQL and include live data.
+   *
+   * @param options - Filtering, pagination, and data options
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Paginated list of charts
+   *
+   * @example
+   * ```typescript
+   * // List charts with pagination
+   * const charts = await qp.listCharts({
+   *   tenantId: "tenant_123",
+   *   pagination: { page: 1, limit: 10 },
+   *   sortBy: "created_at",
+   *   sortDir: "desc",
+   * });
+   *
+   * // List with live data
+   * const chartsWithData = await qp.listCharts({
+   *   tenantId: "tenant_123",
+   *   includeData: true,
+   * });
+   * ```
+   */
   async listCharts(options, signal) {
     return await listCharts(
       this.client,
@@ -1407,6 +1806,24 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  /**
+   * Retrieves a single chart by ID with live data.
+   *
+   * The chart's SQL is automatically executed and data is included in the response.
+   *
+   * @param id - Chart ID
+   * @param options - Tenant, user, and scope options
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Chart with live data populated
+   *
+   * @example
+   * ```typescript
+   * const chart = await qp.getChart("chart_123", {
+   *   tenantId: "tenant_123",
+   * });
+   * console.log(chart.vega_lite_spec.data.values); // Live data
+   * ```
+   */
   async getChart(id, options, signal) {
     return await getChart(
       this.client,
@@ -1416,6 +1833,23 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  /**
+   * Updates an existing chart's metadata or configuration.
+   *
+   * @param id - Chart ID to update
+   * @param body - Fields to update (partial update supported)
+   * @param options - Tenant, user, and scope options
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Updated chart
+   *
+   * @example
+   * ```typescript
+   * const updated = await qp.updateChart("chart_123", {
+   *   title: "Updated Chart Title",
+   *   description: "New description",
+   * }, { tenantId: "tenant_123" });
+   * ```
+   */
   async updateChart(id, body, options, signal) {
     return await updateChart(
       this.client,
@@ -1425,10 +1859,42 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  /**
+   * Deletes a chart permanently.
+   *
+   * @param id - Chart ID to delete
+   * @param options - Tenant, user, and scope options
+   * @param signal - Optional AbortSignal for cancellation
+   *
+   * @example
+   * ```typescript
+   * await qp.deleteChart("chart_123", { tenantId: "tenant_123" });
+   * ```
+   */
   async deleteChart(id, options, signal) {
     await deleteChart(this.client, id, options, signal);
   }
-  // Active Chart CRUD operations
+  // Active Chart CRUD operations (Dashboard)
+  /**
+   * Pins a saved chart to the dashboard (Active Charts).
+   *
+   * Active Charts are used for building dashboards. Unlike the chart history,
+   * active charts are meant to be displayed together with layout metadata.
+   *
+   * @param body - Active chart config with chart_id, order, and optional meta
+   * @param options - Tenant, user, and scope options
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Created active chart entry
+   *
+   * @example
+   * ```typescript
+   * const pinned = await qp.createActiveChart({
+   *   chart_id: savedChart.id,
+   *   order: 1,
+   *   meta: { width: "full", variant: "dark" },
+   * }, { tenantId: "tenant_123" });
+   * ```
+   */
   async createActiveChart(body, options, signal) {
     return await createActiveChart(
       this.client,
@@ -1437,6 +1903,30 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  /**
+   * Lists all active charts (dashboard items) with optional live data.
+   *
+   * Use `withData: true` to execute each chart's SQL and include results.
+   * This is the primary method for loading a complete dashboard.
+   *
+   * @param options - Filtering and data options including withData
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Paginated list of active charts with optional live data
+   *
+   * @example
+   * ```typescript
+   * // Load dashboard with live data
+   * const dashboard = await qp.listActiveCharts({
+   *   tenantId: "tenant_123",
+   *   withData: true,
+   * });
+   *
+   * dashboard.data.forEach(item => {
+   *   console.log(item.chart?.title);
+   *   console.log(item.chart?.vega_lite_spec.data.values);
+   * });
+   * ```
+   */
   async listActiveCharts(options, signal) {
     return await listActiveCharts(
       this.client,
@@ -1445,6 +1935,22 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  /**
+   * Retrieves a single active chart by ID.
+   *
+   * @param id - Active chart ID
+   * @param options - Options including withData for live data
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Active chart with associated chart data
+   *
+   * @example
+   * ```typescript
+   * const activeChart = await qp.getActiveChart("active_123", {
+   *   tenantId: "tenant_123",
+   *   withData: true,
+   * });
+   * ```
+   */
   async getActiveChart(id, options, signal) {
     return await getActiveChart(
       this.client,
@@ -1454,6 +1960,25 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  /**
+   * Updates an active chart's order or metadata.
+   *
+   * Use this to reorder dashboard items or update layout hints.
+   *
+   * @param id - Active chart ID to update
+   * @param body - Fields to update (order, meta)
+   * @param options - Tenant, user, and scope options
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Updated active chart
+   *
+   * @example
+   * ```typescript
+   * const updated = await qp.updateActiveChart("active_123", {
+   *   order: 5,
+   *   meta: { width: "half" },
+   * }, { tenantId: "tenant_123" });
+   * ```
+   */
   async updateActiveChart(id, body, options, signal) {
     return await updateActiveChart(
       this.client,
@@ -1463,6 +1988,20 @@ var QueryPanelSdkAPI = class {
       signal
     );
   }
+  /**
+   * Removes a chart from the dashboard (unpins it).
+   *
+   * This only removes the active chart entry, not the underlying saved chart.
+   *
+   * @param id - Active chart ID to delete
+   * @param options - Tenant, user, and scope options
+   * @param signal - Optional AbortSignal for cancellation
+   *
+   * @example
+   * ```typescript
+   * await qp.deleteActiveChart("active_123", { tenantId: "tenant_123" });
+   * ```
+   */
   async deleteActiveChart(id, options, signal) {
     await deleteActiveChart(this.client, id, options, signal);
   }