Refactor interactions to use "interaction types" terminology.

Author: dlongley

lib/config.js

@@ -48,14 +48,14 @@ cc(`${meterServiceName}.url`, () => `${bedrock.config.server.baseUri}/meters`);
 // ensure meter service config is overridden in deployments
 config.ensureConfigOverride.fields.push(meterServiceName);
 
-// optional interaction config
+// optional interactions config
 cfg.interactions = {
   // FIXME: add qr-code route fallback for non-accept-json "protocols" requests
   enabled: false,
-  // named workflows for interactions
+  // types of interactions, type name => definition
   /* Spec:
   {
-    <workflow name>: {
+    <interaction type name>: {
       ...,
       // a unique local interaction ID for use in interaction URLs
       localInteractionId,
@@ -65,5 +65,5 @@ cfg.interactions = {
     }
   }
   */
-  workflows: {}
+  types: {}
 };

lib/interactions.js

@@ -13,54 +13,52 @@ import {ZCAP_CLIENT as zcapClient} from './zcapClient.js';
 
 const {config, util: {BedrockError}} = bedrock;
 
-let WORKFLOWS_BY_NAME_MAP;
-let WORKFLOWS_BY_ID_MAP;
+let DEFINITIONS_BY_TYPE_MAP;
+let DEFINITIONS_BY_ID_MAP;
 
 bedrock.events.on('bedrock.init', () => {
   const cfg = config['profile-http'];
 
   // interactions feature is optional, return early if not enabled
-  const {interactions} = cfg;
-  if(!interactions?.enabled) {
+  if(!cfg.interactions?.enabled) {
     return;
   }
 
-  // parse workflow configs when interactions are enabled
-  const {workflows = {}} = interactions;
-  WORKFLOWS_BY_NAME_MAP = new Map();
-  WORKFLOWS_BY_ID_MAP = new Map();
-  for(const workflowName in workflows) {
-    const {localInteractionId, zcaps} = workflows[workflowName];
+  // parse interaction types when enabled
+  const {types = {}} = cfg.interactions;
+  DEFINITIONS_BY_TYPE_MAP = new Map();
+  DEFINITIONS_BY_ID_MAP = new Map();
+  for(const typeName in types) {
+    const {localInteractionId, zcaps} = types[typeName];
     if(!localInteractionId) {
       throw new TypeError(
-        '"bedrock.config.profile-http.interactions.workflows" must each ' +
+        '"bedrock.config.profile-http.interaction.types" must each ' +
         'have "localInteractionId".');
     }
-    const workflow = {
+    const definition = {
+      name: typeName,
       localInteractionId,
-      name: workflowName,
       zcaps: new Map()
     };
     for(const zcapName in zcaps) {
       const zcap = zcaps[zcapName];
-      workflow.zcaps.set(zcapName, JSON.parse(zcap));
+      definition.zcaps.set(zcapName, JSON.parse(zcap));
     }
-    if(!workflow.zcaps.has('readWriteExchanges')) {
+    if(!definition.zcaps.has('readWriteExchanges')) {
       throw new TypeError(
-        '"bedrock.config.profile-http.interactions.workflows" must each ' +
+        '"bedrock.config.profile-http.interaction.types" must each ' +
         'have "zcaps.readWriteExchanges".');
     }
-    WORKFLOWS_BY_NAME_MAP.set(workflowName, workflow);
-    WORKFLOWS_BY_ID_MAP.set(localInteractionId, workflow);
+    DEFINITIONS_BY_TYPE_MAP.set(typeName, definition);
+    DEFINITIONS_BY_ID_MAP.set(localInteractionId, definition);
   }
 });
 
 bedrock.events.on('bedrock-express.configure.routes', app => {
   const cfg = config['profile-http'];
 
-  // interactions feature is optional, return early if not enabled
-  const {interactions} = cfg;
-  if(!interactions?.enabled) {
+  // interaction feature is optional, return early if not enabled
+  if(!cfg.interactions?.enabled) {
     return;
   }
 
@@ -77,11 +75,11 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
     validate({bodySchema: schemas.createInteraction}),
     asyncHandler(async (req, res) => {
       const {id: accountId} = req.user.account || {};
-      const {workflowName, exchange: {variables}} = req.body;
+      const {type, exchange: {variables}} = req.body;
 
-      const workflow = WORKFLOWS_BY_NAME_MAP.get(workflowName);
-      if(!workflow) {
-        throw new BedrockError(`Workflow "${workflowName}" not found.`, {
+      const definition = DEFINITIONS_BY_TYPE_MAP.get(type);
+      if(!definition) {
+        throw new BedrockError(`Interaction type "${type}" not found.`, {
           name: 'NotFoundError',
           details: {
             httpStatusCode: 404,
@@ -101,18 +99,18 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
           accountId
         }
       };
-      const capability = workflow.zcaps.get('readWriteExchanges');
+      const capability = definition.zcaps.get('readWriteExchanges');
       const response = await zcapClient.write({json: exchange, capability});
       const exchangeId = response.headers.get('location');
-      const {localInteractionId} = workflow;
+      const {localInteractionId} = definition;
       // reuse `localExchangeId` in path
       const localExchangeId = exchangeId.slice(exchangeId.lastIndexOf('/'));
       const id = `${config.server.baseUri}/${routes.interactions}/` +
         `${localInteractionId}/${localExchangeId}`;
       res.json({interactionId: id, exchangeId});
     }));
 
-  // gets an interaction by its "id"
+  // gets an interaction
   app.get(
     routes.interaction,
     ensureAuthenticated,
@@ -124,20 +122,18 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
         query: {iuv}
       } = req;
 
-      const workflow = WORKFLOWS_BY_ID_MAP.get(localInteractionId);
-      if(!workflow) {
+      // get interaction definition
+      const definition = DEFINITIONS_BY_ID_MAP.get(localInteractionId);
+      if(!definition) {
         throw new BedrockError(
-          `Workflow "${localInteractionId}" not found.`, {
+          `Interaction type for "${localInteractionId}" not found.`, {
             name: 'NotFoundError',
-            details: {
-              httpStatusCode: 404,
-              public: true
-            }
+            details: {httpStatusCode: 404, public: true}
           });
       }
 
       // determine full exchange ID based on related capability
-      const capability = workflow.zcaps.get('readWriteExchanges');
+      const capability = definition.zcaps.get('readWriteExchanges');
       const exchangeId = `${capability.invocationTarget}/${localExchangeId}`;
 
       // if an "Interaction URL Version" is present send "protocols"
@@ -172,10 +168,10 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
           filterExchange({exchange/*, previousPollResult*/}) {
             // ensure `accountId` matches exchange variables
             if(exchange?.variables.accountId !== accountId) {
-              throw new BedrockError(
-                'Not authorized.',
-                'NotAllowedError',
-                {httpStatusCode: 403, public: true});
+              throw new BedrockError('Not authorized.', {
+                name: 'NotAllowedError',
+                details: {httpStatusCode: 403, public: true}
+              });
             }
             // return only information that should be accessible to client
             return {

schemas/bedrock-profile-http.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2020-2024 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2020-2025 Digital Bazaar, Inc. All rights reserved.
  */
 const account = {
   title: 'Account',
@@ -165,10 +165,10 @@ const delegateCapability = {
 const createInteraction = {
   title: 'Create Interaction',
   type: 'object',
-  required: ['workflowName', 'exchange'],
+  required: ['type', 'exchange'],
   additionalProperties: false,
   properties: {
-    workflowName: {
+    type: {
       type: 'string'
     },
     exchange: {

test/mocha/10-api.js

@@ -848,7 +848,7 @@ describe('bedrock-profile-http', () => {
     });
   });
   describe('interactions', () => {
-    // FIXME: create workflow instance
+    // FIXME: create associated workflow instance
     // before()
     it('fails to create a new interaction with bad post data', async () => {
       let result;
@@ -865,12 +865,12 @@ describe('bedrock-profile-http', () => {
       result.data.message.should.equal(
         `A validation error occurred in the 'Create Interaction' validator.`);
     });
-    it('fails to create a new interaction with unknown workflow', async () => {
+    it('fails to create a new interaction with unknown type', async () => {
       let result;
       let error;
       try {
         result = await api.post('/interactions', {
-          workflowName: 'does-not-exist',
+          type: 'does-not-exist',
           exchange: {
             variables: {}
           }
@@ -883,7 +883,8 @@ describe('bedrock-profile-http', () => {
       result.status.should.equal(404);
       result.ok.should.equal(false);
       result.data.name.should.equal('NotFoundError');
-      result.data.message.should.equal('Workflow "does-not-exist" not found.');
+      result.data.message.should.equal(
+        'Interaction type "does-not-exist" not found.');
     });
     it.skip('creates a new interaction', async () => {
       let interactionId;
@@ -892,7 +893,7 @@ describe('bedrock-profile-http', () => {
         let error;
         try {
           result = await api.post('/interactions', {
-            workflowName: 'test',
+            type: 'test',
             exchange: {
               variables: {}
             }

test/test.config.js

@@ -39,7 +39,7 @@ config['profile-http'].additionalEdvs = {
 
 // enable optional `interactions`
 config['profile-http'].interactions.enabled = true;
-config['profile-http'].interactions.workflows.test = {
+config['profile-http'].interactions.types.test = {
   localInteractionId: '1d35d09b-94c8-44d5-9d10-8dd3460a5fc4',
   zcaps: {
     // FIXME: