Storage SDK Reference

File upload, download, and management with the InsForge SDK

npm

npm install @insforge/sdk@latest

import { createClient } from '@insforge/sdk';

const insforge = createClient({
  baseUrl: 'https://your-app.us-east.insforge.app',
  anonKey: 'your-anon-key'  // Optional: for public/unauthenticated requests
});

from()

Get a bucket instance for file operations.

Parameters

• bucketName (string, required) - Name of the storage bucket

Returns

StorageBucket // Instance with upload, uploadAuto, download, remove methods

Example

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

{
  data: {
    bucket: string,
    key: string,
    size: number,
    mimeType: string,
    uploadedAt: string,
    url: string
  } | null,
  error: Error | null
}

If a file with the same key exists, backend auto-renames it. Always use the returned key and url.

Example

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

{
  "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

{
  data: {
    bucket: string,
    key: string,
    size: number,
    mimeType: string,
    uploadedAt: string,
    url: string
  } | null,
  error: Error | null
}

Example

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

{
  "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

{
  data: Blob | null,
  error: Error | null
}

Example

// 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

{
  "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

{
  data: { message: string } | null,
  error: Error | null
}

Example

// 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

{
  "data": {
    "message": "Object deleted successfully"
  },
  "error": null
}