@querypanel/node-sdk 1.0.28 → 1.0.29

package/dist/index.d.ts

@@ -1,11 +1,3 @@
-import { QueryParams, DataFormat } from '@clickhouse/client';
-
-/**
- * Simplified schema types aligned with backend IngestRequest format
- * Following Ousterhout's principle: "Define errors out of existence"
- * - Removed indexes, constraints, foreign keys, statistics
- * - Only collect what the backend needs for vectorization
- */
 type DatabaseKind = "clickhouse" | "postgres" | string;
 interface DatabaseIdentifier {
     kind: DatabaseKind;
@@ -13,24 +5,66 @@ interface DatabaseIdentifier {
     schema?: string;
     version?: string;
 }
+interface ColumnStatistics {
+    compressedBytes?: number;
+    uncompressedBytes?: number;
+    distinctValues?: number;
+}
 interface ColumnSchema {
     name: string;
     type: string;
     rawType?: string;
-    isPrimaryKey: boolean;
+    nullable: boolean;
+    defaultKind?: string;
+    defaultExpression?: string;
     comment?: string;
+    isPrimaryKey: boolean;
+    isForeignKey: boolean;
+    foreignKeyTable?: string;
+    foreignKeyColumn?: string;
+    maxLength?: number;
+    precision?: number;
+    scale?: number;
+    codec?: string;
+    ttlExpression?: string;
+    statistics?: ColumnStatistics;
+}
+interface IndexSchema {
+    name: string;
+    columns: string[];
+    unique: boolean;
+    type: string;
+    definition?: string;
+}
+interface ConstraintSchema {
+    name: string;
+    type: "PRIMARY KEY" | "FOREIGN KEY" | "UNIQUE" | "CHECK" | string;
+    columns: string[];
+    referencedTable?: string;
+    referencedColumns?: string[];
+    definition?: string;
+}
+interface TableStatistics {
+    totalRows?: number;
+    totalBytes?: number;
+    uncompressedBytes?: number;
 }
 interface TableSchema {
     name: string;
     schema: string;
     type: "table" | "view" | string;
+    engine?: string;
     comment?: string;
+    statistics?: TableStatistics;
     columns: ColumnSchema[];
+    indexes: IndexSchema[];
+    constraints: ConstraintSchema[];
 }
 interface SchemaIntrospection {
     db: DatabaseIdentifier;
     tables: TableSchema[];
     introspectedAt: string;
+    metadata?: Record<string, unknown>;
 }
 interface IntrospectOptions {
     /** Optional allow-list of table names to introspect (schema-qualified or bare). */
@@ -74,11 +108,17 @@ interface DatabaseAdapter {
     close?(): Promise<void>;
 }
 
+type QueryParams = {
+    query: string;
+    format?: string;
+};
+type ClickHouseSettings = Record<string, unknown>;
+type Row = Record<string, unknown>;
 interface ClickHouseAdapterOptions {
     /** Optional logical database name used in introspection metadata. */
     database?: string;
     /** Override the default response format used for query execution. */
-    defaultFormat?: DataFormat;
+    defaultFormat?: QueryParams["format"];
     /**
      * Optional database kind label. Defaults to "clickhouse" but allows
      * sub-classing/custom branding if needed.
@@ -94,12 +134,10 @@ interface ClickHouseAdapterOptions {
 type ClickHouseQueryResult = {
     json: () => Promise<unknown>;
 };
-type ClickHouseClientFn = (params: QueryParams) => Promise<ClickHouseQueryResult | Array<Record<string, unknown>> | Record<string, unknown>[]>;
-/**
- * Simplified ClickHouse adapter following IngestRequest format
- * Removed: indexes, constraints, statistics
- * Kept only: tables, columns (name, type, isPrimaryKey, comment)
- */
+type ClickHouseClientFn = (params: QueryParams & {
+    query_params?: Record<string, unknown>;
+    clickhouse_settings?: ClickHouseSettings;
+}) => Promise<ClickHouseQueryResult | Array<Record<string, unknown>> | Row[]>;
 declare class ClickHouseAdapter implements DatabaseAdapter {
     private readonly clientFn;
     private readonly databaseName;
@@ -110,11 +148,11 @@ declare class ClickHouseAdapter implements DatabaseAdapter {
     execute(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<DatabaseExecutionResult>;
     validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
     getDialect(): "clickhouse";
+    introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
     /**
-     * Simplified introspection: only collect table/column metadata for IngestRequest
-     * No indexes, constraints, or statistics
+     * Validate that the SQL query only references allowed tables.
+     * This is a basic validation that extracts table-like patterns from the query.
      */
-    introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
     private validateQueryTables;
     close(): Promise<void>;
     private query;
@@ -141,11 +179,6 @@ interface PostgresAdapterOptions {
      */
     allowedTables?: string[];
 }
-/**
- * Simplified PostgreSQL adapter following IngestRequest format
- * Removed: indexes, constraints, foreign keys, statistics
- * Kept only: tables, columns (name, type, isPrimaryKey, comment)
- */
 declare class PostgresAdapter implements DatabaseAdapter {
     private readonly clientFn;
     private readonly databaseName;
@@ -154,24 +187,112 @@ declare class PostgresAdapter implements DatabaseAdapter {
     private readonly allowedTables?;
     constructor(clientFn: PostgresClientFn, options?: PostgresAdapterOptions);
     execute(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<DatabaseExecutionResult>;
+    /**
+     * Validate that the SQL query only references allowed tables.
+     * This is a basic validation that extracts table-like patterns from the query.
+     */
     private validateQueryTables;
     /**
      * Convert named params to positional array for PostgreSQL
      * PostgreSQL expects $1, $2, $3 in SQL and an array of values [val1, val2, val3]
+     *
+     * Supports two formats:
+     * 1. Numeric keys: { '1': 'value1', '2': 'value2' } - maps directly to $1, $2
+     * 2. Named keys: { 'tenant_id': 'value' } - values extracted in alphabetical order
+     * 3. Mixed: { '1': 'value1', 'tenant_id': 'value' } - numeric keys first, then named keys
      */
     private convertNamedToPositionalParams;
     validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
     getDialect(): "postgres";
-    /**
-     * Simplified introspection: only collect table/column metadata for IngestRequest
-     * No indexes, constraints, or statistics
-     */
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
 }
 
 type ParamValue = string | number | boolean | string[] | number[];
 type ParamRecord = Record<string, ParamValue>;
-
+interface ContextDocument {
+    source?: string;
+    pageContent: string;
+    metadata?: Record<string, unknown>;
+    score?: number;
+}
+interface ChartEnvelope {
+    vegaLiteSpec: Record<string, unknown> | null;
+    notes: string | null;
+}
+interface AskOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+    database?: string;
+    lastError?: string;
+    previousSql?: string;
+    maxRetry?: number;
+    chartMaxRetries?: number;
+    disableAutoSync?: boolean;
+}
+interface AskResponse {
+    sql: string;
+    params: ParamRecord;
+    paramMetadata: Array<Record<string, unknown>>;
+    rationale?: string;
+    dialect: string;
+    queryId?: string;
+    rows: Array<Record<string, unknown>>;
+    fields: string[];
+    chart: ChartEnvelope;
+    context?: ContextDocument[];
+}
+interface SchemaSyncOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+    tables?: string[];
+    force?: boolean;
+}
+interface KnowledgeBaseAnnotation {
+    id: string;
+    organization_id: string;
+    target_identifier: string;
+    content: string;
+    created_by: string;
+    updated_by: string;
+    created_at: string;
+    updated_at: string;
+}
+interface KnowledgeBaseAnnotationInput {
+    targetIdentifier: string;
+    content: string;
+    userId: string;
+    tenantId?: string;
+}
+interface KnowledgeBaseChunkTable {
+    table_name: string;
+    gold_sql?: Array<{
+        sql: string;
+        description?: string;
+        name?: string;
+    }>;
+    glossary?: Array<{
+        term: string;
+        definition: string;
+    }>;
+}
+interface KnowledgeBaseChunkRequest {
+    database: string;
+    dialect: string;
+    tables: KnowledgeBaseChunkTable[];
+    tenantId?: string;
+}
+interface KnowledgeBaseChunksResponse {
+    success: boolean;
+    message: string;
+    chunks: {
+        total: number;
+        gold_sql: number;
+        glossary: number;
+        chunks_with_annotations: number;
+    };
+}
 interface SdkChart {
     id: string;
     title: string;
@@ -186,7 +307,19 @@ interface SdkChart {
     created_at: string | null;
     updated_at: string | null;
     active?: boolean;
-    target_db?: string | null;
+    database?: string | null;
+}
+interface SdkActiveChart {
+    id: string;
+    chart_id: string;
+    order: number | null;
+    meta: Record<string, unknown> | null;
+    organization_id: string | null;
+    tenant_id: string | null;
+    user_id: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+    chart?: SdkChart | null;
 }
 interface ChartCreateInput {
     title: string;
@@ -195,7 +328,7 @@ interface ChartCreateInput {
     sql_params?: Record<string, unknown>;
     vega_lite_spec: Record<string, unknown>;
     query_id?: string;
-    target_db?: string;
+    database?: string;
 }
 interface ChartUpdateInput {
     title?: string;
@@ -203,7 +336,17 @@ interface ChartUpdateInput {
     sql?: string;
     sql_params?: Record<string, unknown>;
     vega_lite_spec?: Record<string, unknown>;
-    target_db?: string;
+    database?: string;
+}
+interface ActiveChartCreateInput {
+    chart_id: string;
+    order?: number;
+    meta?: Record<string, unknown>;
+}
+interface ActiveChartUpdateInput {
+    chart_id?: string;
+    order?: number;
+    meta?: Record<string, unknown>;
 }
 interface PaginationQuery {
     page?: number;
@@ -236,33 +379,9 @@ interface ChartListOptions {
     updatedTo?: string;
     includeData?: boolean;
 }
-
-interface SdkActiveChart {
-    id: string;
-    chart_id: string;
-    order: number | null;
-    meta: Record<string, unknown> | null;
-    organization_id: string | null;
-    tenant_id: string | null;
-    user_id: string | null;
-    created_at: string | null;
-    updated_at: string | null;
-    chart?: SdkChart | null;
-}
-interface ActiveChartCreateInput {
-    chart_id: string;
-    order?: number;
-    meta?: Record<string, unknown>;
-}
-interface ActiveChartUpdateInput {
-    chart_id?: string;
-    order?: number;
-    meta?: Record<string, unknown>;
-}
 interface ActiveChartListOptions extends ChartListOptions {
     withData?: boolean;
 }
-
 interface IngestResponse {
     success: boolean;
     message: string;
@@ -273,56 +392,24 @@ interface IngestResponse {
     drift_detected?: boolean;
     skipped?: boolean;
 }
-interface SchemaSyncOptions {
+interface RequestOptions {
     tenantId?: string;
     userId?: string;
     scopes?: string[];
-    tables?: string[];
 }
-
-interface ContextDocument {
-    source?: string;
-    pageContent: string;
-    metadata?: Record<string, unknown>;
-    score?: number;
-}
-interface ChartEnvelope {
-    vegaLiteSpec: Record<string, unknown> | null;
-    notes: string | null;
-}
-interface AskOptions {
-    tenantId?: string;
-    userId?: string;
-    scopes?: string[];
-    database?: string;
-    lastError?: string;
-    previousSql?: string;
-    maxRetry?: number;
-    chartMaxRetries?: number;
-}
-interface AskResponse {
-    sql: string;
-    params: ParamRecord;
-    paramMetadata: Array<Record<string, unknown>>;
-    rationale?: string;
-    dialect: string;
-    queryId?: string;
-    rows: Array<Record<string, unknown>>;
-    fields: string[];
-    chart: ChartEnvelope;
-    context?: ContextDocument[];
-    attempts?: number;
-}
-declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
-
-/**
- * Main SDK class - Thin orchestrator
- * Delegates to deep modules (ApiClient, QueryEngine, route modules)
- * Following Ousterhout's principle: "Simple interface hiding complexity"
- */
 declare class QueryPanelSdkAPI {
-    private readonly client;
-    private readonly queryEngine;
+    private readonly baseUrl;
+    private readonly privateKey;
+    private readonly organizationId;
+    private readonly defaultTenantId?;
+    private readonly additionalHeaders?;
+    private readonly fetchImpl;
+    private cachedPrivateKey?;
+    private databases;
+    private databaseMetadata;
+    private defaultDatabase?;
+    private lastSyncHashes;
+    private syncedDatabases;
     constructor(baseUrl: string, privateKey: string, organizationId: string, options?: {
         defaultTenantId?: string;
         additionalHeaders?: Record<string, string>;
@@ -342,47 +429,40 @@ declare class QueryPanelSdkAPI {
         enforceTenantIsolation?: boolean;
     }): void;
     attachDatabase(name: string, adapter: DatabaseAdapter): void;
-    introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
     syncSchema(databaseName: string, options: SchemaSyncOptions, signal?: AbortSignal): Promise<IngestResponse>;
+    ingestKnowledgeBaseChunks(payload: KnowledgeBaseChunkRequest, options?: RequestOptions, signal?: AbortSignal): Promise<KnowledgeBaseChunksResponse>;
+    introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
     ask(question: string, options: AskOptions, signal?: AbortSignal): Promise<AskResponse>;
-    createChart(body: ChartCreateInput, options?: {
-        tenantId?: string;
-        userId?: string;
-        scopes?: string[];
-    }, signal?: AbortSignal): Promise<SdkChart>;
+    upsertAnnotation(input: KnowledgeBaseAnnotationInput, options?: RequestOptions, signal?: AbortSignal): Promise<KnowledgeBaseAnnotation>;
+    listAnnotations(options?: RequestOptions, signal?: AbortSignal): Promise<KnowledgeBaseAnnotation[]>;
+    getAnnotation(targetIdentifier: string, options?: RequestOptions, signal?: AbortSignal): Promise<KnowledgeBaseAnnotation | null>;
+    deleteAnnotation(targetIdentifier: string, options?: RequestOptions, signal?: AbortSignal): Promise<void>;
+    createChart(body: ChartCreateInput, options?: RequestOptions, signal?: AbortSignal): Promise<SdkChart>;
     listCharts(options?: ChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkChart>>;
-    getChart(id: string, options?: {
-        tenantId?: string;
-        userId?: string;
-        scopes?: string[];
-    }, signal?: AbortSignal): Promise<SdkChart>;
-    updateChart(id: string, body: ChartUpdateInput, options?: {
-        tenantId?: string;
-        userId?: string;
-        scopes?: string[];
-    }, signal?: AbortSignal): Promise<SdkChart>;
-    deleteChart(id: string, options?: {
-        tenantId?: string;
-        userId?: string;
-        scopes?: string[];
-    }, signal?: AbortSignal): Promise<void>;
-    createActiveChart(body: ActiveChartCreateInput, options?: {
-        tenantId?: string;
-        userId?: string;
-        scopes?: string[];
-    }, signal?: AbortSignal): Promise<SdkActiveChart>;
+    getChart(id: string, options?: RequestOptions, signal?: AbortSignal): Promise<SdkChart>;
+    updateChart(id: string, body: ChartUpdateInput, options?: RequestOptions, signal?: AbortSignal): Promise<SdkChart>;
+    deleteChart(id: string, options?: RequestOptions, signal?: AbortSignal): Promise<void>;
+    createActiveChart(body: ActiveChartCreateInput, options?: RequestOptions, signal?: AbortSignal): Promise<SdkActiveChart>;
     listActiveCharts(options?: ActiveChartListOptions, signal?: AbortSignal): Promise<PaginatedResponse<SdkActiveChart>>;
     getActiveChart(id: string, options?: ActiveChartListOptions, signal?: AbortSignal): Promise<SdkActiveChart>;
-    updateActiveChart(id: string, body: ActiveChartUpdateInput, options?: {
-        tenantId?: string;
-        userId?: string;
-        scopes?: string[];
-    }, signal?: AbortSignal): Promise<SdkActiveChart>;
-    deleteActiveChart(id: string, options?: {
-        tenantId?: string;
-        userId?: string;
-        scopes?: string[];
-    }, signal?: AbortSignal): Promise<void>;
+    updateActiveChart(id: string, body: ActiveChartUpdateInput, options?: RequestOptions, signal?: AbortSignal): Promise<SdkActiveChart>;
+    deleteActiveChart(id: string, options?: RequestOptions, signal?: AbortSignal): Promise<void>;
+    private getDatabase;
+    private ensureSchemasSynced;
+    private resolveTenantId;
+    private headers;
+    private request;
+    private get;
+    private post;
+    private put;
+    private delete;
+    private generateJWT;
+    private buildSchemaRequest;
+    private hashSchemaRequest;
+    private mapGeneratedParams;
+    private ensureTenantIsolation;
+    private runSafeQueryOnClient;
 }
+declare function anonymizeResults(rows: Array<Record<string, unknown>>): Array<Record<string, string>>;
 
-export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AskOptions, type AskResponse, type ChartCreateInput, type ChartEnvelope, type ChartListOptions, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type IngestResponse, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryPanelSdkAPI, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, anonymizeResults };
+export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AskOptions, type AskResponse, type ChartCreateInput, type ChartEnvelope, type ChartListOptions, type ChartUpdateInput, ClickHouseAdapter, type ClickHouseAdapterOptions, type ClickHouseClientFn, type ContextDocument, type DatabaseAdapter, type DatabaseDialect, type IngestResponse, type KnowledgeBaseAnnotation, type KnowledgeBaseAnnotationInput, type KnowledgeBaseChunkRequest, type KnowledgeBaseChunkTable, type KnowledgeBaseChunksResponse, type PaginatedResponse, type PaginationInfo, type PaginationQuery, type ParamRecord, type ParamValue, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryPanelSdkAPI, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, anonymizeResults };