feat(notifications): add cursor pagination for notifications endpoint

[Ova-Klik]

Summary

This PR implements stable cursor-based pagination for the /api/notifications endpoint using the (created_at, id) cursor to ensure deterministic ordering, even under concurrent writes.

Changes

• Implement cursor pagination for GET /api/notifications

• Use (created_at, id) as the pagination cursor for stable ordering

• Preserve existing API behavior where applicable

• Add focused tests covering:

  • Cursor generation and parsing
  • Forward pagination
  • Stable ordering when timestamps are identical
  • Concurrent insert scenarios
  • Pagination boundary conditions

• Update API documentation to describe the new pagination behavior

• Ensure request validation, standardized error responses, and structured logging remain consistent with project conventions

Closes #636

summary

Offset-based pagination can produce duplicate or missing records when new notifications are created while clients are paginating. Cursor pagination using (created_at, id) provides deterministic, stable pagination and eliminates these consistency issues.

API Changes

New Query Parameters

• cursor – Opaque cursor representing the last (created_at, id) pair from the previous page.
• limit – Number of notifications to return (existing/default limits preserved where applicable).

Response

The endpoint now returns a cursor for retrieving the next page of notifications.

Testing

• Added unit and/or integration tests for cursor pagination
• Verified stable ordering with identical timestamps
• Verified pagination across multiple pages
• Verified behavior under concurrent inserts
• Confirmed existing notification functionality remains unaffected

Checklist

• Cursor pagination implemented
• Tests added
• Documentation updated
• Lint passes
• Existing tests pass

[drips-wave]

@Ova-Klik 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

[greatest0fallt1me]

Looks good — merging. Thanks for the contribution!