feat: add Product tags and bulk tag updates

apps/api/src/infrastructure/database/schema.js

@@ -218,6 +218,7 @@ export const products = pgTable(
     cardNumber: text("card_number"),
     eventName: text("event_name"),
     releaseYear: integer("release_year"),
+    tags: text("tags").array().default([]).notNull(),
     ...timestamps,
   },
   (table) => [

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

@@ -57,6 +57,24 @@ export function createInventoryItemRepository(db) {
         .returning();
     },
 
+    async updateProductTagsByIdsForSeller(inventoryItemIds, sellerId, addTags, removeTags) {
+      const rows = await db
+        .select({ productId: inventoryItems.productId })
+        .from(inventoryItems)
+        .innerJoin(products, eq(products.id, inventoryItems.productId))
+        .where(and(inArray(inventoryItems.id, inventoryItemIds), eq(products.sellerId, sellerId)));
+      const productIds = [...new Set(rows.map(({ productId }) => productId))];
+      const updated = [];
+      for (const productId of productIds) {
+        const [product] = await db.select().from(products).where(eq(products.id, productId));
+        const tags = [...new Set([...(product.tags ?? []), ...addTags.map((tag) => tag.toLowerCase())])]
+          .filter((tag) => !removeTags.map((value) => value.toLowerCase()).includes(tag));
+        const [result] = await db.update(products).set({ tags, updatedAt: new Date() }).where(eq(products.id, productId)).returning();
+        updated.push(result);
+      }
+      return updated;
+    },
+
     async searchPublic({ page = 1, limit = 20 } = {}) {
       const conditions = [
         eq(inventoryItems.status, 'ACTIVE'),

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

@@ -78,16 +78,25 @@ export async function registerAdminInventoryRoutes(app, options) {
         inventoryItemIds: result.data.inventoryItemIds,
         sellerId: request.admin.sellerId,
       })
-      : await inventoryItemService.refreshPricingMany({
+      : result.data.action === 'PRICING_REFRESH'
+        ? await inventoryItemService.refreshPricingMany({
         inventoryItemIds: result.data.inventoryItemIds,
         providerId: result.data.providerId,
         sellerId: request.admin.sellerId,
-      });
+        })
+        : await inventoryItemService.updateTagsMany({
+          inventoryItemIds: result.data.inventoryItemIds,
+          sellerId: request.admin.sellerId,
+          addTags: result.data.add ?? [],
+          removeTags: result.data.remove ?? [],
+        });
 
     if (result.data.action === 'ARCHIVE') {
       return reply.send({ data: inventoryItems.map(toAdminInventoryItemDto) });
     }
 
+    if (result.data.action === 'TAGS') return reply.send({ data: inventoryItems });
+
     return reply.code(202).send({
       data: inventoryItems.map(({ id, status, createdAt }) => ({ id, status, createdAt })),
     });

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

@@ -68,5 +68,13 @@ export function createInventoryItemService({
         conditionId: item.conditionId,
       })));
     },
+
+    async updateTagsMany({ inventoryItemIds, sellerId, addTags = [], removeTags = [] }) {
+      const items = await inventoryItemRepository.listBySellerId(sellerId);
+      if (items.filter(({ id }) => inventoryItemIds.includes(id)).length !== inventoryItemIds.length) {
+        throw createApplicationError('INVENTORY_NOT_FOUND', 'One or more inventory items were not found.', 404);
+      }
+      return inventoryItemRepository.updateProductTagsByIdsForSeller(inventoryItemIds, sellerId, addTags, removeTags);
+    },
   };
 }

apps/api/src/modules/listings/repositories/listing-repository.js

@@ -125,6 +125,7 @@ export function createListingRepository(db) {
                   ilike(products.description, `%${term}%`),
                   ilike(products.setName, `%${term}%`),
                   ilike(products.brand, `%${term}%`),
+                  sql`${products.tags}::text ILIKE ${`%${term}%`}`,
                 ),
               ),
             ),

apps/api/src/modules/products/domain/product.js

@@ -6,11 +6,13 @@ function requiredText(value, fieldName) {
   return value.trim();
 }
 
-export function createProduct({ name, categoryId, sellerId }) {
+export function createProduct({ name, categoryId, sellerId, tags = [] }) {
+  const normalizedTags = [...new Set(tags.map((tag) => tag.trim().toLowerCase()))];
   return {
     name: requiredText(name, 'Product name'),
     categoryId: requiredText(categoryId, 'Category ID'),
     sellerId: requiredText(sellerId, 'Seller ID'),
+    tags: normalizedTags,
   };
 }
 

apps/api/tests/application/inventory-item-service.test.js

@@ -113,6 +113,34 @@ test('enqueues pricing refresh jobs for owned inventory items', async () => {
   assert.deepEqual(jobs, [{ id: 'job-1', status: 'PENDING' }]);
 });
 
+test('updates Product tags for selected owned inventory items', async () => {
+  const updates = [];
+  const service = createInventoryItemService({
+    productRepository: { async findById() { return null; } },
+    conditionRepository: { async findById() { return null; } },
+    inventoryItemRepository: {
+      async listBySellerId() {
+        return [
+          { id: 'item-1', productId: 'product-1', conditionId: 'condition-1' },
+          { id: 'item-2', productId: 'product-1', conditionId: 'condition-1' },
+        ];
+      },
+      async updateProductTagsByIdsForSeller(...input) {
+        updates.push(input);
+        return [{ id: 'product-1', tags: ['binder', 'keep'] }];
+      },
+    },
+  });
+
+  assert.deepEqual(await service.updateTagsMany({
+    inventoryItemIds: ['item-1', 'item-2'],
+    sellerId: 'seller-id',
+    addTags: ['Binder'],
+    removeTags: ['sell'],
+  }), [{ id: 'product-1', tags: ['binder', 'keep'] }]);
+  assert.deepEqual(updates, [[['item-1', 'item-2'], 'seller-id', ['Binder'], ['sell']]]);
+});
+
 test('rejects conditions from another category', async () => {
   const service = createService({
     product: { id: 'product-id', sellerId: 'seller-id', categoryId: 'cards' },

apps/api/tests/domain/product.test.js

@@ -14,6 +14,7 @@ test('creates a product with required product identity fields', () => {
     name: 'Charizard ex',
     categoryId: 'category-id',
     sellerId: 'seller-id',
+    tags: [],
   });
 });
 

apps/api/tests/http/admin-product-routes.test.js

@@ -69,6 +69,9 @@ function createTestApp({ authenticateAdmin, authorizeUnsafeRequest, pricingServi
             return item;
           });
         },
+        async updateProductTagsByIdsForSeller() {
+          return [];
+        },
       },
       pricingService,
     }),
@@ -248,6 +251,44 @@ test('enqueues selected inventory pricing refreshes through the bulk route', asy
   assert.equal(response.json().data[0].status, 'PENDING');
 });
 
+test('updates Product tags through the authenticated bulk route', async (testContext) => {
+  const app = createTestApp({
+    authenticateAdmin: async () => ({ sellerId: 'b078adf4-6a91-4b3d-a263-740246c11e3f' }),
+  });
+  testContext.after(() => app.close());
+
+  const productResponse = await app.inject({
+    method: 'POST',
+    url: '/api/v1/admin/products',
+    payload: {
+      name: 'Pikachu Plush',
+      categoryId: 'ab8150c7-96c1-4b55-8d69-7d0b77d48958',
+      tags: ['Keep'],
+    },
+  });
+  await app.inject({
+    method: 'POST',
+    url: '/api/v1/admin/inventory',
+    payload: {
+      productId: productResponse.json().data.id,
+      conditionId: '21eb218b-7a95-4f80-a9e3-e306f7ca1f2e',
+    },
+  });
+  const response = await app.inject({
+    method: 'POST',
+    url: '/api/v1/admin/bulk',
+    payload: {
+      action: 'TAGS',
+      inventoryItemIds: ['8a0a836a-a597-454d-8c5e-e146d27dbbf2'],
+      add: ['Binder'],
+      remove: ['sell'],
+    },
+  });
+
+  assert.equal(response.statusCode, 200);
+  assert.deepEqual(response.json().data, []);
+});
+
 test('rejects an authenticated product write without a CSRF token', async (testContext) => {
   const app = createTestApp({
     authenticateAdmin: async () => ({ sellerId: 'b078adf4-6a91-4b3d-a263-740246c11e3f' }),

apps/api/tests/http/public-product-routes.test.js

@@ -50,6 +50,7 @@ test('returns a public product without private seller identity', async (testCont
     cardNumber: null,
     eventName: null,
     releaseYear: null,
+    tags: [],
     createdAt: '2026-09-07T00:00:00.000Z',
     updatedAt: '2026-09-07T00:00:00.000Z',
   });

apps/web/src/pages/AdminHomePage.stories.js

@@ -46,3 +46,14 @@ export const InventoryCsvExport = {
     },
   },
 };
+
+export const BulkTagSelection = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The admin workspace supports adding or removing Product tags for selected physical copies.",
+      },
+    },
+  },
+};

apps/web/src/pages/AdminHomePage.vue

@@ -13,6 +13,7 @@ import {
   listAdminInventory,
   listAdminProducts,
   refreshAdminInventoryPricing,
+  updateAdminInventoryTags,
 } from "@/services/admin-catalog-service.js";
 import {
   createAdminListing,
@@ -50,6 +51,7 @@ const { principal } = useAuth();
 const products = ref([]);
 const inventory = ref([]);
 const selectedInventoryIds = ref([]);
+const inventoryTags = ref("");
 const listings = ref([]);
 const sales = ref([]);
 const acquisitions = ref([]);
@@ -232,6 +234,26 @@ async function refreshSelectedPricing() {
   }
 }
 
+async function updateSelectedTags(action) {
+  const tags = inventoryTags.value.split(",").map((tag) => tag.trim()).filter(Boolean);
+  if (!selectedInventoryIds.value.length || !tags.length) return;
+  isSaving.value = true;
+  try {
+    await updateAdminInventoryTags(
+      selectedInventoryIds.value,
+      action === "add" ? tags : [],
+      action === "remove" ? tags : [],
+      csrfToken(),
+    );
+    inventoryTags.value = "";
+    selectedInventoryIds.value = [];
+  } catch (requestError) {
+    error.value = requestError;
+  } finally {
+    isSaving.value = false;
+  }
+}
+
 async function createListing() {
   const item = inventory.value.find(
     (candidate) => candidate.id === listingInventoryId.value,
@@ -999,6 +1021,29 @@ onMounted(load);
         >
           Refresh pricing
         </button>
+        <input
+          v-model="inventoryTags"
+          class="fixture-input"
+          type="text"
+          placeholder="Tags, comma separated"
+          aria-label="Tags to add or remove"
+        />
+        <button
+          class="button button--secondary"
+          type="button"
+          :disabled="isSaving || !selectedInventoryIds.length || !inventoryTags.trim()"
+          @click="updateSelectedTags('add')"
+        >
+          Add tags
+        </button>
+        <button
+          class="button button--secondary"
+          type="button"
+          :disabled="isSaving || !selectedInventoryIds.length || !inventoryTags.trim()"
+          @click="updateSelectedTags('remove')"
+        >
+          Remove tags
+        </button>
       </div>
       <p v-if="!inventory.length && !isLoading" class="state state--empty">
         No physical copies yet.

apps/web/src/services/admin-catalog-service.js

@@ -38,4 +38,12 @@ export function refreshAdminInventoryPricing(inventoryItemIds, providerId, csrfT
     headers: { 'x-csrf-token': csrfToken },
     body: JSON.stringify({ action: 'PRICING_REFRESH', inventoryItemIds, providerId }),
   });
+}
+
+export function updateAdminInventoryTags(inventoryItemIds, add, remove, csrfToken) {
+  return request('/admin/bulk', {
+    method: 'POST',
+    headers: { 'x-csrf-token': csrfToken },
+    body: JSON.stringify({ action: 'TAGS', inventoryItemIds, add, remove }),
+  });
 }

apps/web/tests/catalog-service.test.js

@@ -92,4 +92,28 @@ test('enqueues selected admin inventory pricing refreshes through the bulk API',
   } finally {
     globalThis.fetch = originalFetch;
   }
+});
+
+test('updates selected admin inventory tags through the bulk API', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async (url, options) => {
+    assert.equal(url, '/api/v1/admin/bulk');
+    assert.equal(options.method, 'POST');
+    assert.deepEqual(JSON.parse(options.body), {
+      action: 'TAGS',
+      inventoryItemIds: ['item-1'],
+      add: ['binder'],
+      remove: [],
+    });
+    return { ok: true, async json() { return { data: [{ id: 'product-1', tags: ['binder'] }] }; } };
+  };
+
+  try {
+    const { updateAdminInventoryTags } = await import('../src/services/admin-catalog-service.js');
+    assert.deepEqual(await updateAdminInventoryTags(['item-1'], ['binder'], [], 'csrf-token'), [
+      { id: 'product-1', tags: ['binder'] },
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
 });

database/migrations/0022_product_tags.sql

@@ -0,0 +1 @@
+ALTER TABLE "products" ADD COLUMN "tags" text[] DEFAULT ARRAY[]::text[] NOT NULL;

database/migrations/meta/_journal.json

@@ -148,6 +148,20 @@
       "when": 1790323200000,
       "tag": "0020_pricing_job_mapping_context",
       "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1790409600000,
+      "tag": "0021_pricing_observation_mapping_context",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1790496000000,
+      "tag": "0022_product_tags",
+      "breakpoints": true
     }
   ]
 }

docs/API.md

@@ -96,6 +96,8 @@ POST   /api/v1/admin/inventory/:id/valuation/override
 POST   /api/v1/admin/inventory/:id/pricing/refresh
 POST   /api/v1/admin/bulk
 
+`POST /api/v1/admin/bulk` supports `ARCHIVE`, `PRICING_REFRESH`, and `TAGS` actions. `TAGS` accepts `add` and/or `remove` arrays and applies labels to the selected items' Products.
+
 GET    /api/v1/admin/dashboard
 GET    /api/v1/admin/exports/inventory.json
 GET    /api/v1/admin/exports/inventory.csv

docs/IMPLEMENTATION-STATUS.md

@@ -148,7 +148,7 @@ Remaining roadmap areas are bulk status/tag/pricing actions, richer exports/sett
 - Pricing refresh enqueue now resolves its provider from an active Product mapping and rejects unmapped Products explicitly.
 - Local development and CI can enable a deterministic fixture provider for end-to-end refresh coverage; production provider adapters remain explicitly configured deployment boundaries.
 - Pricing refresh jobs have a bounded three-attempt retry policy with exponential backoff. The worker schedules completed-job cleanup using configurable retention days and cleanup interval settings.
-- Bulk archive and asynchronous bulk pricing refresh are implemented through the seller-scoped API boundary; bulk status changes and tags remain.
+- Bulk archive, asynchronous bulk pricing refresh, and Product-level bulk tag updates are implemented through the seller-scoped API boundary; bulk status changes remain.
 - Admin inventory JSON export is implemented at `GET /api/v1/admin/exports/inventory.json` and serializes seller-scoped admin DTOs as a downloadable attachment.
 - Admin inventory CSV export is implemented at `GET /api/v1/admin/exports/inventory.csv` with escaped spreadsheet-safe fields and seller-scoped admin DTOs.
 - PostgreSQL restore verification and image snapshot restore scripts are implemented and covered by shell tests as part of the deployment drill workflow.

packages/contracts/product.js

@@ -15,6 +15,7 @@ export function toAdminProductDto(product) {
     cardNumber: product.cardNumber ?? null,
     eventName: product.eventName ?? null,
     releaseYear: product.releaseYear ?? null,
+    tags: product.tags ?? [],
     createdAt: toIsoString(product.createdAt),
     updatedAt: toIsoString(product.updatedAt),
   };

packages/contracts/public-product.js

@@ -14,6 +14,7 @@ export function toPublicProductDto(product) {
     cardNumber: product.cardNumber ?? null,
     eventName: product.eventName ?? null,
     releaseYear: product.releaseYear ?? null,
+    tags: product.tags ?? [],
     createdAt: toIsoString(product.createdAt),
     updatedAt: toIsoString(product.updatedAt),
   };

packages/validation/inventory.js

@@ -23,7 +23,21 @@ export const bulkPricingRefreshInventorySchema = z
   })
   .strict();
 
+export const bulkTagInventorySchema = z
+  .object({
+    action: z.literal('TAGS'),
+    inventoryItemIds: z.array(z.uuid()).min(1).max(100),
+    add: z.array(z.string().trim().min(1).max(100)).max(50).optional(),
+    remove: z.array(z.string().trim().min(1).max(100)).max(50).optional(),
+  })
+  .strict()
+  .refine(({ add, remove }) => (add?.length ?? 0) > 0 || (remove?.length ?? 0) > 0, {
+    message: 'Add or remove at least one tag.',
+    path: ['add'],
+  });
+
 export const bulkInventorySchema = z.discriminatedUnion('action', [
   bulkArchiveInventorySchema,
   bulkPricingRefreshInventorySchema,
+  bulkTagInventorySchema,
 ]);

packages/validation/product.js

@@ -6,5 +6,6 @@ export const createProductSchema = z
   .object({
     name: z.string().trim().min(1).max(255),
     categoryId: identifier,
+    tags: z.array(z.string().trim().min(1).max(100)).max(50).optional(),
   })
   .strict();