openemail 0.0.1

data/lib/openemail/resources/webhooks.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module OpenEmail
+  module Resources
+    class Webhooks < Resource
+      def list(limit: nil, cursor: nil, api_key: nil)
+        fetch_page(ApiPaths::WEBHOOKS, limit:, cursor:, api_key:)
+      end
+
+      def list_all(limit: nil, cursor: nil, api_key: nil)
+        collect_all(ApiPaths::WEBHOOKS, limit:, cursor:, api_key:)
+      end
+
+      def iterate(limit: nil, cursor: nil, api_key: nil, &)
+        iterate_pages(ApiPaths::WEBHOOKS, limit:, cursor:, api_key:, &)
+      end
+
+      def get(id, api_key: nil)
+        request(fill(ApiPaths::WEBHOOK, id:), api_key:)
+      end
+
+      def create(body = nil, api_key: nil, **fields)
+        request(ApiPaths::WEBHOOKS, method: :post, body: payload(body, fields), api_key:)
+      end
+
+      def update(id, patch = nil, api_key: nil, **fields)
+        request(fill(ApiPaths::WEBHOOK, id:), method: :patch, body: payload(patch, fields), repeatable: true, api_key:)
+      end
+
+      def delete(id, api_key: nil)
+        request(fill(ApiPaths::WEBHOOK, id:), method: :delete, api_key:)
+      end
+
+      def rotate_secret(id, api_key: nil)
+        request(fill(ApiPaths::WEBHOOK_ROTATE_SECRET, id:), method: :post, api_key:)
+      end
+
+      def test(id, api_key: nil)
+        request(fill(ApiPaths::WEBHOOK_TEST, id:), method: :post, api_key:)
+      end
+
+      def list_deliveries(id, status: nil, since: nil, until: nil, limit: nil, cursor: nil, api_key: nil)
+        query = delivery_query(status, since, binding.local_variable_get(:until))
+        fetch_page(fill(ApiPaths::WEBHOOK_DELIVERIES, id:), query, limit:, cursor:, api_key:)
+      end
+
+      def list_all_deliveries(id, status: nil, since: nil, until: nil, limit: nil, cursor: nil, api_key: nil)
+        query = delivery_query(status, since, binding.local_variable_get(:until))
+        collect_all(fill(ApiPaths::WEBHOOK_DELIVERIES, id:), query, limit:, cursor:, api_key:)
+      end
+
+      def iterate_deliveries(id, status: nil, since: nil, until: nil, limit: nil, cursor: nil, api_key: nil, &)
+        query = delivery_query(status, since, binding.local_variable_get(:until))
+        iterate_pages(fill(ApiPaths::WEBHOOK_DELIVERIES, id:), query, limit:, cursor:, api_key:, &)
+      end
+
+      def get_delivery(id, delivery_id, api_key: nil)
+        request(fill(ApiPaths::WEBHOOK_DELIVERY, id:, deliveryId: delivery_id), api_key:)
+      end
+
+      def replay_delivery(id, delivery_id, api_key: nil)
+        request(fill(ApiPaths::WEBHOOK_DELIVERY_REPLAY, id:, deliveryId: delivery_id), method: :post, api_key:)
+      end
+
+      def list_workspace_deliveries(endpoint_ids: nil, status: nil, since: nil, until: nil, limit: nil, cursor: nil,
+        api_key: nil)
+        query = workspace_delivery_query(endpoint_ids, status, since, binding.local_variable_get(:until))
+        fetch_page(ApiPaths::WEBHOOKS_DELIVERIES, query, limit:, cursor:, api_key:)
+      end
+
+      def list_all_workspace_deliveries(endpoint_ids: nil, status: nil, since: nil, until: nil, limit: nil,
+        cursor: nil, api_key: nil)
+        query = workspace_delivery_query(endpoint_ids, status, since, binding.local_variable_get(:until))
+        collect_all(ApiPaths::WEBHOOKS_DELIVERIES, query, limit:, cursor:, api_key:)
+      end
+
+      def iterate_workspace_deliveries(endpoint_ids: nil, status: nil, since: nil, until: nil, limit: nil, cursor: nil,
+        api_key: nil, &)
+        query = workspace_delivery_query(endpoint_ids, status, since, binding.local_variable_get(:until))
+        iterate_pages(ApiPaths::WEBHOOKS_DELIVERIES, query, limit:, cursor:, api_key:, &)
+      end
+
+      def list_activity(id, since: nil, until: nil, limit: nil, cursor: nil, api_key: nil)
+        query = window_query(since, binding.local_variable_get(:until))
+        fetch_page(fill(ApiPaths::WEBHOOK_ACTIVITY, id:), query, limit:, cursor:, api_key:)
+      end
+
+      def list_all_activity(id, since: nil, until: nil, limit: nil, cursor: nil, api_key: nil)
+        query = window_query(since, binding.local_variable_get(:until))
+        collect_all(fill(ApiPaths::WEBHOOK_ACTIVITY, id:), query, limit:, cursor:, api_key:)
+      end
+
+      def iterate_activity(id, since: nil, until: nil, limit: nil, cursor: nil, api_key: nil, &)
+        query = window_query(since, binding.local_variable_get(:until))
+        iterate_pages(fill(ApiPaths::WEBHOOK_ACTIVITY, id:), query, limit:, cursor:, api_key:, &)
+      end
+
+      def list_workspace_activity(endpoint_ids: nil, since: nil, until: nil, limit: nil, cursor: nil, api_key: nil)
+        query = workspace_activity_query(endpoint_ids, since, binding.local_variable_get(:until))
+        fetch_page(ApiPaths::WEBHOOKS_ACTIVITY, query, limit:, cursor:, api_key:)
+      end
+
+      def list_all_workspace_activity(endpoint_ids: nil, since: nil, until: nil, limit: nil, cursor: nil, api_key: nil)
+        query = workspace_activity_query(endpoint_ids, since, binding.local_variable_get(:until))
+        collect_all(ApiPaths::WEBHOOKS_ACTIVITY, query, limit:, cursor:, api_key:)
+      end
+
+      def iterate_workspace_activity(endpoint_ids: nil, since: nil, until: nil, limit: nil, cursor: nil, api_key: nil, &)
+        query = workspace_activity_query(endpoint_ids, since, binding.local_variable_get(:until))
+        iterate_pages(ApiPaths::WEBHOOKS_ACTIVITY, query, limit:, cursor:, api_key:, &)
+      end
+
+      def list_events(api_key: nil)
+        request(ApiPaths::WEBHOOKS_EVENTS, api_key:)
+      end
+
+      def stats(endpoint_ids: nil, since: nil, until: nil, grain: nil, offset_minutes: nil, api_key: nil)
+        query = window_query(since, binding.local_variable_get(:until))
+          .merge(query_params(endpoint_ids: joined(endpoint_ids), grain:, offset_minutes:))
+        request(ApiPaths::WEBHOOKS_STATS, query:, api_key:)
+      end
+
+      private
+
+      def window_query(since, until_value)
+        query_params(since: instant(since), until: instant(until_value))
+      end
+
+      def delivery_query(status, since, until_value)
+        window_query(since, until_value).merge(query_params(status:))
+      end
+
+      def workspace_delivery_query(endpoint_ids, status, since, until_value)
+        delivery_query(status, since, until_value).merge(query_params(endpoint_ids: joined(endpoint_ids)))
+      end
+
+      def workspace_activity_query(endpoint_ids, since, until_value)
+        window_query(since, until_value).merge(query_params(endpoint_ids: joined(endpoint_ids)))
+      end
+    end
+  end
+end

data/lib/openemail/resources/workspaces.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OpenEmail
+  module Resources
+    class Workspaces < Resource
+      def list(api_key: nil)
+        request(ApiPaths::WORKSPACES, api_key:)
+      end
+
+      def create(body = nil, api_key: nil, **fields)
+        request(ApiPaths::WORKSPACES, method: :post, body: payload(body, fields), api_key:)
+      end
+
+      def get_active(api_key: nil)
+        request(ApiPaths::WORKSPACES_ACTIVE, api_key:)
+      end
+
+      def set_active(workspace_id, api_key: nil)
+        request(ApiPaths::WORKSPACES_ACTIVE, method: :put, body: {"workspaceId" => workspace_id}, repeatable: true,
+          api_key:)
+      end
+
+      def delete(id, confirm:, api_key: nil)
+        request(fill(ApiPaths::WORKSPACE, id:), method: :delete, query: query_params(confirm:), api_key:)
+      end
+    end
+  end
+end

data/lib/openemail/results.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OpenEmail
+  Page = Data.define(:items, :has_more, :next_cursor) do
+    def has_more?
+      has_more
+    end
+  end
+
+  PeoplePage = Data.define(:items, :has_more, :next_cursor, :seen) do
+    def has_more?
+      has_more
+    end
+  end
+
+  TempMessagesPage = Data.define(:items, :has_more, :next_cursor, :expires_at) do
+    def has_more?
+      has_more
+    end
+  end
+
+  AddressBookPage = Data.define(:unrestricted, :addresses, :domains, :has_more, :next_cursor) do
+    def has_more?
+      has_more
+    end
+  end
+
+  AddressBook = Data.define(:unrestricted, :addresses, :domains)
+
+  BatchResult = Data.define(:items, :sent, :failed)
+
+  TemplateSends = Data.define(:items, :total, :page, :page_size)
+end

data/lib/openemail/transport.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module OpenEmail
+  class Transport
+    HTTP_DATE_FORMATS = %i[httpdate rfc2822 iso8601].freeze
+    LINE_BREAK = /[\r\n]/
+    HEADER_NAME = /\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/
+    PROGRAMMING_ERRORS = [NameError, TypeError, ArgumentError].freeze
+
+    attr_reader :base_url, :timeout
+
+    def initialize(api_key: nil, access_token: nil, inbox_token: nil, base_url: nil, adapter: nil, max_retries: nil,
+      timeout: nil, user_agent: nil, headers: nil, disable_update_notice: false)
+      Credentials.assert_credential(api_key, access_token, required: false)
+
+      @api_key = Credentials.present?(api_key) ? api_key : nil
+      @access_token = Credentials.present?(access_token) ? access_token : nil
+      @inbox_token = inbox_token
+      @base_url = Endpoint.valid_base_url(base_url || Defaults::BASE_URL)
+      @secure_origin = Endpoint.secure_origin?(@base_url)
+      @adapter = adapter || NetHttpAdapter.new
+      @max_retries = [Integer(max_retries || Defaults::MAX_RETRIES), 0].max
+      @timeout = timeout.nil? ? Defaults::TIMEOUT : timeout_option(timeout)
+      @user_agent = header_value(user_agent || Defaults::USER_AGENT)
+      @headers = (headers || {}).to_h { |name, value| [header_name(name), header_value(value)] }.freeze
+
+      UpdateNotice.check(@adapter) unless disable_update_notice
+    end
+
+    def request(path, method: :get, query: nil, body: nil, raw: nil, content_type: nil, api_key: nil, inbox_token: nil,
+      anonymous: false, idempotent: false, idempotency_key: nil, repeatable: nil, accept: nil, binary: false,
+      timeout: nil)
+      verb = method.to_s.upcase
+      outbound = HttpRequest.new(
+        method: verb,
+        url: Endpoint.build_url(@base_url, path, query),
+        headers: headers_for(body:, raw:, content_type:, api_key:, inbox_token:, anonymous:, idempotent:,
+          idempotency_key:, accept:),
+        body: raw.nil? ? json_body(body) : RawBody.read(raw),
+        timeout: seconds(timeout.nil? ? @timeout : timeout_option(timeout))
+      )
+
+      deliver(outbound, repeatable.nil? ? Protocol::RETRY[:METHODS].include?(verb) : repeatable, accept, binary)
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+    end
+
+    private
+
+    def deliver(outbound, repeatable, accept, binary)
+      attempt = 0
+
+      loop do
+        outcome = exchange(outbound)
+
+        if outcome.is_a?(NetworkError)
+          raise outcome, cause: outcome.original unless repeatable && attempt < @max_retries
+
+          sleep(backoff(attempt))
+          attempt += 1
+          next
+        end
+
+        return binary ? outcome.body.b : parse(outcome, accept) if outcome.ok?
+
+        wait = retry_after(outcome.header(Protocol::HEADER_KEYS[:RETRY_AFTER]))
+
+        if repeatable && attempt < @max_retries && retry_status?(outcome.status) && honoured?(outcome.status, wait)
+          sleep(wait.nil? ? backoff(attempt) : wait)
+          attempt += 1
+          next
+        end
+
+        raise api_error(outcome, wait)
+      end
+    end
+
+    def exchange(outbound)
+      response = @adapter.call(outbound)
+      HttpResponse.new(status: Integer(response.status), headers: header_table(response.headers), body: response.body.to_s)
+    rescue Timeout::Error => error
+      NetworkError.new(format(Defaults::MESSAGES[:TIMED_OUT], seconds: outbound.timeout), original: error, timeout: true)
+    rescue *PROGRAMMING_ERRORS
+      raise
+    rescue => error
+      NetworkError.new(format(Defaults::MESSAGES[:UNREACHABLE], base_url: @base_url, reason: error.message),
+        original: error)
+    end
+
+    def header_table(headers)
+      (headers || {}).to_h { |name, value| [name.to_s.downcase, value.is_a?(Array) ? value.join(", ") : value.to_s] }
+    end
+
+    def headers_for(body:, raw:, content_type:, api_key:, inbox_token:, anonymous:, idempotent:, idempotency_key:, accept:)
+      headers = @headers.merge(
+        Protocol::HEADER_KEYS[:ACCEPT] => accept || Protocol::CONTENT_TYPES[:JSON],
+        Protocol::HEADER_KEYS[:USER_AGENT] => @user_agent
+      )
+
+      if !raw.nil?
+        headers[Protocol::HEADER_KEYS[:CONTENT_TYPE]] = header_value(content_type || Protocol::CONTENT_TYPES[:OCTET_STREAM])
+      elsif !body.nil?
+        headers[Protocol::HEADER_KEYS[:CONTENT_TYPE]] = Protocol::CONTENT_TYPES[:JSON]
+      end
+
+      authorize(headers, api_key, inbox_token) unless anonymous
+
+      if idempotent
+        headers[Protocol::HEADER_KEYS[:IDEMPOTENCY_KEY]] = header_value(idempotency_key || generated_idempotency_key)
+      end
+      headers
+    end
+
+    def authorize(headers, api_key, inbox_token)
+      Credentials.assert_api_key(api_key, "The api_key passed to this call") unless api_key.nil?
+
+      direct = [inbox_token, api_key, @inbox_token, @api_key].find { |value| !value.nil? }
+
+      if Credentials.present?(direct.nil? ? @access_token : direct) && !@secure_origin
+        raise ArgumentError, format(Defaults::MESSAGES[:CLEARTEXT], base_url: @base_url)
+      end
+
+      credential = direct.nil? ? resolved_access_token : direct
+      return unless Credentials.present?(credential)
+
+      headers[Protocol::HEADER_KEYS[:AUTHORIZATION]] = header_value("Bearer #{credential}")
+    end
+
+    def resolved_access_token
+      return @access_token unless @access_token.respond_to?(:call)
+
+      token = @access_token.call
+      return token if Credentials.access_token?(token)
+
+      raise ArgumentError, "#{Defaults::MESSAGES[:ACCESS_TOKEN_PROVIDED]} #{Defaults::MESSAGES[:ACCESS_TOKEN_SHAPE]}"
+    end
+
+    def generated_idempotency_key
+      "#{Protocol::IDEMPOTENCY_KEY_PREFIX}#{SecureRandom.uuid}"
+    end
+
+    def header_name(name)
+      text = name.to_s
+      raise ArgumentError, Defaults::MESSAGES[:HEADER_SHAPE] unless HEADER_NAME.match?(text)
+
+      text
+    end
+
+    def header_value(value)
+      text = value.to_s
+      raise ArgumentError, Defaults::MESSAGES[:HEADER_SHAPE] if LINE_BREAK.match?(text)
+
+      text
+    end
+
+    def timeout_option(value)
+      return value if value.is_a?(Numeric) && !(value.is_a?(Float) && value.nan?) && !value.negative?
+
+      raise ArgumentError, Defaults::MESSAGES[:TIMEOUT_SHAPE]
+    end
+
+    def json_body(body)
+      body.nil? ? nil : JSON.generate(Wire.json_ready(body))
+    end
+
+    def seconds(value)
+      value.positive? ? value : nil
+    end
+
+    def parse(response, accept)
+      text = Decode.text(response.body)
+      return text if accept && accept != Protocol::CONTENT_TYPES[:JSON]
+      return nil if text.empty?
+
+      Decode.json(text)
+    rescue JSON::ParserError
+      raise ApiError.build(
+        message: format(Defaults::MESSAGES[:NOT_JSON], status: response.status),
+        status: response.status,
+        type: ERROR_TYPES[:API_ERROR],
+        code: Protocol::ERROR_CODES[:UNRECOGNISED_RESPONSE],
+        request_id: response.header(Protocol::HEADER_KEYS[:REQUEST_ID])
+      )
+    end
+
+    def api_error(response, wait)
+      text = Decode.text(response.body)
+      body = parse_json(text)
+      payload = (body.is_a?(Hash) && body[:error].is_a?(Hash)) ? body[:error] : {}
+
+      ApiError.build(
+        message: text_of(payload[:message]) || fallback_message(response.status, text),
+        status: response.status,
+        type: ERROR_TYPES.value?(payload[:type]) ? payload[:type] : type_for_status(response.status),
+        code: text_of(payload[:code]) || Protocol::ERROR_CODES[:UNRECOGNISED_RESPONSE],
+        param: text_of(payload[:param]),
+        doc_url: text_of(payload[:docUrl]),
+        request_id: text_of(payload[:requestId]) || response.header(Protocol::HEADER_KEYS[:REQUEST_ID]),
+        retry_after_seconds: wait,
+        fields: fields_of(payload[:fields]),
+        body:
+      )
+    end
+
+    def fallback_message(status, text)
+      text.empty? ? format(Defaults::MESSAGES[:UNRECOGNISED_BODY], status:) : text[0, 300]
+    end
+
+    def type_for_status(status)
+      return ERROR_TYPES[:API_ERROR] if status >= 500
+
+      mapped = Protocol::ERROR_TYPE_BY_STATUS[status]
+      ERROR_TYPES.value?(mapped) ? mapped : ERROR_TYPES[:INVALID_REQUEST_ERROR]
+    end
+
+    def fields_of(value)
+      return nil unless value.is_a?(Array)
+
+      value.select { |field| field.is_a?(Hash) && field[:key].is_a?(String) && field[:error].is_a?(String) }
+    end
+
+    def text_of(value)
+      (value.is_a?(String) && !value.empty?) ? value : nil
+    end
+
+    def parse_json(text)
+      text.empty? ? nil : Decode.json(text)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def retry_status?(status)
+      Protocol::RETRY[:STATUSES].include?(status)
+    end
+
+    def honoured?(status, wait)
+      return status != Protocol::RETRY[:RATE_LIMIT_STATUS] if wait.nil?
+
+      wait * 1000 <= Protocol::RETRY[:MAX_HONOURED_RETRY_AFTER_MS]
+    end
+
+    def backoff(attempt)
+      ceiling = [Protocol::RETRY[:MAX_BACKOFF_MS], Protocol::RETRY[:BASE_BACKOFF_MS] * (2**attempt)].min
+      (ceiling * (0.5 + (rand * 0.5))).round / 1000.0
+    end
+
+    def retry_after(value)
+      return nil if value.nil? || value.strip.empty?
+
+      seconds = Float(value, exception: false)
+      return whole(seconds) if seconds&.finite? && seconds >= 0
+
+      at = http_date(value.strip)
+      at && [0, (at - Time.now).ceil].max
+    end
+
+    def http_date(text)
+      HTTP_DATE_FORMATS.each do |format|
+        return Time.public_send(format, text)
+      rescue ArgumentError
+        next
+      end
+      nil
+    end
+
+    def whole(number)
+      (number == number.to_i) ? number.to_i : number
+    end
+  end
+end

data/lib/openemail/update_notice.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module OpenEmail
+  module UpdateNotice
+    @checked = false
+    @lock = Mutex.new
+
+    module_function
+
+    def check(adapter)
+      return unless claim
+
+      Thread.new do
+        Thread.current.report_on_exception = false
+        latest = latest_version(adapter)
+        warn(notice(latest)) if latest && newer?(latest, VERSION)
+      end
+    end
+
+    def claim
+      @lock.synchronize do
+        next false if @checked || disabled?
+
+        @checked = true
+      end
+    end
+
+    def disabled?
+      !ENV.fetch(Defaults::UPDATE_NOTICE[:ENV_DISABLE], "").empty? || !$stdout.tty?
+    end
+
+    def latest_version(adapter)
+      response = adapter.call(HttpRequest.new(
+        method: Protocol::HTTP_METHODS[:GET],
+        url: Defaults::UPDATE_NOTICE[:REGISTRY_URL],
+        headers: {
+          Protocol::HEADER_KEYS[:ACCEPT] => Protocol::CONTENT_TYPES[:JSON],
+          Protocol::HEADER_KEYS[:USER_AGENT] => Defaults::USER_AGENT
+        },
+        body: nil,
+        timeout: Defaults::UPDATE_NOTICE[:TIMEOUT]
+      ))
+      return nil unless Integer(response.status).between?(200, 299)
+
+      version = JSON.parse(response.body.to_s)["version"]
+      version.is_a?(String) ? version : nil
+    rescue
+      nil
+    end
+
+    def newer?(candidate, current)
+      left = parts(candidate)
+      right = parts(current)
+      return false if left.nil? || right.nil?
+
+      (left <=> right) == 1
+    end
+
+    def parts(value)
+      numbers = value.to_s.strip.delete_prefix("v").split(".").map { |part| Integer(part, 10, exception: false) }
+      (numbers.size == 3 && numbers.none?(&:nil?)) ? numbers : nil
+    end
+
+    def notice(latest)
+      format(Defaults::MESSAGES[:UPDATE_AVAILABLE], icon: Defaults::UPDATE_NOTICE[:ICON],
+        package: Defaults::UPDATE_NOTICE[:PACKAGE], latest:, current: VERSION, page: Defaults::UPDATE_NOTICE[:PAGE_URL])
+    end
+  end
+end

data/lib/openemail/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenEmail
+  VERSION = "0.0.1"
+end

data/lib/openemail/webhook.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module OpenEmail
+  module Webhook
+    module_function
+
+    def verify(payload:, headers:, secret:, tolerance_seconds: nil)
+      raise ArgumentError, Defaults::MESSAGES[:WEBHOOK_PAYLOAD_SHAPE] unless payload.is_a?(String)
+      raise ArgumentError, Defaults::MESSAGES[:WEBHOOK_SECRET_REQUIRED] unless secret.is_a?(String) && !secret.empty?
+
+      header = read_header(headers, WEBHOOK_SIGNATURE_HEADERS[:SIGNATURE])
+      raise WebhookSignatureError, Defaults::MESSAGES[:WEBHOOK_MISSING_HEADER] if header.nil? || header.empty?
+
+      timestamp, signatures = parse_signature(header)
+      raise WebhookSignatureError, Defaults::MESSAGES[:WEBHOOK_MALFORMED_HEADER] if timestamp.nil?
+
+      assert_fresh(timestamp, tolerance_seconds.nil? ? Protocol::WEBHOOK_SIGNATURE[:TOLERANCE_SECONDS] : tolerance_seconds)
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{payload}")
+      raise WebhookSignatureError, Defaults::MESSAGES[:WEBHOOK_MISMATCH] unless signatures.any? { |candidate| same?(expected, candidate) }
+
+      Decode.json(Decode.text(payload))
+    end
+
+    def read_header(headers, name)
+      wanted = name.downcase
+      rack = "HTTP_#{name.upcase.tr("-", "_")}"
+
+      if headers.respond_to?(:each_pair)
+        headers.each_pair do |key, value|
+          return first_value(value) if key.to_s.downcase == wanted || key.to_s == rack
+        end
+        nil
+      elsif headers.respond_to?(:[])
+        first_value(headers[name])
+      end
+    end
+
+    def first_value(value)
+      value = value.first if value.is_a?(Array)
+      value&.to_s
+    end
+
+    def parse_signature(header)
+      timestamp = nil
+      signatures = []
+
+      header.split(Protocol::WEBHOOK_SIGNATURE[:PAIR_SEPARATOR]).each do |pair|
+        at = pair.index(Protocol::WEBHOOK_SIGNATURE[:VALUE_SEPARATOR])
+        next if at.nil? || at < 1
+
+        key = pair[0, at].strip
+        value = pair[(at + 1)..].strip
+        timestamp = number(value) if key == Protocol::WEBHOOK_SIGNATURE[:TIMESTAMP]
+        signatures << value if key == Protocol::WEBHOOK_SIGNATURE[:VERSION] && !value.empty?
+      end
+
+      (timestamp.nil? || signatures.empty?) ? nil : [timestamp, signatures]
+    end
+
+    def number(value)
+      integer = Integer(value, 10, exception: false)
+      return integer unless integer.nil?
+
+      float = Float(value, exception: false)
+      return nil if float.nil? || !float.finite?
+
+      (float == float.to_i) ? float.to_i : float
+    end
+
+    def assert_fresh(timestamp, tolerance)
+      drift = (Time.now.to_i - timestamp).abs
+      return unless tolerance.positive? && drift > tolerance
+
+      raise WebhookSignatureError, format(Defaults::MESSAGES[:WEBHOOK_OUT_OF_TOLERANCE], drift:, tolerance:)
+    end
+
+    def same?(expected, candidate)
+      candidate.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(expected, candidate)
+    end
+  end
+end