feat: implement recurring payment scheduler (#214)

[TEEZY234]

Pull Request: Implement Recurring Payment Scheduler

Closes #214

Summary

This PR implements a backend service for scheduling recurring Stellar payments (e.g., monthly subscriptions) with a cron-based worker to execute these automatically.

Changes Made

Database Schema

• Added RecurringPaymentSchedule model with fields for destination, asset code, amount, cron expression, status, and next run time
• Added RecurringPaymentRun model to track individual payment execution attempts with status, error tracking, and Stellar transaction ID
• Created Prisma migration for new tables with appropriate indexes and foreign keys

Service Layer

• Implemented RecurringPaymentsService with:
  • CRUD operations for schedules (create, list, get, update, delete)
  • Input validation for cron expressions, Stellar addresses, and amounts
  • processDueSchedules() method to find and execute due payments
  • Integration with existing BatchPaymentService for Stellar transactions
  • Automatic computation of next run times using cron-parser

API Layer

• Created recurring-payments.controller.ts with request handlers
• Added recurring-payments.route.ts with authenticated endpoints:
  • POST /api/recurring-payments - Create new schedule
  • GET /api/recurring-payments - List user's schedules
  • GET /api/recurring-payments/:id - Get specific schedule
  • PATCH /api/recurring-payments/:id - Update schedule
  • DELETE /api/recurring-payments/:id - Delete schedule
• Registered routes in main Express app under /api/recurring-payments
• Applied JWT authentication middleware and Zod validation

Worker

• Implemented recurring-payments.worker.ts using node-cron
• Configured via RECURRING_PAYMENTS_WORKER_CRON environment variable (default: */1 * * * *)
• Processes due schedules periodically and logs results

Configuration

• Added environment variables:
  • RECURRING_PAYMENTS_WORKER_CRON - Worker execution schedule
  • STELLAR_HORIZON_URL - Stellar Horizon server URL
  • STELLAR_NETWORK_PASSPHRASE - Network passphrase
  • STELLAR_DISTRIBUTION_SECRET - Distribution account secret key

Dependencies

• Added node-cron for scheduling
• Added cron-parser for cron expression parsing
• Added @types/node-cron for TypeScript support
• Added npm script start:worker:recurring-payments

Tests

• Added Jest tests for RecurringPaymentsService
• Added Jest tests for recurring payments routes

Bug Fixes

• Resolved merge conflicts in auth.service.ts (combined tracing and configService)
• Resolved merge conflicts in webhook.service.ts (combined imports and fixed deliver method)

Usage

Start the worker

npm run start:worker:recurring-payments

API Example

# Create a monthly payment schedule
curl -X POST https://api.example.com/api/recurring-payments \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "assetCode": "XLM",
    "amount": "10.0",
    "cron": "0 0 1 * *"
  }'

Notes

• The Prisma migration SQL file has been created but may need to be applied manually in production due to database state
• The broader codebase has pre-existing TypeScript build errors unrelated to this feature that should be addressed separately
• The worker uses the existing BatchPaymentService for Stellar transaction submission, ensuring consistency with the payment flow

[drips-wave]

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