@smallwebco/tinypivot-server 1.0.57

package/dist/index.d.cts

@@ -0,0 +1,180 @@
+export { AIColumnSchema, AIProxyRequest, AIProxyResponse, AITableSchema, QueryRequest, QueryResponse, SchemaRequest, SchemaResponse } from '@smallwebco/tinypivot-core';
+
+/**
+ * TinyPivot Server - Type Definitions
+ */
+
+/**
+ * Generic request handler type
+ * Compatible with Express, Fastify, Next.js API routes, etc.
+ */
+type RequestHandler = (req: Request) => Promise<Response>;
+
+/**
+ * Table filtering options for controlling which tables are exposed
+ */
+interface TableFilterOptions {
+    /**
+     * Only include tables matching these patterns (exact string or regex)
+     * If not provided, all tables in the specified schemas are included.
+     *
+     * Example: `['sales', 'customers', /^app_.+/]`
+     */
+    include?: (string | RegExp)[];
+    /**
+     * Exclude tables matching these patterns (applied after include)
+     *
+     * Example: `[/^_/, 'migrations', 'sessions']`
+     */
+    exclude?: (string | RegExp)[];
+    /**
+     * Only include tables from these schemas (default: ['public'])
+     *
+     * Example: `['public', 'analytics']`
+     */
+    schemas?: string[];
+    /**
+     * Descriptions to show to the AI for context
+     * Keys are table names, values are human-readable descriptions
+     */
+    descriptions?: Record<string, string>;
+}
+/**
+ * Options for creating the unified TinyPivot handler
+ */
+interface TinyPivotHandlerOptions {
+    /**
+     * PostgreSQL connection string
+     * @default process.env.DATABASE_URL
+     */
+    connectionString?: string;
+    /**
+     * AI API key - auto-detects provider from key format:
+     * - `sk-ant-...` → Anthropic
+     * - `sk-or-...` → OpenRouter
+     * - `sk-...` → OpenAI
+     * @default process.env.AI_API_KEY
+     */
+    apiKey?: string;
+    /**
+     * Table filtering options
+     * By default, all tables in the 'public' schema are exposed.
+     */
+    tables?: TableFilterOptions;
+    /**
+     * Maximum rows to return from queries.
+     * If not set, no limit is enforced (queries may return large result sets).
+     */
+    maxRows?: number;
+    /**
+     * Query timeout in milliseconds.
+     * If not set, uses PostgreSQL default (no timeout).
+     */
+    timeout?: number;
+    /**
+     * Override the AI model.
+     *
+     * Priority: options.model > AI_MODEL env var > cheap default per provider
+     *
+     * Defaults (cheap/fast):
+     * - Anthropic: claude-3-haiku-20240307
+     * - OpenAI: gpt-4o-mini
+     * - OpenRouter: anthropic/claude-3-haiku
+     *
+     * @example 'claude-sonnet-4-20250514', 'gpt-4o'
+     */
+    model?: string;
+    /**
+     * Maximum tokens for AI responses
+     * @default 2048
+     */
+    maxTokens?: number;
+    /**
+     * Custom error handler
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Request body for the unified endpoint
+ */
+interface TinyPivotRequest {
+    /** Action to perform */
+    action: 'list-tables' | 'get-schema' | 'query' | 'chat';
+    tables?: string[];
+    sql?: string;
+    table?: string;
+    messages?: Array<{
+        role: 'user' | 'assistant' | 'system';
+        content: string;
+    }>;
+}
+/**
+ * Response for list-tables action
+ */
+interface ListTablesResponse {
+    tables: Array<{
+        name: string;
+        description?: string;
+    }>;
+    error?: string;
+}
+/**
+ * Create a unified TinyPivot handler
+ *
+ * This single endpoint handles:
+ * - `action: 'list-tables'` - Auto-discover tables from PostgreSQL
+ * - `action: 'get-schema'` - Get column schema for tables
+ * - `action: 'query'` - Execute validated SELECT queries
+ * - `action: 'chat'` - Proxy to AI provider
+ *
+ * @example
+ * ```typescript
+ * // Next.js App Router - app/api/tinypivot/route.ts
+ * import { createTinyPivotHandler } from '@smallwebco/tinypivot-server'
+ *
+ * export const POST = createTinyPivotHandler()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With options
+ * const handler = createTinyPivotHandler({
+ *   tables: {
+ *     include: ['sales', 'customers', 'products'],
+ *     exclude: [/^_/, 'migrations'],
+ *     descriptions: {
+ *       sales: 'Sales transactions with revenue data',
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function createTinyPivotHandler(options?: TinyPivotHandlerOptions): RequestHandler;
+
+/**
+ * TinyPivot Server - SQL Validation
+ * Ensures queries are safe and read-only
+ */
+interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate that a SQL query is safe to execute
+ */
+declare function validateSQL(sql: string, allowedTables: string[]): ValidationResult;
+/**
+ * Extract table names from a SELECT query
+ * This is a simplified parser - for production, consider using a proper SQL parser
+ */
+declare function extractTableNames(sql: string): string[];
+/**
+ * Sanitize a table name to prevent SQL injection
+ */
+declare function sanitizeTableName(name: string): string;
+/**
+ * Add LIMIT clause if not present
+ */
+declare function ensureLimit(sql: string, maxRows: number): string;
+
+export { type ListTablesResponse, type RequestHandler, type TableFilterOptions, type TinyPivotHandlerOptions, type TinyPivotRequest, type ValidationResult, createTinyPivotHandler, ensureLimit, extractTableNames, sanitizeTableName, validateSQL };

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+export { AIColumnSchema, AIProxyRequest, AIProxyResponse, AITableSchema, QueryRequest, QueryResponse, SchemaRequest, SchemaResponse } from '@smallwebco/tinypivot-core';
+
+/**
+ * TinyPivot Server - Type Definitions
+ */
+
+/**
+ * Generic request handler type
+ * Compatible with Express, Fastify, Next.js API routes, etc.
+ */
+type RequestHandler = (req: Request) => Promise<Response>;
+
+/**
+ * Table filtering options for controlling which tables are exposed
+ */
+interface TableFilterOptions {
+    /**
+     * Only include tables matching these patterns (exact string or regex)
+     * If not provided, all tables in the specified schemas are included.
+     *
+     * Example: `['sales', 'customers', /^app_.+/]`
+     */
+    include?: (string | RegExp)[];
+    /**
+     * Exclude tables matching these patterns (applied after include)
+     *
+     * Example: `[/^_/, 'migrations', 'sessions']`
+     */
+    exclude?: (string | RegExp)[];
+    /**
+     * Only include tables from these schemas (default: ['public'])
+     *
+     * Example: `['public', 'analytics']`
+     */
+    schemas?: string[];
+    /**
+     * Descriptions to show to the AI for context
+     * Keys are table names, values are human-readable descriptions
+     */
+    descriptions?: Record<string, string>;
+}
+/**
+ * Options for creating the unified TinyPivot handler
+ */
+interface TinyPivotHandlerOptions {
+    /**
+     * PostgreSQL connection string
+     * @default process.env.DATABASE_URL
+     */
+    connectionString?: string;
+    /**
+     * AI API key - auto-detects provider from key format:
+     * - `sk-ant-...` → Anthropic
+     * - `sk-or-...` → OpenRouter
+     * - `sk-...` → OpenAI
+     * @default process.env.AI_API_KEY
+     */
+    apiKey?: string;
+    /**
+     * Table filtering options
+     * By default, all tables in the 'public' schema are exposed.
+     */
+    tables?: TableFilterOptions;
+    /**
+     * Maximum rows to return from queries.
+     * If not set, no limit is enforced (queries may return large result sets).
+     */
+    maxRows?: number;
+    /**
+     * Query timeout in milliseconds.
+     * If not set, uses PostgreSQL default (no timeout).
+     */
+    timeout?: number;
+    /**
+     * Override the AI model.
+     *
+     * Priority: options.model > AI_MODEL env var > cheap default per provider
+     *
+     * Defaults (cheap/fast):
+     * - Anthropic: claude-3-haiku-20240307
+     * - OpenAI: gpt-4o-mini
+     * - OpenRouter: anthropic/claude-3-haiku
+     *
+     * @example 'claude-sonnet-4-20250514', 'gpt-4o'
+     */
+    model?: string;
+    /**
+     * Maximum tokens for AI responses
+     * @default 2048
+     */
+    maxTokens?: number;
+    /**
+     * Custom error handler
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Request body for the unified endpoint
+ */
+interface TinyPivotRequest {
+    /** Action to perform */
+    action: 'list-tables' | 'get-schema' | 'query' | 'chat';
+    tables?: string[];
+    sql?: string;
+    table?: string;
+    messages?: Array<{
+        role: 'user' | 'assistant' | 'system';
+        content: string;
+    }>;
+}
+/**
+ * Response for list-tables action
+ */
+interface ListTablesResponse {
+    tables: Array<{
+        name: string;
+        description?: string;
+    }>;
+    error?: string;
+}
+/**
+ * Create a unified TinyPivot handler
+ *
+ * This single endpoint handles:
+ * - `action: 'list-tables'` - Auto-discover tables from PostgreSQL
+ * - `action: 'get-schema'` - Get column schema for tables
+ * - `action: 'query'` - Execute validated SELECT queries
+ * - `action: 'chat'` - Proxy to AI provider
+ *
+ * @example
+ * ```typescript
+ * // Next.js App Router - app/api/tinypivot/route.ts
+ * import { createTinyPivotHandler } from '@smallwebco/tinypivot-server'
+ *
+ * export const POST = createTinyPivotHandler()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With options
+ * const handler = createTinyPivotHandler({
+ *   tables: {
+ *     include: ['sales', 'customers', 'products'],
+ *     exclude: [/^_/, 'migrations'],
+ *     descriptions: {
+ *       sales: 'Sales transactions with revenue data',
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function createTinyPivotHandler(options?: TinyPivotHandlerOptions): RequestHandler;
+
+/**
+ * TinyPivot Server - SQL Validation
+ * Ensures queries are safe and read-only
+ */
+interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate that a SQL query is safe to execute
+ */
+declare function validateSQL(sql: string, allowedTables: string[]): ValidationResult;
+/**
+ * Extract table names from a SELECT query
+ * This is a simplified parser - for production, consider using a proper SQL parser
+ */
+declare function extractTableNames(sql: string): string[];
+/**
+ * Sanitize a table name to prevent SQL injection
+ */
+declare function sanitizeTableName(name: string): string;
+/**
+ * Add LIMIT clause if not present
+ */
+declare function ensureLimit(sql: string, maxRows: number): string;
+
+export { type ListTablesResponse, type RequestHandler, type TableFilterOptions, type TinyPivotHandlerOptions, type TinyPivotRequest, type ValidationResult, createTinyPivotHandler, ensureLimit, extractTableNames, sanitizeTableName, validateSQL };