expo_notifier 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2d86c0f277972155ddcf39b833745bfdaef1a94173ba61e90f92c8b1715b5920
+  data.tar.gz: a86943ba071821f9432efe3855abab57d1ba89f3424af4dd22619bfec1ef2322
+SHA512:
+  metadata.gz: 0c0f39964de4d9d00228e002048eba5ebffc34c2c51d56703bef71d5539e5751a38cb1766a28e7d04d0fc8789f7cc644a00ffe8a8b370ddf89f55cee116b53aa
+  data.tar.gz: d962ac34f292bda4f07956dd084884a6fb49f883671a271944e7493e2798a1e800dbfbb0f1932b9e3db21bf4a0c50b8f0ce12e3ffdfc07f9918af29dd507c955

data/.ruby-version

@@ -0,0 +1 @@
+4.0.0

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.1.0] - 2026-01-06
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Michał Zaporski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+[![Ruby](https://github.com/MichalZaporski/expo_notifier/actions/workflows/main.yml/badge.svg)](https://github.com/MichalZaporski/expo_notifier/actions/workflows/main.yml)
+
+# ExpoNotifier
+
+A Ruby client for the Expo Push Notifications API, providing typed request/response objects, automatic payload mapping, error classification, and configurable HTTP behavior. It is built on Faraday for HTTP communication.
+
+The library currently supports:
+
+- Sending push notifications
+
+- Fetching push notification receipts
+
+- Validating Expo push tokens
+
+More information about the Expo API you can [find here.](https://docs.expo.dev/push-notifications/sending-notifications/)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add expo_notifier
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install expo_notifier
+```
+
+## Usage
+
+### SendPushNotifications
+
+#### Example
+
+```ruby
+params = ExpoNotifier::Mapper::PushMessages.build do |msgs|
+  msgs.push_message do |msg|
+    msg.to    = ['ExponentPushToken[xxxxxxxx]']
+    msg.title = 'Title'
+    msg.body  = 'Body'
+    msg.data  = { order_id: 123 }
+  end
+  msgs.push_message do |msg|
+    msg.to    = ['ExponentPushToken[xxxxxxxx]']
+    msg.title = 'Title'
+    msg.body  = 'Second msg'
+  end
+end
+
+request = ExpoNotifier::Request::SendPushNotifications.new(params)
+response = request.execute
+if response.success?
+  response.body.data.each do |ticket|
+    puts "Notification status: #{ticket.status}, id: #{ticket.id}"
+  end
+end
+```
+
+#### Available message parameters
+
+| Parameter            | Type            |
+| -------------------- | --------------- |
+| `to`                 | `Array[String]` |
+| `title`              | `String`        |
+| `body`               | `String`        |
+| `data`               | `Hash`          |
+| `content_available`  | `Boolean`       |
+| `ttl`                | `Integer`       |
+| `expiration`         | `Integer`       |
+| `priority`           | `String`        |
+| `subtitle`           | `String`        |
+| `sound`              | `String`        |
+| `badge`              | `Integer`       |
+| `interruption_level` | `String`        |
+| `channel_id`         | `String`        |
+| `icon`               | `String`        |
+| `category_id`        | `String`        |
+| `mutable_content`    | `Boolean`       |
+| `rich_content.image` | `String`        |
+
+
+### GetPushNotificationReceipts
+
+#### Example
+
+``` ruby
+params = ExpoNotifier::Mapper::PushReceiptIds.new(
+  ids: ['receipt-id-1', 'receipt-id-2'],
+)
+
+request = ExpoNotifier::Request::GetPushNotificationReceipts.new(params)
+response = request.execute
+if response.success?
+  response.body.data.each do |receipt_id, receipt|
+    puts "Receipt #{receipt_id}: status=#{receipt.status}, message=#{receipt.message}"
+  end
+end
+```
+
+### Request configuration
+
+Each request accepts optional configuration parameters that control HTTP behavior.
+
+#### Available options
+
+```ruby
+access_token:       String   # Adds Authorization: Bearer <token>
+faraday_adapter:    Symbol   # Default: your default Faraday adapter
+base_url:           String   # API base URL, default: https://exp.host
+write_timeout:      Integer  # Write timeout in seconds, default: 5
+open_timeout:       Integer  # Open timeout in seconds, default: 5
+read_timeout:       Integer  # Read timeout in seconds, default: 30
+gzip:               Boolean  # Enable gzip compression, default: true
+gzip_min_size:      Integer  # Minimum request body size to enable gzip, default: 1024 bytes
+additional_headers: Hash     # Your additional headers
+```
+
+#### Example
+
+```ruby
+request = ExpoNotifier::Request::SendPushNotifications.new(
+  params,
+  access_token: 'secret-token',
+  base_url: 'https://example.test',
+  gzip_min_size: 512,
+  additional_headers: {
+    'X-Custom-Header' => 'custom',
+  },
+)
+```
+
+### Response Handling
+
+All requests return a Response object exposing:
+
+```ruby
+response.status_code
+response.duration
+response.headers
+response.body
+
+response.success?                   # 200
+response.malformed_request_error?   # 400
+response.too_many_requests_error?   # 429
+response.server_error?              # 5xx
+response.communication_error?       # HTTP communication error
+response.communication_error_message
+```
+
+### Expo push token validation
+
+The library provides a helper for validating Expo push tokens before sending requests. Usage:
+
+```ruby
+ExpoNotifier.expo_push_token?('ExponentPushToken[abcdef123456]')
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/MichalZaporski/expo_notifier.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+desc 'Run Sorbet type checking'
+task :typecheck do
+  sh 'bundle exec srb tc'
+end
+
+task default: %i[test rubocop typecheck]

data/lib/expo_notifier/mapper/base.rb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'active_support/core_ext/string'
+require 'shale'
+require 'shale/builder'
+
+module ExpoNotifier
+  module Mapper
+    # An abstract mapper class.
+    # @abstract
+    class Base < Shale::Mapper
+      include Shale::Builder
+
+      class << self
+        alias orig_attribute attribute
+
+        #: (Symbol, *Object, ?as: String?, **Object) ?{ -> void } -> void
+        def attribute(name, *args, as: nil, **kwargs, &block)
+          json_mapping.finalize! unless json_mapping.finalized?
+          T.unsafe(self).orig_attribute(name, *args, **kwargs, &block) # rubocop:disable Sorbet/ForbidTUnsafe
+          as ||= name.to_s.camelize(:lower)
+
+          json_mapping.map(as, to: name)
+        end
+      end
+
+    end
+  end
+end

data/lib/expo_notifier/mapper/error.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ExpoNotifier
+  module Mapper
+    class Error < Base
+      attribute :code, Shale::Type::String, doc: <<~DOC
+        Available values:
+
+        - TOO_MANY_REQUESTS: You are exceeding the request limit of 600 notifications per second per project.
+
+        - PUSH_TOO_MANY_EXPERIENCE_IDS: You are trying to send push notifications to different Expo experiences.
+
+        - PUSH_TOO_MANY_NOTIFICATIONS: You are trying to send more than 100 push notifications in one request.
+
+        - PUSH_TOO_MANY_RECEIPTS: You are trying to get more than 1000 push receipts in one request.
+      DOC
+
+      attribute :message, Shale::Type::String
+    end
+  end
+end

data/lib/expo_notifier/mapper/push_message.rb

@@ -0,0 +1,132 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'rich_content'
+
+module ExpoNotifier
+  module Mapper
+    class PushMessage < Base
+      attribute :to, Shale::Type::String, collection: true, doc: <<~DOC
+        Android and iOS
+
+        An array of Expo push tokens specifying the recipient(s) of this message.
+      DOC
+
+      attribute :content_available, Shale::Type::Boolean, as: '_contentAvailable', doc: <<~DOC
+        iOS Only
+
+        When this is set to true, the notification will cause the iOS app to start in the background to
+        run a background task. Your app needs to be configured to support this.
+      DOC
+
+      attribute :data, Shale::Type::Value, doc: <<~DOC
+        Android and iOS
+
+        A JSON object delivered to your app.It may be up to about 4KiB; the total notification payload
+        sent to Apple and Google must be at most 4KiB or else you will get a "Message Too Big" error.
+      DOC
+
+      attribute :title, Shale::Type::String, doc: <<~DOC
+        Android and iOS
+
+        The title to display in the notification. Often displayed above the notification body.
+        Maps to `AndroidNotification.title` and `aps.alert.title`.
+      DOC
+
+      attribute :body, Shale::Type::String, doc: <<~DOC
+        Android and iOS
+
+        The message to display in the notification. Maps to `AndroidNotification.body` and `aps.alert.body`.
+      DOC
+
+      attribute :ttl, Shale::Type::Integer, doc: <<~DOC
+        Android and iOS
+
+        Time to Live: the number of seconds for which the message may be kept around for redelivery if
+        it hasn't been delivered yet. Defaults to undefined to use the respective defaults of each
+        provider (1 month for Android/FCM as well as iOS/APNs).
+      DOC
+
+      attribute :expiration, Shale::Type::Integer, doc: <<~DOC
+        Android and iOS
+
+        Timestamp since the Unix epoch specifying when the message expires.
+        Same effect as `ttl` (`ttl` takes precedence over `expiration`).
+      DOC
+
+      attribute :priority, Shale::Type::String, doc: <<~DOC
+        Android and iOS
+
+        Accepted values: 'default' | 'normal' | 'high'
+
+        The delivery priority of the message. Specify default or omit this field to use the default priority
+        on each platform ("normal" on Android and "high" on iOS).
+      DOC
+
+      attribute :subtitle, Shale::Type::String, doc: <<~DOC
+        iOS Only
+
+        The subtitle to display in the notification below the title. Maps to `aps.alert.subtitle`.
+      DOC
+
+      attribute :sound, Shale::Type::String, doc: <<~DOC
+        iOS Only
+
+        Play a sound when the recipient receives this notification. Specify default to play the device's
+        default notification sound, or omit this field to play no sound. Custom sounds need to be configured
+        via the config plugin and then specified including the file extension. Example: bells_sound.wav.
+      DOC
+
+      attribute :badge, Shale::Type::Integer, doc: <<~DOC
+        iOS Only
+
+        Number to display in the badge on the app icon. Specify zero to clear the badge.
+      DOC
+
+      attribute :interruption_level, Shale::Type::String, doc: <<~DOC
+        iOS Only
+
+        Accepted values: 'active' | 'critical' | 'passive' | 'time-sensitive'
+
+        The importance and delivery timing of a notification. The string values correspond to the
+        `UNNotificationInterruptionLevel` enumeration cases.
+      DOC
+
+      attribute :channel_id, Shale::Type::String, doc: <<~DOC
+        Android Only
+
+        ID of the Notification Channel through which to display this notification. If an ID is specified but
+        the corresponding channel does not exist on the device (that has not yet been created by your app),
+        the notification will not be displayed to the user.
+      DOC
+
+      attribute :icon, Shale::Type::String, doc: <<~DOC
+        Android Only
+
+        The notification's icon. Name of an Android drawable resource (example: my_icon).
+        Defaults to the icon specified in the config plugin.
+      DOC
+
+      attribute :rich_content, RichContent, doc: <<~DOC
+        Android and iOS
+
+        Currently supports setting a notification image. Provide an object with key image and value of
+        type string, which is the image URL. Android will show the image out of the box. On iOS, you need to add
+        a Notification Service Extension target to your app.
+      DOC
+
+      attribute :category_id, Shale::Type::String, doc: <<~DOC
+        Android and iOS
+
+        ID of the notification category that this notification is associated with.
+      DOC
+
+      attribute :mutable_content, Shale::Type::Boolean, doc: <<~DOC
+        iOS Only
+
+        Specifies whether this notification can be intercepted by the client app. Defaults to false.
+      DOC
+    end
+  end
+end

data/lib/expo_notifier/mapper/push_messages.rb

@@ -0,0 +1,15 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'push_message'
+
+module ExpoNotifier
+  module Mapper
+    class PushMessages < Base
+      attribute :push_message, PushMessage, collection: true, doc: <<~DOC
+        An array of push messages.
+      DOC
+    end
+  end
+end

data/lib/expo_notifier/mapper/push_receipt.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'push_receipt_error_details'
+
+module ExpoNotifier
+  module Mapper
+    class PushReceipt < Base
+      attribute :status, Shale::Type::String, doc: <<~DOC
+        Available values: 'error' | 'ok'
+      DOC
+
+      attribute :message, Shale::Type::String, doc: <<~DOC
+        Error message. Only populated if `status` is equal to `error`.
+      DOC
+
+      attribute :details, PushReceiptErrorDetails, doc: <<~DOC
+        Error details. Only populated if `status` is equal to `error`.
+      DOC
+    end
+  end
+end

data/lib/expo_notifier/mapper/push_receipt_error_details.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ExpoNotifier
+  module Mapper
+    class PushReceiptErrorDetails < Base
+      attribute :error, Shale::Type::String, doc: <<~DOC
+        Available values:
+
+        - DeviceNotRegistered: The device cannot receive push notifications anymore and you should stop
+        sending messages to the corresponding Expo push token.
+
+        - MessageTooBig: The total notification payload was too large. On Android and iOS, the total payload must be at most 4096 bytes.
+
+        - MismatchSenderId: This indicates that there is an issue with your FCM push credentials.
+
+        - InvalidCredentials: Your push notification credentials for your standalone app are invalid.
+      DOC
+    end
+  end
+end

data/lib/expo_notifier/mapper/push_receipt_ids.rb

@@ -0,0 +1,16 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'push_ticket'
+require_relative 'error'
+
+module ExpoNotifier
+  module Mapper
+    class PushReceiptIds < Base
+      attribute :ids, Shale::Type::String, collection: true, doc: <<~DOC
+        An array of Expo push receipt ids.
+      DOC
+    end
+  end
+end

data/lib/expo_notifier/mapper/push_receipts.rb

@@ -0,0 +1,38 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'push_receipt'
+require_relative 'error'
+
+module ExpoNotifier
+  module Mapper
+    class PushReceipts < Base
+
+      # Hash where keys are receipt IDs and values are push receipts
+      #: Hash[String, PushReceipt]
+      attr_accessor :data
+
+      attribute :errors, Error, collection: true, doc: <<~DOC
+        Errors — only populated if there was an error with the entire request.
+      DOC
+
+      json do
+        map 'data', using: {
+          from: :parse_push_receipts_from_json,
+          to:   :undefined,
+        }
+
+        map 'errors', to: :errors
+      end
+
+      #: (ExpoNotifier::Mapper::PushReceipts, Hash[String, Object]) -> void
+      def parse_push_receipts_from_json(model, value)
+        model.data = value.transform_values do |receipt_hash|
+          PushReceipt.from_hash(receipt_hash)
+        end
+      end
+
+    end
+  end
+end

data/lib/expo_notifier/mapper/push_ticket.rb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'push_ticket_error_details'
+
+module ExpoNotifier
+  module Mapper
+    class PushTicket < Base
+      attribute :status, Shale::Type::String, doc: <<~DOC
+        Available values: 'error' | 'ok'
+
+        A status of ok along with a receipt ID means that the message was received by Expo's servers,
+        not that it was received by the user (for that you will need to check the push receipt).
+      DOC
+
+      attribute :id, Shale::Type::String, doc: <<~DOC
+        The Receipt ID.
+      DOC
+
+      attribute :message, Shale::Type::String, doc: <<~DOC
+        Error message. Only populated if `status` is equal to `error`.
+      DOC
+
+      attribute :details, PushTicketErrorDetails, doc: <<~DOC
+        Error details. Only populated if `status` is equal to `error`.
+      DOC
+    end
+  end
+end

data/lib/expo_notifier/mapper/push_ticket_error_details.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ExpoNotifier
+  module Mapper
+    class PushTicketErrorDetails < Base
+      attribute :error, Shale::Type::String, doc: <<~DOC
+        Available values:
+
+        - DeviceNotRegistered: The device cannot receive push notifications anymore and you should stop
+        sending messages to the corresponding Expo push token.
+      DOC
+
+      attribute :expo_push_token, Shale::Type::String
+    end
+  end
+end

data/lib/expo_notifier/mapper/push_tickets.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'push_ticket'
+require_relative 'error'
+
+module ExpoNotifier
+  module Mapper
+    class PushTickets < Base
+      attribute :data, PushTicket, collection: true, doc: <<~DOC
+        An array of Expo push tickets.
+
+        The Expo push notification service responds with push tickets upon successfully receiving notifications.
+        A push ticket indicates that Expo has received your notification payload but may still need to send it.
+        Each push ticket contains a ticket ID, which you later use to look up a push receipt.
+        A push receipt is available after Expo has tried to deliver the notification to FCM or APNs.
+        It tells you whether delivery to the push notification provider was successful.
+      DOC
+
+      attribute :errors, Error, collection: true, doc: <<~DOC
+        Errors — only populated if there was an error with the entire request.
+      DOC
+    end
+  end
+end

data/lib/expo_notifier/mapper/rich_content.rb

@@ -0,0 +1,17 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ExpoNotifier
+  module Mapper
+    class RichContent < Base
+      attribute :image, Shale::Type::String, doc: <<~DOC
+        Android and iOS
+
+        The image URL. Android will show the image out of the box. On iOS, you need to add a Notification Service Extension
+        target to your app. See this example on how to do that.
+      DOC
+    end
+  end
+end