zerodrop 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dce1e4e518096ffccfd4fdc04f743750b64230b58cd11e631b49ee116b1ad143
+  data.tar.gz: a847df3318ff736eb8500a1407b1e2d602c637f54e18dfb0959db2d1d786fc0c
+SHA512:
+  metadata.gz: a8bfc595cd95a7b75ed9c652c27ccea75353e25b7c4355d6512c514a000773eedc09749e107738d1820c6e71cef87f619a2f41b06ebeb9f253f42798ea555eae
+  data.tar.gz: 0fbf9f95d8772a227f9a2b46c2b9092238b9dbdb75f0ddbc8a835df83bd77f28cde57c6b9b966a66b2917da534b7b5d7382217e755eaff4ba7227edc02c2c8b3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZeroDrop
+
+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,189 @@
+# zerodrop
+
+[![Gem Version](https://badge.fury.io/rb/zerodrop.svg)](https://rubygems.org/gems/zerodrop)
+[![CI](https://github.com/zerodrop-dev/zerodrop-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/zerodrop-dev/zerodrop-ruby/actions/workflows/ci.yml)
+[![license](https://img.shields.io/github/license/zerodrop-dev/zerodrop-ruby.svg)](LICENSE)
+
+Email verification infrastructure for CI pipelines.
+
+Send a verification email. Catch it at the edge. Get `email.otp` and `email.magic_link` back — auto-extracted, no regex, no Docker, no signup.
+
+```ruby
+email = mail.wait_for_latest(inbox, timeout: 15)
+
+email.otp        # => "123456" — auto-extracted
+email.magic_link # => "https://..." — no regex needed
+```
+
+**[Documentation](https://docs.zerodrop.dev)** · [GitHub](https://github.com/zerodrop-dev) · [Status](https://zerodrop.instatus.com)
+
+## Install
+
+```bash
+gem install zerodrop
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "zerodrop", group: :test
+```
+
+Zero runtime dependencies. Ruby 3.0+.
+
+## Quick start
+
+```ruby
+require "zerodrop"
+
+mail = ZeroDrop::Client.new
+inbox = mail.generate_inbox
+# => "swift-x7k29ab@zerodrop-sandbox.online"
+
+# Trigger your app's email flow with the inbox address...
+
+email = mail.wait_for_latest(inbox, timeout: 15)
+
+email.subject    # => "Verify your email"
+email.otp        # => "123456" — auto-extracted, no regex
+email.magic_link # => "https://..." — auto-extracted
+```
+
+## RSpec + Capybara
+
+```ruby
+RSpec.describe "Signup email verification", type: :system do
+  let(:mail) { ZeroDrop::Client.new }
+
+  it "verifies the account via emailed OTP" do
+    inbox = mail.generate_inbox
+
+    visit "/signup"
+    fill_in "Email", with: inbox
+    fill_in "Password", with: "TestPassword123!"
+    click_button "Create account"
+
+    email = mail.wait_for_latest(inbox, timeout: 15)
+
+    expect(email.otp).not_to be_nil
+    fill_in "Code", with: email.otp
+    click_button "Verify"
+
+    expect(page).to have_current_path("/dashboard")
+  end
+end
+```
+
+## Minitest
+
+```ruby
+require "minitest/autorun"
+require "zerodrop"
+
+class SignupTest < Minitest::Test
+  def test_email_verification
+    mail = ZeroDrop::Client.new
+    inbox = mail.generate_inbox
+
+    # Trigger signup with inbox...
+
+    email = mail.wait_for_latest(inbox, timeout: 15)
+
+    refute_nil email.otp
+    assert_match(/\A\d{6}\z/, email.otp)
+  end
+end
+```
+
+## Email filtering
+
+Filter by sender, subject, body, or extracted fields:
+
+```ruby
+email = mail.wait_for_latest(
+  inbox,
+  timeout: 15,
+  filter: ZeroDrop::Filter.new(
+    from: "noreply@yourapp.com",
+    subject: "Verify",
+    has_otp: true
+  )
+)
+```
+
+All string filters are case-insensitive partial matches.
+
+## Magic link flows
+
+```ruby
+email = mail.wait_for_latest(
+  inbox,
+  timeout: 15,
+  filter: ZeroDrop::Filter.new(has_magic_link: true)
+)
+
+visit email.magic_link
+expect(page).to have_current_path("/dashboard")
+```
+
+## Parallel test runs
+
+`generate_inbox` runs locally — no network request, no collisions:
+
+```ruby
+# parallel_tests, flatware, turbo_tests — all safe
+# Each process gets isolated inboxes automatically
+inbox = mail.generate_inbox # unique every call
+```
+
+## Error handling
+
+```ruby
+begin
+  email = mail.wait_for_latest(inbox, timeout: 15)
+rescue ZeroDrop::TimeoutError
+  # No email arrived — check your app is sending correctly
+rescue ZeroDrop::AuthError
+  # Invalid API key
+rescue ZeroDrop::NetworkError => e
+  # Transport failure — e.message includes status page link
+end
+```
+
+## Workspaces
+
+```ruby
+mail = ZeroDrop::Client.new(api_key: ENV["ZERODROP_API_KEY"])
+```
+
+## Self-hosted
+
+```ruby
+mail = ZeroDrop::Client.new(base_url: "https://your-instance.yourdomain.com")
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `Client.new(api_key: nil, base_url: ...)` | Create a client. No args = free sandbox mode. |
+| `#generate_inbox` | Instant inbox address. No network request. |
+| `#fetch_latest(inbox, filter: nil)` | Latest matching email or nil. |
+| `#wait_for_latest(inbox, timeout: 10, poll_interval: 2, filter: nil)` | Block until email arrives. |
+
+## Free vs Workspace
+
+|  | Free | Workspace |
+|---|---|---|
+| Inbox generation | ✓ | ✓ |
+| OTP auto-extraction | ✓ | ✓ |
+| Magic link extraction | ✓ | ✓ |
+| Email filtering | ✓ | ✓ |
+| Email retention | 30 min | Extended |
+| Custom domains | ✗ | ✓ |
+
+Get a Workspace at [zerodrop.dev](https://zerodrop.dev)
+
+## License
+
+MIT

data/lib/zerodrop/version.rb

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

data/lib/zerodrop.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "securerandom"
+require "time"
+
+require_relative "zerodrop/version"
+
+# ZeroDrop — disposable email inboxes for testing auth flows in CI.
+# OTPs and magic links auto-extracted at Cloudflare's edge.
+# No regex, no Docker, no signup.
+#
+#   mail = ZeroDrop::Client.new
+#   inbox = mail.generate_inbox
+#   email = mail.wait_for_latest(inbox, timeout: 15)
+#   email.otp        # => "847291"
+#   email.magic_link # => "https://..."
+module ZeroDrop
+  DEFAULT_BASE_URL = "https://zerodrop.dev"
+  FREE_DOMAIN = "zerodrop-sandbox.online"
+  ADJECTIVES = %w[swift dark cold null void zero dead raw base core].freeze
+
+  # Raised when no email arrives within the timeout.
+  class TimeoutError < StandardError
+    def initialize(inbox, timeout)
+      super("no email received at #{inbox.inspect} within #{timeout}s — " \
+            "check that your app is sending to the correct address")
+    end
+  end
+
+  # Raised when an invalid API key is provided.
+  class AuthError < StandardError
+    def initialize
+      super("invalid or missing API key")
+    end
+  end
+
+  # Raised on transport-level failures.
+  class NetworkError < StandardError; end
+
+  # A caught email with auto-extracted fields.
+  Email = Struct.new(
+    :id, :from, :to, :subject, :body, :raw_body, :received_at,
+    :otp, :magic_link,
+    keyword_init: true
+  )
+
+  # Filter for narrowing which email is returned.
+  # All string matches are case-insensitive partial matches.
+  Filter = Struct.new(
+    :from, :subject, :body, :has_otp, :has_magic_link,
+    keyword_init: true
+  ) do
+    def matches?(email)
+      return false if from && !email.from.to_s.downcase.include?(from.downcase)
+      return false if subject && !email.subject.to_s.downcase.include?(subject.downcase)
+      return false if body && !email.body.to_s.downcase.include?(body.downcase)
+
+      unless has_otp.nil?
+        return false if has_otp && email.otp.to_s.empty?
+        return false if !has_otp && !email.otp.to_s.empty?
+      end
+
+      unless has_magic_link.nil?
+        return false if has_magic_link && email.magic_link.to_s.empty?
+        return false if !has_magic_link && !email.magic_link.to_s.empty?
+      end
+
+      true
+    end
+  end
+
+  # The ZeroDrop API client.
+  class Client
+    # @param api_key [String, nil] Workspace API key. Omit for free sandbox mode.
+    # @param base_url [String] Override for self-hosted instances.
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL)
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+    end
+
+    # Returns a ready-to-use email address instantly.
+    # No network request is made.
+    #
+    # @return [String] e.g. "swift-x7k29ab@zerodrop-sandbox.online"
+    def generate_inbox
+      adjective = ADJECTIVES.sample
+      suffix = SecureRandom.alphanumeric(7).downcase
+      "#{adjective}-#{suffix}@#{FREE_DOMAIN}"
+    end
+
+    # Returns the newest email matching the filter, or nil.
+    #
+    # @param inbox [String] inbox address or name
+    # @param filter [ZeroDrop::Filter, nil]
+    # @return [ZeroDrop::Email, nil]
+    def fetch_latest(inbox, filter: nil)
+      name = inbox_name(inbox)
+      uri = URI("#{@base_url}/api/inbox/#{name}?source=ruby-sdk")
+
+      res = http_get(uri)
+      raise AuthError if res.code == "401"
+      raise NetworkError, "API returned #{res.code}" unless res.code == "200"
+
+      payload = JSON.parse(res.body)
+      emails = payload.fetch("emails", [])
+
+      emails.each do |raw|
+        email = build_email(raw)
+        return email if filter.nil? || filter.matches?(email)
+      end
+      nil
+    rescue JSON::ParserError => e
+      raise NetworkError, "invalid response: #{e.message}"
+    rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError => e
+      raise NetworkError, "#{e.message} (check https://zerodrop.instatus.com)"
+    end
+
+    # Blocks until an email matching the filter arrives.
+    # Polls every `poll_interval` seconds up to `timeout` seconds.
+    #
+    # @param inbox [String] inbox address or name
+    # @param timeout [Numeric] seconds to wait (default 10)
+    # @param poll_interval [Numeric] seconds between polls (default 2)
+    # @param filter [ZeroDrop::Filter, nil]
+    # @return [ZeroDrop::Email]
+    # @raise [ZeroDrop::TimeoutError] if nothing arrives in time
+    def wait_for_latest(inbox, timeout: 10, poll_interval: 2, filter: nil)
+      deadline = Time.now + timeout
+
+      loop do
+        email = fetch_latest(inbox, filter: filter)
+        return email if email
+
+        raise TimeoutError.new(inbox, timeout) if Time.now + poll_interval > deadline
+
+        sleep poll_interval
+      end
+    end
+
+    private
+
+    def http_get(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      req = Net::HTTP::Get.new(uri)
+      req["Authorization"] = "Bearer #{@api_key}" if @api_key
+      req["User-Agent"] = "zerodrop-ruby/#{VERSION}"
+
+      http.request(req)
+    end
+
+    def build_email(raw)
+      Email.new(
+        id: raw["id"],
+        from: raw["from"],
+        to: raw["to"],
+        subject: raw["subject"],
+        body: extract_body(raw["raw"]),
+        raw_body: raw["raw"],
+        received_at: parse_time(raw["receivedAt"]),
+        otp: raw["otp"].to_s.empty? ? nil : raw["otp"],
+        magic_link: raw["magicLink"].to_s.empty? ? nil : raw["magicLink"]
+      )
+    end
+
+    def parse_time(str)
+      Time.parse(str) if str
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def extract_body(raw)
+      return "" if raw.nil? || raw.empty?
+
+      if (m = raw.match(%r{Content-Type: text/plain[^\r\n]*\r\n\r\n(.*?)(?:\r\n--|\r\n\r\n--)}m))
+        return m[1].strip
+      end
+
+      parts = raw.split("\r\n\r\n", 2)
+      return "" unless parts.length == 2
+
+      body = parts[1].strip
+      body.length > 5000 ? body[0, 5000] : body
+    end
+
+    def inbox_name(inbox)
+      name = inbox.include?("@") ? inbox.split("@").first : inbox
+      name.downcase
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: zerodrop
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ZeroDrop
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-13 00:00:00.000000000 Z
+dependencies: []
+description: ZeroDrop catches verification emails at Cloudflare's edge and auto-extracts
+  OTP codes and magic links. Test email verification, magic links, OTP and password
+  reset flows in RSpec, Minitest or Capybara — no regex, no Docker, no signup.
+email:
+- founder@zerodrop.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/zerodrop.rb
+- lib/zerodrop/version.rb
+homepage: https://zerodrop.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://zerodrop.dev
+  source_code_uri: https://github.com/zerodrop-dev/zerodrop-ruby
+  documentation_uri: https://docs.zerodrop.dev
+  bug_tracker_uri: https://github.com/zerodrop-dev/zerodrop-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Disposable email inboxes for testing auth flows in CI — OTPs and magic links
+  auto-extracted.
+test_files: []