sendmux-core 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ec69806267556e76727d816bb6d01054bc5c77434a04596d02975252059ab2a
+  data.tar.gz: a1872633a358fbd8c9d63f62e28d1ff4a9ef593ace894586fa3d824b6605c597
+SHA512:
+  metadata.gz: a0e6497dc16e4b7900822a2f95c773c6ca8d555dc06eb10ac421646622ec9fc9f351768df70d2ade31553ef45711892f8ced4ea5981adc19399d42700a64ef37
+  data.tar.gz: 7540b87b27243eb36500d0afb1659162e76afe2aebb3f59f3d48aa7387b2f63203d0377297dc1c01d1412257301fc48d645b6246ba7f9f92675f68e3f522d6df

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0 (2026-06-02)
+
+
+### Features
+
+* **ruby:** add generated SDK packages ([f097fdf](https://github.com/Sendmux/sendmux-sdk/commit/f097fdf6afcbc2a048d9fdb1c9a669fff2a7ca4f))
+
+## 1.0.0
+
+- Initial Ruby core helper package.

data/README.md

@@ -0,0 +1,3 @@
+# sendmux-core
+
+Shared authentication, retry, pagination, header, and error helpers for the Sendmux Ruby SDK packages.

data/lib/sendmux/core/api_key_surface.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Sendmux
+  module Core
+    module ApiKeySurface
+      ROOT = 'root'
+      MAILBOX = 'mailbox'
+    end
+  end
+end

data/lib/sendmux/core/auth.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Sendmux
+  module Core
+    class Auth
+      ROOT_PREFIX = 'smx_root_'
+      MAILBOX_PREFIX = 'smx_mbx_'
+
+      def self.configure_bearer(configuration, api_key, expected_surface, base_url: nil)
+        assert_api_key_surface(api_key, expected_surface)
+        unless configuration.respond_to?(:access_token=)
+          raise ArgumentError, 'Generated configuration does not support bearer access tokens'
+        end
+
+        configuration.access_token = api_key
+        configure_base_url(configuration, base_url) if base_url && !base_url.empty?
+        configuration
+      end
+
+      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
+
+        raise ArgumentError, "Expected a #{expected_surface} API key, received a #{actual} API key"
+      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)
+
+        nil
+      end
+
+      def self.configure_base_url(configuration, base_url)
+        uri = URI(base_url)
+        raise ArgumentError, 'base_url must include a scheme and host' unless uri.scheme && uri.host
+
+        configuration.scheme = uri.scheme
+        configuration.host = uri.host
+        configuration.base_path = uri.path
+        configuration.ignore_operation_servers = true if configuration.respond_to?(:ignore_operation_servers=)
+      end
+    end
+  end
+end

data/lib/sendmux/core/errors.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Sendmux
+  module Core
+    class ApiError < StandardError
+      attr_reader :status, :code, :request_id, :param, :retryable, :errors, :response_body, :response_headers
+
+      def initialize(status:, code:, message:, retryable:, request_id: nil, param: nil, errors: nil,
+                     response_body: nil, response_headers: {})
+        super(message)
+        @status = status
+        @code = code
+        @request_id = request_id
+        @param = param
+        @retryable = retryable
+        @errors = errors
+        @response_body = response_body
+        @response_headers = response_headers
+      end
+    end
+
+    class ErrorMapper
+      def self.map(error)
+        return error if error.is_a?(ApiError)
+
+        headers = normalise_headers(error.respond_to?(:response_headers) ? error.response_headers : {})
+        body = error.respond_to?(:response_body) ? error.response_body : nil
+        payload = payload_from(body)
+        detail = hash_at(payload, 'error') || {}
+        status = status_from(error)
+
+        ApiError.new(
+          status: status,
+          code: string_at(detail, 'code') || 'api_error',
+          message: string_at(detail, 'message') || error.message || 'Sendmux API request failed',
+          retryable: retryable(detail, status),
+          request_id: request_id(payload, headers),
+          param: string_at(detail, 'param'),
+          errors: detail['errors'],
+          response_body: body,
+          response_headers: headers
+        )
+      end
+
+      def self.status_from(error)
+        return error.code if error.respond_to?(:code) && error.code.is_a?(Integer) && error.code.positive?
+
+        nil
+      end
+
+      def self.payload_from(body)
+        return nil unless body.is_a?(String) && !body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def self.request_id(payload, headers)
+        string_at(hash_at(payload, 'meta'), 'request_id') || header(headers, 'x-request-id')
+      end
+
+      def self.normalise_headers(headers)
+        return {} unless headers.respond_to?(:each)
+
+        headers.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value.is_a?(Array) ? value.join(', ') : value.to_s
+        end
+      end
+
+      def self.hash_at(value, key)
+        child = value[key] if value.is_a?(Hash)
+        child.is_a?(Hash) ? child : nil
+      end
+
+      def self.string_at(value, key)
+        child = value[key] if value.is_a?(Hash)
+        child.is_a?(String) && !child.empty? ? child : nil
+      end
+
+      def self.bool_at(value, key)
+        child = value[key] if value.is_a?(Hash)
+        [true, false].include?(child) ? child : nil
+      end
+
+      def self.retryable(detail, status)
+        explicit = bool_at(detail, 'retryable')
+        explicit.nil? ? default_retryable?(status) : explicit
+      end
+
+      def self.header(headers, name)
+        pair = headers.find { |key, _value| key.downcase == name }
+        pair&.last
+      end
+
+      def self.default_retryable?(status)
+        status == 429 || (status.is_a?(Integer) && status >= 500)
+      end
+    end
+  end
+end

data/lib/sendmux/core/headers.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Sendmux
+  module Core
+    module Headers
+      def self.idempotency_key(value)
+        { idempotency_key: value }
+      end
+
+      def self.if_match(value)
+        { if_match: value }
+      end
+
+      def self.if_none_match(value)
+        { if_none_match: value }
+      end
+
+      def self.conditional(if_match: nil, if_none_match: nil)
+        {}.tap do |headers|
+          headers[:if_match] = if_match if if_match
+          headers[:if_none_match] = if_none_match if if_none_match
+        end
+      end
+    end
+  end
+end

data/lib/sendmux/core/pagination.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Sendmux
+  module Core
+    class CursorPager
+      include Enumerable
+
+      def initialize(fetch_page, cursor_param: :cursor)
+        @fetch_page = fetch_page
+        @cursor_param = cursor_param
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        cursor = nil
+        loop do
+          response = @fetch_page.call(cursor ? { @cursor_param => cursor } : {})
+          extract_items(response).each(&block)
+          pagination = extract_pagination(response)
+          break unless bool_value?(pagination, 'has_more')
+
+          cursor = value(pagination, 'next_cursor')
+          break unless cursor
+        end
+      end
+
+      private
+
+      def extract_items(response)
+        data = value(response, 'data')
+        return data if data.is_a?(Array)
+
+        []
+      end
+
+      def extract_pagination(response)
+        meta = value(response, 'meta')
+        value(meta, 'pagination') || value(response, 'pagination') || {}
+      end
+
+      def bool_value?(object, name)
+        value(object, name) == true
+      end
+
+      def value(object, name)
+        return object[name] || object[name.to_sym] if object.is_a?(Hash)
+        return object.public_send(name) if object.respond_to?(name)
+
+        method = snake_to_camel(name)
+        object.public_send(method) if object.respond_to?(method)
+      end
+
+      def snake_to_camel(name)
+        parts = name.to_s.split('_')
+        parts.first + parts.drop(1).map(&:capitalize).join
+      end
+    end
+
+    def self.each_cursor(fetch_page, cursor_param: :cursor)
+      CursorPager.new(fetch_page, cursor_param: cursor_param)
+    end
+  end
+end

data/lib/sendmux/core/retry.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'faraday/retry'
+
+module Sendmux
+  module Core
+    module Retry
+      SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
+
+      def self.configure(configuration, retry_options = nil)
+        options = retry_options || RetryOptions.new
+        configuration.request(:retry, options.to_faraday_options)
+      end
+
+      def self.retryable_request?(env)
+        method = env[:method].to_s.upcase
+        return true if SAFE_METHODS.include?(method)
+
+        method == 'POST' && header(env[:request_headers] || {}, 'Idempotency-Key') && replayable_body?(env[:body])
+      end
+
+      def self.header(headers, name)
+        headers.find { |key, _value| key.to_s.downcase == name.downcase }&.last
+      end
+
+      def self.replayable_body?(body)
+        body.nil? || body.is_a?(String) || body.respond_to?(:rewind)
+      end
+    end
+  end
+end

data/lib/sendmux/core/retry_options.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Sendmux
+  module Core
+    class RetryOptions
+      RETRY_STATUSES = [408, 409, 425, 429, 500, 502, 503, 504].freeze
+
+      attr_reader :max_attempts, :base_delay_seconds, :max_delay_seconds, :jitter
+
+      def initialize(max_attempts: 3, base_delay_seconds: 0.25, max_delay_seconds: 5.0, jitter: true)
+        raise ArgumentError, 'max_attempts must be at least 1' if max_attempts < 1
+        if base_delay_seconds.negative? || max_delay_seconds.negative?
+          raise ArgumentError,
+                'retry delays must be non-negative'
+        end
+
+        @max_attempts = max_attempts
+        @base_delay_seconds = base_delay_seconds
+        @max_delay_seconds = max_delay_seconds
+        @jitter = jitter
+      end
+
+      def to_faraday_options
+        {
+          max: max_attempts - 1,
+          interval: base_delay_seconds,
+          max_interval: max_delay_seconds,
+          interval_randomness: jitter ? 0.5 : 0.0,
+          backoff_factor: 2,
+          methods: [],
+          retry_statuses: RETRY_STATUSES,
+          rate_limit_retry_header: 'Retry-After',
+          rate_limit_reset_header: 'X-RateLimit-Reset',
+          retry_if: ->(env, _exception) { Retry.retryable_request?(env) }
+        }
+      end
+    end
+  end
+end

data/lib/sendmux/core/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Sendmux
+  module Core
+    VERSION = '1.0.0'
+  end
+end

data/lib/sendmux/core.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'sendmux/core/api_key_surface'
+require 'sendmux/core/auth'
+require 'sendmux/core/errors'
+require 'sendmux/core/headers'
+require 'sendmux/core/pagination'
+require 'sendmux/core/retry'
+require 'sendmux/core/retry_options'
+require 'sendmux/core/version'

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: sendmux-core
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sendmux
+bindir: bin
+cert_chain: []
+date: 2026-06-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+email:
+- contact@sendmux.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/sendmux/core.rb
+- lib/sendmux/core/api_key_surface.rb
+- lib/sendmux/core/auth.rb
+- lib/sendmux/core/errors.rb
+- lib/sendmux/core/headers.rb
+- lib/sendmux/core/pagination.rb
+- lib/sendmux/core/retry.rb
+- lib/sendmux/core/retry_options.rb
+- lib/sendmux/core/version.rb
+homepage: https://github.com/Sendmux/sendmux-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Sendmux/sendmux-sdk
+  source_code_uri: https://github.com/Sendmux/sendmux-sdk/tree/main/packages/ruby/core
+  changelog_uri: https://github.com/Sendmux/sendmux-sdk/blob/main/packages/ruby/core/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Shared core helpers for Sendmux Ruby SDK packages.
+test_files: []