agdirlabs-email 0.1.0

data/lib/agdirlabs/email/webhook.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    # Verification of signed webhook requests (Standard Webhooks: `webhook-id`,
+    # `webhook-timestamp`, `webhook-signature`).
+    module Webhook
+      # Alias of {AgdirLabs::Email::WebhookVerificationError}.
+      VerificationError = WebhookVerificationError
+
+      # Default maximum age (and clock skew) of a message, in seconds.
+      DEFAULT_TOLERANCE = 300
+
+      module_function
+
+      # Checks that a webhook request came from Agdir Email and returns the parsed event.
+      #
+      #   event = AgdirLabs::Email::Webhook.verify(
+      #     payload: request.raw_post, headers: request.headers, secret: ENV["AGDIR_EMAIL_WEBHOOK_SECRET"]
+      #   )
+      #
+      # @param payload [String] the raw request body, exactly as received (not re-serialized JSON)
+      # @param headers [Hash, #[]] request headers: a Hash (any key case, Rack `HTTP_*` keys work too),
+      #   or any object answering `headers["webhook-id"]` (e.g. Rails `request.headers`)
+      # @param secret [String] the webhook's `whsec_…` signing secret
+      # @param tolerance [Integer] reject messages older or newer than this many seconds
+      # @param now [Time] for tests
+      # @return [WebhookEvent]
+      # @raise [WebhookVerificationError]
+      def verify(payload:, headers:, secret:, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+        id = header(headers, "webhook-id")
+        timestamp = header(headers, "webhook-timestamp")
+        signatures = header(headers, "webhook-signature")
+        raise WebhookVerificationError, "Missing webhook signature headers" unless id && timestamp && signatures
+
+        sent_at = Integer(timestamp, 10, exception: false)
+        if sent_at.nil? || (now.to_i - sent_at).abs > tolerance
+          raise WebhookVerificationError, "Webhook timestamp is outside the allowed tolerance"
+        end
+
+        expected = sign(secret: secret, id: id, timestamp: timestamp, payload: payload)
+        # The header may hold several space-separated `v1,<sig>` entries (e.g. during secret rotation).
+        valid = signatures.split.any? do |entry|
+          entry.start_with?("v1,") && secure_compare(entry.delete_prefix("v1,"), expected)
+        end
+        raise WebhookVerificationError, "Webhook signature does not match" unless valid
+
+        begin
+          json = JSON.parse(payload)
+          raise WebhookVerificationError, "Webhook payload is not a JSON object" unless json.is_a?(Hash)
+
+          Wire.webhook_event(json)
+        rescue JSON::ParserError
+          raise WebhookVerificationError, "Webhook payload is not valid JSON"
+        end
+      end
+
+      # Computes the base64 `v1` signature of a message. Useful to sign test requests.
+      # @return [String]
+      # @raise [WebhookVerificationError] when the secret is not valid base64
+      def sign(secret:, id:, timestamp:, payload:)
+        encoded = secret.to_s.delete_prefix("whsec_")
+        key = begin
+          encoded.unpack1("m0")
+        rescue ArgumentError
+          raise WebhookVerificationError, "Signing secret is not valid base64"
+        end
+        [OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{payload}")].pack("m0")
+      end
+
+      # @api private
+      def header(headers, name)
+        value = if headers.is_a?(Hash)
+                  rack = "HTTP_#{name.upcase.tr("-", "_")}"
+                  match = headers.find { |k, _| k.to_s.casecmp?(name) || k.to_s == rack }
+                  match&.last
+                else
+                  headers[name]
+                end
+        value = value.first if value.is_a?(Array)
+        value.nil? || value.to_s.empty? ? nil : value.to_s
+      end
+
+      # @api private
+      def secure_compare(left, right)
+        return false unless left.bytesize == right.bytesize
+
+        OpenSSL.fixed_length_secure_compare(left, right)
+      end
+    end
+  end
+end

data/lib/agdirlabs/email/wire.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module AgdirLabs
+  module Email
+    # Mapping between the SDK's Ruby objects and the API's JSON.
+    # @api private
+    module Wire
+      module_function
+
+      def time(value) = Time.iso8601(value.to_s)
+      def optional_time(value) = value.nil? || value == "" ? nil : time(value)
+      def list(value) = (value.nil? ? [] : Array(value)).map { |v| str(v) }.freeze
+      def str(value) = value.nil? ? nil : value.to_s.dup.freeze
+
+      def deep_freeze(value)
+        case value
+        when Hash then value.each_value { |v| deep_freeze(v) }.freeze
+        when Array then value.each { |v| deep_freeze(v) }.freeze
+        else value.freeze
+        end
+      end
+
+      # Builds a `POST /emails` body from keyword arguments (snake_case on both sides).
+      def send_email_body(params)
+        params = params.transform_keys(&:to_sym)
+        unknown = params.keys - SEND_KEYS
+        raise ArgumentError, "unknown email field(s): #{unknown.join(", ")}" unless unknown.empty?
+
+        scheduled_at = params[:scheduled_at]
+        scheduled_at = scheduled_at.iso8601 if scheduled_at.respond_to?(:iso8601) && !scheduled_at.is_a?(String)
+        tags = params[:tags]
+        tags = tags.map { |name, value| { name: name.to_s, value: value.to_s } } if tags.is_a?(Hash)
+        {
+          from: params[:from],
+          to: params[:to],
+          subject: params[:subject],
+          html: params[:html],
+          text: params[:text],
+          cc: params[:cc],
+          bcc: params[:bcc],
+          reply_to: params[:reply_to],
+          headers: params[:headers]&.to_h { |k, v| [k.to_s, v.to_s] },
+          tags: tags&.map { |t| { name: (t[:name] || t["name"]).to_s, value: (t[:value] || t["value"]).to_s } },
+          scheduled_at: scheduled_at
+        }.compact
+      end
+
+      SEND_KEYS = %i[from to subject html text cc bcc reply_to headers tags scheduled_at].freeze
+
+      def email(json)
+        EmailDetails.new(
+          id: str(json["id"]),
+          from: str(json["from"]),
+          to: list(json["to"]),
+          cc: list(json["cc"]),
+          bcc: list(json["bcc"]),
+          reply_to: list(json["reply_to"]),
+          subject: str(json["subject"]),
+          html: str(json["html"]),
+          text: str(json["text"]),
+          created_at: time(json["created_at"]),
+          scheduled_at: optional_time(json["scheduled_at"]),
+          status: str(json["last_event"])
+        )
+      end
+
+      def record(json)
+        DnsRecord.new(
+          purpose: str(json["record"]),
+          name: str(json["name"]),
+          type: str(json["type"]),
+          value: str(json["value"]),
+          ttl: str(json["ttl"]),
+          priority: json["priority"],
+          status: str(json["status"])
+        )
+      end
+
+      def domain(json)
+        Domain.new(
+          id: str(json["id"]),
+          name: str(json["name"]),
+          status: str(json["status"]),
+          region: str(json["region"]),
+          created_at: time(json["created_at"]),
+          open_tracking: json["open_tracking"] ? true : false,
+          click_tracking: json["click_tracking"] ? true : false,
+          records: json.key?("records") ? (json["records"] || []).map { |r| record(r) }.freeze : nil
+        )
+      end
+
+      def webhook(json)
+        WebhookEndpoint.new(
+          id: str(json["id"]),
+          endpoint: str(json["endpoint"]),
+          status: str(json["status"]),
+          events: list(json["events"]),
+          created_at: time(json["created_at"]),
+          signing_secret: str(json["signing_secret"])
+        )
+      end
+
+      def delivery(json)
+        WebhookDelivery.new(
+          id: str(json["id"]),
+          type: str(json["type"]),
+          status: str(json["status"]),
+          created_at: time(json["created_at"]),
+          next_attempt_at: optional_time(json["next_attempt_at"]),
+          payload: deep_freeze(json["payload"])
+        )
+      end
+
+      def attempt(json)
+        WebhookAttempt.new(
+          id: str(json["id"]),
+          http_status: json["http_status_code"].to_i,
+          response: str(json["response"]),
+          sent_at: time(json["sent_at"])
+        )
+      end
+
+      def page(json, &)
+        items = json["data"] || []
+        has_more = json["has_more"] ? true : false
+        last = items.last
+        Page.new(
+          data: items.map(&),
+          has_more: has_more,
+          next_cursor: has_more && last ? last["id"].to_s.freeze : nil
+        )
+      end
+
+      def webhook_event(json)
+        d = json["data"] || {}
+        WebhookEvent.new(
+          type: str(json["type"]),
+          created_at: time(json["created_at"]),
+          data: WebhookEventData.new(
+            email_id: str(d["email_id"]),
+            message_id: str(d["message_id"]),
+            from: str(d["from"]),
+            to: list(d["to"]),
+            subject: str(d["subject"]),
+            tags: deep_freeze((d["tags"] || {}).to_h { |k, v| [k.to_s, v.to_s] }),
+            created_at: time(d["created_at"]),
+            bounce: d["bounce"] && bounce(d["bounce"]),
+            click: d["click"] && click(d["click"]),
+            failed: d["failed"] && Failure.new(reason: str(d["failed"]["reason"]))
+          )
+        )
+      end
+
+      def bounce(json)
+        Bounce.new(type: str(json["type"]), sub_type: str(json["subType"]), message: str(json["message"]))
+      end
+
+      def click(json)
+        Click.new(link: str(json["link"]), ip_address: str(json["ipAddress"]), user_agent: str(json["userAgent"]),
+                  timestamp: optional_time(json["timestamp"]))
+      end
+    end
+  end
+end

data/lib/agdirlabs/email.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "time"
+require "uri"
+
+module AgdirLabs
+  # The official Ruby SDK for Agdir Email (https://agdir.email).
+  #
+  #   client = AgdirLabs::Email::Client.new(api_key: "re_…")
+  #   client.emails.send(from: "Acme <hi@acme.com>", to: "ana@example.com", subject: "Hi", html: "<p>Hi</p>")
+  module Email
+  end
+end
+
+require_relative "email/version"
+require_relative "email/errors"
+require_relative "email/models"
+require_relative "email/wire"
+require_relative "email/transport"
+require_relative "email/resources/emails"
+require_relative "email/resources/domains"
+require_relative "email/resources/webhooks"
+require_relative "email/client"
+require_relative "email/webhook"
+require_relative "email/delivery_method"
+require_relative "email/railtie" if defined?(Rails::Railtie)

data/sig/agdirlabs/email.rbs

@@ -0,0 +1,318 @@
+module AgdirLabs
+  module Email
+    VERSION: String
+    USER_AGENT: String
+    DEFAULT_BASE_URL: String
+
+    type address = String
+    type addresses = String | Array[String]
+    type tags = Array[{ name: String, value: String }] | Hash[String | Symbol, untyped]
+
+    class Error < StandardError
+      CODES: Hash[String, singleton(Error)]
+
+      attr_reader code: String
+      attr_reader status: Integer
+      attr_reader retry_after: Float?
+
+      def initialize: (?String? message, ?code: String, ?status: Integer, ?retry_after: Float?) -> void
+      def self.build: (String message, code: String, status: Integer, ?retry_after: Float?) -> Error
+    end
+
+    class AuthenticationError < Error
+    end
+
+    class ValidationError < Error
+    end
+
+    class NotFoundError < Error
+    end
+
+    class IdempotencyError < Error
+    end
+
+    class RateLimitError < Error
+    end
+
+    class QuotaExceededError < Error
+    end
+
+    class ServerError < Error
+    end
+
+    class ConnectionError < Error
+    end
+
+    class TimeoutError < ConnectionError
+    end
+
+    class ConfigurationError < ArgumentError
+    end
+
+    class WebhookVerificationError < StandardError
+    end
+
+    class UnsupportedMessageError < ArgumentError
+    end
+
+    class SendResult
+      attr_reader id: String
+      def initialize: (id: String) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class BatchError
+      attr_reader index: Integer
+      attr_reader message: String
+      def initialize: (index: Integer, message: String) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class BatchResult
+      attr_reader data: Array[SendResult]
+      attr_reader errors: Array[BatchError]
+      def initialize: (data: Array[SendResult], errors: Array[BatchError]) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class Result
+      attr_reader id: String
+      attr_reader deleted: bool
+      def initialize: (id: String, deleted: bool) -> void
+      def deleted?: () -> bool
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class EmailDetails
+      attr_reader id: String
+      attr_reader from: String
+      attr_reader to: Array[String]
+      attr_reader cc: Array[String]
+      attr_reader bcc: Array[String]
+      attr_reader reply_to: Array[String]
+      attr_reader subject: String
+      attr_reader html: String?
+      attr_reader text: String?
+      attr_reader created_at: Time
+      attr_reader scheduled_at: Time?
+      attr_reader status: String
+      def initialize: (**untyped) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class DnsRecord
+      attr_reader purpose: String
+      attr_reader name: String
+      attr_reader type: String
+      attr_reader value: String
+      attr_reader ttl: String
+      attr_reader priority: Integer?
+      attr_reader status: String
+      def initialize: (**untyped) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class Domain
+      attr_reader id: String
+      attr_reader name: String
+      attr_reader status: String
+      attr_reader region: String
+      attr_reader created_at: Time
+      attr_reader open_tracking: bool
+      attr_reader click_tracking: bool
+      attr_reader records: Array[DnsRecord]?
+      def initialize: (**untyped) -> void
+      def verified?: () -> bool
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class WebhookEndpoint
+      attr_reader id: String
+      attr_reader endpoint: String
+      attr_reader status: String
+      attr_reader events: Array[String]
+      attr_reader created_at: Time
+      attr_reader signing_secret: String?
+      def initialize: (**untyped) -> void
+      def enabled?: () -> bool
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class WebhookSecret
+      attr_reader id: String
+      attr_reader signing_secret: String
+      def initialize: (id: String, signing_secret: String) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class WebhookDelivery
+      attr_reader id: String
+      attr_reader type: String
+      attr_reader status: String
+      attr_reader created_at: Time
+      attr_reader next_attempt_at: Time?
+      attr_reader payload: Hash[String, untyped]?
+      def initialize: (**untyped) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class WebhookAttempt
+      attr_reader id: String
+      attr_reader http_status: Integer
+      attr_reader response: String
+      attr_reader sent_at: Time
+      def initialize: (**untyped) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class Bounce
+      attr_reader type: String
+      attr_reader sub_type: String
+      attr_reader message: String
+      def initialize: (type: String, sub_type: String, message: String) -> void
+    end
+
+    class Click
+      attr_reader link: String
+      attr_reader ip_address: String
+      attr_reader user_agent: String
+      attr_reader timestamp: Time?
+      def initialize: (link: String, ip_address: String, user_agent: String, timestamp: Time?) -> void
+    end
+
+    class Failure
+      attr_reader reason: String
+      def initialize: (reason: String) -> void
+    end
+
+    class WebhookEventData
+      attr_reader email_id: String
+      attr_reader message_id: String?
+      attr_reader from: String
+      attr_reader to: Array[String]
+      attr_reader subject: String
+      attr_reader tags: Hash[String, String]
+      attr_reader created_at: Time
+      attr_reader bounce: Bounce?
+      attr_reader click: Click?
+      attr_reader failed: Failure?
+      def initialize: (**untyped) -> void
+    end
+
+    class WebhookEvent
+      attr_reader type: String
+      attr_reader created_at: Time
+      attr_reader data: WebhookEventData
+      def initialize: (type: String, created_at: Time, data: WebhookEventData) -> void
+    end
+
+    class Page[T]
+      include Enumerable[T]
+
+      attr_reader data: Array[T]
+      attr_reader has_more: bool
+      attr_reader next_cursor: String?
+
+      def initialize: (data: Array[T], has_more: bool, next_cursor: String?) -> void
+      def has_more?: () -> bool
+      def each: () { (T) -> void } -> Array[T]
+              | () -> Enumerator[T, Array[T]]
+      def size: () -> Integer
+      def length: () -> Integer
+      def empty?: () -> bool
+      def to_h: () -> { data: Array[T], has_more: bool, next_cursor: String? }
+    end
+
+    class HttpResponse
+      attr_reader status: Integer
+      attr_reader headers: Hash[String, String]
+      attr_reader body: String
+      def initialize: (status: Integer, headers: Hash[String, String], body: String) -> void
+    end
+
+    interface _HttpClient
+      def call: (method: String, url: URI::Generic, headers: Hash[String, String], body: String?, timeout: Numeric) -> HttpResponse
+    end
+
+    class NetHttpClient
+      include _HttpClient
+    end
+
+    class Client
+      attr_reader emails: Resources::Emails
+      attr_reader domains: Resources::Domains
+      attr_reader webhooks: Resources::Webhooks
+      attr_reader base_url: String
+      attr_reader max_retries: Integer
+      attr_reader timeout: Numeric
+
+      def initialize: (?api_key: String?, ?base_url: String?, ?max_retries: Integer, ?timeout: Numeric, ?http_client: _HttpClient?) -> void
+    end
+
+    module Resources
+      class Emails
+        MAX_BATCH_SIZE: Integer
+
+        def send: (from: address, to: addresses, subject: String, ?html: String?, ?text: String?, ?cc: addresses?,
+                   ?bcc: addresses?, ?reply_to: addresses?, ?headers: Hash[String | Symbol, untyped]?, ?tags: tags?,
+                   ?scheduled_at: Time | String | nil, ?idempotency_key: String?) -> SendResult
+        def send_batch: (Array[Hash[Symbol, untyped]] emails, ?validation: :strict | :permissive | String, ?idempotency_key: String?) -> BatchResult
+        def get: (String id) -> EmailDetails
+        def cancel: (String id) -> Result
+      end
+
+      class Domains
+        def create: (name: String, ?region: String?) -> Domain
+        def get: (String id) -> Domain
+        def list: (?limit: Integer?, ?after: String?) -> Page[Domain]
+        def list_all: (?limit: Integer?, ?after: String?) -> Enumerator[Domain, void]
+        def verify: (String id) -> Result
+        def delete: (String id) -> Result
+      end
+
+      class WebhookDeliveries
+        def list: (String webhook_id, ?limit: Integer?, ?after: String?) -> Page[WebhookDelivery]
+        def list_all: (String webhook_id, ?limit: Integer?, ?after: String?) -> Enumerator[WebhookDelivery, void]
+        def get: (String webhook_id, String delivery_id) -> WebhookDelivery
+        def attempts: (String webhook_id, String delivery_id, ?limit: Integer?, ?after: String?) -> Page[WebhookAttempt]
+        def replay: (String webhook_id, String delivery_id) -> Result
+      end
+
+      class Webhooks
+        EVENT_TYPES: Array[String]
+
+        attr_reader deliveries: WebhookDeliveries
+
+        def create: (endpoint: String, events: Array[String] | String) -> WebhookSecret
+        def get: (String id) -> WebhookEndpoint
+        def list: (?limit: Integer?, ?after: String?) -> Page[WebhookEndpoint]
+        def list_all: (?limit: Integer?, ?after: String?) -> Enumerator[WebhookEndpoint, void]
+        def update: (String id, ?endpoint: String?, ?events: Array[String] | String | nil, ?status: String | Symbol | nil) -> Result
+        def delete: (String id) -> Result
+        def rotate_secret: (String id) -> WebhookSecret
+      end
+    end
+
+    module Webhook
+      VerificationError: singleton(WebhookVerificationError)
+      DEFAULT_TOLERANCE: Integer
+
+      def self.verify: (payload: String, headers: untyped, secret: String, ?tolerance: Integer, ?now: Time) -> WebhookEvent
+      def self.sign: (secret: String, id: String, timestamp: String | Integer, payload: String) -> String
+    end
+
+    class DeliveryMethod
+      TAGS_HEADER: String
+      SCHEDULED_AT_HEADER: String
+      IDEMPOTENCY_KEY_HEADER: String
+      EMAIL_ID_HEADER: String
+
+      attr_accessor settings: Hash[Symbol, untyped]
+
+      def initialize: (?Hash[String | Symbol, untyped]? settings) -> void
+      def deliver!: (untyped mail) -> SendResult
+      def client: () -> Client
+      def self.to_params: (untyped mail) -> [Hash[Symbol, untyped], String?]
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: agdirlabs-email
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Agdir AS
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Send transactional email, manage sending domains and webhooks, and verify
+  signed webhook events with the Agdir Email API. Includes an ActionMailer / mail
+  gem delivery method. No runtime dependencies.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/agdirlabs/email.rb
+- lib/agdirlabs/email/client.rb
+- lib/agdirlabs/email/delivery_method.rb
+- lib/agdirlabs/email/errors.rb
+- lib/agdirlabs/email/models.rb
+- lib/agdirlabs/email/railtie.rb
+- lib/agdirlabs/email/resources/domains.rb
+- lib/agdirlabs/email/resources/emails.rb
+- lib/agdirlabs/email/resources/webhooks.rb
+- lib/agdirlabs/email/transport.rb
+- lib/agdirlabs/email/version.rb
+- lib/agdirlabs/email/webhook.rb
+- lib/agdirlabs/email/wire.rb
+- sig/agdirlabs/email.rbs
+homepage: https://agdir.email
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://agdir.email
+  source_code_uri: https://github.com/AgdirAS/agdirlabs-sdks/tree/main/ruby
+  changelog_uri: https://github.com/AgdirAS/agdirlabs-sdks/blob/main/ruby/CHANGELOG.md
+  bug_tracker_uri: https://github.com/AgdirAS/agdirlabs-sdks/issues
+  documentation_uri: https://github.com/AgdirAS/agdirlabs-sdks/tree/main/ruby#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby SDK for Agdir Email — programmatic SMTP for developers, hosted
+  in the EU.
+test_files: []