relaygrid 0.1.1

data/lib/relaygrid/client.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module RelayGrid
+  # The entry point for every API call. Holds one Faraday connection and hands
+  # out the resource objects.
+  #
+  #   client = RelayGrid::Client.new                      # global configuration
+  #   client = RelayGrid::Client.new(api_key: "sk_other") # per-client override
+  #
+  # Instances are frozen once built, so a single client is safe to share across
+  # threads.
+  class Client
+    # Requests that may be replayed without changing server state. `notify` is
+    # deliberately absent: a blind retry sends the recipient a second real
+    # notification. See README ("Retries and idempotency").
+    IDEMPOTENT_METHODS = %i[get head options].freeze
+
+    RETRIABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    RETRIABLE_EXCEPTIONS = [
+      Faraday::ConnectionFailed,
+      Faraday::TimeoutError,
+      # Required for RETRIABLE_STATUSES to have any effect: faraday-retry signals
+      # a retriable status by raising this, and only retries exceptions listed
+      # here. Leaving it out silently disables status-based retries.
+      Faraday::RetriableResponse,
+    ].freeze
+
+    attr_reader :configuration
+
+    def initialize(configuration = nil, **overrides)
+      base = configuration || RelayGrid.configuration
+      @configuration = base.merge(overrides).validate!
+
+      # Built up front so the frozen instance never has to memoize lazily.
+      @connection = build_connection
+      @resources = {}
+
+      freeze
+    end
+
+    def notifications
+      resource(:notifications) { Resources::Notifications.new(self) }
+    end
+
+    def deliveries
+      resource(:deliveries) { Resources::Deliveries.new(self) }
+    end
+
+    def messages
+      resource(:messages) { Resources::Messages.new(self) }
+    end
+
+    def users
+      resource(:users) { Resources::Users.new(self) }
+    end
+
+    def channel_tokens
+      resource(:channel_tokens) { Resources::ChannelTokens.new(self) }
+    end
+
+    def message_templates
+      resource(:message_templates) { Resources::MessageTemplates.new(self) }
+    end
+
+    # Send a notification -- the one call the whole gem exists for.
+    # See Resources::Notifications#notify.
+    def notify(**kwargs)
+      notifications.notify(**kwargs)
+    end
+
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, body: {})
+      request(:post, path, body: body)
+    end
+
+    def patch(path, body: {})
+      request(:patch, path, body: body)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    attr_reader :connection
+
+    private
+
+    # Resource objects are stateless wrappers, so building one twice under a
+    # race is harmless -- which is what lets the client stay frozen.
+    def resource(name)
+      @resources[name] ||= yield
+    end
+
+    def build_connection
+      Faraday.new(url: configuration.base_url) do |conn|
+        conn.request :json
+        # Only idempotent verbs are replayed, so this can never duplicate a send.
+        conn.request :retry,
+                     max: configuration.max_retries,
+                     interval: 0.25,
+                     backoff_factor: 2,
+                     interval_randomness: 0.5,
+                     methods: IDEMPOTENT_METHODS,
+                     retry_statuses: RETRIABLE_STATUSES,
+                     exceptions: RETRIABLE_EXCEPTIONS
+        conn.response :json, content_type: /\bjson$/
+        conn.response :logger, configuration.logger, headers: false, bodies: false if configuration.logger
+
+        conn.headers["Authorization"] = "Bearer #{configuration.api_key}"
+        conn.headers["User-Agent"] = "relaygrid-ruby/#{RelayGrid::VERSION}"
+
+        conn.options.timeout = configuration.timeout
+        conn.options.open_timeout = configuration.open_timeout
+        # Certificates are always verified; ca_file only adds a trust anchor.
+        conn.ssl.ca_file = configuration.ca_file if configuration.ca_file
+
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    # Single funnel for every call: the one place that turns transport failures
+    # and non-2xx responses into the RelayGrid::Error hierarchy, so no Faraday
+    # exception ever escapes the gem.
+    def request(method, path, params: nil, body: nil)
+      response =
+        case method
+        when :get then connection.get(path, params || {})
+        when :post then connection.post(path, body || {})
+        when :patch then connection.patch(path, body || {})
+        when :delete then connection.delete(path)
+        else raise ArgumentError, "unsupported HTTP method: #{method}"
+        end
+
+      return response.body if response.success?
+
+      raise APIError.from_response(response.status, response.body)
+    rescue Faraday::RetriableResponse => e
+      # faraday-retry raises this instead of returning the response when the
+      # status is retriable but no attempts are left -- and immediately, without
+      # retrying, for a non-idempotent method like the POST behind `notify`.
+      # Convert it like any other unsuccessful response.
+      raise APIError.from_response(*retriable_response_parts(e))
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, "Request to #{path} timed out: #{e.message}"
+    rescue Faraday::SSLError => e
+      raise ConnectionError, "TLS handshake with #{configuration.base_url} failed: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Could not connect to #{configuration.base_url}: #{e.message}"
+    end
+
+    # Faraday::RetriableResponse carries either a Faraday::Response or a raw env
+    # hash depending on where it was raised.
+    def retriable_response_parts(error)
+      response = error.response
+
+      if response.respond_to?(:status)
+        [response.status, response.body]
+      else
+        [response[:status], response[:body]]
+      end
+    end
+  end
+end

data/lib/relaygrid/configuration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module RelayGrid
+  # Settings a Client reads. `RelayGrid.configure` sets the process-wide
+  # default; `Client.new(api_key: ...)` takes per-client overrides so a
+  # multi-account host app can talk to several accounts at once.
+  class Configuration
+    DEFAULT_BASE_URL = "https://relaygrid.dev"
+
+    # @return [String] account API key ("sk_...")
+    attr_accessor :api_key
+    # @return [String] API origin, e.g. "https://relaygrid.dev"
+    attr_accessor :base_url
+    # @return [Integer] seconds to wait for a response
+    attr_accessor :timeout
+    # @return [Integer] seconds to wait for the connection to open
+    attr_accessor :open_timeout
+    # @return [Logger, nil] when set, requests are logged (headers redacted)
+    attr_accessor :logger
+    # @return [String, nil] PEM bundle for a private CA. TLS certificates are
+    #   always verified; this only adds trust anchors (self-signed local dev,
+    #   internal deployments). There is deliberately no switch to turn
+    #   verification off -- this client carries an API key and relays push
+    #   channel tokens, so an unverified connection is never the right default.
+    attr_accessor :ca_file
+    # @return [String, nil] overrides the Action Cable URL derived from base_url
+    attr_accessor :ws_url
+    # @return [Integer] retry attempts for idempotent (GET) requests
+    attr_accessor :max_retries
+
+    def initialize(api_key: nil, base_url: nil, timeout: 30, open_timeout: 10, logger: nil,
+                   ca_file: nil, ws_url: nil, max_retries: 3)
+      @api_key = api_key
+      @base_url = base_url || DEFAULT_BASE_URL
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @logger = logger
+      @ca_file = ca_file
+      @ws_url = ws_url
+      @max_retries = max_retries
+    end
+
+    # A copy with the given attributes replaced. Client.new layers per-client
+    # overrides over the global default this way, without mutating it.
+    def merge(overrides = {})
+      dup.tap do |copy|
+        overrides.each do |attribute, value|
+          copy.public_send(:"#{attribute}=", value) unless value.nil?
+        end
+      end
+    end
+
+    # Fail at construction rather than on the first request, so a misconfigured
+    # deploy surfaces at boot.
+    def validate!
+      raise ConfigurationError, "api_key is required" if blank?(api_key)
+      raise ConfigurationError, "base_url is required" if blank?(base_url)
+
+      uri = begin
+        URI.parse(base_url.to_s)
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+        raise ConfigurationError, "base_url must be an http(s) URL, got #{base_url.inspect}"
+      end
+
+      if ca_file && !File.readable?(ca_file.to_s)
+        raise ConfigurationError, "ca_file is not readable: #{ca_file.inspect}"
+      end
+
+      self
+    end
+
+    # Action Cable endpoint, derived from base_url unless one was set explicitly
+    # ("https://relaygrid.dev" -> "wss://relaygrid.dev/cable").
+    def cable_url
+      return ws_url if ws_url
+
+      uri = URI.parse(base_url.to_s)
+      uri.scheme = uri.scheme == "https" ? "wss" : "ws"
+      uri.path = "/cable"
+      uri.query = nil
+      uri.to_s
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/relaygrid/delivery.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "time"
+
+module RelayGrid
+  # One attempt to deliver a message over one channel (email, push, ...).
+  #
+  # Immutable: `#refresh` returns a new Delivery rather than mutating this one,
+  # so a Delivery handed to another thread never changes underneath it.
+  class Delivery
+    QUEUED = "queued"
+    SENT = "sent"
+    DELIVERED = "delivered"
+    FAILED = "failed"
+    BOUNCED = "bounced"
+    OPENED = "opened"
+
+    # States the server will not move away from on its own.
+    SUCCESS_STATUSES = [DELIVERED, OPENED].freeze
+
+    attr_reader :id, :message_id, :status, :channel_id, :channel_name, :channel_type,
+                :error_message, :friendly_error_message,
+                :sent_at, :delivered_at, :failed_at, :opened_at, :created_at, :updated_at,
+                :raw
+
+    def initialize(attributes, client: nil)
+      @raw = attributes
+      @client = client
+
+      @id = attributes["id"]
+      @message_id = attributes["message_id"]
+      @status = attributes["status"]
+      @error_message = attributes["error_message"]
+      @friendly_error_message = attributes["friendly_error_message"]
+
+      channel = attributes["notification_channel"] || {}
+      @channel_id = channel["id"]
+      @channel_name = channel["name"]
+      @channel_type = channel["channel_type"]
+
+      @sent_at = parse_time(attributes["sent_at"])
+      @delivered_at = parse_time(attributes["delivered_at"])
+      @failed_at = parse_time(attributes["failed_at"])
+      @opened_at = parse_time(attributes["opened_at"])
+      @created_at = parse_time(attributes["created_at"])
+      @updated_at = parse_time(attributes["updated_at"])
+
+      freeze
+    end
+
+    def queued?
+      status == QUEUED
+    end
+
+    def sent?
+      status == SENT
+    end
+
+    def delivered?
+      status == DELIVERED
+    end
+
+    def failed?
+      status == FAILED
+    end
+
+    def bounced?
+      status == BOUNCED
+    end
+
+    def opened?
+      status == OPENED
+    end
+
+    # Reached a state the server considers final and successful.
+    #
+    # `failed` is deliberately *not* terminal: delivery jobs retry, so a failed
+    # row can still flip to `sent`. This mirrors the dashboard's polling
+    # semantics (see docs/DELIVERY_STATUS_PLAN.md in the API repo).
+    def success?
+      SUCCESS_STATUSES.include?(status)
+    end
+
+    def push?
+      channel_type == "push"
+    end
+
+    def email?
+      channel_type == "email"
+    end
+
+    # @return [RelayGrid::Delivery] this delivery's current server-side state
+    def refresh
+      client.deliveries.get(id)
+    end
+
+    def to_h
+      raw
+    end
+
+    def ==(other)
+      other.is_a?(Delivery) && other.id == id && other.status == status
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, id, status].hash
+    end
+
+    def inspect
+      "#<RelayGrid::Delivery id: #{id.inspect}, channel_type: #{channel_type.inspect}, " \
+        "status: #{status.inspect}>"
+    end
+
+    private
+
+    def client
+      @client || raise(Error, "This Delivery was built without a client and cannot be refreshed")
+    end
+
+    def parse_time(value)
+      return nil if value.nil? || value.to_s.empty?
+
+      Time.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/relaygrid/errors.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module RelayGrid
+  # Every error the gem raises descends from this, so `rescue RelayGrid::Error`
+  # is always enough. Faraday's own exceptions are never allowed to escape.
+  class Error < StandardError; end
+
+  # Bad or missing client configuration; raised at construction, not on request.
+  class ConfigurationError < Error; end
+
+  # Transport-level failure -- the request never produced an HTTP response.
+  class ConnectionError < Error; end
+
+  # A ConnectionError specifically from a timeout. Retryable.
+  class TimeoutError < ConnectionError; end
+
+  # The server answered, but not with success.
+  class APIError < Error
+    # @return [Integer, nil] HTTP status
+    attr_reader :status
+    # @return [Hash, String, nil] parsed response body
+    attr_reader :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message || default_message)
+    end
+
+    # The server's own `error` string when it sent one.
+    def error_message
+      body["error"] if body.is_a?(Hash)
+    end
+
+    # Maps an HTTP response onto the right subclass. 404s are discriminated
+    # further by the server's message so callers can tell "no such template"
+    # from "no such user" without string-matching themselves.
+    def self.from_response(status, body)
+      klass =
+        case status
+        when 401, 403 then AuthenticationError
+        when 402 then LimitExceededError
+        when 404 then not_found_class(body)
+        when 422 then ValidationError
+        when 400..499 then APIError
+        when 500..599 then ServerError
+        else APIError
+        end
+
+      klass.new(status: status, body: body)
+    end
+
+    def self.not_found_class(body)
+      error = body.is_a?(Hash) ? body["error"].to_s : body.to_s
+
+      case error
+      when /message template/i then TemplateNotFoundError
+      when /notification user/i then UserNotFoundError
+      else NotFoundError
+      end
+    end
+    private_class_method :not_found_class
+
+    private
+
+    def default_message
+      detail = error_message || body
+      "RelayGrid API error (HTTP #{status})#{": #{detail}" unless detail.nil?}"
+    end
+  end
+
+  # 401/403 -- the API key is missing, invalid, inactive, expired, or its
+  # account is suspended.
+  class AuthenticationError < APIError; end
+
+  # 402 -- the account's monthly notification limit is exhausted.
+  class LimitExceededError < APIError; end
+
+  # 404 -- the referenced record does not exist within this account.
+  class NotFoundError < APIError; end
+
+  # 404 naming a message template.
+  class TemplateNotFoundError < NotFoundError; end
+
+  # 404 naming a notification user.
+  class UserNotFoundError < NotFoundError; end
+
+  # 422 -- the payload reached the server but was rejected.
+  class ValidationError < APIError; end
+
+  # 5xx -- a fault on the RelayGrid side. Safe to retry for reads.
+  class ServerError < APIError; end
+
+  # `wait_for_deliveries` gave up before every delivery reached a terminal
+  # state. Carries the deliveries as last seen so the caller can inspect them.
+  class TimeoutWaitingForDeliveries < Error
+    # @return [Array<RelayGrid::Delivery>]
+    attr_reader :deliveries
+
+    def initialize(message = nil, deliveries: [])
+      @deliveries = deliveries
+      super(message || "Timed out waiting for deliveries to settle: #{deliveries.map(&:id).join(', ')}")
+    end
+  end
+end

data/lib/relaygrid/resources/channel_tokens.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RelayGrid
+  module Resources
+    # Mints the short-lived token an end user's device presents when subscribing
+    # to the realtime channel.
+    #
+    # A send already returns one (`SendResult#push_token`); this is how to get a
+    # fresh one once the hour is up, or without sending anything.
+    class ChannelTokens
+      def initialize(client)
+        @client = client
+      end
+
+      # @param user_id [String] your identifier for the user (external_user_id)
+      # @return [Hash] `{ token:, expires_in:, expires_at: }`
+      # @raise [RelayGrid::UserNotFoundError] no such recipient in this account
+      def create(user_id:)
+        body = @client.post("/api/v1/channel_tokens", body: { external_user_id: user_id.to_s })
+        expires_in = body["expires_in"]
+
+        {
+          token: body["token"],
+          expires_in: expires_in,
+          expires_at: expires_in ? Time.now + expires_in.to_i : nil,
+        }
+      end
+
+      # @return [String] just the token
+      def token_for(user_id)
+        create(user_id: user_id)[:token]
+      end
+    end
+  end
+end

data/lib/relaygrid/resources/deliveries.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module RelayGrid
+  module Resources
+    # Delivery status lookup for the ids a send returned.
+    class Deliveries
+      # Matches the server's cap (Api::V1::DeliveriesController::MAX_BATCH_SIZE);
+      # longer id lists are split across several requests.
+      MAX_BATCH_SIZE = 100
+
+      def initialize(client)
+        @client = client
+      end
+
+      # @param id [Integer, String]
+      # @return [RelayGrid::Delivery]
+      # @raise [RelayGrid::NotFoundError] no such delivery in this account
+      def get(id)
+        body = @client.get("/api/v1/deliveries/#{id}")
+        Delivery.new(body["delivery"], client: @client)
+      end
+
+      # Batch lookup. Ids that don't resolve are simply absent from the result,
+      # so one stale id never fails a whole poll.
+      #
+      # @param ids [Array<Integer>]
+      # @return [Array<RelayGrid::Delivery>]
+      def get_all(ids)
+        ids = Array(ids).compact
+        return [] if ids.empty?
+
+        ids.each_slice(MAX_BATCH_SIZE).flat_map do |batch|
+          body = @client.get("/api/v1/deliveries", params: { ids: batch.join(",") })
+          Array(body["deliveries"]).map { |delivery| Delivery.new(delivery, client: @client) }
+        end
+      end
+
+      # Poll until every delivery reaches a success state or `timeout` elapses.
+      #
+      # BLOCKING. This sleeps the calling thread between polls. That is fine in a
+      # background job, a rake task, a script, or a test -- but do not call it
+      # from inside a web request: it pins a request thread for up to `timeout`
+      # seconds, and enough concurrent sends will exhaust the pool. In a request,
+      # return the delivery ids and let the browser poll `#get_all`, or subscribe
+      # to the realtime channel with `RelayGrid.websocket`.
+      #
+      # `failed` is not terminal here: delivery jobs retry, so a failed row can
+      # still flip to `sent` and then `delivered` inside the window. Waiting out
+      # the timeout on a genuinely failed delivery is the deliberate trade -- it
+      # mirrors the dashboard, and reporting a transient failure as final is the
+      # worse error.
+      #
+      # @param ids [Array<Integer>]
+      # @param timeout [Numeric] seconds
+      # @param interval [Numeric] seconds between polls
+      # @param raise_on_timeout [Boolean]
+      # @return [Array<RelayGrid::Delivery>] as last seen
+      # @raise [RelayGrid::TimeoutWaitingForDeliveries] when `raise_on_timeout`
+      def wait_for(ids, timeout: 30, interval: 2, raise_on_timeout: false)
+        ids = Array(ids).compact
+        return [] if ids.empty?
+
+        deadline = monotonic_now + timeout
+        deliveries = []
+
+        loop do
+          deliveries = get_all(ids)
+          return deliveries if deliveries.any? && deliveries.all?(&:success?)
+
+          # Never sleep past the deadline: the caller's timeout is honoured to
+          # within one request, not rounded up to the next whole interval.
+          remaining = deadline - monotonic_now
+          break if remaining <= 0
+
+          sleeper.call([interval, remaining].min)
+        end
+
+        raise TimeoutWaitingForDeliveries.new(deliveries: deliveries) if raise_on_timeout
+
+        deliveries
+      end
+
+      private
+
+      # `sleeper` and `clock` are separate seams so specs can drive the loop
+      # with a fake clock -- the fake sleeper advances the fake clock -- instead
+      # of sleeping for real.
+      def sleeper
+        @sleeper ||= ->(seconds) { sleep(seconds) }
+      end
+
+      def clock
+        @clock ||= -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      end
+
+      def monotonic_now
+        clock.call
+      end
+    end
+  end
+end

data/lib/relaygrid/resources/message_templates.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RelayGrid
+  module Resources
+    # Read access to the account's templates. `notify` takes a template *name*,
+    # so this is mostly for discovery -- listing what's available, or checking
+    # which attributes a template expects before sending.
+    class MessageTemplates
+      def initialize(client)
+        @client = client
+      end
+
+      # @return [Array<Hash>] every template in the account
+      def list
+        Array(@client.get("/api/v1/message_templates")["message_templates"])
+      end
+
+      # @param id [Integer]
+      # @return [Hash]
+      def get(id)
+        @client.get("/api/v1/message_templates/#{id}")["message_template"]
+      end
+
+      # Look a template up by the same name `notify` takes.
+      #
+      # @param name [String]
+      # @return [Hash, nil]
+      def find_by_name(name)
+        list.find { |template| template["name"] == name.to_s }
+      end
+    end
+  end
+end