kit-rb 0.1.0 → 0.3.0

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.1.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

data/lib/kit/webhooks/events.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Kit
+  module Webhooks
+    # Event types a webhook endpoint (/v4/webhook_endpoints) can subscribe to,
+    # as listed at developers.kit.com/webhooks/event-types (verified
+    # 2026-09-06). Use these instead of hand-typed strings:
+    #
+    #   client.webhook_endpoints.create(url: url, events: [Events::SUBSCRIBER_CREATED, Events::TAG_CREATED])
+    #
+    # DATA_KEYS names the keys each event's `data` carries. PLANNED events are
+    # documented but not yet delivered.
+    module Events
+      SUBSCRIBER_CREATED = "subscriber.created"
+      SUBSCRIBER_ACTIVATED = "subscriber.activated"
+      SUBSCRIBER_UNSUBSCRIBED = "subscriber.unsubscribed"
+      SUBSCRIBER_BOUNCED = "subscriber.bounced"
+      SUBSCRIBER_COMPLAINED = "subscriber.complained"
+      SUBSCRIBER_SUBSCRIBED_TO_FORM = "subscriber.subscribed_to_form"
+      SUBSCRIBER_ADDED_TO_SEQUENCE = "subscriber.added_to_sequence"
+      SUBSCRIBER_SEQUENCE_COMPLETED = "subscriber.sequence_completed"
+      SUBSCRIBER_TAG_ADDED = "subscriber.tag_added"
+      SUBSCRIBER_TAG_REMOVED = "subscriber.tag_removed"
+      SUBSCRIBER_CUSTOM_FIELD_VALUE_UPDATED = "subscriber.custom_field_value_updated"
+      SUBSCRIBER_PRODUCT_PURCHASED = "subscriber.product_purchased" # planned
+      SUBSCRIBER_LINK_CLICKED = "subscriber.link_clicked"           # planned
+      SUBSCRIBER_EMAIL_OPENED = "subscriber.email_opened"           # planned
+      TAG_CREATED = "tag.created"
+      TAG_DELETED = "tag.deleted"
+      CUSTOM_FIELD_CREATED = "custom_field.created"
+      CUSTOM_FIELD_DELETED = "custom_field.deleted"
+      SEQUENCE_CREATED = "sequence.created"
+      SEQUENCE_DELETED = "sequence.deleted"
+      SEQUENCE_PUBLISHED = "sequence.published"
+      SEQUENCE_DISABLED = "sequence.disabled"
+      BROADCAST_CREATED = "broadcast.created"
+      BROADCAST_SENT = "broadcast.sent"
+      BROADCAST_DELETED = "broadcast.deleted"
+      POST_PUBLISHED = "post.published"
+      LANDING_PAGE_CREATED = "landing_page.created" # planned
+      LANDING_PAGE_DELETED = "landing_page.deleted" # planned
+
+      DATA_KEYS = {
+        SUBSCRIBER_CREATED => %w[subscriber], SUBSCRIBER_ACTIVATED => %w[subscriber],
+        SUBSCRIBER_UNSUBSCRIBED => %w[subscriber], SUBSCRIBER_BOUNCED => %w[subscriber],
+        SUBSCRIBER_COMPLAINED => %w[subscriber], SUBSCRIBER_SUBSCRIBED_TO_FORM => %w[subscriber form],
+        SUBSCRIBER_ADDED_TO_SEQUENCE => %w[subscriber sequence],
+        SUBSCRIBER_SEQUENCE_COMPLETED => %w[subscriber sequence],
+        SUBSCRIBER_TAG_ADDED => %w[subscriber tag], SUBSCRIBER_TAG_REMOVED => %w[subscriber tag],
+        SUBSCRIBER_CUSTOM_FIELD_VALUE_UPDATED => %w[subscriber custom_field],
+        SUBSCRIBER_PRODUCT_PURCHASED => %w[subscriber], SUBSCRIBER_LINK_CLICKED => %w[subscriber],
+        SUBSCRIBER_EMAIL_OPENED => %w[subscriber],
+        TAG_CREATED => %w[tag], TAG_DELETED => %w[tag],
+        CUSTOM_FIELD_CREATED => %w[custom_field], CUSTOM_FIELD_DELETED => %w[custom_field],
+        SEQUENCE_CREATED => %w[sequence], SEQUENCE_DELETED => %w[sequence],
+        SEQUENCE_PUBLISHED => %w[sequence], SEQUENCE_DISABLED => %w[sequence],
+        BROADCAST_CREATED => %w[broadcast], BROADCAST_SENT => %w[broadcast], BROADCAST_DELETED => %w[broadcast],
+        POST_PUBLISHED => %w[post],
+        LANDING_PAGE_CREATED => [], LANDING_PAGE_DELETED => []
+      }.freeze
+
+      PLANNED = [
+        SUBSCRIBER_PRODUCT_PURCHASED, SUBSCRIBER_LINK_CLICKED, SUBSCRIBER_EMAIL_OPENED,
+        LANDING_PAGE_CREATED, LANDING_PAGE_DELETED
+      ].freeze
+
+      ALL = DATA_KEYS.keys.freeze
+      AVAILABLE = (ALL - PLANNED).freeze
+    end
+
+    # Event names for the previous-generation /v4/webhooks (one event per
+    # webhook, unsigned). Kept for existing integrations; new ones should use
+    # webhook endpoints. REQUIRED_PARAM names the extra key the `event` hash
+    # must carry for the events that are scoped to a resource:
+    #
+    #   client.webhooks.create(target_url: url,
+    #                          event: { name: LegacyEvents::TAG_ADD, tag_id: 12 })
+    module LegacyEvents
+      SUBSCRIBER_ACTIVATE = "subscriber.subscriber_activate"
+      SUBSCRIBER_UNSUBSCRIBE = "subscriber.subscriber_unsubscribe"
+      SUBSCRIBER_BOUNCE = "subscriber.subscriber_bounce"
+      SUBSCRIBER_COMPLAIN = "subscriber.subscriber_complain"
+      FORM_SUBSCRIBE = "subscriber.form_subscribe"
+      COURSE_SUBSCRIBE = "subscriber.course_subscribe"
+      COURSE_COMPLETE = "subscriber.course_complete"
+      LINK_CLICK = "subscriber.link_click"
+      PRODUCT_PURCHASE = "subscriber.product_purchase"
+      TAG_ADD = "subscriber.tag_add"
+      TAG_REMOVE = "subscriber.tag_remove"
+      PURCHASE_CREATE = "purchase.purchase_create"
+      FIELD_CREATED = "custom_field.field_created"
+      FIELD_DELETED = "custom_field.field_deleted"
+      FIELD_VALUE_UPDATED = "custom_field.field_value_updated"
+
+      REQUIRED_PARAM = {
+        FORM_SUBSCRIBE => :form_id,
+        COURSE_SUBSCRIBE => :sequence_id,
+        COURSE_COMPLETE => :sequence_id,
+        LINK_CLICK => :initiator_value,
+        PRODUCT_PURCHASE => :product_id,
+        TAG_ADD => :tag_id,
+        TAG_REMOVE => :tag_id,
+        FIELD_VALUE_UPDATED => :custom_field_id
+      }.freeze
+
+      ALL = [
+        SUBSCRIBER_ACTIVATE, SUBSCRIBER_UNSUBSCRIBE, SUBSCRIBER_BOUNCE, SUBSCRIBER_COMPLAIN,
+        FORM_SUBSCRIBE, COURSE_SUBSCRIBE, COURSE_COMPLETE, LINK_CLICK, PRODUCT_PURCHASE,
+        TAG_ADD, TAG_REMOVE, PURCHASE_CREATE, FIELD_CREATED, FIELD_DELETED, FIELD_VALUE_UPDATED
+      ].freeze
+    end
+  end
+end

data/lib/kit/webhooks/signature.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Kit
+  module Webhooks
+    # Raised when a delivery's X-Kit-Signature is missing, malformed, stale, or
+    # does not match the body under any supplied secret.
+    class SignatureError < Error; end
+
+    # Verifies the `X-Kit-Signature` header Kit sends with every webhook-endpoint
+    # delivery (verified against developers.kit.com/webhooks/verifying-signatures,
+    # 2026-09-06):
+    #
+    #   X-Kit-Signature: t=1753797130,v1=<hex>[,v1=<hex>]
+    #
+    # Each v1 is hex(HMAC-SHA256(secret, "#{t}.#{raw_body}")). During a secret
+    # rotation the header carries two v1 entries (new and previous secret), so
+    # a delivery is valid when any v1 matches any of the secrets you hold.
+    #
+    #   Kit::Webhooks::Signature.verify!(request.raw_post, request.headers["X-Kit-Signature"],
+    #                                    secret: ENV["KIT_WEBHOOK_SECRET"])
+    module Signature
+      HEADER = "X-Kit-Signature"
+      SCHEME = "v1"
+      DEFAULT_TOLERANCE = 300 # seconds; Kit's recommended replay window
+
+      Parsed = Data.define(:timestamp, :signatures)
+
+      # hex(HMAC-SHA256(secret, "t.payload")) — what Kit puts in v1.
+      def self.compute(secret, timestamp, payload)
+        OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{payload}")
+      end
+
+      # Splits the header into its timestamp and v1 signatures. Pairs are kept
+      # as a list, not a Hash: a rotation sends two v1 entries.
+      def self.parse(header)
+        raise SignatureError, "missing #{HEADER} header" if header.nil? || header.strip.empty?
+
+        pairs = header.split(",").map { |pair| pair.strip.split("=", 2) }
+        signatures = pairs.filter_map { |key, value| value if key == SCHEME }
+        raise SignatureError, "malformed #{HEADER} header: #{header.inspect}" if signatures.empty?
+
+        Parsed.new(timestamp: parse_timestamp(pairs, header), signatures: signatures)
+      end
+
+      def self.parse_timestamp(pairs, header)
+        value = pairs.find { |key, _| key == "t" }&.last
+        raise SignatureError, "malformed #{HEADER} header: #{header.inspect}" if value.nil?
+        raise SignatureError, "malformed timestamp in #{HEADER}: #{value.inspect}" unless value.match?(/\A\d+\z/)
+
+        value.to_i
+      end
+      private_class_method :parse_timestamp
+
+      # True when the payload was signed by one of `secret` (a String, or an
+      # Array of Strings while you hold both sides of a rotation) within
+      # `tolerance` seconds of `now`. Constant-time comparison.
+      def self.verify?(payload, header, secret:, tolerance: DEFAULT_TOLERANCE, now: Time.now.to_i)
+        verify!(payload, header, secret: secret, tolerance: tolerance, now: now)
+        true
+      rescue SignatureError
+        false
+      end
+
+      # As #verify?, but raises SignatureError describing why the delivery was
+      # rejected. `payload` must be the raw request body, byte for byte.
+      def self.verify!(payload, header, secret:, tolerance: DEFAULT_TOLERANCE, now: Time.now.to_i)
+        secrets = secrets_from(secret)
+        parsed = parse(header)
+        check_freshness(parsed.timestamp, tolerance, now)
+        return true if secrets.any? { |value| matches?(value, parsed, payload) }
+
+        raise SignatureError, "no #{SCHEME} signature matched the payload"
+      end
+
+      def self.secrets_from(secret)
+        secrets = Array(secret).reject { |value| value.nil? || value.empty? }
+        raise ArgumentError, "at least one webhook secret is required" if secrets.empty?
+
+        secrets
+      end
+      private_class_method :secrets_from
+
+      def self.check_freshness(timestamp, tolerance, now)
+        return unless tolerance
+
+        age = (now - timestamp).abs
+        raise SignatureError, "timestamp outside tolerance (#{age}s > #{tolerance}s)" if age > tolerance
+      end
+      private_class_method :check_freshness
+
+      def self.matches?(secret, parsed, payload)
+        expected = compute(secret, parsed.timestamp, payload)
+        parsed.signatures.any? { |given| OpenSSL.secure_compare(expected, given) }
+      end
+      private_class_method :matches?
+    end
+  end
+end

data/lib/kit-rb.rb

@@ -15,6 +15,7 @@ end
 require "kit/version"
 require "kit/errors"
 require "kit/configuration"
+require "kit/auth/credential"
 require "kit/auth/api_key"
 require "kit/auth/oauth"
 require "kit/connection"
@@ -22,7 +23,6 @@ require "kit/pagination"
 require "kit/oauth/pkce"
 require "kit/oauth/token"
 require "kit/oauth/client"
-require "kit/objects/raw"
 require "kit/objects/account"
 require "kit/objects/creator_profile"
 require "kit/objects/subscriber"
@@ -32,6 +32,11 @@ require "kit/objects/form"
 require "kit/objects/sequence"
 require "kit/objects/sequence_email"
 require "kit/objects/broadcast"
+require "kit/objects/broadcast_stats"
+require "kit/objects/broadcast_click"
+require "kit/objects/subscriber_stats"
+require "kit/objects/email_stats"
+require "kit/objects/growth_stats"
 require "kit/objects/webhook"
 require "kit/objects/webhook_endpoint"
 require "kit/objects/email_template"
@@ -39,6 +44,10 @@ require "kit/objects/segment"
 require "kit/objects/post"
 require "kit/objects/snippet"
 require "kit/objects/purchase"
+require "kit/objects/bulk_result"
+require "kit/webhooks/signature"
+require "kit/webhooks/delivery"
+require "kit/webhooks/events"
 require "kit/resources/base"
 require "kit/resources/account"
 require "kit/resources/subscribers"