insforge 1.2.10 → 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

@@ -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: 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