flodesk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 999226163522bb5f96dd6a3c8dc4465e082c50edb329a9f4ab549ccb00841ef5
+  data.tar.gz: ba0ed925433c53183b33fdce21fa43bea96d14f82e699ff16e5042a14f87bc37
+SHA512:
+  metadata.gz: c39fbbac523b7fead38581e89c47387b68f2a574025d298ce44e6c71db8a36392ab117d9700d6f76263280502594195da793aa6954721fe0519fafeff0b85527
+  data.tar.gz: 1360b3cb89ba5d41ea31345ed79ae3179228242fbfc2f3f281e6b22c79ca8c4455eae298bf057c24aff303d10603ff8e70630c4839a1f0d2d73d30bd712e3f51

data/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+## [0.1.0] - 2026-09-19
+
+Initial release.
+
+> **The public API is unstable until it has been exercised against a live Flodesk
+> account.** Everything here is verified against the vendored API description and
+> WebMock stubs, but only the `401` envelope has been confirmed against the real
+> service. Expect breaking changes in `0.1.x`.
+
+The vendored API description (`spec/fixtures/openapi.json`) was captured
+2026-08-30.
+
+### Added
+
+- `Flodesk::Client` — explicit, frozen, thread-safe. No global configuration, so
+  per-tenant API keys are straightforward.
+- Full coverage of all 26 documented operations across six resources:
+  subscribers, segments, custom fields, workflows, webhooks and campaigns
+  (including the Canva and Studio publishing endpoints).
+- API-key (HTTP Basic) authentication, behind a strategy seam so OAuth2 can be
+  added later without a breaking change.
+- Immutable `Data.define` value objects, each exposing `#to_h` with the raw
+  payload — so a field Flodesk adds is reachable without a gem release.
+- `BatchResult` with explicit partial-failure semantics. `batch_upsert` raises
+  `Flodesk::PartialFailureError` when any record fails, carrying the successes;
+  `raise_on_failure: false` returns the result quietly.
+- Per-endpoint idempotency declarations driving retries. `POST /segments`,
+  `POST /custom-fields`, `POST /webhooks`, `POST /campaigns/canva` and
+  `POST /campaigns/studio` are never retried; the campaign publishing endpoints
+  are never retried even on `429`, because a retry could send a campaign to the
+  entire list twice.
+- One uniform `page:` / `per_page:` interface across every list endpoint,
+  translating to `per_page`, `perPage` or PascalCase filters as each requires.
+- Opt-in `auto_paging_each` returning a lazy `Enumerator`. Not the default,
+  because traversing a large collection can consume the whole rate-limit budget.
+- Webhook handling with **mandatory** verification — Flodesk signs nothing — via
+  either a constant-time token-in-path check or authoritative re-fetch, plus a
+  composed SHA-256 dedupe key since events carry no unique id.
+- Rails integration: `rails g flodesk:install`, a Railtie, `flodesk.request`
+  `ActiveSupport::Notifications` events, and opt-in WebMock test helpers. All
+  loaded conditionally; the gem declares **no runtime dependencies**.
+- PII redaction throughout logging and instrumentation: `email`,
+  `custom_fields` and `optin_ip` never appear, including when an email is
+  embedded in a request path.
+- RBS signatures for the public surface.
+- `subscribers.list(status: :archived)` and `Subscriber#status == :archived` —
+  the seventh `SubscriberRes.status` value.
+- `Segment#segment_type` — `"static"` or `"dynamic"`. Not symbolized: the
+  description documents the two values in prose but declares no enum array.
+- A contract spec that walks the vendored `openapi.json` and fails the build when
+  client coverage drifts from the documented API. It verifies **request bodies**,
+  not just query parameters — a change to a documented body would otherwise sail
+  through green, the client simply ceasing to send a field while every stubbed
+  example still passed. `Subscribers::SUBSCRIBER_FIELDS` is asserted to match
+  `CreateOrUpdateSubscriberItem` exactly, which is what makes rejecting unknown
+  keys safe rather than brittle: a field Flodesk adds fails the build instead of
+  becoming a runtime rejection of a value the API accepts.
+
+### Behavior worth knowing
+
+- `subscribers.upsert` and `batch_upsert` **raise `ArgumentError` on an
+  unrecognized attribute** rather than dropping it. A misspelled `frist_name:`
+  would otherwise vanish silently while the request reported success, leaving the
+  caller believing they had written a field they had not. Batch errors name the
+  offending record by index. Error messages name the rejected key only, never
+  its value.
+- `batch_upsert` validates argument shape before contents: a non-Array, or a
+  record that is not a Hash, raises a named `ArgumentError` rather than a
+  `NoMethodError` from inside the payload builder. Passing a single record
+  instead of an array would otherwise have its *values* parsed as field names.
+- The gem is published as **`flodesk`**, while the repository is named
+  `flodesk-rb`. The Ruby namespace is `Flodesk`. Requests identify themselves as
+  `flodesk/<version>`, or `<app_name> flodesk/<version>` when `app_name:` is
+  given.
+- `campaigns.publish_studio` appeared in the 2026-08-30 specification capture and
+  has not been confirmed against the live API, so the maturity caveat above
+  applies to it in full.
+
+### Notes on the API this wraps
+
+Behaviors the client absorbs, recorded here because they are easy to
+rediscover the hard way:
+
+- `POST /subscribers` is an upsert returning `200` for both creation and update,
+  and never reports which occurred.
+- `POST /subscribers/batch` reports per-record failures inside a `200`.
+- `GET /workflows` spells its page-size parameter `perPage`; `GET /campaigns`
+  uses PascalCase filters while keeping snake_case pagination.
+- `GET /workflows`'s `statuses` filter is comma-separated, not repeated keys, and
+  has its own enum (`active`/`paused`/`draft`) distinct from the subscriber and
+  campaign status enums.
+- `POST /webhooks` requires a `name` field.
+- Custom field values are typed `string` only.
+- Rate-limit responses include `X-Fd-RateLimit-Limit` and `-Remaining` but **no
+  reset header**, so no correct backoff interval is computable.
+- The description declares no error-body schema anywhere; the `{code, message}`
+  envelope was established by probing the live API.
+
+[0.1.0]: https://github.com/mymat-yoga/flodesk-rb/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 mymat.yoga
+
+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

@@ -0,0 +1,351 @@
+# flodesk
+
+A dependency-free Ruby client for the [Flodesk API](https://developers.flodesk.com), built for Rails apps.
+
+Covers all 26 documented operations across subscribers, segments, custom fields, workflows, webhooks and campaigns — and absorbs the API's rough edges so you don't have to think about them:
+
+- **Pagination isn't uniform.** Most endpoints take `per_page`; `GET /workflows` takes `perPage`; `GET /campaigns` takes PascalCase filters. You always pass `page:` and `per_page:`.
+- **Batch upsert reports failure inside a `200`.** A client that treats 2xx as success silently drops subscribers. Here, partial failure raises by default.
+- **Retry safety is per-endpoint, not per-verb.** Most `POST`s are idempotent upserts, but four create records — and one *publishes an email campaign*. A generic "retry POST on 5xx" wrapper can send a campaign to your whole list twice.
+
+## Installation
+
+```ruby
+gem "flodesk"
+```
+
+Requires Ruby 3.2+. No runtime dependencies.
+
+> The gem is `flodesk`; the repository is named `flodesk-rb`. The Ruby namespace
+> is `Flodesk` — there is no `Flodesk::Rb`. The `-rb` suffix is a leftover of how
+> the repository was first generated and appears nowhere in the public API.
+
+## Quick start
+
+```ruby
+client = Flodesk::Client.new(
+  api_key:  ENV.fetch("FLODESK_API_KEY"),
+  app_name: "MyApp (myapp.com)"   # the API asks integrations to identify themselves
+)
+
+client.subscribers.upsert(email: "ada@example.com", first_name: "Ada")
+```
+
+Create and manage API keys at [app.flodesk.com/account/integration/api](https://app.flodesk.com/account/integration/api).
+
+### Rails
+
+```bash
+bin/rails g flodesk:install
+bin/rails credentials:edit   # add: flodesk_api_key: fd_your_key_here
+```
+
+That writes `config/initializers/flodesk.rb` assigning a client to a `FLODESK` constant. The gem holds **no global configuration** — ownership stays visible in your app, and a second Flodesk account is just another `Flodesk::Client.new`. A client is frozen and safe to share across request threads.
+
+## Configuration
+
+```ruby
+Flodesk::Client.new(
+  api_key:       "fd_...",   # required
+  app_name:      "MyApp",    # added to the User-Agent
+  open_timeout:  5,
+  read_timeout:  15,
+  max_retries:   2,          # 0 disables retrying entirely
+  backoff_base:  0.5
+)
+```
+
+## Subscribers
+
+```ruby
+# Create or update. The API returns 200 for both and never says which, so this
+# cannot tell you whether the subscriber was new. Unknown attributes raise
+# rather than being dropped, so a typo surfaces instead of vanishing.
+subscriber = client.subscribers.upsert(
+  email:         "ada@example.com",
+  first_name:    "Ada",
+  segment_ids:   ["seg_123"],       # max 50
+  custom_fields: { "tier" => "gold" },
+  double_optin:  true               # only honored on creation
+)
+
+subscriber.email           # => "ada@example.com"
+subscriber.status          # => :active
+subscriber.active?         # => true
+subscriber.segments.first.name
+subscriber.to_h            # the raw payload, always available
+
+client.subscribers.retrieve("ada@example.com")   # id or email
+client.subscribers.add_to_segments("sub_1", ["seg_123"])
+client.subscribers.remove_from_segments("sub_1", ["seg_123"])
+client.subscribers.unsubscribe("sub_1")
+```
+
+Custom field values are typed `string` throughout the API, so non-string values are coerced (`42` → `"42"`, `true` → `"true"`). `nil` is preserved, because it means "clear this field" rather than "set it to empty".
+
+### Batch upsert
+
+Up to 50 records per request, at 20 requests/minute — an effective ceiling of 1,000 upserts/minute.
+
+The API returns `200` carrying **both** `successes` and `failures`, so `batch_upsert` raises on partial failure by default. The error carries the whole result, so successful records are never lost:
+
+```ruby
+begin
+  client.subscribers.batch_upsert([
+    { email: "ada@example.com" },
+    { email: "not-an-email" }
+  ])
+rescue Flodesk::PartialFailureError => e
+  e.result.successes            # => [Subscriber]
+  e.result.failures.first.code  # => "invalid_email"
+  e.result.failures.first.index # => 1, the position in your input
+  e.result.failed_emails        # ready to retry
+end
+```
+
+Prefer to inspect rather than rescue? Opt out explicitly:
+
+```ruby
+result = client.subscribers.batch_upsert(rows, raise_on_failure: false)
+result.success?   # => false
+result.failures
+```
+
+## Listing and pagination
+
+`list` issues exactly one request and returns a `Page`:
+
+```ruby
+page = client.subscribers.list(page: 2, per_page: 100, status: :active)
+
+page.items          # => [Subscriber]
+page.total_items
+page.more_pages?
+page.each { |s| ... }   # this page only — no further requests
+```
+
+To walk everything, opt in explicitly. This is *not* the behavior of `each`, because traversing a large list can consume your entire 100 requests/minute budget — a cost that should be visible at the call site:
+
+```ruby
+client.subscribers.auto_paging_each do |subscriber|
+  # ...
+end
+
+# Lazy: fetches only what it needs.
+client.subscribers.auto_paging_each.first(10)
+```
+
+## Segments, custom fields, workflows
+
+```ruby
+client.segments.list
+client.segments.retrieve("seg_123")
+client.segments.create(name: "VIPs", color: "#ffeecc")
+client.segments.colors
+
+client.custom_fields.list          # paginated
+client.custom_fields.list_all      # every field, unpaginated
+client.custom_fields.create(label: "Favorite colour")
+
+client.workflows.list(statuses: [:active, :paused])
+client.workflows.add_subscriber("wf_123", email: "ada@example.com")
+client.workflows.remove_subscriber("wf_123", "ada@example.com")
+```
+
+## Campaigns
+
+```ruby
+client.campaigns.list(search: "spring", status: :draft, order_by: "created_at")
+
+client.campaigns.publish_canva(bundle_url: "https://...", title: "Spring")
+client.campaigns.publish_studio(html: "<html>...</html>", title: "Spring")
+```
+
+> **Maturity caveat.** The campaign publishing endpoints (`publish_canva`, `publish_studio`, `canva_design_state`) cannot be safely exercised against a live account during development, so they are covered only by specification-derived stubs and are less battle-tested than the subscriber and segment operations.
+
+> **`publish_canva` and `publish_studio` are never retried** — not on `5xx`, not on a timeout, not even on `429`. They publish an email campaign, and no response code proves the campaign was *not* accepted. A retry could send it to your entire list a second time, which is unrecoverable and visible to every recipient. Failures are surfaced for a human to decide.
+>
+> Both are documented upstream as publishing a *draft*, which is a weaker hazard than an immediate send. The policy deliberately does not lean on that: "draft" is a one-line summary in the API description, not a guarantee, and the mistake it would license cannot be undone.
+
+## Errors
+
+Everything descends from `Flodesk::Error`, so you can rescue broadly or narrowly:
+
+```ruby
+begin
+  client.subscribers.retrieve("nope")
+rescue Flodesk::NotFoundError => e
+  e.status    # => 404
+  e.code      # => "not_found"
+  e.message
+  e.raw_body  # for debugging an unexpected shape
+end
+```
+
+| Class | Cause |
+| --- | --- |
+| `Flodesk::BadRequestError` | `400` — your payload was rejected. Never retried |
+| `Flodesk::AuthenticationError` | `401`/`403` |
+| `Flodesk::NotFoundError` | `404` |
+| `Flodesk::RateLimitError` | `429` |
+| `Flodesk::ServerError` | `5xx` |
+| `Flodesk::TimeoutError` | connect or read timeout |
+| `Flodesk::ConnectionError` | the request never completed |
+| `Flodesk::PartialFailureError` | a batch reported per-record failures |
+
+The API declares no error-body schema anywhere; the `{code, message}` envelope this gem parses was established by probing the live API. Parsing therefore degrades gracefully — an HTML body from an edge proxy still raises a typed error carrying the raw response.
+
+## Rate limits and retries
+
+| Endpoint | Limit |
+| --- | --- |
+| Everything (default) | 100 requests/minute |
+| `POST /subscribers/batch` | 20 requests/minute (≤50 subscribers each) |
+
+Flodesk returns `X-Fd-RateLimit-Limit` and `X-Fd-RateLimit-Remaining` but **no reset header**, so there is no correct wait time to compute. Backoff is exponential with jitter, capped at 60 seconds, and is a documented heuristic — **this gem does not promise to keep you within quota.** Check the observed state if you need to pace a bulk job yourself:
+
+```ruby
+client.rate_limit&.remaining   # => 68
+```
+
+(Rate-limit state is per-thread, since a shared frozen client cannot hold mutable state.)
+
+Which operations get retried:
+
+| Safe to retry | Never retried |
+| --- | --- |
+| `POST /subscribers` (upsert) | `POST /segments` (creates) |
+| `POST /subscribers/batch` (upsert) | `POST /custom-fields` (creates) |
+| `POST .../segments` (idempotent add) | `POST /webhooks` (creates) |
+| `POST .../unsubscribe` (terminal state) | `POST /campaigns/canva` (**publishes**) |
+| `POST /workflows/.../subscribers` | `POST /campaigns/studio` (**publishes**) |
+| every `GET`, `PUT`, `DELETE` | |
+
+## Webhooks
+
+> **Flodesk does not sign webhooks.** The API description declares `security: []` on all three events — there is no signature header to verify. Anyone who learns your callback URL can forge a `subscriber.created` event.
+
+Because of that, **verification is mandatory**: constructing a handler without choosing a strategy raises rather than defaulting to trust.
+
+### Strategy 1 — token in the callback path
+
+Cheap, no extra API call.
+
+```ruby
+# One-time: generate and store a token, then register the webhook.
+token = Flodesk::Webhooks::Handler.generate_token
+
+client.webhooks.create(
+  name:     "My app",
+  post_url: "https://app.example.com/flodesk/#{token}",
+  events:   ["subscriber.created"]
+)
+```
+
+```ruby
+# config/routes.rb
+post "/flodesk/:token", to: "flodesk_webhooks#create"
+
+class FlodeskWebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  HANDLER = Flodesk::Webhooks::Handler.new(
+    token: Rails.application.credentials.flodesk_webhook_token
+  )
+
+  def create
+    status, _headers, body = HANDLER.respond(
+      body:     request.raw_post,
+      token:    params[:token],
+      on_error: ->(e) { Rails.logger.error("flodesk webhook failed: #{e.class}") }
+    ) do |event|
+      SyncSubscriberJob.perform_later(event.subscriber.id) unless seen?(event.dedupe_key)
+    end
+
+    render plain: body.join, status: status
+  end
+end
+```
+
+⚠️ **The token appears in your logs.** It is a path segment, so it lands in Rails request logs and your web server's access logs. Filter or silence that route before deploying, or use strategy 2 if you'd rather not put a secret in a URL at all.
+
+### Strategy 2 — re-fetch (strongest)
+
+Treats the payload as an untrusted *hint*: takes only the subscriber id and reads the authoritative record back from the API. Forgery-proof, but costs one API call per event against your 100/minute budget.
+
+```ruby
+HANDLER = Flodesk::Webhooks::Handler.new(verify: :refetch, client: FLODESK)
+
+event = HANDLER.call(body: request.raw_post)
+event.subscriber.email   # from the API, not from the payload
+```
+
+IP allowlisting is not an option — Flodesk publishes no ranges.
+
+### Replay protection is yours
+
+The event schemas define **no unique event id**, so the gem exposes a composed, SHA-256 dedupe key and leaves storage to you — only your app has a database:
+
+```ruby
+event.dedupe_key   # stable across identical deliveries
+event.known?       # false for an event name the gem doesn't recognize yet
+event.to_h         # raw payload, so a new Flodesk event stays usable
+```
+
+Respond with any 2xx to acknowledge. `#respond` maps failures to non-2xx (401 unverified, 400 unparseable, 500 if your block raises) so Flodesk retries rather than considering the event delivered.
+
+### PII in webhook payloads
+
+Events embed `email` **and** `optin_ip`. The gem never logs payload contents, redacts sensitive fields from instrumentation, and keeps PII out of `Event#inspect` — but what your own handler logs is up to you.
+
+## Instrumentation
+
+When ActiveSupport is present, every request attempt emits `flodesk.request`:
+
+```ruby
+ActiveSupport::Notifications.subscribe("flodesk.request") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  event.payload
+  # => { method: "GET", endpoint: "/subscribers/[REDACTED]", status: 200,
+  #      duration: 0.08, attempt: 1, rate_limit_remaining: 68 }
+end
+```
+
+One event per *attempt*, so retries are visible. Payloads carry no request body, no response body, no API key, and any email embedded in a path is redacted.
+
+## Testing
+
+```ruby
+require "flodesk/test_helpers"
+
+RSpec.configure { |c| c.include Flodesk::TestHelpers }
+
+stub_flodesk_upsert(email: "ada@example.com")
+stub_flodesk_error(:get, "/subscribers/nope", status: 404)
+stub_flodesk_batch(failures: [flodesk_batch_failure(index: 1)])
+```
+
+Fixture payloads follow the API description rather than whatever your code expects, so a stub can't drift into hiding a broken integration.
+
+## What this gem does not do
+
+- **OAuth2 / partner integrations.** API-key auth only. The OAuth2 flow needs token storage, expiry, and single-use refresh-token rotation whose concurrent-refresh race requires locking — a subsystem, not a feature. An auth seam is in place so it can be added without a breaking change.
+- **ActiveRecord-style persistence.** No `save!`, dirty tracking, or lazy associations. `POST /subscribers` is upsert-only and never reports create-vs-update, so those semantics would be fiction, and lazy associations would hide N+1 HTTP calls.
+- **Code generation.** The OpenAPI description is vendored as a *test oracle* instead: the suite asserts every documented operation has a client method, that declared parameters are sent, and that every documented status maps to an error class. Dropping in a newer spec fails the build when Flodesk adds an endpoint.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+bundle exec rbs -I sig validate
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/mymat-yoga/flodesk-rb>.
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/flodesk/auth.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # Authentication strategies.
+  #
+  # Only API-key (HTTP Basic) auth is implemented. This seam exists so OAuth2
+  # bearer tokens can be added later without changing Connection: partner
+  # integrations need an authorization-code flow with token storage, expiry, and
+  # single-use refresh-token rotation, which is a subsystem rather than a
+  # feature and is deliberately out of scope for v1.
+  module Auth
+    # Flodesk expects the API key as the HTTP Basic username with an empty
+    # password.
+    class ApiKey
+      def initialize(api_key)
+        @api_key = api_key
+        freeze
+      end
+
+      def apply(request)
+        request.basic_auth(@api_key, "")
+        request
+      end
+
+      # Never interpolate the key into logs or inspect output.
+      def inspect
+        "#<#{self.class.name} api_key=[REDACTED]>"
+      end
+      alias to_s inspect
+    end
+  end
+end

data/lib/flodesk/client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # Entry point to the Flodesk API.
+  #
+  #   client = Flodesk::Client.new(
+  #     api_key:  ENV.fetch("FLODESK_API_KEY"),
+  #     app_name: "MyApp (myapp.com)"
+  #   )
+  #   client.subscribers.upsert(email: "a@b.com")
+  #
+  # There is deliberately no global configuration: per-tenant API keys stay
+  # trivial, and no process-wide state can leak between tests. Instances are
+  # frozen at construction, so a client assigned to a constant is safe to share
+  # across request threads.
+  class Client
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 15
+    DEFAULT_MAX_RETRIES = 2
+    DEFAULT_BACKOFF_BASE = 0.5
+
+    attr_reader :api_key, :app_name, :base_url, :open_timeout, :read_timeout,
+                :max_retries, :backoff_base, :auth,
+                :subscribers, :segments, :custom_fields, :workflows, :webhooks, :campaigns
+
+    def initialize(api_key: nil, app_name: nil, base_url: DEFAULT_BASE_URL,
+                   open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES, backoff_base: DEFAULT_BACKOFF_BASE)
+      # Validate at construction rather than on first request, so a
+      # misconfigured initializer fails at boot instead of in a background job.
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.to_s.strip.empty?
+      raise ArgumentError, "max_retries must be >= 0" if max_retries.negative?
+
+      @api_key = api_key.to_s.dup.freeze
+      @app_name = app_name.nil? ? nil : app_name.to_s.dup.freeze
+      @base_url = base_url.to_s.sub(%r{/+\z}, "").dup.freeze
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @max_retries = max_retries
+      @backoff_base = backoff_base
+      @auth = Auth::ApiKey.new(@api_key)
+      @connection = Connection.new(self)
+
+      build_resources
+      freeze
+    end
+
+    # Flodesk's documentation asks integrations to identify themselves.
+    def user_agent
+      [@app_name, "flodesk/#{VERSION}"].compact.join(" ")
+    end
+
+    # Rate-limit state from this thread's most recent request, or nil.
+    # Only `remaining` is actionable: the API sends no reset header.
+    def rate_limit
+      RateLimit.last(self)
+    end
+
+    # @api private
+    def request(...)
+      @connection.request(...)
+    end
+
+    # Never leak the API key through inspect, which Rails prints in consoles and
+    # error pages.
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect} api_key=[REDACTED]>"
+    end
+    alias to_s inspect
+
+    private
+
+    # Built eagerly rather than memoized lazily: these are tiny, and a frozen
+    # client shared across threads must not mutate a memo hash concurrently.
+    def build_resources
+      @subscribers = Resources::Subscribers.new(self)
+      @segments = Resources::Segments.new(self)
+      @custom_fields = Resources::CustomFields.new(self)
+      @workflows = Resources::Workflows.new(self)
+      @webhooks = Resources::Webhooks.new(self)
+      @campaigns = Resources::Campaigns.new(self)
+    end
+  end
+end

data/lib/flodesk/coercion.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Flodesk
+  # Turns raw JSON values into useful Ruby ones.
+  #
+  # Every coercion here passes unrecognized input through unchanged rather than
+  # raising. Flodesk can add an enum member or change a format at any time, and
+  # a client that raises on an unfamiliar value would break working code for a
+  # change that does not actually affect the caller.
+  module Coercion
+    module_function
+
+    # Converts a documented enum value to a Symbol. Values outside `allowed`
+    # are returned as-is, so a newly introduced Flodesk value cannot break an
+    # existing caller.
+    def enum(value, allowed)
+      return nil if value.nil?
+
+      allowed.include?(value.to_s) ? value.to_s.to_sym : value
+    end
+
+    # Parses an ISO 8601 timestamp to a Time, passing unparseable input through.
+    def time(value)
+      return nil if value.nil?
+      return value unless value.is_a?(String)
+
+      begin
+        Time.iso8601(value)
+      rescue ArgumentError
+        value
+      end
+    end
+
+    # Builds an array of value objects, tolerating a missing or empty list.
+    def array_of(klass, value)
+      return [] unless value.is_a?(Array)
+
+      value.filter_map { |item| klass.from(item) }.freeze
+    end
+
+    # Custom field values are typed `string` throughout the API, so keys and
+    # values pass through intact.
+    def string_hash(value)
+      return {} unless value.is_a?(Hash)
+
+      snapshot(value)
+    end
+
+    # An immutable copy of a payload.
+    #
+    # Copied rather than frozen in place: `.from` is public, so freezing the
+    # argument would be a side effect on data the caller still owns and could
+    # break code that reuses the hash afterwards. The copy also means a later
+    # caller mutation cannot change what the value object reports.
+    #
+    # Recursive, so nested hashes and arrays are copied and frozen too: a
+    # top-level-only copy would still hand back references the caller could
+    # mutate underneath a supposedly immutable object.
+    def snapshot(value)
+      case value
+      when Hash then value.transform_values { |v| snapshot(v) }.freeze
+      when Array then value.map { |v| snapshot(v) }.freeze
+      else value
+      end
+    end
+  end
+end