duva-mail 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e827ccf2e586d4395a447ea3c9d7056b1f260434d3d5db34c7332499f1ab583f
-  data.tar.gz: 8ea23bf187bb8aee8e200268b99742c7ab26771c417114e2d64f39da1367f58d
+  metadata.gz: b62be0aef438ad137fa4db07aae85263042d924b2db6c50d70347301f62f2737
+  data.tar.gz: 231d12564797d902d3398972da4809b2e3c8b1488f9a6e7750efa2ad15bca89a
 SHA512:
-  metadata.gz: 62d73492bde77e29ccdc73f184fc99c6d490690c2bf4f7dce36ea65e5c1a856c74dab6314991fbf42723eb01ce26f58972366405ddab4fb5bad2d3df6a183cb6
-  data.tar.gz: 8c10eaa315d432fb61d9521bae50e070625a2d9747f74b038b7e8ef7386a3d67e49d1a8e9ad6986903b40903d46ba82fa1a42e6e3bc5f6951a8e38e42edb7924
+  metadata.gz: 4133719861683e4084116674223885e0e1a3cf1eede3352725f6e492e5ec9c29665806a82fa552a0096cb775e6d4018961551b132061125f947db14f7adb381f
+  data.tar.gz: dac5abbdcf145b0f4d25258d69c478bf083adfee8e19f2f9bf8549bd6630420599cfb29cc1b5ab8b40136461c9b4ddb30e83f212f4b8a29640bd1b2a5298c97b

data/README.md

@@ -1,15 +1,144 @@
 # Duva for Ruby
 
-The official [Duva](https://duva.ca) client library for Ruby. **Not released yet: this package name is reserved.**
+The official [Duva](https://duva.ca) client library for Ruby. Duva is a transactional email API
+hosted in Canada.
 
-Duva is a transactional email API hosted in Canada. In the meantime, the HTTP API is documented at
-<https://duva.ca/en/docs> and described by an OpenAPI 3.1 specification at <https://duva.ca/openapi.json>.
+```bash
+gem install duva-mail
+# or, in a Gemfile: gem "duva-mail"
+```
 
----
+Requires Ruby 3.3 or later. No runtime dependency beyond `base64` (bundled with Ruby; declared
+explicitly since it left Ruby's default gems in 3.4).
 
-# Duva pour Ruby
+## Sending a message
 
-La bibliothèque cliente officielle de [Duva](https://duva.ca) pour Ruby. **Pas encore publiée : ce nom de paquet est réservé.**
+```ruby
+require "duva"
 
-Duva est une API de courriels transactionnels hébergée au Canada. En attendant, l'API HTTP est documentée sur
-<https://duva.ca/docs> et décrite par une spécification OpenAPI 3.1 sur <https://duva.ca/openapi.json>.
+duva = Duva::Client.new(api_key: "dv_...", domain: "example.com") # or DUVA_API_KEY / DUVA_DOMAIN
+
+message = duva.messages.deliver(
+  from: "Example <notifications@example.com>",
+  to: ["client@example.org"],
+  subject: "Your order",
+  text: "Thank you for your order."
+)
+puts message.id, message.status # "queued": always asynchronous
+```
+
+Named `deliver`, not `send`: `Object#send` is a core Ruby method and shadowing it would be
+confusing in a `rescue`/`method_missing`-heavy codebase.
+
+## Reading events and pagination
+
+```ruby
+duva.events.list_all(type: "bounced").each { |event| puts event.type, event.detail["recipient"] }
+```
+
+`events.list` and `suppressions.list` return one page (`.data`, `.next_cursor`); `events.list_all`
+and `suppressions.list_all` return a lazy `Enumerator` that follows `next_cursor` for you, without
+ever loading every page into memory, optionally bounded with `max_items:`.
+
+## Verifying a webhook
+
+```ruby
+begin
+  event = Duva::Webhooks.construct_event(ENV.fetch("DUVA_WEBHOOK_SECRET"), request.headers, raw_body)
+  puts event.type, event.data["message_id"]
+rescue Duva::WebhookSignatureError
+  # respond 400
+end
+```
+
+`raw_body` must be the **exact bytes** Duva sent (`request.raw_post` in Rails, `request.body.read`
+in Sinatra/Rack): re-encoding a parsed body changes it and invalidates the signature. Rotating
+your webhook secret? Pass an array — `Duva::Webhooks.construct_event([old_secret, new_secret], ...)`
+— while both are active.
+
+## Errors
+
+Every error Duva answers with is a `Duva::Error` subclass; rely on `.code` (the contract), never on
+the exception message (its wording can change):
+
+```ruby
+begin
+  duva.messages.deliver(...)
+rescue Duva::ValidationError => e
+  p e.fields # [{"field" => "to[0]", "message" => "..."}]
+rescue Duva::QuotaExceededError => e
+  puts "retry in #{e.retry_after}s"
+rescue Duva::NotFoundError
+  # the API key, domain or resource could not be found
+end
+```
+
+Network failures and timeouts raise `Duva::ConnectionError` / `Duva::TimeoutError` instead (no
+HTTP response was ever received). Reads and `messages.deliver` (idempotency-key protected) are
+retried automatically on a transient failure; `suppressions.add`/`remove` and
+`webhooks.create`/`delete` are not, because the outcome of a timed-out first attempt is unknown. A
+`429 quota_exceeded` is never retried automatically (its `retry_after` can be hours); a
+`429 rate_limited` is, as long as the wait fits within `max_retry_wait_seconds` (30s by default).
+
+## Attachments
+
+```ruby
+attachment = Duva::Attachments.from_file("./invoice.pdf")
+duva.messages.deliver(..., attachments: [attachment])
+```
+
+`Duva::Attachments.from_bytes(filename, content, content_type:, content_id:)` works from data
+already in memory; `content_id:` turns the attachment into an inline image the HTML references
+with `cid:`.
+
+## Testing your own application
+
+```ruby
+transport = Duva::TestTransport.new do |_config, spec|
+  Duva::TestTransport.response({ "status" => "ok" })
+end
+duva = Duva::Client.new(api_key: "dv_test", domain: "example.com", transport: transport)
+duva.health
+transport.requests.last.path # => "/health"
+```
+
+`Duva::TestTransport` records every `RequestSpec` sent and lets you script the responses: no
+network call, no stubbing library required.
+
+## Configuration
+
+| Argument | Default | |
+|---|---|---|
+| `api_key:` | `DUVA_API_KEY` | Required. |
+| `domain:` | `DUVA_DOMAIN` | Required: the domain this key was created for. |
+| `base_url:` | `https://api.duva.ca` | |
+| `timeout:` | `10` (seconds) | |
+| `max_retries:` | `2` | Network failures / `5xx` on a safe-to-retry call. |
+| `max_retry_wait_seconds:` | `30` | A `429 rate_limited` with a longer wait is not retried. |
+| `language:` | unset | `"en"` or `"fr"`: the language of `error.message`. |
+| `transport:` | a new `Duva::NetHttpTransport` (`Net::HTTP`, no gem dependency) | Inject your own (proxying, Faraday, tests). |
+
+## Full reference
+
+The complete API surface and the OpenAPI specification this library follows:
+<https://duva.ca/en/docs> and <https://duva.ca/openapi.json>.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec                                  # unit tests
+ruby script/fetch_conformance.rb && bundle exec rake conformance
+bundle exec rake rubocop
+gem build duva-mail.gemspec
+```
+
+Response types are hand-written value objects (`lib/duva/models.rb`, `Data.define`): Ruby's typing
+is optional (RBS/Sorbet are left to the application), so there is no separate code-generation step
+for them, unlike the Node.js and Python libraries. The client itself (retries, pagination, errors,
+webhooks) is checked against the shared fixtures published in
+[`duva-mail/duva-conformance`](https://github.com/duva-mail/duva-conformance).
+
+## License
+
+MIT, see [LICENSE](./LICENSE).

data/duva-mail.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "lib/duva"
+
+Gem::Specification.new do |spec|
+  spec.name = "duva-mail"
+  spec.version = Duva::VERSION
+  spec.summary = "Official Duva client library (transactional email API hosted in Canada)."
+  spec.description = "Official client library for Duva, a transactional email API hosted in Canada: " \
+                     "sending, delivery events, suppressions, webhooks and statistics."
+  spec.authors = ["9573-4562 Québec inc."]
+  spec.license = "MIT"
+  spec.homepage = "https://duva.ca"
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/duva-mail/duva-ruby",
+    "documentation_uri" => "https://duva.ca/en/docs",
+    "changelog_uri" => "https://duva.ca/en/docs#changelog",
+    "rubygems_mfa_required" => "true"
+  }
+  spec.required_ruby_version = ">= 3.3"
+  spec.files = Dir.glob("lib/**/*.rb") + ["README.md", "LICENSE", "duva-mail.gemspec"]
+  spec.require_paths = ["lib"]
+  # `base64` left Ruby's default gems in 3.4 (a bare `require` then warns, and would eventually
+  # break): declared explicitly so it installs regardless of the running Ruby's bundled set.
+  # Everything else used (json, net/http, openssl, securerandom, time, uri) remains a Ruby
+  # default gem; no other dependency, matching `docs/bibliotheques-clientes.md` section 4.
+  spec.add_dependency "base64", "~> 0.2"
+end

data/lib/duva/address.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Duva
+  # Small formatting helpers matched to the API's own parsing rules (`docs/api.md`).
+  module Address
+    NEEDS_QUOTING = /[",]/
+    private_constant :NEEDS_QUOTING
+
+    class << self
+      # `"Name <address>"` (with `Name` quoted if it contains a `"` or `,`), or just `address`
+      # without a name.
+      def format(email, name = nil)
+        return email if name.nil? || name.empty?
+
+        escaped = name.gsub('"', '\\"')
+        quoted = NEEDS_QUOTING.match?(name) ? "\"#{escaped}\"" : name
+        "#{quoted} <#{email}>"
+      end
+
+      # Builds `List-Unsubscribe` (and `List-Unsubscribe-Post` for one-click) exactly as the API
+      # validates them: at most 3 links, `https://` or `mailto:` only. Raises ArgumentError when
+      # neither `https_url:` nor `mailto:` is given.
+      #
+      # `one_click:` adds `List-Unsubscribe-Post` (RFC 8058). Defaults to `true` when
+      # `https_url:` is given, `false` otherwise.
+      def unsubscribe_headers(https_url: nil, mailto: nil, one_click: nil)
+        raise ArgumentError, "Duva: unsubscribe_headers needs https_url and/or mailto" if https_url.nil? && mailto.nil?
+        if https_url && !https_url.start_with?("https://")
+          raise ArgumentError,
+                "Duva: unsubscribe_headers.https_url must be an https:// link"
+        end
+
+        resolved_one_click = one_click.nil? ? !https_url.nil? : one_click
+
+        links = [https_url, mailto && "mailto:#{mailto}"].compact.map { |link| "<#{link}>" }
+        headers = { "List-Unsubscribe" => links.join(", ") }
+        if resolved_one_click
+          raise ArgumentError, "Duva: one-click unsubscribe (List-Unsubscribe-Post) needs https_url" unless https_url
+
+          headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click"
+        end
+        headers
+      end
+    end
+  end
+end

data/lib/duva/attachments.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Duva
+  # Attachment helpers. The server remains the authority on the limits below (they can change):
+  # these are a courtesy, so a mistake fails locally instead of after an upload.
+  Attachment = Data.define(:filename, :content, :content_type, :content_id) do
+    def to_h
+      { "filename" => filename, "content" => content, "content_type" => content_type, "content_id" => content_id }
+    end
+  end
+
+  module Attachments
+    # Mirrors `services/messages.py` in the `duva` repository at the time of writing: 10
+    # attachments, 5 MB decoded in total, these extensions refused. Re-check against
+    # `docs/api.md` if this drifts.
+    MAX_ATTACHMENTS = 10
+    MAX_TOTAL_BYTES = 5 * 1024 * 1024
+    FORBIDDEN_EXTENSIONS = %w[.exe .bat .cmd .com .js .vbs .vbe .scr .msi .msp .ps1 .jar].freeze
+
+    class << self
+      # From raw bytes already in memory.
+      def from_bytes(filename, content, content_type: nil, content_id: nil)
+        assert_allowed_filename(filename)
+        Attachment.new(filename: filename, content: Base64.strict_encode64(content),
+                       content_type: content_type, content_id: content_id)
+      end
+
+      # Reads a file from disk.
+      def from_file(path, content_type: nil, content_id: nil, filename: nil)
+        from_bytes(filename || File.basename(path), File.binread(path), content_type: content_type, content_id: content_id)
+      end
+
+      # Local, courtesy-only checks: at most MAX_ATTACHMENTS attachments, at most
+      # MAX_TOTAL_BYTES decoded in total. Raises ArgumentError when exceeded; the server
+      # re-checks regardless.
+      def assert_limits(attachments)
+        raise ArgumentError, "Duva: at most #{MAX_ATTACHMENTS} attachments per message" if attachments.size > MAX_ATTACHMENTS
+
+        total_bytes = attachments.sum { |a| decoded_length(a.content) }
+        return unless total_bytes > MAX_TOTAL_BYTES
+
+        raise ArgumentError, "Duva: attachments are #{total_bytes} bytes decoded, over the #{MAX_TOTAL_BYTES} limit"
+      end
+
+      private
+
+      def assert_allowed_filename(filename)
+        if filename.include?("/") || filename.include?("\\")
+          raise ArgumentError,
+                "Duva: attachment filename must not contain a path: #{filename}"
+        end
+
+        ext = File.extname(filename).downcase
+        raise ArgumentError, "Duva: executable attachments are refused: #{filename}" if FORBIDDEN_EXTENSIONS.include?(ext)
+      end
+
+      def decoded_length(base64)
+        padding = if base64.end_with?("==")
+                    2
+                  elsif base64.end_with?("=")
+                    1
+                  else
+                    0
+                  end
+        (base64.length * 3 / 4) - padding
+      end
+    end
+  end
+end

data/lib/duva/client.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Duva
+  # Decides whether a failed request may be retried, exactly per
+  # `docs/bibliotheques-clientes.md` section 3.5 in the `duva` repository.
+  #
+  # @api private
+  module RetryPolicy
+    module_function
+
+    # `nil` = do not retry (re-raise); a number = wait this many seconds, then retry.
+    def delay_for(error, spec, attempt, config)
+      if error.is_a?(RateLimitError)
+        return error.retry_after > config.max_retry_wait_seconds ? nil : error.retry_after.to_f
+      end
+      # A QuotaExceededError (has retry_after too) is never retried automatically; neither is
+      # any other DuvaError that isn't a ServerError (4xx: the outcome is already known).
+      return nil if error.is_a?(Error) && !error.is_a?(ServerError)
+
+      transient = error.is_a?(ConnectionError) || error.is_a?(TimeoutError) || error.is_a?(ServerError)
+      return nil unless transient && spec.safe_retry && attempt < config.max_retries
+
+      backoff(attempt)
+    end
+
+    # Exponential backoff with jitter, capped: never a fixed delay, never unbounded.
+    def backoff(attempt)
+      base = [0.5 * (2.0**attempt), 8.0].min
+      (base / 2) + (rand * (base / 2))
+    end
+  end
+  private_constant :RetryPolicy
+
+  # What `messages.deliver` returns: the accepted message plus the idempotency outcome.
+  SendMessageResult = Data.define(:id, :status, :replayed, :location)
+
+  # A synchronous Duva client, bound to one domain and its API key.
+  #
+  #   duva = Duva::Client.new(api_key: "dv_...", domain: "example.com")
+  #   message = duva.messages.deliver(
+  #     from: "Example <notifications@example.com>",
+  #     to: ["client@example.org"],
+  #     subject: "Your order",
+  #     text: "Thank you for your order.",
+  #   )
+  class Client
+    # @api private
+    attr_reader :config
+    attr_reader :messages, :events, :suppressions, :webhooks, :stats
+
+    def initialize(api_key: nil, domain: nil, base_url: Duva::DEFAULT_BASE_URL, timeout: 10, max_retries: 2,
+                   max_retry_wait_seconds: 30, language: nil, user_agent: nil, transport: nil)
+      @config = Config.resolve(api_key: api_key, domain: domain, base_url: base_url, timeout: timeout,
+                               max_retries: max_retries, max_retry_wait_seconds: max_retry_wait_seconds,
+                               language: language, user_agent: user_agent)
+      @transport = transport || NetHttpTransport.new
+      @messages = MessagesResource.new(self)
+      @events = EventsResource.new(self)
+      @suppressions = SuppressionsResource.new(self)
+      @webhooks = WebhooksResource.new(self)
+      @stats = StatsResource.new(self)
+    end
+
+    # `GET /health`, without authentication: `{"status" => "ok"}` when the service works. Raises
+    # ServerError on a `503` (its database is unreachable).
+    def health
+      request(RequestSpec.new(method: "GET", path: "/health", safe_retry: true)).data
+    end
+
+    # @api private
+    def request(spec)
+      attempt = 0
+      loop do
+        return @transport.call(@config, spec)
+      rescue Error, ConnectionError, TimeoutError => e
+        delay = RetryPolicy.delay_for(e, spec, attempt, @config)
+        raise e if delay.nil?
+
+        attempt += 1
+        sleep(delay)
+      end
+    end
+  end
+
+  # @api private
+  class MessagesResource
+    def initialize(client)
+      @client = client
+    end
+
+    # Accepts a message for delivery. Always asynchronous: `queued` never confirms a delivery,
+    # only that the message was validated. Read the outcome with `messages.get`, `events.list`,
+    # or a webhook. Named `deliver`, not `send`: `Object#send` is a core Ruby method.
+    #
+    # `idempotency_key:`: unique per domain. A UUID is generated when omitted (see
+    # `docs/bibliotheques-clientes.md` section 3.3): a network-level retry of the SAME call can
+    # then never create a duplicate message, but two separate calls each get their own random
+    # key, so they are NOT deduplicated against each other; pass your own stable key for that
+    # (e.g. an order id).
+    def deliver(from:, to:, subject:, idempotency_key: nil, **fields)
+      body = message_body(from: from, to: to, subject: subject, **fields)
+      key = idempotency_key || SecureRandom.uuid
+      result = @client.request(RequestSpec.new(method: "POST", path: "#{@client.config.domain_path}/messages",
+                                               body: body, idempotency_key: key, safe_retry: true))
+      accepted = MessageAccepted.from_json_hash(result.data)
+      SendMessageResult.new(id: accepted.id, status: accepted.status,
+                            replayed: result.headers["idempotent-replayed"] == "true",
+                            location: result.headers["location"])
+    end
+
+    # The message's status and each recipient's status.
+    def get(id)
+      result = @client.request(RequestSpec.new(method: "GET", path: "#{@client.config.domain_path}/messages/#{id}",
+                                               safe_retry: true))
+      Message.from_json_hash(result.data)
+    end
+
+    private
+
+    def message_body(from:, to:, subject:, html: nil, text: nil, tags: nil, tracking: nil, reply_to: nil,
+                     headers: nil, metadata: nil, attachments: nil)
+      Attachments.assert_limits(attachments) if attachments && !attachments.empty?
+      body = { "from" => from, "to" => to, "subject" => subject }
+      body["html"] = html unless html.nil?
+      body["text"] = text unless text.nil?
+      body["tags"] = tags unless tags.nil?
+      unless tracking.nil?
+        body["tracking"] =
+          { "opens" => tracking.fetch(:opens, false), "clicks" => tracking.fetch(:clicks, false) }
+      end
+      body["reply_to"] = reply_to unless reply_to.nil?
+      body["headers"] = headers unless headers.nil?
+      body["metadata"] = metadata unless metadata.nil?
+      body["attachments"] = attachments.map(&:to_h) unless attachments.nil?
+      body
+    end
+  end
+
+  # @api private
+  class EventsResource
+    def initialize(client)
+      @client = client
+    end
+
+    # One page of delivery events, most recent first.
+    def list(message_id: nil, type: nil, recipient: nil, since: nil, limit: nil, cursor: nil)
+      query = { "message_id" => message_id, "type" => type, "recipient" => recipient,
+                "since" => since&.iso8601, "limit" => limit, "cursor" => cursor }
+      result = @client.request(RequestSpec.new(method: "GET", path: "#{@client.config.domain_path}/events", query: query,
+                                               safe_retry: true))
+      EventPage.from_json_hash(result.data)
+    end
+
+    # Every delivery event, most recent first, following `next_cursor` automatically. Returns a
+    # lazy Enumerator (nothing is fetched until you iterate).
+    def list_all(message_id: nil, type: nil, recipient: nil, since: nil, max_items: nil)
+      Pagination.paginate(max_items: max_items) do |cursor|
+        list(message_id: message_id, type: type, recipient: recipient, since: since, cursor: cursor)
+      end
+    end
+  end
+
+  # @api private
+  class SuppressionsResource
+    def initialize(client)
+      @client = client
+    end
+
+    # One page of suppressed addresses, most recent first.
+    def list(reason: nil, limit: nil, cursor: nil)
+      query = { "reason" => reason, "limit" => limit, "cursor" => cursor }
+      result = @client.request(RequestSpec.new(method: "GET", path: "#{@client.config.domain_path}/suppressions", query: query,
+                                               safe_retry: true))
+      SuppressionPage.from_json_hash(result.data)
+    end
+
+    # Every suppressed address, most recent first, following `next_cursor` automatically.
+    def list_all(reason: nil, max_items: nil)
+      Pagination.paginate(max_items: max_items) { |cursor| list(reason: reason, cursor: cursor) }
+    end
+
+    # Adds an address by hand (reason `manual`): it receives nothing more from this domain.
+    # Naturally idempotent: adding an already-suppressed address changes nothing.
+    def add(email)
+      result = @client.request(RequestSpec.new(method: "POST", path: "#{@client.config.domain_path}/suppressions",
+                                               body: { "email" => email }, safe_retry: false))
+      Suppression.from_json_hash(result.data)
+    end
+
+    # Removes an address from the list: it may receive mail again. Raises NotFoundError if it
+    # was not on the list.
+    def remove(email)
+      path = "#{@client.config.domain_path}/suppressions/#{Config.percent_encode(email)}"
+      @client.request(RequestSpec.new(method: "DELETE", path: path, safe_retry: false))
+      nil
+    end
+  end
+
+  # @api private
+  class WebhooksResource
+    def initialize(client)
+      @client = client
+    end
+
+    # Registers an endpoint. The response carries the signing `secret` (`whsec_...`): shown
+    # ONCE, store it to verify signatures. Each call creates a DISTINCT endpoint, never retried
+    # automatically.
+    def create(url, events: nil)
+      result = @client.request(RequestSpec.new(method: "POST", path: "#{@client.config.domain_path}/webhooks",
+                                               body: { "url" => url, "events" => events || [] }, safe_retry: false))
+      Webhook.from_json_hash(result.data)
+    end
+
+    def list
+      result = @client.request(RequestSpec.new(method: "GET", path: "#{@client.config.domain_path}/webhooks", safe_retry: true))
+      WebhookList.from_json_hash(result.data).data
+    end
+
+    def get(id)
+      result = @client.request(RequestSpec.new(method: "GET", path: "#{@client.config.domain_path}/webhooks/#{id}",
+                                               safe_retry: true))
+      Webhook.from_json_hash(result.data)
+    end
+
+    def delete(id)
+      @client.request(RequestSpec.new(method: "DELETE", path: "#{@client.config.domain_path}/webhooks/#{id}", safe_retry: false))
+      nil
+    end
+
+    # The latest deliveries of this endpoint (`limit`: 1 to 100, 50 by default).
+    def deliveries(id, limit: nil)
+      path = "#{@client.config.domain_path}/webhooks/#{id}/deliveries"
+      result = @client.request(RequestSpec.new(method: "GET", path: path, query: { "limit" => limit }, safe_retry: true))
+      WebhookDeliveryList.from_json_hash(result.data).data
+    end
+  end
+
+  # @api private
+  class StatsResource
+    def initialize(client)
+      @client = client
+    end
+
+    # Counters of the domain by period (UTC). Defaults to the last 30 days (or 24 hours, by
+    # hour). At most 366 days, or 7 days by hour.
+    def get(granularity: nil, since: nil, until_: nil)
+      query = { "granularity" => granularity, "since" => since&.iso8601, "until" => until_&.iso8601 }
+      result = @client.request(RequestSpec.new(method: "GET", path: "#{@client.config.domain_path}/stats", query: query,
+                                               safe_retry: true))
+      Stats.from_json_hash(result.data)
+    end
+  end
+end

data/lib/duva/errors.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Duva
+  # Base of every error raised for a request Duva actually answered (as opposed to a network
+  # failure: see ConnectionError and TimeoutError). Mapped from `error.code` (the contract),
+  # never from the HTTP status alone or the wording of `error.message` (which can change between
+  # languages and over time). See `docs/bibliotheques-clientes.md` section 3.6 in the `duva`
+  # repository for the source table.
+  class Error < StandardError
+    # The HTTP status Duva answered with.
+    attr_reader :status
+    # `error.code`: the contract. Rely on this, never on the exception message.
+    attr_reader :code
+    # `error.fields`, when the error is a validation error (`code == "invalid_request"`).
+    attr_reader :fields
+    # The raw response body, bounded to 4 KB: never includes your API key.
+    attr_reader :raw_body
+
+    def initialize(status:, code:, message:, raw_body:, fields: nil)
+      super(message)
+      @status = status
+      @code = code
+      @fields = fields
+      @raw_body = raw_body.to_s[0, 4096]
+    end
+
+    # Never leak the raw body (which could, in principle, carry a stray fragment of a request)
+    # through the default `#inspect` a debugger or a crash report would print.
+    def inspect
+      "#<#{self.class}: status=#{status} code=#{code.inspect}>"
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class NotFoundError < Error; end
+
+  # `domain_not_verified` or `sending_not_allowed`; `code` distinguishes the two.
+  class PermissionError < Error; end
+
+  # `idempotency_conflict` or `limit_reached`; `code` distinguishes the two.
+  class ConflictError < Error; end
+
+  class PayloadTooLargeError < Error; end
+
+  class ValidationError < Error
+    def initialize(status:, code:, message:, raw_body:, fields: nil)
+      super(status: status, code: code, message: message, raw_body: raw_body, fields: fields || [])
+    end
+  end
+
+  # A `429` on YOUR ACCOUNT quota (daily or monthly). `retry_after` can be hours: never retried
+  # automatically, by design (see `docs/bibliotheques-clientes.md` section 3.5).
+  class QuotaExceededError < Error
+    attr_reader :retry_after
+
+    def initialize(status:, code:, message:, raw_body:, fields:, retry_after:)
+      super(status: status, code: code, message: message, raw_body: raw_body, fields: fields)
+      @retry_after = retry_after
+    end
+  end
+
+  # A `429` from the per-key rate limit (unrelated to your sending quota). Retried automatically
+  # when `retry_after` fits within `max_retry_wait_seconds`.
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(status:, code:, message:, raw_body:, fields:, retry_after:)
+      super(status: status, code: code, message: message, raw_body: raw_body, fields: fields)
+      @retry_after = retry_after
+    end
+  end
+
+  # A `5xx`, or a response whose body was not the documented error envelope.
+  class ServerError < Error; end
+
+  # No response was received at all (DNS, TLS, connection refused, connection reset...). The
+  # original exception is kept as `#cause` (Ruby's own chaining, via `raise ... from:`-less
+  # `raise` inside a `rescue` block).
+  class ConnectionError < StandardError; end
+
+  # The request exceeded `timeout` before any response arrived.
+  class TimeoutError < StandardError; end
+
+  # A webhook signature failed to verify: never carries the secret or the raw body.
+  class WebhookSignatureError < StandardError; end
+
+  # @api private
+  CODES = {
+    "unauthorized" => AuthenticationError,
+    "not_found" => NotFoundError,
+    "domain_not_verified" => PermissionError,
+    "sending_not_allowed" => PermissionError,
+    "idempotency_conflict" => ConflictError,
+    "limit_reached" => ConflictError,
+    "payload_too_large" => PayloadTooLargeError,
+    "invalid_request" => ValidationError,
+    "internal_error" => ServerError,
+    "method_not_allowed" => ServerError,
+    "http_error" => ServerError
+  }.freeze
+  private_constant :CODES
+
+  # Builds the right Error subclass from a parsed response body, or a generic ServerError when
+  # the body does not match the documented envelope (a proxy error page, for instance): never
+  # raises itself.
+  #
+  # @api private
+  def self.error_from_response(status, parsed_body, raw_body, retry_after_header)
+    code, message, fields = as_error_body(parsed_body)
+    retry_after = retry_after_header ? retry_after_header.to_i : 0
+    case code
+    when "quota_exceeded"
+      QuotaExceededError.new(status: status, code: code, message: message, raw_body: raw_body,
+                             fields: fields, retry_after: retry_after)
+    when "rate_limited"
+      RateLimitError.new(status: status, code: code, message: message, raw_body: raw_body,
+                         fields: fields, retry_after: retry_after)
+    else
+      klass = CODES.fetch(code, ServerError)
+      klass.new(status: status, code: code, message: message, raw_body: raw_body, fields: fields)
+    end
+  end
+
+  # @api private
+  def self.as_error_body(value)
+    error = value.is_a?(Hash) && value["error"].is_a?(Hash) ? value["error"] : nil
+    return ["http_error", "Duva answered with an unexpected body.", nil] unless error.is_a?(Hash) && error["code"].is_a?(String)
+
+    [error["code"], error["message"] || "", error["fields"]]
+  end
+  private_class_method :as_error_body
+end

data/lib/duva/models.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Duva
+  # Hand-written response value objects (Ruby's typing is optional per
+  # `docs/bibliotheques-clientes.md` section 4 -- RBS/Sorbet are left to the application, unlike
+  # the generated models of the Node.js and Python libraries). Each `.from_json_hash` factory
+  # reads only the fields it knows and ignores the rest, and never restricts a string enum-like
+  # field (`status`, `type`, `reason`...) to a fixed set: a value the server adds later still
+  # comes through as plain text rather than raising (section 3.7, "tolerance").
+  #
+  # @api private
+  module Models
+    def self.time(value)
+      value && Time.iso8601(value)
+    end
+  end
+  private_constant :Models
+
+  Tracking = Data.define(:opens, :clicks) do
+    def self.from_json_hash(h)
+      new(opens: h["opens"] || false, clicks: h["clicks"] || false)
+    end
+  end
+
+  Recipient = Data.define(:email, :status, :updated_at) do
+    def self.from_json_hash(h)
+      new(email: h["email"], status: h["status"], updated_at: Models.time(h["updated_at"]))
+    end
+  end
+
+  Message = Data.define(:id, :status, :from, :subject, :tags, :metadata, :tracking, :created_at, :recipients) do
+    def self.from_json_hash(h)
+      new(
+        id: h["id"], status: h["status"], from: h["from"], subject: h["subject"],
+        tags: h["tags"] || [], metadata: h["metadata"] || {},
+        tracking: Tracking.from_json_hash(h["tracking"] || {}),
+        created_at: Models.time(h["created_at"]),
+        recipients: (h["recipients"] || []).map { |r| Recipient.from_json_hash(r) }
+      )
+    end
+  end
+
+  MessageAccepted = Data.define(:id, :status) do
+    def self.from_json_hash(h)
+      new(id: h["id"], status: h["status"])
+    end
+  end
+
+  Event = Data.define(:id, :type, :message_id, :recipient, :occurred_at, :detail, :metadata) do
+    def self.from_json_hash(h)
+      new(
+        id: h["id"], type: h["type"], message_id: h["message_id"], recipient: h["recipient"],
+        occurred_at: Models.time(h["occurred_at"]), detail: h["detail"] || {}, metadata: h["metadata"] || {}
+      )
+    end
+  end
+
+  EventPage = Data.define(:data, :next_cursor) do
+    def self.from_json_hash(h)
+      new(data: (h["data"] || []).map { |e| Event.from_json_hash(e) }, next_cursor: h["next_cursor"])
+    end
+  end
+
+  Suppression = Data.define(:email, :reason, :message_id, :created_at) do
+    def self.from_json_hash(h)
+      new(email: h["email"], reason: h["reason"], message_id: h["message_id"], created_at: Models.time(h["created_at"]))
+    end
+  end
+
+  SuppressionPage = Data.define(:data, :next_cursor) do
+    def self.from_json_hash(h)
+      new(data: (h["data"] || []).map { |s| Suppression.from_json_hash(s) }, next_cursor: h["next_cursor"])
+    end
+  end
+
+  Webhook = Data.define(:id, :url, :events, :status, :disabled_reason, :created_at, :secret) do
+    def self.from_json_hash(h)
+      new(
+        id: h["id"], url: h["url"], events: h["events"] || [], status: h["status"],
+        disabled_reason: h["disabled_reason"], created_at: Models.time(h["created_at"]), secret: h["secret"]
+      )
+    end
+  end
+
+  WebhookList = Data.define(:data) do
+    def self.from_json_hash(h)
+      new(data: (h["data"] || []).map { |w| Webhook.from_json_hash(w) })
+    end
+  end
+
+  WebhookDelivery = Data.define(:id, :event_id, :status, :attempts, :last_status_code, :last_error, :created_at, :delivered_at) do
+    def self.from_json_hash(h)
+      new(
+        id: h["id"], event_id: h["event_id"], status: h["status"], attempts: h["attempts"],
+        last_status_code: h["last_status_code"], last_error: h["last_error"],
+        created_at: Models.time(h["created_at"]), delivered_at: Models.time(h["delivered_at"])
+      )
+    end
+  end
+
+  WebhookDeliveryList = Data.define(:data) do
+    def self.from_json_hash(h)
+      new(data: (h["data"] || []).map { |d| WebhookDelivery.from_json_hash(d) })
+    end
+  end
+
+  StatsPeriod = Data.define(:period, :accepted, :suppressed, :delivered, :bounced, :deferred, :expired, :complained, :opened,
+                            :clicked) do
+    def self.from_json_hash(h)
+      new(
+        period: Models.time(h["period"]), accepted: h["accepted"], suppressed: h["suppressed"],
+        delivered: h["delivered"], bounced: h["bounced"], deferred: h["deferred"], expired: h["expired"],
+        complained: h["complained"], opened: h["opened"], clicked: h["clicked"]
+      )
+    end
+  end
+
+  Stats = Data.define(:granularity, :since, :until, :data, :totals) do
+    def self.from_json_hash(h)
+      new(
+        granularity: h["granularity"], since: Models.time(h["since"]), until: Models.time(h["until"]),
+        data: (h["data"] || []).map { |p| StatsPeriod.from_json_hash(p) }, totals: h["totals"] || {}
+      )
+    end
+  end
+end

data/lib/duva/pagination.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Duva
+  # Cursor pagination, shared by `events.list_all` and `suppressions.list_all`: follows
+  # `next_cursor` until it is `nil`, without ever loading every page into memory at once.
+  #
+  # @api private
+  module Pagination
+    # `fetch_page` is called with the current cursor (`nil` for the first page) and must return
+    # an object responding to `#data` (an Array) and `#next_cursor`. Returns a lazy Enumerator:
+    # nothing is fetched until the caller actually iterates (`each`, `first`, `to_a`...).
+    def self.paginate(max_items: nil, &fetch_page)
+      Enumerator.new do |yielder|
+        cursor = nil
+        yielded = 0
+        catch(:duva_pagination_done) do
+          loop do
+            page = fetch_page.call(cursor)
+            page.data.each do |item|
+              yielder << item
+              yielded += 1
+              throw :duva_pagination_done if max_items && yielded >= max_items
+            end
+            break if page.next_cursor.nil?
+
+            cursor = page.next_cursor
+          end
+        end
+      end
+    end
+  end
+end

data/lib/duva/test_transport.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Duva
+  # A scriptable fake Transport (`docs/bibliotheques-clientes.md` section 3.10: "a fake
+  # transport and a response builder, so you can test YOUR OWN application without a network
+  # call"). Inject it via `Client.new(transport: ...)`.
+  #
+  #   transport = Duva::TestTransport.new { |_config, spec| Duva::TestTransport.response({"status" => "ok"}) }
+  #   duva = Duva::Client.new(api_key: "dv_test", domain: "example.com", transport: transport)
+  #   duva.health
+  #   transport.requests.last.path # => "/health"
+  class TestTransport
+    # Every RequestSpec actually sent, in order: inspect it to assert what your code sent.
+    attr_reader :requests
+
+    # `handler` receives `(config, spec)` for each call and must return a RawResponse (see
+    # .response) or raise a Duva::Error subclass, Duva::ConnectionError or Duva::TimeoutError.
+    def initialize(&handler)
+      @handler = handler
+      @requests = []
+    end
+
+    # @api private
+    def call(config, spec)
+      @requests << spec
+      @handler.call(config, spec)
+    end
+
+    # Builds a RawResponse from a plain Hash (or nil, for a 204), as your handler returns it.
+    def self.response(data = nil, headers: {})
+      RawResponse.new(data: data, headers: headers.transform_keys { |k| k.to_s.downcase })
+    end
+  end
+end

data/lib/duva/transport.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Duva
+  DEFAULT_BASE_URL = "https://api.duva.ca"
+
+  # Resolved, validated client configuration.
+  Config = Data.define(:api_key, :domain, :base_url, :timeout, :max_retries, :max_retry_wait_seconds,
+                       :language, :user_agent) do
+    class << self
+      def resolve(api_key: nil, domain: nil, base_url: DEFAULT_BASE_URL, timeout: 10, max_retries: 2,
+                  max_retry_wait_seconds: 30, language: nil, user_agent: nil)
+        resolved_key = api_key || ENV.fetch("DUVA_API_KEY", nil)
+        resolved_domain = domain || ENV.fetch("DUVA_DOMAIN", nil)
+        raise ArgumentError, "Duva: an API key is required (api_key: or DUVA_API_KEY)" unless resolved_key
+        raise ArgumentError, "Duva: a domain is required (domain: or DUVA_DOMAIN)" unless resolved_domain
+
+        clean_base_url = base_url.chomp("/")
+        unless clean_base_url.start_with?("https://") || clean_base_url.include?("localhost")
+          raise ArgumentError, "Duva: base_url must be https:// (http://localhost is allowed for tests)"
+        end
+
+        new(api_key: resolved_key, domain: resolved_domain, base_url: clean_base_url, timeout: timeout,
+            max_retries: max_retries, max_retry_wait_seconds: max_retry_wait_seconds, language: language,
+            user_agent: user_agent)
+      end
+
+      # RFC 3986 percent-encoding with no "safe" characters (mirrors Python's
+      # `urllib.parse.quote(s, safe="")`): every octet outside unreserved (`A-Za-z0-9-_.~`) is
+      # escaped, including `/`.
+      def percent_encode(str)
+        str.b.gsub(/[^A-Za-z0-9\-_.~]/) { |char| format("%%%02X", char.ord) }
+      end
+    end
+
+    # The path prefix for this client's domain (`/v1/<domain>`).
+    def domain_path
+      "/v1/#{self.class.percent_encode(domain)}"
+    end
+
+    def user_agent_header
+      extra = user_agent ? " #{user_agent}" : ""
+      "duva-ruby/#{Duva::VERSION} Ruby/#{RUBY_VERSION}#{extra}"
+    end
+  end
+
+  # One HTTP call to make: built by Client, executed by a Transport.
+  RequestSpec = Data.define(:method, :path, :query, :body, :idempotency_key, :safe_retry) do
+    def initialize(method:, path:, query: nil, body: nil, idempotency_key: nil, safe_retry: false)
+      super
+    end
+  end
+
+  # A parsed response: `data` is the parsed JSON body (or nil for a 204 or an empty body),
+  # `headers` a Hash with lower-cased keys.
+  RawResponse = Data.define(:data, :headers)
+
+  # Builds the wire-level shape of a request (method, URI, headers, body) from a Config and a
+  # RequestSpec: a PURE function, with no I/O, so it can be checked directly (see
+  # `spec/conformance/requests_spec.rb`) without a network call or a fake transport.
+  #
+  # @api private
+  module HttpMessage
+    def self.build(config, spec)
+      uri = URI.parse(config.base_url + spec.path)
+      uri.query = URI.encode_www_form(spec.query.compact) if spec.query && !spec.query.compact.empty?
+      headers = {
+        "authorization" => "Bearer #{config.api_key}",
+        "user-agent" => config.user_agent_header
+      }
+      headers["accept-language"] = config.language if config.language
+      headers["idempotency-key"] = spec.idempotency_key if spec.idempotency_key
+      body = nil
+      if spec.body
+        headers["content-type"] = "application/json"
+        body = JSON.generate(spec.body)
+      end
+      { method: spec.method, uri: uri, headers: headers, body: body }
+    end
+  end
+
+  # Default transport: plain `Net::HTTP` (no gem dependency). Any object responding to
+  # `#call(config, spec) -> RawResponse` (raising ConnectionError/TimeoutError/a Duva::Error
+  # subclass as appropriate) can be injected instead -- for your own tests (see TestTransport) or
+  # to plug in Faraday or another HTTP client.
+  class NetHttpTransport
+    def call(config, spec)
+      built = HttpMessage.build(config, spec)
+      request = build_net_http_request(built)
+      response = perform(built[:uri], request, config.timeout)
+      parse(response)
+    rescue Net::OpenTimeout, Net::ReadTimeout
+      raise Duva::TimeoutError, "Duva: request timed out"
+    rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET, OpenSSL::SSL::SSLError, IOError => e
+      raise Duva::ConnectionError, "Duva: the request could not be sent: #{e.message}"
+    end
+
+    private
+
+    def build_net_http_request(built)
+      request_class = { "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post, "DELETE" => Net::HTTP::Delete }.fetch(built[:method])
+      request = request_class.new(built[:uri])
+      built[:headers].each { |name, value| request[name] = value }
+      request.body = built[:body] if built[:body]
+      request
+    end
+
+    def perform(uri, request, timeout)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: timeout, read_timeout: timeout) do |http|
+        http.request(request)
+      end
+    end
+
+    def parse(response)
+      headers = {}
+      response.each_header { |name, value| headers[name] = value }
+      body = response.body
+      data = body && !body.empty? ? JSON.parse(body) : nil
+      code = response.code.to_i
+      return RawResponse.new(data: data, headers: headers) if code < 300
+
+      raise Duva.error_from_response(code, data, body.to_s, headers["retry-after"])
+    end
+  end
+end

data/lib/duva/webhooks.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+module Duva
+  # The JSON body Duva sends to your webhook URL, already parsed.
+  WebhookEvent = Data.define(:id, :type, :domain, :data)
+
+  # Webhook signature verification, "Standard Webhooks" format (see `docs/api.md` "Webhooks" in
+  # the `duva` repository). Duva SENDS webhooks; this module is for VERIFYING them on your side.
+  module Webhooks
+    SECRET_PREFIX = "whsec_"
+    DEFAULT_TOLERANCE_SECONDS = 300
+    private_constant :SECRET_PREFIX, :DEFAULT_TOLERANCE_SECONDS
+
+    class << self
+      # Verifies a webhook request. `secrets` accepts one secret or an array (for key rotation:
+      # while both the old and the new secret are active, a webhook signed with either must
+      # verify).
+      #
+      # `headers` is looked up case-insensitively (whatever your framework hands you is not
+      # guaranteed to have lower-case keys). `raw_body` must be the EXACT bytes Duva sent: re-
+      # encoding a parsed-then-re-serialized JSON body changes its bytes and invalidates every
+      # signature.
+      #
+      # `now`: the current instant as a Unix timestamp in seconds. Defaults to `Time.now.to_i`;
+      # override only in your OWN tests (see .sign and the fixtures of `duva-mail/duva-conformance`,
+      # which document the exact instant each vector was signed at).
+      def verify_signature(secrets, headers, raw_body, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil)
+        event_id = header(headers, "webhook-id")
+        timestamp = header(headers, "webhook-timestamp")
+        signature_header = header(headers, "webhook-signature")
+        return false if event_id.nil? || timestamp.nil? || signature_header.nil? || signature_header.empty?
+
+        at = Integer(timestamp, exception: false)
+        return false if at.nil?
+
+        current = now || Time.now.to_i
+        return false if (current - at).abs > tolerance_seconds
+
+        secret_list = secrets.is_a?(Array) ? secrets : [secrets]
+        expected = expected_signatures(secret_list, event_id, timestamp, raw_body)
+        return false if expected.nil?
+
+        # `webhook-signature` may carry several space-separated `v1,<signature>` entries (Duva
+        # sends one; a sender that itself rotates its OWN signing key mid-flight could send
+        # more): any match against any of your active secrets is accepted.
+        signature_header.split.any? do |part|
+          version, _, signature = part.partition(",")
+          next false if version != "v1" || signature.empty?
+
+          expected.any? { |candidate| secure_compare(signature, candidate) }
+        end
+      end
+
+      # .verify_signature, then parses the body: raises WebhookSignatureError on a bad signature
+      # rather than returning a boolean, for call sites that want to raise on failure. Never
+      # includes the secret or the raw body in the error.
+      def construct_event(secrets, headers, raw_body, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil)
+        unless verify_signature(secrets, headers, raw_body, tolerance_seconds: tolerance_seconds, now: now)
+          raise WebhookSignatureError, "webhook signature verification failed"
+        end
+
+        parsed = JSON.parse(raw_body)
+        WebhookEvent.new(id: parsed["id"], type: parsed["type"], domain: parsed["domain"], data: parsed["data"])
+      end
+
+      # Builds a validly signed request FOR YOUR OWN TESTS: the headers a real Duva webhook
+      # delivery would carry for `body`, signed with `secret` as of `timestamp` (Unix seconds;
+      # defaults to now). Never used by the library itself to send anything: Duva is the only
+      # real sender.
+      def sign(secret, event_id, body, timestamp: nil)
+        at = timestamp || Time.now.to_i
+        ts = at.to_s
+        signature = expected_signature(secret, event_id, ts, body)
+        {
+          "content-type" => "application/json",
+          "webhook-id" => event_id,
+          "webhook-timestamp" => ts,
+          "webhook-signature" => "v1,#{signature}"
+        }
+      end
+
+      private
+
+      def header(headers, name)
+        match = headers.find { |key, _| key.to_s.downcase == name }
+        match && match[1]
+      end
+
+      def decode_secret(secret)
+        raise WebhookSignatureError, "a Duva webhook secret starts with whsec_" unless secret.start_with?(SECRET_PREFIX)
+
+        Base64.strict_decode64(secret.delete_prefix(SECRET_PREFIX))
+      rescue ArgumentError
+        raise WebhookSignatureError, "a Duva webhook secret starts with whsec_"
+      end
+
+      def expected_signature(secret, event_id, timestamp, raw_body)
+        key = decode_secret(secret)
+        digest = OpenSSL::HMAC.digest("SHA256", key, "#{event_id}.#{timestamp}.#{raw_body}")
+        Base64.strict_encode64(digest)
+      end
+
+      def expected_signatures(secret_list, event_id, timestamp, raw_body)
+        secret_list.map { |secret| expected_signature(secret, event_id, timestamp, raw_body) }
+      rescue WebhookSignatureError
+        nil
+      end
+
+      def secure_compare(left, right)
+        OpenSSL.secure_compare(left, right)
+      rescue TypeError, ArgumentError
+        false # secure_compare requires equal-length strings; a mismatched length is just "false"
+      end
+    end
+  end
+end

data/lib/duva-mail.rb

@@ -1,2 +1,4 @@
+# frozen_string_literal: true
+
 # Convention RubyGems pour un nom a trait d union : `require "duva-mail"` charge la bibliotheque comme `require "duva"`.
 require_relative "duva"

data/lib/duva.rb

@@ -1,4 +1,15 @@
-# Reserved name: the official Duva client library is not released yet. See https://duva.ca
+# frozen_string_literal: true
+
 module Duva
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end
+
+require_relative "duva/errors"
+require_relative "duva/models"
+require_relative "duva/pagination"
+require_relative "duva/transport"
+require_relative "duva/test_transport"
+require_relative "duva/client"
+require_relative "duva/webhooks"
+require_relative "duva/attachments"
+require_relative "duva/address"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: duva-mail
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - 9573-4562 Québec inc.
@@ -9,9 +9,23 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2026-09-27 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 description: 'Official client library for Duva, a transactional email API hosted in
-  Canada. This name is reserved: the library is not released yet.'
+  Canada: sending, delivery events, suppressions, webhooks and statistics.'
 email:
 executables: []
 extensions: []
@@ -19,14 +33,25 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- duva-mail.gemspec
 - lib/duva-mail.rb
 - lib/duva.rb
+- lib/duva/address.rb
+- lib/duva/attachments.rb
+- lib/duva/client.rb
+- lib/duva/errors.rb
+- lib/duva/models.rb
+- lib/duva/pagination.rb
+- lib/duva/test_transport.rb
+- lib/duva/transport.rb
+- lib/duva/webhooks.rb
 homepage: https://duva.ca
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/duva-mail/duva-ruby
   documentation_uri: https://duva.ca/en/docs
+  changelog_uri: https://duva.ca/en/docs#changelog
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -43,8 +68,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.15
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Official Duva client library (name reserved, not released yet)
+summary: Official Duva client library (transactional email API hosted in Canada).
 test_files: []