feat(intake): report what a whole-item background removal actually did (#293)

removeBackgroundsForItem answered void and threw on the first failure, which is enough for the drafting worker — it catches and logs, and a draft is not worth failing over — and not enough for an admin standing in front of a screen who needs to know whether the thing they pressed happened. It now returns a summary: how many photos the item has, how many carry a cut-out, and whether it stopped early.

It still stops at the first failure. Six attempts against a sidecar that is not answering helps nobody, and stopping costs nothing because removeImageBackground skips a photo that already has an original recorded, so a retry resumes rather than starting over. The count is what turns that retry into an informed choice instead of a guess.

Adds restoreOriginalsForItem alongside it. A photo that was never cut out is skipped rather than refused, because the mixed state a partial removal leaves behind is exactly when somebody reaches for this.

The one existing caller does not change: the worker ignores the result, and ignoring a returned value is legal, which is what makes this additive rather than breaking.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

backend/src/intake/backgroundRemoval.ts

@@ -169,21 +169,103 @@ export async function restoreImageOriginal(imageId: number): Promise<void> {
 }
 
 /**
- * Every photo of one item, in order.
+ * What a whole-item removal actually did.
  *
- * Sequential rather than parallel: the sidecar is assumed to handle one
- * request at a time, and the worker it runs inside is not in a hurry. A
- * failure on one photo stops the rest, and the caller logs it — the item keeps
- * whatever was already done, and nothing is left half-written.
+ * `void` was enough for the drafting worker, which catches and logs and would
+ * not fail a draft over a background — but not for an admin standing in front
+ * of the screen, who needs to know whether the thing they pressed happened.
+ * Three of four is the normal shape of a bad day here, not an exception, and
+ * the count is what decides whether pressing it again is worth anything.
  */
-export async function removeBackgroundsForItem(itemId: number): Promise<void> {
-  if (!isRembgConfigured()) return;
+export interface RemovalSummary {
+  /** How many images the item has. */
+  total: number;
+  /** How many now carry a cut-out, including any that already did. */
+  removed: number;
+  /** Whether it stopped early because one of them failed. */
+  failed: boolean;
+}
 
+/**
+ * What a whole-item restore did.
+ *
+ * No `failed`, because restoring cannot fail the way removing can: it is a
+ * database swap with no sidecar in it, and a photo that was never cut out is
+ * skipped rather than being an error.
+ */
+export interface RestoreSummary {
+  total: number;
+  /** How many were put back. Photos that were never cut out are not counted. */
+  restored: number;
+}
+
+/** Every photo of one item, in order. */
+async function imageIdsFor(itemId: number): Promise<number[]> {
   const { rows } = await pool.query<{ id: number }>(
     `SELECT id FROM item_images WHERE item_id = $1 ORDER BY sort_order`,
     [itemId]
   );
-  for (const row of rows) {
-    await removeImageBackground(row.id);
+  return rows.map((row) => row.id);
+}
+
+/**
+ * Cuts out every photo of one item.
+ *
+ * Sequential rather than parallel: the sidecar is assumed to handle one request
+ * at a time, and neither caller is in a hurry.
+ *
+ * Stops at the first failure rather than pushing on. Six attempts against a
+ * sidecar that is not answering helps nobody, and stopping costs nothing
+ * because `removeImageBackground` skips a photo that already has an original
+ * recorded — so pressing the button again resumes where this stopped instead of
+ * starting over. The summary is what makes that retry an informed choice rather
+ * than a guess.
+ *
+ * An unconfigured environment is not a failure, here as everywhere else in this
+ * feature: nothing was attempted, so nothing went wrong.
+ */
+export async function removeBackgroundsForItem(itemId: number): Promise<RemovalSummary> {
+  const imageIds = await imageIdsFor(itemId);
+  if (!isRembgConfigured()) {
+    return { total: imageIds.length, removed: 0, failed: false };
   }
+
+  let removed = 0;
+  for (const imageId of imageIds) {
+    try {
+      await removeImageBackground(imageId);
+      removed += 1;
+    } catch (err) {
+      // Logged rather than thrown. The caller gets the count, which is the
+      // thing it can act on; the reason belongs in the log, because the admin's
+      // next move is the same whatever it was.
+      console.error(`[background-removal] item ${itemId}, image ${imageId}:`, err);
+      return { total: imageIds.length, removed, failed: true };
+    }
+  }
+  return { total: imageIds.length, removed, failed: false };
+}
+
+/**
+ * Puts every cut-out photo of one item back.
+ *
+ * A photo that was never cut out is skipped rather than refused — the mixed
+ * state a partial removal leaves behind has to be restorable too, and half an
+ * item is exactly when somebody reaches for this.
+ */
+export async function restoreOriginalsForItem(itemId: number): Promise<RestoreSummary> {
+  const imageIds = await imageIdsFor(itemId);
+
+  let restored = 0;
+  for (const imageId of imageIds) {
+    try {
+      await restoreImageOriginal(imageId);
+      restored += 1;
+    } catch (err) {
+      // Only "there was nothing to restore" is skipped. Anything else is a real
+      // failure and belongs to the caller.
+      if (!(err instanceof NoOriginalToRestoreError)) throw err;
+    }
+  }
+  return { total: imageIds.length, restored };
 }