@kmlckj/licos-platform-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,3 +1,32 @@
 # @kmlckj/licos-platform-sdk
 
-Node.js SDK for LICOS platform storage upload, download, and preview APIs.
+LICOS 平台对象存储 SDK，兼容前端和后端调用。
+
+## 后端模式
+
+- `baseUrl` / `token` / `userId` / `projectId` 不传时，会回退读取 `LICOS_*` 环境变量
+- `uploadUser` / `uploadProject` 支持直接传本地文件路径
+- `download(url, outputPath)` 会把文件写到本地路径
+
+```js
+import { uploadProject, download } from '@kmlckj/licos-platform-sdk';
+
+const uploaded = await uploadProject('/tmp/report.pdf');
+await download(uploaded.download_url, '/tmp/report-downloaded.pdf');
+```
+
+## 前端模式
+
+- 默认走同源相对地址；也可以显式传 `baseUrl`
+- 上传支持 `File` / `Blob` / `ArrayBuffer` / TypedArray / `{ data, fileName, contentType }`
+- `download(url)` 返回 `Blob`
+
+```js
+import { uploadUser, download } from '@kmlckj/licos-platform-sdk';
+
+const uploaded = await uploadUser(fileInput.files[0], {
+  token: userJwt,
+});
+
+const blob = await download(uploaded.download_url);
+```

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@kmlckj/licos-platform-sdk",
-  "version": "0.1.0",
-  "description": "LICOS platform SDK for storage upload, download, and preview",
+  "version": "0.2.0",
+  "description": "LICOS platform SDK for storage upload, download, and preview in browser and Node runtimes",
   "author": "kmlckj",
   "type": "module",
   "main": "./src/index.js",
+  "browser": "./src/browser.js",
   "types": "./src/index.d.ts",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
+      "browser": "./src/browser.js",
       "import": "./src/index.js",
       "default": "./src/index.js"
     }

package/src/browser.js

@@ -0,0 +1,101 @@
+import {
+  ApiError,
+  ConfigurationError,
+  PlatformSdkError,
+  downloadBlob,
+  encodeObjectKey,
+  encodeStorageSegment,
+  normalizeBaseUrl,
+  resolveProjectId,
+  resolveUserId,
+  uploadFile,
+} from './shared.js';
+
+export class StorageClient {
+  constructor(options = {}) {
+    this.baseUrl = options.baseUrl;
+    this.token = options.token;
+    this.userId = options.userId;
+    this.projectId = options.projectId;
+    this.fetchImpl = options.fetch ?? fetch;
+    this.headers = options.headers;
+    this.credentials = options.credentials;
+  }
+
+  previewUrl(bucket, objectKey) {
+    const baseUrl = normalizeBaseUrl(this.baseUrl);
+    return `${baseUrl}/api/v1/public/storage/${encodeStorageSegment(bucket)}/${encodeObjectKey(objectKey)}`;
+  }
+
+  downloadUrl(bucket, objectKey) {
+    return `${this.previewUrl(bucket, objectKey)}?download=1`;
+  }
+
+  async uploadUser(file) {
+    const baseUrl = normalizeBaseUrl(this.baseUrl);
+    return uploadFile(this.fetchImpl, `${baseUrl}/api/v1/storage/upload/user`, file, {
+      token: this.token,
+      headers: this.headers,
+      credentials: this.credentials,
+    });
+  }
+
+  async uploadProject(file, options = {}) {
+    const baseUrl = normalizeBaseUrl(this.baseUrl);
+    const userId = resolveUserId(options.userId ?? this.userId);
+    const projectId = resolveProjectId(options.projectId ?? this.projectId);
+    return uploadFile(
+      this.fetchImpl,
+      `${baseUrl}/api/v1/storage/upload/project/${encodeStorageSegment(userId)}/${encodeStorageSegment(projectId)}`,
+      file,
+      {
+        token: this.token,
+        headers: this.headers,
+        credentials: this.credentials,
+      },
+    );
+  }
+
+  async download(url, outputPath) {
+    if (outputPath !== undefined) {
+      throw new ConfigurationError(
+        'Front-end mode does not support downloading directly to a filesystem path. Omit outputPath to receive a Blob.',
+      );
+    }
+    return downloadBlob(this.fetchImpl, url, {
+      headers: this.headers,
+      credentials: this.credentials,
+    });
+  }
+}
+
+function defaultClient(options = {}) {
+  return new StorageClient(options);
+}
+
+export function previewUrl(bucket, objectKey, options = {}) {
+  return defaultClient(options).previewUrl(bucket, objectKey);
+}
+
+export function downloadUrl(bucket, objectKey, options = {}) {
+  return defaultClient(options).downloadUrl(bucket, objectKey);
+}
+
+export async function uploadUser(file, options = {}) {
+  return defaultClient(options).uploadUser(file);
+}
+
+export async function uploadProject(file, options = {}) {
+  return defaultClient(options).uploadProject(file, options);
+}
+
+export async function download(url, outputPathOrOptions, maybeOptions = {}) {
+  if (typeof outputPathOrOptions === 'string') {
+    throw new ConfigurationError(
+      'Front-end mode does not support downloading directly to a filesystem path. Omit outputPath to receive a Blob.',
+    );
+  }
+  return defaultClient(outputPathOrOptions ?? maybeOptions).download(url);
+}
+
+export { PlatformSdkError, ConfigurationError, ApiError };

package/src/index.d.ts

@@ -8,12 +8,35 @@ export interface UploadResult {
   download_url: string;
 }
 
+export interface BlobLike {
+  arrayBuffer(): Promise<ArrayBuffer>;
+  readonly size?: number;
+  readonly type?: string;
+  readonly name?: string;
+}
+
+export interface UploadBinaryDescriptor {
+  data?: ArrayBuffer | ArrayBufferView | BlobLike;
+  file?: ArrayBuffer | ArrayBufferView | BlobLike;
+  fileName?: string;
+  contentType?: string;
+}
+
+export type UploadSource =
+  | string
+  | ArrayBuffer
+  | ArrayBufferView
+  | BlobLike
+  | UploadBinaryDescriptor;
+
 export interface StorageClientOptions {
   baseUrl?: string;
   token?: string;
   userId?: string;
   projectId?: string;
   fetch?: typeof fetch;
+  headers?: HeadersInit;
+  credentials?: RequestCredentials;
 }
 
 export interface UploadProjectOptions extends StorageClientOptions {
@@ -34,8 +57,9 @@ export class StorageClient {
   constructor(options?: StorageClientOptions);
   previewUrl(bucket: string, objectKey: string): string;
   downloadUrl(bucket: string, objectKey: string): string;
-  uploadUser(filePath: string): Promise<UploadResult>;
-  uploadProject(filePath: string, options?: UploadProjectOptions): Promise<UploadResult>;
+  uploadUser(file: UploadSource): Promise<UploadResult>;
+  uploadProject(file: UploadSource, options?: UploadProjectOptions): Promise<UploadResult>;
+  download(url: string): Promise<Blob>;
   download(url: string, outputPath: string): Promise<string>;
 }
 
@@ -50,13 +74,14 @@ export function downloadUrl(
   options?: StorageClientOptions,
 ): string;
 export function uploadUser(
-  filePath: string,
+  file: UploadSource,
   options?: StorageClientOptions,
 ): Promise<UploadResult>;
 export function uploadProject(
-  filePath: string,
+  file: UploadSource,
   options?: UploadProjectOptions,
 ): Promise<UploadResult>;
+export function download(url: string, options?: StorageClientOptions): Promise<Blob>;
 export function download(
   url: string,
   outputPath: string,

package/src/index.js

@@ -1,89 +1,20 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-export class PlatformSdkError extends Error {
-  constructor(message, options = {}) {
-    super(message);
-    this.name = new.target.name;
-    this.status = options.status;
-    this.code = options.code;
-    this.details = options.details;
-  }
-}
-
-export class ConfigurationError extends PlatformSdkError {}
-export class ApiError extends PlatformSdkError {}
-
-function requireEnv(name) {
-  const value = process.env[name];
-  if (value) {
-    return value;
-  }
-  throw new ConfigurationError(`Missing required environment variable: ${name}`);
-}
-
-function normalizeBaseUrl(baseUrl) {
-  return (baseUrl ?? requireEnv('LICOS_API_BASE_URL')).replace(/\/+$/, '');
-}
-
-function resolveToken(token) {
-  return token ?? requireEnv('LICOS_USER_TOKEN');
-}
-
-function resolveUserId(userId) {
-  return userId ?? requireEnv('LICOS_USER_ID');
-}
-
-function resolveProjectId(projectId) {
-  return projectId ?? requireEnv('LICOS_PROJECT_ID');
-}
-
-function encodeStorageSegment(value) {
-  return encodeURIComponent(value);
-}
-
-function encodeObjectKey(value) {
-  return value.split('/').map(encodeStorageSegment).join('/');
-}
-
-function guessContentType(filePath) {
-  switch (path.extname(filePath).toLowerCase()) {
-    case '.txt':
-      return 'text/plain';
-    case '.json':
-      return 'application/json';
-    case '.pdf':
-      return 'application/pdf';
-    case '.png':
-      return 'image/png';
-    case '.jpg':
-    case '.jpeg':
-      return 'image/jpeg';
-    default:
-      return 'application/octet-stream';
-  }
-}
-
-async function readJsonEnvelope(response) {
-  let payload;
-  try {
-    payload = await response.json();
-  } catch (error) {
-    throw new ApiError('Platform API returned non-JSON response', {
-      status: response.status,
-      details: error instanceof Error ? error.message : String(error),
-    });
-  }
-
-  if (!response.ok || payload?.code !== 0) {
-    throw new ApiError(payload?.message ?? `Platform API failed: HTTP ${response.status}`, {
-      status: response.status,
-      code: payload?.code,
-      details: payload?.data ?? payload,
-    });
-  }
-  return payload.data;
-}
+import {
+  ApiError,
+  ConfigurationError,
+  PlatformSdkError,
+  downloadBlob,
+  encodeObjectKey,
+  encodeStorageSegment,
+  fileNameFromPath,
+  guessContentType,
+  normalizeBaseUrl,
+  resolveProjectId,
+  resolveUserId,
+  uploadFile,
+} from './shared.js';
 
 export class StorageClient {
   constructor(options = {}) {
@@ -92,6 +23,8 @@ export class StorageClient {
     this.userId = options.userId;
     this.projectId = options.projectId;
     this.fetchImpl = options.fetch ?? fetch;
+    this.headers = options.headers;
+    this.credentials = options.credentials;
   }
 
   previewUrl(bucket, objectKey) {
@@ -103,53 +36,56 @@ export class StorageClient {
     return `${this.previewUrl(bucket, objectKey)}?download=1`;
   }
 
-  async uploadUser(filePath) {
+  async uploadUser(file) {
     const baseUrl = normalizeBaseUrl(this.baseUrl);
-    return this.#upload(`${baseUrl}/api/v1/storage/upload/user`, filePath);
+    return this.#upload(`${baseUrl}/api/v1/storage/upload/user`, file);
   }
 
-  async uploadProject(filePath, options = {}) {
+  async uploadProject(file, options = {}) {
     const baseUrl = normalizeBaseUrl(this.baseUrl);
     const userId = resolveUserId(options.userId ?? this.userId);
     const projectId = resolveProjectId(options.projectId ?? this.projectId);
     return this.#upload(
       `${baseUrl}/api/v1/storage/upload/project/${encodeStorageSegment(userId)}/${encodeStorageSegment(projectId)}`,
-      filePath,
+      file,
     );
   }
 
   async download(url, outputPath) {
-    const response = await this.fetchImpl(url, { method: 'GET' });
-    if (!response.ok) {
-      throw new ApiError(`Platform download failed: HTTP ${response.status}`, {
-        status: response.status,
-      });
+    const blob = await downloadBlob(this.fetchImpl, url, {
+      headers: this.headers,
+      credentials: this.credentials,
+    });
+    if (outputPath === undefined) {
+      return blob;
     }
-    const buffer = Buffer.from(await response.arrayBuffer());
+    const buffer = Buffer.from(await blob.arrayBuffer());
     await fs.mkdir(path.dirname(outputPath), { recursive: true });
     await fs.writeFile(outputPath, buffer);
     return outputPath;
   }
 
-  async #upload(url, filePath) {
-    const token = resolveToken(this.token);
-    const fileBuffer = await fs.readFile(filePath);
-    const fileName = path.basename(filePath);
-    const formData = new FormData();
-    formData.append(
-      'file',
-      new Blob([fileBuffer], { type: guessContentType(filePath) }),
-      fileName,
-    );
-
-    const response = await this.fetchImpl(url, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${token}`,
+  async #upload(url, file) {
+    return uploadFile(
+      this.fetchImpl,
+      url,
+      file,
+      {
+        token: this.token,
+        headers: this.headers,
+        credentials: this.credentials,
       },
-      body: formData,
-    });
-    return readJsonEnvelope(response);
+      async (filePath) => {
+        const fileBuffer = await fs.readFile(filePath);
+        const fileName = fileNameFromPath(filePath);
+        const contentType = guessContentType(fileName);
+        return {
+          fileName,
+          contentType,
+          blob: new Blob([fileBuffer], { type: contentType }),
+        };
+      },
+    );
   }
 }
 
@@ -173,6 +109,11 @@ export async function uploadProject(filePath, options = {}) {
   return defaultClient(options).uploadProject(filePath, options);
 }
 
-export async function download(url, outputPath, options = {}) {
-  return defaultClient(options).download(url, outputPath);
+export async function download(url, outputPathOrOptions, maybeOptions = {}) {
+  if (typeof outputPathOrOptions === 'string') {
+    return defaultClient(maybeOptions).download(url, outputPathOrOptions);
+  }
+  return defaultClient(outputPathOrOptions ?? {}).download(url);
 }
+
+export { PlatformSdkError, ConfigurationError, ApiError };

package/src/shared.js

@@ -0,0 +1,256 @@
+export class PlatformSdkError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.status = options.status;
+    this.code = options.code;
+    this.details = options.details;
+  }
+}
+
+export class ConfigurationError extends PlatformSdkError {}
+export class ApiError extends PlatformSdkError {}
+
+export function isNodeRuntime() {
+  return typeof process !== 'undefined' && !!process?.versions?.node;
+}
+
+function readEnv(name) {
+  if (typeof process === 'undefined' || !process?.env) {
+    return undefined;
+  }
+  const value = process.env[name];
+  return value ? value : undefined;
+}
+
+export function requireEnv(name) {
+  const value = readEnv(name);
+  if (value) {
+    return value;
+  }
+  throw new ConfigurationError(`Missing required environment variable: ${name}`);
+}
+
+export function normalizeBaseUrl(baseUrl) {
+  if (typeof baseUrl === 'string') {
+    return baseUrl.replace(/\/+$/, '');
+  }
+
+  const envBaseUrl = readEnv('LICOS_API_BASE_URL');
+  if (envBaseUrl) {
+    return envBaseUrl.replace(/\/+$/, '');
+  }
+
+  if (!isNodeRuntime()) {
+    return '';
+  }
+
+  throw new ConfigurationError('Missing required environment variable: LICOS_API_BASE_URL');
+}
+
+export function resolveUserId(userId) {
+  return userId ?? requireEnv('LICOS_USER_ID');
+}
+
+export function resolveProjectId(projectId) {
+  return projectId ?? requireEnv('LICOS_PROJECT_ID');
+}
+
+export function encodeStorageSegment(value) {
+  return encodeURIComponent(value);
+}
+
+export function encodeObjectKey(value) {
+  return value.split('/').map(encodeStorageSegment).join('/');
+}
+
+export function fileNameFromPath(filePath) {
+  const parts = String(filePath).split(/[\\/]/);
+  const fileName = parts[parts.length - 1];
+  return fileName || 'upload.bin';
+}
+
+export function guessContentType(fileName) {
+  const ext = /\.[^./\\]+$/.exec(String(fileName).toLowerCase())?.[0] ?? '';
+  switch (ext) {
+    case '.txt':
+      return 'text/plain';
+    case '.json':
+      return 'application/json';
+    case '.pdf':
+      return 'application/pdf';
+    case '.png':
+      return 'image/png';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.gif':
+      return 'image/gif';
+    case '.webp':
+      return 'image/webp';
+    case '.svg':
+      return 'image/svg+xml';
+    case '.md':
+      return 'text/markdown';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+function isBlobLike(value) {
+  return !!value && typeof value === 'object' && typeof value.arrayBuffer === 'function';
+}
+
+function isBinaryDescriptor(value) {
+  if (!value || typeof value !== 'object' || isBlobLike(value)) {
+    return false;
+  }
+  return 'data' in value || 'file' in value;
+}
+
+function toUint8Array(data) {
+  if (data instanceof Uint8Array) {
+    return data;
+  }
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  return new Uint8Array(data);
+}
+
+async function normalizeBinaryPayload(data, overrides = {}) {
+  if (isBlobLike(data)) {
+    const fileName =
+      overrides.fileName ??
+      (typeof data.name === 'string' && data.name ? data.name : undefined) ??
+      'upload.bin';
+    const contentType =
+      overrides.contentType ??
+      (typeof data.type === 'string' && data.type ? data.type : undefined) ??
+      guessContentType(fileName);
+    return {
+      fileName,
+      contentType,
+      blob: new Blob([await data.arrayBuffer()], { type: contentType }),
+    };
+  }
+
+  if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+    const fileName = overrides.fileName ?? 'upload.bin';
+    const contentType = overrides.contentType ?? guessContentType(fileName);
+    return {
+      fileName,
+      contentType,
+      blob: new Blob([toUint8Array(data)], { type: contentType }),
+    };
+  }
+
+  throw new ConfigurationError(
+    'Unsupported upload input. Use a file path string, Blob/File, ArrayBuffer, TypedArray, or { data, fileName }.',
+  );
+}
+
+export async function normalizeUploadSource(source, readPathSource) {
+  if (typeof source === 'string') {
+    if (!readPathSource) {
+      throw new ConfigurationError(
+        'Front-end mode does not support filesystem path uploads. Pass File, Blob, ArrayBuffer, TypedArray, or { data, fileName } instead.',
+      );
+    }
+    return readPathSource(source);
+  }
+
+  if (isBinaryDescriptor(source)) {
+    return normalizeBinaryPayload(source.data ?? source.file, {
+      fileName: source.fileName,
+      contentType: source.contentType,
+    });
+  }
+
+  return normalizeBinaryPayload(source);
+}
+
+function headersFromInit(headersInit) {
+  return new Headers(headersInit ?? undefined);
+}
+
+export function buildRequestHeaders(options = {}, { authenticated = false } = {}) {
+  const headers = headersFromInit(options.headers);
+  if (authenticated && !headers.has('Authorization')) {
+    const resolvedToken = options.token ?? readEnv('LICOS_USER_TOKEN');
+    if (resolvedToken) {
+      headers.set('Authorization', `Bearer ${resolvedToken}`);
+    } else if (isNodeRuntime()) {
+      throw new ConfigurationError(
+        'Missing authentication token. Pass options.token, provide an Authorization header, or set LICOS_USER_TOKEN.',
+      );
+    }
+  }
+  return headers;
+}
+
+export function buildRequestInit(options = {}, init = {}) {
+  const requestInit = { ...init };
+  if (options.credentials) {
+    requestInit.credentials = options.credentials;
+  }
+  return requestInit;
+}
+
+export async function readJsonEnvelope(response) {
+  let payload;
+  try {
+    payload = await response.json();
+  } catch (error) {
+    throw new ApiError('Platform API returned non-JSON response', {
+      status: response.status,
+      details: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  if (!response.ok || payload?.code !== 0) {
+    throw new ApiError(payload?.message ?? `Platform API failed: HTTP ${response.status}`, {
+      status: response.status,
+      code: payload?.code,
+      details: payload?.data ?? payload,
+    });
+  }
+  return payload.data;
+}
+
+export async function downloadBlob(fetchImpl, url, options = {}) {
+  const response = await fetchImpl(
+    url,
+    buildRequestInit(options, {
+      method: 'GET',
+      headers: buildRequestHeaders(options),
+    }),
+  );
+  if (!response.ok) {
+    throw new ApiError(`Platform download failed: HTTP ${response.status}`, {
+      status: response.status,
+    });
+  }
+  if (typeof response.blob === 'function') {
+    return response.blob();
+  }
+  return new Blob([await response.arrayBuffer()], {
+    type: response.headers.get('content-type') ?? undefined,
+  });
+}
+
+export async function uploadFile(fetchImpl, url, source, options = {}, readPathSource) {
+  const normalized = await normalizeUploadSource(source, readPathSource);
+  const formData = new FormData();
+  formData.append('file', normalized.blob, normalized.fileName);
+
+  const response = await fetchImpl(
+    url,
+    buildRequestInit(options, {
+      method: 'POST',
+      headers: buildRequestHeaders(options, { authenticated: true }),
+      body: formData,
+    }),
+  );
+  return readJsonEnvelope(response);
+}