kit-rb 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cae15a3c1ed91dc15b4e8e6046c4b00c851f0abd3a0bba1e3e65f0c75dec5b5e
-  data.tar.gz: e9f0b1a56b24687b3e6bb0fdc30d1f6d3f20f3b7679b9ffa6ebffdd17f5569ad
+  metadata.gz: d8a032593d0a6e493c45d6d0bb84bd540b0dc7e61fd596ed1b4048b1b7d44d66
+  data.tar.gz: 2e0616764a8ca5b0f9fb64114dd5d2d0c2c5141fa2a5e057c1a4d39d423a8e90
 SHA512:
-  metadata.gz: a535e23e3f337c84e57bd89833486efc32f95231f3f9a5a5804ecf6bae99c009c9780d3120e6de9062c4ef289871a8971f214d98d923767fe0c5324e1de4f372
-  data.tar.gz: 39638ca088dc6f40886566d4515635b83b713597f3d8e480da9444d60cd8c19df1449aceed45a04ba53e94544de2f7728e2c0395687f5be170dd27579dcd6133
+  metadata.gz: 8de55860a7da6d89e4488d94999e106d291bcfde45e3523b740d25b1861b78b7eccea1de82280b80b22288d3cdb7447185dc5b94f45add55a44447bc5f998bba
+  data.tar.gz: 5b80309f71b11d1c74ec5b7d1332c910d10fab5a7690608bb78f0dfa564247d148c1a0a67e78e8fcf2b2adad889248157958dbf07116f445ed3619ef11287151

data/CHANGELOG.md

@@ -6,6 +6,42 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-09
+
+### Added
+- `require "kit/testing"`: envelope builders for consumer specs, built from
+  Kit's documented example responses. `Kit::Testing.response(operation,
+  http_status:, **overrides)` for any of the 83 operations (`Kit::Testing::OPERATIONS`,
+  named `<resource>_<method>`), `attributes` (the bare object), `list_json`
+  (a cursor page from rows or a count), `pagination_json`, `error_json`, and
+  one `<object>_json` per envelope (`subscriber_json`, `tag_json`,
+  `account_json`, ...). Overrides must be fields Kit documents for that
+  envelope. Fixtures are generated by `rake testing:fixtures` from the vendored
+  OpenAPI document and pinned by a contract test. Not loaded by `kit-rb`. (#14)
+- `Kit::Testing` typed factories: one `<object>` per envelope builder
+  (`Kit::Testing.subscriber(id: 1)` → `Kit::Objects::Subscriber`, `tag`,
+  `account`, ...), parsed by the same `Kit::Objects` class the resource uses,
+  plus `account_info` (the whole GET /v4/account result), `oauth_token`
+  (`Kit::OAuth::Token` with a working 48 h expiry) and `tagged_subscriber`
+  (`upsert_and_tag`'s result). Overrides are validated like the builders'.
+  Loading `kit/testing` no longer needs http.rb. (#14)
+- `Kit::Testing.stub(operation, http_status:, **path_params_and_overrides)`,
+  `stub_error(operation, status, *messages)`, `stub_rate_limited(operation,
+  retry_after:)` and `url_for(operation, **path_params)`: WebMock stubs by
+  operation name, built from the same documented examples — path params by
+  name, percent-encoded exactly as the client sends them (one that is also a
+  response field, like `id:`, shapes the body too; on a list, every row),
+  unspecified ones and any query string match, `http_status:` selects the
+  status-specific documented body, 204 operations answer with no body. WebMock is required by the consumer, not by this gem; a clear
+  `ConfigurationError` says so when it is absent. (#14)
+- `instrumenter:` and `logger:` on `Kit::Client` / `Kit::Configuration`. The
+  instrumenter receives one `"request.kit"` event per HTTP attempt through
+  `instrument(name, payload) { }` (`ActiveSupport::Notifications` compatible,
+  no Rails dependency) with `method`, `path`, `status`, `duration`, `retries`,
+  `retry_after` and `error`; never the query string, body or a header value.
+  `logger:` writes the same payload as one debug line per attempt. Both may be
+  given. (#13)
+
 ## [0.4.0] - 2026-09-09
 
 ### Added
@@ -199,7 +235,8 @@ vertical slice. Not yet feature-complete — resources land in 0.1.0 per docs/DE
   429/5xx retry with backoff.
 - RBS signatures for the public surface.
 
-[Unreleased]: https://github.com/linyiru/kit-rb/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/linyiru/kit-rb/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/linyiru/kit-rb/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/linyiru/kit-rb/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/linyiru/kit-rb/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/linyiru/kit-rb/compare/v0.2.0...v0.3.0

data/README.md

@@ -75,6 +75,33 @@ A 429 is retried for every request (with `Retry-After`, capped at
 retried only for idempotent verbs, so a POST is never replayed after those.
 Credentials are masked in `#inspect`.
 
+### Instrumentation
+
+Pass `instrumenter:` to observe every HTTP attempt (Sentry breadcrumbs,
+per-request timing), or `logger:` for one debug line each:
+
+```ruby
+client = Kit::Client.new(api_key: key, instrumenter: ActiveSupport::Notifications)
+ActiveSupport::Notifications.subscribe("request.kit") do |*, payload|
+  Sentry.add_breadcrumb(Sentry::Breadcrumb.new(category: "kit", data: payload))
+end
+
+client = Kit::Client.new(api_key: key, logger: Rails.logger)
+# D, kit GET /v4/account status=429 duration=0.212s retries=0 retry_after=7 error=Kit::RateLimitError
+# D, kit GET /v4/account status=200 duration=0.180s retries=1
+```
+
+The interface is `ActiveSupport::Notifications`' (`instrument(name, payload) { }`)
+but the gem has no Rails dependency: any object with that method works. One
+`"request.kit"` event is emitted per attempt, so a retried request shows each
+attempt, with `method`, `path`, `status` (nil when no response arrived),
+`duration` (seconds), `retries`, `retry_after` (on a 429) and `error` (the Kit
+error class name). The payload never contains the query string, the body, or
+any header value, so no credential or subscriber email can reach a log — and a
+failed attempt is reported through `error`, not by raising inside the
+instrumenter, so `ActiveSupport::Notifications` never attaches the exception
+(with its response body) to the payload.
+
 ### Background jobs
 
 The built-in retry sleeps on the calling thread, which is right for a script
@@ -284,7 +311,58 @@ produces. A transport error means no response was received, not that the request
 was not processed: a timed-out `refresh` may already have consumed the refresh
 token (documented as single-use), so treat retrying it as your own decision.
 
-## Testing
+## Testing your integration
+
+`require "kit/testing"` (not loaded by `kit-rb` itself; no test-framework
+dependency) builds response bodies from Kit's own documented examples, so a
+consumer spec reads as "the upsert succeeds" instead of a hand-written envelope
+that drifts when a field changes:
+
+```ruby
+require "kit/testing"
+
+Kit::Testing.subscriber_json(id: 500, email_address: "ada@example.com")
+# => { "subscriber" => { "id" => 500, "email_address" => "ada@example.com", "state" => "active", ... } }
+Kit::Testing.tag_json(name: "vip")                       # { "tag" => {...} }
+Kit::Testing.account_json(plan_type: "free", name: "")   # { "user" => {...}, "account" => {...} }
+Kit::Testing.error_json("The API key is invalid")        # { "errors" => [...] }
+
+Kit::Testing.response(:tags_create, http_status: 201, name: "vip")        # any operation, by name
+Kit::Testing.list_json(:subscribers_list, [{ id: 1 }, { id: 2 }], has_next_page: true, end_cursor: "E")
+Kit::Testing.attributes(:subscribers_get, first_name: "Ada")              # the bare object, for Objects::Subscriber.from
+
+# With WebMock loaded, stub a whole operation by name (path params by name — one
+# that is also a response field, like id:, shapes the body too; any query string
+# matches; returns WebMock's stub for .with / have_been_requested):
+Kit::Testing.stub(:subscribers_create, id: 500)
+Kit::Testing.stub(:tags_tag_subscriber, tag_id: 7, id: 500)
+Kit::Testing.stub(:tags_list, items: [{ name: "vip" }], has_next_page: true)
+Kit::Testing.stub_error(:account_get, 401, "The API key is invalid")
+Kit::Testing.stub_rate_limited(:subscribers_create, retry_after: 7)
+expect(a_request(:post, Kit::Testing.url_for(:tags_tag_subscriber, tag_id: 7, id: 500))).to have_been_made
+
+# Typed values for instance_double returns and unit tests — the same examples,
+# parsed by the same Kit::Objects classes the client uses:
+Kit::Testing.subscriber(id: 500, email_address: "ada@example.com")  # => Kit::Objects::Subscriber
+Kit::Testing.account_info(plan_type: "free", user: { email: "owner@example.com" })
+Kit::Testing.oauth_token(created_at: Time.now.to_i)                  # => Kit::OAuth::Token, 48 h expiry
+Kit::Testing.tagged_subscriber(tag_names: ["vip", "beta"])           # upsert_and_tag's result
+allow(kit).to receive(:subscribers).and_return(instance_double(Kit::Resources::Subscribers, get: Kit::Testing.subscriber))
+```
+
+Operations are named `<resource>_<method>` after the client method
+(`Kit::Testing::OPERATIONS`, 83 of them); `http_status:` picks among the 2xx
+codes Kit documents for one (`status:` stays free for the field of that name on
+posts, purchases, broadcasts and webhook endpoints). An override that is not a documented field of the
+response type (`Kit::Testing::TYPES` disambiguates envelopes such as `"stats"`
+that wrap different objects) raises `ArgumentError`, so a typo — or a field of
+the wrong object — cannot build a response the real API would never send. The fixtures are generated from the vendored OpenAPI
+document's examples (`rake testing:fixtures`) and a contract test fails when
+they, the operation registry, or the document drift apart. `require "kit/testing"` loads only the
+value objects, not http.rb, so it works wherever the gem's runtime dependencies
+are absent.
+
+## Testing this gem
 
 The suite is layered:
 

data/Rakefile

@@ -25,6 +25,15 @@ namespace :contract do
   end
 end
 
+namespace :testing do
+  desc "Regenerate lib/kit/testing/fixtures.json from the registry + OpenAPI examples"
+  task :fixtures do
+    require_relative "spec/support/testing_fixtures"
+    TestingFixtures.write
+    puts "Wrote #{TestingFixtures::PATH} (#{Kit::Testing::OPERATIONS.size} operations)"
+  end
+end
+
 desc "Live read-only smoke test against the real API (needs KIT_API_KEY)"
 task :smoke do
   require_relative "spec/support/smoke"

data/lib/kit/configuration.rb

@@ -12,15 +12,21 @@ module Kit
   # differs from the token it was given, another process refreshed first and
   # it should return the persisted token without calling Kit. Errors it raises
   # propagate untouched. A 403 is never renewed: that is scope, not expiry.
+  #
+  # `instrumenter:` receives one "request.kit" event per HTTP attempt through
+  # `instrument(name, payload) { }` (ActiveSupport::Notifications compatible);
+  # `logger:` logs the same payload at debug level. See Kit::Instrumentation.
   class Configuration
     attr_reader :auth, :base_url, :open_timeout, :read_timeout, :write_timeout,
-                :max_retries, :retry_backoff, :max_backoff, :renew
+                :max_retries, :retry_backoff, :max_backoff, :renew, :instrumenter
 
     def initialize(api_key: nil, access_token: nil, base_url: DEFAULT_BASE_URL,
                    open_timeout: 10, read_timeout: 30, write_timeout: 30,
-                   max_retries: 2, retry_backoff: 0.5, max_backoff: 30, renew: nil)
+                   max_retries: 2, retry_backoff: 0.5, max_backoff: 30, renew: nil,
+                   instrumenter: nil, logger: nil)
       @auth = build_auth(api_key, access_token)
       @renew = validate_renew(renew)
+      @instrumenter = Instrumentation.build(instrumenter: instrumenter, logger: logger)
       @base_url = base_url
       @open_timeout = open_timeout
       @read_timeout = read_timeout

data/lib/kit/connection.rb

@@ -56,8 +56,10 @@ module Kit
       attempt = 0
       renewed = false
       begin
-        used = renewable_token
-        handle(perform(method, path, params, body, used), method, path)
+        # Snapshot the token this attempt is sent with (renewal on), so a 401 is
+        # attributed to it rather than to whatever another thread installs since.
+        used = @config.renew && @config.auth.access_token
+        attempt_request(method, path, params, body, token: used, attempt: attempt, renewed: renewed)
       rescue *RETRYABLE => e
         attempt += 1
         raise if attempt > @config.max_retries || !retryable?(method, e)
@@ -84,20 +86,12 @@ module Kit
       error.is_a?(RateLimitError) || IDEMPOTENT.include?(method)
     end
 
-    # The access token this request will be sent with, when renewal is on (nil
-    # otherwise): snapshotted so the 401 is attributed to the token that
-    # earned it, not to whatever another thread has installed since.
-    def renewable_token
-      @config.renew && @config.auth.access_token
-    end
-
-    # Answers a 401 on `used`. Returns true when the request should be retried:
-    # either another thread already installed a newer token (use it, do not
-    # renew again), or config.renew returned a replacement. False when there
-    # is no callable or it answered nil (cannot renew) — unless a newer token
-    # arrived while it was deciding, which is still worth a retry. The
-    # replacement is installed compare-and-swap against `used`, so a renewal
-    # that completes after a newer token was installed does not roll it back.
+    # Answers a 401 on `used`. True when the request should be retried: another
+    # thread already installed a newer token (use it, do not renew again), or
+    # config.renew returned a replacement. False when there is no callable or
+    # it answered nil — unless a newer token arrived meanwhile, still worth a
+    # retry. The replacement is installed compare-and-swap against `used`, so
+    # a renewal that completes after a newer token cannot roll it back.
     def renew_token?(used)
       renew = @config.renew
       return false unless renew
@@ -112,8 +106,21 @@ module Kit
       true
     end
 
+    # One HTTP attempt, instrumented (see Instrumentation): perform + handle.
+    # `attempt` is the retry budget (429/5xx/transport only); the renewal retry
+    # does not consume it but is still an earlier attempt, so it is reported.
+    def attempt_request(method, path, params, body, token:, attempt:, renewed:)
+      retries = attempt + (renewed ? 1 : 0)
+      Instrumentation.around(@config.instrumenter, method, path, retries) do
+        handle(perform(method, path, params, body, token), method, path)
+      end
+    end
+
+    # The auth header is added per request as a new immutable http.rb chain —
+    # for the given token snapshot, or the credential's current header — so a
+    # renewed token is used without rebuilding @client.
     def perform(method, path, params, body, token = nil)
-      authed_client(token).request(method, "#{@config.base_url}#{path}", params: params, json: body)
+      authed(token).request(method, "#{@config.base_url}#{path}", params: params, json: body)
     rescue HTTP::TimeoutError => e
       raise TimeoutError, "#{method.to_s.upcase} #{path} timed out: #{e.message}"
     rescue HTTP::ConnectionError => e
@@ -122,12 +129,7 @@ module Kit
       raise TransportError, "#{method.to_s.upcase} #{path} failed in transport: #{e.message}"
     end
 
-    # The shared client plus the auth header (a new immutable chain each time,
-    # so a renewed token is used without rebuilding @client) — for the given
-    # OAuth token snapshot, or the credential's current header.
-    def authed_client(token = nil)
-      @client.headers(token ? @config.auth.headers_for(token) : @config.auth.headers)
-    end
+    def authed(token) = @client.headers(token ? @config.auth.headers_for(token) : @config.auth.headers)
 
     def default_headers
       {

data/lib/kit/instrumentation.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Kit
+  # Observability for requests. Configuration#instrumenter receives one event
+  # per HTTP round-trip (so a retried request produces one event per attempt):
+  #
+  #   instrumenter.instrument("request.kit", payload) { ... }
+  #
+  # The interface is ActiveSupport::Notifications' — pass
+  # `ActiveSupport::Notifications` itself in a Rails app — but the gem has no
+  # Rails dependency: anything responding to `instrument(name, payload) { }`
+  # works. The payload is filled in as the request runs (mutated in place, as
+  # ActiveSupport does), so subscribers see the final values:
+  #
+  #   method:      :get, :post, ...
+  #   path:        "/v4/subscribers/42" — never the query string (it can carry
+  #                an email address) and never the body
+  #   status:      Integer, or nil when no response was received
+  #   duration:    seconds, Float
+  #   retries:     how many earlier attempts this request has made (0 = first)
+  #   retry_after: the parsed Retry-After on a 429, else nil
+  #   error:       the Kit error class name when the attempt failed, else nil
+  #
+  # No header or credential value is ever included; Auth::Credential.mask is
+  # for inspect output, not for payloads, which simply omit secrets.
+  module Instrumentation
+    EVENT = "request.kit"
+
+    # Runs one HTTP attempt inside an instrumenter event, filling the payload
+    # in as it completes (including on failure) and re-raising. `block` returns
+    # [status, body]. With no instrumenter this is a plain yield.
+    #
+    # A failure is captured inside the block and re-raised only after
+    # `instrument` has returned: ActiveSupport::Notifications would otherwise
+    # rescue it and add `:exception` / `:exception_object` to this very
+    # payload — the latter a Kit::APIError still holding the response body —
+    # which a subscriber forwarding the payload wholesale would then leak.
+    def self.around(instrumenter, method, path, retries)
+      return yield unless instrumenter
+
+      payload = new_payload(method, path, retries)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = failure = nil
+      instrumenter.instrument(EVENT, payload) do
+        result = yield
+        payload[:status] = result.first
+      rescue Error => e
+        failure = e
+        record_error(payload, e)
+      ensure
+        payload[:duration] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      end
+      raise failure if failure
+
+      # The request's own result, never the instrumenter's return value:
+      # observability must not change what a client method returns. nil here
+      # means the instrumenter never yielded, so no request was made.
+      result || raise(ConfigurationError, "instrumenter did not yield to the request block")
+    end
+
+    # The query string is dropped here, not left to callers: Connection#request
+    # is public and a path passed with `?email_address=...` inline must not
+    # reach a breadcrumb either.
+    def self.new_payload(method, path, retries)
+      { method: method, path: path.split(/[?#]/, 2).first.to_s, status: nil, duration: nil,
+        retries: retries, retry_after: nil, error: nil }
+    end
+
+    def self.record_error(payload, error)
+      payload[:error] = error.class.name
+      payload[:status] = error.status if error.is_a?(APIError)
+      payload[:retry_after] = error.retry_after if error.is_a?(RateLimitError)
+    end
+
+    # Wraps a plain Logger as an instrumenter: one debug line per attempt.
+    # Used for Configuration#logger; you can also pass it as `instrumenter:`.
+    class LoggerInstrumenter
+      def initialize(logger)
+        @logger = logger
+      end
+
+      def instrument(_name, payload)
+        yield payload
+      ensure
+        @logger.debug { format_line(payload) }
+      end
+
+      private
+
+      def format_line(payload)
+        line = "kit #{payload[:method].to_s.upcase} #{payload[:path]} status=#{payload[:status] || "-"} " \
+               "duration=#{format("%.3f", payload[:duration] || 0)}s retries=#{payload[:retries]}"
+        line += " retry_after=#{payload[:retry_after]}" if payload[:retry_after]
+        line += " error=#{payload[:error]}" if payload[:error]
+        line
+      end
+    end
+
+    # Fans one event out to several instrumenters (instrumenter: and logger:
+    # given together). Blocks nest so each sees the same payload.
+    class Multi
+      def initialize(instrumenters)
+        @instrumenters = instrumenters
+      end
+
+      # Yields the payload to the caller's block like every instrumenter does,
+      # forwarding whatever each layer yields so nesting stays transparent.
+      def instrument(name, payload, &block)
+        @instrumenters.reverse.inject(block) do |inner, instrumenter|
+          ->(yielded) { instrumenter.instrument(name, yielded) { |inner_payload| inner.call(inner_payload) } }
+        end.call(payload)
+      end
+    end
+
+    # Resolves Configuration's instrumenter:/logger: pair into one instrumenter
+    # (or nil when neither is set).
+    def self.build(instrumenter: nil, logger: nil)
+      list = []
+      if instrumenter
+        unless instrumenter.respond_to?(:instrument)
+          raise ConfigurationError, "instrumenter: must respond to #instrument"
+        end
+
+        list << instrumenter
+      end
+      if logger
+        raise ConfigurationError, "logger: must respond to #debug" unless logger.respond_to?(:debug)
+
+        list << LoggerInstrumenter.new(logger)
+      end
+      return nil if list.empty?
+
+      list.size == 1 ? list.first : Multi.new(list)
+    end
+  end
+end

data/lib/kit/resources/subscribers.rb

@@ -107,10 +107,7 @@ module Kit
 
       private
 
-      # Normalised names, first spelling wins, one per case-insensitive key.
-      def distinct_tag_names(tag_names)
-        Array(tag_names).map { |name| Tags.normalize_name(name) }.uniq(&:downcase)
-      end
+      def distinct_tag_names(tag_names) = TagNames.distinct(tag_names)
 
       def apply_tag(subscriber, name)
         tag = @tags.ensure(name: name)

data/lib/kit/resources/tags.rb

@@ -12,22 +12,12 @@ module Kit
       end
 
       # Kit matches tag names case-insensitively and v3 consumers carry over a
-      # "find_tag_by_name or create" dance that v4 no longer needs. This is the
-      # canonical form of a name for that matching: runs of Unicode whitespace
-      # (`[[:space:]]`, not `\s`, so a fullwidth or typographic space cannot
-      # mint a look-alike tag) collapsed to one ASCII space and trimmed.
-      # Raises ArgumentError when nothing is left.
-      def self.normalize_name(name)
-        normalized = name.to_s.gsub(/[[:space:]]+/, " ").strip
-        raise ArgumentError, "tag name must not be blank" if normalized.empty?
+      # "find_tag_by_name or create" dance that v4 no longer needs. These are
+      # the canonical form of a name for that matching and its match key; the
+      # rules live in Kit::TagNames so Kit::Testing shares them exactly.
+      def self.normalize_name(name) = TagNames.normalize(name)
 
-        normalized
-      end
-
-      # The key two names share when Kit would treat them as the same tag.
-      def self.name_key(name)
-        normalize_name(name).downcase
-      end
+      def self.name_key(name) = TagNames.key(name)
 
       # GET /v4/tags
       def list(**params)

data/lib/kit/tag_names.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Kit
+  # How Kit matches tag names, in one dependency-free place so the client
+  # (Resources::Tags#ensure, Subscribers#upsert_and_tag) and Kit::Testing's
+  # factories agree exactly: runs of Unicode whitespace (`[[:space:]]`, not
+  # `\s`, so a fullwidth or typographic space cannot mint a look-alike tag)
+  # collapsed to one ASCII space and trimmed; then matched case-insensitively.
+  module TagNames
+    # The canonical spelling. Raises ArgumentError when nothing is left.
+    def self.normalize(name)
+      normalized = name.to_s.gsub(/[[:space:]]+/, " ").strip
+      raise ArgumentError, "tag name must not be blank" if normalized.empty?
+
+      normalized
+    end
+
+    # The key two names share when Kit would treat them as the same tag.
+    def self.key(name)
+      normalize(name).downcase
+    end
+
+    # Normalised names, first spelling wins, one per case-insensitive key —
+    # the set of tags upsert_and_tag applies for `names`.
+    def self.distinct(names)
+      Array(names).map { |name| normalize(name) }.uniq(&:downcase)
+    end
+  end
+end

data/lib/kit/testing/factories.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# The value objects are plain Data classes with no dependency on http.rb, so
+# they are loaded here directly: `require "kit/testing"` stays usable without
+# the gem's runtime dependencies installed (the standalone guarantee).
+%w[account creator_profile subscriber tag custom_field sequence sequence_email broadcast broadcast_stats
+   post snippet purchase webhook webhook_endpoint email_stats growth_stats subscriber_stats
+   tagged_subscriber].each { |object| require_relative "../objects/#{object}" }
+require_relative "../auth/credential"
+require_relative "../oauth/token"
+require_relative "../tag_names"
+
+module Kit
+  module Testing # rubocop:disable Style/Documentation -- documented in lib/kit/testing.rb
+    # Typed value objects for `instance_double` returns and direct unit tests,
+    # built from the same documented examples as the envelope builders:
+    #
+    #   Kit::Testing.subscriber(id: 500, email_address: "ada@example.com")
+    #   # => #<data Kit::Objects::Subscriber id=500, email_address="ada@example.com", state="active", ...>
+    #   Kit::Testing.account_info(plan_type: "free")   # => Kit::Objects::AccountInfo
+    #   Kit::Testing.oauth_token(expires_in: 3600)     # => Kit::OAuth::Token
+    #   Kit::Testing.tagged_subscriber(tag_names: ["vip", "beta"])
+    #
+    # Each `<object>` factory is the `<object>_json` builder's envelope object
+    # parsed by the Kit::Objects class the resource itself uses, so a factory
+    # cannot produce a value the real client could not — the same field
+    # validation applies to overrides.
+    module Factories
+      # <object> factory => the Kit::Objects class that parses its envelope
+      # object (the operation comes from Testing::OBJECTS under the same key).
+      # `account` is the account object alone; `account_info` below builds the
+      # whole GET /v4/account result.
+      OBJECT_CLASSES = {
+        subscriber: Objects::Subscriber,
+        tag: Objects::Tag,
+        custom_field: Objects::CustomField,
+        sequence: Objects::Sequence,
+        sequence_email: Objects::SequenceEmail,
+        broadcast: Objects::Broadcast,
+        broadcast_stats: Objects::BroadcastStats,
+        post: Objects::Post,
+        snippet: Objects::Snippet,
+        purchase: Objects::Purchase,
+        webhook: Objects::Webhook,
+        webhook_endpoint: Objects::WebhookEndpoint,
+        creator_profile: Objects::CreatorProfile,
+        email_stats: Objects::EmailStats,
+        growth_stats: Objects::GrowthStats,
+        subscriber_stats: Objects::SubscriberStats,
+        account: Objects::Account
+      }.freeze
+
+      # Kit's documented token response, for Kit::OAuth::Token.
+      TOKEN_EXAMPLE = {
+        "access_token" => "<ACCESS_TOKEN>",
+        "refresh_token" => "<REFRESH_TOKEN>",
+        "token_type" => "Bearer",
+        "expires_in" => 172_800,
+        "scope" => "public",
+        "created_at" => 1_700_000_000
+      }.freeze
+
+      # The typed object for `factory` (:subscriber, :tag, ...) with overrides
+      # applied to its documented example.
+      def object(factory, **overrides)
+        klass = OBJECT_CLASSES.fetch(factory.to_sym) do
+          raise ArgumentError,
+                "unknown Kit::Testing factory #{factory.inspect}; known: #{OBJECT_CLASSES.keys.join(", ")}"
+        end
+        klass.from(attributes(OBJECTS.fetch(factory.to_sym), **overrides))
+      end
+
+      # The whole GET /v4/account result. Account overrides apply to
+      # `account`; pass `user:` to override user fields (validated against the
+      # documented user example like every other override).
+      def account_info(user: {}, **account_overrides)
+        body = account_json(**account_overrides)
+        Objects::AccountInfo.new(
+          user: Objects::User.from(merge_known("user", body.fetch("user"), user)),
+          account: Objects::Account.from(body.fetch("account"))
+        )
+      end
+
+      # A Kit::OAuth::Token from Kit's documented token response. `expires_in`
+      # 172800 (48 h) and `created_at` are set, so #expires_at / #expired? /
+      # #expiring_within? work; pass `created_at:` to place it in time.
+      def oauth_token(**overrides)
+        OAuth::Token.from(merge_known("token", TOKEN_EXAMPLE, overrides))
+      end
+
+      # Subscribers#upsert_and_tag's result, shaped as production would: names
+      # normalised and de-duplicated the way Kit matches them (Kit::TagNames,
+      # the same code the resource runs), one Tag per distinct name with ids
+      # ascending from the tag example's, around a subscriber built from the
+      # remaining overrides.
+      def tagged_subscriber(tag_names: ["vip"], **subscriber_overrides)
+        base = object(:tag)
+        tags = TagNames.distinct(tag_names).each_with_index.map { |name, i| object(:tag, id: base.id + i, name: name) }
+        Objects::TaggedSubscriber.new(subscriber: object(:subscriber, **subscriber_overrides), tags: tags)
+      end
+
+      private
+
+      # `overrides` over `example`, rejecting a key the documented example does
+      # not carry — the same rule the envelope builders apply to their types.
+      def merge_known(what, example, overrides)
+        unknown = overrides.keys.map(&:to_s) - example.keys
+        if unknown.any?
+          raise ArgumentError,
+                "#{unknown.first.inspect} is not a field of #{what.inspect}; known: #{example.keys.join(", ")}"
+        end
+
+        example.merge(overrides.transform_keys(&:to_s))
+      end
+    end
+
+    extend Factories
+
+    # Kit::Testing.subscriber(id: 1) etc., one per OBJECTS entry.
+    Factories::OBJECT_CLASSES.each_key do |factory|
+      define_singleton_method(factory) { |**overrides| object(factory, **overrides) }
+    end
+  end
+end