@dofe/file-sdk-web 0.1.1

package/README.md

@@ -0,0 +1,68 @@
+# @dofe/file-sdk-web
+
+DofeAI unified file uploader SDK for **browsers** — direct upload, multipart upload with progress, via `sso.dofe.ai`.
+
+## Install
+
+```bash
+pnpm add @dofe/file-sdk-web
+```
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+interface UploadResult {
+  fileId: string;    // SSO FileSource UUID
+  key: string;       // Object storage key
+  url: string;       // Upload URL / token
+  cdnUrl: string | null;  // CDN URL (null for private files)
+  bucket: string;    // Storage bucket name
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { FileUploader } from './uploader';
+export type { FileUploaderConfig, FileScope, UploadOptions, MultipartUploadOptions, UploadProgress, UploadResult, } from './types';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileUploader = void 0;
+var uploader_1 = require("./uploader");
+Object.defineProperty(exports, "FileUploader", { enumerable: true, get: function () { return uploader_1.FileUploader; } });

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+/** File scope types */
+export type FileScope = 'avatar' | 'media_asset' | 'knowledge' | 'general' | 'system';
+/** Upload progress callback */
+export interface UploadProgress {
+    /** Percentage complete (0-100) */
+    percent: number;
+    /** Bytes uploaded so far */
+    loaded: number;
+    /** Total bytes to upload */
+    total: number;
+}
+/** Upload options */
+export interface UploadOptions {
+    /** File scope / category */
+    scope: FileScope;
+    /** Progress callback */
+    onProgress?: (progress: UploadProgress) => void;
+    /** Tenant ID (optional, derived from auth context if not provided) */
+    tenantId?: string;
+}
+/** Multipart upload options */
+export interface MultipartUploadOptions extends UploadOptions {
+    /** Part size in bytes (default: 5MB) */
+    partSize?: number;
+    /** Max concurrent parts (default: 3) */
+    concurrency?: number;
+}
+/** Upload result */
+export interface UploadResult {
+    fileId: string;
+    key: string;
+    url: string;
+    cdnUrl: string | null;
+    bucket: string;
+}
+/** FileUploader configuration */
+export interface FileUploaderConfig {
+    /** API base URL for upload token requests (e.g., "/api/proxy/sso" or "https://sso.dofe.ai") */
+    apiBase: string;
+    /** Timeout per request in ms (default: 30000) */
+    timeout?: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/uploader.d.ts

@@ -0,0 +1,37 @@
+import { FileUploaderConfig, UploadOptions, MultipartUploadOptions, UploadResult } from './types';
+export declare class FileUploader {
+    private readonly apiBase;
+    private readonly timeout;
+    constructor(config: FileUploaderConfig);
+    /**
+     * Upload a file. Automatically chooses between direct upload (small files)
+     * and multipart upload (large files > 5MB).
+     */
+    upload(file: File, options: UploadOptions): Promise<UploadResult>;
+    /**
+     * Direct upload for small files.
+     * 1. Get upload token from SSO API
+     * 2. PUT file directly to presigned URL
+     */
+    uploadDirect(file: File, options: UploadOptions): Promise<UploadResult>;
+    /**
+     * Multipart upload for large files.
+     * 1. Init multipart upload → get uploadId + first part token
+     * 2. Upload first part
+     * 3. Get tokens for remaining parts and upload in parallel
+     * 4. Complete multipart upload
+     */
+    uploadMultipart(file: File, options: MultipartUploadOptions): Promise<UploadResult>;
+    /**
+     * Upload a single part in a multipart upload.
+     */
+    private uploadPart;
+    /**
+     * PUT file/blob directly to a presigned URL.
+     */
+    private uploadToPresignedUrl;
+    /**
+     * Fetch JSON from API, extracting the data field from the standard response wrapper.
+     */
+    private fetchJson;
+}

package/dist/uploader.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileUploader = void 0;
+/** Default part size for multipart uploads: 5MB */
+const DEFAULT_PART_SIZE = 5 * 1024 * 1024;
+class FileUploader {
+    constructor(config) {
+        var _a;
+        this.apiBase = config.apiBase.replace(/\/$/, '');
+        this.timeout = (_a = config.timeout) !== null && _a !== void 0 ? _a : 30000;
+    }
+    /**
+     * Upload a file. Automatically chooses between direct upload (small files)
+     * and multipart upload (large files > 5MB).
+     */
+    async upload(file, options) {
+        if (file.size > DEFAULT_PART_SIZE) {
+            return this.uploadMultipart(file, options);
+        }
+        return this.uploadDirect(file, options);
+    }
+    /**
+     * Direct upload for small files.
+     * 1. Get upload token from SSO API
+     * 2. PUT file directly to presigned URL
+     */
+    async uploadDirect(file, options) {
+        var _a, _b, _c, _d;
+        // Step 1: Get upload token
+        const tokenRes = await this.fetchJson(`${this.apiBase}/api/uploader/token/private`, {
+            method: 'POST',
+            body: JSON.stringify({
+                filename: file.name,
+                fsize: file.size,
+                mimeType: file.type || 'application/octet-stream',
+                scope: options.scope,
+                signature: 'browser-upload', // Will be validated differently for browser uploads
+                tenantId: options.tenantId,
+            }),
+        });
+        const { token, fileId, key, cdnUrl, bucket } = (_a = tokenRes.data) !== null && _a !== void 0 ? _a : tokenRes;
+        // Step 2: PUT file to presigned URL
+        await this.uploadToPresignedUrl(token, file);
+        (_b = options.onProgress) === null || _b === void 0 ? void 0 : _b.call(options, { percent: 100, loaded: file.size, total: file.size });
+        return { fileId, key, url: (_d = (_c = tokenRes.data) === null || _c === void 0 ? void 0 : _c.url) !== null && _d !== void 0 ? _d : token, cdnUrl, bucket };
+    }
+    /**
+     * Multipart upload for large files.
+     * 1. Init multipart upload → get uploadId + first part token
+     * 2. Upload first part
+     * 3. Get tokens for remaining parts and upload in parallel
+     * 4. Complete multipart upload
+     */
+    async uploadMultipart(file, options) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        const partSize = (_a = options.partSize) !== null && _a !== void 0 ? _a : DEFAULT_PART_SIZE;
+        const concurrency = (_b = options.concurrency) !== null && _b !== void 0 ? _b : 3;
+        const totalParts = Math.ceil(file.size / partSize);
+        // Step 1: Init multipart upload
+        const initRes = await this.fetchJson(`${this.apiBase}/api/uploader/init/multipart`, {
+            method: 'POST',
+            body: JSON.stringify({
+                filename: file.name,
+                fsize: file.size,
+                mimeType: file.type || 'application/octet-stream',
+                scope: options.scope,
+                signature: 'browser-upload',
+                tenantId: options.tenantId,
+            }),
+        });
+        const { token, fileId, key, bucket, url: uploadId } = (_c = initRes.data) !== null && _c !== void 0 ? _c : initRes;
+        // Step 2: Upload first part
+        const part1 = file.slice(0, partSize);
+        await this.uploadToPresignedUrl(token, part1);
+        const parts = [{ partNumber: 1, etag: 'uploaded' }];
+        let loaded = partSize;
+        (_d = options.onProgress) === null || _d === void 0 ? void 0 : _d.call(options, { percent: Math.round((loaded / file.size) * 100), loaded, total: file.size });
+        // Step 3: Upload remaining parts in parallel batches
+        for (let i = 2; i <= totalParts; i += concurrency) {
+            const batch = [];
+            const batchEnd = Math.min(i + concurrency - 1, totalParts);
+            for (let partNumber = i; partNumber <= batchEnd; partNumber++) {
+                batch.push(this.uploadPart(partNumber, file, partSize, uploadId, fileId, options));
+            }
+            const results = await Promise.all(batch);
+            parts.push(...results.filter(Boolean));
+            loaded += (batchEnd - i + 1) * partSize;
+            const actualLoaded = Math.min(loaded, file.size);
+            (_e = options.onProgress) === null || _e === void 0 ? void 0 : _e.call(options, { percent: Math.round((actualLoaded / file.size) * 100), loaded: actualLoaded, total: file.size });
+        }
+        // Step 4: Complete multipart upload
+        const completeRes = await this.fetchJson(`${this.apiBase}/api/uploader/complete`, {
+            method: 'POST',
+            body: JSON.stringify({
+                fileId,
+                signature: 'browser-upload',
+                parts,
+                uploadId,
+            }),
+        });
+        return {
+            fileId,
+            key,
+            url: (_g = (_f = completeRes.data) === null || _f === void 0 ? void 0 : _f.url) !== null && _g !== void 0 ? _g : '',
+            cdnUrl: (_j = (_h = completeRes.data) === null || _h === void 0 ? void 0 : _h.cdnUrl) !== null && _j !== void 0 ? _j : null,
+            bucket,
+        };
+    }
+    /**
+     * Upload a single part in a multipart upload.
+     */
+    async uploadPart(partNumber, file, partSize, uploadId, fileId, options) {
+        var _a, _b;
+        try {
+            const tokenRes = await this.fetchJson(`${this.apiBase}/api/uploader/token/multipart`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    fileId,
+                    uploadId,
+                    partNumber,
+                    signature: 'browser-upload',
+                }),
+            });
+            const start = (partNumber - 1) * partSize;
+            const end = Math.min(start + partSize, file.size);
+            const chunk = file.slice(start, end);
+            await this.uploadToPresignedUrl((_b = (_a = tokenRes.data) === null || _a === void 0 ? void 0 : _a.token) !== null && _b !== void 0 ? _b : tokenRes.token, chunk);
+            return { partNumber, etag: `etag-${partNumber}` };
+        }
+        catch (err) {
+            // Part upload failed; caller can retry
+            throw err;
+        }
+    }
+    /**
+     * PUT file/blob directly to a presigned URL.
+     */
+    async uploadToPresignedUrl(presignedUrl, data) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(presignedUrl, {
+                method: 'PUT',
+                body: data,
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': data.type || 'application/octet-stream',
+                },
+            });
+            if (!res.ok) {
+                throw new Error(`Upload to storage failed: HTTP ${res.status}`);
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Fetch JSON from API, extracting the data field from the standard response wrapper.
+     */
+    async fetchJson(url, options) {
+        var _a;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(url, Object.assign(Object.assign({}, options), { signal: controller.signal, headers: Object.assign({ 'Content-Type': 'application/json' }, ((_a = options === null || options === void 0 ? void 0 : options.headers) !== null && _a !== void 0 ? _a : {})), credentials: 'include' }));
+            if (!res.ok) {
+                throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+            }
+            const json = await res.json();
+            // Unwrap standard { code, msg, data } envelope
+            if (json && typeof json === 'object' && 'data' in json) {
+                return json;
+            }
+            return json;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+exports.FileUploader = FileUploader;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dofe/file-sdk-web",
+  "version": "0.1.1",
+  "description": "DofeAI unified file uploader SDK for browsers — direct upload, multipart upload with progress, via sso.dofe.ai",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --project tsconfig.build.json --noEmit",
+    "prepublishOnly": "pnpm run clean && pnpm run build"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "dofe",
+    "file",
+    "upload",
+    "browser",
+    "multipart",
+    "sso"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dofe-ai/sso.dofe.ai.git"
+  },
+  "author": "Techwu <wumin.itea@gmail.com>"
+}