relaygrid 0.1.1

data/lib/relaygrid/resources/messages.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RelayGrid
+  module Resources
+    # The receive side: reading a recipient's inbox and marking messages off.
+    #
+    # `user_id` is always *your* identifier for the user (the API's
+    # `external_user_id`), never a RelayGrid internal id.
+    class Messages
+      def initialize(client)
+        @client = client
+      end
+
+      # Unseen messages for a recipient, newest first. The polling counterpart
+      # to `RelayGrid.websocket`, and what an inbox view renders.
+      #
+      # @param user_id [String]
+      # @return [Array<Hash>]
+      # @raise [RelayGrid::UserNotFoundError] no such recipient in this account
+      def new_for(user_id:)
+        body = @client.get(
+          "/api/v1/messages/new_messages_for",
+          params: { external_user_id: user_id.to_s }
+        )
+
+        Array(body["messages"])
+      end
+
+      # @param id [Integer] message id
+      # @return [Hash] the message with its deliveries
+      def get(id)
+        @client.get("/api/v1/messages/#{id}")["message"]
+      end
+
+      # Mark a message read. With a channel id, the matching delivery is marked
+      # opened (which is what drives open-rate analytics); without one, only the
+      # message's own seen flag is set.
+      #
+      # @return [Hash] the updated message
+      def mark_as_seen(id, notification_channel_id: nil)
+        body = {}
+        body[:notification_channel_id] = notification_channel_id if notification_channel_id
+
+        @client.patch("/api/v1/messages/#{id}/mark_as_seen", body: body)["message"]
+      end
+
+      # Confirm a push message reached the device. Normally the browser/device
+      # does this over the websocket; this is the HTTP equivalent.
+      #
+      # @return [Boolean]
+      def mark_as_delivered(id)
+        @client.patch("/api/v1/messages/#{id}/mark_as_delivered")["success"] == true
+      end
+
+      # Rendered subject and body with the message's attributes substituted in.
+      #
+      # @return [Hash] `{ "rendered_subject" => ..., "rendered_body" => ... }`
+      def render(id)
+        @client.get("/api/v1/messages/#{id}/render_message")
+      end
+    end
+  end
+end

data/lib/relaygrid/resources/notifications.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module RelayGrid
+  module Resources
+    # Sending. The developer contract the gem exists for: a user, a template
+    # name, and the attributes the template needs.
+    class Notifications
+      # Recipient details a send may carry alongside the id. `email` becomes the
+      # contact email deliveries resolve their recipient through.
+      RECIPIENT_ATTRIBUTES = %i[first_name middle_name last_name email].freeze
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Send a notification, creating or updating the recipient on the way.
+      #
+      # @param user [Hash] `{ id:, first_name:, last_name:, middle_name:,
+      #   email: }`. `id` is the *your-system* identifier -- it maps to the API's
+      #   `external_user_id`. RelayGrid's internal ids are never exposed here.
+      #   May also be a bare String/Integer id for a recipient that already
+      #   exists, in which case nothing about them is sent.
+      #
+      #   `email` is optional but load-bearing: email deliveries resolve their
+      #   recipient through the contact stored for that channel type, so a send
+      #   over an email channel for a user with no email on file produces a
+      #   delivery that fails with "no contact on file". Push needs no contact.
+      #   Passing an empty string removes the contact.
+      # @param template [String] the message template's name
+      # @param attributes [Hash] values for the template's `{{placeholders}}`
+      # @return [RelayGrid::SendResult]
+      #
+      # @raise [RelayGrid::TemplateNotFoundError] no such template in the account
+      # @raise [RelayGrid::LimitExceededError] the monthly notification limit is spent
+      # @raise [RelayGrid::ValidationError] the payload was rejected
+      #
+      # @example
+      #   result = RelayGrid.client.notify(
+      #     user:       { id: "user-123", first_name: "Ada", last_name: "Lovelace" },
+      #     template:   "order_shipped",
+      #     attributes: { order_number: "1042", eta: "tomorrow" }
+      #   )
+      #   result.delivery_ids # => [201, 202]
+      def notify(user:, template:, attributes: {})
+        message = {
+          message_template_name: template.to_s,
+          message_attributes_attributes: format_attributes(attributes),
+        }
+        message.merge!(recipient_params(user))
+
+        SendResult.new(@client.post("/api/v1/messages", body: { message: message }), client: @client)
+      end
+
+      private
+
+      # A Hash upserts the recipient server-side (one round trip instead of
+      # registering the user first); a bare id is a strict lookup.
+      def recipient_params(user)
+        return { external_user_id: user.to_s } unless user.is_a?(Hash)
+
+        user = normalize_keys(user)
+        external_user_id = user[:id] || user[:external_user_id]
+
+        if external_user_id.nil? || external_user_id.to_s.empty?
+          raise ArgumentError, "user must include an :id (your own identifier for the recipient)"
+        end
+
+        nested = { external_user_id: external_user_id.to_s }
+        # Only keys the caller actually supplied are forwarded: the server leaves
+        # anything absent untouched, so omitting a name doesn't blank it out and
+        # omitting an email doesn't drop the contact.
+        RECIPIENT_ATTRIBUTES.each do |name|
+          nested[name] = user[name].to_s unless user[name].nil?
+        end
+
+        { user: nested }
+      end
+
+      # The API takes attributes as [{ name:, value: }], which is awkward to
+      # write by hand, so a plain Hash is accepted and converted.
+      def format_attributes(attributes)
+        return [] if attributes.nil? || attributes.empty?
+
+        case attributes
+        when Hash
+          attributes.map { |name, value| { name: name.to_s, value: value.to_s } }
+        when Array
+          attributes.map do |attribute|
+            attribute = normalize_keys(attribute)
+            unless attribute.is_a?(Hash) && attribute.key?(:name)
+              raise ArgumentError, "array attributes must be hashes with a :name key"
+            end
+
+            { name: attribute[:name].to_s, value: attribute[:value].to_s }
+          end
+        else
+          raise ArgumentError, "attributes must be a Hash or an Array of {name:, value:} hashes"
+        end
+      end
+
+      def normalize_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) { |(key, value), out| out[key.to_sym] = value }
+      end
+    end
+  end
+end

data/lib/relaygrid/resources/users.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RelayGrid
+  module Resources
+    # Recipient management. `notify` upserts the recipient for you, so these are
+    # only needed to manage users outside a send -- backfilling, renaming, or
+    # honouring a deletion request.
+    #
+    # Everywhere here, `id` means *your* identifier for the user (the API's
+    # `external_user_id`). RelayGrid's internal ids stay internal.
+    class Users
+      def initialize(client)
+        @client = client
+      end
+
+      # @return [Array<Hash>] every recipient in the account
+      def list
+        Array(@client.get("/api/v1/notification_users")["notification_users"])
+      end
+
+      # @param id [String] your identifier for the user
+      # @return [Hash, nil]
+      def get(id)
+        list.find { |user| user["external_user_id"] == id.to_s }
+      end
+
+      # Create the recipient, or update their names if they already exist.
+      #
+      # @return [Hash] the notification user
+      def upsert(id:, first_name:, last_name:, middle_name: nil)
+        existing = get(id)
+        attributes = { first_name: first_name, last_name: last_name }
+        attributes[:middle_name] = middle_name unless middle_name.nil?
+
+        if existing
+          body = @client.patch(
+            "/api/v1/notification_users/#{existing['id']}",
+            body: { notification_user: attributes }
+          )
+        else
+          body = @client.post(
+            "/api/v1/notification_users",
+            body: { notification_user: attributes.merge(external_user_id: id.to_s) }
+          )
+        end
+
+        body["notification_user"]
+      end
+
+      # Soft-delete the recipient. Their message history is retained.
+      #
+      # @return [Boolean] false when there was no such user
+      def delete(id)
+        existing = get(id)
+        return false unless existing
+
+        @client.delete("/api/v1/notification_users/#{existing['id']}")
+        true
+      end
+
+      # -----------------------------------------------------------------------
+      # Contacts
+      #
+      # Email deliveries resolve their recipient through the contact stored for
+      # that channel *type* -- one address per user, whichever channel of that
+      # type delivers the message. `notify` upserts it from the `user:` payload,
+      # so these are for managing contacts outside a send: backfilling an
+      # existing user base, or reacting to someone changing their address.
+      # -----------------------------------------------------------------------
+
+      # @param id [String] your identifier for the user
+      # @return [Array<Hash>] the user's live contacts
+      # @raise [RelayGrid::UserNotFoundError]
+      def contacts(id)
+        Array(@client.get("#{contacts_path(id)}")["contacts"])
+      end
+
+      # Create or repoint the user's contact for one channel type.
+      #
+      # @param channel_type [String] "email"
+      # @param value [String] the address deliveries on that channel are sent to
+      # @return [Hash] the contact
+      # @raise [RelayGrid::ValidationError] the value was rejected
+      def set_contact(id, channel_type:, value:)
+        path = contacts_path(id)
+        existing = contacts(id).find { |contact| contact["channel_type"] == channel_type.to_s }
+        body = { contact: { channel_type: channel_type.to_s, value: value } }
+
+        if existing
+          @client.patch("#{path}/#{existing['id']}", body: body)["contact"]
+        else
+          @client.post(path, body: body)["contact"]
+        end
+      end
+
+      # @return [Boolean] false when there was no such contact
+      def delete_contact(id, channel_type:)
+        existing = contacts(id).find { |contact| contact["channel_type"] == channel_type.to_s }
+        return false unless existing
+
+        @client.delete("#{contacts_path(id)}/#{existing['id']}")
+        true
+      end
+
+      private
+
+      # Contacts hang off the user's *internal* id, which callers never hold, so
+      # it is resolved from their own identifier first.
+      def contacts_path(id)
+        user = get(id)
+        raise UserNotFoundError.new("Notification user '#{id}' not found", status: 404) unless user
+
+        "/api/v1/notification_users/#{user['id']}/contacts"
+      end
+    end
+  end
+end

data/lib/relaygrid/send_result.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RelayGrid
+  # What `RelayGrid.client.notify` hands back: the message that was created, the
+  # deliveries queued for it, and -- when the template has a live push channel
+  # -- the short-lived token the recipient's device needs to subscribe to the
+  # realtime channel.
+  class SendResult
+    attr_reader :message_id, :push_token, :push_token_expires_at, :deliveries,
+                :rendered_subject, :rendered_body, :raw
+
+    def initialize(body, client:)
+      @raw = body
+      @client = client
+
+      message = body["message"] || {}
+      @message_id = message["id"]
+      @rendered_subject = message["rendered_subject"]
+      @rendered_body = message["rendered_body"]
+
+      @push_token = body["push_token"]
+      expires_in = body["push_token_expires_in"]
+      @push_token_expires_at = expires_in ? Time.now + expires_in.to_i : nil
+
+      @deliveries = Array(message["deliveries"]).map { |d| Delivery.new(d, client: client) }.freeze
+
+      freeze
+    end
+
+    # Ids to hand to `client.deliveries.get_all` later. The primary reason a
+    # caller keeps anything from a send.
+    def delivery_ids
+      deliveries.map(&:id)
+    end
+
+    # True when the template dispatched over a push channel, so `push_token` is
+    # present and worth handing down to the recipient's device.
+    def push?
+      !push_token.nil?
+    end
+
+    def delivery_for(channel_type)
+      deliveries.find { |delivery| delivery.channel_type == channel_type.to_s }
+    end
+
+    # Poll until every delivery settles into a success state, or `timeout`
+    # seconds elapse.
+    #
+    # `failed` is not treated as terminal inside the window: delivery jobs
+    # retry, so a failed row can still flip to `sent` and then `delivered`.
+    # That mirrors the dashboard's semantics.
+    #
+    # @param timeout [Numeric] seconds to keep polling
+    # @param interval [Numeric] seconds between polls
+    # @param raise_on_timeout [Boolean] raise TimeoutWaitingForDeliveries
+    #   instead of returning the last-seen deliveries
+    # @return [Array<RelayGrid::Delivery>] deliveries as last seen
+    def wait_for_deliveries(timeout: 30, interval: 2, raise_on_timeout: false)
+      return deliveries if deliveries.empty?
+
+      @client.deliveries.wait_for(
+        delivery_ids,
+        timeout: timeout,
+        interval: interval,
+        raise_on_timeout: raise_on_timeout
+      )
+    end
+
+    def to_h
+      raw
+    end
+
+    def inspect
+      "#<RelayGrid::SendResult message_id: #{message_id.inspect}, " \
+        "delivery_ids: #{delivery_ids.inspect}, push: #{push?}>"
+    end
+  end
+end

data/lib/relaygrid/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RelayGrid
+  VERSION = "0.1.1"
+end

data/lib/relaygrid/websocket_client.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "websocket-client-simple"
+require "json"
+require "uri"
+
+module RelayGrid
+  # Realtime delivery of a recipient's messages over Action Cable.
+  #
+  #   ws = RelayGrid.websocket(user_id: "user-123")
+  #   ws.on_message { |message| puts message["rendered_subject"] }
+  #   ws.connect
+  #
+  # Authentication is the same short-lived channel token the send response
+  # returns -- it authorises exactly one recipient's stream. Tokens last an
+  # hour, so a fresh one is minted on every (re)connect rather than being held
+  # for the life of the object.
+  class WebsocketClient
+    CHANNEL = "MessagesChannel"
+
+    # Action Cable's own frame types, which are protocol noise rather than
+    # messages a subscriber cares about.
+    CONTROL_TYPES = %w[welcome ping confirm_subscription reject_subscription disconnect].freeze
+
+    attr_reader :user_id
+
+    def initialize(user_id:, client: nil, configuration: nil, reconnect: true)
+      @user_id = user_id.to_s
+      @client = client || RelayGrid.client
+      @configuration = configuration || @client.configuration
+      @reconnect = reconnect
+
+      @message_callbacks = []
+      @error_callbacks = []
+      @connect_callbacks = []
+      @close_callbacks = []
+
+      @mutex = Mutex.new
+      @connected = false
+      @subscribed = false
+      @closing = false
+    end
+
+    # @yield [Hash] the message payload, as `messages.new_for` returns them
+    def on_message(&block)
+      @message_callbacks << block
+      self
+    end
+
+    # @yield [Exception]
+    def on_error(&block)
+      @error_callbacks << block
+      self
+    end
+
+    def on_connect(&block)
+      @connect_callbacks << block
+      self
+    end
+
+    def on_close(&block)
+      @close_callbacks << block
+      self
+    end
+
+    # Open the connection and subscribe.
+    #
+    # @param blocking [Boolean] block the calling thread until disconnected.
+    #   Useful for a standalone consumer process; never do this in a web
+    #   request.
+    def connect(blocking: false)
+      @closing = false
+      open_socket
+
+      wait_until_closed if blocking
+
+      self
+    end
+
+    def disconnect
+      @closing = true
+      set(:@subscribed, false)
+      set(:@connected, false)
+      @socket&.close
+      @socket = nil
+      self
+    end
+
+    def connected?
+      read(:@connected)
+    end
+
+    def subscribed?
+      read(:@subscribed)
+    end
+
+    private
+
+    def open_socket
+      # Minted per connection: a token from an earlier connect may well have
+      # expired by the time a reconnect happens.
+      token = @client.channel_tokens.token_for(@user_id)
+      identifier = { channel: CHANNEL, channel_token: token }.to_json
+
+      @socket = WebSocket::Client::Simple.connect(@configuration.cable_url)
+      attach_handlers(@socket, identifier)
+      @socket
+    end
+
+    def attach_handlers(socket, identifier)
+      subscriber = self
+
+      socket.on :open do
+        subscriber.send(:handle_open, socket, identifier)
+      end
+
+      socket.on :message do |frame|
+        subscriber.send(:handle_frame, frame)
+      end
+
+      socket.on :close do
+        subscriber.send(:handle_close)
+      end
+
+      socket.on :error do |error|
+        subscriber.send(:handle_error, error)
+      end
+    end
+
+    def handle_open(socket, identifier)
+      set(:@connected, true)
+      socket.send({ command: "subscribe", identifier: identifier }.to_json)
+      dispatch(@connect_callbacks)
+    end
+
+    def handle_frame(frame)
+      data = frame.respond_to?(:data) ? frame.data : frame
+      return if data.nil? || data.empty?
+
+      payload = JSON.parse(data)
+      return unless payload.is_a?(Hash)
+
+      case payload["type"]
+      when "confirm_subscription"
+        set(:@subscribed, true)
+        return
+      when "reject_subscription"
+        set(:@subscribed, false)
+        handle_error(Error.new("Subscription rejected for user #{@user_id}"))
+        return
+      when *CONTROL_TYPES
+        return
+      end
+
+      # Action Cable wraps the broadcast in "message"; the server broadcasts
+      # `{ message: <payload> }`, so the message itself is one level further in.
+      envelope = payload["message"]
+      return unless envelope.is_a?(Hash)
+
+      message = envelope["message"] || envelope
+      dispatch(@message_callbacks, message)
+    rescue JSON::ParserError
+      nil # a frame we can't parse is not worth tearing the connection down for
+    end
+
+    def handle_close
+      set(:@connected, false)
+      set(:@subscribed, false)
+      dispatch(@close_callbacks)
+
+      reconnect! if @reconnect && !@closing
+    end
+
+    def handle_error(error)
+      set(:@connected, false)
+
+      # Nothing is watching for exceptions on the socket's own thread, so an
+      # unhandled raise here would vanish silently. Hand it to the caller's
+      # callback, or re-raise only if they never registered one.
+      raise error if @error_callbacks.empty? && error.is_a?(Exception)
+
+      dispatch(@error_callbacks, error)
+    end
+
+    def reconnect!
+      sleep(1)
+      open_socket
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    def wait_until_closed
+      sleep(0.1) while connected? || (@reconnect && !@closing)
+    end
+
+    def dispatch(callbacks, *args)
+      callbacks.each do |callback|
+        callback.call(*args)
+      rescue StandardError => e
+        # One misbehaving subscriber must not take down the connection or stop
+        # the remaining callbacks.
+        @configuration.logger&.error("RelayGrid websocket callback failed: #{e.message}")
+      end
+    end
+
+    def set(ivar, value)
+      @mutex.synchronize { instance_variable_set(ivar, value) }
+    end
+
+    def read(ivar)
+      @mutex.synchronize { instance_variable_get(ivar) }
+    end
+  end
+end

data/lib/relaygrid.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "relaygrid/version"
+require_relative "relaygrid/errors"
+require_relative "relaygrid/configuration"
+require_relative "relaygrid/delivery"
+require_relative "relaygrid/send_result"
+require_relative "relaygrid/client"
+require_relative "relaygrid/websocket_client"
+require_relative "relaygrid/resources/notifications"
+require_relative "relaygrid/resources/deliveries"
+require_relative "relaygrid/resources/messages"
+require_relative "relaygrid/resources/message_templates"
+require_relative "relaygrid/resources/users"
+require_relative "relaygrid/resources/channel_tokens"
+
+# Ruby client for the RelayGrid / RelayGrid notification API.
+#
+#   RelayGrid.configure do |config|
+#     config.api_key  = ENV["RELAYGRID_API_KEY"]
+#     config.base_url = ENV.fetch("RELAYGRID_BASE_URL", "https://relaygrid.dev")
+#   end
+#
+#   result = RelayGrid.client.notify(
+#     user:       { id: "user-123", first_name: "Ada", last_name: "Lovelace" },
+#     template:   "order_shipped",
+#     attributes: { order_number: "1042" }
+#   )
+module RelayGrid
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Set the process-wide defaults. The cached default client is dropped so the
+    # next call picks the new settings up (clients are frozen and never mutate).
+    def configure
+      yield(configuration)
+      @client = nil
+      configuration
+    end
+
+    # The default client, built from the global configuration.
+    #
+    # @return [RelayGrid::Client]
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    # Send a notification with the default client.
+    # See Resources::Notifications#notify.
+    #
+    # @return [RelayGrid::SendResult]
+    def notify(**kwargs)
+      client.notify(**kwargs)
+    end
+
+    # A realtime subscriber for one recipient's messages.
+    #
+    # @param user_id [String] your identifier for the user
+    # @return [RelayGrid::WebsocketClient]
+    def websocket(user_id:, **options)
+      WebsocketClient.new(user_id: user_id, client: client, **options)
+    end
+
+    # Drop the global configuration and cached client. Intended for test suites.
+    def reset!
+      @configuration = Configuration.new
+      @client = nil
+    end
+  end
+end

data/sig/relaygrid.rbs

@@ -0,0 +1,4 @@
+module RelayGrid
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end