where_is_waldo 0.1.1

data/lib/where_is_waldo/engine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class Engine < ::Rails::Engine
+    isolate_namespace WhereIsWaldo
+
+    config.autoload_paths << File.expand_path("../../app/services", __dir__)
+    config.autoload_paths << File.expand_path("../../app/channels", __dir__)
+    config.autoload_paths << File.expand_path("../../app/jobs", __dir__)
+    config.autoload_paths << File.expand_path("../../app/models", __dir__)
+
+    # Configure Presence model associations after all code is loaded
+    config.after_initialize do
+      WhereIsWaldo::Presence.configure_associations! if WhereIsWaldo::Presence.respond_to?(:configure_associations!)
+    end
+  end
+end

data/lib/where_is_waldo/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  VERSION = File.read(File.expand_path("../../VERSION", __dir__)).strip
+end

data/lib/where_is_waldo.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "where_is_waldo/version"
+require "where_is_waldo/configuration"
+require "where_is_waldo/engine" if defined?(Rails)
+
+module WhereIsWaldo
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def config
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # === Presence Management ===
+
+    def connect(...)
+      PresenceService.connect(...)
+    end
+
+    def disconnect(...)
+      PresenceService.disconnect(...)
+    end
+
+    def heartbeat(...)
+      PresenceService.heartbeat(...)
+    end
+
+    # === Queries ===
+
+    # Get online subjects from a scope
+    # @example WhereIsWaldo.online(org.members) => AR relation of online members
+    def online(scope, timeout: nil)
+      PresenceService.online(scope, timeout: timeout)
+    end
+
+    # Get online subject IDs from a scope
+    # @example WhereIsWaldo.online_ids(org.members.admin)
+    def online_ids(scope, timeout: nil)
+      PresenceService.online_ids(scope, timeout: timeout)
+    end
+
+    # Get all online subject IDs (no scope filtering)
+    def all_online_ids(timeout: nil)
+      PresenceService.all_online_ids(timeout: timeout)
+    end
+
+    delegate :subject_online?, to: :PresenceService
+
+    delegate :sessions_for_subject, to: :PresenceService
+
+    delegate :session_status, to: :PresenceService
+
+    def cleanup(timeout: nil)
+      PresenceService.cleanup(timeout: timeout)
+    end
+
+    # === Presence roster (live presence awareness) ===
+
+    # Full roster state for an org record (every member + current presence).
+    def roster_snapshot(org, timeout: nil)
+      Roster.snapshot(org, timeout: timeout)
+    end
+
+    # Aggregate presence state ({ status:, devices: }) for one subject.
+    def roster_state_for(subject_id, timeout: nil)
+      Roster.state_for(subject_id, timeout: timeout)
+    end
+
+    # Presence status for a subject on a specific device/platform.
+    # @example WhereIsWaldo.presence_on(user.id, :mobile) # => "idle"
+    def presence_on(subject_id, platform, timeout: nil)
+      Roster.device_status(subject_id, platform, timeout: timeout)
+    end
+
+    # Broadcast a compact presence delta for a subject to their org's roster
+    # stream. Call on transitions only (usually automatic via PresenceChannel).
+    def publish_presence(subject_id, timeout: nil)
+      Roster.publish(subject_id, timeout: timeout)
+    end
+
+    # Shared roster stream name for the org a subject belongs to.
+    def roster_stream_for(subject)
+      Roster.stream_for_subject(subject)
+    end
+
+    # === Broadcasting ===
+
+    # Broadcast to subjects in a scope
+    # @example WhereIsWaldo.broadcast_to(org.members, :notification, { message: "Hello" })
+    def broadcast_to(scope, message_type, data = {})
+      Broadcaster.broadcast_to(scope, message_type, data)
+    end
+
+    # Broadcast only to online subjects in a scope
+    # @example WhereIsWaldo.broadcast_to_online(org.members, :alert, { message: "Urgent" })
+    def broadcast_to_online(scope, message_type, data = {})
+      Broadcaster.broadcast_to_online(scope, message_type, data)
+    end
+
+    # Broadcast to a specific session
+    # @example WhereIsWaldo.broadcast_to_session(session_id, :force_logout, { reason: "..." })
+    def broadcast_to_session(session_id, message_type, data = {})
+      Broadcaster.broadcast_to_session(session_id, message_type, data)
+    end
+  end
+end

metadata

@@ -0,0 +1,249 @@
+--- !ruby/object:Gem::Specification
+name: where_is_waldo
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Scott Gibson
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: mock_redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.36'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.36'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.1
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.23'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.26'
+- !ruby/object:Gem::Dependency
+  name: sprockets-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: Track who's online, their activity state, and broadcast messages. Fully
+  configurable - works with any user model, session system, and room concept.
+email:
+- scott@byscott.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- VERSION
+- app/channels/where_is_waldo/application_cable/channel.rb
+- app/channels/where_is_waldo/application_cable/connection.rb
+- app/channels/where_is_waldo/jwt_connection.rb
+- app/channels/where_is_waldo/presence_channel.rb
+- app/channels/where_is_waldo/roster_channel.rb
+- app/jobs/where_is_waldo/application_job.rb
+- app/jobs/where_is_waldo/presence_cleanup_job.rb
+- app/models/concerns/where_is_waldo/broadcastable.rb
+- app/models/where_is_waldo/application_record.rb
+- app/models/where_is_waldo/presence.rb
+- app/services/where_is_waldo/adapters/base_adapter.rb
+- app/services/where_is_waldo/adapters/database_adapter.rb
+- app/services/where_is_waldo/adapters/redis_adapter.rb
+- app/services/where_is_waldo/broadcaster.rb
+- app/services/where_is_waldo/presence_service.rb
+- app/services/where_is_waldo/roster.rb
+- app/services/where_is_waldo/roster_delivery.rb
+- lib/generators/where_is_waldo/install/install_generator.rb
+- lib/generators/where_is_waldo/install/templates/channel.rb.tt
+- lib/generators/where_is_waldo/install/templates/connection.rb.tt
+- lib/generators/where_is_waldo/install/templates/create_presences.rb.tt
+- lib/generators/where_is_waldo/install/templates/initializer.rb.tt
+- lib/generators/where_is_waldo/install/templates/migration.rb.tt
+- lib/generators/where_is_waldo/install/templates/presence_channel.rb.tt
+- lib/where_is_waldo.rb
+- lib/where_is_waldo/configuration.rb
+- lib/where_is_waldo/engine.rb
+- lib/where_is_waldo/version.rb
+homepage: https://github.com/byscott-io/where_is_waldo
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/byscott-io/where_is_waldo
+  source_code_uri: https://github.com/byscott-io/where_is_waldo
+  changelog_uri: https://github.com/byscott-io/where_is_waldo/blob/master/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Real-time presence tracking for Rails + React applications
+test_files: []