@dofe/file-sdk

DofeAI unified file management SDK for Node.js — upload, CDN URL resolution, and file metadata via sso.dofe.ai.

The caller provides business context such as scope, tenantId, and teamId. SSO owns the physical storage route. Do not pass or persist bucket configuration in business services.

Install

pnpm add @dofe/file-sdk

Quick Start

import { FileClient } from '@dofe/file-sdk';

const fileClient = new FileClient({
  baseUrl: 'https://sso.dofe.ai',
  internalSecret: process.env.INTERNAL_API_SECRET,
});

// Get upload token (your app passes this to the browser)
const { token, fileId, cdnUrl } = await fileClient.getUploadToken({
  filename: 'photo.jpg',
  fsize: 2048000,
  scope: 'avatar',
  signature: '<user-signature>',
});

// Upload from a remote URL
const file = await fileClient.uploadFromUrl({
  url: 'https://cdn.example.com/image.png',
  scope: 'media_asset',
});

// Upload in-memory content, useful for server-side artifacts
const artifact = await fileClient.uploadContent({
  content: Buffer.from('{"ok":true}'),
  filename: 'audit.json',
  mimeType: 'application/json',
  scope: 'system',
});

// Get CDN URL (cached for public files)
const url = await fileClient.getCdnUrl(fileId, {
  template: 'thumb',
  width: 200,
  height: 200,
});

// Batch query files
const files = await fileClient.batchGetFiles([id1, id2, id3]);

// Delete a file
await fileClient.deleteFile(fileId);

API Reference

new FileClient(config)

| Option | Type | Required | Default | Description | | ---------------- | -------- | :------: | ------- | --------------------------------------------- | | baseUrl | string | ✅ | — | SSO base URL (e.g., https://sso.dofe.ai) | | internalSecret | string | ✅ | — | INTERNAL_API_SECRET for HMAC-SHA256 signing | | timeout | number | ❌ | 30000 | Request timeout in ms |

Methods

| Method | Returns | Auth | Description | | ----------------------------------- | ----------------------- | :------: | ------------------------------------------------ | | getUploadToken(params) | UploadTokenResponse | Public | Get SSO-issued presigned upload URL | | uploadFromUrl(params) | UploadFromUrlResponse | Internal | Let SSO fetch a remote URL into managed storage | | uploadContent(params) | UploadContentResponse | Internal | Upload server-side Buffer/string content via SSO | | getFileById(id) | FileItem | Internal | Get file metadata | | batchGetFiles(ids) | BatchFileResponse | Internal | Batch get file metadata | | getCdnUrl(id, options?) | string \| null | Internal | Get CDN URL (cached for public files) | | batchResolveCdnUrl(ids, options?) | SignedUrl[] | Internal | Batch get signed CDN URLs | | deleteFile(id) | void | Internal | Soft-delete a file |

Scopes

| Scope | Intended use | Access | URL behavior | | ------------- | --------------------------------- | :-----: | ------------------------------ | | avatar | User avatar | public | Permanent CDN URL when enabled | | logo | Tenant/vendor logo | public | Permanent CDN URL when enabled | | media_asset | Public media assets | public | Permanent CDN URL when enabled | | knowledge | Knowledge-base source files | private | Signed URL | | general | Default private business files | private | Signed URL | | system | Internal artifacts and audit data | private | Signed URL |

bucket, key, vendor, and region may appear in responses as SSO-owned physical metadata. They are read-only integration details and must not be used as configuration in agents/models or other business services.

License

MIT