feat: add GET /creators/:id/holders endpoint

[Temi-suwa18]

Summary

Closes #422

Adds GET /api/v1/creators/:id/holders — a paginated endpoint that lets creators see which wallets hold their keys, the current balance for each holder, and when they first bought (for loyalty sorting).

• Accepts creator cuid id or handle as the :id param
• Returns 404 if the creator does not exist
• Returns empty items: [] (not 404) if creator exists but has no holders
• Default sort: key_balance descending (largest holders first)
• ?sort=held_since returns earliest buyers first (KeyOwnership.createdAt ascending)
• held_since is derived from KeyOwnership.createdAt — the timestamp when the ownership row is first created, which corresponds to the wallet's first buy for that creator
• Standard offset pagination (limit / offset) with meta.hasMore
• 5-minute public cache via existing cache preset infrastructure

Response shape

{
  "success": true,
  "data": {
    "items": [
      {
        "wallet_address": "GABC...",
        "key_balance": 5,
        "held_since": "2024-03-01T00:00:00.000Z"
      }
    ],
    "meta": { "limit": 20, "offset": 0, "total": 1, "hasMore": false }
  }
}

Files changed

File	Change
src/modules/creators/creator-holders.schemas.ts	Zod query schema (limit, offset, sort)
src/modules/creators/creator-holders.service.ts	findCreatorByIdOrHandle + fetchCreatorHolders
src/modules/creators/creator-holders.controller.ts	httpGetCreatorHolders handler
src/modules/creators/creator-holders.integration.test.ts	9 integration tests (mock-based, no DB)
src/modules/creators/creators.routes.ts	Register GET /:id/holders + 405 handler
src/constants/creator-public-routes.constants.ts	GET_HOLDERS route name constant
src/constants/creator-public-cache.constants.ts	Cache preset for holders route

Test plan

• Returns 404 when creator does not exist
• Returns empty list (not 404) when creator exists but has no holders
• Returns holders sorted by key_balance desc by default
• ?sort=held_since passes correct sort to service
• Pagination meta (hasMore, total, limit, offset) is correct
• hasMore=false on the last page
• Each item has wallet_address, key_balance, held_since
• Returns 400 for unknown query params (strict schema)
• Returns 400 for invalid sort value
• next(error) is called on service exception

🤖 Generated with Claude Code