relaygrid 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08c77a1f6d4cf7d515c07899a1b7ec8e30a590921fff71bf0261cc2caa58fc86'
-  data.tar.gz: 0a4d7357d29d5fada986ac8bc2cf67b6a87c833a410f47a1d15590665bd06d4b
+  metadata.gz: b882a7bed3e374b22766cb62d2d79d29ce370ac1ac9eb62c3190c3ccf0239e16
+  data.tar.gz: 580b2d452d74e956bce502515ed67c0db9747fc38ab40c42c80081970341d345
 SHA512:
-  metadata.gz: fcc099fa99bc3f2312b16308b61ed94731284533fac178506a49dec418ee84bbdf118984f49f003c6076c931deb8eb2675c22f4d55e1c2966e58283125c19ef4
-  data.tar.gz: 9376cfbafd25399ecb4bc2aa8091bdbf95712d22d6713fca2db039823ddaedc790d111b1752b9bf360a4b9613a02cfe7c46df0ef03ce5178f15fe8239829b9e6
+  metadata.gz: a271ee98e4bb2d8720c2e74bd75b57fcfb3eded0f7a3888bac266bba828048463fe47c6721d2aaae1f5b82a1a70a1eae2fa4d2616812f81510f04aa286232352
+  data.tar.gz: d7fc151625f6bfa0159839c8f6952c7d7265ab65fbf41445e863d662cd541571e815f9476c7712ccc763a3ff438be52002ca610981787f49050e08488b871488

data/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-26
+
+### Added
+
+- **Scheduled deliveries.** `notify` accepts `scheduled_at:` to deliver later
+  instead of immediately. A `Time`, `DateTime`, or `ActiveSupport::TimeWithZone`
+  is serialized with `.iso8601`, which always emits a UTC offset; a `String` is
+  passed through untouched for the server to validate. **The server requires an
+  explicit UTC offset and returns a 422 on a naive or malformed timestamp** —
+  it never assumes a timezone, so a client that serializes naively would
+  otherwise turn into a 422 the caller can't diagnose. A bare `Date` raises
+  `ArgumentError` locally, since a date has no instant.
+- `messages.cancel_schedule(id)` withdraws a scheduled send before it
+  dispatches (`DELETE /api/v1/messages/:id/schedule`). Raises `ValidationError`
+  if the message has already dispatched or been canceled.
+- `SendResult#scheduled?` and `#scheduled_at`, read off the created message.
+- **`wait_for_deliveries` returns immediately for a scheduled send**, without
+  polling. A `scheduled` delivery is never terminal — nothing has been handed
+  to a provider yet — so without this a caller who scheduled and then waited
+  would block for the full `timeout`.
+- Note for integrators: a `201` at schedule time is not a delivery guarantee.
+  A scheduled send can still end in `delivery.failed` if the account's
+  monthly quota is spent by dispatch time. `push?`/`push_token` are unaffected
+  by scheduling — the token is for the device to subscribe now, independent
+  of when the message dispatches, because the server reads the template's
+  live channels rather than the deliveries.
+
+## [0.2.1] - 2026-08-21
+
+### Fixed
+
+- Gemspec metadata now points at the self-hosted GitLab repository
+  (`git.relaygrid.dev`): the homepage, source, and changelog URIs no longer
+  reference the old GitHub location. No code changes.
+
 ## [0.2.0] - 2026-08-06
 
 ### Added

data/QUICKSTART.md

@@ -74,6 +74,33 @@ 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.
 
+## 6a. Schedule for later (optional)
+
+Pass `scheduled_at` instead of sending immediately:
+
+```ruby
+RelayGrid.client.notify(
+  user: current_user.id, template: "order_shipped",
+  scheduled_at: Time.now + 1.day # or an ISO 8601 String like "2026-09-01T09:00:00-07:00"
+)
+```
+
+**The timestamp must carry an explicit UTC offset.** A `Time`/`DateTime`/
+`ActiveSupport::TimeWithZone` is serialized with `.iso8601` for you, which
+always includes one; a naive `String` (no offset) is rejected by the server
+with a 422 rather than assumed to mean UTC. A bare `Date` raises
+`ArgumentError` locally — it has no instant to schedule.
+
+A `201` here means the schedule was accepted, not that the message will
+successfully send: a scheduled delivery can still end in `delivery.failed`
+if the account's quota is spent by dispatch time. Withdraw it beforehand with:
+
+```ruby
+RelayGrid.client.messages.cancel_schedule(result.message_id)
+```
+
+See the [README](README.md#scheduling-a-send) for the full behavior.
+
 ## 7. Receive (optional)
 
 If your template has a push channel, the send hands you a token for the
@@ -104,6 +131,8 @@ ws.connect
 | `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. |
+| `scheduled_at` gets a 422 | The timestamp has no UTC offset, or isn't a real date/time. Use `Time`/`DateTime`/`ActiveSupport::TimeWithZone`, or an explicit-offset ISO 8601 string. |
+| A scheduled send ends in `delivery.failed` | Quota was spent between scheduling and dispatch. The `201` at schedule time isn't a delivery guarantee. |
 
 ## Next steps
 

data/README.md

@@ -123,8 +123,53 @@ 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
+result.scheduled?            # => true when scheduled_at was set
+result.scheduled_at          # => 2026-09-01 16:00:00 +0000, or nil for an immediate send
 ```
 
+### Scheduling a send
+
+Pass `scheduled_at` to deliver later instead of immediately:
+
+```ruby
+RelayGrid.client.notify(
+  user: "user-123", template: "order_shipped",
+  scheduled_at: Time.now + 3600 # or a DateTime, an ActiveSupport::TimeWithZone, or an ISO 8601 String
+)
+```
+
+A `Time`, `DateTime`, or `ActiveSupport::TimeWithZone` is serialized with
+`.iso8601`, which always emits a UTC offset. A `String` is passed through
+untouched for the server to validate. **The server requires an explicit UTC
+offset and returns a 422 (`RelayGrid::ValidationError`) on a naive or
+malformed timestamp** — it never guesses what timezone you meant, so
+`"2026-09-01T09:00:00"` (no offset) is rejected rather than silently treated
+as UTC. A bare `Date` raises `ArgumentError` locally, before any request is
+made — a date has no instant, so there's no correct offset to send.
+
+The message is created immediately with status-`scheduled` deliveries, and
+returns a `201` right away; nothing has reached a channel provider yet. A
+scheduled send can still end in `delivery.failed` at dispatch time if the
+account's monthly quota is spent by then — the `201` at schedule time is not
+a guarantee of delivery, only that the schedule was accepted.
+
+The push token, when present, is unaffected by scheduling: it authenticates
+the recipient's device to subscribe *now*, independent of when the message
+actually dispatches. `push?`/`push_token` work exactly as they do for an
+immediate send, because the server reads the template's live channels, not
+the deliveries.
+
+Withdraw a scheduled send before it dispatches:
+
+```ruby
+RelayGrid.client.messages.cancel_schedule(message_id)
+```
+
+Only pending messages can be withdrawn. Once dispatch has claimed the row,
+sends may already be going out, and the call raises `ValidationError` (422) —
+there is a small window where a well-timed cancel can lose the race to the
+dispatch sweep.
+
 ### The push token
 
 When the template has a live push channel, the send response carries a token
@@ -165,6 +210,12 @@ It returns once every delivery is **terminal** — successful or not — so chec
 `success?` yourself rather than treating a return as a win. A delivery the server
 is still retrying reads `retrying`, which is why `failed` means final.
 
+For a scheduled send (`result.scheduled?`), this returns `deliveries`
+immediately — still reading `status: "scheduled"` — instead of polling. A
+`scheduled` delivery is never terminal, since nothing has been handed to a
+provider yet, so polling it would otherwise just block for the full `timeout`
+waiting on a state change that isn't coming until dispatch.
+
 > **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

data/lib/relaygrid/delivery.rb

@@ -15,11 +15,16 @@ module RelayGrid
     FAILED = "failed"
     BOUNCED = "bounced"
     OPENED = "opened"
+    SCHEDULED = "scheduled"
+    CANCELED = "canceled"
 
     SUCCESS_STATUSES = [DELIVERED, OPENED].freeze
 
-    # States the server will not move away from on its own.
-    TERMINAL_STATUSES = (SUCCESS_STATUSES + [FAILED, BOUNCED]).freeze
+    # States the server will not move away from on its own. `scheduled` is
+    # deliberately absent -- only the sweep moves it, which can be well past
+    # any reasonable poll timeout. `canceled` is terminal; the server never
+    # revives a canceled delivery.
+    TERMINAL_STATUSES = (SUCCESS_STATUSES + [FAILED, BOUNCED, CANCELED]).freeze
 
     attr_reader :id, :message_id, :status, :channel_id, :channel_name, :channel_type,
                 :error_message, :friendly_error_message,
@@ -79,6 +84,14 @@ module RelayGrid
       status == OPENED
     end
 
+    def scheduled?
+      status == SCHEDULED
+    end
+
+    def canceled?
+      status == CANCELED
+    end
+
     # Reached a state the server considers final and successful.
     def success?
       SUCCESS_STATUSES.include?(status)

data/lib/relaygrid/resources/messages.rb

@@ -58,6 +58,18 @@ module RelayGrid
       def render(id)
         @client.get("/api/v1/messages/#{id}/render_message")
       end
+
+      # Withdraw a scheduled send before it dispatches. Only pending messages
+      # can be withdrawn -- once dispatch has claimed the row, channel sends
+      # may already be going out, and there's nothing left to cancel.
+      #
+      # @return [Hash] the message, with `schedule_canceled_reason: "requested"`
+      # @raise [RelayGrid::ValidationError] the message already dispatched or
+      #   was already canceled (the sweep won the race)
+      # @raise [RelayGrid::NotFoundError] no such message
+      def cancel_schedule(id)
+        @client.delete("/api/v1/messages/#{id}/schedule")["message"]
+      end
     end
   end
 end

data/lib/relaygrid/resources/notifications.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "date"
+require "time"
+
 module RelayGrid
   module Resources
     # Sending. The developer contract the gem exists for: a user, a template
@@ -28,11 +31,19 @@ module RelayGrid
       #   Passing an empty string removes the contact.
       # @param template [String] the message template's name
       # @param attributes [Hash] values for the template's `{{placeholders}}`
+      # @param scheduled_at [Time, DateTime, ActiveSupport::TimeWithZone, String, nil]
+      #   when to deliver instead of immediately. A `Time`/`DateTime`/`TimeWithZone`
+      #   is serialized with `.iso8601`, which always emits a UTC offset; a
+      #   `String` is passed through untouched for the server to validate. The
+      #   server rejects a naive or malformed timestamp with a 422 -- it never
+      #   guesses a timezone. `nil` (the default) sends immediately.
       # @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
+      # @raise [RelayGrid::ValidationError] the payload was rejected, e.g. a
+      #   `scheduled_at` with no UTC offset
+      # @raise [ArgumentError] `scheduled_at` is a bare `Date`, which has no instant
       #
       # @example
       #   result = RelayGrid.client.notify(
@@ -41,18 +52,45 @@ module RelayGrid
       #     attributes: { order_number: "1042", eta: "tomorrow" }
       #   )
       #   result.delivery_ids # => [201, 202]
-      def notify(user:, template:, attributes: {})
+      #
+      # @example Scheduling a send
+      #   RelayGrid.client.notify(
+      #     user: "user-123", template: "order_shipped",
+      #     scheduled_at: Time.now + 3600 # or "2026-09-01T09:00:00-07:00"
+      #   )
+      def notify(user:, template:, attributes: {}, scheduled_at: nil)
         message = {
           message_template_name: template.to_s,
           message_attributes_attributes: format_attributes(attributes),
         }
         message.merge!(recipient_params(user))
+        message[:scheduled_at] = serialize_scheduled_at(scheduled_at) unless scheduled_at.nil?
 
         SendResult.new(@client.post("/api/v1/messages", body: { message: message }), client: @client)
       end
 
       private
 
+      # A `Date` has a day but no instant, so there's no correct offset to emit
+      # -- `DateTime` (which `Date` is a superclass of) is fine, only a bare
+      # `Date` is rejected. Everything else that responds to `iso8601` (`Time`,
+      # `DateTime`, `ActiveSupport::TimeWithZone`) is serialized with it; a
+      # `String` passes through for the server to validate.
+      def serialize_scheduled_at(value)
+        return value if value.is_a?(String)
+
+        if value.is_a?(Date) && !value.is_a?(DateTime)
+          raise ArgumentError, "scheduled_at must be a Time, DateTime, or TimeWithZone -- " \
+                                "a Date has no instant, so there is no offset to serialize"
+        end
+
+        unless value.respond_to?(:iso8601)
+          raise ArgumentError, "scheduled_at must be a Time, DateTime, TimeWithZone, or ISO 8601 String"
+        end
+
+        value.iso8601
+      end
+
       # 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)

data/lib/relaygrid/send_result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "time"
+
 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
@@ -7,7 +9,7 @@ module RelayGrid
   # realtime channel.
   class SendResult
     attr_reader :message_id, :push_token, :push_token_expires_at, :deliveries,
-                :rendered_subject, :rendered_body, :raw
+                :rendered_subject, :rendered_body, :scheduled_at, :raw
 
     def initialize(body, client:)
       @raw = body
@@ -17,6 +19,7 @@ module RelayGrid
       @message_id = message["id"]
       @rendered_subject = message["rendered_subject"]
       @rendered_body = message["rendered_body"]
+      @scheduled_at = parse_time(message["scheduled_at"])
 
       @push_token = body["push_token"]
       expires_in = body["push_token_expires_in"]
@@ -43,16 +46,28 @@ module RelayGrid
       deliveries.find { |delivery| delivery.channel_type == channel_type.to_s }
     end
 
+    # True when this send was scheduled for later rather than sent immediately.
+    def scheduled?
+      !scheduled_at.nil?
+    end
+
     # Poll until every delivery reaches a terminal state, or `timeout` seconds
     # elapse. A delivery the server is still retrying reads `retrying`.
     #
+    # A `scheduled` delivery is never terminal -- nothing has been handed to a
+    # provider yet, so there is nothing to settle -- and polling it would just
+    # burn the full `timeout` waiting for a state change that isn't coming
+    # until dispatch. When `scheduled?` is true, this returns `deliveries`
+    # (each still reading `status: "scheduled"`) immediately without calling
+    # the API at all.
+    #
     # @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?
+      return deliveries if deliveries.empty? || scheduled?
 
       @client.deliveries.wait_for(
         delivery_ids,
@@ -70,5 +85,15 @@ module RelayGrid
       "#<RelayGrid::SendResult message_id: #{message_id.inspect}, " \
         "delivery_ids: #{delivery_ids.inspect}, push: #{push?}>"
     end
+
+    private
+
+    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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: relaygrid
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ali Zand
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -153,13 +167,13 @@ files:
 - lib/relaygrid/webhooks.rb
 - lib/relaygrid/websocket_client.rb
 - sig/relaygrid.rbs
-homepage: https://github.com/alizand1992/relaygrid-gem
+homepage: https://git.relaygrid.dev/relaygrid/relaygrid-gem
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/alizand1992/relaygrid-gem
-  source_code_uri: https://github.com/alizand1992/relaygrid-gem
-  changelog_uri: https://github.com/alizand1992/relaygrid-gem/blob/master/CHANGELOG.md
+  homepage_uri: https://git.relaygrid.dev/relaygrid/relaygrid-gem
+  source_code_uri: https://git.relaygrid.dev/relaygrid/relaygrid-gem
+  changelog_uri: https://git.relaygrid.dev/relaygrid/relaygrid-gem/-/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: