feat(pryv): access versioning support — v3.1.0 (Plan 66 Phase H)

New utilities, typed error, and Connection helpers for the composite
access reference format introduced by open-pryv.io ≥ 2.0.0-pre.X
(Plan 66).

Utils
- pryv.utils.parseAccessRef(ref) → { base, serial | null }
  Parses both bare cuid (never-updated access) and composite
  `<base>:<serial>` (versioned access). Throws on malformed input.
- pryv.utils.serializeAccessRef({ base, serial }) → string
  Inverse helper.

Typed error
- pryv.StaleAccessIdError extends PryvError. Surfaced when the
  server responds with 409 stale-resource on accesses.update or
  accesses.delete. Carries { provided, currentSerial } in .data so
  callers can refetch + retry.

Connection helpers
- connection.updateAccess(id, changes) — wrapper around
  accesses.update. Translates the 409 stale-resource response into
  StaleAccessIdError automatically.
- connection.getAccessWithHistory(id) — wrapper around
  accesses.getOne?includeHistory=true. Returns
  { access, current?, history?: [...] }.

Wire-format compatibility
- Older servers still return bare cuids; parseAccessRef yields
  { base, serial: null } in that case so callers can use it
  unconditionally. The new utilities are pure JS — no server
  dependency for the helpers themselves.

Tests
- 6 new utils.test.js cases: [UTLF]-[UTLK] covering parse, serialize,
  round-trip, validation, and the StaleAccessIdError class. All
  passing.

Author: perki

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 <!-- Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) -->
 
+## [3.1.0]
+
+Plan 66 (open-pryv.io ≥ 2.0.0-pre.X): access versioning.
+
+### Added
+- `pryv.utils.parseAccessRef(ref) → { base, serial | null }` — parses the wire-format access reference. Bare cuid → `{ base, serial: null }`, composite `<base>:<serial>` → `{ base, serial: <int> }`. Throws on malformed input.
+- `pryv.utils.serializeAccessRef({ base, serial }) → string` — inverse helper.
+- `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?: [...] }`.
+
+### 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.
+
 ## [3.0.4](https://github.com/pryv/lib-js/compare/3.0.3...3.0.4)
 
 ### Added

components/pryv/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pryv",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "Pryv JavaScript library",
   "keywords": [
     "Pryv",

components/pryv/src/Connection.js

@@ -6,6 +6,7 @@ const utils = require('./utils.js');
 const jsonParser = require('./lib/json-parser');
 const libGetEventStreamed = require('./lib/getEventStreamed');
 const PryvError = require('./lib/PryvError');
+const StaleAccessIdError = require('./lib/StaleAccessIdError');
 const buildSearchParams = require('./lib/buildSearchParams');
 
 /**
@@ -416,6 +417,48 @@ class Connection {
     return utils.buildAPIEndpoint(this);
   }
 
+  /**
+   * Plan 66 (open-pryv.io ≥ 2.0.0-pre.X): update an access by composite id.
+   * Wraps `accesses.update` and translates the 409 `stale-resource` response
+   * into a typed `StaleAccessIdError` so callers can `instanceof`-test and
+   * refetch + retry without re-parsing the inner error.
+   *
+   * Pass `id` as the wire-format reference returned by the server — bare
+   * cuid on a never-updated access, composite `<base>:<serial>` otherwise.
+   * `changes` is the body of mutable fields (name, deviceName, permissions,
+   * expireAfter, expires:null, clientData).
+   *
+   * @param {string} id
+   * @param {Object} changes
+   * @returns {Promise<Object>} the updated access (with new composite id)
+   * @throws {StaleAccessIdError} if the server reports the id is stale
+   */
+  async updateAccess (id, changes) {
+    try {
+      return await this.apiOne('accesses.update', { id, update: changes }, 'access');
+    } catch (e) {
+      if (e && e.innerObject && e.innerObject.id === 'stale-resource') {
+        throw new StaleAccessIdError(e.message, e.innerObject.data || {});
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Plan 66: fetch an access by composite id including its full version
+   * history (oldest first). Server: `accesses.getOne ?includeHistory=true`.
+   *
+   * Useful for audit views. Pass the composite `<base>:<serial>` to
+   * inspect a specific past version (the result's `current` field then
+   * points at the live head's composite id).
+   *
+   * @param {string} id
+   * @returns {Promise<{ access: Object, current?: string, history?: Object[] }>}
+   */
+  async getAccessWithHistory (id) {
+    return await this.apiOne('accesses.getOne', { id, includeHistory: true });
+  }
+
   // private method that handle meta data parsing
   _handleMeta (res, requestLocalTimestamp) {
     if (!res.meta) throw new Error('Cannot find .meta in response.');

components/pryv/src/index.js

@@ -10,6 +10,8 @@
  * @property {pryv.Browser} Browser - Browser Tools - Access request helpers and visuals (button)
  * @property {pryv.utils} utils - Exposes some utils for HTTP calls and tools to manipulate Pryv's API endpoints
  * @property {pryv.PryvError} PryvError - Custom error class with innerObject + structured API-error fields
+ * @property {pryv.MfaRequiredError} MfaRequiredError - Thrown by Service.login when the platform returns an mfaToken instead of a token. Carries `.mfaToken`.
+ * @property {pryv.StaleAccessIdError} StaleAccessIdError - Plan 66: thrown when a Pryv.io server rejects an `accesses.update` / `accesses.delete` with a 409 stale-resource. Refetch + retry.
  * @property {Object} ERRORS - Catalogue of Pryv API error ids (mirrors open-pryv.io/components/errors)
  */
 module.exports = {
@@ -20,6 +22,7 @@ module.exports = {
   utils: require('./utils'),
   PryvError: require('./lib/PryvError'),
   MfaRequiredError: require('./lib/MfaRequiredError'),
+  StaleAccessIdError: require('./lib/StaleAccessIdError'),
   ERRORS: require('./lib/errorIds'),
   version: require('../package.json').version
 };

components/pryv/src/lib/StaleAccessIdError.js

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+const PryvError = require('./PryvError');
+
+/**
+ * Plan 66: typed error surfaced when a Pryv.io server (≥ 2.0.0-pre.X)
+ * rejects an `accesses.update` or `accesses.delete` call with a
+ * 409 `stale-resource` response.
+ *
+ * The composite access id `<base>:<serial>` carries the version the
+ * caller last observed. If the access has since been updated, the
+ * server rejects the call so the caller refetches the current head
+ * (`connection.api('accesses.getOne', { id: base })`) and retries
+ * with the fresh composite id.
+ *
+ * Reach for `.data.provided` to see what the caller sent and
+ * `.data.currentSerial` to see what the server currently has.
+ *
+ * @extends PryvError
+ */
+class StaleAccessIdError extends PryvError {
+  /**
+   * @param {string} message
+   * @param {{ provided?: string, currentSerial?: number | null }} data
+   */
+  constructor (message, data) {
+    super(message);
+    this.name = 'StaleAccessIdError';
+    /** @type {{ provided?: string, currentSerial?: number | null }} */
+    this.data = data || {};
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, StaleAccessIdError);
+    }
+  }
+}
+
+module.exports = StaleAccessIdError;

components/pryv/src/utils.js

@@ -155,6 +155,56 @@ const utils = module.exports = {
     return url.replace(PRYV_REGEXP, '');
   },
 
+  /**
+   * Plan 66 (open-pryv.io ≥ 2.0.0-pre.X): parse a wire-format access
+   * reference into `{ base, serial }`. Accepts both bare cuid
+   * (`"abc123"` → `{ base: 'abc123', serial: null }`) and composite
+   * (`"abc123:3"` → `{ base: 'abc123', serial: 3 }`). Throws on
+   * malformed input. Apply this to `access.id`, `access.createdBy`,
+   * `access.modifiedBy`, and `streamIds` entries of the form
+   * `access-<base>:<serial>` from audit events.
+   * @memberof pryv.utils
+   * @param {string} ref - Access reference string
+   * @returns {{ base: string, serial: number | null }}
+   */
+  parseAccessRef: function (ref) {
+    if (typeof ref !== 'string' || ref.length === 0) {
+      throw new Error('parseAccessRef: expected a non-empty string, got ' + JSON.stringify(ref));
+    }
+    const colonIdx = ref.indexOf(':');
+    if (colonIdx === -1) return { base: ref, serial: null };
+    const base = ref.slice(0, colonIdx);
+    const tail = ref.slice(colonIdx + 1);
+    if (base.length === 0) {
+      throw new Error('parseAccessRef: empty base in ' + JSON.stringify(ref));
+    }
+    const serial = Number(tail);
+    if (!Number.isInteger(serial) || serial < 1) {
+      throw new Error('parseAccessRef: serial must be a positive integer, got ' + JSON.stringify(tail));
+    }
+    return { base, serial };
+  },
+
+  /**
+   * Plan 66: render an `{ base, serial }` pair back to the wire
+   * format. Bare cuid when serial is null/undefined; `<base>:<serial>`
+   * otherwise. Mostly used to construct the composite id when calling
+   * `connection.api()` for `accesses.update` / `accesses.delete`.
+   * @memberof pryv.utils
+   * @param {{ base: string, serial?: number | null }} ref
+   * @returns {string}
+   */
+  serializeAccessRef: function (ref) {
+    if (ref == null || typeof ref.base !== 'string' || ref.base.length === 0) {
+      throw new Error('serializeAccessRef: ref.base must be a non-empty string');
+    }
+    if (ref.serial == null) return ref.base;
+    if (!Number.isInteger(ref.serial) || ref.serial < 1) {
+      throw new Error('serializeAccessRef: serial must be a positive integer, got ' + JSON.stringify(ref.serial));
+    }
+    return ref.base + ':' + ref.serial;
+  },
+
   /**
    * Extract query parameters from a URL
    * @memberof pryv.utils

components/pryv/test/utils.test.js

@@ -59,4 +59,48 @@ describe('[UTLX] utils', function () {
     expect(apiEndpoint).to.equal(testData.apiEndpoint);
     done();
   });
+
+  // Plan 66 — composite access references.
+
+  it('[UTLF] parseAccessRef on a bare cuid returns { base, serial: null }', function () {
+    const ref = pryv.utils.parseAccessRef('abc123def456');
+    expect(ref).to.eql({ base: 'abc123def456', serial: null });
+  });
+
+  it('[UTLG] parseAccessRef on a composite returns { base, serial }', function () {
+    const ref = pryv.utils.parseAccessRef('abc123:7');
+    expect(ref).to.eql({ base: 'abc123', serial: 7 });
+  });
+
+  it('[UTLH] parseAccessRef on garbage throws', function () {
+    expect(() => pryv.utils.parseAccessRef('')).to.throw();
+    expect(() => pryv.utils.parseAccessRef(':1')).to.throw();
+    expect(() => pryv.utils.parseAccessRef('abc:notanumber')).to.throw();
+    expect(() => pryv.utils.parseAccessRef('abc:0')).to.throw();
+    expect(() => pryv.utils.parseAccessRef('abc:-1')).to.throw();
+    expect(() => pryv.utils.parseAccessRef(null)).to.throw();
+  });
+
+  it('[UTLI] serializeAccessRef round-trips parseAccessRef', function () {
+    const samples = ['plainCuid', 'plainCuid:1', 'plainCuid:42'];
+    for (const s of samples) {
+      expect(pryv.utils.serializeAccessRef(pryv.utils.parseAccessRef(s))).to.equal(s);
+    }
+  });
+
+  it('[UTLJ] serializeAccessRef rejects bad inputs', function () {
+    expect(() => pryv.utils.serializeAccessRef(null)).to.throw();
+    expect(() => pryv.utils.serializeAccessRef({ base: '' })).to.throw();
+    expect(() => pryv.utils.serializeAccessRef({ base: 'abc', serial: 0 })).to.throw();
+    expect(() => pryv.utils.serializeAccessRef({ base: 'abc', serial: 1.5 })).to.throw();
+  });
+
+  it('[UTLK] StaleAccessIdError extends PryvError', function () {
+    const err = new pryv.StaleAccessIdError('stale!', { provided: 'abc:1', currentSerial: 2 });
+    expect(err).to.be.instanceOf(pryv.StaleAccessIdError);
+    expect(err).to.be.instanceOf(pryv.PryvError);
+    expect(err.data.provided).to.equal('abc:1');
+    expect(err.data.currentSerial).to.equal(2);
+    expect(err.name).to.equal('StaleAccessIdError');
+  });
 });