insforge 1.2.10 → 1.4.8

package/docs/agent-docs/deployment.md

@@ -0,0 +1,79 @@
+# InsForge Deployment - Agent Documentation
+
+## Overview
+
+Deploy frontend applications to InsForge using the `create-deployment` MCP tool. The tool handles uploading source files, building, and deploying automatically.
+
+## Deploy with MCP Tool
+
+Use the `create-deployment` tool with these parameters:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `sourceDirectory` | Yes | **Absolute path** to source directory (e.g., `/Users/me/project/frontend`). Relative paths do not work. |
+| `projectSettings.buildCommand` | No | Build command (default: auto-detected) |
+| `projectSettings.outputDirectory` | No | Build output directory (default: auto-detected) |
+| `projectSettings.installCommand` | No | Install command (default: `npm install`) |
+| `projectSettings.rootDirectory` | No | Root directory within source |
+| `envVars` | No | Array of `{key, value}` objects |
+| `meta` | No | Custom metadata key-value pairs |
+
+### Example
+
+```json
+{
+  "sourceDirectory": "/Users/me/project/frontend",
+  "projectSettings": {
+    "buildCommand": "npm run build",
+    "outputDirectory": "dist"
+  },
+  "envVars": [
+    { "key": "VITE_INSFORGE_BASE_URL", "value": "https://your-project.insforge.app" },
+    { "key": "VITE_INSFORGE_ANON_KEY", "value": "your-anon-key" }
+  ]
+}
+```
+
+**Important**:
+- `sourceDirectory` must be an **absolute path** (relative paths don't work on Windows)
+- Pass the source directory, NOT pre-built static files
+- Include all required environment variables (e.g., `VITE_*` for Vite apps)
+
+## Check Deployment Status
+
+After creating a deployment, query the status using `run-raw-sql`:
+
+```sql
+SELECT id, status, url, created_at
+FROM system.deployments
+ORDER BY created_at DESC
+LIMIT 1;
+```
+
+### Status Values
+
+| Status | Description |
+|--------|-------------|
+| `WAITING` | Waiting for source upload |
+| `UPLOADING` | Uploading to build server |
+| `QUEUED` | Queued for build |
+| `BUILDING` | Building (typically ~1 min) |
+| `READY` | Deployment complete, URL available |
+| `ERROR` | Build or deployment failed |
+| `CANCELED` | Deployment was cancelled |
+
+### Get Deployment URL
+
+Once status is `READY`, the `url` column contains the live deployment URL.
+
+```sql
+SELECT url FROM system.deployments WHERE id = '<deployment-id>';
+```
+
+## Quick Reference
+
+| Task | Tool | Command |
+|------|------|---------|
+| Deploy app | `create-deployment` | Provide `sourceDirectory` and `envVars` |
+| Check status | `run-raw-sql` | `SELECT status FROM system.deployments WHERE id = '...'` |
+| List deployments | `run-raw-sql` | `SELECT * FROM system.deployments ORDER BY created_at DESC` |

package/docs/agent-docs/real-time.md

@@ -0,0 +1,269 @@
+# InsForge Realtime - Agent Documentation
+
+## Overview
+
+InsForge Realtime enables real-time pub/sub messaging via WebSockets:
+- **Database events**: Emit events when data changes using triggers
+- **Client events**: Clients can publish custom events to each other
+
+## Backend Setup (Raw SQL)
+
+### Step 1: Create Channel Patterns
+
+Define which channels are available:
+
+```sql
+INSERT INTO realtime.channels (pattern, description, enabled)
+VALUES
+  ('orders', 'Global order events', true),
+  ('order:%', 'Order-specific events (order:123, order:456)', true),
+  ('chat:%', 'Chat room events', true);
+```
+
+**Pattern syntax**: Use `:` as separator, `%` as wildcard (SQL LIKE pattern).
+
+### Step 2: Create Triggers for Database Events
+
+**IMPORTANT**: To emit events when database rows change, create a trigger that calls `realtime.publish()`:
+
+```sql
+-- Step 2a: Create the trigger function
+CREATE OR REPLACE FUNCTION notify_order_changes()
+RETURNS TRIGGER AS $$
+BEGIN
+  PERFORM realtime.publish(
+    'order:' || NEW.id::text,    -- channel name
+    TG_OP || '_order',           -- event name: INSERT_order, UPDATE_order, DELETE_order
+    jsonb_build_object(          -- payload (what clients receive)
+      'id', NEW.id,
+      'status', NEW.status,
+      'total', NEW.total
+    )
+  );
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+-- Step 2b: Attach trigger to table
+CREATE TRIGGER order_realtime
+  AFTER INSERT OR UPDATE ON orders
+  FOR EACH ROW
+  EXECUTE FUNCTION notify_order_changes();
+```
+
+### Step 3: Add Access Control (Optional)
+
+**RLS is disabled by default** for the best developer experience. All authenticated and anonymous users can subscribe to any channel and publish messages out of the box.
+
+To restrict access, first enable RLS, then add policies:
+
+#### Step 3a: Enable RLS
+
+```sql
+ALTER TABLE realtime.channels ENABLE ROW LEVEL SECURITY;
+ALTER TABLE realtime.messages ENABLE ROW LEVEL SECURITY;
+```
+
+#### Step 3b: Restrict who can subscribe (SELECT on realtime.channels)
+
+```sql
+-- Only order owner can subscribe to their order channel
+CREATE POLICY "users_subscribe_own_orders"
+ON realtime.channels FOR SELECT
+TO authenticated
+USING (
+  pattern = 'order:%'
+  AND EXISTS (
+    SELECT 1 FROM orders
+    WHERE id = NULLIF(split_part(realtime.channel_name(), ':', 2), '')::uuid
+      AND user_id = auth.uid()
+  )
+);
+```
+
+**Note**: Use `realtime.channel_name()` in subscribe policies to get the actual channel (e.g., `order:123`) since the table only stores patterns (e.g., `order:%`).
+
+#### Step 3c: Restrict who can publish from client (INSERT on realtime.messages)
+
+```sql
+-- Only chat room members can publish messages
+CREATE POLICY "members_publish_chat"
+ON realtime.messages FOR INSERT
+TO authenticated
+WITH CHECK (
+  channel_name LIKE 'chat:%'
+  AND EXISTS (
+    SELECT 1 FROM chat_members
+    WHERE room_id = NULLIF(split_part(channel_name, ':', 2), '')::uuid
+      AND user_id = auth.uid()
+  )
+);
+```
+
+## Frontend SDK
+
+### Setup
+
+```typescript
+import { createClient } from '@insforge/sdk'
+
+const insforge = createClient({
+  baseUrl: 'https://your-project.insforge.app'
+})
+```
+
+### Core Methods
+
+#### connect() - Establish WebSocket connection
+
+```typescript
+await insforge.realtime.connect()
+```
+
+#### subscribe(channel) - Subscribe to a channel
+
+```typescript
+const { ok, error } = await insforge.realtime.subscribe('order:123')
+if (!ok) console.error('Failed:', error?.message)
+```
+
+#### on(event, callback) - Listen for events
+
+```typescript
+// Listen for database-triggered events
+insforge.realtime.on('INSERT_order', (payload) => {
+  console.log('New order:', payload.id, payload.status)
+})
+
+insforge.realtime.on('UPDATE_order', (payload) => {
+  console.log('Order updated:', payload)
+})
+```
+
+#### once(event, callback) - Listen for event once
+
+```typescript
+// Auto-removes after first invocation
+insforge.realtime.once('order_completed', (payload) => {
+  console.log('Order completed:', payload)
+})
+```
+
+#### publish(channel, event, payload) - Send client events
+
+```typescript
+// Must be subscribed to channel first
+await insforge.realtime.publish('chat:room-1', 'new_message', {
+  text: 'Hello!',
+  sender: 'Alice'
+})
+```
+
+#### unsubscribe(channel)
+
+```typescript
+insforge.realtime.unsubscribe('order:123')
+```
+
+#### off(event, callback) - Remove listener
+
+```typescript
+insforge.realtime.off('UPDATE_order', handler)
+```
+
+#### disconnect() - Close connection
+
+```typescript
+insforge.realtime.disconnect()
+```
+
+### Connection Events
+
+```typescript
+insforge.realtime.on('connect', () => console.log('Connected'))
+insforge.realtime.on('disconnect', (reason) => console.log('Disconnected:', reason))
+insforge.realtime.on('connect_error', (err) => console.error('Connection failed:', err))
+insforge.realtime.on('error', ({ code, message }) => console.error('Error:', code, message))
+```
+
+**Error codes**: `UNAUTHORIZED`, `NOT_SUBSCRIBED`, `INTERNAL_ERROR`
+
+### Properties
+
+```typescript
+insforge.realtime.isConnected           // boolean
+insforge.realtime.connectionState       // 'disconnected' | 'connecting' | 'connected'
+insforge.realtime.socketId              // string (when connected)
+insforge.realtime.getSubscribedChannels() // string[]
+```
+
+### Message Metadata
+
+All received messages include a `meta` field:
+
+```typescript
+insforge.realtime.on('UPDATE_order', (payload) => {
+  console.log(payload.meta.messageId)   // UUID
+  console.log(payload.meta.channel)     // 'order:123'
+  console.log(payload.meta.senderType)  // 'system' (trigger) or 'user' (client)
+  console.log(payload.meta.timestamp)   // Date
+
+  // Your payload fields
+  console.log(payload.status)
+})
+```
+
+## Complete Example
+
+**Backend SQL:**
+```sql
+-- 1. Create channel
+INSERT INTO realtime.channels (pattern, description, enabled)
+VALUES ('order:%', 'Order updates', true);
+
+-- 2. Create trigger for database events
+CREATE OR REPLACE FUNCTION notify_order_status()
+RETURNS TRIGGER AS $$
+BEGIN
+  PERFORM realtime.publish(
+    'order:' || NEW.id::text,
+    'status_changed',
+    jsonb_build_object('id', NEW.id, 'status', NEW.status, 'updated_at', NEW.updated_at)
+  );
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+CREATE TRIGGER order_status_trigger
+  AFTER UPDATE ON orders
+  FOR EACH ROW
+  WHEN (OLD.status IS DISTINCT FROM NEW.status)
+  EXECUTE FUNCTION notify_order_status();
+```
+
+**Frontend:**
+```typescript
+await insforge.realtime.connect()
+await insforge.realtime.subscribe(`order:${orderId}`)
+
+// Listen for database-triggered events
+insforge.realtime.on('status_changed', (payload) => {
+  updateUI(payload.status)
+})
+
+// Client can also publish events to the same channel
+await insforge.realtime.publish(`order:${orderId}`, 'customer_viewed', {
+  viewedAt: new Date().toISOString()
+})
+```
+
+## Quick Reference
+
+| Task | How |
+|------|-----|
+| Emit event on DB change | Create trigger calling `realtime.publish(channel, event, payload)` |
+| Client sends event | `insforge.realtime.publish(channel, event, payload)` |
+| Listen for events | `insforge.realtime.on(eventName, callback)` |
+| Listen once | `insforge.realtime.once(eventName, callback)` |
+| Restrict subscribe access | Enable RLS on `realtime.channels`, then add SELECT policy |
+| Restrict client publish | Enable RLS on `realtime.messages`, then add INSERT policy |

package/docs/changelog.mdx

@@ -1,67 +1,212 @@
----
-title: "Changelog"
-description: "Latest updates and improvements to InsForge"
----
-
-## November 2025
-
-<AccordionGroup>
-  <Accordion title="November 30, 2025" icon="rocket">
-    ### QuickStart Prompts & Templates
-    Get started faster with our new quickstart prompts and templates for common apps. Builders can now start with one click and get a fullstack app running in **5 minutes**.
-
-    <img src="/images/changelog/nov-2025/quickstart-prompts.webp" alt="QuickStart Prompts and Templates" />
-
-    ### Auth Components
-    Drop-in prebuilt React auth components for your app. Get a working auth flow right away with social sign-on support built in by default.
-
-    <img src="/images/changelog/nov-2025/auth-components.webp" alt="Auth Components with Social Sign-on" />
-
-    ### Database Metadata Dashboard
-    View your RLS policies, triggers, functions, and indexes all in one place. This makes debugging and understanding your project security much easier.
-
-    <img src="/images/changelog/nov-2025/database-metadata.webp" alt="Database Metadata Dashboard" />
-
-    ### SQL Editor
-    Run SQL queries directly in the InsForge dashboard. No external tools required.
-
-    <img src="/images/changelog/nov-2025/sql-editor.webp" alt="SQL Editor in Dashboard" />
-
-    ### Usage Page
-    A new dashboard section that displays a clear breakdown of your resource usage and what your plan includes.
-
-    <img src="/images/changelog/nov-2025/usage-page.webp" alt="Usage Page Dashboard" />
-  </Accordion>
-</AccordionGroup>
-
-## October 2025
-
-<AccordionGroup>
-  <Accordion title="October 30, 2025" icon="rocket">
-    ### OAuth: 4 New Third-Party Providers
-    You can now enable third-party logins with **LinkedIn, Microsoft, Facebook, and Discord**. On InsForge Cloud, we provide shared credentials for developers who want to quickly test these login flows.
-
-    After enabling, you can implement these logins directly through your agent by sending a simple prompt:
-
-    ```text
-    implement Discord login
-    ```
-
-    <img src="/images/changelog/october-2025/oauth-providers.webp" alt="OAuth Providers - LinkedIn, Microsoft, Facebook, and Discord" />
-
-    ### Import CSV to Your Table
-    You can now upload `.csv` files directly into any table from the dashboard. Perfect for bringing in sample data or migrating from other tools.
-
-    <img src="/images/changelog/october-2025/csv-upload.webp" alt="CSV Upload to Tables Feature" />
-
-    ### InsForge.js SDK
-    We've released our **insforge-js SDK** to make it easier for developers to integrate InsForge into their workflows. Manage auth, query databases, and control your backend programmatically with a few lines of code.
-
-    **Repository:** [GitHub](https://github.com/InsForge/InsForge-sdk-js)
-
-    ### Logs
-    The new logs page lets you monitor container logs in real time. You can watch your backend activity directly in the dashboard, or let AI coding agents query logs through the InsForge MCP to automatically debug and search for errors.
-
-    <img src="/images/changelog/october-2025/logs-feature.webp" alt="Real-time Logs Monitoring Feature" />
-  </Accordion>
-</AccordionGroup>
+---
+title: "Changelog"
+description: "New features, improvements, and fixes shipped to InsForge."
+---
+
+<Update label="Dec 21, 2025" tags={["Realtime", "Auth", "Payments", "AI"]}>
+  ## Realtime Module
+
+  We launched a new Realtime module built on WebSockets with a pub/sub architecture. It supports channels for live updates, message history for state syncing, and RLS-based permissions out of the box—making it well suited for real-time apps, games, chat, and collaborative experiences.
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/realtime2.png" alt="Realtime module with collaborative cursors and messaging" />
+  </Frame>
+
+  ### Apple OAuth
+
+  Apple OAuth is now available in InsForge Auth, as requested by the community. You can enable Sign in with Apple in a few clicks and ship apps with Apple login without manual OAuth setup.
+
+  <Frame>
+    <video autoPlay muted loop playsInline src="/images/changelog/dec-2025/apple-oauth.mp4" />
+  </Frame>
+
+  ### Alipay Payments
+
+  Alipay is now supported for InsForge subscriptions, so you can subscribe without a credit card. This removes a major payment barrier for users in the APAC region.
+
+  ### More Models in the Model Gateway
+
+  We have added more popular and state-of-the-art models to the InsForge Model Gateway so you can choose the right model for each use case:
+
+  - **GPT 5.2** - Stronger reasoning and longer context
+  - **DeepSeek V3** - High performance at a lower cost
+  - **Gemini 3 Flash** - Low latency real-time inference
+
+  More models are coming soon.
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/moreModels.png" alt="AI Integration dashboard with new models" />
+  </Frame>
+
+  [View AI SDK documentation →](/core-concepts/ai/sdk)
+</Update>
+
+<Update label="Dec 19, 2025" tags={["Multi Region", "Postgres Connection"]}>
+  ## Multi-Region Deployments
+  Deploy your project to the appropriate region for improved latency and compliance. We currently support `us-east`, `us-west`, `eu-central` and `ap-southeast` regions. More regions will be added based on demand.
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/multi-region.webp" alt="Multi-Region Deployments" />
+  </Frame>
+
+  ## Postgres Connection
+  Connect to your project's Postgres database and query it directly from your database clients. This also allows you to integrate InsForge with external services and tools like n8n.
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/postgres-connection.webp" alt="Postgres Connection" />
+  </Frame>
+</Update>
+
+<Update label="Dec 16, 2025" tags={["Email"]}>
+  ## Custom Emails (Private Preview)
+  Send custom transactional emails directly from your app using the SDK. Supports multiple recipients, CC/BCC, custom sender names, and full HTML content.
+
+  [View Email SDK documentation →](/core-concepts/email/sdk)
+</Update>
+
+<Update label="Dec 12, 2025" tags={["Payments", "AI"]}>
+  ## Alipay Payment Support
+  Added **Alipay** as an alternative payment method. Users can now pay for InsForge subscriptions without a credit card.
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/alipay-payment.webp" alt="Alipay payment method option" />
+  </Frame>
+
+  ## New AI Models
+  Expanded AI model support:
+  - **GPT-5.2** - OpenAI's latest flagship model with enhanced reasoning, longer context windows, and improved instruction following
+  - **DeepSeek V3** - Open-weight model offering strong performance at lower cost, ideal for high-volume workloads
+
+  [View AI SDK documentation →](/core-concepts/ai/sdk)
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/ai-models.webp" alt="AI Integration with new models" />
+  </Frame>
+</Update>
+
+<Update label="Dec 11, 2025" tags={["Auth", "Realtime"]}>
+  ## Apple Login
+  **Sign in with Apple** is now available as an OAuth provider. Enable it in your project settings and let users authenticate with their Apple ID. Like other social providers, InsForge Cloud offers shared credentials for quick testing.
+
+  [View Authentication docs →](/core-concepts/authentication/sdk)
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/apple-login.jpg" alt="Sign in with Apple authentication" />
+  </Frame>
+
+  ## Realtime Module
+  Build apps with **realtime pub/sub messaging**. Whether you're creating a chat room, multiplayer game, or collaborative document editor, the new Realtime module handles WebSocket connections, channel subscriptions, and message delivery out of the box.
+
+  Key features include:
+  - **Channel patterns** with wildcard support (e.g., `chat:*`, `game:lobby`)
+  - **Webhook integrations** for server-side event processing
+  - **Message history** and delivery analytics
+  - **RLS-based permissions** for secure subscribe and publish operations
+
+  [View Realtime SDK documentation →](/core-concepts/realtime/sdk)
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/realtime-module.jpg" alt="Realtime multiplayer chess game demo" />
+  </Frame>
+</Update>
+
+<Update label="Dec 7, 2025" tags={["AI", "Security"]}>
+  ## AI Integration
+  Expanded model support with smarter defaults for different use cases.
+
+  - **Gemini 3 Pro** is now the default image generation model.
+  - **Grok 4.1 Fast** added to model selection for quicker, lightweight inference.
+
+  [View AI SDK documentation →](/core-concepts/ai/sdk)
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/ai-integration.png" alt="AI Integration with new models" />
+  </Frame>
+
+  ## MCP Installer
+  Updated installer experience with a new InsForge-branded startup screen and clearer next-step instructions.
+
+  <Frame>
+    <img src="/images/changelog/dec-2025/mcp-installer.png" alt="MCP Installer with InsForge branding" />
+  </Frame>
+
+  ## Security & Framework Updates
+  Updated Next.js and React versions in response to a [security incident](https://nextjs.org/blog/CVE-2025-66478).
+</Update>
+
+<Update label="Nov 30, 2025" tags={["Dashboard", "Auth"]}>
+  ## QuickStart Prompts & Templates
+  Get started faster with our new quickstart prompts and templates for common apps. Builders can now start with one click and get a fullstack app running in **5 minutes**.
+
+  [Try the quickstart →](/quickstart)
+
+  <Frame>
+    <img src="/images/changelog/nov-2025/quickstart-prompts.webp" alt="QuickStart Prompts and Templates" />
+  </Frame>
+
+  ## Auth Components
+  Drop-in prebuilt React auth components for your app. Get a working auth flow right away with social sign-on support built in by default.
+
+  [View Auth Components docs →](/core-concepts/authentication/ui-components/react)
+
+  <Frame>
+    <img src="/images/changelog/nov-2025/auth-components.webp" alt="Auth Components with Social Sign-on" />
+  </Frame>
+
+  ## Database Metadata Dashboard
+  View your RLS policies, triggers, functions, and indexes all in one place. This makes debugging and understanding your project security much easier.
+
+  <Frame>
+    <img src="/images/changelog/nov-2025/database-metadata.webp" alt="Database Metadata Dashboard" />
+  </Frame>
+
+  ## SQL Editor
+  Run SQL queries directly in the InsForge dashboard. No external tools required.
+
+  <Frame>
+    <img src="/images/changelog/nov-2025/sql-editor.webp" alt="SQL Editor in Dashboard" />
+  </Frame>
+
+  ## Usage Page
+  A new dashboard section that displays a clear breakdown of your resource usage and what your plan includes.
+
+  <Frame>
+    <img src="/images/changelog/nov-2025/usage-page.webp" alt="Usage Page Dashboard" />
+  </Frame>
+</Update>
+
+<Update label="Oct 30, 2025" tags={["Auth", "SDK"]}>
+  ## OAuth: 4 New Third-Party Providers
+  You can now enable third-party logins with **LinkedIn, Microsoft, Facebook, and Discord**. On InsForge Cloud, we provide shared credentials for developers who want to quickly test these login flows.
+
+  After enabling, you can implement these logins directly through your agent by sending a simple prompt:
+
+  ```text
+  implement Discord login
+  ```
+
+  [View Authentication docs →](/core-concepts/authentication/sdk)
+
+  <Frame>
+    <img src="/images/changelog/october-2025/oauth-providers.webp" alt="OAuth Providers - LinkedIn, Microsoft, Facebook, and Discord" />
+  </Frame>
+
+  ## Import CSV to Your Table
+  You can now upload `.csv` files directly into any table from the dashboard. Perfect for bringing in sample data or migrating from other tools.
+
+  <Frame>
+    <img src="/images/changelog/october-2025/csv-upload.webp" alt="CSV Upload to Tables Feature" />
+  </Frame>
+
+  ## InsForge.js SDK
+  We've released our **insforge-js SDK** to make it easier for developers to integrate InsForge into their workflows. Manage auth, query databases, and control your backend programmatically with a few lines of code.
+
+  [GitHub](https://github.com/InsForge/InsForge-sdk-js) · [Database SDK →](/core-concepts/database/sdk)
+
+  ## Logs
+  The new logs page lets you monitor container logs in real time. You can watch your backend activity directly in the dashboard, or let AI coding agents query logs through the InsForge MCP to automatically debug and search for errors.
+
+  <Frame>
+    <img src="/images/changelog/october-2025/logs-feature.webp" alt="Real-time Logs Monitoring Feature" />
+  </Frame>
+</Update>