feat: soft-limit webhook warnings #538

[Sulamoney222]

Overview

This PR adds partner-token overage soft-limit warning webhooks so partners get an early warning before quotas hard-cut them off. Includes configurable thresholds, deduplicated enqueueing, and at-least-once delivery with ack tracking in a durable ledger.

Related Issue

Closes #538

Changes

Soft-limit warning engine

• [ADD] src/services/partnerTokenSoftLimitService.ts

  • Soft-limit threshold config per partner (0, 1] (default 0.8) + HTTPS webhook URL.
  • Dedupe key {partnerId}:{roundedPct}:{15minWindow} to avoid warning storms.
  • Delivery ledger with pending / failed / acked and retry until ack (at-least-once).
  • Wired into the quota consume path via maybeEnqueueSoftLimitWarning.

• [ADD] src/db/migrations/021_create_partner_token_delivery_ledger.ts

  • Tables: partner_token_soft_limit_config, partner_token_delivery_ledger.

• [MODIFY] src/services/partnerQuotaService.ts

  • Enqueues soft-limit warning when approaching quota (before hard cutoff).

• [MODIFY] src/routes/webhooks.ts

  • Admin config + usage check + deliver endpoints; HMAC-protected /api/v1/webhooks/partner-token/*.

• [ADD] src/services/__tests__/partnerTokenSoftLimitService.test.ts

  • Covers threshold at 100%, duplicate warnings, partner webhook down, retries/acks.

• [ADD] docs/partner-token-soft-limit.md

Verification Results

npm test -- --testPathPattern=partnerTokenSoftLimitService --coverage=false
✅ 23/23 passed

Acceptance Criteria	Status
Soft-limit threshold config	✅ Per-partner config + default 0.8
Enqueue warning webhook with dedupe	✅ Unique dedupe key + PG 23505
Track ack in delivery ledger	✅ acked only after HTTP 2xx
At-least-once delivery	✅ Retries pending/failed until ack
Edge: webhook down / softLimit=1.0 / duplicates	✅ Covered in unit tests

[drips-wave]

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