feat: reorder inventory images atomically

apps/api/src/modules/inventory/domain/image-order.js

@@ -0,0 +1,19 @@
+import { createApplicationError } from '../../../shared/errors/application-error.js';
+
+export function validateImageMove(direction) {
+  if (direction !== 'up' && direction !== 'down') {
+    throw createApplicationError('IMAGE_MOVE_INVALID', 'Image move must be up or down.', 400);
+  }
+}
+
+// Input is the persisted display order. Return a reordered copy; boundary moves
+// are no-ops. Persistence assigns contiguous positions after an actual move.
+export function moveImageInOrder(images, imageId, direction) {
+  validateImageMove(direction);
+  const index = images.findIndex((image) => image.id === imageId);
+  const neighbor = index + (direction === 'up' ? -1 : 1);
+  if (index < 0 || neighbor < 0 || neighbor >= images.length) return images;
+  const reordered = [...images];
+  [reordered[index], reordered[neighbor]] = [reordered[neighbor], reordered[index]];
+  return reordered;
+}

apps/api/src/modules/inventory/repositories/inventory-image-repository.js

@@ -1,3 +1,4 @@
+import { moveImageInOrder } from '../domain/image-order.js';
 import { and, eq, inArray } from 'drizzle-orm';
 
 import {
@@ -53,10 +54,42 @@ export function createInventoryImageRepository(db) {
           eq(inventoryImages.inventoryItemId, inventoryItemId),
           eq(products.sellerId, sellerId),
         ))
-        .orderBy(inventoryImages.sortOrder)
+        .orderBy(inventoryImages.sortOrder, inventoryImages.createdAt, inventoryImages.id)
         .then((rows) => rows.map(({ image }) => image));
     },
 
+    async moveForSeller(imageId, direction, sellerId) {
+      return db.transaction(async (tx) => {
+        // Lock the owning physical item first, serializing moves within a gallery.
+        const [owned] = await tx
+          .select({ inventoryItemId: inventoryItems.id })
+          .from(inventoryImages)
+          .innerJoin(inventoryItems, eq(inventoryItems.id, inventoryImages.inventoryItemId))
+          .innerJoin(products, eq(products.id, inventoryItems.productId))
+          .where(and(eq(inventoryImages.id, imageId), eq(products.sellerId, sellerId)))
+          .for('update', { of: inventoryItems });
+        if (!owned) return null;
+
+        const images = await tx.select().from(inventoryImages)
+          .where(eq(inventoryImages.inventoryItemId, owned.inventoryItemId))
+          .orderBy(inventoryImages.sortOrder, inventoryImages.createdAt, inventoryImages.id)
+          .for('update');
+        const target = images.find((image) => image.id === imageId);
+        if (!target) return null;
+        const reordered = moveImageInOrder(images, imageId, direction);
+        if (reordered === images) return target;
+        const updatedAt = new Date();
+        for (const [sortOrder, image] of reordered.entries()) {
+          if (image.sortOrder !== sortOrder) {
+            await tx.update(inventoryImages).set({ sortOrder, updatedAt })
+              .where(eq(inventoryImages.id, image.id));
+          }
+        }
+        const [moved] = await tx.select().from(inventoryImages).where(eq(inventoryImages.id, imageId));
+        return moved;
+      });
+    },
+
     async updateOrderForSeller(imageId, sortOrder, sellerId) {
       const owned = await this.findByIdForSeller(imageId, sellerId);
       if (!owned) return null;
@@ -135,7 +168,7 @@ export function createInventoryImageRepository(db) {
           eq(inventoryImages.processingStatus, 'COMPLETED'),
           eq(imageDerivativeJobs.status, 'COMPLETED'),
         ))
-        .orderBy(inventoryImages.sortOrder);
+        .orderBy(inventoryImages.sortOrder, inventoryImages.createdAt, inventoryImages.id);
     },
 
     async findPublicById(imageId) {

apps/api/src/modules/inventory/routes/admin-image-routes.js

@@ -1,5 +1,5 @@
 import { toAdminInventoryImageDto } from '@pokemon-inventory/contracts/image';
-import { createInventoryImageSchema } from '@pokemon-inventory/validation/image';
+import { createInventoryImageSchema, moveInventoryImageSchema } from '@pokemon-inventory/validation/image';
 import { randomUUID } from 'node:crypto';
 
 import { createApplicationError } from '../../../shared/errors/application-error.js';
@@ -98,6 +98,18 @@ export async function registerAdminImageRoutes(app, options) {
     return admin;
   }
 
+  app.post('/images/:id/move', async (request, reply) => {
+    const admin = await authorizeAdminMutation(request);
+    const result = moveInventoryImageSchema.safeParse(request.body);
+    if (!result.success) return validationError(reply, result);
+    const image = await inventoryImageService.move({
+      imageId: request.params.id,
+      direction: result.data.direction,
+      sellerId: admin.sellerId,
+    });
+    return { data: toAdminInventoryImageDto(image) };
+  });
+
   app.patch('/images/:id/order', async (request) => {
     const admin = await authorizeAdminMutation(request);
     const image = await inventoryImageService.updateOrder({

apps/api/src/modules/inventory/services/inventory-image-service.js

@@ -1,3 +1,4 @@
+import { validateImageMove } from '../domain/image-order.js';
 import { createApplicationError } from '../../../shared/errors/application-error.js';
 import { validateImageSignature, validateInventoryImageMetadata } from '../domain/inventory-image.js';
 
@@ -42,6 +43,11 @@ export function createInventoryImageService({ inventoryImageRepository, imageDer
       }
     },
 
+    async move({ imageId, direction, sellerId }) {
+      validateImageMove(direction);
+      return requireOwnedImage(inventoryImageRepository.moveForSeller(imageId, direction, sellerId));
+    },
+
     async updateOrder({ imageId, sortOrder, sellerId }) {
       return requireOwnedImage(inventoryImageRepository.updateOrderForSeller(imageId, sortOrder, sellerId));
     },

apps/api/tests/application/inventory-image-management.test.js

@@ -35,3 +35,16 @@ test('manages owned image order, primary state, alt text, retry, and deletion',
   assert.ok(calls.some(([action]) => action === 'delete-job'));
   assert.ok(calls.some(([action]) => action === 'storage-delete'));
 });
+
+test('moves an image through the owned atomic repository operation', async () => {
+  const service = createInventoryImageService({ inventoryImageRepository: {
+    async moveForSeller(id, direction, sellerId) {
+      assert.equal(direction, 'down');
+      assert.equal(sellerId, 'seller-1');
+      return id === 'owned' ? { id, sortOrder: 1 } : null;
+    },
+  } });
+  assert.deepEqual(await service.move({ imageId: 'owned', direction: 'down', sellerId: 'seller-1' }), { id: 'owned', sortOrder: 1 });
+  await assert.rejects(() => service.move({ imageId: 'missing', direction: 'down', sellerId: 'seller-1' }), { code: 'IMAGE_NOT_FOUND' });
+  await assert.rejects(() => service.move({ imageId: 'owned', direction: 'left', sellerId: 'seller-1' }), { code: 'IMAGE_MOVE_INVALID' });
+});

apps/api/tests/domain/image-order.test.js

@@ -0,0 +1,13 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { moveImageInOrder } from '../../src/modules/inventory/domain/image-order.js';
+
+test('moves one image next to its neighbor without changing the input order', () => {
+  const images = [{ id: 'a' }, { id: 'b' }, { id: 'c' }];
+  assert.deepEqual(moveImageInOrder(images, 'b', 'up').map(({ id }) => id), ['b', 'a', 'c']);
+  assert.deepEqual(moveImageInOrder(images, 'b', 'down').map(({ id }) => id), ['a', 'c', 'b']);
+  assert.deepEqual(images.map(({ id }) => id), ['a', 'b', 'c']);
+  assert.equal(moveImageInOrder(images, 'a', 'up'), images);
+  assert.equal(moveImageInOrder(images, 'c', 'down'), images);
+  assert.throws(() => moveImageInOrder(images, 'a', 'left'), { code: 'IMAGE_MOVE_INVALID' });
+});

apps/api/tests/http/image-move-routes.test.js

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildApp } from '../../src/app/build-app.js';
+
+test('validates and authorizes image moves and exposes only the image DTO', async (context) => {
+  const calls = [];
+  const app = buildApp({
+    authenticateAdmin: async () => ({ sellerId: 'seller-1' }),
+    authorizeUnsafeRequest: async () => { calls.push('csrf'); },
+    inventoryImageService: { async move(input) { calls.push(input); return { id: input.imageId, sortOrder: 1, privateData: 'hidden' }; } },
+  });
+  context.after(() => app.close());
+  const response = await app.inject({ method: 'POST', url: '/api/v1/admin/images/image-1/move', payload: { direction: 'down' } });
+  assert.equal(response.statusCode, 200);
+  assert.deepEqual(calls, ['csrf', { imageId: 'image-1', direction: 'down', sellerId: 'seller-1' }]);
+  assert.equal(response.json().data.sortOrder, 1);
+  assert.equal(response.json().data.privateData, undefined);
+  for (const payload of [{}, { direction: 'left' }, { direction: 'up', sellerId: 'other' }]) {
+    assert.equal((await app.inject({ method: 'POST', url: '/api/v1/admin/images/image-1/move', payload })).statusCode, 400);
+  }
+});
+
+test('rejects unauthenticated and CSRF-blocked moves without calling the service', async (context) => {
+  for (const csrf of [false, true]) {
+    const app = buildApp({
+      authenticateAdmin: async () => csrf ? { sellerId: 'seller-1' } : null,
+      authorizeUnsafeRequest: async () => { throw Object.assign(new Error('Forbidden'), { statusCode: 403 }); },
+      inventoryImageService: { async move() { assert.fail('unauthorized move'); } },
+    });
+    context.after(() => app.close());
+    assert.equal((await app.inject({ method: 'POST', url: '/api/v1/admin/images/image-1/move', payload: { direction: 'up' } })).statusCode, csrf ? 403 : 401);
+  }
+});

apps/api/tests/integration/listing-repository.test.js

@@ -273,3 +273,65 @@ test('reads and updates listings only through the owning seller scope', async ()
   const archivedListing = await listingRepository.updateStatus(createdListing.id, 'ARCHIVED');
   assert.equal(archivedListing.status, 'ARCHIVED');
 });
+
+async function createImageOrderFixture() {
+  const { seller, inventoryItem } = await createInventoryFixture();
+  const images = [];
+  for (let index = 0; index < 3; index += 1) {
+    images.push(await inventoryImageRepository.createForSeller({
+      inventoryItemId: inventoryItem.id, storageKey: `move-${index}.jpg`, originalFilename: `move-${index}.jpg`,
+      mimeType: 'image/jpeg', fileSize: 100, width: 10, height: 10, sortOrder: 0,
+      isPrimary: index === 0,
+    }, seller.id));
+  }
+  return { seller, inventoryItem, images: await inventoryImageRepository.listByInventoryItemForSeller(inventoryItem.id, seller.id) };
+}
+
+test('moves images atomically with tied positions, ownership checks and boundary no-ops', async () => {
+  const { seller, inventoryItem, images } = await createImageOrderFixture();
+  const read = () => inventoryImageRepository.listByInventoryItemForSeller(inventoryItem.id, seller.id);
+  assert.equal(await inventoryImageRepository.moveForSeller(images[0].id, 'down', '00000000-0000-0000-0000-000000000000'), null);
+  assert.equal(await inventoryImageRepository.moveForSeller('00000000-0000-0000-0000-000000000000', 'down', seller.id), null);
+  assert.deepEqual(await read(), images);
+  await inventoryImageRepository.moveForSeller(images[0].id, 'up', seller.id);
+  assert.deepEqual(await read(), images);
+  await inventoryImageRepository.moveForSeller(images[0].id, 'down', seller.id);
+  const moved = await read();
+  assert.deepEqual(moved.map(({ id }) => id), [images[1].id, images[0].id, images[2].id]);
+  assert.deepEqual(moved.map(({ sortOrder }) => sortOrder), [0, 1, 2]);
+  assert.equal(moved.find(({ id }) => id === images[0].id).isPrimary, images[0].isPrimary);
+  await inventoryImageRepository.moveForSeller(images[0].id, 'up', seller.id);
+  assert.deepEqual((await read()).map(({ id }) => id), images.map(({ id }) => id));
+});
+
+test('rolls back every position if an image move fails after its first write', async () => {
+  const { seller, inventoryItem, images } = await createImageOrderFixture();
+  let writes = 0;
+  const failingRepository = createInventoryImageRepository({
+    transaction: (action) => database.db.transaction((tx) => action(new Proxy(tx, {
+      get(target, property) {
+        if (property === 'update') return (...args) => {
+          writes += 1;
+          if (writes === 2) throw new Error('Injected second write failure');
+          return target.update(...args);
+        };
+        const value = target[property];
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    }))),
+  });
+  await assert.rejects(() => failingRepository.moveForSeller(images[0].id, 'down', seller.id), /Injected second write failure/);
+  assert.equal(writes, 2);
+  assert.deepEqual(await inventoryImageRepository.listByInventoryItemForSeller(inventoryItem.id, seller.id), images);
+});
+
+test('serializes concurrent moves within the same gallery', async () => {
+  const { seller, inventoryItem, images } = await createImageOrderFixture();
+  await Promise.all([
+    inventoryImageRepository.moveForSeller(images[0].id, 'down', seller.id),
+    inventoryImageRepository.moveForSeller(images[0].id, 'down', seller.id),
+  ]);
+  const result = await inventoryImageRepository.listByInventoryItemForSeller(inventoryItem.id, seller.id);
+  assert.deepEqual(result.map(({ id }) => id), [images[1].id, images[2].id, images[0].id]);
+  assert.deepEqual(result.map(({ sortOrder }) => sortOrder), [0, 1, 2]);
+});