drizzle-cube 0.6.0 → 0.6.2

package/dist/cjs/adapters/mcp-transport.d.ts

@@ -0,0 +1,158 @@
+import { SemanticLayerCompiler, SecurityContext } from '../server/index.js';
+import { MCPPrompt } from '../server/ai/mcp-prompts.js';
+import { McpAppConfig } from './utils.js';
+export type { McpAppConfig };
+export { type MCPPrompt };
+export declare const MCP_APP_RESOURCE_URI = "ui://drizzle-cube/visualization.html";
+export declare const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+/** Get the bundled MCP App HTML, optionally with locale config injected. Returns empty string if not yet built. */
+export declare function getMcpAppHtml(config?: McpAppConfig): string;
+export type JsonRpcId = string | number | null | undefined;
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface McpDispatchContext {
+    semanticLayer: SemanticLayerCompiler;
+    extractSecurityContext: (req: any, res: any) => SecurityContext | Promise<SecurityContext>;
+    rawRequest: unknown;
+    rawResponse: unknown;
+    negotiatedProtocol?: string | null;
+    resources?: MCPResource[];
+    prompts?: MCPPrompt[];
+    /**
+     * Pre-resolved instructions string returned in the `initialize` result
+     * (`InitializeResult.instructions` per MCP spec). When omitted, falls
+     * back to `getDefaultMcpInstructions()`. Adapters resolve this from the
+     * `MCPOptions.instructions` resolver before calling `dispatchMcpMethod`.
+     */
+    instructions?: string;
+    /** Enable MCP App visualization for load tool */
+    appEnabled?: boolean;
+    /** Locale configuration for the MCP App (only used when appEnabled is true) */
+    appConfig?: McpAppConfig;
+    /** Optional name for the MCP serverInfo.name field. Defaults to 'drizzle-cube'. */
+    serverName?: string;
+}
+export interface MCPResource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    text: string;
+}
+export type MCPPromptResolver = MCPPrompt[] | ((defaults: MCPPrompt[]) => MCPPrompt[]);
+export type MCPResourceResolver = MCPResource[] | ((defaults: MCPResource[]) => MCPResource[]);
+export type MCPInstructionsResolver = string | ((defaults: string) => string);
+export interface ProtocolNegotiation {
+    ok: boolean;
+    negotiated: string | null;
+    supported: string[];
+}
+export declare const SUPPORTED_MCP_PROTOCOLS: string[];
+export declare const DEFAULT_MCP_PROTOCOL = "2025-11-25";
+export declare function negotiateProtocol(headers: Record<string, string | string[] | undefined>): ProtocolNegotiation;
+export declare function wantsEventStream(accept: string | null | undefined): boolean;
+/**
+ * MCP Session ID header name (per 2025-11-25 spec)
+ */
+export declare const MCP_SESSION_ID_HEADER = "mcp-session-id";
+/**
+ * MCP Protocol Version header name (per 2025-11-25 spec)
+ */
+export declare const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
+/**
+ * Validate the Accept header per MCP 2025-11-25 spec.
+ * Client MUST include both `application/json` and `text/event-stream` as supported content types.
+ *
+ * @returns true if valid, false if invalid
+ */
+export declare function validateAcceptHeader(accept: string | null | undefined): boolean;
+export interface OriginValidationOptions {
+    /**
+     * List of allowed origins (e.g., ['http://localhost:3000', 'https://myapp.com'])
+     * If not provided, defaults to localhost origins only
+     */
+    allowedOrigins?: string[];
+    /**
+     * If true, allows requests without an Origin header (non-browser clients)
+     * @default true
+     */
+    allowMissingOrigin?: boolean;
+}
+/**
+ * Validate the Origin header per MCP 2025-11-25 spec.
+ * Servers MUST validate Origin to prevent DNS rebinding attacks.
+ * If Origin is present and invalid, MUST respond with 403 Forbidden.
+ *
+ * @returns { valid: true } if allowed, or { valid: false, reason: string } if blocked
+ */
+export declare function validateOriginHeader(origin: string | null | undefined, options?: OriginValidationOptions): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Extract a Bearer token from an Authorization header.
+ * Returns the token string if present and well-formed, or null otherwise.
+ */
+export declare function extractBearerToken(authHeader: string | null | undefined): string | null;
+/**
+ * Build a WWW-Authenticate challenge header value per MCP / RFC 9728.
+ * Points the client to the Protected Resource Metadata document so it can
+ * discover the authorization server and begin the OAuth 2.1 flow.
+ */
+export declare function buildWwwAuthenticateChallenge(resourceMetadataUrl: string): string;
+export declare function serializeSseEvent(payload: unknown, eventId?: string, retryMs?: number): string;
+export declare function buildJsonRpcError(id: JsonRpcId, code: number, message: string, data?: unknown): JsonRpcResponse;
+export declare function buildJsonRpcResult(id: JsonRpcId, result: unknown): JsonRpcResponse;
+export declare function parseJsonRpc(body: unknown): JsonRpcRequest | null;
+export declare function dispatchMcpMethod(method: string, params: unknown, ctx: McpDispatchContext): Promise<unknown>;
+export declare function jsonRpcError(code: number, message: string, data?: unknown): Error & {
+    code: number;
+    data?: unknown;
+};
+export declare function normalizeHeader(value: string | string[] | undefined): string | null;
+export declare function isNotification(request: JsonRpcRequest): boolean;
+export declare function primeEventId(): string;
+export declare function buildToolList(options?: {
+    appEnabled?: boolean;
+}): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    _meta?: unknown;
+}[];
+export declare function getDefaultResources(): MCPResource[];
+export declare function getDefaultPrompts(): MCPPrompt[];
+/**
+ * Default instructions string returned in `InitializeResult.instructions`.
+ * Re-exported here so adapter consumers don't need to reach into `server/ai`.
+ */
+export declare function getDefaultInstructions(): string;
+export declare function resolveMcpPrompts(prompts?: MCPPromptResolver): MCPPrompt[];
+export declare function resolveMcpResources(resources?: MCPResourceResolver): MCPResource[];
+/**
+ * Resolve the MCP instructions string for the `initialize` response.
+ *
+ * - `undefined` → returns the built-in defaults.
+ * - `string`    → replaces the defaults entirely.
+ * - `(defaults) => string` → derive from / extend the defaults (e.g. append
+ *   project-specific guidance like custom cube semantics).
+ */
+export declare function resolveMcpInstructions(instructions?: MCPInstructionsResolver): string;
+export declare function buildMcpSchemaResource(semanticLayer: SemanticLayerCompiler): MCPResource;
+export declare function buildMcpResources(semanticLayer: SemanticLayerCompiler, resources?: MCPResourceResolver): MCPResource[];

package/dist/cjs/adapters/nextjs/index.d.ts

@@ -0,0 +1,196 @@
+import { NextRequest } from 'next/server';
+import { SemanticQuery, SecurityContext, DatabaseExecutor, DrizzleDatabase, Cube, CacheConfig, RLSSetupFn } from '../../server/index.js';
+import { AgentConfig } from '../../server/agent/types.js';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { MySql2Database } from 'drizzle-orm/mysql2';
+import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import { MCPOptions } from '../utils.js';
+export interface NextCorsOptions {
+    /**
+     * Allowed origins for CORS
+     */
+    origin?: string | string[] | ((origin: string) => boolean);
+    /**
+     * Allowed HTTP methods
+     */
+    methods?: string[];
+    /**
+     * Allowed headers
+     */
+    allowedHeaders?: string[];
+    /**
+     * Allow credentials
+     */
+    credentials?: boolean;
+}
+export interface NextAdapterOptions {
+    /**
+     * Array of cube definitions to register
+     */
+    cubes: Cube[];
+    /**
+     * Drizzle database instance (REQUIRED)
+     * This is the core of drizzle-cube - Drizzle ORM integration
+     * Accepts PostgreSQL, MySQL, or SQLite database instances
+     */
+    drizzle: PostgresJsDatabase<any> | MySql2Database<any> | BetterSQLite3Database<any> | DrizzleDatabase;
+    /**
+     * Database schema for type inference (RECOMMENDED)
+     * Provides full type safety for cube definitions
+     */
+    schema?: any;
+    /**
+     * Extract security context from incoming HTTP request.
+     * Called for EVERY API request to determine user permissions and multi-tenant isolation.
+     *
+     * This is your security boundary - ensure proper authentication and authorization here.
+     *
+     * @param request - Next.js Request object containing the incoming HTTP request
+     * @param context - Route context with params (optional)
+     * @returns Security context with organisationId, userId, roles, etc.
+     *
+     * @example
+     * extractSecurityContext: async (request, context) => {
+     *   // Extract JWT from Authorization header
+     *   const token = request.headers.get('Authorization')?.replace('Bearer ', '')
+     *   const decoded = await verifyJWT(token)
+     *
+     *   // Return context that will be available in all cube SQL functions
+     *   return {
+     *     organisationId: decoded.orgId,
+     *     userId: decoded.userId,
+     *     roles: decoded.roles
+     *   }
+     * }
+     */
+    extractSecurityContext: (request: NextRequest, context?: RouteContext) => SecurityContext | Promise<SecurityContext>;
+    /**
+     * Database engine type (optional - auto-detected if not provided)
+     */
+    engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+    /**
+     * CORS configuration (optional)
+     */
+    cors?: NextCorsOptions;
+    /**
+     * Runtime environment (default: 'nodejs')
+     * 'edge' for Edge Runtime, 'nodejs' for Node.js Runtime
+     */
+    runtime?: 'edge' | 'nodejs';
+    /**
+     * Cache configuration for query result caching
+     * When provided, query results will be cached using the specified provider
+     */
+    cache?: CacheConfig;
+    /**
+     * MCP (AI-Ready) endpoint configuration
+     * Enables AI agents to discover and query your data
+     * @default { enabled: true }
+     */
+    mcp?: MCPOptions;
+    /**
+     * Agent configuration for the agentic AI notebook feature.
+     * When provided, enables the POST /agent/chat SSE endpoint.
+     * Requires `@anthropic-ai/sdk` as a peer dependency.
+     */
+    agent?: AgentConfig;
+    /**
+     * Row-Level Security setup function.
+     * When provided, every query execution opens a transaction, calls this function
+     * to configure RLS (e.g., set JWT claims and switch Postgres roles), then runs the query.
+     */
+    rlsSetup?: RLSSetupFn;
+}
+export interface RouteContext {
+    params?: Record<string, string | string[]>;
+}
+export type RouteHandler = (request: NextRequest, context?: RouteContext) => Promise<Response>;
+export interface CubeHandlers {
+    load: RouteHandler;
+    meta: RouteHandler;
+    sql: RouteHandler;
+    dryRun: RouteHandler;
+    batch: RouteHandler;
+    explain: RouteHandler;
+    mcpRpc?: RouteHandler;
+    agentChat?: RouteHandler;
+}
+/**
+ * Create OPTIONS handler for CORS preflight requests
+ */
+export declare function createOptionsHandler(corsOptions: NextCorsOptions): RouteHandler;
+/**
+ * Create load handler - Execute queries
+ */
+export declare function createLoadHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create meta handler - Get cube metadata
+ */
+export declare function createMetaHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create SQL handler - Generate SQL without execution
+ */
+export declare function createSqlHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create dry-run handler - Validate queries without execution
+ */
+export declare function createDryRunHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create batch handler - Execute multiple queries in a single request
+ * Optimizes network overhead for dashboards with many portlets
+ */
+export declare function createBatchHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create explain handler - Get execution plan for a query
+ * Returns normalized EXPLAIN output across PostgreSQL, MySQL, and SQLite
+ */
+export declare function createExplainHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create discover handler - Find relevant cubes based on topic/intent
+ */
+export declare function createDiscoverHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create suggest handler - Generate query from natural language
+ */
+export declare function createSuggestHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create validate handler - Validate query with helpful corrections
+ */
+export declare function createValidateHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create MCP load handler - Execute a query and return results
+ * Completes the AI workflow: discover → suggest → validate → load
+ */
+export declare function createMcpLoadHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create MCP Streamable HTTP handler (JSON-RPC 2.0 + optional SSE)
+ * Implements MCP 2025-11-25 spec
+ */
+export declare function createMcpRpcHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create agent chat handler - Agentic AI notebook chat
+ * Streams SSE events as the agent discovers data, executes queries,
+ * and creates visualizations.
+ */
+export declare function createAgentChatHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Convenience function to create all route handlers
+ *
+ * @example
+ * const handlers = createCubeHandlers({
+ *   cubes: [salesCube, employeesCube],
+ *   drizzle: db,
+ *   schema,
+ *   extractSecurityContext: async (request, context) => {
+ *     const token = request.headers.get('Authorization')?.replace('Bearer ', '')
+ *     const decoded = await verifyJWT(token)
+ *     return { organisationId: decoded.orgId, userId: decoded.userId }
+ *   }
+ * })
+ *
+ * // Use in your API routes:
+ * export const GET = handlers.load
+ * export const POST = handlers.load
+ */
+export declare function createCubeHandlers(options: NextAdapterOptions): CubeHandlers;
+export type { SecurityContext, DatabaseExecutor, SemanticQuery, DrizzleDatabase, NextCorsOptions as CorsOptions };

package/dist/cjs/adapters/nextjs/mcp-handler.d.ts

@@ -0,0 +1,36 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { JsonRpcRequest } from '../mcp-transport.js';
+/** MCP endpoint config fields the Next.js handler helpers depend on. */
+export interface NextMcpHandlerConfig {
+    allowedOrigins?: string[];
+}
+/** Applies adapter CORS headers to an outgoing header set (no-op when CORS is disabled). */
+export type ApplyCors = (request: NextRequest, headers: Headers) => void;
+/** Builds the adapter CORS header record for JSON responses (empty when disabled). */
+export type CorsHeaders = (request: NextRequest) => Record<string, string>;
+/**
+ * Build the SSE `Response` for a GET (streaming connection open) request,
+ * emitting the initial `mcp/ready` event.
+ */
+export declare function buildMcpGetResponse(request: NextRequest, applyCors: ApplyCors): NextResponse;
+/**
+ * Result of the POST pre-dispatch validation gauntlet. When `response` is set
+ * the caller must return it immediately; otherwise `rpcRequest` and
+ * `acceptHeader` are populated for dispatch.
+ */
+export interface NextMcpRequestPrep {
+    response?: NextResponse;
+    rpcRequest?: JsonRpcRequest;
+    acceptHeader?: string | null;
+}
+/**
+ * Run the POST validation sequence (origin, Accept, protocol, body). Returns a
+ * short-circuit `response` on the first failure, or the parsed request on success.
+ */
+export declare function prepareMcpPostRequest(request: NextRequest, mcp: NextMcpHandlerConfig): Promise<NextMcpRequestPrep>;
+/** Build a single-event SSE `NextResponse` carrying one JSON-RPC payload, with CORS + extra headers. */
+export declare function buildMcpSseResponse(request: NextRequest, payload: unknown, applyCors: ApplyCors, extraHeaders?: Record<string, string>): NextResponse;
+/** Extract the MCP-Session-Id header value from an `initialize` result, if present. */
+export declare function extractMcpSessionHeaders(isInitialize: boolean, result: unknown, headerName: string): Record<string, string>;
+/** Build a JSON-RPC error response from a thrown error (preserving code/data). */
+export declare function buildMcpErrorPayload(error: unknown, id: JsonRpcRequest['id']): import('../mcp-transport.js').JsonRpcResponse;

package/dist/cjs/adapters/types.d.ts

@@ -0,0 +1,41 @@
+import { SemanticLayerCompiler, SecurityContext, DatabaseExecutor } from '../server/index.js';
+/**
+ * Base adapter configuration
+ */
+export interface BaseAdapterOptions {
+    semanticLayer: SemanticLayerCompiler;
+    databaseExecutor?: DatabaseExecutor;
+    basePath?: string;
+}
+/**
+ * Framework-specific context extractor
+ * Each framework adapter will provide their own context type
+ */
+export interface ContextExtractor<TContext = any> {
+    (context: TContext): SecurityContext | Promise<SecurityContext>;
+}
+/**
+ * Standard CORS configuration
+ */
+export interface CorsConfig {
+    origin?: string | string[] | ((origin: string) => boolean);
+    allowMethods?: string[];
+    allowHeaders?: string[];
+    credentials?: boolean;
+}
+/**
+ * Standard adapter response format
+ */
+export interface AdapterResponse {
+    data?: any;
+    error?: string;
+    status?: number;
+}
+/**
+ * Future adapter interface (for Express, Fastify, etc.)
+ */
+export interface AdapterFactory<TOptions extends BaseAdapterOptions, TApp = any> {
+    createRoutes(options: TOptions): TApp;
+    mountRoutes?(app: TApp, options: TOptions): TApp;
+    createApp?(options: TOptions): TApp;
+}