feat(cache): add TTL-based entry expiry to invoice cache (#606)

[yahia008]

Title:

feat(cache): add TTL-based entry expiry to invoice cache

───────────────────────────────────────────────────────────────────────────────────────────

Description:

Closes #606

Summary

Adds a new Cache<V> class to src/cache.ts with opt-in TTL-based entry
expiry. When ttlMs is omitted the class behaves identically to a plain
Map, preserving full backward compatibility. When a TTL is supplied,
stale entries are evicted lazily on access and/or eagerly via
purgeExpired().

The existing SimpleCache (LRU + per-method TTL config) is untouched.

Changes

src/cache.ts

• New Cache<V> class with:
  • constructor(ttlMs?: number) — optional TTL; no arg = no expiry
  • set(key, value) — records writtenAt: Date.now() alongside the value
  • get(key) — returns undefined and deletes the entry when `Date.now() - writtenAt

ttlMs -has(key)— respects TTL; returnsfalseand evicts expired entries -purgeExpired()— single-pass sweep of all expired entries; no-op when TTL is not configured -delete(key), clear(), size` getter

src/index.ts

• Cache exported from ./cache.js alongside SimpleCache

test/cache.test.ts

• 15 new unit tests using vi.useFakeTimers() (no real-time delays):
  • Entry valid before TTL elapses
  • Entry expired and removed after TTL elapses
  • has() returns false for expired entries
  • purgeExpired() removes only expired entries, leaves fresh ones
  • No-expiry backward-compatibility path
  • delete, clear, size correctness

Test results

Suite	Tests	Result
npm test (CI — client + retryPolicy)	98	✅ all pass
vitest run test/cache.test.ts	19	✅ all pass

Notes

• Zero new dependencies — uses Date.now() only as required by the issue
• All pre-existing tests continue to pass unchanged