> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 存储 SDK 参考

> 使用 InsForge TypeScript SDK 进行文件上传、下载和管理

## 安装

<CodeGroup>
  ```bash npm theme={null}
  npm install @insforge/sdk@latest
  ```

  ```bash yarn theme={null}
  yarn add @insforge/sdk@latest
  ```

  ```bash pnpm theme={null}
  pnpm add @insforge/sdk@latest
  ```
</CodeGroup>

```javascript theme={null}
import { createClient } from '@insforge/sdk';

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

Find the anon key with `npx @insforge/cli secrets get ANON_KEY`, or in the dashboard: click **Install** and open **API Keys**.

## from()

获取存储桶实例以进行文件操作。

### 参数

* `bucketName` (string, required) - 存储桶的名称

### 返回

```typescript theme={null}
StorageBucket // Instance with upload, uploadAuto, download, remove methods
```

### 示例

```javascript theme={null}
const bucket = insforge.storage.from('images')
```

***

## upload()

使用特定路径/密钥上传文件。

### 参数

* `path` (string, required) - 文件的对象密钥/路径
* `file` (File | Blob, required) - 要上传的文件或 Blob

### 返回

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

<Warning>
  如果存在具有相同密钥的文件，后端会自动重命名。始终使用返回的 `key` 和 `url`。
</Warning>

### 示例

```javascript theme={null}
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')
```

### 输出

```json theme={null}
{
  "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()

使用自动生成的唯一密钥上传文件。

### 参数

* `file` (File | Blob, required) - 要上传的文件或 Blob

### 返回

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

### 示例

```javascript theme={null}
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
  }])
```

### 输出

```json theme={null}
{
  "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()

将文件下载为 Blob。

### 参数

* `path` (string, required) - 要下载的对象密钥/路径

### 返回

```typescript theme={null}
{
  data: Blob | null,
  error: Error | null
}
```

### 示例

```javascript theme={null}
// 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
```

### 输出

```json theme={null}
{
  "data": "Blob { size: 45678, type: 'image/jpeg' }",
  "error": null
}
```

***

## remove()

从存储中删除文件。

### 参数

* `path` (string, required) - 要删除的对象密钥/路径

### 返回

```typescript theme={null}
{
  data: { message: string } | null,
  error: Error | null
}
```

### 示例

```javascript theme={null}
// 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')
```

### 输出

```json theme={null}
{
  "data": {
    "message": "Object deleted successfully"
  },
  "error": null
}
```