quolle 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37768ae3c543a6ebc5a59a65f4c208d1c2c1ccbb7fdb5f47eec6e01fe17ab9a4
-  data.tar.gz: 289978e8755370fa7a339248c16ffdcd098b8ff4b5a7e3355f0e6312853ac1d0
+  metadata.gz: d49a558cd0e8d55d4a043225faf03055ab2d71b645b0d1fb9480acb5931addc0
+  data.tar.gz: 57eaff3fe141479fe6f99e5a84dc226957efb2dc3145f65f0666e9e9b5c8d556
 SHA512:
-  metadata.gz: c2ab703c9aad2e30a20b45fca63657833b571a915681669222c61589bc928492b54517ee1e1758e71b565e4a54b426215f7a488be045be4f911581d34bed163e
-  data.tar.gz: b2b5282fe08b21d98e4906416e7d4a4a17bb0a3f938f2566dab9427667c734d1c439a3097f90d65908ca5d7c81a98e2278b1a12794c0b4e7f1e4df779a4e937a
+  metadata.gz: aa4abf51a8b949560722c0fb9e7f4ad55653a6a16fac85f56c7a427ab0fe34ce0a52bad869c48274c76b959287734f48aef984a7134727854e931b9e8f4c1f5f
+  data.tar.gz: f04d7e24d159145ef67a7dbcc5c4675637d562dcd62f7eb509428837b1715e5ec735d3f5673d01bed8a531e80fa26310c07895488e75d37c328591da5570d457

data/README.md

@@ -14,7 +14,7 @@ Or in your Gemfile:
 gem "quolle"
 ```
 
-Requires Ruby 2.7+. No third-party dependencies.
+Requires Ruby 3.3+. No third-party dependencies.
 
 ## Quick start
 
@@ -33,6 +33,11 @@ result = quolle.emails.send(
 puts "Queued: #{result['id']}"
 ```
 
+`emails.create(...)` does exactly the same thing and doesn't shadow Ruby's
+`Object#send`, so prefer it if you use `send` for dynamic dispatch. Pass
+`type: "marketing"` for marketing mail (adds unsubscribe headers); the default
+is transactional.
+
 ## Sending
 
 ### Multiple recipients
@@ -135,6 +140,7 @@ begin
   )
 rescue Quolle::Error => e
   puts e.status_code # e.g. 402
+  puts e.code        # e.g. "monthly_quota_exceeded" — branch on this
   puts e.message     # e.g. "Monthly limit reached"
   puts e.data        # extra fields, e.g. {"limit" => 3000}
 end
@@ -165,9 +171,32 @@ end
 
 HMAC-SHA256 with a 5-minute timestamp window (replay protection).
 
+## Domains, API keys and webhooks
+
+These need a **full-access** API key. A sending-only key gets `403` with code `restricted_api_key`, so a key you ship in an app can't create keys or change your domains.
+
+```ruby
+# Domains
+created = quolle.domains.create("mail.example.com")    # created["dnsRecords"] to publish
+quolle.domains.verify(created["domain"]["id"])          # check DNS now
+quolle.domains.list.each { |d| puts "#{d["domain"]} #{d["status"]}" }
+
+# API keys
+new_key = quolle.api_keys.create(name: "web app", scope: "sending", domains: ["mail.example.com"])
+puts new_key["key"]                                      # shown once
+quolle.api_keys.remove(new_key["id"])
+
+# Webhook endpoints
+hook = quolle.webhooks.create(url: "https://example.com/hooks/quolle", events: %w[email.delivered email.bounced])
+# hook["secret"] (whsec_…) is shown once; store it for quolle.webhooks.verify(...)
+quolle.webhooks.test(hook["id"])
+quolle.webhooks.deliveries(hook["id"], status: "failed").each { |d| quolle.webhooks.redeliver(hook["id"], d["id"]) }
+new_secret = quolle.webhooks.rotate_secret(hook["id"])["secret"]
+```
+
 ## Automatic retries
 
-Transient failures — HTTP 429 (rate limit) and 5xx, plus network errors — are retried automatically with exponential backoff, honoring the `Retry-After` header. To avoid double-sending, a POST is only retried on a 5xx/network error when you pass an idempotency key; a 429 is always safe to retry (the request was never processed). Tune with `max_retries:` on `Quolle.new` (default 3).
+Transient failures — HTTP 429 (rate limit) and 5xx, plus network errors — are retried automatically with exponential backoff, honoring the `Retry-After` header. To avoid double-sending, a POST is only retried on a 5xx/network error when you pass an idempotency key; a 429 is always safe to retry (the request was never processed). Quota limits are the exception: `daily_quota_exceeded` and `warmup_limit_exceeded` (and any `Retry-After` over 60 seconds) are raised immediately, because they reset at a fixed time, not in seconds; check `e.code` and queue the send for later. Tune with `max_retries:` on `Quolle.new` (default 3).
 
 ## License
 

data/lib/quolle/client.rb

@@ -8,6 +8,8 @@ require_relative "version"
 require_relative "error"
 require_relative "resources/emails"
 require_relative "resources/webhooks"
+require_relative "resources/domains"
+require_relative "resources/api_keys"
 
 module Quolle
   # The Quolle API client.
@@ -27,6 +29,18 @@ module Quolle
     attr_reader :emails
     # @return [Quolle::Resources::Webhooks]
     attr_reader :webhooks
+    # @return [Quolle::Resources::Domains] sending domains (full-access key)
+    attr_reader :domains
+    # @return [Quolle::Resources::ApiKeys] API keys (full-access key)
+    attr_reader :api_keys
+
+    # 429s that retrying can't fix: the limit resets at a fixed time (midnight
+    # UTC, the next billing period), not in seconds. Raised at once so the
+    # caller can queue the send instead of blocking in a retry loop.
+    NO_RETRY_CODES = %w[daily_quota_exceeded warmup_limit_exceeded monthly_quota_exceeded].freeze
+    # A Retry-After longer than this (seconds) means "not soon": raise instead
+    # of sleeping through it.
+    MAX_RETRY_WAIT = 60
 
     # @param api_key [String, nil] your API key (falls back to QUOLLE_API_KEY)
     # @param base_url [String]
@@ -41,6 +55,8 @@ module Quolle
       @max_retries = max_retries
       @emails = Resources::Emails.new(self)
       @webhooks = Resources::Webhooks.new(self)
+      @domains = Resources::Domains.new(self)
+      @api_keys = Resources::ApiKeys.new(self)
     end
 
     # Perform an authenticated request and return the parsed JSON body.
@@ -62,6 +78,7 @@ module Quolle
       klass = {
         "GET" => Net::HTTP::Get,
         "POST" => Net::HTTP::Post,
+        "PATCH" => Net::HTTP::Patch,
         "DELETE" => Net::HTTP::Delete
       }.fetch(method.upcase)
 
@@ -89,18 +106,38 @@ module Quolle
           raise last_error
         end
 
-        parsed = resp.body.to_s.empty? ? {} : (JSON.parse(resp.body) rescue {})
         status = resp.code.to_i
+        json_ok = true
+        parsed =
+          if resp.body.to_s.empty?
+            {}
+          else
+            begin
+              JSON.parse(resp.body)
+            rescue JSON::ParserError
+              json_ok = false
+              {}
+            end
+          end
 
         if (200..299).cover?(status)
+          # A 2xx that isn't JSON (a proxy page, a truncated body) is an error,
+          # not an empty success.
+          unless json_ok
+            raise Quolle::Error.new("Unexpected non-JSON response from the Quolle API",
+                                    status_code: status, data: { "body" => resp.body.to_s[0, 500] })
+          end
           return parsed
         end
 
         message = parsed.delete("error") || "Request failed with status #{status}"
-        last_error = Quolle::Error.new(message, status_code: status, data: parsed)
-        retryable = status == 429 || ((500..504).cover?(status) && (idempotent || has_idem))
-        if attempt < @max_retries && retryable
-          sleep(backoff(attempt, resp["Retry-After"]))
+        code = parsed.delete("code")
+        last_error = Quolle::Error.new(message, status_code: status, data: parsed, code: code)
+        retryable = (status == 429 && !NO_RETRY_CODES.include?(code)) ||
+                    ((500..504).cover?(status) && (idempotent || has_idem))
+        wait = backoff(attempt, resp["Retry-After"])
+        if attempt < @max_retries && retryable && wait <= MAX_RETRY_WAIT
+          sleep(wait)
           next
         end
         raise last_error

data/lib/quolle/error.rb

@@ -8,11 +8,16 @@ module Quolle
     attr_reader :status_code
     # @return [Hash] extra fields returned alongside +error+.
     attr_reader :data
+    # @return [String, nil] the API's stable, machine-readable error code
+    #   (e.g. "validation_error", "rate_limit_exceeded"). Branch on this, not
+    #   on the message. nil for transport failures.
+    attr_reader :code
 
-    def initialize(message, status_code: nil, data: {})
+    def initialize(message, status_code: nil, data: {}, code: nil)
       super(message)
       @status_code = status_code
       @data = data || {}
+      @code = code
     end
   end
 end

data/lib/quolle/resources/api_keys.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "path"
+
+module Quolle
+  module Resources
+    # API keys (+client.api_keys+). Needs a full-access key; a sending-only key
+    # gets 403 +restricted_api_key+.
+    class ApiKeys
+      def initialize(client)
+        @client = client
+      end
+
+      # @return [Array<Hash>] active keys (only a +preview+ of each key)
+      def list
+        @client.request("GET", "/v1/keys")["keys"] || []
+      end
+
+      # Create a key. The returned +key+ (qle_…) is shown once; store it now.
+      #
+      # @param scope ["full", "sending", nil] "sending" keys can only send email and read its status
+      # @param domains [Array<String>, nil] limit the key to these sending domains
+      # @param expires_in_days [Integer, nil] days until the key stops working
+      def create(name:, scope: nil, domains: nil, expires_in_days: nil)
+        body = { name: name }
+        body[:scope] = scope if scope
+        body[:domains] = domains if domains
+        body[:expiresInDays] = expires_in_days if expires_in_days
+        @client.request("POST", "/v1/keys", body: body)
+      end
+
+      # Revoke a key. Requests made with it fail from now on.
+      def remove(id)
+        @client.request("DELETE", "/v1/keys/#{Path.escape(id)}")
+      end
+    end
+  end
+end

data/lib/quolle/resources/domains.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "path"
+
+module Quolle
+  module Resources
+    # Sending domains (+client.domains+). Needs a full-access API key.
+    class Domains
+      def initialize(client)
+        @client = client
+      end
+
+      # @return [Array<Hash>] every sending domain, with verification and warm-up state
+      def list
+        @client.request("GET", "/v1/domains")["domains"] || []
+      end
+
+      # Add a domain (e.g. "mail.example.com").
+      # @return [Hash] +domain+ and the +dnsRecords+ to publish
+      def create(domain)
+        @client.request("POST", "/v1/domains", body: { domain: domain })
+      end
+
+      # @return [Hash] one domain
+      def get(id)
+        @client.request("GET", "/v1/domains/#{Path.escape(id)}")["domain"]
+      end
+
+      # @return [Hash] the DNS records to publish, and which are found
+      def records(id)
+        @client.request("GET", "/v1/domains/#{Path.escape(id)}/records")
+      end
+
+      # Check DNS again now instead of waiting for the next automatic check.
+      def verify(id)
+        @client.request("POST", "/v1/domains/#{Path.escape(id)}/recheck")
+      end
+
+      # Remove a domain. Mail can no longer be sent from it.
+      def remove(id)
+        @client.request("DELETE", "/v1/domains/#{Path.escape(id)}")
+      end
+    end
+  end
+end

data/lib/quolle/resources/emails.rb

@@ -12,15 +12,26 @@ module Quolle
       #
       # Provide either +:html+ (with +:subject+) or a +:template+ slug (with
       # optional +:variables+). Pass +idempotency_key:+ to make retries safe.
+      # +type:+ (or +message_type:+) is "transactional" (default) or
+      # "marketing"; marketing mail gets unsubscribe headers and honours
+      # unsubscribes.
       #
       # @param params [Hash] from:, to:, subject:, html:, text:, template:,
-      #   variables:, reply_to:/replyTo:, scheduled_at:/scheduledAt:, metadata:
+      #   variables:, reply_to:/replyTo:, scheduled_at:/scheduledAt:, metadata:,
+      #   attachments:, type:
       # @return [Hash] at least "id" and "message"
-      def send(idempotency_key: nil, **params)
+      def create(idempotency_key: nil, **params)
         headers = idempotency_key ? { "Idempotency-Key" => idempotency_key } : {}
         @client.request("POST", "/v1/emails/send", body: normalize(params), headers: headers)
       end
 
+      # Same as {#create}. Kept because it's the documented name; note that it
+      # shadows Object#send on this object, so prefer +create+ in new code
+      # (and +public_send+ / +__send__+ for dynamic dispatch).
+      def send(idempotency_key: nil, **params)
+        create(idempotency_key: idempotency_key, **params)
+      end
+
       # Send up to 100 emails in one all-or-nothing request.
       #
       # @param emails [Array<Hash>]
@@ -54,14 +65,16 @@ module Quolle
           k = key.to_s
           k = "replyTo" if k == "reply_to"
           k = "scheduledAt" if k == "scheduled_at"
+          k = "type" if k == "message_type"
           out[k] = value
         end
         out
       end
 
+      # Path-segment encoding. (encode_www_form_component turned a space into
+      # "+", which is a literal plus in a URL path.)
       def escape(id)
-        require "uri"
-        URI.encode_www_form_component(id.to_s)
+        id.to_s.b.gsub(/[^A-Za-z0-9\-._~]/) { |ch| format("%%%02X", ch.ord) }
       end
     end
   end

data/lib/quolle/resources/path.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Quolle
+  module Resources
+    # Path-segment encoding shared by the resources.
+    module Path
+      module_function
+
+      def escape(id)
+        id.to_s.b.gsub(/[^A-Za-z0-9\-._~]/) { |ch| format("%%%02X", ch.ord) }
+      end
+    end
+  end
+end

data/lib/quolle/resources/webhooks.rb

@@ -2,14 +2,73 @@
 
 require "openssl"
 require "json"
+require "uri"
+require_relative "path"
 
 module Quolle
   module Resources
-    # Verify that an incoming webhook really came from Quolle.
+    # Verify incoming webhooks, and manage webhook endpoints (+client.webhooks+).
+    # +verify+ makes no API call; the management methods need a full-access key.
     class Webhooks
       DEFAULT_TOLERANCE = 300 # seconds
 
-      def initialize(_client = nil); end
+      def initialize(client = nil)
+        @client = client
+      end
+
+      # @return [Array<Hash>] the events a webhook can subscribe to
+      def events
+        req("GET", "/v1/webhooks/events")["events"] || []
+      end
+
+      # @return [Array<Hash>]
+      def list
+        req("GET", "/v1/webhooks")["webhooks"] || []
+      end
+
+      # Add an endpoint. The returned +secret+ (whsec_…) is shown once; store it.
+      def create(url:, events:)
+        req("POST", "/v1/webhooks", { url: url, events: events })
+      end
+
+      def get(id)
+        req("GET", "/v1/webhooks/#{Path.escape(id)}")
+      end
+
+      # Change the URL or events. The signing secret stays the same.
+      def update(id, url: nil, events: nil)
+        body = {}
+        body[:url] = url if url
+        body[:events] = events if events
+        req("PATCH", "/v1/webhooks/#{Path.escape(id)}", body)
+      end
+
+      def remove(id)
+        req("DELETE", "/v1/webhooks/#{Path.escape(id)}")
+      end
+
+      # Send a signed +webhook.test+ event now and report how the endpoint answered.
+      def test(id)
+        req("POST", "/v1/webhooks/#{Path.escape(id)}/test")
+      end
+
+      # Deliveries from the last 30 days, newest first.
+      # @param status ["succeeded", "pending", "failed", nil]
+      def deliveries(id, status: nil, limit: nil)
+        params = { status: status, limit: limit }.compact
+        qs = params.empty? ? "" : "?#{URI.encode_www_form(params)}"
+        req("GET", "/v1/webhooks/#{Path.escape(id)}/deliveries#{qs}")["deliveries"] || []
+      end
+
+      # Send a delivery again, with the same body and +eventId+.
+      def redeliver(id, delivery_id)
+        req("POST", "/v1/webhooks/#{Path.escape(id)}/deliveries/#{Path.escape(delivery_id)}/redeliver")
+      end
+
+      # Replace the signing secret. Takes effect immediately; the new +secret+ is returned once.
+      def rotate_secret(id)
+        req("POST", "/v1/webhooks/#{Path.escape(id)}/rotate-secret")
+      end
 
       # Verify a webhook signature and return the parsed event.
       #
@@ -52,6 +111,12 @@ module Quolle
         b.each_byte { |byte| res |= byte ^ l.shift }
         res.zero?
       end
+
+      def req(method, path, body = nil)
+        raise Quolle::Error.new("Webhooks was created without a client; use client.webhooks") unless @client
+
+        body ? @client.request(method, path, body: body) : @client.request(method, path)
+      end
     end
   end
 end

data/lib/quolle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quolle
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: quolle
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Quolle
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-25 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -39,7 +38,6 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 description: Send transactional email through Quolle from Ruby.
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -49,7 +47,10 @@ files:
 - lib/quolle.rb
 - lib/quolle/client.rb
 - lib/quolle/error.rb
+- lib/quolle/resources/api_keys.rb
+- lib/quolle/resources/domains.rb
 - lib/quolle/resources/emails.rb
+- lib/quolle/resources/path.rb
 - lib/quolle/resources/webhooks.rb
 - lib/quolle/version.rb
 homepage: https://quolle.com
@@ -59,7 +60,6 @@ metadata:
   homepage_uri: https://quolle.com
   documentation_uri: https://docs.quolle.com
   source_code_uri: https://github.com/Quolle-main/quolle-ruby
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -67,15 +67,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Official Ruby SDK for the Quolle email API
 test_files: []