quolle 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37768ae3c543a6ebc5a59a65f4c208d1c2c1ccbb7fdb5f47eec6e01fe17ab9a4
-  data.tar.gz: 289978e8755370fa7a339248c16ffdcd098b8ff4b5a7e3355f0e6312853ac1d0
+  metadata.gz: a0658c46b0cbf87fde8e453e3c79da2444565b8a97360807ae24d7865125e57b
+  data.tar.gz: ca10637ae139bfe029c0b98608e0b3edde03a0f0f3b9a54cbd75ba2c7201a6a4
 SHA512:
-  metadata.gz: c2ab703c9aad2e30a20b45fca63657833b571a915681669222c61589bc928492b54517ee1e1758e71b565e4a54b426215f7a488be045be4f911581d34bed163e
-  data.tar.gz: b2b5282fe08b21d98e4906416e7d4a4a17bb0a3f938f2566dab9427667c734d1c439a3097f90d65908ca5d7c81a98e2278b1a12794c0b4e7f1e4df779a4e937a
+  metadata.gz: 46130d471c82ef7e8e1fc6f4a940d8a6a8937f039309d4fb75e45422923c7be48edc61953ba6fba44aa0a8d00db4b427747d0f4c43fa2a5e93b092606e1f4ad9
+  data.tar.gz: ee558f680e6311a1eb05b56a611ca493c0bd24cbe57828ae1119e11b51dbb30b6bd9c4bc1dbffb8e613ed7cc66a5bb0f69ca71a55e61201695e321058c68e332

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
@@ -167,7 +173,7 @@ HMAC-SHA256 with a 5-minute timestamp window (replay protection).
 
 ## 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

@@ -28,6 +28,14 @@ module Quolle
     # @return [Quolle::Resources::Webhooks]
     attr_reader :webhooks
 
+    # 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]
     # @param timeout [Integer] per-request timeout in seconds
@@ -89,18 +97,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/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/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: quolle
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.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: []
@@ -59,7 +57,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 +64,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: []