magicbell 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76d91ee7dd27c175853dff9ff3dcf5a296dbf58c5151f1a228841a23beb57cc3
-  data.tar.gz: dd40c6308d20d6219ef0d5a7962d4a70f5e0f381bf8911c76eec1d9d3dbcd439
+  metadata.gz: 205676a39e21a70f18682b926501b0d8c67ea674df273cbda92fe838f21b0750
+  data.tar.gz: 9d0e2fbf7661d9cd6f4f910fa2d0dd89e2ee6d230798015cabe606202627ca53
 SHA512:
-  metadata.gz: 2eb10d824cc3228716ef4e1f0c4f392d44528e6b961352e382bb8dc8790ec12cafccdb9a9210a4211dc459a436930a5ec1901bdf8fa58ee17bc63cc041c779ab
-  data.tar.gz: 1895cbe977bcd395598963545f057fb2e5bb614faa5b6d57eed185d1892dbef0a90e9aa736a59ac601c6b26478718f1b52a289bb23c3566bd0f0e2126c77652b
+  metadata.gz: 524d8ed46c49c90e295974547b72b05db01a80ce3215070f48348a846ddcada01f07368846f4bbd5baca680a3ff8127e43abe5915bf1c85dfcb423270e72a8b9
+  data.tar.gz: 0d3d21452e55687032910556225db73a2f95d933d6a6f54edc9897c3499326ce8d9b527fa1226f9853352157cfb3c1cdbe1634dbbb58910078dd822c264e3512

data/README.md

@@ -1,261 +1,278 @@
-# magicbell-ruby
+# MagicBell Ruby Library
 
-[MagicBell](https://magicbell.io) is an embeddable Notification Inbox for web & mobile applications.
+This library provides convenient access to the [MagicBell REST API](https://magicbell.com/docs/rest-api/overview)
+from applications written in Ruby. It includes helpers for creating
+notifications, fetching them, and calculating the HMAC for a user.
 
-Please familiarlize yourself with the [core concepts of MagicBell](https://developer.magicbell.io/docs/core-concepts) before using this gem.
+[MagicBell](https://magicbell.com) is the notification inbox for your web and
+mobile applications. You may find it helpful to familiarize yourself with the
+[core concepts of MagicBell](https://magicbell.com/docs/core-concepts).
 
-This gem
+<img width="415" alt="MagicBell Notification Inbox" src="https://files.readme.io/c09b21a-image1.png">
 
-1. Makes it easy to interact with [MagicBell's REST API](https://developer.magicbell.io/reference) from Ruby.
+## Installation
 
-   You can use it to create a notification in your MagicBell project etc.
+First, [sign up for a MagicBell account](https://magicbell.com) and grab your
+MagicBell project's API key and secret from the "Settings" section of your
+MagicBell dashboard.
 
-2. Can BCC your ActionMailer email notifications to MagicBell if you rather not use MagicBell's API in your Rails application.
+If you just want to use the package, run:
 
-   MagicBell will create an in-app notification from any email notification that's blind copied to it.
+```
+gem install magicbell
+```
 
-3. Helps you calculate the HMAC for a user's email or external_id when you turn on [HMAC Authentication](https://developer.magicbell.io/docs/turn-on-hmac-authentication) for your MagicBell project
+### Bundler
 
-<img width="415" alt="MagicBell Notification Inbox" src="https://files.readme.io/c09b21a-image1.png">
+If you are installing via bundler, add the gem to your app's Gemfile:
 
-## Installation
+```ruby
+# Gemfile
+source 'https://rubygems.org'
 
-Sign up at magicbell.io and obtain your MagicBell project's API Key and API Secret from the "Settings" section in your MagicBell dashboard.
+gem 'magicbell'
+```
 
-Add the gem to your app's Gemfile
+and run `bundle install` a usual.
 
-```ruby
-gem "magicbell"
-```
+## Configuration
 
-and install the gem
+The library needs to be configured with your MagicBell project's API key and
+secret.
 
-```
-bundle install
-```
+### Global configuration
 
-The gem will automatically pick your MagicBell project's API Key and API Secret from the `MAGICBELL_API_KEY` and `MAGICBELL_API_SECRET` environment variables. Alternatively, provide the API Key and API Secret in an initializer
+By default, this library will automatically pick your MagicBell project's API
+key and secret from the `MAGICBELL_API_KEY` and `MAGICBELL_API_SECRET`
+environment variables, respectively.
 
-```
-vim config/initializers/magicbell.rb
-```
+Alternatively, you can configure your MagicBell manually. For example, for a
+rails project, create an initializer file for MagicBell and set your project's
+keys:
 
 ```ruby
 # config/initializers/magicbell.rb
 
 MagicBell.configure do |config|
-  config.api_key = "your_magicbell_api_key"
-  config.api_secret = "your_magicbell_api_secret"
+  config.api_key = 'MAGICBELL_API_KEY'
+  config.api_secret = 'MAGICBELL_API_SECRET'
 end
 ```
 
-## API Wrapper
+### Per-request configuration
+
+For apps that need to use multiple keys during the lifetime of a process,
+provide the specific keys when you create instances of `MagicBell::Client`:
+
+```ruby
+require 'magicbell'
+
+magicbell = MagicBell::Client.new(
+  api_key: 'MAGICBELL_PROJECT_API_KEY',
+  api_secret: 'MAGICBELL_PROJECT_API_SECRET'
+)
+```
+
+Please keep in mind that any instance of `MagicBell::Client` will default to the
+global configuration unless an API key and secret are provided.
 
-This gem makes it easy to interact with MagicBell's REST API https://developer.magicbell.io/reference from Ruby
+## Usage
 
 ### Create a notification
 
-Send a notification to one or many users by identifying them with their email address
+You can send a notification to one or many users by identifying them by their
+email address:
 
 ```ruby
+require 'magicbell'
+
 magicbell = MagicBell::Client.new
 magicbell.create_notification(
-  "title" => "Rob assigned a task to you",
-  "recipients" => [
-    {
-      email: "joe@example.com"
-    },
-  ]
+  title: 'Rob assigned a task to you',
+  recipients: [{
+    email: 'joe@example.com'
+  }, {
+    email: 'mary@example.com'
+  }]
 )
 ```
 
-You can also identify users with their `external_id`, which is their ID in your database. That way, if their email address changes, they'd still have access to their notifications. You'll need to make sure you identify them with their `externalID` [in your frontend](https://developer.magicbell.io/docs/browser-js#identifying-users).
+Or you can identify users by an `external_id` (their ID in your database, for example):
 
 ```ruby
-     magicbell.create_notification(
-          title: "Welcome to Muziboo",
-          recipients: [{
-            external_id: "id_in_your_database"
-          }]
-        )
+require 'magicbell'
+
+magicbell = MagicBell::Client.new
+magicbell.create_notification(
+  title: 'Rob assigned a task to you',
+  recipients: [{
+    external_id: 'DATABASE_ID'
+  }]
+)
 ```
 
-You can even provide content for the notification and a URL to redirect the user to when they click on the notification the MagicBell Notification Inbox
+This method has the benefit of allowing users to access their notifications when
+their email address changes. Make sure you identify users by their `externalID`
+when you [initialize the notification inbox](https://magicbell.com/docs/react/identifying-users), too.
+
+You can also provide other data accepted by [our API](https://magicbell.com/docs/rest-api/reference):
 
 ```ruby
+require 'magicbell'
+
 magicbell = MagicBell::Client.new
 magicbell.create_notification(
-  "title" => "Rob assigned to a task to you",
-  "recipients" => [
-    {
-      email: "joe@example.com"
-    },
-  ],
-  "content": "Hey Joe, can give this customer a demo of our app?",
-  "action_url" => "https://yourwebsite.com/task_path"
+  title: 'Rob assigned to a task to you',
+  content: 'Hey Joe, can give this customer a demo of our app?',
+  action_url: 'https://example.com/task_path',
+  custom_attributes: {
+    recipient: {
+      first_name: 'Joe',
+      last_name: 'Smith'
+    }
+  },
+  overrides: {
+    channels: {
+      web_push: {
+        title: 'New task assigned'
+      }
+    }
+  },
+  recipients: [{
+    email: 'joe@example.com'
+  }],
 )
 ```
 
 ### Fetch a user's notifications
 
-Fetch a user's notifications
+To fetch a user's notifications you can do this:
 
 ```ruby
+require 'magicbell'
+
 magicbell = MagicBell::Client.new
-user = magicbell.user_with_email("joe@example.com")
-user_notifications = user.notifications
-user_notifications.each { |user_notification| puts user_notification.attribute("title") }
+
+user = magicbell.user_with_email('joe@example.com')
+user.notifications.each { |notification| puts notification.attribute('title') }
 ```
 
-Please note that the example above fetches the user's 15 most recent notification (the default number of notifications per page) If you'd like to fetch subsequent pages, use
+If you identify a user by an ID, you can use the
+`magicbell.user_with_external_id` method instead.
+
+Please note that the example above fetches the user's 15 most recent
+notifications (the default number per page). If you'd like to fetch subsequent
+pages, use the `each_page` method instead:
 
 ```ruby
+require 'magicbell'
+
 magicbell = MagicBell::Client.new
-user = magicbell.user_with_email("joe@example.com")
-user_notifications = user.notifications
-user_notifications.each_page do |page|
-  page.each do |user_notification|
-    puts user_notification.attribute("title")
+
+user = magicbell.user_with_email('joe@example.com')
+user.notifications.each_page do |page|
+  page.each do |notification|
+    puts notification.attribute('title')
   end
 end
 ```
 
-### Mark a user notification as read/unread
+### Mark a user's notification as read/unread
 
 ```ruby
+require 'magicbell'
+
 magicbell = MagicBell::Client.new
-user = magicbell.user_with_email("joe@example.com")
-user_notification = user.notifications.first
-user_notification.mark_as_read
-user_notification.mark_as_unread
+
+user = magicbell.user_with_email('joe@example.com')
+
+notification = user.notifications.first
+notification.mark_as_read
+notification.mark_as_unread
 ```
 
-### Mark all notifications of a user as read/seen
+### Mark all notifications of a user as read
 
 ```ruby
+require 'magicbell'
+
 magicbell = MagicBell::Client.new
-user = magicbell.user_with_email("joe@example.com")
+
+user = magicbell.user_with_email('joe@example.com')
 user.mark_all_notifications_as_read
+```
+
+### Mark all notifications of a user as seen
+
+```ruby
+require 'magicbell'
+
+magicbell = MagicBell::Client.new
+
+user = magicbell.user_with_email('joe@example.com')
 user.mark_all_notifications_as_seen
 ```
 
 ### Error handling
 
-Please note that the gem raises a `MagicBell::Client::HTTPError` if an API returns a non 2xx response
+This gem raises a `MagicBell::Client::HTTPError` if the MagicBell API returns a
+non-2xx response.
 
 ```ruby
+require 'magicbell'
+
 begin
   magicbell = MagicBell::Client.new
   magicbell.create_notification(
-    "title" => "Rob assigned to a task to you"
+    title: 'Rob assigned to a task to you'
   )
 rescue MagicBell::Client::HTTPError => e
-  # Report the error to your error tracker
+  # Report the error to your error tracker, for example
   error_context = {
     response_status: e.response_status,
     response_headers: e.response_headers,
     response_body: e.response_body
   }
-  ErrorReporter.report(e, context: error_context)
-end
-```
-
-## Rails integration
-
-If you've existing ActionMailer email notifications in your Rails app and prefer to not spend time migrating to MagicBell's API, you can blind copy your ActionMailer email notifications to MagicBell. MagicBell will create in-app notifications from email notifications blind copied to it.
-
-Call the `ring_the_magicbell` method in your action mailers like in the example below
-
-```ruby
-class NotificationMailer < ActionMailer::Base
-  # The ring_the_magicbell method will bcc your email notifications to your MagicBell project's BCC email address
-  #
-  # Upon receiving a blind copied email notification, magicbell.io will automatically create an in-app notification for the user
-  ring_the_magicbell
-
-  # This is an email notification in your app
-  def new_comment
-    # ...
-  end
-
-  # This is another email notification in your app
-  def mentioned
-    # ...
-  end
-end
-```
-
-The gem will automatically pick your MagicBell project's BCC email from the `MAGICBELL_BCC_EMAIL` environment variable. Alternatively, provide your MagicBell project's BCC email address in an initializer
-
-```
-vim config/initializers/magicbell.rb
-```
 
-```ruby
-# config/initializers/magicbell.rb
-
-MagicBell.configure do |config|
-  config.api_key = "your_magicbell_api_key"
-  config.api_secret = "your_magicbell_api_secret"
-  config.bcc_email = "your_magicbell_bcc_email@ring.magicbell.io"
+  ErrorReporter.report(e, context: error_context)
 end
 ```
 
-The BCC email address is available in the "Settings" section in your MagicBell dashboard.
-
-### Customize Action URL
+### Calculate the HMAC secret for a user
 
-When a user clicks on a notification in MagicBell's Notification Inbox, the Notification Inbox redirects the user to the first URL the body of the email notification. This URL is called the `action_url`.
-
-If you wish to redirect users to a different URL instead, provide an `action_url` in your mailers
+You can use the `MagicBell.hmac` method. Note that in this case, the API secret,
+which is used to generate the HMAC, will be fetched from the global
+configuration.
 
 ```ruby
-class NotificationMailer < ActionMailer::Base
-  ring_the_magicbell
+require 'magicbell'
 
-  def new_comment(comment)
-    # ...
-    magicbell_notification_action_url("https://myapp.com/comments/#{comment.id}")
-    # ...
-  end
-end
+hmac = MagicBell.hmac('joe@example.com')
 ```
 
-### Customize Notification Title
-
-The Notification inbox will use the subject of the email notification as a notification's title. If this behaviour isn't sutiable for your app, provide a title in your mailers
+You can also use the API secret of a specific client instance to calculate the
+HMAC:
 
 ```ruby
-class NotificationMailer < ActionMailer::Base
-  ring_the_magicbell
+require 'magicbell'
 
-  def new_comment(comment)
-    # ...
-    magicbell_notification_title("Richard posted a new comment")
-    # ...
-  end
-end
-```
-
-## HMAC Authentication
-
-### Calculate HMAC
+magicbell = MagicBell::Client.new(
+  api_key: 'MAGICBELL_API_KEY',
+  api_secret: 'MAGICBELL_API_SECRET'
+)
 
-```
-user_email = "joe@example.com"
-hmac = MagicBell.hmac(user_email)
+hmac = magicbell.hmac('joe@example.com')
 ```
 
-See https://developer.magicbell.io/docs/turn-on-hmac-authentication for more information on turning on HMAC Authentication for your MagicBell Project
+Please refer to our docs to know [how to turn on HMAC authentication](https://magicbell.com/docs/turn-on-hmac-authentication)
+for your MagicBell project.
 
 ## API docs
 
-Please visit our website https://magicbell.io and our API docs https://developer.magicbell.io for more information MagicBell's embeddable notification inbox and MagicBell's REST API
+Please visit [our website](https://magicbell.com) and
+[our docs](https://magicbell.com/docs) for more information.
 
 ## Contact Us
 
-Have a query or hit upon a problem? Create a post in our Developer Community https://community.magicbell.io or contact us at hello@magicbell.io
-
-```
-
-```
+Have a query or hit upon a problem? Feel free to contact us at
+[hello@magicbell.io](mailto:hello@magicbell.io).

data/lib/magicbell/action_mailer_extension.rb

@@ -2,16 +2,6 @@ require "json"
 
 module MagicBell
   module ActionMailerExtension
-    def self.included(mailer_class)
-      mailer_class.send :extend, ClassMethods
-    end
-
-    module ClassMethods
-      def ring_the_magicbell
-        default bcc: MagicBell.bcc_email
-      end
-    end
-
     def magicbell_notification_action_url(action_url)
       headers["X-MagicBell-Notification-ActionUrl"] = action_url
     end

data/lib/magicbell/api_operations.rb

@@ -44,12 +44,16 @@ module MagicBell
       e.errors = []
       unless e.response_body.nil? || e.response_body.empty?
         body = JSON.parse(response.body)
-        e.errors = body["errors"]
+        e.errors = body["errors"].is_a?(Array) ? body["errors"] : []
         e.errors.each do |error, index|
-          puts "#{error["suggestion"].red}"
-          puts "#{error["help_link"].blue.on_white}"
+          suggestion = error["suggestion"]
+          help_link = error["help_link"]
+
+          puts "#{suggestion.red}" if suggestion
+          puts "#{help_link.blue.on_white}" if help_link
         end
       end
+
       raise e
     end
   end

data/lib/magicbell/api_resources/user.rb

@@ -2,11 +2,13 @@ module MagicBell
   class User < ApiResource
     include ApiOperations
 
-    attr_reader :email
+    attr_reader :email, :external_id
 
     def initialize(client, attributes)
       @client = client
       @email = attributes["email"]
+      @external_id = attributes["external_id"]
+
       super(client, attributes)
     end
 
@@ -38,13 +40,19 @@ module MagicBell
     def path
       if id
         self.class.path + "/#{id}"
+      elsif external_id
+        self.class.path + "/external_id:#{external_id}"
       elsif email
         self.class.path + "/email:#{email}"
       end
     end
 
     def authentication_headers
-      MagicBell.authentication_headers.merge("X-MAGICBELL-USER-EMAIL" => email)
+      if external_id
+        MagicBell.authentication_headers.merge("X-MAGICBELL-USER-EXTERNAL-ID" => external_id)
+      elsif email
+        MagicBell.authentication_headers.merge("X-MAGICBELL-USER-EMAIL" => email)
+      end
     end
   end
 end

data/lib/magicbell/client.rb

@@ -9,21 +9,39 @@ module MagicBell
 
     include ApiOperations
 
+    def initialize(api_key: nil, api_secret: nil)
+      @api_key = api_key
+      @api_secret = api_secret
+    end
+
     def create_notification(notification_attributes)
       MagicBell::Notification.create(self, notification_attributes)
     end
 
-    # def user(user_id)
-    #   MagicBell::User.find(user_id)
-    # end
-
     def user_with_email(email)
       client = self
       MagicBell::User.new(client, "email" => email)
     end
 
+    def user_with_external_id(external_id)
+      client = self
+      MagicBell::User.new(client, "external_id" => external_id)
+    end
+
     def authentication_headers
-      MagicBell.authentication_headers
+      MagicBell.authentication_headers(client_api_key: @api_key, client_api_secret: @api_secret)
+    end
+
+    def hmac(message)
+      secret = @api_secret || MagicBell.api_secret
+
+      Base64.encode64(OpenSSL::HMAC::digest(sha256_digest, secret, message)).strip
+    end
+
+    private
+
+    def sha256_digest
+      OpenSSL::Digest::Digest.new('sha256')
     end
   end
 end

data/lib/magicbell/config.rb

@@ -2,7 +2,6 @@ module MagicBell
   class Config
     attr_writer :api_key
     attr_writer :api_secret
-    attr_writer :bcc_email
     attr_writer :api_host
 
     def initialize
@@ -17,10 +16,6 @@ module MagicBell
       @api_secret || ENV["MAGICBELL_API_SECRET"]
     end
 
-    def bcc_email
-      @bcc_email || ENV["MAGICBELL_BCC_EMAIL"]
-    end
-
     def api_host
       @api_host || ENV["MAGICBELL_API_HOST"] || "https://api.magicbell.io"
     end

data/lib/magicbell/version.rb

@@ -1,3 +1,3 @@
 module MagicBell
-  VERSION = '2.0.0'
+  VERSION = '2.2.0'
 end

data/lib/magicbell.rb

@@ -32,7 +32,6 @@ module MagicBell
 
     def_delegators :config, :api_key,
                             :api_secret,
-                            :bcc_email,
                             :api_host
 
     def configure
@@ -47,25 +46,16 @@ module MagicBell
       @config = Config.new
     end
 
-    def authentication_headers
+    def authentication_headers(client_api_key: nil, client_api_secret: nil)
       {
-        "X-MAGICBELL-API-KEY" => api_key,
-        "X-MAGICBELL-API-SECRET" => api_secret
+        "X-MAGICBELL-API-KEY" => client_api_key || api_key,
+        "X-MAGICBELL-API-SECRET" => client_api_secret || api_secret
       }
     end
 
     # Calculate HMAC for user's email
     def hmac(message)
-      digest = sha256_digest
-      secret = api_secret
-
-      Base64.encode64(OpenSSL::HMAC.digest(digest, secret, message)).strip
-    end
-
-    private
-
-    def sha256_digest
-      OpenSSL::Digest::Digest.new('sha256')
+      MagicBell::Client.new(api_key: api_key, api_secret: api_secret).hmac(message)
     end
   end
 end

metadata

@@ -1,15 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: magicbell
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Hana Mohan
 - Nisanth Chunduru
-autorequire:
+- Rahmane Ousmane
+- Josue Montano
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-23 00:00:00.000000000 Z
+date: 2021-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -123,10 +125,12 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Notifications like never before!
+description: The notification inbox for your product
 email:
 - hana@magicbell.io
 - nisanth@supportbee.com
+- rahmane@magicbell.io
+- josue@magicbell.io
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -153,11 +157,13 @@ files:
 - lib/magicbell/railtie.rb
 - lib/magicbell/singleton_api_resource.rb
 - lib/magicbell/version.rb
-homepage: https://magicbell.io
+homepage: https://magicbell.com
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: "\n    *** Breaking Change:: The 2.0.0 release removes the BCC
+  functionality. ***\n    Please update your MagicBell integration to use the API
+  for creating notifications or downgrade to 1.0.4\n  "
 rdoc_options: []
 require_paths:
 - lib
@@ -172,8 +178,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
-signing_key:
+rubygems_version: 3.1.6
+signing_key: 
 specification_version: 4
-summary: Ruby wrapper for MagicBell.io
+summary: Ruby Library for MagicBell
 test_files: []