@yswgaicx/yswg-img-cli 0.1.0 → 0.1.3

package/README.md

@@ -32,13 +32,33 @@ The token is saved to `~/.yswg-img-cli/config.json`.
 
 ## Generate
 
+Supported Monkey Genius options mirrored by the CLI:
+
+- Model/group selection: `--group-id`, `--model`
+- Aspect ratio: `--ratio 1:1|3:2|2:3|4:3|3:4|16:9|9:16|5:4|4:5|21:9`
+- Single/double image output: `--count 1` or `--count 2` when the selected model supports it
+- Reference images: `--ref ./a.png,https://example.com/b.jpg`
+- Night/off-peak queue submission: `--night`
+- AI tool/template payloads: `--template-code`, `--template-vars-json`
+- Generation history lookup and timeout recovery: `tasks search`, `tasks recover`
+- History tabs/search/delete/night-cancel: `tasks search --tab ...`, `tasks delete`, `tasks cancel-night`
+
+Local reference images are compressed before OSS upload by default, matching the
+Monkey Genius frontend behavior:
+
+- Images below 50 KB are kept as-is.
+- Images are resized to fit within 1280 x 1280.
+- Opaque images are converted to JPEG at quality 0.82, then stepped down toward
+  0.5 until they are near 300 KB.
+- Images with transparency are kept as PNG.
+
+Use `--no-compress` only when the original file must be uploaded unchanged.
+
 Dry-run the backend payload:
 
 ```bash
 yswg-img generate \
   --prompt "一张白底产品图，柔和自然光，高级电商摄影" \
-  --group-id 5 \
-  --model gemini-2.5-flash-image \
   --ratio 1:1 \
   --count 1 \
   --dry-run \
@@ -50,8 +70,6 @@ Submit and wait for output images:
 ```bash
 yswg-img generate \
   --prompt "一张白底产品图，柔和自然光，高级电商摄影" \
-  --group-id 5 \
-  --model gemini-2.5-flash-image \
   --ratio 1:1 \
   --count 1 \
   --out outputs \
@@ -63,16 +81,70 @@ Use reference images:
 ```bash
 yswg-img generate \
   --prompt "参考产品主体，生成室内生活方式场景图" \
-  --group-id 5 \
   --ref ./product.png,https://example.com/ref.jpg \
   --out outputs \
   --json
 ```
 
+Use an AI tool/template payload:
+
+```bash
+yswg-img generate \
+  --group-id 6 \
+  --template-code tool_code \
+  --template-vars-json '{"color":"red"}' \
+  --display-prompt "AI 工具生成" \
+  --dry-run \
+  --json
+```
+
 Submit only and return task IDs:
 
 ```bash
-yswg-img generate --prompt "..." --group-id 5 --no-wait --json
+yswg-img generate --prompt "..." --no-wait --json
+```
+
+If a long generation times out or the WebSocket disconnects, the CLI now checks
+generation history for the returned invoke task IDs before failing. This avoids
+submitting the same prompt again when the image was already produced.
+
+Tune the wait timeout:
+
+```bash
+yswg-img generate --prompt "..." --timeout 900 --json
+```
+
+Query recent task history without creating a new generation task:
+
+```bash
+yswg-img tasks search --size 10 --keyword "兔子" --tab all --json
+```
+
+The CLI intentionally only queries the latest 10 records. If you need older
+records, open the navigation site and query them in the Monkey Genius page.
+
+Available history tabs: `all`, `expiring1d`, `expiring2d`, `nightQueue`.
+
+Fetch a history record by record ID:
+
+```bash
+yswg-img tasks get --id 2064983569742958594 --json
+```
+
+Recover/download completed images by invoke task ID after a timeout:
+
+```bash
+yswg-img tasks recover \
+  --task-id 2065019349651689473 \
+  --out outputs/recovered \
+  --json
+```
+
+Delete a history record or cancel an off-peak queued task:
+
+```bash
+yswg-img tasks delete --id <record-id> --json
+yswg-img tasks cancel-night --id <record-id> --json
 ```
 
 ## Configuration
@@ -86,3 +158,5 @@ Flags override environment variables, which override the saved config.
 - `YSWG_WS_PATH`
 
 Default app ID: `2014153035982319618`.
+Default ratio: `1:1`.
+Default generation model: `gemini-3.1-flash-image-preview` (`groupId=6`, 三代).

package/bin/yswg-img.js

@@ -2,7 +2,22 @@
 import { parseArgs, readFlag, splitCsv } from "../src/args.js";
 import { loadConfig, normalizeEmail, resolveConfig, saveConfig, DEFAULT_CONFIG_PATH } from "../src/config.js";
 import { YswgApi } from "../src/api.js";
-import { buildGeneratePayload, downloadImages, extractImageUrls, uploadReferences, waitForTask } from "../src/generate.js";
+import {
+  buildGeneratePayload,
+  DEFAULT_GENERATE_OPTIONS,
+  downloadImages,
+  extractImageUrls,
+  findModelByGroupId,
+  findRecordsByInvokeTaskIds,
+  isTimeoutLikeError,
+  normalizeHistoryLimit,
+  normalizeTaskSearchParams,
+  parseTemplateInput,
+  taskImageUrlsFromRecord,
+  uploadReferences,
+  validateGenerateOptions,
+  waitForTask,
+} from "../src/generate.js";
 
 function printHelp() {
   console.log(`yswg-img
@@ -11,7 +26,13 @@ Commands:
   auth send-code --email <name|email>
   auth login --email <name|email> --code <6 digits>
   models [--app-id <id>]
-  generate --prompt <text> --group-id <id> [--model <name>] [--ratio 1:1] [--count 1] [--ref a.png,b.jpg] [--out outputs]
+  templates [--app-id <id>] [--json]
+  tasks search [--size 10] [--keyword <text>] [--tab all|expiring1d|expiring2d|nightQueue] [--json]
+  tasks get --id <record-id> [--json]
+  tasks recover --task-id <invoke-task-id>[,<id>] [--out outputs] [--json]
+  tasks delete --id <record-id> [--json]
+  tasks cancel-night --id <record-id> [--json]
+  generate --prompt <text> [--group-id 6] [--model gemini-3.1-flash-image-preview] [--ratio 1:1] [--count 1] [--ref a.png,b.jpg] [--template-code <code>] [--template-vars-json '{}'] [--no-compress] [--out outputs]
 
 Environment:
   YSWG_TOKEN, YSWG_REFRESH_TOKEN, YSWG_APP_ID, YSWG_BASE_URL, YSWG_WS_PATH
@@ -72,21 +93,107 @@ async function main() {
     return;
   }
 
+  if (command === "templates") {
+    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
+    const templates = await api.templates(String(readFlag(flags, ["appId"], resolved.appId)));
+    output(templates, json);
+    return;
+  }
+
+  if (command === "tasks" && subcommand === "search") {
+    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
+    const result = await api.searchGenTasks(normalizeTaskSearchParams({
+      tab: String(readFlag(flags, ["tab"], "all")),
+      keyword: String(readFlag(flags, ["keyword", "q"], "")),
+      userId: config.user?.userId || config.user?.id,
+      appId: String(readFlag(flags, ["appId"], resolved.appId)),
+      size: readFlag(flags, ["size"], 10),
+    }));
+    output(result, json);
+    return;
+  }
+
+  if (command === "tasks" && subcommand === "get") {
+    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
+    const id = String(readFlag(flags, ["id"], "")).trim();
+    if (!id) throw new Error("missing --id");
+    const record = await api.genTask(id);
+    output(record, json);
+    return;
+  }
+
+  if (command === "tasks" && subcommand === "delete") {
+    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
+    const id = String(readFlag(flags, ["id"], "")).trim();
+    if (!id) throw new Error("missing --id");
+    await api.deleteGenTask(id);
+    output({ ok: true, id }, json);
+    return;
+  }
+
+  if (command === "tasks" && subcommand === "cancel-night") {
+    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
+    const id = String(readFlag(flags, ["id"], "")).trim();
+    if (!id) throw new Error("missing --id");
+    await api.cancelNightTask(id);
+    output({ ok: true, id }, json);
+    return;
+  }
+
+  if (command === "tasks" && subcommand === "recover") {
+    if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
+    const taskIds = splitCsv(readFlag(flags, ["taskId", "taskIds", "id"], ""));
+    if (!taskIds.length) throw new Error("missing --task-id");
+    const records = await findRecordsByInvokeTaskIds(api, {
+      taskIds,
+      appId: String(readFlag(flags, ["appId"], resolved.appId)),
+      userId: config.user?.userId || config.user?.id,
+      pageSize: normalizeHistoryLimit(readFlag(flags, ["size"], 10)),
+      maxPages: 1,
+    });
+    const imageUrls = records.flatMap((record) => taskImageUrlsFromRecord(record));
+    if (!imageUrls.length) throw new Error("最近 10 条生成记录里还没有找到该任务结果；如果需要查看更多，请去导航站「天才猴子」页面查询。");
+    const files = flags.out === "none" ? [] : await downloadImages(imageUrls, String(readFlag(flags, ["out"], "outputs")));
+    output({ ok: true, taskIds, recordIds: records.map((record) => record.id), imageUrls, files }, json);
+    return;
+  }
+
   if (command === "generate") {
     if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
     const prompt = String(readFlag(flags, ["prompt", "p"], "")).trim();
     const refs = splitCsv(readFlag(flags, ["ref", "refs"], ""));
-    const refImages = await uploadReferences(api, refs);
+    const refImages = await uploadReferences(api, refs, { compress: !flags.noCompress });
+    const groupId = String(readFlag(flags, ["groupId", "group"], DEFAULT_GENERATE_OPTIONS.groupId));
+    const model = String(readFlag(flags, ["model", "m"], DEFAULT_GENERATE_OPTIONS.model));
+    const ratio = String(readFlag(flags, ["ratio", "r"], DEFAULT_GENERATE_OPTIONS.ratio));
+    const imageCount = Number(readFlag(flags, ["count", "imageCount"], DEFAULT_GENERATE_OPTIONS.imageCount));
+    const templateInput = parseTemplateInput({
+      code: String(readFlag(flags, ["templateCode", "template"], "")),
+      varsJson: String(readFlag(flags, ["templateVarsJson", "varsJson"], "")),
+      displayPrompt: String(readFlag(flags, ["displayPrompt"], "")),
+    });
+
+    if (!flags.skipValidate) {
+      const modelGroups = await api.models(resolved.appId);
+      validateGenerateOptions({
+        model: findModelByGroupId(modelGroups, groupId),
+        ratio,
+        imageCount,
+      });
+    }
+
     const payload = buildGeneratePayload({
       appId: resolved.appId,
-      groupId: String(readFlag(flags, ["groupId", "group"], "")),
+      groupId,
       prompt,
-      model: String(readFlag(flags, ["model", "m"], "gemini-2.5-flash-image")),
-      ratio: String(readFlag(flags, ["ratio", "r"], "1:1")),
-      imageCount: Number(readFlag(flags, ["count", "imageCount"], 1)),
+      model,
+      ratio,
+      imageCount,
       refImages,
       size: String(readFlag(flags, ["size"], "")),
       night: Boolean(flags.night),
+      templates: templateInput.templates,
+      displayPrompt: templateInput.displayPrompt,
     });
 
     if (flags.dryRun) {
@@ -104,14 +211,39 @@ async function main() {
     }
 
     const timeoutMs = Number(readFlag(flags, ["timeoutMs"], Number(readFlag(flags, ["timeout"], 3600)) * 1000));
-    const messages = await Promise.all(ids.map((taskId) => waitForTask({
-      baseUrl: resolved.baseUrl,
-      token: resolved.token,
-      wsPath: resolved.wsPath,
-      taskId,
-      timeoutMs,
-    })));
-    const imageUrls = messages.flatMap((message) => extractImageUrls(message.responseJson));
+    let imageUrls = [];
+    let waitError;
+    try {
+      const messages = await Promise.all(ids.map((taskId) => waitForTask({
+        baseUrl: resolved.baseUrl,
+        token: resolved.token,
+        wsPath: resolved.wsPath,
+        taskId,
+        timeoutMs,
+      })));
+      imageUrls = messages.flatMap((message) => extractImageUrls(message.responseJson));
+    } catch (error) {
+      if (!isTimeoutLikeError(error)) throw error;
+      waitError = error;
+    }
+
+    if (!imageUrls.length) {
+      const records = await findRecordsByInvokeTaskIds(api, {
+        taskIds: ids,
+        appId: resolved.appId,
+        userId: config.user?.userId || config.user?.id,
+        pageSize: 10,
+        maxPages: 1,
+      });
+      imageUrls = records.flatMap((record) => taskImageUrlsFromRecord(record));
+    }
+
+    if (!imageUrls.length && waitError) {
+      const error = new Error(`${waitError.message}; 最近 10 条生成记录里还没有找到该任务结果。请稍后用 tasks recover --task-id <id> 查询；如果需要查看更多，请去导航站「天才猴子」页面查询，避免重复提交同一任务。`);
+      error.cause = waitError;
+      throw error;
+    }
+
     const files = flags.out === "none" ? [] : await downloadImages(imageUrls, String(readFlag(flags, ["out"], "outputs")));
     output({ ok: true, taskIds: ids, imageUrls, files }, json);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yswgaicx/yswg-img-cli",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "CLI wrapper for YSWG Monkey Genius image generation.",
   "type": "module",
   "bin": {
@@ -21,5 +21,8 @@
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "sharp": "^0.35.0"
   }
 }

package/src/api.js

@@ -69,6 +69,29 @@ export class YswgApi {
     return this.request("/web/ai/invoke/tasks", { method: "POST", data: payload });
   }
 
+  searchGenTasks(params) {
+    return this.request("/web/ai-gen-tasks/search", { method: "POST", data: params });
+  }
+
+  genTask(id) {
+    return this.request(`/web/ai-gen-tasks/${id}`);
+  }
+
+  deleteGenTask(id) {
+    return this.request(`/web/ai-gen-tasks/${id}`, { method: "DELETE" });
+  }
+
+  cancelNightTask(id) {
+    return this.request(`/web/ai-gen-tasks/${id}/night-cancel`, { method: "DELETE" });
+  }
+
+  invokeTextService(serviceId, text) {
+    return this.request(`/web/ai/services/invoke/${serviceId}`, {
+      method: "POST",
+      data: { params: { text } },
+    });
+  }
+
   ossToken(scene = "ai_invoke") {
     return this.request("/web/oss-tokens", { params: { scene } });
   }

package/src/generate.js

@@ -1,5 +1,13 @@
 import { basename } from "node:path";
 import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { compressImageBuffer } from "./image-compress.js";
+
+export const DEFAULT_GENERATE_OPTIONS = {
+  groupId: "6",
+  model: "gemini-3.1-flash-image-preview",
+  ratio: "1:1",
+  imageCount: 1,
+};
 
 export function buildGeneratePayload({
   appId,
@@ -50,16 +58,190 @@ export function extractImageUrls(responseJson) {
   return [];
 }
 
-export async function uploadReferences(api, refs) {
+export function unique(items) {
+  return Array.from(new Set(items.filter(Boolean)));
+}
+
+export function taskImageUrlsFromRecord(record) {
+  const outputUrls = Array.isArray(record?.outPutFile)
+    ? record.outPutFile
+    : typeof record?.outPutFile === "string"
+      ? record.outPutFile.split(",").map((item) => item.trim())
+      : [];
+  const invokeUrls = (record?.invokeTasks || [])
+    .filter((task) => Number(task.status) === 2)
+    .flatMap((task) => {
+      try {
+        return extractImageUrls(task.responseJson);
+      } catch {
+        return [];
+      }
+    });
+  return unique([...outputUrls, ...invokeUrls]);
+}
+
+export const HISTORY_LIMIT_MESSAGE = "CLI 一次最多只能查询最近 10 条生成记录；如果需要查看更多，请去导航站「天才猴子」页面查询。";
+
+export function normalizeHistoryLimit(value, fallback = 10) {
+  const size = Number(value ?? fallback);
+  if (!Number.isFinite(size) || size < 1) return fallback;
+  if (size > 10) throw new Error(HISTORY_LIMIT_MESSAGE);
+  return Math.floor(size);
+}
+
+function formatDateTime(date) {
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+export function normalizeTaskSearchParams({
+  tab = "all",
+  keyword = "",
+  userId,
+  appId,
+  size = 10,
+  now = new Date(),
+} = {}) {
+  const params = {
+    current: 1,
+    size: normalizeHistoryLimit(size),
+    userId,
+    appId,
+    keyword: keyword.trim() || undefined,
+    includeFailedRecords: true,
+  };
+
+  if (tab === "nightQueue") {
+    params.status = 3;
+  } else if (tab === "expiring1d" || tab === "expiring2d") {
+    const startOffset = tab === "expiring2d" ? 24 * 60 * 60 * 1000 : 0;
+    const endOffset = tab === "expiring2d" ? 2 * 24 * 60 * 60 * 1000 : 24 * 60 * 60 * 1000;
+    params.expireTimeStart = formatDateTime(new Date(now.getTime() + startOffset));
+    params.expireTimeEnd = formatDateTime(new Date(now.getTime() + endOffset));
+  }
+
+  return params;
+}
+
+export function findModelByGroupId(modelGroups, groupId) {
+  const groups = Array.isArray(modelGroups) ? modelGroups : [];
+  for (const group of groups) {
+    const models = Array.isArray(group?.models) ? group.models : [];
+    for (const model of models) {
+      if (String(model.groupId || model.value || "") === String(groupId)) {
+        return { ...model, group: group.typeCode || model.group };
+      }
+    }
+  }
+  return null;
+}
+
+export function unsupportedRatiosForModel(model) {
+  const modelName = model?.modelName || "";
+  const label = model?.label || "";
+  const dreamRatios = ["4:5", "5:4", "4:1", "1:4", "8:1", "1:8"];
+  const defaultRatios = ["4:1", "1:4", "8:1", "1:8"];
+  if (label.includes("三代")) return [];
+  if (modelName === "seedream-5.0") return dreamRatios;
+  return defaultRatios;
+}
+
+export function validateGenerateOptions({ model, ratio, imageCount }) {
+  if (!model) return;
+  if (unsupportedRatiosForModel(model).includes(ratio)) {
+    throw new Error(`当前模型不支持比例 ${ratio}`);
+  }
+  const countEnabled = model.imageGenOptions?.imageCountEnabled ?? true;
+  if (!countEnabled && Number(imageCount) > 1) {
+    throw new Error("当前模型不支持双图生成");
+  }
+}
+
+export function parseTemplateInput({ code, varsJson, displayPrompt = "" } = {}) {
+  if (!code) return { templates: [], displayPrompt };
+  const params = varsJson ? JSON.parse(varsJson) : {};
+  return {
+    templates: [{ code, params }],
+    displayPrompt: displayPrompt || code,
+  };
+}
+
+export async function findRecordsByInvokeTaskIds(api, {
+  taskIds,
+  appId,
+  userId,
+  pageSize = 10,
+  maxPages = 1,
+}) {
+  const parsedPageSize = Number(pageSize);
+  const size = Number.isFinite(parsedPageSize) && parsedPageSize > 0
+    ? Math.min(Math.floor(parsedPageSize), 10)
+    : 10;
+  const remaining = new Set(taskIds.map(String));
+  const matches = [];
+
+  for (let current = 1; current <= Math.min(maxPages, 1) && remaining.size > 0; current += 1) {
+    const result = await api.searchGenTasks({
+      current,
+      size,
+      userId,
+      appId,
+      includeFailedRecords: true,
+    });
+    const page = result?.data || result || {};
+    const records = page.records || page.list || [];
+
+    for (const record of records) {
+      const invokeTaskIds = (record.invokeTasks || []).map((task) => String(task.id || task.taskId || ""));
+      const matched = invokeTaskIds.some((id) => remaining.has(id));
+      if (!matched) continue;
+      matches.push(record);
+      for (const id of invokeTaskIds) remaining.delete(id);
+    }
+
+    const total = Number(page.total);
+    if (Number.isFinite(total) && current * size >= total) break;
+    if (!records.length) break;
+  }
+
+  return matches;
+}
+
+export function isTimeoutLikeError(error) {
+  const message = String(error?.message || "").toLowerCase();
+  return error?.code === "ETIMEDOUT"
+    || message.includes("timed out")
+    || message.includes("timeout")
+    || message.includes("websocket failed")
+    || message.includes("websocket");
+}
+
+function mimeTypeFromFilename(filename) {
+  const lower = filename.toLowerCase();
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".webp")) return "image/webp";
+  if (lower.endsWith(".gif")) return "image/gif";
+  return "application/octet-stream";
+}
+
+export async function uploadReferences(api, refs, { compress = true } = {}) {
   const urls = [];
   for (const ref of refs) {
     if (/^https?:\/\//i.test(ref)) {
       urls.push(ref);
       continue;
     }
+    const originalName = basename(ref);
     const bytes = await readFile(ref);
-    const blob = new Blob([bytes]);
-    urls.push(await api.uploadFile(blob, basename(ref)));
+    const prepared = compress
+      ? await compressImageBuffer(bytes, {
+        filename: originalName,
+        mimeType: mimeTypeFromFilename(originalName),
+      })
+      : { buffer: bytes, filename: originalName, mimeType: mimeTypeFromFilename(originalName) };
+    const blob = new Blob([prepared.buffer], { type: prepared.mimeType });
+    urls.push(await api.uploadFile(blob, prepared.filename));
   }
   return urls;
 }
@@ -71,6 +253,7 @@ export function waitForTask({ baseUrl, token, wsPath, taskId, timeoutMs = 360000
 
   return new Promise((resolve, reject) => {
     const ws = new WebSocket(url);
+    let heartbeat;
     const timer = setTimeout(() => {
       try {
         ws.close();
@@ -78,10 +261,16 @@ export function waitForTask({ baseUrl, token, wsPath, taskId, timeoutMs = 360000
       reject(new Error(`task ${taskId} timed out`));
     }, timeoutMs);
 
-    const cleanup = () => clearTimeout(timer);
+    const cleanup = () => {
+      clearTimeout(timer);
+      if (heartbeat) clearInterval(heartbeat);
+    };
     ws.addEventListener("open", () => {
       ws.send(JSON.stringify({ type: 3, taskId }));
       ws.send(JSON.stringify({ type: 8888 }));
+      heartbeat = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 8888 }));
+      }, 30000);
     });
     ws.addEventListener("message", (event) => {
       const text = String(event.data).replace(/(?<=[:,[]\s*)(\d{16,})(?=\s*[,}\]])/g, '"$1"');
@@ -96,6 +285,10 @@ export function waitForTask({ baseUrl, token, wsPath, taskId, timeoutMs = 360000
       cleanup();
       reject(new Error(`websocket failed for ${taskId}`));
     });
+    ws.addEventListener("close", (event) => {
+      cleanup();
+      if (event.code !== 1000) reject(new Error(`websocket closed for ${taskId}: ${event.code}`));
+    });
   });
 }
 

package/src/image-compress.js

@@ -0,0 +1,89 @@
+import sharp from "sharp";
+
+export const FRONTEND_UPLOAD_COMPRESSION = {
+  maxWidth: 1280,
+  maxHeight: 1280,
+  jpegQuality: 82,
+  minJpegQuality: 50,
+  minCompressBytes: 50 * 1024,
+  jpegTargetBytes: 300 * 1024,
+  supportedTypes: new Set(["image/jpeg", "image/jpg", "image/png", "image/webp", "image/gif"]),
+};
+
+export function shouldCompressImage({ mimeType, size }) {
+  return FRONTEND_UPLOAD_COMPRESSION.supportedTypes.has(String(mimeType || "").toLowerCase())
+    && Number(size) >= FRONTEND_UPLOAD_COMPRESSION.minCompressBytes;
+}
+
+function replaceExtension(filename, extension) {
+  const base = filename.includes(".") ? filename.slice(0, filename.lastIndexOf(".")) : filename;
+  return `${base}.${extension}`;
+}
+
+export async function compressImageBuffer(buffer, {
+  filename,
+  mimeType,
+  size = buffer.length,
+  options = FRONTEND_UPLOAD_COMPRESSION,
+} = {}) {
+  const normalizedMime = String(mimeType || "").toLowerCase();
+  if (!shouldCompressImage({ mimeType: normalizedMime, size })) {
+    return { buffer, filename, mimeType: normalizedMime, changed: false };
+  }
+
+  try {
+    const image = sharp(buffer, { animated: false });
+    const metadata = await image.metadata();
+    const hasAlpha = Boolean(metadata.hasAlpha);
+    const format = hasAlpha ? "png" : "jpeg";
+    const resize = {
+      width: options.maxWidth,
+      height: options.maxHeight,
+      fit: "inside",
+      withoutEnlargement: true,
+    };
+
+    if (format === "png") {
+      const compressed = await image
+        .resize(resize)
+        .png({ compressionLevel: 9, adaptiveFiltering: true })
+        .toBuffer();
+      if (compressed.length >= buffer.length && metadata.width <= options.maxWidth && metadata.height <= options.maxHeight) {
+        return { buffer, filename, mimeType: normalizedMime, changed: false };
+      }
+      return {
+        buffer: compressed,
+        filename: replaceExtension(filename, "png"),
+        mimeType: "image/png",
+        changed: true,
+      };
+    }
+
+    let quality = options.jpegQuality;
+    let compressed = await image
+      .resize(resize)
+      .jpeg({ quality, mozjpeg: true })
+      .toBuffer();
+
+    while (compressed.length > options.jpegTargetBytes && quality > options.minJpegQuality) {
+      quality = Math.max(quality - 5, options.minJpegQuality);
+      compressed = await image
+        .resize(resize)
+        .jpeg({ quality, mozjpeg: true })
+        .toBuffer();
+    }
+
+    if (compressed.length >= buffer.length && metadata.width <= options.maxWidth && metadata.height <= options.maxHeight) {
+      return { buffer, filename, mimeType: normalizedMime, changed: false };
+    }
+
+    return {
+      buffer: compressed,
+      filename: replaceExtension(filename, "jpg"),
+      mimeType: "image/jpeg",
+      changed: true,
+    };
+  } catch {
+    return { buffer, filename, mimeType: normalizedMime, changed: false };
+  }
+}