insforge 0.3.3 → 1.3.0

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

@@ -0,0 +1,101 @@
+---
+title: Architecture
+description: Transactional email delivery powered by AWS SES
+---
+
+<Note>**Private Preview** - This feature is currently in private preview.</Note>
+
+## 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

@@ -0,0 +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

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

@@ -0,0 +1,184 @@
+---
+title: Functions SDK Reference
+description: Invoke serverless functions with the InsForge SDK
+---
+
+import Installation from '/snippets/sdk-installation.mdx';
+
+<Installation />
+
+## invoke()
+
+Invoke a serverless function by slug.
+
+### Parameters
+
+- `slug` (string, required) - Function slug/name
+- `body` (any, optional) - Request body (JSON-serializable)
+- `headers` (object, optional) - Custom headers
+- `method` ('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', optional) - HTTP method (default: POST)
+
+### Returns
+
+```typescript
+{
+  data: any | null,  // Response from function
+  error: Error | null
+}
+```
+
+<Note>
+SDK automatically includes authentication token from logged-in user.
+</Note>
+
+### Example (POST with body)
+
+```javascript
+const { data, error } = await insforge.functions.invoke('hello-world', {
+  body: { name: 'World', greeting: 'Hello' }
+})
+
+console.log(data)
+```
+
+### Output (POST with body)
+
+```json
+{
+  "data": {
+    "message": "Hello, World!",
+    "timestamp": "2024-01-15T10:30:00Z"
+  },
+  "error": null
+}
+```
+
+### Example (GET request)
+
+```javascript
+const { data, error } = await insforge.functions.invoke('get-stats', {
+  method: 'GET'
+})
+
+console.log(data)
+```
+
+### Output (GET request)
+
+```json
+{
+  "data": {
+    "users": 100,
+    "posts": 500,
+    "comments": 1200
+  },
+  "error": null
+}
+```
+
+### Example (With custom headers)
+
+```javascript
+const { data, error } = await insforge.functions.invoke('api-endpoint', {
+  method: 'PUT',
+  body: { id: '123', status: 'active' },
+  headers: { 'X-Custom-Header': 'value' }
+})
+```
+
+### Output (With custom headers)
+
+```json
+{
+  "data": {
+    "updated": true,
+    "id": "123"
+  },
+  "error": null
+}
+```
+
+## Complete Serverless Function Examples
+
+### Example 1: Public Function (No Authentication Required)
+
+```javascript
+// Use anon token for public data access
+// No import needed - createClient is injected by the worker template
+module.exports = async function(request) {
+  const corsHeaders = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization'
+  };
+
+  if (request.method === 'OPTIONS') {
+    return new Response(null, { status: 204, headers: corsHeaders });
+  }
+
+  // Create client with anon token - no authentication needed
+  const client = createClient({
+    baseUrl: Deno.env.get('INSFORGE_INTERNAL_URL') || 'http://insforge:7130',
+    anonKey: Deno.env.get('ANON_KEY')
+  });
+
+  // Access public data
+  const { data, error } = await client.database
+    .from('public_posts')
+    .select('*')
+    .limit(10);
+
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { ...corsHeaders, 'Content-Type': 'application/json' }
+  });
+}
+```
+
+### Example 2: Authenticated Function (Access User Data)
+
+```javascript
+// Use functionToken to access authenticated user's data
+// No import needed - createClient is injected by the worker template
+module.exports = async function(request) {
+  const corsHeaders = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization'
+  };
+
+  if (request.method === 'OPTIONS') {
+    return new Response(null, { status: 204, headers: corsHeaders });
+  }
+
+  // Extract token from request headers
+  const authHeader = request.headers.get('Authorization');
+  const userToken = authHeader ? authHeader.replace('Bearer ', '') : null;
+
+  // Create client with user's token for authenticated access
+  const client = createClient({
+    baseUrl: Deno.env.get('INSFORGE_INTERNAL_URL') || 'http://insforge:7130',
+    edgeFunctionToken: userToken
+  });
+
+  // Get authenticated user
+  const { data: userData } = await client.auth.getCurrentUser();
+  if (!userData?.user?.id) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+      status: 401,
+      headers: { ...corsHeaders, 'Content-Type': 'application/json' }
+    });
+  }
+
+  // Access user's private data or create records with user_id
+  await client.database.from('user_posts').insert([{
+    user_id: userData.user.id,
+    content: 'My post'
+  }]);
+
+  return new Response(JSON.stringify({ success: true }), {
+    status: 200,
+    headers: { ...corsHeaders, 'Content-Type': 'application/json' }
+  });
+}
+```