@pryv/cmc: API ergonomics — revokeRelationship({inviteEventId}) + require explicit scopeStreamId on accept/refuse

Surfaced while adapting Plan 68 validation scenarios to use the new
package. Pre-publish polish of the v1.0.0 surface.

revokeRelationship
- Now accepts EITHER { accessId, scopeStreamId, reason? } (existing power-user
  path) OR { inviteEventId, scopeStreamId?, reason? } (new convenience path).
- The inviteEventId path reads the invite event + the matching consent/accept-cmc
  on :_cmc:inbox (matched via originalEventId / requestEventId / inviteEventId
  in the accept's content) and pulls backChannelAccessId from there.
- scopeStreamId auto-derived from the invite event's own stream when not
  given.

acceptInvite + refuseInvite
- Previous default scopeStreamId was ':_cmc:apps:patient:incoming' which (a)
  requires the accepter to pre-create that sub-stream and (b) the
  default-fallback case isn't actually safer than throwing. Now REQUIRED.
- Bad-default trap: ':_cmc:inbox' is the inbox stream — events written there
  route through the peer-delivered handleIncomingAccept path, not the local
  handleAccept. The error message points this out so callers don't
  accidentally pick it.

listAcceptedRelationships
- Default scopeStreamId changed from ':_cmc:apps:patient:incoming' to NS_APPS
  (':_cmc:apps') so the recursive default covers every app scope on the
  account (matches the user mental model of 'list everything I've accepted').

Tests: 4 [CMCL1A*] tests updated to pass explicit scopeStreamId. 43/43 still
passing. common.js in _plans/68/tests/ continues to load (already passed
explicit scopeStreamId).

createInvite features key
- Spec asked for {chat, system}; server-side validators.ts requires
  {chat, systemMessaging}. Kept current (correct) {chat, systemMessaging}
  shape. Documented in CHANGELOG.

Bumps minor not needed — this is still pre-publish work on the same v1.0.0
release branch.

Author: perki

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

@@ -185,11 +185,17 @@ declare module '@pryv/cmc' {
 
   export function getInviteStatus(conn: any, inviteEventId: string): Promise<InviteRecord>;
 
-  export function revokeRelationship(conn: any, params: {
-    scopeStreamId: string;
-    accessId: string;
-    reason?: Record<string, string>;
-  }): Promise<void>;
+  /**
+   * Revoke a relationship (provider side). Two ways to identify the
+   * relationship:
+   *   1. `{ accessId, scopeStreamId, reason? }` — power-user path.
+   *   2. `{ inviteEventId, scopeStreamId?, reason? }` — convenience path;
+   *      derives `accessId` from the matching inbox accept event.
+   */
+  export function revokeRelationship(conn: any, params:
+    | { accessId: string; scopeStreamId: string; reason?: Record<string, string> }
+    | { inviteEventId: string; scopeStreamId?: string; reason?: Record<string, string> }
+  ): Promise<void>;
 
   export function invalidateCapability(conn: any, params: {
     inviteEventId: string;
@@ -214,8 +220,13 @@ declare module '@pryv/cmc' {
     features: { chat?: boolean; systemMessaging?: boolean };
   }>;
 
-  export function acceptInvite(conn: any, capabilityUrl: string, opts?: {
-    scopeStreamId?: string;
+  /**
+   * Accept an offer. `opts.scopeStreamId` is REQUIRED — must be an
+   * `:_cmc:apps:<app>[:...]` stream on the accepter's account. Do not
+   * pass `:_cmc:inbox` (which routes through the peer-delivered path).
+   */
+  export function acceptInvite(conn: any, capabilityUrl: string, opts: {
+    scopeStreamId: string;
     extra?: { chat?: boolean; systemMessaging?: boolean };
     accessName?: string;
     waitForCompletion?: boolean;
@@ -226,8 +237,12 @@ declare module '@pryv/cmc' {
     | { acceptEventId: string; dataGrantAccessId: string | null; dataGrantApiEndpoint: string | null; counterparty: any; features: any }
   >;
 
-  export function refuseInvite(conn: any, capabilityUrl: string, opts?: {
-    scopeStreamId?: string;
+  /**
+   * Refuse an offer. `opts.scopeStreamId` is REQUIRED — same constraints
+   * as `acceptInvite`.
+   */
+  export function refuseInvite(conn: any, capabilityUrl: string, opts: {
+    scopeStreamId: string;
     reason?: Record<string, string>;
   }): Promise<{ refuseEventId: string }>;
 

components/pryv-cmc/src/index.js

@@ -411,19 +411,63 @@ async function getInviteStatus (conn, inviteEventId) {
  * `consent/revoke-cmc` event with `{ accessId, reason }`; plugin
  * orchestrates dual delete.
  *
+ * Two ways to identify the relationship:
+ *   1. `{ accessId, scopeStreamId, reason? }` — power-user path, pass
+ *      the back-channel access id directly.
+ *   2. `{ inviteEventId, scopeStreamId?, reason? }` — convenience path.
+ *      Reads the invite event + matching inbox accept to derive
+ *      `backChannelAccessId`. Two extra API calls. Defaults
+ *      `scopeStreamId` to the invite event's own stream.
+ *
  * @param {Object} conn
  * @param {Object} params
- * @param {string} params.scopeStreamId           - own scope to write into
- * @param {string} params.accessId                - back-channel access id (provider side)
+ * @param {string} [params.accessId]              - back-channel access id (provider side)
+ * @param {string} [params.inviteEventId]         - alternative to accessId
+ * @param {string} [params.scopeStreamId]         - own scope to write into (required with accessId; auto-derived with inviteEventId)
  * @param {Object} [params.reason]
  * @returns {Promise<void>}
  */
 async function revokeRelationship (conn, params) {
   if (params == null) throw new Error('revokeRelationship: params required');
-  const content = { accessId: params.accessId };
+  let accessId = params.accessId;
+  let scopeStreamId = params.scopeStreamId;
+  if (!accessId) {
+    if (!params.inviteEventId) {
+      throw new Error('revokeRelationship: provide accessId, or inviteEventId for lookup');
+    }
+    const inviteEvent = await conn.apiOne('events.getOne', { id: params.inviteEventId }, 'event');
+    if (!inviteEvent) {
+      throw new Error('revokeRelationship: invite event not found: ' + params.inviteEventId);
+    }
+    if (!scopeStreamId) {
+      scopeStreamId = (inviteEvent.streamIds && inviteEvent.streamIds[0]) || inviteEvent.streamId;
+    }
+    const acceptsRaw = await conn.apiOne('events.get', {
+      streams: [NS_INBOX],
+      types: [ET_ACCEPT],
+      limit: 200
+    }, 'events');
+    const match = (acceptsRaw || []).find(function (e) {
+      const c = e.content || {};
+      return c.originalEventId === params.inviteEventId ||
+             c.requestEventId === params.inviteEventId ||
+             c.inviteEventId === params.inviteEventId;
+    });
+    if (!match) {
+      throw new Error('revokeRelationship: no inbox accept found for invite ' + params.inviteEventId);
+    }
+    accessId = match.content && match.content.backChannelAccessId;
+    if (!accessId) {
+      throw new Error('revokeRelationship: inbox accept ' + match.id + ' has no backChannelAccessId');
+    }
+  }
+  if (!scopeStreamId) {
+    throw new Error('revokeRelationship: scopeStreamId is required with accessId path');
+  }
+  const content = { accessId };
   if (params.reason) content.reason = params.reason;
   await conn.apiOne('events.create', {
-    streamIds: [params.scopeStreamId],
+    streamIds: [scopeStreamId],
     type: ET_REVOKE,
     content
   }, 'event');
@@ -560,8 +604,8 @@ async function readOffer (capabilityUrl, opts) {
  *
  * @param {Object} conn                     accepter's connection
  * @param {string} capabilityUrl
- * @param {Object} [opts]
- * @param {string} [opts.scopeStreamId]     - own scope to write the accept into (default ':_cmc:apps:patient:incoming')
+ * @param {Object} opts
+ * @param {string} opts.scopeStreamId       - REQUIRED. Own :_cmc:apps:<app>[:...] stream where the accept trigger lands. Must NOT be :_cmc:inbox (which routes through the peer-delivered path).
  * @param {{chat?:boolean,systemMessaging?:boolean}} [opts.extra]
  * @param {string} [opts.accessName]
  * @param {boolean} [opts.waitForCompletion=true]
@@ -571,7 +615,12 @@ async function readOffer (capabilityUrl, opts) {
  */
 async function acceptInvite (conn, capabilityUrl, opts) {
   opts = opts || {};
-  const scopeStreamId = opts.scopeStreamId || ':_cmc:apps:patient:incoming';
+  if (!opts.scopeStreamId) {
+    throw new Error('acceptInvite: opts.scopeStreamId is required ' +
+      '(an :_cmc:apps:<app>[:...] stream on YOUR account where the accept ' +
+      'trigger lands — not :_cmc:inbox, which routes through the peer-delivered path)');
+  }
+  const scopeStreamId = opts.scopeStreamId;
   const content = { capabilityUrl };
   if (opts.extra) content.extra = opts.extra;
   if (opts.accessName) content.accessName = opts.accessName;
@@ -632,14 +681,18 @@ function sleep (ms) {
  *
  * @param {Object} conn
  * @param {string} capabilityUrl
- * @param {Object} [opts]
- * @param {string} [opts.scopeStreamId]
+ * @param {Object} opts
+ * @param {string} opts.scopeStreamId       - REQUIRED. Own :_cmc:apps:<app>[:...] stream where the refuse trigger lands.
  * @param {Object} [opts.reason]
  * @returns {Promise<{refuseEventId:string}>}
  */
 async function refuseInvite (conn, capabilityUrl, opts) {
   opts = opts || {};
-  const scopeStreamId = opts.scopeStreamId || ':_cmc:apps:patient:incoming';
+  if (!opts.scopeStreamId) {
+    throw new Error('refuseInvite: opts.scopeStreamId is required ' +
+      '(an :_cmc:apps:<app>[:...] stream on YOUR account where the refuse trigger lands)');
+  }
+  const scopeStreamId = opts.scopeStreamId;
   const content = { capabilityUrl };
   if (opts.reason) content.reason = opts.reason;
   const event = await conn.apiOne('events.create', {
@@ -677,13 +730,16 @@ async function revokeAcceptance (conn, params) {
  *
  * @param {Object} conn
  * @param {Object} [params]
- * @param {string} [params.scopeStreamId=':_cmc:apps:patient:incoming']
+ * @param {string} [params.scopeStreamId=':_cmc:apps']  - root or sub-scope to search recursively
  * @param {number} [params.limit=1000]
  * @returns {Promise<Array>}
  */
 async function listAcceptedRelationships (conn, params) {
   params = params || {};
-  const streams = [params.scopeStreamId || ':_cmc:apps:patient:incoming'];
+  // Default to the apps root (recursive) so callers get every relationship
+  // across all of their app scopes. Pass `params.scopeStreamId` for a narrower
+  // view (e.g. a single app or sub-scope).
+  const streams = [params.scopeStreamId || NS_APPS];
   const limit = params.limit || 1000;
   const events = await conn.apiOne('events.get', {
     streams,

components/pryv-cmc/test/cmc.test.js

@@ -414,7 +414,7 @@ describe('[CMCL1] @pryv/cmc Level-1 protocol functions', function () {
           }
         }
       });
-      const r = await cmc.acceptInvite(conn, 'https://t@x.example.com/', { waitForCompletion: false });
+      const r = await cmc.acceptInvite(conn, 'https://t@x.example.com/', { scopeStreamId: ':_cmc:apps:test', waitForCompletion: false });
       expect(r).to.deep.equal({ acceptEventId: 'acc-1', dataGrantAccessId: null, status: 'pending' });
       expect(conn.calls).to.have.length(1);
     });
@@ -443,7 +443,7 @@ describe('[CMCL1] @pryv/cmc Level-1 protocol functions', function () {
           }
         }
       });
-      const r = await cmc.acceptInvite(conn, 'https://t@x/', { completionPollIntervalMs: 5, completionTimeoutMs: 1000 });
+      const r = await cmc.acceptInvite(conn, 'https://t@x/', { scopeStreamId: ':_cmc:apps:test', completionPollIntervalMs: 5, completionTimeoutMs: 1000 });
       expect(r.acceptEventId).to.equal('acc-2');
       expect(r.dataGrantAccessId).to.equal('dg-1');
       expect(r.counterparty).to.deep.equal({ username: 'alice', host: 'pryv.me' });
@@ -463,7 +463,7 @@ describe('[CMCL1] @pryv/cmc Level-1 protocol functions', function () {
       });
       let err = null;
       try {
-        await cmc.acceptInvite(conn, 'https://t@x/', { completionPollIntervalMs: 5, completionTimeoutMs: 1000 });
+        await cmc.acceptInvite(conn, 'https://t@x/', { scopeStreamId: ':_cmc:apps:test', completionPollIntervalMs: 5, completionTimeoutMs: 1000 });
       } catch (e) { err = e; }
       expect(err).to.exist;
       expect(err).to.be.instanceOf(cmc.CmcError);
@@ -478,7 +478,7 @@ describe('[CMCL1] @pryv/cmc Level-1 protocol functions', function () {
           }
         }
       });
-      const r = await cmc.refuseInvite(conn, 'https://t@x/', { reason: { en: 'no' } });
+      const r = await cmc.refuseInvite(conn, 'https://t@x/', { scopeStreamId: ':_cmc:apps:test', reason: { en: 'no' } });
       expect(conn.calls[0].params.type).to.equal('consent/refuse-cmc');
       expect(r.refuseEventId).to.equal('rf-1');
     });