kit-rb 0.1.0 → 0.3.0

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,40 +12,63 @@ 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
 
-      # GET /v4/broadcasts/stats — a cursor-paginated list of per-broadcast stats
-      # ({ "id", "stats", "subject", "send_at" } hashes), not full broadcasts.
+      # GET /v4/broadcasts/stats — a cursor-paginated list of per-broadcast stats.
       def stats_list(**params)
-        collection("/v4/broadcasts/stats", "broadcasts", Objects::Raw, params)
+        collection("/v4/broadcasts/stats", "broadcasts", Objects::BroadcastStats, params)
       end
 
-      # GET /v4/broadcasts/:id/stats — the raw stats hash for one broadcast.
+      # GET /v4/broadcasts/:id/stats — one broadcast's performance stats.
       def stats(id)
-        http_get("/v4/broadcasts/#{id}/stats").fetch("broadcast")
+        one(:get, "/v4/broadcasts/#{path_id(id)}/stats", "broadcast", Objects::BroadcastStats)
       end
 
-      # GET /v4/broadcasts/:id/clicks — the raw link-click report ({ "id",
-      # "clicks" => [...] }); accepts pagination params.
+      # 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)
-        http_get("/v4/broadcasts/#{id}/clicks", params: params).fetch("broadcast")
+        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
   end

data/lib/kit/resources/bulk.rb

@@ -3,60 +3,58 @@
 module Kit
   module Resources
     # The /v4/bulk endpoints — batch operations that all require OAuth. Each call
-    # takes an array of items and an optional callback_url, and returns the raw
-    # result hash: the created/affected items under their resource key plus a
-    # "failures" array. Large batches are processed asynchronously and reported
-    # to callback_url; the response still carries whatever completed inline.
+    # takes an array of items and an optional callback_url and returns a
+    # BulkResult: the affected records under `items`, the rejected inputs under
+    # `failures`, and `async?` when Kit queued the batch (202) and will report
+    # the outcome to callback_url instead.
     class Bulk < Base
       # POST /v4/bulk/subscribers
       def create_subscribers(subscribers, callback_url: nil)
-        post("/v4/bulk/subscribers", subscribers: subscribers, callback_url: callback_url)
+        bulk(:post, "/v4/bulk/subscribers", "subscribers", subscribers: subscribers, callback_url: callback_url)
       end
 
       # POST /v4/bulk/custom_fields
       def create_custom_fields(custom_fields, callback_url: nil)
-        post("/v4/bulk/custom_fields", custom_fields: custom_fields, callback_url: callback_url)
+        bulk(:post, "/v4/bulk/custom_fields", "custom_fields",
+             custom_fields: custom_fields, callback_url: callback_url)
       end
 
       # POST /v4/bulk/custom_fields/subscribers
       def update_custom_field_values(custom_field_values, callback_url: nil)
-        post("/v4/bulk/custom_fields/subscribers",
+        bulk(:post, "/v4/bulk/custom_fields/subscribers", "custom_field_values",
              custom_field_values: custom_field_values, callback_url: callback_url)
       end
 
       # POST /v4/bulk/forms/subscribers
       def add_subscribers_to_forms(additions, callback_url: nil)
-        post("/v4/bulk/forms/subscribers", additions: additions, callback_url: callback_url)
+        bulk(:post, "/v4/bulk/forms/subscribers", "subscribers", additions: additions, callback_url: callback_url)
       end
 
       # POST /v4/bulk/tags
       def create_tags(tags, callback_url: nil)
-        post("/v4/bulk/tags", tags: tags, callback_url: callback_url)
+        bulk(:post, "/v4/bulk/tags", "tags", tags: tags, callback_url: callback_url)
       end
 
-      # DELETE /v4/bulk/tags
+      # DELETE /v4/bulk/tags — returns failures only.
       def delete_tags(tags, callback_url: nil)
-        delete("/v4/bulk/tags", tags: tags, callback_url: callback_url)
+        bulk(:delete, "/v4/bulk/tags", nil, tags: tags, callback_url: callback_url)
       end
 
       # POST /v4/bulk/tags/subscribers
       def tag_subscribers(taggings, callback_url: nil)
-        post("/v4/bulk/tags/subscribers", taggings: taggings, callback_url: callback_url)
+        bulk(:post, "/v4/bulk/tags/subscribers", "subscribers", taggings: taggings, callback_url: callback_url)
       end
 
-      # DELETE /v4/bulk/tags/subscribers
+      # DELETE /v4/bulk/tags/subscribers — returns failures only.
       def remove_tag_subscribers(taggings, callback_url: nil)
-        delete("/v4/bulk/tags/subscribers", taggings: taggings, callback_url: callback_url)
+        bulk(:delete, "/v4/bulk/tags/subscribers", nil, taggings: taggings, callback_url: callback_url)
       end
 
       private
 
-      def post(path, **body)
-        http_post(path, body: body.compact)
-      end
-
-      def delete(path, **body)
-        http_delete(path, body: body.compact)
+      def bulk(verb, path, key, **body)
+        status, response = @connection.request_with_status(verb, path, body: body.compact)
+        Objects::BulkResult.from(status, response, key)
       end
     end
   end

data/lib/kit/resources/custom_fields.rb

@@ -16,12 +16,12 @@ module Kit
 
       # PUT /v4/custom_fields/:id
       def update(id, label:)
-        one(:put, "/v4/custom_fields/#{id}", "custom_field", Objects::CustomField, body: { label: label })
+        one(:put, "/v4/custom_fields/#{path_id(id)}", "custom_field", Objects::CustomField, body: { label: label })
       end
 
       # DELETE /v4/custom_fields/:id
       def delete(id)
-        http_delete("/v4/custom_fields/#{id}")
+        http_delete("/v4/custom_fields/#{path_id(id)}")
         nil
       end
     end

data/lib/kit/resources/forms.rb

@@ -12,18 +12,18 @@ module Kit
 
       # GET /v4/forms/:form_id/subscribers
       def subscribers(form_id, **params)
-        collection("/v4/forms/#{form_id}/subscribers", "subscribers", Objects::Subscriber, params)
+        collection("/v4/forms/#{path_id(form_id)}/subscribers", "subscribers", Objects::Subscriber, params)
       end
 
       # POST /v4/forms/:form_id/subscribers/:subscriber_id
       def add_subscriber(form_id, subscriber_id, referrer: nil)
-        one(:post, "/v4/forms/#{form_id}/subscribers/#{subscriber_id}", "subscriber",
+        one(:post, "/v4/forms/#{path_id(form_id)}/subscribers/#{path_id(subscriber_id)}", "subscriber",
             Objects::Subscriber, body: { referrer: referrer }.compact)
       end
 
       # POST /v4/forms/:form_id/subscribers
       def add_subscriber_by_email(form_id, email_address:, referrer: nil)
-        one(:post, "/v4/forms/#{form_id}/subscribers", "subscriber", Objects::Subscriber,
+        one(:post, "/v4/forms/#{path_id(form_id)}/subscribers", "subscriber", Objects::Subscriber,
             body: { email_address: email_address, referrer: referrer }.compact)
       end
     end

data/lib/kit/resources/posts.rb

@@ -11,7 +11,7 @@ module Kit
 
       # GET /v4/posts/:id
       def get(id)
-        one(:get, "/v4/posts/#{id}", "post", Objects::Post)
+        one(:get, "/v4/posts/#{path_id(id)}", "post", Objects::Post)
       end
     end
   end

data/lib/kit/resources/purchases.rb

@@ -12,14 +12,18 @@ module Kit
 
       # GET /v4/purchases/:id
       def get(id)
-        one(:get, "/v4/purchases/#{id}", "purchase", Objects::Purchase)
+        one(:get, "/v4/purchases/#{path_id(id)}", "purchase", Objects::Purchase)
       end
 
-      # POST /v4/purchases — the request wraps the fields under a "purchase" key.
-      # Pass email_address/transaction_id/status/currency/transaction_time,
-      # the monetary totals, and a products array.
-      def create(**attributes)
-        one(:post, "/v4/purchases", "purchase", Objects::Purchase, body: { purchase: attributes })
+      # POST /v4/purchases — the request wraps the fields under a "purchase"
+      # key. The spec marks every field required; `products` is an array of
+      # { name, pid, lid, quantity, unit_price, sku }.
+      def create(email_address:, transaction_id:, status:, currency:, transaction_time: OMIT, subtotal: OMIT,
+                 tax: OMIT, shipping: OMIT, discount: OMIT, total: OMIT, products: OMIT)
+        purchase = given(email_address: email_address, transaction_id: transaction_id, status: status,
+                         currency: currency, transaction_time: transaction_time, subtotal: subtotal, tax: tax,
+                         shipping: shipping, discount: discount, total: total, products: products)
+        one(:post, "/v4/purchases", "purchase", Objects::Purchase, body: { purchase: purchase })
       end
     end
   end

data/lib/kit/resources/sequences.rb

@@ -10,67 +10,91 @@ module Kit
         collection("/v4/sequences", "sequences", Objects::Sequence, params)
       end
 
-      # GET /v4/sequences/:id
-      def get(id)
-        one(:get, "/v4/sequences/#{id}", "sequence", Objects::Sequence)
+      # GET /v4/sequences/:id — pass include: "stats" to embed the sequence's
+      # performance stats.
+      def get(id, include: nil)
+        one(:get, "/v4/sequences/#{path_id(id)}", "sequence", Objects::Sequence, params: { include: include }.compact)
       end
 
       # GET /v4/sequences/:sequence_id/subscribers
       def subscribers(sequence_id, **params)
-        collection("/v4/sequences/#{sequence_id}/subscribers", "subscribers", Objects::Subscriber, params)
+        collection("/v4/sequences/#{path_id(sequence_id)}/subscribers", "subscribers", Objects::Subscriber, params)
       end
 
-      # POST /v4/sequences
-      def create(name:, **attributes)
-        one(:post, "/v4/sequences", "sequence", Objects::Sequence, body: { name: name }.merge(attributes))
+      # POST /v4/sequences. `send_days` is an array of weekday names,
+      # `send_hour` 0–23, `time_zone` an IANA name; `exclude_subscriber_sources`
+      # is [{ type: "tag"|"sequence"|"form"|"segment", ids: [...] }].
+      def create(name:, email_address: OMIT, email_template_id: OMIT, send_days: OMIT, send_hour: OMIT,
+                 time_zone: OMIT, active: OMIT, repeat: OMIT, hold: OMIT, exclude_subscriber_sources: OMIT)
+        body = given(name: name, email_address: email_address, email_template_id: email_template_id,
+                     send_days: send_days, send_hour: send_hour, time_zone: time_zone, active: active,
+                     repeat: repeat, hold: hold, exclude_subscriber_sources: exclude_subscriber_sources)
+        one(:post, "/v4/sequences", "sequence", Objects::Sequence, body: body)
       end
 
-      # PUT /v4/sequences/:id
-      def update(id, **attributes)
-        one(:put, "/v4/sequences/#{id}", "sequence", Objects::Sequence, body: attributes)
+      # PUT /v4/sequences/:id — same fields as #create; only those passed change.
+      def update(id, name: OMIT, email_address: OMIT, email_template_id: OMIT, send_days: OMIT, send_hour: OMIT,
+                 time_zone: OMIT, active: OMIT, repeat: OMIT, hold: OMIT, exclude_subscriber_sources: OMIT)
+        body = given(name: name, email_address: email_address, email_template_id: email_template_id,
+                     send_days: send_days, send_hour: send_hour, time_zone: time_zone, active: active,
+                     repeat: repeat, hold: hold, exclude_subscriber_sources: exclude_subscriber_sources)
+        one(:put, "/v4/sequences/#{path_id(id)}", "sequence", Objects::Sequence, body: body)
       end
 
       # DELETE /v4/sequences/:id
       def delete(id)
-        http_delete("/v4/sequences/#{id}")
+        http_delete("/v4/sequences/#{path_id(id)}")
         nil
       end
 
       # POST /v4/sequences/:sequence_id/subscribers/:subscriber_id
       def add_subscriber(sequence_id, subscriber_id)
-        one(:post, "/v4/sequences/#{sequence_id}/subscribers/#{subscriber_id}", "subscriber", Objects::Subscriber)
+        one(:post, "/v4/sequences/#{path_id(sequence_id)}/subscribers/#{path_id(subscriber_id)}", "subscriber", Objects::Subscriber)
       end
 
       # POST /v4/sequences/:sequence_id/subscribers
       def add_subscriber_by_email(sequence_id, email_address:)
-        one(:post, "/v4/sequences/#{sequence_id}/subscribers", "subscriber", Objects::Subscriber,
+        one(:post, "/v4/sequences/#{path_id(sequence_id)}/subscribers", "subscriber", Objects::Subscriber,
             body: { email_address: email_address })
       end
 
       # GET /v4/sequences/:sequence_id/emails
       def emails(sequence_id, **params)
-        collection("/v4/sequences/#{sequence_id}/emails", "emails", Objects::SequenceEmail, params)
+        collection("/v4/sequences/#{path_id(sequence_id)}/emails", "emails", Objects::SequenceEmail, params)
       end
 
-      # GET /v4/sequences/:sequence_id/emails/:id
-      def email(sequence_id, id)
-        one(:get, "/v4/sequences/#{sequence_id}/emails/#{id}", "email", Objects::SequenceEmail)
+      # GET /v4/sequences/:sequence_id/emails/:id — include: "stats" embeds the
+      # email's performance stats.
+      def email(sequence_id, id, include: nil)
+        one(:get, "/v4/sequences/#{path_id(sequence_id)}/emails/#{path_id(id)}", "email", Objects::SequenceEmail,
+            params: { include: include }.compact)
       end
 
-      # POST /v4/sequences/:sequence_id/emails — subject/delay_value/delay_unit
-      # are required; content/position/send_days and the rest are optional.
-      def create_email(sequence_id, **attributes)
-        one(:post, "/v4/sequences/#{sequence_id}/emails", "email", Objects::SequenceEmail, body: attributes)
+      # POST /v4/sequences/:sequence_id/emails. `delay_unit` is "days" or
+      # "hours"; `send_days` nil resets to all seven days; `position` is
+      # zero-based and defaults to last.
+      def create_email(sequence_id, subject:, delay_value:, delay_unit:, preview_text: OMIT, content: OMIT,
+                       email_template_id: OMIT, published: OMIT, send_days: OMIT, position: OMIT)
+        body = given(subject: subject, delay_value: delay_value, delay_unit: delay_unit, preview_text: preview_text,
+                     content: content, email_template_id: email_template_id, published: published,
+                     send_days: send_days, position: position)
+        one(:post, "/v4/sequences/#{path_id(sequence_id)}/emails", "email", Objects::SequenceEmail, body: body)
       end
 
-      # PUT /v4/sequences/:sequence_id/emails/:id
-      def update_email(sequence_id, id, **attributes)
-        one(:put, "/v4/sequences/#{sequence_id}/emails/#{id}", "email", Objects::SequenceEmail, body: attributes)
+      # PUT /v4/sequences/:sequence_id/emails/:id — only the fields passed
+      # change; pass nil for email_template_id or send_days to clear them.
+      def update_email(sequence_id, id, subject: OMIT, delay_value: OMIT, delay_unit: OMIT, preview_text: OMIT,
+                       content: OMIT, email_template_id: OMIT, published: OMIT, send_days: OMIT, position: OMIT)
+        body = given(subject: subject, delay_value: delay_value, delay_unit: delay_unit, preview_text: preview_text,
+                     content: content, email_template_id: email_template_id, published: published,
+                     send_days: send_days, position: position)
+        one(:put, "/v4/sequences/#{path_id(sequence_id)}/emails/#{path_id(id)}", "email", Objects::SequenceEmail,
+            body: body)
       end
 
       # DELETE /v4/sequences/:sequence_id/emails/:id
       def delete_email(sequence_id, id)
-        http_delete("/v4/sequences/#{sequence_id}/emails/#{id}")
+        http_delete("/v4/sequences/#{path_id(sequence_id)}/emails/#{path_id(id)}")
         nil
       end
     end

data/lib/kit/resources/snippets.rb

@@ -11,18 +11,23 @@ module Kit
 
       # GET /v4/snippets/:id
       def get(id)
-        one(:get, "/v4/snippets/#{id}", "snippet", Objects::Snippet)
+        one(:get, "/v4/snippets/#{path_id(id)}", "snippet", Objects::Snippet)
       end
 
-      # POST /v4/snippets — pass name/snippet_type and content (inline) or
-      # document (document); the API validates the combination.
-      def create(**attributes)
-        one(:post, "/v4/snippets", "snippet", Objects::Snippet, body: attributes)
+      # POST /v4/snippets. An "inline" snippet carries Liquid text in
+      # `content`; a "block" snippet carries HTML in
+      # `document_attributes: { value_html: ... }`.
+      def create(name:, snippet_type:, content: OMIT, document_attributes: OMIT)
+        body = given(name: name, snippet_type: snippet_type, content: content,
+                     document_attributes: document_attributes)
+        one(:post, "/v4/snippets", "snippet", Objects::Snippet, body: body)
       end
 
-      # PUT /v4/snippets/:id
-      def update(id, **attributes)
-        one(:put, "/v4/snippets/#{id}", "snippet", Objects::Snippet, body: attributes)
+      # PUT /v4/snippets/:id — rename, archive/restore, or replace the content
+      # (snippet_type cannot change).
+      def update(id, name: OMIT, archived: OMIT, content: OMIT, document_attributes: OMIT)
+        body = given(name: name, archived: archived, content: content, document_attributes: document_attributes)
+        one(:put, "/v4/snippets/#{path_id(id)}", "snippet", Objects::Snippet, body: body)
       end
     end
   end

data/lib/kit/resources/subscribers.rb

@@ -13,7 +13,7 @@ module Kit
 
       # GET /v4/subscribers/:id
       def get(id)
-        one(:get, "/v4/subscribers/#{id}", "subscriber", Objects::Subscriber)
+        one(:get, "/v4/subscribers/#{path_id(id)}", "subscriber", Objects::Subscriber)
       end
 
       # POST /v4/subscribers — email_address required; first_name, state, fields optional.
@@ -26,12 +26,17 @@ module Kit
       # PUT /v4/subscribers/:id
       def update(id, first_name: nil, email_address: nil, fields: nil)
         body = { first_name: first_name, email_address: email_address, fields: fields }.compact
-        one(:put, "/v4/subscribers/#{id}", "subscriber", Objects::Subscriber, body: body)
+        one(:put, "/v4/subscribers/#{path_id(id)}", "subscriber", Objects::Subscriber, body: body)
       end
 
-      # POST /v4/subscribers/:id/unsubscribe
+      # POST /v4/subscribers/:id/unsubscribe — the API answers 204 with no body,
+      # so this returns nil. Should Kit ever echo the subscriber back, it is
+      # returned as a Subscriber instead of being discarded.
       def unsubscribe(id)
-        one(:post, "/v4/subscribers/#{id}/unsubscribe", "subscriber", Objects::Subscriber)
+        body = http_post("/v4/subscribers/#{path_id(id)}/unsubscribe")
+        return nil unless body.is_a?(Hash) && body.key?("subscriber")
+
+        Objects::Subscriber.from(body.fetch("subscriber"))
       end
 
       # POST /v4/subscribers/filter — the same filters as #list, sent in the
@@ -42,25 +47,33 @@ module Kit
 
       # GET /v4/subscribers/:id/tags — the tags applied to a subscriber.
       def tags(id, **params)
-        collection("/v4/subscribers/#{id}/tags", "tags", Objects::Tag, params)
+        collection("/v4/subscribers/#{path_id(id)}/tags", "tags", Objects::Tag, params)
       end
 
-      # GET /v4/subscribers/:id/stats — engagement stats. Returns the raw
-      # `subscriber` hash ({ "id" => ..., "stats" => { ... } }).
-      def stats(id)
-        http_get("/v4/subscribers/#{id}/stats").fetch("subscriber")
+      # GET /v4/subscribers/:id/stats — the subscriber's engagement stats.
+      # Bound the window with email_sent_after / email_sent_before (yyyy-mm-dd).
+      def stats(id, email_sent_after: nil, email_sent_before: nil)
+        params = { email_sent_after: email_sent_after, email_sent_before: email_sent_before }.compact
+        one(:get, "/v4/subscribers/#{path_id(id)}/stats", "subscriber", Objects::SubscriberStats, params: params)
       end
 
       # POST /v4/subscribers/:id/location — set the subscriber's location
       # (a hash of city/state_province/country_code/latitude/longitude/timezone).
       def set_location(id, location:)
-        one(:post, "/v4/subscribers/#{id}/location", "subscriber", Objects::Subscriber,
+        one(:post, "/v4/subscribers/#{path_id(id)}/location", "subscriber", Objects::Subscriber,
+            body: { location: location })
+      end
+
+      # PATCH /v4/subscribers/:id/location — replace a pinned location. Kit
+      # requires the full location (all six keys) on update, not a partial.
+      def update_location(id, location:)
+        one(:patch, "/v4/subscribers/#{path_id(id)}/location", "subscriber", Objects::Subscriber,
             body: { location: location })
       end
 
       # DELETE /v4/subscribers/:id/location
       def remove_location(id)
-        http_delete("/v4/subscribers/#{id}/location")
+        http_delete("/v4/subscribers/#{path_id(id)}/location")
         nil
       end
     end

data/lib/kit/resources/tags.rb

@@ -16,36 +16,36 @@ module Kit
 
       # PUT /v4/tags/:id
       def update(id, name:)
-        one(:put, "/v4/tags/#{id}", "tag", Objects::Tag, body: { name: name })
+        one(:put, "/v4/tags/#{path_id(id)}", "tag", Objects::Tag, body: { name: name })
       end
 
       # POST /v4/tags/:tag_id/subscribers/:id
       def tag_subscriber(tag_id, subscriber_id)
-        one(:post, "/v4/tags/#{tag_id}/subscribers/#{subscriber_id}", "subscriber", Objects::Subscriber)
+        one(:post, "/v4/tags/#{path_id(tag_id)}/subscribers/#{path_id(subscriber_id)}", "subscriber", Objects::Subscriber)
       end
 
       # DELETE /v4/tags/:tag_id/subscribers/:id
       def remove_subscriber(tag_id, subscriber_id)
-        http_delete("/v4/tags/#{tag_id}/subscribers/#{subscriber_id}")
+        http_delete("/v4/tags/#{path_id(tag_id)}/subscribers/#{path_id(subscriber_id)}")
         nil
       end
 
       # POST /v4/tags/:tag_id/subscribers — tag a subscriber by email address.
       def tag_subscriber_by_email(tag_id, email_address:)
-        one(:post, "/v4/tags/#{tag_id}/subscribers", "subscriber", Objects::Subscriber,
+        one(:post, "/v4/tags/#{path_id(tag_id)}/subscribers", "subscriber", Objects::Subscriber,
             body: { email_address: email_address })
       end
 
       # DELETE /v4/tags/:tag_id/subscribers — remove a tag from a subscriber by
       # email address (passed as a query parameter).
       def remove_subscriber_by_email(tag_id, email_address:)
-        http_delete("/v4/tags/#{tag_id}/subscribers", params: { email_address: email_address })
+        http_delete("/v4/tags/#{path_id(tag_id)}/subscribers", params: { email_address: email_address })
         nil
       end
 
       # GET /v4/tags/:tag_id/subscribers
       def subscribers(tag_id, **params)
-        collection("/v4/tags/#{tag_id}/subscribers", "subscribers", Objects::Subscriber, params)
+        collection("/v4/tags/#{path_id(tag_id)}/subscribers", "subscribers", Objects::Subscriber, params)
       end
     end
   end