@querypanel/node-sdk 1.0.43 → 1.0.45

package/dist/index.d.ts

@@ -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>;
 
@@ -208,11 +249,11 @@ interface ChartUpdateInput {
     spec_type?: 'vega-lite' | 'vizspec';
     target_db?: string;
 }
-interface PaginationQuery {
+interface PaginationQuery$1 {
     page?: number;
     limit?: number;
 }
-interface PaginationInfo {
+interface PaginationInfo$1 {
     page: number;
     limit: number;
     total: number;
@@ -220,15 +261,15 @@ interface PaginationInfo {
     hasNext: boolean;
     hasPrev: boolean;
 }
-interface PaginatedResponse<T> {
+interface PaginatedResponse$1<T> {
     data: T[];
-    pagination: PaginationInfo;
+    pagination: PaginationInfo$1;
 }
 interface ChartListOptions {
     tenantId?: string;
     userId?: string;
     scopes?: string[];
-    pagination?: PaginationQuery;
+    pagination?: PaginationQuery$1;
     sortBy?: "title" | "user_id" | "created_at" | "updated_at";
     sortDir?: "asc" | "desc";
     title?: string;
@@ -372,42 +413,90 @@ interface MetricSpec extends VizSpecBase {
 }
 type VizSpec = ChartSpec | TableSpec | MetricSpec;
 
+/**
+ * Context document returned by the query pipeline.
+ */
 interface ContextDocument {
+    /** Optional source identifier for the document. */
     source?: string;
+    /** Raw document content or excerpt. */
     pageContent: string;
+    /** Additional metadata attached to the document. */
     metadata?: Record<string, unknown>;
+    /** Optional relevance score from retrieval. */
     score?: number;
 }
+/**
+ * Chart payload returned with query results.
+ */
 interface ChartEnvelope {
+    /** Vega-Lite spec when specType is "vega-lite". */
     vegaLiteSpec?: Record<string, unknown> | null;
+    /** VizSpec payload when specType is "vizspec". */
     vizSpec?: VizSpec | null;
-    specType: 'vega-lite' | 'vizspec';
+    /** Chart specification type. */
+    specType: "vega-lite" | "vizspec";
+    /** Optional chart generation notes or errors. */
     notes: string | null;
 }
+/**
+ * Configuration options for query generation.
+ */
 interface AskOptions {
+    /** Tenant identifier for scoped access. */
     tenantId?: string;
+    /** Optional user identifier for audit/telemetry. */
     userId?: string;
+    /** Optional scopes to include in the auth token. */
     scopes?: string[];
+    /** Override the default database name. */
     database?: string;
+    /** Previous error message for retry context. */
     lastError?: string;
+    /** Previous SQL statement for retry context. */
     previousSql?: string;
+    /** Maximum number of retry attempts on execution failure. */
     maxRetry?: number;
+    /** Maximum number of retries for chart generation. */
     chartMaxRetries?: number;
-    chartType?: 'vega-lite' | 'vizspec';
+    /** Choose chart generation method. */
+    chartType?: "vega-lite" | "vizspec";
+    /**
+     * QueryPanel session ID for context-aware follow-ups.
+     * Use this to reuse a previously returned session for follow-up prompts.
+     */
+    querypanelSessionId?: string;
 }
+/**
+ * Response returned after executing a query.
+ */
 interface AskResponse {
+    /** Generated SQL statement. */
     sql: string;
+    /** Parameter values for the generated SQL. */
     params: ParamRecord;
+    /** Raw parameter metadata from the backend. */
     paramMetadata: Array<Record<string, unknown>>;
+    /** Optional reasoning for SQL generation. */
     rationale?: string;
+    /** SQL dialect selected by the backend. */
     dialect: string;
+    /** Optional query identifier for traceability. */
     queryId?: string;
+    /** Result rows returned by the query execution. */
     rows: Array<Record<string, unknown>>;
+    /** Column names for returned rows. */
     fields: string[];
+    /** Generated chart payload. */
     chart: ChartEnvelope;
+    /** Optional context documents used for query generation. */
     context?: ContextDocument[];
+    /** Number of attempts used for execution. */
     attempts?: number;
+    /** Target database name resolved by the backend or engine. */
     target_db?: string;
+    /** QueryPanel session ID for follow-up queries. */
+    querypanelSessionId?: string;
 }
 declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
 
@@ -563,6 +652,93 @@ interface ChartModifyResponse extends AskResponse {
     };
 }
 
+/**
+ * A single session turn containing the question and optional SQL output.
+ */
+interface SdkSessionTurn {
+    id: string;
+    session_id: string;
+    turn_index: number;
+    question: string;
+    sql: string | null;
+    rationale: string | null;
+    row_count: number | null;
+    fields: string[] | null;
+    error: string | null;
+    created_at: string;
+}
+/**
+ * Session metadata with optional turn history.
+ */
+interface SdkSession {
+    id: string;
+    session_id: string;
+    organization_id: string;
+    tenant_id: string | null;
+    user_id: string | null;
+    title: string | null;
+    created_at: string;
+    updated_at: string;
+    turns?: SdkSessionTurn[];
+}
+/**
+ * Fields allowed when updating a session.
+ */
+interface SessionUpdateInput {
+    title?: string;
+}
+/**
+ * Pagination settings for list endpoints.
+ */
+interface PaginationQuery {
+    page?: number;
+    limit?: number;
+}
+/**
+ * Pagination metadata returned by list endpoints.
+ */
+interface PaginationInfo {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/**
+ * Generic paginated response wrapper.
+ */
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: PaginationInfo;
+}
+/**
+ * Options for listing sessions with filters and pagination.
+ */
+interface SessionListOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+    pagination?: PaginationQuery;
+    sortBy?: "title" | "user_id" | "created_at" | "updated_at";
+    sortDir?: "asc" | "desc";
+    title?: string;
+    userFilter?: string;
+    createdFrom?: string;
+    createdTo?: string;
+    updatedFrom?: string;
+    updatedTo?: string;
+}
+/**
+ * Options for retrieving a session.
+ */
+interface SessionGetOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+    includeTurns?: boolean;
+}
+
 interface VizSpecGenerateInput {
     question: string;
     sql: string;
@@ -659,6 +835,7 @@ declare class QueryPanelSdkAPI {
      * 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", {
@@ -802,7 +979,81 @@ declare class QueryPanelSdkAPI {
      * });
      * ```
      */
-    listCharts(options?: ChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkChart>>;
+    listCharts(options?: ChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse$1<SdkChart>>;
+    /**
+     * 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",
+     * });
+     * ```
+     */
+    listSessions(options?: SessionListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkSession>>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    getSession(sessionId: string, options?: SessionGetOptions, signal?: AbortSignal): Promise<SdkSession>;
+    /**
+     * 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" },
+     * );
+     * ```
+     */
+    updateSession(sessionId: string, body: SessionUpdateInput, options?: {
+        tenantId?: string;
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkSession>;
+    /**
+     * 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" });
+     * ```
+     */
+    deleteSession(sessionId: string, options?: {
+        tenantId?: string;
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<void>;
     /**
      * Retrieves a single chart by ID with live data.
      *
@@ -914,7 +1165,7 @@ declare class QueryPanelSdkAPI {
      * });
      * ```
      */
-    listActiveCharts(options?: ActiveChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkActiveChart>>;
+    listActiveCharts(options?: ActiveChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse$1<SdkActiveChart>>;
     /**
      * Retrieves a single active chart by ID.
      *
@@ -977,4 +1228,4 @@ declare class QueryPanelSdkAPI {
     }, signal?: AbortSignal): Promise<void>;
 }
 
-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, QueryPanelSdkAPI, 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 };
+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$1 as PaginatedResponse, type PaginationInfo$1 as PaginationInfo, type PaginationQuery$1 as 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 SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecResponse, anonymizeResults };