lettermint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eaf2c7d68c2a67e9bdcfff25733031fd17e23645ae6d5c2cc73100177ecd8865
+  data.tar.gz: 7ecfec4398f01936474380abb69c595e9220d1f90e3e990b9261e426e72c1772
+SHA512:
+  metadata.gz: fa95bb5a225b54f848de6b62e0e334072207373ab84bbd0a56ba5babc23b47f6b60d4bbdf30097884c6df28c64209ae7956e4c9b551e7b38a735740555a43e09
+  data.tar.gz: a4e41473d58b93ced91c3219d6074d0eaf6382b61174758cc62a091c8ca59762fc75e1a1e9acd4de5372e5c86083cd3a34767c88d7561ab31a7d0ff7b5c4ad4f

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-18
+
+### Added
+
+- Email sending via `Client#email` with fluent builder interface
+- Support for to, cc, bcc, reply-to, attachments, custom headers, metadata, tags, and routing
+- `deliver` method (avoids `Object#send` collision)
+- Idempotency key support for safe retries
+- `SendEmailResponse` and `EmailAttachment` frozen value objects (`Data.define`)
+- HMAC-SHA256 webhook signature verification via `Webhook`
+- Timestamp tolerance checking (default 300s)
+- Instance and class-level verification methods
+- Typed error hierarchy: `HttpRequestError`, `ValidationError`, `ClientError`, `TimeoutError`, `WebhookVerificationError`, `InvalidSignatureError`, `TimestampToleranceError`, `WebhookJsonDecodeError`
+- Faraday-based HTTP transport with `x-lettermint-token` authentication
+- Block-style client configuration
+- Full RSpec test suite (86 examples)
+- RuboCop configuration
+
+[0.1.0]: https://github.com/onetimesecret/lettermint-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onetime Secret
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,325 @@
+# Lettermint Ruby SDK
+
+[![Gem Version](https://img.shields.io/gem/v/lettermint?style=flat-square)](https://rubygems.org/gems/lettermint)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red?style=flat-square)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://github.com/onetimesecret/lettermint-ruby/blob/main/LICENSE)
+
+Unofficial Ruby SDK for the [Lettermint](https://lettermint.co) transactional email API. Based on the official [Python SDK](https://github.com/lettermint/lettermint-python).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lettermint'
+```
+
+Or install directly:
+
+```bash
+gem install lettermint
+```
+
+## Quick Start
+
+### Sending Emails
+
+```ruby
+require 'lettermint'
+
+client = Lettermint::Client.new(api_token: 'your-api-token')
+
+response = client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .subject('Hello from Ruby')
+  .html('<h1>Welcome!</h1>')
+  .text('Welcome!')
+  .deliver
+
+puts response.message_id
+```
+
+## Email Options
+
+### Multiple Recipients
+
+```ruby
+client.email
+  .from('sender@example.com')
+  .to('recipient1@example.com', 'recipient2@example.com')
+  .subject('Hello')
+  .deliver
+```
+
+### CC and BCC
+
+```ruby
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .cc('cc1@example.com', 'cc2@example.com')
+  .bcc('bcc@example.com')
+  .subject('Hello')
+  .deliver
+```
+
+### Reply-To
+
+```ruby
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .reply_to('reply@example.com')
+  .subject('Hello')
+  .deliver
+```
+
+### RFC 5322 Addresses
+
+```ruby
+client.email
+  .from('John Doe <john@example.com>')
+  .to('Jane Doe <jane@example.com>')
+  .subject('Hello')
+  .deliver
+```
+
+### Attachments
+
+```ruby
+require 'base64'
+
+content = Base64.strict_encode64(File.binread('document.pdf'))
+
+# Regular attachment
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .subject('Your Document')
+  .attach('document.pdf', content)
+  .deliver
+
+# Inline attachment (for embedding in HTML)
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .subject('Welcome')
+  .html('<img src="cid:logo@example.com">')
+  .attach('logo.png', logo_content, content_id: 'logo@example.com')
+  .deliver
+```
+
+You can also use the `EmailAttachment` value object:
+
+```ruby
+attachment = Lettermint::EmailAttachment.new(
+  filename: 'document.pdf',
+  content: content,
+  content_id: nil
+)
+
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .attach(attachment)
+  .deliver
+```
+
+### Custom Headers
+
+```ruby
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .subject('Hello')
+  .headers({ 'X-Custom-Header' => 'value' })
+  .deliver
+```
+
+### Metadata and Tags
+
+```ruby
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .subject('Hello')
+  .metadata({ campaign_id: '123', user_id: '456' })
+  .tag('welcome-campaign')
+  .deliver
+```
+
+### Routing
+
+```ruby
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .subject('Hello')
+  .route('my-route')
+  .deliver
+```
+
+### Idempotency Key
+
+Prevent duplicate sends when retrying failed requests:
+
+```ruby
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .subject('Hello')
+  .idempotency_key('unique-request-id')
+  .deliver
+```
+
+## Webhook Verification
+
+Verify webhook signatures to ensure authenticity:
+
+```ruby
+require 'lettermint'
+
+webhook = Lettermint::Webhook.new(secret: 'your-webhook-secret')
+
+# Verify using headers (recommended)
+payload = webhook.verify_headers(request.headers, request.body)
+
+# Or verify using the signature directly
+payload = webhook.verify(
+  request.body,
+  request.headers['X-Lettermint-Signature']
+)
+
+puts payload['event']
+```
+
+### Class Method
+
+For one-off verification:
+
+```ruby
+payload = Lettermint::Webhook.verify_signature(
+  request.body,
+  request.headers['X-Lettermint-Signature'],
+  secret: 'your-webhook-secret'
+)
+```
+
+### Custom Tolerance
+
+Adjust the timestamp tolerance (default: 300 seconds):
+
+```ruby
+webhook = Lettermint::Webhook.new(secret: 'your-webhook-secret', tolerance: 600)
+```
+
+### Replay Protection
+
+The webhook verifier validates timestamp freshness and HMAC integrity but does not
+track previously seen deliveries. Within the tolerance window (default 300 seconds),
+a captured request could be replayed. Your application should deduplicate incoming
+webhooks using the `x-lettermint-delivery` header value as an idempotency key -- for
+example, by recording processed delivery IDs in a database or cache and rejecting
+duplicates.
+
+## Error Handling
+
+```ruby
+require 'lettermint'
+
+client = Lettermint::Client.new(api_token: 'your-api-token')
+
+begin
+  response = client.email
+    .from('sender@example.com')
+    .to('recipient@example.com')
+    .subject('Hello')
+    .deliver
+rescue Lettermint::AuthenticationError => e
+  # 401/403 errors (invalid or revoked token)
+  puts "Auth error #{e.status_code}: #{e.message}"
+rescue Lettermint::RateLimitError => e
+  # 429 errors
+  puts "Rate limited, retry after: #{e.retry_after}s"
+rescue Lettermint::ValidationError => e
+  # 422 errors (e.g., daily limit exceeded)
+  puts "Validation error: #{e.error_type}"
+  puts "Response: #{e.response_body}"
+rescue Lettermint::ClientError => e
+  # 400 errors
+  puts "Client error: #{e.message}"
+rescue Lettermint::TimeoutError => e
+  # Request timeout
+  puts "Timeout: #{e.message}"
+rescue Lettermint::HttpRequestError => e
+  # Other HTTP errors
+  puts "HTTP error #{e.status_code}: #{e.message}"
+end
+```
+
+### Webhook Errors
+
+```ruby
+begin
+  payload = webhook.verify_headers(headers, body)
+rescue Lettermint::InvalidSignatureError
+  puts 'Invalid signature - request may be forged'
+rescue Lettermint::TimestampToleranceError
+  puts 'Timestamp too old - possible replay attack'
+rescue Lettermint::WebhookJsonDecodeError => e
+  puts "Invalid JSON in payload: #{e.original_exception}"
+rescue Lettermint::WebhookVerificationError => e
+  puts "Verification failed: #{e.message}"
+end
+```
+
+## Configuration
+
+### Global Configuration
+
+Set defaults once at application boot (e.g., in a Rails initializer):
+
+```ruby
+Lettermint.configure do |config|
+  config.base_url = 'https://custom.api.com/v1'
+  config.timeout = 60
+end
+```
+
+All clients created afterward inherit these defaults:
+
+```ruby
+client = Lettermint::Client.new(api_token: 'your-api-token')
+# Uses the global base_url and timeout
+```
+
+### Per-Client Overrides
+
+Explicit keyword arguments take precedence over global configuration:
+
+```ruby
+client = Lettermint::Client.new(
+  api_token: 'your-api-token',
+  base_url: 'https://other.api.com/v1',
+  timeout: 10
+)
+```
+
+### Block Configuration
+
+```ruby
+client = Lettermint::Client.new(api_token: 'your-api-token') do |config|
+  config.base_url = 'https://custom.api.com/v1'
+  config.timeout = 60
+end
+```
+
+## Requirements
+
+- Ruby >= 3.2
+- [Faraday](https://github.com/lostisland/faraday) ~> 2.0
+
+## License
+
+MIT

data/lettermint.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'lib/lettermint/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'lettermint'
+  spec.version = Lettermint::VERSION
+  spec.authors = ['Delano']
+  spec.email = ['gems@onetimesecret.com']
+
+  spec.summary = 'Ruby SDK for the Lettermint transactional email API'
+  spec.description = 'Send transactional emails and verify webhooks with the Lettermint API. ' \
+                     'Provides a fluent builder interface, typed responses, and HMAC-SHA256 webhook verification.'
+  spec.homepage = 'https://github.com/onetimesecret/lettermint-ruby'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?('spec/', 'examples/', '.git', '.rubocop', 'Rakefile', 'Gemfile',
+                      'CLAUDE', '.pre-commit', '.rspec')
+    end
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'faraday', '~> 2.0'
+end

data/lib/lettermint/client.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Lettermint
+  class Client
+    attr_reader :configuration
+
+    def initialize(api_token:, base_url: nil, timeout: nil)
+      validate_api_token!(api_token)
+
+      @configuration = Configuration.new
+      @configuration.base_url = base_url || Lettermint.configuration.base_url
+      @configuration.timeout = timeout || Lettermint.configuration.timeout
+
+      yield @configuration if block_given?
+
+      @http_client = HttpClient.new(
+        api_token: api_token,
+        base_url: @configuration.base_url,
+        timeout: @configuration.timeout
+      )
+    end
+
+    def email
+      EmailMessage.new(http_client: @http_client)
+    end
+
+    private
+
+    def validate_api_token!(token)
+      raise ArgumentError, 'API token cannot be empty' if token.nil? || token.to_s.strip.empty?
+    end
+  end
+end

data/lib/lettermint/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Lettermint
+  class Configuration
+    DEFAULT_BASE_URL = 'https://api.lettermint.co/v1'
+    DEFAULT_TIMEOUT = 30
+
+    attr_accessor :base_url, :timeout
+
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+    end
+  end
+end

data/lib/lettermint/email_message.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Lettermint
+  class EmailMessage
+    def initialize(http_client:)
+      @http_client = http_client
+      reset
+    end
+
+    def from(email)
+      @payload[:from] = email
+      self
+    end
+    alias from_addr from
+
+    def to(*emails)
+      @payload[:to] = emails.flatten
+      self
+    end
+
+    def subject(str)
+      @payload[:subject] = str
+      self
+    end
+
+    def html(str)
+      @payload[:html] = str if str
+      self
+    end
+
+    def text(str)
+      @payload[:text] = str if str
+      self
+    end
+
+    def cc(*emails)
+      @payload[:cc] = emails.flatten
+      self
+    end
+
+    def bcc(*emails)
+      @payload[:bcc] = emails.flatten
+      self
+    end
+
+    def reply_to(*emails)
+      @payload[:reply_to] = emails.flatten
+      self
+    end
+
+    def route(str)
+      @payload[:route] = str
+      self
+    end
+
+    def tag(str)
+      @payload[:tag] = str
+      self
+    end
+
+    def headers(hash)
+      @payload[:headers] = hash
+      self
+    end
+
+    def metadata(hash)
+      @payload[:metadata] = hash
+      self
+    end
+
+    def attach(filename_or_attachment, content = nil, content_id: nil)
+      attachment = case filename_or_attachment
+                   when EmailAttachment
+                     filename_or_attachment.to_h
+                   else
+                     h = { filename: filename_or_attachment, content: content }
+                     h[:content_id] = content_id if content_id
+                     h
+                   end
+      @payload[:attachments] ||= []
+      @payload[:attachments] << attachment
+      self
+    end
+
+    def idempotency_key(key)
+      @idempotency_key = key
+      self
+    end
+
+    def deliver
+      validate_required_fields
+
+      request_headers = {}
+      request_headers['Idempotency-Key'] = @idempotency_key if @idempotency_key
+
+      result = @http_client.post(
+        path: '/send',
+        data: @payload,
+        headers: request_headers.empty? ? nil : request_headers
+      )
+      SendEmailResponse.from_hash(result)
+    ensure
+      reset
+    end
+    alias deliver! deliver
+
+    private
+
+    def validate_required_fields
+      missing = %i[from subject].select { |f| blank?(f) }
+      missing << :to if @payload[:to].nil? || @payload[:to].none? { |e| e.is_a?(String) && !e.strip.empty? }
+      return if missing.empty?
+
+      raise ArgumentError, "Missing required field(s): #{missing.join(', ')}"
+    end
+
+    def blank?(field)
+      @payload[field].nil? || @payload[field].to_s.strip.empty?
+    end
+
+    def reset
+      @payload = {}
+      @idempotency_key = nil
+    end
+  end
+end

data/lib/lettermint/errors.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Lettermint
+  class Error < StandardError; end
+
+  class HttpRequestError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message:, status_code:, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  class ValidationError < HttpRequestError
+    attr_reader :error_type
+
+    def initialize(message:, error_type:, response_body: nil)
+      @error_type = error_type
+      super(message: message, status_code: 422, response_body: response_body)
+    end
+  end
+
+  class ClientError < HttpRequestError
+    def initialize(message:, response_body: nil)
+      super(message: message, status_code: 400, response_body: response_body)
+    end
+  end
+
+  class AuthenticationError < HttpRequestError
+    def initialize(message:, status_code:, response_body: nil)
+      super
+    end
+  end
+
+  class RateLimitError < HttpRequestError
+    attr_reader :retry_after
+
+    def initialize(message:, retry_after: nil, response_body: nil)
+      @retry_after = retry_after
+      super(message: message, status_code: 429, response_body: response_body)
+    end
+  end
+
+  class TimeoutError < Error; end
+
+  class WebhookVerificationError < Error; end
+
+  class InvalidSignatureError < WebhookVerificationError; end
+
+  class TimestampToleranceError < WebhookVerificationError; end
+
+  class WebhookJsonDecodeError < WebhookVerificationError
+    attr_reader :original_exception
+
+    def initialize(message, original_exception: nil)
+      @original_exception = original_exception
+      super(message)
+    end
+  end
+end

data/lib/lettermint/http_client.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module Lettermint
+  class HttpClient
+    def initialize(api_token:, base_url:, timeout:)
+      normalized_url = "#{base_url.chomp('/')}/"
+      @connection = Faraday.new(url: normalized_url) do |f|
+        f.request :json
+        f.response :json
+        f.options.timeout = timeout
+        f.options.open_timeout = timeout
+        f.headers = {
+          'Content-Type' => 'application/json',
+          'Accept' => 'application/json',
+          'x-lettermint-token' => api_token,
+          'User-Agent' => "Lettermint/#{Lettermint::VERSION} (Ruby; ruby #{RUBY_VERSION})"
+        }
+      end
+    end
+
+    def get(path:, params: nil, headers: nil)
+      with_error_handling do
+        @connection.get(path.delete_prefix('/')) do |req|
+          req.params = params if params
+          req.headers.update(headers) if headers
+        end
+      end
+    end
+
+    def post(path:, data: nil, headers: nil)
+      with_error_handling do
+        @connection.post(path.delete_prefix('/')) do |req|
+          req.body = data if data
+          req.headers.update(headers) if headers
+        end
+      end
+    end
+
+    def put(path:, data: nil, headers: nil)
+      with_error_handling do
+        @connection.put(path.delete_prefix('/')) do |req|
+          req.body = data if data
+          req.headers.update(headers) if headers
+        end
+      end
+    end
+
+    def delete(path:, headers: nil)
+      with_error_handling do
+        @connection.delete(path.delete_prefix('/')) do |req|
+          req.headers.update(headers) if headers
+        end
+      end
+    end
+
+    private
+
+    def with_error_handling
+      response = yield
+      handle_response(response)
+    rescue Faraday::TimeoutError, Timeout::Error
+      raise Lettermint::TimeoutError, "Request timeout after #{@connection.options.timeout}s"
+    rescue Faraday::ConnectionFailed => e
+      raise Lettermint::Error, e.message
+    end
+
+    def handle_response(response)
+      return response.body if response.success?
+
+      body = response.body.is_a?(Hash) ? response.body : nil
+      raise_api_error(response.status, body, response.headers)
+    end
+
+    def raise_api_error(status, body, headers)
+      raise build_error(status, body, headers)
+    end
+
+    def build_error(status, body, headers) # rubocop:disable Metrics
+      msg = ->(key, fallback) { body&.dig(key) || fallback }
+
+      case status
+      when 401, 403
+        AuthenticationError.new(message: msg['message', "HTTP #{status}"],
+                                status_code: status, response_body: body)
+      when 400
+        ClientError.new(message: msg['error', 'Unknown client error'], response_body: body)
+      when 422
+        ValidationError.new(message: msg['message', 'Validation error'],
+                            error_type: msg['error', 'ValidationError'], response_body: body)
+      when 429
+        retry_after = headers && headers['Retry-After'] && Integer(headers['Retry-After'], exception: false)
+        RateLimitError.new(message: msg['message', 'Rate limit exceeded'],
+                           retry_after: retry_after, response_body: body)
+      else
+        HttpRequestError.new(message: msg['message', "HTTP #{status}"],
+                             status_code: status, response_body: body)
+      end
+    end
+  end
+end

data/lib/lettermint/types.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Lettermint
+  SendEmailResponse = Data.define(:message_id, :status) do
+    def self.from_hash(hash)
+      raise Lettermint::Error, 'Empty response body from API' if hash.nil?
+      raise Lettermint::Error, "Unexpected response type: #{hash.class}" unless hash.is_a?(Hash)
+
+      new(message_id: hash['message_id'], status: hash['status'])
+    end
+  end
+
+  EmailAttachment = Data.define(:filename, :content, :content_id) do
+    def initialize(filename:, content:, content_id: nil)
+      super
+    end
+
+    def to_h
+      h = { filename: filename, content: content }
+      h[:content_id] = content_id if content_id
+      h
+    end
+  end
+end

data/lib/lettermint/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lettermint
+  VERSION = '0.1.0'
+end

data/lib/lettermint/webhook.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+
+module Lettermint
+  class Webhook
+    DEFAULT_TOLERANCE = 300
+
+    SIGNATURE_HEADER = 'x-lettermint-signature'
+    DELIVERY_HEADER = 'x-lettermint-delivery'
+
+    def initialize(secret:, tolerance: DEFAULT_TOLERANCE)
+      raise ArgumentError, 'Webhook secret cannot be empty' if secret.nil? || secret.empty?
+
+      @secret = secret
+      @tolerance = tolerance
+    end
+
+    def verify(payload, signature, timestamp: nil)
+      ts, sig_hash = parse_signature(signature)
+
+      raise WebhookVerificationError, 'Timestamp mismatch between header and signature' if timestamp && timestamp != ts
+
+      validate_timestamp(ts)
+      validate_signature(payload, ts, sig_hash)
+      parse_payload(payload)
+    end
+
+    def verify_headers(headers, payload)
+      normalized = headers.transform_keys(&:downcase)
+
+      signature = normalized[SIGNATURE_HEADER]
+      delivery = normalized[DELIVERY_HEADER]
+
+      raise WebhookVerificationError, "Missing #{SIGNATURE_HEADER} header" unless signature
+      raise WebhookVerificationError, "Missing #{DELIVERY_HEADER} header" unless delivery
+
+      ts = begin
+        Integer(delivery)
+      rescue ArgumentError, TypeError
+        raise WebhookVerificationError, "Invalid #{DELIVERY_HEADER} header value"
+      end
+
+      verify(payload, signature, timestamp: ts)
+    end
+
+    def self.verify_signature(payload, signature, secret:, timestamp: nil, tolerance: DEFAULT_TOLERANCE)
+      new(secret: secret, tolerance: tolerance).verify(payload, signature, timestamp: timestamp)
+    end
+
+    private
+
+    def parse_signature(signature)
+      raise WebhookVerificationError, 'Invalid signature format' if signature.nil?
+
+      parts = split_signature_parts(signature)
+      sig_ts = Integer(parts['t'])
+      sig_hash = parts['v1']
+      raise WebhookVerificationError, 'Invalid signature format' unless sig_hash
+
+      [sig_ts, sig_hash]
+    rescue ArgumentError, TypeError
+      raise WebhookVerificationError, 'Invalid signature format'
+    end
+
+    def split_signature_parts(signature)
+      signature.split(',').each_with_object({}) do |part, hash|
+        key, value = part.split('=', 2)
+        hash[key.strip] = value&.strip if key && value
+      end
+    end
+
+    def validate_timestamp(sig_ts)
+      difference = (Time.now.to_i - sig_ts).abs
+      return if difference <= @tolerance
+
+      raise TimestampToleranceError, 'Webhook timestamp is too old or too far in the future'
+    end
+
+    def validate_signature(payload, sig_ts, expected_hash)
+      signed_content = "#{sig_ts}.#{payload}"
+      computed = OpenSSL::HMAC.hexdigest('SHA256', @secret, signed_content)
+
+      return if OpenSSL.secure_compare(computed, expected_hash)
+
+      raise InvalidSignatureError, 'Signature verification failed'
+    end
+
+    def parse_payload(payload)
+      JSON.parse(payload)
+    rescue JSON::ParserError => e
+      raise WebhookJsonDecodeError.new('Failed to parse webhook payload as JSON', original_exception: e)
+    end
+  end
+end

data/lib/lettermint.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'lettermint/version'
+require_relative 'lettermint/errors'
+require_relative 'lettermint/types'
+require_relative 'lettermint/configuration'
+require_relative 'lettermint/http_client'
+require_relative 'lettermint/email_message'
+require_relative 'lettermint/webhook'
+require_relative 'lettermint/client'
+
+module Lettermint
+  class << self
+    def configure
+      yield configuration if block_given?
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: lettermint
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Delano
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Send transactional emails and verify webhooks with the Lettermint API.
+  Provides a fluent builder interface, typed responses, and HMAC-SHA256 webhook verification.
+email:
+- gems@onetimesecret.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lettermint.gemspec
+- lib/lettermint.rb
+- lib/lettermint/client.rb
+- lib/lettermint/configuration.rb
+- lib/lettermint/email_message.rb
+- lib/lettermint/errors.rb
+- lib/lettermint/http_client.rb
+- lib/lettermint/types.rb
+- lib/lettermint/version.rb
+- lib/lettermint/webhook.rb
+homepage: https://github.com/onetimesecret/lettermint-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/onetimesecret/lettermint-ruby
+  source_code_uri: https://github.com/onetimesecret/lettermint-ruby
+  changelog_uri: https://github.com/onetimesecret/lettermint-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby SDK for the Lettermint transactional email API
+test_files: []