sendmux-core 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ec69806267556e76727d816bb6d01054bc5c77434a04596d02975252059ab2a
-  data.tar.gz: a1872633a358fbd8c9d63f62e28d1ff4a9ef593ace894586fa3d824b6605c597
+  metadata.gz: 6f7280607072f289f30f40b8a525dac73a3ba919d5947f88e50897727a79ea72
+  data.tar.gz: 4b30715c9fa1c545a0f51c15a8142b20b17b9654c7bcee1ab8253657d0b3c9a9
 SHA512:
-  metadata.gz: a0e6497dc16e4b7900822a2f95c773c6ca8d555dc06eb10ac421646622ec9fc9f351768df70d2ade31553ef45711892f8ced4ea5981adc19399d42700a64ef37
-  data.tar.gz: 7540b87b27243eb36500d0afb1659162e76afe2aebb3f59f3d48aa7387b2f63203d0377297dc1c01d1412257301fc48d645b6246ba7f9f92675f68e3f522d6df
+  metadata.gz: ebc3cc155bc1c79850c19428e2265986cd5d2fe29217acd77a68579c393e2c0cf3c73bf3171b51a1474e08b306d89d4d9f3186baec5051c8356e803fee3ebf0c
+  data.tar.gz: 1259a51bfa4f700cc23faf10b918de1b6deab56bc7d683277bf7c6f943002a4a644da1bb88de1acde68ec09c44313b2b2c2b33598ffa22b0e441be06b76828c2

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.1.0](https://github.com/Sendmux/sendmux-sdk/compare/ruby-core/v1.0.0...ruby-core/v1.1.0) (2026-07-01)
+
+
+### Features
+
+* allow owner-approved agent tokens for sending ([9d1cb7d](https://github.com/Sendmux/sendmux-sdk/commit/9d1cb7df3df5aef1f59a4990dc087178ba3a7b21))
+
 ## 1.0.0 (2026-06-02)
 
 

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sendmux
+
+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

@@ -1,3 +1,98 @@
 # sendmux-core
 
+[![Gem Version](https://badge.fury.io/rb/sendmux-core.svg)](https://rubygems.org/gems/sendmux-core)
+[![CI](https://github.com/Sendmux/sendmux-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Sendmux/sendmux-sdk/actions/workflows/ci.yml)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](https://github.com/Sendmux/sendmux-sdk/blob/main/LICENSE)
+
 Shared authentication, retry, pagination, header, and error helpers for the Sendmux Ruby SDK packages.
+
+## Documentation
+
+- Ruby SDK guide: https://sendmux.ai/docs/sdks/ruby
+- Source: https://github.com/Sendmux/sendmux-sdk/tree/main/packages/ruby/core
+- Changelog: https://github.com/Sendmux/sendmux-sdk/blob/main/packages/ruby/core/CHANGELOG.md
+
+## Requirements
+
+- Ruby 3.1 or newer.
+- A Sendmux API key when using the helpers with a surface client.
+
+## Installation
+
+```sh
+gem install sendmux-core
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem "sendmux-core", "~> 1.0"
+```
+
+## Usage
+
+The core package is installed automatically by the surface gems, but it can also be used directly when you need shared helpers.
+
+```ruby
+require "sendmux/core"
+
+surface = Sendmux::Core::Auth.assert_api_key_surface(
+  ENV.fetch("SENDMUX_ROOT_KEY"),
+  Sendmux::Core::ApiKeySurface::ROOT
+)
+
+puts surface
+```
+
+Use `Sendmux::Core::ApiKeySurface::ROOT` for root-key management clients, `Sendmux::Core::ApiKeySurface::SENDING` for send-capable `smx_mbx_` keys or owner-approved Sending-resource `smx_agent_` tokens, and `Sendmux::Core::ApiKeySurface::MAILBOX` for mailbox-compatible credentials. Mailbox-compatible credentials can start with `smx_mbx_` or `smx_agent_`.
+
+### Header helpers
+
+Generated Ruby operations accept option hashes. The header helpers return the option keys expected by those generated operations.
+
+```ruby
+headers = Sendmux::Core::Headers.idempotency_key("idem_123")
+etag = Sendmux::Core::Headers.if_match('W/"etag"')
+conditional = Sendmux::Core::Headers.conditional(if_none_match: 'W/"cached"')
+```
+
+### Cursor pagination
+
+`Sendmux::Core.each_cursor` wraps any generated list call that accepts a cursor option and returns Sendmux pagination metadata.
+
+```ruby
+pager = Sendmux::Core.each_cursor(lambda do |opts|
+  mailbox_client.mailbox_api.mailbox_list_messages(opts.merge(limit: 50))
+end)
+
+pager.each do |message|
+  puts message.id
+end
+```
+
+### Retries and errors
+
+Surface clients accept `Sendmux::Core::RetryOptions` and map generated errors to `Sendmux::Core::ApiError`.
+
+```ruby
+retry_options = Sendmux::Core::RetryOptions.new(max_attempts: 4)
+
+begin
+  # Pass retry_options: retry_options to any Sendmux surface client.
+  # Call a generated operation here.
+  nil
+rescue Sendmux::Core::ApiError => error
+  warn "#{error.code}: #{error.message} (request #{error.request_id})"
+end
+```
+
+Retries are enabled for safe requests and for idempotent `POST` requests that use an `Idempotency-Key`.
+
+## Support
+
+- Documentation: https://sendmux.ai/docs
+- Contact: contact@sendmux.ai
+
+## Licence
+
+MIT licence. See https://github.com/Sendmux/sendmux-sdk/blob/main/LICENSE.

data/lib/sendmux/core/api_key_surface.rb

@@ -5,6 +5,7 @@ module Sendmux
     module ApiKeySurface
       ROOT = 'root'
       MAILBOX = 'mailbox'
+      SENDING = 'sending'
     end
   end
 end

data/lib/sendmux/core/auth.rb

@@ -7,6 +7,7 @@ module Sendmux
     class Auth
       ROOT_PREFIX = 'smx_root_'
       MAILBOX_PREFIX = 'smx_mbx_'
+      AGENT_PREFIX = 'smx_agent_'
 
       def self.configure_bearer(configuration, api_key, expected_surface, base_url: nil)
         assert_api_key_surface(api_key, expected_surface)
@@ -21,15 +22,28 @@ module Sendmux
 
       def self.assert_api_key_surface(api_key, expected_surface)
         actual = surface_for(api_key)
-        raise ArgumentError, "Sendmux API keys must start with #{ROOT_PREFIX} or #{MAILBOX_PREFIX}" unless actual
-        return actual if actual == expected_surface
+        unless actual
+          raise ArgumentError,
+                "Sendmux API keys must start with #{ROOT_PREFIX}, #{MAILBOX_PREFIX}, or #{AGENT_PREFIX}"
+        end
+        return actual if compatible_surface?(api_key, actual, expected_surface)
 
         raise ArgumentError, "Expected a #{expected_surface} API key, received a #{actual} API key"
       end
 
+      def self.compatible_surface?(api_key, actual, expected_surface)
+        return true if actual == expected_surface
+        return true if expected_surface == ApiKeySurface::SENDING &&
+                       (api_key.start_with?(MAILBOX_PREFIX) || api_key.start_with?(AGENT_PREFIX))
+        return true if expected_surface == ApiKeySurface::MAILBOX && actual == ApiKeySurface::MAILBOX
+
+        false
+      end
+
       def self.surface_for(api_key)
         return ApiKeySurface::ROOT if api_key.start_with?(ROOT_PREFIX)
         return ApiKeySurface::MAILBOX if api_key.start_with?(MAILBOX_PREFIX)
+        return ApiKeySurface::MAILBOX if api_key.start_with?(AGENT_PREFIX)
 
         nil
       end

data/lib/sendmux/core/version.rb

@@ -2,6 +2,6 @@
 
 module Sendmux
   module Core
-    VERSION = '1.0.0'
+    VERSION = '1.1.0'
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sendmux-core
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Sendmux
 bindir: bin
 cert_chain: []
-date: 2026-06-02 00:00:00.000000000 Z
+date: 2026-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -50,6 +50,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- LICENSE
 - README.md
 - lib/sendmux/core.rb
 - lib/sendmux/core/api_key_surface.rb