kit-rb 0.2.0 → 0.3.0

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,24 +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 — the subscriber's engagement stats.
-      def stats(id)
-        one(:get, "/v4/subscribers/#{id}/stats", "subscriber", Objects::SubscriberStats)
+      # 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

data/lib/kit/resources/webhook_endpoints.rb

@@ -16,7 +16,7 @@ module Kit
 
       # GET /v4/webhook_endpoints/:id
       def get(id)
-        one(:get, "/v4/webhook_endpoints/#{id}", "webhook_endpoint", Objects::WebhookEndpoint)
+        one(:get, "/v4/webhook_endpoints/#{path_id(id)}", "webhook_endpoint", Objects::WebhookEndpoint)
       end
 
       # POST /v4/webhook_endpoints
@@ -25,21 +25,29 @@ module Kit
             body: { url: url, events: events, name: name, description: description }.compact)
       end
 
+      # PATCH /v4/webhook_endpoints/:id — change name/url/description, pause or
+      # resume delivery with status: "active" | "disabled", or replace the
+      # subscribed events (the list given here replaces the whole set).
+      def update(id, name: nil, url: nil, description: nil, status: nil, events: nil)
+        body = { name: name, url: url, description: description, status: status, events: events }.compact
+        one(:patch, "/v4/webhook_endpoints/#{path_id(id)}", "webhook_endpoint", Objects::WebhookEndpoint, body: body)
+      end
+
       # DELETE /v4/webhook_endpoints/:id
       def delete(id)
-        http_delete("/v4/webhook_endpoints/#{id}")
+        http_delete("/v4/webhook_endpoints/#{path_id(id)}")
         nil
       end
 
       # POST /v4/webhook_endpoints/:id/rotate_secret
       def rotate_secret(id, force: nil)
-        one(:post, "/v4/webhook_endpoints/#{id}/rotate_secret", "webhook_endpoint", Objects::WebhookEndpoint,
+        one(:post, "/v4/webhook_endpoints/#{path_id(id)}/rotate_secret", "webhook_endpoint", Objects::WebhookEndpoint,
             body: { force: force }.compact)
       end
 
       # POST /v4/webhook_endpoints/:id/revoke_previous_secret
       def revoke_previous_secret(id)
-        one(:post, "/v4/webhook_endpoints/#{id}/revoke_previous_secret", "webhook_endpoint", Objects::WebhookEndpoint)
+        one(:post, "/v4/webhook_endpoints/#{path_id(id)}/revoke_previous_secret", "webhook_endpoint", Objects::WebhookEndpoint)
       end
     end
   end

data/lib/kit/resources/webhooks.rb

@@ -16,7 +16,7 @@ module Kit
 
       # DELETE /v4/webhooks/:id
       def delete(id)
-        http_delete("/v4/webhooks/#{id}")
+        http_delete("/v4/webhooks/#{path_id(id)}")
         nil
       end
     end

data/lib/kit/version.rb

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

data/lib/kit/webhooks/delivery.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kit
+  module Webhooks
+    # One event inside a delivery. `id` is the deduplication key (deliveries
+    # are retried whole, so the same event can arrive twice); `type` is the
+    # event name (e.g. "subscriber.created"); `created` an ISO 8601 UTC string;
+    # `data` the event-specific payload, keyed by resource ("subscriber",
+    # "tag", ...), left as a Hash because its shape varies per type.
+    Event = Data.define(:id, :type, :created, :data) do
+      def self.from(hash)
+        new(id: hash["id"], type: hash["type"], created: hash["created"], data: hash["data"] || {})
+      end
+    end
+
+    # The JSON envelope a webhook endpoint receives (developers.kit.com/
+    # webhooks/delivery-format, verified 2026-09-06): { delivery_id, events[] }
+    # with 1..100 events of one type, plus the headers X-Kit-Delivery (the same
+    # id), X-Kit-Signature, and User-Agent "Kit-Webhooks/2.0". Answer 2xx to
+    # acknowledge; anything else is retried (8 attempts over ~41 hours).
+    #
+    #   delivery = Kit::Webhooks::Delivery.from_request(
+    #     request.raw_post, request.headers["X-Kit-Signature"], secret: secret
+    #   )
+    #   delivery.events.each { |event| handle(event) unless seen?(event.id) }
+    # The header carrying the delivery id on each request.
+    DELIVERY_HEADER = "X-Kit-Delivery"
+
+    Delivery = Data.define(:delivery_id, :events) do
+      def self.from(hash)
+        new(delivery_id: hash["delivery_id"], events: Array(hash["events"]).map { |event| Event.from(event) })
+      end
+
+      # Parses a raw JSON body. Raises UnexpectedResponseError when it is not
+      # the documented envelope.
+      def self.parse(payload)
+        body = JSON.parse(payload)
+        raise UnexpectedResponseError.new("webhook delivery is not a JSON object", body: body) unless body.is_a?(Hash)
+
+        from(body)
+      rescue JSON::ParserError => e
+        raise UnexpectedResponseError.new("webhook delivery is not valid JSON: #{e.message}", body: payload)
+      end
+
+      # Verifies the signature, then parses. The one call a webhook receiver
+      # needs; a failed check raises SignatureError before any JSON is read.
+      def self.from_request(payload, signature_header, secret:, tolerance: Signature::DEFAULT_TOLERANCE,
+                            now: Time.now.to_i)
+        Signature.verify!(payload, signature_header, secret: secret, tolerance: tolerance, now: now)
+        parse(payload)
+      end
+
+      # Every event in a delivery shares one type.
+      def type
+        events.first&.type
+      end
+    end
+  end
+end