Integration Test for Holder Sorting, Idempotency Middleware, and Price Alert Docs

[testersweb]

Summary

This PR addresses three key backlog items that enhance API stability, improve developer experience, and ensure correctness of our data retrieval routes. It introduces a comprehensive integration test for the creator holders endpoint, idempotency guarantees for mutation endpoints, and explicit payload documentation for our price alerts feature.

Changes Implemented

1. Creator Holders Sorting Integration Test (#448)

• Context: The GET /creators/:id/holders endpoint accepts an optional sort parameter. While mocked unit tests exist, we needed a robust integration test that hits the database to guarantee that sorting correctly maps to the Prisma query ordering.
• Implementation:
  • Created src/__tests__/integration/creator-holders-sort.test.ts.
  • Added a seeding routine to populate a test creator with three distinct holders differing in both their key_balance and held_since (createdAt) timestamps.
  • Asserted that ?sort=held_since correctly applies the createdAt: 'asc' sorting criteria, returning the earliest buyer first.
  • Asserted that when no sort parameter is provided, the API defaults to sorting by balance: 'desc', returning the holder with the largest balance first.

2. Idempotency-Key Middleware (#133)

• Context: To prevent duplicate processing of mutations (e.g., retrying a failed checkout or double-clicking a submit button), mutation endpoints (POST/PUT/PATCH/DELETE) require idempotency support.
• Implementation:
  • Added optional idempotency-key support for write routes.
  • Designed the middleware to cache and replay successful duplicate requests safely without re-executing business logic.
  • Documented expected header behavior (Idempotency-Key) for API consumers so clients can begin integrating safe retries.

3. Price Alerts API Documentation (#446)

• Context: As we roll out the Price Alerts feature, external integrators and internal contributors need explicit documentation defining the request schema and webhook behaviors for POST /alerts.
• Implementation:
  • Fully documented all payload fields: creator_id, wallet_address, target_price, direction, and callback_url.
  • Added clear, plain-language definitions for the direction values (above and below).
  • Documented the one-shot delivery behavior: alerts are strictly deleted after their first successful delivery.
  • Provided a worked example of the request payload and the expected callback payload that will hit the provided webhook.

Testing and Validation

• Run pnpm test src/__tests__/integration/creator-holders-sort.test.ts to ensure DB sorting matches the specification.
• Verified idempotency caches correctly on duplicate POST requests.
• Verified documentation correctly renders and all types are accurate.

Related Issues

• Resolves Add integration test for key holders list sorted by held_since returning earliest buyer first #448
• Resolves Add idempotency-key middleware for mutation endpoints #133
• Resolves Add docs for price alert registration payload fields and direction values #446

[drips-wave]

@testersweb0-bug Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits