zapsmtp 0.1.0.beta3

data/lib/zapsmtp/retry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ZapSMTP
+  # When a failed request is tried again, and after how long
+  # (docs/DESIGN-sdks.md, retries).
+  module Retry
+    RETRY_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+    NO_RETRY_429 = %w[monthly_quota_exceeded daily_quota_exceeded thread_reply_limit].freeze
+
+    module_function
+
+    # Whether an error answer is worth another attempt. A 429 was refused
+    # before any work, so it is always safe; other statuses only for a
+    # request that is safe to repeat.
+    def retryable?(status, code, safe)
+      return !NO_RETRY_429.include?(code) if status == 429
+      return code == "idempotency_request_in_progress" if status == 409
+
+      safe && RETRY_STATUSES.include?(status)
+    end
+
+    # Seconds to wait before attempt number attempt + 1: Retry-After up to 60
+    # seconds, else exponential backoff (0.5, 1, 2 ... capped at 8) with jitter.
+    def backoff(attempt, retry_after)
+      return [retry_after, 60].min.to_f if retry_after
+
+      base = [0.5 * (2**attempt), 8.0].min
+      (base / 2) + (rand * (base / 2))
+    end
+
+    # The Retry-After header in seconds (a number or an HTTP date), or nil.
+    def retry_after(headers)
+      value = headers && headers["retry-after"]
+      return nil if value.nil? || value.strip.empty?
+
+      seconds = Float(value, exception: false)
+      return [seconds, 0.0].max if seconds&.finite?
+
+      begin
+        [Time.httpdate(value.strip) - Time.now, 0.0].max
+      rescue ArgumentError, RangeError
+        nil
+      end
+    end
+  end
+end

data/lib/zapsmtp/transport.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module ZapSMTP
+  # How requests reach the API. A transport is any object with
+  # #call(request) -> response, taking a Transport::Request and answering a
+  # Transport::Response (or anything with status, headers and body); it
+  # raises on a network failure or timeout. Pass one as
+  # ZapSMTP::Client.new(transport: ...) to use another HTTP library or to
+  # stub the API in tests.
+  module Transport
+    # One HTTP attempt: http_method ("GET"...), url, headers (Hash), body
+    # (String or nil) and timeout (seconds).
+    Request = Struct.new(:http_method, :url, :headers, :body, :timeout, keyword_init: true)
+
+    # An HTTP answer: status (Integer), headers (Hash) and body (String).
+    Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+    # A timeout: no connection, or no answer, within the timeout.
+    class TimeoutError < StandardError; end
+
+    # The answer's head came but its body broke off (or stalled): the
+    # status and headers are kept for the ConnectionError.
+    class ResponseBodyError < StandardError
+      # @return [Integer]
+      attr_reader :status
+      # @return [Hash]
+      attr_reader :headers
+
+      def initialize(message, status:, headers:)
+        super(message)
+        @status = status
+        @headers = headers
+      end
+    end
+
+    # The default transport: Net::HTTP, keeping one connection alive per
+    # thread and host. The timeout bounds connecting, each write and each
+    # read, the response body's included.
+    class NetHTTP
+      TIMEOUTS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout].freeze
+      # The encodings Net::HTTP inflates (when it asked for compression itself).
+      INFLATED = %w[gzip deflate x-gzip].freeze
+
+      def initialize
+        @key = :"zapsmtp_connections_#{object_id}"
+      end
+
+      def call(request)
+        uri = URI.parse(request.url)
+        head = nil
+        begin
+          http = connection(uri, request.timeout)
+          message = Net::HTTPGenericRequest.new(request.http_method, !request.body.nil?, true, uri.request_uri,
+                                                request.headers)
+          message.body = request.body
+          answer = http.request(message) do |response|
+            head = response
+            read_body(response)
+          end
+        rescue StandardError => e
+          close(uri)
+          raise failure(e, head, request.timeout)
+        end
+        Response.new(status: answer.code.to_i, headers: headers(answer),
+                     body: answer.body.to_s.dup.force_encoding(Encoding::UTF_8))
+      end
+
+      private
+
+      def headers(response)
+        response.to_hash.transform_values { |v| v.join(", ") }
+      end
+
+      # The error to raise for a failed attempt: a timeout says so, and a
+      # failure after the answer's head keeps its status and headers.
+      def failure(error, head, timeout)
+        timed_out = TIMEOUTS.any? { |t| error.is_a?(t) }
+        message = timed_out ? "timed out after #{timeout} s" : error.message
+        return ResponseBodyError.new(message, status: head.code.to_i, headers: headers(head)) if head
+
+        timed_out ? TimeoutError.new(message) : error
+      end
+
+      # Reads the body, refusing one cut short: Net::HTTP returns what came
+      # before the connection closed. Content-Length counts the bytes on the
+      # wire, so it is checked unless Net::HTTP inflated them (a compressed
+      # body cut short fails to inflate instead).
+      def read_body(response)
+        inflated = response.decode_content && INFLATED.include?(response["content-encoding"].to_s.downcase)
+        length = response.content_length
+        response.read_body
+        return if inflated || length.nil? || response.body.to_s.bytesize >= length
+
+        raise EOFError, "response body cut short: #{response.body.to_s.bytesize} of #{length} bytes"
+      end
+
+      # This thread's open connection to the URI's host, or a new one. A
+      # forked process never reuses its parent's connections.
+      def connection(uri, timeout)
+        pool = Thread.current[@key]
+        pool = Thread.current[@key] = { pid: Process.pid } if pool.nil? || pool[:pid] != Process.pid
+        http = pool[origin(uri)]
+        unless http&.started?
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = timeout
+          http.max_retries = 0 # the client decides what is retried
+          http.start
+          pool[origin(uri)] = http
+        end
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+        http
+      end
+
+      def close(uri)
+        http = Thread.current[@key].delete(origin(uri))
+        http.finish if http&.started?
+      end
+
+      def origin(uri)
+        "#{uri.scheme}://#{uri.host}:#{uri.port}"
+      end
+    end
+  end
+end

data/lib/zapsmtp/util.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+require "uri"
+
+module ZapSMTP
+  # Request building helpers used by the resources.
+  #
+  # @api private
+  module Util
+    module_function
+
+    # A call's parameters: a Hash and keyword arguments, merged, with String keys.
+    def params(params, kwargs)
+      raise ArgumentError, "params must be a Hash, got #{params.class}" unless params.respond_to?(:each_pair)
+
+      merged = {}
+      params.each_pair { |k, v| merged[k.to_s] = v }
+      kwargs.each_pair { |k, v| merged[k.to_s] = v }
+      merged
+    end
+
+    # The given keys of params, or nil when it has none of them.
+    def pick(params, keys)
+      picked = params.slice(*keys)
+      picked.empty? ? nil : picked
+    end
+
+    # A path segment, escaped. An empty value, "." or ".." can be no id: URL
+    # normalization would resolve it into another path (percent-encoded too),
+    # so it is refused before anything is sent.
+    def seg(name, value)
+      value = value.to_s
+      if ["", ".", ".."].include?(value)
+        raise ValidationError.new("#{name} must not be #{value.empty? ? "empty" : "\"#{value}\""}",
+                                  code: "invalid_parameter")
+      end
+      URI.encode_www_form_component(value).gsub("+", "%20")
+    end
+
+    # The query string: nil values are left out, arrays repeat their key and
+    # hashes become key[name]=value.
+    def query_string(query)
+      pairs = []
+      (query || {}).each do |key, value|
+        case value
+        when nil then next
+        when Array then value.each { |v| pairs << [key.to_s, scalar(v)] }
+        when Hash then value.each { |k, v| pairs << ["#{key}[#{k}]", scalar(v)] }
+        else pairs << [key.to_s, scalar(value)]
+        end
+      end
+      URI.encode_www_form(pairs)
+    end
+
+    def scalar(value)
+      value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+    end
+
+    # A value made ready for JSON: times as RFC 3339, models as hashes.
+    def jsonable(value)
+      case value
+      when Hash then value.to_h { |k, v| [k, jsonable(v)] }
+      when Array then value.map { |v| jsonable(v) }
+      when Model then value.to_h
+      else value.respond_to?(:iso8601) ? value.iso8601 : value
+      end
+    end
+
+    # A parsed JSON value with every number that is not finite (NaN,
+    # Infinity, or one too large for a Float) as nil.
+    def finite(value)
+      case value
+      when Hash then value.transform_values { |v| finite(v) }
+      when Array then value.map { |v| finite(v) }
+      when Float then value.finite? ? value : nil
+      else value
+      end
+    end
+
+    # A multipart/form-data body.
+    Form = Struct.new(:body, :content_type)
+
+    # The multipart body of a file upload: field holds the file; name, when
+    # given, is sent as the "name" field.
+    def upload_form(field, file, name:, filename:)
+      data, own_name = read_file(file)
+      filename ||= name || own_name
+      boundary = "zapsmtp-#{SecureRandom.hex(16)}"
+      body = String.new(encoding: Encoding::BINARY)
+      type = Attachment.content_type_for(filename) || "application/octet-stream"
+      body << part_head(boundary, field, filename) << "Content-Type: #{type}\r\n\r\n".b << data.b << "\r\n".b
+      body << part_head(boundary, "name", nil) << "\r\n".b << name.to_s.b << "\r\n".b unless name.nil?
+      body << "--#{boundary}--\r\n".b
+      Form.new(body, "multipart/form-data; boundary=#{boundary}")
+    end
+
+    def part_head(boundary, field, filename)
+      head = "--#{boundary}\r\nContent-Disposition: form-data; name=\"#{quote(field)}\""
+      head << "; filename=\"#{quote(filename)}\"" if filename
+      (head << "\r\n").b
+    end
+
+    # A form-data name or filename, escaped as browsers do.
+    def quote(value)
+      value.to_s.gsub("\"", "%22").gsub("\r", "%0D").gsub("\n", "%0A")
+    end
+
+    # The bytes of a file given by path (a String or Pathname, or a File) or
+    # as another IO, and its own name.
+    def read_file(file)
+      path = file.respond_to?(:to_path) ? file.to_path : file
+      return [File.binread(path), File.basename(path)] if path.is_a?(String)
+
+      [file.read, "image"]
+    end
+  end
+end

data/lib/zapsmtp/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ZapSMTP
+  # Kept in step with the gemspec by the release script.
+  VERSION = "0.1.0.beta3"
+end

data/lib/zapsmtp/webhook.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module ZapSMTP
+  # Webhook signature verification (docs: Webhook events). Every request
+  # ZapSMTP sends carries Zap-Signature: t=<unix seconds>,v1=<hex>, where v1
+  # is HMAC-SHA256 over "<t>.<raw body>" keyed with the whole secret (its
+  # whsec_ prefix included). Two v1 entries are sent for 24 hours after a
+  # rotation.
+  module Webhook
+    DEFAULT_TOLERANCE = 300
+    SIGNATURE_HEADER = "zap-signature"
+
+    module_function
+
+    # Checks a webhook request's signature and returns its event. Pass the
+    # body exactly as received, before any JSON parsing. A webhook with batch
+    # delivery sends an array of events: use .verify_events.
+    #
+    #   event = ZapSMTP::Webhook.verify(request.raw_post, request.headers, ENV["ZAP_WEBHOOK_SECRET"])
+    #   event.type # => "email.delivered"
+    #
+    # @param payload [String] the raw request body
+    # @param headers [Hash, #each, String] the request headers (a Hash in any
+    #   case, a Rack env, ActionDispatch headers), or the Zap-Signature value
+    # @param secret [String] the webhook's signing secret, whsec_...
+    # @param tolerance [Integer] the oldest signature accepted, in seconds
+    # @param now [Integer, nil] the time to check against, in unix seconds (default: now)
+    # @return [ZapSMTP::WebhookEvent]
+    # @raise [ZapSMTP::WebhookVerificationError]
+    def verify(payload, headers, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+      body = verified(payload, headers, secret, tolerance: tolerance, now: now)
+      raise WebhookVerificationError, "The body is a batch of events: use verify_events" if body.is_a?(Array)
+
+      event(body)
+    end
+
+    # Checks a webhook request's signature and returns its events: every
+    # event of a batch (a webhook with batch: true), or the one event of any
+    # other request. Takes the arguments of .verify.
+    #
+    # @return [Array<ZapSMTP::WebhookEvent>]
+    # @raise [ZapSMTP::WebhookVerificationError]
+    def verify_events(payload, headers, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+      body = verified(payload, headers, secret, tolerance: tolerance, now: now)
+      (body.is_a?(Array) ? body : [body]).map { |item| event(item) }
+    end
+
+    # Checks the signature and answers the parsed body: an event, or an
+    # array of them for a batch.
+    #
+    # @api private
+    def verified(payload, headers, secret, tolerance:, now:)
+      signature = headers.is_a?(String) ? headers : signature_header(headers)
+      raise WebhookVerificationError, "Missing Zap-Signature header" if signature.nil? || signature.empty?
+      raise WebhookVerificationError, "Missing webhook secret" if secret.nil? || secret.to_s.empty?
+
+      timestamp, signatures = parse_signature(signature)
+      # unix seconds: at most 12 digits
+      unless timestamp.match?(/\A\d{1,12}\z/) && !signatures.empty?
+        raise WebhookVerificationError, "Malformed Zap-Signature header"
+      end
+      if ((now || Time.now.to_i) - timestamp.to_i).abs > tolerance
+        raise WebhookVerificationError, "Webhook signature is too old (or from the future)"
+      end
+
+      body = payload.to_s.b
+      expected = OpenSSL::HMAC.digest("SHA256", secret.to_s, "#{timestamp}.".b + body)
+      unless signatures.any? { |hex| matches?(hex, expected) }
+        raise WebhookVerificationError, "Webhook signature does not match"
+      end
+
+      parse(body)
+    end
+
+    # The Zap-Signature value among headers, whatever their case or form
+    # (Zap-Signature, zap_signature, Rack's HTTP_ZAP_SIGNATURE).
+    #
+    # @api private
+    def signature_header(headers)
+      return nil unless headers.respond_to?(:each)
+
+      headers.each do |name, value|
+        name = name.to_s.downcase.tr("_", "-").delete_prefix("http-")
+        return value.is_a?(Array) ? value.join(",") : value.to_s if name == SIGNATURE_HEADER
+      end
+      nil
+    end
+
+    # @api private
+    def parse_signature(signature)
+      timestamp = ""
+      signatures = []
+      signature.split(",").each do |part|
+        key, value = part.split("=", 2).map(&:strip)
+        if key == "t"
+          timestamp = value.to_s
+        elsif key == "v1"
+          signatures << value.to_s
+        end
+      end
+      [timestamp, signatures]
+    end
+
+    # Compares a v1 entry with the expected HMAC in constant time.
+    #
+    # @api private
+    def matches?(hex, expected)
+      return false unless hex.match?(/\A[0-9a-f]{64}\z/i)
+
+      OpenSSL.fixed_length_secure_compare([hex].pack("H*"), expected)
+    end
+
+    # @api private
+    def parse(body)
+      Util.finite(JSON.parse(body.dup.force_encoding(Encoding::UTF_8), symbolize_names: true))
+    rescue JSON::ParserError, EncodingError
+      raise WebhookVerificationError, "Webhook body is not JSON"
+    end
+
+    # @api private
+    def event(item)
+      raise WebhookVerificationError, "Webhook body is not an event" unless item.is_a?(Hash)
+
+      WebhookEvent.new(item)
+    end
+  end
+end

data/lib/zapsmtp/webhook_middleware.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ZapSMTP
+  # Rack middleware that checks the signature of ZapSMTP webhook requests
+  # (Rails, Sinatra, Hanami, any Rack app). A request to +path+ (or every
+  # request, without one) with a valid signature reaches the app with its
+  # events in env["zapsmtp.events"] (one, or every event of a batch) and,
+  # unless it is a batch, its event in env["zapsmtp.event"]; any other is
+  # answered 400.
+  #
+  #   # config/application.rb
+  #   config.middleware.use ZapSMTP::WebhookMiddleware, path: "/webhooks/zapsmtp",
+  #                                                     secret: ENV["ZAP_WEBHOOK_SECRET"]
+  #   # the controller then reads request.env["zapsmtp.event"]
+  class WebhookMiddleware
+    EVENT_KEY = "zapsmtp.event"
+    EVENTS_KEY = "zapsmtp.events"
+
+    def initialize(app, secret: ENV.fetch("ZAP_WEBHOOK_SECRET", nil), path: nil, tolerance: Webhook::DEFAULT_TOLERANCE)
+      @app = app
+      @secret = secret
+      @path = path
+      @tolerance = tolerance
+    end
+
+    def call(env)
+      return @app.call(env) unless @path.nil? || env["PATH_INFO"] == @path
+
+      begin
+        body = Webhook.verified(read_body(env), env, @secret, tolerance: @tolerance, now: nil)
+        events = (body.is_a?(Array) ? body : [body]).map { |item| Webhook.event(item) }
+      rescue WebhookVerificationError => e
+        return [400, { "content-type" => "application/json" }, [JSON.generate(error: e.message)]]
+      end
+      env[EVENTS_KEY] = events
+      env[EVENT_KEY] = events.first unless body.is_a?(Array)
+      @app.call(env)
+    end
+
+    private
+
+    # The raw body, the input left rewound for the app.
+    def read_body(env)
+      input = env["rack.input"]
+      return "" if input.nil?
+
+      input.rewind if input.respond_to?(:rewind)
+      body = input.read.to_s
+      input.rewind if input.respond_to?(:rewind)
+      body
+    end
+  end
+end

data/lib/zapsmtp.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# The official Ruby library for the ZapSMTP email API (https://zapsmtp.com).
+#
+#   require "zapsmtp"
+#   zap = ZapSMTP::Client.new(api_key: "zap_...")
+#   zap.emails.send(from: "Acme <hello@acme.com>", to: "jane@example.org", subject: "Hi", html: "<p>Hi</p>")
+module ZapSMTP
+end
+
+require_relative "zapsmtp/core"
+
+# The Rails integration (delivery method, webhook concern) loads with Rails;
+# without Rails, require "zapsmtp/rails" for the Mail delivery method alone.
+# :nocov: a load-time switch, tested in separate processes (test/loading_test.rb)
+require_relative "zapsmtp/railtie" if defined?(Rails::Railtie)
+# :nocov:

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: zapsmtp
+version: !ruby/object:Gem::Version
+  version: 0.1.0.beta3
+platform: ruby
+authors:
+- ZapSMTP
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-30 00:00:00.000000000 Z
+dependencies: []
+description: 'Send, receive and track email with ZapSMTP: every API operation, safe
+  retries with idempotency keys, paging over every list, webhook signature verification
+  and an ActionMailer delivery method. No dependencies beyond Ruby''s standard library.'
+email:
+- support@zapsmtp.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/zapsmtp.rb
+- lib/zapsmtp/attachment.rb
+- lib/zapsmtp/base_client.rb
+- lib/zapsmtp/core.rb
+- lib/zapsmtp/errors.rb
+- lib/zapsmtp/generated/client.rb
+- lib/zapsmtp/generated/models.rb
+- lib/zapsmtp/generated/resources.rb
+- lib/zapsmtp/model.rb
+- lib/zapsmtp/page.rb
+- lib/zapsmtp/rails.rb
+- lib/zapsmtp/rails/delivery_method.rb
+- lib/zapsmtp/rails/message.rb
+- lib/zapsmtp/rails/webhook_verification.rb
+- lib/zapsmtp/railtie.rb
+- lib/zapsmtp/response.rb
+- lib/zapsmtp/retry.rb
+- lib/zapsmtp/transport.rb
+- lib/zapsmtp/util.rb
+- lib/zapsmtp/version.rb
+- lib/zapsmtp/webhook.rb
+- lib/zapsmtp/webhook_middleware.rb
+homepage: https://zapsmtp.com/docs/sdks/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://zapsmtp.com/docs/sdks/
+  documentation_uri: https://zapsmtp.com/docs/
+  source_code_uri: https://github.com/zapsmtp/zapsmtp-ruby
+  changelog_uri: https://github.com/zapsmtp/zapsmtp-ruby/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: The official Ruby library for the ZapSMTP email API, with a Rails delivery
+  method
+test_files: []