anear-js-api 0.4.40 → 0.5.3

package/EACH_PARTICIPANT_LIFECYCLE.md

@@ -0,0 +1,144 @@
+# The `eachParticipant` Display Lifecycle
+
+This document provides a detailed, step-by-by-step breakdown of how a display targeted at `eachParticipant` travels from the application's state machine (AppM) to an individual participant's browser client.
+
+### The Goal
+
+We want to render a specific view (`QuestionScreen.pug`) for a single user (`participant-123`) and make sure they answer within 10 seconds.
+
+### The Big Picture
+
+The core idea is to translate a declarative `meta` block in your application's state machine (AppM) into concrete HTML content that gets delivered to a specific participant's device. This process involves a chain of components:
+
+`AppMachineTransition` -> `AnearEventMachine` -> `DisplayEventProcessor` -> `AnearParticipantMachine` -> **Ably Message**
+
+Let's break down each step.
+
+---
+
+### Part 1: The Trigger (Your AppM & `AppMachineTransition.js`)
+
+It all starts in your application-specific state machine (e.g., `anear-q-and-a/StateMachine.js`). When your machine enters a state that needs to display something to participants, you define a `meta` object.
+
+**Context:** The `meta` object is how your AppM communicates rendering intentions to the Anear platform. The `AppMachineTransition` module is a subscriber that listens for *every* state change in your AppM. Its job is to parse that `meta` object and translate it into a standardized command for the rest of the system.
+
+#### Code Example (Your AppM)
+Imagine your Q&A machine enters the `askQuestion` state. The state definition would look like this:
+
+```javascript
+// anear-q-and-a/StateMachine.js
+// ...
+confirmMove: {
+  meta: {
+    // 'eachParticipant' is a function for selective rendering.
+    // This example shows how to target a single participant based on the
+    // event that triggered this state transition.
+    eachParticipant: (appContext, event) => {
+      // 'event' is the event that led to this state, e.g., { type: 'MOVE', participantId: 'p1', ... }
+      const movingParticipantId = event.participantId;
+
+      if (!movingParticipantId) return []; // Always return an array
+
+      // We only want to send a display to the participant who just moved.
+      return [{
+        participantId: movingParticipantId,
+        view: 'participant/MoveConfirmation', // A view confirming their move was received
+        props: {
+          message: 'Your move has been recorded. Waiting for opponent...',
+          move: event.moveData
+        },
+        timeout: 2000 // A short timeout for the confirmation display
+      }];
+    }
+  }
+}
+// ...
+```
+
+#### Lifecycle Step 1: Parsing the `meta` block
+
+When your AppM transitions to `confirmMove`, the `AppMachineTransition` function is invoked.
+
+*   **File:** `/Users/machvee/dev/anear-js-api/lib/utils/AppMachineTransition.js`
+*   **Description:** It detects the `meta.eachParticipant` property. Since it's a function, it executes it, receiving the array of display instructions we defined above. It then iterates through that array. For each instruction, it creates a standardized "display event" object.
+*   **Code Reference (`AppMachineTransition.js` lines 62-95):**
+
+```javascript
+// ... inside AppMachineTransition.js
+if (meta.eachParticipant) {
+  if (typeof meta.eachParticipant === 'function') {
+    // This is our path: the selective rendering function
+    const participantRenderFunc = meta.eachParticipant;
+    const participantDisplays = participantRenderFunc(appContext, event); // Executes our function from the AppM
+
+    // ... loops through the returned array ...
+    participantDisplays.forEach(participantDisplay => {
+      if (participantDisplay && participantDisplay.participantId && participantDisplay.view) {
+        const timeout = participantDisplay.timeout || null;
+
+        // Packages the info into a standard object
+        displayEvent = RenderContextBuilder.buildDisplayEvent(
+          participantDisplay.view,
+          baseAppRenderContext,
+          'eachParticipant',
+          participantDisplay.participantId,
+          timeout
+        );
+        displayEvents.push(displayEvent);
+      }
+    });
+  } // ...
+}
+```
+
+#### Lifecycle Step 2: Sending the Command
+
+After processing all `meta` properties, `AppMachineTransition` bundles all the generated `displayEvent` objects into a single event and sends it to the `AnearEventMachine` (AEM).
+
+*   **File:** `/Users/machvee/dev/anear-js-api/lib/utils/AppMachineTransition.js`
+*   **Code Reference (lines 137-140):**
+
+```javascript
+if (displayEvents.length > 0) {
+  // Sends one event with a list of all rendering jobs
+  anearEvent.send('RENDER_DISPLAY', { displayEvents });
+}
+```
+
+---
+
+### Part 2: The Router (`AnearEventMachine.js`)
+
+**Context:** The `AnearEventMachine` (AEM) is the central orchestrator for an event. When it receives the `RENDER_DISPLAY` event, its role isn't to render anything itself, but to delegate the task to a specialized processor.
+
+#### Lifecycle Step 3: Delegation
+
+The AEM enters a rendering state (e.g., `announceRendering` or `liveRendering`) and invokes its `renderDisplay` service.
+
+*   **File:** `/Users/machvee/dev/anear-js-api/lib/state_machines/AnearEventMachine.js`
+*   **Description:** This service is simple: it creates an instance of `DisplayEventProcessor` and tells it to handle the `displayEvents` array we sent in the previous step.
+*   **Code Reference (lines 1144-1148):**
+
+```javascript
+// ... inside AnearEventMachine.js
+services: {
+  renderDisplay: async (context, event) => {
+    // The event here contains our { displayEvents } payload
+    const displayEventProcessor = new DisplayEventProcessor(context);
+    return await displayEventProcessor.processAndPublish(event.displayEvents);
+  },
+// ...
+```
+
+---
+
+### Part 3: The Processor (`DisplayEventProcessor.js`)
+
+**Context:** This class is the workhorse. It knows how to handle different display targets (`allParticipants`, `spectators`, `host`, and our target, `eachParticipant`). It's responsible for compiling the Pug templates and figuring out *who* gets the final HTML.
+
+#### Lifecycle Step 4: Processing and Routing the Display
+
+The `DisplayEventProcessor` loops through each `displayEvent` and, based on the target, decides what to do.
+
+*   **File:** `/Users/machvee/dev/anear-js-api/lib/utils/DisplayEventProcessor.js`
+*   **Description:** For an `eachParticipant`

package/RENDER_USAGE_EXAMPLES.md

@@ -18,15 +18,19 @@ const Config = {
       states: {
         registration: {
           meta: {
-            participants: 'ViewableGameBoard',
+            allParticipants: 'ViewableGameBoard',
             spectators: 'ViewableGameBoard'
           }
         },
         gameInProgress: {
           meta: {
-            participant: { 
-              view: 'PlayableGameBoard', 
-              timeout: calcParticipantTimeout 
+            eachParticipant: {
+              view: 'PlayableGameBoard',
+              timeout: calcParticipantTimeout,
+              props: {
+                title: "Your Move!",
+                highlightLastMove: true
+              }
             },
             spectators: 'ViewableGameBoard'
           }
@@ -51,26 +55,26 @@ const actions = {
   renderGameOver: (context, event) => {
     anearEvent.render(
       'GameOver',           // viewPath
-      'participants',       // displayType
+      'allParticipants',       // displayType
       context,              // appContext (AppM's context)
       event,                // event that triggered this render
       null,                 // timeout (null for no timeout)
       { winner: context.winningPlayerId } // additional props
     )
   },
-  
+
   // Render with timeout for participant displays
   renderWithTimeout: (context, event) => {
     anearEvent.render(
       'WaitingForMove',
-      'participant',
+      'eachParticipant',
       context,
       event,
       (appContext, participantId) => 30000, // 30 second timeout
       { currentPlayer: context.currentPlayerToken }
     )
   },
-  
+
   // Render for spectators
   renderForSpectators: (context, event) => {
     anearEvent.render(
@@ -95,11 +99,11 @@ const actions = {
       // Render winner display
       anearEvent.render(
         'WinnerDisplay',
-        'participants',
+        'allParticipants',
         context,
         event,
         null,
-        { 
+        {
           winner: context.winner,
           finalScore: context.score,
           gameDuration: context.gameDuration
@@ -109,14 +113,14 @@ const actions = {
       // Render tie display
       anearEvent.render(
         'TieDisplay',
-        'participants',
+        'allParticipants',
         context,
         event,
         null,
         { finalScore: context.score }
       )
     }
-    
+
     // Now close the event
     anearEvent.closeEvent()
   }
@@ -128,14 +132,14 @@ const actions = {
 ### `anearEvent.render(viewPath, displayType, appContext, event, timeout, props)`
 
 - **`viewPath`** (string): Template/view path to render (e.g., 'GameBoard', 'GameOver')
-- **`displayType`** (string): One of 'participants', 'participant', or 'spectators'
+- **`displayType`** (string): One of 'allParticipants', 'eachParticipant', or 'spectators'
 - **`appContext`** (Object): The AppM's context object (available in scope)
 - **`event`** (Object): The event that triggered this render (available in scope)
-- **`timeout`** (Function|number|null): 
+- **`timeout`** (Function|number|null):
   - `null`: No timeout
   - `number`: Fixed timeout in milliseconds
   - `Function`: Dynamic timeout function `(appContext, participantId) => msecs`
-- **`props`** (Object): Additional properties merged into meta (optional)
+- **`props`** (Object): Additional properties made available at the root of the pug template's render context (optional)
 
 ## When to Use Each Approach
 

package/lib/api/AnearApi.js

@@ -79,6 +79,28 @@ class AnearApi extends ApiService {
     logger.debug('getAppFontAssetsUploadUrls response:', attrs)
     return attrs
   }
+
+  async saveAppEventContext(eventId, appmContext) {
+    logger.debug(`API: POST developer events/${eventId}/app_event_context`)
+    const path = `events/${eventId}/app_event_context`
+    return this.postRaw(path, { appm_context: appmContext })
+  }
+
+  async getLatestAppEventContext(eventId) {
+    logger.debug(`API: GET developer events/${eventId}/app_event_context`)
+    const path = `events/${eventId}/app_event_context`
+    const json = await this.get(path)
+    const attrs = json.data && json.data.attributes ? json.data.attributes : {}
+    const eventIdAttr = attrs['event-id']
+    const raw = attrs['appm-context']
+    let appmContext = null
+    try {
+      appmContext = typeof raw === 'string' ? JSON.parse(raw) : raw
+    } catch (e) {
+      // leave appmContext as null if parsing fails
+    }
+    return { eventId: eventIdAttr, appmContext }
+  }
 }
 
 // Instantiate and export the API immediately

package/lib/api/ApiService.js

@@ -56,6 +56,18 @@ class ApiService {
     return this.issueRequest(request)
   }
 
+  postRaw(path, body={}) {
+    const urlString = `${this.api_base_url}/${path}`
+    const request = new fetch.Request(
+      urlString, {
+        method: 'POST',
+        headers: this.default_headers,
+        body: JSON.stringify(body)
+      }
+    )
+    return this.issueRequest(request)
+  }
+
   put(resource, id, attributes, relationships={}) {
     const payload = this.formatPayload(resource, attributes, relationships)
     const urlString = `${this.api_base_url}/${resource}/${id}`

package/lib/models/AnearEvent.js

@@ -1,5 +1,6 @@
 "use strict"
 const logger = require('../utils/Logger')
+const anearApi = require('../api/AnearApi')
 
 const JsonApiResource = require('./JsonApiResource')
 
@@ -46,6 +47,20 @@ class AnearEvent extends JsonApiResource {
     this.send("CLOSE")
   }
 
+  pauseEvent(context, resumeEvent = { type: 'RESUME' }) {
+    // Persist via AEM and acknowledge with PAUSED
+    this.send('PAUSE', { appmContext: { context, resumeEvent } })
+  }
+
+  saveEvent(context, resumeEvent = { type: 'RESUME' }) {
+    // Delegate save to the AEM; AEM will persist via ANAPI and acknowledge with SAVED
+    this.send('SAVE', { appmContext: { context, resumeEvent } })
+  }
+
+  bootParticipant(participantId, reason) {
+    this.send("BOOT_PARTICIPANT", { participantId, reason })
+  }
+
   render(viewPath, displayType, appContext, event, timeout = null, props = {}) {
     // Explicit render method for guaranteed rendering control
     // This complements the meta: {} approach for when you need explicit control
@@ -80,14 +95,6 @@ class AnearEvent extends JsonApiResource {
     })
   }
 
-  pauseEvent() {
-    this.send("PAUSE")
-  }
-
-  resumeEvent() {
-    this.send("RESUME")
-  }
-
   getClonedFromEvent() {
     // if the current event was a clone of previous event, fetch if from
     // Peristence and return
@@ -111,6 +118,18 @@ class AnearEvent extends JsonApiResource {
     return this.attributes.hosted
   }
 
+  get name() {
+    return this.attributes.name
+  }
+
+  get description() {
+    return this.attributes.description
+  }
+
+  get createdAt() {
+    return this.attributes['created-at']
+  }
+
   get participantTimeout() {
     // TODO: This probably should be set for each publishEventPrivateMessage
     // and then referenceable as an anear-data attribute in the html.  That way

package/lib/models/AnearParticipant.js

@@ -18,7 +18,8 @@ class AnearParticipant extends JsonApiResource {
       id: this.data.id,
       name: this.name,
       avatarUrl: this.avatarUrl,
-      geoLocation: this.geoLocation
+      geoLocation: this.geoLocation,
+      isHost: this.isHost
     }
   }
 
@@ -62,6 +63,10 @@ class AnearParticipant extends JsonApiResource {
     return this.attributes['private-channel-name']
   }
 
+  get isHost() {
+    return this.userType === HostUserType
+  }
+
   setMachine(service) {
     if (service) {
       this.send = service.send.bind(service)
@@ -69,11 +74,6 @@ class AnearParticipant extends JsonApiResource {
       this.send = () => {}
     }
   }
-
-
-  isHost() {
-    return this.userType === HostUserType
-  }
 }
 
 module.exports = AnearParticipant

package/lib/state_machines/AnearCoreServiceMachine.js

@@ -134,7 +134,7 @@ const AnearCoreServiceMachineConfig = appId => ({
       }
     },
     waitAnearEventLifecycleCommand: {
-      // The Anear API backend will send CREATE_EVENT messages with the event JSON data
+      // The Anear API backend will send CREATE_EVENT or LOAD_EVENT messages with the event JSON data
       // to this createEventMessages Channel when it needs to create a new instance of an
       // Event
       entry: (context) => logger.debug(`Waiting on ${context.appData.data.attributes['short-name']} lifecycle command`),
@@ -142,6 +142,9 @@ const AnearCoreServiceMachineConfig = appId => ({
         CREATE_EVENT: {
           actions: ['startNewEventMachine']
         },
+        LOAD_EVENT: {
+          actions: ['startNewEventMachine']
+        },
         EVENT_MACHINE_EXIT: {
           actions: [
             'cleanupEventMachine'
@@ -234,6 +237,11 @@ const AnearCoreServiceMachineFunctions = {
         context.coreServiceMachine,
         'CREATE_EVENT'
       )
+      RealtimeMessaging.subscribe(
+        context.newEventCreationChannel,
+        context.coreServiceMachine,
+        'LOAD_EVENT'
+      )
     },
     startNewEventMachine: assign(
       {
@@ -242,11 +250,12 @@ const AnearCoreServiceMachineFunctions = {
           const anearEvent = new AnearEvent(eventJSON)
 
           if (context.anearEventMachines[anearEvent.id]) {
-            logger.info(`[ACSM] Event machine for ${anearEvent.id} already exists. Ignoring CREATE_EVENT.`)
+            logger.info(`[ACSM] Event machine for ${anearEvent.id} already exists. Ignoring ${event.type}.`)
             return context.anearEventMachines
           }
 
-          const service = AnearEventMachine(anearEvent, context)
+          const isLoadEvent = event.type === 'LOAD_EVENT'
+          const service = AnearEventMachine(anearEvent, { ...context, rehydrate: isLoadEvent })
 
           return {
             ...context.anearEventMachines,