@realnation/builder-shared-sdk 1.0.1 → 1.0.4

package/README.md

@@ -218,6 +218,30 @@ function UserProfileForm() {
 -   `clearEvents()`: 移除所有**非系统级**的自定义事件。
 -   `emitEvent(type: string, ...args: any[])`: Remote触发一个流程事件。参数会透传给回调，如果最后一个参数是函数，则被视作本地回退`callback`。
 
+### OSS
+
+-   `fetchOssCredential(options: OssCredentialRequestOptions)`: 获取固定接口的OSS临时凭证。
+-   `createOssClient(credential: OssCredential, options?)`: 使用临时凭证创建OSS客户端。
+-   `uploadOssFile(options: OssUploadOptions)`: 上传文件并返回对象地址与Key，支持进度回调和上传目录配置。
+-   `clearOssCache(projectId?)`: 清理OSS凭证与客户端缓存，可按项目或全量清理。
+
+说明：SDK会基于接口返回的`expireAtUnix/expireAt/expiration`自动缓存并复用凭证与客户端，默认提前60秒刷新；可通过`cacheSkewMs`调整。`uploadOssFile` 默认在凭证失效时重试1次，可用 `retryTimes` 控制，并支持 `allowedExtensions`、`maxSizeBytes`、`minSizeBytes` 限制上传文件。
+
+#### OSS 快速示例
+
+```typescript
+import { uploadOssFile } from '@realnation/builder-shared-sdk';
+
+const result = await uploadOssFile({
+  projectId: 'project-id',
+  file,
+  directory: 'uploads/images',
+  onProgress: (ratio) => console.log('progress:', ratio)
+});
+
+console.log(result.url);
+```
+
 ## 🔧 构建
 
 ```bash

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export * from './types';
 export * from './http';
 export * from './events';
 export * from './flow';
+export * from './oss';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC"}

package/dist/index.js

@@ -2,3 +2,4 @@ export * from './types';
 export * from './http';
 export * from './events';
 export * from './flow';
+export * from './oss';

package/dist/oss.d.ts

@@ -0,0 +1,48 @@
+import OSS from 'ali-oss';
+export interface OssCredential {
+    endpoint: string;
+    cdnDomain?: string;
+    accessKeyId: string;
+    accessKeySecret: string;
+    securityToken: string;
+    bucket: string;
+    dir?: string;
+    cname?: boolean;
+    expiration?: string;
+    expireAt?: string;
+    expireAtUnix?: number;
+}
+export interface OssCredentialResponse {
+    credential: OssCredential;
+}
+export interface OssCredentialRequestOptions {
+    projectId: string;
+    responseMapper?: (responseData: unknown) => OssCredentialResponse;
+    cacheSkewMs?: number;
+}
+export interface OssUploadOptions extends OssCredentialRequestOptions {
+    file: File | Blob;
+    directory: string;
+    fileName?: string;
+    partSize?: number;
+    secure?: boolean;
+    simulateProgress?: boolean;
+    onProgress?: (ratio: number) => void;
+    retryTimes?: number;
+    timeoutRetryTimes?: number;
+    allowedExtensions?: string[];
+    maxSizeBytes?: number;
+    minSizeBytes?: number;
+}
+export interface OssUploadResult {
+    url: string;
+    objectKey: string;
+}
+export declare function clearOssCache(projectId?: string): void;
+export declare function fetchOssCredential(options: OssCredentialRequestOptions): Promise<OssCredential>;
+export declare function createOssClient(credential: OssCredential, options?: {
+    refresh?: () => Promise<OssCredential>;
+    secure?: boolean;
+}): Promise<OSS>;
+export declare function uploadOssFile(options: OssUploadOptions): Promise<OssUploadResult>;
+//# sourceMappingURL=oss.d.ts.map

package/dist/oss.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oss.d.ts","sourceRoot":"","sources":["../src/oss.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,SAAS,CAAC;AAG1B,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,aAAa,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,KAAK,qBAAqB,CAAC;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAiB,SAAQ,2BAA2B;IACnE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAwKD,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAUtD;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,aAAa,CAAC,CAcxB;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,aAAa,EACzB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACzE,OAAO,CAAC,GAAG,CAAC,CAwBd;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiGvF"}

package/dist/oss.js

@@ -0,0 +1,266 @@
+import OSS from 'ali-oss';
+import { getHttpClient } from './http';
+const DEFAULT_PART_SIZE = 1024 * 1024;
+const DEFAULT_CACHE_SKEW_MS = 60 * 1000;
+const credentialCache = new Map();
+const clientCache = new Map();
+function defaultResponseMapper(responseData) {
+    if (!responseData || typeof responseData !== 'object') {
+        throw new Error('[builder-shared-sdk] OSS credential response is empty.');
+    }
+    const dataRecord = responseData;
+    if (dataRecord.success === false) {
+        const errorRecord = dataRecord.error;
+        const errorMessage = errorRecord?.message ??
+            '[builder-shared-sdk] OSS credential request failed.';
+        throw new Error(errorMessage);
+    }
+    const directCredential = dataRecord.credential;
+    if (directCredential) {
+        return { credential: directCredential };
+    }
+    const nestedData = dataRecord.data;
+    const nestedCredential = nestedData?.credential;
+    if (nestedCredential) {
+        return { credential: nestedCredential };
+    }
+    throw new Error('[builder-shared-sdk] OSS credential response missing credential.');
+}
+function resolveBrowserSecureFlag(explicitSecure) {
+    if (explicitSecure !== undefined)
+        return explicitSecure;
+    if (typeof window === 'undefined')
+        return true;
+    return window.location.protocol === 'https:';
+}
+function normalizeDir(dir) {
+    if (!dir)
+        return '';
+    const trimmed = dir.replace(/^\/+/, '');
+    return trimmed.endsWith('/') ? trimmed : `${trimmed}/`;
+}
+function joinUrl(baseUrl, path) {
+    const trimmedBase = baseUrl.replace(/\/+$/, '');
+    const trimmedPath = path.replace(/^\/+/, '');
+    return `${trimmedBase}/${trimmedPath}`;
+}
+function resolveAccessBaseUrl(credential) {
+    return credential.cdnDomain ?? credential.endpoint;
+}
+function getFileExtension(file) {
+    if ('name' in file && typeof file.name === 'string') {
+        const segments = file.name.split('.');
+        if (segments.length > 1) {
+            return segments.pop() ?? null;
+        }
+    }
+    return null;
+}
+function normalizeExtension(extension) {
+    return extension.replace(/^\./, '').trim().toLowerCase();
+}
+function resolveUploadExtension(file, fileName) {
+    if (fileName) {
+        const segments = fileName.split('.');
+        if (segments.length > 1) {
+            return segments.pop() ?? null;
+        }
+    }
+    return getFileExtension(file);
+}
+function validateUploadOptions(options) {
+    const size = options.file.size;
+    if (Number.isFinite(options.minSizeBytes) && size < options.minSizeBytes) {
+        throw new Error('[builder-shared-sdk] OSS upload file size is below minimum limit.');
+    }
+    if (Number.isFinite(options.maxSizeBytes) && size > options.maxSizeBytes) {
+        throw new Error('[builder-shared-sdk] OSS upload file size exceeds maximum limit.');
+    }
+    const allowed = options.allowedExtensions?.map(normalizeExtension).filter(Boolean) ?? [];
+    if (allowed.length > 0) {
+        const extension = resolveUploadExtension(options.file, options.fileName);
+        if (!extension) {
+            throw new Error('[builder-shared-sdk] OSS upload file extension is missing.');
+        }
+        const normalized = normalizeExtension(extension);
+        if (!allowed.includes(normalized)) {
+            throw new Error('[builder-shared-sdk] OSS upload file extension is not allowed.');
+        }
+    }
+}
+function buildObjectKey(credential, file, directory, fileName) {
+    const prefix = credential.dir + normalizeDir(directory);
+    const safeFileName = (fileName ?? '').replace(/^\/+/, '');
+    if (safeFileName) {
+        return `${prefix}${safeFileName}`;
+    }
+    const extension = getFileExtension(file);
+    const timestamp = Date.now();
+    const generatedName = extension ? `${timestamp}.${extension}` : `${timestamp}`;
+    return `${prefix}${generatedName}`;
+}
+function resolveCredentialExpiryMs(credential) {
+    if (typeof credential.expireAtUnix === 'number' && Number.isFinite(credential.expireAtUnix)) {
+        return credential.expireAtUnix * 1000;
+    }
+    const raw = credential.expireAt ?? credential.expiration;
+    if (!raw)
+        return null;
+    const parsed = Date.parse(raw);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+function isCredentialFresh(expiresAtMs, skewMs) {
+    if (!expiresAtMs)
+        return true;
+    return Date.now() + skewMs < expiresAtMs;
+}
+function getCacheKey(projectId, secure) {
+    return `${projectId}|${secure ? 'https' : 'http'}`;
+}
+function isAuthError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const record = error;
+    const reason = record.reason;
+    const cause = reason?.cause;
+    const code = (cause?.code ?? record.code);
+    return code === 'auth.invalid_token' || code === 'auth.token_expired';
+}
+function isTimeoutError(error) {
+    if (!error)
+        return false;
+    const message = typeof error === 'string'
+        ? error
+        : (error.message ?? '');
+    return message.includes('ConnectionTimeoutError') || message.includes('timeout');
+}
+export function clearOssCache(projectId) {
+    if (!projectId) {
+        credentialCache.clear();
+        clientCache.clear();
+        return;
+    }
+    credentialCache.delete(projectId);
+    clientCache.delete(getCacheKey(projectId, true));
+    clientCache.delete(getCacheKey(projectId, false));
+}
+export async function fetchOssCredential(options) {
+    const skewMs = options.cacheSkewMs ?? DEFAULT_CACHE_SKEW_MS;
+    const cached = credentialCache.get(options.projectId);
+    if (cached && isCredentialFresh(cached.expiresAtMs, skewMs)) {
+        return cached.credential;
+    }
+    const httpClient = getHttpClient();
+    const response = await httpClient.post(`/partner/aliyun/oss/credential/${options.projectId}`);
+    const mapper = options.responseMapper ?? defaultResponseMapper;
+    const mapped = mapper(response.data);
+    const expiresAtMs = resolveCredentialExpiryMs(mapped.credential);
+    credentialCache.set(options.projectId, { credential: mapped.credential, expiresAtMs });
+    return mapped.credential;
+}
+export async function createOssClient(credential, options = {}) {
+    const secure = resolveBrowserSecureFlag(options.secure);
+    const refresh = options.refresh;
+    return new OSS({
+        endpoint: credential.endpoint,
+        accessKeyId: credential.accessKeyId,
+        accessKeySecret: credential.accessKeySecret,
+        stsToken: credential.securityToken,
+        bucket: credential.bucket,
+        cname: credential.cname ?? true,
+        secure,
+        refreshSTSTokenInterval: 3000000,
+        refreshSTSToken: refresh
+            ? async () => {
+                const refreshed = await refresh();
+                return {
+                    accessKeyId: refreshed.accessKeyId,
+                    accessKeySecret: refreshed.accessKeySecret,
+                    stsToken: refreshed.securityToken
+                };
+            }
+            : undefined
+    });
+}
+export async function uploadOssFile(options) {
+    validateUploadOptions(options);
+    const secure = resolveBrowserSecureFlag(options.secure);
+    const cacheKey = getCacheKey(options.projectId, secure);
+    const skewMs = options.cacheSkewMs ?? DEFAULT_CACHE_SKEW_MS;
+    const retryTimes = Math.max(options.retryTimes ?? 1, 0);
+    const timeoutRetryTimes = Math.max(options.timeoutRetryTimes ?? 1, 0);
+    const attemptUpload = async (authAttempt, timeoutAttempt) => {
+        let cachedClient = clientCache.get(cacheKey);
+        if (!cachedClient || !isCredentialFresh(cachedClient.expiresAtMs, skewMs)) {
+            const credential = await fetchOssCredential(options);
+            const expiresAtMs = resolveCredentialExpiryMs(credential);
+            const client = await createOssClient(credential, {
+                secure,
+                refresh: () => fetchOssCredential(options)
+            });
+            cachedClient = { client, expiresAtMs };
+            clientCache.set(cacheKey, cachedClient);
+        }
+        const credential = credentialCache.get(options.projectId)?.credential;
+        if (!credential) {
+            throw new Error('[builder-shared-sdk] OSS credential cache is missing.');
+        }
+        const client = cachedClient.client;
+        const objectKey = buildObjectKey(credential, options.file, options.directory, options.fileName);
+        const partSize = options.partSize ?? DEFAULT_PART_SIZE;
+        const onProgress = options.onProgress;
+        let timer = null;
+        try {
+            if (options.file.size < partSize) {
+                if (onProgress && options.simulateProgress) {
+                    let progressValue = 0;
+                    timer = setInterval(() => {
+                        progressValue = Math.min(progressValue + 0.01, 0.95);
+                        onProgress(progressValue);
+                    }, 400);
+                }
+                const result = await client.put(objectKey, options.file);
+                if (timer) {
+                    clearInterval(timer);
+                    timer = null;
+                }
+                onProgress?.(1);
+                const url = joinUrl(resolveAccessBaseUrl(credential), objectKey);
+                return { url, objectKey };
+            }
+            const result = await client.multipartUpload(objectKey, options.file, {
+                partSize,
+                progress: (percentage) => {
+                    onProgress?.(percentage);
+                }
+            });
+            onProgress?.(1);
+            const url = joinUrl(resolveAccessBaseUrl(credential), objectKey);
+            const requestUrls = result?.res?.requestUrls;
+            if (requestUrls?.length) {
+                return { url, objectKey };
+            }
+            return { url, objectKey };
+        }
+        catch (error) {
+            if (isAuthError(error) && authAttempt < retryTimes) {
+                clearOssCache(options.projectId);
+                return attemptUpload(authAttempt + 1, timeoutAttempt);
+            }
+            if (isTimeoutError(error)) {
+                if (timeoutAttempt < timeoutRetryTimes) {
+                    return attemptUpload(authAttempt, timeoutAttempt + 1);
+                }
+                throw new Error('Timeout. Please check your network and try again.');
+            }
+            console.log('[builder-shared-sdk] OSS upload error:', error);
+            throw new Error('Upload failed. Please try again later.');
+        }
+        finally {
+            if (timer) {
+                clearInterval(timer);
+            }
+        }
+    };
+    return attemptUpload(0, 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realnation/builder-shared-sdk",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "type": "module",
   "private": false,
   "exports": {
@@ -20,9 +20,11 @@
     "prepare": "npm run clean && npm run build"
   },
   "dependencies": {
+    "ali-oss": "^6.23.0",
     "axios": "^1.7.7"
   },
   "devDependencies": {
+    "@types/ali-oss": "^6.16.11",
     "rimraf": "^5.0.5",
     "typescript": "^5.4.5"
   }