kit-rb 0.2.0 → 0.3.1

data/lib/kit/errors.rb

@@ -8,24 +8,51 @@ module Kit
   # (e.g. no credentials supplied).
   class ConfigurationError < Error; end
 
+  # Base for failures below HTTP: the request never got a response. `cause`
+  # is the underlying http.rb exception.
+  class TransportError < Error; end
+  # The connection or read timed out (config.open_timeout / read_timeout).
+  class TimeoutError < TransportError; end
+  # The connection could not be established or was dropped (DNS, refused,
+  # reset, TLS).
+  class ConnectionError < TransportError; end
+
+  # Raised when a 2xx response does not have the shape the resource expects
+  # (a missing envelope key, a non-JSON body). Distinct from APIError because
+  # the request succeeded; the client and the API disagree about the payload.
+  # `body` is the parsed (or raw) response body for diagnosis.
+  class UnexpectedResponseError < Error
+    attr_reader :body
+
+    def initialize(message, body: nil)
+      @body = body
+      super(message)
+    end
+  end
+
   # Base for every error that carries an HTTP response. `status` is the code,
   # `body` the parsed JSON body (or the raw string when it wasn't JSON), and
-  # `errors` the `errors` array Kit returns on validation failures.
+  # `errors` the `errors` array Kit returns on validation failures. `method`
+  # and `path` identify the request that failed (nil for OAuth token errors).
   class APIError < Error
-    attr_reader :status, :body, :errors, :response
+    attr_reader :status, :body, :errors, :response, :method, :path
 
-    def initialize(message = nil, status:, body: nil, response: nil)
+    def initialize(message = nil, status:, body: nil, response: nil, method: nil, path: nil)
       @status = status
       @body = body
       @response = response
+      @method = method
+      @path = path
       @errors = body.is_a?(Hash) ? Array(body["errors"]) : []
       super(message || default_message)
     end
 
     private
 
+    # e.g. "GET /v4/subscribers/1 failed with status 404: Not Found"
     def default_message
-      base = "Kit API request failed with status #{status}"
+      request = method && path ? "#{method.to_s.upcase} #{path}" : "Kit API request"
+      base = "#{request} failed with status #{status}"
       @errors.empty? ? base : "#{base}: #{@errors.join(", ")}"
     end
   end
@@ -36,6 +63,12 @@ module Kit
   class AuthorizationError < APIError; end
   # 404 — no such resource.
   class NotFoundError < APIError; end
+  # 409 — the request conflicts with current state (e.g. rotating a webhook
+  # endpoint secret while a previous rotation is still in its grace period).
+  class ConflictError < APIError; end
+  # 413 — the request exceeds Kit's size quota (the bulk endpoints' enqueued
+  # data cap); split the batch.
+  class PayloadTooLargeError < APIError; end
   # 422 — the request was well-formed but semantically invalid.
   class UnprocessableEntityError < APIError; end
 
@@ -43,9 +76,9 @@ module Kit
   class RateLimitError < APIError
     attr_reader :retry_after
 
-    def initialize(message = nil, status:, body: nil, response: nil, retry_after: nil)
+    def initialize(message = nil, status:, body: nil, response: nil, method: nil, path: nil, retry_after: nil)
       @retry_after = retry_after
-      super(message, status: status, body: body, response: response)
+      super(message, status: status, body: body, response: response, method: method, path: path)
     end
   end
 
@@ -69,16 +102,20 @@ module Kit
 
   # Maps an HTTP status to the most specific error class above.
   class Error
+    STATUS_CLASSES = {
+      401 => AuthenticationError,
+      403 => AuthorizationError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      413 => PayloadTooLargeError,
+      422 => UnprocessableEntityError,
+      429 => RateLimitError
+    }.freeze
+
     def self.class_for(status)
-      case status
-      when 401 then AuthenticationError
-      when 403 then AuthorizationError
-      when 404 then NotFoundError
-      when 422 then UnprocessableEntityError
-      when 429 then RateLimitError
-      when 500..599 then ServerError
-      else APIError
-      end
+      return ServerError if (500..599).cover?(status)
+
+      STATUS_CLASSES.fetch(status, APIError)
     end
   end
 end

data/lib/kit/oauth/token.rb

@@ -19,6 +19,15 @@ module Kit
         )
       end
 
+      # Both tokens are masked in #inspect; #to_h still returns the real values
+      # for persistence.
+      def inspect
+        "#<data #{self.class.name} access_token=#{Auth::Credential.mask(access_token)}, " \
+          "refresh_token=#{Auth::Credential.mask(refresh_token)}, token_type=#{token_type.inspect}, " \
+          "expires_in=#{expires_in.inspect}, scope=#{scope.inspect}, created_at=#{created_at.inspect}>"
+      end
+      alias_method :to_s, :inspect
+
       # Unix time the access token expires, or nil when the fields are absent.
       def expires_at
         return nil unless created_at && expires_in

data/lib/kit/objects/account.rb

@@ -9,16 +9,57 @@ module Kit
       end
     end
 
+    # The account's timezone, nested under account.timezone.
+    Timezone = Data.define(:name, :friendly_name, :utc_offset) do
+      def self.from(hash)
+        new(name: hash["name"], friendly_name: hash["friendly_name"], utc_offset: hash["utc_offset"])
+      end
+    end
+
+    # Billing plan details, nested under account.plan.
+    Plan = Data.define(
+      :plan_type, :interval, :subscriber_limit, :on_trial, :trial_lapse_date, :renews_at, :cancels_at
+    ) do
+      def self.from(hash)
+        new(
+          plan_type: hash["plan_type"], interval: hash["interval"], subscriber_limit: hash["subscriber_limit"],
+          on_trial: hash["on_trial"], trial_lapse_date: hash["trial_lapse_date"],
+          renews_at: hash["renews_at"], cancels_at: hash["cancels_at"]
+        )
+      end
+    end
+
+    # One verified sender address, listed under account.sending_addresses.
+    SendingAddress = Data.define(
+      :email_address, :from_name, :status, :is_default, :is_verified, :is_dmarc_configured
+    ) do
+      def self.from(hash)
+        new(
+          email_address: hash["email_address"], from_name: hash["from_name"], status: hash["status"],
+          is_default: hash["is_default"], is_verified: hash["is_verified"],
+          is_dmarc_configured: hash["is_dmarc_configured"]
+        )
+      end
+    end
+
     # The account half of GET /v4/account. Extra fields Kit adds later are
-    # ignored rather than crashing the client (forward-compatible).
-    Account = Data.define(:id, :name, :plan_type, :primary_email_address, :created_at) do
+    # ignored rather than crashing the client (forward-compatible). `timezone`
+    # and `plan` are typed sub-objects (nil when absent); `sending_addresses` is
+    # an Array of SendingAddress.
+    Account = Data.define(
+      :id, :name, :plan_type, :primary_email_address, :created_at,
+      :timezone, :plan, :sending_addresses
+    ) do
       def self.from(hash)
         new(
           id: hash["id"],
           name: hash["name"],
           plan_type: hash["plan_type"],
           primary_email_address: hash["primary_email_address"],
-          created_at: hash["created_at"]
+          created_at: hash["created_at"],
+          timezone: hash["timezone"] && Timezone.from(hash["timezone"]),
+          plan: hash["plan"] && Plan.from(hash["plan"]),
+          sending_addresses: Array(hash["sending_addresses"]).map { |address| SendingAddress.from(address) }
         )
       end
     end

data/lib/kit/objects/bulk_result.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Kit
+  module Objects
+    # One rejected item from a bulk call: `item` is the input echoed back by
+    # Kit (the hash under "subscriber"/"tag"/... — the key varies per
+    # endpoint) and `errors` the validation messages for it.
+    BulkFailure = Data.define(:item, :errors) do
+      def self.from(hash)
+        new(item: hash.except("errors").values.first,
+            errors: Array(hash["errors"]))
+      end
+    end
+
+    # The outcome of a /v4/bulk call. Small batches are applied synchronously
+    # (200): `items` are the created/affected records as raw Hashes — their
+    # shape is endpoint-specific and partial — and `failures` the rejected
+    # inputs. Batches over Kit's inline threshold are queued (202, empty
+    # body): `async?` is true, `items`/`failures` are empty, and the full
+    # result is POSTed to the request's callback_url when processing ends.
+    BulkResult = Data.define(:items, :failures, :async) do
+      # `key` is the envelope key of the affected records ("subscribers",
+      # "tags", ...), or nil for the delete endpoints, which return failures only.
+      def self.from(status, body, key)
+        body = {} unless body.is_a?(Hash)
+        new(
+          items: key ? Array(body[key]) : [],
+          failures: Array(body["failures"]).map { |failure| BulkFailure.from(failure) },
+          async: status == 202
+        )
+      end
+
+      def async? = async
+
+      # True when Kit applied the batch now and rejected nothing.
+      def success? = !async && failures.empty?
+    end
+  end
+end

data/lib/kit/objects/custom_field.rb

@@ -5,9 +5,11 @@ module Kit
     # A custom field as returned by /v4/custom_fields. `label` is what a creator
     # sets; `key` is the derived attribute used on subscribers (e.g. a `label`
     # of "Last name" yields a `key` of "last_name").
-    CustomField = Data.define(:id, :name, :key, :label) do
+    # `created_at` is returned by the bulk create endpoint only.
+    CustomField = Data.define(:id, :name, :key, :label, :created_at) do
       def self.from(hash)
-        new(id: hash["id"], name: hash["name"], key: hash["key"], label: hash["label"])
+        new(id: hash["id"], name: hash["name"], key: hash["key"], label: hash["label"],
+            created_at: hash["created_at"])
       end
     end
   end

data/lib/kit/objects/post.rb

@@ -4,10 +4,12 @@ module Kit
   module Objects
     # A post (a broadcast published to the web) as returned by /v4/posts.
     # `publication_id` ties it back to the broadcast it was published from.
+    # `content` (the HTML body) is present on a single-post read and on list
+    # reads made with include_content: true; nil otherwise.
     Post = Data.define(
       :id, :publication_id, :created_at, :title, :slug, :description,
       :meta_description, :status, :published_at, :sent_at,
-      :thumbnail_alt, :thumbnail_url, :is_paid, :public_url
+      :thumbnail_alt, :thumbnail_url, :is_paid, :public_url, :content
     ) do
       def self.from(hash)
         new(
@@ -16,7 +18,7 @@ module Kit
           meta_description: hash["meta_description"], status: hash["status"],
           published_at: hash["published_at"], sent_at: hash["sent_at"],
           thumbnail_alt: hash["thumbnail_alt"], thumbnail_url: hash["thumbnail_url"],
-          is_paid: hash["is_paid"], public_url: hash["public_url"]
+          is_paid: hash["is_paid"], public_url: hash["public_url"], content: hash["content"]
         )
       end
     end

data/lib/kit/objects/sequence_email.rb

@@ -5,9 +5,11 @@ module Kit
     # An email within a sequence, as returned by
     # /v4/sequences/:sequence_id/emails. `position` is its order in the sequence;
     # `delay_value`/`delay_unit` set how long after the previous step it sends.
+    # `content` (the HTML body) is present on a single-email read, on
+    # create/update responses, and on list reads with include_content: true.
     SequenceEmail = Data.define(
       :id, :sequence_id, :subject, :preview_text, :email_address, :email_template_id,
-      :published, :position, :delay_value, :delay_unit, :send_days, :stats
+      :published, :position, :delay_value, :delay_unit, :send_days, :content, :stats
     ) do
       def self.from(hash)
         new(
@@ -15,7 +17,8 @@ module Kit
           preview_text: hash["preview_text"], email_address: hash["email_address"],
           email_template_id: hash["email_template_id"], published: hash["published"],
           position: hash["position"], delay_value: hash["delay_value"],
-          delay_unit: hash["delay_unit"], send_days: hash["send_days"], stats: hash["stats"]
+          delay_unit: hash["delay_unit"], send_days: hash["send_days"], content: hash["content"],
+          stats: hash["stats"]
         )
       end
     end

data/lib/kit/objects/subscriber.rb

@@ -4,20 +4,27 @@ module Kit
   module Objects
     # A subscriber as returned by /v4/subscribers. `fields` holds custom-field
     # values; `location` is present on some responses; both are plain Hashes.
+    #
+    # Context fields, nil unless the endpoint supplies them:
+    # - `added_at`, `referrer`, `referrer_utm_parameters` — form/sequence
+    #   subscriber lists (when this subscriber joined through that form/sequence)
+    # - `tagged_at` — a tag's subscriber list
+    # - `attribution`, `tags` — list reads made with include: "attribution,tags"
+    # - `tag_names`, `tag_ids`, `stats` — POST /v4/subscribers/filter
     Subscriber = Data.define(
       :id, :first_name, :email_address, :state,
-      :created_at, :canceled_at, :location, :fields
+      :created_at, :canceled_at, :location, :fields,
+      :added_at, :tagged_at, :referrer, :referrer_utm_parameters,
+      :attribution, :tags, :tag_names, :tag_ids, :stats
     ) do
       def self.from(hash)
         new(
-          id: hash["id"],
-          first_name: hash["first_name"],
-          email_address: hash["email_address"],
-          state: hash["state"],
-          created_at: hash["created_at"],
-          canceled_at: hash["canceled_at"],
-          location: hash["location"],
-          fields: hash["fields"]
+          id: hash["id"], first_name: hash["first_name"], email_address: hash["email_address"],
+          state: hash["state"], created_at: hash["created_at"], canceled_at: hash["canceled_at"],
+          location: hash["location"], fields: hash["fields"],
+          added_at: hash["added_at"], tagged_at: hash["tagged_at"], referrer: hash["referrer"],
+          referrer_utm_parameters: hash["referrer_utm_parameters"], attribution: hash["attribution"],
+          tags: hash["tags"], tag_names: hash["tag_names"], tag_ids: hash["tag_ids"], stats: hash["stats"]
         )
       end
     end

data/lib/kit/objects/tag.rb

@@ -2,14 +2,16 @@
 
 module Kit
   module Objects
-    # A tag as returned by /v4/tags. Fields are all non-nil.
-    Tag = Data.define(:id, :name, :created_at, :subscriber_count) do
+    # A tag as returned by /v4/tags. `tagged_at` is set only when the tag is
+    # read through a subscriber (/v4/subscribers/:id/tags): when it was applied.
+    Tag = Data.define(:id, :name, :created_at, :subscriber_count, :tagged_at) do
       def self.from(hash)
         new(
           id: hash["id"],
           name: hash["name"],
           created_at: hash["created_at"],
-          subscriber_count: hash["subscriber_count"]
+          subscriber_count: hash["subscriber_count"],
+          tagged_at: hash["tagged_at"]
         )
       end
     end

data/lib/kit/objects/webhook_endpoint.rb

@@ -5,16 +5,21 @@ module Kit
     # A webhook endpoint as returned by /v4/webhook_endpoints — the newer signed-
     # delivery model, with a secret that can be rotated. `events` is the list of
     # subscribed event names; `previous_secret_expires_at` is set after a rotate.
+    #
+    # `secret` (the `whsec_`-prefixed signing secret) is present only on the
+    # response to `create` and `rotate_secret` — Kit never returns it again, so
+    # persist it from that object. It is nil on every other read.
     WebhookEndpoint = Data.define(
       :id, :name, :url, :events, :status, :source, :description,
-      :created_by_app, :created_at, :previous_secret_expires_at
+      :created_by_app, :created_at, :previous_secret_expires_at, :secret
     ) do
       def self.from(hash)
         new(
           id: hash["id"], name: hash["name"], url: hash["url"], events: hash["events"],
           status: hash["status"], source: hash["source"], description: hash["description"],
           created_by_app: hash["created_by_app"], created_at: hash["created_at"],
-          previous_secret_expires_at: hash["previous_secret_expires_at"]
+          previous_secret_expires_at: hash["previous_secret_expires_at"],
+          secret: hash["secret"]
         )
       end
     end

data/lib/kit/pagination.rb

@@ -3,17 +3,24 @@
 module Kit
   # The `pagination` object Kit returns alongside every list. Kit uses cursor
   # pagination: to walk forward, pass `after: end_cursor`; backward, `before:
-  # start_cursor`.
+  # start_cursor`. `total_count` is present only when the request asked for it
+  # with `include_total_count: true` (nil otherwise).
   Pagination = Data.define(
-    :has_previous_page, :has_next_page, :start_cursor, :end_cursor, :per_page
+    :has_previous_page, :has_next_page, :start_cursor, :end_cursor, :per_page, :total_count
   ) do
+    # total_count is optional so Pagination.new(...) without it keeps working.
+    def initialize(total_count: nil, **rest)
+      super
+    end
+
     def self.from(hash)
       new(
         has_previous_page: hash["has_previous_page"],
         has_next_page: hash["has_next_page"],
         start_cursor: hash["start_cursor"],
         end_cursor: hash["end_cursor"],
-        per_page: hash["per_page"]
+        per_page: hash["per_page"],
+        total_count: hash["total_count"]
       )
     end
   end
@@ -29,8 +36,23 @@ module Kit
   class Collection
     include Enumerable
 
+    # Query params that must not be carried into a follow-up page request: a
+    # `before` cursor contradicts the `after` we add, and Kit asks that
+    # `include_total_count` be sent on the first page only.
+    FIRST_PAGE_ONLY = %i[before include_total_count].freeze
+
+    # The params for the page after `after`, derived from the original request.
+    def self.next_page_params(params, after)
+      params.reject { |key, _| FIRST_PAGE_ONLY.include?(key.to_sym) }.merge(after: after)
+    end
+
     attr_reader :data, :pagination
 
+    # Kit's total across all pages, when the first request asked for it.
+    def total_count
+      @pagination.total_count
+    end
+
     def initialize(data:, pagination:, &fetch_after)
       @data = data
       @pagination = pagination
@@ -42,6 +64,28 @@ module Kit
       @data.each(&)
     end
 
+    # Size of the current page (not the total across pages — see total_count).
+    def size
+      @data.size
+    end
+    alias length size
+
+    def empty?
+      @data.empty?
+    end
+
+    # Positional access into the current page.
+    def [](index)
+      @data[index]
+    end
+
+    # e.g. #<Kit::Collection[Kit::Objects::Tag] size=2 has_next_page=true total_count=57>
+    def inspect
+      element = @data.first&.class&.name
+      "#<#{self.class.name}#{"[#{element}]" if element} size=#{size} " \
+        "has_next_page=#{@pagination.has_next_page.inspect} total_count=#{total_count.inspect}>"
+    end
+
     # The next Collection, or nil when there is no next page.
     def next_page
       return nil unless @pagination.has_next_page

data/lib/kit/resources/account.rb

@@ -2,8 +2,8 @@
 
 module Kit
   module Resources
-    # The /v4/account endpoints. P0 covers the current-account read; colors,
-    # creator_profile, email_stats, and growth_stats follow in P1/P2.
+    # The /v4/account endpoints: the current account, its colour palette,
+    # creator profile, and account-wide email and growth stats.
     class Account < Base
       # GET /v4/account — current account and user info.
       #
@@ -14,12 +14,12 @@ module Kit
 
       # GET /v4/account/colors — the account's brand color palette (hex strings).
       def colors
-        http_get("/v4/account/colors").fetch("colors")
+        extract(http_get("/v4/account/colors"), "colors")
       end
 
       # PUT /v4/account/colors — replace the palette; returns the saved colors.
       def update_colors(colors)
-        http_put("/v4/account/colors", body: { colors: colors }).fetch("colors")
+        extract(http_put("/v4/account/colors", body: { colors: colors }), "colors")
       end
 
       # GET /v4/account/creator_profile

data/lib/kit/resources/base.rb

@@ -1,17 +1,28 @@
 # frozen_string_literal: true
 
+require "erb"
+
 module Kit
   module Resources
     # Shared base for every resource group. Holds the connection and exposes
     # verb helpers under `http_*` names so a resource can define public methods
     # like `get(id)` or `list` without colliding with the transport helpers.
     class Base
+      # Default for optional body keywords: "not given", as distinct from nil,
+      # which Kit accepts on some fields to clear them (e.g. send_days: nil).
+      OMIT = Object.new.freeze
+
       def initialize(connection)
         @connection = connection
       end
 
       private
 
+      # Drops the keywords the caller did not pass, keeping explicit nils.
+      def given(**attributes)
+        attributes.reject { |_, value| value.equal?(OMIT) }
+      end
+
       # Non-enveloped read (whole body) and list reads go through http_get;
       # deletes return no object and go through http_delete. Enveloped
       # single-object and list responses are built by `one` and `collection`.
@@ -35,13 +46,23 @@ module Kit
         @connection.request(:delete, path, params: params, body: body)
       end
 
+      # Renders an id into a path segment. Kit ids are integers; a String is
+      # accepted but percent-encoded so a value like "1/unsubscribe" cannot
+      # rewrite the route, and nil/blank raises before any request is made
+      # (a blank id would silently hit the parent list endpoint).
+      def path_id(value)
+        raise ArgumentError, "id must not be nil or blank" if value.nil? || value.to_s.strip.empty?
+
+        ERB::Util.url_encode(value.to_s)
+      end
+
       # Sends one request that returns a single wrapped object and builds it.
       # `key` is the envelope key (e.g. "subscriber"), `klass` the object built
       # via `klass.from`. Centralised so a resource never hand-writes the read/
       # build/return plumbing — it declares only verb, path, key, class, body.
       def one(verb, path, key, klass, body: nil, params: {})
         response = @connection.request(verb, path, params: params, body: body)
-        klass.from(response.fetch(key))
+        klass.from(extract(response, key))
       end
 
       # Fetches a cursor-paginated list and wraps it in a Collection whose next
@@ -53,9 +74,30 @@ module Kit
       # endpoints pass verb: :post with a filter body, still paging by cursor.
       def collection(path, key, klass, params, verb: :get, body: nil)
         response = @connection.request(verb, path, params: params, body: body)
-        data = response.fetch(key).map { |element| klass.from(element) }
-        Collection.new(data: data, pagination: Pagination.from(response.fetch("pagination"))) do |after|
-          collection(path, key, klass, params.merge(after: after), verb: verb, body: body)
+        data = extract(response, key).map { |element| klass.from(element) }
+        Collection.new(data: data, pagination: Pagination.from(extract(response, "pagination"))) do |after|
+          collection(path, key, klass, Collection.next_page_params(params, after), verb: verb, body: body)
+        end
+      end
+
+      # Reads `key` from a 2xx body, raising UnexpectedResponseError (a
+      # Kit::Error, so `rescue Kit::Error` still catches it) instead of the bare
+      # KeyError/NoMethodError a drifted or non-JSON response would otherwise
+      # produce deep inside the resource.
+      def extract(response, key)
+        return response.fetch(key) if response.is_a?(Hash) && response.key?(key)
+
+        raise UnexpectedResponseError.new(
+          "expected a JSON object with #{key.inspect} in the response, got #{describe(response)}",
+          body: response
+        )
+      end
+
+      def describe(response)
+        case response
+        when Hash then "keys #{response.keys.inspect}"
+        when nil then "an empty body"
+        else "a #{response.class} body"
         end
       end
     end

data/lib/kit/resources/broadcasts.rb

@@ -12,22 +12,41 @@ module Kit
 
       # GET /v4/broadcasts/:id
       def get(id)
-        one(:get, "/v4/broadcasts/#{id}", "broadcast", Objects::Broadcast)
+        one(:get, "/v4/broadcasts/#{path_id(id)}", "broadcast", Objects::Broadcast)
       end
 
-      # POST /v4/broadcasts
-      def create(**attributes)
-        one(:post, "/v4/broadcasts", "broadcast", Objects::Broadcast, body: attributes)
+      BROADCAST_FIELDS = %i[
+        subject preview_text content description public published_at send_at
+        email_address email_template_id thumbnail_alt thumbnail_url subscriber_filter
+      ].freeze
+
+      # POST /v4/broadcasts. `subscriber_filter` is an array of one group
+      # ({ all: | any: | none: [{ type: "segment"|"tag", ids: [...] }] }); omit
+      # it to send to every subscriber. Timestamps are ISO 8601 (UTC assumed).
+      def create(subject: OMIT, preview_text: OMIT, content: OMIT, description: OMIT, public: OMIT,
+                 published_at: OMIT, send_at: OMIT, email_address: OMIT, email_template_id: OMIT,
+                 thumbnail_alt: OMIT, thumbnail_url: OMIT, subscriber_filter: OMIT)
+        body = given(subject: subject, preview_text: preview_text, content: content, description: description,
+                     public: public, published_at: published_at, send_at: send_at, email_address: email_address,
+                     email_template_id: email_template_id, thumbnail_alt: thumbnail_alt,
+                     thumbnail_url: thumbnail_url, subscriber_filter: subscriber_filter)
+        one(:post, "/v4/broadcasts", "broadcast", Objects::Broadcast, body: body)
       end
 
-      # PUT /v4/broadcasts/:id
-      def update(id, **attributes)
-        one(:put, "/v4/broadcasts/#{id}", "broadcast", Objects::Broadcast, body: attributes)
+      # PUT /v4/broadcasts/:id — same fields as #create; only those passed change.
+      def update(id, subject: OMIT, preview_text: OMIT, content: OMIT, description: OMIT, public: OMIT,
+                 published_at: OMIT, send_at: OMIT, email_address: OMIT, email_template_id: OMIT,
+                 thumbnail_alt: OMIT, thumbnail_url: OMIT, subscriber_filter: OMIT)
+        body = given(subject: subject, preview_text: preview_text, content: content, description: description,
+                     public: public, published_at: published_at, send_at: send_at, email_address: email_address,
+                     email_template_id: email_template_id, thumbnail_alt: thumbnail_alt,
+                     thumbnail_url: thumbnail_url, subscriber_filter: subscriber_filter)
+        one(:put, "/v4/broadcasts/#{path_id(id)}", "broadcast", Objects::Broadcast, body: body)
       end
 
       # DELETE /v4/broadcasts/:id
       def delete(id)
-        http_delete("/v4/broadcasts/#{id}")
+        http_delete("/v4/broadcasts/#{path_id(id)}")
         nil
       end
 
@@ -38,17 +57,17 @@ module Kit
 
       # GET /v4/broadcasts/:id/stats — one broadcast's performance stats.
       def stats(id)
-        one(:get, "/v4/broadcasts/#{id}/stats", "broadcast", Objects::BroadcastStats)
+        one(:get, "/v4/broadcasts/#{path_id(id)}/stats", "broadcast", Objects::BroadcastStats)
       end
 
       # GET /v4/broadcasts/:id/clicks — a cursor-paginated Collection of the
       # broadcast's clicked links. The API nests the array under "broadcast", so
       # this is built directly rather than through Base#collection.
       def clicks(id, **params)
-        body = http_get("/v4/broadcasts/#{id}/clicks", params: params)
-        rows = body.fetch("broadcast").fetch("clicks").map { |row| Objects::BroadcastClick.from(row) }
-        Collection.new(data: rows, pagination: Pagination.from(body.fetch("pagination"))) do |after|
-          clicks(id, **params, after: after)
+        body = http_get("/v4/broadcasts/#{path_id(id)}/clicks", params: params)
+        rows = extract(extract(body, "broadcast"), "clicks").map { |row| Objects::BroadcastClick.from(row) }
+        Collection.new(data: rows, pagination: Pagination.from(extract(body, "pagination"))) do |after|
+          clicks(id, **Collection.next_page_params(params, after))
         end
       end
     end