zerodrop 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0225cad7779948af748c4fbb893f2b99fa91d3e5847229e8328ce435976ab9f6
-  data.tar.gz: df8926330db49fe3693dd70c4fdb19020314151fb5f8cdec2d00af83f0418b9f
+  metadata.gz: e0d9d15ff014c8e68ab17b5df720fe91c106519d0ce80be1b392e6f1a8d6f670
+  data.tar.gz: 2976e98c1c12b66f32b0b2dae010f5333c9ae1cc2c8ee82e32e23187242ce56c
 SHA512:
-  metadata.gz: a2e94b76e3b4be8886b8da78537cdec7754f03c012c592b24fe870d0abb7b8cf44f70fc8d89b5e9eb5830126536dad0645c0323a06e5b3416fb44f2a685e7cc8
-  data.tar.gz: c626edc88d22b88b74345fa45740f002532b73078df16c9ca9cf7ce067c2ffce0352031542a01255a10057e23d39670a6476080d1ffd2d616e4b9c791e410505
+  metadata.gz: e6d6a91f651194b2838800da831b989275d2952ed01158117660f4cc5cf9f97ae64f9d1dfac1807257774466919b9524eeccdb6f0694caaec82eeee74982c245
+  data.tar.gz: c239fc035a52eee16bc2e094391f04e27157b4dd9d00e02bea8a87414662d14e8b492f29bc42a68109f788166ea7a6a5e65ffb9e1c5cbfafeba4ff78387b5601

data/README.md

@@ -141,6 +141,19 @@ mail.generate_inbox
 
 Reading a `k7x2-…` inbox without your key raises `ZeroDrop::AuthError` with the reason. Without a key, if ZeroDrop held an email because its sender passed the daily limit, the inbox gets a notice instead, and `fetch_latest` and `wait_for_latest` raise `ZeroDrop::HeldError` saying so (0.3.0 or later; older versions return the notice as if it were the email, or time out when a filter skips it). `mail.prefix` holds your prefix if you build an address yourself. A key holding a character that can't be sent in an HTTP header (a line break, a byte-order mark) makes `ZeroDrop::Client.new` raise `ArgumentError`; the message never includes the key.
 
+## Workspace domain
+
+A Workspace receives mail on a domain of its own, such as `yourcompany-qa.com`, so sign-up forms that block disposable domains accept it. Every inbox on it can be read only with your key. Set the domain as `ZERODROP_DOMAIN`, or pass `domain:`, next to your key:
+
+```ruby
+mail = ZeroDrop::Client.new(api_key: ENV["ZERODROP_API_KEY"], domain: "yourcompany-qa.com")
+inbox = mail.generate_inbox
+# => "k7x2-swift-x7k29ab@yourcompany-qa.com"
+email = mail.wait_for_latest(inbox, timeout: 15)
+```
+
+Any address on the domain works, including one you name yourself: mail to `qa@yourcompany-qa.com` is filed under your prefix, and `mail.wait_for_latest("qa@yourcompany-qa.com")` reads it from there. `mail.domain` holds the domain in use. Workspaces are set up with the founder: [zerodrop.dev/pricing](https://zerodrop.dev/pricing).
+
 ## Parallel test runs
 
 `generate_inbox` runs locally — no network request, no collisions:
@@ -173,7 +186,7 @@ end
 ## Workspaces
 
 ```ruby
-mail = ZeroDrop::Client.new(api_key: ENV["ZERODROP_API_KEY"])
+mail = ZeroDrop::Client.new(api_key: ENV["ZERODROP_API_KEY"], domain: "yourcompany-qa.com")
 ```
 
 ## Self-hosted
@@ -186,9 +199,10 @@ mail = ZeroDrop::Client.new(base_url: "https://your-instance.yourdomain.com")
 
 | Method | Description |
 |---|---|
-| `Client.new(api_key: nil, base_url: ...)` | Create a client. `api_key` defaults to `ENV["ZERODROP_API_KEY"]`; without a key, inboxes are public to anyone who knows the name. |
+| `Client.new(api_key: nil, base_url: ..., domain: nil)` | Create a client. `api_key` defaults to `ENV["ZERODROP_API_KEY"]`; without a key, inboxes are public to anyone who knows the name. `domain` is your Workspace's own domain; it defaults to `ENV["ZERODROP_DOMAIN"]`, then the shared `zerodrop-sandbox.online`, and a value that isn't a domain name raises `ArgumentError`. |
 | `#generate_inbox` | Instant inbox address. No network request. With a key, the name starts with your prefix. |
 | `#prefix` | Your key's inbox prefix (`"k7x2"`), or `nil` without a key. |
+| `#domain` | The domain generated addresses use: your Workspace's, or `zerodrop-sandbox.online`. |
 | `#fetch_latest(inbox, filter: nil)` | Latest matching email or nil. Raises `HeldError` if nothing matches and the inbox has a notice that ZeroDrop held an email. |
 | `#wait_for_latest(inbox, timeout: 10, poll_interval: 2, filter: nil)` | Block until email arrives. Raises `TimeoutError` on timeout, and `HeldError` at once if ZeroDrop held the email. |
 
@@ -200,8 +214,8 @@ mail = ZeroDrop::Client.new(base_url: "https://your-instance.yourdomain.com")
 | OTP auto-extraction | ✓ | ✓ |
 | Magic link extraction | ✓ | ✓ |
 | Email filtering | ✓ | ✓ |
-| Email retention | 30 min | Extended |
-| Custom domains | ✗ | ✓ |
+| Email retention | 30 min | Up to 7 days, set for your team |
+| Custom domains | ✗ | ✓ (see [Workspace domain](#workspace-domain)) |
 | API key | ✓ free at [zerodrop.dev/keys](https://zerodrop.dev/keys) | ✓ |
 | Daily limit per sender | 5 inboxes without a key, none with one | None |
 

data/lib/zerodrop/version.rb

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

data/lib/zerodrop.rb

@@ -34,6 +34,9 @@ module ZeroDrop
   # marks that copying and pasting can bring along.
   KEY_PADDING = /\A[[:space:]\0\u{FEFF}]+|[[:space:]\0\u{FEFF}]+\z/
 
+  # A Workspace's own domain, from the domain: option or ZERODROP_DOMAIN.
+  HOST_NAME = /\A(?=.{1,253}\z)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+(?:[a-z]{2,63}|xn--[a-z0-9-]{1,59})\z/
+
   # Raised when no email arrives within the timeout.
   class TimeoutError < StandardError
     def initialize(inbox, timeout)
@@ -104,13 +107,22 @@ module ZeroDrop
     # Your key's inbox prefix ("k7x2"), or nil without a key.
     attr_reader :prefix
 
+    # The domain generated addresses use: your Workspace's, or
+    # zerodrop-sandbox.online.
+    attr_reader :domain
+
     # @param api_key [String, nil] Free API key from https://zerodrop.dev/keys.
     #   Defaults to ENV["ZERODROP_API_KEY"]. Without a key, anyone who knows
     #   an inbox's name can read it.
     # @param base_url [String] Override for self-hosted instances.
+    # @param domain [String, nil] Your Workspace's own domain, such as
+    #   "yourcompany-qa.com". Generated addresses use it, and its inboxes are
+    #   read with your key. Defaults to ENV["ZERODROP_DOMAIN"], then the shared
+    #   zerodrop-sandbox.online.
     # @raise [ArgumentError] if the key holds a character that can't be sent in
-    #   an HTTP header (a line break, a byte-order mark...)
-    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL)
+    #   an HTTP header (a line break, a byte-order mark...), or if the domain
+    #   isn't a domain name
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, domain: nil)
       key = trim_key(api_key)
       key = trim_key(ENV.fetch("ZERODROP_API_KEY", "")) if key.empty?
       unless key.empty? || key.match?(KEY_CHARS)
@@ -120,6 +132,12 @@ module ZeroDrop
       @api_key = key.empty? ? nil : key
       @prefix = KEY_FORMAT.match(@api_key.to_s)&.[](1)
       @base_url = base_url.chomp("/")
+      @domain = resolve_domain(domain)
+
+      if @domain != FREE_DOMAIN && @prefix.nil?
+        warn "[ZeroDrop] Inboxes on #{@domain} belong to your Workspace and can be read only with its API key " \
+             "(zd_xxxx_… from https://zerodrop.dev/keys). Set ZERODROP_API_KEY."
+      end
     end
 
     # Returns a ready-to-use email address instantly.
@@ -132,7 +150,7 @@ module ZeroDrop
       suffix = SecureRandom.alphanumeric(7).downcase
       name = "#{adjective}-#{suffix}"
       name = "#{@prefix}-#{name}" if @prefix
-      "#{name}@#{FREE_DOMAIN}"
+      "#{name}@#{@domain}"
     end
 
     # Returns the newest email matching the filter, or nil.
@@ -208,6 +226,22 @@ module ZeroDrop
       value.to_s.b.strip
     end
 
+    # The receiving domain: the option, else ZERODROP_DOMAIN, else the shared
+    # one. Trimmed like the key, since it is copied and pasted the same way.
+    def resolve_domain(option)
+      value = trim_key(option)
+      value = trim_key(ENV.fetch("ZERODROP_DOMAIN", "")) if value.empty?
+      return FREE_DOMAIN if value.empty?
+
+      domain = value.downcase.delete_suffix(".")
+      unless domain.match?(HOST_NAME)
+        raise ArgumentError, "ZeroDrop: the domain: option (or ZERODROP_DOMAIN) isn't a domain name. " \
+                             "Use your Workspace's domain, such as yourcompany-qa.com."
+      end
+
+      domain
+    end
+
     def http_get(uri)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
@@ -269,9 +303,17 @@ module ZeroDrop
       body.length > 5000 ? body[0, 5000] : body
     end
 
+    # The inbox an address is read from: its local part. On your Workspace's
+    # own domain, mail is filed under your key's prefix, so an address you
+    # named yourself, such as qa@yourcompany-qa.com, is read as k7x2-qa.
     def inbox_name(inbox)
-      name = inbox.include?("@") ? inbox.split("@").first : inbox
-      name.downcase
+      local = inbox.partition("@").first.downcase
+      return local unless inbox.include?("@") && @prefix && @domain != FREE_DOMAIN
+
+      domain = inbox.rpartition("@").last.downcase.delete_suffix(".")
+      return local if domain != @domain || local.start_with?("#{@prefix}-")
+
+      "#{@prefix}-#{local}"
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zerodrop
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - ZeroDrop
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-11-03 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