broadcast-ruby 0.1.4 → 0.3.0

data/SDK-COVERAGE.md

@@ -0,0 +1,422 @@
+# broadcast-ruby — coverage
+
+What this gem covers, what it deliberately doesn't, and what the Broadcast
+application can do that no client can reach.
+
+**Headline: 104/104 API operations (100%).**
+
+That number is narrower than it sounds, and [Limits of the 100%](#limits-of-the-100)
+explains exactly what it does not measure. Read that section before quoting the
+figure.
+
+- Gem version: **0.3.0**
+- API version: **2.19.0** (75 paths, 104 operations)
+- Generated by: `bin/rails "openapi:coverage[../broadcast-ruby]"` in the
+  `broadcast` repo
+- Verified: self-hosted and SaaS mode (the `/api` surface is identical in both)
+
+---
+
+## Contents
+
+1. [How coverage is measured](#how-coverage-is-measured)
+2. [Endpoint map](#endpoint-map) — every operation → the method that calls it
+3. [Transport coverage](#transport-coverage) — the protocol, not the endpoints
+4. [Webhook coverage](#webhook-coverage) — inbound
+5. [Not in the API at all](#not-in-the-api-at-all) — app features no client can reach
+6. [Limits of the 100%](#limits-of-the-100)
+
+---
+
+## How coverage is measured
+
+The `broadcast` repo generates an OpenAPI 3.1 document from `config/routes.rb`
+plus the `*_PARAM_KEYS` constants each controller declares, then scans this
+gem's source for the paths it calls.
+
+```bash
+# in the broadcast repo
+bin/rails openapi:generate
+bin/rails "openapi:coverage[../broadcast-ruby]"
+```
+
+Two details worth knowing when reading the map below:
+
+- **PATCH is canonical.** Rails' `resources` routes `update` to both PATCH and
+  PUT. They are one operation; the generator drops the PUT alias. Counting both
+  would inflate the denominator by 8 and make this gem look 8 endpoints short.
+- **Metaprogrammed endpoints are declared.** The 18 migration collections are
+  defined by `define_method` over `Migration::COLLECTIONS`, so no path literal
+  exists to scan. They are listed in `.api-coverage.yml` and marked
+  *(generated)* below. That file is produced from the gem's own constants — it
+  is not a hand-written promise.
+
+---
+
+## Endpoint map
+
+Every operation in the API, and the gem method that issues it. Grouped as the
+spec groups them.
+
+### Discovery — 4/4
+
+Introspection endpoints. Useful as a deploy-time smoke check and as the entry
+point for agents and CLIs.
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/whoami` | `Discovery#whoami` — also `client.whoami` |
+| GET | `/api/v1/status` | `Discovery#status` — also `client.status` |
+| GET | `/api/v1/prime` | `Discovery#prime` — also `client.prime` |
+| GET | `/api/v1/skill` | `Discovery#skill` — also `client.skill`; returns a String, not a Hash |
+
+### Subscribers — 11/11
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/subscribers` | `Subscribers#list` |
+| GET | `/api/v1/subscribers/find` | `Subscribers#find` |
+| POST | `/api/v1/subscribers` | `Subscribers#create` |
+| PATCH | `/api/v1/subscribers` | `Subscribers#update` |
+| POST | `/api/v1/subscribers/add_tag` | `Subscribers#add_tags` |
+| DELETE | `/api/v1/subscribers/remove_tag` | `Subscribers#remove_tags` |
+| POST | `/api/v1/subscribers/activate` | `Subscribers#activate` |
+| POST | `/api/v1/subscribers/deactivate` | `Subscribers#deactivate` |
+| POST | `/api/v1/subscribers/unsubscribe` | `Subscribers#unsubscribe` |
+| POST | `/api/v1/subscribers/resubscribe` | `Subscribers#resubscribe` |
+| POST | `/api/v1/subscribers/redact` | `Subscribers#redact` |
+
+Subscribers are addressed by **email**, not id — there is no
+`/api/v1/subscribers/{id}`. `list` supports eight filters (`is_active`,
+`source`, `created_after`, `created_before`, `tags`, `email` partial match,
+`confirmation_status`, `custom_data` JSONB containment).
+
+There is no destroy endpoint by design; `redact` is the GDPR erasure path and
+preserves aggregate statistics.
+
+### Broadcasts — 8/8, plus statistics 3/3
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/broadcasts` | `Broadcasts#list` |
+| GET | `/api/v1/broadcasts/{id}` | `Broadcasts#get_broadcast` |
+| POST | `/api/v1/broadcasts` | `Broadcasts#create` |
+| PATCH | `/api/v1/broadcasts/{id}` | `Broadcasts#update` |
+| DELETE | `/api/v1/broadcasts/{id}` | `Broadcasts#delete` |
+| POST | `/api/v1/broadcasts/{id}/send_broadcast` | `Broadcasts#send_broadcast` |
+| POST | `/api/v1/broadcasts/{id}/schedule_broadcast` | `Broadcasts#schedule` |
+| POST | `/api/v1/broadcasts/{id}/cancel_schedule` | `Broadcasts#cancel_schedule` |
+| GET | `/api/v1/broadcasts/{id}/statistics` | `Broadcasts#statistics` |
+| GET | `/api/v1/broadcasts/{id}/statistics/timeline` | `Broadcasts#statistics_timeline` |
+| GET | `/api/v1/broadcasts/{id}/statistics/links` | `Broadcasts#statistics_links` |
+
+### Sequences — 8/8, plus steps 6/6
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/sequences` | `Sequences#list` |
+| GET | `/api/v1/sequences/{id}` | `Sequences#get_sequence` |
+| POST | `/api/v1/sequences` | `Sequences#create` |
+| PATCH | `/api/v1/sequences/{id}` | `Sequences#update` |
+| DELETE | `/api/v1/sequences/{id}` | `Sequences#delete` |
+| POST | `/api/v1/sequences/{id}/add_subscriber` | `Sequences#add_subscriber` |
+| DELETE | `/api/v1/sequences/{id}/remove_subscriber` | `Sequences#remove_subscriber` |
+| GET | `/api/v1/sequences/{id}/list_subscribers` | `Sequences#list_subscribers` |
+| GET | `/api/v1/sequences/{id}/steps` | `Sequences#list_steps` |
+| GET | `/api/v1/sequences/{id}/steps/{step_id}` | `Sequences#get_step` |
+| POST | `/api/v1/sequences/{id}/steps` | `Sequences#create_step` |
+| PATCH | `/api/v1/sequences/{id}/steps/{step_id}` | `Sequences#update_step` |
+| DELETE | `/api/v1/sequences/{id}/steps/{step_id}` | `Sequences#delete_step` |
+| POST | `/api/v1/sequences/{id}/steps/{step_id}/move` | `Sequences#move_step` |
+
+Steps form a tree linked by `parent_id`, not a flat list — `move_step` reparents
+rather than reorders.
+
+### Transactionals — 2/2
+
+| Method | Path | Gem |
+|---|---|---|
+| POST | `/api/v1/transactionals` | `Transactionals#create` — also `client.send_email` |
+| GET | `/api/v1/transactionals/{id}` | `Transactionals#get_transactional` — also `client.get_email` |
+
+The only endpoint accepting `Idempotency-Key`. Also reachable through
+ActionMailer via the `:broadcast` delivery method.
+
+### Templates — 5/5
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/templates` | `Templates#list` |
+| GET | `/api/v1/templates/{id}` | `Templates#get_template` |
+| POST | `/api/v1/templates` | `Templates#create` |
+| PATCH | `/api/v1/templates/{id}` | `Templates#update` |
+| DELETE | `/api/v1/templates/{id}` | `Templates#delete` |
+
+### Segments — 5/5
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/segments` | `Segments#list` |
+| GET | `/api/v1/segments/{id}` | `Segments#get_segment` |
+| POST | `/api/v1/segments` | `Segments#create` |
+| PATCH | `/api/v1/segments/{id}` | `Segments#update` |
+| DELETE | `/api/v1/segments/{id}` | `Segments#delete` |
+
+`get_segment` returns the segment's *matching subscribers*, paginated, and
+recounts on read — it is a query, not a cheap fetch.
+
+### Opt-in forms — 8/8
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/opt_in_forms` | `OptInForms#list` |
+| GET | `/api/v1/opt_in_forms/{id}` | `OptInForms#get_opt_in_form` |
+| POST | `/api/v1/opt_in_forms` | `OptInForms#create` |
+| PATCH | `/api/v1/opt_in_forms/{id}` | `OptInForms#update` |
+| DELETE | `/api/v1/opt_in_forms/{id}` | `OptInForms#delete` |
+| GET | `/api/v1/opt_in_forms/{id}/analytics` | `OptInForms#analytics` |
+| POST | `/api/v1/opt_in_forms/{id}/variants` | `OptInForms#create_variant` |
+| POST | `/api/v1/opt_in_forms/{id}/duplicate` | `OptInForms#duplicate` |
+
+`list` returns main forms only — A/B variants are excluded.
+
+### Email servers — 7/7
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/email_servers` | `EmailServers#list` |
+| GET | `/api/v1/email_servers/{id}` | `EmailServers#get_email_server` |
+| POST | `/api/v1/email_servers` | `EmailServers#create` |
+| PATCH | `/api/v1/email_servers/{id}` | `EmailServers#update` |
+| DELETE | `/api/v1/email_servers/{id}` | `EmailServers#delete` |
+| POST | `/api/v1/email_servers/{id}/test_connection` | `EmailServers#test_connection` |
+| POST | `/api/v1/email_servers/{id}/copy_to_channel` | `EmailServers#copy_to_channel` — admin token |
+
+`update` carries a **credential-redaction guard**: the API returns credential
+fields bullet-masked, and the gem strips values matching that shape out of the
+payload so a naive fetch-modify-save cannot overwrite a real SMTP password with
+`••••••••`. This is behaviour the API does not provide — it is the gem
+protecting you from a data-loss bug.
+
+### Webhook endpoints — 7/7
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/webhook_endpoints` | `WebhookEndpoints#list` |
+| GET | `/api/v1/webhook_endpoints/{id}` | `WebhookEndpoints#get_endpoint` |
+| POST | `/api/v1/webhook_endpoints` | `WebhookEndpoints#create` |
+| PATCH | `/api/v1/webhook_endpoints/{id}` | `WebhookEndpoints#update` |
+| DELETE | `/api/v1/webhook_endpoints/{id}` | `WebhookEndpoints#delete` |
+| POST | `/api/v1/webhook_endpoints/{id}/test` | `WebhookEndpoints#test` |
+| GET | `/api/v1/webhook_endpoints/{id}/deliveries` | `WebhookEndpoints#deliveries` |
+
+The `secret` is returned once, on create, and never again.
+
+### Autopilot — 10/10
+
+AI-generated newsletters. Requires the `autopilot_read` / `autopilot_write`
+token permissions.
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/v1/autopilots` | `Autopilots#list` |
+| GET | `/api/v1/autopilots/{id}` | `Autopilots#get_autopilot` |
+| POST | `/api/v1/autopilots` | `Autopilots#create` |
+| PATCH | `/api/v1/autopilots/{id}` | `Autopilots#update` |
+| DELETE | `/api/v1/autopilots/{id}` | `Autopilots#delete` |
+| POST | `/api/v1/autopilots/{id}/activate` | `Autopilots#activate` |
+| POST | `/api/v1/autopilots/{id}/pause` | `Autopilots#pause` |
+| POST | `/api/v1/autopilots/{id}/deactivate` | `Autopilots#deactivate` |
+| POST | `/api/v1/autopilots/{id}/trigger_run` | `Autopilots#trigger_run` |
+| GET | `/api/v1/autopilots/{id}/runs` | `Autopilots#runs` |
+
+`openrouter_api_key` is never returned — it is encrypted at rest, and `show`
+reports only `api_key_configured`. `update` carries the same **credential
+redaction guard** as email servers: a bullet-masked key is stripped from the
+payload so a fetch-modify-save cannot destroy the stored credential.
+
+`activate` requires an active source, an API key, and a model; it returns 422
+naming the missing prerequisites. `trigger_run` returns 202 — generation is
+asynchronous, so poll `runs`.
+
+### Migration / export — 20/20
+
+Admin tokens only. `broadcast_channel_id` is required on every call; set it once
+on the client and the gem attaches it.
+
+| Method | Path | Gem |
+|---|---|---|
+| GET | `/api/migration/v1/manifest` | `Migration#manifest` |
+| GET | `/api/migration/v1/file_assets/{id}/download` | `Migration#download_file_asset` — raw bytes |
+| GET | `/api/migration/v1/channels` | *(generated)* `Migration#channels` |
+| GET | `/api/migration/v1/subscribers` | *(generated)* `Migration#subscribers` |
+| GET | `/api/migration/v1/templates` | *(generated)* `Migration#templates` |
+| GET | `/api/migration/v1/segments` | *(generated)* `Migration#segments` |
+| GET | `/api/migration/v1/sequences` | *(generated)* `Migration#sequences` |
+| GET | `/api/migration/v1/email_servers` | *(generated)* `Migration#email_servers` |
+| GET | `/api/migration/v1/opt_in_forms` | *(generated)* `Migration#opt_in_forms` |
+| GET | `/api/migration/v1/broadcasts` | *(generated)* `Migration#broadcasts` |
+| GET | `/api/migration/v1/outbound_receipts` | *(generated)* `Migration#outbound_receipts` |
+| GET | `/api/migration/v1/webhook_endpoints` | *(generated)* `Migration#webhook_endpoints` |
+| GET | `/api/migration/v1/tokens` | *(generated)* `Migration#tokens` |
+| GET | `/api/migration/v1/suppressions` | *(generated)* `Migration#suppressions` |
+| GET | `/api/migration/v1/tags` | *(generated)* `Migration#tags` |
+| GET | `/api/migration/v1/users` | *(generated)* `Migration#users` |
+| GET | `/api/migration/v1/link_redirects` | *(generated)* `Migration#link_redirects` |
+| GET | `/api/migration/v1/link_clicks` | *(generated)* `Migration#link_clicks` |
+| GET | `/api/migration/v1/subscriber_histories` | *(generated)* `Migration#subscriber_histories` |
+| GET | `/api/migration/v1/file_assets` | *(generated)* `Migration#file_assets` |
+
+`Migration#each_record(:collection)` pages any of them automatically, advancing
+by the page size the **server granted** rather than the one requested (the
+server clamps `limit` to 250).
+
+---
+
+## Transport coverage
+
+Endpoint coverage is the easy half. These are the protocol behaviours the API
+expects a well-behaved client to implement — and where a client can look
+complete while quietly losing information.
+
+| Capability | Status | Gem surface |
+|---|---|---|
+| Bearer auth | ✅ | `api_token:` / `BROADCAST_API_TOKEN` |
+| Explicit host, no default | ✅ | `host:` / `BROADCAST_HOST`, required |
+| `User-Agent` attribution | ✅ | `broadcast-ruby/<version>` |
+| **`warnings` array** | ✅ | `result.warnings`, `warnings_mode:` `:log`/`:raise`/`:ignore` |
+| **`Idempotency-Key`** | ✅ | `transactionals.create(idempotency_key:)` |
+| **`Idempotency-Replayed`** | ✅ | `result.idempotent_replay?` |
+| **Rate-limit headers** | ✅ | `result.rate_limit` — limit, remaining, reset |
+| **429 + `Retry-After`** | ✅ | Retried, bounded by `max_retry_delay` |
+| Retry on 5xx and timeout | ✅ | `retry_attempts`, `retry_delay` |
+| Typed errors | ✅ | 401/403/404/409/422/429/5xx each distinct |
+| Redirect handling | ✅ | Same-host GET follows; writes and cross-host refuse |
+| Raw/text responses | ✅ | `client.skill`, `download_file_asset` |
+| Channel scoping | ✅ | `broadcast_channel_id:`, `with_channel(id) { }` |
+| Debug logging | ✅ | Credentials redacted |
+| Pagination helper | ⚠️ Migration only | `each_record`; v1 endpoints page manually |
+| ActionMailer integration | ✅ | `:broadcast` delivery method + Railtie |
+
+Error mapping in full:
+
+| HTTP | Exception |
+|---|---|
+| 401 | `Broadcast::AuthenticationError` |
+| 403 | `Broadcast::AuthorizationError` |
+| 404 | `Broadcast::NotFoundError` |
+| 409 | `Broadcast::ConflictError` — idempotency replay in flight |
+| 422 | `Broadcast::ValidationError` |
+| 429 | `Broadcast::RateLimitError` — carries `#retry_after` |
+| 5xx | `Broadcast::APIError` |
+| — | `Broadcast::TimeoutError`, `ConfigurationError`, `WarningError`, `DeliveryError` |
+
+---
+
+## Webhook coverage
+
+Inbound webhooks — the app calling you.
+
+| Capability | Status |
+|---|---|
+| HMAC-SHA256 verification (`v1,<base64>`) | ✅ `Webhook.verify` |
+| 5-minute timestamp tolerance | ✅ Replay protection |
+| Constant-time comparison | ✅ `OpenSSL.fixed_length_secure_compare` |
+| Event type constants | ✅ `Webhook::EVENT_TYPES` — 32 values |
+
+Categories: `EMAIL_EVENTS` (8), `SUBSCRIBER_EVENTS` (7), `BROADCAST_EVENTS` (8),
+`SEQUENCE_EVENTS` (7), `SYSTEM_EVENTS` (2).
+
+Not covered: payload deserialisation into typed objects. You get the parsed
+JSON body and dispatch on `type` yourself.
+
+---
+
+## Not in the API at all
+
+These are Broadcast features with no v1 endpoints. **No client can reach them** —
+this is an API gap, not a gem gap, and nothing here is actionable in this repo.
+
+| Feature | Where it lives | Notes |
+|---|---|---|
+| **Autopilot** (AI newsletter generation) | Web UI | Sources, tone samples, runs, scheduling. See below — this one is different. |
+| **Ask AI** | Web UI | Conversations, messages, tool-call approval |
+| **Subscriber imports** | Web UI | CSV/TSV upload, mapping, processing |
+| **CSV exports** | Web UI | Subscribers, broadcasts, activity. `GET /subscribers/export` is a web route |
+| **Bulk operations** | Web UI | Subscriber, template, and file-asset bulk actions; broadcast bulk archive |
+| **Channel management** | Web UI | Creating channels, domain/sender setup, onboarding |
+| **User & permission management** | Web UI | Users, system permissions, per-channel permissions |
+| **Settings** | Web UI | General, AI, DNS checks, ESP integrations, sender details |
+| **Global suppressions** | Web UI + migration export | Read-only via `migration.suppressions`; no v1 CRUD |
+| **File assets** | Web UI + migration export | Read-only via migration; no v1 upload |
+| **Link tracking config** | Web UI | Click data readable via `statistics_links` and migration |
+| **Admin / platform** | Web UI | Admin API tokens, SaaS platform admin |
+| **Confirmation templates & pages** | Partly API | Configurable as template attributes; no dedicated endpoints |
+
+### Autopilot is worth a separate note
+
+The `Token` model already defines **`permission_to_autopilot_read`** and
+**`permission_to_autopilot_write`** — but there is no `api/v1/autopilots`
+controller and zero autopilot routes under `/api`. The permission flags exist
+with nothing behind them.
+
+So an operator can grant an API token "Autopilot" access today and that grant
+does nothing. That is worth either building the endpoints or hiding the
+permission — and it is the most likely next addition to the API surface, which
+makes it the first thing to check when this document goes stale.
+
+---
+
+## Limits of the 100%
+
+The figure means **every operation the router serves has a corresponding gem
+method**. It does not mean the gem is complete. Specifically, it does not measure:
+
+**Parameter completeness.** This is the important one. Resource methods take
+`**attrs` and forward them, so a method covers its endpoint regardless of which
+attributes it knows about. The v2.19 additions — template `confirmation_page_settings`,
+opt-in-form `welcome_email_template_id`, admin-only `confirmed_at` on subscriber
+create — all "passed through" at 100% coverage while being entirely undocumented.
+They are documented now, but the metric would not have caught them and will not
+catch the next ones. Closing this needs response schemas in `openapi/overlay.yml`
+and a parameter-level check.
+
+**Response shapes.** The gem returns parsed JSON. It does not model or validate
+response bodies, so an API field that changes type is invisible to it.
+
+**Semantics.** Coverage says a method issues the right request, not that it
+handles the endpoint's behaviour correctly. `list` returning only main opt-in
+forms, or `get_segment` recounting on read, are documented in comments — not
+enforced by anything.
+
+**Live correctness.** The suite mocks HTTP. `rake test_live` exercises a real
+instance and is **not** part of the coverage figure; it needs a token and host.
+
+### Known unevenness
+
+- **Pagination.** `Migration#each_record` auto-pages. The v1 endpoints do not
+  have an equivalent — callers loop on `page:` themselves.
+- **Naming.** Getters are inconsistent: `get_broadcast`, `get_segment`,
+  `get_endpoint`, `get_opt_in_form`, `get_email_server`, `get_template`,
+  `get_transactional`, `get_step`. `Broadcast` collides with the top-level
+  module name, which is what forced the prefix originally; the rest followed for
+  symmetry. Worth settling before other SDKs copy the pattern.
+- **Steps live on `Sequences`.** There is no `client.sequence_steps`; step
+  methods hang off the sequences resource, matching the nested routes.
+
+---
+
+## Keeping this current
+
+This file is written by hand from generated data. Regenerate the underlying
+numbers with:
+
+```bash
+# in the broadcast repo
+bin/rails openapi:generate
+bin/rails "openapi:coverage[../broadcast-ruby]"
+```
+
+If `openapi:check` fails in CI, the API changed and this document is stale.
+Cross-language plans live in [SDK-TODO.md](SDK-TODO.md); the v0.3.0 work log is
+in [TODO.md](TODO.md).

data/lib/broadcast/client.rb

@@ -1,29 +1,65 @@
 # frozen_string_literal: true
 
-require 'net/http'
-require 'json'
-require 'uri'
-
 module Broadcast
   class Client
+    CHANNEL_OVERRIDE_KEY = :__broadcast_ruby_channel_override
+
     attr_reader :config
 
     def initialize(**settings)
       @config = Configuration.new
       settings.each { |k, v| @config.public_send(:"#{k}=", v) }
       @config.validate!
+      @connection = Connection.new(@config)
+    end
+
+    # --- Channel scoping (admin/system tokens) ---
+
+    # Run a block with a temporary broadcast_channel_id override that will be
+    # auto-included on every request inside the block. Useful for admin/system
+    # tokens that need to scope each call to a specific channel.
+    #
+    #   client.with_channel(123) do
+    #     client.email_servers.list
+    #   end
+    def with_channel(broadcast_channel_id)
+      key = channel_override_key
+      previous = Thread.current[key]
+      Thread.current[key] = broadcast_channel_id
+      yield self
+    ensure
+      Thread.current[key] = previous
     end
 
-    # --- Transactional email ---
+    # --- Transactional email (convenience shims) ---
 
-    def send_email(to:, subject:, body:, reply_to: nil)
-      payload = { to: to, subject: subject, body: body }
-      payload[:reply_to] = reply_to if reply_to
-      request(:post, '/api/v1/transactionals.json', payload)
+    # Thin convenience wrapper around `transactionals.create`. Use
+    # `client.transactionals.create` directly for template_id, double_opt_in,
+    # preheader, idempotency_key, and other advanced options.
+    def send_email(to:, subject: nil, body: nil, reply_to: nil)
+      transactionals.create(to: to, subject: subject, body: body, reply_to: reply_to)
     end
 
     def get_email(id)
-      request(:get, "/api/v1/transactionals/#{id}.json")
+      transactionals.get_transactional(id)
+    end
+
+    # --- Discovery (convenience shims) ---
+
+    def whoami
+      discovery.whoami
+    end
+
+    def status
+      discovery.status
+    end
+
+    def prime
+      discovery.prime
+    end
+
+    def skill
+      discovery.skill
     end
 
     # --- Resource sub-clients ---
@@ -52,124 +88,59 @@ module Broadcast
       @webhook_endpoints ||= Resources::WebhookEndpoints.new(self)
     end
 
-    # @api private
-    def request(method, path, body_or_params = nil)
-      uri = URI("#{@config.host}#{path}")
+    def transactionals
+      @transactionals ||= Resources::Transactionals.new(self)
+    end
 
-      if method == :get && body_or_params.is_a?(Hash) && body_or_params.any?
-        uri.query = URI.encode_www_form(flatten_params(body_or_params))
-      end
+    def opt_in_forms
+      @opt_in_forms ||= Resources::OptInForms.new(self)
+    end
 
-      retry_with_backoff do
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = uri.scheme == 'https'
-        http.open_timeout = @config.open_timeout
-        http.read_timeout = @config.timeout
+    def email_servers
+      @email_servers ||= Resources::EmailServers.new(self)
+    end
 
-        req = build_request(method, uri)
-        req.body = body_or_params.to_json if method != :get && body_or_params.is_a?(Hash) && body_or_params.any?
+    def autopilots
+      @autopilots ||= Resources::Autopilots.new(self)
+    end
 
-        log_request(req, method == :get ? nil : body_or_params) if @config.debug
+    def discovery
+      @discovery ||= Resources::Discovery.new(self)
+    end
+
+    # Read-only export endpoints under /api/migration/v1. Requires an admin
+    # (system) API token.
+    def migration
+      @migration ||= Resources::Migration.new(self)
+    end
 
-        response = http.request(req)
-        log_response(response) if @config.debug
-        handle_response(response)
-      end
-    rescue Net::OpenTimeout, Net::ReadTimeout => e
-      raise Broadcast::TimeoutError, "Request timeout: #{e.message}"
+    # @api private
+    def request(method, path, body_or_params = nil, headers: {}, raw: false)
+      payload = inject_channel_scope(body_or_params)
+      @connection.request(method, path, payload, headers: headers, raw: raw)
     end
 
     private
 
-    def build_request(method, uri)
-      klass = case method
-              when :get then Net::HTTP::Get
-              when :post then Net::HTTP::Post
-              when :patch then Net::HTTP::Patch
-              when :delete then Net::HTTP::Delete
-              else raise ArgumentError, "Unsupported HTTP method: #{method}"
-              end
-
-      req = klass.new(uri)
-      req['Authorization'] = "Bearer #{@config.api_token}"
-      req['Content-Type'] = 'application/json'
-      req['User-Agent'] = "broadcast-ruby/#{Broadcast::VERSION}"
-      req
-    end
-
-    def handle_response(response)
-      case response.code.to_i
-      when 200, 201
-        return {} if response.body.nil? || response.body.strip.empty?
-
-        JSON.parse(response.body)
-      when 401
-        raise AuthenticationError, parse_error(response) || 'Authentication failed'
-      when 404
-        raise NotFoundError, parse_error(response) || 'Resource not found'
-      when 422
-        raise ValidationError, parse_error(response) || 'Validation failed'
-      when 429
-        raise RateLimitError, parse_error(response) || 'Rate limit exceeded'
-      when 500, 502, 503, 504
-        raise APIError, parse_error(response) || "Server error (#{response.code})"
-      else
-        raise APIError, parse_error(response) || "Unexpected response: #{response.code}"
-      end
-    end
-
-    def parse_error(response)
-      JSON.parse(response.body)['error']
-    rescue JSON::ParserError
-      nil
-    end
-
-    def retry_with_backoff
-      attempts = 0
-      begin
-        attempts += 1
-        yield
-      rescue Net::OpenTimeout, Net::ReadTimeout
-        raise if attempts >= @config.retry_attempts
-
-        sleep(@config.retry_delay * attempts)
-        retry
-      rescue APIError => e
-        raise unless attempts < @config.retry_attempts && e.message.include?('Server error')
-
-        sleep(@config.retry_delay * attempts)
-        retry
-      end
-    end
-
-    def flatten_params(params)
-      result = []
-      params.each do |key, value|
-        case value
-        when Array
-          value.each { |v| result << ["#{key}[]", v.to_s] }
-        when Hash
-          value.each { |k, v| result << ["#{key}[#{k}]", v.to_s] }
-        when nil
-          next
-        else
-          result << [key.to_s, value.to_s]
-        end
-      end
-      result
-    end
-
-    def log_request(request, body)
-      return unless @config.logger
-
-      @config.logger.debug("[Broadcast] #{request.method} #{request.uri}")
-      @config.logger.debug("[Broadcast] Body: #{body.to_json}") if body.is_a?(Hash) && body.any?
-    end
-
-    def log_response(response)
-      return unless @config.logger
-
-      @config.logger.debug("[Broadcast] Response: #{response.code} #{response.body}")
+    def channel_override_key
+      :"#{CHANNEL_OVERRIDE_KEY}_#{object_id}"
+    end
+
+    def active_channel_id
+      Thread.current[channel_override_key] || @config.broadcast_channel_id
+    end
+
+    # Auto-include broadcast_channel_id in request payload when configured (or
+    # set via with_channel) and not already specified by the caller.
+    def inject_channel_scope(body_or_params)
+      channel_id = active_channel_id
+      return body_or_params if channel_id.nil?
+
+      payload = body_or_params.is_a?(Hash) ? body_or_params.dup : {}
+      return payload if payload[:broadcast_channel_id] || payload['broadcast_channel_id']
+
+      payload[:broadcast_channel_id] = channel_id
+      payload
     end
   end
 end