{"id":13416333,"url":"https://github.com/excid3/noticed","last_synced_at":"2025-04-22T18:16:34.577Z","repository":{"id":38335883,"uuid":"283022742","full_name":"excid3/noticed","owner":"excid3","description":"Notifications for Ruby on Rails applications","archived":false,"fork":false,"pushed_at":"2024-10-17T15:50:26.000Z","size":1559,"stargazers_count":2428,"open_issues_count":0,"forks_count":172,"subscribers_count":22,"default_branch":"main","last_synced_at":"2024-10-29T14:15:01.393Z","etag":null,"topics":["email","hacktoberfest","notifications","rails","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/excid3.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["excid3"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-07-27T21:39:18.000Z","updated_at":"2024-10-27T07:23:13.000Z","dependencies_parsed_at":"2023-12-07T16:46:25.963Z","dependency_job_id":"0c3e9335-6297-443d-9720-6f2150180940","html_url":"https://github.com/excid3/noticed","commit_stats":{"total_commits":515,"total_committers":77,"mean_commits":6.688311688311688,"dds":0.2951456310679612,"last_synced_commit":"d23f3d9aa10be8adfae8ed7306111f266d1e7fca"},"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Fnoticed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Fnoticed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Fnoticed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Fnoticed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/excid3","download_url":"https://codeload.github.com/excid3/noticed/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250296265,"owners_count":21407037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","hacktoberfest","notifications","rails","ruby"],"created_at":"2024-07-30T21:00:57.232Z","updated_at":"2025-04-22T18:16:34.529Z","avatar_url":"https://github.com/excid3.png","language":"Ruby","readme":"# Noticed\n\n## 🎉  Notifications for your Ruby on Rails app.\n\n[![Build Status](https://github.com/excid3/noticed/workflows/Tests/badge.svg)](https://github.com/excid3/noticed/actions) [![Gem Version](https://badge.fury.io/rb/noticed.svg)](https://badge.fury.io/rb/noticed)\n\n\u003e [!IMPORTANT]\n\u003e **⚠️ Upgrading from V1? Read the [Upgrade Guide](https://github.com/excid3/noticed/blob/main/UPGRADE.md)!**\n\nNoticed is a gem that allows your application to send notifications of varying types, over various mediums, to various recipients. Be it a Slack notification to your own team when some internal event occurs or a notification to your user, sent as a text message, email, and real-time UI element in the browser, Noticed supports all of the above (at the same time)!\n\nNoticed implements two top-level types of delivery methods:\n\n1. **Individual Deliveries**: Where each recipient gets their own notification\n\u003cdetails\u003e\n\u003csummary\u003e Show Example \u003c/summary\u003e\n\nLet’s use a car dealership as an example here. When someone purchases a car, a notification will be sent to the buyer with some contract details (“Congrats on your new 2024 XYZ Model...”), another to the car sales-person with different details (“You closed X deal; your commission is Y”), and another to the bank handling the loan with financial details (“New loan issued; amount $20,000...”). The event (the car being sold) necessitates multiple notifications being sent out to different recipients, but each contains its own unique information and should be separate from the others. These are individual deliveries.\n\u003c/details\u003e\n\n2. **Bulk Deliveries**: One notification for all recipients. This is useful for sending a notification to your Slack team, for example.\n\n\u003cdetails\u003e\n\u003csummary\u003e Show Example \u003c/summary\u003e\nLet’s continue with the car-sale example here. Consider that your development team created the car-sales application that processed the deal above and sent out the notifications to the three parties. For the sake of team morale and feeling the ‘wins’, you may want to implement a notification that notifies your internal development team whenever a car sells through your platform. In this case, you’ll be notifying many people (your development team, maybe others at your company) but with the same content (“someone just bought a car through our platform!”). This is a bulk delivery. It’s generally a single notification that many people just need to be made aware of.\n\nBulk deliveries are typically used to push notifications to other platforms where users are managed (Slack, Discord, etc.) instead of your own.\n\u003c/details\u003e\n\nDelivery methods we officially support:\n\n* [ActionCable](docs/delivery_methods/action_cable.md)\n* [Apple Push Notification Service](docs/delivery_methods/ios.md)\n* [Email](docs/delivery_methods/email.md)\n* [Firebase Cloud Messaging](docs/delivery_methods/fcm.md) (iOS, Android, and web clients)\n* [Microsoft Teams](docs/delivery_methods/microsoft_teams.md)\n* [Slack](docs/delivery_methods/slack.md)\n* [Twilio Messaging](docs/delivery_methods/twilio_messaging.md) - SMS, Whatsapp\n* [Vonage SMS](docs/delivery_methods/vonage_sms.md)\n* [Test](docs/delivery_methods/test.md)\n\nBulk delivery methods we support:\n\n* [Bluesky](docs/bulk_delivery_methods/bluesky.md)\n* [Discord](docs/bulk_delivery_methods/discord.md)\n* [Slack](docs/bulk_delivery_methods/slack.md)\n* [Webhook](docs/bulk_delivery_methods/webhook.md)\n\n## 🎬 Screencast\n\n\u003ca href=\"https://www.youtube.com/watch?v=SzX-aBEqnAc\"\u003e\u003cimg src=\"https://i.imgur.com/UvVKWwD.png\" title=\"How to add Notifications to Rails with Noticed\" width=\"50%\" /\u003e\u003c/a\u003e\n\n[Watch Screencast](https://www.youtube.com/watch?v=SzX-aBEqnAc)\n\n## 🚀 Installation\nRun the following command to add Noticed to your Gemfile:\n\n```ruby\nbundle add \"noticed\"\n```\n\nGenerate then run the migrations:\n\n```bash\nrails noticed:install:migrations\nrails db:migrate\n```\n\n## 📝 Usage\n\nNoticed operates with a few constructs: Notifiers, delivery methods, and Notification records.\n\nTo start, generate a Notifier:\n\n```bash\nrails generate noticed:notifier NewCommentNotifier\n```\n\n### Usage Contents\n- [Notifier Objects](#notifier-objects)\n  - [Delivery Method Configuration](#delivery-method-configuration)\n  - [Required Params](#required-params)\n  - [Helper Methods](#helper-methods)\n  - [URL Helpers](#url-helpers)\n  - [Translations](#translations)\n  - [Tip: Capture User Preferences](#tip-capture-user-preferences)\n  - [Tip: Extracting Delivery Method Configurations](#tip-extracting-delivery-method-configurations)\n  - [Shared Delivery Method Options](#shared-delivery-method-options)\n- [Sending Notifications](#-sending-notifications)\n- [Custom Noticed Model Methods](#custom-noticed-model-methods)\n\n### Notifier Objects\n\nNotifiers 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.\n\nNotifiers must inherit from `Noticed::Event`. This provides all of their functionality.\n\nA Notifier exists to declare the various delivery methods that should be used for that event _and_ any notification helper methods necessary in those delivery mechanisms. In this example we’ll deliver by `:action_cable` to provide real-time UI updates to users’ browsers, `:email` if they’ve opted into email notifications, and a bulk notification to `:discord` to tell everyone on the Discord server there’s been a new comment.\n\n```ruby\n# ~/app/notifiers/new_comment_notifier.rb\n\nclass NewCommentNotifier \u003c Noticed::Event\n  deliver_by :action_cable do |config|\n    config.channel = \"NotificationsChannel\"\n    config.stream = :some_stream\n  end\n\n  deliver_by :email do |config|\n    config.mailer = \"CommentMailer\"\n    config.if = -\u003e { !!recipient.preferences[:email] }\n  end\n\n  bulk_deliver_by :discord do |config|\n    config.url = \"https://discord.com/xyz/xyz/123\"\n    config.json = -\u003e {\n      {\n        message: message,\n        channel: :general\n      }\n    }\n  end\n\n  notification_methods do\n    # I18n helpers\n    def message\n      t(\".message\")\n    end\n\n    # URL helpers are accessible in notifications\n    # Don't forget to set your default_url_options so Rails knows how to generate urls\n    def url\n      user_post_path(recipient, params[:post])\n    end\n  end\nend\n```\n\nFor 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).\n\n#### Delivery Method Configuration\n\nEach delivery method can be configured with a block that yields a `config` object.\n\nProcs/Lambdas will be evaluated when needed and symbols can be used to call a method.\n\nWhen a lambda is passed, it will not pass any arguments and evaluates the Proc in the context of the Noticed::Notification\n\nIf 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.\nYour method must accept a single argument. If you don't need to use the object you can just use `(*)`.\n\n\u003cdetails\u003e\n\u003csummary\u003e Show Example \u003c/summary\u003e\n\n```ruby\nclass CommentNotifier \u003c Noticed::Event\n  deliver_by :ios do |config|\n    config.format = :ios_format\n    config.apns_key = :ios_cert\n    config.key_id = :ios_key_id\n    config.team_id = :ios_team_id\n    config.bundle_identifier = Rails.application.credentials.dig(:ios, :bundle_identifier)\n    config.device_tokens = :ios_device_tokens\n    config.if = -\u003e { recipient.send_ios_notification? }\n  end\n\n  def ios_format(apn)\n    apn.alert = { title:, body: }\n    apn.mutable_content = true\n    apn.content_available = true\n    apn.sound = \"notification.m4r\"\n    apn.custom_payload = {\n      url:,\n      type: self.class.name,\n      id: record.id,\n      image_url: \"\" || image_url,\n      params: params.to_json\n    }\n  end\n\n  def ios_cert(*)\n    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :apns_token_cert)\n  end\n\n  def ios_key_id(*)\n    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :key_id)\n  end\n\n  def ios_team_id(*)\n    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :team_id)\n  end\n\n  def ios_bundle_id(*)\n    Rails.application.credentials.dig(:ios, Rails.env.to_sym, :bundle_identifier)\n  end\n\n  def ios_device_tokens(notification)\n    notification.recipient.ios_device_tokens\n  end\n\n  def url\n    comment_thread_path(record.thread)\n  end\nend\n\nclass Recipient \u003c ApplicationRecord # or whatever your recipient model is\n  has_many :ios_device_tokens\n\n  def send_ios_notification?\n    # some logic\n  end\nend\n```\n\u003c/details\u003e\n\nMore examples are in the docs for each delivery method.\n\n#### Required Params\n\nWhile explicit / required parameters are completely optional, Notifiers are able to opt in to required parameters via the `required_params` method:\n\n```ruby\nclass CarSaleNotifier \u003c Noticed::Event\n  deliver_by :email { |c| c.mailer = \"BranchMailer\" }\n\n  # `record` is the Car record, `Branch` is the dealership\n  required_params :branch\n\n  # To validate the `:record` param, add a validation since it is an association on the Noticed::Event\n  validates :record, presence: true\nend\n```\n\nWhich will validate upon any invocation that the specified parameters are present:\n\n```ruby\nCarSaleNotifier.with(record: Car.last).deliver(Branch.last)\n#=\u003e Noticed::ValidationError(\"Param `branch` is required for CarSaleNotifier\")\n\nCarSaleNotifier.with(record: Car.last, branch: Branch.last).deliver(Branch.hq)\n#=\u003e OK\n```\n\n#### Helper Methods\n\nNotifiers 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:\n\n```erb\n\u003cdiv\u003e\n  \u003c% @user.notifications.each do |notification| %\u003e\n    \u003c%= link_to notification.message, notification.url %\u003e\n  \u003c% end %\u003e\n\u003c/div\u003e\n```\n\nOn 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.\n\n#### URL Helpers\n\nRails 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.\n\n_But don't forget_, you'll need to configure `default_url_options` in order for Rails to know what host and port to use when generating URLs.\n\n```ruby\nRails.application.routes.default_url_options[:host] = 'localhost:3000'\n```\n\n#### Translations\n\nWe'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:\n\nFrom the above Notifier...\n\n```ruby\nclass NewCommentNotifier \u003c Noticed::Event\n  # ...\n\n  notification_methods do\n    def message\n      t(\".message\")\n    end\n  end\n\n  # ...\nend\n```\n\nCalling the `message` helper in an ERB view:\n\n```erb\n\u003c%= @user.notifications.last.message %\u003e\n```\n\nWill look for the following translation path:\n\n```yml\n# ~/config/locales/en.yml\n\nen:\n  notifiers:\n    new_comment_notifier:\n      notification:\n        message: \"Someone posted a new comment!\"\n```\n\nOr, 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).\n\n#### Tip: Capture User Preferences\n\nYou 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.\n\nFor example:\n\n```ruby\nclass CommentNotifier \u003c Noticed::Event\n  deliver_by :email do |config|\n    config.mailer = 'CommentMailer'\n    config.method = :new_comment\n    config.if = -\u003e{ recipient.email_notifications? }\n  end\nend\n```\n\nIf you would like to skip the delivery job altogether, for example if you know that a user doesn't support the platform and you would like to save resources by not enqueuing the job, you can use `before_enqueue`.\n\nFor example:\n\n```ruby\nclass IosNotifier \u003c Noticed::Event\n  deliver_by :ios do |config|\n    # ...\n    config.before_enqueue = -\u003e{ throw(:abort) unless recipient.registered_ios? }\n  end\nend\n```\n\n#### Tip: Extracting Delivery Method Configurations\n\nIf you want to reuse delivery method configurations across multiple Notifiers, you can extract them into a module and include them in your Notifiers.\n\n```ruby\n# /app/notifiers/notifiers/comment_notifier.rb\nclass CommentNotifier \u003c Noticed::Event\n  include IosNotifier\n  include AndroidNotifier\n  include EmailNotifier\n\n  validates :record, presence: true\nend\n\n# /app/notifiers/concerns/ios_notifier.rb\nmodule IosNotifier\n  extend ActiveSupport::Concern\n\n  included do\n    deliver_by :ios do |config|\n      config.device_tokens = -\u003e(recipient) { recipient.notification_tokens.where(platform: :iOS).pluck(:token) }\n      config.format = -\u003e(apn) {\n        apn.alert = \"Hello world\"\n        apn.custom_payload = {url: root_url(host: \"example.org\")}\n      }\n      config.bundle_identifier = Rails.application.credentials.dig(:ios, :bundle_id)\n      config.key_id = Rails.application.credentials.dig(:ios, :key_id)\n      config.team_id = Rails.application.credentials.dig(:ios, :team_id)\n      config.apns_key = Rails.application.credentials.dig(:ios, :apns_key)\n      config.if = -\u003e { recipient.ios_notifications? }\n    end\n  end\nend\n```\n\n#### Shared Delivery Method Options\n\nEach 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.\n\n* `config.if` — Intended for a lambda or method; runs after the `wait` if configured; cancels the delivery method if returns falsey\n* `config.unless`  — Intended for a lambda or method; runs after the `wait` if configured; cancels the delivery method if returns truthy\n\nThe following are evaluated in the context of the Notification so it can be customize to the recipient:\n\n* `config.wait` — (Should yield an `ActiveSupport::Duration`) Delays the job that runs this delivery method for the given duration of time\n* `config.wait_until` — (Should yield a specific time object) Delays the job that runs this delivery method until the specific time specified\n* `config.queue` — Sets the ActiveJob queue name to be used for the job that runs this delivery method.\n\nWhen using a symbol, the matching method must be defined inside the `notification_methods` block:\n\n```ruby\n# app/notifiers/message_notifier.rb\nclass MessageNotifier \u003c Noticed::Event\n  deliver_by :delivery_method do |config|\n    config.queue = :queue\n  end\n\n  notification_methods do\n    def queue\n      \"high_priority\"\n    end\n  end\nend\n```\n\n### 📨 Sending Notifications\n\nFollowing 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:\n\n```ruby\nNewCommentNotifier.with(record: @comment, foo: \"bar\").deliver(@comment.thread.all_authors)\n```\n\nThis instantiates a new `NewCommentNotifier` with params (similar to ActiveJob, any serializable params are permitted), then delivers notifications to all authors in the thread.\n\n✨ The `record:` param is a special param that gets assigned to the `record` polymorphic association in the database. You should try to set the `record:` param where possible. This may be best understood as ‘the record/object this notification is _about_’, and allows for future queries from the record-side: “give me all notifications that were generated from this comment”.\n\nThis invocation will create a single `Noticed::Event` record and a `Noticed::Notification` record for each recipient. A background job will then process the Event and fire off a separate background job for each bulk delivery method _and_ each recipient + individual-delivery-method combination. In this case, that’d be the following jobs kicked off from this event:\n\n- A bulk delivery job for `:discord` bulk delivery\n- An individual delivery job for `:action_cable` method to the first thread author\n- An individual delivery job for `:email` method to the first thread author\n- An individual delivery job for `:action_cable` method to the second thread author\n- An individual delivery job for `:email` method to the second thread author\n- Etc...\n\n#### Tip: Define recipients inside the notifier\n\nRecipients can also be computed inside a notifier:\n\n```ruby\nclass NewCommentNotifier \u003c ApplicationNotifier\n  recipients -\u003e{ params[:record].thread.all_authors }\n\n  # or\n  recipients do\n    params[:record].thread.all_authors\n  end\n\n  # or\n  recipients :fetch_recipients\n\n  def fetch_recipients\n     # ...\n  end\nend\n```\n\nThis makes the code for sending a notification neater:\n\n```ruby\nNewCommentNotifier.with(record: @comment, foo: \"bar\").deliver\n```\n\n### Custom Noticed Model Methods\n\nIn order to extend the Noticed models you'll need to use a concern and a to_prepare block:\n\n```ruby\n# config/initializers/noticed.rb\nmodule NotificationExtensions\n  extend ActiveSupport::Concern\n\n  included do\n    belongs_to :organization\n\n    scope :filter_by_type, -\u003e(type) { where(type:) }\n    scope :exclude_type, -\u003e(type) { where.not(type:) }\n  end\n\n  # You can also add instance methods here\nend\n\nRails.application.config.to_prepare do\n  # You can extend Noticed::Event or Noticed::Notification here\n  Noticed::Event.include EventExtensions\n  Noticed::Notification.include NotificationExtensions\nend\n```\n\nThe `NotificationExtensions` class could be separated into it's own file and live somewhere like `app/models/concerns/notification_extensions.rb`.\n\nIf you do this, the `to_prepare` block will need to be in `application.rb` instead of an initializer.\n\n```ruby\n# config/application.rb\nmodule MyApp\n  class Application \u003c Rails::Application\n\n    # ...\n\n    config.to_prepare do\n      Noticed::Event.include EventExtensions\n      Noticed::Notification.include NotificationExtensions\n    end\n  end\nend\n```\n\n## ✅ Best Practices\n\n### Renaming Notifiers\n\nIf you rename a Notifier class your existing data and Noticed setup may break. This is because Noticed serializes the class name and sets it to the `type` column on the `Noticed::Event` record and the `type` column on the `Noticed::Notification` record.\n\nWhen renaming a Notifier class you will need to backfill existing Events and Notifications to reference the new name.\n\n```ruby\nNoticed::Event.where(type: \"OldNotifierClassName\").update_all(type: NewNotifierClassName.name)\n# and\nNoticed::Notification.where(type: \"OldNotifierClassName::Notification\").update_all(type: \"#{NewNotifierClassName.name}::Notification\")\n```\n\n## 🚛 Delivery Methods\n\nThe delivery methods are designed to be modular so you can customize the way each type gets delivered.\n\nFor example, emails will require a subject, body, and email address while an SMS requires a phone number and simple message. You can define the formats for each of these in your Notifier and the delivery method will handle the processing of it.\n\nIndividual delivery methods:\n\n* [ActionCable](docs/delivery_methods/action_cable.md)\n* [Apple Push Notification Service](docs/delivery_methods/ios.md)\n* [Email](docs/delivery_methods/email.md)\n* [Firebase Cloud Messaging](docs/delivery_methods/fcm.md) (iOS, Android, and web clients)\n* [Microsoft Teams](docs/delivery_methods/microsoft_teams.md)\n* [Slack](docs/delivery_methods/slack.md)\n* [Twilio Messaging](docs/delivery_methods/twilio_messaging.md) - SMS, Whatsapp\n* [Vonage SMS](docs/delivery_methods/vonage_sms.md)\n* [Test](docs/delivery_methods/test.md)\n\nBulk delivery methods:\n\n* [Bluesky](docs/bulk_delivery_methods/bluesky.md)\n* [Discord](docs/bulk_delivery_methods/discord.md)\n* [Slack](docs/bulk_delivery_methods/slack.md)\n* [Webhook](docs/bulk_delivery_methods/webhook.md)\n\n### No Delivery Methods\n\nIt’s worth pointing out that you can have a fully-functional and useful Notifier that has _no_ delivery methods. This means that invoking the Notifier and ‘sending’ the notification will only create new database records (no external surfaces like email, sms, etc.). This is still useful as it’s the database records that allow your app to render a user’s (or other object’s) notifications in your web UI.\n\nSo even with no delivery methods set, this example is still perfectly available and helpful:\n\n```erb\n\u003cdiv\u003e\n  \u003c% @user.notifications.each do |notification| %\u003e\n    \u003c%= link_to notification.message, notification.url %\u003e\n  \u003c% end %\u003e\n\u003c/div\u003e\n```\n\nSending a notification is entirely an internal-to-your-app function. Delivery methods just get the word out! But many apps may be fully satisfied without that extra layer.\n\n### Fallback Notifications\n\nA common pattern is to deliver a notification via a real (or real-ish)-time service, then, after some time has passed, email the user if they have not yet read the notification. You can implement this functionality by combining multiple delivery methods, the `wait` option, and the conditional `if` / `unless` option.\n\n```ruby\nclass NewCommentNotifier \u003c Noticed::Event\n  deliver_by :action_cable\n  deliver_by :email do |config|\n    config.mailer = \"CommentMailer\"\n    config.wait = 15.minutes\n    config.unless = -\u003e { read? }\n  end\nend\n```\n\nHere a notification will be created immediately in the database (for display directly in your app’s web interface) and sent via ActionCable. If the notification has not been marked `read` after 15 minutes, the email notification will be sent. If the notification has already been read in the app, the email will be skipped.\n\n_A note here: notifications expose a `#mark_as_read` method, but your app must choose when and where to call that method._\n\nYou can mix and match the options and delivery methods to suit your application specific needs.\n\n### 🚚 Custom Delivery Methods\n\nIf you want to build your own delivery method to deliver notifications to a specific service or medium that Noticed doesn’t (or doesn’t _yet_) support, you’re welcome to do so! To generate a custom delivery method, simply run\n\n`rails generate noticed:delivery_method Discord`\n\nThis will generate a new `ApplicationDeliveryMethod` and `DeliveryMethods::Discord` class inside the `app/notifiers/delivery_methods` folder, which can be used to deliver notifications to Discord.\n\n```ruby\nclass DeliveryMethods::Discord \u003c ApplicationDeliveryMethod\n  # Specify the config options your delivery method requires in its config block\n  required_options # :foo, :bar\n\n  def deliver\n    # Logic for sending the notification\n  end\nend\n\n```\n\nYou can use the custom delivery method thus created by adding a `deliver_by` line with a unique name and `class` option in your notification class.\n\n```ruby\nclass MyNotifier \u003c Noticed::Event\n  deliver_by :discord, class: \"DeliveryMethods::Discord\"\nend\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eTurbo Stream Custom Delivery Method Example\u003c/summary\u003e\n\nA common custom delivery method in the Rails world might be to Delivery to the web via turbo stream.\n\nNote: This example uses custom methods that extend the `Noticed::Notification` class.\n\nSee the [Custom Noticed Model Methods](#custom-noticed-model-methods) section for more information.\n\n```ruby\n# app/notifiers/delivery_methods/turbo_stream.rb\n\nclass DeliveryMethods::TurboStream \u003c ApplicationDeliveryMethod\n  def deliver\n    return unless recipient.is_a?(User)\n\n    notification.broadcast_update_to_bell\n    notification.broadcast_replace_to_index_count\n    notification.broadcast_prepend_to_index_list\n  end\nend\n```\n\n```ruby\n# app/models/concerns/noticed/notification_extensions.rb\n\nmodule Noticed::NotificationExtensions\n  extend ActiveSupport::Concern\n\n  def broadcast_update_to_bell\n    broadcast_update_to(\n      \"notifications_#{recipient.id}\",\n      target: \"notification_bell\",\n      partial: \"navbar/notifications/bell\",\n      locals: { user: recipient }\n    )\n  end\n\n  def broadcast_replace_to_index_count\n    broadcast_replace_to(\n      \"notifications_index_#{recipient.id}\",\n      target: \"notification_index_count\",\n      partial: \"notifications/notifications_count\",\n      locals: { count: recipient.reload.notifications_count, unread: recipient.reload.unread_notifications_count }\n    )\n  end\n\n  def broadcast_prepend_to_index_list\n    broadcast_prepend_to(\n      \"notifications_index_list_#{recipient.id}\",\n      target: \"notifications\",\n      partial: \"notifications/notification\",\n      locals: { notification: self }\n    )\n  end\nend\n```\n\u003c/details\u003e\n\nDelivery methods have access to the following methods and attributes:\n\n* `event` — The `Noticed::Event` record that spawned the notification object currently being delivered\n* `record` — The object originally passed into the Notifier as the `record:` param (see the ✨ note above)\n* `notification` — The `Noticed::Notification` instance being delivered. All notification helper methods are available on this object\n* `recipient` — The individual recipient object being delivered to for this notification (remember that each recipient gets their own instance of the Delivery Method `#deliver`)\n* `config` — The hash of configuration options declared by the Notifier that generated this notification and delivery\n* `params` — The parameters given to the Notifier in the invocation (via `.with()`)\n\n#### Validating config options passed to Custom Delivery methods\n\nThe presence of delivery method config options are automatically validated when declaring them with the `required_options` method. In the following example, Noticed will ensure that any Notifier using `deliver_by :email` will specify the `mailer` and `method` config keys:\n\n```ruby\nclass DeliveryMethods::Email \u003c Noticed::DeliveryMethod\n  required_options :mailer, :method\n\n  def deliver\n    # ...\n    method = config.method\n  end\nend\n```\n\nIf you’d like your config options to support dynamic resolution (set `config.foo` to a lambda or symbol of a method name etc.), you can use `evaluate_option`:\n\n```ruby\nclass NewSaleNotifier \u003c Noticed::Event\n  deliver_by :whats_app do |config|\n    config.day = -\u003e { is_tuesday? \"Tuesday\" : \"Not Tuesday\" }\n  end\nend\n\nclass DeliveryMethods::WhatsApp \u003c Noticed::DeliveryMethod\n  required_options :day\n\n  def deliver\n    # ...\n    config.day #=\u003e #\u003cProc:0x000f7c8 (lambda)\u003e\n    evaluate_option(:day) #=\u003e \"Tuesday\"\n  end\nend\n```\n\n#### Callbacks\n\nCallbacks 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.\n\n```ruby\nclass DeliveryMethods::Discord \u003c Noticed::DeliveryMethod\n  after_deliver do\n    # Do whatever you want\n  end\nend\n```\n\n## 📦 Database Model\n\nThe Noticed database models include several helpful features to make working with notifications easier.\n\n### Notification\n\n#### Class methods/scopes\n\n(Assuming your user `has_many :notifications, as: :recipient, class_name: \"Noticed::Notification\"`)\n\nSorting notifications by newest first:\n\n```ruby\n@user.notifications.newest_first\n```\n\nQuery for read or unread notifications:\n\n```ruby\nuser.notifications.read\nuser.notifications.unread\n```\n\nMarking all notifications as read or unread:\n\n```ruby\nuser.notifications.mark_as_read\nuser.notifications.mark_as_unread\n```\n\n#### Instance methods\n\nMark notification as read / unread:\n\n```ruby\n@notification.mark_as_read\n@notification.mark_as_read!\n@notification.mark_as_unread\n@notification.mark_as_unread!\n```\n\nCheck if read / unread:\n\n```ruby\n@notification.read?\n@notification.unread?\n```\n\n#### Associating Notifications\n\nAdding notification associations to your models makes querying, rendering, and managing notifications easy (and is a pretty critical feature of most applications).\n\nThere are two ways to associate your models to notifications:\n\n1. Where your object `has_many` notifications as the recipient (who you sent the notification to)\n2. Where your object `has_many` notifications as the `record` (what the notifications were about)\n\nIn the former, we’ll use a `has_many` to `:notifications`. In the latter, we’ll actually `has_many` to `:events`, since `record`s generate notifiable _events_ (and events generate notifications).\n\nWe can illustrate that in the following:\n\n```ruby\nclass User \u003c ApplicationRecord\n  has_many :notifications, as: :recipient, dependent: :destroy, class_name: \"Noticed::Notification\"\nend\n\n# All of the notifications the user has been sent\n# @user.notifications.each { |n| render(n) }\n\nclass Post \u003c ApplicationRecord\n  has_many :noticed_events, as: :record, dependent: :destroy, class_name: \"Noticed::Event\"\n  has_many :notifications, through: :noticed_events, class_name: \"Noticed::Notification\"\nend\n\n# All of the notification events this post generated\n# @post.notifications\n```\n\n#### ActiveJob Parent Class\n\nNoticed 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.\n\n```ruby\nNoticed.parent_class = \"ApplicationJob\"\n```\n\n#### Handling Deleted Records\n\nGenerally 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.\n\n```ruby\nclass ApplicationJob \u003c ActiveJob::Base\n  discard_on ActiveJob::DeserializationError\nend\n```\n\n### Customizing the Database Models\n\nYou can modify the database models by editing the generated migrations.\n\nOne common adjustment is to change the IDs to UUIDs (if you're using UUIDs in your app).\n\nYou can also add additional columns to the `Noticed::Event` and `Noticed::Notification` models.\n\n```ruby\n# This migration comes from noticed (originally 20231215190233)\nclass CreateNoticedTables \u003c ActiveRecord::Migration[7.1]\n  def change\n    create_table :noticed_events, id: :uuid do |t|\n      t.string :type\n      t.belongs_to :record, polymorphic: true, type: :uuid\n      t.jsonb :params\n\n      # Custom Fields\n      t.string :organization_id, type: :uuid, as: \"((params -\u003e\u003e 'organization_id')::uuid)\", stored: true\n      t.virtual :action_type, type: :string, as: \"((params -\u003e\u003e 'action_type'))\", stored: true\n      t.virtual :url, type: :string, as: \"((params -\u003e\u003e 'url'))\", stored: true\n\n      t.timestamps\n    end\n\n    create_table :noticed_notifications, id: :uuid do |t|\n      t.string :type\n      t.belongs_to :event, null: false, type: :uuid\n      t.belongs_to :recipient, polymorphic: true, null: false, type: :uuid\n      t.datetime :read_at\n      t.datetime :seen_at\n\n      t.timestamps\n    end\n\n    add_index :noticed_notifications, :read_at\n  end\nend\n```\n\nThe custom fields in the above example are stored as virtual columns.  These are populated from values passed in the `params` hash when creating the notifier.\n\n## 🙏 Contributing\n\nThis project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `standardrb` before submitting pull requests.\n\nRunning tests against multiple databases locally:\n\n```\nDATABASE_URL=sqlite3:noticed_test rails test\nDATABASE_URL=trilogy://root:@127.0.0.1/noticed_test rails test\nDATABASE_URL=postgres://127.0.0.1/noticed_test rails test\n```\n\n## 📝 License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":["https://github.com/sponsors/excid3"],"categories":["Ruby","Notifications"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcid3%2Fnoticed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexcid3%2Fnoticed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcid3%2Fnoticed/lists"}