@life-palette/uploader 0.2.1

package/dist/index.d.cts

@@ -0,0 +1,195 @@
+import { AnalyzeMediaOptions, MediaAnalysisResult } from "@life-palette/media";
+//#region src/file-url.d.ts
+/**
+ * OSS URL 处理：图片缩略、实况照片配对、文件名解析等。
+ *
+ * 这些工具属于 OSS 契约的一部分——既被上传器消费，也被前端展示层消费。
+ */
+export interface FileData {
+  cover?: string;
+  extension?: string;
+  live_photo_video?: {
+    url?: string;
+    video_variants?: Array<{
+      quality?: string;
+      url?: string;
+    }>;
+  };
+  type?: string;
+  url?: string;
+  [key: string]: unknown;
+}
+export interface FileParseOptions {
+  format?: string;
+  resize?: number;
+}
+export interface FileParseResult extends FileData {
+  baseSrc: string;
+  cover: string;
+  fileType: "IMAGE" | "VIDEO";
+  thumbnailUrl: string;
+  videoSrc: string;
+}
+/**
+ * 解析文件数据，生成展示所需的 URL
+ * - IMAGE: thumbnailUrl（缩略图）、baseSrc（原图/转格式）、videoSrc（实况视频）
+ * - VIDEO: cover（封面截图）
+ */
+export declare function fileParse(data: FileData, options?: FileParseOptions): FileParseResult;
+/**
+ * 判断文件是否为视频
+ */
+export declare function isVideo(file: {
+  type?: string;
+}): boolean;
+/**
+ * 判断文件是否为实况照片（有 videoSrc 但本身不是视频）
+ */
+export declare function isLivePhoto(file: {
+  type?: string;
+  videoSrc?: string | null;
+}): boolean;
+/**
+ * 生成 OSS 视频截帧 URL
+ */
+export declare function getVideoThumbnailUrl(videoUrl: string): string;
+/**
+ * 生成 OSS 图片处理参数（resize + quality + webp）
+ */
+export declare function generateOssImageParams(originalWidth: number, originalHeight: number, targetWidth: number, quality?: number): string;
+/**
+ * 解析文件名 → baseName + ext + isVideo
+ */
+export declare function parseFileName(fileName: string): {
+  baseName: string;
+  ext: string;
+  isVideo: boolean;
+};
+//#endregion
+//#region src/live-photo.d.ts
+/**
+ * Live Photo pairing utilities.
+ */
+/**
+ * 检测文件列表中的 Live Photo 配对（同名 image + video）。
+ */
+export declare function detectLivePhotoPairs<T extends {
+  name: string;
+  type?: string;
+}>(files: T[]): Array<{
+  image: T;
+  video: T;
+}>;
+//#endregion
+//#region src/pool.d.ts
+/**
+ * Concurrency-limited async pool.
+ *
+ * Lightweight replacement for `p-limit` (≈ 30 lines, no dependency).
+ */
+export declare class PromisePool {
+  private readonly limit;
+  private active;
+  private readonly queue;
+  constructor(limit: number);
+  run<T>(task: () => Promise<T>): Promise<T>;
+  private next;
+}
+/**
+ * Retry an async operation with exponential backoff.
+ */
+export declare function withRetry<T>(task: () => Promise<T>, attempts: number, baseDelayMs?: number): Promise<T>;
+//#endregion
+//#region src/uploader.d.ts
+export interface OSSFile {
+  address?: string;
+  arthash?: string;
+  arthash_codec?: string;
+  blurhash?: string;
+  colors?: unknown[];
+  created_at: string;
+  file_md5: string;
+  height?: number;
+  is_private: boolean;
+  live_photo_video_id?: number;
+  live_photo_video_sec_uid?: string;
+  name: string;
+  sec_uid: string;
+  size: number;
+  taken_at?: string;
+  type: string;
+  updated_at: string;
+  url: string;
+  width?: number;
+}
+export interface UploadToken {
+  accessid: string;
+  dir: string;
+  expire: number;
+  host: string;
+  key: string;
+  policy: string;
+  signature: string;
+}
+export interface CompletePart {
+  etag: string;
+  part_number: number;
+}
+export type UploadStage = "compress" | "analyze" | "md5" | "upload" | "complete";
+export interface UploadProgress {
+  percent: number;
+  stage: UploadStage;
+}
+export interface UploadOptions {
+  /** 媒体分析参数 */
+  analysis?: Omit<AnalyzeMediaOptions, "onProgress">;
+  /** 是否在上传前执行浏览器端媒体分析，默认 true */
+  analyze?: boolean;
+  /** 压缩图片 */
+  compress?: boolean;
+  /** 是否私有 */
+  isPrivate?: boolean;
+  /** 手动地理位置（经纬度） */
+  location?: {
+    lat: number;
+    lng: number;
+  };
+  /** 最大文件大小 MB（压缩用） */
+  maxSizeMB?: number;
+  /** 进度回调 */
+  onProgress?: (progress: UploadProgress) => void;
+  /** 已经计算好的分析结果，可避免上传前重复分析 */
+  precomputedAnalysis?: MediaAnalysisResult;
+}
+/** 仅上传文件到 OSS，不创建 DB 记录 */
+export interface UploadToOSSResult {
+  file_name: string;
+  file_size: number;
+  key: string;
+  md5: string;
+  parts?: CompletePart[];
+  upload_id?: string;
+}
+export interface UploaderConfig {
+  /** API 基础路径，如 https://api.lpalette.cn/api/v1 */
+  apiBaseUrl: string;
+  /** 分片大小（字节），默认 5MB */
+  chunkSize?: number;
+  /** 带浏览器 metadata 的完成接口，默认 /file/upload/complete */
+  completeEndpoint?: string;
+  /** 获取 token 的函数 */
+  getToken: () => string | null;
+  /** 分片阈值（字节），默认 5MB */
+  multipartThreshold?: number;
+  /** 分片并发数，默认 4 */
+  partConcurrency?: number;
+  /** 单片失败重试次数，默认 3 */
+  partRetries?: number;
+}
+export declare function createOssUploader(config: UploaderConfig): {
+  associateLivePhotos: (results: OSSFile[]) => Promise<OSSFile[]>;
+  upload: (file: File, options?: UploadOptions) => Promise<OSSFile>;
+  uploadBatch: (files: File[], options?: UploadOptions, concurrency?: number, maxRetries?: number) => Promise<OSSFile[]>;
+  uploadToOSS: (file: File, options?: UploadOptions) => Promise<UploadToOSSResult>;
+};
+//#endregion

package/dist/index.d.mts

@@ -0,0 +1,195 @@
+import { AnalyzeMediaOptions, MediaAnalysisResult } from "@life-palette/media";
+//#region src/file-url.d.ts
+/**
+ * OSS URL 处理：图片缩略、实况照片配对、文件名解析等。
+ *
+ * 这些工具属于 OSS 契约的一部分——既被上传器消费，也被前端展示层消费。
+ */
+export interface FileData {
+  cover?: string;
+  extension?: string;
+  live_photo_video?: {
+    url?: string;
+    video_variants?: Array<{
+      quality?: string;
+      url?: string;
+    }>;
+  };
+  type?: string;
+  url?: string;
+  [key: string]: unknown;
+}
+export interface FileParseOptions {
+  format?: string;
+  resize?: number;
+}
+export interface FileParseResult extends FileData {
+  baseSrc: string;
+  cover: string;
+  fileType: "IMAGE" | "VIDEO";
+  thumbnailUrl: string;
+  videoSrc: string;
+}
+/**
+ * 解析文件数据，生成展示所需的 URL
+ * - IMAGE: thumbnailUrl（缩略图）、baseSrc（原图/转格式）、videoSrc（实况视频）
+ * - VIDEO: cover（封面截图）
+ */
+export declare function fileParse(data: FileData, options?: FileParseOptions): FileParseResult;
+/**
+ * 判断文件是否为视频
+ */
+export declare function isVideo(file: {
+  type?: string;
+}): boolean;
+/**
+ * 判断文件是否为实况照片（有 videoSrc 但本身不是视频）
+ */
+export declare function isLivePhoto(file: {
+  type?: string;
+  videoSrc?: string | null;
+}): boolean;
+/**
+ * 生成 OSS 视频截帧 URL
+ */
+export declare function getVideoThumbnailUrl(videoUrl: string): string;
+/**
+ * 生成 OSS 图片处理参数（resize + quality + webp）
+ */
+export declare function generateOssImageParams(originalWidth: number, originalHeight: number, targetWidth: number, quality?: number): string;
+/**
+ * 解析文件名 → baseName + ext + isVideo
+ */
+export declare function parseFileName(fileName: string): {
+  baseName: string;
+  ext: string;
+  isVideo: boolean;
+};
+//#endregion
+//#region src/live-photo.d.ts
+/**
+ * Live Photo pairing utilities.
+ */
+/**
+ * 检测文件列表中的 Live Photo 配对（同名 image + video）。
+ */
+export declare function detectLivePhotoPairs<T extends {
+  name: string;
+  type?: string;
+}>(files: T[]): Array<{
+  image: T;
+  video: T;
+}>;
+//#endregion
+//#region src/pool.d.ts
+/**
+ * Concurrency-limited async pool.
+ *
+ * Lightweight replacement for `p-limit` (≈ 30 lines, no dependency).
+ */
+export declare class PromisePool {
+  private readonly limit;
+  private active;
+  private readonly queue;
+  constructor(limit: number);
+  run<T>(task: () => Promise<T>): Promise<T>;
+  private next;
+}
+/**
+ * Retry an async operation with exponential backoff.
+ */
+export declare function withRetry<T>(task: () => Promise<T>, attempts: number, baseDelayMs?: number): Promise<T>;
+//#endregion
+//#region src/uploader.d.ts
+export interface OSSFile {
+  address?: string;
+  arthash?: string;
+  arthash_codec?: string;
+  blurhash?: string;
+  colors?: unknown[];
+  created_at: string;
+  file_md5: string;
+  height?: number;
+  is_private: boolean;
+  live_photo_video_id?: number;
+  live_photo_video_sec_uid?: string;
+  name: string;
+  sec_uid: string;
+  size: number;
+  taken_at?: string;
+  type: string;
+  updated_at: string;
+  url: string;
+  width?: number;
+}
+export interface UploadToken {
+  accessid: string;
+  dir: string;
+  expire: number;
+  host: string;
+  key: string;
+  policy: string;
+  signature: string;
+}
+export interface CompletePart {
+  etag: string;
+  part_number: number;
+}
+export type UploadStage = "compress" | "analyze" | "md5" | "upload" | "complete";
+export interface UploadProgress {
+  percent: number;
+  stage: UploadStage;
+}
+export interface UploadOptions {
+  /** 媒体分析参数 */
+  analysis?: Omit<AnalyzeMediaOptions, "onProgress">;
+  /** 是否在上传前执行浏览器端媒体分析，默认 true */
+  analyze?: boolean;
+  /** 压缩图片 */
+  compress?: boolean;
+  /** 是否私有 */
+  isPrivate?: boolean;
+  /** 手动地理位置（经纬度） */
+  location?: {
+    lat: number;
+    lng: number;
+  };
+  /** 最大文件大小 MB（压缩用） */
+  maxSizeMB?: number;
+  /** 进度回调 */
+  onProgress?: (progress: UploadProgress) => void;
+  /** 已经计算好的分析结果，可避免上传前重复分析 */
+  precomputedAnalysis?: MediaAnalysisResult;
+}
+/** 仅上传文件到 OSS，不创建 DB 记录 */
+export interface UploadToOSSResult {
+  file_name: string;
+  file_size: number;
+  key: string;
+  md5: string;
+  parts?: CompletePart[];
+  upload_id?: string;
+}
+export interface UploaderConfig {
+  /** API 基础路径，如 https://api.lpalette.cn/api/v1 */
+  apiBaseUrl: string;
+  /** 分片大小（字节），默认 5MB */
+  chunkSize?: number;
+  /** 带浏览器 metadata 的完成接口，默认 /file/upload/complete */
+  completeEndpoint?: string;
+  /** 获取 token 的函数 */
+  getToken: () => string | null;
+  /** 分片阈值（字节），默认 5MB */
+  multipartThreshold?: number;
+  /** 分片并发数，默认 4 */
+  partConcurrency?: number;
+  /** 单片失败重试次数，默认 3 */
+  partRetries?: number;
+}
+export declare function createOssUploader(config: UploaderConfig): {
+  associateLivePhotos: (results: OSSFile[]) => Promise<OSSFile[]>;
+  upload: (file: File, options?: UploadOptions) => Promise<OSSFile>;
+  uploadBatch: (files: File[], options?: UploadOptions, concurrency?: number, maxRetries?: number) => Promise<OSSFile[]>;
+  uploadToOSS: (file: File, options?: UploadOptions) => Promise<UploadToOSSResult>;
+};
+//#endregion