kit-rb 0.4.0 → 0.5.0

data/lib/kit/testing/fixtures.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+require "set" # rubocop:disable Lint/RedundantRequireStatement -- autoloaded since Ruby 3.2, but be explicit
+require_relative "operations"
+
+module Kit
+  module Testing
+    # The documented example responses Kit::Testing builds from, generated by
+    # `rake testing:fixtures` from OPERATIONS and the vendored OpenAPI document
+    # (see spec/support/testing_fixtures.rb); a contract test fails when the
+    # shipped file differs from what the generator would produce.
+    module Fixtures
+      PATH = File.expand_path("fixtures.json", __dir__)
+
+      # { "subscribers_get" => { "verb" => "get", "path" => "/v4/subscribers/{id}",
+      #   "key" => "subscriber", "kind" => "object" | "list" | "raw" | "none",
+      #   "type" => "subscriber", "responses" => { "200" => { "subscriber" => {...} } } }, ... }
+      # `type` is the logical response type (see Testing::TYPES): the
+      # envelope key alone does not identify one — "stats" is three objects.
+      # Recursively freezes a parsed JSON tree (Hashes, Arrays, Strings).
+      # Done by hand rather than with `JSON.parse(freeze: true)`: that option
+      # arrived in json 2.7, and Ruby 3.2's bundled json (2.6) — which is what
+      # `ruby --disable-gems` loads — would silently leave the tree mutable.
+      def self.deep_freeze(value)
+        case value
+        when Hash then value.each_value { |v| deep_freeze(v) }
+        when Array then value.each { |v| deep_freeze(v) }
+        end
+        value.freeze
+      end
+
+      # Deep-frozen: a caller reaching in through FIXTURES / .for must not be
+      # able to alter a documented example for every later builder call.
+      ALL = deep_freeze(JSON.parse(File.read(PATH)))
+
+      # Response type => every field any documented example of that type
+      # shows, so an override the canonical example happens to omit
+      # (tagged_at on a subscriber) is still accepted, while a typo — or a
+      # field of a different type that shares the envelope key — is not.
+      KNOWN_FIELDS = ALL.each_value.with_object(Hash.new { |h, k| h[k] = Set.new }) do |fixture, fields|
+        type = fixture["type"]
+        next unless type
+
+        fixture["responses"].each_value do |body|
+          value = body && body[fixture["key"]]
+          value = value.first if value.is_a?(Array)
+          fields[type].merge(value.keys) if value.is_a?(Hash)
+        end
+      end.transform_values(&:freeze).freeze
+
+      def self.for(operation)
+        ALL.fetch(operation.to_s) do
+          raise ArgumentError, "unknown Kit operation #{operation.inspect}; see Kit::Testing::OPERATIONS"
+        end
+      end
+
+      # The response code to build: the first Kit documents, or `status` when
+      # it is one of them.
+      def self.status_for(fixture, status)
+        codes = fixture["responses"].keys
+        return codes.first if status.nil?
+        return status.to_s if codes.include?(status.to_s)
+
+        raise ArgumentError, "Kit documents #{codes.join(", ")} for this operation, not #{status}"
+      end
+
+      # `overrides` (Symbol or String keys) merged over a copy of `example`
+      # (which may be frozen), rejecting a field Kit never documents for this
+      # response type. Override values are deep-copied too, so two rows given
+      # the same nested Hash stay independent and a frozen value does not
+      # leave part of the returned body frozen.
+      def self.merge_fields(type, example, overrides)
+        overrides.each_with_object(example.dup) do |(field, value), merged|
+          name = field.to_s
+          unless KNOWN_FIELDS[type].include?(name)
+            raise ArgumentError,
+                  "#{name.inspect} is not a field of #{type.inspect}; known: #{KNOWN_FIELDS[type].sort.join(", ")}"
+          end
+
+          merged[name] = deep_dup(value)
+        end
+      end
+
+      # An unfrozen deep copy: what builders hand out, so specs may mutate.
+      def self.deep_dup(value)
+        case value
+        when Hash then value.to_h { |k, v| [k, deep_dup(v)] }
+        when Array then value.map { |v| deep_dup(v) }
+        when String then value.dup
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/kit/testing/operations.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Kit
+  module Testing
+    # Every Kit v4 operation this gem drives, named `<resource>_<method>` after
+    # the client method that calls it (`client.subscribers.create` is
+    # :subscribers_create). Paths keep the OpenAPI `{placeholder}` form so the
+    # registry can be checked one-to-one against the vendored contract; the
+    # stub helpers substitute the placeholders.
+    #
+    # This is the single hand-written source: fixtures.json (example responses)
+    # is generated from it plus the OpenAPI document, and a contract test fails
+    # when either drifts from the other.
+    OPERATIONS = {
+      account_get: [:get, "/v4/account"],
+      account_colors: [:get, "/v4/account/colors"],
+      account_update_colors: [:put, "/v4/account/colors"],
+      account_creator_profile: [:get, "/v4/account/creator_profile"],
+      account_email_stats: [:get, "/v4/account/email_stats"],
+      account_growth_stats: [:get, "/v4/account/growth_stats"],
+
+      subscribers_list: [:get, "/v4/subscribers"],
+      subscribers_create: [:post, "/v4/subscribers"],
+      subscribers_filter: [:post, "/v4/subscribers/filter"],
+      subscribers_get: [:get, "/v4/subscribers/{id}"],
+      subscribers_update: [:put, "/v4/subscribers/{id}"],
+      subscribers_unsubscribe: [:post, "/v4/subscribers/{id}/unsubscribe"],
+      subscribers_tags: [:get, "/v4/subscribers/{subscriber_id}/tags"],
+      subscribers_stats: [:get, "/v4/subscribers/{subscriber_id}/stats"],
+      subscribers_set_location: [:post, "/v4/subscribers/{subscriber_id}/location"],
+      subscribers_update_location: [:patch, "/v4/subscribers/{subscriber_id}/location"],
+      subscribers_remove_location: [:delete, "/v4/subscribers/{subscriber_id}/location"],
+
+      tags_list: [:get, "/v4/tags"],
+      tags_create: [:post, "/v4/tags"],
+      tags_update: [:put, "/v4/tags/{id}"],
+      tags_subscribers: [:get, "/v4/tags/{tag_id}/subscribers"],
+      tags_tag_subscriber: [:post, "/v4/tags/{tag_id}/subscribers/{id}"],
+      tags_remove_subscriber: [:delete, "/v4/tags/{tag_id}/subscribers/{id}"],
+      tags_tag_subscriber_by_email: [:post, "/v4/tags/{tag_id}/subscribers"],
+      tags_remove_subscriber_by_email: [:delete, "/v4/tags/{tag_id}/subscribers"],
+
+      custom_fields_list: [:get, "/v4/custom_fields"],
+      custom_fields_create: [:post, "/v4/custom_fields"],
+      custom_fields_update: [:put, "/v4/custom_fields/{id}"],
+      custom_fields_delete: [:delete, "/v4/custom_fields/{id}"],
+
+      forms_list: [:get, "/v4/forms"],
+      forms_subscribers: [:get, "/v4/forms/{form_id}/subscribers"],
+      forms_add_subscriber: [:post, "/v4/forms/{form_id}/subscribers/{id}"],
+      forms_add_subscriber_by_email: [:post, "/v4/forms/{form_id}/subscribers"],
+
+      sequences_list: [:get, "/v4/sequences"],
+      sequences_create: [:post, "/v4/sequences"],
+      sequences_get: [:get, "/v4/sequences/{id}"],
+      sequences_update: [:put, "/v4/sequences/{id}"],
+      sequences_delete: [:delete, "/v4/sequences/{id}"],
+      sequences_subscribers: [:get, "/v4/sequences/{sequence_id}/subscribers"],
+      sequences_add_subscriber: [:post, "/v4/sequences/{sequence_id}/subscribers/{id}"],
+      sequences_add_subscriber_by_email: [:post, "/v4/sequences/{sequence_id}/subscribers"],
+      sequences_emails: [:get, "/v4/sequences/{sequence_id}/emails"],
+      sequences_create_email: [:post, "/v4/sequences/{sequence_id}/emails"],
+      sequences_email: [:get, "/v4/sequences/{sequence_id}/emails/{id}"],
+      sequences_update_email: [:put, "/v4/sequences/{sequence_id}/emails/{id}"],
+      sequences_delete_email: [:delete, "/v4/sequences/{sequence_id}/emails/{id}"],
+
+      broadcasts_list: [:get, "/v4/broadcasts"],
+      broadcasts_create: [:post, "/v4/broadcasts"],
+      broadcasts_get: [:get, "/v4/broadcasts/{id}"],
+      broadcasts_update: [:put, "/v4/broadcasts/{id}"],
+      broadcasts_delete: [:delete, "/v4/broadcasts/{id}"],
+      broadcasts_stats_list: [:get, "/v4/broadcasts/stats"],
+      broadcasts_stats: [:get, "/v4/broadcasts/{broadcast_id}/stats"],
+      broadcasts_clicks: [:get, "/v4/broadcasts/{broadcast_id}/clicks"],
+
+      email_templates_list: [:get, "/v4/email_templates"],
+      segments_list: [:get, "/v4/segments"],
+
+      posts_list: [:get, "/v4/posts"],
+      posts_get: [:get, "/v4/posts/{id}"],
+
+      snippets_list: [:get, "/v4/snippets"],
+      snippets_get: [:get, "/v4/snippets/{id}"],
+      snippets_create: [:post, "/v4/snippets"],
+      snippets_update: [:put, "/v4/snippets/{id}"],
+
+      purchases_list: [:get, "/v4/purchases"],
+      purchases_get: [:get, "/v4/purchases/{id}"],
+      purchases_create: [:post, "/v4/purchases"],
+
+      webhooks_list: [:get, "/v4/webhooks"],
+      webhooks_create: [:post, "/v4/webhooks"],
+      webhooks_delete: [:delete, "/v4/webhooks/{id}"],
+
+      webhook_endpoints_list: [:get, "/v4/webhook_endpoints"],
+      webhook_endpoints_get: [:get, "/v4/webhook_endpoints/{id}"],
+      webhook_endpoints_create: [:post, "/v4/webhook_endpoints"],
+      webhook_endpoints_update: [:patch, "/v4/webhook_endpoints/{id}"],
+      webhook_endpoints_delete: [:delete, "/v4/webhook_endpoints/{id}"],
+      webhook_endpoints_rotate_secret: [:post, "/v4/webhook_endpoints/{id}/rotate_secret"],
+      webhook_endpoints_revoke_previous_secret: [:post, "/v4/webhook_endpoints/{id}/revoke_previous_secret"],
+
+      bulk_create_subscribers: [:post, "/v4/bulk/subscribers"],
+      bulk_create_custom_fields: [:post, "/v4/bulk/custom_fields"],
+      bulk_update_custom_field_values: [:post, "/v4/bulk/custom_fields/subscribers"],
+      bulk_add_subscribers_to_forms: [:post, "/v4/bulk/forms/subscribers"],
+      bulk_create_tags: [:post, "/v4/bulk/tags"],
+      bulk_delete_tags: [:delete, "/v4/bulk/tags"],
+      bulk_tag_subscribers: [:post, "/v4/bulk/tags/subscribers"],
+      bulk_remove_tag_subscribers: [:delete, "/v4/bulk/tags/subscribers"]
+    }.each_value(&:freeze).freeze
+
+    # The logical response type an operation's envelope holds — the same
+    # grouping as the Kit::Objects class the resource builds — for the
+    # operations whose envelope key alone does not say: "stats" is three
+    # different objects, "broadcast"/"broadcasts" hold BroadcastStats on the
+    # stats endpoints, "email(s)" are sequence emails. Every other operation's
+    # type is its envelope key singularised (subscribers => subscriber).
+    TYPES = {
+      account_email_stats: "email_stats",
+      account_growth_stats: "growth_stats",
+      subscribers_stats: "subscriber_stats",
+      broadcasts_stats: "broadcast_stats",
+      broadcasts_stats_list: "broadcast_stats",
+      sequences_emails: "sequence_email",
+      sequences_create_email: "sequence_email",
+      sequences_email: "sequence_email",
+      sequences_update_email: "sequence_email",
+      account_creator_profile: "creator_profile"
+    }.freeze
+  end
+end

data/lib/kit/testing/stubs.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "erb"
+require_relative "../errors"
+
+module Kit
+  module Testing # rubocop:disable Style/Documentation -- documented in lib/kit/testing.rb
+    # WebMock stubs by operation name, so a consumer spec reads as "the upsert
+    # succeeds" instead of as a URL, a header hash and a hand-written envelope:
+    #
+    #   Kit::Testing.stub(:subscribers_create, id: 500)                 # 200 with the documented body
+    #   Kit::Testing.stub(:tags_tag_subscriber, tag_id: 7, id: 500)     # path params by name
+    #   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)
+    #
+    # Each returns WebMock's request stub, so `.with(...)`, `.to_return(...)`
+    # chaining and `expect(stub).to have_been_requested` work as usual. Path
+    # params not given match any value; any query string matches. WebMock is
+    # not a dependency of this gem: require it in your spec_helper.
+    module Stubs
+      BASE_URL = "https://api.kit.com"
+      JSON_HEADERS = { "Content-Type" => "application/json" }.freeze
+
+      # A successful response for `operation`: the documented example at
+      # `http_status:` (default: the first Kit documents) with `overrides` on
+      # its envelope object. Path params are given by name (`id:`, `tag_id:`);
+      # for a list operation `items:` and the pagination keywords shape the
+      # page as #list_json does. A path param that is also a field of the
+      # response object (`id:` on subscribers_get) applies to both, so the
+      # body answers with the id that was asked for.
+      def stub(operation, http_status: nil, **params)
+        fixture = Fixtures.for(operation)
+        template = operation(operation).last
+        path_params = params.select { |key, _| template.include?("{#{key}}") }
+        overrides = params.reject { |key, _| path_params.key?(key) && !body_field?(fixture, key) }
+        status = Fixtures.status_for(fixture, http_status)
+        request_stub(operation, path_params).to_return(status: status.to_i, headers: JSON_HEADERS,
+                                                       body: stub_body(operation, fixture, status, overrides))
+      end
+
+      # A failing response: Kit's { "errors" => [...] } envelope at `status`.
+      def stub_error(operation, status, *messages, **path_params)
+        request_stub(operation, path_params)
+          .to_return(status: status, headers: JSON_HEADERS, body: JSON.generate(error_json(*messages)))
+      end
+
+      # A 429 with `Retry-After` (seconds), as Kit sends it.
+      def stub_rate_limited(operation, retry_after: 30, **path_params)
+        request_stub(operation, path_params)
+          .to_return(status: 429, headers: JSON_HEADERS.merge("Retry-After" => retry_after.to_s),
+                     body: JSON.generate(error_json("Rate limit exceeded")))
+      end
+
+      # The URL of an operation with its path params filled in: a String when
+      # every placeholder is given (for `a_request(verb, url)`), else a Regexp
+      # with `[^/?]+` for the rest. Neither admits a query string; stubs do.
+      def url_for(operation, **path_params)
+        template, given = url_parts(operation, path_params)
+        return "#{BASE_URL}#{fill(template, given)}" if complete?(template, given)
+
+        /\A#{Regexp.escape(BASE_URL)}#{path_pattern(template, given)}\z/
+      end
+
+      private
+
+      # The template and the given params as encoded path segments — exactly
+      # what Resources::Base#path_id sends, so `id: "a b"` matches `/a%20b` and
+      # `id: "1/unsubscribe"` cannot rewrite the route; nil/blank raises like
+      # the client does instead of collapsing onto the parent route.
+      def url_parts(operation, path_params)
+        template = operation(operation).last
+        unknown = path_params.keys.map(&:to_s) - placeholders(template)
+        raise ArgumentError, "#{unknown.first.inspect} is not a path param of #{template}" if unknown.any?
+
+        [template, path_params.to_h { |key, value| [key.to_s, path_segment(key, value)] }]
+      end
+
+      def path_segment(key, value)
+        raise ArgumentError, "#{key} must not be nil or blank" if value.nil? || value.to_s.strip.empty?
+
+        ERB::Util.url_encode(value.to_s)
+      end
+
+      def placeholders(template) = template.scan(/\{(\w+)\}/).flatten
+      def complete?(template, given) = (placeholders(template) - given.keys).empty?
+      def fill(template, given) = template.gsub(/\{(\w+)\}/) { given.fetch(Regexp.last_match(1)) }
+
+      def path_pattern(template, given)
+        Regexp.escape(template).gsub(/\\\{(\w+)\\\}/) do
+          given.key?(Regexp.last_match(1)) ? Regexp.escape(given[Regexp.last_match(1)]) : "[^/?]+"
+        end
+      end
+
+      # Stubs match the path with any query string, since list filters and
+      # remove_*_by_email travel there.
+      def request_stub(operation, path_params)
+        webmock!
+        verb, = operation(operation)
+        template, given = url_parts(operation, path_params)
+        WebMock::API.stub_request(verb, /\A#{Regexp.escape(BASE_URL)}#{path_pattern(template, given)}(\?.*)?\z/)
+      end
+
+      # True when `key` is a documented field of the operation's response type
+      # (so a same-named path param should also override the body).
+      def body_field?(fixture, key)
+        type = fixture["type"]
+        type && Fixtures::KNOWN_FIELDS[type]&.include?(key.to_s)
+      end
+
+      # The body for the selected status: the list page (list operations
+      # document one status), the status-specific example (bulk 202s are
+      # empty; a 201 may differ from the 200), or nothing for a 204.
+      def stub_body(operation, fixture, status, overrides)
+        case fixture["kind"]
+        when "none" then ""
+        when "list" then JSON.generate(list_body(operation, overrides))
+        else JSON.generate(response(operation, http_status: status, **overrides))
+        end
+      end
+
+      # A list page: `items:` (rows or a count), the pagination keywords, and
+      # any remaining keys — a same-named path field such as sequence_id — are
+      # applied to every row.
+      def list_body(operation, overrides)
+        items = overrides.fetch(:items, 1)
+        pagination = overrides.slice(*PAGINATION_FIELDS)
+        row_fields = overrides.except(:items, *PAGINATION_FIELDS)
+        rows = items.is_a?(Integer) ? Array.new(items) { |i| { "id" => attributes(operation)["id"].to_i + i } } : items
+        # The path is the source of truth for a shared field: it wins over a row.
+        rows = rows.map { |row| row.merge(row_fields) } if row_fields.any?
+        list_json(operation, rows, **pagination)
+      end
+
+      def webmock!
+        return if defined?(WebMock::API)
+
+        raise ConfigurationError,
+              "Kit::Testing.stub needs WebMock: add `gem \"webmock\"` to your test group and require \"webmock/rspec\""
+      end
+    end
+
+    extend Stubs
+  end
+end

data/lib/kit/testing.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative "testing/operations"
+require_relative "testing/fixtures"
+
+module Kit
+  # Test support for consumers of this gem: `require "kit/testing"` (it is not
+  # loaded by `require "kit-rb"`, and depends on no test framework).
+  #
+  # Every builder starts from Kit's own documented example response for the
+  # operation (lib/kit/testing/fixtures.json, generated from the OpenAPI
+  # document and kept in step by a contract test), so a consumer spec reads as
+  # "the upsert succeeds" instead of a hand-written envelope that drifts when
+  # Kit changes a field:
+  #
+  #   Kit::Testing.subscriber_json(id: 500, email_address: "ada@example.com")
+  #   # => { "subscriber" => { "id" => 500, "email_address" => "ada@example.com", "state" => "active", ... } }
+  #
+  #   Kit::Testing.response(:tags_create, http_status: 201, name: "vip")   # any operation, by name
+  #   Kit::Testing.list_json(:tags_list, [{ name: "vip" }, { name: "beta" }], has_next_page: true)
+  #   Kit::Testing.error_json("The API key is invalid")               # => { "errors" => [...] }
+  #
+  #   Kit::Testing.subscriber(id: 500)                                # typed Kit::Objects::Subscriber
+  #   Kit::Testing.account_info(plan_type: "free")                    # Kit::Objects::AccountInfo
+  #   Kit::Testing.oauth_token(created_at: Time.now.to_i)             # Kit::OAuth::Token
+  #
+  #   Kit::Testing.stub(:subscribers_create, id: 500)                 # WebMock stub by operation
+  #   Kit::Testing.stub_error(:account_get, 401, "The API key is invalid")
+  #
+  # Operation names are `<resource>_<method>` after the client method
+  # (Kit::Testing::OPERATIONS). Overrides must be fields Kit documents for
+  # that response type (Kit::Testing::TYPES) — a typo, or a field of another
+  # type that happens to share the envelope key, raises ArgumentError rather
+  # than silently building a response the real API would never send.
+  module Testing
+    FIXTURES_PATH = Fixtures::PATH
+    FIXTURES = Fixtures::ALL
+    KNOWN_FIELDS = Fixtures::KNOWN_FIELDS
+
+    # The canonical operation behind each `<object>_json` / `<object>` builder.
+    OBJECTS = {
+      subscriber: :subscribers_get,
+      tag: :tags_create,
+      custom_field: :custom_fields_create,
+      sequence: :sequences_get,
+      sequence_email: :sequences_email,
+      broadcast: :broadcasts_get,
+      broadcast_stats: :broadcasts_stats,
+      post: :posts_get,
+      snippet: :snippets_get,
+      purchase: :purchases_get,
+      webhook: :webhooks_create,
+      webhook_endpoint: :webhook_endpoints_get,
+      creator_profile: :account_creator_profile,
+      email_stats: :account_email_stats,
+      growth_stats: :account_growth_stats,
+      subscriber_stats: :subscribers_stats,
+      account: :account_get
+    }.freeze
+
+    PAGINATION_FIELDS = %i[has_next_page has_previous_page start_cursor end_cursor per_page total_count].freeze
+
+    class << self
+      # The documented example body for `operation` at `http_status` (default:
+      # the first 2xx Kit documents), with `overrides` applied to its envelope
+      # object. For a paginated list the overrides apply to the first item;
+      # use #list_json to shape the whole page. (The selector is not called
+      # `status:` because `status` is a documented field of posts, purchases,
+      # broadcasts and webhook endpoints, which must stay overridable.)
+      def response(operation, http_status: nil, **overrides)
+        fixture = Fixtures.for(operation)
+        body = Fixtures.deep_dup(fixture["responses"].fetch(Fixtures.status_for(fixture, http_status)))
+        apply_overrides!(fixture, body, overrides) unless overrides.empty?
+        body
+      end
+
+      # The envelope object alone (no wrapper key): what `klass.from` receives.
+      def attributes(operation, **overrides)
+        fixture = Fixtures.for(operation)
+        raise ArgumentError, "#{operation} has no envelope object to build" unless %w[object
+                                                                                      list].include?(fixture["kind"])
+
+        value = response(operation, **overrides).fetch(fixture["key"])
+        fixture["kind"] == "list" ? value.first : value
+      end
+
+      # A cursor-paginated page for a list operation. `items` is an Array of
+      # override Hashes (each merged over the documented example item) or an
+      # Integer count of example items; pagination fields are keywords.
+      def list_json(operation, items = 1, **pagination)
+        fixture = Fixtures.for(operation)
+        raise ArgumentError, "#{operation} is not a paginated list" unless fixture["kind"] == "list"
+
+        body = Fixtures.deep_dup(fixture["responses"].values.first)
+        rows = list_rows(fixture["type"], attributes(operation), items)
+        body[fixture["key"]] = rows
+        body["pagination"] = pagination_json(body["pagination"], **page_fields(rows, pagination))
+        body
+      end
+
+      # A pagination object: `example` (default: the tags list's) with exactly
+      # the given fields replaced — an omitted keyword keeps the example's
+      # value, an explicit nil clears a cursor. list_json passes the terminal-
+      # page defaults itself.
+      def pagination_json(example = Fixtures.for(:tags_list)["responses"]["200"]["pagination"], **fields)
+        unknown = fields.keys - PAGINATION_FIELDS
+        if unknown.any?
+          raise ArgumentError, "unknown pagination field(s) #{unknown.inspect}; known: #{PAGINATION_FIELDS.join(", ")}"
+        end
+
+        page = example.dup
+        fields.each { |field, value| page[field.to_s] = value }
+        Fixtures.deep_dup(page) # neither the frozen example's strings nor the caller's own values
+      end
+
+      # The error envelope Kit sends on every non-2xx: { "errors" => [...] }.
+      def error_json(*messages) = { "errors" => Fixtures.deep_dup(messages.flatten) }
+
+      # The HTTP status a builder defaults to for `operation` (or validates).
+      def http_status(operation, http_status = nil) = Fixtures.status_for(Fixtures.for(operation), http_status).to_i
+
+      # The [verb, path] Kit::Testing::OPERATIONS declares for `operation`
+      # (a frozen tuple; the registry cannot be altered through it).
+      def operation(name)
+        Fixtures.for(name) # validates the name with the same message
+        OPERATIONS.fetch(name.to_sym)
+      end
+
+      private
+
+      # list_json's page is a single terminal page unless told otherwise, and an
+      # empty page has no cursors, as the real API answers; keywords still win.
+      def page_fields(rows, pagination)
+        defaults = { has_next_page: false, has_previous_page: false }
+        defaults.merge!(start_cursor: nil, end_cursor: nil) if rows.empty?
+        defaults.merge(pagination)
+      end
+
+      # Rows for a page: n deep copies of the example with distinct ids (kept
+      # in the example's own type — subscribers_filter documents string ids),
+      # or each given override Hash merged over its own deep copy, so mutating
+      # one row's nested Hash never changes a sibling.
+      def list_rows(type, example, items)
+        unless items.is_a?(Integer)
+          return items.map do |row|
+            Fixtures.merge_fields(type, Fixtures.deep_dup(example), row)
+          end
+        end
+
+        Array.new(items) do |i|
+          row = Fixtures.deep_dup(example)
+          row["id"] = successor_id(example["id"], i) if example.key?("id")
+          row
+        end
+      end
+
+      def successor_id(id, offset)
+        case id
+        when Integer then id + offset
+        when String then (id.to_i + offset).to_s
+        else id
+        end
+      end
+
+      def apply_overrides!(fixture, body, overrides)
+        key = fixture["key"]
+        type = fixture["type"]
+        case fixture["kind"]
+        when "object" then body[key] = Fixtures.merge_fields(type, body[key], overrides)
+        when "list" then body[key][0] = Fixtures.merge_fields(type, body[key][0], overrides)
+        else raise ArgumentError, "#{fixture["verb"].upcase} #{fixture["path"]} has no envelope object to override"
+        end
+      end
+    end
+
+    # Kit::Testing.subscriber_json(id: 1) etc., one per OBJECTS entry: the
+    # canonical operation's response with overrides on its envelope object.
+    OBJECTS.each do |object, operation|
+      define_singleton_method(:"#{object}_json") { |**overrides| response(operation, **overrides) }
+    end
+  end
+end
+
+require_relative "testing/factories"
+require_relative "testing/stubs"

data/lib/kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kit
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/kit-rb.rb

@@ -14,10 +14,12 @@ end
 
 require "kit/version"
 require "kit/errors"
+require "kit/tag_names"
 require "kit/configuration"
 require "kit/auth/credential"
 require "kit/auth/api_key"
 require "kit/auth/oauth"
+require "kit/instrumentation"
 require "kit/connection"
 require "kit/pagination"
 require "kit/oauth/pkce"