sendara 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4dc1a93353c4f74c9858a5c0456819cf09d8822bfc2d85e52380310800ab361
+  data.tar.gz: 01b26945825759c360b80e0fa82be866b76daeb75632a2aae4800b79eb7024a4
+SHA512:
+  metadata.gz: d2ff26bc76b493d4f12dabfeba8aecf5bee14192bc2bae40fc31ba7e85f6c4116b89b1d5293912869f8278588c3729e7ceecbc6e431bb7b5ef4793a835059b93
+  data.tar.gz: 1792963bb32043679409cc010483e1fb7a0cb9fa9af8019656cce503370ec1b8e6b8130dc47ed7d27f99c1b3c91d1d45026d6281fa9bb630a1742f3c93759f55

data/README.md

@@ -0,0 +1,313 @@
+# Sendara Ruby
+
+Email-first Ruby client for the [Sendara](https://sendara.dev) API: transactional email, broadcasts, contacts, templates, domains, and signed webhooks. Pure stdlib HTTP, zero runtime dependencies.
+
+Requires Ruby >= 3.0.
+
+## Installation
+
+```bash
+gem install sendara
+```
+
+Or with Bundler, add to your `Gemfile`:
+
+```ruby
+gem "sendara"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quickstart
+
+```ruby
+require "sendara"
+
+client = Sendara.new(ENV.fetch("SENDARA_API_KEY"))
+
+result = client.emails.send(
+  from: "you@yourdomain.com",
+  to: "customer@example.com",
+  subject: "Welcome to Acme",
+  html: "<h1>Hello</h1><p>Thanks for signing up.</p>",
+  text: "Hello — thanks for signing up."
+)
+
+puts result["id"]
+```
+
+`Sendara.new` accepts the API key as the first argument plus optional keywords:
+
+```ruby
+client = Sendara.new(
+  ENV.fetch("SENDARA_API_KEY"),
+  base_url: "https://api.sendara.dev",
+  timeout: 30,
+  max_retries: 2
+)
+```
+
+The client automatically attaches an `Idempotency-Key` to every write and retries idempotent requests with exponential backoff (honoring `Retry-After`).
+
+### Sending email
+
+`emails.send` is keyword-based. `from`, `to`, and `subject` are the essentials; provide `html`, `text`, or both:
+
+```ruby
+client.emails.send(
+  from: "you@yourdomain.com",
+  to: "customer@example.com",
+  subject: "Your receipt",
+  html: "<p>Thanks for your order.</p>",
+  text: "Thanks for your order.",
+  message_type: "transactional",
+  metadata: { "order_id" => "ord_123" }
+)
+```
+
+Send with a stored template instead of inline content:
+
+```ruby
+client.emails.send(
+  from: "you@yourdomain.com",
+  to: "customer@example.com",
+  subject: "Your receipt",
+  template_id: "tmpl_abc",
+  template_vars: { "name" => "Ada", "total" => "$42.00" }
+)
+```
+
+Pass your own `idempotency_key` to make retries safe across process restarts:
+
+```ruby
+client.emails.send(
+  from: "you@yourdomain.com",
+  to: "customer@example.com",
+  subject: "Your receipt",
+  html: "<p>Thanks!</p>",
+  idempotency_key: "receipt-ord_123"
+)
+```
+
+For full control over the request envelope, use `send_raw`, or `send_batch` for many messages in one call:
+
+```ruby
+client.emails.send_raw({
+  "channel" => "email",
+  "destination" => { "email" => "customer@example.com" },
+  "payload" => { "subject" => "Hi", "body_html" => "<p>Hi</p>" }
+})
+
+client.emails.send_batch([request_a, request_b, request_c])
+```
+
+## Broadcasts
+
+Broadcasts send one email to an audience — a saved list or an inline set of recipients.
+
+```ruby
+broadcast = client.broadcasts.create(
+  from_email: "you@yourdomain.com",
+  name: "June newsletter",
+  subject: "What's new in June",
+  body_html: "<h1>June</h1><p>Updates inside.</p>",
+  body_text: "June updates inside.",
+  audience_list_id: "list_123"
+)
+
+client.broadcasts.send(broadcast["id"])
+```
+
+Schedule for later, or send immediately on create with `send_now: true`:
+
+```ruby
+client.broadcasts.create(
+  from_email: "you@yourdomain.com",
+  name: "Launch",
+  subject: "We're live",
+  body_html: "<p>We launched.</p>",
+  recipients: ["a@example.com", "b@example.com"],
+  scheduled_at: "2026-07-01T09:00:00Z"
+)
+```
+
+List, fetch, cancel, and delete:
+
+```ruby
+client.broadcasts.list(limit: 20, offset: 0)
+client.broadcasts.get("bcast_123")
+client.broadcasts.cancel("bcast_123")
+client.broadcasts.delete("bcast_123")
+```
+
+To create-and-send an audience in a single request, use `bulk_send` (same arguments as `create`):
+
+```ruby
+client.broadcasts.bulk_send(
+  from_email: "you@yourdomain.com",
+  subject: "Flash sale",
+  body_html: "<p>24 hours only.</p>",
+  audience_list_id: "list_123",
+  send_now: true
+)
+```
+
+## Messages & pagination
+
+Fetch a single page with `messages.page`, which returns a `Sendara::MessagePage`:
+
+```ruby
+page = client.messages.page(status: "delivered", limit: 50)
+
+page.messages.each { |message| puts message["id"] }
+page.has_more?   # => true / false
+page.next_cursor # => cursor string or nil
+```
+
+`messages.each` iterates across **all** pages transparently, following the cursor for you:
+
+```ruby
+client.messages.each(status: "bounced") do |message|
+  puts "#{message['id']} → #{message['to']}"
+end
+```
+
+Called without a block it returns an `Enumerator`, so the full `Enumerable` API is available:
+
+```ruby
+recent = client.messages.each(channel: "email", limit: 100).first(10)
+```
+
+Filters: `channel`, `status`, `from`, `to`, `limit`, `cursor`. Fetch one message by id:
+
+```ruby
+client.messages.get("msg_123")
+```
+
+## Webhook verification
+
+Verify the signature on incoming webhooks with `Sendara::Webhooks.verify`. Pass the **raw request body** (not parsed), the request headers, and your signing secret. On success it returns the parsed event payload; on failure it raises `Sendara::WebhookVerificationError`.
+
+```ruby
+require "sendara"
+
+event = Sendara::Webhooks.verify(
+  raw_body,
+  request.headers,
+  ENV.fetch("SENDARA_WEBHOOK_SECRET")
+)
+
+event["type"] # => "email.delivered"
+```
+
+`verify` checks the `Sendara-Signature` HMAC and rejects requests whose `Sendara-Timestamp` is outside the tolerance window (default 300 seconds). Adjust it if needed:
+
+```ruby
+Sendara::Webhooks.verify(raw_body, headers, secret, tolerance: 600)
+```
+
+## Error handling
+
+API responses outside the 2xx range raise `Sendara::ApiError`, which exposes the HTTP `status`, the machine-readable `code`, the `request_id`, and `retry_after` (seconds, when the server sent it):
+
+```ruby
+begin
+  client.emails.send(
+    from: "you@yourdomain.com",
+    to: "customer@example.com",
+    subject: "Hi",
+    html: "<p>Hi</p>"
+  )
+rescue Sendara::ApiError => e
+  warn "#{e.code} (HTTP #{e.status}): #{e.message}"
+  warn "request_id=#{e.request_id}"
+  raise unless e.code == "rate_limited"
+  sleep(e.retry_after || 1)
+  retry
+end
+```
+
+The exception hierarchy, all under `Sendara::Error`:
+
+| Class | Raised when |
+| --- | --- |
+| `Sendara::ApiError` | The API returned a non-2xx response. Has `status`, `code`, `request_id`, `retry_after`. |
+| `Sendara::ConnectionError` | The request could not reach the API (DNS, TLS, socket). |
+| `Sendara::TimeoutError` | The request exceeded the configured timeout. Subclass of `ConnectionError`. |
+| `Sendara::WebhookVerificationError` | A webhook signature, timestamp, or body failed verification. |
+
+Rescue `Sendara::Error` to catch everything from the gem:
+
+```ruby
+rescue Sendara::Error => e
+  # any Sendara failure
+end
+```
+
+## Rails usage
+
+Build one client and share it. An initializer works well:
+
+```ruby
+# config/initializers/sendara.rb
+require "sendara"
+
+SENDARA = Sendara.new(Rails.application.credentials.sendara_api_key)
+```
+
+Send from anywhere, ideally off the request cycle in a background job:
+
+```ruby
+# app/jobs/welcome_email_job.rb
+class WelcomeEmailJob < ApplicationJob
+  queue_as :default
+
+  def perform(user)
+    SENDARA.emails.send(
+      from: "hello@yourdomain.com",
+      to: user.email,
+      subject: "Welcome to Acme",
+      html: WelcomeMailer.render(user),
+      idempotency_key: "welcome-#{user.id}"
+    )
+  rescue Sendara::ApiError => e
+    Rails.logger.error("sendara send failed: #{e.code} #{e.message} (#{e.request_id})")
+    raise
+  end
+end
+```
+
+Receiving webhooks — verify against the **raw** body, which Rails exposes via `request.raw_post`:
+
+```ruby
+# config/routes.rb
+post "/webhooks/sendara", to: "sendara_webhooks#receive"
+
+# app/controllers/sendara_webhooks_controller.rb
+class SendaraWebhooksController < ActionController::API
+  def receive
+    event = Sendara::Webhooks.verify(
+      request.raw_post,
+      request.headers,
+      Rails.application.credentials.sendara_webhook_secret
+    )
+
+    case event["type"]
+    when "email.delivered" then handle_delivered(event)
+    when "email.bounced"   then handle_bounced(event)
+    end
+
+    head :ok
+  rescue Sendara::WebhookVerificationError
+    head :bad_request
+  end
+end
+```
+
+## License
+
+MIT

data/lib/sendara/client.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module Sendara
+  class Client
+    DEFAULT_BASE_URL = "https://api.sendara.dev"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 2
+
+    RETRY_BASE_DELAY = 0.5
+    RETRY_MAX_DELAY = 8.0
+    WRITE_METHODS = %w[POST PUT PATCH].freeze
+    RETRIABLE_METHODS = %w[GET HEAD PUT DELETE].freeze
+
+    attr_reader :base_url, :timeout, :max_retries
+
+    def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES, transport: nil)
+      raise Error, "An API key is required" if api_key.nil? || api_key.to_s.empty?
+
+      @api_key = api_key.to_s
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @timeout = Integer(timeout)
+      @max_retries = [0, Integer(max_retries)].max
+      @transport = transport || method(:net_http_transport)
+      @resources = {}
+    end
+
+    def request(method, path, body: nil, query: {})
+      method = method.to_s.upcase
+      url = @base_url + path + build_query(query)
+
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json"
+      }
+
+      raw_body = nil
+      unless body.nil?
+        headers["Content-Type"] = "application/json"
+        raw_body = JSON.generate(body)
+      end
+
+      headers["Idempotency-Key"] = SecureRandom.uuid if WRITE_METHODS.include?(method)
+
+      idempotent = RETRIABLE_METHODS.include?(method)
+      max_attempts = idempotent ? @max_retries + 1 : 1
+
+      last_error = nil
+      attempt = 0
+
+      while attempt < max_attempts
+        begin
+          response = @transport.call(method, url, headers, raw_body, @timeout)
+        rescue ConnectionError => e
+          last_error = e
+          if attempt < max_attempts - 1
+            sleep_for(backoff_delay(attempt, nil))
+            attempt += 1
+            next
+          end
+          raise
+        end
+
+        status = response[:status].to_i
+        response_headers = response[:headers] || {}
+        response_body = response[:body].to_s
+
+        if status >= 200 && status < 300
+          return nil if status == 204 || response_body.empty?
+
+          return parse_json(response_body)
+        end
+
+        error = error_from_response(status, response_body, response_headers)
+        if idempotent && attempt < max_attempts - 1 && retriable_status?(status)
+          last_error = error
+          sleep_for(backoff_delay(attempt, retry_after_seconds(response_headers)))
+          attempt += 1
+          next
+        end
+
+        raise error
+      end
+
+      raise last_error || ConnectionError.new("Request failed after retries")
+    end
+
+    def emails       = resource(:emails, Resources::Emails)
+    def broadcasts   = resource(:broadcasts, Resources::Broadcasts)
+    def messages     = resource(:messages, Resources::Messages)
+    def contacts     = resource(:contacts, Resources::Contacts)
+    def lists        = resource(:lists, Resources::Lists)
+    def domains      = resource(:domains, Resources::Domains)
+    def templates    = resource(:templates, Resources::Templates)
+    def suppressions = resource(:suppressions, Resources::Suppressions)
+    def usage        = resource(:usage, Resources::Usage)
+    def api_keys     = resource(:api_keys, Resources::ApiKeys)
+    def billing      = resource(:billing, Resources::Billing)
+
+    def self.generate_idempotency_key
+      SecureRandom.uuid
+    end
+
+    private
+
+    def resource(name, klass)
+      @resources[name] ||= klass.new(self)
+    end
+
+    def parse_json(text)
+      JSON.parse(text)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def build_query(query)
+      return "" if query.nil? || query.empty?
+
+      pairs = query.each_with_object([]) do |(key, value), acc|
+        next if value.nil? || value == ""
+
+        value = value ? "true" : "false" if value == true || value == false
+        acc << [key.to_s, value.to_s]
+      end
+      return "" if pairs.empty?
+
+      "?" + URI.encode_www_form(pairs)
+    end
+
+    def retriable_status?(status)
+      status == 429 || status >= 500
+    end
+
+    def retry_after_seconds(headers)
+      value = header_value(headers, "retry-after")
+      return nil if value.nil?
+
+      return value.to_i if value.match?(/\A\d+\z/)
+
+      timestamp = (Time.httpdate(value).to_i rescue nil)
+      return nil if timestamp.nil?
+
+      [0, timestamp - Time.now.to_i].max
+    end
+
+    def backoff_delay(attempt, retry_after)
+      return retry_after.to_f if !retry_after.nil? && retry_after >= 0
+
+      exp = [RETRY_MAX_DELAY, RETRY_BASE_DELAY * (2**attempt)].min
+      half = exp / 2.0
+      half + (rand * half)
+    end
+
+    def sleep_for(seconds)
+      sleep(seconds) if seconds.positive?
+    end
+
+    def error_from_response(status, body, headers)
+      code = "error"
+      message = body.empty? ? "HTTP #{status}" : body
+
+      decoded = body.empty? ? nil : (JSON.parse(body) rescue nil)
+      if decoded.is_a?(Hash)
+        envelope = decoded["error"]
+        if envelope.is_a?(Hash)
+          code = (envelope["code"] || code).to_s
+          message = (envelope["message"] || message).to_s
+        elsif decoded.key?("message")
+          code = (decoded["code"] || code).to_s
+          message = decoded["message"].to_s
+        end
+      end
+
+      request_id = header_value(headers, "x-request-id")
+      retry_after_header = header_value(headers, "retry-after")
+      retry_after = retry_after_header&.match?(/\A\d+\z/) ? retry_after_header.to_i : nil
+
+      ApiError.new(message, status: status, code: code, request_id: request_id, retry_after: retry_after)
+    end
+
+    def header_value(headers, name)
+      lower = name.downcase
+      headers.each do |key, value|
+        next unless key.to_s.downcase == lower
+
+        value = value.first if value.is_a?(Array)
+        return value.nil? ? nil : value.to_s
+      end
+      nil
+    end
+
+    def net_http_transport(method, url, headers, body, timeout)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+      request_class = net_http_request_class(method)
+      request = request_class.new(uri.request_uri)
+      headers.each { |name, value| request[name] = value }
+      request.body = body unless body.nil?
+
+      response = http.request(request)
+
+      {
+        status: response.code.to_i,
+        headers: flatten_headers(response),
+        body: response.body.to_s
+      }
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+      raise TimeoutError, "Request timed out: #{e.message}"
+    rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+      raise ConnectionError, "Network request failed: #{e.message}"
+    end
+
+    def net_http_request_class(method)
+      {
+        "GET" => Net::HTTP::Get,
+        "HEAD" => Net::HTTP::Head,
+        "POST" => Net::HTTP::Post,
+        "PUT" => Net::HTTP::Put,
+        "PATCH" => Net::HTTP::Patch,
+        "DELETE" => Net::HTTP::Delete
+      }.fetch(method) { raise Error, "Unsupported HTTP method: #{method}" }
+    end
+
+    def flatten_headers(response)
+      headers = {}
+      response.each_header { |name, value| headers[name] = value }
+      headers
+    end
+  end
+end

data/lib/sendara/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Sendara
+  class Error < StandardError; end
+
+  class ApiError < Error
+    attr_reader :status, :code, :request_id, :retry_after
+
+    def initialize(message, status:, code: "error", request_id: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @code = code
+      @request_id = request_id
+      @retry_after = retry_after
+    end
+  end
+
+  class ConnectionError < Error; end
+
+  class TimeoutError < ConnectionError; end
+
+  class WebhookVerificationError < Error; end
+end

data/lib/sendara/generators/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Sendara
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Sendara initializer at config/initializers/sendara.rb"
+
+      def copy_initializer
+        template "sendara.rb", "config/initializers/sendara.rb"
+      end
+    end
+  end
+end

data/lib/sendara/generators/templates/sendara.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+Sendara.configure do |config|
+  config.api_key = ENV["SENDARA_API_KEY"]
+  # config.base_url = "https://api.sendara.dev"
+  # config.timeout = 30
+  # config.max_retries = 2
+end

data/lib/sendara/message_page.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Sendara
+  class MessagePage
+    include Enumerable
+
+    attr_reader :messages, :next_cursor
+
+    def initialize(messages:, next_cursor: nil)
+      @messages = messages
+      @next_cursor = next_cursor
+    end
+
+    def self.from_response(response)
+      response ||= {}
+      raw = response["messages"]
+      messages = raw.is_a?(Array) ? raw : []
+      cursor = response["next_cursor"]
+      cursor = nil unless cursor.is_a?(String) && !cursor.empty?
+
+      new(messages: messages, next_cursor: cursor)
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      messages.each(&block)
+    end
+
+    def has_more?
+      !next_cursor.nil?
+    end
+  end
+end