Add invoice payment velocity tracker

[wendypetersondev]

Closes #143
Implements issue #143: Add invoice payment velocity tracker.

Adds SDK method to analyze how quickly payments are arriving for invoices, identifying fast-filling and stalled payment patterns.

Changes

• src/velocityTracker.ts: New velocity tracking module

  • trackVelocity(address, client) fetches all invoices for creator and computes analytics
  • Calculates paymentsPerDay from actual payment timestamps
  • Classifies trend based on comparing first-half vs second-half payment rates
  • Supports three trend classifications: accelerating, steady, stalling

• Type Exports: VelocityReport, InvoiceVelocity, PaymentTrend

  • VelocityReport: address and array of invoice velocity metrics
  • InvoiceVelocity: invoiceId, paymentsPerDay, trend
  • PaymentTrend: type union of trend classifications

• Tests: 4 new tests covering:

  • paymentsPerDay calculation from timestamps
  • Stalling trend detection (early payment concentration)
  • Accelerating trend detection (late payment concentration)
  • Steady trend detection (even payment distribution)

Verification

✓ All 51 tests pass (47 existing + 4 new velocity tests)
✓ TypeScript strict mode (zero any types)
✓ trackVelocity function exported and fully typed
✓ VelocityReport and PaymentTrend types exported
✓ Trend classification verified with test data

Technical Details

• Fetches all invoices for address with pagination support (50 items per page)
• Filters payments to include only those with timestamps
• Computes rate as payments per day over full time span
• Trend analysis: splits payments into two halves, compares rates with 20% threshold
• Gracefully handles invoices with 0-1 payments (classified as 'steady')

Usage Example

import { trackVelocity } from '@stellar-split/sdk';

const report = await trackVelocity(creatorAddress, client);
// report.invoices[0].trend === 'accelerating' | 'steady' | 'stalling'
// report.invoices[0].paymentsPerDay === 2.5

[drips-wave]

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