@dofe/file-sdk-web

DofeAI unified file uploader SDK for browsers — direct upload, multipart upload with progress, via sso.dofe.ai.

The browser only supplies business scope and optional context such as tenantId/teamId. SSO resolves the physical bucket and upload key.

Install

pnpm add @dofe/file-sdk-web

Quick Start

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

const uploader = new FileUploader({
  apiBase: '/api/proxy/sso', // via Next.js proxy
});

// Small files: direct upload
const { fileId, cdnUrl } = await uploader.upload(file, {
  scope: 'avatar',
  onProgress: ({ percent }) => console.log(`${percent}%`),
});

// Large files: multipart upload with concurrency
const { fileId, cdnUrl } = await uploader.uploadMultipart(bigFile, {
  scope: 'media_asset',
  partSize: 5 * 1024 * 1024, // 5MB parts
  concurrency: 3, // 3 parallel parts
  onProgress: ({ percent, loaded, total }) => {
    console.log(`${percent}% (${loaded}/${total})`);
  },
});

API Reference

new FileUploader(config)

| Option | Type | Required | Default | Description | | --------- | -------- | :------: | ------- | -------------------------------------------------------------- | | apiBase | string | ✅ | — | API base URL (e.g., /api/proxy/sso or https://sso.dofe.ai) | | timeout | number | ❌ | 30000 | Request timeout in ms |

Methods

| Method | Returns | Description | | -------------------------------- | ----------------------- | ---------------------------------------------------------------------- | | upload(file, options) | Promise<UploadResult> | Auto-chooses direct or multipart based on file size (>5MB → multipart) | | uploadDirect(file, options) | Promise<UploadResult> | Direct upload for small files | | uploadMultipart(file, options) | Promise<UploadResult> | Multipart upload with configurable part size and concurrency |

UploadResult

interface UploadResult {
  fileId: string; // SSO FileSource UUID
  key: string; // SSO-returned physical key; read-only metadata
  url: string; // Upload URL / token
  cdnUrl: string | null; // CDN URL (null for private files)
  bucket: string; // SSO-returned physical bucket; do not configure or persist as routing input
}

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 | private | Signed URL |

Do not send bucket from the browser. Any bucket/key value returned by SSO is physical metadata for diagnostics and compatibility only.

License

MIT