insforge 0.3.1

package/docs/deprecated/insforge-db-api.md

@@ -0,0 +1,359 @@
+# Insforge OSS Database API Documentation
+
+## API Basics
+
+**Base URL:** `http://localhost:7130`
+
+**Note:** Avoid special characters (!,$,`,\) in curl command data - they can cause bash interpretation issues. Use simple text for testing.
+
+**Authentication Requirements:**
+- **READ operations (GET):** No authentication required - public access by default
+- **WRITE operations (POST/PATCH/DELETE):** Requires `Authorization: Bearer <token>` header (JWT token or API key for MCP testing)
+
+**Important: How Authentication Works**
+1. Login returns a **JWT access token** - e.g., `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
+2. Just use: `Authorization: Bearer <token>` in your requests
+3. API keys (starting with `ik_`) can also be used as Bearer tokens for testing
+**Critical:** Always call `get-backend-metadata` first to understand current database structure
+**Critical:** POST body must be arrays `[{...}]`, query filters `?field=eq.value`, add header `Prefer: return=representation` to return created data - follows PostgREST design (not traditional REST)
+
+## Table Operations (Use MCP Tools)
+
+### Available MCP Tools
+
+1. **get-backend-metadata** - Get current database structure (always start here)
+2. **create-table** - Create new table with explicit schema
+3. **update-table-schema** - Alter existing table schema  
+4. **delete-table** - Remove table completely
+5. **get-table-schema** - Get specific table structure
+
+### Column Types
+- `string` - Text data
+- `integer` - Whole numbers
+- `float` - Decimal numbers
+- `boolean` - True/false values
+- `datetime` - Date and time
+- `json` - JSON objects
+- `uuid` - Unique identifiers
+
+## Record Operations (Use REST API)
+
+### Base URL
+`/api/database/records/:tableName`
+
+### Query Records
+**GET** `/api/database/records/:tableName`
+
+Query parameters:
+- `limit` - Maximum records (default: 100)
+- `offset` - Skip records for pagination
+- `order` - Sort by field (e.g., `createdAt.desc`)
+- PostgREST filters: `field=eq.value`, `field=gt.value`, etc.
+
+Response: Array of records with auto-generated `id`, `created_at`, `updated_at` fields
+
+Example:
+```bash
+# Windows PowerShell: use curl.exe
+curl -X GET "http://localhost:7130/api/database/records/posts?limit=10"
+```
+
+### Create Records
+**POST** `/api/database/records/:tableName`
+
+**AUTHENTICATION REQUIRED** - Must include `Authorization: Bearer <token>`
+
+**CRITICAL**: Request body MUST be an array, even for single records!
+
+**⚠️ IMPORTANT: Default Response Behavior**
+- **By default, POST requests return an empty array `[]`**
+- **To get the created records in the response, you MUST include the header:**
+  ```
+  Prefer: return=representation
+  ```
+- **Without this header, you get no data back, just an empty array!**
+
+Send array of records:
+```json
+[
+  {
+    "field1": "value1",
+    "field2": "value2"
+  }
+]
+```
+
+For a single record, still wrap in array:
+```json
+[
+  {
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+]
+```
+
+Response format (WITHOUT `Prefer` header - default):
+```json
+[]
+```
+
+Response format (WITH `Prefer: return=representation` header):
+```json
+[
+  {
+    "id": "248373e1-0aea-45ce-8844-5ef259203749",
+    "name": "John Doe",
+    "email": "john@example.com",
+    "createdAt": "2025-07-18T05:37:24.338Z",
+    "updatedAt": "2025-07-18T05:37:24.338Z"
+  }
+]
+```
+
+Example:
+```bash
+# Mac/Linux
+curl -X POST http://localhost:7130/api/database/records/comments \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -H 'Prefer: return=representation' \
+  -d '[{"user_id": "from-localStorage", "post_id": "post-uuid", "content": "Great"}]'
+
+# Windows PowerShell (use curl.exe) - different quotes needed for nested JSON
+curl.exe -X POST http://localhost:7130/api/database/records/comments \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -H "Prefer: return=representation" \
+  -d '[{\"user_id\": \"from-localStorage\", \"post_id\": \"post-uuid\", \"content\": \"Great\"}]'
+```
+
+### Update Record
+**PATCH** `/api/database/records/:tableName?id=eq.uuid`
+
+**AUTHENTICATION REQUIRED**
+
+**⚠️ IMPORTANT: PATCH Limitations**
+- **PostgREST does NOT support SQL expressions** like `count + 1`
+- You must fetch the current value and calculate in your code:
+
+```javascript
+// ❌ WRONG - This will NOT work
+await api.patch(`/api/database/records/posts?id=eq.${postId}`, {
+  comments_count: 'comments_count + 1'  // PostgREST doesn't evaluate expressions!
+});
+
+// ✅ CORRECT - Fetch and calculate
+const post = await api.get(`/api/database/records/posts?id=eq.${postId}`);
+await api.patch(`/api/database/records/posts?id=eq.${postId}`, {
+  comments_count: post.data[0].comments_count + 1
+});
+```
+
+**Default Response Behavior**
+- **By default, PATCH requests return an empty array `[]`**
+- **To get the updated record in the response, you MUST include the header:**
+  ```
+  Prefer: return=representation
+  ```
+
+Send fields to update:
+```json
+{
+  "field1": "new_value"
+}
+```
+
+Response format (WITHOUT `Prefer: return=representation` header - default):
+```json
+""
+```
+
+Response format (WITH `Prefer: return=representation` header):
+```json
+[
+  {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "field1": "new_value",
+    "createdAt": "2025-01-01T00:00:00Z",
+    "updatedAt": "2025-01-21T11:00:00Z"
+  }
+]
+```
+
+### Delete Record
+**DELETE** `/api/database/records/:tableName?id=eq.uuid`
+
+**AUTHENTICATION REQUIRED**
+
+**⚠️ IMPORTANT: Delete Behavior**
+- **Without `Prefer: return=representation`**: Returns `204 No Content` (no body)
+- **With `Prefer: return=representation`**: Returns `200 OK` with:
+  - `[{...}]` - Array containing deleted record(s) if found
+  - `[]` - Empty array if record didn't exist
+- **DELETE is idempotent**: No error if record doesn't exist
+
+Response format (WITHOUT `Prefer` header - default):
+```
+204 No Content (no body)
+```
+
+Response format (WITH `Prefer: return=representation` header):
+```json
+// If record existed and was deleted:
+[
+  {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "name": "Deleted User",
+    "createdAt": "2025-01-01T00:00:00Z",
+    "updatedAt": "2025-01-21T11:00:00Z"
+  }
+]
+
+// If record didn't exist (already deleted or never existed):
+[]
+```
+
+## Error Response Format
+
+All error responses follow this format:
+```json
+{
+  "error": "ERROR_CODE",
+  "message": "Human-readable error message",
+  "statusCode": 400,
+  "nextActions": "Suggested action to resolve the error"
+}
+```
+
+Example error:
+```json
+{
+  "error": "TABLE_NOT_FOUND",
+  "message": "Table 'nonexistent' does not exist",
+  "statusCode": 404,
+  "nextActions": "Check table name and try again"
+}
+```
+
+## Pagination
+
+For paginated results, use the `Range` header:
+```bash
+# Windows PowerShell: use curl.exe
+curl "http://localhost:7130/api/database/records/posts" \
+  -H "Range: 0-9" \
+  -H "Prefer: count=exact"
+```
+
+Response includes `Content-Range` header:
+```
+Content-Range: 0-9/100  # Shows items 0-9 out of 100 total
+```
+
+Without `Prefer: count=exact`, you get: `Content-Range: 0-9/*` (no total count)
+
+## 🚨 Working with User Data
+
+**The `users` table stores user profiles:**
+- **✅ READ**: `GET /api/database/records/users` - Get user profiles
+- **✅ WRITE**: `PATCH /api/database/records/users?id=eq.<user_id>` - Update profiles
+
+**Schema:**
+- `id` - User ID (UUID, references auth system)
+- `nickname` - Display name (text, nullable)
+- `avatar_url` - Profile picture URL (text, nullable)
+- `bio` - User biography (text, nullable)
+- `birthday` - Birth date (date, nullable)
+- `created_at` - Profile creation timestamp
+- `updated_at` - Last update timestamp
+
+**Important:**
+- User accounts (email, password) are managed via Auth API only
+- The `users` table is automatically created when a user registers
+- Use `users.id` for foreign key references in your tables
+
+**Creating tables with user references:**
+```json
+{
+  "table_name": "posts",
+  "columns": [
+    {"name": "user_id", "type": "string", "nullable": false,
+     "foreign_key": {"reference_table": "users", "reference_column": "id", 
+                     "on_delete": "CASCADE", "on_update": "CASCADE"}},
+    {"name": "content", "type": "string", "nullable": false}
+  ]
+}
+```
+
+## 🚨 Critical: Always Include user_id
+
+**Every user-related table MUST include user_id field from localStorage:**
+
+```javascript
+// Frontend: Get user_id from localStorage after login
+const userId = localStorage.getItem('user_id');
+```
+
+```bash
+# ❌ WRONG - Missing user_id
+curl -X POST http://localhost:7130/api/database/records/comments \
+  -H "Authorization: Bearer TOKEN" \
+  -d '[{"content": "Great post"}]'
+
+# ✅ CORRECT - Includes user_id
+# Mac/Linux
+curl -X POST http://localhost:7130/api/database/records/comments \
+  -H 'Authorization: Bearer TOKEN' \
+  -H 'Prefer: return=representation' \
+  -d '[{"content": "Great post", "user_id": "user-uuid-from-localStorage"}]'
+
+# Windows PowerShell (use curl.exe) - different quotes needed for nested JSON
+curl.exe -X POST http://localhost:7130/api/database/records/comments \
+  -H "Authorization: Bearer TOKEN" \
+  -H "Prefer: return=representation" \
+  -d '[{\"content\": \"Great post\", \"user_id\": \"user-uuid-from-localStorage\"}]'
+```
+
+**Required for all user-related operations:**
+- Creating posts, comments, likes, follows
+- Any table with a `user_id` foreign key
+- Without it, your INSERT will fail with missing field error
+
+## Important Rules
+
+1. **Authentication Summary**:
+   | Operation | Auth Required | Header |
+   |-----------|--------------|--------|
+   | GET (read) | ❌ No | None needed |
+   | POST (create) | ✅ Yes | `Authorization: Bearer <token>` |
+   | PATCH (update) | ✅ Yes | `Authorization: Bearer <token>` |
+   | DELETE | ✅ Yes | `Authorization: Bearer <token>` |
+
+2. **Auto-Generated Fields**
+   - `id` - UUID primary key (auto-generated)
+   - `createdAt` - Timestamp (auto-set)
+   - `updatedAt` - Timestamp (auto-updated)
+
+2. **System Tables**
+   - Tables prefixed with `_` are system tables (protected)
+   - User profiles stored in `users` table (read/write allowed)
+   - Account management only through Auth API (register/login)
+
+3. **Common PostgREST Errors**:
+   ```json
+   {"code": "42501", "message": "permission denied for table comments"}
+   // Means: User not authenticated for write operation
+   
+   {"code": "PGRST301", "message": "JWSError (CompactDecodeError Invalid number of parts: Expected 3 parts; got 1)"}
+   // Means: Invalid or expired token - user needs to login again
+   ```
+
+4. **Remember**
+   - READ operations are public (no auth needed)
+   - WRITE operations require token from login
+   - POST needs array `[{...}]` even for single record
+   - Add `Prefer: return=representation` to see created/updated data  
+   - PATCH cannot use SQL expressions - calculate in JavaScript
+   - Tokens from login work directly as Bearer tokens
+   - Always include `user_id` in user-related tables

package/docs/deprecated/insforge-db-sdk.md

@@ -0,0 +1,140 @@
+# InsForge Database SDK
+
+## Setup
+```javascript
+import { createClient } from '@insforge/sdk';
+const client = createClient({ baseUrl: 'http://localhost:7130' });
+```
+
+## Query Builder
+
+### from(table)
+```javascript
+client.database.from('posts')  // Returns QueryBuilder
+```
+
+## Operations
+
+### select
+```javascript
+.select()              // All columns
+.select('id, title')   // Specific columns
+.select('*, user:user_id(name, email)')  // Foreign key expansion
+```
+
+### insert
+```javascript
+.insert({ title: 'Hello' }).select()     // Single record with data returned
+.insert([{...}, {...}]).select()         // Multiple records with data returned
+// Note: Always sends array to API
+// Without .select(), returns null data
+```
+
+### update
+```javascript
+.update({ title: 'Updated' }).eq('id', '123').select()
+// Must chain with filter and .select() to return data
+```
+
+### delete
+```javascript
+.delete().eq('id', '123').select()
+// Must chain with filter and .select() to return data
+```
+
+### upsert
+```javascript
+.upsert({ id: '123', title: 'New or Update' }).select()
+// Updates if exists, inserts if not
+// Use .select() to return data
+```
+
+## Filters
+
+```javascript
+.eq('col', value)      // column = value
+.neq('col', value)     // column != value
+.gt('col', value)      // column > value
+.gte('col', value)     // column >= value
+.lt('col', value)      // column < value
+.lte('col', value)     // column <= value
+.like('col', '%pat%')  // LIKE pattern
+.ilike('col', '%pat%') // ILIKE pattern
+.is('col', null)       // IS NULL
+.in('col', [1,2,3])    // IN array
+
+.or('status.eq.active,status.eq.pending')  // OR condition
+.and('price.gte.100,price.lte.500')        // Explicit AND
+.not('deleted', 'is.true')                 // NOT condition
+```
+
+### OR Examples
+```javascript
+// Simple OR
+.or('status.eq.active,status.eq.pending')
+// WHERE status = 'active' OR status = 'pending'
+
+// OR with other filters (implicit AND)
+.eq('user_id', '123')
+.or('status.eq.draft,status.eq.published')
+// WHERE user_id = '123' AND (status = 'draft' OR status = 'published')
+
+// Complex OR with NOT
+.or('age.lt.18,age.gt.65,not.is_active.is.true')
+// WHERE age < 18 OR age > 65 OR NOT is_active
+```
+
+## Modifiers
+
+```javascript
+.order('col')                        // ASC
+.order('col', { ascending: false })  // DESC
+.limit(10)
+.offset(20)
+.range(0, 9)                         // Headers: Range: 0-9
+.single()                            // Return object not array
+.count('exact')                      // Include total count
+```
+
+## Execute
+
+```javascript
+// Methods are thenable
+const { data, error } = await client.database
+  .from('posts')
+  .select()
+  .eq('user_id', '123')
+  .limit(10);
+
+// data: array or null
+// error: { message, statusCode, code } or null
+```
+
+## Foreign Key Expansion
+
+```javascript
+// PostgREST syntax
+.select('*, user:user_id(name, email)')
+
+// Response:
+{
+  id: '123',
+  title: 'Post',
+  user_id: '456',
+  user: { name: 'John', email: 'john@example.com' }
+}
+```
+
+## Users Table
+
+```javascript
+// Profile data (not auth)
+await client.database.from('users').select().eq('id', userId).single()
+await client.database.from('users').update({ nickname, avatar_url }).eq('id', userId).select()
+```
+
+## Notes
+- Uses PostgREST under the hood
+- POST requires array format `[{...}]`
+- All methods return QueryBuilder for chaining
+- Execute returns `{ data, error }`

package/docs/deprecated/insforge-debug-sdk.md

@@ -0,0 +1,157 @@
+# InsForge Debug SDK
+
+## Common SDK Errors
+
+### Auth Errors
+```javascript
+// Token not stored
+{ code: 'MISSING_AUTHORIZATION_HEADER' }
+// Fix: User needs to login
+
+// Token expired
+{ code: 'INVALID_TOKEN' }
+// Fix: client.auth.signInWithPassword()
+
+// Invalid credentials
+{ code: 'INVALID_CREDENTIALS' }
+// Fix: Check email/password
+```
+
+### Database Errors
+```javascript
+// Table doesn't exist
+{ statusCode: 404, message: 'Table not found' }
+// Fix: Use MCP tool to create table
+
+// Missing required field
+{ code: '23502', message: 'null value in column "user_id"' }
+// Fix: Include all required fields
+
+// Foreign key violation
+{ code: '23503', message: 'violates foreign key constraint' }
+// Fix: Referenced record must exist
+
+// Permission denied
+{ code: '42501', message: 'permission denied for table' }
+// Fix: User must be authenticated
+```
+
+## Debug Techniques
+
+### 1. Check Authentication
+```javascript
+const { data, error } = await client.auth.getCurrentUser();
+if (error) {
+  console.log('Not authenticated:', error.message);
+  // Need to login first
+}
+```
+
+### 2. Verify Token Storage
+```javascript
+const { data } = await client.auth.getCurrentSession();
+console.log('Stored token:', data?.session?.accessToken ? 'Present' : 'Missing');
+```
+
+### 3. Test Database Connection
+```javascript
+// Simple query to test connection
+const { error } = await client.database.from('users').select().limit(1);
+if (error) {
+  console.log('Database issue:', error);
+}
+```
+
+### 4. Enable Network Inspection
+```javascript
+// Browser: Open DevTools > Network tab
+// Check request headers for Authorization: Bearer token
+// Check response for error details
+```
+
+### 5. Test With Raw HTTP
+```javascript
+// When SDK fails, test endpoint directly
+const response = await fetch('http://localhost:7130/api/database/records/posts', {
+  headers: {
+    'Authorization': 'Bearer ' + token
+  }
+});
+const data = await response.json();
+console.log('Raw response:', data);
+```
+
+## Common Issues
+
+### Empty Response
+```javascript
+// INSERT/UPDATE/DELETE return empty without Prefer header
+// SDK handles this automatically, but check if using raw API
+```
+
+### Array Format
+```javascript
+// POST requires array
+// ❌ Wrong: { title: 'Test' }
+// ✅ Right: [{ title: 'Test' }]
+// SDK handles this automatically
+```
+
+### Token Not Persisting
+```javascript
+// Check storage adapter
+const client = createClient({
+  baseUrl: 'http://localhost:7130',
+});
+```
+
+### CORS Issues
+```javascript
+// Backend allows all origins by default
+// If modified, check backend CORS settings
+```
+
+## Test Utilities
+
+### Full Test Suite
+```javascript
+async function testSDK() {
+  const email = `test-${Date.now()}@example.com`;
+  
+  // Test auth
+  console.log('Testing auth...');
+  const { error: signUpError } = await client.auth.signUp({ email, password: 'test123' });
+  if (signUpError) return console.error('SignUp failed:', signUpError);
+  
+  // Test current user
+  const { data: user, error: userError } = await client.auth.getCurrentUser();
+  if (userError) return console.error('GetUser failed:', userError);
+  console.log('✅ Auth working, user:', user.user.id);
+  
+  // Test database
+  console.log('Testing database...');
+  const { data: posts, error: dbError } = await client.database.from('posts').select().limit(1);
+  if (dbError) return console.error('Database failed:', dbError);
+  console.log('✅ Database working, posts:', posts.length);
+  
+  // Test insert
+  const { error: insertError } = await client.database
+    .from('posts')
+    .insert({ title: 'Test', user_id: user.user.id })
+    .select();
+  if (insertError) return console.error('Insert failed:', insertError);
+  console.log('✅ Insert working');
+}
+
+testSDK().catch(console.error);
+```
+
+## Backend Verification
+
+```javascript
+// Check backend is running
+fetch('http://localhost:7130/api/health')
+  .then(r => r.json())
+  .then(d => console.log('Backend:', d))
+  .catch(e => console.error('Backend not running'));
+```