Fix keyword-call crash, path encoding, and missing-key error shape

- Emails.send declared idempotency_key: as a keyword, so Ruby 3 keyword
  separation rejected the documented bare-keyword call shape
  (Emails.send(from:, to:, ...) raised ArgumentError). Drop declared
  keywords: params and options are plain positional hashes, so both the
  bare-keyword quickstart and send(hash, idempotency_key: ...) bind.
  Batch.send matches.
- Util.encode used form encoding, mapping space to "+" — wrong in a path
  segment. Re-map to %20 (safe: literal plus is already %2B).
- Missing API key raised bare Error with no name; now ApplicationError with
  status_code nil and name "application_error", matching transport errors.
- Specs: bare-keyword call shape, RFC 3986 segment encoding, and the
  strengthened missing-key assertion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Hélio Costa

lib/millionsend/batch.rb

@@ -4,10 +4,11 @@ module Millionsend
   # Send up to 100 emails in a single call.
   module Batch
     class << self
-      # POST /emails/batch with a bare array body. Supports idempotency_key:.
-      def send(list, idempotency_key: nil)
+      # POST /emails/batch with a bare array body. A trailing options hash
+      # carries idempotency_key (no keyword params, matching Emails.send).
+      def send(list, options = {})
         Millionsend::Request.new(
-          method: :post, path: "/emails/batch", body: list, idempotency_key: idempotency_key
+          method: :post, path: "/emails/batch", body: list, idempotency_key: options[:idempotency_key]
         ).perform
       end
       alias_method :create, :send

lib/millionsend/emails.rb

@@ -4,10 +4,13 @@ module Millionsend
   # Transactional email: send one, look it up, cancel a scheduled one.
   module Emails
     class << self
-      # POST /emails. Pass idempotency_key: to make a send safe to retry.
-      def send(params, idempotency_key: nil)
+      # POST /emails. Accepts a params hash or bare keywords
+      # (Emails.send(from: ..., to: ...)); a trailing options hash carries
+      # idempotency_key. No keyword parameters are declared on purpose — Ruby 3
+      # keyword separation would otherwise reject the bare-keyword call shape.
+      def send(params = {}, options = {})
         Millionsend::Request.new(
-          method: :post, path: "/emails", body: params, idempotency_key: idempotency_key
+          method: :post, path: "/emails", body: params, idempotency_key: options[:idempotency_key]
         ).perform
       end
       alias_method :create, :send

lib/millionsend/request.rb

@@ -37,8 +37,11 @@ def initialize(method:, path:, body: nil, query: nil, idempotency_key: nil)
     def perform
       api_key = Millionsend.api_key
       if api_key.nil? || api_key.to_s.empty?
-        raise Millionsend::Error.new(
-          "Missing API key. Set Millionsend.api_key or the MILLIONSEND_API_KEY environment variable.", nil
+        # Client-side failure: same class and stable name as a transport error,
+        # so rescue Millionsend::ApplicationError / branching on e.name works.
+        raise Millionsend::ApplicationError.new(
+          "Missing API key. Set Millionsend.api_key or the MILLIONSEND_API_KEY environment variable.",
+          nil, "application_error"
         )
       end
 

lib/millionsend/util.rb

@@ -8,9 +8,12 @@ module Util
     module_function
 
     # Percent-encode a single URL path segment (contact ids and emails, which
-    # can contain "@" and "+").
+    # can contain "@" and "+"). encode_www_form_component is form encoding, so
+    # it maps space to "+" — wrong inside a path segment, where servers decode
+    # "+" literally. It already turned real plus signs into %2B, so every
+    # remaining "+" is a space and can safely become %20.
     def encode(value)
-      URI.encode_www_form_component(value.to_s)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
     end
 
     # The keyset pagination params every list endpoint accepts. nil values are

spec/millionsend_spec.rb

@@ -130,11 +130,33 @@ def ok(body = '{"id":"e1"}')
       end
     end
 
-    it "raises when no API key is configured" do
+    it "raises ApplicationError with a stable name when no API key is configured" do
       Millionsend.api_key = nil
       with_env("MILLIONSEND_API_KEY" => nil) do
-        expect { Millionsend::Emails.get("e1") }.to raise_error(Millionsend::Error, /Missing API key/)
+        expect { Millionsend::Emails.get("e1") }
+          .to raise_error(Millionsend::ApplicationError, /Missing API key/) do |err|
+            expect(err.status_code).to be_nil
+            expect(err.name).to eq("application_error")
+          end
       end
     end
   end
+
+  describe "call shapes" do
+    it "accepts bare keywords, matching the README quickstart" do
+      stub_request(:post, "https://api.test/emails").to_return(ok)
+      Millionsend::Emails.send(from: "a@x.dev", to: "b@x.dev", subject: "s", html: "<p>h</p>")
+
+      expect(WebMock).to have_requested(:post, "https://api.test/emails").with(
+        body: { "from" => "a@x.dev", "to" => "b@x.dev", "subject" => "s", "html" => "<p>h</p>" }
+      )
+    end
+  end
+
+  describe Millionsend::Util do
+    it "path-encodes a segment per RFC 3986 (space is %20, never +)" do
+      expect(Millionsend::Util.encode("a b@x.dev")).to eq("a%20b%40x.dev")
+      expect(Millionsend::Util.encode("a+b@x.dev")).to eq("a%2Bb%40x.dev")
+    end
+  end
 end