Skip to content

Add KYC expiration automation to kyc.worker - #187

Open
FroDev-CR wants to merge 1 commit into
aid-linkk:masterfrom
FroDev-CR:feature/kyc-expiration-automation
Open

Add KYC expiration automation to kyc.worker#187
FroDev-CR wants to merge 1 commit into
aid-linkk:masterfrom
FroDev-CR:feature/kyc-expiration-automation

Conversation

@FroDev-CR

Copy link
Copy Markdown

Closes #91

Summary

Adds background automation to expire KYC submissions once their expiresAt window has passed, and notifies affected beneficiaries — closing the gap where approved KYC could remain VALID indefinitely.

Changes

  • kyc.worker.ts: new periodic EXPIRE_KYC_SUBMISSIONS job (configurable cron, hourly by default) that scans APPROVED KYCSubmission rows with expiresAt <= now and transitions them to EXPIRED.
  • Idempotent & safe to run repeatedly/concurrently: only APPROVED rows are ever matched, and each transition re-checks status inside the write transaction to close the race window.
  • Resets the linked beneficiary to PENDING, writes a KYC_EXPIRED audit log entry, and dispatches a KYC_STATUS_CHANGED webhook.
  • Notifies the beneficiary by email + in-app (respecting notification preferences) with resubmission instructions, and optionally alerts active admins/reviewers for high-risk (fraud score) expirations.
  • New kycExpiration config block (cron interval, batch size, admin-alert threshold, feature flag) — all via env vars.
  • Adds KYC_EXPIRED to NotificationType/AuditAction enums + migration, new kyc-expiration email template, and wires the worker into app startup (it wasn't being started before).
  • Unit tests covering expiration detection, status transition, idempotency, and notification dispatch.
  • Documented in docs/ARCHITECTURE.md.

Testing

Reviewed manually against existing patterns (moderation/analytics workers); added unit tests for BeneficiaryService.expireKYCSubmissions, kyc.worker.ts job orchestration, and notification service methods.

- Add periodic EXPIRE_KYC_SUBMISSIONS job that scans APPROVED KYCSubmission
  rows with expiresAt <= now and transitions them to EXPIRED (idempotent,
  keyset-paginated, race-safe re-check inside the write transaction).
- Reset the linked beneficiary to PENDING and write a KYC_EXPIRED audit log
  entry + KYC_STATUS_CHANGED webhook on each transition.
- Notify beneficiaries by email/in-app when their KYC expires, and alert
  active admins/reviewers for high-risk (fraudScore-based) expirations.
- Add configurable kycExpiration settings (cron interval, batch size,
  admin-alert threshold, feature flag).
- Add KYC_EXPIRED to the NotificationType/AuditAction enums + migration,
  new kyc-expiration email template, and wire the worker into startup.
- Add unit tests for expiration detection, status transition, idempotency,
  and notification dispatch; document the automation in ARCHITECTURE.md.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

KYC Expiration Automation: expire submissions and notify beneficiaries

1 participant