@life-palette/uploader 0.2.1

package/README.md

@@ -0,0 +1,50 @@
+# @life-palette/uploader
+
+OSS uploader for the Life Palette stack: image compression → media analysis → multipart upload (concurrent, retryable per part) → server-side completion → live-photo pairing. Browser-only, framework-agnostic.
+
+## Highlights
+
+- **Concurrent multipart upload** — `partConcurrency` parts in flight at once.
+- **Per-part retry with backoff** — defaults to 3 attempts.
+- **Resumable** — `init` returns `uploaded_part_etags` so retries only re-upload what's missing.
+- **Live-photo pairing** — auto-associates `.jpg + .mov` pairs after a batch upload.
+- **Pure factory** — no Vue/React/Svelte dependency.
+
+## Install
+
+```bash
+pnpm add @life-palette/uploader @life-palette/media
+```
+
+## Usage
+
+```ts
+import { createOssUploader } from "@life-palette/uploader";
+
+const uploader = createOssUploader({
+  apiBaseUrl: "https://api.example.com/api/v1",
+  getToken: () => localStorage.getItem("access_token"),
+});
+
+const file = await selectFile({ accept: "image/*,video/*" });
+if (!file) return;
+
+const result = await uploader.upload(file, {
+  compress: true,
+  onProgress: ({ stage, percent }) => console.log(stage, percent),
+});
+console.log(result.url);
+```
+
+## API surface
+
+| Export | Description |
+| --- | --- |
+| `createOssUploader(config)` | Factory returning `{ upload, uploadBatch, uploadToOSS, associateLivePhotos }` |
+| `fileParse`, `isVideo`, `isLivePhoto`, `getVideoThumbnailUrl`, `generateOssImageParams`, `parseFileName` | OSS URL/display helpers |
+| `detectLivePhotoPairs` | Pair JPG+MOV files by base name |
+| `PromisePool`, `withRetry` | Small async utilities |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,575 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _life_palette_media = require("@life-palette/media");
+//#region src/file-url.ts
+/**
+* OSS URL 处理：图片缩略、实况照片配对、文件名解析等。
+*
+* 这些工具属于 OSS 契约的一部分——既被上传器消费，也被前端展示层消费。
+*/
+const NEED_FORMAT_EXTS = [".heic", ".heif"];
+const VIDEO_EXTS = [
+	"mov",
+	"mp4",
+	"avi",
+	"mkv",
+	"webm",
+	"m4v"
+];
+/**
+* 从 live_photo_video.video_variants 中取 1080p，兜底取原始 url
+*/
+function getLivePhotoVideoUrl(file) {
+	const lv = file?.live_photo_video;
+	if (!lv) return "";
+	const variants = lv.video_variants;
+	if (Array.isArray(variants) && variants.length) {
+		const v1080 = variants.find((v) => v.quality === "1080p");
+		if (v1080?.url) return v1080.url;
+	}
+	return lv.url || "";
+}
+/**
+* 解析文件数据，生成展示所需的 URL
+* - IMAGE: thumbnailUrl（缩略图）、baseSrc（原图/转格式）、videoSrc（实况视频）
+* - VIDEO: cover（封面截图）
+*/
+function fileParse(data, options) {
+	const { url = "", type = "" } = data || {};
+	const fileType = type.toUpperCase().includes("VIDEO") ? "VIDEO" : "IMAGE";
+	const { format = "jpg", resize = 400 } = options || {};
+	let baseSrc = "";
+	let thumbnailUrl = "";
+	let cover = "";
+	let videoSrc = "";
+	if (fileType === "IMAGE") {
+		const ext = (data?.extension || url.slice(Math.max(0, url.lastIndexOf(".")))).toLowerCase();
+		if (NEED_FORMAT_EXTS.some((e) => ext.includes(e))) {
+			baseSrc = `${url}?x-oss-process=image/format,${format}`;
+			thumbnailUrl = `${url}?x-oss-process=image/resize,l_${resize}/format,${format}`;
+		} else {
+			baseSrc = url;
+			thumbnailUrl = `${url}?x-oss-process=image/resize,l_${resize}`;
+		}
+		videoSrc = getLivePhotoVideoUrl(data);
+	} else cover = data?.cover || `${url}?x-oss-process=video/snapshot,t_7000,f_${format},w_0,h_0,m_fast`;
+	return {
+		...data,
+		baseSrc,
+		cover,
+		fileType,
+		thumbnailUrl,
+		videoSrc
+	};
+}
+/**
+* 判断文件是否为视频
+*/
+function isVideo(file) {
+	return !!file.type?.startsWith("video/");
+}
+/**
+* 判断文件是否为实况照片（有 videoSrc 但本身不是视频）
+*/
+function isLivePhoto(file) {
+	return !!(file.videoSrc && !isVideo(file));
+}
+/**
+* 生成 OSS 视频截帧 URL
+*/
+function getVideoThumbnailUrl(videoUrl) {
+	return `${videoUrl}?x-oss-process=video/snapshot,t_1000,f_jpg,w_0,h_0,m_fast`;
+}
+/**
+* 生成 OSS 图片处理参数（resize + quality + webp）
+*/
+function generateOssImageParams(originalWidth, originalHeight, targetWidth, quality = 10) {
+	if (!(originalWidth && originalHeight)) return `?x-oss-process=image/resize,w_${targetWidth},m_lfit/quality,q_${quality}/format,webp`;
+	return `?x-oss-process=image/resize,w_${targetWidth},h_${Math.round(originalHeight / originalWidth * targetWidth)},m_lfit/quality,q_${quality}/format,webp`;
+}
+/**
+* 解析文件名 → baseName + ext + isVideo
+*/
+function parseFileName(fileName) {
+	const parts = fileName.split(".");
+	const ext = (parts.pop() || "").toLowerCase();
+	return {
+		baseName: parts.join("."),
+		ext,
+		isVideo: VIDEO_EXTS.includes(ext)
+	};
+}
+//#endregion
+//#region src/live-photo.ts
+/**
+* Live Photo pairing utilities.
+*/
+/**
+* 检测文件列表中的 Live Photo 配对（同名 image + video）。
+*/
+function detectLivePhotoPairs(files) {
+	const pairs = [];
+	const usedIndices = /* @__PURE__ */ new Set();
+	files.forEach((file, idx) => {
+		const { baseName, isVideo: isVid } = parseFileName(file.name);
+		if (!isVid) return;
+		const imageIdx = files.findIndex((f, i) => {
+			if (i === idx || usedIndices.has(i)) return false;
+			const info = parseFileName(f.name);
+			return info.baseName === baseName && !info.isVideo;
+		});
+		if (imageIdx !== -1) {
+			const image = files[imageIdx];
+			if (!image) return;
+			pairs.push({
+				image,
+				video: file
+			});
+			usedIndices.add(imageIdx);
+			usedIndices.add(idx);
+		}
+	});
+	return pairs;
+}
+//#endregion
+//#region src/pool.ts
+/**
+* Concurrency-limited async pool.
+*
+* Lightweight replacement for `p-limit` (≈ 30 lines, no dependency).
+*/
+var PromisePool = class {
+	limit;
+	active = 0;
+	queue = [];
+	constructor(limit) {
+		this.limit = limit;
+	}
+	run(task) {
+		return new Promise((resolve, reject) => {
+			const execute = () => {
+				this.active += 1;
+				task().then(resolve, reject).finally(() => {
+					this.active -= 1;
+					this.next();
+				});
+			};
+			this.queue.push(execute);
+			this.next();
+		});
+	}
+	next() {
+		while (this.active < this.limit && this.queue.length > 0) this.queue.shift()?.();
+	}
+};
+/**
+* Retry an async operation with exponential backoff.
+*/
+async function withRetry(task, attempts, baseDelayMs = 500) {
+	let lastError;
+	for (let index = 0; index < attempts; index += 1) try {
+		return await task();
+	} catch (error) {
+		lastError = error;
+		if (index === attempts - 1) break;
+		await new Promise((r) => setTimeout(r, baseDelayMs * 2 ** index));
+	}
+	throw lastError;
+}
+//#endregion
+//#region src/uploader.ts
+/**
+* OSS Uploader — pure factory with no framework dependency.
+*
+* Pipeline: compress(optional) → analyze → init(秒传检查) → upload parts → complete.
+* Concurrent multipart upload with per-part retry; live-photo association runs after batch.
+*/
+const RE_HOST_PREFIX = /^https?:\/\/[^/]+\//;
+function createOssUploader(config) {
+	const { apiBaseUrl, getToken, multipartThreshold = 5242880, chunkSize = 5242880, partConcurrency = 4, partRetries = 3, completeEndpoint = "/file/upload/complete" } = config;
+	const uploadPath = "/file/upload";
+	async function request(endpoint, method, body) {
+		const token = getToken();
+		const res = await fetch(`${apiBaseUrl}${endpoint}`, {
+			body: JSON.stringify(body),
+			headers: {
+				"Content-Type": "application/json",
+				...token ? { Authorization: `Bearer ${token}` } : {}
+			},
+			method
+		});
+		const data = await res.json();
+		if (!res.ok || data.code && data.code >= 400) throw new Error(data.message || data.msg || "请求失败");
+		return data.data ?? data.result;
+	}
+	function initUpload(fileName, fileSize, md5, chunk) {
+		const body = {
+			file_name: fileName,
+			file_size: fileSize,
+			md5
+		};
+		if (chunk) body.chunk_size = chunk;
+		return request(`${uploadPath}/init`, "POST", body);
+	}
+	function completeUpload(data) {
+		return request(completeEndpoint, "POST", data);
+	}
+	function getPartUrls(key, uploadId, partNumbers) {
+		return request(`${uploadPath}/urls`, "POST", {
+			key,
+			part_numbers: partNumbers,
+			upload_id: uploadId
+		});
+	}
+	async function compress(file, maxSizeMB = 1) {
+		if (!file.type.startsWith("image/")) return file;
+		try {
+			const { default: imageCompression } = await import("browser-image-compression");
+			const compressed = await imageCompression(file, {
+				maxSizeMB,
+				preserveExif: true,
+				useWebWorker: true
+			});
+			return compressed.name ? compressed : new File([compressed], file.name, { type: compressed.type || file.type });
+		} catch {
+			return file;
+		}
+	}
+	function simpleUpload(token, file, onProgress) {
+		const fd = new FormData();
+		fd.append("key", token.key);
+		fd.append("policy", token.policy);
+		fd.append("OSSAccessKeyId", token.accessid);
+		fd.append("signature", token.signature);
+		fd.append("success_action_status", "200");
+		fd.append("file", file);
+		return new Promise((resolve, reject) => {
+			const xhr = new XMLHttpRequest();
+			xhr.upload.onprogress = (e) => {
+				if (e.lengthComputable) onProgress?.(Math.round(e.loaded / e.total * 100));
+			};
+			xhr.onload = () => xhr.status === 200 ? resolve() : reject(/* @__PURE__ */ new Error(`OSS 上传失败: ${xhr.status}`));
+			xhr.onerror = () => reject(/* @__PURE__ */ new Error("OSS 上传失败"));
+			xhr.open("POST", token.host);
+			xhr.send(fd);
+		});
+	}
+	async function uploadPart(part) {
+		return withRetry(async () => {
+			const res = await fetch(part.url, {
+				body: part.blob,
+				headers: { "Content-Type": "application/octet-stream" },
+				method: "PUT"
+			});
+			if (!res.ok) throw new Error(`Failed to upload part ${part.partNumber}: ${res.status}`);
+			return {
+				etag: (res.headers.get("ETag") || "").replace(/"/g, ""),
+				part_number: part.partNumber
+			};
+		}, partRetries);
+	}
+	async function multipartUpload(file, md5, metadata, isPrivate, location, onProgress) {
+		const init = await initUpload(file.name, file.size, md5, chunkSize);
+		if (init.exists) {
+			onProgress?.(100);
+			return init.file;
+		}
+		if (init.mode !== "multipart") throw new Error("Unexpected upload mode");
+		const { upload_id: uid, key, uploaded_parts: done = [], uploaded_part_etags: existingParts = [], total_parts: total } = init;
+		const doneSet = new Set(done);
+		const pending = Array.from({ length: total }, (_, i) => i + 1).filter((n) => !doneSet.has(n));
+		const parts = [...existingParts];
+		let uploaded = 0;
+		if (pending.length > 0) {
+			const { urls } = await getPartUrls(key, uid, pending);
+			const urlMap = new Map(urls.map((u) => [u.part_number, u.url]));
+			const pool = new PromisePool(partConcurrency);
+			const tasks = pending.map((partNumber) => {
+				const url = urlMap.get(partNumber);
+				if (!url) throw new Error(`No URL for part ${partNumber}`);
+				const start = (partNumber - 1) * chunkSize;
+				const blob = file.slice(start, Math.min(start + chunkSize, file.size));
+				return () => uploadPart({
+					blob,
+					partNumber,
+					url
+				}).then((part) => {
+					parts.push(part);
+					uploaded += 1;
+					onProgress?.(Math.round(uploaded / pending.length * 100));
+				});
+			});
+			await Promise.all(tasks.map((t) => pool.run(t)));
+		}
+		parts.sort((a, b) => a.part_number - b.part_number);
+		onProgress?.(100);
+		return completeUpload({
+			file_name: file.name,
+			file_size: file.size,
+			is_private: isPrivate,
+			key,
+			md5,
+			parts,
+			upload_id: uid,
+			...location ? {
+				lat: location.lat,
+				lng: location.lng
+			} : {},
+			metadata
+		});
+	}
+	/**
+	* 仅上传文件到 OSS，不调用 completeUpload（不创建 DB 记录）
+	*/
+	async function uploadToOSS(file, options = {}) {
+		const { compress: shouldCompress = false, maxSizeMB, onProgress } = options;
+		let processed = file;
+		if (shouldCompress && file.type.startsWith("image/")) {
+			onProgress?.({
+				percent: 0,
+				stage: "compress"
+			});
+			processed = await compress(file, maxSizeMB);
+			onProgress?.({
+				percent: 100,
+				stage: "compress"
+			});
+		}
+		onProgress?.({
+			percent: 0,
+			stage: "md5"
+		});
+		const md5 = await (0, _life_palette_media.hashBlob)(processed);
+		onProgress?.({
+			percent: 100,
+			stage: "md5"
+		});
+		onProgress?.({
+			percent: 0,
+			stage: "upload"
+		});
+		const init = await initUpload(processed.name, processed.size, md5, processed.size >= multipartThreshold ? chunkSize : void 0);
+		if (init.exists) {
+			onProgress?.({
+				percent: 100,
+				stage: "complete"
+			});
+			return {
+				file_name: processed.name,
+				file_size: processed.size,
+				key: init.file.url.replace(RE_HOST_PREFIX, ""),
+				md5: init.file.file_md5
+			};
+		}
+		if (init.mode === "simple") {
+			await simpleUpload(init.token, processed, (pct) => onProgress?.({
+				percent: pct,
+				stage: "upload"
+			}));
+			onProgress?.({
+				percent: 100,
+				stage: "complete"
+			});
+			return {
+				file_name: processed.name,
+				file_size: processed.size,
+				key: init.token.key,
+				md5
+			};
+		}
+		const { upload_id: uid, key, uploaded_parts: done = [] } = init;
+		const doneSet = new Set(done);
+		const pending = Array.from({ length: init.total_parts }, (_, i) => i + 1).filter((n) => !doneSet.has(n));
+		const parts = [];
+		if (pending.length > 0) {
+			const { urls } = await getPartUrls(key, uid, pending);
+			const urlMap = new Map(urls.map((u) => [u.part_number, u.url]));
+			const pool = new PromisePool(partConcurrency);
+			const tasks = pending.map((partNumber) => {
+				const url = urlMap.get(partNumber);
+				if (!url) throw new Error(`No URL for part ${partNumber}`);
+				const start = (partNumber - 1) * chunkSize;
+				const blob = processed.slice(start, Math.min(start + chunkSize, processed.size));
+				return () => uploadPart({
+					blob,
+					partNumber,
+					url
+				});
+			});
+			const collected = await Promise.all(tasks.map((t) => pool.run(t)));
+			collected.sort((a, b) => a.part_number - b.part_number);
+			parts.push(...collected);
+		}
+		onProgress?.({
+			percent: 100,
+			stage: "complete"
+		});
+		return {
+			file_name: processed.name,
+			file_size: processed.size,
+			key,
+			md5,
+			parts,
+			upload_id: uid
+		};
+	}
+	/**
+	* 上传单个文件（完整流程：压缩 → 分析 → MD5 → OSS → complete）。
+	*/
+	async function upload(file, options = {}) {
+		const { compress: shouldCompress = false, maxSizeMB, isPrivate, location, onProgress, analyze: shouldAnalyze = true, analysis: analysisOptions, precomputedAnalysis } = options;
+		let processed = file;
+		if (shouldCompress && file.type.startsWith("image/")) {
+			onProgress?.({
+				percent: 0,
+				stage: "compress"
+			});
+			processed = await compress(file, maxSizeMB);
+			onProgress?.({
+				percent: 100,
+				stage: "compress"
+			});
+		}
+		let metadata;
+		let md5;
+		if (precomputedAnalysis) {
+			metadata = precomputedAnalysis;
+			md5 = metadata.basic.md5;
+			if (!md5) throw new Error("预计算媒体分析结果缺少 MD5");
+		} else if (shouldAnalyze) {
+			onProgress?.({
+				percent: 0,
+				stage: "analyze"
+			});
+			metadata = await (0, _life_palette_media.analyzeMedia)(processed, {
+				...analysisOptions,
+				onProgress: ({ stage, percent }) => {
+					if (stage === "md5") onProgress?.({
+						percent: Math.round(percent * .35),
+						stage: "analyze"
+					});
+					else if (stage === "decode") onProgress?.({
+						percent: 35 + Math.round(percent * .35),
+						stage: "analyze"
+					});
+					else onProgress?.({
+						percent: 70 + Math.round(percent * .3),
+						stage: "analyze"
+					});
+				}
+			});
+			md5 = metadata.basic.md5;
+		} else {
+			onProgress?.({
+				percent: 0,
+				stage: "md5"
+			});
+			md5 = await (0, _life_palette_media.hashBlob)(processed);
+			metadata = {
+				basic: {
+					extension: processed.name.includes(".") ? processed.name.slice(processed.name.lastIndexOf(".")) : "",
+					md5,
+					name: processed.name,
+					size: processed.size,
+					type: processed.type
+				},
+				schema_version: 1
+			};
+		}
+		if (!metadata) throw new Error("媒体 metadata 生成失败");
+		onProgress?.({
+			percent: 0,
+			stage: "upload"
+		});
+		const result = processed.size >= multipartThreshold ? await multipartUpload(processed, md5, metadata, isPrivate, location, (pct) => onProgress?.({
+			percent: pct,
+			stage: "upload"
+		})) : await simpleUploadWithComplete(processed, md5, metadata, isPrivate, location, (pct) => onProgress?.({
+			percent: pct,
+			stage: "upload"
+		}));
+		onProgress?.({
+			percent: 100,
+			stage: "complete"
+		});
+		return result;
+	}
+	async function simpleUploadWithComplete(file, md5, metadata, isPrivate, location, onProgress) {
+		onProgress?.(10);
+		const init = await initUpload(file.name, file.size, md5);
+		if (init.exists) {
+			onProgress?.(100);
+			return init.file;
+		}
+		if (init.mode !== "simple") throw new Error("Unexpected upload mode");
+		onProgress?.(30);
+		await simpleUpload(init.token, file, (pct) => onProgress?.(30 + Math.round(pct * .55)));
+		onProgress?.(90);
+		return completeUpload({
+			file_name: file.name,
+			file_size: file.size,
+			is_private: isPrivate,
+			key: init.token.key,
+			md5,
+			...location ? {
+				lat: location.lat,
+				lng: location.lng
+			} : {},
+			metadata
+		});
+	}
+	async function associateLivePhotos(results) {
+		const associatedResults = [...results];
+		for (const { image, video } of detectLivePhotoPairs(results)) {
+			if (!(image && video)) continue;
+			try {
+				const updatedImage = await request(`/file/${image.sec_uid}`, "PUT", { live_photo_video_sec_uid: video.sec_uid });
+				const imageIndex = associatedResults.findIndex((item) => item.sec_uid === image.sec_uid);
+				if (imageIndex >= 0) associatedResults[imageIndex] = {
+					...associatedResults[imageIndex],
+					...updatedImage,
+					live_photo_video_sec_uid: video.sec_uid
+				};
+			} catch (e) {
+				console.error("实况照片关联失败:", e);
+			}
+		}
+		return associatedResults;
+	}
+	/**
+	* 批量上传（并发，带重试），上传完成后自动关联实况照片
+	*/
+	async function uploadBatch(files, options = {}, concurrency = 2, maxRetries = 3) {
+		const pool = new PromisePool(concurrency);
+		const settled = await Promise.allSettled(files.map((file) => pool.run(async () => {
+			let lastErr = null;
+			for (let attempt = 0; attempt < maxRetries; attempt += 1) try {
+				return await upload(file, options);
+			} catch (e) {
+				lastErr = e;
+				if (attempt < maxRetries - 1) await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
+			}
+			throw lastErr;
+		})));
+		const successes = [];
+		for (const result of settled) if (result.status === "fulfilled") successes.push(result.value);
+		else console.error("文件上传失败:", result.reason);
+		return associateLivePhotos(successes);
+	}
+	return {
+		associateLivePhotos,
+		upload,
+		uploadBatch,
+		uploadToOSS
+	};
+}
+//#endregion
+exports.PromisePool = PromisePool;
+exports.createOssUploader = createOssUploader;
+exports.detectLivePhotoPairs = detectLivePhotoPairs;
+exports.fileParse = fileParse;
+exports.generateOssImageParams = generateOssImageParams;
+exports.getVideoThumbnailUrl = getVideoThumbnailUrl;
+exports.isLivePhoto = isLivePhoto;
+exports.isVideo = isVideo;
+exports.parseFileName = parseFileName;
+exports.withRetry = withRetry;