feat(backend): standardize pagination and cursor validation across list endpoints

[Belzabeem]

Closes #641

Summary

This PR implements shared pagination helpers that enforce consistent cursor validation and error responses across all list endpoints, bringing them in line with the rigor already present in subscription services.

Changes

• backend/src/utils/pagination.ts (new) - Shared pagination utilities

  • validateCursor() - Validates base64-encoded cursor with created_at field, throws MALFORMED_CURSOR or INVALID_CURSOR errors
  • validateLimit() - Validates limit parameter (1-100 range), throws INVALID_LIMIT error
  • encodeCursor() - Encodes cursor data to base64
  • PaginationError - Custom error class with error codes
  • cursorPaginationSchema - Zod schema for cursor-based pagination validation

• backend/src/schemas/common.ts - Added cursorPaginationSchema for reusable validation

• backend/src/services/subscription-service.ts - Updated to use shared validateCursor and encodeCursor helpers

• backend/src/routes/subscriptions.ts - Uses shared pagination validation with proper error handling

• backend/src/routes/merchants.ts - Added PaginationError handling for consistent error responses

• backend/src/routes/audit.ts - Added PaginationError handling for consistent error responses

• backend/src/routes/gift-card-ledger.ts - Uses validateLimit for limit validation

• backend/tests/pagination.test.ts (new) - 28 tests covering all pagination utilities

• backend/tests/subscription-service.test.ts - Updated tests for cursor-based pagination

• backend/SUBSCRIPTION_API.md - Updated documentation with cursor pagination semantics

Error Codes

All pagination errors now return consistent structured responses:

• INVALID_CURSOR - The cursor is malformed or cannot be decoded
• MALFORMED_CURSOR - The cursor is missing required created_at field
• INVALID_LIMIT - The limit parameter is out of range or not a valid integer

Tests

All 35 pagination-related tests pass:

• validateCursor: 9 tests
• validateLimit: 12 tests
• encodeCursor: 2 tests
• cursorPaginationSchema: 5 tests
• listSubscriptions integration: 7 tests

Checklist

• Shared pagination helpers exist
• Invalid cursors and limits return consistent errors
• Tests added/updated and passing
• Documentation updated
• No security regressions introduced

[drips-wave]

@Belzabeem 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