insforge 0.3.2 → 1.2.10

package/docs/core-concepts/database/architecture.mdx

@@ -0,0 +1,256 @@
+---
+title: Architecture
+description: PostgreSQL database with automatic REST APIs via PostgREST
+---
+
+## Overview
+
+InsForge uses a powerful database stack that automatically generates REST APIs from your PostgreSQL schema, eliminating the need to write backend CRUD code.
+
+## Technology Stack
+
+```mermaid
+graph TB
+    Client[Client Application] --> SDK[InsForge SDK]
+    SDK --> API[InsForge API]
+    API --> PostgREST[PostgREST v12.2]
+    PostgREST --> PG[(PostgreSQL 15)]
+    API --> PG
+    
+    PG --> RLS[Row Level Security]
+    PG --> Triggers[Database Triggers]
+    PG --> Functions[Stored Functions]
+    PG --> Schemas[Multiple Schemas]
+    
+    style Client fill:#1e293b,stroke:#475569,color:#e2e8f0
+    style SDK fill:#1e40af,stroke:#3b82f6,color:#dbeafe
+    style API fill:#166534,stroke:#22c55e,color:#dcfce7
+    style PostgREST fill:#c2410c,stroke:#fb923c,color:#fed7aa
+    style PG fill:#0e7490,stroke:#06b6d4,color:#cffafe
+    style RLS fill:#4c1d95,stroke:#8b5cf6,color:#ede9fe
+    style Triggers fill:#4c1d95,stroke:#8b5cf6,color:#ede9fe
+    style Functions fill:#4c1d95,stroke:#8b5cf6,color:#ede9fe
+    style Schemas fill:#4c1d95,stroke:#8b5cf6,color:#ede9fe
+```
+
+## Core Components
+
+| Component | Technology | Version | Purpose |
+|-----------|------------|---------|---------|
+| **Database** | PostgreSQL | 15.13 | ACID-compliant relational database |
+| **REST API** | PostgREST | 12.2.12 | Auto-generates RESTful APIs from public schema only |
+| **Query Engine** | PostgREST DSL | - | Powerful filtering with operators and functions |
+| **Security** | Row Level Security | - | Fine-grained access control at the row level |
+| **Roles** | PostgreSQL Roles | - | anon (read-only), authenticated (CRUD), project_admin (full) |
+| **SDK** | @insforge/sdk | Latest | Type-safe JavaScript/TypeScript client |
+
+## How It Works
+
+### 1. Schema Definition
+When you create a table through the InsForge API or migrations:
+- Table structure is stored in PostgreSQL
+- PostgREST discovers the schema via database introspection
+- REST endpoints are instantly available
+
+### 2. API Generation
+PostgREST automatically creates endpoints:
+- `GET /api/database/records/{table}` - Query records
+- `POST /api/database/records/{table}` - Insert records  
+- `PATCH /api/database/records/{table}` - Update records
+- `DELETE /api/database/records/{table}` - Delete records
+
+### 3. Query Translation
+HTTP requests are converted to optimized SQL:
+```
+GET /api/database/records/products?price=gte.100&category=eq.electronics
+↓
+SELECT * FROM products 
+WHERE price >= 100 
+AND category = 'electronics'
+```
+
+### 4. Security Layer
+- JWT tokens are validated on each request
+- User ID extracted from token
+- RLS policies applied based on user context
+- Only authorized rows are returned
+
+### 5. Response Format
+- Results returned as JSON arrays
+- HTTP status codes indicate success/failure
+- Headers include pagination info
+
+## PostgREST Features
+
+<CardGroup cols={2}>
+  <Card title="Instant APIs" icon="bolt">
+    Every table gets full CRUD endpoints automatically without writing any backend code
+  </Card>
+  
+  <Card title="Advanced Filtering" icon="filter">
+    Complex queries with operators like `eq`, `gt`, `like`, `in`, `is`, `or`
+  </Card>
+  
+  <Card title="Relationship Embedding" icon="link">
+    Join related tables in single requests using foreign key relationships
+  </Card>
+  
+  <Card title="Bulk Operations" icon="layer-group">
+    Insert, update, or delete multiple records in a single atomic transaction
+  </Card>
+  
+  <Card title="Computed Fields" icon="calculator">
+    Expose database functions and views as API endpoints
+  </Card>
+  
+  <Card title="Real-time Updates" icon="sync">
+    NOTIFY/LISTEN for schema changes without restart
+  </Card>
+</CardGroup>
+
+## Database Structure
+
+InsForge uses two PostgreSQL databases:
+
+### Main Database (`insforge`)
+All application and system tables reside in the `public` schema:
+
+| Table Type | Purpose | Examples |
+|------------|---------|----------|
+| **User Tables** | Created by developers | Any table you create |
+| **System Tables** | Internal InsForge tables | Prefixed with `_` |
+
+### Analytics Database (`_insforge`)
+Separate database for analytics with `_analytics` schema for Logflare integration.
+
+### System Tables (in `public` schema)
+
+| Table | Purpose |
+|-------|---------|
+| `_accounts` | Core user authentication records |
+| `users` | User profile data (references _accounts) |
+| `_account_providers` | OAuth provider connections |
+| `_storage_buckets` | Storage bucket configuration |
+| `_storage` | File metadata and references |
+| `_ai_configs` | AI model configurations per project |
+| `_ai_usage` | AI token usage tracking |
+| `_config` | System configuration key-value store |
+| `_metadata` | Application metadata |
+| `_mcp_usage` | MCP tool usage tracking |
+| `_edge_functions` | Serverless function definitions |
+| `logs` | Activity and audit logs |
+
+## Query Syntax
+
+PostgREST provides a powerful query syntax that maps to SQL:
+
+### Operators
+
+| Operator | SQL Equivalent | Example |
+|----------|---------------|---------|
+| `eq` | `=` | `?id=eq.123` |
+| `neq` | `!=` | `?status=neq.deleted` |
+| `gt` | `>` | `?age=gt.18` |
+| `gte` | `>=` | `?price=gte.100` |
+| `lt` | `<` | `?created=lt.2024-01-01` |
+| `lte` | `<=` | `?quantity=lte.10` |
+| `like` | `LIKE` | `?name=like.*john*` |
+| `ilike` | `ILIKE` | `?email=ilike.*gmail*` |
+| `in` | `IN` | `?status=in.(active,pending)` |
+| `is` | `IS` | `?deleted_at=is.null` |
+
+### Complex Queries
+
+```javascript
+// Combine conditions with AND
+GET /api/database/records/products?price=gte.100&category=eq.electronics
+
+// OR conditions
+GET /api/database/records/products?or=(price.lt.50,on_sale.is.true)
+
+// Nested conditions
+GET /api/database/records/orders?and=(status.eq.pending,or=(priority.eq.high,created_at.lt.2024-01-01))
+```
+
+## Performance Optimizations
+
+### Connection Pooling
+- PgBouncer manages database connections
+- Reduces connection overhead
+- Handles concurrent requests efficiently
+
+### Query Optimization
+- PostgREST generates optimized SQL
+- Uses prepared statements
+- Leverages PostgreSQL query planner
+
+### Indexing Strategy
+- Automatic indexes on primary keys
+- Foreign key indexes for joins
+- Custom indexes via migrations
+
+### Caching
+- ETags for conditional requests
+- Client-side caching support
+- Response compression
+
+## Data Types
+
+PostgreSQL types are automatically mapped to JSON:
+
+| InsForge Type | PostgreSQL Type | JSON Type | Notes |
+|---------------|----------------|-----------|-------|
+| `string` | `TEXT` | string | Text of any length |
+| `integer` | `INTEGER` | number | 32-bit integers |
+| `float` | `DOUBLE PRECISION` | number | Decimal numbers |
+| `boolean` | `BOOLEAN` | boolean | true/false |
+| `date` | `DATE` | string | ISO 8601 date format |
+| `datetime` | `TIMESTAMPTZ` | string | ISO 8601 with timezone |
+| `uuid` | `UUID` | string | Auto-generated unique identifier |
+| `json` | `JSONB` | object/array | Structured JSON data with indexing |
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Use Indexes" icon="gauge">
+    Create indexes on frequently queried columns
+  </Card>
+  
+  <Card title="Leverage RLS" icon="shield">
+    Implement Row Level Security for data isolation
+  </Card>
+  
+  <Card title="Batch Operations" icon="boxes">
+    Use bulk inserts/updates for better performance
+  </Card>
+  
+  <Card title="Select Columns" icon="table-columns">
+    Query only needed columns to reduce payload
+  </Card>
+  
+  <Card title="Use Views" icon="eye">
+    Create views for complex queries
+  </Card>
+  
+  <Card title="Monitor Performance" icon="chart-line">
+    Use EXPLAIN ANALYZE for slow queries
+  </Card>
+</CardGroup>
+
+## Limitations
+
+- **No Custom Business Logic**: PostgREST handles CRUD only
+- **SQL Knowledge Helpful**: Complex queries benefit from SQL understanding
+- **Schema Changes**: Require PostgREST reload (automatic via NOTIFY)
+- **File Handling**: Use storage API for files, not database
+
+## Comparison with Traditional APIs
+
+| Aspect | Traditional REST API | InsForge + PostgREST |
+|--------|---------------------|----------------------|
+| **Development Time** | Write CRUD for each table | Instant APIs from schema |
+| **Maintenance** | Update code for schema changes | Automatic updates |
+| **Performance** | Depends on implementation | Optimized SQL generation |
+| **Consistency** | Varies by developer | Uniform API patterns |
+| **Documentation** | Manual updates needed | Auto-generated OpenAPI |
+| **Security** | Custom implementation | Built-in RLS + JWT |

package/docs/core-concepts/database/sdk.mdx

@@ -0,0 +1,382 @@
+---
+title: Database SDK Reference
+description: Type-safe database operations using the InsForge SDK
+---
+
+import Installation from '/snippets/sdk-installation.mdx';
+
+<Installation />
+
+## insert()
+
+Insert new records into a table.
+
+### Parameters
+
+- `values` (object | Array, required) - Data to insert. Single object or array for bulk insert
+- `options.count` ('exact' | 'planned' | 'estimated', optional) - Include count of inserted rows
+
+### Returns
+
+```typescript
+{
+  data: Array<object> | null,
+  error: Error | null,
+  count?: number
+}
+```
+
+<Note>
+Chain `.select()` after `.insert()` to return the inserted data
+</Note>
+
+### Examples
+
+<CodeGroup>
+```javascript Single insert
+const { data, error } = await insforge.database
+  .from('users')
+  .insert({ name: 'John', email: 'john@example.com' })
+  .select()
+```
+
+```javascript Bulk insert
+const { data, error } = await insforge.database
+  .from('users')
+  .insert([
+    { name: 'Alice', email: 'alice@example.com' },
+    { name: 'Bob', email: 'bob@example.com' }
+  ])
+  .select()
+```
+</CodeGroup>
+
+### Output Example
+
+```json
+{
+  "data": [
+    { "id": "789", "name": "John", "email": "john@example.com", "created_at": "2024-01-15T10:30:00Z" }
+  ],
+  "error": null
+}
+```
+
+---
+
+## update()
+
+Update existing records in a table. Must use filters to target specific rows.
+
+### Parameters
+
+- `values` (object, required) - Fields to update
+- `options.count` ('exact' | 'planned' | 'estimated', optional) - Include count of updated rows
+
+### Returns
+
+```typescript
+{
+  data: Array<object> | null,
+  error: Error | null,
+  count?: number
+}
+```
+
+<Warning>
+Always use filters like `.eq()` or `.in()` to specify which rows to update
+</Warning>
+
+### Examples
+
+<CodeGroup>
+```javascript Update by ID
+const { data, error } = await insforge.database
+  .from('users')
+  .update({ name: 'Jane Doe' })
+  .eq('id', userId)
+  .select()
+```
+
+```javascript Update multiple
+const { data, error } = await insforge.database
+  .from('tasks')
+  .update({ status: 'completed' })
+  .in('id', ['task-1', 'task-2'])
+  .select()
+```
+</CodeGroup>
+
+### Output Example
+
+```json
+{
+  "data": [
+    { "id": "123", "name": "Jane Doe", "email": "john@example.com", "updated_at": "2024-01-15T11:00:00Z" }
+  ],
+  "error": null
+}
+```
+
+---
+
+## delete()
+
+Delete records from a table. Must use filters to target specific rows.
+
+### Parameters
+
+- `options.count` ('exact' | 'planned' | 'estimated', optional) - Include count of deleted rows
+
+### Returns
+
+```typescript
+{
+  data: Array<object> | null,
+  error: Error | null,
+  count?: number
+}
+```
+
+<Warning>
+Always use filters to specify which rows to delete
+</Warning>
+
+### Examples
+
+<CodeGroup>
+```javascript Delete by ID
+const { error } = await insforge.database
+  .from('posts')
+  .delete()
+  .eq('id', postId)
+```
+
+```javascript Delete with filter
+const { error } = await insforge.database
+  .from('sessions')
+  .delete()
+  .lt('expires_at', new Date())
+```
+</CodeGroup>
+
+### Output Example
+
+```json
+{
+  "data": null,
+  "error": null
+}
+```
+
+---
+
+## select()
+
+Query records from a table or view.
+
+### Parameters
+
+- `columns` (string, optional) - Comma-separated column names. Use `*` for all columns
+- `options.count` ('exact' | 'planned' | 'estimated', optional) - Include total row count
+- `options.head` (boolean, optional) - Return only count, no data
+
+### Returns
+
+```typescript
+{
+  data: Array<object> | null,
+  error: Error | null,
+  count?: number
+}
+```
+
+### Examples
+
+<CodeGroup>
+```javascript Get all
+const { data, error } = await insforge.database
+  .from('users')
+  .select()
+```
+
+```javascript Specific columns
+const { data, error } = await insforge.database
+  .from('users')
+  .select('id, name, email')
+```
+
+```javascript With relationships
+const { data, error } = await insforge.database
+  .from('posts')
+  .select('*, users(nickname, avatar_url)')
+```
+</CodeGroup>
+
+### Output Example
+
+```json
+{
+  "data": [
+    { "id": "123", "name": "John", "email": "john@example.com" },
+    { "id": "456", "name": "Jane", "email": "jane@example.com" }
+  ],
+  "error": null
+}
+```
+
+---
+
+## Filters
+
+Chain filters to narrow down query results. All filters take `(column, value)` as parameters.
+
+| Filter | Description | Example |
+|--------|-------------|---------|
+| `.eq(column, value)` | Equals | `.eq('status', 'active')` |
+| `.neq(column, value)` | Not equals | `.neq('status', 'banned')` |
+| `.gt(column, value)` | Greater than | `.gt('age', 18)` |
+| `.gte(column, value)` | Greater than or equal | `.gte('price', 100)` |
+| `.lt(column, value)` | Less than | `.lt('stock', 10)` |
+| `.lte(column, value)` | Less than or equal | `.lte('priority', 3)` |
+| `.like(column, pattern)` | Case-sensitive pattern (use `%` wildcard) | `.like('name', '%Widget%')` |
+| `.ilike(column, pattern)` | Case-insensitive pattern (use `%` wildcard) | `.ilike('email', '%@gmail.com')` |
+| `.in(column, array)` | Value in array | `.in('status', ['pending', 'active'])` |
+| `.is(column, value)` | Exactly equals (for null checks) | `.is('deleted_at', null)` |
+
+```javascript
+// Example: Chain multiple filters
+const { data } = await insforge.database
+  .from('products')
+  .select()
+  .eq('category', 'electronics')
+  .gte('price', 50)
+  .lte('price', 500)
+  .is('in_stock', true)
+```
+
+---
+
+## Modifiers
+
+Control how query results are returned.
+
+| Modifier | Description | Example |
+|----------|-------------|---------|
+| `.order(column, options)` | Sort results. Options: `{ ascending: true/false, nullsFirst: true/false }` | `.order('created_at', { ascending: false })` |
+| `.limit(count)` | Limit number of rows | `.limit(10)` |
+| `.range(from, to)` | Get rows between indices (pagination) | `.range(0, 9)` |
+| `.single()` | Return object instead of array (throws if multiple) | `.single()` |
+| `.maybeSingle()` | Return object or null (no error) | `.maybeSingle()` |
+
+```javascript
+// Example: Pagination with sorting
+const { data } = await insforge.database
+  .from('posts')
+  .select()
+  .order('created_at', { ascending: false })
+  .range(0, 9)
+  .limit(10)
+```
+
+---
+
+## Common Patterns
+
+### Pagination with Count
+
+```javascript
+const page = 1;
+const pageSize = 10;
+const from = (page - 1) * pageSize;
+const to = from + pageSize - 1;
+
+const { data, count } = await insforge.database
+  .from('posts')
+  .select('*', { count: 'exact' })
+  .range(from, to)
+  .order('created_at', { ascending: false })
+
+console.log(`Page ${page}: ${data.length} of ${count} total`)
+```
+
+**Output:**
+```json
+{
+  "data": [
+    { "id": "1", "title": "Post 1", "created_at": "2024-01-15T10:00:00Z" },
+    { "id": "2", "title": "Post 2", "created_at": "2024-01-14T10:00:00Z" }
+  ],
+  "count": 50,
+  "error": null
+}
+```
+
+### Filtered Search
+
+```javascript
+const { data } = await insforge.database
+  .from('products')
+  .select('id, name, price, category')
+  .eq('category', 'electronics')
+  .gte('price', 50)
+  .lte('price', 500)
+  .order('price', { ascending: true })
+  .limit(20)
+```
+
+**Output:**
+```json
+{
+  "data": [
+    { "id": "101", "name": "USB Cable", "price": 59.99, "category": "electronics" },
+    { "id": "102", "name": "Keyboard", "price": 89.99, "category": "electronics" }
+  ],
+  "error": null
+}
+```
+
+### Using with Authentication Hooks
+
+Combine database queries with `useUser()` or `useAuth()` hooks to fetch user-specific data:
+
+```tsx
+import { useUser } from '@insforge/react'; // or '@insforge/react-router'
+import { insforge } from './lib/insforge';
+import { useEffect, useState } from 'react';
+
+function MyProfile() {
+  const { user, isLoaded } = useUser();
+  const [posts, setPosts] = useState([]);
+
+  useEffect(() => {
+    if (user) {
+      // Fetch user's posts from database
+      insforge.database
+        .from('posts')
+        .select('*')
+        .eq('user_id', user.id)
+        .then(({ data }) => setPosts(data));
+    }
+  }, [user]);
+
+  if (!isLoaded) return <div>Loading...</div>;
+  if (!user) return <div>Not signed in</div>;
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+      <h2>My Posts: {posts.length}</h2>
+      {posts.map(post => (
+        <div key={post.id}>{post.title}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+**Key points:**
+- Use `user.id` to filter data for the authenticated user
+- Check `isLoaded` before accessing `user` to avoid race conditions
+- Check `!user` to handle unauthenticated state