zapsmtp 0.1.0.beta3

data/lib/zapsmtp/model.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ZapSMTP
+  # A JSON object the API answered. Every documented field has a reader;
+  # every field, documented or not, is kept and can be read with #[] or
+  # #to_h. A missing field reads as nil; nothing about a response's shape is
+  # ever fatal.
+  #
+  #   email = zap.emails.get(id)
+  #   email.status        # => "delivered"
+  #   email[:status]      # the same
+  #   email.to_h          # every field, keys as symbols
+  #   case email
+  #   in { status: "bounced" } then ...
+  #   end
+  class Model
+    class << self
+      # The documented fields and how each is converted (see .cast).
+      #
+      # @api private
+      def attribute_types
+        @attribute_types ||= {}
+      end
+
+      # Declares a documented field and its reader. A field whose name is
+      # already a method of every model (such as +method+ or +hash+) gets no
+      # reader: read it with #[].
+      #
+      # @api private
+      def attribute(name, type = nil)
+        attribute_types[name] = type
+        return if Model.public_method_defined?(name)
+
+        define_method(name) { read(name) }
+      end
+
+      # The model of a parsed JSON value: a Hash becomes an instance of
+      # +model+, anything else (or no model) is returned as it is.
+      #
+      # @api private
+      def build(model, value, http_response = nil)
+        return value unless model && value.is_a?(Hash)
+
+        model.new(value, http_response: http_response)
+      end
+
+      # Converts a field's value: type is nil (as parsed), a model name, or
+      # [:array, type] / [:map, type]. A value of another shape than expected
+      # is returned as it is.
+      #
+      # @api private
+      def cast(type, value)
+        case type
+        when nil then value
+        when String then build(Models.const_get(type, false), value)
+        else
+          kind, inner = type
+          if kind == :array
+            value.is_a?(Array) ? value.map { |v| cast(inner, v) } : value
+          else
+            value.is_a?(Hash) ? value.transform_values { |v| cast(inner, v) } : value
+          end
+        end
+      end
+
+      # @api private
+      def deep_dup(value)
+        case value
+        when Hash then value.to_h { |k, v| [k, deep_dup(v)] }
+        when Array then value.map { |v| deep_dup(v) }
+        when String then value.dup
+        else value
+        end
+      end
+    end
+
+    # @return [ZapSMTP::Response, nil] the status, headers and request id of the
+    #   answer this model came from (nil for a model nested in another)
+    attr_reader :http_response
+
+    # @param attributes [Hash] the parsed JSON object (or its fields as keyword arguments)
+    def initialize(attributes = {}, http_response: nil, **fields)
+      @attributes = attributes.merge(fields).transform_keys(&:to_sym)
+      @http_response = http_response
+      @cache = {}
+    end
+
+    # A field's value, by name (a String or Symbol). Documented fields are
+    # converted like their readers; others are as parsed.
+    def [](key)
+      key = key.to_sym
+      self.class.attribute_types.key?(key) ? read(key) : @attributes[key]
+    end
+
+    # Whether the API answered this field.
+    def key?(key)
+      @attributes.key?(key.to_sym)
+    end
+
+    # @return [Array<Symbol>] the names of the fields the API answered
+    def keys
+      @attributes.keys
+    end
+
+    def dig(key, *rest)
+      value = self[key]
+      rest.empty? || value.nil? ? value : value.dig(*rest)
+    end
+
+    # Every field as parsed, keys as symbols (a copy).
+    #
+    # @return [Hash]
+    def to_h
+      Model.deep_dup(@attributes)
+    end
+
+    def to_json(*args)
+      @attributes.to_json(*args)
+    end
+
+    def deconstruct_keys(_keys)
+      @attributes
+    end
+
+    def ==(other)
+      other.instance_of?(self.class) && other.to_h == @attributes
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, @attributes].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@attributes.inspect}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def read(name)
+      return @cache[name] if @cache.key?(name)
+
+      @cache[name] = Model.cast(self.class.attribute_types[name], @attributes[name])
+    end
+  end
+
+  # A webhook request's body: see ZapSMTP::Webhook.verify.
+  class WebhookEvent < Model
+    # @!attribute [r] id
+    #   @return [String, nil] evt_...; absent on email.received, thread.created and thread.replied (see Zap-Event-Id)
+    attribute :id
+    # @!attribute [r] type
+    #   @return [String] e.g. "email.delivered"
+    attribute :type
+    # @!attribute [r] created_at
+    #   @return [String] RFC 3339
+    attribute :created_at
+    # @!attribute [r] data
+    #   @return [Hash] the event's data, keys as symbols
+    attribute :data
+  end
+end

data/lib/zapsmtp/page.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module ZapSMTP
+  # One page of a list. #each walks this page; #auto_paging_each walks every
+  # page, asking for the next one only when the previous is used up.
+  #
+  #   page = zap.emails.list(limit: 50)
+  #   page.data              # this page's emails
+  #   page.next_page         # the next page, or nil
+  #   zap.emails.list(status: "bounced").auto_paging_each { |email| ... }
+  #   zap.emails.list.auto_paging_each.lazy.select { ... }.first(10)
+  class Page
+    include Enumerable
+
+    # @return [Array<ZapSMTP::Model>] this page's items
+    attr_reader :data
+    # @return [String, nil] the cursor of the next page, for lists paged by cursor
+    attr_reader :next_cursor
+    # @return [ZapSMTP::Response, nil] the status, headers and request id of this page's answer
+    attr_reader :http_response
+
+    # @api private
+    def initialize(body, model:, query:, paging:, loader:, http_response: nil)
+      @body = body.is_a?(Hash) ? body : {}
+      items = @body[:data].is_a?(Array) ? @body[:data] : []
+      @data = items.map { |item| Model.build(model, item) }
+      @has_more = @body[:has_more] == true
+      @next_cursor = @body[:next_cursor]
+      @http_response = http_response
+      @next_query = @has_more ? Page.next_query(query || {}, items, @next_cursor, paging) : nil
+      @loader = loader
+    end
+
+    # @return [String] "list"
+    def object
+      @body.fetch(:object, "list")
+    end
+
+    # Whether the API said there are more items after this page.
+    def has_more?
+      @has_more
+    end
+    alias has_more has_more?
+
+    # Whether there is a next page to ask for. Makes no request.
+    def next_page?
+      !@next_query.nil?
+    end
+
+    # The next page (one request), or nil after the last one.
+    #
+    # @return [ZapSMTP::Page, nil]
+    def next_page
+      @next_query && @loader.call(@next_query)
+    end
+
+    # Yields this page's items.
+    def each(&block)
+      return enum_for(:each) { @data.size } unless block
+
+      @data.each(&block)
+      self
+    end
+
+    # Yields every item of this page and the pages after it, loading each
+    # page when the previous one is used up. Without a block, an Enumerator
+    # (use .lazy to stop early without loading further pages).
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block
+
+      each_page { |page| page.data.each(&block) }
+      nil
+    end
+
+    # Yields this page and every page after it.
+    def each_page
+      return enum_for(:each_page) unless block_given?
+
+      page = self
+      while page
+        yield page
+        page = page.next_page
+      end
+      nil
+    end
+
+    # A field of the list object, by name.
+    def [](key)
+      key.to_sym == :data ? @data : @body[key.to_sym]
+    end
+
+    # The list object as parsed, keys as symbols (a copy).
+    def to_h
+      Model.deep_dup(@body)
+    end
+
+    def inspect
+      "#<#{self.class.name} data=#{@data.size} items has_more=#{@has_more}>"
+    end
+
+    # The query of the page after one (docs/DESIGN-sdks.md, paging): the
+    # caller's query plus where the next page starts, or nil when there is no
+    # way to ask for it.
+    #
+    # @api private
+    def self.next_query(query, items, cursor, paging)
+      first = items.first
+      last = items.last
+      case paging
+      when :cursor then present(cursor) && query.merge("after" => cursor)
+      when :before then (id = field(last, :id)) && query.merge("before" => id)
+      when :after then (id = field(last, :id)) && query.merge("after" => id)
+      when :logs then logs_query(query, first, last)
+      when :thread then thread_query(query, last)
+      end
+    end
+
+    # With after, logs come oldest-first from the server and newest-first in
+    # the page: the next newer page starts after the page's newest entry.
+    #
+    # @api private
+    def self.logs_query(query, first, last)
+      if query["after"].nil?
+        (id = field(last, :id)) && query.merge("before" => id)
+      else
+        (id = field(first, :id)) && query.merge("after" => id)
+      end
+    end
+
+    # @api private
+    def self.thread_query(query, last)
+      id = field(last, :id)
+      at = field(last, :last_message_at)
+      id && at && query.merge("before" => at, "before_id" => id)
+    end
+
+    # @api private
+    def self.field(item, key)
+      present(item.is_a?(Hash) ? item[key] : nil)
+    end
+
+    # @api private
+    def self.present(value)
+      value.nil? || value == "" ? nil : value
+    end
+  end
+end

data/lib/zapsmtp/rails/delivery_method.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module ZapSMTP
+  module Rails
+    # A Mail / ActionMailer delivery method that sends through the ZapSMTP API.
+    #
+    #   # config/environments/production.rb
+    #   config.action_mailer.delivery_method = :zapsmtp
+    #   config.action_mailer.zapsmtp_settings = { api_key: ENV["ZAP_API_KEY"] }
+    #
+    # Settings: api_key, base_url, timeout, max_retries, default_headers and
+    # transport (as for ZapSMTP::Client.new), or client: a ZapSMTP::Client;
+    # return_response: true makes Mail::Message#deliver! answer the API's
+    # response. After a send the message carries the email's id in its
+    # X-Zapsmtp-Email-Id header.
+    class DeliveryMethod
+      CLIENT_SETTINGS = %i[api_key base_url timeout max_retries default_headers transport].freeze
+
+      @clients = {}
+      @mutex = Mutex.new
+
+      class << self
+        # One client per distinct settings, shared by the deliveries that use
+        # them (Mail makes a delivery method per message).
+        #
+        # @api private
+        def client_for(settings)
+          config = settings.slice(*CLIENT_SETTINGS)
+          @mutex.synchronize { @clients[config] ||= ZapSMTP::Client.new(**config) }
+        end
+      end
+
+      # @return [Hash]
+      attr_accessor :settings
+
+      def initialize(settings = {})
+        @settings = settings.to_h.transform_keys(&:to_sym)
+      end
+
+      # Sends the message; raises a ZapSMTP::Error when the API refuses it.
+      #
+      # The message keeps its options until the API has taken it, and its
+      # Idempotency-Key (the caller's, or one made on the first attempt and
+      # kept with the options): delivering the same message again after a
+      # failure, a lost answer included, sends the same request and never
+      # sends twice.
+      #
+      # @param message [Mail::Message]
+      # @return [ZapSMTP::Models::SendEmailResponse]
+      def deliver!(message)
+        options = ZapSMTP::Rails.options(message)
+        unless options["idempotency_key"]
+          options["idempotency_key"] = SecureRandom.uuid
+          ZapSMTP::Rails.set_options(message, options)
+        end
+        key = options.delete("idempotency_key")
+        result = client.emails.send(Message.params(message, options), request_options: { idempotency_key: key })
+        message[OPTIONS_HEADER] = nil
+        message[EMAIL_ID_HEADER] = result.id
+        result
+      end
+
+      # @return [ZapSMTP::Client]
+      def client
+        settings[:client] || DeliveryMethod.client_for(settings)
+      end
+    end
+  end
+end

data/lib/zapsmtp/rails/message.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ZapSMTP
+  module Rails
+    # Turns a Mail::Message into emails.send parameters.
+    module Message
+      # Headers the message's own fields already carry, or the API sets.
+      SKIPPED_HEADERS = %w[
+        from to cc bcc reply-to subject date message-id mime-version content-type content-transfer-encoding
+        content-disposition content-id return-path received dkim-signature
+        x-zapsmtp-options x-zapsmtp-email-id
+      ].freeze
+
+      module_function
+
+      # @param message [Mail::Message]
+      # @param options [Hash{String => Object}] see ZapSMTP::Rails.set_options
+      # @return [Hash{String => Object}]
+      def params(message, options = {})
+        params = {}
+        from = addresses(message, :from)
+        params["from"] = from.first if from
+        { "to" => :to, "cc" => :cc, "bcc" => :bcc, "reply_to" => :reply_to }.each do |key, field|
+          list = addresses(message, field)
+          params[key] = list if list
+        end
+        params["subject"] = message.subject unless message.subject.nil?
+        add_bodies(params, message) unless options.key?("template")
+        headers = custom_headers(message)
+        params["headers"] = headers unless headers.empty?
+        attachments = message.attachments.map { |part| attachment(part) }
+        params["attachments"] = attachments unless attachments.empty?
+        params.merge(options).compact
+      end
+
+      # A field's addresses, formatted with their display names; nil when
+      # the field is absent or empty.
+      def addresses(message, name)
+        field = message[name]
+        return nil if field.nil?
+
+        list = field.field.respond_to?(:addrs) ? field.addrs.map(&:format) : [field.value.to_s]
+        list.empty? ? nil : list
+      end
+
+      def add_bodies(params, message)
+        if message.multipart?
+          params["html"] = message.html_part&.decoded
+          params["text"] = message.text_part&.decoded
+        elsif message.mime_type == "text/html"
+          params["html"] = message.decoded
+        else
+          params["text"] = message.decoded
+        end
+      end
+
+      # The message's other header fields: In-Reply-To, References, List-Unsubscribe, X-...
+      def custom_headers(message)
+        message.header.fields.each_with_object({}) do |field, out|
+          next if SKIPPED_HEADERS.include?(field.name.downcase)
+
+          out[field.name] = field.value.to_s
+        end
+      end
+
+      def attachment(part)
+        out = { "filename" => part.filename, "content" => [part.body.decoded].pack("m0"),
+                "content_type" => part.mime_type }
+        out["content_id"] = part.cid if part.inline?
+        out.compact
+      end
+    end
+  end
+end

data/lib/zapsmtp/rails/webhook_verification.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ZapSMTP
+  module Rails
+    # A controller concern that verifies ZapSMTP webhook requests. A request
+    # whose signature is missing, wrong or too old is answered 400.
+    #
+    #   class ZapsmtpWebhooksController < ActionController::API
+    #     include ZapSMTP::Rails::WebhookVerification
+    #
+    #     def create
+    #       event = zapsmtp_webhook_event # zapsmtp_webhook_events for a webhook with batch delivery
+    #       EmailBounce.record(event.data) if event.type == "email.bounced"
+    #       head :ok
+    #     end
+    #   end
+    #
+    # The secret is ENV["ZAP_WEBHOOK_SECRET"]; override #zapsmtp_webhook_secret
+    # to take it from elsewhere (credentials). In an ActionController::Base
+    # controller, skip_forgery_protection for the action.
+    module WebhookVerification
+      def self.included(controller)
+        controller.rescue_from(ZapSMTP::WebhookVerificationError) do |error|
+          render json: { error: error.message }, status: :bad_request
+        end
+      end
+
+      private
+
+      # The verified event of this request.
+      #
+      # @return [ZapSMTP::WebhookEvent]
+      # @raise [ZapSMTP::WebhookVerificationError]
+      def zapsmtp_webhook_event
+        @zapsmtp_webhook_event ||= ZapSMTP::Webhook.verify(request.raw_post, request.headers,
+                                                           zapsmtp_webhook_secret,
+                                                           tolerance: zapsmtp_webhook_tolerance)
+      end
+
+      # The verified events of this request: every event of a batch (a
+      # webhook with batch: true), or its one event.
+      #
+      # @return [Array<ZapSMTP::WebhookEvent>]
+      # @raise [ZapSMTP::WebhookVerificationError]
+      def zapsmtp_webhook_events
+        @zapsmtp_webhook_events ||= ZapSMTP::Webhook.verify_events(request.raw_post, request.headers,
+                                                                   zapsmtp_webhook_secret,
+                                                                   tolerance: zapsmtp_webhook_tolerance)
+      end
+
+      # A before_action: refuses a request whose signature is not valid.
+      def verify_zapsmtp_webhook!
+        zapsmtp_webhook_events
+      end
+
+      # @return [String]
+      def zapsmtp_webhook_secret
+        ENV.fetch("ZAP_WEBHOOK_SECRET", nil)
+      end
+
+      # @return [Integer] seconds
+      def zapsmtp_webhook_tolerance
+        ZapSMTP::Webhook::DEFAULT_TOLERANCE
+      end
+    end
+  end
+end

data/lib/zapsmtp/rails.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "core"
+
+module ZapSMTP
+  # The Rails and Mail integration: an ActionMailer delivery method
+  # (ZapSMTP::Rails::DeliveryMethod) and a controller concern that verifies
+  # webhooks (ZapSMTP::Rails::WebhookVerification). In a Rails app the
+  # Railtie registers the delivery method as :zapsmtp; with the Mail gem
+  # alone, require "zapsmtp/rails" and use the class.
+  module Rails
+    # The private header that carries the zapsmtp: options of a mail()
+    # call (tags, metadata, stream, template...) to the delivery method,
+    # which removes it before sending.
+    OPTIONS_HEADER = "X-Zapsmtp-Options"
+    # The header the delivery method sets on a sent message: the email's id.
+    EMAIL_ID_HEADER = "X-Zapsmtp-Email-Id"
+
+    module_function
+
+    # Registers the delivery method and the zapsmtp: option of mail() on
+    # ActionMailer::Base (the Railtie does this).
+    def install(mailer_base)
+      mailer_base.add_delivery_method(:zapsmtp, DeliveryMethod)
+      mailer_base.prepend(MailerOptions)
+    end
+
+    # Sets the ZapSMTP options of a Mail::Message: tags, metadata, stream,
+    # template, tracking, scheduled_at, tls, idempotency_key, or any other
+    # emails.send parameter. A nil value removes that parameter.
+    def set_options(message, options)
+      message[OPTIONS_HEADER] = nil
+      message[OPTIONS_HEADER] = JSON.generate(options, ascii_only: true)
+      message
+    end
+
+    # Reads the options of a Mail::Message (they stay on it until it is sent).
+    #
+    # @return [Hash{String => Object}]
+    def options(message)
+      field = message.header.fields.reverse.find { |f| f.name.casecmp?(OPTIONS_HEADER) }
+      return {} unless field
+
+      options = JSON.parse(field.value.to_s)
+      raise ArgumentError unless options.is_a?(Hash)
+
+      options
+    rescue JSON::ParserError, ArgumentError
+      raise Error, "#{OPTIONS_HEADER} must be a JSON object"
+    end
+
+    # The zapsmtp: option of ActionMailer's mail():
+    #
+    #   mail(to: user.email, subject: "Welcome", zapsmtp: { tags: [{ name: "category", value: "welcome" }],
+    #                                                        metadata: { user_id: user.id.to_s } })
+    module MailerOptions
+      def mail(headers = {}, &block)
+        return super unless headers.is_a?(Hash) && headers.key?(:zapsmtp)
+
+        message = super(headers.except(:zapsmtp), &block)
+        ZapSMTP::Rails.set_options(message, headers[:zapsmtp])
+      end
+    end
+  end
+end
+
+require_relative "rails/message"
+require_relative "rails/delivery_method"
+require_relative "rails/webhook_verification"

data/lib/zapsmtp/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "rails"
+
+module ZapSMTP
+  module Rails
+    # Registers the :zapsmtp delivery method with ActionMailer:
+    #
+    #   config.action_mailer.delivery_method = :zapsmtp
+    #   config.action_mailer.zapsmtp_settings = { api_key: ENV["ZAP_API_KEY"] }
+    class Railtie < ::Rails::Railtie
+      initializer "zapsmtp.action_mailer", before: "action_mailer.set_configs" do
+        ActiveSupport.on_load(:action_mailer) { ZapSMTP::Rails.install(self) }
+      end
+    end
+  end
+end

data/lib/zapsmtp/response.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ZapSMTP
+  # What the API answered besides the body: the status, the headers (rate
+  # limits, quotas) and the request id.
+  class Response
+    # @return [Integer]
+    attr_reader :status
+    # @return [Hash{String => String}] names in lower case
+    attr_reader :headers
+    # @return [String, nil] X-Request-Id: quote it to support
+    attr_reader :request_id
+
+    def initialize(status, headers)
+      @status = status
+      @headers = headers
+      @request_id = headers["x-request-id"]
+    end
+
+    # A header's value, its name in any case.
+    #
+    # @return [String, nil]
+    def [](name)
+      headers[name.to_s.downcase]
+    end
+
+    def inspect
+      "#<#{self.class.name} status=#{status} request_id=#{request_id.inspect}>"
+    end
+  end
+
+  # A result with its response, from ZapSMTP::Client#with_response:
+  #
+  #   email, response = zap.with_response.emails.get(id)
+  Result = Struct.new(:data, :response) do
+    def to_ary
+      [data, response]
+    end
+  end
+end