cloudflare-ruby 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79f116a0ab2331ea5587107448e486c7659867ca8e40b1519159819371d080a4
-  data.tar.gz: 2e02047872c19bb021fda6c841ee7ac783ed8892274cb6e20a3a361f08dd5674
+  metadata.gz: e840df4dc6ff74e2cb0fddaba160fc041c80472c52f7a583f9c23185d24b8765
+  data.tar.gz: 9a42b0db13ed3d842fb1bc1b9df86011de55223a6667a666e3431bd455d4e4fd
 SHA512:
-  metadata.gz: d8bd76dddd2e2051ca5b2ab81189889683877d8238acf9c9e33c5f40120cd5a8fc9e9e14193322e33b2be013d27b1e2f7c71d83a2d250f36dc77447a79067e70
-  data.tar.gz: 6d259474067c3354e00f0dee5cd1e158f342cce6c13abea5c1d299162b61be3502f1c395a3db1300f63ad73965702fe171b1e567f1ead349f9afcb26ae46ac3c
+  metadata.gz: 71d24e6e2fbb63aee5c96e23e581f668207df71b7cc281cc02bfdb8c07e2e377e3a30e5a5888c90a5dd1acb0b0b4a4d734faf779bc9140b51a2400cad6029769
+  data.tar.gz: 9a73874dadf0b7847b5058a4ab40dec0acedb93765438d0c2b96632c376bddf1a9b23f04ee167206c7ee35a138ca8cfabca8c2e6eba66a20bd646050e13f5c7a

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 0.2.0
+
+- **Default `app_id` per process.** Set `Cloudflare::RealtimeKit.app_id`
+  once at boot and every RealtimeKit call defaults to it; pass `app_id:`
+  per-call only to override. Mirrors the existing `Cloudflare.account_id`
+  pattern. Eliminates `app_id:` repetition in apps that talk to a single
+  RealtimeKit app per process (the common case).
+- `Resource.build_scope` and `extract_scope!` now consult a generic
+  `global_default_for(key)` helper that resolves `:account_id` against
+  `Cloudflare.account_id` and any other key against a same-named
+  accessor on the resource's product namespace
+  (e.g., `:app_id` → `Cloudflare::RealtimeKit.app_id`). Generalizes for
+  future product surfaces.
+- `Recording.start_track`, `Recording.active_for`,
+  `Session.find_participant_by_peer_id`, `Analytics.daywise`, and
+  `Analytics.livestreams_overall` now accept `app_id:` as optional with
+  the default falling through.
+
+## 0.1.2
+
+- Add `require "bundler/gem_tasks"` to the Rakefile so `rake release`
+  resolves. The `rubygems/release-gem@v1` action invokes that task on
+  release; without it the workflow failed at the publish step.
+
+## 0.1.1
+
+- Re-publish 0.1.0 with the RubyGems trusted publisher configured. No
+  code changes.
+
+## 0.1.0
+
+- Initial release. Hand-written Ruby client for the Cloudflare API.
+- Covers the **RealtimeKit** product surface: `App`, `Meeting`, `Participant`,
+  `ActiveSession`, `Session`, `SessionParticipant`, `Chat`, `Summary`,
+  `Transcript`, `Recording`, `Preset`, `Webhook`, `Livestream`,
+  `LivestreamSession`, `ActiveLivestreamSession`, and `Analytics`.
+  Every endpoint in the upstream OpenAPI slice is reachable through one
+  Ruby method (MECE-verified).
+- AR-flavored foundation: `Cloudflare::Resource` with `attribute`,
+  `has_many`, `has_one`, `read_only`, plus `Cloudflare::Relation` for
+  nested-collection access.
+- Stripe-style global config (`Cloudflare.configure`).
+- Status-keyed error hierarchy: `AuthenticationError`, `NotFoundError`,
+  `ValidationError`, `RateLimitError`, `ServerError`.
+- Drift-detection CLI: `bundle exec exe/cloudflare-ruby check-drift PRODUCT`
+  fetches upstream `openapi.json`, runs the slicer, and reports a
+  structured diff against the saved `spec/slices/<product>.json`. Caches
+  upstream at `tmp/upstream-openapi.json` for offline re-runs.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tokimonki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,9 +1,133 @@
 # cloudflare-ruby
 
-Ruby SDK for the Cloudflare API.
+Ruby SDK for the Cloudflare API. Hand-written, narrow on purpose — currently covers the **RealtimeKit** product surface; other surfaces (R2, Workers, DNS) added on demand.
 
-> **Status: placeholder.** This release reserves the gem name. The real SDK is in active development. Track progress at https://github.com/tokimonki/cloudflare-ruby.
+> **Status: prototyping.** API not yet stable. The 0.0.x line is exploratory; the first stable release will be `0.1.0`. Repo is private until then.
+
+## Product surfaces
+
+Each Cloudflare product is its own namespace under `Cloudflare::`, with its own README living next to the code:
+
+| Product | Namespace | README |
+|---|---|---|
+| RealtimeKit | `Cloudflare::RealtimeKit` | [`lib/cloudflare/realtime_kit/README.md`](lib/cloudflare/realtime_kit/README.md) |
+
+New product surfaces are added by writing the resource classes by hand (no codegen) and adding a slice entry under `spec/slices/<product>.json` for drift detection.
+
+## Why hand-rolled and not openapi-generator / Stainless
+
+- We only need a thin slice of Cloudflare's 2,000+ endpoint API.
+- We want code that reads like the rest of our Ruby — generated SDKs in any language carry a generic style we'd rather not adopt.
+- A dedicated drift checker, scoped to *what we use*, gives us automation without 17 KLOC of generated noise.
+
+See [the design doc](https://github.com/am1006/tokimonki-exchange/issues/215) for the full reasoning.
+
+## Install
+
+```ruby
+# Gemfile
+gem "cloudflare-ruby", git: "git@github.com:tokimonki/cloudflare-ruby.git"
+```
+
+## Configuration
+
+Stripe-style global config; every resource picks it up implicitly.
+
+```ruby
+Cloudflare.configure do |c|
+  c.api_token  = ENV.fetch("CLOUDFLARE_API_TOKEN")
+  c.account_id = ENV.fetch("CLOUDFLARE_ACCOUNT_ID")  # default for every call
+end
+```
+
+Per-call `account_id:` overrides the global. `api_token` has no per-call override — set it once.
+
+## Errors
+
+Every product surface raises a member of the same hierarchy:
+
+```ruby
+begin
+  Cloudflare::RealtimeKit::Meeting.find("missing", app_id: "app-1")
+rescue Cloudflare::NotFoundError => e
+  e.status  # => 404
+  e.body    # => parsed response body
+end
+```
+
+Hierarchy:
+
+```
+Cloudflare::Error
+├── AuthenticationError   (401, 403)
+├── NotFoundError         (404)
+├── ValidationError       (422)
+├── RateLimitError        (429)
+└── ServerError           (5xx)
+```
+
+`Connection` retries 429/502/503/504 up to 2× with backoff before raising.
+
+## Drift detection
+
+The SDK is hand-written against a saved slice of Cloudflare's OpenAPI spec (`spec/slices/<product>.json`). When upstream changes, you re-extract the slice and diff to surface what moved:
+
+```bash
+bundle exec exe/cloudflare-ruby check-drift realtime_kit
+# → "No drift detected for realtime_kit." (exit 0)
+# → or a structured report of added/removed/changed paths and components (exit 1)
+```
+
+The fetched upstream spec is cached at `tmp/upstream-openapi.json` (gitignored) for inspection or offline re-runs (`--spec PATH`).
+
+To re-baseline after an intentional update:
+
+```bash
+bundle exec exe/cloudflare-ruby refresh-slice realtime_kit
+```
+
+The diff covers `paths` plus every `components.*` sub-section discovered in either slice's union — new sections upstream starts using (e.g., `requestBodies`, `securitySchemes`) get diffed without code changes.
+
+## Architecture
+
+```
+lib/
+├── cloudflare.rb               # top-level module, autoload registry
+└── cloudflare/
+    ├── version.rb
+    ├── configuration.rb        # global config (api_token, account_id, base_url)
+    ├── connection.rb           # Faraday singleton — auth, retries, JSON
+    ├── errors.rb               # status-keyed error classes
+    ├── resource.rb             # AR-flavored base (attribute, has_many, has_one, ...)
+    ├── relation.rb             # nested-collection proxy
+    └── <product>/              # one folder per product surface
+        ├── README.md           # product-specific DX guide
+        └── *.rb                # resource classes
+
+codegen/                        # drift detection, not codegen
+├── cli.rb                      # Thor: refresh-slice + check-drift
+├── slicer.rb                   # extract paths-by-prefix from upstream
+├── drift_detector.rb           # structured diff
+└── spec_version.rb             # OpenAPI 3.0.3 pin
+
+spec/slices/<product>.json      # the saved slice — drift baseline
+test/                           # foundation + per-resource tests
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+Adding a new product surface:
+
+1. `bundle exec exe/cloudflare-ruby refresh-slice <product>` (after registering it in `codegen/cli.rb` `PRODUCTS`).
+2. Write the resource classes under `lib/cloudflare/<product>/`.
+3. Write a `lib/cloudflare/<product>/README.md` documenting the DX.
+4. Add a row to the product surfaces table above.
 
 ## License
 
-MIT
+MIT.

data/lib/cloudflare/configuration.rb

@@ -0,0 +1,11 @@
+module Cloudflare
+  class Configuration
+    attr_accessor :api_token, :account_id, :base_url, :timeout, :user_agent
+
+    def initialize
+      @base_url   = "https://api.cloudflare.com/client/v4"
+      @timeout    = 30
+      @user_agent = "cloudflare-ruby/#{VERSION}"
+    end
+  end
+end

data/lib/cloudflare/connection.rb

@@ -0,0 +1,52 @@
+module Cloudflare
+  # Internal Faraday wrapper. Singleton; shared by every resource across every
+  # product. Auth, retries, and JSON encoding live here so the Resource layer
+  # can stay focused on REST semantics.
+  class Connection
+    class << self
+      def instance = @instance ||= new
+      def reset!   = @instance = nil
+    end
+
+    def request(method, path, body: nil, params: nil)
+      raise Error, "Cloudflare.api_token not configured" if Cloudflare.api_token.nil?
+
+      faraday.public_send(method, path.delete_prefix("/")) do |req|
+        req.headers["Authorization"] = "Bearer #{Cloudflare.api_token}"
+        req.headers["User-Agent"]    = Cloudflare.configuration.user_agent
+        req.params = compact(params) if params
+        req.body   = compact(body)   if body
+      end.body
+    rescue Faraday::Error => e
+      raise translate_error(e)
+    end
+
+    private
+      def faraday
+        Faraday.new(url: Cloudflare.base_url, request: { timeout: Cloudflare.configuration.timeout }) do |f|
+          f.request  :json
+          f.request  :retry, max: 2, interval: 0.5, backoff_factor: 2,
+                             retry_statuses: [ 429, 502, 503, 504 ]
+          f.response :json, content_type: /\bjson$/
+          f.response :raise_error
+          f.adapter  Faraday.default_adapter
+        end
+      end
+
+      # Strip nil values recursively so unset kwargs don't become explicit nulls.
+      def compact(value)
+        case value
+        when Hash  then value.each_with_object({}) { |(k, v), h| h[k] = compact(v) unless v.nil? }
+        when Array then value.map { compact(_1) }
+        else            value
+        end
+      end
+
+      def translate_error(faraday_error)
+        status = faraday_error.response_status
+        body   = faraday_error.response_body
+        klass  = ERROR_BY_STATUS[status] || (status && status >= 500 ? ServerError : Error)
+        klass.new(faraday_error.message, status: status, body: body)
+      end
+  end
+end

data/lib/cloudflare/errors.rb

@@ -0,0 +1,25 @@
+module Cloudflare
+  class Error < StandardError
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class NotFoundError       < Error; end
+  class ValidationError     < Error; end
+  class RateLimitError      < Error; end
+  class ServerError         < Error; end
+
+  ERROR_BY_STATUS = {
+    401 => AuthenticationError,
+    403 => AuthenticationError,
+    404 => NotFoundError,
+    422 => ValidationError,
+    429 => RateLimitError
+  }.freeze
+end

data/lib/cloudflare/realtime_kit/README.md

@@ -0,0 +1,209 @@
+# RealtimeKit
+
+Ruby bindings for [Cloudflare RealtimeKit](https://developers.cloudflare.com/realtime/realtimekit/) — managed video/audio infrastructure for meetings, livestreams, recordings, sessions, and analytics. Every endpoint in the upstream OpenAPI spec is reachable through one method on a hand-written class under `Cloudflare::RealtimeKit::*`.
+
+## Setup
+
+```ruby
+require "cloudflare"
+
+Cloudflare.configure do |c|
+  c.api_token  = ENV.fetch("CLOUDFLARE_API_TOKEN")
+  c.account_id = ENV.fetch("CLOUDFLARE_ACCOUNT_ID")
+end
+
+# Default app_id for every RealtimeKit call this process makes.
+# Pass `app_id:` per-call only to override (e.g., admin tools that hop
+# between apps).
+Cloudflare::RealtimeKit.app_id = ENV.fetch("REALTIMEKIT_APP_ID")
+
+RK = Cloudflare::RealtimeKit  # alias to taste
+```
+
+After that, both `account_id:` and `app_id:` are implicit on every call — pass either per-call only to override.
+
+## Apps
+
+Top-level tenants. Meetings, sessions, recordings, presets, webhooks, livestreams, and analytics all live under an app.
+
+```ruby
+RK::App.create(name: "Production")   # POST /apps
+RK::App.all                          # GET  /apps
+```
+
+## Meetings
+
+Most calls below show `app_id:` for clarity. With `Cloudflare::RealtimeKit.app_id` set globally (see Setup), you can omit it.
+
+```ruby
+meeting = RK::Meeting.create(app_id: app.id, title: "Standup", record_on_start: true)
+meeting.id            # => "mtg-…"
+meeting.title         # => "Standup"
+meeting.persist_chat? # => false
+meeting.created_at    # => Time
+
+meeting.update(title: "Daily standup")               # PATCH
+meeting.replace(title: "Daily", persist_chat: false) # PUT — full replacement
+
+RK::Meeting.find(meeting.id, app_id: app.id)
+RK::Meeting.all(app_id: app.id, page_no: 1, per_page: 50, search: "team")
+```
+
+Per-meeting livestream control:
+
+```ruby
+meeting.start_livestreaming(name: "Stream")                   # POST /meetings/{id}/livestreams
+meeting.active_livestream                                     # → Livestream
+meeting.stop_livestream                                       # POST /meetings/{id}/active-livestream/stop
+meeting.livestream_details(page_no: 1, per_page: 10)          # legacy bundled view
+```
+
+## Participants
+
+```ruby
+host = meeting.participants.create(
+  custom_participant_id: "u-1",
+  preset_name: "host_preset",
+  name: "Alex"
+)
+
+host.token                # → join token
+host.regenerate_token     # mints fresh; mutates in place
+host.update(name: "Alexandra")
+host.destroy
+
+meeting.participants.all
+meeting.participants.find("p-1")
+```
+
+## Active session — moderation surface
+
+`meeting.active_session` returns a stub that auto-fetches its attrs only on the first attribute read. Action methods (`kick_all`, `mute_all`, etc.) skip the fetch — pure-action flows pay no GET.
+
+```ruby
+active = meeting.active_session
+active.live_participants                                              # 1 GET
+active.kick(participant_ids: %w[p-1 p-2], custom_participant_ids: [])
+active.kick_all
+active.mute(participant_ids: %w[p-1], custom_participant_ids: [])
+active.mute_all(allow_unmute: false)
+active.create_poll(question: "Lunch?", options: %w[Pizza Salad], anonymous: true)
+```
+
+## Recording
+
+```ruby
+rec = RK::Recording.create(app_id: app.id, meeting_id: meeting.id)
+
+# Transitions: one canonical method, three sugar verbs.
+rec.transition(action: :pause)   # canonical — sole wire mapping for PUT /recordings/{id}
+rec.pause                        # sugar — calls transition(action: :pause)
+rec.resume
+rec.stop
+
+RK::Recording::TRANSITIONS       # => [:pause, :resume, :stop] — spec-enumerated
+RK::Recording.active_for(meeting_id: meeting.id, app_id: app.id)
+RK::Recording.start_track(app_id: app.id, meeting_id: meeting.id, layers: [{ type: "audio" }])
+```
+
+## Sessions — historical records
+
+Sessions are read-only from the SDK; they're created automatically by the platform when a meeting goes live.
+
+```ruby
+session = RK::Session.find("sess-1", app_id: app.id)
+session.participants.all                                # → Array<SessionParticipant>
+session.chat.messages                                   # auto-loads /sessions/{id}/chat
+session.summary.text                                    # auto-loads /sessions/{id}/summary
+session.summary.generate                                # POST to (re)trigger summary
+session.transcript.segments                             # auto-loads /sessions/{id}/transcript
+session.livestream_sessions(page_no: 1, per_page: 20)   # → Array<LivestreamSession>
+
+# Reverse lookup: peer-id from a webhook → participant data
+RK::Session.find_participant_by_peer_id("peer-99", app_id: app.id)
+```
+
+`SessionParticipant` is read-only — the upstream spec exposes only GET endpoints. Calling `session.participants.create(...)` raises `NoMethodError` immediately, before any HTTP call.
+
+## Livestreams
+
+```ruby
+ls = RK::Livestream.create(app_id: app.id, name: "Conference")
+ls.ingest_server   # => "rtmps://live.cloudflare.com:443/live/"
+ls.stream_key
+ls.playback_url    # HLS
+
+# Active session — bundles config + runtime stats as typed sub-objects
+active = ls.active_session
+active.livestream.stream_key       # → Livestream instance
+active.session.viewer_seconds      # → LivestreamSession instance
+
+# Direct lookup
+RK::LivestreamSession.find("lsx-1", app_id: app.id)
+```
+
+## Webhooks
+
+```ruby
+hook = RK::Webhook.create(
+  app_id: app.id,
+  name:   "Recording finished",
+  url:    "https://example.com/hooks/realtimekit",
+  events: %w[recording.finished session.ended]
+)
+hook.enabled?
+hook.update(enabled: false)
+hook.replace(name: "...", url: "...", events: [...])  # PUT
+hook.destroy
+```
+
+## Presets
+
+```ruby
+preset = RK::Preset.create(
+  app_id: app.id,
+  name:   "host_preset",
+  config: { ... },
+  ui:     { ... },
+  permissions: { ... }
+)
+preset.update(permissions: { ... })
+preset.destroy
+```
+
+## Analytics
+
+```ruby
+RK::Analytics.daywise(app_id: app.id, start_date: "2025-01-01", end_date: "2025-01-31")
+RK::Analytics.livestreams_overall(app_id: app.id, start_time: "...", end_time: "...")
+```
+
+Returns the raw report Hash — no per-row modeling.
+
+## Conventions
+
+- **Envelopes** (`{data: ...}` or `{result: ...}`) are unwrapped automatically. You read attributes as if they were flat.
+- **Time coercion**: ISO-8601 strings → `Time` on read for any attribute typed `Time`.
+- **Booleans**: typed attributes get a `?` predicate (`webhook.enabled?`).
+- **Scope plumbing**: once you have a `meeting`, every nested call (`meeting.participants.find(id)`, `meeting.active_session.kick_all`) carries `account_id` + `app_id` + `meeting_id` automatically.
+- **Singletons** (`active_session`, `chat`, `summary`, `transcript`): lazy-load on first attribute read. Action methods skip the fetch.
+- **Read-only resources** (`SessionParticipant`): `create` / `update` / `destroy` raise `NoMethodError` before any HTTP call, citing the missing endpoint.
+
+## Class index
+
+| Class | Endpoints under |
+|---|---|
+| `App` | `/accounts/{id}/realtime/kit/apps` |
+| `Meeting` | `/.../{app_id}/meetings`, `/meetings/{id}` |
+| `Participant` | `/meetings/{id}/participants` |
+| `ActiveSession` | `/meetings/{id}/active-session` (singleton) |
+| `Session` | `/.../{app_id}/sessions`, `/sessions/{id}` |
+| `SessionParticipant` | `/sessions/{id}/participants` (read-only) |
+| `Chat`, `Summary`, `Transcript` | session sub-singletons |
+| `Recording` | `/.../{app_id}/recordings`, `/recordings/{id}` |
+| `Preset` | `/.../{app_id}/presets`, `/presets/{id}` |
+| `Webhook` | `/.../{app_id}/webhooks`, `/webhooks/{id}` |
+| `Livestream` | `/.../{app_id}/livestreams`, `/livestreams/{id}` |
+| `LivestreamSession` | `/livestreams/sessions/{id}` |
+| `ActiveLivestreamSession` | `/livestreams/{id}/active-livestream-session` (singleton) |
+| `Analytics` | `/.../{app_id}/analytics/*` (function namespace, not a Resource) |

data/lib/cloudflare/realtime_kit/active_livestream_session.rb

@@ -0,0 +1,46 @@
+module Cloudflare
+  module RealtimeKit
+    # A livestream's currently-active session. Singleton — there's at most one
+    # active session per livestream. Reached via +livestream.active_session+,
+    # which returns a stub that auto-fetches on first attribute read.
+    #
+    # The response bundles two sub-objects: +livestream+ (the broadcast
+    # configuration: ingest server, stream key, playback URL) and +session+
+    # (the runtime: started_time, viewer_seconds, status). Both are returned
+    # as typed instances of +Livestream+ and +LivestreamSession+ — partial
+    # copies of those schemas, but typed access reads better than Hash
+    # bracketing, and the returned instances carry enough scope to call
+    # +#reload+ against their canonical endpoints if you want a full refresh.
+    #
+    #   active = livestream.active_session
+    #   active.livestream.stream_key   # → String
+    #   active.session.viewer_seconds  # → Integer
+    #   active.livestream.reload       # → fetches /livestreams/{id} for the full record
+    class ActiveLivestreamSession < Resource
+      member_path "/accounts/{account_id}/realtime/kit/{app_id}/livestreams/{livestream_id}/active-livestream-session"
+      scope_required :app_id, :livestream_id
+
+      # Override the default attribute readers: instead of returning the raw
+      # Hash sub-object, hand back a typed Livestream / LivestreamSession
+      # scoped to the same app so the caller can keep operating on it.
+      def livestream
+        ensure_loaded!
+        raw = @attrs["livestream"]
+        raw && Livestream.new(raw, scope: parent_scope)
+      end
+
+      def session
+        ensure_loaded!
+        raw = @attrs["session"]
+        raw && LivestreamSession.new(raw, scope: parent_scope)
+      end
+
+      private
+        # The sub-objects share the app-level scope but not the
+        # +livestream_id+ that's specific to *this* active-session lookup.
+        def parent_scope
+          { account_id: @scope[:account_id], app_id: @scope[:app_id] }
+        end
+    end
+  end
+end

data/lib/cloudflare/realtime_kit/active_session.rb

@@ -0,0 +1,68 @@
+module Cloudflare
+  module RealtimeKit
+    # A meeting's currently-running session. Modeled as a singleton: every
+    # meeting has at most one active session at a time. Reached via
+    # +meeting.active_session+, which auto-loads the session attributes on
+    # first access and caches them.
+    #
+    #   active = meeting.active_session
+    #   active.live_participants
+    #   active.kick(participant_ids: [ "p-1" ])
+    #   active.mute_all(allow_unmute: false)
+    #   active.create_poll(question: "Lunch?", options: [ "Pizza", "Salad" ])
+    #
+    # +kick_all+ and +mute_all+ act on every participant; the others target
+    # specific ids (or +custom_participant_ids+ if you assigned them at
+    # invite time).
+    class ActiveSession < Resource
+      # Singleton path — no +{id}+ placeholder. The base +reload+ uses
+      # +member_path+ regardless of whether the path interpolates an id.
+      member_path "/accounts/{account_id}/realtime/kit/{app_id}/meetings/{meeting_id}/active-session"
+      scope_required :app_id, :meeting_id
+
+      attribute :id,                          String
+      attribute :associated_id,               String
+      attribute :type,                        String
+      attribute :status,                      String
+      attribute :meeting_display_name,        String
+      attribute :organization_id,             String
+      attribute :live_participants,           Integer
+      attribute :max_concurrent_participants, Integer
+      attribute :minutes_consumed,            Integer
+      attribute :started_at,                  Time
+      attribute :ended_at,                    Time
+      attribute :created_at,                  Time
+      attribute :updated_at,                  Time
+
+      # POST .../active-session/kick — remove specified participants.
+      def kick(participant_ids:, custom_participant_ids:)
+        Connection.instance.request(:post, "#{member_path}/kick",
+          body: { participant_ids: participant_ids, custom_participant_ids: custom_participant_ids })
+      end
+
+      # POST .../active-session/kick-all — remove every participant.
+      def kick_all
+        Connection.instance.request(:post, "#{member_path}/kick-all")
+      end
+
+      # POST .../active-session/mute — mute specified participants.
+      def mute(participant_ids:, custom_participant_ids:)
+        Connection.instance.request(:post, "#{member_path}/mute",
+          body: { participant_ids: participant_ids, custom_participant_ids: custom_participant_ids })
+      end
+
+      # POST .../active-session/mute-all — mute every participant.
+      # +allow_unmute+ controls whether participants can re-enable their mic.
+      def mute_all(allow_unmute:)
+        Connection.instance.request(:post, "#{member_path}/mute-all",
+          body: { allow_unmute: allow_unmute })
+      end
+
+      # POST .../active-session/poll — broadcast a poll to participants.
+      def create_poll(question:, options:, anonymous: nil, hide_votes: nil)
+        Connection.instance.request(:post, "#{member_path}/poll",
+          body: { question: question, options: options, anonymous: anonymous, hide_votes: hide_votes })
+      end
+    end
+  end
+end