carriercrow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d4fb877ed489b1fdd80fd705182e6d4df63f6ddf5006a5c4eb05d01e721abc0
+  data.tar.gz: 6f92c5c83fa024d7ed01ad79170a469614692fc5f09b857b3f790b16eae0e2c5
+SHA512:
+  metadata.gz: 1eba931e96527f4688b58a7109ed9ca316a4c2a55551db128531ce5523817fe9033e5c021cef888b81a19a467a1bc98f0a8bf887bb5dccacaba071ed4fa2f477
+  data.tar.gz: e9425a60dae95a25d9dd270bfbe24adc2890831bfc764f9a9eeafea92d2b0fad49b7fb0e43100d19db008b875aa079d691b0a2bf745a360fddeadca5d1b2813b

data/LICENSE

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

@@ -0,0 +1,143 @@
+# Carrier Crow for Ruby
+
+Ruby 3.1+ client using `net/http`, with no runtime gem dependencies.
+
+```sh
+gem install carriercrow
+```
+
+Or in a Gemfile: `gem 'carriercrow'`.
+
+## Send and batch
+
+```ruby
+require 'carriercrow'
+require 'base64'
+
+client = CarrierCrow::Client.new # reads CARRIERCROW_API_KEY
+# Or: CarrierCrow::Client.new('ccm_test_example', base_url: 'http://localhost:3000')
+# OAuth access tokens (cco_...) also work; include app on OAuth sends.
+message = {
+  from: 'Northwind <orders@mail.example.com>',
+  to: ['customer@example.net'],
+  cc: 'accounts@example.net',
+  reply_to: 'support@example.com',
+  subject: 'Order received',
+  text: 'Thanks for your order.',
+  html: '<p>Thanks for your order.</p>',
+  headers: {'X-Order-Number' => '48213'},
+  attachments: [{filename: 'receipt.txt', content: Base64.strict_encode64('Paid'), content_type: 'text/plain'}],
+  message_id: 'order-48213', subscriber: 'customer-42', campaign: 'orders', app: 'orders'
+}
+result = client.emails.send(message, idempotency_key: 'order-48213')
+id = result['recipients'].first['id'] # String or nil in send and batch results
+if id.nil?
+  puts "Accepted; find it later by message_id: #{result['message_id']}"
+else
+  puts id
+end
+batch = client.emails.batch([message], idempotency_key: 'batch-48213')
+batch['results'].each do |item|
+  puts item['status'] # accepted or rejected; inspect error/code/field on rejection
+end
+```
+
+Responses are parsed Ruby hashes with string keys. Batch wraps the supplied
+array as `{"emails": [...]}`; individual rejections remain in `results`.
+
+## Read and page emails
+
+```ruby
+unless id.nil?
+  story = client.emails.get(id)
+  puts story['email']['status']
+  puts story['events']
+  puts story['updates']
+end
+page = client.emails.list(q: 'customer@example.net', status: ['delivered', 'bounced'],
+                          tenant: 'northwind', app: 'orders', days: 7, limit: 100)
+next_page = client.emails.list(before: page['next'], limit: 100) if page['next']
+client.emails.each(status: ['delivered'], days: 7).each do |email|
+  puts email['id']
+end
+```
+
+`emails.each` is a lazy enumerator that follows `next` as `before`, retaining
+filters. `list` returns a single page including `emails`, `next`, and `since`.
+
+## Domains
+
+```ruby
+domains = client.domains.list['domains']
+domain = client.domains.get(domains.first['id'])
+checked = client.domains.check(domain['id'])
+checked['records'].each { |record| puts "#{record['name']}: #{record['status']}" }
+```
+
+## Errors and retries
+
+```ruby
+begin
+  client.emails.send(message, retries: 2) # opts into a generated idempotency key
+rescue CarrierCrow::Error => error
+  warn "#{error.status} #{error.code}: #{error.message} (#{error.field})"
+  warn "Retry after #{error.retry_after} seconds" if error.retry_after
+end
+```
+
+`CarrierCrow::Error` carries `status`, `code`, `message`, `field`, and
+`retry_after` (seconds or nil). Network failures use `code: 'network_error'`
+and nil status. Webhook errors use `invalid_signature` or `invalid_payload`.
+
+Client options are `base_url`, `retries` (default 2 additional attempts),
+`timeout` (default 30 seconds for connection and reads), and an injectable
+`sleeper` callable. Reads and domain checks retry 429, 503, and network failures
+with exponential backoff and jitter, honoring a numeric `Retry-After` minimum.
+Other HTTP failures are raised immediately. Every request sends
+`User-Agent: carriercrow-ruby/0.1.0` and bearer authentication.
+
+Sends and batches without a key make exactly one attempt, even when client
+retries are configured. A supplied `idempotency_key` enables the client retry
+budget. Setting per-send `retries: 2` explicitly opts into a generated UUID when
+no key was supplied. The same key and serialized bytes are reused across all
+attempts; `retries: 0` disables retries. Keep your own stable key when you need
+safe retries across separate SDK calls. Keys must contain 1–255 characters.
+
+## Verify webhooks
+
+```ruby
+# Rack: read the original request bytes, before parsing or transforming them.
+raw_body = request.body.read
+payload = client.webhooks.verify(raw_body, request.env['HTTP_X_CC_SIGNATURE'],
+                                 ENV.fetch('CARRIERCROW_WEBHOOK_SECRET'))
+payload['events'].each { |event| puts event['id'] } # deduplicate on this ID
+
+# Deterministic testing can fix the clock and adjust the tolerance in seconds:
+payload = CarrierCrow::Webhooks.verify(raw_body, signature, 'whsec_test_example',
+                                      now: 1_805_047_200, tolerance: 300)
+```
+
+Verification uses the entire secret including `whsec_`, HMAC-SHA256 over the
+original timestamp plus `.` plus the exact body bytes, constant-time signature
+comparison, and an inclusive ±300-second window by default. Multiple `v1`
+signatures support secret rotation. Only after verification is JSON parsed.
+Invalid signatures, expired timestamps, or signed invalid JSON raise
+`CarrierCrow::Error`.
+
+## Tests
+
+From the repository root:
+
+```sh
+ruby -I ruby/lib ruby/test/client_test.rb
+```
+
+The minitest suite uses a local TCP HTTP mock and runs every case in
+`../test-vectors/webhooks.json`, including per-case clock/tolerance overrides.
+No API credentials or external API connection are required.
+
+Missing API keys raise `CarrierCrow::Error` with `missing_api_key` at construction. The client option `max_retry_after` defaults to 60 seconds; responses above it raise immediately with `retry_after` preserved. Repeated pagination cursors raise `invalid_response`. Webhook verification uses the first timestamp and accepts lowercase v1 hex only.
+
+A 202 means every recipient was accepted, including when an ID is null.
+A refused recipient fails the send with 422 or 429 and an indexed `field`
+such as `to[1]`; no recipients were sent.

data/lib/carriercrow.rb

@@ -0,0 +1,177 @@
+require 'net/http'
+require 'json'
+require 'openssl'
+require 'securerandom'
+require 'uri'
+
+module CarrierCrow
+  VERSION = '0.1.0'
+  class Error < StandardError
+    attr_reader :status, :code, :field, :retry_after
+
+    def initialize(message, status: nil, code: nil, field: nil, retry_after: nil)
+      super(message)
+      @status, @code, @field, @retry_after = status, code, field, retry_after
+    end
+  end
+
+  class Webhooks
+    def self.verify(body, signature, secret, tolerance: 300, now: Time.now.to_i)
+      parts = signature.to_s.split(',').map { |p| p.strip.split('=', 2) }
+      timestamps = parts.select { |k, _| k == 't' }.map(&:last)
+      timestamp = timestamps.first
+      valid = timestamp && timestamp.match?(/\A\d+\z/) && now.finite? && tolerance.finite? &&
+              tolerance >= 0 && (now - timestamp.to_i).abs <= tolerance
+      digest = OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp}.".b + body.b)
+      valid &&= parts.any? { |k, v|
+        k == 'v1' && v && v.match?(/\A[0-9a-f]{64}\z/) && OpenSSL.fixed_length_secure_compare(digest, v)
+      }
+      raise Error.new('Invalid webhook signature', code: 'invalid_signature') unless valid
+
+      parsed = JSON.parse(body)
+      unless parsed.is_a?(Hash) && parsed['webhook'].is_a?(String) &&
+             parsed['delivery'].is_a?(String) && parsed['events'].is_a?(Array)
+        raise Error.new('Invalid webhook envelope', code: 'invalid_payload')
+      end
+
+      parsed
+    rescue JSON::ParserError
+      raise Error.new('Invalid webhook JSON', code: 'invalid_payload')
+    end
+  end
+
+  class Client
+    attr_reader :emails, :domains, :webhooks
+
+    def initialize(api_key = ENV['CARRIERCROW_API_KEY'],
+                   base_url: 'https://api.mta.carriercrow.com', retries: 2, timeout: 30, max_retry_after: 60,
+                   sleeper: ->(seconds) { sleep(seconds) })
+      raise Error.new('API key is required', code: 'missing_api_key') if api_key.nil? || api_key.empty?
+      unless max_retry_after.is_a?(Numeric) && max_retry_after.finite? && max_retry_after >= 0
+        raise ArgumentError, 'max_retry_after must be finite and nonnegative'
+      end
+
+      @max_retry_after = max_retry_after
+      raise ArgumentError, 'retries must be a nonnegative integer' unless retries.is_a?(Integer) && retries >= 0
+
+      @api_key, @base_url, @retries, @timeout, @sleeper = api_key, base_url.sub(%r{/+\z}, ''), retries, timeout, sleeper
+      @emails, @domains, @webhooks = Emails.new(self), Domains.new(self), Webhooks
+    end
+
+    def request(method, path, query: {}, body: nil, idempotency_key: nil, retries: nil, send_request: false)
+      count = retries.nil? ? @retries : retries
+      raise ArgumentError, 'retries must be a nonnegative integer' unless count.is_a?(Integer) && count >= 0
+      if idempotency_key && (!idempotency_key.is_a?(String) || !idempotency_key.length.between?(1, 255))
+        raise ArgumentError, 'idempotency_key must contain 1–255 characters'
+      end
+
+      idempotency_key ||= SecureRandom.uuid if send_request && !retries.nil? && retries > 0
+      count = 0 if send_request && !idempotency_key
+      uri = URI(@base_url + path)
+      uri.query = URI.encode_www_form(query.flat_map { |k, v| Array(v).map { |value| [k, value] } }) unless query.empty?
+      encoded = body.nil? ? nil : JSON.generate(body)
+      attempt = 0
+      loop do
+        begin
+          request = Net::HTTP.const_get(method.capitalize).new(uri)
+          request['Authorization'] = "Bearer #{@api_key}"
+          request['User-Agent'] = "carriercrow-ruby/#{VERSION}"
+          request['Accept'] = 'application/json'
+          request['Idempotency-Key'] = idempotency_key if idempotency_key
+          request['Content-Type'] = 'application/json' if encoded
+          request.body = encoded
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == 'https'
+          http.open_timeout = http.read_timeout = @timeout
+          http.max_retries = 0
+          response = http.start { |connection| connection.request(request) }
+          status = response.code.to_i
+          data = begin
+            JSON.parse(response.body.to_s)
+          rescue JSON::ParserError
+            nil
+          end
+          if status.between?(200, 299)
+            unless data.is_a?(Hash)
+              raise Error.new('Invalid JSON response', status: status, code: 'invalid_response')
+            end
+
+            return data
+          end
+          retry_after = Float(response['Retry-After'], exception: false)
+          retry_after = nil unless retry_after && retry_after.finite? && retry_after >= 0
+          data = {} unless data.is_a?(Hash)
+          error = Error.new(data['error'] || "HTTP #{status}", status: status, code: data['code'],
+                                                               field: data['field'], retry_after: retry_after)
+          within_cap = retry_after.nil? || retry_after <= @max_retry_after
+          raise error unless [429, 503].include?(status) && attempt < count && within_cap
+        rescue IOError, SystemCallError, Timeout::Error, SocketError, OpenSSL::SSL::SSLError => cause
+          error = Error.new(cause.message, code: 'network_error')
+          raise error unless attempt < count
+
+          retry_after = nil
+        end
+        @sleeper.call([retry_after || 0, 0.25 * (2**attempt) * (0.5 + rand)].max)
+        attempt += 1
+      end
+    end
+  end
+
+  class Emails
+    def initialize(client)
+      @client = client
+    end
+
+    # Recipient IDs in send and batch results are String or nil.
+    def send(params, **options)
+      @client.request('post', '/v1/emails', body: params, send_request: true, **options)
+    end
+
+    def batch(emails, **options)
+      @client.request('post', '/v1/emails/batch', body: { emails: emails }, send_request: true, **options)
+    end
+
+    def get(id)
+      @client.request('get', "/v1/emails/#{URI.encode_www_form_component(id).gsub('+', '%20')}")
+    end
+
+    def list(query = {})
+      @client.request('get', '/v1/emails', query: query)
+    end
+
+    def each(query = {})
+      return enum_for(:each, query) unless block_given?
+
+      query = query.transform_keys(&:to_s)
+      seen = [query['before']].compact
+      loop do
+        page = list(query)
+        page.fetch('emails').each { |email| yield email }
+        break if page['next'].nil? || page['next'].empty?
+
+        raise Error.new('Repeated pagination cursor', code: 'invalid_response') if seen.include?(page['next'])
+
+        seen << page['next']
+        query = query.merge('before' => page['next'])
+      end
+    end
+  end
+
+  class Domains
+    def initialize(client)
+      @client = client
+    end
+
+    def list
+      @client.request('get', '/v1/domains')
+    end
+
+    def get(id)
+      @client.request('get', "/v1/domains/#{URI.encode_www_form_component(id).gsub('+', '%20')}")
+    end
+
+    def check(id)
+      @client.request('post', "/v1/domains/#{URI.encode_www_form_component(id).gsub('+', '%20')}/check")
+    end
+  end
+end

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: carriercrow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Frozen Crow Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Send email through Carrier Crow, read what happened to it, check your
+  domains and verify webhook signatures.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/carriercrow.rb
+homepage: https://github.com/Frozen-Crow/carrier-crow-sdks/tree/main/ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Frozen-Crow/carrier-crow-sdks
+  bug_tracker_uri: https://github.com/Frozen-Crow/carrier-crow-sdks/issues
+  rubygems_mfa_required: 'true'
+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.9
+specification_version: 4
+summary: Carrier Crow email API client
+test_files: []