quolle 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37768ae3c543a6ebc5a59a65f4c208d1c2c1ccbb7fdb5f47eec6e01fe17ab9a4
+  data.tar.gz: 289978e8755370fa7a339248c16ffdcd098b8ff4b5a7e3355f0e6312853ac1d0
+SHA512:
+  metadata.gz: c2ab703c9aad2e30a20b45fca63657833b571a915681669222c61589bc928492b54517ee1e1758e71b565e4a54b426215f7a488be045be4f911581d34bed163e
+  data.tar.gz: b2b5282fe08b21d98e4906416e7d4a4a17bb0a3f938f2566dab9427667c734d1c439a3097f90d65908ca5d7c81a98e2278b1a12794c0b4e7f1e4df779a4e937a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quolle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# Quolle Ruby SDK
+
+Official Ruby client for the [Quolle](https://quolle.com) email API.
+
+## Install
+
+```bash
+gem install quolle
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "quolle"
+```
+
+Requires Ruby 2.7+. No third-party dependencies.
+
+## Quick start
+
+```ruby
+require "quolle"
+
+quolle = Quolle.new(api_key: "qle_...") # or set QUOLLE_API_KEY
+
+result = quolle.emails.send(
+  from: "hello@mail.yourdomain.com",
+  to: "customer@example.com",
+  subject: "Welcome!",
+  html: "<h1>Thanks for signing up</h1>"
+)
+
+puts "Queued: #{result['id']}"
+```
+
+## Sending
+
+### Multiple recipients
+
+```ruby
+quolle.emails.send(
+  from: "hello@mail.yourdomain.com",
+  to: ["a@example.com", "b@example.com"],
+  subject: "Announcement",
+  html: "<p>Hello everyone</p>"
+)
+```
+
+### Templates
+
+```ruby
+quolle.emails.send(
+  from: "hello@mail.yourdomain.com",
+  to: "customer@example.com",
+  template: "welcome-email",
+  variables: { firstName: "Amaka", planName: "Starter" }
+)
+```
+
+### Scheduled send
+
+```ruby
+quolle.emails.send(
+  from: "hello@mail.yourdomain.com",
+  to: "customer@example.com",
+  subject: "Your weekly digest",
+  html: "<p>Here's what happened this week.</p>",
+  scheduled_at: "2026-12-25T09:00:00.000Z"
+)
+```
+
+### Idempotency
+
+```ruby
+quolle.emails.send(
+  from: "billing@mail.yourdomain.com",
+  to: "customer@example.com",
+  subject: "Invoice #1234",
+  html: "<p>Your invoice is attached.</p>",
+  idempotency_key: "order_invoice_12345"
+)
+```
+
+### Batch
+
+Up to 100 emails in one all-or-nothing request:
+
+```ruby
+result = quolle.emails.send_batch([
+  { from: "hello@mail.yourdomain.com", to: "a@example.com", subject: "Hi Alice", html: "<p>Hi Alice</p>" },
+  { from: "hello@mail.yourdomain.com", to: "b@example.com", subject: "Hi Bob", html: "<p>Hi Bob</p>" }
+])
+puts "Queued #{result['queued']}"
+```
+
+### Attachments
+
+Pass `attachments:` — an array of hashes with `filename`, base64 `content`, and an
+optional `contentType`. Up to 20 files, 10 MB total.
+
+```ruby
+require "base64"
+
+quolle.emails.send(
+  from: "billing@mail.yourdomain.com",
+  to: "customer@example.com",
+  subject: "Your invoice",
+  html: "<p>Invoice attached.</p>",
+  attachments: [
+    {
+      filename: "invoice.pdf",
+      content: Base64.strict_encode64(File.binread("invoice.pdf")),
+      contentType: "application/pdf"
+    }
+  ]
+)
+```
+
+## Retrieve & cancel
+
+```ruby
+email = quolle.emails.get("a1b2c3d4-...")
+puts email["status"] # queued | sending | sent | delivered | bounced | failed
+
+quolle.emails.cancel("a1b2c3d4-...") # only while status == "scheduled"
+```
+
+## Error handling
+
+```ruby
+begin
+  quolle.emails.send(
+    from: "hello@mail.yourdomain.com", to: "customer@example.com",
+    subject: "Welcome!", html: "<h1>Welcome</h1>"
+  )
+rescue Quolle::Error => e
+  puts e.status_code # e.g. 402
+  puts e.message     # e.g. "Monthly limit reached"
+  puts e.data        # extra fields, e.g. {"limit" => 3000}
+end
+```
+
+## Testing your integration
+
+Send to a reserved test address to simulate any outcome without touching your
+sending reputation: `delivered@test.quolle.com`, `bounced@test.quolle.com`,
+`complained@test.quolle.com`, `suppressed@test.quolle.com`.
+
+## Verifying webhooks
+
+Confirm an incoming webhook really came from Quolle. Pass the **raw** request body, the `Quolle-Signature` header, and your signing secret (`whsec_…`):
+
+```ruby
+begin
+  event = quolle.webhooks.verify(
+    request.body.read,                  # raw body
+    request.env["HTTP_QUOLLE_SIGNATURE"],
+    "whsec_your_signing_secret"
+  )
+  # event["event"] == "email.delivered"
+rescue Quolle::Error
+  halt 400
+end
+```
+
+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).
+
+## License
+
+MIT

data/lib/quolle/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "version"
+require_relative "error"
+require_relative "resources/emails"
+require_relative "resources/webhooks"
+
+module Quolle
+  # The Quolle API client.
+  #
+  #   quolle = Quolle::Client.new(api_key: "qle_...")
+  #   result = quolle.emails.send(
+  #     from: "hello@mail.yourdomain.com",
+  #     to: "customer@example.com",
+  #     subject: "Welcome!",
+  #     html: "<h1>Thanks for signing up</h1>"
+  #   )
+  #   puts result["id"]
+  class Client
+    DEFAULT_BASE_URL = "https://api.quolle.com"
+
+    # @return [Quolle::Resources::Emails]
+    attr_reader :emails
+    # @return [Quolle::Resources::Webhooks]
+    attr_reader :webhooks
+
+    # @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
+    # @param max_retries [Integer] retries for transient failures (default 3)
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, timeout: 30, max_retries: 3)
+      @api_key = api_key || ENV["QUOLLE_API_KEY"]
+      raise ArgumentError, "A Quolle API key is required (pass api_key: or set QUOLLE_API_KEY)" if @api_key.nil? || @api_key.empty?
+
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = max_retries
+      @emails = Resources::Emails.new(self)
+      @webhooks = Resources::Webhooks.new(self)
+    end
+
+    # Perform an authenticated request and return the parsed JSON body.
+    #
+    # Transient failures (HTTP 429 and 5xx, plus network errors) are retried with
+    # exponential backoff, honoring Retry-After on 429. To avoid double-sending, a
+    # POST is only retried on a 5xx/network error when an Idempotency-Key is
+    # present; a 429 (never processed) is always safe to retry.
+    #
+    # @raise [Quolle::Error] on a non-2xx response or transport failure after retries
+    # @return [Hash]
+    def request(method, path, body: nil, headers: {})
+      uri = URI.parse("#{@base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      klass = {
+        "GET" => Net::HTTP::Get,
+        "POST" => Net::HTTP::Post,
+        "DELETE" => Net::HTTP::Delete
+      }.fetch(method.upcase)
+
+      idempotent = %w[GET DELETE].include?(method.upcase)
+      has_idem = headers.keys.any? { |k| k.to_s.downcase == "idempotency-key" }
+
+      last_error = nil
+      (0..@max_retries).each do |attempt|
+        req = klass.new(uri.request_uri)
+        req["Authorization"] = "Bearer #{@api_key}"
+        req["Content-Type"] = "application/json"
+        req["Accept"] = "application/json"
+        req["User-Agent"] = "quolle-ruby/#{Quolle::VERSION}"
+        headers.each { |k, v| req[k] = v }
+        req.body = JSON.generate(body) unless body.nil?
+
+        begin
+          resp = http.request(req)
+        rescue StandardError => e
+          last_error = Quolle::Error.new("Network error: #{e.message}")
+          if attempt < @max_retries && (idempotent || has_idem)
+            sleep(backoff(attempt, nil))
+            next
+          end
+          raise last_error
+        end
+
+        parsed = resp.body.to_s.empty? ? {} : (JSON.parse(resp.body) rescue {})
+        status = resp.code.to_i
+
+        if (200..299).cover?(status)
+          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"]))
+          next
+        end
+        raise last_error
+      end
+
+      raise(last_error || Quolle::Error.new("Request failed"))
+    end
+
+    private
+
+    # Seconds to wait before the next retry: Retry-After if given, else
+    # exponential backoff (0.5, 1, 2, …) capped at 8s, with jitter.
+    def backoff(attempt, retry_after)
+      if retry_after && retry_after.to_s =~ /\A\d+\z/
+        return retry_after.to_i
+      end
+
+      [0.5 * (2**attempt), 8.0].min + rand * 0.25
+    end
+  end
+end

data/lib/quolle/error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Quolle
+  # Raised when the Quolle API returns a non-2xx response, or a request could
+  # not be completed (network/timeout).
+  class Error < StandardError
+    # @return [Integer, nil] HTTP status code, or nil for transport failures.
+    attr_reader :status_code
+    # @return [Hash] extra fields returned alongside +error+.
+    attr_reader :data
+
+    def initialize(message, status_code: nil, data: {})
+      super(message)
+      @status_code = status_code
+      @data = data || {}
+    end
+  end
+end

data/lib/quolle/resources/emails.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Quolle
+  module Resources
+    # Send and manage emails.
+    class Emails
+      def initialize(client)
+        @client = client
+      end
+
+      # Queue an email for immediate or scheduled delivery.
+      #
+      # Provide either +:html+ (with +:subject+) or a +:template+ slug (with
+      # optional +:variables+). Pass +idempotency_key:+ to make retries safe.
+      #
+      # @param params [Hash] from:, to:, subject:, html:, text:, template:,
+      #   variables:, reply_to:/replyTo:, scheduled_at:/scheduledAt:, metadata:
+      # @return [Hash] at least "id" and "message"
+      def send(idempotency_key: nil, **params)
+        headers = idempotency_key ? { "Idempotency-Key" => idempotency_key } : {}
+        @client.request("POST", "/v1/emails/send", body: normalize(params), headers: headers)
+      end
+
+      # Send up to 100 emails in one all-or-nothing request.
+      #
+      # @param emails [Array<Hash>]
+      # @return [Hash] { "queued" => Integer, "ids" => Array<String> }
+      def send_batch(emails, idempotency_key: nil)
+        headers = idempotency_key ? { "Idempotency-Key" => idempotency_key } : {}
+        body = { emails: emails.map { |e| normalize(e) } }
+        @client.request("POST", "/v1/emails/batch", body: body, headers: headers)
+      end
+
+      # Retrieve a single email by ID.
+      # @return [Hash]
+      def get(id)
+        resp = @client.request("GET", "/v1/emails/#{escape(id)}")
+        resp["email"] || resp
+      end
+
+      # Cancel a scheduled email that has not yet been sent.
+      # @return [Hash]
+      def cancel(id)
+        @client.request("DELETE", "/v1/emails/#{escape(id)}/cancel")
+      end
+
+      private
+
+      # Accept Ruby-idiomatic snake_case keys and map them to the API's
+      # camelCase where they differ. Existing camelCase keys pass through.
+      def normalize(params)
+        out = {}
+        params.each do |key, value|
+          k = key.to_s
+          k = "replyTo" if k == "reply_to"
+          k = "scheduledAt" if k == "scheduled_at"
+          out[k] = value
+        end
+        out
+      end
+
+      def escape(id)
+        require "uri"
+        URI.encode_www_form_component(id.to_s)
+      end
+    end
+  end
+end

data/lib/quolle/resources/webhooks.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module Quolle
+  module Resources
+    # Verify that an incoming webhook really came from Quolle.
+    class Webhooks
+      DEFAULT_TOLERANCE = 300 # seconds
+
+      def initialize(_client = nil); end
+
+      # Verify a webhook signature and return the parsed event.
+      #
+      # @param payload [String] the RAW request body
+      # @param signature_header [String] the value of the +Quolle-Signature+ header
+      # @param secret [String] your webhook signing secret (whsec_…)
+      # @param tolerance [Integer] max timestamp age in seconds (replay window)
+      # @raise [Quolle::Error] on a malformed header, stale timestamp, or bad signature
+      # @return [Hash] the parsed event
+      def verify(payload, signature_header, secret, tolerance: DEFAULT_TOLERANCE)
+        parts = signature_header.to_s.split(",").each_with_object({}) do |seg, acc|
+          k, v = seg.strip.split("=", 2)
+          acc[k] = v if k && v
+        end
+        t = parts["t"]
+        v1 = parts["v1"]
+        raise Quolle::Error.new("Invalid Quolle-Signature header") if t.nil? || v1.nil? || t.empty? || v1.empty?
+
+        ts = t.to_i
+        if (Time.now.to_i - ts).abs > tolerance
+          raise Quolle::Error.new("Webhook timestamp outside the tolerance window (possible replay)")
+        end
+
+        expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{ts}.#{payload}")
+        unless secure_compare(expected, v1)
+          raise Quolle::Error.new("Webhook signature verification failed")
+        end
+
+        JSON.parse(payload)
+      end
+
+      private
+
+      # Constant-time string comparison (no timing side channel).
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        l = a.unpack("C*")
+        res = 0
+        b.each_byte { |byte| res |= byte ^ l.shift }
+        res.zero?
+      end
+    end
+  end
+end

data/lib/quolle/version.rb

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

data/lib/quolle.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "quolle/version"
+require_relative "quolle/error"
+require_relative "quolle/client"
+
+# Official Ruby SDK for the Quolle email API.
+module Quolle
+  # Convenience constructor: Quolle.new(api_key: "qle_...")
+  def self.new(**kwargs)
+    Client.new(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: quolle
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Quolle
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Send transactional email through Quolle from Ruby.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/quolle.rb
+- lib/quolle/client.rb
+- lib/quolle/error.rb
+- lib/quolle/resources/emails.rb
+- lib/quolle/resources/webhooks.rb
+- lib/quolle/version.rb
+homepage: https://quolle.com
+licenses:
+- MIT
+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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Quolle email API
+test_files: []