noticed 2.0.2 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2526071997479bc9e570c51d5b148ce569f9afb45912b6c2b1bea71be65fc30e
-  data.tar.gz: ffa64bdc283245497a456f125680a41da2cf0ba7ad52c2c6320af24b5ec3d956
+  metadata.gz: af64af61a772e3e67456ecab3807b7ad1c9c689a8b411d45583f1c68f61ebc4e
+  data.tar.gz: eed9bec207e731b07727e7a85d500e90d7f9db6437cdfadc6ac0b39153a2bb11
 SHA512:
-  metadata.gz: 1cf980bb8d8ae9057ff80bd6313158997b1cee1fd664e3e4fef819d1cf3ba5cac469e55e02e8c4d1a2e70bf53658a58cd6c524e93da00fb2dc7a228bdda1a195
-  data.tar.gz: 109fe7195032238f53ed001910db4bdce5e58a89543b45c2aefc88046f7e649b68cd77421dc005fa932fe1984e610349597b1f5ffb60fde9550356b91585f5b9
+  metadata.gz: c442042bac58a37b9f3adca3b534c20839f662ce9c7d3336691425e0363990686bbfefbc42cfbf581593d11b2fc24ebea99c6b925bafde71934ba9d9ef580a8a
+  data.tar.gz: 26215e49a2786596852dcf539dab854a5e8550eb83c1240acfe872aa64a163227237ca212d6e9f936d537768df6117793fa2b9f1234cd525083393604860bf2b

data/README.md

@@ -62,13 +62,13 @@ rails db:migrate
 
 Noticed operates with a few constructs: Notifiers, delivery methods, and Notification records.
 
-To start, generate a Notifier: 
+To start, generate a Notifier:
 
 ```sh
 rails generate noticed:notifier NewCommentNotifier
 ```
 
-#### Notifier Objects
+### Notifier Objects
 
 Notifiers are essentially the controllers of the Noticed ecosystem and represent an Event. As such, we recommend naming them with the event they model in mind — be it a `NewSaleNotifier,` `ChargeFailureNotifier`, etc.
 
@@ -117,7 +117,75 @@ end
 
 For deeper specifics on setting up the `:action_cable`, `:email`, and `:discord` (bulk) delivery methods, refer to their docs: [`action_cable`](docs/delivery_methods/action_cable.md), [`email`](docs/delivery_methods/email.md), and [`discord` (bulk)](docs/bulk_delivery_methods/discord.md).
 
-##### Required Params
+#### Delivery Method Configuration
+
+Each delivery method can be configured with a block that yields a `config` object.
+
+Procs/Lambdas will be evaluated when needed and symbols can be used to call a method.
+
+If you are using a symbol to call a method, we pass the notification object as an argument to the method. This allows you to access the notification object within the method.
+Your method must accept a single argument. If you don't need to use the object you can just use `(*)`.
+
+```ruby
+class CommentNotifier < Noticed::Event
+  deliver_by :ios do |config|
+    config.format = :ios_format
+    config.apns_key = :ios_cert
+    config.key_id = :ios_key_id
+    config.team_id = :ios_team_id
+    config.bundle_identifier = Rails.application.credentials.dig(:ios, :bundle_identifier)
+    config.device_tokens = :ios_device_tokens
+    config.if = ->(notification) { recipient.send_ios_notification? }
+  end
+
+  def ios_format(apn)
+    apn.alert = { title:, body: }
+    apn.mutable_content = true
+    apn.content_available = true
+    apn.sound = "notification.m4r"
+    apn.custom_payload = {
+      url:,
+      type: self.class.name,
+      id: record.id,
+      image_url: "" || image_url,
+      params: params.to_json
+    }
+  end
+
+  def ios_cert(*)
+    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :apns_token_cert)
+  end
+
+  def ios_key_id(*)
+    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :key_id)
+  end
+
+  def ios_team_id(*)
+    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :team_id)
+  end
+
+  def ios_bundle_id(*)
+    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :bundle_identifier)
+  end
+
+  def ios_device_tokens(notification)
+    notification.recipient.ios_device_tokens
+  end
+
+  def send_ios_notification?(notification)
+    recipient = notification.recipient
+    return false unless recipient.is_a?(User)
+
+    recipient.send_notifications?
+  end
+
+  def url
+    comment_thread_path(record.thread)
+  end
+end
+```
+
+#### Required Params
 
 While explicit / required parameters are completely optional, Notifiers are able to opt in to required parameters via the `required_params` method:
 
@@ -126,7 +194,10 @@ class CarSaleNotifier < Noticed::Event
   deliver_by :email { |c| c.mailer = "BranchMailer" }
 
   # `record` is the Car record, `Branch` is the dealership
-  required_params :record, :branch
+  required_params :branch
+
+  # To validate the `:record` param, add a validation since it is an association on the Noticed::Event
+  validates :record, presence: true
 end
 ```
 
@@ -141,8 +212,7 @@ CarSaleNotifier.with(record: Car.last, branch: Branch.last).deliver(Branch.hq)
 ```
 
 
-
-##### Helper Methods
+#### Helper Methods
 
 Notifiers can implement various helper methods, within a `notification_methods` block, that make it easier to render the resulting notification directly. These helpers can be helpful depending on where and how you choose to render notifications. A common use is rendering a user’s notifications in your web UI as standard ERB. These notification helper methods make that rendering much simpler:
 
@@ -156,7 +226,7 @@ Notifiers can implement various helper methods, within a `notification_methods`
 
 On the other hand, if you’re using email delivery, ActionMailer has its own full stack for setting up objects and rendering. Your notification helper methods will always be available from the notification object, but using ActionMailer’s own paradigms may fit better for that particular delivery method. YMMV.
 
-######  URL Helpers
+####  URL Helpers
 
 Rails url helpers are included in Notifiers by default so you have full access to them in your notification helper methods, just like you would in your controllers and views.
 
@@ -166,7 +236,7 @@ _But don't forget_, you'll need to configure `default_url_options` in order for
 Rails.application.routes.default_url_options[:host] = 'localhost:3000'
 ```
 
-###### Translations
+#### Translations
 
 We've also included Rails’ `translate` and `t` helpers for you to use in your notification helper methods. This also provides an easy way of scoping translations. If the key starts with a period, it will automatically scope the key under `notifiers`, the underscored name of the notifier class, and `notification`. For example:
 
@@ -175,13 +245,13 @@ From the above Notifier...
 ```ruby
 class NewCommentNotifier < Noticed::Event
   # ...
-  
+
   notification_methods do
     def message
       t(".message")
     end
   end
-  
+
   # ...
 end
 ```
@@ -206,7 +276,7 @@ en:
 
 Or, if you have your Notifier within another module, such as `Admin::NewCommentNotifier`, the resulting lookup path will be `en.notifiers.admin.new_comment_notifier.notification.message` (modules become nesting steps).
 
-##### Tip: Capture User Preferences
+#### Tip: Capture User Preferences
 
 You can use the `if:` and `unless: ` options on your delivery methods to check the user's preferences and skip processing if they have disabled that type of notification.
 
@@ -221,8 +291,42 @@ class CommentNotifier < Noticed::Event
   end
 end
 ```
+#### Tip: Extracting Delivery Method Configurations
+
+If you want to reuse delivery method configurations across multiple Notifiers, you can extract them into a module and include them in your Notifiers.
+
+```ruby
+# /app/notifiers/notifiers/comment_notifier.rb
+class CommentNotifier < Noticed::Event
+  include IosNotifier
+  include AndriodNotifer
+  include EmailNotifier
+
+  validates :record, presence: true
+end
+
+# /app/notifiers/concerns/ios_notifier.rb
+module IosNotifier
+  extend ActiveSupport::Concern
+
+  included do
+    deliver_by :ios do |config|
+      config.device_tokens = ->(recipient) { recipient.notification_tokens.where(platform: :iOS).pluck(:token) }
+      config.format = ->(apn) {
+        apn.alert = "Hello world"
+        apn.custom_payload = {url: root_url(host: "example.org")}
+      }
+      config.bundle_identifier = Rails.application.credentials.dig(:ios, :bundle_id)
+      config.key_id = Rails.application.credentials.dig(:ios, :key_id)
+      config.team_id = Rails.application.credentials.dig(:ios, :team_id)
+      config.apns_key = Rails.application.credentials.dig(:ios, :apns_key)
+      config.if = ->(recipient) { recipient.ios_notifications? }
+    end
+  end
+end
+```
 
-**Shared Delivery Method Options**
+#### Shared Delivery Method Options
 
 Each of these options are available for every delivery method (individual or bulk). The value passed may be a lambda, a symbol that represents a callable method, a symbol value, or a string value.
 
@@ -232,7 +336,7 @@ Each of these options are available for every delivery method (individual or bul
 * `config.wait_until` — (Should yield a specific time object) Delays the job that runs this delivery method until the specific time specified
 * `config.queue` — Sets the ActiveJob queue name to be used for the job that runs this delivery method
 
-#### Sending Notifications
+### Sending Notifications
 
 Following the `NewCommentNotifier` example above, here’s how we might invoke the Notifier to send notifications to every author in the thread about a new comment being added:
 
@@ -400,6 +504,18 @@ class DeliveryMethods::WhatsApp < Noticed::DeliveryMethod
 end
 ```
 
+#### Callbacks
+
+Callbacks for delivery methods wrap the _actual_ delivery of the notification. You can use `before_deliver`, `around_deliver` and `after_deliver` in your custom delivery methods.
+
+```ruby
+class DeliveryMethods::Discord < Noticed::DeliveryMethod
+  after_deliver do
+    # Do whatever you want
+  end
+end
+```
+
 ### 📦 Database Model
 
 The Noticed database models include several helpful features to make working with notifications easier.
@@ -484,6 +600,14 @@ end
 # @post.noticed_events.each { |ne| ne.notifications... }
 ```
 
+#### ActiveJob Parent Class
+
+Noticed uses its own `Noticed::ApplicationJob` as the base job for all notifications.  In the event that you would like to customize the parent job class, there is a `parent_class` attribute that can be overridden with your own class.  This should be done in a `noticed.rb` initializer.
+
+```ruby
+Noticed.parent_class = "ApplicationJob"
+```
+
 #### Handling Deleted Records
 
 Generally we recommend using a `dependent: ___` relationship on your models to avoid cases where Noticed Events or Notifications are left lingering when your models are destroyed. In the case that they are or data becomes mis-matched, you’ll likely run into deserialization issues. That may be globally alleviated with the following snippet, but use with caution.
@@ -508,4 +632,3 @@ DATABASE_URL=postgres://127.0.0.1/noticed_test rails test
 
 ## 📝 License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-

data/app/channels/noticed/notification_channel.rb

@@ -1,5 +1,5 @@
 module Noticed
-  class NotificationChannel < ApplicationCable::Channel
+  class NotificationChannel < ::ApplicationCable::Channel
     def subscribed
       stream_for current_user
     end

data/app/models/concerns/noticed/deliverable.rb

@@ -91,7 +91,7 @@ module Noticed
     def recipient_attributes_for(recipient)
       {
         type: "#{self.class.name}::Notification",
-        recipient_type: recipient.class.name,
+        recipient_type: recipient.class.base_class.name,
         recipient_id: recipient.id
       }
     end
@@ -103,7 +103,7 @@ module Noticed
 
     def validate_params!
       required_param_names.each do |param_name|
-        raise ValidationError, "Param `#{param_name}` is required for #{self.class.name}." unless params[param_name].present?
+        raise ValidationError, "Param `#{param_name}` is required for #{self.class.name}." unless params.has_key?(param_name)
       end
     end
 

data/lib/generators/noticed/delivery_method_generator.rb

@@ -12,6 +12,7 @@ module Noticed
       desc "Generates a class for a custom delivery method with the given NAME."
 
       def generate_notification
+        template "application_delivery_method.rb", "app/notifiers/application_delivery_method.rb"
         template "delivery_method.rb", "app/notifiers/delivery_methods/#{singular_name}.rb"
       end
     end

data/lib/generators/noticed/notifier_generator.rb

@@ -7,12 +7,21 @@ module Noticed
     class NotifierGenerator < Rails::Generators::NamedBase
       include Rails::Generators::ResourceHelpers
 
+      check_class_collision suffix: "Notifier"
+
       source_root File.expand_path("../templates", __FILE__)
 
       desc "Generates a notification with the given NAME."
 
       def generate_notification
-        template "notifier.rb", "app/notifiers/#{file_path}.rb"
+        template "application_notifier.rb", "app/notifiers/application_notifier.rb"
+        template "notifier.rb", "app/notifiers/#{file_path}_notifier.rb"
+      end
+
+      private
+
+      def file_name # :doc:
+        @_file_name ||= super.sub(/_notifier\z/i, "")
       end
     end
   end

data/lib/generators/noticed/templates/application_delivery_method.rb.tt

@@ -0,0 +1,2 @@
+class ApplicationDeliveryMethod < Noticed::DeliveryMethod
+end

data/lib/generators/noticed/templates/application_notifier.rb.tt

@@ -0,0 +1,2 @@
+class ApplicationNotifier < Noticed::Event
+end

data/lib/generators/noticed/templates/delivery_method.rb.tt

@@ -1,4 +1,4 @@
-class DeliveryMethods::<%= class_name %> < Noticed::DeliveryMethod
+class DeliveryMethods::<%= class_name %> < ApplicationDeliveryMethod
   # Specify the config options your delivery method requires in its config block
   required_options # :foo, :bar
 

data/lib/generators/noticed/templates/notifier.rb.tt

@@ -2,7 +2,7 @@
 #
 # <%= class_name %>.with(record: @post, message: "New post").deliver(User.all)
 
-class <%= class_name %> < Noticed::Event
+class <%= class_name %>Notifier < ApplicationNotifier
   # Add your delivery methods
   #
   # deliver_by :email do |config|

data/lib/noticed/delivery_method.rb

@@ -1,8 +1,11 @@
 module Noticed
-  class DeliveryMethod < ApplicationJob
+  class DeliveryMethod < Noticed.parent_class.constantize
     include ApiClient
     include RequiredOptions
 
+    extend ActiveModel::Callbacks
+    define_model_callbacks :deliver
+
     class_attribute :logger, default: Rails.logger
 
     attr_reader :config, :event, :notification
@@ -19,7 +22,9 @@ module Noticed
       return false if config.has_key?(:if) && !evaluate_option(:if)
       return false if config.has_key?(:unless) && evaluate_option(:unless)
 
-      deliver
+      run_callbacks :deliver do
+        deliver
+      end
     end
 
     def deliver
@@ -40,7 +45,7 @@ module Noticed
 
       # Call method if symbol and matching method on Notifier
       elsif option.is_a?(Symbol) && event.respond_to?(option)
-        event.send(option, self)
+        event.send(option, notification)
 
       # Return the value
       else

data/lib/noticed/delivery_methods/fcm.rb

@@ -14,7 +14,7 @@ module Noticed
       def send_notification(device_token)
         post_request("https://fcm.googleapis.com/v1/projects/#{credentials[:project_id]}/messages:send",
           headers: {authorization: "Bearer #{access_token}"},
-          json: notification.instance_exec(device_token, &config[:json]))
+          json: format_notification(device_token))
       rescue Noticed::ResponseUnsuccessful => exception
         if exception.response.code == "404" && config[:invalid_token]
           notification.instance_exec(device_token, &config[:invalid_token])
@@ -23,6 +23,15 @@ module Noticed
         end
       end
 
+      def format_notification(device_token)
+        method = config[:json]
+        if method.is_a?(Symbol) && event.respond_to?(method)
+          event.send(method, device_token)
+        else
+          notification.instance_exec(device_token, &method)
+        end
+      end
+
       def credentials
         @credentials ||= begin
           value = evaluate_option(:credentials)

data/lib/noticed/delivery_methods/ios.rb

@@ -33,6 +33,7 @@ module Noticed
         apn.topic = evaluate_option(:bundle_identifier)
 
         if (method = config[:format])
+          method = event.send(method, apn) if method.is_a?(Symbol) && event.respond_to?(method)
           notification.instance_exec(apn, &method)
         elsif notification.params.try(:has_key?, :message)
           apn.alert = notification.params[:message]
@@ -70,9 +71,9 @@ module Noticed
       def connection_pool_options
         {
           auth_method: :token,
-          cert_path: StringIO.new(config.fetch(:apns_key)),
-          key_id: config.fetch(:key_id),
-          team_id: config.fetch(:team_id)
+          cert_path: StringIO.new(evaluate_option(:apns_key)),
+          key_id: evaluate_option(:key_id),
+          team_id: evaluate_option(:team_id)
         }
       end
 

data/lib/noticed/version.rb

@@ -1,3 +1,3 @@
 module Noticed
-  VERSION = "2.0.2"
+  VERSION = "2.0.4"
 end

data/lib/noticed.rb

@@ -39,6 +39,9 @@ module Noticed
     autoload :Webhook, "noticed/delivery_methods/webhook"
   end
 
+  mattr_accessor :parent_class
+  @@parent_class = "Noticed::ApplicationJob"
+
   class ValidationError < StandardError
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noticed
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.0.4
 platform: ruby
 authors:
 - Chris Oliver
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-19 00:00:00.000000000 Z
+date: 2024-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -50,6 +50,8 @@ files:
 - lib/generators/noticed/install_generator.rb
 - lib/generators/noticed/notifier_generator.rb
 - lib/generators/noticed/templates/README
+- lib/generators/noticed/templates/application_delivery_method.rb.tt
+- lib/generators/noticed/templates/application_notifier.rb.tt
 - lib/generators/noticed/templates/delivery_method.rb.tt
 - lib/generators/noticed/templates/notifier.rb.tt
 - lib/noticed.rb
@@ -94,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.4
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Notifications for Ruby on Rails applications