feat: Enhancement: Detailed SDK Feature #38

[OkeQueen]

Summary

Closes #372

(placeholder enhancement for #38, whose original content is no longer available on GitHub — issue #38 returns 410 Gone).

Since the referenced issue had no recoverable requirements, I audited the SDK for a real, measurable performance issue rather than guessing. FactoryModule.streamAddress() resolves a streamId → contract address mapping that is fixed at stream creation and never changes, yet it made a fresh RPC round trip (buildContractCallTx + simulateReadOnly) on every call. This lookup sits on the hot path for nearly every stream operation — get, withdraw, cancel, pause, resume, topUp, clawback all resolve the address via StreamsModule._resolveAddr — and list() fans it out again for every stream on every page.

• Added an in-memory Map<string, string> cache inside FactoryModule, keyed by streamId.toString().
• Only successful (non-null) resolutions are cached — a "not found" result is not cached, since a stream could be created after a failed lookup.
• No public API changes; behavior is identical for callers, just fewer redundant network calls.

Changes

• src/factory.ts — cache resolved addresses in streamAddress(), skip the network call on a cache hit.
• src/tests/factory.test.ts — added tests for: cache hit avoids a second simulateReadOnly call, separate cache entries per streamId, bigint/string id forms sharing one cache key, and not-found (void) results not being cached.
• docs/api.md — documented the caching behavior under client.factory.streamAddress.
• CHANGELOG.md — added a "Performance" entry under [Unreleased].

Test plan

• npx vitest run — full suite passes (557 passed, 2 skipped)
• npx vitest run --coverage src/tests/factory.test.ts — factory.ts at ~93% statement / 89% branch coverage
• npx tsc -p tsconfig.build.json --noEmit — clean
• npx eslint src/factory.ts src/tests/factory.test.ts — clean

[drips-wave]

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