anear-js-api 1.5.2 → 1.6.2

package/lib/state_machines/AnearEventMachine.js

@@ -134,6 +134,7 @@ const getPresenceEventName = (participant, presenceAction) => {
 };
 
 const RealtimeMessaging = require('../utils/RealtimeMessaging')
+const EventStats = require('../utils/EventStats')
 const AppMachineTransition = require('../utils/AppMachineTransition')
 const DisplayEventProcessor = require('../utils/DisplayEventProcessor')
 const PugHelpers = require('../utils/PugHelpers')
@@ -144,6 +145,34 @@ const AnearParticipant = require('../models/AnearParticipant')
 
 const CurrentDateTimestamp = _ => new Date().getTime()
 
+// Event stats: AEM-only, for metering. Never passed to AppM. Shape matches persisted event_stats.
+// event channel: we publish and may receive → publishCount, bytesPublished, receivedCount, bytesReceived.
+// actions channel: we receive ACTIONS from clients → receivedCount, bytesReceived.
+// Other channels: we publish only → publishCount, bytesPublished.
+const CHANNEL_NAMES_PUBLISH_ONLY = ['participants', 'spectators', 'private']
+function createInitialEventStats() {
+  const channels = {}
+  CHANNEL_NAMES_PUBLISH_ONLY.forEach(name => {
+    channels[name] = { publishCount: 0, bytesPublished: 0 }
+  })
+  channels.event = { publishCount: 0, bytesPublished: 0, receivedCount: 0, bytesReceived: 0 }
+  channels.actions = { receivedCount: 0, bytesReceived: 0 }
+  return {
+    liveDurationMs: 0,
+    liveStartedAt: null,
+    channels
+  }
+}
+
+// Serializable snapshot for persistence (omit liveStartedAt).
+function serializeEventStats(eventStats) {
+  if (!eventStats || !eventStats.channels) return null
+  return {
+    liveDurationMs: eventStats.liveDurationMs ?? 0,
+    channels: { ...eventStats.channels }
+  }
+}
+
 const AnearEventMachineContext = (
   anearEvent,
   coreServiceMachine,
@@ -174,7 +203,8 @@ const AnearEventMachineContext = (
   pendingCancelConfirmations: null,  // Set of participantIds waiting for TIMER_CANCELED confirmation
   pendingCancelAction: null,  // ACTION to forward after cancellation completes: { participantId, appEventName, payload }
   consecutiveTimeoutCount: 0,  // Global counter tracking consecutive timeouts across all participants for dead-man switch
-  consecutiveAllParticipantsTimeoutCount: 0  // Counter tracking consecutive allParticipants timeouts where ALL participants timed out
+  consecutiveAllParticipantsTimeoutCount: 0,  // Counter tracking consecutive allParticipants timeouts where ALL participants timed out
+  eventStats: null  // Set on createAppEventMachine onDone (initial or rehydrated); createInitialEventStats() shape
 })
 
 const ActiveEventGlobalEvents = {
@@ -189,11 +219,12 @@ const ActiveEventGlobalEvents = {
   CLOSE: {
     // AppM has reached a final state or explicitly called closeEvent()
     // initiate orderly shutdown
+    actions: ['addLiveDurationSegment'],
     target: '#activeEvent.closeEvent'
   },
   CANCEL: {
     // appM does an abrupt shutdown of the event
-    actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} CANCEL received`),
+    actions: ['addLiveDurationSegment', ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} CANCEL received`)],
     target: '#canceled'
   },
   APPM_FINAL: {
@@ -341,7 +372,7 @@ const ActiveEventStatesConfig = {
           id: 'waitingAnnounce',
           after: {
             timeoutEventAnnounce: {
-              actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} TIMED OUT waiting for ANNOUNCE`),
+              actions: ['addLiveDurationSegment', ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} TIMED OUT waiting for ANNOUNCE`)],
               target: '#canceled'
             }
           },
@@ -350,12 +381,15 @@ const ActiveEventStatesConfig = {
               target: '#activeEvent.announce'
             },
             START: {
+              actions: ['startLiveDuration'],
               target: '#activeEvent.live'
             },
             PAUSE: {
+              actions: ['addLiveDurationSegment'],
               target: '#pausingEvent'
             },
             SAVE: {
+              actions: ['addLiveDurationSegment'],
               target: 'savingAppEventContext'
             }
           }
@@ -528,13 +562,13 @@ const ActiveEventStatesConfig = {
           entry: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} created → announce`),
           after: {
             timeoutEventStart: {
-              actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} TIMED OUT waiting for START`),
+              actions: ['addLiveDurationSegment', ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} TIMED OUT waiting for START`)],
               target: '#canceled'
             }
           },
           on: {
             START: {
-              actions: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} announce → live`),
+              actions: ['startLiveDuration', ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} announce → live`)],
               target: '#activeEvent.live'
             }
           }
@@ -902,25 +936,15 @@ const ActiveEventStatesConfig = {
     closeEvent: {
       id: 'closeEvent',
       entry: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} live → closed`),
-      initial: 'savingContextMaybe',
+      initial: 'savingAppEventContext',
       on: {
         APPM_FINAL: {
           actions: () => logger.debug('[AEM] Ignoring APPM_FINAL during closeEvent.')
         }
       },
       states: {
-        savingContextMaybe: {
-          always: [
-            {
-              guard: ({ event }) => {
-                const c = event?.appmContext?.context
-                return !!(c && typeof c === 'object')
-              },
-              target: 'savingAppEventContext'
-            },
-            { target: 'notifyingParticipants' }
-          ]
-        },
+        // Always persist event_stats on close (with full or empty app context).
+        // saveAppEventContext includes event_stats; appmContext may be {} or { context, resumeEvent }.
         savingAppEventContext: {
           invoke: {
             src: 'saveAppEventContext',
@@ -1428,6 +1452,26 @@ const AnearEventMachineFunctions = ({
       },
       appMachineTransition: ({ event }) => {
         return event?.output?.appMachineTransition ?? event?.data?.appMachineTransition ?? null
+      },
+      eventStats: ({ event, context }) => {
+        const fromOutput = event?.output?.eventStats ?? event?.data?.eventStats
+        return fromOutput ?? context.eventStats ?? createInitialEventStats()
+      }
+    }),
+    startLiveDuration: assign({
+      eventStats: ({ context }) => {
+        const s = context.eventStats
+        if (!s || !s.channels) return s
+        return { ...s, liveStartedAt: Date.now() }
+      }
+    }),
+    addLiveDurationSegment: assign({
+      eventStats: ({ context }) => {
+        const s = context.eventStats
+        if (!s || !s.channels) return s
+        const now = Date.now()
+        const add = (s.liveStartedAt != null) ? (now - s.liveStartedAt) : 0
+        return { ...s, liveDurationMs: (s.liveDurationMs || 0) + add, liveStartedAt: null }
       }
     }),
     notifyAppMachineRendered: ({ context }) => {
@@ -1486,13 +1530,21 @@ const AnearEventMachineFunctions = ({
       )
     },
     subscribeToActionMessages: ({ context, self }) => {
-      RealtimeMessaging.subscribe(
-        context.actionsChannel,
-        self,
-        'ACTION'
-      )
+      RealtimeMessaging.subscribe(context.actionsChannel, self, 'ACTION', {
+        onMessage: (message, actor) => {
+          const ctx = actor.getSnapshot().context
+          EventStats.recordReceived(ctx.eventStats, ctx.actionsChannel, message.data)
+        }
+      })
+    },
+    subscribeToEventMessages: ({ context, self }) => {
+      RealtimeMessaging.subscribe(context.eventChannel, self, null, {
+        onMessage: (message, actor) => {
+          const ctx = actor.getSnapshot().context
+          EventStats.recordReceived(ctx.eventStats, ctx.eventChannel, message.data)
+        }
+      })
     },
-    subscribeToEventMessages: ({ context, self }) => RealtimeMessaging.subscribe(context.eventChannel, self),
     createParticipantsDisplayChannel: assign({
       participantsDisplayChannel: ({ context, self }) => RealtimeMessaging.getChannel(
         context.anearEvent.participantsChannelName,
@@ -2281,14 +2333,17 @@ const AnearEventMachineFunctions = ({
   actors: {
     saveAppEventContext: fromPromise(async ({ input }) => {
       const { context, event } = input
-      // Events like PAUSE/SAVE are sent as send('PAUSE', { appmContext: {...} })
-      // event.appmContext -> { context, resumeEvent }
+      // PAUSE/SAVE/CLOSE may include appmContext: { context, resumeEvent }
+      // Always include event_stats when present (AEM flushes metering on every save)
       const appmContext = event?.appmContext || {}
       const payload = {
         eventId: context.anearEvent.id,
         savedAt: new Date().toISOString(),
         ...appmContext
       }
+      if (context.eventStats) {
+        payload.event_stats = serializeEventStats(context.eventStats)
+      }
       await AnearApi.saveAppEventContext(context.anearEvent.id, payload)
       return 'done'
     }),
@@ -2306,6 +2361,7 @@ const AnearEventMachineFunctions = ({
       let machineToStart = baseMachine
       let actorInput = undefined
       let resumeEvent = null
+      let eventStats = createInitialEventStats()
 
       if (context.rehydrate) {
         try {
@@ -2318,6 +2374,35 @@ const AnearEventMachineFunctions = ({
               // (AppM machine config should define `context: ({ input }) => ...`).
               actorInput = savedContext
             }
+            // AEM-only: restore event_stats for metering; never pass to AppM
+            if (appmContext.event_stats && typeof appmContext.event_stats === 'object') {
+              const raw = appmContext.event_stats
+              eventStats = {
+                liveDurationMs: typeof raw.liveDurationMs === 'number' ? raw.liveDurationMs : 0,
+                liveStartedAt: null,
+                channels: { ...createInitialEventStats().channels }
+              }
+              if (raw.channels && typeof raw.channels === 'object') {
+                Object.keys(raw.channels).forEach(key => {
+                  const c = raw.channels[key]
+                  if (!c) return
+                  if (key === 'actions' && typeof c.receivedCount === 'number' && typeof c.bytesReceived === 'number') {
+                    eventStats.channels[key] = { receivedCount: c.receivedCount, bytesReceived: c.bytesReceived }
+                  } else if (key === 'event') {
+                    const pub = typeof c.publishCount === 'number' && typeof c.bytesPublished === 'number'
+                    const rec = typeof c.receivedCount === 'number' && typeof c.bytesReceived === 'number'
+                    eventStats.channels[key] = {
+                      publishCount: pub ? c.publishCount : 0,
+                      bytesPublished: pub ? c.bytesPublished : 0,
+                      receivedCount: rec ? c.receivedCount : 0,
+                      bytesReceived: rec ? c.bytesReceived : 0
+                    }
+                  } else if (typeof c.publishCount === 'number' && typeof c.bytesPublished === 'number') {
+                    eventStats.channels[key] = { publishCount: c.publishCount, bytesPublished: c.bytesPublished }
+                  }
+                })
+              }
+            }
           }
         } catch (e) {
           // Log and proceed without rehydration
@@ -2464,7 +2549,7 @@ const AnearEventMachineFunctions = ({
         appActor.send(resumeEvent)
       }
 
-      return { service: appActor, appMachineTransition }
+      return { service: appActor, appMachineTransition, eventStats }
     }),
     renderDisplay: fromPromise(async ({ input }) => {
       const { context, event } = input
@@ -2541,6 +2626,7 @@ const AnearEventMachineFunctions = ({
       // without terminating the event or detaching channels.
       await AnearApi.transitionEvent(context.anearEvent.id, 'restart')
 
+      EventStats.recordPublish(context.eventStats, context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'announce' } })
       const publishPromise = RealtimeMessaging.publish(
         context.eventChannel,
         'EVENT_TRANSITION',
@@ -2563,6 +2649,7 @@ const AnearEventMachineFunctions = ({
       // Transition the event to 'live' via ANAPI and publish an EVENT_TRANSITION
       // message so ABRs can react immediately (e.g., auto-close expanded QR).
       const transitionPromise = AnearApi.transitionEvent(context.anearEvent.id, 'live')
+      EventStats.recordPublish(context.eventStats, context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'live' } })
       const publishPromise = RealtimeMessaging.publish(
         context.eventChannel,
         'EVENT_TRANSITION',
@@ -2579,16 +2666,23 @@ const AnearEventMachineFunctions = ({
       // and the publishing of the 'EVENT_TRANSITION' message to ABRs.
       // It's a promise that resolves when both operations are complete.
       const transitionPromise = AnearApi.transitionEvent(context.anearEvent.id, 'closed')
+      EventStats.recordPublish(context.eventStats, context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'closed' } })
       const publishPromise = RealtimeMessaging.publish(context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'closed' } })
       await Promise.all([transitionPromise, publishPromise])
       return 'done' // Indicate completion
     }),
     eventTransitionCanceled: fromPromise(async ({ input }) => {
       const { context } = input
-      // This service handles the transition of the event to 'canceled' via AnearApi
-      // and the publishing of the 'EVENT_TRANSITION' message to ABRs.
-      // It's a promise that resolves when both operations are complete.
+      // Persist event_stats once on cancel (no app context to save).
+      const statsPayload = context.eventStats
+        ? { eventId: context.anearEvent.id, savedAt: new Date().toISOString(), event_stats: serializeEventStats(context.eventStats) }
+        : null
+      if (statsPayload) {
+        await AnearApi.saveAppEventContext(context.anearEvent.id, statsPayload)
+      }
+      // Transition the event to 'canceled' via AnearApi and publish EVENT_TRANSITION to ABRs.
       const transitionPromise = AnearApi.transitionEvent(context.anearEvent.id, 'canceled')
+      EventStats.recordPublish(context.eventStats, context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'canceled' } })
       const publishPromise = RealtimeMessaging.publish(context.eventChannel, 'EVENT_TRANSITION', { content: { state: 'canceled' } })
       await Promise.all([transitionPromise, publishPromise])
       return 'done' // Indicate completion

package/lib/state_machines/AnearParticipantMachine.js

@@ -99,10 +99,11 @@ const { assign, createMachine, createActor, fromPromise } = require('xstate')
 const C = require('../utils/Constants')
 
 const RealtimeMessaging = require('../utils/RealtimeMessaging')
+const EventStats = require('../utils/EventStats')
 
 const CurrentDateTimestamp = _ => new Date().getTime()
 
-const AnearParticipantMachineContext = (anearParticipant, anearEvent, appParticipantMachineFactory) => ({
+const AnearParticipantMachineContext = (anearParticipant, anearEvent, appParticipantMachineFactory, eventStats = null) => ({
   anearEvent,
   anearParticipant,
   privateChannel: null,
@@ -117,7 +118,8 @@ const AnearParticipantMachineContext = (anearParticipant, anearEvent, appPartici
   // would be dropped (no handler in that state). We keep the latest and flush it
   // immediately after the current publish completes.
   queuedRenderDisplay: null,
-  lastSeen: CurrentDateTimestamp()
+  lastSeen: CurrentDateTimestamp(),
+  eventStats // AEM-only metering; optional for EventStats.recordPublish before publish
 })
 
 const AnearParticipantMachineConfig = participantId => ({
@@ -653,6 +655,7 @@ const AnearParticipantMachineFunctions = {
     publishPrivateDisplay: fromPromise(async ({ input }) => {
       const { context, event } = input
       const displayMessage = { content: event.content }
+      EventStats.recordPublish(context.eventStats, context.privateChannel, 'PRIVATE_DISPLAY', displayMessage)
       await RealtimeMessaging.publish(context.privateChannel, 'PRIVATE_DISPLAY', displayMessage)
       return { timeout: event.timeout }
     }),
@@ -664,6 +667,7 @@ const AnearParticipantMachineFunctions = {
           reason: reason || 'You have been removed from the event.'
         }
       }
+      EventStats.recordPublish(context.eventStats, context.privateChannel, 'FORCE_SHUTDOWN', payload)
       await RealtimeMessaging.publish(context.privateChannel, 'FORCE_SHUTDOWN', payload)
       return 'done'
     }),
@@ -714,7 +718,7 @@ const AnearParticipantMachineFunctions = {
 //   4. handles activity state, response timeouts, idle state
 //   5. receives ACTION events relayed by the AnearEventMachine
 //   6. relays all relevant events to the participant XState Machine for Application-specific handling
-const AnearParticipantMachine = (anearParticipant, { anearEvent, appParticipantMachineFactory }) => {
+const AnearParticipantMachine = (anearParticipant, { anearEvent, appParticipantMachineFactory, eventStats }) => {
   const anearParticipantMachine = createMachine(
     {
       ...AnearParticipantMachineConfig(anearParticipant.id),
@@ -727,7 +731,8 @@ const AnearParticipantMachine = (anearParticipant, { anearEvent, appParticipantM
   const anearParticipantMachineContext = AnearParticipantMachineContext(
     anearParticipant,
     anearEvent,
-    appParticipantMachineFactory
+    appParticipantMachineFactory,
+    eventStats
   )
 
   const actor = createActor(anearParticipantMachine, { input: anearParticipantMachineContext })

package/lib/utils/AppMachineTransition.js

@@ -122,7 +122,12 @@ const AppMachineTransition = (anearEvent) => {
 
     if (event.type === 'RENDERED') {
       // Re-examine meta on RENDERED; send RENDER_DISPLAY only when state/context actually changed.
-      if (baseSignature === lastBaseSignature) {
+      // Exception: eachParticipant states re-send once on RENDERED so participants who had a
+      // display queued (e.g. joined while another was publishing) still get the view. No opt-in.
+      const hasEachParticipant = (rawMeta && typeof rawMeta === 'object' && rawMeta.eachParticipant != null) ||
+        metaObjects.some(m => m && typeof m === 'object' && m.eachParticipant != null)
+      const sameSignature = baseSignature === lastBaseSignature
+      if (sameSignature && !hasEachParticipant) {
         logger.debug(`[AppMachineTransition] RENDERED re-examination: no change, skipping RENDER_DISPLAY stateName='${stateName}'`)
         return
       }

package/lib/utils/DisplayEventProcessor.js

@@ -40,6 +40,7 @@
 
 const logger = require('./Logger')
 const RealtimeMessaging = require('./RealtimeMessaging')
+const EventStats = require('./EventStats')
 const C = require('./Constants')
 
 class DisplayEventProcessor {
@@ -54,6 +55,7 @@ class DisplayEventProcessor {
     this.spectatorsDisplayChannel = anearEventMachineContext.spectatorsDisplayChannel
     this.participants = anearEventMachineContext.participants
     this.participantsIndex = this._buildParticipantsIndex(anearEventMachineContext.participants)
+    this.eventStats = anearEventMachineContext.eventStats ?? null
   }
 
   processAndPublish(displayEvents, cancelActionType = null) {
@@ -168,6 +170,7 @@ class DisplayEventProcessor {
           logger.debug(`[DisplayEventProcessor] no allParticipants timeout resolved`)
         }
 
+        EventStats.recordPublish(this.eventStats, this.participantsDisplayChannel, 'PARTICIPANTS_DISPLAY', formattedDisplayMessage())
         publishPromise = RealtimeMessaging.publish(
           this.participantsDisplayChannel,
           'PARTICIPANTS_DISPLAY',
@@ -211,11 +214,12 @@ class DisplayEventProcessor {
           logger.debug(`[DisplayEventProcessor] spectators visual timeout set to msecs=${specTimeout.msecs}, remaining=${specTimeout.remainingMsecs}`)
         }
 
+        EventStats.recordPublish(this.eventStats, this.spectatorsDisplayChannel, 'SPECTATORS_DISPLAY', formattedDisplayMessage())
         publishPromise = RealtimeMessaging.publish(
           this.spectatorsDisplayChannel,
-                  'SPECTATORS_DISPLAY',
-        formattedDisplayMessage()
-      )
+          'SPECTATORS_DISPLAY',
+          formattedDisplayMessage()
+        )
         break
 
       case 'eachParticipant':

package/lib/utils/EventStats.js

@@ -0,0 +1,119 @@
+"use strict"
+
+/**
+ * Event stats metering for realtime publishes. Invoke recordPublish before each
+ * RealtimeMessaging.publish so the event's stats (per-channel publish count and
+ * bytes) are updated. RealtimeMessaging does not know about event stats.
+ */
+
+/**
+ * Extracts a short channel name from the full channel name (same mapping as RTM).
+ * @param {string} channelName - Full channel name (e.g. "anear:appId:e:eventId:actions")
+ * @returns {string} - Short key (e.g. "actions", "private", "participants", "spectators", "event")
+ */
+function getChannelShortName(channelName) {
+  if (!channelName) return 'unknown'
+
+  const parts = channelName.split(':')
+
+  if (parts.length >= 4 && parts[2] === 'e') {
+    if (parts.length === 5) return parts[4]
+    if (parts.length === 6 && parts[4] === 'private') return 'private'
+  }
+
+  if (parts.length === 3 && parts[2] === 'e') return 'events'
+
+  return parts[parts.length - 1] || channelName
+}
+
+const ACTIONS_CHANNEL_KEY = 'actions'
+const EVENT_CHANNEL_KEY = 'event'
+
+/**
+ * Default shape for a channel that receives messages (e.g. actions channel).
+ * Server receives ACTIONS from clients on the actions channel; we track receivedCount/bytesReceived.
+ */
+function defaultReceivedChannelShape() {
+  return { receivedCount: 0, bytesReceived: 0 }
+}
+
+/**
+ * Default shape for a channel we publish to (participants, spectators, private).
+ */
+function defaultPublishChannelShape() {
+  return { publishCount: 0, bytesPublished: 0 }
+}
+
+/**
+ * Default shape for a channel that both publishes and receives (e.g. event channel).
+ */
+function defaultDualChannelShape() {
+  return { publishCount: 0, bytesPublished: 0, receivedCount: 0, bytesReceived: 0 }
+}
+
+/**
+ * Record one publish for event stats. Call before RealtimeMessaging.publish.
+ * No-op if eventStats is null/undefined or missing channels.
+ * Not used for the actions channel (server does not publish to actions).
+ *
+ * @param {{ channels: Record<string, { publishCount: number, bytesPublished: number } | { receivedCount: number, bytesReceived: number }> } | null | undefined} eventStats - AEM context.eventStats
+ * @param {{ name: string } | string} channel - Ably channel (with .name) or channel name string
+ * @param {string} msgType - Message type (for consistency; bytes are from message payload)
+ * @param {object} message - The message object being published (stringified for byte count)
+ */
+function recordPublish(eventStats, channel, msgType, message) {
+  if (!eventStats || !eventStats.channels || typeof eventStats.channels !== 'object') return
+
+  const channelName = typeof channel === 'string' ? channel : (channel && channel.name)
+  const shortName = getChannelShortName(channelName)
+
+  if (!eventStats.channels[shortName]) {
+    eventStats.channels[shortName] = shortName === EVENT_CHANNEL_KEY ? defaultDualChannelShape() : defaultPublishChannelShape()
+  }
+  const ch = eventStats.channels[shortName]
+  if ('publishCount' in ch && 'bytesPublished' in ch) {
+    ch.publishCount += 1
+    const payload = typeof message === 'string' ? message : JSON.stringify(message)
+    const bytes = typeof Buffer !== 'undefined' ? Buffer.byteLength(payload, 'utf8') : new TextEncoder().encode(payload).length
+    ch.bytesPublished += bytes
+  }
+}
+
+/**
+ * Record one received message on a channel. Used for actions channel (ACTION from clients) and
+ * event channel (any message received on the event channel). No-op if eventStats is null/undefined.
+ *
+ * @param {{ channels: Record<string, object> } | null | undefined} eventStats - AEM context.eventStats
+ * @param {{ name: string } | string} channel - Ably channel (or channel short name)
+ * @param {object} message - The received message payload (e.g. event.data or message.data)
+ */
+function recordReceived(eventStats, channel, message) {
+  if (!eventStats || !eventStats.channels || typeof eventStats.channels !== 'object') return
+
+  const channelName = typeof channel === 'string' ? channel : (channel && channel.name)
+  const shortName = getChannelShortName(channelName)
+  // Only actions and event channels track receives (event can have both publish and receive).
+  if (shortName !== ACTIONS_CHANNEL_KEY && shortName !== EVENT_CHANNEL_KEY) return
+
+  if (!eventStats.channels[shortName]) {
+    eventStats.channels[shortName] = shortName === EVENT_CHANNEL_KEY ? defaultDualChannelShape() : defaultReceivedChannelShape()
+  }
+  const ch = eventStats.channels[shortName]
+  if (!('receivedCount' in ch)) ch.receivedCount = 0
+  if (!('bytesReceived' in ch)) ch.bytesReceived = 0
+  ch.receivedCount += 1
+  const payload = typeof message === 'string' ? message : JSON.stringify(message)
+  const bytes = typeof Buffer !== 'undefined' ? Buffer.byteLength(payload, 'utf8') : new TextEncoder().encode(payload).length
+  ch.bytesReceived += bytes
+}
+
+module.exports = {
+  ACTIONS_CHANNEL_KEY,
+  EVENT_CHANNEL_KEY,
+  getChannelShortName,
+  recordPublish,
+  recordReceived,
+  defaultReceivedChannelShape,
+  defaultPublishChannelShape,
+  defaultDualChannelShape
+}

package/lib/utils/RealtimeMessaging.js

@@ -255,17 +255,26 @@ class RealtimeMessaging {
     await Promise.all(detachPromises)
   }
 
-  subscribe(channel, actor, eventName = null) {
+  /**
+   * @param {Channel} channel
+   * @param {Actor} actor
+   * @param {string | null} eventName - If set, only subscribe to this message name
+   * @param {{ onMessage?: (message: object, actor: Actor) => void }} [options] - Optional; onMessage(message, actor) is called before forwarding to actor (e.g. for receive stats)
+   */
+  subscribe(channel, actor, eventName = null, options = null) {
     // Note: subscribing to an Ably channel will implicitly attach()
     const key = `${actor.id}::${channel.name}::subscribe::${eventName || '*'}`
     if (this._messageListenerKeys.has(key)) return
     this._messageListenerKeys.add(key)
 
+    const onMessage = options?.onMessage
+
     const args = []
 
     if (eventName) args.push(eventName)
     args.push(
       message => {
+        if (typeof onMessage === 'function') onMessage(message, actor)
         const participantId = message.data?.participantId || null
         const participantIdStr = participantId ? ` participantId=${participantId}` : ''
         const channelShortName = getChannelShortName(channel.name)

package/package.json

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