{"id":14955933,"url":"https://github.com/sleede/wupee","last_synced_at":"2025-10-24T09:30:31.938Z","repository":{"id":27295950,"uuid":"30769756","full_name":"sleede/wupee","owner":"sleede","description":"Very simple notification system for rails","archived":false,"fork":false,"pushed_at":"2023-01-26T15:31:17.000Z","size":138,"stargazers_count":26,"open_issues_count":4,"forks_count":8,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-10-29T14:18:01.585Z","etag":null,"topics":["notifications","rails","ruby"],"latest_commit_sha":null,"homepage":"https://github.com/sleede/wupee","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/sleede.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-13T18:27:36.000Z","updated_at":"2020-07-06T13:03:19.000Z","dependencies_parsed_at":"2023-02-14T18:46:55.731Z","dependency_job_id":null,"html_url":"https://github.com/sleede/wupee","commit_stats":null,"previous_names":["sleede/notfity_with"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleede%2Fwupee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleede%2Fwupee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleede%2Fwupee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleede%2Fwupee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sleede","download_url":"https://codeload.github.com/sleede/wupee/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237944040,"owners_count":19391588,"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":["notifications","rails","ruby"],"created_at":"2024-09-24T13:12:02.566Z","updated_at":"2025-10-24T09:30:26.593Z","avatar_url":"https://github.com/sleede.png","language":"Ruby","readme":"# Breaking changes\n\nAfter using this gem in a few projects, I realized that all projects have different needs concerning the configuration of notifications (whether or not the user should received a notification or an email). We have apps which doesn't have the need for configuration so we are having a lots of Wupee::NotificationTypeConfiguration created and fetched from db for nothing. I really feel that the app should be responsible for addressing this. \nAlso, in some apps, I had to reopen classes to override default behaviour of the gem or skip callbacks and adding others and I was feeling that something was wrong. See [this issue](https://github.com/sleede/wupee/issues/7) for another example.\nTherefore, this branch removes all Wupee::NotificationTypeConfiguration but leaves a door open to customization, see [Wupee initializer](#initializer).\n\n\n# Wupee\n\nWupee is a simple gem which tries to fill the gap of lacking gems to manage **notifications** in Rails app.\nWupee is an opinionated solution which assumes that users needs to:\n\n* be able to receive notifications in the app\n* be able to receive notifications by email\n\nThe main object of the solution is the `Wupee::Notification` which stores:\n* receiver (polymorphic): the recipient of the message\n* attached_object (polymorphic): the subject of the notification\n* notification_type_id: a reference to a `Wupee::NotificationType` object\n* is_read: boolean\n\n\n## Install:\n\nTo use it, add it to your Gemfile:\n```ruby\ngem 'wupee'\n```\n\nand bundle:\n```bash\n$ bundle\n```\n\nRun the generator, install migrations and migrate:\n\n```bash\n$ rails g wupee:install\n$ rake wupee:install:migrations\n$ rake db:migrate\n```\n\nRunning the generator will do a few things:\n\n1. create \u003ca name=\"initializer\"\u003ewupee initializer\u003c/a\u003e:\n\n  ```ruby\n  # config/initializers/wupee.rb\n  Wupee.mailer = NotificationsMailer # the class of the mailer you will use to send the emails\n  Wupee.deliver_when = :now # use :later if you already configured a queuing system\n \n  # uncomment and implement your logic here to avoid/permit email sending to your users\n  # leave it commented if you always want your users received emails\n  # Wupee.email_sending_rule = Proc.new do |receiver, notification_type| \n  #   # logic goes here, returning a boolean\n  # end\n\n  # uncomment and implement your logic here to avoid/permit email sending to your users\n  # leave it commented if you always want your users received notifications\n  # Wupee.notification_sending_rule = Proc.new do |receiver, notification_type| \n  #   # logic goes here, returning a boolean\n  # end\n  ```\n2. create a mailer `NotificationsMailer` which inheritates from `Wupee::NotificationsMailer`\n\n  ```ruby\n  # app/mailers/notifications_mailer.rb\n  class NotificationsMailer \u003c Wupee::NotificationsMailer\n    default from: 'contact@sleede.com'\n    layout false\n end\n  ```\n\n3. adds wupee to your locale yml file (for email subjects)\n  ```yml\n  # config/locales/en.yml\n  en:\n    wupee:\n      email_subjects:\n  ```\n\n## Getting started:\n\n### Generate a new notification type\n\n```bash\nrails g wupee:notification_type user_has_been_created\n```\n\nWill execute a few things:\n\n1. add an entry to your locale yml file :\n\n ```yml\n en:\n   wupee:\n     email_subjects:\n       user_has_been_created: \"user_has_been_created\"\n ```\n Feel free to edit the subject, you can put variables, example\n ```yml\n  ...\n      user_has_been_created: \"New user created: %{user_full_name}\"\n ```\n\n2. create a json template for the notification:\n\n ```ruby\n json.subject \"\"\n json.body \"\"\n json.url \"\"\n # none of this json attribute are mandatory!\n ```\n In this template, you have access to the **notification** variable.\n You can customize it to fit your need, this is just an example.\n\n3. create an empty html template for the notification:\n ```html\n \u003c!-- app/views/wupee/notifications/_user_has_been_created.html.erb --\u003e\n ```\n\n4. You will have to create your email template as the generator doesn't create it.\n For example, if your mailer is named `NotificationsMailer`, your template will take place in\n `app/views/notifications_mailer/user_has_been_created.html.erb`\n\n\n### Use the concerns\n\n#### Wupee::Receiver\n\nIncluding the concern `Wupee::Receiver` in your receiver class (probably the `User` class) permits a few things:\n * get notifications of a user: `@user.notifications`\n * destroy `Wupee::Notification` associated to the receiver from db if it is destroyed\n\n#### Wupee::AttachedObject\n\nIncluding the concern `Wupee::AttachedObject` in your attached object classe(s) permits a few things:\n * get notifications associated to an attached object: `@attached_object.notifications_as_attached_object`\n * destroy `Wupee::Notification` associated to the attached object if it is destroyed\n\n### Use the DSL to send notifications\n\nImagine that you want to notify all admin that a new user signed up in your app and that you have a scope `admin` in your `User` class.\n\n```ruby\n Wupee.notify do |n|\n   n.attached_object @the_new_user\n   n.notif_type :user_has_been_created # you can also pass an instance of a Wupee::NotificationType class to this method\n   n.subject_vars user_full_name: Proc.new { |notification| notification.attached_object.full_name } # variables to be interpolated the fill in the subject of the email (obviously optional)\n   n.locals extra_data: \"something\" # extra_data will be accessible in template as @locals[:extra_data]\n   n.receivers User.admin # you can use the method receiver instead of receivers for clarity if you pass only one instance of a receiver\n   n.deliver :now # you can overwrite global configuration here, optional\n end\n```\n\nYou can also use the method `notify` this way:\n\n```ruby\n Wupee.notify attached_object: @the_new_user, notif_type: :user_has_been_created, subject_vars: { user_full_name: Proc.new { |notification| notification.attached_object.full_name } }, locals: { extra_data: \"Yeahhhhh\" }, receivers: User.admin\n```\n\n## Wupee::Api::NotificationsController\n\nThe controller have various actions all scoped for the current user:\n * `wupee/api/notifications#index` : fetch notifications, takes an optional get parameter `scopes` (example: scopes=read,ordered)\n * `wupee/api/notifications#show` : fetch a notification\n * `wupee/api/notifications#mark_as_read` : mark a notification as read \n * `wupee/api/notifications#mark_all_as_read` : mark all notifications as read\n\nTo use this controller, define a controller inheriting from `Wupee::Api::NotificationsController`, set the routes in your `config/routes.rb` \nand define a method `current_user`  which returns the user signed in.\n\nExample:\n```ruby\n  # config/routes.rb\n  namespace :api, defaults: { format: :json } do\n    resources :notifications, only: [:index, :show] do\n      patch :mark_as_read, on: :member\n      patch :mark_all_as_read, on: :collection\n    end\n  end\n\n  # app/controllers/api/notifications_controller.rb\n  class Api::NotificationsController \u003c Wupee::Api::NotificationsController \n    before_action :authenticate_user! # if you are using devise\n  end\n```\n\n## Why WUPEE ?\n\n**W**hat's **UP** Sl**EE**de\n\n## License\n\nThis project rocks and uses MIT-LICENSE.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleede%2Fwupee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsleede%2Fwupee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleede%2Fwupee/lists"}