@smallwebco/tinypivot-server 1.0.57

package/LICENSE.md

@@ -0,0 +1,78 @@
+# TinyPivot License
+
+## Free Tier (MIT License)
+
+Copyright (c) 2024 TinyPivot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the Free Tier features of this software and associated documentation files
+(the "Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+### Free Tier Features Include:
+- Basic data grid display with sorting
+- Column filtering with unique values
+- Keyboard navigation and cell selection
+- Copy/paste support
+- Row striping and hover states
+- Responsive column widths
+- Cell number formatting
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+---
+
+## Pro License (Commercial)
+
+The following features require a Pro license:
+
+### Pro Features:
+- **Pivot Table**: Full pivot table functionality with drag-and-drop configuration
+- **Advanced Aggregations**: Sum, Count, Average, Min, Max, Count Distinct
+- **Row/Column Totals**: Automatic total calculations
+- **Percentage Mode**: View data as % of row, column, or grand total
+- **Column/Row Grouping**: Multi-level grouping for pivot tables
+- **Session Persistence**: Auto-save and restore pivot configuration
+- **Priority Support**: Direct email support and issue prioritization
+
+### Pricing:
+- **Single Project**: $49 one-time payment
+- **Unlimited Projects**: $149 one-time payment
+- **Team License (up to 10 devs)**: $399 one-time payment
+
+### How to Purchase:
+Visit https://tiny-pivot.com/#pricing to purchase a license.
+
+After purchase, you'll receive a license key to unlock Pro features:
+
+```typescript
+import { DataGrid, setLicenseKey } from 'tinypivot'
+
+setLicenseKey('YOUR_LICENSE_KEY')
+```
+
+### License Validation:
+- License keys are validated locally (no network calls)
+- Keys are tied to your npm username or organization
+- Licenses are perpetual with 1 year of updates included
+
+---
+
+## Terms
+
+1. **No Removal of Attribution**: Free tier users must keep the "Powered by TinyPivot" 
+   watermark visible. Pro license removes this requirement.
+
+2. **No Redistribution**: You may not redistribute this library as part of another 
+   component library or framework.
+
+3. **No Sub-licensing**: Licenses cannot be transferred or sub-licensed.
+
+---
+
+For questions about licensing, contact: license@tiny-pivot.com
+

package/README.md

@@ -0,0 +1,362 @@
+# @smallwebco/tinypivot-server
+
+Server-side handlers for TinyPivot AI Data Analyst.
+
+## Two Deployment Options
+
+### Option 1: Full Server (PostgreSQL + AI)
+
+Use this when you have a PostgreSQL database. The unified handler provides:
+- Auto-discovery of tables from your database
+- Schema introspection  
+- SQL query execution with safety validation
+- AI chat proxy
+
+### Option 2: Client-Side Queries + AI Proxy Only
+
+Use this when your data is already in the browser (e.g., DuckDB WASM, static data). You only need a server endpoint for AI chat to keep API keys secure.
+
+---
+
+## Option 1: Full Server Setup
+
+### Requirements
+
+- PostgreSQL database
+- AI API key (OpenAI, Anthropic, or OpenRouter)
+- Node.js 18+
+
+### 1. Install
+
+```bash
+pnpm add @smallwebco/tinypivot-server pg
+```
+
+### 2. Set Environment Variables
+
+```bash
+# .env
+DATABASE_URL=postgresql://user:password@localhost:5432/mydb
+AI_API_KEY=sk-...  # Your API key
+
+# Optional: Override the default model
+AI_MODEL=claude-sonnet-4-20250514
+```
+
+The AI provider is **auto-detected** from your API key format:
+- `sk-ant-...` → Anthropic (defaults to `claude-3-haiku-20240307`)
+- `sk-or-...` → OpenRouter (defaults to `anthropic/claude-3-haiku`)
+- `sk-...` → OpenAI (defaults to `gpt-4o-mini`)
+
+Default models are cheap/fast. Override with `AI_MODEL` for better quality.
+
+### 3. Create API Endpoint
+
+**Next.js App Router**
+
+```typescript
+// app/api/tinypivot/route.ts
+import { createTinyPivotHandler } from '@smallwebco/tinypivot-server'
+
+export const POST = createTinyPivotHandler()
+```
+
+**Next.js Pages Router**
+
+```typescript
+// pages/api/tinypivot.ts
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { createTinyPivotHandler } from '@smallwebco/tinypivot-server'
+
+const handler = createTinyPivotHandler()
+
+export default async function (req: NextApiRequest, res: NextApiResponse) {
+  const response = await handler(
+    new Request('http://localhost', {
+      method: 'POST',
+      body: JSON.stringify(req.body),
+      headers: { 'Content-Type': 'application/json' },
+    })
+  )
+  const data = await response.json()
+  res.status(response.status).json(data)
+}
+```
+
+**Express**
+
+```typescript
+import express from 'express'
+import { createTinyPivotHandler } from '@smallwebco/tinypivot-server'
+
+const app = express()
+app.use(express.json())
+
+const handler = createTinyPivotHandler()
+
+app.post('/api/tinypivot', async (req, res) => {
+  const response = await handler(
+    new Request('http://localhost', {
+      method: 'POST',
+      body: JSON.stringify(req.body),
+      headers: { 'Content-Type': 'application/json' },
+    })
+  )
+  const data = await response.json()
+  res.status(response.status).json(data)
+})
+```
+
+### 4. Use in Frontend
+
+**Vue 3**
+
+```vue
+<script setup>
+import { DataGrid } from '@smallwebco/tinypivot-vue'
+import '@smallwebco/tinypivot-vue/style.css'
+</script>
+
+<template>
+  <DataGrid 
+    :data="[]" 
+    :ai-analyst="{ endpoint: '/api/tinypivot' }"
+  />
+</template>
+```
+
+**React**
+
+```tsx
+import { DataGrid } from '@smallwebco/tinypivot-react'
+import '@smallwebco/tinypivot-react/style.css'
+
+function App() {
+  return (
+    <DataGrid 
+      data={[]} 
+      aiAnalyst={{ endpoint: '/api/tinypivot' }}
+    />
+  )
+}
+```
+
+---
+
+## Option 2: Client-Side Queries + AI Proxy
+
+Use this when you're executing queries in the browser (e.g., DuckDB WASM) and only need the server for AI chat.
+
+### 1. Create AI-Only Endpoint
+
+```typescript
+// api/ai-proxy.ts (Vercel) or your framework equivalent
+export default async function handler(req, res) {
+  const apiKey = process.env.AI_API_KEY
+  if (!apiKey) {
+    return res.status(500).json({ error: 'AI_API_KEY not configured' })
+  }
+
+  const { messages } = req.body
+
+  // Auto-detect provider from key format
+  const isAnthropic = apiKey.startsWith('sk-ant-')
+  const isOpenRouter = apiKey.startsWith('sk-or-')
+
+  // Call the appropriate API...
+  // (See full implementation in the TinyPivot demo)
+
+  return res.json({ content: aiResponse })
+}
+```
+
+### 2. Configure Frontend with queryExecutor
+
+**Vue 3**
+
+```vue
+<script setup>
+import { DataGrid } from '@smallwebco/tinypivot-vue'
+import '@smallwebco/tinypivot-vue/style.css'
+
+// Your client-side query function (e.g., DuckDB WASM)
+async function executeQuery(sql: string, table: string) {
+  const result = await duckdb.query(sql)
+  return {
+    data: result.toArray(),
+    rowCount: result.numRows,
+  }
+}
+
+const aiConfig = {
+  endpoint: '/api/ai-proxy',      // Server endpoint for AI chat only
+  queryExecutor: executeQuery,     // Client-side SQL execution
+  dataSources: [
+    { id: 'sales', table: 'sales', name: 'Sales Data', description: 'Sales transactions' }
+  ],
+  dataSourceLoader: async (id) => {
+    // Load data into your client-side DB and return schema
+    const data = await loadDataset(id)
+    return { data, schema: inferSchema(data) }
+  }
+}
+</script>
+
+<template>
+  <DataGrid :data="myData" :ai-analyst="aiConfig" />
+</template>
+```
+
+**React**
+
+```tsx
+import { DataGrid } from '@smallwebco/tinypivot-react'
+import '@smallwebco/tinypivot-react/style.css'
+
+function App() {
+  const executeQuery = async (sql: string, table: string) => {
+    const result = await duckdb.query(sql)
+    return { data: result.toArray(), rowCount: result.numRows }
+  }
+
+  const aiConfig = {
+    endpoint: '/api/ai-proxy',
+    queryExecutor: executeQuery,
+    dataSources: [
+      { id: 'sales', table: 'sales', name: 'Sales Data', description: 'Sales transactions' }
+    ],
+    dataSourceLoader: async (id) => {
+      const data = await loadDataset(id)
+      return { data, schema: inferSchema(data) }
+    }
+  }
+
+  return <DataGrid data={myData} aiAnalyst={aiConfig} />
+}
+```
+
+---
+
+## Configuration Options
+
+### Handler Options (Full Server)
+
+```typescript
+createTinyPivotHandler({
+  // PostgreSQL connection (default: process.env.DATABASE_URL)
+  connectionString: 'postgresql://...',
+  
+  // AI API key (default: process.env.AI_API_KEY)
+  apiKey: 'sk-...',
+  
+  // Table filtering
+  tables: {
+    include: ['sales', 'customers'],      // Only these tables
+    exclude: [/^_/, 'migrations'],         // Exclude patterns
+    schemas: ['public'],                   // PostgreSQL schemas
+    descriptions: {                        // Context for AI
+      sales: 'Sales transactions with revenue data',
+    }
+  },
+  
+  // Query limits (optional)
+  maxRows: 10000,
+  timeout: 30000,
+  
+  // AI settings
+  model: 'claude-sonnet-4-20250514',      // Override default model
+  maxTokens: 2048,
+  
+  // Error handling
+  onError: (error) => console.error(error),
+})
+```
+
+### AI Analyst Config (Frontend)
+
+```typescript
+interface AIAnalystConfig {
+  // Required: API endpoint
+  endpoint: string
+  
+  // For client-side queries (Option 2)
+  queryExecutor?: (sql: string, table: string) => Promise<QueryResult>
+  dataSources?: AIDataSource[]
+  dataSourceLoader?: (id: string) => Promise<{ data: any[], schema?: Schema }>
+  
+  // Optional
+  enabled?: boolean
+  persistToLocalStorage?: boolean
+  sessionId?: string
+  maxRows?: number
+  aiModelName?: string  // Display name in UI
+}
+```
+
+---
+
+## API Contract
+
+The endpoint accepts POST requests with an `action` field:
+
+### `list-tables`
+```typescript
+// Request
+{ action: 'list-tables' }
+
+// Response
+{ tables: [{ name: 'sales', description: '...' }] }
+```
+
+### `get-schema`
+```typescript
+// Request
+{ action: 'get-schema', tables: ['sales'] }
+
+// Response
+{ schemas: [{ table: 'sales', columns: [...] }] }
+```
+
+### `query`
+```typescript
+// Request
+{ action: 'query', sql: 'SELECT ...', table: 'sales' }
+
+// Response
+{ success: true, data: [...], rowCount: 100, truncated: false }
+```
+
+### `chat`
+```typescript
+// Request
+{ action: 'chat', messages: [{ role: 'user', content: '...' }] }
+
+// Response
+{ content: 'AI response with SQL...' }
+```
+
+---
+
+## Security
+
+Built-in protections:
+
+1. **SQL Validation**: Only SELECT queries allowed
+2. **Table Whitelisting**: Only configured tables are queryable
+3. **LIMIT Enforcement**: Auto-added if missing
+4. **Error Sanitization**: Connection strings stripped from errors
+
+---
+
+## Troubleshooting
+
+| Error | Solution |
+|-------|----------|
+| "PostgreSQL driver not installed" | `pnpm add pg` |
+| "Database connection not configured" | Set `DATABASE_URL` |
+| "AI API key not configured" | Set `AI_API_KEY` |
+| "Table X is not allowed" | Add to `tables.include` or remove from `tables.exclude` |
+
+## License
+
+MIT