mailcapture 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 435a3e55721f1f7c5b9ec7a00fd74d97fc0ae885c2dbdb18f25adff35f93c83f
+  data.tar.gz: c40a4f37bcdff35a7a8ecb90aad1b5dc883aad72ffc29dedfd09daa7b2d71b18
+SHA512:
+  metadata.gz: 566b16ae0811c9244c458f47afedfb0cf7a7b79abc3741a14e8fd1d91212081b5bcf006b3baa774c44541bf480a680d40dab32b5cefdd14f4cbed954390f7de2
+  data.tar.gz: 8a502fd4cf5cbb425da8ab5b0326cb01a40c1929aa497a47fcaa804823cbc1dbdab9843f52f71b6fbee6c24e568f8c30b73799737d7a127a0f1c149b7a636099

data/README.md

@@ -0,0 +1,271 @@
+# mailcapture
+
+Official Ruby gem for [MailCapture](https://mailcapture.app) — a real email capture API for integration testing OTP codes, verification links, and other transactional emails.
+
+Zero runtime dependencies. Works with any Ruby web framework (Rails, Sinatra, Hanami, Roda, or plain Rack).
+
+## Requirements
+
+- Ruby 3.1+
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'mailcapture'
+```
+
+Or install directly:
+
+```bash
+gem install mailcapture
+```
+
+## Quick start
+
+```ruby
+mc = MailCapture.new(api_key: ENV['MAILCAPTURE_API_KEY'])
+mc.ping  # validates key, caches username
+
+# In your test:
+mc.delete('signup')
+MyApp.register(mc.address('signup'))   # "alice-signup@mailcapture.app"
+email = mc.wait_for('signup', timeout: 15)
+
+puts email.subject   # "Verify your account"
+puts email.otp       # "123456" — extracted automatically
+```
+
+## Integration test pattern (RSpec)
+
+```ruby
+# spec/features/user_registration_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'User registration email', :integration do
+  let(:mc)    { MailCapture.new(api_key: ENV['MAILCAPTURE_API_KEY']) }
+  let(:inbox) { mc.inbox('signup') }
+
+  before(:all) { mc.ping }   # validates key, caches username
+  before(:each) { inbox.clear }  # clean inbox before every test
+
+  it 'sends a 6-digit OTP' do
+    post '/users', params: { email: inbox.address }
+
+    email = inbox.wait_for(timeout: 10)
+
+    expect(email.subject).to eq('Verify your account')
+    expect(email.otp).to match(/\A\d{6}\z/)
+    expect(email.latency_ms).to be < 5000
+  end
+end
+```
+
+## Integration test pattern (Minitest / Rails)
+
+```ruby
+# test/integration/signup_test.rb
+class SignupEmailTest < ActionDispatch::IntegrationTest
+  setup do
+    @mc    = MailCapture.new(api_key: ENV['MAILCAPTURE_API_KEY'], username: 'alice')
+    @inbox = @mc.inbox('signup')
+    @inbox.clear
+  end
+
+  test 'sends verification email with OTP' do
+    post sign_up_path, params: { email: @inbox.address }
+
+    email = @inbox.wait_for(timeout: 10)
+
+    assert_equal 'Verify your account', email.subject
+    assert_match(/\A\d{6}\z/, email.otp)
+  end
+end
+```
+
+## API reference
+
+### `MailCapture.new(api_key:, ...)`
+
+```ruby
+# Minimal
+mc = MailCapture.new(api_key: ENV['MAILCAPTURE_API_KEY'])
+
+# All options
+mc = MailCapture.new(
+  api_key:  ENV['MAILCAPTURE_API_KEY'],
+  base_url: 'http://localhost:3002',  # local dev
+  timeout:  15,                       # default request timeout in seconds
+  username: 'alice',                  # pre-set to skip ping
+)
+```
+
+---
+
+### `mc.ping` → `PingResult`
+
+Validates your API key and returns your address template. Caches your username so `address` works without a network call.
+
+```ruby
+result = mc.ping
+result.username          # => "alice"
+result.address_template  # => "alice-{tag}@mailcapture.app"
+result.example           # => "alice-signup@mailcapture.app"
+```
+
+---
+
+### `mc.wait_for(tag, timeout:, poll_timeout:, after:)` → `Capture`
+
+Long-polls the API and returns the first email captured for the given tag. The server holds the connection open — no busy-waiting.
+
+```ruby
+# Named arguments (recommended)
+email = mc.wait_for('signup', timeout: 15)
+
+# Full options
+email = mc.wait_for('signup',
+  timeout:      15,             # total seconds to wait (default 30)
+  poll_timeout: 5,              # per-poll server timeout in seconds, max 30 (default 10)
+  after:        Time.now - 30,  # only captures after this time
+)
+```
+
+Raises `MailCapture::TimeoutError` if no email arrives in time.
+
+---
+
+### `mc.inbox(tag)` → `Inbox`
+
+Returns a scoped `Inbox` for a tag. Keeps test code clean.
+
+```ruby
+inbox = mc.inbox('password-reset')
+
+inbox.address               # => "alice-password-reset@mailcapture.app"
+inbox.wait_for(timeout: 10) # => Capture
+inbox.list(limit: 5)        # => CaptureList
+inbox.clear                 # deletes all captures for this tag
+```
+
+---
+
+### `mc.address(tag)` → `String`
+
+Generates the capture email address synchronously. Requires `ping` first (or `username:` in the constructor).
+
+```ruby
+mc.ping
+mc.address('signup')  # => "alice-signup@mailcapture.app"
+```
+
+---
+
+### `mc.list(tag:, limit:, after:)` → `CaptureList`
+
+Lists recent captures (newest first).
+
+```ruby
+result = mc.list(tag: 'signup', limit: 10)
+result.items.each { |email| puts email.subject }
+result.count  # => total count
+```
+
+---
+
+### `mc.get(capture_id)` → `Capture`
+
+Gets a single capture by ID. Raises `MailCapture::NotFoundError` if not found.
+
+---
+
+### `mc.delete(tag)` → `nil`
+
+Deletes all captures for a tag. Use in `before(:each)` or `setup` for test isolation.
+
+---
+
+## The `Capture` object
+
+```ruby
+email.id          # String  — UUID
+email.tag         # String  — e.g. "signup"
+email.subject     # String  — email subject line
+email.otp         # String? — extracted code, nil if none detected
+email.body_text   # String? — plain-text body
+email.body_html   # String? — HTML body
+email.latency_ms  # Integer — send-to-capture time in ms
+email.status      # String  — e.g. "captured"
+email.received_at # String  — ISO 8601 timestamp
+```
+
+The `otp` field is extracted automatically. If your OTP is in the middle of a sentence, the service finds it for you.
+
+---
+
+## Exception handling
+
+All exceptions extend `MailCapture::Error` and have a `code` attribute.
+
+```ruby
+begin
+  email = mc.wait_for('signup', timeout: 10)
+rescue MailCapture::TimeoutError => e
+  puts "Waited #{e.waited_seconds}s for tag: #{e.tag}"
+  puts 'Did the email actually send? Check your email service logs.'
+rescue MailCapture::AuthError
+  puts 'Check your MAILCAPTURE_API_KEY environment variable.'
+rescue MailCapture::NetworkError => e
+  puts "Network error: #{e.message}"
+end
+```
+
+| Exception | `code` | When |
+|---|---|---|
+| `MailCapture::AuthError` | `UNAUTHORIZED` | Invalid or revoked API key |
+| `MailCapture::TimeoutError` | `TIMEOUT` | `wait_for` exceeded its timeout |
+| `MailCapture::NotFoundError` | `NOT_FOUND` | `get` — capture not found |
+| `MailCapture::NetworkError` | `NETWORK_ERROR` | Could not reach the API |
+| `MailCapture::ApiError` | varies | Unexpected API error |
+
+---
+
+## Parallel tests
+
+Each tag is its own inbox — safe to run in parallel.
+
+```ruby
+# RSpec with parallel_tests gem:
+describe 'signup email', :parallel do
+  let(:inbox) { mc.inbox("signup-#{$$}") }  # per-process tag
+  before { inbox.clear }
+
+  it 'sends OTP' do
+    email = inbox.wait_for(timeout: 10)
+    expect(email.otp).to match(/\A\d{6}\z/)
+  end
+end
+```
+
+---
+
+## Rails configuration
+
+```ruby
+# config/initializers/mailcapture.rb (test environment only)
+if Rails.env.test?
+  MAILCAPTURE = MailCapture.new(
+    api_key: ENV.fetch('MAILCAPTURE_API_KEY'),
+    username: ENV.fetch('MAILCAPTURE_USERNAME', nil),  # skip ping if known
+  )
+end
+```
+
+---
+
+## Local development
+
+```ruby
+mc = MailCapture.new(api_key: key, base_url: 'http://localhost:3002')
+```

data/lib/mailcapture/client.rb

@@ -0,0 +1,329 @@
+require 'json'
+require 'net/http'
+require 'uri'
+
+module MailCapture
+  # MailCapture API client. Create one with {MailCapture.new} or
+  # {MailCapture::Client.new} and reuse it across your test suite.
+  #
+  # @example Basic usage
+  #   mc = MailCapture.new(api_key: ENV['MAILCAPTURE_API_KEY'])
+  #   mc.ping
+  #
+  #   mc.delete('signup')
+  #   MyApp.register(mc.address('signup'))   # "alice-signup@mailcapture.app"
+  #   email = mc.wait_for('signup', timeout: 15)
+  #   expect(email.otp).to eq('123456')
+  #
+  # @example With Inbox (recommended)
+  #   inbox = mc.inbox('signup')
+  #   inbox.clear
+  #   MyApp.register(inbox.address)
+  #   email = inbox.wait_for(timeout: 15)
+  class Client
+    MAX_POLL_SECONDS   = 30
+    SERVER_POLL_BUFFER = 5
+
+    ADJECTIVES = %w[
+      angry bold brave calm cold cool dark dizzy dusty eager fierce fluffy
+      funky fuzzy glad gloomy grumpy hasty hungry icy itchy jolly jumpy
+      keen lazy lucky mad mean moody muddy noisy odd pale peppy proud quick
+      quiet rowdy rusty silly sleepy sneaky spooky swift tiny tough vivid
+      weird wild young
+    ].freeze
+
+    ANIMALS = %w[
+      ant bear boar cat crab crow deer dove duck eel elk finch fox frog
+      goat hawk hare ibis jay kiwi lamb lark lion lynx mink mole moth mule
+      newt owl panda pig puma ram rat rook seal slug snail swan toad vole
+      wasp wolf wren yak zebra bat bee carp
+    ].freeze
+
+    # @param api_key [String]     your MailCapture API key (+mc_...+)
+    # @param base_url [String]    API base URL (override for local dev)
+    # @param timeout [Numeric]    default request timeout in seconds
+    # @param username [String, nil] pre-set username to skip +ping+
+    def initialize(api_key:, base_url: 'https://mailcapture.app', timeout: 10, username: nil)
+      raise ArgumentError,
+        "MailCapture: api_key is required.\n" \
+        "  MailCapture.new(api_key: ENV['MAILCAPTURE_API_KEY'])" if api_key.to_s.empty?
+
+      unless api_key.start_with?('mc_')
+        warn '[mailcapture] API key does not start with "mc_". Are you sure you copied the full key? ' \
+             'Make sure you copied the full key from https://mailcapture.app/admin/api-keys'
+      end
+
+      @api_key  = api_key
+      @base_url = base_url.chomp('/')
+      @timeout  = timeout
+      @username = username
+    end
+
+    # -------------------------------------------------------------------------
+    # Public API
+
+    # Validate your API key and return your capture address template.
+    # Also caches your username so {#address} works without a network call.
+    #
+    # @return [PingResult]
+    # @raise [AuthError] if the API key is invalid
+    def ping
+      data = request(:get, '/v1/ping')
+      result = PingResult.from_hash(data)
+      @username = result.username
+      result
+    end
+
+    # Wait for an email to arrive at the given tag and return it.
+    #
+    # Long-polls the API — the server holds the connection open and responds
+    # the instant an email arrives. No busy-waiting.
+    #
+    # The +after+ cursor defaults to 60 seconds ago so recent emails are
+    # included but stale ones from previous runs are ignored.
+    # For maximum isolation, call +delete(tag)+ before triggering the email.
+    #
+    # @param tag [String]
+    # @param timeout [Numeric]     total seconds to wait (default 60)
+    # @param poll_timeout [Integer] per-poll server timeout, max 30 (default 10)
+    # @param after [Time, nil]     only captures received after this time
+    # @return [Capture]
+    # @raise [TimeoutError]  if no email arrives before +timeout+
+    # @raise [AuthError]     if the API key is invalid
+    #
+    # @example
+    #   email = mc.wait_for('signup', timeout: 15)
+    #   expect(email.otp).to match(/\A\d{6}\z/)
+    def wait_for(tag, timeout: 60, poll_timeout: 10, after: nil)
+      poll_timeout = [[poll_timeout.to_i, 1].max, MAX_POLL_SECONDS].min
+      deadline     = Time.now + timeout
+      after      ||= Time.now - 60
+
+      loop do
+        remaining = deadline - Time.now
+        break if remaining <= 0
+
+        effective_poll = [poll_timeout, [1, remaining.ceil].max].min
+
+        result = poll_latest(tag, effective_poll, after)
+        if result
+          return result[:items].first unless result[:items].empty?
+
+          after = Time.parse(result[:next_after])
+        end
+        # result nil => server-side 408, loop again
+      end
+
+      hint = if @username
+               "Make sure you're sending to #{@username}-#{tag}@mailcapture.app."
+             else
+               'Check that you\'re sending to the right address (call ping first to get your username).'
+             end
+      raise TimeoutError.new(tag: tag, waited_seconds: timeout, hint: hint)
+    end
+
+    # List recent captures (newest first).
+    #
+    # @param tag [String, nil]
+    # @param limit [Integer, nil]  max results (1-100, default 25)
+    # @param after [Time, nil]     only captures received after this time
+    # @return [CaptureList]
+    #
+    # @example
+    #   result = mc.list(tag: 'signup', limit: 10)
+    #   result.items.each { |e| puts e.subject }
+    def list(tag: nil, limit: nil, after: nil)
+      params = {}
+      params[:tag]   = tag                                     if tag
+      params[:limit] = limit.to_s                             if limit
+      params[:after] = after.utc.strftime('%Y-%m-%dT%H:%M:%SZ') if after
+
+      CaptureList.from_hash(request(:get, '/v1/captures', params: params))
+    end
+
+    # Get a single capture by ID.
+    #
+    # @param capture_id [String]
+    # @return [Capture]
+    # @raise [NotFoundError] if the capture does not exist
+    def get(capture_id)
+      raise ArgumentError, 'capture_id is required' if capture_id.to_s.empty?
+
+      Capture.from_hash(request(:get, "/v1/captures/#{encode(capture_id)}"))
+    end
+
+    # Delete all captures for a tag.
+    # Call before each test to start with a clean inbox.
+    #
+    # @param tag [String]
+    #
+    # @example
+    #   before(:each) { mc.delete('signup') }
+    def delete(tag)
+      raise ArgumentError, 'tag is required' if tag.to_s.empty?
+
+      request(:delete, "/v1/captures/#{encode(tag)}")
+      nil
+    end
+
+    # Return a scoped {Inbox} for a specific tag.
+    #
+    # @param tag [String]
+    # @return [Inbox]
+    #
+    # @example
+    #   inbox = mc.inbox('password-reset')
+    #   inbox.clear
+    #   MyApp.request_password_reset(inbox.address)
+    #   email = inbox.wait_for(timeout: 10)
+    def inbox(tag)
+      raise ArgumentError, 'tag is required' if tag.to_s.empty?
+
+      Inbox.new(self, tag)
+    end
+
+    # Return the capture email address for a tag.
+    #
+    # Requires {#ping} to have been called first, or +:username+ set in the constructor.
+    #
+    # @param tag [String]
+    # @return [String] e.g. "alice-signup@mailcapture.app"
+    # @raise [RuntimeError] if username is not yet known
+    def address(tag)
+      raise 'MailCapture: username is not known. Call ping first or pass username: to the constructor.' \
+        unless @username
+
+      "#{@username}-#{tag}@mailcapture.app"
+    end
+
+    # Your cached username, set after {#ping} or via the constructor.
+    # @return [String, nil]
+    def username
+      @username
+    end
+
+    # Generate a unique, human-readable tag such as +"funky-otter-a3f2b8"+.
+    # Format: +{adjective}-{animal}-{6 hex digits}+.
+    # ~42 billion combinations — collision probability < 0.1% across 10 000 tags.
+    # No client or network call needed.
+    #
+    # @return [String]
+    #
+    # @example
+    #   tag = MailCapture::Client.generate_tag   # "funky-otter-a3f2b8"
+    def self.generate_tag
+      adj    = ADJECTIVES.sample
+      animal = ANIMALS.sample
+      suffix = format('%06x', rand(0x1000000))
+      "#{adj}-#{animal}-#{suffix}"
+    end
+
+    # Instance-level shortcut so you can call +mc.generate_tag+ too.
+    # @return [String]
+    def generate_tag
+      self.class.generate_tag
+    end
+
+    # Generate a unique tag and its capture email address.
+    # Requires {#ping} to have been called first (same contract as {#address}).
+    #
+    # @return [GenerateResult] with +tag+ and +email+ attributes
+    #
+    # @example
+    #   mc.ping
+    #   result = mc.generate
+    #   # result.tag   => "funky-otter-a3f2b8"
+    #   # result.email => "alice-funky-otter-a3f2b8@mailcapture.app"
+    #   MyApp.register(result.email)
+    #   email = mc.wait_for(result.tag, timeout: 15)
+    def generate
+      tag = generate_tag
+      GenerateResult.new(tag: tag, email: address(tag))
+    end
+
+    private
+
+    # -------------------------------------------------------------------------
+    # Internals
+
+    # Long-poll /v1/latest/:tag once.
+    # Returns nil on a server-side 408 (no emails yet — caller loops again).
+    def poll_latest(tag, poll_timeout, after)
+      params = {
+        timeout: poll_timeout.to_i,
+        after:   after.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+      }
+      path = "/v1/latest/#{encode(tag)}"
+
+      response = send_http(:get, path, params: params,
+                                        read_timeout: poll_timeout + SERVER_POLL_BUFFER)
+
+      return nil if response.code.to_i == 408
+
+      raise_for_status(response)
+
+      data = JSON.parse(response.body)
+      {
+        items:      (data['items'] || []).map { |item| Capture.from_hash(item) },
+        next_after: data['next_after']
+      }
+    rescue JSON::ParserError
+      raise ApiError.new('Invalid JSON from API', status_code: 200, code: 'INVALID_RESPONSE')
+    end
+
+    def request(method, path, params: {})
+      response = send_http(method, path, params: params, read_timeout: @timeout)
+      return {} if response.code.to_i == 204
+
+      raise_for_status(response)
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise ApiError.new('Invalid JSON from API', status_code: 200, code: 'INVALID_RESPONSE')
+    end
+
+    def send_http(method, path, params: {}, read_timeout: @timeout)
+      uri = URI("#{@base_url}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
+                                          open_timeout: 10,
+                                          read_timeout: read_timeout) do |http|
+        req = case method
+              when :get    then Net::HTTP::Get.new(uri)
+              when :delete then Net::HTTP::Delete.new(uri)
+              end
+        req['X-API-Key'] = @api_key
+        req['Accept']    = 'application/json'
+        http.request(req)
+      end
+    rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+           Net::OpenTimeout, SocketError => e
+      raise NetworkError.new(@base_url, e)
+    end
+
+    def raise_for_status(response)
+      return if response.code.to_i.between?(200, 299)
+
+      body = parse_error_body(response.body)
+      case response.code.to_i
+      when 401 then raise AuthError.new(body[:detail])
+      when 404 then raise NotFoundError.new(body[:detail])
+      else
+        raise ApiError.new(body[:detail] || body[:code],
+                           status_code: response.code.to_i,
+                           code: body[:code])
+      end
+    end
+
+    def parse_error_body(raw)
+      data = JSON.parse(raw)
+      { code: data['message'], detail: data['detail'] }
+    rescue JSON::ParserError
+      { code: 'UNKNOWN_ERROR', detail: nil }
+    end
+
+    def encode(str)
+      URI.encode_uri_component(str)
+    end
+  end
+end

data/lib/mailcapture/errors.rb

@@ -0,0 +1,87 @@
+module MailCapture
+  # Base class for all MailCapture errors.
+  # Check +code+ for a machine-readable error type.
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(message, code:)
+      super(message)
+      @code = code
+    end
+  end
+
+  # Raised when authentication fails — the API key is invalid, expired, or revoked.
+  #
+  #   rescue MailCapture::AuthError
+  #     # Check your MAILCAPTURE_API_KEY environment variable.
+  #   end
+  class AuthError < Error
+    def initialize(detail = nil)
+      hint = detail ? "Server said: #{detail.inspect}." : 'Your API key was rejected.'
+      super(
+        "Authentication failed. #{hint} " \
+        'Make sure your key is valid and has not been revoked. ' \
+        'Keys look like: mc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. ' \
+        'Find your keys at https://mailcapture.app/admin/api-keys',
+        code: 'UNAUTHORIZED'
+      )
+    end
+  end
+
+  # Raised by +wait_for+ when no email arrives before the timeout.
+  #
+  #   rescue MailCapture::TimeoutError => e
+  #     puts "Waited #{e.waited_seconds}s for tag: #{e.tag}"
+  #   end
+  class TimeoutError < Error
+    # @return [String] the tag that was being waited on
+    attr_reader :tag
+    # @return [Numeric] seconds elapsed before giving up
+    attr_reader :waited_seconds
+
+    def initialize(tag:, waited_seconds:, hint: nil)
+      @tag = tag
+      @waited_seconds = waited_seconds
+      message = "No email arrived for tag #{tag.inspect} within #{waited_seconds.to_i}s."
+      message += " #{hint}" if hint
+      super(message, code: 'TIMEOUT')
+    end
+  end
+
+  # Raised when a capture is not found by ID.
+  class NotFoundError < Error
+    def initialize(detail = nil)
+      super(
+        detail || 'Capture not found. It may have expired, been deleted, or the ID is incorrect.',
+        code: 'NOT_FOUND'
+      )
+    end
+  end
+
+  # Raised when the SDK cannot reach the MailCapture API.
+  # The original exception is available via +cause+ (Ruby's built-in +cause+ on exceptions).
+  class NetworkError < Error
+    def initialize(base_url, original_error = nil)
+      @original_error = original_error
+      super(
+        "Could not reach the MailCapture API at #{base_url}. " \
+        'Check your network connection and firewall settings.',
+        code: 'NETWORK_ERROR'
+      )
+    end
+  end
+
+  # Raised when the API returns an unexpected status code.
+  class ApiError < Error
+    # @return [Integer] HTTP status code
+    attr_reader :status_code
+    # @return [String, nil] human-readable detail from the server
+    attr_reader :detail
+
+    def initialize(detail, status_code:, code: 'UNKNOWN_ERROR')
+      @status_code = status_code
+      @detail = detail
+      super("API error (#{status_code}): #{detail || code}", code: code)
+    end
+  end
+end

data/lib/mailcapture/inbox.rb

@@ -0,0 +1,53 @@
+module MailCapture
+  # A scoped handle for a single capture inbox (tag).
+  # Create one with +Client#inbox+.
+  #
+  # Keeps test code clean by binding the tag once:
+  #
+  #   inbox = mc.inbox('signup')
+  #   inbox.clear
+  #   MyApp.register(inbox.address)
+  #   email = inbox.wait_for(timeout: 15)
+  #   expect(email.otp).to match(/\A\d{6}\z/)
+  class Inbox
+    # @return [String] the tag this inbox is scoped to
+    attr_reader :tag
+
+    def initialize(client, tag)
+      @client = client
+      @tag    = tag
+    end
+
+    # The full capture email address for this inbox,
+    # e.g. "alice-signup@mailcapture.app".
+    #
+    # Requires +ping+ to have been called first, or +:username+ set in the constructor.
+    #
+    # @raise [RuntimeError] if the username is not yet known
+    def address
+      @client.address(tag)
+    end
+
+    # Wait for an email to arrive. See {Client#wait_for}.
+    def wait_for(timeout: 30, poll_timeout: 10, after: nil)
+      @client.wait_for(tag, timeout: timeout, poll_timeout: poll_timeout, after: after)
+    end
+
+    # List recent captures. See {Client#list}.
+    def list(limit: nil, after: nil)
+      @client.list(tag: tag, limit: limit, after: after)
+    end
+
+    # Delete all captures. Call before each test for a clean starting state.
+    #
+    #   before(:each) { inbox.clear }
+    def clear
+      @client.delete(tag)
+    end
+
+    def to_s
+      "#<MailCapture::Inbox tag=#{tag.inspect}>"
+    end
+    alias inspect to_s
+  end
+end

data/lib/mailcapture/models.rb

@@ -0,0 +1,97 @@
+module MailCapture
+  # Result from {Client#generate}.
+  GenerateResult = Struct.new(:tag, :email, keyword_init: true) do
+    def to_s
+      "#<MailCapture::GenerateResult tag=#{tag.inspect} email=#{email.inspect}>"
+    end
+    alias inspect to_s
+  end
+
+  # A captured email.
+  #
+  #   email = mc.wait_for('signup')
+  #   email.otp        # => "123456"
+  #   email.subject    # => "Verify your account"
+  #   email.latency_ms # => 145
+  class Capture
+    # @return [String] unique capture ID
+    attr_reader :id
+    # @return [String] tag portion of the address, e.g. "signup"
+    attr_reader :tag
+    # @return [String] email subject line
+    attr_reader :subject
+    # @return [String, nil] extracted OTP/code, or nil if none detected
+    attr_reader :otp
+    # @return [String, nil] plain-text body, or nil if not present
+    attr_reader :body_text
+    # @return [String, nil] HTML body, or nil if not present
+    attr_reader :body_html
+    # @return [Integer] send-to-capture latency in milliseconds
+    attr_reader :latency_ms
+    # @return [String] delivery status, e.g. "captured"
+    attr_reader :status
+    # @return [String] ISO 8601 timestamp of when the email was received
+    attr_reader :received_at
+
+    def self.from_hash(data)
+      new(data)
+    end
+
+    def initialize(data)
+      @id          = data['id']
+      @tag         = data['tag']
+      @subject     = data['subject']
+      @otp         = data['otp']
+      @body_text   = data['body_text']
+      @body_html   = data['body_html']
+      @latency_ms  = data['latency_ms']
+      @status      = data['status']
+      @received_at = data['received_at']
+    end
+
+    def to_s
+      "#<MailCapture::Capture id=#{id.inspect} tag=#{tag.inspect} subject=#{subject.inspect}>"
+    end
+    alias inspect to_s
+  end
+
+  # Response from +list+.
+  class CaptureList
+    # @return [Array<Capture>]
+    attr_reader :items
+    # @return [Integer]
+    attr_reader :count
+
+    def self.from_hash(data)
+      new(data)
+    end
+
+    def initialize(data)
+      @items = (data['items'] || []).map { |item| Capture.from_hash(item) }
+      @count = data['count'].to_i
+    end
+  end
+
+  # Response from +ping+.
+  class PingResult
+    # @return [String] your unique username
+    attr_reader :username
+    # @return [String] template string — replace {tag} with your desired tag
+    attr_reader :address_template
+    # @return [String] a concrete example address
+    attr_reader :example
+    # @return [String]
+    attr_reader :status
+
+    def self.from_hash(data)
+      new(data)
+    end
+
+    def initialize(data)
+      @status           = data['status']
+      @username         = data['username']
+      @address_template = data['address_template']
+      @example          = data['example']
+    end
+  end
+end

data/lib/mailcapture/version.rb

@@ -0,0 +1,3 @@
+module MailCapture
+  VERSION = '1.0.0'
+end

data/lib/mailcapture.rb

@@ -0,0 +1,30 @@
+require 'mailcapture/version'
+require 'mailcapture/errors'
+require 'mailcapture/models'
+require 'mailcapture/inbox'
+require 'mailcapture/client'
+
+# MailCapture — real email capture for integration tests.
+#
+# @example Quick start
+#   mc = MailCapture.new(api_key: ENV['MAILCAPTURE_API_KEY'])
+#   mc.ping
+#
+#   mc.delete('signup')
+#   MyApp.register(mc.address('signup'))   # "alice-signup@mailcapture.app"
+#   email = mc.wait_for('signup', timeout: 15)
+#   email.otp  # => "123456"
+#
+# @example With Inbox (recommended for test suites)
+#   inbox = mc.inbox('signup')
+#   inbox.clear
+#   MyApp.register(inbox.address)
+#   email = inbox.wait_for(timeout: 15)
+module MailCapture
+  # Convenience constructor — equivalent to MailCapture::Client.new.
+  #
+  # @return [Client]
+  def self.new(**kwargs)
+    Client.new(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: mailcapture
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- MailCapture
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: Capture and assert on real transactional emails in integration and CI
+  tests.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/mailcapture.rb
+- lib/mailcapture/client.rb
+- lib/mailcapture/errors.rb
+- lib/mailcapture/inbox.rb
+- lib/mailcapture/models.rb
+- lib/mailcapture/version.rb
+homepage: https://mailcapture.app
+licenses:
+- MIT
+metadata: {}
+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: Official Ruby SDK for the MailCapture email testing API
+test_files: []