sendmux-core

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

gem install sendmux-core

Or add it to your Gemfile:

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.

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.

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.

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.

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.