@querypanel/node-sdk 1.0.55 → 1.0.57

package/dist/index.d.cts

@@ -156,8 +156,11 @@ declare class PostgresAdapter implements DatabaseAdapter {
     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]
+     * Convert params to positional array for PostgreSQL.
+     * PostgreSQL expects $1, $2, $3 in SQL and an array of values [val1, val2, val3].
+     * When the record has numeric keys ("1", "2", "3") — e.g. from mapGeneratedParams —
+     * use only those in order so placeholder order matches SQL. Otherwise fall back to
+     * named keys in alphabetical order for backward compatibility.
      */
     private convertNamedToPositionalParams;
     validate(sql: string, params?: Record<string, string | number | boolean | string[] | number[]>): Promise<void>;
@@ -169,6 +172,46 @@ declare class PostgresAdapter implements DatabaseAdapter {
     introspect(options?: IntrospectOptions): Promise<SchemaIntrospection>;
 }
 
+/**
+ * Interface for the API layer used by route modules.
+ * Implemented by ApiClient (HTTP to querypanel-sdk) and CallbackApiClient (in-process callbacks).
+ * Allows the SDK to be used inside your own API without HTTP recursion by providing a callback-based implementation.
+ */
+interface IQueryPanelApi {
+    getDefaultTenantId(): string | undefined;
+    get<T>(path: string, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+    post<T>(path: string, body: unknown, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+    postWithHeaders<T>(path: string, body: unknown, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<{
+        data: T;
+        headers: Headers;
+    }>;
+    put<T>(path: string, body: unknown, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+    patch<T>(path: string, body: unknown, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+    delete<T = void>(path: string, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+}
+/**
+ * Options passed to the request handler when using the callback-based API.
+ * Use this when you run the SDK inside your own API and want to handle "API" calls in-process (e.g. call querypanel-sdk services directly) to avoid recursion.
+ */
+interface RequestHandlerOptions {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    body?: unknown;
+    tenantId: string;
+    userId?: string;
+    scopes?: string[];
+    signal?: AbortSignal;
+    sessionId?: string;
+}
+/**
+ * Result from the request handler. Return `headers` for POST requests to paths like `/query` or `/v2/query` when the SDK needs to read response headers (e.g. x-querypanel-session-id).
+ */
+interface RequestHandlerResult {
+    data: unknown;
+    headers?: Headers;
+}
+type RequestHandler = (opts: RequestHandlerOptions) => Promise<RequestHandlerResult>;
+
 /**
  * Error codes for the query pipeline
  * These match the server-side error codes returned in API responses
@@ -191,8 +234,8 @@ type QueryErrorCode = (typeof QueryErrorCode)[keyof typeof QueryErrorCode];
  */
 declare class QueryPipelineError extends Error {
     readonly code: QueryErrorCode;
-    readonly details?: Record<string, unknown>;
-    constructor(message: string, code: QueryErrorCode, details?: Record<string, unknown>);
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: QueryErrorCode, details?: Record<string, unknown> | undefined);
     /**
      * Check if this is a moderation error
      */
@@ -315,6 +358,78 @@ interface ActiveChartListOptions extends ChartListOptions {
     withData?: boolean;
 }
 
+/**
+ * Dashboard interface matching querypanel-sdk schema
+ */
+interface SdkDashboard {
+    id: string;
+    organization_id: string;
+    name: string;
+    description: string | null;
+    status: "draft" | "deployed";
+    content_json: string | null;
+    widget_config: Record<string, unknown> | null;
+    editor_type: "blocknote" | "custom";
+    is_customer_fork: boolean;
+    forked_from_dashboard_id: string | null;
+    tenant_id: string | null;
+    datasource_id: string | null;
+    version: number;
+    deployed_at: string | null;
+    created_at: string;
+    updated_at: string;
+    created_by: string | null;
+}
+/**
+ * Dashboard creation input
+ */
+interface DashboardCreateInput {
+    name: string;
+    description?: string;
+    content_json?: string;
+    widget_config?: Record<string, unknown>;
+    editor_type?: "blocknote" | "custom";
+    datasource_id?: string;
+}
+/**
+ * Dashboard update input
+ */
+interface DashboardUpdateInput {
+    name?: string;
+    description?: string;
+    content_json?: string;
+    widget_config?: Record<string, unknown>;
+    editor_type?: "blocknote" | "custom";
+    datasource_id?: string | null;
+}
+/**
+ * Dashboard list options
+ */
+interface DashboardListOptions {
+    tenantId?: string;
+    userId?: string;
+    scopes?: string[];
+    pagination?: PaginationQuery$1;
+    status?: "draft" | "deployed";
+    sortBy?: "name" | "created_at" | "updated_at" | "deployed_at";
+    sortDir?: "asc" | "desc";
+}
+/**
+ * Fork dashboard input
+ */
+interface DashboardForkInput {
+    tenant_id: string;
+    name?: string;
+}
+/**
+ * Fork update input
+ */
+interface DashboardForkUpdateInput {
+    tenant_id: string;
+    content_json?: string;
+    widget_config?: Record<string, unknown>;
+}
+
 interface IngestResponse {
     success: boolean;
     message: string;
@@ -741,6 +856,8 @@ interface ChartModifyOptions {
      * QueryPanel session ID for context-aware follow-ups.
      * Pass the querypanelSessionId from a previous ask() response
      * to preserve conversation history when modifying charts.
+     * If omitted, modifyChart starts a new QueryPanel session and sends
+     * the original question with modification hints.
      */
     querypanelSessionId?: string;
 }
@@ -869,19 +986,84 @@ interface VizSpecResponse {
     notes: string | null;
 }
 
+/**
+ * API client that delegates every request to a callback instead of HTTP.
+ * Use this when running the SDK inside your own API so that "API" calls are handled in-process (e.g. by calling querypanel-sdk services directly) and do not cause recursion.
+ */
+declare class CallbackApiClient implements IQueryPanelApi {
+    private readonly requestHandler;
+    private readonly defaultTenantId?;
+    constructor(requestHandler: RequestHandler, options?: {
+        defaultTenantId?: string;
+    });
+    getDefaultTenantId(): string | undefined;
+    private request;
+    get<T>(path: string, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+    post<T>(path: string, body: unknown, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+    postWithHeaders<T>(path: string, body: unknown, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<{
+        data: T;
+        headers: Headers;
+    }>;
+    put<T>(path: string, body: unknown, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+    patch<T>(path: string, body: unknown, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+    delete<T = void>(path: string, tenantId: string, userId?: string, scopes?: string[], signal?: AbortSignal, sessionId?: string): Promise<T>;
+}
+
+/** Options when constructing the SDK with HTTP (default) or with a custom API implementation. */
+interface QueryPanelSdkAPIOptions {
+    defaultTenantId?: string;
+    additionalHeaders?: Record<string, string>;
+    fetch?: typeof fetch;
+    /**
+     * Use a custom API implementation (e.g. CallbackApiClient) instead of HTTP.
+     * When set, baseUrl and privateKey are ignored and no requests are sent to querypanel-sdk;
+     * use this when calling the SDK from within your own API to avoid recursion.
+     */
+    api?: IQueryPanelApi;
+}
 /**
  * Main SDK class - Thin orchestrator
- * Delegates to deep modules (ApiClient, QueryEngine, route modules)
+ * Delegates to deep modules (ApiClient or custom API, 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?: {
+    constructor(baseUrl: string, privateKey: string, organizationId: string, options?: QueryPanelSdkAPIOptions);
+    /**
+     * Create an SDK instance that uses a request callback instead of HTTP.
+     * Use this when calling the SDK from within your own API so that "API" calls
+     * are handled in-process (e.g. by invoking querypanel-sdk services directly)
+     * and do not cause recursion.
+     *
+     * @param organizationId - Organization identifier
+     * @param requestHandler - Callback invoked for each logical API request (method, path, body, tenantId, etc.)
+     * @param options - Optional defaultTenantId
+     * @returns QueryPanelSdkAPI instance; attach databases and call ask(), syncSchema(), etc. as usual
+     *
+     * @example
+     * ```ts
+     * const qp = QueryPanelSdkAPI.withCallbacks(
+     *   process.env.ORGANIZATION_ID!,
+     *   async (opts) => {
+     *     // Call your in-process services (e.g. querypanel-sdk logic) instead of HTTP
+     *     if (opts.path === '/query' || opts.path === '/v2/query') {
+     *       const result = await yourSqlGenerator.generate(opts.body, opts.tenantId);
+     *       return { data: result, headers: new Headers({ 'x-querypanel-session-id': result.sessionId }) };
+     *     }
+     *     if (opts.path === '/chart') return { data: await yourChartService.generate(opts.body) };
+     *     // ... other paths
+     *     return { data: await yourProxy(opts) };
+     *   },
+     *   { defaultTenantId: process.env.DEFAULT_TENANT_ID }
+     * );
+     * qp.attachPostgres('db', createClient, { tenantFieldName: 'tenant_id' });
+     * const result = await qp.ask('Top 10 orders', { tenantId: 't1', database: 'db' });
+     * ```
+     */
+    static withCallbacks(organizationId: string, requestHandler: RequestHandler, options?: {
         defaultTenantId?: string;
-        additionalHeaders?: Record<string, string>;
-        fetch?: typeof fetch;
-    });
+    }): QueryPanelSdkAPI;
     attachClickhouse(name: string, clientFn: ClickHouseClientFn, options?: ClickHouseAdapterOptions & {
         description?: string;
         tags?: string[];
@@ -955,6 +1137,31 @@ declare class QueryPanelSdkAPI {
      * ```
      */
     ask(question: string, options: AskOptions, signal?: AbortSignal): Promise<AskResponse>;
+    /**
+     * Creates a JWT for the given tenant (and optional userId, scopes).
+     * Use this when you need to pass a token to the embed (e.g. frontend or demo).
+     * Only available when using the HTTP client (ApiClient); not available when using withCallbacks.
+     */
+    createJwt(options: {
+        tenantId: string;
+        userId?: string;
+        scopes?: string[];
+    }): Promise<string>;
+    /**
+     * Runs SQL against an attached database with tenant isolation applied.
+     * Used by embed run-sql (e.g. dashboard chart execution). Requires a database
+     * to be attached (e.g. via attachPostgres) and options.tenantId.
+     */
+    runSqlForDashboard(input: {
+        sql: string;
+        params?: Record<string, unknown>;
+        database?: string;
+    }, options: {
+        tenantId: string;
+    }): Promise<{
+        rows: unknown[];
+        fields: string[];
+    }>;
     /**
      * Generates a VizSpec visualization specification from query results.
      *
@@ -1336,6 +1543,248 @@ declare class QueryPanelSdkAPI {
         userId?: string;
         scopes?: string[];
     }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Creates a new dashboard with BlockNote content.
+     *
+     * @param body - Dashboard configuration including name and BlockNote content
+     * @param options - Tenant, user, and scope options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Created dashboard
+     *
+     * @example
+     * ```typescript
+     * const dashboard = await qp.createDashboard({
+     *   name: "Sales Dashboard",
+     *   description: "Monthly sales metrics",
+     *   content_json: blockNoteContent,
+     *   editor_type: "blocknote",
+     * }, { tenantId: "tenant_123" });
+     * ```
+     */
+    createDashboard(body: DashboardCreateInput, options?: {
+        tenantId?: string;
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkDashboard>;
+    /**
+     * Lists dashboards with pagination and filtering.
+     *
+     * @param options - Filtering and pagination options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Paginated list of dashboards
+     *
+     * @example
+     * ```typescript
+     * const dashboards = await qp.listDashboards({
+     *   tenantId: "tenant_123",
+     *   status: "deployed",
+     *   pagination: { page: 1, limit: 10 },
+     * });
+     * ```
+     */
+    listDashboards(options?: DashboardListOptions, signal?: AbortSignal): Promise<PaginatedResponse$1<SdkDashboard>>;
+    /**
+     * Gets a dashboard by ID.
+     *
+     * @param id - Dashboard ID
+     * @param options - Tenant, user, and scope options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Dashboard details
+     *
+     * @example
+     * ```typescript
+     * const dashboard = await qp.getDashboard("dash_123", {
+     *   tenantId: "tenant_123",
+     * });
+     * ```
+     */
+    getDashboard(id: string, options?: {
+        tenantId?: string;
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkDashboard>;
+    /**
+     * Gets a dashboard for a specific tenant.
+     * Returns customer fork if exists, otherwise returns the original dashboard.
+     *
+     * @param id - Dashboard ID
+     * @param tenantId - Tenant ID to check for fork
+     * @param options - Additional auth options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Dashboard (fork if exists, original otherwise)
+     *
+     * @example
+     * ```typescript
+     * const dashboard = await qp.getDashboardForTenant(
+     *   "dash_123",
+     *   "tenant_456",
+     * );
+     * ```
+     */
+    getDashboardForTenant(id: string, tenantId: string, options?: {
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkDashboard>;
+    /**
+     * Updates a dashboard.
+     *
+     * @param id - Dashboard ID to update
+     * @param body - Fields to update
+     * @param options - Tenant, user, and scope options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Updated dashboard
+     *
+     * @example
+     * ```typescript
+     * const updated = await qp.updateDashboard("dash_123", {
+     *   name: "Updated Dashboard",
+     *   content_json: newBlockNoteContent,
+     * }, { tenantId: "tenant_123" });
+     * ```
+     */
+    updateDashboard(id: string, body: DashboardUpdateInput, options?: {
+        tenantId?: string;
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkDashboard>;
+    /**
+     * Updates dashboard status (deploy/undeploy).
+     *
+     * @param id - Dashboard ID
+     * @param status - New status
+     * @param options - Tenant, user, and scope options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Updated dashboard
+     *
+     * @example
+     * ```typescript
+     * const deployed = await qp.updateDashboardStatus(
+     *   "dash_123",
+     *   "deployed",
+     *   { tenantId: "tenant_123" },
+     * );
+     * ```
+     */
+    updateDashboardStatus(id: string, status: "draft" | "deployed", options?: {
+        tenantId?: string;
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkDashboard>;
+    /**
+     * Deletes a dashboard.
+     *
+     * @param id - Dashboard ID to delete
+     * @param options - Tenant, user, and scope options
+     * @param signal - Optional AbortSignal for cancellation
+     *
+     * @example
+     * ```typescript
+     * await qp.deleteDashboard("dash_123", { tenantId: "tenant_123" });
+     * ```
+     */
+    deleteDashboard(id: string, options?: {
+        tenantId?: string;
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Forks a dashboard for customer customization (copy-on-write).
+     *
+     * Creates a full copy of the dashboard that the customer can edit independently.
+     * The original dashboard remains unchanged.
+     *
+     * @param id - Dashboard ID to fork
+     * @param input - Fork configuration with tenant_id
+     * @param options - Additional auth options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Forked dashboard
+     *
+     * @example
+     * ```typescript
+     * const fork = await qp.forkDashboard("dash_123", {
+     *   tenant_id: "tenant_456",
+     *   name: "Customer's Custom Dashboard",
+     * });
+     * ```
+     */
+    forkDashboard(id: string, input: DashboardForkInput, options?: {
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkDashboard>;
+    /**
+     * Updates a customer fork.
+     *
+     * @param forkId - Fork ID to update
+     * @param input - Update data including tenant_id
+     * @param options - Additional auth options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Updated fork
+     *
+     * @example
+     * ```typescript
+     * const updated = await qp.updateFork("fork_123", {
+     *   tenant_id: "tenant_456",
+     *   content_json: newBlockNoteContent,
+     * });
+     * ```
+     */
+    updateFork(forkId: string, input: DashboardForkUpdateInput, options?: {
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkDashboard>;
+    /**
+     * Rollbacks a fork to the original dashboard.
+     * This deletes the fork and the customer will see the original again.
+     *
+     * @param forkId - Fork ID to rollback
+     * @param tenantId - Tenant ID
+     * @param options - Additional auth options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Original dashboard
+     *
+     * @example
+     * ```typescript
+     * const original = await qp.rollbackFork("fork_123", "tenant_456");
+     * ```
+     */
+    rollbackFork(forkId: string, tenantId: string, options?: {
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkDashboard>;
+    /**
+     * Deletes a customer fork.
+     *
+     * @param forkId - Fork ID to delete
+     * @param tenantId - Tenant ID
+     * @param options - Additional auth options
+     * @param signal - Optional AbortSignal for cancellation
+     *
+     * @example
+     * ```typescript
+     * await qp.deleteFork("fork_123", "tenant_456");
+     * ```
+     */
+    deleteFork(forkId: string, tenantId: string, options?: {
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Lists all customer forks for a tenant.
+     *
+     * @param tenantId - Tenant ID
+     * @param options - Additional auth options
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Array of forks
+     *
+     * @example
+     * ```typescript
+     * const forks = await qp.listForksForTenant("tenant_456");
+     * ```
+     */
+    listForksForTenant(tenantId: string, options?: {
+        userId?: string;
+        scopes?: string[];
+    }, signal?: AbortSignal): Promise<SdkDashboard[]>;
 }
 
-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 EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IngestResponse, type IntentResult, 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, type PipelineTrace, 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 ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults };
+export { type ActiveChartCreateInput, type ActiveChartListOptions, type ActiveChartUpdateInput, type AggregateOp, type AskOptions, type AskResponse, type AxisField, type AxisFieldInput, CallbackApiClient, 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 DashboardCreateInput, type DashboardForkInput, type DashboardForkUpdateInput, type DashboardListOptions, type DashboardUpdateInput, type DatabaseAdapter, type DatabaseDialect, type DateRangeInput, type EncodingHints, type FieldRef, type FieldRefInput, type FieldType, type IQueryPanelApi, type IngestResponse, type IntentResult, 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, type PipelineTrace, PostgresAdapter, type PostgresAdapterOptions, type PostgresClientFn, QueryErrorCode, QueryErrorCode as QueryErrorCodeType, QueryPanelSdkAPI, type QueryPanelSdkAPIOptions, QueryPipelineError, type RequestHandler, type RequestHandlerOptions, type RequestHandlerResult, type SchemaIntrospection, type SchemaSyncOptions, type SdkActiveChart, type SdkChart, type SdkDashboard, type SdkSession, type SdkSessionTurn, type SessionGetOptions, type SessionListOptions, type SessionUpdateInput, type SqlModifications, type StackingMode, type TableColumn, type TableEncoding, type TableSpec, type TimeUnit, type ValueFormat, type VizModifications, type VizSpec, type VizSpecGenerateInput, type VizSpecGenerateOptions, type VizSpecGeneratorInput, type VizSpecKind, type VizSpecResponse, type VizSpecResult, anonymizeResults };