@querypanel/node-sdk 1.0.23 → 1.0.25

package/dist/index.d.ts

@@ -0,0 +1,468 @@
+type DatabaseKind = "clickhouse" | "postgres" | string;
+interface DatabaseIdentifier {
+    kind: DatabaseKind;
+    name: string;
+    schema?: string;
+    version?: string;
+}
+interface ColumnStatistics {
+    compressedBytes?: number;
+    uncompressedBytes?: number;
+    distinctValues?: number;
+}
+interface ColumnSchema {
+    name: string;
+    type: string;
+    rawType?: string;
+    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). */
+    tables?: string[];
+}
+
+type DatabaseDialect = "clickhouse" | "postgres" | "mysql";
+interface DatabaseExecutionResult {
+    fields: string[];
+    rows: Array<Record<string, unknown>>;
+}
+/**
+ * Database adapter interface for abstracting database-specific operations.
+ * Allows the SDK to work with multiple database types.
+ */
+interface DatabaseAdapter {
+    /**
+     * Execute a SQL query and return results
+     * @param sql - The SQL query to execute
+     * @param params - Optional query parameters for parameterized queries
+     */
+    execute(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<DatabaseExecutionResult>;
+    /**
+     * Validate SQL query (e.g., using EXPLAIN)
+     * Throws an error if the SQL is invalid
+     * @param sql - The SQL query to validate
+     * @param params - Optional query parameters for parameterized queries
+     */
+    validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
+    /**
+     * Introspect database schema metadata
+     */
+    introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
+    /**
+     * Get the database dialect/type
+     */
+    getDialect(): DatabaseDialect;
+    /**
+     * Optional: Close/cleanup database connection
+     */
+    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?: QueryParams["format"];
+    /**
+     * Optional database kind label. Defaults to "clickhouse" but allows
+     * sub-classing/custom branding if needed.
+     */
+    kind?: SchemaIntrospection["db"]["kind"];
+    /**
+     * Optional allow-list of table names.
+     * When specified, introspection and queries are restricted to these tables only.
+     * ClickHouse tables are not schema-qualified, so just provide table names.
+     */
+    allowedTables?: string[];
+}
+type ClickHouseQueryResult = {
+    json: () => Promise<unknown>;
+};
+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;
+    private readonly defaultFormat;
+    private readonly kind;
+    private readonly allowedTables?;
+    constructor(clientFn: ClickHouseClientFn, options?: ClickHouseAdapterOptions);
+    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>;
+    /**
+     * Validate that the SQL query only references allowed tables.
+     * This is a basic validation that extracts table-like patterns from the query.
+     */
+    private validateQueryTables;
+    close(): Promise<void>;
+    private query;
+    private extractRows;
+}
+
+interface PostgresQueryResult {
+    rows: Array<Record<string, unknown>>;
+    fields: Array<{
+        name: string;
+    }>;
+}
+type PostgresClientFn = (sql: string, params?: unknown[]) => Promise<PostgresQueryResult>;
+interface PostgresAdapterOptions {
+    /** Logical database name used in introspection metadata. */
+    database?: string;
+    /** Schema to assume when a table is provided without qualification. */
+    defaultSchema?: string;
+    /** Optional database kind label. Defaults to "postgres". */
+    kind?: SchemaIntrospection["db"]["kind"];
+    /**
+     * Optional allow-list of table names (schema-qualified or bare).
+     * When specified, introspection and queries are restricted to these tables only.
+     */
+    allowedTables?: string[];
+}
+declare class PostgresAdapter implements DatabaseAdapter {
+    private readonly clientFn;
+    private readonly databaseName;
+    private readonly defaultSchema;
+    private readonly kind;
+    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";
+    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;
+    description: string | null;
+    sql: string;
+    sql_params: Record<string, unknown> | null;
+    vega_lite_spec: Record<string, unknown>;
+    query_id: string | null;
+    organization_id: string | null;
+    tenant_id: string | null;
+    user_id: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+    active?: boolean;
+    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;
+    description?: string;
+    sql: string;
+    sql_params?: Record<string, unknown>;
+    vega_lite_spec: Record<string, unknown>;
+    query_id?: string;
+    database?: string;
+}
+interface ChartUpdateInput {
+    title?: string;
+    description?: string;
+    sql?: string;
+    sql_params?: Record<string, unknown>;
+    vega_lite_spec?: Record<string, unknown>;
+    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;
+    limit?: number;
+}
+interface PaginationInfo {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: PaginationInfo;
+}
+interface ChartListOptions {
+    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;
+    includeData?: boolean;
+}
+interface ActiveChartListOptions extends ChartListOptions {
+    withData?: boolean;
+}
+interface IngestResponse {
+    success: boolean;
+    message: string;
+    chunks: number;
+    chunks_with_annotations: number;
+    schema_id?: string;
+    schema_hash?: string;
+    drift_detected?: boolean;
+    skipped?: boolean;
+}
+interface RequestOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+}
+declare class QueryPanelSdkAPI {
+    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>;
+        fetch?: typeof fetch;
+    });
+    attachClickhouse(name: string, clientFn: ClickHouseClientFn, options?: ClickHouseAdapterOptions & {
+        description?: string;
+        tags?: string[];
+        tenantFieldName?: string;
+        tenantFieldType?: string;
+        enforceTenantIsolation?: boolean;
+    }): void;
+    attachPostgres(name: string, clientFn: PostgresClientFn, options?: PostgresAdapterOptions & {
+        description?: string;
+        tags?: string[];
+        tenantFieldName?: string;
+        enforceTenantIsolation?: boolean;
+    }): void;
+    attachDatabase(name: string, adapter: DatabaseAdapter): void;
+    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>;
+    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?: 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?: 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 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 };