mailkube 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afd85d0c480e7cff16fd2df6344b221acf946f644e97e7f9d7b33f2472ac5c51
-  data.tar.gz: 32f66b35b8f0e9631ca737ffcc1c51b6e1b98be6746f9a1d4019c623ce24e9ff
+  metadata.gz: c5efd02b82c63ffe38f919d2fa9a5141aa5c7e10a893ddc33ecdf6227d0eb379
+  data.tar.gz: 6cafb691b11923b959de7be667353c0f410183fa72dcb91fa538a40f5ad2eda9
 SHA512:
-  metadata.gz: e7d1a7c1e83031bbd5fca5533ecff6635361726c401b20112e856d3b62ca62211764c3498501a36d9907a6de7a2b9d0d0304d0002a725f4f4c8c013c6e3a35d0
-  data.tar.gz: 9c7ecae8c33e302db1a539d4fbc88ec46bd1b3edf60cda62820e7b4d3ae8d499d67f116736bec04a6445f50692dc3b7a76d108b2e209e9faa983eac9890a1a17
+  metadata.gz: b2b0bfab25b6a83378b6a943c1493af5ad98fd7046eb4baec3428bb93b4fbf536c376c737058baed3d0cf9a56c722e74809e79c306ee4dcf67d0b774d9b54640
+  data.tar.gz: c3d57c7e69b2ed05e6ab5472242d5309df53a4e0a33d83f0a473f0bf1f9164abca2c83e9fc4ed6eee936bf3440667adb373a8c8948b766c99ff81b4df9b227eb

data/README.md

@@ -7,6 +7,8 @@
 
 The official Ruby SDK for [mailkube](https://mailkube.com).
 
+Full product and API documentation: [docs.mailkube.com/sdks/ruby](https://docs.mailkube.com/sdks/ruby).
+
 Requires Ruby 3.4 or newer.
 
 ## Install
@@ -149,6 +151,28 @@ client.scheduled_emails.batches.cancel("welcome-2026-08")
 An unknown batch is a no-op reporting `canceled_count: 0` rather than a 404, so a count of zero is
 not a failure.
 
+## Your API key
+
+`client.credential.info` describes the key the client authenticates with: its domain,
+organization, source-IP allowlist, plan and send-quota usage.
+
+```ruby
+key = client.credential.info
+puts key.key_id, key.domain.name, key.organization.alias
+
+key.plan&.quotas&.each do |quota|
+  puts "#{quota.name}: #{quota.used} of #{quota.limit} in #{quota.period}"
+end
+```
+
+The key is checked exactly as a send checks it, so a key that cannot send raises
+`Mailkube::AuthenticationError` (`invalid_api_key`): calling `info` is how to verify a key. The call
+counts as a use of the key, and plan and quota figures can be up to 30 seconds old. `plan` is nil
+when the organization has no subscription, and a plan without a daily limit lists
+`emails_per_month` only. `remaining` counts recipients, not messages.
+
+The client keeps the key it was constructed with. To use another key, construct another client.
+
 ## Errors
 
 Every error descends from `Mailkube::Error`, so rescue the category you care about:
@@ -171,7 +195,8 @@ on the response line, which is what makes a failure traceable from your own logs
 Categories: `BadRequestError` (400), `AuthenticationError` (403), `NotFoundError` (404),
 `ConflictError` (409), `InvalidRequestError` (422), `RateLimitError` (429), `ServerError` (5xx),
 and `APIError` for anything else, which is also the parent of all of them. A transport failure
-raises `ConnectionError` and is deliberately **not** an API error.
+raises `ConnectionError` and is deliberately **not** an API error. Neither is a 2xx response whose
+body is not the shape the call expects: that raises the base `Mailkube::Error`.
 
 `Mailkube::ErrorName` lists the documented `name` values for discoverability. It is **not** a
 closed set: `error_name` stays a plain String, so a value this release has never heard of is
@@ -295,7 +320,7 @@ response body. If you want pooling, inject an adapter that pools — and make it
 These are covered by semantic versioning:
 
 - `Mailkube.new`, `Mailkube.enable_logging`
-- `client.emails`, `client.scheduled_emails` and their verbs
+- `client.emails`, `client.scheduled_emails`, `client.credential` and their verbs
 - the response models and `Mailkube::Attachment` / `Mailkube::Tag`
 - the error hierarchy and `Mailkube::ErrorName`
 - `Mailkube::Webhooks` and everything under `Mailkube::Events`
@@ -319,10 +344,14 @@ Runnable scripts in [`examples/`](examples/):
 - [`send_with_tags.rb`](examples/send_with_tags.rb) — tag a send for filtering and reporting
 - [`send_with_template.rb`](examples/send_with_template.rb) — send from a saved template
 - [`schedule_send.rb`](examples/schedule_send.rb) — schedule a send, then inspect the ack
+- [`list_scheduled_emails.rb`](examples/list_scheduled_emails.rb) — one page for the metadata,
+  then the lazy walk, read-only
 - [`manage_scheduled_emails.rb`](examples/manage_scheduled_emails.rb) — list, paginate, retrieve,
   reschedule and cancel
 - [`schedule_batch.rb`](examples/schedule_batch.rb) — schedule a batch, then move or cancel it as
   a unit
+- [`credential_info.rb`](examples/credential_info.rb) — describe the calling key, its plan and quota
+  usage
 - [`webhook_receiver_sinatra.rb`](examples/webhook_receiver_sinatra.rb) — verify and dispatch
   webhooks in Sinatra
 - [`webhook_receiver_rails.rb`](examples/webhook_receiver_rails.rb) — the same in Rails, including

data/lib/mailkube/client.rb

@@ -26,6 +26,8 @@ module Mailkube
     attr_reader :emails
     # @return [Resources::ScheduledEmails] the scheduled-emails namespace.
     attr_reader :scheduled_emails
+    # @return [Resources::Credential] the namespace for the API key this client authenticates with.
+    attr_reader :credential
 
     # Create a client, resolving configuration from the arguments then the environment.
     #
@@ -49,6 +51,7 @@ module Mailkube
       @config = config
       @emails = Resources::Emails.new(transport)
       @scheduled_emails = Resources::ScheduledEmails.new(transport)
+      @credential = Resources::Credential.new(transport)
       freeze
     end
 

data/lib/mailkube/resources/credential.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Mailkube
+  module Resources
+    # The client's own credential, reached as `client.credential`.
+    #
+    # It describes the API key the client was constructed with and holds no setter: a client takes
+    # its key at construction and keeps it, which is what makes one instance safe to share across
+    # threads. A second key is a second client.
+    class Credential
+      # @param transport [#request_json] the transport performing this resource's requests.
+      def initialize(transport)
+        @transport = transport
+        freeze
+      end
+
+      # Describe the API key this client authenticates with: its domain, organization, source-IP
+      # allowlist, plan and send-quota usage.
+      #
+      # The key is checked exactly as a send checks it, so a key that cannot send raises
+      # {AuthenticationError} (`invalid_api_key`), which also makes this the way to verify a key.
+      # The call counts as a use of the key. Plan and quota figures can be up to 30 seconds old.
+      #
+      # @return [APIKey] the calling API key.
+      # @raise [APIError] on any non-2xx response.
+      # @raise [ConnectionError] on a transport failure or timeout.
+      def info
+        APIKey.from(@transport.request_json(RequestSpec.new(path: "api-keys/me", method: "GET")))
+      end
+    end
+  end
+end

data/lib/mailkube/transport.rb

@@ -80,12 +80,14 @@ module Mailkube
     # @param spec [RequestSpec] the request to perform.
     # @return [Email] the accepted-send result.
     # @raise [APIError] on any non-2xx response.
+    # @raise [Error] on a 2xx body without an `id`: a body of the wrong shape is an SDK-level
+    #   failure, not an API error.
     # @raise [ConnectionError] on a transport failure or timeout.
     def send_email(spec)
       response = perform(spec)
       payload = decode(response.body)
       id = payload["id"]
-      raise APIError.new("expected a JSON body with an 'id'", status_code: response.status) unless id.is_a?(String)
+      raise Error, "expected a JSON body with an 'id' from a #{response.status} response" unless id.is_a?(String)
 
       Email.new(
         id: id,
@@ -111,12 +113,14 @@ module Mailkube
     #
     # @param spec [RequestSpec] the request to perform.
     # @return [Hash{String => Object}] the decoded 2xx body.
-    # @raise [APIError] on any non-2xx response, or a 2xx body that is not a JSON object.
+    # @raise [APIError] on any non-2xx response.
+    # @raise [Error] on a 2xx body that is not a JSON object: a body of the wrong shape is an
+    #   SDK-level failure, not an API error.
     # @raise [ConnectionError] on a transport failure or timeout.
     def request_json(spec)
       response = perform(spec)
       payload = decode_object(response.body)
-      raise APIError.new("expected a JSON object body", status_code: response.status) if payload.nil?
+      raise Error, "expected a JSON object body from a #{response.status} response" if payload.nil?
 
       payload
     end

data/lib/mailkube/types/api_key.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Mailkube
+  # The API key the client authenticates with, as it describes itself.
+  #
+  # Returned by {Resources::Credential#info}. Timestamps stay the verbatim ISO-8601 strings the
+  # server sent; call `Time.iso8601` yourself if you want objects. Plan and quota figures can be up
+  # to 30 seconds old.
+  class APIKey < Data.define(:object, :key_id, :name, :description, :created_at, :last_auth_at,
+                             :allowed_source_ips, :domain, :organization, :plan)
+    # @param object [String] the resource discriminator, always `api_key`.
+    # @param key_id [String] the key's public identifier.
+    # @param name [String] the key's name.
+    # @param description [String, nil] the key's description.
+    # @param created_at [String] when the key was created.
+    # @param last_auth_at [String, nil] the key's last successful authentication, this call included.
+    # @param allowed_source_ips [Array<String>] the CIDR networks the key may be used from; empty
+    #   means any address.
+    # @param domain [APIKeyDomain] the sending domain the key belongs to.
+    # @param organization [APIKeyOrganization] the organization owning the domain.
+    # @param plan [APIKeyPlan, nil] the organization's plan, nil when it has no subscription.
+    def initialize(key_id:, object: "api_key", name: "", description: nil, created_at: "", last_auth_at: nil,
+                   allowed_source_ips: [], domain: APIKeyDomain.new, organization: APIKeyOrganization.new,
+                   plan: nil)
+      super
+    end
+
+    # `plan` is the one field the API sends as null, meaning "no subscription", so it is decoded
+    # only when present: an empty plan built from defaults would look like a real one.
+    #
+    # @param payload [Hash{String => Object}] the decoded `api_key` object.
+    # @return [APIKey] the model.
+    def self.from(payload)
+      new(key_id: payload["key_id"], object: payload["object"] || "api_key", name: payload["name"] || "",
+          description: payload["description"], created_at: payload["created_at"] || "",
+          last_auth_at: payload["last_auth_at"], allowed_source_ips: payload["allowed_source_ips"] || [],
+          domain: APIKeyDomain.from(payload["domain"]), organization: APIKeyOrganization.from(payload["organization"]),
+          plan: payload["plan"] && APIKeyPlan.from(payload["plan"]))
+    end
+  end
+
+  # The sending domain an API key belongs to.
+  class APIKeyDomain < Data.define(:name)
+    # @param name [String] the domain name, e.g. `example.com`.
+    def initialize(name: "") = super
+
+    # @param payload [Hash{String => Object}, nil] the decoded `domain` block.
+    # @return [APIKeyDomain] the model.
+    def self.from(payload) = new(name: (payload || {})["name"] || "")
+  end
+
+  # The organization owning an API key's domain.
+  class APIKeyOrganization < Data.define(:name, :alias)
+    # @param name [String] the organization's display name.
+    # @param alias [String] the organization's short alias.
+    def initialize(name: "", alias: "") = super
+
+    # @param payload [Hash{String => Object}, nil] the decoded `organization` block.
+    # @return [APIKeyOrganization] the model.
+    def self.from(payload)
+      block = payload || {}
+      new(name: block["name"] || "", alias: block["alias"] || "")
+    end
+  end
+
+  # The organization's plan, its status and its send quotas.
+  #
+  # `status` is a server-controlled string, deliberately not an enum. A plan without a daily limit
+  # lists the monthly quota only: an absent quota is a missing limit, never a limit of zero.
+  class APIKeyPlan < Data.define(:code, :name, :status, :quotas)
+    # @param code [String] the plan's UUID.
+    # @param name [String] the plan's name.
+    # @param status [String] the subscription status, e.g. `active`.
+    # @param quotas [Array<APIKeyQuota>] the send quotas the plan carries.
+    def initialize(code: "", name: "", status: "", quotas: []) = super
+
+    # @param payload [Hash{String => Object}] the decoded `plan` block.
+    # @return [APIKeyPlan] the model.
+    def self.from(payload)
+      new(code: payload["code"] || "", name: payload["name"] || "", status: payload["status"] || "",
+          quotas: (payload["quotas"] || []).map { |quota| APIKeyQuota.from(quota) })
+    end
+  end
+
+  # One send quota of the plan: its limit and what the current period has used, in recipients.
+  class APIKeyQuota < Data.define(:name, :limit, :used, :remaining, :period)
+    # @param name [String] which quota, e.g. `emails_per_day` or `emails_per_month`; a
+    #   server-controlled string, deliberately not an enum.
+    # @param limit [Integer] the plan's limit for the period.
+    # @param used [Integer] recipients sent to so far in the period.
+    # @param remaining [Integer] recipients left in the period.
+    # @param period [String] the UTC day (`2026-10-19`) or month (`2026-10`) the figures count.
+    def initialize(name: "", limit: 0, used: 0, remaining: 0, period: "") = super
+
+    # @param payload [Hash{String => Object}] one decoded quota.
+    # @return [APIKeyQuota] the model.
+    def self.from(payload)
+      new(name: payload["name"] || "", limit: payload["limit"] || 0, used: payload["used"] || 0,
+          remaining: payload["remaining"] || 0, period: payload["period"] || "")
+    end
+  end
+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.2.1"
+  VERSION = "1.3.0"
 end

data/lib/mailkube.rb

@@ -6,6 +6,7 @@ require_relative "mailkube/logging"
 require_relative "mailkube/types"
 require_relative "mailkube/types/scheduled_emails"
 require_relative "mailkube/types/scheduled_acks"
+require_relative "mailkube/types/api_key"
 require_relative "mailkube/serialization"
 require_relative "mailkube/config"
 require_relative "mailkube/transport"
@@ -13,6 +14,7 @@ require_relative "mailkube/net_http_adapter"
 require_relative "mailkube/resources/emails"
 require_relative "mailkube/resources/scheduled_email_requests"
 require_relative "mailkube/resources/scheduled_emails"
+require_relative "mailkube/resources/credential"
 require_relative "mailkube/client"
 require_relative "mailkube/events/node"
 require_relative "mailkube/events/contexts"

data/sig/mailkube/client.rbs

@@ -2,6 +2,7 @@ module Mailkube
   class Client
     attr_reader emails: Resources::Emails
     attr_reader scheduled_emails: Resources::ScheduledEmails
+    attr_reader credential: Resources::Credential
 
     def initialize: (?api_key: String?, ?base_url: String?, ?timeout: Numeric, ?http: _HttpAdapter?,
                      ?user_agent_suffix: String?) -> void

data/sig/mailkube/resources/credential.rbs

@@ -0,0 +1,8 @@
+module Mailkube
+  module Resources
+    class Credential
+      def initialize: (_JsonTransport) -> void
+      def info: () -> APIKey
+    end
+  end
+end

data/sig/mailkube/types/api_key.rbs

@@ -0,0 +1,57 @@
+module Mailkube
+  # Declared the same way as every other model; see `sig/mailkube/types.rbs`.
+  class APIKey
+    attr_reader object: String
+    attr_reader key_id: String
+    attr_reader name: String
+    attr_reader description: String?
+    attr_reader created_at: String
+    attr_reader last_auth_at: String?
+    attr_reader allowed_source_ips: Array[String]
+    attr_reader domain: APIKeyDomain
+    attr_reader organization: APIKeyOrganization
+    attr_reader plan: APIKeyPlan?
+
+    def initialize: (key_id: String, ?object: String, ?name: String, ?description: String?,
+                     ?created_at: String, ?last_auth_at: String?, ?allowed_source_ips: Array[String],
+                     ?domain: APIKeyDomain, ?organization: APIKeyOrganization, ?plan: APIKeyPlan?) -> void
+    def self.from: (Hash[String, untyped]) -> APIKey
+  end
+
+  class APIKeyDomain
+    attr_reader name: String
+
+    def initialize: (?name: String) -> void
+    def self.from: (Hash[String, untyped]?) -> APIKeyDomain
+  end
+
+  class APIKeyOrganization
+    attr_reader name: String
+    # Declared as `def` because `alias` is a keyword, as `PageSteps#next` is.
+    def alias: () -> String
+
+    def initialize: (?name: String, ?alias: String) -> void
+    def self.from: (Hash[String, untyped]?) -> APIKeyOrganization
+  end
+
+  class APIKeyPlan
+    attr_reader code: String
+    attr_reader name: String
+    attr_reader status: String
+    attr_reader quotas: Array[APIKeyQuota]
+
+    def initialize: (?code: String, ?name: String, ?status: String, ?quotas: Array[APIKeyQuota]) -> void
+    def self.from: (Hash[String, untyped]) -> APIKeyPlan
+  end
+
+  class APIKeyQuota
+    attr_reader name: String
+    attr_reader limit: Integer
+    attr_reader used: Integer
+    attr_reader remaining: Integer
+    attr_reader period: String
+
+    def initialize: (?name: String, ?limit: Integer, ?used: Integer, ?remaining: Integer, ?period: String) -> void
+    def self.from: (Hash[String, untyped]) -> APIKeyQuota
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailkube
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Mail Tactic Corporation
@@ -29,12 +29,14 @@ files:
 - lib/mailkube/events/registry.rb
 - lib/mailkube/logging.rb
 - lib/mailkube/net_http_adapter.rb
+- lib/mailkube/resources/credential.rb
 - lib/mailkube/resources/emails.rb
 - lib/mailkube/resources/scheduled_email_requests.rb
 - lib/mailkube/resources/scheduled_emails.rb
 - lib/mailkube/serialization.rb
 - lib/mailkube/transport.rb
 - lib/mailkube/types.rb
+- lib/mailkube/types/api_key.rb
 - lib/mailkube/types/scheduled_acks.rb
 - lib/mailkube/types/scheduled_emails.rb
 - lib/mailkube/version.rb
@@ -50,12 +52,14 @@ files:
 - sig/mailkube/events/registry.rbs
 - sig/mailkube/logging.rbs
 - sig/mailkube/net_http_adapter.rbs
+- sig/mailkube/resources/credential.rbs
 - sig/mailkube/resources/emails.rbs
 - sig/mailkube/resources/scheduled_email_requests.rbs
 - sig/mailkube/resources/scheduled_emails.rbs
 - sig/mailkube/serialization.rbs
 - sig/mailkube/transport.rbs
 - sig/mailkube/types.rbs
+- sig/mailkube/types/api_key.rbs
 - sig/mailkube/types/scheduled_acks.rbs
 - sig/mailkube/types/scheduled_emails.rbs
 - sig/mailkube/webhooks.rbs