@hubfluencer/mcp 0.4.0 → 0.6.0

package/src/uploads.ts

@@ -12,10 +12,39 @@
  * are confined to HUBFLUENCER_INPUT_DIR (or cwd) and an extension allowlist.
  */
 
+import { createReadStream, type ReadStream } from "node:fs";
 import { open, readFile, stat } from "node:fs/promises";
 import { basename, extname, isAbsolute, resolve, sep } from "node:path";
 import type { HubfluencerClient } from "./client.js";
-import { assertSafeFetchUrl } from "./core.js";
+import {
+	assertSafeFetchUrl,
+	backoffDelayMs,
+	DEFAULT_RETRY,
+	isRetryableNetworkError,
+} from "./core.js";
+import { USER_AGENT } from "./version.js";
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Progress sink for the upload phase, bound by the caller to the MCP progress
+ * helper. Lives as a plain callback (not the SDK's `reportProgress`) so uploads.ts
+ * stays free of the index.ts dependency — index.ts boots a live stdio server at
+ * module load. Best-effort: index.ts's reportProgress already swallows its own
+ * failures, so this never needs to.
+ */
+export type UploadProgress = (
+	completed: number,
+	total: number,
+	message: string,
+) => Promise<void> | void;
+
+// How many extra attempts a single multipart part gets after its first PUT
+// fails: the part URL is re-signed before each retry (the old presign may have
+// expired, or the failure may be specific to that signed URL). 2 retries = 3
+// total PUT attempts per part, mirroring DEFAULT_RETRY.attempts for GETs. A part
+// PUT is idempotent (same bytes, same object/part), so re-uploading it is safe.
+const PART_RETRIES = 2;
 
 // Server-returned presign/download URLs are normally on R2/S3 over https. Allow
 // loopback http only when the API base itself is local (dev MinIO/localstack),
@@ -29,9 +58,10 @@ const ALLOW_LOOPBACK_FETCH =
 // Mirror the server-side constants (editor_upload.ex / editor_asset_controller.ex)
 // so we fail fast client-side with a clear message instead of after a wasted PUT.
 const MAX_VIDEO_BYTES = 500_000_000; // EditorUpload.@max_upload_bytes
-const MAX_IMAGE_BYTES = 20 * 1024 * 1024; // editor_asset @max_image_size
-const MAX_LOGO_BYTES = 20 * 1024 * 1024; // logos go through the image inspector too
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024; // editor_asset @max_image_size (logos share this inspector)
 const MULTIPART_THRESHOLD = 50 * 1024 * 1024; // @multipart_min_size — at/above this, use multipart
+const MAX_CATALOG_VIDEO_DURATION_SECONDS = 60; // CatalogAsset video validator
+type FilePutBody = { filePath: string; size: number };
 
 const VIDEO_EXT_MIME: Record<string, string> = {
 	mp4: "video/mp4",
@@ -51,6 +81,22 @@ const IMAGE_EXT_MIME: Record<string, string> = {
 export const VIDEO_EXTS = Object.keys(VIDEO_EXT_MIME);
 export const IMAGE_EXTS = Object.keys(IMAGE_EXT_MIME);
 
+// The reusable ASSET CATALOG (catalog_asset.ex) accepts BOTH images and videos:
+// image/jpeg,image/png (≤20 MiB) + video/mp4,quicktime,webm,x-matroska (≤500 MB).
+// One combined ext→mime map so a single upload primitive covers the catalog; the
+// per-type byte cap is resolved by `catalogMaxBytes` below, mirroring
+// CatalogAsset.max_upload_bytes/1 so we fail fast client-side.
+const CATALOG_EXT_MIME: Record<string, string> = {
+	...IMAGE_EXT_MIME,
+	...VIDEO_EXT_MIME,
+};
+export const CATALOG_ASSET_EXTS = Object.keys(CATALOG_EXT_MIME);
+
+/** The catalog byte cap for a resolved mime — 20 MiB for images, 500 MB for video. */
+function catalogMaxBytes(mime: string): number {
+	return mime.startsWith("video/") ? MAX_VIDEO_BYTES : MAX_IMAGE_BYTES;
+}
+
 export interface ResolvedFile {
 	path: string;
 	ext: string;
@@ -95,6 +141,27 @@ export function planMultipartParts(
 	return parts;
 }
 
+/**
+ * Guards a multipart part read: `fh.read` can return fewer bytes than requested
+ * (the file shrank/was truncated under us, or the plan disagrees with the file's
+ * real size). A short read would leave the tail of the part buffer zero-filled
+ * and upload a silently-corrupt part (the confirm still succeeds — the asset is
+ * garbage), so fail loudly instead. Pure + total so the check is unit-testable
+ * without the filesystem or the network, like `planMultipartParts`.
+ */
+export function assertFullRead(
+	bytesRead: number,
+	len: number,
+	partNumber: number,
+	offset: number,
+): void {
+	if (bytesRead !== len) {
+		throw new Error(
+			`Short read on part ${partNumber}: got ${bytesRead} of ${len} bytes at offset ${offset} (file changed under us?).`,
+		);
+	}
+}
+
 /**
  * Confines a model-supplied read path to an allowlisted input base and an
  * extension allowlist, then stats it. Base = HUBFLUENCER_INPUT_DIR if set, else
@@ -146,49 +213,87 @@ export async function resolveReadPath(
 	return { path: target, ext, mime, size };
 }
 
+/**
+ * Validates a model-supplied video read path with the SAME ext allowlist + size
+ * cap `uploadVideoFile` will use, without leaking the underlying constants. Lets
+ * a caller fail fast on an invalid path BEFORE a side effect (e.g. creating a
+ * draft project) instead of orphaning it when `uploadVideoFile` later rejects.
+ */
+export async function resolveVideoReadPath(
+	filePath: string,
+): Promise<ResolvedFile> {
+	return resolveReadPath(filePath, VIDEO_EXT_MIME, MAX_VIDEO_BYTES);
+}
+
 /**
  * PUTs bytes to a presigned S3/R2 URL. `contentType` is sent ONLY when the URL
  * signed it (single-object presign does — see S3Client.presign_put's
  * query_params; multipart part presign does NOT, so callers omit it there to
- * avoid sending an unsigned header). Returns the object/part ETag from the
- * response (needed to complete a multipart upload).
+ * avoid sending an unsigned header). `contentLength` is supplied for file streams
+ * so large catalog uploads use a file-backed body without relying on chunked
+ * transfer. Returns the object/part ETag from the response (needed to complete a
+ * multipart upload).
  */
 export async function putToPresignedUrl(
 	url: string,
-	body: Buffer,
+	body: Buffer | FilePutBody,
 	contentType: string | undefined,
 	timeoutMs = 300_000,
+	contentLength?: number,
 ): Promise<string | undefined> {
 	// The presigned URL comes back in API JSON — refuse to PUT bytes to an
 	// insecure or private/internal host (SSRF / cleartext exfil of file bytes).
 	assertSafeFetchUrl(url, { allowLoopback: ALLOW_LOOPBACK_FETCH });
-	const headers: Record<string, string> = {};
+	// user-agent is not part of the presigned SignedHeaders, so S3/R2 ignores it
+	// for signature purposes — safe to send on both single-object and part PUTs.
+	const headers: Record<string, string> = { "user-agent": USER_AGENT };
 	if (contentType) headers["content-type"] = contentType;
-	// Pass an exact ArrayBuffer slice — the generic Uint8Array<ArrayBufferLike>
-	// type doesn't resolve cleanly against fetch's BodyInit union, but a plain
-	// ArrayBuffer is unambiguous (and this is a one-time copy of a bounded chunk).
-	const ab = body.buffer.slice(
-		body.byteOffset,
-		body.byteOffset + body.byteLength,
-	) as ArrayBuffer;
-	let resp: Response;
-	try {
-		resp = await fetch(url, {
+	let fetchBody: BodyInit;
+	let fetchInit: RequestInit & { duplex?: "half" };
+	let stream: ReadStream | undefined;
+	if (Buffer.isBuffer(body)) {
+		// Pass an exact ArrayBuffer slice — the generic Uint8Array<ArrayBufferLike>
+		// type doesn't resolve cleanly against fetch's BodyInit union, but a plain
+		// ArrayBuffer is unambiguous (and this is a one-time copy of a bounded chunk).
+		fetchBody = body.buffer.slice(
+			body.byteOffset,
+			body.byteOffset + body.byteLength,
+		) as ArrayBuffer;
+		fetchInit = { method: "PUT", headers, body: fetchBody };
+	} else {
+		stream = createReadStream(body.filePath);
+		headers["content-length"] = String(contentLength ?? body.size);
+		fetchInit = {
 			method: "PUT",
 			headers,
-			body: ab,
-			signal: AbortSignal.timeout(timeoutMs),
-		});
+			body: stream as unknown as BodyInit,
+			duplex: "half",
+		};
+	}
+	fetchInit.signal = AbortSignal.timeout(timeoutMs);
+	let resp: Response;
+	try {
+		resp = await fetch(url, fetchInit);
 	} catch (e) {
+		stream?.destroy();
+		// A connection-level blip or timeout on a PUT is transient — re-wrap it with
+		// the `retryable` marker so a caller (uploadPartWithRetry) can re-sign and
+		// retry the part. The friendly message would otherwise erase the original
+		// error name isRetryableNetworkError keys on.
 		if (
 			e instanceof Error &&
 			(e.name === "TimeoutError" || e.name === "AbortError")
 		) {
-			throw new Error(`Upload PUT timed out after ${timeoutMs / 1000}s.`);
+			throw markRetryable(`Upload PUT timed out after ${timeoutMs / 1000}s.`);
 		}
-		throw e instanceof Error ? new Error(`Upload PUT failed: ${e.message}`) : e;
+		throw e instanceof Error
+			? markRetryable(`Upload PUT failed: ${e.message}`)
+			: e;
 	}
 	if (!resp.ok) {
+		// An HTTP-status rejection from S3 (bad/expired signature, 4xx) is NOT
+		// marked retryable — re-uploading the same bytes would just be rejected the
+		// same way. Only the transient connection failures above are retried.
 		const text = await resp.text().catch(() => "");
 		throw new Error(
 			`Upload PUT rejected (HTTP ${resp.status})${text ? `: ${text.slice(0, 200)}` : ""}.`,
@@ -197,6 +302,11 @@ export async function putToPresignedUrl(
 	return resp.headers.get("etag") ?? undefined;
 }
 
+/** An Error carrying the `retryable` marker isRetryableNetworkError honours. */
+function markRetryable(message: string): Error {
+	return Object.assign(new Error(message), { retryable: true });
+}
+
 interface PresignVideoResponse {
 	data: { upload_id: number | string; presigned_url: string; s3_key: string };
 }
@@ -232,7 +342,11 @@ export async function uploadVideoFile(
 	client: HubfluencerClient,
 	slug: string,
 	filePath: string,
-	opts: { fitMode?: string; productDescription?: string } = {},
+	opts: {
+		fitMode?: string;
+		productDescription?: string;
+		onProgress?: UploadProgress;
+	} = {},
 ): Promise<UploadedVideo> {
 	const file = await resolveReadPath(filePath, VIDEO_EXT_MIME, MAX_VIDEO_BYTES);
 	const filename = basename(file.path);
@@ -240,11 +354,17 @@ export async function uploadVideoFile(
 	const product_description = opts.productDescription;
 
 	if (file.size >= MULTIPART_THRESHOLD) {
-		return uploadVideoMultipart(client, slug, file, {
-			filename,
-			fit_mode,
-			product_description,
-		});
+		return uploadVideoMultipart(
+			client,
+			slug,
+			file,
+			{
+				filename,
+				fit_mode,
+				product_description,
+			},
+			opts.onProgress,
+		);
 	}
 
 	const presign = await client.post<PresignVideoResponse>(
@@ -259,20 +379,73 @@ export async function uploadVideoFile(
 	);
 	const { upload_id, presigned_url } = presign.data;
 	const buf = await readFile(file.path);
+	// A small file is one PUT — report it as a single 1-of-1 step so the caller
+	// still gets a progress beat during the transfer.
+	await opts.onProgress?.(0, 1, `uploading ${filename}`);
 	// Content-Type MUST equal the presigned mime exactly — confirm HEADs the
 	// object and 422s on mismatch (editor/uploads.ex).
 	await putToPresignedUrl(presigned_url, buf, file.mime);
+	await opts.onProgress?.(1, 1, `uploaded ${filename}, confirming`);
 	const confirmed = await client.post<ConfirmUploadResponse>(
 		`/editor/${slug}/uploads/${upload_id}/confirm`,
 	);
 	return { upload_id, status: confirmed.data?.status ?? "processing" };
 }
 
+/**
+ * PUTs one multipart part, re-signing the part URL before each retry. A part PUT
+ * is idempotent (same bytes → same object part), so a transient network failure
+ * or an expired presign is safe to retry: we ask the server for a FRESH signed
+ * URL each attempt (the previous one may have timed out) and re-PUT. After the
+ * final attempt the error propagates so the caller aborts the whole upload.
+ * Returns the part's ETag (needed to complete the multipart upload).
+ */
+async function uploadPartWithRetry(
+	client: HubfluencerClient,
+	slug: string,
+	ids: { upload_id: number | string; s3_upload_id: string },
+	part_number: number,
+	chunk: Buffer,
+): Promise<string> {
+	for (let attempt = 1; ; attempt++) {
+		try {
+			const sign = await client.post<SignPartResponse>(
+				`/editor/${slug}/uploads/multipart/sign-part`,
+				{
+					upload_id: ids.upload_id,
+					s3_upload_id: ids.s3_upload_id,
+					part_number,
+				},
+			);
+			// No content-type here — the part presign does not sign one.
+			const etag = await putToPresignedUrl(
+				sign.data.presigned_url,
+				chunk,
+				undefined,
+			);
+			if (!etag) {
+				throw new Error(`Part ${part_number} returned no ETag from S3.`);
+			}
+			return etag;
+		} catch (e) {
+			// Retry only a transient network/timeout failure, and only while attempts
+			// remain. A definite rejection (e.g. a 4xx from S3, or a sign-part error
+			// the client already classified as non-retryable) propagates immediately.
+			if (attempt <= PART_RETRIES && isRetryableNetworkError(e)) {
+				await sleep(backoffDelayMs(attempt, DEFAULT_RETRY));
+				continue;
+			}
+			throw e;
+		}
+	}
+}
+
 async function uploadVideoMultipart(
 	client: HubfluencerClient,
 	slug: string,
 	file: ResolvedFile,
 	meta: { filename: string; fit_mode?: string; product_description?: string },
+	onProgress?: UploadProgress,
 ): Promise<UploadedVideo> {
 	const init = await client.post<MultipartInitResponse>(
 		`/editor/${slug}/uploads/multipart/init`,
@@ -294,26 +467,35 @@ async function uploadVideoMultipart(
 			`Multipart plan mismatch: server expects ${parts_count} parts, computed ${plan.length} for ${file.size} bytes at ${part_size}/part.`,
 		);
 	}
+	await onProgress?.(
+		0,
+		plan.length,
+		`uploading ${meta.filename} in ${plan.length} parts`,
+	);
 	const fh = await open(file.path, "r");
 	const parts: Array<{ part_number: number; etag: string }> = [];
 	try {
 		for (const { part_number, offset, len } of plan) {
 			const chunk = Buffer.alloc(len);
-			await fh.read(chunk, 0, len, offset);
-			const sign = await client.post<SignPartResponse>(
-				`/editor/${slug}/uploads/multipart/sign-part`,
-				{ upload_id, s3_upload_id, part_number },
-			);
-			// No content-type here — the part presign does not sign one.
-			const etag = await putToPresignedUrl(
-				sign.data.presigned_url,
+			// Verify the read filled the whole part — a short read would upload a
+			// zero-padded, silently-corrupt part (see assertFullRead).
+			const { bytesRead } = await fh.read(chunk, 0, len, offset);
+			assertFullRead(bytesRead, len, part_number, offset);
+			const etag = await uploadPartWithRetry(
+				client,
+				slug,
+				{ upload_id, s3_upload_id },
+				part_number,
 				chunk,
-				undefined,
 			);
-			if (!etag) {
-				throw new Error(`Part ${part_number} returned no ETag from S3.`);
-			}
 			parts.push({ part_number, etag });
+			// Report after each part lands, so a long large-file upload shows steady
+			// forward progress (N of M parts) rather than a single silent stall.
+			await onProgress?.(
+				part_number,
+				plan.length,
+				`uploaded part ${part_number}/${plan.length}`,
+			);
 		}
 		const done = await client.post<ConfirmUploadResponse>(
 			`/editor/${slug}/uploads/multipart/complete`,
@@ -390,5 +572,116 @@ export async function uploadShortPoster(
 	return { s3_key };
 }
 
-export const LOGO_MAX_BYTES = MAX_LOGO_BYTES;
-export const IMAGE_MAX_BYTES = MAX_IMAGE_BYTES;
+interface CatalogPresignResponse {
+	data: {
+		asset_id: number | string;
+		presigned_url: string;
+		s3_key: string;
+		expires_in_seconds?: number;
+	};
+}
+
+export interface UploadedCatalogAsset {
+	asset_id: number | string;
+	status: string;
+	media_type: string;
+	mime_type: string;
+	filename: string;
+	size_bytes: number;
+}
+
+/**
+ * Uploads a local file to the reusable ASSET CATALOG (catalog_asset.ex) and
+ * confirms it: presign (`POST /assets/presign`) → PUT the bytes to the signed
+ * URL → confirm (`POST /assets/:id/confirm`). Reuses the same path-confinement +
+ * SSRF-safe PUT primitives as the editor uploads (`resolveReadPath`,
+ * `putToPresignedUrl`); the ONLY difference from the editor asset flow is the
+ * envelope shape (asset_id + a separate `/assets/:id/confirm`).
+ *
+ * The catalog presign signs the content-type (S3Client.presign_put content_type),
+ * so — unlike a multipart part — the PUT MUST send it; the confirm HEADs the
+ * object and 422s on a mismatch. For a VIDEO the confirm needs a
+ * `duration_seconds` (the server rejects a video with no/over-long duration,
+ * `:invalid_video_duration`); the caller passes it through `opts`. Returns the
+ * confirmed asset's id + status + media/mime so the tool can report it.
+ */
+export async function uploadCatalogAsset(
+	client: HubfluencerClient,
+	filePath: string,
+	opts: {
+		description?: string;
+		width?: number;
+		height?: number;
+		durationSeconds?: number;
+	} = {},
+): Promise<UploadedCatalogAsset> {
+	// Resolve against the larger (video) ceiling first so a valid image/video
+	// path passes the confinement + extension check, then enforce the true
+	// per-type cap (images are capped lower) with a precise message.
+	const file = await resolveReadPath(
+		filePath,
+		CATALOG_EXT_MIME,
+		MAX_VIDEO_BYTES,
+	);
+	const cap = catalogMaxBytes(file.mime);
+	if (file.size > cap) {
+		throw new Error(
+			`${file.path} is ${file.size} bytes — over the ${cap}-byte cap for ${file.mime} catalog uploads.`,
+		);
+	}
+	if (file.mime.startsWith("video/")) {
+		const duration = opts.durationSeconds;
+		if (
+			typeof duration !== "number" ||
+			!Number.isFinite(duration) ||
+			duration <= 0 ||
+			duration > MAX_CATALOG_VIDEO_DURATION_SECONDS
+		) {
+			throw new Error(
+				`Catalog video uploads require durationSeconds to be greater than 0 and no more than ${MAX_CATALOG_VIDEO_DURATION_SECONDS} seconds.`,
+			);
+		}
+	}
+	const filename = basename(file.path);
+	const presign = await client.post<CatalogPresignResponse>("/assets/presign", {
+		filename,
+		mime_type: file.mime,
+		size_bytes: file.size,
+	});
+	const { asset_id, presigned_url } = presign.data;
+	// Content-Type MUST equal the presigned mime exactly — the catalog presign
+	// signs it and confirm HEADs the object, 422ing on mismatch.
+	if (file.size >= MULTIPART_THRESHOLD) {
+		await putToPresignedUrl(
+			presigned_url,
+			{ filePath: file.path, size: file.size },
+			file.mime,
+			300_000,
+			file.size,
+		);
+	} else {
+		const buf = await readFile(file.path);
+		await putToPresignedUrl(presigned_url, buf, file.mime);
+	}
+	const confirmBody: Record<string, unknown> = {};
+	if (typeof opts.description === "string" && opts.description.trim() !== "")
+		confirmBody.description = opts.description;
+	if (typeof opts.width === "number") confirmBody.width = opts.width;
+	if (typeof opts.height === "number") confirmBody.height = opts.height;
+	if (typeof opts.durationSeconds === "number")
+		confirmBody.duration_seconds = opts.durationSeconds;
+	const confirmed = await client.post<{ data: Record<string, unknown> }>(
+		`/assets/${asset_id}/confirm`,
+		confirmBody,
+	);
+	const data = confirmed.data ?? {};
+	return {
+		asset_id,
+		status: typeof data.status === "string" ? data.status : "ready",
+		media_type: typeof data.media_type === "string" ? data.media_type : "",
+		mime_type: typeof data.mime_type === "string" ? data.mime_type : file.mime,
+		filename: typeof data.filename === "string" ? data.filename : filename,
+		size_bytes:
+			typeof data.size_bytes === "number" ? data.size_bytes : file.size,
+	};
+}

package/src/version.ts

@@ -0,0 +1,18 @@
+/**
+ * Single source of truth for the package version.
+ *
+ * Imported from package.json so the version is declared in exactly one place —
+ * the McpServer handshake, the outbound `User-Agent`, and the published package
+ * can never drift apart. `bun build --target node` inlines this JSON into the
+ * single-file bundle (no runtime file read), and `tsc` resolves it via
+ * `resolveJsonModule`. A plain default import (no `with { type: "json" }`
+ * attribute) is used deliberately: import attributes require `module: nodenext`,
+ * but this package targets `Node16`.
+ */
+
+import pkg from "../package.json";
+
+export const VERSION: string = pkg.version;
+
+/** The `User-Agent` sent on every outbound HTTP request (API + S3 + download). */
+export const USER_AGENT = `hubfluencer-mcp/${VERSION}`;