anear-js-api 1.4.0 → 1.4.2

package/README.md

@@ -0,0 +1,382 @@
+# Anear JavaScript API (JSAPI)
+
+The Anear JavaScript API is a runtime SDK that enables app developers to create real-time interactive events without needing to understand the underlying complexity of Ably.io interactions, event lifecycle management, and participant/spectator coordination.
+
+## Overview
+
+The `anear-js-api` is the server-side Node.js runtime for Anear applications. It manages real-time communication via Ably.io, coordinates participant presence, handles event lifecycle, and renders dynamic UI templates. App developers write XState state machines that define their application logic, and the JSAPI handles all the infrastructure concerns.
+
+### Key Philosophy
+
+The Anear platform is designed for **hyperlocal, face-to-face interaction**. Anear Apps are experiences designed for in-person participants who share the same physical space. The core principle is to leverage technology to enhance, not replace, real-world social dynamics. Participants are typically in the same room, fostering an environment of direct, face-to-face interaction.
+
+### System Purpose
+
+The anear-js-api abstracts away:
+- Ably.io channel management and messaging
+- Event lifecycle state transitions (`created` → `announce` → `live` → `closed`)
+- Participant presence tracking and coordination
+- Display rendering and template compilation
+- Asset management (CSS, images) and CDN uploads
+- Timeout management for participant actions
+- Reconnection handling and error recovery
+
+## Architecture
+
+### State Machine Hierarchy
+
+```
+AnearCoreServiceMachine (Root)
+├── AnearEventMachine (Per Event)
+│   ├── AnearParticipantMachine (Per Participant)
+│   └── AppEventMachine (Developer's App Logic)
+└── AppParticipantMachine (Optional, Per Participant)
+```
+
+### Core Components
+
+#### AnearCoreServiceMachine
+- **Purpose**: Highest-level parent state machine managing realtime messaging and event lifecycle
+- **Responsibilities**:
+  - Initialize Ably.io realtime messaging
+  - Manage multiple concurrent events via `anearEventMachines` object
+  - Handle app data fetching and asset uploads (CSS, images)
+  - Load and compile PUG templates
+  - Listen for `CREATE_EVENT` messages from backend via Ably REST API
+- **Key States**: `waitForContextUpdate` → `fetchAppDataWithRetry` → `initRealtimeMessaging` → `waitAnearEventLifecycleCommand`
+
+#### AnearEventMachine (AEM)
+- **Purpose**: Manages individual event lifecycle and participant coordination
+- **Responsibilities**:
+  - Handle event lifecycle states: `created` → `announce` → `live` → `closed`
+  - Route messages between participants and app logic
+  - Manage participant presence (enter/leave/exit)
+  - Coordinate display rendering for all channels
+  - Handle individual participant timeouts
+- **Key States**: `registerCreator` → `eventCreated` → `announce` → `live` → `closeEvent`
+
+#### AnearParticipantMachine (APM)
+- **Purpose**: Manages individual participant state and private communications
+- **Responsibilities**:
+  - Handle participant private channel communications
+  - Manage participant timeouts and reconnection logic
+  - Track participant activity and idle states
+  - Route participant-specific actions to app logic
+- **Key States**: `setup` → `live` → `waitReconnect` → `cleanupAndExit`
+
+### Separation of Concerns: JSAPI vs. AppM
+
+A key architectural principle is the clear separation of concerns between the Anear JSAPI (the "engine") and the App Event Machine (the "application").
+
+#### JSAPI (AEM & APM): The Engine Room
+
+The JSAPI is responsible for all the underlying infrastructure and communication mechanics. Its concerns are purely technical:
+
+- **Event Lifecycle & State:** Manages the low-level state transitions of an event (`created` → `announce` → `live` → `closed`) and the lifecycle of participants.
+- **Real-time Communication:** Handles all Ably channel setup, messaging, presence events, and connection state.
+- **Orderly Operations:** Ensures smooth, reliable startup and shutdown of all services and participant connections.
+- **Notifier:** The JSAPI acts as a notifier. It informs the AppM of important events (`PARTICIPANT_ENTER`, `PARTICIPANT_DISCONNECT`, `ACTION`, `PARTICIPANT_TIMEOUT`) but does not decide what these events mean for the application.
+
+#### AppM: The Application & User Experience
+
+The AppM developer is responsible for everything related to the specific event's logic and what the user sees:
+
+- **Game/Event Logic:** Controls the flow, rules, and state of the interactive event.
+- **User Experience (UX/UI):** Defines what the user sees at every stage via `meta` display properties in its state nodes. All display content is the AppM's responsibility.
+- **Decision Maker:** The AppM is the decision-maker. When the JSAPI notifies it of an event (e.g., "a participant timed out"), the AppM decides what to do. Should the game end? Should the participant be removed? Should the state change? That is application-level logic.
+
+This strict separation allows AppM developers to focus entirely on their application logic without needing to manage the complexities of real-time infrastructure.
+
+## Getting Started
+
+### Installation
+
+```bash
+npm install anear-js-api
+```
+
+### Basic Setup
+
+```javascript
+// index.js
+const { AnearService } = require('anear-js-api')
+const MachineFactory = require('./StateMachine')
+
+// Starts and instantiates the service
+AnearService(MachineFactory)
+```
+
+### Required Environment Variables
+
+```bash
+ANEARAPP_API_KEY=your_api_key
+ANEARAPP_API_SECRET=your_api_secret
+ANEARAPP_API_VERSION=v1
+ANEARAPP_API_URL=http://api.lvh.me:3001/developer  # Optional, for local development
+```
+
+### Developer API Authentication
+
+`anear-js-api` communicates with the **ANAPI Developer API** (`/developer/v1/*` endpoints) using JWT authentication:
+
+1. **Challenge (credentials → JWT)**: On startup, exchanges developer credentials (`api_key`, `secret`) for a short-lived JWT via `POST /developer/v1/sessions`
+2. **Authenticated requests**: All subsequent requests use `Authorization: Bearer <auth_token>`
+3. **Expiry**: JWT expiry is enforced by ANAPI (configured via `developer_api_token_expiration_interval_hours`)
+
+## Event Lifecycle
+
+Anear events follow a specific lifecycle managed by the Anear Event Machine (AEM):
+
+1. **Created**: Event is created in the AEM but not yet visible. No participants can join yet.
+2. **Announced**: Developer calls `anearEvent.announceEvent()`. Event becomes visible to potential participants. **Critical**: This step is required for participants to join!
+3. **Live**: Developer calls `anearEvent.startEvent()`. Event is actively running.
+4. **Complete/Cancelled**: Developer calls `anearEvent.closeEvent()` or `anearEvent.cancelEvent()`. **Critical**: You MUST explicitly call one of these methods before your AppM reaches a `final` state.
+
+Your AppM state names are completely independent of these AEM states. You can start your AppM in any state you want - the AEM lifecycle runs in parallel.
+
+## Channel Architecture
+
+### Ably.io Channels
+
+- **`eventChannel`**: Event control messages
+- **`actionsChannel`**: Participant presence events + ACTION clicks
+- **`participantsDisplayChannel`**: Group display messages for all participants
+- **`spectatorsDisplayChannel`**: Display messages for all spectators
+- **`privateChannel`**: Individual participant private displays (per participant)
+
+### Message Flow
+
+1. **Presence Events**: Ably presence API → `actionsChannel` → XState events
+2. **Action Events**: Participant clicks → `actionsChannel` → App logic
+3. **Display Events**: App state transitions → `AppMachineTransition` → Channel rendering
+
+## Participant Presence Events
+
+The JSAPI handles participant lifecycle through presence events:
+
+| Event | When It Fires | AppM Receives |
+|-------|---------------|---------------|
+| `PARTICIPANT_ENTER` | New participant joins | `HOST_ENTER` or `PARTICIPANT_ENTER` (role-specific) |
+| `PARTICIPANT_RECONNECT` | Participant rejoins after disconnect | `HOST_RECONNECT` or `PARTICIPANT_RECONNECT` |
+| `PARTICIPANT_EXIT` | Participant permanently leaves | `HOST_EXIT` or `PARTICIPANT_EXIT` |
+| `PARTICIPANT_DISCONNECT` | Temporary connection loss | `HOST_DISCONNECT` or `PARTICIPANT_DISCONNECT` |
+| `PARTICIPANT_TIMEOUT` | Participant fails to respond in time | `PARTICIPANT_TIMEOUT` |
+| `ACTION` | Participant performs an action | Custom event (e.g., `MOVE`, `ANSWER`) |
+
+**Key Point**: The AEM uses role-specific events (`HOST_*` vs `PARTICIPANT_*`) based on whether the user is the event creator/host. Your AppM never needs to check `isHost` - it just reacts to the specific events it receives.
+
+## Display Rendering
+
+### Meta Properties
+
+App developers control what participants see using XState `meta` properties:
+
+```javascript
+meta: {
+  // Legacy formats (still supported)
+  eachParticipant: 'TemplateName',           // String template name
+  allParticipants: 'TemplateName',           // String template name
+  spectators: 'TemplateName',                 // String template name
+  
+  // Object format with timeout
+  eachParticipant: { 
+    view: 'TemplateName', 
+    timeout: (appContext, participantId) => 30000,
+    props: { message: 'Your turn!' }
+  },
+  
+  // Selective participant rendering (function)
+  eachParticipant: (appContext, event) => {
+    const participantId = event.participantId
+    if (participantId) {
+      return [{ participantId, view: 'ThanksScreen', timeout: null }]
+    }
+    return []
+  },
+  
+  // Host-specific display
+  host: { view: 'HostScreen', props: { questionCount: 10 } }
+}
+```
+
+### Template Context
+
+PUG templates receive rich context including:
+- `app`: Application XState context
+- `participants`: All participants map
+- `participant`: Individual participant data
+- `meta`: Display metadata (state, event, timeout, viewer)
+- `props`: Custom data from the `meta` block
+- PUG helpers: `cdnImg()`, `action()` for interactive elements
+
+## Timeout Management
+
+### Individual Timeouts
+
+For turn-based actions where each participant has their own timer:
+
+```javascript
+meta: {
+  eachParticipant: {
+    view: 'PlayableGameBoard',
+    timeout: (context, participant) => {
+      // Only current player gets timeout
+      return context.currentPlayerId === participant.info.id ? 30000 : null
+    }
+  }
+},
+on: {
+  MOVE: 'nextTurn',
+  PARTICIPANT_TIMEOUT: 'handleTimeout'
+}
+```
+
+### Group Timeouts
+
+For coordinated actions where all participants must respond:
+
+```javascript
+meta: {
+  allParticipants: { view: 'QuestionScreen', timeout: 20000 }
+},
+on: {
+  ANSWER: [
+    {
+      guard: ({ event }) => event.finalAction === true,
+      actions: ['handleAllResponded']
+    },
+    {
+      actions: ['handleIndividualResponse']
+    }
+  ],
+  ACTIONS_TIMEOUT: {
+    actions: ['handleTimeout']
+  }
+}
+```
+
+## Asset Management
+
+The JSAPI automatically handles asset management:
+
+1. **CSS Upload**: All CSS files in `assets/css/` are uploaded to CloudFront
+2. **Image Upload**: All images in `assets/images/` are uploaded to CloudFront
+3. **Template Preloading**: All PUG templates are preloaded and cached
+
+### Asset Structure
+
+```
+assets/
+├── css/
+│   └── app.css
+├── fonts/
+│   └── YourCustomFont.ttf
+└── images/
+    ├── Background.png
+    └── ...
+```
+
+## The anearEvent Object
+
+The `anearEvent` object is passed to your `MachineFactory` and provides access to Anear's core functionality:
+
+```javascript
+// Event lifecycle management
+await anearEvent.announceEvent()  // Transition to announced
+await anearEvent.startEvent()     // Transition to live
+await anearEvent.closeEvent()     // Transition to complete
+await anearEvent.cancelEvent()    // Transition to cancelled
+
+// Participant timeout management
+anearEvent.cancelAllParticipantTimeouts()  // Cancel all active timeouts
+```
+
+## XState Integration
+
+### State Machine Factory Pattern
+
+```javascript
+const MachineFactory = anearEvent => {
+  const expandedConfig = {
+    predictableActionArguments: true,
+    ...Config
+  }
+  const machine = createMachine(
+    expandedConfig,
+    Functions(anearEvent)
+  )
+  return machine.withContext(Context)
+}
+```
+
+### Context Structure
+
+```javascript
+const Context = {
+  C: Object.freeze(Constants), // Available in templates
+  // Game-specific state
+  playerIds: {},
+  gameState: 'WAITING',
+  // ... other state
+}
+```
+
+## Event Termination
+
+**Critical**: You must explicitly call `closeEvent()` or `cancelEvent()` before your AppM reaches a `final` state:
+
+```javascript
+gameOver: {
+  entry: ['saveGameStats', 'closeEvent'],
+  type: 'final'
+}
+
+gameAborted: {
+  entry: ['logAbortReason', 'cancelEvent'],
+  type: 'final'
+}
+```
+
+If your AppM reaches a `final` state without calling a termination method, the AEM will log an error and forcibly cancel the event.
+
+## RENDERED Event Synchronization
+
+The `RENDERED` event is helpful for synchronizing display rendering with state transitions. It ensures that displays are fully processed before the AppM proceeds to the next state.
+
+**Use RENDERED for:**
+- Display-only states with no user interaction
+- Start/end states in event flows
+- States where participants need time to see important displays
+
+**Skip RENDERED for:**
+- Interactive states that will transition naturally
+- States waiting on user actions or timeouts
+
+## Key Benefits
+
+1. **Abstraction**: Hides Ably.io complexity from app developers
+2. **Declarative**: XState meta properties define display behavior
+3. **Flexible**: Rich context system enables dynamic content
+4. **Scalable**: Handles multiple concurrent events efficiently
+5. **Reliable**: Built-in reconnection and timeout management
+6. **Consistent**: XState-based architecture throughout
+
+## Documentation
+
+For detailed information, see:
+
+- **[ANEAR_GLOBAL_ARCHITECTURE.md](./ANEAR_GLOBAL_ARCHITECTURE.md)**: Complete system architecture and API reference
+- **[ANEAR_DEVELOPER_GUIDE.md](../anear-hsm-test/ANEAR_DEVELOPER_GUIDE.md)**: Practical development guide with examples (in `anear-hsm-test` project)
+- **[RENDER_USAGE_EXAMPLES.md](./RENDER_USAGE_EXAMPLES.md)**: Examples of display rendering patterns
+
+## Example Projects
+
+- **anear-hsm-test**: Tic-Tac-Toe game demonstrating standard patterns
+- **sparkpoll**: Q&A app with selective participant rendering
+- **neonbluff**: Dice game with complex timeout management
+- **perimeter-chat**: Chat room demonstrating open-house events
+- **event-chat**: Embeddable chat widget for child apps
+
+## License
+
+GPL-3.0-or-later

package/lib/state_machines/AnearEventMachine.js

@@ -2305,7 +2305,7 @@ const AnearEventMachineFunctions = ({
                               context.anearEvent.attributes.initial_context
         if (initialContext && typeof initialContext === 'object' && !Array.isArray(initialContext)) {
           actorInput = initialContext
-          logger.debug(`[AEM] Using initial_context (partial) from event for ${context.anearEvent.id}`, initialContext)
+          logger.debug(`[AEM] Using initial_context from event ${context.anearEvent.id}:`, JSON.stringify(initialContext))
         }
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anear-js-api",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Javascript Developer API for Anear Apps",
   "main": "lib/index.js",
   "scripts": {