feat: classify failed-charge alerts by reason with dedup and webhook

[islarmeeyah-cyber]

Overview

This PR adds a failed-charge alert classification system that uses ChargeResult and DLQ payloads to distinguish failure reasons, rate-limits repeated alerts per subscriber, and sends webhook notifications through the configurable WEBHOOK_URL. It replaces flat failure alerts with reason-aware, deduplicated, actionable webhook events.

Related Issue

Changes

🚨 Failed-Charge Alert Classifier

• [ADD] alert-failed-charges.ts

  • Ingests batch results and DLQ entries; maps ChargeResult fields to normalized failure reasons (allowance, grace, card, etc.).
  • Groups alerts per reason and separates allowance vs grace distinctions.
  • Enforces a per-subscriber dedup window to rate-limit repeat alerts.
  • Builds and sends webhook payloads to WEBHOOK_URL; no PagerDuty-specific APIs are used.

• [ADD] config.ts

  • Adds WEBHOOK_URL, dedup window duration, and failure-reason handling options.
  • Documents the webhook payload schema and classification semantics.

• [ADD] tests/alert-failed-charges.test.ts

  • Validates per-reason grouping, dedup-window behavior, payload schema, and webhook delivery mocking.
  • Runs against fixture result sets and covers allowance vs grace cases.

• [ADD] tests/fixtures/batch-results.json

  • Includes representative ChargeResult and DLQ failure fixtures for classification and dedup scenarios.

• [MODIFY] package.json, tsconfig.json

  • Wires test execution, types, and linting for the new alert module.

Verification Results

npm test -- tests/alert-failed-charges.test.ts --runInBand
✅ 10/10 passed

Fixture acceptance:
✅ Per-reason grouping: allowance, grace, card, and DLQ reasons mapped
✅ Dedup window: 1 alert per subscriber per reason per 15m
✅ Webhook payload matches documented schema
✅ 100% fixture scenarios classified correctly

Acceptance Criteria	Status
Per-reason grouping	✅ Allowance, grace, card, and DLQ reasons are grouped into distinct alert types
Dedup window	✅ Repeated failures per subscriber are rate-limited with a 15-minute window
Webhook payload documented	✅ Payload schema is documented in config.ts and asserted in tests
Tests with fixtures	✅ batch-results.json fixtures drive classification, dedup, and webhook tests

Closes #883

[drips-wave]

@islarmeeyah-cyber 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