@querypanel/node-sdk 1.0.26 → 1.0.28

package/dist/index.d.ts

@@ -0,0 +1,388 @@
+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;
+    name: string;
+    schema?: string;
+    version?: string;
+}
+interface ColumnSchema {
+    name: string;
+    type: string;
+    rawType?: string;
+    isPrimaryKey: boolean;
+    comment?: string;
+}
+interface TableSchema {
+    name: string;
+    schema: string;
+    type: "table" | "view" | string;
+    comment?: string;
+    columns: ColumnSchema[];
+}
+interface SchemaIntrospection {
+    db: DatabaseIdentifier;
+    tables: TableSchema[];
+    introspectedAt: string;
+}
+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>;
+}
+
+interface ClickHouseAdapterOptions {
+    /** Optional logical database name used in introspection metadata. */
+    database?: string;
+    /** Override the default response format used for query execution. */
+    defaultFormat?: DataFormat;
+    /**
+     * 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) => 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)
+ */
+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";
+    /**
+     * Simplified introspection: only collect table/column metadata for IngestRequest
+     * No indexes, constraints, or statistics
+     */
+    introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
+    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[];
+}
+/**
+ * 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;
+    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>;
+    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]
+     */
+    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 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;
+    target_db?: string | null;
+}
+interface ChartCreateInput {
+    title: string;
+    description?: string;
+    sql: string;
+    sql_params?: Record<string, unknown>;
+    vega_lite_spec: Record<string, unknown>;
+    query_id?: string;
+    target_db?: string;
+}
+interface ChartUpdateInput {
+    title?: string;
+    description?: string;
+    sql?: string;
+    sql_params?: Record<string, unknown>;
+    vega_lite_spec?: Record<string, unknown>;
+    target_db?: string;
+}
+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 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;
+    chunks: number;
+    chunks_with_annotations: number;
+    schema_id?: string;
+    schema_hash?: string;
+    drift_detected?: boolean;
+    skipped?: boolean;
+}
+interface SchemaSyncOptions {
+    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;
+    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;
+    introspect(databaseName: string, tables?: string[]): Promise<SchemaIntrospection>;
+    syncSchema(databaseName: string, options: SchemaSyncOptions, signal?: AbortSignal): Promise<IngestResponse>;
+    ask(question: string, options: AskOptions, signal?: AbortSignal): Promise<AskResponse>;
+    createChart(body: ChartCreateInput, options?: {
+        tenantId?: string;
+        userId?: string;
+        scopes?: string[];
+    }, 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>;
+    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>;
+}
+
+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 };