@querypanel/node-sdk 1.0.42 → 1.0.44

package/dist/index.d.cts

@@ -169,6 +169,47 @@ declare class PostgresAdapter implements DatabaseAdapter {
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
 }
 
+/**
+ * Error codes for the query pipeline
+ * These match the server-side error codes returned in API responses
+ */
+declare const QueryErrorCode: {
+    readonly MODERATION_FAILED: "MODERATION_FAILED";
+    readonly RELEVANCE_CHECK_FAILED: "RELEVANCE_CHECK_FAILED";
+    readonly SECURITY_CHECK_FAILED: "SECURITY_CHECK_FAILED";
+    readonly SQL_GENERATION_FAILED: "SQL_GENERATION_FAILED";
+    readonly SQL_VALIDATION_FAILED: "SQL_VALIDATION_FAILED";
+    readonly CONTEXT_RETRIEVAL_FAILED: "CONTEXT_RETRIEVAL_FAILED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+};
+type QueryErrorCode = (typeof QueryErrorCode)[keyof typeof QueryErrorCode];
+/**
+ * Error thrown when the query pipeline fails
+ */
+declare class QueryPipelineError extends Error {
+    readonly code: QueryErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: QueryErrorCode, details?: Record<string, unknown> | undefined);
+    /**
+     * Check if this is a moderation error
+     */
+    isModeration(): boolean;
+    /**
+     * Check if this is a relevance error (question not related to database)
+     */
+    isRelevanceError(): boolean;
+    /**
+     * Check if this is a security error (SQL injection, prompt injection, etc.)
+     */
+    isSecurityError(): boolean;
+    /**
+     * Check if this is any guardrail error (relevance or security)
+     */
+    isGuardrailError(): boolean;
+}
+
 type ParamValue = string | number | boolean | string[] | number[];
 type ParamRecord = Record<string, ParamValue>;
 
@@ -381,7 +422,7 @@ interface ContextDocument {
 interface ChartEnvelope {
     vegaLiteSpec?: Record<string, unknown> | null;
     vizSpec?: VizSpec | null;
-    specType: 'vega-lite' | 'vizspec';
+    specType: "vega-lite" | "vizspec";
     notes: string | null;
 }
 interface AskOptions {
@@ -393,7 +434,7 @@ interface AskOptions {
     previousSql?: string;
     maxRetry?: number;
     chartMaxRetries?: number;
-    chartType?: 'vega-lite' | 'vizspec';
+    chartType?: "vega-lite" | "vizspec";
 }
 interface AskResponse {
     sql: string;
@@ -411,6 +452,158 @@ interface AskResponse {
 }
 declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
 
+/**
+ * Simplified field reference for modification inputs.
+ * More ergonomic than the full AxisField type.
+ */
+interface AxisFieldInput {
+    /** Column name from the SQL result */
+    field: string;
+    /** Human-friendly label for the axis */
+    label?: string;
+    /** Field data type */
+    type?: FieldType;
+    /** Aggregation operation (e.g., 'sum', 'avg') */
+    aggregate?: AggregateOp;
+    /** Time unit for temporal fields */
+    timeUnit?: TimeUnit;
+    /** Value formatting options */
+    format?: ValueFormat;
+}
+/**
+ * Simplified field reference for series/grouping fields.
+ */
+interface FieldRefInput {
+    /** Column name from the SQL result */
+    field: string;
+    /** Human-friendly label */
+    label?: string;
+    /** Field data type */
+    type?: FieldType;
+}
+/**
+ * Date range specification for SQL modifications.
+ */
+interface DateRangeInput {
+    /** Start date in ISO format (e.g., '2024-01-01') */
+    from?: string;
+    /** End date in ISO format (e.g., '2024-12-31') */
+    to?: string;
+}
+/**
+ * SQL modification options that trigger query regeneration.
+ * When any of these are provided, a new ask() call is made.
+ */
+interface SqlModifications {
+    /**
+     * Direct SQL override. When provided, this SQL is executed directly
+     * without calling the query generation endpoint.
+     */
+    customSql?: string;
+    /**
+     * Change the time granularity of the query.
+     * Triggers SQL regeneration with hints about the desired grouping.
+     */
+    timeGranularity?: TimeUnit;
+    /**
+     * Filter the query to a specific date range.
+     * Triggers SQL regeneration with date filter hints.
+     */
+    dateRange?: DateRangeInput;
+    /**
+     * Additional natural language instructions to modify the query.
+     * These are appended to the original question as hints.
+     * Example: "exclude cancelled orders" or "only show top 10"
+     */
+    additionalInstructions?: string;
+}
+/**
+ * Visualization modification options that don't affect the SQL.
+ * These changes only affect how the chart is rendered.
+ */
+interface VizModifications {
+    /** Change the chart type (line, bar, area, scatter, pie) */
+    chartType?: ChartType;
+    /** Configure the X axis field and settings */
+    xAxis?: AxisFieldInput;
+    /** Configure the Y axis field(s) and settings */
+    yAxis?: AxisFieldInput | AxisFieldInput[];
+    /** Configure the series/grouping field for multi-series charts */
+    series?: FieldRefInput;
+    /** Stacking mode for multi-series charts */
+    stacking?: StackingMode;
+    /** Maximum number of rows to display in the chart */
+    limit?: number;
+}
+/**
+ * Input for the modifyChart() method.
+ * Accepts chart data from either ask() responses or saved charts.
+ */
+interface ChartModifyInput {
+    /**
+     * The SQL query to modify or re-execute.
+     * From ask() response: response.sql
+     * From saved chart: chart.sql
+     */
+    sql: string;
+    /**
+     * The original natural language question.
+     * Used when regenerating SQL with modifications.
+     */
+    question: string;
+    /**
+     * The database to execute the query against.
+     * From ask() response: response.target_db
+     * From saved chart: chart.target_db
+     */
+    database: string;
+    /**
+     * Query parameters (optional).
+     * From ask() response: response.params
+     * From saved chart: chart.sql_params
+     */
+    params?: ParamRecord;
+    /**
+     * SQL modifications that trigger query regeneration.
+     * When provided, a new ask() call is made with modification hints.
+     */
+    sqlModifications?: SqlModifications;
+    /**
+     * Visualization modifications that don't affect the SQL.
+     * Applied during chart generation.
+     */
+    vizModifications?: VizModifications;
+}
+/**
+ * Options for the modifyChart() method.
+ */
+interface ChartModifyOptions {
+    /** Tenant ID for multi-tenant isolation */
+    tenantId?: string;
+    /** User ID for audit/tracking */
+    userId?: string;
+    /** Permission scopes */
+    scopes?: string[];
+    /** Maximum retry attempts for SQL generation */
+    maxRetry?: number;
+    /** Maximum retry attempts for chart generation */
+    chartMaxRetries?: number;
+    /** Chart generation method: 'vega-lite' or 'vizspec' */
+    chartType?: "vega-lite" | "vizspec";
+}
+/**
+ * Response from modifyChart(), extending AskResponse with modification metadata.
+ */
+interface ChartModifyResponse extends AskResponse {
+    /** Metadata about what was modified */
+    modified: {
+        /** Whether the SQL was changed (regenerated or custom) */
+        sqlChanged: boolean;
+        /** Whether visualization settings were applied */
+        vizChanged: boolean;
+    };
+}
+
 interface VizSpecGenerateInput {
     question: string;
     sql: string;
@@ -460,42 +653,364 @@ declare class QueryPanelSdkAPI {
     }): void;
     attachDatabase(name: string, adapter: DatabaseAdapter): void;
     introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
     syncSchema(databaseName: string, options: SchemaSyncOptions, signal?: AbortSignal): Promise<IngestResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
     ask(question: string, options: AskOptions, signal?: AbortSignal): Promise<AskResponse>;
+    /**
+     * 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" });
+     * ```
+     */
     generateVizSpec(input: VizSpecGenerateInput, options?: VizSpecGenerateOptions, signal?: AbortSignal): Promise<VizSpecResponse>;
+    /**
+     * 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" });
+     * ```
+     */
+    modifyChart(input: ChartModifyInput, options?: ChartModifyOptions, signal?: AbortSignal): Promise<ChartModifyResponse>;
+    /**
+     * 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" });
+     * ```
+     */
     createChart(body: ChartCreateInput, options?: {
         tenantId?: string;
         userId?: string;
         scopes?: string[];
     }, signal?: AbortSignal): Promise<SdkChart>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
     listCharts(options?: ChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkChart>>;
+    /**
+     * 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
+     * ```
+     */
     getChart(id: string, options?: {
         tenantId?: string;
         userId?: string;
         scopes?: string[];
     }, signal?: AbortSignal): Promise<SdkChart>;
+    /**
+     * 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" });
+     * ```
+     */
     updateChart(id: string, body: ChartUpdateInput, options?: {
         tenantId?: string;
         userId?: string;
         scopes?: string[];
     }, signal?: AbortSignal): Promise<SdkChart>;
+    /**
+     * 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" });
+     * ```
+     */
     deleteChart(id: string, options?: {
         tenantId?: string;
         userId?: string;
         scopes?: string[];
     }, signal?: AbortSignal): Promise<void>;
+    /**
+     * 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" });
+     * ```
+     */
     createActiveChart(body: ActiveChartCreateInput, options?: {
         tenantId?: string;
         userId?: string;
         scopes?: string[];
     }, signal?: AbortSignal): Promise<SdkActiveChart>;
+    /**
+     * 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);
+     * });
+     * ```
+     */
     listActiveCharts(options?: ActiveChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkActiveChart>>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
     getActiveChart(id: string, options?: ActiveChartListOptions, signal?: AbortSignal): Promise<SdkActiveChart>;
+    /**
+     * 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" });
+     * ```
+     */
     updateActiveChart(id: string, body: ActiveChartUpdateInput, options?: {
         tenantId?: string;
         userId?: string;
         scopes?: string[];
     }, signal?: AbortSignal): Promise<SdkActiveChart>;
+    /**
+     * 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" });
+     * ```
+     */
     deleteActiveChart(id: string, options?: {
         tenantId?: string;
         userId?: string;
@@ -503,4 +1018,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<void>;
 }
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AskOptions, type AskResponse, type AxisField, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type FieldRef, type FieldType, type IngestResponse, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryPanelSdkAPI, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type TableColumn, type TableEncoding, type TableSpec, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };
+export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, type ChartCreateInput, type ChartEncoding, type ChartEnvelope, type ChartListOptions, type ChartModifyInput, type ChartModifyOptions, type ChartModifyResponse, type ChartSpec, type ChartType, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, type MetricEncoding, type MetricField, type MetricSpec, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, QueryPipelineError, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };