Add manual cache invalidation API to watchAndInvalidate

[Lakes41]

Difficulty: Intermediate
Type: Feature
Recommended labels (if available in this repo): enhancement, caching, sdk

Background

src/contracts/watchAndInvalidate.ts appears to handle automatic cache invalidation based on on-chain events. There is currently no way for a consumer to manually force-invalidate a cache entry (e.g. after performing a mutation through another path, like an admin action in guildpass-integrations).

Problem

If a consumer application changes on-chain or off-chain state through a path the SDK isn't watching (e.g. a direct admin API call), the SDK's cache can serve stale data until the next automatic invalidation trigger fires.

Expected Outcome

A public client.cache.invalidate(key | pattern) method that lets consumers manually evict specific cache entries or entries matching a pattern (e.g. by wallet address or guild ID).

Suggested Implementation

Expose an invalidate method on the client that delegates to the configured cache adapter's delete/clear methods, and extend watchAndInvalidate.ts to support a pattern-based invalidation helper if the underlying cache doesn't natively support pattern matching (e.g. by tracking key prefixes).

Acceptance Criteria

• client.cache.invalidate() is implemented and exported
• Supports invalidating a single known key and a prefix/pattern
• Works correctly regardless of which cache adapter (in-memory, Redis, LRU) is configured
• Unit tests cover single-key and pattern invalidation
• pnpm test:run passes

Likely Affected Files/Directories

• src/contracts/watchAndInvalidate.ts
• src/cache/cache.types.ts
• src/client/GuildPassClient.ts

[Caerlower]

Allow me to work on this, I can fix this.

[grantfox-oss]

🦊 GrantFox — @Caerlower has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #328)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[Caerlower]

Hello @Lakes41, this issue has been resolved with my PR in the guildpass-sdk, please close this issue.