letmesendemail 0.1.0

data/lib/letmesendemail/client.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module LetMeSendEmail
+  # HTTP client and entry point for all API resources.
+  class Client
+    RETRYABLE_HTTP_STATUSES = [408, 500, 502, 503, 504].freeze
+    SAFE_METHODS = %i[get delete].freeze
+    MAX_RETRY_DELAY_SECONDS = 300
+    BASE_RETRY_DELAY_SECONDS = 0.1
+
+    # @return [Resources::Emails]
+    attr_reader :emails
+    # @return [Resources::Domains]
+    attr_reader :domains
+    # @return [Resources::Contacts]
+    attr_reader :contacts
+    # @return [Resources::ContactCategories]
+    attr_reader :contact_categories
+    # @return [Resources::EmailTopics]
+    attr_reader :email_topics
+
+    # @param api_key [String, nil]
+    # @param config [Config, nil]
+    # @raise [ArgumentError] when configuration is invalid
+    def initialize(api_key: nil, config: nil)
+      raise ArgumentError, 'provide api_key or config, not both' if api_key && config
+
+      @config = config || Config.new(api_key || raise(ArgumentError, 'api_key is required'))
+      raise ArgumentError, 'config must be a LetMeSendEmail::Config' unless @config.is_a?(Config)
+
+      @config = @config.dup.validate!.freeze
+      @transport = HttpTransport.new(@config)
+      initialize_resources
+    end
+
+    # Performs an API request. Resource classes provide the primary public API.
+    # @param method [Symbol]
+    # @param path [String]
+    # @param body [Hash, nil]
+    # @param extra_headers [Hash]
+    # @return [Models::Model]
+    # @raise [Error]
+    def request(method, path, body: nil, extra_headers: {})
+      retry_eligible = retry_eligible?(method, extra_headers)
+      max_attempts = retry_eligible ? @config.retries + 1 : 1
+      last_error = nil
+
+      max_attempts.times do |attempt|
+        return @transport.call(method, path, body: body, extra_headers: extra_headers)
+      rescue RateLimitError => e
+        raise unless attempt < max_attempts - 1 && e.retry_after
+
+        last_error = e
+        sleep(e.retry_after)
+      rescue NetworkError, TimeoutError => e
+        raise unless attempt < max_attempts - 1
+
+        last_error = e
+        sleep(retry_delay(attempt))
+      rescue ApiError => e
+        raise unless RETRYABLE_HTTP_STATUSES.include?(e.status_code) && attempt < max_attempts - 1
+
+        last_error = e
+        sleep(retry_delay(attempt))
+      end
+
+      raise last_error
+    end
+
+    # Encodes an untrusted identifier as exactly one URL path segment.
+    # @param id [String]
+    # @return [String]
+    # @raise [ArgumentError] when the identifier is empty or unsafe
+    def resource_path_segment(id)
+      raise ArgumentError, 'resource id must be a string' unless id.is_a?(String)
+
+      value = id
+      if value.empty? || value != value.strip || %w[. ..].include?(value) || value.match?(/[[:cntrl:]]/)
+        raise ArgumentError, 'resource id must be non-empty and must not be a dot segment or contain unsafe whitespace'
+      end
+
+      URI::DEFAULT_PARSER.escape(value, /[^A-Za-z0-9\-._~]/)
+    end
+
+    private
+
+    def initialize_resources
+      @emails = Resources::Emails.new(self)
+      @domains = Resources::Domains.new(self)
+      @contacts = Resources::Contacts.new(self)
+      @contact_categories = Resources::ContactCategories.new(self)
+      @email_topics = Resources::EmailTopics.new(self)
+    end
+
+    def retry_eligible?(method, headers)
+      return true if SAFE_METHODS.include?(method)
+
+      key = headers['Idempotency-Key'] || headers['idempotency-key']
+      %i[post put].include?(method) && key.is_a?(String) && !key.empty?
+    end
+
+    def retry_delay(attempt)
+      base = [BASE_RETRY_DELAY_SECONDS * (2**attempt), MAX_RETRY_DELAY_SECONDS].min
+      [base + (rand * base * 0.25), MAX_RETRY_DELAY_SECONDS].min
+    end
+  end
+end

data/lib/letmesendemail/config.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module LetMeSendEmail
+  # Validated client configuration.
+  class Config
+    DEFAULT_BASE_URL = 'https://letmesend.email/api/v1'
+    DEFAULT_TIMEOUT_MS = 30_000
+    DEFAULT_RETRIES = 0
+    MAX_RETRIES = 20
+
+    attr_reader :base_url
+    attr_accessor :api_key, :timeout_ms, :retries
+
+    # @param api_key [String] API bearer token
+    def initialize(api_key)
+      @api_key = api_key
+      @base_url = DEFAULT_BASE_URL
+      @timeout_ms = DEFAULT_TIMEOUT_MS
+      @retries = DEFAULT_RETRIES
+    end
+
+    # @param url [String] absolute API base URL
+    # @return [String]
+    def base_url=(url)
+      @base_url = url.to_s.sub(%r{/+\z}, '')
+    end
+
+    # Validates and normalizes configuration before use.
+    # @return [self]
+    # @raise [ArgumentError] for unsafe or unsupported configuration
+    def validate!
+      validate_api_key!
+      validate_base_url!
+      validate_timeout!
+      validate_retries!
+      @api_key = api_key.dup.freeze
+      @base_url = base_url.dup.freeze
+      self
+    end
+
+    private
+
+    def validate_api_key!
+      return if api_key.is_a?(String) && !api_key.empty? && api_key == api_key.strip && !api_key.match?(/[[:cntrl:]]/)
+
+      raise ArgumentError, 'api_key must be a non-empty string without surrounding whitespace or control characters'
+    end
+
+    def validate_base_url!
+      uri = URI.parse(base_url)
+      unless valid_base_uri?(uri)
+        raise ArgumentError,
+              'base_url must be an absolute HTTP(S) URL without credentials, query, or fragment'
+      end
+
+      self.base_url = base_url
+    rescue URI::InvalidURIError
+      raise ArgumentError, 'base_url must be an absolute HTTP(S) URL without credentials, query, or fragment'
+    end
+
+    def valid_base_uri?(uri)
+      uri.is_a?(URI::HTTP) && %w[http https].include?(uri.scheme) && uri.host &&
+        !uri.userinfo && !uri.query && !uri.fragment
+    end
+
+    def validate_timeout!
+      return if timeout_ms.is_a?(Numeric) && timeout_ms.positive?
+
+      raise ArgumentError, 'timeout_ms must be greater than zero'
+    end
+
+    def validate_retries!
+      return if retries.is_a?(Integer) && retries.between?(0, MAX_RETRIES)
+
+      raise ArgumentError, "retries must be an integer between 0 and #{MAX_RETRIES}"
+    end
+  end
+end

data/lib/letmesendemail/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module LetMeSendEmail
+  # Base class for all SDK failures.
+  class Error < StandardError
+    attr_reader :status_code, :api_code, :validation_errors, :request_id, :response_headers, :raw_body
+
+    def initialize(message = nil, status_code: nil, api_code: nil,
+                   validation_errors: nil, request_id: nil,
+                   response_headers: nil, raw_body: nil)
+      super(message)
+      @status_code = status_code
+      @api_code = api_code
+      @validation_errors = validation_errors || {}
+      @request_id = request_id
+      @response_headers = response_headers || {}
+      @raw_body = raw_body
+    end
+  end
+
+  # An API response that does not have a more specific mapping.
+  class ApiError < Error; end
+  # HTTP 401 authentication failure.
+  class AuthenticationError < Error; end
+  # HTTP 403 authorization failure.
+  class AuthorizationError < Error; end
+  # HTTP 400, 413, or 422 validation failure.
+  class ValidationError < Error; end
+
+  # HTTP 429 failure with rate-limit metadata.
+  class RateLimitError < Error
+    attr_reader :retry_after, :limit, :remaining, :reset_at
+
+    def initialize(message = nil, status_code: nil, api_code: nil,
+                   validation_errors: nil, request_id: nil,
+                   response_headers: nil, raw_body: nil,
+                   retry_after: nil, limit: nil, remaining: nil, reset_at: nil)
+      super(message, status_code: status_code, api_code: api_code,
+                     validation_errors: validation_errors, request_id: request_id,
+                     response_headers: response_headers, raw_body: raw_body)
+      @retry_after = retry_after
+      @limit = limit
+      @remaining = remaining
+      @reset_at = reset_at
+    end
+  end
+
+  # HTTP 404 failure.
+  class NotFoundError < Error; end
+  # HTTP 409 failure.
+  class ConflictError < Error; end
+  # Connection, socket, TLS, or response transport failure.
+  class NetworkError < Error; end
+  # HTTP connection, read, or write timeout.
+  class TimeoutError < Error; end
+  # Invalid webhook request or signature.
+  class WebhookVerificationError < Error; end
+  # Invalid webhook signing secret.
+  class WebhookSigningError < Error; end
+end

data/lib/letmesendemail/http_transport.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'openssl'
+require 'time'
+require 'uri'
+
+module LetMeSendEmail
+  # Internal net/http transport.
+  class HttpTransport
+    MAX_RETRY_AFTER_SECONDS = 300
+
+    def initialize(config)
+      @config = config
+    end
+
+    def call(method, path, body: nil, extra_headers: {})
+      uri = URI.parse("#{@config.base_url}/#{path.sub(%r{^/}, '')}")
+      response = perform(uri, method, body, extra_headers)
+      headers = response.each_header.to_h { |key, value| [key.downcase, value] }
+      status = response.code.to_i
+      raw_body = response.body.to_s
+      parsed = parse_response_body(raw_body, status, headers)
+
+      return Models.wrap(parsed) if status.between?(200, 299)
+
+      raise error_from_status(status, parsed, headers, raw_body)
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+      raise TimeoutError, e.message
+    rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse => e
+      raise NetworkError, e.message
+    end
+
+    private
+
+    def perform(uri, method, body, extra_headers)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      timeout_seconds = @config.timeout_ms / 1000.0
+      http.open_timeout = timeout_seconds
+      http.read_timeout = timeout_seconds
+      http.write_timeout = timeout_seconds if http.respond_to?(:write_timeout=)
+
+      request = request_class(method).new(uri)
+      request['Authorization'] = "Bearer #{@config.api_key}"
+      request['Content-Type'] = 'application/json'
+      request['Accept'] = 'application/json'
+      request['User-Agent'] = "letmesendemail-ruby/#{LetMeSendEmail::VERSION}"
+      extra_headers.each { |key, value| request[key] = value }
+      request.body = JSON.generate(body) if body
+      http.request(request)
+    end
+
+    def request_class(method)
+      {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }.fetch(method) { raise ArgumentError, "unknown HTTP method: #{method}" }
+    end
+
+    def parse_response_body(raw_body, status, headers)
+      return {} if raw_body.empty?
+
+      parsed = JSON.parse(raw_body)
+      return parsed if parsed.is_a?(Hash)
+
+      raise_response_error('API response must be a JSON object.', status, headers, raw_body)
+    rescue JSON::ParserError => e
+      raise_response_error("API returned invalid JSON: #{e.message}", status, headers, raw_body)
+    end
+
+    def raise_response_error(message, status, headers, raw_body)
+      raise ApiError.new(message, status_code: status, response_headers: headers, raw_body: raw_body)
+    end
+
+    def error_from_status(status, body, headers, raw_body)
+      message = body['message'] || 'Unknown error.'
+      keywords = error_keywords(status, body, headers, raw_body)
+
+      case status
+      when 400, 413, 422 then ValidationError.new(message, **keywords)
+      when 401 then AuthenticationError.new(message, **keywords)
+      when 403 then AuthorizationError.new(message, **keywords)
+      when 404 then NotFoundError.new(message, **keywords)
+      when 409 then ConflictError.new(message, **keywords)
+      when 429 then rate_limit_error(message, keywords, headers)
+      else ApiError.new(message, **keywords)
+      end
+    end
+
+    def error_keywords(status, body, headers, raw_body)
+      {
+        status_code: status,
+        api_code: body['name'],
+        validation_errors: body['errors'],
+        request_id: headers['x-request-id'],
+        response_headers: headers,
+        raw_body: raw_body
+      }
+    end
+
+    def rate_limit_error(message, keywords, headers)
+      RateLimitError.new(
+        message,
+        **keywords,
+        retry_after: parse_retry_after(headers['retry-after']),
+        limit: parse_integer(headers['x-ratelimit-limit']),
+        remaining: parse_integer(headers['x-ratelimit-remaining']),
+        reset_at: headers['x-ratelimit-reset']
+      )
+    end
+
+    def parse_retry_after(value)
+      return if value.nil?
+
+      seconds = value.match?(/\A\d+\z/) ? value.to_i : (Time.httpdate(value) - Time.now).ceil
+      seconds if seconds.between?(1, MAX_RETRY_AFTER_SECONDS)
+    rescue ArgumentError
+      nil
+    end
+
+    def parse_integer(value)
+      Integer(value, exception: false)
+    end
+  end
+end

data/lib/letmesendemail/models.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module LetMeSendEmail
+  # Plain-data wrappers for API responses.
+  module Models
+    # Application-friendly representation of an API response.
+    #
+    # Nested hashes and arrays are recursively wrapped. Use {#to_h} for a
+    # defensive plain-data copy suitable for database persistence.
+    class Model
+      include Enumerable
+
+      # @param attributes [Hash] response attributes
+      def initialize(attributes)
+        raise ArgumentError, 'attributes must be a Hash' unless attributes.is_a?(Hash)
+
+        @attributes = attributes.each_with_object({}) do |(key, value), result|
+          result[key.to_s.dup.freeze] = Models.wrap(value)
+        end.freeze
+      end
+
+      # @param key [String, Symbol] field name
+      # @return [Object, nil] wrapped field value
+      def [](key)
+        @attributes[key.to_s]
+      end
+
+      # @param key [String, Symbol] field name
+      # @return [Object] wrapped field value
+      def fetch(key, *defaults, &)
+        @attributes.fetch(key.to_s, *defaults, &)
+      end
+
+      # @param key [String, Symbol] field name
+      # @return [Boolean] whether the field exists
+      def key?(key)
+        @attributes.key?(key.to_s)
+      end
+
+      # Iterates through response fields.
+      # @yieldparam key [String]
+      # @yieldparam value [Object]
+      # @return [Enumerator, self]
+      def each(&block)
+        return enum_for(:each) unless block
+
+        @attributes.each(&block)
+      end
+
+      # @return [Hash] recursive defensive plain-data copy
+      def to_h
+        Models.unwrap(@attributes)
+      end
+
+      # Rails-compatible JSON representation.
+      # @return [Hash]
+      def as_json(*)
+        to_h
+      end
+
+      # @return [String] JSON document
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} #{@attributes.inspect}>"
+      end
+    end
+
+    module_function
+
+    # Recursively wraps hashes returned by the API.
+    # @param value [Object]
+    # @return [Object]
+    def wrap(value)
+      return value.dup.freeze if value.is_a?(String)
+      return Model.new(value) if value.is_a?(Hash)
+      return value.map { |item| wrap(item) }.freeze if value.is_a?(Array)
+
+      value
+    end
+
+    # Recursively converts models into plain mutable Ruby data.
+    # @param value [Object]
+    # @return [Object]
+    def unwrap(value)
+      return value.dup if value.is_a?(String)
+      return value.to_h if value.is_a?(Model)
+      return value.to_h { |key, item| [key.dup, unwrap(item)] } if value.is_a?(Hash)
+      return value.map { |item| unwrap(item) } if value.is_a?(Array)
+
+      value
+    end
+  end
+end

data/lib/letmesendemail/resources/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module LetMeSendEmail
+  module Resources
+    # Shared resource URL and pagination behavior.
+    class Base
+      # @param client [Client]
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def path_for(collection, id)
+        "/#{collection}/#{@client.resource_path_segment(id)}"
+      end
+
+      def list_path(collection, per_page:, after:, before:)
+        raise ArgumentError, 'after and before cannot be used together' if after && before
+
+        params = {}
+        params[:per_page] = per_page unless per_page.nil?
+        params[:after] = after unless after.nil?
+        params[:before] = before unless before.nil?
+        params.empty? ? "/#{collection}" : "/#{collection}?#{URI.encode_www_form(params)}"
+      end
+    end
+  end
+end

data/lib/letmesendemail/resources/contact_categories.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module LetMeSendEmail
+  module Resources
+    # Contact Categories API operations.
+    class ContactCategories < Base
+      # Creates a contact category.
+      # @return [Models::Model]
+      def create(name:, slug: nil)
+        body = { name: name }
+        body[:slug] = slug if slug
+        @client.request(:post, '/contact-categories', body: body)
+      end
+
+      # Lists one cursor page of contact categories.
+      # @return [Models::Model]
+      def list(per_page: nil, after: nil, before: nil)
+        @client.request(:get, list_path('contact-categories', per_page: per_page, after: after, before: before))
+      end
+
+      # Retrieves a contact category.
+      # @param id [String]
+      # @return [Models::Model]
+      def get(id)
+        @client.request(:get, path_for('contact-categories', id))
+      end
+
+      # Updates a contact category.
+      # @param id [String]
+      # @return [Models::Model]
+      def update(id, name:, slug: nil)
+        body = { name: name }
+        body[:slug] = slug if slug
+        @client.request(:put, path_for('contact-categories', id), body: body)
+      end
+
+      # Deletes a contact category.
+      # @param id [String]
+      # @return [Models::Model]
+      def delete(id)
+        @client.request(:delete, path_for('contact-categories', id))
+      end
+    end
+  end
+end

data/lib/letmesendemail/resources/contacts.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module LetMeSendEmail
+  module Resources
+    # Contacts API operations.
+    class Contacts < Base
+      # Creates a contact.
+      # @return [Models::Model]
+      def create(email:, first_name: nil, last_name: nil, phone: nil,
+                 is_globally_unsubscribed: nil, categories: nil, email_topics: nil)
+        body = { email: email }
+        body[:first_name] = first_name if first_name
+        body[:last_name] = last_name if last_name
+        body[:phone] = phone if phone
+        body[:is_globally_unsubscribed] = is_globally_unsubscribed unless is_globally_unsubscribed.nil?
+        body[:categories] = categories if categories
+        body[:email_topics] = email_topics if email_topics
+        @client.request(:post, '/contacts', body: body)
+      end
+
+      # Lists one cursor page of contacts.
+      # @return [Models::Model]
+      def list(per_page: nil, after: nil, before: nil)
+        @client.request(:get, list_path('contacts', per_page: per_page, after: after, before: before))
+      end
+
+      # Retrieves a contact.
+      # @param id [String]
+      # @return [Models::Model]
+      def get(id)
+        @client.request(:get, path_for('contacts', id))
+      end
+
+      # Updates a contact.
+      # @param id [String]
+      # @return [Models::Model]
+      def update(id, first_name: nil, last_name: nil, phone: nil,
+                 is_globally_unsubscribed: nil, categories: nil, email_topics: nil,
+                 sync_categories: nil, sync_email_topics: nil)
+        body = {}
+        body[:first_name] = first_name if first_name
+        body[:last_name] = last_name if last_name
+        body[:phone] = phone if phone
+        body[:is_globally_unsubscribed] = is_globally_unsubscribed unless is_globally_unsubscribed.nil?
+        body[:categories] = categories if categories
+        body[:email_topics] = email_topics if email_topics
+        body[:sync_categories] = sync_categories unless sync_categories.nil?
+        body[:sync_email_topics] = sync_email_topics unless sync_email_topics.nil?
+        @client.request(:put, path_for('contacts', id), body: body)
+      end
+
+      # Deletes a contact.
+      # @param id [String]
+      # @return [Models::Model]
+      def delete(id)
+        @client.request(:delete, path_for('contacts', id))
+      end
+    end
+  end
+end

data/lib/letmesendemail/resources/domains.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LetMeSendEmail
+  module Resources
+    # Domains API operations.
+    class Domains < Base
+      # Lists one cursor page of domains.
+      # @return [Models::Model]
+      def list(per_page: nil, after: nil, before: nil)
+        @client.request(:get, list_path('domains', per_page: per_page, after: after, before: before))
+      end
+
+      # Retrieves a domain.
+      # @param id [String]
+      # @return [Models::Model]
+      def get(id)
+        @client.request(:get, path_for('domains', id))
+      end
+
+      # Requests verification for a domain name.
+      # @param domain [String]
+      # @return [Models::Model]
+      def verify(domain)
+        @client.request(:post, '/domains/verify', body: { domain: domain })
+      end
+    end
+  end
+end

data/lib/letmesendemail/resources/email_topics.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module LetMeSendEmail
+  module Resources
+    # Email Topics API operations.
+    class EmailTopics < Base
+      # Creates an email topic.
+      # @return [Models::Model]
+      def create(name:, slug:, auto_subscribe: nil, public: nil,
+                 description: nil, domain_id: nil)
+        body = { name: name, slug: slug }
+        body[:auto_subscribe] = auto_subscribe unless auto_subscribe.nil?
+        body[:public] = public unless public.nil?
+        body[:description] = description if description
+        body[:domain] = { id: domain_id } if domain_id
+        @client.request(:post, '/email-topics', body: body)
+      end
+
+      # Lists one cursor page of email topics.
+      # @return [Models::Model]
+      def list(per_page: nil, after: nil, before: nil)
+        @client.request(:get, list_path('email-topics', per_page: per_page, after: after, before: before))
+      end
+
+      # Retrieves an email topic.
+      # @param id [String]
+      # @return [Models::Model]
+      def get(id)
+        @client.request(:get, path_for('email-topics', id))
+      end
+
+      # Updates an email topic.
+      # @param id [String]
+      # @return [Models::Model]
+      def update(id, name: nil, slug: nil, description: nil, public: nil, auto_subscribe: nil)
+        body = {}
+        body[:name] = name if name
+        body[:slug] = slug if slug
+        body[:description] = description if description
+        body[:public] = public unless public.nil?
+        body[:auto_subscribe] = auto_subscribe unless auto_subscribe.nil?
+        @client.request(:put, path_for('email-topics', id), body: body)
+      end
+
+      # Deletes an email topic.
+      # @param id [String]
+      # @return [Models::Model]
+      def delete(id)
+        @client.request(:delete, path_for('email-topics', id))
+      end
+    end
+  end
+end