anear-js-api 0.5.2 → 0.5.4

package/EACH_PARTICIPANT_LIFECYCLE.md

@@ -43,6 +43,10 @@ confirmMove: {
       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
       }];
     }
@@ -137,94 +141,4 @@ services: {
 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` target, it doesn't publish to a public channel. Instead, it performs a critical handoff: it finds the specific participant's own state machine (`AnearParticipantMachine`) and sends a *private* `RENDER_DISPLAY` event directly to that machine. This is the key to sending a message to only one person.
-*   **Code Reference (lines 142-156 and 229-256):**
-
-```javascript
-// ... inside DisplayEventProcessor.js _processSingle
-case 'eachParticipant':
-  // ...
-  // It determines we need to send to a specific participant
-  publishPromise = this._processSelectiveParticipantDisplay(
-    template,
-    templateRenderContext,
-    null,
-    participantId, // e.g., 'participant-123'
-    displayTimeout // e.g., 10000
-  );
-  // ...
-
-// ... inside _sendPrivateDisplay
-_sendPrivateDisplay(participantMachine, participantId, template, templateRenderContext, timeoutFn) {
-  // ... it compiles the pug template into HTML ...
-  const privateHtml = template(privateRenderContext);
-
-  const renderMessage = { content: privateHtml };
-  if (timeout !== null) {
-    renderMessage.timeout = timeout; // Attaches the 10000ms timeout
-  }
-
-  // CRITICAL: It sends an event to the specific participant's machine, NOT to Ably.
-  participantMachine.send('RENDER_DISPLAY', renderMessage);
-}
-```
----
-
-### Part 4: The Target & Delivery (`AnearParticipantMachine.js`)
-
-**Context:** Each participant in an event has their own instance of the `AnearParticipantMachine` (APM). This machine manages their connection, timeouts, and, most importantly, their private Ably channel.
-
-#### Lifecycle Step 5: Receiving the Private Display Command
-
-The target participant's APM receives the `RENDER_DISPLAY` event from the `DisplayEventProcessor`.
-
-*   **File:** `/Users/machvee/dev/anear-js-api/lib/state_machines/AnearParticipantMachine.js`
-*   **Description:** The APM transitions to its own `renderDisplay` state, where it invokes its `publishPrivateDisplay` service. The payload it received (`renderMessage`) contains the final HTML and the 10-second timeout.
-*   **Code Reference (lines 96-98 and 147-160):**
-
-```javascript
-// ... inside AnearParticipantMachine.js
-idle: {
-  on: {
-    RENDER_DISPLAY: {
-      target: '#renderDisplay'
-    },
-// ...
-renderDisplay: {
-  id: 'renderDisplay',
-  invoke: {
-    src: 'publishPrivateDisplay', // This is the final step
-    onDone: [
-      // After publishing, it starts waiting for the user's ACTION
-      { cond: 'hasActionTimeout', actions: 'updateActionTimeout', target: 'waitParticipantResponse' },
-      { target: 'idle', internal: true }
-    ],
-// ...
-```
-
-#### Lifecycle Step 6: Sending the Ably Message
-
-This is the final hop. The `publishPrivateDisplay` service does one thing: it publishes the HTML to the participant's private channel.
-
-*   **File:** `/Users/machvee/dev/anear-js-api/lib/state_machines/AnearParticipantMachine.js`
-*   **Description:** It uses the `RealtimeMessaging` utility to send the message over Ably. The participant's browser, which is subscribed to this unique channel, receives the message and updates the DOM.
-*   **Code Reference (lines 348-358):**
-
-```javascript
-// ... inside AnearParticipantMachine.js
-services: {
-  publishPrivateDisplay: async (context, event) => {
-    // event.content is the final HTML from the DisplayEventProcessor
-    const displayMessage = { content: event.content };
-
-    await RealtimeMessaging.publish(
-      context.privateChannel, // The participant's unique channel
-      'PRIVATE_DISPLAY',
-      displayMessage
-    );
-
-    // It returns the timeout so the onDone transition knows to start the timer
-    return { timeout: event.timeout };
-  },
-// ...
-```
+*   **Description:** For an `eachParticipant`

package/RENDER_USAGE_EXAMPLES.md

@@ -26,7 +26,11 @@ const Config = {
           meta: {
             eachParticipant: {
               view: 'PlayableGameBoard',
-              timeout: calcParticipantTimeout
+              timeout: calcParticipantTimeout,
+              props: {
+                title: "Your Move!",
+                highlightLastMove: true
+              }
             },
             spectators: 'ViewableGameBoard'
           }
@@ -135,7 +139,7 @@ const actions = {
   - `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
@@ -138,6 +145,10 @@ class AnearEvent extends JsonApiResource {
     return this.app.attributes["participant-timeout"]
   }
 
+  get appIconUrl() {
+    return this.app.attributes["icon-url"]
+  }
+
   hasFlag(flagName) {
     return this.attributes.flags.includes(flagName)
   }

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,