feat(api): wire AI route handlers to SSE progress via clientJobId

Extract clientJobId from multipart form data in all 5 AI route handlers
(remove-background, upscale, blur-faces, erase-object, ocr) and forward
progress callbacks to the SSE system via updateSingleFileProgress.

apps/api/src/routes/tools/blur-faces.ts

@@ -4,6 +4,7 @@ import { writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import { blurFaces } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
+import { updateSingleFileProgress } from "../progress.js";
 
 /**
  * Face detection and blurring route.
@@ -16,6 +17,7 @@ export function registerBlurFaces(app: FastifyInstance) {
       let fileBuffer: Buffer | null = null;
       let filename = "image";
       let settingsRaw: string | null = null;
+      let clientJobId: string | null = null;
 
       try {
         const parts = request.parts();
@@ -29,6 +31,8 @@ export function registerBlurFaces(app: FastifyInstance) {
             filename = basename(part.filename ?? "image");
           } else if (part.fieldname === "settings") {
             settingsRaw = part.value as string;
+          } else if (part.fieldname === "clientJobId") {
+            clientJobId = part.value as string;
           }
         }
       } catch (err) {
@@ -52,6 +56,17 @@ export function registerBlurFaces(app: FastifyInstance) {
         await writeFile(inputPath, fileBuffer);
 
         // Process
+        const onProgress = clientJobId
+          ? (percent: number, stage: string) => {
+              updateSingleFileProgress({
+                jobId: clientJobId!,
+                phase: "processing",
+                stage,
+                percent,
+              });
+            }
+          : undefined;
+
         const result = await blurFaces(
           fileBuffer,
           join(workspacePath, "output"),
@@ -59,6 +74,7 @@ export function registerBlurFaces(app: FastifyInstance) {
             blurRadius: settings.blurRadius ?? 30,
             sensitivity: settings.sensitivity ?? 0.5,
           },
+          onProgress,
         );
 
         // Save output
@@ -67,6 +83,14 @@ export function registerBlurFaces(app: FastifyInstance) {
         const outputPath = join(workspacePath, "output", outputFilename);
         await writeFile(outputPath, result.buffer);
 
+        if (clientJobId) {
+          updateSingleFileProgress({
+            jobId: clientJobId,
+            phase: "complete",
+            percent: 100,
+          });
+        }
+
         return reply.send({
           jobId,
           downloadUrl: `/api/v1/download/${jobId}/${encodeURIComponent(outputFilename)}`,

apps/api/src/routes/tools/erase-object.ts

@@ -4,6 +4,7 @@ import { writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import { inpaint } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
+import { updateSingleFileProgress } from "../progress.js";
 
 /**
  * Object eraser / inpainting route.
@@ -16,6 +17,7 @@ export function registerEraseObject(app: FastifyInstance) {
       let imageBuffer: Buffer | null = null;
       let maskBuffer: Buffer | null = null;
       let filename = "image";
+      let clientJobId: string | null = null;
 
       try {
         const parts = request.parts();
@@ -32,6 +34,8 @@ export function registerEraseObject(app: FastifyInstance) {
               imageBuffer = buf;
               filename = basename(part.filename ?? "image");
             }
+          } else if (part.fieldname === "clientJobId") {
+            clientJobId = part.value as string;
           }
         }
       } catch (err) {
@@ -59,10 +63,22 @@ export function registerEraseObject(app: FastifyInstance) {
         await writeFile(inputPath, imageBuffer);
 
         // Process
+        const onProgress = clientJobId
+          ? (percent: number, stage: string) => {
+              updateSingleFileProgress({
+                jobId: clientJobId!,
+                phase: "processing",
+                stage,
+                percent,
+              });
+            }
+          : undefined;
+
         const resultBuffer = await inpaint(
           imageBuffer,
           maskBuffer,
           join(workspacePath, "output"),
+          onProgress,
         );
 
         // Save output
@@ -71,6 +87,14 @@ export function registerEraseObject(app: FastifyInstance) {
         const outputPath = join(workspacePath, "output", outputFilename);
         await writeFile(outputPath, resultBuffer);
 
+        if (clientJobId) {
+          updateSingleFileProgress({
+            jobId: clientJobId,
+            phase: "complete",
+            percent: 100,
+          });
+        }
+
         return reply.send({
           jobId,
           downloadUrl: `/api/v1/download/${jobId}/${encodeURIComponent(outputFilename)}`,

apps/api/src/routes/tools/ocr.ts

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { basename } from "node:path";
 import { extractText } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
+import { updateSingleFileProgress } from "../progress.js";
 
 /**
  * OCR / text extraction route.
@@ -15,6 +16,7 @@ export function registerOcr(app: FastifyInstance) {
       let fileBuffer: Buffer | null = null;
       let filename = "image";
       let settingsRaw: string | null = null;
+      let clientJobId: string | null = null;
 
       try {
         const parts = request.parts();
@@ -28,6 +30,8 @@ export function registerOcr(app: FastifyInstance) {
             filename = basename(part.filename ?? "image");
           } else if (part.fieldname === "settings") {
             settingsRaw = part.value as string;
+          } else if (part.fieldname === "clientJobId") {
+            clientJobId = part.value as string;
           }
         }
       } catch (err) {
@@ -46,10 +50,34 @@ export function registerOcr(app: FastifyInstance) {
         const jobId = randomUUID();
         const workspacePath = await createWorkspace(jobId);
 
-        const result = await extractText(fileBuffer, workspacePath, {
+        const onProgress = clientJobId
-          engine: settings.engine,
+          ? (percent: number, stage: string) => {
-          language: settings.language,
+              updateSingleFileProgress({
-        });
+                jobId: clientJobId!,
+                phase: "processing",
+                stage,
+                percent,
+              });
+            }
+          : undefined;
+
+        const result = await extractText(
+          fileBuffer,
+          workspacePath,
+          {
+            engine: settings.engine,
+            language: settings.language,
+          },
+          onProgress,
+        );
+
+        if (clientJobId) {
+          updateSingleFileProgress({
+            jobId: clientJobId,
+            phase: "complete",
+            percent: 100,
+          });
+        }
 
         return reply.send({
           jobId,

apps/api/src/routes/tools/remove-background.ts

@@ -4,6 +4,7 @@ import { writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import { removeBackground } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
+import { updateSingleFileProgress } from "../progress.js";
 
 /**
  * AI background removal route.
@@ -16,6 +17,7 @@ export function registerRemoveBackground(app: FastifyInstance) {
       let fileBuffer: Buffer | null = null;
       let filename = "image";
       let settingsRaw: string | null = null;
+      let clientJobId: string | null = null;
 
       try {
         const parts = request.parts();
@@ -29,6 +31,8 @@ export function registerRemoveBackground(app: FastifyInstance) {
             filename = basename(part.filename ?? "image");
           } else if (part.fieldname === "settings") {
             settingsRaw = part.value as string;
+          } else if (part.fieldname === "clientJobId") {
+            clientJobId = part.value as string;
           }
         }
       } catch (err) {
@@ -52,10 +56,22 @@ export function registerRemoveBackground(app: FastifyInstance) {
         await writeFile(inputPath, fileBuffer);
 
         // Process
+        const onProgress = clientJobId
+          ? (percent: number, stage: string) => {
+              updateSingleFileProgress({
+                jobId: clientJobId!,
+                phase: "processing",
+                stage,
+                percent,
+              });
+            }
+          : undefined;
+
         const resultBuffer = await removeBackground(
           fileBuffer,
           join(workspacePath, "output"),
           { model: settings.model, backgroundColor: settings.backgroundColor },
+          onProgress,
         );
 
         // Save output
@@ -63,6 +79,14 @@ export function registerRemoveBackground(app: FastifyInstance) {
         const outputPath = join(workspacePath, "output", outputFilename);
         await writeFile(outputPath, resultBuffer);
 
+        if (clientJobId) {
+          updateSingleFileProgress({
+            jobId: clientJobId,
+            phase: "complete",
+            percent: 100,
+          });
+        }
+
         return reply.send({
           jobId,
           downloadUrl: `/api/v1/download/${jobId}/${encodeURIComponent(outputFilename)}`,

apps/api/src/routes/tools/upscale.ts

@@ -4,6 +4,7 @@ import { writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import { upscale } from "@stirling-image/ai";
 import { createWorkspace } from "../../lib/workspace.js";
+import { updateSingleFileProgress } from "../progress.js";
 
 /**
  * AI image upscaling route.
@@ -16,6 +17,7 @@ export function registerUpscale(app: FastifyInstance) {
       let fileBuffer: Buffer | null = null;
       let filename = "image";
       let settingsRaw: string | null = null;
+      let clientJobId: string | null = null;
 
       try {
         const parts = request.parts();
@@ -29,6 +31,8 @@ export function registerUpscale(app: FastifyInstance) {
             filename = basename(part.filename ?? "image");
           } else if (part.fieldname === "settings") {
             settingsRaw = part.value as string;
+          } else if (part.fieldname === "clientJobId") {
+            clientJobId = part.value as string;
           }
         }
       } catch (err) {
@@ -54,10 +58,22 @@ export function registerUpscale(app: FastifyInstance) {
         await writeFile(inputPath, fileBuffer);
 
         // Process
+        const onProgress = clientJobId
+          ? (percent: number, stage: string) => {
+              updateSingleFileProgress({
+                jobId: clientJobId!,
+                phase: "processing",
+                stage,
+                percent,
+              });
+            }
+          : undefined;
+
         const result = await upscale(
           fileBuffer,
           join(workspacePath, "output"),
           { scale },
+          onProgress,
         );
 
         // Save output
@@ -66,6 +82,14 @@ export function registerUpscale(app: FastifyInstance) {
         const outputPath = join(workspacePath, "output", outputFilename);
         await writeFile(outputPath, result.buffer);
 
+        if (clientJobId) {
+          updateSingleFileProgress({
+            jobId: clientJobId,
+            phase: "complete",
+            percent: 100,
+          });
+        }
+
         return reply.send({
           jobId,
           downloadUrl: `/api/v1/download/${jobId}/${encodeURIComponent(outputFilename)}`,