mailkube 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7641c72078cd5550384c2e708dc156aea1f487d2304d07689ed7fcebc0868bd4
-  data.tar.gz: 4d0d9ea1e793297301d4cc7652a3ee0fa40b08dc7fcc2fa069b33cb20ddcfef2
+  metadata.gz: 11e623e291d499bfa611c9eb8e4e768b8a93dbffafe84422dfc0692f0e4c719a
+  data.tar.gz: 2f945465f2bb22cd7633aeb05901f53a48311d41c748c216264c8862720f50bc
 SHA512:
-  metadata.gz: 8abad977f64add055a7d30eb83c88529ba3602fdeeb37f7f543386f2b7683fbec70e00f28e7cd102fa1288fabf4f503dbf81cf4c616429f62539d672c3c2b499
-  data.tar.gz: dd85a8fc81e7cc52a2446bd13e70a348866694b65c0034133b4dbfe7fe8ecd31c45f82a4479216e60d783785131a5d5a27fa90ce265d86c3949493f161191cc2
+  metadata.gz: 4d02cc6a359397afb79581541156aa4f6774b7f187c798d63d4e3e2923024e095d40c5d7676c5024b6b319bffc28bec7ed9c89be98d668c8300ae6c5b5155ac2
+  data.tar.gz: 4ee50cef68dfaaae7a8dacc2c76ab6b6bb02e5fbaa4f642014c6224ce45ba90d8e72558a98a1ee009b480cc6b0711b185d6a4fb58f4bcb60f48e454bc365c32e

data/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 Mailtactic, Corp.
+   Copyright 2026 Mail Tactic Corporation
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/NOTICE

@@ -1,11 +1,8 @@
 mailkube-ruby
-Copyright 2026 Mailtactic, Corp.
+Copyright 2026 Mail Tactic Corporation
 
 This product is licensed under the Apache License, Version 2.0 (the "License");
 you may not use this product except in compliance with the License. You may
 obtain a copy of the License at:
 
     http://www.apache.org/licenses/LICENSE-2.0
-
-"mailkube" is a trademark of Mailtactic, Corp. Use of the name is governed by
-Section 6 (Trademarks) of the License.

data/README.md

@@ -46,6 +46,13 @@ Create one client and reuse it.
 | Base URL | `base_url:` | `MAILKUBE_BASE_URL` | `https://api.mailkube.com/mta/v1/` |
 | Timeout | `timeout:` | | 30s |
 | HTTP adapter | `http:` | | `Mailkube::NetHttpAdapter` |
+| User-Agent suffix | `user_agent_suffix:` | | none |
+
+If you are building something on top of this gem — a CLI, an internal service, a framework
+integration — set `user_agent_suffix:` to your own `name/version`. It is appended after this SDK's
+own token, so both are visible: `mailkube-ruby/1.1.0 my-cli/1.0.0`. Surrounding whitespace is
+trimmed, and a value containing CR or LF is **ignored rather than sanitized** — a header value that
+could split the request is not one this gem will send, and quietly repairing it would hide the bug.
 
 Pass your own `http:` adapter — anything responding to
 `#call(method:, url:, headers:, body:)` and returning a `Mailkube::HttpResponse` — to route
@@ -198,6 +205,15 @@ header mapping, including Rack's CGI-env spelling.
 `Mailkube::Webhooks.verify_signature` is the signature check alone, if you want to parse yourself.
 `X-Webhook-Id` is stable across retries; deduplicate on it.
 
+`Mailkube::Webhooks.sign` is the mirror, so your own tests can build a valid request without
+reimplementing the HMAC from this page:
+
+```ruby
+signature = Mailkube::Webhooks.sign(
+  id: "wh_1", timestamp: Time.now.utc.iso8601, payload: body, secret: secret
+)
+```
+
 ### Endpoint registration
 
 When you create an endpoint, or re-point an existing one, mailkube probes it with
@@ -224,6 +240,12 @@ implement it.
 Every `email.*` payload also carries the message context: `email_id`, `created_at`, `domain`,
 `subject`, `to`, `from` and `tags`.
 
+On the `data.open` and `data.click` blocks, `ip_address`, `country` and `user_agent` are recorded
+only where the sending domain has elected them, and both settings are off by default. The server
+omits the key rather than sending an empty value, so the accessor returns `nil` when it was not
+recorded. `country` can be `nil` even where the address was recorded, because it is resolved at the
+edge and is not available on every path.
+
 Two guarantees hold for every released version, so a platform change never breaks a running
 receiver:
 
@@ -320,4 +342,4 @@ must pass. Security issues: see [SECURITY.md](SECURITY.md).
 
 ## License
 
-[Apache-2.0](LICENSE) © 2026 Mailtactic, Corp.
+[Apache-2.0](LICENSE) © 2026 Mail Tactic Corporation

data/lib/mailkube/client.rb

@@ -35,9 +35,15 @@ module Mailkube
     # @param http [#call, nil] an HTTP adapter to use instead of the built-in {NetHttpAdapter}.
     #   This is the dependency-inversion seam the test suite injects through; when supplied,
     #   `timeout` is the adapter's business rather than this client's.
+    # @param user_agent_suffix [String, nil] a `name/version` token identifying software that
+    #   wraps this SDK — a CLI, an internal service, a framework integration — appended after
+    #   this SDK's own token so both are visible. A value containing CR or LF is ignored.
     # @raise [ConfigurationError] when no API key is available.
-    def initialize(api_key: nil, base_url: nil, timeout: Config::DEFAULT_TIMEOUT, http: nil)
-      config = Config.new(api_key: api_key, base_url: base_url, timeout: timeout)
+    def initialize(api_key: nil, base_url: nil, timeout: Config::DEFAULT_TIMEOUT, http: nil,
+                   user_agent_suffix: nil)
+      config = Config.new(
+        api_key: api_key, base_url: base_url, timeout: timeout, user_agent_suffix: user_agent_suffix
+      )
       transport = Transport.new(config, http || NetHttpAdapter.new(timeout: timeout))
 
       @config = config

data/lib/mailkube/config.rb

@@ -30,14 +30,20 @@ module Mailkube
     # @param api_key [String, nil] the API key; falls back to `MAILKUBE_API_KEY`.
     # @param base_url [String, nil] the API base URL; falls back to `MAILKUBE_BASE_URL`.
     # @param timeout [Integer, Float] the per-request timeout in seconds.
+    # @param user_agent_suffix [String, nil] a `name/version` token identifying software that
+    #   wraps this SDK, appended after this SDK's own token.
     # @raise [ConfigurationError] when no API key is available.
-    def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT)
+    def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT, user_agent_suffix: nil)
       key = api_key || ENV.fetch(ENV_API_KEY, nil)
       raise ConfigurationError, "no API key provided: pass api_key: or set #{ENV_API_KEY}" if key.nil? || key.empty?
 
       @api_key = key
       @base_url = base_url || ENV.fetch(ENV_BASE_URL, nil) || Mailkube::DEFAULT_BASE_URL
       @timeout = timeout
+      suffix = user_agent_suffix.to_s.strip
+      # Dropped rather than sanitized: a header value that could split the request is not one this
+      # gem will send, and silently repairing it hides the caller's bug.
+      @user_agent_suffix = suffix.match?(/[\r\n]/) ? "" : suffix
       freeze
     end
 
@@ -51,12 +57,23 @@ module Mailkube
     def default_headers
       {
         "Authorization" => "Bearer #{@api_key}",
-        "User-Agent" => "mailkube-ruby/#{VERSION}",
+        "User-Agent" => user_agent,
         "Content-Type" => "application/json",
         "Accept" => "application/json"
       }
     end
 
+    # This gem's token, plus any suffix a wrapping tool supplied.
+    #
+    # The SDK token always leads, so attribution of the SDK itself never depends on what the
+    # wrapper chose to call itself.
+    #
+    # @return [String] the User-Agent value.
+    def user_agent
+      agent = "mailkube-ruby/#{VERSION}"
+      @user_agent_suffix.empty? ? agent : "#{agent} #{@user_agent_suffix}"
+    end
+
     # Join a relative path onto the base URL, attach the query, and refuse any absolute URL off
     # the base URL's origin.
     #

data/lib/mailkube/events/contexts.rb

@@ -63,10 +63,19 @@ module Mailkube
     # These nested keys are camelCase on the wire, unlike every other block here. The SDK mirrors
     # the server rather than normalizing it.
     class EngagementContext < Node
-      # @return [String] the opening client's IP address (wire key `ipAddress`).
+      # The three connection accessors return nil unless the sending domain elected to record the
+      # field, which is off by default. The server omits the key rather than sending a blank, so
+      # nil here means "the sender did not record this" and never "the sender recorded an empty
+      # value".
+      #
+      # @return [String, nil] the opening client's IP address (wire key `ipAddress`).
       def ip_address = self["ipAddress"]
-      # @return [String] the opening client's user agent (wire key `userAgent`).
+      # @return [String, nil] the opening client's user agent (wire key `userAgent`).
       def user_agent = self["userAgent"]
+      # Elected together with {#ip_address}, but can still be nil when the address was recorded:
+      # it is resolved at the edge and is not available on every path.
+      # @return [String, nil] the two-letter country the address resolves to.
+      def country = self["country"]
       # @return [String] when the interaction was recorded.
       def timestamp = self["timestamp"]
     end

data/lib/mailkube/version.rb

@@ -11,5 +11,5 @@ module Mailkube
   # semantic-release rewrites this line **in the release runner** just before the gem is built, and
   # commits nothing back to `main` (see `.rules/RELEASE.md`). So a checkout reports `0.0.0` and an
   # installed gem reports the real version: that is intended, not a bug to fix by hardcoding one.
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/mailkube/webhooks.rb

@@ -5,7 +5,7 @@ require "time"
 require "json"
 
 module Mailkube
-  # Webhook signature verification.
+  # Webhook signature verification and event parsing.
   #
   # Verification is pure and dependency-free: no client instance, no configuration, so you call
   # it directly inside your webhook handler.
@@ -89,6 +89,39 @@ module Mailkube
       parse_event(verify_signature(payload: payload, headers: headers, secret: secret, tolerance: tolerance))
     end
 
+    # Produce the `X-Webhook-Sig` value for a payload, the mirror of {verify_signature}.
+    #
+    # This exists so anything that produces a delivery — a fixture, a local replay tool, a fake
+    # endpoint in your own suite — computes the signature the way this module verifies it. A
+    # reimplementation from the docs above agrees with its author's reading of the prose rather
+    # than with this SDK, and the two drift silently. Production code verifies; it does not sign.
+    #
+    # Freshness is not this method's concern: it signs the timestamp it is given, so replaying an
+    # old capture reproduces the original signature exactly.
+    #
+    # @param id [String] the `X-Webhook-Id` value.
+    # @param timestamp [String] the `X-Webhook-Ts` value, ISO-8601.
+    # @param payload [String] the raw body that will be sent.
+    # @param secret [String] the endpoint's signing secret.
+    # @return [String] the header value, including the `sha256=` prefix.
+    def self.sign(id:, timestamp:, payload:, secret:)
+      SIGNATURE_PREFIX + signature_hex(id, timestamp, payload, secret)
+    end
+
+    # Return the hex HMAC-SHA256 over the contract's signed input.
+    #
+    # One implementation, so signing and verifying cannot disagree.
+    #
+    # @param id [String] the `X-Webhook-Id` value.
+    # @param timestamp [String] the `X-Webhook-Ts` value.
+    # @param payload [String] the raw body.
+    # @param secret [String] the signing secret.
+    # @return [String] the hex digest, without the prefix.
+    def self.signature_hex(id, timestamp, payload, secret)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, "#{id}.#{timestamp}.#{payload}")
+    end
+    private_class_method :signature_hex
+
     # Normalize a header mapping to lowercase, dashed names.
     #
     # This accepts more than a Hash on purpose. `ActionDispatch::Http::Headers` is `Enumerable`
@@ -139,7 +172,7 @@ module Mailkube
     # @param secret [String] the signing secret.
     # @raise [SignatureVerificationError] when the digests differ.
     def self.check_signature(payload, id, timestamp, signature, secret)
-      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{id}.#{timestamp}.#{payload}")
+      expected = signature_hex(id, timestamp, payload, secret)
       provided = signature.delete_prefix(SIGNATURE_PREFIX)
       # Length is compared first because `fixed_length_secure_compare` raises on a mismatch, and
       # the length of a hex digest is not a secret.

data/sig/mailkube/client.rbs

@@ -3,7 +3,8 @@ module Mailkube
     attr_reader emails: Resources::Emails
     attr_reader scheduled_emails: Resources::ScheduledEmails
 
-    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?) -> void
+    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?,
+                     ?user_agent_suffix: String?) -> void
     def base_url: () -> String
   end
 end

data/sig/mailkube/config.rbs

@@ -7,8 +7,9 @@ module Mailkube
     attr_reader base_url: String
     attr_reader timeout: Numeric
 
-    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric) -> void
+    def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?user_agent_suffix: String?) -> void
     def default_headers: () -> Hash[String, String]
+    def user_agent: () -> String
     def build_url: (String, ?Hash[String, String]) -> String
   end
 end

data/sig/mailkube/events/contexts.rbs

@@ -22,8 +22,9 @@ module Mailkube
     end
 
     class EngagementContext < Node
-      def ip_address: () -> String
-      def user_agent: () -> String
+      def ip_address: () -> String?
+      def user_agent: () -> String?
+      def country: () -> String?
       def timestamp: () -> String
     end
 

data/sig/mailkube/webhooks.rbs

@@ -12,6 +12,8 @@ module Mailkube
     def self.parse_event: (String) -> Events::Event
     def self.verify: (payload: String, headers: _HeaderMap, secret: String,
                       ?tolerance: Integer) -> Events::Event
+    def self.sign: (id: String, timestamp: String, payload: String, secret: String) -> String
+    def self.signature_hex: (String, String, String, String) -> String
     def self.check_freshness: (String, Integer) -> void
     def self.check_signature: (String, String, String, String, String) -> void
     def self.normalize_headers: (_HeaderMap) -> Hash[String, String]

data/sig/mailkube.rbs

@@ -29,7 +29,8 @@ module Mailkube
     def request_json: (RequestSpec) -> Hash[String, untyped]
   end
 
-  def self.new: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?) -> Client
+  def self.new: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?,
+                 ?user_agent_suffix: String?) -> Client
   def self.error_class_for: (Integer) -> Class
 
   STATUS_ERRORS: Hash[Integer, Class]

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: mailkube
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
-- Mailtactic, Corp.
+- Mail Tactic Corporation
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z