hooksniff 1.1.1 → 1.3.0

data/lib/hooksniff/models/message_in.rb

@@ -63,6 +63,7 @@ module HookSniff
     def self.deserialize(attributes = {})
       attributes = attributes.transform_keys(&:to_s)
       attrs = Hash.new
+      attrs["application"] = HookSniff::ApplicationIn.deserialize(attributes["application"]) if attributes["application"]
       attrs["channels"] = attributes["channels"]
       attrs["deliver_at"] = DateTime.rfc3339(attributes["deliverAt"]).to_time if attributes["deliverAt"]
       attrs["event_id"] = attributes["eventId"]

data/lib/hooksniff/options.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module HookSniff
+  # Configuration options for the HookSniff client.
+  #
+  # @example
+  #   options = HookSniff::Options.new(
+  #     server_url: "https://custom.hooksniff.com",
+  #     timeout: 60,
+  #     debug: true,
+  #     headers: { "X-Custom" => "value" }
+  #   )
+  #   client = HookSniff::HookSniff.new("token", options)
+  class Options
+    attr_accessor :server_url, :timeout, :debug, :headers, :retry_schedule
+
+    def initialize(
+      server_url: nil,
+      timeout: 30,
+      debug: false,
+      headers: {},
+      retry_schedule: [1, 2, 4]
+    )
+      @server_url = server_url
+      @timeout = timeout
+      @debug = debug
+      @headers = headers || {}
+      @retry_schedule = retry_schedule
+    end
+  end
+end

data/lib/hooksniff/paginator.rb

@@ -0,0 +1,45 @@
+# Pagination Helper for HookSniff Ruby SDK.
+#
+# Usage:
+#   hs.message.list_all(limit: 100).each do |msg|
+#     puts msg.id
+#   end
+#
+#   # Or collect all
+#   all_messages = hs.message.list_all(limit: 100).to_a
+
+module HookSniff
+  class Paginator
+    include Enumerable
+
+    def initialize(fetch_page, limit: nil)
+      @fetch_page = fetch_page
+      @limit = limit
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      iterator = nil
+
+      loop do
+        page = @fetch_page.call(limit: @limit, iterator: iterator)
+
+        page.data.each(&block)
+
+        break if page.done || page.iterator.nil? || page.iterator.empty?
+        iterator = page.iterator
+      end
+    end
+
+    # Collect all items into an array
+    def to_a
+      each.to_a
+    end
+
+    # Count all items
+    def count
+      each.count
+    end
+  end
+end

data/lib/hooksniff/response_metadata.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module HookSniff
+  # Response metadata from the last API request.
+  #
+  # Access via +client.last_response+ after any API call.
+  #
+  # @example
+  #   endpoints = client.endpoint.list
+  #   puts client.last_response.request_id
+  #   puts client.last_response.rate_limit_remaining
+  class ResponseMetadata
+    # @return [Integer] HTTP status code
+    attr_reader :status_code
+
+    # @return [String, nil] x-request-id header
+    attr_reader :request_id
+
+    # @return [Integer, nil] x-ratelimit-remaining header
+    attr_reader :rate_limit_remaining
+
+    # @return [Integer, nil] x-ratelimit-reset header (Unix timestamp)
+    attr_reader :rate_limit_reset
+
+    # @return [Hash] All response headers
+    attr_reader :headers
+
+    def initialize(status_code:, request_id: nil, rate_limit_remaining: nil, rate_limit_reset: nil, headers: {})
+      @status_code = status_code
+      @request_id = request_id
+      @rate_limit_remaining = rate_limit_remaining
+      @rate_limit_reset = rate_limit_reset
+      @headers = headers
+    end
+
+    # Create from a Net::HTTP response.
+    def self.from_http_response(response)
+      headers = response.to_hash.transform_values { |v| v.is_a?(Array) ? v.first : v }
+      new(
+        status_code: response.code.to_i,
+        request_id: headers["x-request-id"],
+        rate_limit_remaining: headers["x-ratelimit-remaining"]&.to_i,
+        rate_limit_reset: headers["x-ratelimit-reset"]&.to_i,
+        headers: headers
+      )
+    end
+  end
+end

data/lib/hooksniff/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HookSniff
-  VERSION = "1.1.1"
+  VERSION = "1.3.0"
 end

data/lib/hooksniff/webhook.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
+require "base64"
+require "json"
 
 module HookSniff
+  # Error raised when webhook signature verification fails
+  class WebhookVerificationError < StandardError; end
+  # Error raised when webhook signing fails
+  class WebhookSigningError < StandardError; end
+
   class Webhook
 
     def self.new_using_raw_bytes(secret)
@@ -15,6 +22,15 @@ module HookSniff
       @secret = Base64.decode64(secret)
     end
 
+    # Verify and parse a webhook payload.
+    #
+    # Verifies the HMAC-SHA256 signature, then parses the payload
+    # into a typed WebhookEvent with +event+, +data+, and +timestamp+.
+    #
+    # @param payload [String] raw request body
+    # @param headers [Hash] request headers containing hooksniff-id, hooksniff-timestamp, hooksniff-signature
+    # @return [WebhookEvent] parsed webhook event
+    # @raise [WebhookVerificationError] if signature is invalid or timestamp is outside tolerance
     def verify(payload, headers)
       msgId = headers["hooksniff-id"]
       msgSignature = headers["hooksniff-signature"]
@@ -32,6 +48,45 @@ module HookSniff
 
       _, signature = sign(msgId, msgTimestamp, payload).split(",", 2)
 
+      passedSignatures = msgSignature.split(" ")
+      passedSignatures.each do |versionedSignature|
+        version, expectedSignature = versionedSignature.split(",", 2)
+        if version != "v1"
+          next
+        end
+
+        if ::HookSniff::secure_compare(signature, expectedSignature)
+          return parse_payload(payload)
+        end
+      end
+
+      raise WebhookVerificationError, "No matching signature found"
+    end
+
+    # Verify and return raw payload without parsing.
+    # Use this when you need the raw hash instead of a typed event.
+    #
+    # @param payload [String] raw request body
+    # @param headers [Hash] request headers
+    # @return [Hash, nil] parsed JSON hash
+    # @raise [WebhookVerificationError] if signature is invalid
+    def verify_raw(payload, headers)
+      msgId = headers["hooksniff-id"]
+      msgSignature = headers["hooksniff-signature"]
+      msgTimestamp = headers["hooksniff-timestamp"]
+      if !msgSignature || !msgId || !msgTimestamp
+        msgId = headers["webhook-id"]
+        msgSignature = headers["webhook-signature"]
+        msgTimestamp = headers["webhook-timestamp"]
+        if !msgSignature || !msgId || !msgTimestamp
+          raise WebhookVerificationError, "Missing required headers"
+        end
+      end
+
+      verify_timestamp(msgTimestamp)
+
+      _, signature = sign(msgId, msgTimestamp, payload).split(",", 2)
+
       passedSignatures = msgSignature.split(" ")
       passedSignatures.each do |versionedSignature|
         version, expectedSignature = versionedSignature.split(",", 2)
@@ -80,5 +135,12 @@ module HookSniff
         raise WebhookVerificationError, "Message timestamp too new"
       end
     end
+
+    def parse_payload(payload)
+      return WebhookEvent.new(event: "", data: {}, timestamp: "") if payload.empty?
+
+      parsed = JSON.parse(payload, symbolize_names: true)
+      WebhookEvent.parse(parsed)
+    end
   end
 end

data/lib/hooksniff/webhook_event.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module HookSniff
+  # ─── Event Data Classes ─────────────────────────────────────────
+
+  # Data payload for endpoint.created events.
+  class EndpointCreatedEventData
+    attr_reader :app_id, :endpoint_id, :app_uid
+
+    def initialize(app_id:, endpoint_id:, app_uid: nil)
+      @app_id = app_id
+      @endpoint_id = endpoint_id
+      @app_uid = app_uid
+    end
+  end
+
+  # Data payload for endpoint.updated events.
+  class EndpointUpdatedEventData
+    attr_reader :app_id, :endpoint_id, :app_uid
+
+    def initialize(app_id:, endpoint_id:, app_uid: nil)
+      @app_id = app_id
+      @endpoint_id = endpoint_id
+      @app_uid = app_uid
+    end
+  end
+
+  # Data payload for endpoint.deleted events.
+  class EndpointDeletedEventData
+    attr_reader :app_id, :endpoint_id, :app_uid
+
+    def initialize(app_id:, endpoint_id:, app_uid: nil)
+      @app_id = app_id
+      @endpoint_id = endpoint_id
+      @app_uid = app_uid
+    end
+  end
+
+  # Data payload for endpoint.enabled events.
+  class EndpointEnabledEventData
+    attr_reader :app_id, :endpoint_id, :app_uid
+
+    def initialize(app_id:, endpoint_id:, app_uid: nil)
+      @app_id = app_id
+      @endpoint_id = endpoint_id
+      @app_uid = app_uid
+    end
+  end
+
+  # Data payload for endpoint.disabled events.
+  class EndpointDisabledEventData
+    attr_reader :app_id, :endpoint_id, :app_uid, :fail_since, :trigger
+
+    def initialize(app_id:, endpoint_id:, app_uid: nil, fail_since: nil, trigger: nil)
+      @app_id = app_id
+      @endpoint_id = endpoint_id
+      @app_uid = app_uid
+      @fail_since = fail_since
+      @trigger = trigger
+    end
+  end
+
+  # Info about the last delivery attempt.
+  class LastAttemptInfo
+    attr_reader :id, :timestamp, :response_status_code
+
+    def initialize(id:, timestamp:, response_status_code:)
+      @id = id
+      @timestamp = timestamp
+      @response_status_code = response_status_code
+    end
+  end
+
+  # Info about a delivery attempt.
+  class AttemptInfo
+    attr_reader :id, :timestamp, :response_status_code
+
+    def initialize(id:, timestamp:, response_status_code:)
+      @id = id
+      @timestamp = timestamp
+      @response_status_code = response_status_code
+    end
+  end
+
+  # Data payload for message.attempt.exhausted events.
+  class MessageAttemptExhaustedEventData
+    attr_reader :app_id, :msg_id, :last_attempt, :app_uid
+
+    def initialize(app_id:, msg_id:, last_attempt:, app_uid: nil)
+      @app_id = app_id
+      @msg_id = msg_id
+      @last_attempt = last_attempt
+      @app_uid = app_uid
+    end
+  end
+
+  # Data payload for message.attempt.failing events.
+  class MessageAttemptFailingEventData
+    attr_reader :app_id, :msg_id, :attempt, :app_uid
+
+    def initialize(app_id:, msg_id:, attempt:, app_uid: nil)
+      @app_id = app_id
+      @msg_id = msg_id
+      @attempt = attempt
+      @app_uid = app_uid
+    end
+  end
+
+  # Data payload for message.attempt.recovered events.
+  class MessageAttemptRecoveredEventData
+    attr_reader :app_id, :msg_id, :attempt, :app_uid
+
+    def initialize(app_id:, msg_id:, attempt:, app_uid: nil)
+      @app_id = app_id
+      @msg_id = msg_id
+      @attempt = attempt
+      @app_uid = app_uid
+    end
+  end
+
+  # ─── WebhookEvent (base class — must come before subclasses) ────
+
+  # Represents a parsed webhook event from HookSniff.
+  class WebhookEvent
+    # @return [String] event type name (e.g., "endpoint.created")
+    attr_reader :event
+
+    # @return [Object] event payload data (typed data class or Hash)
+    attr_reader :data
+
+    # @return [String] ISO 8601 timestamp string
+    attr_reader :timestamp
+
+    def initialize(event:, data:, timestamp:)
+      @event = event
+      @data = data
+      @timestamp = timestamp
+    end
+
+    # Alias for +event+ — the event type name.
+    def event_type
+      @event
+    end
+
+    # Get a value from the data (Hash or typed object).
+    def get(key)
+      if @data.is_a?(Hash)
+        @data[key.to_s] || @data[key.to_sym]
+      else
+        @data.respond_to?(key.to_sym) ? @data.send(key.to_sym) : nil
+      end
+    end
+
+    # Access data values with bracket notation (backward compat).
+    def [](key)
+      get(key)
+    end
+
+    # Check if key exists in data.
+    def key?(key)
+      if @data.is_a?(Hash)
+        @data.key?(key.to_s) || @data.key?(key.to_sym)
+      else
+        @data.respond_to?(key.to_sym)
+      end
+    end
+
+    def to_s
+      "#<#{self.class.name} event=#{@event} timestamp=#{@timestamp}>"
+    end
+
+    def inspect
+      to_s
+    end
+
+    # Map of known event types to their classes
+    EVENT_TYPE_MAP = {
+      "endpoint.created" => "EndpointCreatedEvent",
+      "endpoint.updated" => "EndpointUpdatedEvent",
+      "endpoint.deleted" => "EndpointDeletedEvent",
+      "endpoint.enabled" => "EndpointEnabledEvent",
+      "endpoint.disabled" => "EndpointDisabledEvent",
+      "message.attempt.exhausted" => "MessageAttemptExhaustedEvent",
+      "message.attempt.failing" => "MessageAttemptFailingEvent",
+      "message.atattempt.failing" => "MessageAttemptFailingEvent",
+      "message.attempt.recovered" => "MessageAttemptRecoveredEvent",
+      "message.atattempt.recovered" => "MessageAttemptRecoveredEvent",
+    }.freeze
+
+    # Parse a webhook payload hash into a typed WebhookEvent.
+    def self.parse(data)
+      event_type = data[:event] || data["event"] || data[:eventType] || data["eventType"] || ""
+      raw_data = data[:data] || data["data"] || {}
+      timestamp = data[:timestamp] || data["timestamp"] || ""
+
+      parsed_data = parse_event_data(event_type, raw_data)
+      class_name = EVENT_TYPE_MAP[event_type]
+      event_class = class_name ? const_get(class_name) : WebhookEvent
+
+      event_class.new(event: event_type, data: parsed_data, timestamp: timestamp)
+    end
+
+    private
+
+    def self.parse_event_data(event_type, raw)
+      case event_type
+      when "endpoint.created"
+        EndpointCreatedEventData.new(
+          app_id: raw[:appId] || raw["appId"] || raw[:app_id] || raw["app_id"] || "",
+          endpoint_id: raw[:endpointId] || raw["endpointId"] || raw[:endpoint_id] || raw["endpoint_id"] || "",
+          app_uid: raw[:appUid] || raw["appUid"] || raw[:app_uid] || raw["app_uid"]
+        )
+      when "endpoint.updated"
+        EndpointUpdatedEventData.new(
+          app_id: raw[:appId] || raw["appId"] || raw[:app_id] || raw["app_id"] || "",
+          endpoint_id: raw[:endpointId] || raw["endpointId"] || raw[:endpoint_id] || raw["endpoint_id"] || "",
+          app_uid: raw[:appUid] || raw["appUid"] || raw[:app_uid] || raw["app_uid"]
+        )
+      when "endpoint.deleted"
+        EndpointDeletedEventData.new(
+          app_id: raw[:appId] || raw["appId"] || raw[:app_id] || raw["app_id"] || "",
+          endpoint_id: raw[:endpointId] || raw["endpointId"] || raw[:endpoint_id] || raw["endpoint_id"] || "",
+          app_uid: raw[:appUid] || raw["appUid"] || raw[:app_uid] || raw["app_uid"]
+        )
+      when "endpoint.enabled"
+        EndpointEnabledEventData.new(
+          app_id: raw[:appId] || raw["appId"] || raw[:app_id] || raw["app_id"] || "",
+          endpoint_id: raw[:endpointId] || raw["endpointId"] || raw[:endpoint_id] || raw["endpoint_id"] || "",
+          app_uid: raw[:appUid] || raw["appUid"] || raw[:app_uid] || raw["app_uid"]
+        )
+      when "endpoint.disabled"
+        EndpointDisabledEventData.new(
+          app_id: raw[:appId] || raw["appId"] || raw[:app_id] || raw["app_id"] || "",
+          endpoint_id: raw[:endpointId] || raw["endpointId"] || raw[:endpoint_id] || raw["endpoint_id"] || "",
+          app_uid: raw[:appUid] || raw["appUid"] || raw[:app_uid] || raw["app_uid"],
+          fail_since: raw[:failSince] || raw["failSince"] || raw[:fail_since] || raw["fail_since"],
+          trigger: raw[:trigger] || raw["trigger"]
+        )
+      when "message.attempt.exhausted"
+        last_raw = raw[:lastAttempt] || raw["lastAttempt"] || raw[:last_attempt] || raw["last_attempt"] || {}
+        MessageAttemptExhaustedEventData.new(
+          app_id: raw[:appId] || raw["appId"] || raw[:app_id] || raw["app_id"] || "",
+          msg_id: raw[:msgId] || raw["msgId"] || raw[:msg_id] || raw["msg_id"] || "",
+          last_attempt: parse_last_attempt(last_raw),
+          app_uid: raw[:appUid] || raw["appUid"] || raw[:app_uid] || raw["app_uid"]
+        )
+      when "message.attempt.failing", "message.atattempt.failing"
+        attempt_raw = raw[:attempt] || raw["attempt"] || {}
+        MessageAttemptFailingEventData.new(
+          app_id: raw[:appId] || raw["appId"] || raw[:app_id] || raw["app_id"] || "",
+          msg_id: raw[:msgId] || raw["msgId"] || raw[:msg_id] || raw["msg_id"] || "",
+          attempt: parse_attempt(attempt_raw),
+          app_uid: raw[:appUid] || raw["appUid"] || raw[:app_uid] || raw["app_uid"]
+        )
+      when "message.atattempt.recovered", "message.attempt.recovered"
+        attempt_raw = raw[:attempt] || raw["attempt"] || {}
+        MessageAttemptRecoveredEventData.new(
+          app_id: raw[:appId] || raw["appId"] || raw[:app_id] || raw["app_id"] || "",
+          msg_id: raw[:msgId] || raw["msgId"] || raw[:msg_id] || raw["msg_id"] || "",
+          attempt: parse_attempt(attempt_raw),
+          app_uid: raw[:appUid] || raw["appUid"] || raw[:app_uid] || raw["app_uid"]
+        )
+      else
+        raw
+      end
+    end
+
+    def self.parse_last_attempt(raw)
+      LastAttemptInfo.new(
+        id: raw[:id] || raw["id"] || "",
+        timestamp: raw[:timestamp] || raw["timestamp"] || "",
+        response_status_code: raw[:responseStatusCode] || raw["responseStatusCode"] || raw[:response_status_code] || raw["response_status_code"] || 0
+      )
+    end
+
+    def self.parse_attempt(raw)
+      AttemptInfo.new(
+        id: raw[:id] || raw["id"] || "",
+        timestamp: raw[:timestamp] || raw["timestamp"] || "",
+        response_status_code: raw[:responseStatusCode] || raw["responseStatusCode"] || raw[:response_status_code] || raw["response_status_code"] || 0
+      )
+    end
+  end
+
+  # ─── Typed Event Subclasses ─────────────────────────────────────
+
+  class EndpointCreatedEvent < WebhookEvent; end
+  class EndpointUpdatedEvent < WebhookEvent; end
+  class EndpointDeletedEvent < WebhookEvent; end
+  class EndpointEnabledEvent < WebhookEvent; end
+  class EndpointDisabledEvent < WebhookEvent; end
+  class MessageAttemptExhaustedEvent < WebhookEvent; end
+  class MessageAttemptFailingEvent < WebhookEvent; end
+  class MessageAttemptRecoveredEvent < WebhookEvent; end
+end