letmesendemail 0.1.0

data/lib/letmesendemail/resources/emails.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module LetMeSendEmail
+  module Resources
+    # Emails API operations.
+    class Emails < Base
+      # Sends a regular email.
+      # @return [Models::Model]
+      def send(from:, to:, subject:, html: nil, text: nil, type: nil,
+               event_name: nil, email_topic_id: nil, reply_to: nil,
+               cc: nil, bcc: nil, headers: nil, attachments: nil,
+               idempotency_key: nil)
+        body = { from: from, to: to, subject: subject }
+        body[:html] = html if html
+        body[:text] = text if text
+        body[:type] = type if type
+        body[:event_name] = event_name if event_name
+        body[:email_topic_id] = email_topic_id if email_topic_id
+        body[:reply_to] = reply_to if reply_to
+        body[:cc] = cc if cc
+        body[:bcc] = bcc if bcc
+        body[:headers] = headers if headers
+        body[:attachments] = attachments if attachments
+
+        extra = idempotency_key ? { 'Idempotency-Key' => idempotency_key } : {}
+
+        @client.request(:post, '/emails', body: body, extra_headers: extra)
+      end
+
+      # Sends an email using a template.
+      # @return [Models::Model]
+      def send_with_template(from:, to:, template_id:, subject: nil,
+                             template_variables: nil, type: nil,
+                             event_name: nil, email_topic_id: nil,
+                             reply_to: nil, cc: nil, bcc: nil,
+                             headers: nil, attachments: nil,
+                             idempotency_key: nil)
+        body = { from: from, to: to, template_id: template_id }
+        body[:subject] = subject if subject
+        body[:template_variables] = template_variables if template_variables
+        body[:type] = type if type
+        body[:event_name] = event_name if event_name
+        body[:email_topic_id] = email_topic_id if email_topic_id
+        body[:reply_to] = reply_to if reply_to
+        body[:cc] = cc if cc
+        body[:bcc] = bcc if bcc
+        body[:headers] = headers if headers
+        body[:attachments] = attachments if attachments
+
+        extra = idempotency_key ? { 'Idempotency-Key' => idempotency_key } : {}
+
+        @client.request(:post, '/emails', body: body, extra_headers: extra)
+      end
+
+      # Verifies an email address.
+      # @param email [String]
+      # @return [Models::Model]
+      def verify(email)
+        @client.request(:post, '/emails/verify', body: { email: email })
+      end
+
+      # Lists one cursor page of emails.
+      # @return [Models::Model]
+      def list(per_page: nil, after: nil, before: nil)
+        @client.request(:get, list_path('emails', per_page: per_page, after: after, before: before))
+      end
+
+      # Retrieves detailed information for an email.
+      # @param id [String]
+      # @return [Models::Model]
+      def get(id)
+        @client.request(:get, path_for('emails', id))
+      end
+    end
+  end
+end

data/lib/letmesendemail/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module LetMeSendEmail
+  # Current gem version, used in package metadata and the SDK User-Agent.
+  VERSION = '0.1.0'
+end

data/lib/letmesendemail/webhooks.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+require 'json'
+
+module LetMeSendEmail
+  # Verifies signatures on raw letmesend.email webhook requests.
+  module Webhooks
+    REQUIRED_HEADERS = %w[webhook-id webhook-log-id webhook-timestamp webhook-signature].freeze
+    DEFAULT_TOLERANCE = 300
+
+    module_function
+
+    # Verifies a webhook signature before parsing the JSON payload.
+    # @param payload [String] exact raw request body
+    # @param headers [Hash] request headers
+    # @param secret [String] Base64 secret, optionally prefixed with +whsec_+
+    # @param tolerance [Integer] allowed timestamp skew in seconds
+    # @return [Hash] verified JSON object
+    # @raise [WebhookVerificationError, WebhookSigningError]
+    def verify(payload, headers, secret, tolerance: DEFAULT_TOLERANCE)
+      validate_inputs!(payload, headers, secret, tolerance)
+      extracted = extract_headers(headers)
+      validate_timestamp!(extracted['webhook-timestamp'], tolerance)
+      expected = expected_signature(payload, extracted, secret)
+      validate_signature!(extracted['webhook-signature'], expected)
+      parse_payload(payload)
+    end
+
+    # Normalizes Rack/CGI and ordinary HTTP header hashes.
+    # @param headers [Hash]
+    # @return [Hash]
+    def resolve_headers(headers)
+      headers.each_with_object({}) do |(key, value), result|
+        normalized = key.to_s.downcase.sub(/\Ahttp_/, '').tr('_', '-')
+        result[normalized] = value.to_s
+      end
+    end
+
+    def validate_inputs!(payload, headers, secret, tolerance)
+      raise WebhookVerificationError, 'Webhook payload must be a string.' unless payload.is_a?(String)
+      raise WebhookVerificationError, 'Webhook headers must be a hash.' unless headers.is_a?(Hash)
+      unless tolerance.is_a?(Integer) && tolerance >= 0
+        raise WebhookVerificationError, 'Webhook tolerance must be zero or greater.'
+      end
+      return if secret.is_a?(String) && !secret.empty? && secret == secret.strip
+
+      raise WebhookSigningError, 'Webhook secret must be a non-empty string.'
+    end
+    private_class_method :validate_inputs!
+
+    def extract_headers(headers)
+      resolved = resolve_headers(headers)
+      REQUIRED_HEADERS.to_h do |header|
+        value = resolved[header]
+        raise WebhookVerificationError, "Missing required webhook header: #{header}." if value.nil? || value.empty?
+
+        [header, value]
+      end
+    end
+    private_class_method :extract_headers
+
+    def validate_timestamp!(timestamp_string, tolerance)
+      raise WebhookVerificationError, 'Webhook timestamp is not numeric.' unless timestamp_string.match?(/\A\d+\z/)
+
+      timestamp = timestamp_string.to_i
+      now = Time.now.to_i
+      raise WebhookVerificationError, 'Webhook timestamp must be a positive integer.' unless timestamp.positive?
+      raise WebhookVerificationError, 'Webhook timestamp is too old.' if timestamp < now - tolerance
+      return unless timestamp > now + tolerance
+
+      raise WebhookVerificationError, 'Webhook timestamp is too far in the future.'
+    end
+    private_class_method :validate_timestamp!
+
+    def expected_signature(payload, headers, secret)
+      raw_secret = secret.start_with?('whsec_') ? secret[6..] : secret
+      decoded_secret = Base64.strict_decode64(raw_secret)
+      raise WebhookSigningError, 'Webhook secret could not be decoded.' if decoded_secret.empty?
+
+      signed = "#{headers['webhook-id']}.#{headers['webhook-log-id']}.#{headers['webhook-timestamp']}.#{payload}"
+      Base64.strict_encode64(OpenSSL::HMAC.digest('SHA256', decoded_secret, signed))
+    rescue ArgumentError
+      raise WebhookSigningError, 'Webhook secret could not be decoded.'
+    end
+    private_class_method :expected_signature
+
+    def validate_signature!(signature_header, expected)
+      matched = signature_header.split.any? do |entry|
+        version, candidate = entry.split(',', 2)
+        version == 'v1' && candidate&.bytesize == expected.bytesize &&
+          OpenSSL.fixed_length_secure_compare(candidate, expected)
+      end
+      raise WebhookVerificationError, 'No matching webhook signature found.' unless matched
+    end
+    private_class_method :validate_signature!
+
+    def parse_payload(payload)
+      parsed = JSON.parse(payload)
+      raise WebhookVerificationError, 'Webhook payload must be a JSON object.' unless parsed.is_a?(Hash)
+
+      parsed
+    rescue JSON::ParserError
+      raise WebhookVerificationError, 'Webhook payload is not valid JSON.'
+    end
+    private_class_method :parse_payload
+  end
+end

data/lib/letmesendemail.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'letmesendemail/version'
+require_relative 'letmesendemail/config'
+require_relative 'letmesendemail/errors'
+require_relative 'letmesendemail/models'
+require_relative 'letmesendemail/http_transport'
+require_relative 'letmesendemail/client'
+require_relative 'letmesendemail/webhooks'
+require_relative 'letmesendemail/resources/base'
+require_relative 'letmesendemail/resources/emails'
+require_relative 'letmesendemail/resources/domains'
+require_relative 'letmesendemail/resources/contacts'
+require_relative 'letmesendemail/resources/contact_categories'
+require_relative 'letmesendemail/resources/email_topics'

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: letmesendemail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- letmesendemail
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: Official Ruby SDK for the letmesend.email API.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- docs/docs.md
+- examples/attachments.rb
+- examples/errors.rb
+- examples/idempotency.rb
+- examples/pagination.rb
+- examples/send.rb
+- examples/template.rb
+- examples/webhooks.rb
+- lib/letmesendemail.rb
+- lib/letmesendemail/client.rb
+- lib/letmesendemail/config.rb
+- lib/letmesendemail/errors.rb
+- lib/letmesendemail/http_transport.rb
+- lib/letmesendemail/models.rb
+- lib/letmesendemail/resources/base.rb
+- lib/letmesendemail/resources/contact_categories.rb
+- lib/letmesendemail/resources/contacts.rb
+- lib/letmesendemail/resources/domains.rb
+- lib/letmesendemail/resources/email_topics.rb
+- lib/letmesendemail/resources/emails.rb
+- lib/letmesendemail/version.rb
+- lib/letmesendemail/webhooks.rb
+homepage: https://letmesend.email/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://letmesend.email/
+  source_code_uri: https://github.com/letmesendemail/letmesendemail-ruby
+  changelog_uri: https://github.com/letmesendemail/letmesendemail-ruby/blob/master/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  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: 4.0.11
+specification_version: 4
+summary: letmesend.email Ruby SDK.
+test_files: []