@querypanel/node-sdk 1.3.0-beta.2 → 1.3.1

package/dist/index.d.cts

@@ -360,10 +360,15 @@ interface ChartCreateInput {
     title: string;
     prompt?: string;
     description?: string;
-    sql: string;
+    /**
+     * Required when `query_id` is not provided. Ignored (with `sql_params`) when
+     * `query_id` is present: the server saves the SQL and params it stored for that query.
+     */
+    sql?: string;
     sql_params?: Record<string, unknown>;
     vega_lite_spec: Record<string, unknown>;
     spec_type?: 'vega-lite' | 'vizspec';
+    /** Server-issued query id from ask() / modifyChart(). Preferred over `sql`. */
     query_id?: string;
     target_db?: string;
 }
@@ -373,6 +378,8 @@ interface ChartUpdateInput {
     description?: string;
     sql?: string;
     sql_params?: Record<string, unknown>;
+    /** When present, the server replaces sql / sql_params with the stored query. */
+    query_id?: string;
     vega_lite_spec?: Record<string, unknown>;
     spec_type?: 'vega-lite' | 'vizspec';
     target_db?: string;
@@ -724,12 +731,11 @@ interface AskOptions {
      */
     querypanelSessionId?: string;
     /**
-     * Pipeline version for query generation.
-     * Defaults to `"v2"` (`POST /v2/query`).
-     * - `"v2"` (default): intent planning, hybrid retrieval, schema linking, SQL reflection
-     * - `"v1"` (**deprecated**): legacy `POST /query` pipeline — prefer omitting or `"v2"`
+     * Query pipeline. Only `"v2"` is accepted (`POST /v2/query`).
+     * `"v1"` was removed: passing it fails typecheck and throws at runtime.
+     * Omit this field; asks always use v2.
      */
-    pipeline?: "v1" | "v2";
+    pipeline?: "v2";
     /**
      * Optional model id for SQL generation (e.g. OpenAI or `gemini-*` when the API uses Gemini). Omit for server default.
      */
@@ -743,7 +749,7 @@ interface AskOptions {
      * Use this for tenant-specific policies (e.g. retention windows) that must
      * be enforced on every query.
      *
-     * Sent when the resolved pipeline is `"v2"` (the default).
+     * Sent on every ask (`POST /v2/query`).
      */
     systemPrompt?: string;
     /**
@@ -821,9 +827,10 @@ interface AskResponse {
     trace?: PipelineTrace;
 }
 /**
- * Resolve ask/modify pipeline. Defaults to v2; `"v1"` remains available but deprecated.
+ * Resolve ask/modify pipeline. Always `"v2"` (`POST /v2/query`).
+ * Throws if a removed pipeline such as `"v1"` is passed.
  */
-declare function resolveQueryPipeline(pipeline?: "v1" | "v2"): "v1" | "v2";
+declare function resolveQueryPipeline(pipeline?: "v2"): "v2";
 declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
 
 /**
@@ -917,11 +924,22 @@ interface VizModifications {
  */
 interface ChartModifyInput {
     /**
-     * The SQL query to modify or re-execute.
+     * Server-issued id of the query to modify or re-execute.
+     * From ask() / modifyChart() response: response.queryId
+     * From saved chart: chart.query_id
+     *
+     * Preferred over `sql`: when present the SQL and params are loaded from the server
+     * (scoped to the authenticated tenant) and `sql` / `params` are ignored.
+     */
+    queryId?: string;
+    /**
+     * The SQL query to modify or re-execute. Required when `queryId` is not provided.
      * From ask() response: response.sql
      * From saved chart: chart.sql
+     *
+     * Kept for backward compatibility; prefer `queryId`.
      */
-    sql: string;
+    sql?: string;
     /**
      * The original natural language question.
      * Used when regenerating SQL with modifications.
@@ -967,12 +985,11 @@ interface ChartModifyOptions {
     /** Chart generation method: 'vega-lite' or 'vizspec' */
     chartType?: "vega-lite" | "vizspec";
     /**
-     * Pipeline version for SQL regeneration.
-     * Defaults to `"v2"` (`POST /v2/query`).
-     * - `"v2"` (default): intent planning, hybrid retrieval, schema linking, SQL reflection
-     * - `"v1"` (**deprecated**): legacy `POST /query` pipeline — prefer omitting or `"v2"`
+     * Query pipeline. Only `"v2"` is accepted (`POST /v2/query`).
+     * `"v1"` was removed: passing it fails typecheck and throws at runtime.
+     * Omit this field; chart modifications always use v2.
      */
-    pipeline?: "v1" | "v2";
+    pipeline?: "v2";
     /**
      * QueryPanel session ID for context-aware follow-ups.
      * Pass the querypanelSessionId from a previous ask() response
@@ -1313,7 +1330,13 @@ declare class QueryPanelSdkAPI {
      * to be attached (e.g. via attachPostgres) and options.tenantId.
      */
     runSqlForDashboard(input: {
-        sql: string;
+        /**
+         * Server-issued id from ask() / modifyChart(). Takes priority: the stored SQL
+         * and params are executed and `sql` / `params` are ignored.
+         */
+        queryId?: string;
+        /** Required when `queryId` is not provided (backward compatible raw SQL). */
+        sql?: string;
         params?: Record<string, unknown>;
         database?: string;
     }, options: {

package/dist/index.d.ts

@@ -360,10 +360,15 @@ interface ChartCreateInput {
     title: string;
     prompt?: string;
     description?: string;
-    sql: string;
+    /**
+     * Required when `query_id` is not provided. Ignored (with `sql_params`) when
+     * `query_id` is present: the server saves the SQL and params it stored for that query.
+     */
+    sql?: string;
     sql_params?: Record<string, unknown>;
     vega_lite_spec: Record<string, unknown>;
     spec_type?: 'vega-lite' | 'vizspec';
+    /** Server-issued query id from ask() / modifyChart(). Preferred over `sql`. */
     query_id?: string;
     target_db?: string;
 }
@@ -373,6 +378,8 @@ interface ChartUpdateInput {
     description?: string;
     sql?: string;
     sql_params?: Record<string, unknown>;
+    /** When present, the server replaces sql / sql_params with the stored query. */
+    query_id?: string;
     vega_lite_spec?: Record<string, unknown>;
     spec_type?: 'vega-lite' | 'vizspec';
     target_db?: string;
@@ -724,12 +731,11 @@ interface AskOptions {
      */
     querypanelSessionId?: string;
     /**
-     * Pipeline version for query generation.
-     * Defaults to `"v2"` (`POST /v2/query`).
-     * - `"v2"` (default): intent planning, hybrid retrieval, schema linking, SQL reflection
-     * - `"v1"` (**deprecated**): legacy `POST /query` pipeline — prefer omitting or `"v2"`
+     * Query pipeline. Only `"v2"` is accepted (`POST /v2/query`).
+     * `"v1"` was removed: passing it fails typecheck and throws at runtime.
+     * Omit this field; asks always use v2.
      */
-    pipeline?: "v1" | "v2";
+    pipeline?: "v2";
     /**
      * Optional model id for SQL generation (e.g. OpenAI or `gemini-*` when the API uses Gemini). Omit for server default.
      */
@@ -743,7 +749,7 @@ interface AskOptions {
      * Use this for tenant-specific policies (e.g. retention windows) that must
      * be enforced on every query.
      *
-     * Sent when the resolved pipeline is `"v2"` (the default).
+     * Sent on every ask (`POST /v2/query`).
      */
     systemPrompt?: string;
     /**
@@ -821,9 +827,10 @@ interface AskResponse {
     trace?: PipelineTrace;
 }
 /**
- * Resolve ask/modify pipeline. Defaults to v2; `"v1"` remains available but deprecated.
+ * Resolve ask/modify pipeline. Always `"v2"` (`POST /v2/query`).
+ * Throws if a removed pipeline such as `"v1"` is passed.
  */
-declare function resolveQueryPipeline(pipeline?: "v1" | "v2"): "v1" | "v2";
+declare function resolveQueryPipeline(pipeline?: "v2"): "v2";
 declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
 
 /**
@@ -917,11 +924,22 @@ interface VizModifications {
  */
 interface ChartModifyInput {
     /**
-     * The SQL query to modify or re-execute.
+     * Server-issued id of the query to modify or re-execute.
+     * From ask() / modifyChart() response: response.queryId
+     * From saved chart: chart.query_id
+     *
+     * Preferred over `sql`: when present the SQL and params are loaded from the server
+     * (scoped to the authenticated tenant) and `sql` / `params` are ignored.
+     */
+    queryId?: string;
+    /**
+     * The SQL query to modify or re-execute. Required when `queryId` is not provided.
      * From ask() response: response.sql
      * From saved chart: chart.sql
+     *
+     * Kept for backward compatibility; prefer `queryId`.
      */
-    sql: string;
+    sql?: string;
     /**
      * The original natural language question.
      * Used when regenerating SQL with modifications.
@@ -967,12 +985,11 @@ interface ChartModifyOptions {
     /** Chart generation method: 'vega-lite' or 'vizspec' */
     chartType?: "vega-lite" | "vizspec";
     /**
-     * Pipeline version for SQL regeneration.
-     * Defaults to `"v2"` (`POST /v2/query`).
-     * - `"v2"` (default): intent planning, hybrid retrieval, schema linking, SQL reflection
-     * - `"v1"` (**deprecated**): legacy `POST /query` pipeline — prefer omitting or `"v2"`
+     * Query pipeline. Only `"v2"` is accepted (`POST /v2/query`).
+     * `"v1"` was removed: passing it fails typecheck and throws at runtime.
+     * Omit this field; chart modifications always use v2.
      */
-    pipeline?: "v1" | "v2";
+    pipeline?: "v2";
     /**
      * QueryPanel session ID for context-aware follow-ups.
      * Pass the querypanelSessionId from a previous ask() response
@@ -1313,7 +1330,13 @@ declare class QueryPanelSdkAPI {
      * to be attached (e.g. via attachPostgres) and options.tenantId.
      */
     runSqlForDashboard(input: {
-        sql: string;
+        /**
+         * Server-issued id from ask() / modifyChart(). Takes priority: the stored SQL
+         * and params are executed and `sql` / `params` are ignored.
+         */
+        queryId?: string;
+        /** Required when `queryId` is not provided (backward compatible raw SQL). */
+        sql?: string;
         params?: Record<string, unknown>;
         database?: string;
     }, options: {

package/dist/index.js

@@ -14,6 +14,13 @@ var BigQueryAdapter = class {
       );
     }
   }
+  clientFn;
+  projectId;
+  datasetProjectId;
+  defaultDataset;
+  databaseName;
+  kind;
+  allowedTables;
   async execute(sql, params) {
     if (this.allowedTables) {
       this.validateQueryTables(sql);
@@ -244,6 +251,11 @@ var ClickHouseAdapter = class {
       this.allowedTables = normalizeTableFilter2(options.allowedTables);
     }
   }
+  clientFn;
+  databaseName;
+  defaultFormat;
+  kind;
+  allowedTables;
   async execute(sql, params) {
     if (this.allowedTables) {
       this.validateQueryTables(sql);
@@ -497,6 +509,11 @@ var PostgresAdapter = class {
       );
     }
   }
+  clientFn;
+  databaseName;
+  defaultSchema;
+  kind;
+  allowedTables;
   async execute(sql, params) {
     if (this.allowedTables) {
       this.validateQueryTables(sql);
@@ -805,6 +822,9 @@ var QueryPipelineError = class extends Error {
     this.status = status;
     this.name = "QueryPipelineError";
   }
+  code;
+  details;
+  status;
   /**
    * Check if this is a moderation error
    */
@@ -857,8 +877,14 @@ var QueryPipelineError = class extends Error {
 
 // src/core/client.ts
 var ApiClient = class {
+  baseUrl;
+  privateKey;
+  organizationId;
+  defaultTenantId;
+  additionalHeaders;
+  fetchImpl;
+  cryptoKey = null;
   constructor(baseUrl, privateKey, organizationId, options) {
-    this.cryptoKey = null;
     if (!baseUrl) {
       throw new Error("Base URL is required");
     }
@@ -1112,6 +1138,8 @@ var ApiClient = class {
 
 // src/core/callback-client.ts
 var CallbackApiClient = class {
+  requestHandler;
+  defaultTenantId;
   constructor(requestHandler, options) {
     this.requestHandler = requestHandler;
     this.defaultTenantId = options?.defaultTenantId;
@@ -1254,10 +1282,9 @@ function normalizeSqlParamsInput(params) {
 
 // src/core/query-engine.ts
 var QueryEngine = class {
-  constructor() {
-    this.databases = /* @__PURE__ */ new Map();
-    this.databaseMetadata = /* @__PURE__ */ new Map();
-  }
+  databases = /* @__PURE__ */ new Map();
+  databaseMetadata = /* @__PURE__ */ new Map();
+  defaultDatabase;
   attachDatabase(name, adapter, metadata) {
     this.databases.set(name, adapter);
     this.databaseMetadata.set(name, metadata);
@@ -1943,7 +1970,13 @@ import crypto4 from "crypto";
 // src/routes/query.ts
 import crypto3 from "crypto";
 function resolveQueryPipeline(pipeline) {
-  return pipeline ?? "v2";
+  const requested = pipeline;
+  if (requested != null && requested !== "v2") {
+    throw new Error(
+      `Query pipeline "${requested}" was removed. ask() and modifyChart() always use POST /v2/query.`
+    );
+  }
+  return "v2";
 }
 async function ask(client, queryEngine, question, options, signal) {
   const tenantId = resolveTenantId5(client, options.tenantId);
@@ -1953,8 +1986,9 @@ async function ask(client, queryEngine, question, options, signal) {
   let attempt = 0;
   let lastError = options.lastError;
   let previousSql = options.previousSql;
-  const pipeline = resolveQueryPipeline(options.pipeline);
-  const queryEndpoint = pipeline === "v2" ? "/v2/query" : "/query";
+  let parentQueryId;
+  resolveQueryPipeline(options.pipeline);
+  const queryEndpoint = "/v2/query";
   while (attempt <= maxRetry) {
     const databaseName = options.database ?? queryEngine.getDefaultDatabase();
     const metadata = databaseName ? queryEngine.getDatabaseMetadata(databaseName) : void 0;
@@ -1984,7 +2018,8 @@ async function ask(client, queryEngine, question, options, signal) {
         ...databaseName ? { database: databaseName } : {},
         ...metadata?.dialect ? { dialect: metadata.dialect } : {},
         ...options.model?.trim() ? { model: options.model.trim() } : {},
-        ...pipeline === "v2" && options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {},
+        ...options.systemPrompt?.trim() ? { system_prompt: options.systemPrompt.trim() } : {},
+        ...parentQueryId ? { parent_query_id: parentQueryId } : {},
         debug: options.debug ?? false
       },
       tenantId,
@@ -2006,6 +2041,9 @@ async function ask(client, queryEngine, question, options, signal) {
     if (!sql || !dialect) {
       throw new Error("Query response missing required SQL or dialect");
     }
+    if (queryResponse.data.queryId) {
+      parentQueryId = queryResponse.data.queryId;
+    }
     const dbName = queryResponse.data.database ?? options.database ?? queryEngine.getDefaultDatabase();
     if (!dbName) {
       throw new Error(
@@ -2147,34 +2185,53 @@ function anonymizeResults(rows) {
   });
 }
 
+// src/routes/queries.ts
+async function resolveQuery(client, queryEngine, queryId, options, signal) {
+  const response = await client.get(
+    `/v2/queries/${encodeURIComponent(queryId)}`,
+    options.tenantId,
+    options.userId,
+    options.scopes,
+    signal
+  );
+  const paramMetadata = Array.isArray(response.params) ? response.params : [];
+  return {
+    queryId: response.queryId,
+    sql: response.sql,
+    params: queryEngine.mapGeneratedParams(paramMetadata),
+    paramMetadata,
+    dialect: response.dialect
+  };
+}
+async function markQueryExecuted(client, queryId, options, signal) {
+  try {
+    await client.post(
+      `/v2/queries/${encodeURIComponent(queryId)}/executed`,
+      {},
+      options.tenantId,
+      options.userId,
+      options.scopes,
+      signal
+    );
+  } catch {
+  }
+}
+
 // src/routes/modify.ts
-function buildModifiedQuestion(originalQuestion, modifications, pipeline, hasSessionContext = false) {
+function buildModifiedQuestion(originalQuestion, modifications, hasSessionContext = false) {
   const hints = [];
   if (modifications.timeGranularity) {
     hints.push(`group results by ${modifications.timeGranularity}`);
   }
   if (modifications.dateRange) {
-    if (pipeline === "v2") {
-      const from = normalizeDateInput(modifications.dateRange.from);
-      const to = normalizeDateInput(modifications.dateRange.to);
-      if (from && to) {
-        hints.push(`change date range to ${from} through ${to}`);
-      } else if (from) {
-        hints.push(`change start date to ${from}`);
-      } else if (to) {
-        hints.push(`change end date to ${to}`);
-      }
-    } else {
-      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(" ")}`);
-      }
+    const from = normalizeDateInput(modifications.dateRange.from);
+    const to = normalizeDateInput(modifications.dateRange.to);
+    if (from && to) {
+      hints.push(`change date range to ${from} through ${to}`);
+    } else if (from) {
+      hints.push(`change start date to ${from}`);
+    } else if (to) {
+      hints.push(`change end date to ${to}`);
     }
   }
   if (modifications.additionalInstructions) {
@@ -2183,7 +2240,7 @@ function buildModifiedQuestion(originalQuestion, modifications, pipeline, hasSes
   if (hints.length === 0) {
     return originalQuestion;
   }
-  if (pipeline === "v2" && hasSessionContext) {
+  if (hasSessionContext) {
     return hints.join(", ");
   }
   return `${originalQuestion} (${hints.join(", ")})`;
@@ -2299,13 +2356,30 @@ async function modifyChart(client, queryEngine, input, options, signal) {
   const hasSqlMods = !!input.sqlModifications;
   const hasVizMods = !!input.vizModifications;
   const hasCustomSql = !!input.sqlModifications?.customSql;
-  const pipeline = resolveQueryPipeline(options?.pipeline);
-  const queryEndpoint = pipeline === "v2" ? "/v2/query" : "/query";
-  let finalSql = input.sql;
+  resolveQueryPipeline(options?.pipeline);
+  const queryEndpoint = "/v2/query";
+  let currentSql = input.sql;
   let finalParams = input.params ?? {};
   let paramMetadata = [];
   let rationale;
   let queryId;
+  if (input.queryId) {
+    const resolved = await resolveQuery(
+      client,
+      queryEngine,
+      input.queryId,
+      { tenantId, userId: options?.userId, scopes: options?.scopes },
+      signal
+    );
+    currentSql = resolved.sql;
+    finalParams = resolved.params;
+    paramMetadata = resolved.paramMetadata;
+    queryId = resolved.queryId;
+  }
+  if (!currentSql) {
+    throw new Error("modifyChart requires either queryId or sql.");
+  }
+  let finalSql = currentSql;
   let sqlChanged = false;
   let finalQuestion = input.question;
   const databaseName = input.database ?? queryEngine.getDefaultDatabase();
@@ -2333,23 +2407,21 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     finalSql = input.sqlModifications.customSql;
     finalParams = {};
     paramMetadata = [];
+    queryId = void 0;
     sqlChanged = true;
   } else if (hasSqlMods && !hasCustomSql) {
     const modifiedQuestion = buildModifiedQuestion(
       input.question,
       input.sqlModifications,
-      pipeline,
       hasQuerypanelSessionContext
     );
-    if (pipeline === "v2") {
-      finalQuestion = modifiedQuestion;
-    }
+    finalQuestion = modifiedQuestion;
     const queryResponse = await client.post(
       queryEndpoint,
       {
         question: modifiedQuestion,
         session_id: querypanelSessionId,
-        previous_sql: input.sql,
+        previous_sql: currentSql,
         ...options?.maxRetry ? { max_retry: options.maxRetry } : {},
         ...tenantSettings ? { tenant_settings: tenantSettings } : {},
         ...databaseName ? { database: databaseName } : {},
@@ -2365,16 +2437,14 @@ async function modifyChart(client, queryEngine, input, options, signal) {
     finalSql = queryResponse.sql;
     paramMetadata = Array.isArray(queryResponse.params) ? queryResponse.params : [];
     finalParams = queryEngine.mapGeneratedParams(paramMetadata);
-    if (pipeline === "v2") {
-      applyDateRangeOverrides(
-        input.sqlModifications?.dateRange,
-        finalParams,
-        paramMetadata
-      );
-    }
+    applyDateRangeOverrides(
+      input.sqlModifications?.dateRange,
+      finalParams,
+      paramMetadata
+    );
     rationale = queryResponse.rationale;
     queryId = queryResponse.queryId;
-    sqlChanged = finalSql !== input.sql;
+    sqlChanged = finalSql !== currentSql;
   }
   const execution = await queryEngine.validateAndExecute(
     finalSql,
@@ -2589,6 +2659,9 @@ function resolveAttachEnforceTenantIsolation(tenantFieldName, enforceTenantIsola
   return tenantFieldName ? true : void 0;
 }
 var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
+  client;
+  queryEngine;
+  supportedChartTypes;
   /**
    * @param workspaceId - Workspace UUID (same value as your org in the dashboard). Passed to the API as JWT claim `organizationId`.
    */
@@ -2819,13 +2892,32 @@ var QueryPanelSdkAPI = class _QueryPanelSdkAPI {
       throw new Error("tenantId is required");
     }
     const databaseName = input.database ?? "db";
-    const params = input.params ?? {};
+    let sql = input.sql;
+    let params = input.params ?? {};
+    if (input.queryId) {
+      const resolved = await resolveQuery(
+        this.client,
+        this.queryEngine,
+        input.queryId,
+        { tenantId }
+      );
+      sql = resolved.sql;
+      params = resolved.params;
+    }
+    if (!sql) {
+      throw new Error("Either queryId or sql is required");
+    }
     const result = await this.queryEngine.validateAndExecute(
-      input.sql,
+      sql,
       params,
       databaseName,
       tenantId
     );
+    if (input.queryId) {
+      await markQueryExecuted(this.client, input.queryId, {
+        tenantId
+      });
+    }
     return { rows: result.rows, fields: result.fields };
   }
   // VizSpec generation