where_is_waldo 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33656f9699b2331d830131c39118af0a671b32f3f7f173faec64bde7a522b27b
-  data.tar.gz: 374c04bea26515d249cf4720694699e73ae43f5e9b63601a11d871f16eabe01c
+  metadata.gz: 14d08eaaa5203c578066b674469638145e6bd1a095260ba5874a78e7299b2ab3
+  data.tar.gz: 7a96f733e8dd421884e0bd798f38b5f5de128faaf1eff0fc7126c2f29b556dd0
 SHA512:
-  metadata.gz: d16fdffe075e626fef57fceb95c20b39833c67db2c799ad9099d3873093054152bf68d989958ae432b2ae613b6cb7805a4ebf49a5838ef18b26e6256508a8ac4
-  data.tar.gz: 46024ca78a424b725eace01ad965006691e1c4081ee77ab14c22b6aed26356d11542cd8188abbdc35e588adbc7a7ed04d156bc378e6e7e8d42f8659027a72b21
+  metadata.gz: e5a08ff00777508b95e44767dffc2bb24c0efa7a17a62dddb4386a83a07a222847da426000cc61ec166c177afdf8caec51b4fadd67351db775f96a09579e7d75
+  data.tar.gz: b6268730110e341d4f518899ccc57d1bf4f82c39cdb82ff21e6b8ea4beaa1a3739770f4d8d32995d1969174249d61815de13bb8fb1114c793727a86c723e901c

data/CHANGELOG.md

@@ -3,6 +3,74 @@
 Notable changes to where_is_waldo. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## 0.1.8
+
+### Fixed
+
+- **`WhereIsWaldo.subject_online?`, `.sessions_for_subject`, `.session_status`
+  no longer raise `uninitialized constant` when called.** These three methods
+  were defined with ActiveSupport's `delegate :method, to: :PresenceService`
+  inside a `class << self` block. `delegate` generates the method body via
+  `class_eval` with a **string**, and a string-eval'd body's `Module.nesting`
+  is just the target class — for the WhereIsWaldo module's singleton class,
+  that's `[#<Class:WhereIsWaldo>]`, *without* the enclosing `WhereIsWaldo`.
+  Constant lookup for `PresenceService` inside the generated method then
+  couldn't walk up to the enclosing module and failed with:
+
+  ```
+  uninitialized constant #<Class:WhereIsWaldo>::PresenceService (NameError)
+  ```
+
+  Replaced the three `delegate` calls with plain `def` methods matching the
+  pattern of the other class methods on the module (`.connect`, `.online`,
+  `.online_ids`, `.cleanup`, etc.), which inherit the correct lexical scope
+  and resolve `PresenceService` as `WhereIsWaldo::PresenceService`.
+
+  Waldo's own internal code (`PresenceChannel`, `Roster`) references
+  `PresenceService` at its fully-qualified name from correctly-scoped
+  modules, so this bug never affected the actual presence flow — only host
+  code that calls the top-level convenience wrappers. Affects every
+  released version up to and including `0.1.7`.
+
+### Tests
+
+- Added `spec/where_is_waldo_spec.rb` exercising every top-level convenience
+  method at the public boundary — the only place a `class_eval`-scope
+  regression in the wrapper can be caught, since internal callers bypass it.
+
+## 0.1.7
+
+### Added
+
+- **`last_activity` in roster member payloads.** Each member in a
+  `roster_snapshot` / `roster_delta` message now carries a `last_activity`
+  ISO8601 timestamp — the most recent `subject_active: true` heartbeat time
+  across all of the subject's live sessions (web, mobile, whichever). `nil`
+  when the subject has no live sessions. Lets hosts derive "seconds idle"
+  client-side (`Date.now() - new Date(last_activity)`) and apply their own
+  thresholds instead of being tied to the gem's active↔idle boundary.
+
+  Example: a picker that wants "stay green until 3 minutes without input"
+  no longer needs a server-side `activityTimeout` override — it reads
+  `member.last_activity` and thresholds against its own clock. The
+  server's own active/idle enum still ships in `status` for consumers who
+  do want it, and the roster still broadcasts only on transitions (no
+  extra bandwidth beyond the added field).
+
+  Payload shape:
+  ```json
+  { "id": 7, "status": "idle",
+    "devices": { "web": "idle", "mobile": "active" },
+    "last_activity": "2026-07-27T15:23:04Z",
+    "name": "Alan Smith" }
+  ```
+
+  Both adapters were already tracking `last_activity` per session — this
+  release plumbs it through the roster aggregation (max across sessions)
+  and normalizes to an ISO string in the broadcast payload, absorbing the
+  DB-adapter-returns-string / Redis-adapter-returns-Time mismatch at the
+  roster boundary.
+
 ## 0.1.6
 
 ### Security

data/README.md

@@ -2,6 +2,11 @@
 
 Real-time presence tracking for Rails + React using ActionCable.
 
+[![CI](https://github.com/byscott-io/where_is_waldo/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/byscott-io/where_is_waldo/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/where_is_waldo)](https://rubygems.org/gems/where_is_waldo)
+[![npm version](https://img.shields.io/npm/v/@byscott-io/where-is-waldo)](https://www.npmjs.com/package/@byscott-io/where-is-waldo)
+[![License](https://img.shields.io/github/license/byscott-io/where_is_waldo)](LICENSE)
+
 ## Features
 
 - **Presence tracking** - know who's online
@@ -233,7 +238,8 @@ See `docs/PRESENCE_ROSTER_PLAN.md` for the full mode matrix and tradeoffs.
 their live sessions (multiple browser tabs, mobile, etc.):
 
 ```
-{ id: 7, status: "active", devices: { web: "idle", mobile: "active" } }
+{ id: 7, status: "active", devices: { web: "idle", mobile: "active" },
+  last_activity: "2026-07-27T15:23:04Z" }
 ```
 
 - `status` — highest activity across devices (the "active anywhere?" answer):
@@ -243,6 +249,11 @@ their live sessions (multiple browser tabs, mobile, etc.):
   - `offline` — no live sessions
 - `devices[platform]` — that platform's own status (answers "active on
   **mobile**?" vs. "active at all?").
+- `last_activity` — ISO8601 timestamp of the most recent input across **all**
+  the subject's live sessions (`null` when offline). The roster only
+  broadcasts on `status` transitions, so subtract against your own clock to
+  derive seconds-idle and apply client-side thresholds without a server
+  `timeout` change: `(Date.now() - new Date(m.last_activity)) / 1000`.
 
 #### Configure
 

data/VERSION

@@ -1 +1 @@
-0.1.6
+0.1.8

data/app/services/where_is_waldo/roster.rb

@@ -8,12 +8,18 @@ module WhereIsWaldo
   #
   # A member's presence is reported per device AND as an overall roll-up:
   #
-  #   { id: 7, status: "active", devices: { "web" => "active", "mobile" => "idle" } }
+  #   { id: 7, status: "active",
+  #     devices: { "web" => "active", "mobile" => "idle" },
+  #     last_activity: "2026-07-27T15:23:04Z" }
   #
   # `devices[platform]` is that platform's own aggregate status (several browser
   # tabs roll up into one "web" status); `status` is the highest level across
   # all platforms — the "is the user active anywhere?" answer, while
-  # `devices["mobile"]` answers "is the user active on mobile?". Each status is:
+  # `devices["mobile"]` answers "is the user active on mobile?". `last_activity`
+  # is the most recent input timestamp across all of the subject's live sessions
+  # (nil when offline), letting the client subtract from its own clock to derive
+  # seconds-idle and apply its own thresholds without new broadcasts. Each
+  # status is:
   #
   #   active      - a live session on that device is tab-visible AND working
   #   idle        - a live session is tab-visible but not actively using
@@ -182,15 +188,21 @@ module WhereIsWaldo
       # Reduce a subject's live sessions to per-device statuses plus an overall
       # roll-up. Sessions are grouped by platform (so several browser tabs form
       # one "web" status); the overall status is the highest across platforms.
+      # `last_activity` is the max across all sessions (any platform), so it
+      # answers "when did any of this subject's tabs last see input?".
       # @param sessions [Array<Hash>] presence hashes from the adapter
-      # @return [Hash] { status: "active", devices: { "web" => "active", ... } }
+      # @return [Hash] { status:, devices:, last_activity: }
       def aggregate(sessions)
         devices = sessions.group_by { |s| platform(s) }
                           .transform_values { |sess| platform_level(sess) }
         overall = devices.values.max_by { |level| RANK[level] } || :offline
+        # DB adapter returns last_activity as ISO string, Redis as Time; both sort
+        # correctly among themselves. Normalize to ISO string in the payload.
+        last = sessions.filter_map { |s| s[:last_activity] }.max
         {
           status: overall.to_s,
-          devices: devices.transform_values(&:to_s)
+          devices: devices.transform_values(&:to_s),
+          last_activity: last.respond_to?(:iso8601) ? last.iso8601 : last
         }
       end
 
@@ -229,12 +241,13 @@ module WhereIsWaldo
         data.merge(
           id: id || record&.id,
           status: state[:status],
-          devices: state[:devices]
+          devices: state[:devices],
+          last_activity: state[:last_activity]
         )
       end
 
       def offline_state
-        { status: "offline", devices: {} }
+        { status: "offline", devices: {}, last_activity: nil }
       end
 
       def find_subject(subject_id)

data/lib/where_is_waldo.rb

@@ -55,11 +55,25 @@ module WhereIsWaldo
       PresenceService.all_online_ids(timeout: timeout)
     end
 
-    delegate :subject_online?, to: :PresenceService
+    # NOTE: don't use ActiveSupport's `delegate` here. `delegate` generates
+    # the method via `class_eval` with a STRING, and a string-eval'd body's
+    # `Module.nesting` is just the target class — for a `class << self` inside
+    # `module WhereIsWaldo`, that's `[#<Class:WhereIsWaldo>]`, WITHOUT
+    # `WhereIsWaldo` itself. Constant lookup for `PresenceService` inside the
+    # generated method then can't walk up to the enclosing module and raises
+    # `uninitialized constant #<Class:WhereIsWaldo>::PresenceService`. A plain
+    # `def` inherits the enclosing lexical nesting and resolves correctly.
+    def subject_online?(...)
+      PresenceService.subject_online?(...)
+    end
 
-    delegate :sessions_for_subject, to: :PresenceService
+    def sessions_for_subject(...)
+      PresenceService.sessions_for_subject(...)
+    end
 
-    delegate :session_status, to: :PresenceService
+    def session_status(...)
+      PresenceService.session_status(...)
+    end
 
     def cleanup(timeout: nil)
       PresenceService.cleanup(timeout: timeout)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: where_is_waldo
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - Scott Gibson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-25 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails