insforge 0.3.3 → 1.3.0

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

@@ -0,0 +1,253 @@
+---
+title: Storage SDK Reference
+description: File upload, download, and management with the InsForge SDK
+---
+
+import Installation from '/snippets/sdk-installation.mdx';
+
+<Installation />
+
+## from()
+
+Get a bucket instance for file operations.
+
+### Parameters
+
+- `bucketName` (string, required) - Name of the storage bucket
+
+### Returns
+
+```typescript
+StorageBucket // Instance with upload, uploadAuto, download, remove methods
+```
+
+### Example
+
+```javascript
+const bucket = insforge.storage.from('avatars')
+```
+
+---
+
+## upload()
+
+Upload a file with a specific path/key.
+
+### Parameters
+
+- `path` (string, required) - The object key/path for the file
+- `file` (File | Blob, required) - File or Blob to upload
+
+### Returns
+
+```typescript
+{
+  data: {
+    bucket: string,
+    key: string,
+    size: number,
+    mimeType: string,
+    uploadedAt: string,
+    url: string
+  } | null,
+  error: Error | null
+}
+```
+
+<Warning>
+If a file with the same key exists, backend auto-renames it. Always use the returned `key` and `url`.
+</Warning>
+
+### Example
+
+```javascript
+const { data, error } = await insforge.storage
+  .from('avatars')
+  .upload('user-123/avatar.jpg', fileObject)
+
+// Save BOTH url and key to database
+await insforge.database
+  .from('users')
+  .update({
+    avatar_url: data.url,
+    avatar_key: data.key  // Save key for download/delete operations
+  })
+  .eq('id', 'user-123')
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "bucket": "avatars",
+    "key": "user-123/avatar.jpg",
+    "size": 45678,
+    "mimeType": "image/jpeg",
+    "uploadedAt": "2024-01-15T10:30:00Z",
+    "url": "https://your-app.region.insforge.app/api/storage/buckets/avatars/objects/user-123%2Favatar.jpg"
+  },
+  "error": null
+}
+```
+
+---
+
+## uploadAuto()
+
+Upload a file with auto-generated unique key.
+
+### Parameters
+
+- `file` (File | Blob, required) - File or Blob to upload
+
+### Returns
+
+```typescript
+{
+  data: {
+    bucket: string,
+    key: string,
+    size: number,
+    mimeType: string,
+    uploadedAt: string,
+    url: string
+  } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.storage
+  .from('uploads')
+  .uploadAuto(fileObject)
+
+// Save url and key to database
+await insforge.database
+  .from('posts')
+  .insert([{
+    image_url: data.url,
+    image_key: data.key,  // Save key for download/delete operations
+    user_id: userId
+  }])
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "bucket": "uploads",
+    "key": "myfile-1705315200000-abc123.jpg",
+    "size": 45678,
+    "mimeType": "image/jpeg",
+    "uploadedAt": "2024-01-15T10:30:00Z",
+    "url": "https://your-app.region.insforge.app/api/storage/buckets/uploads/objects/myfile-1705315200000-abc123.jpg"
+  },
+  "error": null
+}
+```
+
+---
+
+## download()
+
+Download a file as Blob.
+
+### Parameters
+
+- `path` (string, required) - The object key/path to download
+
+### Returns
+
+```typescript
+{
+  data: Blob | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+// 1. Get the file key from your database
+const { data: user, error: dbError } = await insforge.database
+  .from('users')
+  .select('avatar_key')
+  .eq('id', 'user-123')
+  .single()
+
+// 2. Download the file using the key
+const { data: blob, error } = await insforge.storage
+  .from('avatars')
+  .download(user.avatar_key)
+
+// 3. Create download link or display image
+const url = URL.createObjectURL(blob)
+const img = document.querySelector('img')
+img.src = url
+```
+
+### Output
+
+```json
+{
+  "data": "Blob { size: 45678, type: 'image/jpeg' }",
+  "error": null
+}
+```
+
+---
+
+## remove()
+
+Delete a file from storage.
+
+### Parameters
+
+- `path` (string, required) - The object key/path to delete
+
+### Returns
+
+```typescript
+{
+  data: { message: string } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+// 1. Get the file key from your database
+const { data: user, error: dbError } = await insforge.database
+  .from('users')
+  .select('avatar_key')
+  .eq('id', 'user-123')
+  .single()
+
+// 2. Delete the file from storage
+const { data, error } = await insforge.storage
+  .from('avatars')
+  .remove(user.avatar_key)
+
+// 3. Clear the database reference
+await insforge.database
+  .from('users')
+  .update({ avatar_url: null, avatar_key: null })
+  .eq('id', 'user-123')
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "message": "Object deleted successfully"
+  },
+  "error": null
+}
+```
+

package/docs/deployment/README.md

@@ -0,0 +1,94 @@
+# InsForge Deployment Guides
+
+This directory contains deployment guides for self-hosting InsForge on various platforms.
+
+## 📚 Available Guides
+
+### Cloud Platforms
+
+- **[Render](./deploy-to-render.md)** - Deploy InsForge on Render with managed services
+  - Managed PostgreSQL database
+  - Automatic deployments from Git
+  - Free SSL certificates
+  - Simple scaling and monitoring
+  - Blueprint (IaC) support
+
+- **[AWS EC2](./deploy-to-aws-ec2.md)** - Deploy InsForge on Amazon EC2 with Docker Compose
+  - Instance setup and configuration
+  - Docker Compose deployment
+  - Domain and SSL configuration
+  - Production best practices
+
+- **[Google Cloud Compute Engine](./deploy-to-google-cloud-compute-engine.md)** - Deploy InsForge on Google Cloud Compute Engine with Docker Compose
+  - VM instance setup and configuration
+  - Docker Compose deployment
+  - Domain and SSL configuration
+  - Production best practices
+
+### Coming Soon
+
+- **Digital Ocean** - Droplet deployment guide
+- **Azure** - VM deployment guide
+- **Hetzner** - VPS deployment guide
+- **Kubernetes** - Production-grade Kubernetes deployment
+- **Railway** - One-click Railway deployment
+- **Fly.io** - Global edge deployment
+
+## 🎯 Choosing a Platform
+
+### For Beginners
+- **Render** - Easiest managed deployment with auto-SSL and Git integration
+- **Railway** (Coming Soon) - One-click deployment
+- **AWS EC2** - Well-documented, widely used
+
+### For Production
+- **Render** - Managed services, auto-scaling, simple operations
+- **AWS EC2** - Reliable, scalable, extensive features
+- **Kubernetes** (Coming Soon) - High availability, auto-scaling
+
+### For Cost-Conscious
+- **Render** - Competitive pricing, free tier available (~$28/month for production)
+- **Hetzner** (Coming Soon) - Best price-to-performance ratio
+- **Digital Ocean** (Coming Soon) - Simple pricing, good performance
+
+### For Global Distribution
+- **Render** - Multi-region deployment with automatic CDN
+- **Fly.io** (Coming Soon) - Edge deployment in multiple regions
+- **AWS with CloudFront** - Global CDN integration
+
+## 📋 General Requirements
+
+All deployment methods require:
+
+- Docker & Docker Compose support (for container-based deployments)
+- Minimum 2 GB RAM (4 GB recommended)
+- 20 GB storage (30 GB recommended)
+- PostgreSQL 15+ compatible
+- Internet connectivity for external services
+
+## 🔧 Architecture Overview
+
+InsForge consists of 6 main services:
+
+1. **PostgreSQL** - Database (port 5432)
+2. **PostgREST** - Auto-generated REST API (port 5430)
+3. **Backend** - Node.js API server (port 7130)
+4. **Frontend** - React dashboard (port 7131)
+5. **Deno Runtime** - Serverless functions (port 7133)
+6. **Vector** - Log collection and shipping
+
+## 🤝 Contributing
+
+Have experience deploying InsForge on a platform not listed here? We'd love your contribution!
+
+1. Fork the repository
+2. Create a deployment guide following the AWS EC2 template
+3. Submit a pull request
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for more details.
+
+## 🆘 Need Help?
+
+- **Documentation**: [https://docs.insforge.dev](https://docs.insforge.dev)
+- **Discord Community**: [https://discord.com/invite/MPxwj5xVvW](https://discord.com/invite/MPxwj5xVvW)
+- **GitHub Issues**: [https://github.com/insforge/insforge/issues](https://github.com/insforge/insforge/issues)