Refactor all list APIs for server-side pagination, search, and sort

All list endpoints now return paginated responses:
  { data: [...], pagination: { page, limit, total, totalPages } }

Query params: ?page=1&limit=25&q=search&sort=name&order=asc

Changes:
- Added PaginationSchema in @forte/shared for consistent param parsing
- Added pagination utils (withPagination, withSort, buildSearchCondition,
  paginatedResponse) in backend
- Refactored all services: AccountService, MemberService, CategoryService,
  SupplierService, ProductService, InventoryUnitService
- Merged separate /search endpoints into list endpoints via ?q= param
- Removed AccountSearchSchema and ProductSearchSchema (replaced by
  PaginationSchema)
- Added pagination test (5 items, page 1 limit 2, expect totalPages=3)
- Updated CLAUDE.md with API conventions
- 34 tests passing

packages/backend/src/routes/v1/accounts.test.ts

@@ -84,11 +84,13 @@ describe('Account routes', () => {
 
       expect(response.statusCode).toBe(200)
       const body = response.json()
-      expect(body.length).toBe(2)
+      expect(body.data.length).toBe(2)
+      expect(body.pagination.total).toBe(2)
+      expect(body.pagination.page).toBe(1)
     })
   })
 
-  describe('GET /v1/accounts/search', () => {
+  describe('GET /v1/accounts?q=', () => {
     it('searches by name', async () => {
       await app.inject({
         method: 'POST',
@@ -105,14 +107,14 @@ describe('Account routes', () => {
 
       const response = await app.inject({
         method: 'GET',
-        url: '/v1/accounts/search?q=johnson',
+        url: '/v1/accounts?q=johnson',
         headers: { authorization: `Bearer ${token}` },
       })
 
       expect(response.statusCode).toBe(200)
       const body = response.json()
-      expect(body.length).toBe(1)
-      expect(body[0].name).toBe('Johnson Family')
+      expect(body.data.length).toBe(1)
+      expect(body.data[0].name).toBe('Johnson Family')
     })
 
     it('searches by phone', async () => {
@@ -125,12 +127,35 @@ describe('Account routes', () => {
 
       const response = await app.inject({
         method: 'GET',
-        url: '/v1/accounts/search?q=867-5309',
+        url: '/v1/accounts?q=867-5309',
         headers: { authorization: `Bearer ${token}` },
       })
 
       expect(response.statusCode).toBe(200)
-      expect(response.json().length).toBe(1)
+      expect(response.json().data.length).toBe(1)
+    })
+
+    it('paginates results', async () => {
+      for (let i = 0; i < 5; i++) {
+        await app.inject({
+          method: 'POST',
+          url: '/v1/accounts',
+          headers: { authorization: `Bearer ${token}` },
+          payload: { name: `Account ${i}` },
+        })
+      }
+
+      const response = await app.inject({
+        method: 'GET',
+        url: '/v1/accounts?page=1&limit=2',
+        headers: { authorization: `Bearer ${token}` },
+      })
+
+      const body = response.json()
+      expect(body.data.length).toBe(2)
+      expect(body.pagination.total).toBe(5)
+      expect(body.pagination.totalPages).toBe(3)
+      expect(body.pagination.page).toBe(1)
     })
   })
 
@@ -180,7 +205,7 @@ describe('Account routes', () => {
         url: '/v1/accounts',
         headers: { authorization: `Bearer ${token}` },
       })
-      expect(listRes.json().length).toBe(0)
+      expect(listRes.json().data.length).toBe(0)
     })
   })
 })
@@ -274,7 +299,7 @@ describe('Member routes', () => {
       })
 
       expect(response.statusCode).toBe(200)
-      expect(response.json().length).toBe(2)
+      expect(response.json().data.length).toBe(2)
     })
   })
 

packages/backend/src/routes/v1/accounts.ts

@@ -4,145 +4,94 @@ import {
   AccountUpdateSchema,
   MemberCreateSchema,
   MemberUpdateSchema,
-  AccountSearchSchema,
+  PaginationSchema,
 } from '@forte/shared/schemas'
 import { AccountService, MemberService } from '../../services/account.service.js'
 
 export const accountRoutes: FastifyPluginAsync = async (app) => {
   // --- Accounts ---
 
-  app.post(
-    '/accounts',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const parsed = AccountCreateSchema.safeParse(request.body)
-      if (!parsed.success) {
-        return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
-      }
-      const account = await AccountService.create(app.db, request.companyId, parsed.data)
-      return reply.status(201).send(account)
-    },
-  )
+  app.post('/accounts', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const parsed = AccountCreateSchema.safeParse(request.body)
+    if (!parsed.success) {
+      return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
+    }
+    const account = await AccountService.create(app.db, request.companyId, parsed.data)
+    return reply.status(201).send(account)
+  })
 
-  app.get(
-    '/accounts',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const accounts = await AccountService.list(app.db, request.companyId)
-      return reply.send(accounts)
-    },
-  )
+  app.get('/accounts', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const params = PaginationSchema.parse(request.query)
+    const result = await AccountService.list(app.db, request.companyId, params)
+    return reply.send(result)
+  })
 
-  app.get(
-    '/accounts/search',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const parsed = AccountSearchSchema.safeParse(request.query)
-      if (!parsed.success) {
-        return reply.status(400).send({ error: { message: 'Query parameter q is required', statusCode: 400 } })
-      }
-      const results = await AccountService.search(app.db, request.companyId, parsed.data.q)
-      return reply.send(results)
-    },
-  )
+  app.get('/accounts/:id', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const { id } = request.params as { id: string }
+    const account = await AccountService.getById(app.db, request.companyId, id)
+    if (!account) return reply.status(404).send({ error: { message: 'Account not found', statusCode: 404 } })
+    return reply.send(account)
+  })
 
-  app.get(
-    '/accounts/:id',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const { id } = request.params as { id: string }
-      const account = await AccountService.getById(app.db, request.companyId, id)
-      if (!account) return reply.status(404).send({ error: { message: 'Account not found', statusCode: 404 } })
-      return reply.send(account)
-    },
-  )
+  app.patch('/accounts/:id', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const { id } = request.params as { id: string }
+    const parsed = AccountUpdateSchema.safeParse(request.body)
+    if (!parsed.success) {
+      return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
+    }
+    const account = await AccountService.update(app.db, request.companyId, id, parsed.data)
+    if (!account) return reply.status(404).send({ error: { message: 'Account not found', statusCode: 404 } })
+    return reply.send(account)
+  })
 
-  app.patch(
-    '/accounts/:id',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const { id } = request.params as { id: string }
-      const parsed = AccountUpdateSchema.safeParse(request.body)
-      if (!parsed.success) {
-        return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
-      }
-      const account = await AccountService.update(app.db, request.companyId, id, parsed.data)
-      if (!account) return reply.status(404).send({ error: { message: 'Account not found', statusCode: 404 } })
-      return reply.send(account)
-    },
-  )
-
-  app.delete(
-    '/accounts/:id',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const { id } = request.params as { id: string }
-      const account = await AccountService.softDelete(app.db, request.companyId, id)
-      if (!account) return reply.status(404).send({ error: { message: 'Account not found', statusCode: 404 } })
-      return reply.send(account)
-    },
-  )
+  app.delete('/accounts/:id', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const { id } = request.params as { id: string }
+    const account = await AccountService.softDelete(app.db, request.companyId, id)
+    if (!account) return reply.status(404).send({ error: { message: 'Account not found', statusCode: 404 } })
+    return reply.send(account)
+  })
 
   // --- Members ---
 
-  app.post(
-    '/accounts/:accountId/members',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const { accountId } = request.params as { accountId: string }
-      const parsed = MemberCreateSchema.safeParse({ ...request.body as object, accountId })
-      if (!parsed.success) {
-        return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
-      }
-      const member = await MemberService.create(app.db, request.companyId, parsed.data)
-      return reply.status(201).send(member)
-    },
-  )
+  app.post('/accounts/:accountId/members', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const { accountId } = request.params as { accountId: string }
+    const parsed = MemberCreateSchema.safeParse({ ...(request.body as object), accountId })
+    if (!parsed.success) {
+      return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
+    }
+    const member = await MemberService.create(app.db, request.companyId, parsed.data)
+    return reply.status(201).send(member)
+  })
 
-  app.get(
-    '/accounts/:accountId/members',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const { accountId } = request.params as { accountId: string }
-      const membersList = await MemberService.listByAccount(app.db, request.companyId, accountId)
-      return reply.send(membersList)
-    },
-  )
+  app.get('/accounts/:accountId/members', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const { accountId } = request.params as { accountId: string }
+    const params = PaginationSchema.parse(request.query)
+    const result = await MemberService.listByAccount(app.db, request.companyId, accountId, params)
+    return reply.send(result)
+  })
 
-  app.get(
-    '/members/:id',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const { id } = request.params as { id: string }
-      const member = await MemberService.getById(app.db, request.companyId, id)
-      if (!member) return reply.status(404).send({ error: { message: 'Member not found', statusCode: 404 } })
-      return reply.send(member)
-    },
-  )
+  app.get('/members/:id', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const { id } = request.params as { id: string }
+    const member = await MemberService.getById(app.db, request.companyId, id)
+    if (!member) return reply.status(404).send({ error: { message: 'Member not found', statusCode: 404 } })
+    return reply.send(member)
+  })
 
-  app.patch(
-    '/members/:id',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const { id } = request.params as { id: string }
-      const parsed = MemberUpdateSchema.safeParse(request.body)
-      if (!parsed.success) {
-        return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
-      }
-      const member = await MemberService.update(app.db, request.companyId, id, parsed.data)
-      if (!member) return reply.status(404).send({ error: { message: 'Member not found', statusCode: 404 } })
-      return reply.send(member)
-    },
-  )
+  app.patch('/members/:id', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const { id } = request.params as { id: string }
+    const parsed = MemberUpdateSchema.safeParse(request.body)
+    if (!parsed.success) {
+      return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
+    }
+    const member = await MemberService.update(app.db, request.companyId, id, parsed.data)
+    if (!member) return reply.status(404).send({ error: { message: 'Member not found', statusCode: 404 } })
+    return reply.send(member)
+  })
 
-  app.delete(
-    '/members/:id',
-    { preHandler: [app.authenticate] },
-    async (request, reply) => {
-      const { id } = request.params as { id: string }
-      const member = await MemberService.delete(app.db, request.companyId, id)
-      if (!member) return reply.status(404).send({ error: { message: 'Member not found', statusCode: 404 } })
-      return reply.send(member)
-    },
-  )
+  app.delete('/members/:id', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const { id } = request.params as { id: string }
+    const member = await MemberService.delete(app.db, request.companyId, id)
+    if (!member) return reply.status(404).send({ error: { message: 'Member not found', statusCode: 404 } })
+    return reply.send(member)
+  })
 }

packages/backend/src/routes/v1/inventory.test.ts

@@ -81,8 +81,8 @@ describe('Category routes', () => {
 
     expect(response.statusCode).toBe(200)
     const body = response.json()
-    expect(body.length).toBe(2)
-    expect(body[0].name).toBe('Aaa First')
+    expect(body.data.length).toBe(2)
+    expect(body.data[0].name).toBe('Aaa First')
   })
 
   it('soft-deletes a category', async () => {
@@ -105,7 +105,7 @@ describe('Category routes', () => {
       url: '/v1/categories',
       headers: { authorization: `Bearer ${token}` },
     })
-    expect(listRes.json().length).toBe(0)
+    expect(listRes.json().data.length).toBe(0)
   })
 })
 
@@ -162,13 +162,13 @@ describe('Supplier routes', () => {
 
     const response = await app.inject({
       method: 'GET',
-      url: '/v1/suppliers/search?q=ferree',
+      url: '/v1/suppliers?q=ferree',
       headers: { authorization: `Bearer ${token}` },
     })
 
     expect(response.statusCode).toBe(200)
-    expect(response.json().length).toBe(1)
-    expect(response.json()[0].name).toBe("Ferree's Tools")
+    expect(response.json().data.length).toBe(1)
+    expect(response.json().data[0].name).toBe("Ferree's Tools")
   })
 
   it('updates a supplier', async () => {

packages/backend/src/routes/v1/inventory.ts

@@ -4,6 +4,7 @@ import {
   CategoryUpdateSchema,
   SupplierCreateSchema,
   SupplierUpdateSchema,
+  PaginationSchema,
 } from '@forte/shared/schemas'
 import { CategoryService, SupplierService } from '../../services/inventory.service.js'
 
@@ -20,8 +21,9 @@ export const inventoryRoutes: FastifyPluginAsync = async (app) => {
   })
 
   app.get('/categories', { preHandler: [app.authenticate] }, async (request, reply) => {
-    const list = await CategoryService.list(app.db, request.companyId)
-    return reply.send(list)
+    const params = PaginationSchema.parse(request.query)
+    const result = await CategoryService.list(app.db, request.companyId, params)
+    return reply.send(result)
   })
 
   app.get('/categories/:id', { preHandler: [app.authenticate] }, async (request, reply) => {
@@ -61,15 +63,9 @@ export const inventoryRoutes: FastifyPluginAsync = async (app) => {
   })
 
   app.get('/suppliers', { preHandler: [app.authenticate] }, async (request, reply) => {
-    const list = await SupplierService.list(app.db, request.companyId)
-    return reply.send(list)
-  })
-
-  app.get('/suppliers/search', { preHandler: [app.authenticate] }, async (request, reply) => {
-    const { q } = request.query as { q?: string }
-    if (!q) return reply.status(400).send({ error: { message: 'Query parameter q is required', statusCode: 400 } })
-    const results = await SupplierService.search(app.db, request.companyId, q)
-    return reply.send(results)
+    const params = PaginationSchema.parse(request.query)
+    const result = await SupplierService.list(app.db, request.companyId, params)
+    return reply.send(result)
   })
 
   app.get('/suppliers/:id', { preHandler: [app.authenticate] }, async (request, reply) => {

packages/backend/src/routes/v1/products.test.ts

@@ -85,24 +85,24 @@ describe('Product routes', () => {
 
     const byName = await app.inject({
       method: 'GET',
-      url: '/v1/products/search?q=stratocaster',
+      url: '/v1/products?q=stratocaster',
       headers: { authorization: `Bearer ${token}` },
     })
-    expect(byName.json().length).toBe(1)
+    expect(byName.json().data.length).toBe(1)
 
     const bySku = await app.inject({
       method: 'GET',
-      url: '/v1/products/search?q=GTR-GIB',
+      url: '/v1/products?q=GTR-GIB',
       headers: { authorization: `Bearer ${token}` },
     })
-    expect(bySku.json().length).toBe(1)
+    expect(bySku.json().data.length).toBe(1)
 
     const byBrand = await app.inject({
       method: 'GET',
-      url: '/v1/products/search?q=fender',
+      url: '/v1/products?q=fender',
       headers: { authorization: `Bearer ${token}` },
     })
-    expect(byBrand.json().length).toBe(1)
+    expect(byBrand.json().data.length).toBe(1)
   })
 
   it('logs price change on update', async () => {
@@ -196,7 +196,7 @@ describe('Inventory unit routes', () => {
     })
 
     expect(response.statusCode).toBe(200)
-    expect(response.json().length).toBe(2)
+    expect(response.json().data.length).toBe(2)
   })
 
   it('updates unit status and condition', async () => {

packages/backend/src/routes/v1/products.ts

@@ -2,9 +2,9 @@ import type { FastifyPluginAsync } from 'fastify'
 import {
   ProductCreateSchema,
   ProductUpdateSchema,
-  ProductSearchSchema,
   InventoryUnitCreateSchema,
   InventoryUnitUpdateSchema,
+  PaginationSchema,
 } from '@forte/shared/schemas'
 import { ProductService, InventoryUnitService } from '../../services/product.service.js'
 
@@ -21,17 +21,9 @@ export const productRoutes: FastifyPluginAsync = async (app) => {
   })
 
   app.get('/products', { preHandler: [app.authenticate] }, async (request, reply) => {
-    const list = await ProductService.list(app.db, request.companyId)
-    return reply.send(list)
-  })
-
-  app.get('/products/search', { preHandler: [app.authenticate] }, async (request, reply) => {
-    const parsed = ProductSearchSchema.safeParse(request.query)
-    if (!parsed.success) {
-      return reply.status(400).send({ error: { message: 'Query parameter q is required', statusCode: 400 } })
-    }
-    const results = await ProductService.search(app.db, request.companyId, parsed.data.q)
-    return reply.send(results)
+    const params = PaginationSchema.parse(request.query)
+    const result = await ProductService.list(app.db, request.companyId, params)
+    return reply.send(result)
   })
 
   app.get('/products/:id', { preHandler: [app.authenticate] }, async (request, reply) => {
@@ -47,7 +39,7 @@ export const productRoutes: FastifyPluginAsync = async (app) => {
     if (!parsed.success) {
       return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
     }
-    const product = await ProductService.update(app.db, request.companyId, id, parsed.data)
+    const product = await ProductService.update(app.db, request.companyId, id, parsed.data, request.user.id)
     if (!product) return reply.status(404).send({ error: { message: 'Product not found', statusCode: 404 } })
     return reply.send(product)
   })
@@ -73,8 +65,9 @@ export const productRoutes: FastifyPluginAsync = async (app) => {
 
   app.get('/products/:productId/units', { preHandler: [app.authenticate] }, async (request, reply) => {
     const { productId } = request.params as { productId: string }
-    const units = await InventoryUnitService.listByProduct(app.db, request.companyId, productId)
-    return reply.send(units)
+    const params = PaginationSchema.parse(request.query)
+    const result = await InventoryUnitService.listByProduct(app.db, request.companyId, productId, params)
+    return reply.send(result)
   })
 
   app.get('/units/:id', { preHandler: [app.authenticate] }, async (request, reply) => {