feat: accessInfo cache + monitor.onAccessUpdated + socket auto-bust (Plan 66)

Follow-up to Phase H. Wires the server's Plan 66 `accessUpdated`
fine-grained event into a useful SDK-side cache + helper.

connection.accessInfo now memoizes
- First call fetches from `/access-info` and caches the result in
  `this._accessInfoCache`. Subsequent calls return the cached object
  reference in O(1).
- New optional arg `forceRefresh` (default `false`); pass `true` to
  bypass + refresh the cache. A failed fetch leaves any prior cached
  value intact.
- Cached object reference is stable so consumers can do reference
  equality across calls.

connection.socket auto-busts the cache
- When the server emits `accessUpdated` after `connection.socket.open()`,
  SocketIO automatically calls `this.connection.accessInfo(true)` so
  the cache reflects the new permissions / serial on the next read.
  Best-effort — a failed refresh is swallowed and leaves the cache
  alone.
- `'accessUpdated'` is added to the SocketIO EVENTS allow-list so
  `socket.on('accessUpdated', handler)` is now a valid subscription.

monitor.onAccessUpdated(handler) helper
- Convenience on the Monitor instance that subscribes to the same
  `accessUpdated` event, re-emitted by `Monitor.UpdateMethod.Socket`
  on the Monitor itself. Requires the Socket update method (the
  event is server-pushed via socket.io; polling-based update methods
  never fire it).
- Returns `this` for chaining.

Type definitions
- `Connection.accessInfo(forceRefresh?)` updated in components/pryv
  /src/index.d.ts. `updateAccess` + `getAccessWithHistory` also added.
- `Monitor.onAccessUpdated(handler)` declared in
  components/pryv-monitor/src/index.d.ts.

Tests
- 2 new Connection.test.js cases — `[CAIC]` memoize-returns-same-ref
  and `[CAID]` forceRefresh-replaces-cache. Both passing.
- Full pryv test suite: 173 passing, 0 failing, 2 pending (matches
  prior baseline; no regression).

Author: perki

CHANGELOG.md

@@ -12,6 +12,10 @@ Plan 66 (open-pryv.io ≥ 2.0.0-pre.X): access versioning.
 - `pryv.StaleAccessIdError` — typed error (extends `PryvError`) surfaced when the server responds with `409 stale-resource` on `accesses.update` / `accesses.delete`. Carries `{ provided, currentSerial }` in `.data` so callers can refetch + retry.
 - `connection.updateAccess(id, changes)` — convenience wrapper around `accesses.update`. Automatically translates the server's 409 response into `StaleAccessIdError`.
 - `connection.getAccessWithHistory(id)` — convenience wrapper around `accesses.getOne?includeHistory=true`. Returns `{ access, current?, history?: [...] }`.
+- `connection.accessInfo(forceRefresh)` — now memoized. First call fetches from the server and caches; subsequent calls return the cached copy in O(1). Pass `forceRefresh: true` to bypass the cache and re-fetch. Cached object reference is stable across calls (safe to compare).
+- `connection.socket.open()` — when the server emits `accessUpdated` (Plan 66 fine-grained event), the SocketIO layer automatically invokes `connection.accessInfo(true)` so the cache reflects the new permissions / serial on the next read. Best-effort: a failed refresh leaves any prior cached value intact.
+- `@pryv/socket.io`: `'accessUpdated'` is now an allowed event for `socket.on(...)`. Payload: `{ type: 'access-updated', accessId: '<base>:<serial>', serial }`.
+- `@pryv/monitor`: `monitor.onAccessUpdated(handler)` — register a callback for the server-pushed `accessUpdated` event. Requires `Monitor.UpdateMethod.Socket` (the event is server-pushed via socket.io; polling-based update methods won't fire it). The handler receives the structured payload above.
 
 ### Notes
 - Wire-format compatibility: every `access.id` / `access.createdBy` / `access.modifiedBy` returned by a Plan-66-capable server is parseable with `parseAccessRef`. Older servers still return bare cuids — `parseAccessRef` returns `{ base, serial: null }` for those, so callers can use the helper unconditionally.

components/pryv-monitor/src/Monitor.js

@@ -163,6 +163,30 @@ class Monitor extends EventEmitter {
     return this.states.started;
   }
 
+  /**
+   * Plan 66: register a handler for the server's fine-grained
+   * `accessUpdated` event. Fires whenever a Pryv.io ≥ 2.0.0-pre.X server
+   * emits the event after a successful `accesses.update` — payload is
+   * `{ type: 'access-updated', accessId: '<base>:<serial>', serial }`.
+   *
+   * Requires `Monitor.UpdateMethod.Socket` to be active (the event
+   * is server-pushed via `@pryv/socket.io`). With other update methods
+   * (e.g. `EventsTimer` polling), the handler will never fire —
+   * polling-based consumers should call `connection.accessInfo(true)`
+   * themselves when they need to refresh the cache.
+   *
+   * The underlying `connection.socket` already busts the
+   * `connection.accessInfo` cache when this event fires, so the next
+   * `connection.accessInfo()` call returns the freshly-fetched copy.
+   *
+   * @param {Function} handler - called with `(payload)` on each event
+   * @returns {Monitor} this (chainable)
+   */
+  onAccessUpdated (handler) {
+    this.on('accessUpdated', handler);
+    return this;
+  }
+
   /**
    * @private
    * Called by UpdateMethod to share cross references

components/pryv-monitor/src/UpdateMethod/Socket.js

@@ -23,6 +23,15 @@ class Socket extends UpdateMethod {
     this.socket = await this.monitor.connection.socket.open();
     this.socket.on('eventsChanged', () => { this.monitor.updateEvents(); });
     this.socket.on('streamsChanged', () => { this.monitor.updateStreams(); });
+    // Plan 66: re-emit the server's fine-grained `accessUpdated` event
+    // on the Monitor itself so consumers can subscribe via
+    // `monitor.onAccessUpdated(handler)`. The underlying SocketIO has
+    // already busted the connection's accessInfo cache; the payload
+    // carries the new composite accessId + serial for fine-grained
+    // reactions.
+    this.socket.on('accessUpdated', (payload) => {
+      this.monitor.emit('accessUpdated', payload);
+    });
     this.socket.on('error', (error) => {
       this.monitor.emit(Changes.ERROR, error);
       // If the underlying socket.io-client transport has been torn down

components/pryv-monitor/src/index.d.ts

@@ -96,6 +96,14 @@ declare module 'pryv' {
      */
     stop(): Monitor;
 
+    /**
+     * Plan 66: register a handler for the server's fine-grained
+     * `accessUpdated` event. Requires `Monitor.UpdateMethod.Socket`.
+     * The underlying `connection.socket` busts the
+     * `connection.accessInfo` cache before this fires.
+     */
+    onAccessUpdated(handler: (payload: { type: 'access-updated', accessId: string, serial: number }) => void): Monitor;
+
     /**
      * True when the monitor has been started and not yet stopped.
      */

components/pryv-socket.io/src/SocketIO.js

@@ -5,7 +5,7 @@
 const io = require('socket.io-client');
 const { EventEmitter } = require('events');
 
-const EVENTS = ['eventsChanged', 'streamsChanged', 'accessesChanged', 'disconnect', 'error'];
+const EVENTS = ['eventsChanged', 'streamsChanged', 'accessesChanged', 'accessUpdated', 'disconnect', 'error'];
 
 /**
  * Socket.IO transport for a Connection.
@@ -84,6 +84,14 @@ class SocketIO extends EventEmitter {
           this._io.on('connect', () => {
             this.connecting = false;
             registerListeners(this);
+            // Plan 66: when the server emits `accessUpdated` (fine-grained
+            // event fired after every successful `accesses.update`), bust
+            // the connection's `accessInfo` cache so the next read picks
+            // up the new permissions / serial. Best-effort: a failed
+            // refresh leaves the previous cached value intact.
+            this._io.on('accessUpdated', () => {
+              this.connection.accessInfo(true).catch(() => { /* swallow */ });
+            });
             resolve(this);
           });
         })
@@ -105,7 +113,7 @@ class SocketIO extends EventEmitter {
 
   /**
    * Add listener for Socket.IO events
-   * @param {('eventsChanged'|'streamsChanged'|'accessesChanged'|'disconnect'|'error')} eventName - The event to listen for
+   * @param {('eventsChanged'|'streamsChanged'|'accessesChanged'|'accessUpdated'|'disconnect'|'error')} eventName - The event to listen for
    * @param {Function} listener - The callback function
    * @returns {SocketIO} this
    */

components/pryv/src/Connection.js

@@ -72,11 +72,22 @@ class Connection {
 
   /**
    * Get access info for this connection.
-   * It's async as it is fetched from the API.
+   *
+   * Memoized per-Connection: the first call fetches from the server and
+   * caches the result; subsequent calls return the cached copy in O(1).
+   * Pass `forceRefresh: true` to invalidate the cache and fetch a fresh
+   * copy from the server — used internally by `connection.socket` to
+   * react to Plan 66 `accessUpdated` server-push events. A failed
+   * server fetch leaves any prior cached value intact.
+   *
+   * @param {boolean} [forceRefresh=false] - bypass + refresh the cache
    * @returns {Promise<AccessInfo>} Promise resolving to the access info
    */
-  async accessInfo () {
-    return this.get('access-info', null);
+  async accessInfo (forceRefresh = false) {
+    if (!forceRefresh && this._accessInfoCache != null) return this._accessInfoCache;
+    const fresh = await this.get('access-info', null);
+    this._accessInfoCache = fresh;
+    return fresh;
   }
 
   /**

components/pryv/src/index.d.ts

@@ -723,7 +723,12 @@ declare module 'pryv' {
       fields: string[],
       points: Array<Array<number | string>>,
     ): Promise<HFSeriesAddResult>;
-    accessInfo(): Promise<AccessInfo>;
+    /** Memoized; pass `forceRefresh: true` to bypass + refresh the cache. */
+    accessInfo(forceRefresh?: boolean): Promise<AccessInfo>;
+    /** Plan 66: update an access by composite id. */
+    updateAccess(id: string, changes: object): Promise<object>;
+    /** Plan 66: fetch an access including its full version history. */
+    getAccessWithHistory(id: string): Promise<{ access: object, current?: string, history?: object[] }>;
     revoke(throwOnFail?: boolean, usingConnection?: Connection): Promise<any>;
     readonly deltaTime: number;
     readonly apiEndpoint: string;

components/pryv/test/Connection.test.js

@@ -499,5 +499,31 @@ describe('[CONX] Connection', () => {
       expect(accessInfoUser.token).to.exist;
       expect(newUser.access.token).to.equal(accessInfoUser.token);
     });
+
+    // Plan 66 — accessInfo caching + forceRefresh.
+
+    it('[CAIC] accessInfo() memoizes — second call returns the same object reference', async () => {
+      const regexAPIandToken = /(.+):\/\/(.+)/gm;
+      const res = regexAPIandToken.exec(testData.apiEndpoint);
+      const apiEndpointWithToken = res[1] + '://' + newUser.access.token + '@' + res[2];
+      const cachingConn = new pryv.Connection(apiEndpointWithToken);
+      const first = await cachingConn.accessInfo();
+      const second = await cachingConn.accessInfo();
+      expect(second).to.equal(first); // same reference — served from cache
+    });
+
+    it('[CAID] accessInfo(true) forces a refresh and replaces the cached object', async () => {
+      const regexAPIandToken = /(.+):\/\/(.+)/gm;
+      const res = regexAPIandToken.exec(testData.apiEndpoint);
+      const apiEndpointWithToken = res[1] + '://' + newUser.access.token + '@' + res[2];
+      const cachingConn = new pryv.Connection(apiEndpointWithToken);
+      const first = await cachingConn.accessInfo();
+      const refreshed = await cachingConn.accessInfo(true);
+      expect(refreshed).to.not.equal(first); // distinct object — re-fetched
+      expect(refreshed.token).to.equal(first.token); // same content
+      // Next non-forced call returns the refreshed copy from cache.
+      const cached = await cachingConn.accessInfo();
+      expect(cached).to.equal(refreshed);
+    });
   });
 });