quolle 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0658c46b0cbf87fde8e453e3c79da2444565b8a97360807ae24d7865125e57b
-  data.tar.gz: ca10637ae139bfe029c0b98608e0b3edde03a0f0f3b9a54cbd75ba2c7201a6a4
+  metadata.gz: d49a558cd0e8d55d4a043225faf03055ab2d71b645b0d1fb9480acb5931addc0
+  data.tar.gz: 57eaff3fe141479fe6f99e5a84dc226957efb2dc3145f65f0666e9e9b5c8d556
 SHA512:
-  metadata.gz: 46130d471c82ef7e8e1fc6f4a940d8a6a8937f039309d4fb75e45422923c7be48edc61953ba6fba44aa0a8d00db4b427747d0f4c43fa2a5e93b092606e1f4ad9
-  data.tar.gz: ee558f680e6311a1eb05b56a611ca493c0bd24cbe57828ae1119e11b51dbb30b6bd9c4bc1dbffb8e613ed7cc66a5bb0f69ca71a55e61201695e321058c68e332
+  metadata.gz: aa4abf51a8b949560722c0fb9e7f4ad55653a6a16fac85f56c7a427ab0fe34ce0a52bad869c48274c76b959287734f48aef984a7134727854e931b9e8f4c1f5f
+  data.tar.gz: f04d7e24d159145ef67a7dbcc5c4675637d562dcd62f7eb509428837b1715e5ec735d3f5673d01bed8a531e80fa26310c07895488e75d37c328591da5570d457

data/README.md

@@ -171,6 +171,29 @@ 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). 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).

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,10 @@ 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
@@ -49,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.
@@ -70,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)
 

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/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.1.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quolle
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Quolle
@@ -47,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