@openclaw/whatsapp 2026.7.1-beta.2 → 2026.7.1-beta.4

package/node_modules/@cacheable/memory/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@cacheable/memory",
-  "version": "2.0.9",
+  "version": "2.2.0",
   "description": "High Performance In-Memory Cache for Node.js",
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": {
       "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
       },
       "require": {
         "types": "./dist/index.d.cts",
@@ -27,14 +27,14 @@
   "license": "MIT",
   "private": false,
   "devDependencies": {
-    "tsup": "^8.5.1",
+    "tsdown": "^0.22.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
     "@keyv/bigmap": "^1.3.1",
     "hookified": "^1.15.1",
     "keyv": "^5.6.0",
-    "@cacheable/utils": "^2.4.1"
+    "@cacheable/utils": "^2.5.0"
   },
   "keywords": [
     "cacheable",
@@ -56,7 +56,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
+    "build": "rimraf ./dist && tsdown src/index.ts --format cjs,esm --dts --clean",
     "lint": "biome check --write --error-on-warnings",
     "test": "pnpm lint && vitest run --coverage",
     "test:ci": "biome check --error-on-warnings && vitest run --coverage",

package/node_modules/@cacheable/utils/README.md

@@ -13,10 +13,11 @@
 * Data Types for Caching Items
 * Hash Functions for Key Generation
 * Coalesce Async for Handling Multiple Promises
-* Stats Helpers for Caching Statistics
+* Statistics for Tracking Cache Metrics
 * Sleep / Delay for Testing and Timing
 * Memoization for wraping or get / set options
 * Time to Live (TTL) Helpers
+* Tag-Based Cache Invalidation
 
 # Table of Contents
 * [Getting Started](#getting-started)
@@ -25,13 +26,14 @@
 * [Hash Functions](#hash-functions)
 * [Shorthand Time Helpers](#shorthand-time-helpers)
 * [Sleep Helper](#sleep-helper)
-* [Stats Helpers](#stats-helpers)
+* [Statistics](#statistics)
 * [Time to Live (TTL) Helpers](#time-to-live-ttl-helpers)
 * [Run if Function Helper](#run-if-function-helper)
 * [Less Than Helper](#less-than-helper)
 * [Is Object Helper](#is-object-helper)
 * [Wrap / Memoization for Sync and Async Functions](#wrap--memoization-for-sync-and-async-functions)
 * [Get Or Set Memoization Function](#get-or-set-memoization-function)
+* [Cache Tags](#cache-tags)
 * [How to Contribute](#how-to-contribute)
 * [License and Copyright](#license-and-copyright)
 
@@ -191,18 +193,223 @@ await sleep(1000); // Pause for 1 second
 console.log('Execution resumed after 1 second');
 ```
 
-# Stats Helpers
+# Statistics
 
-The `@cacheable/utils` package provides statistics helpers that can be used to track and analyze caching operations. These helpers can be used to gather metrics such as hit rates, miss rates, and other performance-related statistics.
+The `Stats` class provides a unified, event-driven way to track caching metrics such as hits, misses, hit rate, item counts, and approximate memory usage. It can be driven two ways:
+
+* **Imperatively** — call `increment` / `decrement` (or the named helpers) directly from your code.
+* **Event-driven** — `subscribe` it to an event emitter (such as `@cacheable/node-cache` or a Node `EventEmitter`) and let matching events update the counters automatically.
+
+Statistics are **opt-in**: a new `Stats` instance is disabled by default and ignores every update until enabled, so there is zero tracking overhead unless you ask for it.
+
+```typescript
+import { Stats } from '@cacheable/utils';
+
+const stats = new Stats({ enabled: true });
+
+stats.incrementHits();
+stats.incrementMisses();
+stats.incrementGets();
+
+console.log(stats.hits);    // 1
+console.log(stats.misses);  // 1
+console.log(stats.hitRate); // 0.5
+```
+
+## Available Statistics
+
+Every counter is exposed as a read-only property:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `hits` | `number` | Number of cache hits. |
+| `misses` | `number` | Number of cache misses. |
+| `gets` | `number` | Number of get operations. |
+| `sets` | `number` | Number of set operations. |
+| `deletes` | `number` | Number of delete operations. |
+| `clears` | `number` | Number of clear operations. |
+| `count` | `number` | Number of items currently tracked. |
+| `ksize` | `number` | Approximate size of all keys, in bytes. |
+| `vsize` | `number` | Approximate size of all values, in bytes. |
+
+### Computed Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `hitRate` | `number` | `hits / (hits + misses)`, or `0` when there have been no lookups. |
+| `missRate` | `number` | `misses / (hits + misses)`, or `0` when there have been no lookups. |
+
+### Metadata
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` | Whether tracking is currently on. |
+| `lastUpdated` | `number \| undefined` | Timestamp (ms since epoch) of the last update while enabled. |
+| `lastReset` | `number \| undefined` | Timestamp (ms since epoch) of the last `reset()` / `clear()`. |
+
+## Enabling, Disabling, and Clearing
+
+```typescript
+const stats = new Stats(); // disabled by default
+
+stats.enable();          // start tracking (or: stats.enabled = true)
+stats.incrementHits();
+console.log(stats.hits); // 1
+
+stats.disable();         // stop tracking (or: stats.enabled = false)
+stats.incrementHits();
+console.log(stats.hits); // still 1
+
+stats.clear();           // reset every counter back to 0 (alias of reset())
+console.log(stats.hits); // 0
+```
+
+* `reset()` / `clear()` — set every counter back to `0` and record `lastReset`.
+* `resetStoreValues()` — reset only `count`, `ksize`, and `vsize`, leaving the hit/miss history intact.
+
+## Incrementing and Decrementing
+
+Use the unified `increment` / `decrement` methods with any counter field, or the named helpers. All updates are ignored while disabled.
+
+```typescript
+const stats = new Stats({ enabled: true });
+
+// Unified API — optional amount (defaults to 1)
+stats.increment('hits');
+stats.increment('sets', 5);
+stats.decrement('count', 2);
+
+// Named helpers
+stats.incrementHits();
+stats.incrementMisses();
+stats.incrementGets();
+stats.incrementSets();
+stats.incrementDeletes();
+stats.incrementClears();
+stats.incrementCount();
+stats.decreaseCount();
+
+// Approximate key/value sizes
+stats.incrementKSize('my-key');  // adds the byte size of the key
+stats.incrementVSize({ a: 1 });  // adds the byte size of the value
+stats.decreaseKSize('my-key');
+stats.decreaseVSize({ a: 1 });
+stats.setCount(10);              // set the item count directly
+```
+
+`StatField` is the union of countable fields: `'hits' | 'misses' | 'gets' | 'sets' | 'deletes' | 'clears' | 'count'`.
+
+## Snapshot
+
+`toJSON()` (aliased as `snapshot()`) returns a plain object of every counter, the computed rates, and the timestamps — handy for logging or sending to a metrics system.
+
+```typescript
+const stats = new Stats({ enabled: true });
+stats.incrementHits(3);
+stats.incrementMisses();
+
+console.log(stats.toJSON());
+// {
+//   enabled: true,
+//   hits: 3, misses: 1, gets: 0, sets: 0, deletes: 0, clears: 0,
+//   vsize: 0, ksize: 0, count: 0,
+//   hitRate: 0.75, missRate: 0.25,
+//   lastUpdated: 1749513600000, lastReset: undefined
+// }
+```
+
+## Event-Driven Tracking
+
+Instead of calling the increment methods yourself, you can `subscribe` a `Stats` instance to an emitter and have events update the counters automatically. The emitter is duck-typed — anything with `.on()` (plus `.off()` or `.removeListener()` to detach) works, including `Hookified`-based classes and Node's `EventEmitter`.
+
+An **event map** describes how each event name updates the stats. A map value can be:
+
+* a single field — `"sets"`
+* an array of fields — `["hits", "gets"]`
+* a custom handler — `(stats, ...args) => void`
+
+```typescript
+import { Stats, nodeCacheStatsEventMap } from '@cacheable/utils';
+import { NodeCache } from '@cacheable/node-cache';
+
+const cache = new NodeCache();
+const stats = new Stats({ enabled: true });
+
+// nodeCacheStatsEventMap maps set -> sets, del -> deletes, flush -> clears,
+// and flush_stats -> reset.
+stats.subscribe(cache, nodeCacheStatsEventMap);
+
+cache.set('key', 'value');
+console.log(stats.sets); // 1
+
+stats.unsubscribe(); // detach all listeners (or pass an emitter to detach just one)
+```
+
+You can also provide your own map for any emitter:
+
+```typescript
+import { EventEmitter } from 'node:events';
+import { Stats } from '@cacheable/utils';
+
+const emitter = new EventEmitter();
+const stats = new Stats({ enabled: true });
+
+stats.subscribe(emitter, {
+  'cache:hit': ['hits', 'gets'],
+  'cache:miss': ['misses', 'gets'],
+  evicted: (s) => s.incrementDeletes(),
+});
+
+emitter.emit('cache:hit', { key: 'a' });
+console.log(stats.hitRate); // 1
+```
+
+You can subscribe to multiple emitters from a single `Stats` instance, and pass an emitter to `unsubscribe(emitter)` to detach just that one. Counting is gated by `enabled`, so you can subscribe first and toggle tracking on later — handlers do not run at all while disabled.
+
+## Per-Key Tracking (Most and Least Used Keys)
+
+To find your hottest and coldest keys, enable per-key tracking with `trackKeys`. Each recorded key keeps its own breakdown of `hits`, `misses`, `gets`, `sets`, and `deletes`, plus a computed total `count` and per-key `hitRate`.
 
 ```typescript
-import { stats } from '@cacheable/utils';
+import { Stats } from '@cacheable/utils';
 
-const cacheStats = stats();
-cacheStats.incrementHits();
-console.log(cacheStats.hits); // Get the hit rate of the cache
+const stats = new Stats({ enabled: true, trackKeys: true });
+
+stats.recordKey('user:1', 'hits');
+stats.recordKey('user:1', 'gets', 5);
+stats.recordKey('user:2', 'misses');
+
+// 100 most used keys by total operations (descending)
+console.log(stats.mostUsedKeys(100));
+// [
+//   { key: 'user:1', count: 6, hits: 1, misses: 0, gets: 5, sets: 0, deletes: 0, hitRate: 1 },
+//   { key: 'user:2', count: 1, hits: 0, misses: 1, gets: 0, sets: 0, deletes: 0, hitRate: 0 }
+// ]
+
+// 100 least used keys by total operations (ascending)
+console.log(stats.leastUsedKeys(100));
+
+// Rank by a single counter instead of the total
+console.log(stats.mostUsedKeys(100, 'hits'));
+
+// Inspect one key, or read the (read-only) tracked-keys map directly
+console.log(stats.keyStats('user:1'));
+console.log(stats.trackedKeys.size);
+
+stats.clearKeys(); // clear per-key stats only (reset() clears these too)
 ```
 
+Both `mostUsedKeys` and `leastUsedKeys` default to 100 entries, and `trackedKeys` is included in `toJSON()` snapshots.
+
+Per-key tracking is fed two ways, just like the aggregate counters:
+
+* **Imperatively** — call `recordKey(key, field, amount?)` wherever you already increment stats.
+* **Event-driven** — `nodeCacheStatsEventMap` automatically records keys from `set`/`del` events when `trackKeys` is on, and custom event-map handlers can call `recordKey` with whatever the payload carries.
+
+Memory is proportional to the number of unique keys tracked, so `trackKeys` is off by default. You can also set `maxTrackedKeys` as a safety cap — when exceeded, the lowest-count keys are pruned. Note that pruning keeps `mostUsedKeys` approximately accurate but makes `leastUsedKeys` unreliable (the pruned keys *are* the least used), so leave it unset if you need exact least-used-key rankings.
+
+> **Note:** a built-in map is provided only where a library's events map cleanly to stats. `nodeCacheStatsEventMap` is included because `@cacheable/node-cache` emits each lifecycle event exactly once. Libraries that emit per-store probes or omit events on a miss (such as `cacheable` and `cache-manager`) should be wired with a custom map or driven imperatively so the counts stay accurate.
+
 # Time to Live (TTL) Helpers
 
 The `@cacheable/utils` package provides helpers for managing time-to-live (TTL) values for cached items. 
@@ -512,6 +719,133 @@ const function_ = async () => Math.random() * 100;
 const value = await getOrSet(generateKey(), function_, { ttl: '1h', cache });
 ```
 
+# Cache Tags
+
+The `CacheTags` service provides tag-based invalidation on top of any [Keyv](https://github.com/jaredwray/keyv) store. It is store-agnostic and does not require any adapter changes.
+
+The service uses a lazy invalidation model. Instead of scanning and deleting keys, `invalidateTag` increments a per-tag version counter. Each cached key stores a snapshot of its tag versions at the time it was written, and `isKeyFresh` compares that snapshot to the current versions. If any tag version has been incremented since the snapshot was taken, the key is considered stale. Stale entries are not deleted explicitly and are expected to fall out of the cache via their TTL.
+
+This approach keeps invalidation constant-time regardless of how many keys reference a tag. The trade-off is one additional `isKeyFresh` read per cache lookup.
+
+```typescript
+import { Keyv } from 'keyv';
+import { CacheTags } from '@cacheable/utils';
+
+const store = new Keyv();
+const cacheTags = new CacheTags({ store, namespace: 'app' });
+
+await cacheTags.setKeyTags('user:42', ['users', 'org:7'], { ttl: 3600000 });
+console.log(await cacheTags.isKeyFresh('user:42')); // true
+
+await cacheTags.invalidateTag('users');
+console.log(await cacheTags.isKeyFresh('user:42')); // false
+```
+
+The recommended pattern is to call `isKeyFresh` before trusting a value returned from your cache, and to refresh the tag snapshot whenever you write a new value:
+
+```typescript
+import { Cacheable } from 'cacheable';
+import { Keyv } from 'keyv';
+import { CacheTags } from '@cacheable/utils';
+
+const cache = new Cacheable();
+const cacheTags = new CacheTags({ store: new Keyv() });
+
+const getUser = async (id: string) => {
+  const key = `user:${id}`;
+
+  if (await cacheTags.isKeyFresh(key)) {
+    const cached = await cache.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+  }
+
+  const fresh = await loadUser(id);
+  await cache.set(key, fresh, '1h');
+  await cacheTags.setKeyTags(key, ['users', `org:${fresh.orgId}`], { ttl: 3600000 });
+  return fresh;
+};
+```
+
+You can invalidate one or many tags at a time. Both methods return the names of the tags that were bumped:
+
+```typescript
+const bumped = await cacheTags.invalidateTags(['users', 'org:7']);
+console.log(bumped); // ['users', 'org:7']
+```
+
+When integrating with a cache where most keys are untagged, use `isKeyStale` instead of `isKeyFresh`. It only reports `true` when a snapshot exists for the key and one of its tags has been invalidated, so keys that were never tagged are not treated as stale:
+
+```typescript
+console.log(await cacheTags.isKeyStale('never-tagged')); // false
+await cacheTags.setKeyTags('user:42', ['users']);
+console.log(await cacheTags.isKeyStale('user:42')); // false
+await cacheTags.invalidateTag('users');
+console.log(await cacheTags.isKeyStale('user:42')); // true
+```
+
+The `getStaleKeys` method checks many keys at once using two batched store reads regardless of how many keys are passed — one for the snapshots and one for the union of their tag versions:
+
+```typescript
+await cacheTags.setKeyTags('a', ['x']);
+await cacheTags.setKeyTags('b', ['y']);
+await cacheTags.invalidateTag('x');
+console.log(await cacheTags.getStaleKeys(['a', 'b', 'untagged'])); // ['a']
+```
+
+The `getTags` method returns the tags currently associated with a key, or `undefined` if the key has no snapshot:
+
+```typescript
+await cacheTags.setKeyTags('user:42', ['users', 'org:7']);
+console.log(await cacheTags.getTags('user:42')); // ['users', 'org:7']
+console.log(await cacheTags.getTags('missing')); // undefined
+```
+
+The `removeKey` and `removeKeys` methods delete tag snapshots when the cached values themselves are deleted. `removeKeys` performs a single batched delete:
+
+```typescript
+await cacheTags.removeKeys(['user:1', 'user:2']);
+```
+
+The service can be disabled via the `enabled` option or property so integrations pay no extra store reads for untagged workloads. While disabled, every method is a no-op: read methods return their neutral value (`isKeyFresh` returns `true`, `isKeyStale` returns `false`, `getStaleKeys` returns `[]`, and so on) and writes are skipped. The service never enables itself — you have to turn it on explicitly, which keeps behavior consistent across distributed instances sharing a store:
+
+```typescript
+const cacheTags = new CacheTags({ store, enabled: false });
+console.log(await cacheTags.isKeyStale('anything')); // false, no store read
+await cacheTags.setKeyTags('user:42', ['users']); // no-op while disabled
+cacheTags.enabled = true; // turn it on to use tags
+```
+
+`setKeyTags`, `removeKey`, and `removeKeys` accept a `nonBlocking` option to fire-and-forget the store write. Failures from non-blocking operations are reported to the `onError` constructor option since they cannot be thrown to the caller:
+
+```typescript
+const cacheTags = new CacheTags({ store, onError: (error) => console.error(error) });
+await cacheTags.setKeyTags('user:42', ['users'], { ttl: 3600000, nonBlocking: true });
+```
+
+The `getKeysByTag` method returns the keys currently referencing a given tag. It iterates the Keyv namespace and is therefore an `O(N)` operation. It is intended for debugging and tests rather than hot paths.
+
+```typescript
+await cacheTags.setKeyTags('user:1', ['users']);
+await cacheTags.setKeyTags('user:2', ['users']);
+const keys = await cacheTags.getKeysByTag('users');
+console.log(keys); // ['user:1', 'user:2']
+```
+
+The service stores its metadata under a reserved prefix so that it cannot collide with user keys:
+
+```
+--cacheable--tags--:<namespace>:tag:<tagName>  → integer version counter
+--cacheable--tags--:<namespace>:key:<keyName>  → { tags: { [tag]: versionAtSetTime } }
+```
+
+Tag version counters are stored without a TTL because they must outlive any key that references them. Key entries respect the `ttl` passed to `setKeyTags`, which should be set to match the TTL of the cached value it tracks.
+
+The namespace defaults to `default` and can be set via the constructor. Two services configured with different namespaces can share the same store without seeing each other's tags or keys.
+
+The read-version then write-snapshot sequence in `setKeyTags` is not atomic across processes. A concurrent `invalidateTag` that runs between the read and the write can leave a freshly written key referencing a stale version. An atomic Redis fast path using `MULTI` or Lua is a planned future enhancement.
+
 # How to Contribute
 
 You can contribute by forking the repo and submitting a pull request. Please make sure to add tests and update the documentation. To learn more about how to contribute go to our main README [https://github.com/jaredwray/cacheable](https://github.com/jaredwray/cacheable). This will talk about how to `Open a Pull Request`, `Ask a Question`, or `Post an Issue`.