insforge 1.2.10 → 1.4.8

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

@@ -0,0 +1,152 @@
+---
+title: Deployment Architecture
+description: Zero-config web app deployments powered by Vercel
+---
+
+<Warning>
+  Deployments is an experimental feature. APIs and behavior may change.
+</Warning>
+
+## Overview
+
+InsForge Deployments enable developers to deploy web applications with a single prompt. By integrating with coding agents via InsForge MCP, developers can simply say "Deploy my app" and have their application live within a minute—no configuration required.
+
+## Technology Stack
+
+```mermaid
+graph TB
+    Agent[Coding Agent] --> MCP[InsForge MCP]
+    MCP --> API[InsForge Server]
+
+    API --> S3[AWS S3]
+    S3 --> Vercel[Vercel Edge Network]
+
+    API --> DB[(PostgreSQL)]
+    DB --> Metadata[Deployment Metadata]
+    DB --> Status[Status Tracking]
+
+    Vercel --> Live[Live Application]
+
+    style Agent fill:#1e293b,stroke:#475569,color:#e2e8f0
+    style MCP fill:#1e40af,stroke:#3b82f6,color:#dbeafe
+    style API fill:#166534,stroke:#22c55e,color:#dcfce7
+    style S3 fill:#ea580c,stroke:#f97316,color:#fed7aa
+    style Vercel fill:#000000,stroke:#ffffff,color:#ffffff
+    style DB fill:#0e7490,stroke:#06b6d4,color:#cffafe
+    style Metadata fill:#0e7490,stroke:#22d3ee,color:#cffafe
+    style Status fill:#0e7490,stroke:#22d3ee,color:#cffafe
+    style Live fill:#166534,stroke:#22c55e,color:#dcfce7
+```
+
+## Core Components
+
+| Component | Technology | Purpose |
+|-----------|------------|---------|
+| **Edge Storage** | AWS S3 | Temporary source file staging |
+| **Build Platform** | Vercel | Production builds and hosting |
+| **Status Tracking** | PostgreSQL | Deployment state and metadata |
+| **Webhook Handler** | HMAC-SHA1 | Real-time build status updates |
+
+## How It Works
+
+### Deployment Flow
+
+```mermaid
+sequenceDiagram
+    participant Agent as Coding Agent
+    participant API as InsForge Server
+    participant S3 as AWS S3
+    participant Vercel as Vercel
+
+    Agent->>API: Create deployment
+    API-->>Agent: Upload URL + deployment ID
+
+    Agent->>S3: Upload source.zip
+    S3-->>Agent: Upload complete
+
+    Agent->>API: Start deployment
+    API->>S3: Download source
+    API->>Vercel: Upload files
+    API->>Vercel: Create deployment
+    API-->>Agent: Deployment started
+
+    Vercel->>Vercel: Build application
+    Vercel->>API: Webhook: Build complete
+
+    Agent->>API: Check status
+    API-->>Agent: READY + live URL
+```
+
+### Step-by-Step Process
+
+1. **Create Deployment**: Agent requests a new deployment, receiving a presigned S3 upload URL
+2. **Upload Source**: Source files are zipped and uploaded directly to S3 via edge network
+3. **Start Build**: InsForge downloads the source, extracts files, and uploads to Vercel
+4. **Build & Deploy**: Vercel builds the application and deploys to its edge network
+5. **Go Live**: Application becomes available at `https://{app-key}.insforge.site`
+
+The entire process typically completes in about one minute.
+
+## Deployment Status
+
+| Status | Description |
+|--------|-------------|
+| `WAITING` | Deployment created, awaiting source upload |
+| `UPLOADING` | Source files being processed |
+| `QUEUED` | Build queued on Vercel |
+| `BUILDING` | Application being built |
+| `READY` | Live and accessible |
+| `ERROR` | Build failed |
+| `CANCELED` | Deployment canceled |
+
+## Environment Variables
+
+Environment variables can be passed during deployment for build-time configuration. They are encrypted at rest and in transit, and are only accessible during the build process. For auditing purposes, only variable names are logged, never values.
+
+<Warning>
+  While environment variables are encrypted, avoid storing sensitive credentials in frontend applications. Variables prefixed with `NEXT_PUBLIC_` or similar are embedded in client bundles.
+</Warning>
+
+## Current Limitations
+
+<Note>
+  This is an experimental feature with the following constraints:
+</Note>
+
+| Limitation | Details |
+|------------|---------|
+| **Environment** | Production deployments only |
+| **Custom Domains** | Coming soon |
+| **Preview Deployments** | Coming soon |
+| **Build Logs** | Limited visibility |
+
+## Performance
+
+### Edge Network Optimization
+
+Both AWS S3 and Vercel utilize global edge networks, enabling:
+
+- **Fast Uploads**: Source files uploaded to nearest S3 edge location
+- **Rapid Builds**: Vercel's distributed build infrastructure
+- **Global Distribution**: Deployed applications served from edge locations worldwide
+- **Low Latency**: Sub-100ms response times for static assets
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Keep Builds Small" icon="minimize">
+    Avoid uploading large assets. Use InsForge Storage and access via URLs.
+  </Card>
+
+  <Card title="Use Environment Variables" icon="key">
+    Configure builds via env vars, not hardcoded values
+  </Card>
+
+  <Card title="Test Locally First" icon="flask">
+    Verify builds work locally before deploying
+  </Card>
+
+  <Card title="Monitor Status" icon="chart-line">
+    Check deployment status for build errors
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,103 @@
+---
+title: Email Architecture
+description: Transactional email delivery powered by AWS SES
+---
+
+<Warning>
+  Email is an experimental feature. APIs and behavior may change.
+</Warning>
+
+## Overview
+
+InsForge provides a managed email service for sending transactional emails. Built on AWS SES, it offers high deliverability and scalability without requiring you to configure email infrastructure.
+
+## Technology Stack
+
+```mermaid
+graph TB
+    Client[Client Application] --> SDK[InsForge SDK]
+    SDK --> API[Email API]
+    API --> Cloud[InsForge Cloud]
+    Cloud --> SES[AWS SES]
+    SES --> Inbox[Recipient Inbox]
+
+    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 Cloud fill:#7c3aed,stroke:#a78bfa,color:#ede9fe
+    style SES fill:#ea580c,stroke:#f97316,color:#fed7aa
+    style Inbox fill:#0e7490,stroke:#06b6d4,color:#cffafe
+```
+
+## How It Works
+
+1. **SDK Call** - Your application calls `emails.send()` with recipients and HTML content
+2. **API Processing** - Request is validated and authenticated
+3. **Cloud Delivery** - InsForge Cloud queues and sends via AWS SES
+4. **Delivery** - Email is delivered to recipient inboxes
+
+```mermaid
+sequenceDiagram
+    participant App as Your App
+    participant SDK as InsForge SDK
+    participant API as Email API
+    participant SES as AWS SES
+
+    App->>SDK: emails.send({to, subject, html})
+    SDK->>API: POST /api/email/send-raw
+    API->>SES: Queue for delivery
+    SES-->>API: Accepted
+    API-->>SDK: Success
+    SDK-->>App: {data, error}
+```
+
+## Key Features
+
+<CardGroup cols={2}>
+  <Card title="High Deliverability" icon="inbox">
+    AWS SES infrastructure with optimized sending reputation
+  </Card>
+
+  <Card title="Multiple Recipients" icon="users">
+    Send to up to 50 recipients per request with CC/BCC support
+  </Card>
+
+  <Card title="Custom Sender" icon="signature">
+    Customize the sender display name for your brand
+  </Card>
+
+  <Card title="HTML Content" icon="code">
+    Full HTML email support for rich formatting
+  </Card>
+</CardGroup>
+
+## Rate Limits
+
+| Plan | Limit |
+|------|-------|
+| **Starter** | 10 emails per hour |
+| **Pro** | 50 emails per hour |
+
+<Note>
+Custom transactional emails require a paid plan. Authentication emails (verification, password reset) are included in all plans.
+</Note>
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Validate Recipients" icon="at">
+    Verify email addresses before sending to maintain deliverability
+  </Card>
+
+  <Card title="Meaningful Content" icon="envelope-open-text">
+    Send relevant, expected emails to avoid spam reports
+  </Card>
+
+  <Card title="Handle Errors" icon="triangle-exclamation">
+    Always check the error response and handle failures gracefully
+  </Card>
+
+  <Card title="Respect Limits" icon="gauge">
+    Implement queuing for bulk sends to stay within rate limits
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,53 @@
+---
+title: Emails SDK Reference
+description: Send custom transactional emails with the InsForge SDK
+---
+
+<Note>**Private Preview** - This feature is currently in private preview.</Note>
+
+import Installation from '/snippets/sdk-installation.mdx';
+
+<Installation />
+
+## emails.send()
+
+Send custom HTML emails to one or more recipients.
+
+### Parameters
+
+- `to` (string | string[], required) - Recipient email(s), max 50 recipients
+- `subject` (string, required) - Email subject line, max 500 characters
+- `html` (string, required) - HTML content of the email
+- `cc` (string | string[], optional) - CC recipient(s), max 50 recipients
+- `bcc` (string | string[], optional) - BCC recipient(s), max 50 recipients
+- `from` (string, optional) - Custom sender name, max 100 characters
+- `replyTo` (string, optional) - Reply-to email address, must be a valid email address
+
+### Returns
+
+```typescript
+{
+  data: {} | null,  // Empty object on success
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.emails.send({
+  to: ['user1@example.com', 'user2@example.com'],
+  cc: 'manager@example.com',
+  from: 'Acme Support Team',
+  subject: 'Team Update',
+  html: '<h1>Weekly Update</h1><p>Here are this week\'s highlights...</p>',
+  replyTo: 'support@example.com'
+});
+
+if (error) {
+  console.error('Failed to send email:', error.message);
+  return;
+}
+
+console.log('Email sent successfully');
+```

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

@@ -1,105 +1,105 @@
----
-title: Architecture
-description: Serverless JavaScript functions running in isolated Deno runtime
----
-
-## Overview
-
-InsForge Functions provide a secure, scalable serverless compute platform that runs JavaScript/TypeScript code in isolated Deno workers with full access to the InsForge SDK.
-
-## Technology Stack
-
-```mermaid
-graph TB
-    Client[Client Application] --> Backend[Backend API :7130]
-    Backend --> Proxy[Proxy Layer]
-    Proxy --> Deno[Deno Runtime :7133]
-    Deno --> Worker[Web Worker]
-    Worker --> Sandbox[Isolated Sandbox]
-
-    Backend --> DB[(PostgreSQL)]
-    Deno --> DB
-    Worker --> SDK[InsForge SDK]
-    SDK --> Backend
-
-    style Client fill:#1e293b,stroke:#475569,color:#e2e8f0
-    style Backend fill:#166534,stroke:#22c55e,color:#dcfce7
-    style Proxy fill:#1e40af,stroke:#3b82f6,color:#dbeafe
-    style Deno fill:#c2410c,stroke:#fb923c,color:#fed7aa
-    style Worker fill:#4c1d95,stroke:#8b5cf6,color:#ede9fe
-    style Sandbox fill:#7c2d12,stroke:#f97316,color:#fed7aa
-    style DB fill:#0e7490,stroke:#06b6d4,color:#cffafe
-    style SDK fill:#1e40af,stroke:#3b82f6,color:#dbeafe
-```
-
-## Core Components
-
-| Component | Technology | Port | Purpose |
-|-----------|------------|------|---------|
-| **Backend API** | Node.js/Express | 7130 | Function management, authentication, proxy |
-| **Runtime** | Deno v2.0.6 | 7133 | Secure JavaScript/TypeScript execution |
-| **Sandbox** | Web Workers | - | Isolated execution environment |
-| **Database** | PostgreSQL | 5432 | Function code and metadata storage |
-| **SDK** | @insforge/sdk | - | Pre-injected client for backend access |
-| **Secrets** | AES-256-GCM | - | Encrypted environment variables |
-
-## How It Works
-
-When a client makes a request to `/functions/{slug}`:
-
-1. The backend API receives and validates the request
-2. Request is proxied to the Deno runtime
-3. Function code is executed in an isolated Web Worker
-4. The function has access to the InsForge SDK and environment variables
-5. Response is returned to the client
-
-### Authentication Flow
-
-```mermaid
-sequenceDiagram
-    participant C as Client
-    participant B as Backend API
-    participant D as Deno Runtime
-    participant W as Worker
-    participant SDK as InsForge SDK
-
-    C->>B: POST /functions/my-api<br/>Authorization: Bearer TOKEN
-    B->>D: Proxy request with headers
-    D->>D: Fetch function code from DB
-    D->>D: Decrypt secrets
-    D->>W: Create worker with code + secrets
-    W->>SDK: createClient({token})
-    SDK->>B: Validate token
-    B-->>SDK: User data
-    W->>C: HTTP Response
-```
-
-## Performance Characteristics
-
-### Execution Limits
-
-| Limit | Value | Description |
-|-------|-------|-------------|
-| **Timeout** | 30 seconds | Maximum execution time per invocation |
-| **Memory** | Worker default | Depends on Deno worker allocation |
-| **Payload Size** | 10MB | Maximum request/response size |
-| **Concurrent Workers** | System dependent | Limited by server resources |
-| **Cold Start** | ~50-200ms | Time to create new worker |
-
-### Optimization Strategies
-
-1. **Worker Pooling**: Workers are created on-demand
-2. **Code Caching**: Function code cached in memory
-3. **Secret Caching**: Decrypted secrets cached per execution
-4. **SDK Reuse**: SDK client created once per worker
-
-## Best Practices
-
-1. **Keep Functions Small**: Single responsibility per function
-2. **Handle Errors Gracefully**: Always return proper HTTP responses
-3. **Validate Input**: Check request data before processing
-4. **Use Caching**: Cache frequently accessed data
-5. **Optimize Queries**: Use efficient database queries
-6. **Monitor Performance**: Track execution times and errors
-7. **Secure Secrets**: Never log sensitive data
-8. **Test Locally**: Test functions before deployment
+---
+title: Functions Architecture
+description: Serverless JavaScript functions running in isolated Deno runtime
+---
+
+## Overview
+
+InsForge Functions provide a secure, scalable serverless compute platform that runs JavaScript/TypeScript code in isolated Deno workers with full access to the InsForge SDK.
+
+## Technology Stack
+
+```mermaid
+graph TB
+    Client[Client Application] --> Backend[Backend API :7130]
+    Backend --> Proxy[Proxy Layer]
+    Proxy --> Deno[Deno Runtime :7133]
+    Deno --> Worker[Web Worker]
+    Worker --> Sandbox[Isolated Sandbox]
+
+    Backend --> DB[(PostgreSQL)]
+    Deno --> DB
+    Worker --> SDK[InsForge SDK]
+    SDK --> Backend
+
+    style Client fill:#1e293b,stroke:#475569,color:#e2e8f0
+    style Backend fill:#166534,stroke:#22c55e,color:#dcfce7
+    style Proxy fill:#1e40af,stroke:#3b82f6,color:#dbeafe
+    style Deno fill:#c2410c,stroke:#fb923c,color:#fed7aa
+    style Worker fill:#4c1d95,stroke:#8b5cf6,color:#ede9fe
+    style Sandbox fill:#7c2d12,stroke:#f97316,color:#fed7aa
+    style DB fill:#0e7490,stroke:#06b6d4,color:#cffafe
+    style SDK fill:#1e40af,stroke:#3b82f6,color:#dbeafe
+```
+
+## Core Components
+
+| Component | Technology | Port | Purpose |
+|-----------|------------|------|---------|
+| **Backend API** | Node.js/Express | 7130 | Function management, authentication, proxy |
+| **Runtime** | Deno v2.0.6 | 7133 | Secure JavaScript/TypeScript execution |
+| **Sandbox** | Web Workers | - | Isolated execution environment |
+| **Database** | PostgreSQL | 5432 | Function code and metadata storage |
+| **SDK** | @insforge/sdk | - | Pre-injected client for backend access |
+| **Secrets** | AES-256-GCM | - | Encrypted environment variables |
+
+## How It Works
+
+When a client makes a request to `/functions/{slug}`:
+
+1. The backend API receives and validates the request
+2. Request is proxied to the Deno runtime
+3. Function code is executed in an isolated Web Worker
+4. The function has access to the InsForge SDK and environment variables
+5. Response is returned to the client
+
+### Authentication Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant B as Backend API
+    participant D as Deno Runtime
+    participant W as Worker
+    participant SDK as InsForge SDK
+
+    C->>B: POST /functions/my-api<br/>Authorization: Bearer TOKEN
+    B->>D: Proxy request with headers
+    D->>D: Fetch function code from DB
+    D->>D: Decrypt secrets
+    D->>W: Create worker with code + secrets
+    W->>SDK: createClient({token})
+    SDK->>B: Validate token
+    B-->>SDK: User data
+    W->>C: HTTP Response
+```
+
+## Performance Characteristics
+
+### Execution Limits
+
+| Limit | Value | Description |
+|-------|-------|-------------|
+| **Timeout** | 30 seconds | Maximum execution time per invocation |
+| **Memory** | Worker default | Depends on Deno worker allocation |
+| **Payload Size** | 10MB | Maximum request/response size |
+| **Concurrent Workers** | System dependent | Limited by server resources |
+| **Cold Start** | ~50-200ms | Time to create new worker |
+
+### Optimization Strategies
+
+1. **Worker Pooling**: Workers are created on-demand
+2. **Code Caching**: Function code cached in memory
+3. **Secret Caching**: Decrypted secrets cached per execution
+4. **SDK Reuse**: SDK client created once per worker
+
+## Best Practices
+
+1. **Keep Functions Small**: Single responsibility per function
+2. **Handle Errors Gracefully**: Always return proper HTTP responses
+3. **Validate Input**: Check request data before processing
+4. **Use Caching**: Cache frequently accessed data
+5. **Optimize Queries**: Use efficient database queries
+6. **Monitor Performance**: Track execution times and errors
+7. **Secure Secrets**: Never log sensitive data
+8. **Test Locally**: Test functions before deployment