feat(library): wire save-mode into the five custom-client tool submitters (#577)

Closes #565. Wires the fileId/saveMode pair into the ocr, erase-object, remove-background, background-replace, and blur-background submitters so the library save-mode selector works for them; remove-background's two-phase effects route now auto-saves the final composite instead of the transparent intermediate.

tests/integration/tools/image/remove-background.test.ts

@@ -8,7 +8,10 @@
  * Also covers the /effects sub-route for Phase 2 compositing.
  */
 
+import { randomUUID } from "node:crypto";
+import sharp from "sharp";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { putObject } from "../../../../apps/api/src/lib/object-storage.js";
 import { fixtures, readFixture } from "../../../fixtures/index.js";
 import {
   buildTestApp,
@@ -502,3 +505,184 @@ describe("Remove Background", () => {
     expect(res.statusCode).toBe(401);
   });
 });
+
+// ── Phase 2 effects route: library auto-save (#495 / #565) ─────────
+//
+// The compositing route is pure Sharp (no AI sidecar), so its library
+// auto-save is testable end to end in CI. It saves the FINAL composited
+// image (not the transparent Phase 1 intermediate) under the chosen
+// saveMode when the request references a library file.
+
+/** Upload a PNG into the library, return its file id. */
+async function uploadLibraryFile(filename: string): Promise<string> {
+  const { body, contentType } = createMultipartPayload([
+    { name: "file", filename, contentType: "image/png", content: PNG },
+  ]);
+  const res = await app.inject({
+    method: "POST",
+    url: "/api/v1/files/upload",
+    headers: { "content-type": contentType, authorization: `Bearer ${adminToken}` },
+    body,
+  });
+  expect(res.statusCode).toBe(201);
+  return JSON.parse(res.body).files[0].id;
+}
+
+/** Fetch file detail (metadata + version chain). */
+async function getFileDetail(id: string) {
+  const res = await app.inject({
+    method: "GET",
+    url: `/api/v1/files/${id}`,
+    headers: { authorization: `Bearer ${adminToken}` },
+  });
+  expect(res.statusCode).toBe(200);
+  return JSON.parse(res.body);
+}
+
+/**
+ * Seed the cached Phase 1 artifacts the effects route reads: a transparent
+ * subject (`_mask.png`) and the original (`_original.png`) under the job's
+ * output prefix, both matching the `<base>` derived from the filename.
+ */
+async function seedPhase1Cache(jobId: string, base: string): Promise<void> {
+  const mask = await sharp({
+    create: { width: 20, height: 20, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
+  })
+    .png()
+    .toBuffer();
+  const original = await sharp({
+    create: { width: 20, height: 20, channels: 3, background: { r: 10, g: 20, b: 30 } },
+  })
+    .png()
+    .toBuffer();
+  await putObject(`outputs/${jobId}/${base}_mask.png`, mask);
+  await putObject(`outputs/${jobId}/${base}_original.png`, original);
+}
+
+function effectsPayload(fields: Array<{ name: string; content: string }>) {
+  return createMultipartPayload(fields);
+}
+
+describe("Remove Background effects route: library saveMode", () => {
+  it("saves the composited result as an independent new library file", async () => {
+    const originalId = await uploadLibraryFile("rbfxnew.png");
+    const jobId = randomUUID();
+    await seedPhase1Cache(jobId, "rbfxnew");
+
+    const { body, contentType } = effectsPayload([
+      {
+        name: "settings",
+        content: JSON.stringify({
+          jobId,
+          filename: "rbfxnew.png",
+          backgroundType: "color",
+          backgroundColor: "#FF0000",
+          outputFormat: "png",
+        }),
+      },
+      { name: "fileId", content: originalId },
+      { name: "saveMode", content: "new" },
+    ]);
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/image/remove-background/effects",
+      headers: { authorization: `Bearer ${adminToken}`, "content-type": contentType },
+      body,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const parsed = JSON.parse(res.body);
+    expect(parsed.savedFileId).toBeDefined();
+    expect(parsed.savedFileId).not.toBe(originalId);
+
+    const detail = await getFileDetail(parsed.savedFileId);
+    expect(detail.file.version).toBe(1);
+    expect(detail.file.parentId).toBeNull();
+    expect(detail.file.toolChain).toContain("remove-background");
+  });
+
+  it("overwrite creates a superseding version linked to the original", async () => {
+    const originalId = await uploadLibraryFile("rbfxover.png");
+    const jobId = randomUUID();
+    await seedPhase1Cache(jobId, "rbfxover");
+
+    const { body, contentType } = effectsPayload([
+      {
+        name: "settings",
+        content: JSON.stringify({
+          jobId,
+          filename: "rbfxover.png",
+          backgroundType: "color",
+          backgroundColor: "#00FF00",
+          outputFormat: "png",
+        }),
+      },
+      { name: "fileId", content: originalId },
+      { name: "saveMode", content: "overwrite" },
+    ]);
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/image/remove-background/effects",
+      headers: { authorization: `Bearer ${adminToken}`, "content-type": contentType },
+      body,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const parsed = JSON.parse(res.body);
+    expect(parsed.savedFileId).toBeDefined();
+
+    const detail = await getFileDetail(parsed.savedFileId);
+    expect(detail.file.version).toBe(2);
+    expect(detail.file.parentId).toBe(originalId);
+  });
+
+  it("does not save when no fileId is sent", async () => {
+    const jobId = randomUUID();
+    await seedPhase1Cache(jobId, "rbfxnolib");
+
+    const { body, contentType } = effectsPayload([
+      {
+        name: "settings",
+        content: JSON.stringify({
+          jobId,
+          filename: "rbfxnolib.png",
+          backgroundType: "color",
+          backgroundColor: "#0000FF",
+          outputFormat: "png",
+        }),
+      },
+    ]);
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/image/remove-background/effects",
+      headers: { authorization: `Bearer ${adminToken}`, "content-type": contentType },
+      body,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body).savedFileId).toBeUndefined();
+  });
+
+  it("rejects an invalid saveMode with 400", async () => {
+    const { body, contentType } = effectsPayload([
+      {
+        name: "settings",
+        content: JSON.stringify({ jobId: randomUUID(), filename: "x.png" }),
+      },
+      { name: "saveMode", content: "destroy-everything" },
+    ]);
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/api/v1/tools/image/remove-background/effects",
+      headers: { authorization: `Bearer ${adminToken}`, "content-type": contentType },
+      body,
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body).error).toMatch(/saveMode/i);
+  });
+});