drizzle-cube 0.6.1 → 0.6.2

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

@@ -0,0 +1,114 @@
+import { Router, Request, Response, Express } from 'express';
+import { CorsOptions } from 'cors';
+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 ExpressAdapterOptions {
+    /**
+     * 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 req - Express Request object containing the incoming HTTP request
+     * @param res - Express Response object
+     * @returns Security context with organisationId, userId, roles, etc.
+     *
+     * @example
+     * extractSecurityContext: async (req, res) => {
+     *   // Extract JWT from Authorization header
+     *   const token = req.headers.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: (req: Request, res: Response) => SecurityContext | Promise<SecurityContext>;
+    /**
+     * Database engine type (optional - auto-detected if not provided)
+     */
+    engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+    /**
+     * CORS configuration (optional)
+     */
+    cors?: CorsOptions;
+    /**
+     * API base path (default: '/cubejs-api/v1')
+     */
+    basePath?: string;
+    /**
+     * JSON body parser limit (default: '10mb')
+     */
+    jsonLimit?: string;
+    /**
+     * 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;
+}
+/**
+ * Create Express router for Cube.js-compatible API
+ */
+export declare function createCubeRouter(options: ExpressAdapterOptions): Router;
+/**
+ * Convenience function to mount Cube routes on an existing Express app
+ */
+export declare function mountCubeRoutes(app: Express, options: ExpressAdapterOptions): Express;
+/**
+ * Create a complete Express app with Cube.js routes
+ *
+ * @example
+ * const app = createCubeApp({
+ *   cubes: [salesCube, employeesCube],
+ *   drizzle: db,
+ *   schema,
+ *   extractSecurityContext: async (req, res) => {
+ *     const token = req.headers.authorization?.replace('Bearer ', '')
+ *     const decoded = await verifyJWT(token)
+ *     return { organisationId: decoded.orgId, userId: decoded.userId }
+ *   }
+ * })
+ */
+export declare function createCubeApp(options: ExpressAdapterOptions): Express;
+export type { SecurityContext, DatabaseExecutor, SemanticQuery, DrizzleDatabase, CorsOptions };

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

@@ -0,0 +1,113 @@
+import { FastifyPluginCallback, FastifyRequest, FastifyInstance } from 'fastify';
+import { FastifyCorsOptions } from '@fastify/cors';
+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 FastifyAdapterOptions {
+    /**
+     * 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 - Fastify Request object containing the incoming HTTP request
+     * @returns Security context with organisationId, userId, roles, etc.
+     *
+     * @example
+     * extractSecurityContext: async (request) => {
+     *   // Extract JWT from Authorization header
+     *   const token = request.headers.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: FastifyRequest) => SecurityContext | Promise<SecurityContext>;
+    /**
+     * Database engine type (optional - auto-detected if not provided)
+     */
+    engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+    /**
+     * CORS configuration (optional)
+     */
+    cors?: FastifyCorsOptions;
+    /**
+     * API base path (default: '/cubejs-api/v1')
+     */
+    basePath?: string;
+    /**
+     * JSON body parser limit (default: 10485760 - 10MB)
+     */
+    bodyLimit?: number;
+    /**
+     * 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;
+}
+/**
+ * Fastify plugin for Cube.js-compatible API
+ */
+export declare const cubePlugin: FastifyPluginCallback<FastifyAdapterOptions>;
+/**
+ * Helper function to register cube routes on an existing Fastify instance
+ */
+export declare function registerCubeRoutes(fastify: FastifyInstance, options: FastifyAdapterOptions): Promise<void>;
+/**
+ * Create a complete Fastify instance with Cube.js routes
+ *
+ * @example
+ * const app = createCubeApp({
+ *   cubes: [salesCube, employeesCube],
+ *   drizzle: db,
+ *   schema,
+ *   extractSecurityContext: async (request) => {
+ *     const token = request.headers.authorization?.replace('Bearer ', '')
+ *     const decoded = await verifyJWT(token)
+ *     return { organisationId: decoded.orgId, userId: decoded.userId }
+ *   }
+ * })
+ */
+export declare function createCubeApp(options: FastifyAdapterOptions): FastifyInstance;
+export type { SecurityContext, DatabaseExecutor, SemanticQuery, DrizzleDatabase, FastifyCorsOptions };

package/dist/cjs/adapters/hono/agent-handler.d.ts

@@ -0,0 +1,9 @@
+import { Context } from 'hono';
+import { SemanticLayerCompiler } from '../../server/compiler.js';
+import { SecurityContext } from '../../server/index.js';
+import { AgentConfig } from '../../server/agent/types.js';
+/**
+ * Handle a `POST /agent/chat` request: validate input, resolve the API key and
+ * overrides, then stream agent events as SSE. Mirrors the previous inline route.
+ */
+export declare function handleAgentChatRequest(c: Context, agentConfig: AgentConfig, semanticLayer: SemanticLayerCompiler, extractSecurityContext: (c: Context) => Promise<SecurityContext>): Promise<Response>;

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

@@ -0,0 +1,120 @@
+import { Hono } from 'hono';
+import { SemanticQuery, SecurityContext, DatabaseExecutor, DrizzleDatabase, Cube, CacheConfig, RLSSetupFn } from '../../server/index.js';
+import { AgentConfig } from '../../server/agent/types.js';
+import { SemanticLayerCompiler } from '../../server/compiler.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 HonoAdapterOptions {
+    /**
+     * Array of cube definitions to register.
+     * Optional when `semanticLayer` is provided (caller manages registration).
+     */
+    cubes?: Cube[];
+    /**
+     * Pre-configured SemanticLayerCompiler instance.
+     * When provided, skips creating a new compiler and cube registration (caller manages it).
+     */
+    semanticLayer?: SemanticLayerCompiler;
+    /**
+     * Drizzle database instance.
+     * Required unless `semanticLayer` is provided.
+     * 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 c - Hono context containing the incoming HTTP request
+     * @returns Security context with organisationId, userId, roles, etc.
+     *
+     * @example
+     * extractSecurityContext: async (c) => {
+     *   // Extract JWT from Authorization header
+     *   const token = c.req.header('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: (c: any) => SecurityContext | Promise<SecurityContext>;
+    /**
+     * Database engine type (optional - auto-detected if not provided)
+     */
+    engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+    /**
+     * CORS configuration (optional)
+     */
+    cors?: {
+        origin?: string | string[] | ((origin: string, c: any) => string | null | undefined);
+        allowMethods?: string[];
+        allowHeaders?: string[];
+        credentials?: boolean;
+    };
+    /**
+     * API base path (default: '/cubejs-api/v1')
+     */
+    basePath?: string;
+    /**
+     * 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;
+}
+/**
+ * Create Hono routes for Cube.js-compatible API
+ */
+export declare function createCubeRoutes(options: HonoAdapterOptions): Hono<import('hono/types').BlankEnv, import('hono/types').BlankSchema, "/">;
+/**
+ * Convenience function to create routes and mount them on an existing Hono app
+ */
+export declare function mountCubeRoutes(app: Hono, options: HonoAdapterOptions): Hono<import('hono/types').BlankEnv, import('hono/types').BlankSchema, "/">;
+/**
+ * Create a complete Hono app with Cube.js routes
+ *
+ * @example
+ * const app = createCubeApp({
+ *   cubes: [salesCube, employeesCube],
+ *   drizzle: db,
+ *   schema,
+ *   extractSecurityContext: async (c) => {
+ *     const token = c.req.header('Authorization')
+ *     const decoded = await verifyJWT(token)
+ *     return { organisationId: decoded.orgId, userId: decoded.userId }
+ *   }
+ * })
+ */
+export declare function createCubeApp(options: HonoAdapterOptions): Hono<import('hono/types').BlankEnv, import('hono/types').BlankSchema, "/">;
+export type { SecurityContext, DatabaseExecutor, SemanticQuery, DrizzleDatabase };

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

@@ -0,0 +1,37 @@
+import { Context } from 'hono';
+import { JsonRpcRequest, McpDispatchContext } from '../mcp-transport.js';
+/** MCP endpoint config fields the handler helpers depend on. */
+export interface HonoMcpHandlerConfig {
+    resourceMetadataUrl?: string;
+    allowedOrigins?: string[];
+}
+/**
+ * Result of the pre-dispatch validation gauntlet. When `response` is set the
+ * caller must return it immediately (short-circuit); otherwise `rpcRequest`,
+ * `acceptHeader`, and `protocol` are populated for dispatch.
+ */
+export interface McpRequestPrep {
+    response?: Response;
+    rpcRequest?: JsonRpcRequest;
+    acceptHeader?: string;
+    negotiatedProtocol?: string | null;
+}
+/**
+ * Run the MCP POST validation sequence (auth, origin, Accept, protocol, body).
+ * Returns a short-circuit `response` on the first failure, or the parsed
+ * request + negotiated protocol on success.
+ */
+export declare function prepareMcpPostRequest(c: Context, mcp: HonoMcpHandlerConfig): Promise<McpRequestPrep>;
+/** Build a single-event SSE `Response` carrying one JSON-RPC payload. */
+export declare function buildMcpSseResponse(payload: unknown, extraHeaders?: Record<string, string>): Response;
+/** 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;
+/** Wrap `wantsEventStream` so the handler imports a single helper module. */
+export declare function clientWantsStream(acceptHeader?: string): boolean;
+/**
+ * Dispatch a validated MCP JSON-RPC request and build the Hono `Response`
+ * (success or error path). Keeps the route handler a thin wrapper.
+ */
+export declare function dispatchMcpPost(c: Context, rpcRequest: JsonRpcRequest, wantsStream: boolean, ctx: McpDispatchContext): Promise<Response>;

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

@@ -0,0 +1,8 @@
+import { SecurityContext } from '../server/index.js';
+export declare const DC_LOCALE_HEADER = "x-dc-locale";
+export declare const DEFAULT_LOCALE = "en-GB";
+type HeaderValue = string | string[] | null | undefined;
+export declare function resolveRequestLocale(getHeader: (name: string) => HeaderValue): string | undefined;
+export declare function withLocaleInSecurityContext(securityContext: SecurityContext, requestLocale?: string): SecurityContext;
+export declare function ensureLocaleHeader(allowHeaders?: string[] | string): string[];
+export {};

package/dist/cjs/adapters/mcp-tools-handlers.d.ts

@@ -0,0 +1,18 @@
+import { SemanticLayerCompiler, SecurityContext } from '../server/index.js';
+import { MCPToolResult } from './mcp-tools.js';
+export interface CubeToolHandlerDeps {
+    semanticLayer: SemanticLayerCompiler;
+    getSecurityContext: (meta?: unknown) => SecurityContext | Promise<SecurityContext>;
+    wrapContent: (result: unknown) => MCPToolResult;
+    wrapError: (error: unknown) => MCPToolResult;
+}
+/** Execute the `discover` tool. */
+export declare function runDiscoverTool(deps: CubeToolHandlerDeps, args: unknown): Promise<MCPToolResult>;
+/** Execute the `validate` tool — security context is optional (SQL omitted without auth). */
+export declare function runValidateTool(deps: CubeToolHandlerDeps, args: unknown, meta?: unknown): Promise<MCPToolResult>;
+/**
+ * Execute the `load` / `chart` tools. Both run the same query path; `chart`
+ * additionally carries `_meta.ui` on its definition so the result renders in the
+ * MCP App UI.
+ */
+export declare function runLoadTool(deps: CubeToolHandlerDeps, args: unknown, meta?: unknown): Promise<MCPToolResult>;

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

@@ -0,0 +1,134 @@
+import { SemanticLayerCompiler, SecurityContext } from '../server/index.js';
+import { DiscoverRequest, ValidateRequest, LoadRequest } from './utils.js';
+import { MCPPrompt } from '../server/ai/mcp-prompts.js';
+import { MCPResource, McpAppConfig } from './mcp-transport.js';
+export type { MCPPrompt, MCPResource, DiscoverRequest, ValidateRequest, LoadRequest };
+export type { SecurityContext } from '../server/index.js';
+/**
+ * MCP tool content block (matches MCP spec)
+ */
+export interface MCPToolContent {
+    type: 'text';
+    text: string;
+}
+/**
+ * MCP tool result (matches MCP spec CallToolResult)
+ */
+export interface MCPToolResult {
+    content: MCPToolContent[];
+    isError: boolean;
+}
+/**
+ * MCP tool definition (matches MCP spec Tool)
+ */
+export interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        required?: string[];
+        properties: Record<string, unknown>;
+    };
+}
+/**
+ * Options for creating composable cube tools
+ */
+export interface GetCubeToolsOptions {
+    /** The semantic layer compiler instance with registered cubes */
+    semanticLayer: SemanticLayerCompiler;
+    /**
+     * Extract security context for query execution.
+     * Called when the `load` tool is invoked.
+     * Receives whatever metadata your MCP server provides (auth info, request context, etc.)
+     */
+    getSecurityContext: (meta?: unknown) => SecurityContext | Promise<SecurityContext>;
+    /**
+     * Optional tool name prefix. Defaults to 'drizzle_cube_'.
+     * Set to '' for no prefix, or provide your own like 'analytics_'.
+     */
+    toolPrefix?: string;
+    /**
+     * Which tools to expose. Defaults to all: ['discover', 'validate', 'load']
+     */
+    tools?: ('discover' | 'validate' | 'load')[];
+    /** Custom MCP prompts (defaults to built-in drizzle-cube prompts) */
+    prompts?: MCPPrompt[];
+    /** Custom MCP resources (defaults to built-in drizzle-cube resources) */
+    resources?: MCPResource[];
+    /**
+     * Enable MCP App visualization for the load tool.
+     * Pass `true` to enable with defaults, or a config object to set locale options.
+     * @example app: { defaultLocale: 'nl-NL', detectBrowserLocale: false }
+     */
+    app?: boolean | McpAppConfig;
+}
+/**
+ * The composable tools object returned by getCubeTools()
+ */
+export interface CubeTools {
+    /** Tool definitions for MCP tools/list responses */
+    definitions: MCPToolDefinition[];
+    /**
+     * Execute a tool by name. Returns MCP-spec-compliant result.
+     * @param name - Tool name (with or without prefix)
+     * @param args - Tool arguments from the MCP client
+     * @param meta - Optional metadata passed to getSecurityContext
+     */
+    handle: (name: string, args: unknown, meta?: unknown) => Promise<MCPToolResult>;
+    /**
+     * Check if a tool name is handled by these cube tools
+     * @param name - Tool name to check (with or without prefix)
+     */
+    handles: (name: string) => boolean;
+    /** MCP prompts for prompts/list responses */
+    prompts: MCPPrompt[];
+    /** MCP resources for resources/list responses */
+    resources: MCPResource[];
+    /** The tool names this instance handles (with prefix applied) */
+    toolNames: string[];
+}
+/**
+ * Create composable MCP tools for your semantic layer.
+ *
+ * Returns tool definitions, a handler function, and prompts/resources
+ * that you can register on any MCP server.
+ *
+ * @example With @modelcontextprotocol/sdk
+ * ```typescript
+ * import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+ * import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+ * import { getCubeTools } from 'drizzle-cube/mcp'
+ *
+ * const cubeTools = getCubeTools({
+ *   semanticLayer,
+ *   getSecurityContext: async (meta) => ({ orgId: meta.authInfo?.orgId })
+ * })
+ *
+ * const server = new Server({ name: 'my-server', version: '1.0.0' })
+ *
+ * server.setRequestHandler(ListToolsRequestSchema, async () => ({
+ *   tools: [...myOtherTools, ...cubeTools.definitions]
+ * }))
+ *
+ * server.setRequestHandler(CallToolRequestSchema, async (req) => {
+ *   if (cubeTools.handles(req.params.name)) {
+ *     return cubeTools.handle(req.params.name, req.params.arguments, req)
+ *   }
+ *   return handleOtherTools(req)
+ * })
+ * ```
+ *
+ * @example With Hono + postgrest-mcp style
+ * ```typescript
+ * import { getCubeTools } from 'drizzle-cube/mcp'
+ *
+ * const cubeTools = getCubeTools({
+ *   semanticLayer,
+ *   getSecurityContext: async () => ({ orgId: 'default' })
+ * })
+ *
+ * // Merge with your existing PostgREST tools
+ * const allTools = [...postgrestTools, ...cubeTools.definitions]
+ * ```
+ */
+export declare function getCubeTools(options: GetCubeToolsOptions): CubeTools;