insforge 1.2.10 → 1.4.8

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

@@ -1,253 +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
-}
-```
-
+---
+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('images')
+```
+
+---
+
+## 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('images')
+  .upload('posts/post-123/cover.jpg', fileObject)
+
+// Save BOTH url and key to database
+await insforge.database
+  .from('posts')
+  .update({
+    image_url: data.url,
+    image_key: data.key  // Save key for download/delete operations
+  })
+  .eq('id', 'post-123')
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "bucket": "images",
+    "key": "posts/post-123/cover.jpg",
+    "size": 45678,
+    "mimeType": "image/jpeg",
+    "uploadedAt": "2024-01-15T10:30:00Z",
+    "url": "https://your-app.region.insforge.app/api/storage/buckets/images/objects/posts%2Fpost-123%2Fcover.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: post, error: dbError } = await insforge.database
+  .from('posts')
+  .select('image_key')
+  .eq('id', 'post-123')
+  .single()
+
+// 2. Download the file using the key
+const { data: blob, error } = await insforge.storage
+  .from('images')
+  .download(post.image_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: post, error: dbError } = await insforge.database
+  .from('posts')
+  .select('image_key')
+  .eq('id', 'post-123')
+  .single()
+
+// 2. Delete the file from storage
+const { data, error } = await insforge.storage
+  .from('images')
+  .remove(post.image_key)
+
+// 3. Clear the database reference
+await insforge.database
+  .from('posts')
+  .update({ image_url: null, image_key: null })
+  .eq('id', 'post-123')
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "message": "Object deleted successfully"
+  },
+  "error": null
+}
+```
+