relaygrid 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d0cc0707a44f80cc25e92aad237601e2fc3ec3f8ea2bd455facb68180843196
+  data.tar.gz: 237cd1b6377a7b4a8fc3ba57287da93990620efc3c6971af67277defcd50b886
+SHA512:
+  metadata.gz: 289569fcadc3c5d298ea4450a0ee00c33e21db743725ef9116aff25206b5c5fcf10ae3564434fb6a8a08af8b31c138e67a9cf79e64debcbef9d5616ba51e3672
+  data.tar.gz: 30de0ca4b93b88a2740787d1ce97eba72bf17807fe9af59eb2df99041909a6d86916a76f64debc45a14af950c38dfb70627b9048898d06c410ec4580d7e4c37a

data/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-07-30
+
+### Removed
+
+- `users.sms_opted_out?`, and `phone` is no longer forwarded from the `user:`
+  payload `notify` accepts. Contact management covers email; passing `phone:`
+  is now silently ignored rather than sent. Technically breaking for anyone who
+  reached for either in the hours 0.1.0 was current.
+
+### Changed
+
+- Contact documentation and examples cover email throughout.
+
+## [0.1.0] - 2026-07-30
+
+First public release.
+
+### Added
+
+- `RelayGrid.client.notify(user:, template:, attributes:)` — the one-call send.
+  Creates or updates the recipient server-side, and returns a `SendResult` with
+  the message id, delivery ids, and a push token when the template has a live
+  push channel.
+- `SendResult` and `Delivery` value objects. Both immutable; `Delivery` carries
+  status predicates (`queued?`, `sent?`, `delivered?`, `failed?`, `bounced?`,
+  `opened?`, `success?`) and `#refresh`.
+- `deliveries.get(id)` and `deliveries.get_all(ids)` for delivery status, backed
+  by the new `GET /api/v1/deliveries` endpoints. `get_all` batches in chunks of
+  100 to match the server's cap.
+- `result.wait_for_deliveries(timeout:, interval:)` — blocking poll until every
+  delivery settles. `failed` is not treated as terminal, since delivery jobs
+  retry.
+- `messages.new_for(user_id:)`, `mark_as_seen`, `mark_as_delivered` for the
+  receive side, addressed by your own user id rather than an internal one.
+- `RelayGrid.websocket(user_id:)` — Action Cable subscriber for `MessagesChannel`
+  that mints a fresh channel token on every connect and reconnect.
+- `channel_tokens.create(user_id:)` to refresh a push token after its hour.
+- `users` resource (`list`, `get`, `upsert`, `delete`) for managing recipients
+  outside a send, plus contact management — `contacts`, `set_contact` and
+  `delete_contact`.
+- `notify` forwards `user[:email]`, which the server upserts as the contact
+  email deliveries resolve their recipient through. Omitting the key leaves that
+  contact untouched; an empty string removes it.
+- Full error hierarchy under `RelayGrid::Error`, including `LimitExceededError`
+  (402) and `TemplateNotFoundError` / `UserNotFoundError` discriminated from a
+  404's message. Faraday exceptions no longer escape the gem.
+- Automatic retries with jittered backoff for idempotent (GET) requests.
+- `ca_file` configuration for trusting a private CA.
+- RuboCop (Omakase, matching the backend) and a GitHub Actions matrix on Ruby
+  3.1/3.2/3.3.
+
+### Changed
+
+- **Renamed from `notify_hub` to `relaygrid`.** The module is now `RelayGrid`,
+  the require path is `relaygrid`, and environment variables are prefixed
+  `RELAYGRID_`. This settles the naming question ahead of the first release.
+- `Client` instances are frozen after construction and safe to share across
+  threads.
+- `Client.new` accepts per-client overrides (`Client.new(api_key: "...")`) for
+  apps serving multiple accounts.
+- Configuration validates eagerly: a blank `api_key` or malformed `base_url`
+  raises `ConfigurationError` when the client is built.
+- Minimum Ruby is now 3.1.
+
+### Removed
+
+- `config.account_id`. The account is resolved from the API key server-side, so
+  it was never needed on the wire.
+- `config.verify_ssl`. TLS certificates are always verified; use `ca_file` to
+  trust a private CA. A switch to disable verification is not something this
+  client should offer, given it carries an API key and relays channel tokens.
+- `actor_email` on sends. The API does not accept the parameter, so passing it
+  was silently a no-op.
+
+### Dependencies
+
+- Added `faraday-retry`.
+- Dropped `faraday-multipart` and `faraday-follow_redirects` (unused).

data/QUICKSTART.md

@@ -0,0 +1,112 @@
+# RelayGrid Gem — Quick Start
+
+From zero to a delivered notification. The [README](README.md) has the full
+reference.
+
+## 1. Install
+
+```ruby
+# Gemfile
+gem "relaygrid"
+```
+
+```bash
+bundle install
+```
+
+## 2. Get an API key
+
+Dashboard → **API Keys** → *New API Key*. Copy it — it is shown once. The key
+identifies your account, so there is nothing else to configure.
+
+```bash
+# .env
+RELAYGRID_API_KEY=sk_your_key_here
+```
+
+## 3. Configure
+
+```ruby
+# config/initializers/relaygrid.rb
+RelayGrid.configure do |config|
+  config.api_key  = ENV["RELAYGRID_API_KEY"]
+  config.base_url = ENV.fetch("RELAYGRID_BASE_URL", "https://relaygrid.dev")
+end
+```
+
+## 4. Create a template
+
+Dashboard → **Templates** → *New Template*. Give it a name you'll pass to
+`notify` (say `order_shipped`), write the subject and body with `{{placeholders}}`,
+attach at least one channel, and set it **active**.
+
+```
+Name:    order_shipped
+Subject: Hi {{first_name}}, order {{order_number}} shipped
+Body:    It should arrive {{eta}}.
+```
+
+## 5. Send
+
+```ruby
+result = RelayGrid.client.notify(
+  user:       { id: current_user.id, first_name: current_user.first_name, last_name: current_user.last_name },
+  template:   "order_shipped",
+  attributes: { first_name: current_user.first_name, order_number: order.number, eta: "tomorrow" }
+)
+```
+
+`user[:id]` is **your** identifier. The recipient is created on first send, so
+there's no registration step.
+
+## 6. Check what happened
+
+```ruby
+result.delivery_ids # => [201, 202] — keep these
+
+delivery = RelayGrid.client.deliveries.get(201)
+delivery.status     # => "delivered"
+delivery.delivered? # => true
+```
+
+Store `delivery_ids` alongside whatever triggered the notification, and poll
+them when you want status. Don't block a web request waiting — see
+`wait_for_deliveries` in the README for when that helper is and isn't
+appropriate.
+
+## 7. Receive (optional)
+
+If your template has a push channel, the send hands you a token for the
+recipient's device:
+
+```ruby
+result.push_token # => "eyJf..." — pass to your frontend; expires in 1 hour
+```
+
+Server-side, poll or subscribe:
+
+```ruby
+RelayGrid.client.messages.new_for(user_id: current_user.id)
+
+ws = RelayGrid.websocket(user_id: current_user.id)
+ws.on_message { |message| puts message["rendered_subject"] }
+ws.connect
+```
+
+## Troubleshooting
+
+| Problem | Cause |
+|---|---|
+| `ConfigurationError: api_key is required` | `RELAYGRID_API_KEY` isn't set in this environment. |
+| `AuthenticationError` | Key is wrong, deactivated, expired, or the account is suspended. |
+| `TemplateNotFoundError` | Template name doesn't match, or the template is soft-deleted. |
+| `LimitExceededError` | Monthly notification limit spent — check Usage in the dashboard. |
+| `result.push_token` is `nil` | The template has no live push channel attached. |
+| Delivery stuck at `queued` | The delivery job hasn't run yet; poll again shortly. |
+| Delivery `failed` | Read `delivery.friendly_error_message` — usually channel credentials. |
+
+## Next steps
+
+- [README](README.md) — full configuration, error hierarchy, retry semantics
+- [examples/usage_examples.rb](examples/usage_examples.rb) — runnable end-to-end script
+- [examples/rails_initializer.rb](examples/rails_initializer.rb) — annotated initializer

data/README.md

@@ -0,0 +1,249 @@
+# RelayGrid Ruby Gem
+
+Send and receive notifications through [RelayGrid](https://relaygrid.com) in one call.
+
+Give it a user, a template name, and the attributes the template needs. Get back
+a push token for the recipient's device and the delivery ids you can check later.
+
+```ruby
+result = RelayGrid.client.notify(
+  user:       { id: "user-123", first_name: "Ada", last_name: "Lovelace" },
+  template:   "order_shipped",
+  attributes: { order_number: "1042", eta: "tomorrow" }
+)
+
+result.message_id   # => 87
+result.delivery_ids # => [201, 202]
+result.push_token   # => "eyJf..." (nil when the template has no push channel)
+```
+
+## Installation
+
+```ruby
+gem "relaygrid"
+```
+
+Then `bundle install`. Requires Ruby >= 3.1.
+
+## Configuration
+
+```ruby
+# config/initializers/relaygrid.rb
+RelayGrid.configure do |config|
+  config.api_key  = ENV["RELAYGRID_API_KEY"]
+  config.base_url = ENV.fetch("RELAYGRID_BASE_URL", "https://relaygrid.dev")
+end
+```
+
+| Option | Default | Purpose |
+|---|---|---|
+| `api_key` | — | Account API key (`sk_...`). Required. |
+| `base_url` | `https://relaygrid.dev` | API origin. |
+| `timeout` | `30` | Seconds to wait for a response. |
+| `open_timeout` | `10` | Seconds to wait for the connection to open. |
+| `max_retries` | `3` | Retry attempts for idempotent (GET) requests. |
+| `logger` | `nil` | Logs requests when set. Headers and bodies are not logged. |
+| `ca_file` | `nil` | PEM bundle for a private CA. |
+| `ws_url` | derived from `base_url` | Overrides the Action Cable URL. |
+
+Bad configuration raises `RelayGrid::ConfigurationError` when the client is
+built, not on the first request.
+
+**TLS.** Certificates are always verified. There is no option to turn
+verification off: the client carries your API key and relays channel tokens, so
+an unverified connection is never the right default. To trust a self-signed or
+internal CA, point `ca_file` at its PEM bundle.
+
+### Multiple accounts
+
+`RelayGrid.client` is the shared default. For a host app talking to several
+accounts, build clients with per-client overrides:
+
+```ruby
+client = RelayGrid::Client.new(api_key: account.relaygrid_key)
+```
+
+Clients are frozen once built and safe to share across threads.
+
+## Sending
+
+`user[:id]` is **your** identifier for the recipient. RelayGrid stores it as
+`external_user_id` and never exposes its own internal ids to you.
+
+```ruby
+result = RelayGrid.client.notify(
+  user:       { id: "user-123", first_name: "Ada", last_name: "Lovelace" },
+  template:   "order_shipped",
+  attributes: { order_number: "1042" }
+)
+```
+
+The recipient is created on first send and their names refreshed when they
+change, so there is no separate registration step. If the recipient already
+exists and you don't want to send names, pass the id on its own:
+
+```ruby
+RelayGrid.client.notify(user: "user-123", template: "order_shipped")
+```
+
+### Email recipients
+
+Push needs nothing but the id. Email deliveries resolve **who** to send to from
+the address stored for the recipient, so include it in the send:
+
+```ruby
+RelayGrid.client.notify(
+  user:     { id: "user-123", first_name: "Ada", last_name: "Lovelace",
+              email: "ada@example.com" },
+  template: "order_shipped"
+)
+```
+
+Without it, a send over an email channel produces a delivery that fails with
+"no contact on file". A value RelayGrid can't use raises `ValidationError`
+rather than failing quietly at delivery time.
+
+Omitting the key leaves the existing address alone; passing an empty string
+removes it. Contacts can also be managed outside a send:
+
+```ruby
+RelayGrid.client.users.contacts("user-123")
+RelayGrid.client.users.set_contact("user-123", channel_type: "email", value: "ada@example.com")
+RelayGrid.client.users.delete_contact("user-123", channel_type: "email")
+```
+
+### The result
+
+```ruby
+result.message_id            # => 87
+result.delivery_ids          # => [201, 202]
+result.deliveries            # => [#<RelayGrid::Delivery id: 201, channel_type: "push", status: "queued">, ...]
+result.delivery_for("email") # => #<RelayGrid::Delivery ...>
+result.rendered_subject      # => "Hi Ada"
+result.push_token            # => "eyJf..." or nil
+result.push_token_expires_at # => 2026-07-28 11:00:00 +0000
+result.push?                 # => true when a push channel was dispatched
+```
+
+### The push token
+
+When the template has a live push channel, the send response carries a token
+that authenticates **the recipient's device** to the realtime channel. Your
+server receives it and hands it down to your client. It expires after an hour;
+mint a fresh one with:
+
+```ruby
+RelayGrid.client.channel_tokens.create(user_id: "user-123")
+# => { token: "eyJf...", expires_in: 3600, expires_at: 2026-07-28 11:00:00 +0000 }
+```
+
+## Checking delivery status
+
+```ruby
+delivery = RelayGrid.client.deliveries.get(201)
+delivery.status                 # => "delivered"
+delivery.delivered?             # => true
+delivery.channel_type           # => "push"
+delivery.friendly_error_message # => nil, or human-readable guidance when failed
+
+RelayGrid.client.deliveries.get_all([201, 202])  # one batched request
+```
+
+Predicates: `queued?`, `sent?`, `delivered?`, `failed?`, `bounced?`, `opened?`,
+plus `success?` (delivered or opened). `#refresh` re-fetches and returns a new
+`Delivery` — the objects are immutable.
+
+### Waiting for deliveries to settle
+
+```ruby
+settled = result.wait_for_deliveries(timeout: 30, interval: 2)
+settled.all?(&:success?) # => true
+```
+
+> **This blocks the calling thread.** Use it in a background job, a rake task, or
+> a script — never inside a web request, where it would pin a request thread for
+> up to `timeout` seconds. In a request, return `delivery_ids` and let the
+> browser poll, or subscribe over the websocket.
+
+`failed` is deliberately **not** treated as final inside the window: delivery
+jobs retry, so a failed delivery can still flip to `sent` and then `delivered`.
+The helper waits rather than reporting a transient failure as permanent.
+
+## Receiving
+
+### Polling
+
+```ruby
+RelayGrid.client.messages.new_for(user_id: "user-123")  # unseen messages
+RelayGrid.client.messages.mark_as_seen(message_id)
+RelayGrid.client.messages.mark_as_delivered(message_id)
+```
+
+### Realtime
+
+```ruby
+ws = RelayGrid.websocket(user_id: "user-123")
+ws.on_message { |message| puts message["rendered_subject"] }
+ws.on_error   { |error| Rails.logger.error(error.message) }
+ws.connect
+```
+
+A fresh channel token is minted on every connect and reconnect, so the hourly
+expiry is handled for you. `connect(blocking: true)` blocks the thread — for a
+standalone consumer process, not a web request.
+
+## Errors
+
+Everything descends from `RelayGrid::Error`, so `rescue RelayGrid::Error` always
+suffices. Faraday exceptions never escape the gem.
+
+| Class | Raised when |
+|---|---|
+| `ConfigurationError` | Bad configuration, at client construction |
+| `ConnectionError` | The request never produced a response |
+| `TimeoutError` | A timeout (subclass of `ConnectionError`) |
+| `AuthenticationError` | 401/403 — key invalid, inactive, expired, or account suspended |
+| `LimitExceededError` | 402 — monthly notification limit spent |
+| `NotFoundError` | 404 |
+| `TemplateNotFoundError` | 404 naming a template (subclass of `NotFoundError`) |
+| `UserNotFoundError` | 404 naming a recipient (subclass of `NotFoundError`) |
+| `ValidationError` | 422 |
+| `ServerError` | 5xx |
+| `TimeoutWaitingForDeliveries` | `wait_for_deliveries` gave up (only with `raise_on_timeout`) |
+
+`APIError` subclasses carry `#status`, `#body`, and `#error_message` (the
+server's own message).
+
+```ruby
+begin
+  RelayGrid.client.notify(user: user, template: "order_shipped")
+rescue RelayGrid::LimitExceededError
+  # out of notifications this month
+rescue RelayGrid::TemplateNotFoundError => e
+  Rails.logger.error(e.error_message)
+end
+```
+
+## Retries and idempotency
+
+GETs retry automatically (3 attempts by default, jittered exponential backoff)
+on 429, 5xx, and transport failures.
+
+**`notify` is never retried.** A blind retry would send the recipient a second
+real notification. If a send fails, deciding whether to re-send is yours to
+make. Server-side `Idempotency-Key` support is planned so retries can be made
+safe.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+```
+
+Specs use WebMock; no example makes a real HTTP call or sleeps for real.
+
+## License
+
+MIT.

data/examples/rails_initializer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# config/initializers/relaygrid.rb
+#
+# Example Rails initializer for the RelayGrid gem. Copy it into your app at
+# config/initializers/relaygrid.rb.
+
+RelayGrid.configure do |config|
+  # Account API key ("sk_..."), from the API Keys page of your dashboard.
+  # Required -- the account is resolved from it server-side.
+  config.api_key = ENV.fetch("RELAYGRID_API_KEY", nil)
+
+  # API origin. Point this at your local stack in development.
+  config.base_url = ENV.fetch("RELAYGRID_BASE_URL", "https://relaygrid.dev")
+
+  # Seconds to wait for a response, and for the connection to open.
+  config.timeout = ENV.fetch("RELAYGRID_TIMEOUT", 30).to_i
+  config.open_timeout = ENV.fetch("RELAYGRID_OPEN_TIMEOUT", 10).to_i
+
+  # Optional: trust a private CA (self-signed local dev, internal deployments).
+  # TLS certificates are always verified -- there is no way to turn that off.
+  config.ca_file = ENV.fetch("RELAYGRID_CA_FILE", nil)
+
+  # Optional: log requests (method, URL, status). Headers and bodies are not
+  # logged, so your API key never reaches the log.
+  config.logger = Rails.logger if Rails.env.development?
+end
+
+# Fail fast on a misconfigured deploy rather than on the first send: building
+# the client validates the configuration.
+begin
+  RelayGrid.client
+  Rails.logger.info("RelayGrid configured: #{RelayGrid.configuration.base_url}")
+rescue RelayGrid::ConfigurationError => e
+  Rails.logger.warn("RelayGrid is not configured: #{e.message}")
+  Rails.logger.warn("Notifications will fail until this is corrected.")
+end

data/examples/usage_examples.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# Example usage of the RelayGrid gem.
+#
+# Run with:
+#   RELAYGRID_API_KEY=sk_... ruby examples/usage_examples.rb
+
+require "relaygrid"
+
+RelayGrid.configure do |config|
+  config.api_key = ENV.fetch("RELAYGRID_API_KEY")
+  config.base_url = ENV.fetch("RELAYGRID_BASE_URL", "https://relaygrid.dev")
+end
+
+# ---------------------------------------------------------------------------
+# 1. Send a notification
+# ---------------------------------------------------------------------------
+# `user[:id]` is your own identifier for the recipient. They are created on the
+# first send and their names refreshed when they change, so there is no separate
+# registration step.
+
+result = RelayGrid.client.notify(
+  user: { id: "user-123", first_name: "Ada", last_name: "Lovelace" },
+  template: "order_shipped",
+  attributes: { order_number: "1042", eta: "tomorrow" }
+)
+
+puts "message:    #{result.message_id}"
+puts "deliveries: #{result.delivery_ids.inspect}"
+puts "subject:    #{result.rendered_subject}"
+
+# ---------------------------------------------------------------------------
+# 2. Hand the push token to the recipient's device
+# ---------------------------------------------------------------------------
+# Present only when the template has a live push channel. It authenticates the
+# *device*, not your server, and expires after an hour.
+
+if result.push?
+  puts "push token: #{result.push_token[0, 12]}... (expires #{result.push_token_expires_at})"
+else
+  puts "push token: none (template has no push channel)"
+end
+
+# ---------------------------------------------------------------------------
+# 3. Check delivery status later
+# ---------------------------------------------------------------------------
+
+result.delivery_ids.each do |id|
+  delivery = RelayGrid.client.deliveries.get(id)
+  puts "delivery #{delivery.id} (#{delivery.channel_type}): #{delivery.status}"
+  puts "  #{delivery.friendly_error_message}" if delivery.failed?
+end
+
+# One request instead of one per id:
+RelayGrid.client.deliveries.get_all(result.delivery_ids).each do |delivery|
+  puts "#{delivery.id} => #{delivery.status}"
+end
+
+# ---------------------------------------------------------------------------
+# 4. Wait for the deliveries to settle
+# ---------------------------------------------------------------------------
+# BLOCKING -- fine in a script or background job, never in a web request.
+
+settled = result.wait_for_deliveries(timeout: 30, interval: 2)
+puts "all delivered: #{settled.all?(&:success?)}"
+
+# ---------------------------------------------------------------------------
+# 5. Read a recipient's inbox
+# ---------------------------------------------------------------------------
+
+unseen = RelayGrid.client.messages.new_for(user_id: "user-123")
+puts "unseen: #{unseen.size}"
+
+unseen.each do |message|
+  puts "  #{message['rendered_subject']}"
+  RelayGrid.client.messages.mark_as_seen(message["id"])
+end
+
+# ---------------------------------------------------------------------------
+# 6. Handle errors
+# ---------------------------------------------------------------------------
+# Everything descends from RelayGrid::Error; no Faraday exception escapes.
+
+begin
+  RelayGrid.client.notify(user: { id: "user-123", first_name: "Ada", last_name: "Lovelace" },
+                          template: "no_such_template")
+rescue RelayGrid::TemplateNotFoundError => e
+  puts "no such template: #{e.error_message}"
+rescue RelayGrid::LimitExceededError
+  puts "monthly notification limit reached"
+rescue RelayGrid::AuthenticationError
+  puts "API key rejected"
+rescue RelayGrid::ConnectionError => e
+  puts "could not reach RelayGrid: #{e.message}"
+end
+
+# ---------------------------------------------------------------------------
+# 7. Receive in realtime
+# ---------------------------------------------------------------------------
+# A fresh channel token is minted on every connect and reconnect, so the hourly
+# expiry is handled for you.
+
+ws = RelayGrid.websocket(user_id: "user-123")
+ws.on_message { |message| puts "realtime: #{message['rendered_subject']}" }
+ws.on_error { |error| warn "websocket error: #{error.message}" }
+
+# ws.connect(blocking: true) # uncomment to run as a standalone consumer
+
+# ---------------------------------------------------------------------------
+# 8. Serve several accounts from one process
+# ---------------------------------------------------------------------------
+# Clients are frozen once built and safe to share across threads.
+
+other_account = RelayGrid::Client.new(api_key: ENV.fetch("OTHER_RELAYGRID_API_KEY", "sk_other"))
+puts "second client ready: #{other_account.configuration.base_url}"