magicbell 1.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ccd683f0bcd9d88443ef5d1ff1ccf869df5c2fe0f5ea1ab79f9338bc09a6d81
-  data.tar.gz: '0056372079d706665429081e7f9df9d6570d1f8b72a6e2287c88d839960e9be0'
+  metadata.gz: 8a2806ab42cdd91d4eaada59a02ef686432dec09656fd369d244e9a9111a5f0f
+  data.tar.gz: ad0d1da2faf2bbdc2c51da677bf4c91c90a4fbb759a70e74da19d525e47de7a2
 SHA512:
-  metadata.gz: 6204b83549f58e878e8f93af5d5aeb77606f70e1f62bbf9be31c07d6b54728fa3af4b096615990ce62b09307cc292b42e612f5dc57a5f1989160cbe9ad3abf2e
-  data.tar.gz: e2799647fc11454b05e2f6c463b08a24fab00838ccebcf3850b6c872b90fc5bf63f9d050fd68809c617bf07858ff1099ba36725086802caec8c7e609f331686e
+  metadata.gz: 6849a6a65cb71d23f3f96b7cfccf47bdc2d808c76004bbfafb4321f9b670b852cb7b2770f0fa3fc0a553ca3c6e5d2ba85a52820c63e00350c61f1a69cffee730
+  data.tar.gz: e0a8e457403e9b67210d0ada15d8aa3adbbbfea7a7c50810e40ad04dcf0b6d3ca74c193f191a34e127a9b5080aab834e9fa6ed66cca7c2ab95e71484c007d4ee

data/README.md

@@ -1,243 +1,250 @@
-# magicbell-ruby
+# MagicBell Ruby Library
 
-[MagicBell](https://magicbell.io) is an embeddable Notification Inbox for web 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.
 
-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).
 
-1. Makes it easy to interact with [MagicBell's REST API](https://developer.magicbell.io/reference) from Ruby.
+<img width="415" alt="MagicBell Notification Inbox" src="https://files.readme.io/c09b21a-image1.png">
 
-   You can use it to create a notification in your MagicBell project etc.
-3. Can BCC your ActionMailer email notifications to MagicBell if you rather not use MagicBell's API in your Rails application.
-  
-    MagicBell will create an in-app notification from any email notification that's blind copied to it.
-3.  Helps you calculate the HMAC for a user's email when you turn on HMAC Authentication for your MagicBell project
+## Installation
 
-<img width="415" alt="MagicBell Notification Inbox" src="https://user-images.githubusercontent.com/1789832/28327736-f3503f44-6c01-11e7-9a72-c15023db18c6.png">
+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.
 
-## Installation
+If you just want to use the package, run:
+
+```
+gem install magicbell
+```
 
-Sign up at magicbell.io and obtain your MagicBell project's API Key and API Secret from the "Settings" section in your MagicBell dashboard.
+### Bundler
 
-Add the gem to your app's Gemfile
+If you are installing via bundler, add the gem to your app's Gemfile:
 
 ```ruby
-gem "magicbell"
+# Gemfile
+source 'https://rubygems.org'
+
+gem 'magicbell'
 ```
 
-and install the gem
+and run `bundle install` a usual.
 
-```
-bundle install
-```
+## 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
+The library needs to be configured with your MagicBell project's API key and secret.
 
-```
-vim config/initializers/magicbell.rb
-```
+### Global configuration
+
+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.
+
+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
+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 even provide content for the notification and a URL to redirect the user to when they click on the notification the MagicBell Notification Inbox
+Or you can identify users by an `external_id` (their ID in your database, for example):
 
 ```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 a task to you',
+  recipients: [{
+    external_id: 'DATABASE_ID'
+  }]
+)
+```
+
+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',
+  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
+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
-
-  def new_comment(comment)
-    # ...
-    magicbell_notification_title("Richard posted a new comment")
-    # ...
-  end
-end
-```
-
-## HMAC Authentication
+require 'magicbell'
 
-### Calculate HMAC
+magicbell = MagicBell::Client.new(
+  api_key: 'MAGICBELL_API_KEY',
+  api_secret: 'MAGICBELL_API_SECRET'
+)
 
+hmac = magicbell.hmac('joe@example.com')
 ```
-user_email = "joe@example.com"
-hmac = MagicBell.hmac(user_email)
-```
-
-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.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

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

@@ -1,44 +1,56 @@
+require 'json'
+require 'colorize'
 module MagicBell
   module ApiOperations
     def get(url, options = {})
-      response = HTTParty.get(
-        url,
-        options.merge(headers: authentication_headers)
-      )
+      defaults = { headers: default_headers }
+      response = HTTParty.get(url, options.merge(defaults))
       raise_http_error_unless_2xx_response(response)
 
       response
     end
 
     def post(url, options = {})
-      response = HTTParty.post(
-        url,
-        options.merge(headers: authentication_headers)
-      )
+      defaults = { headers: default_headers }
+      response = HTTParty.post(url, options.merge(defaults))
       raise_http_error_unless_2xx_response(response)
 
       response
     end
 
     def put(url, options = {})
-      response = HTTParty.put(
-        url,
-        options.merge(headers: authentication_headers)
-      )
+      defaults = { headers: default_headers }
+      response = HTTParty.put(url, options.merge(defaults))
       raise_http_error_unless_2xx_response(response)
 
       response
     end
 
+    protected
+
+    def default_headers
+      authentication_headers.merge({ "Content-Type" => "application/json", "Accept"=> "application/json" })
+    end
+
     private
 
     def raise_http_error_unless_2xx_response(response)
       return if response.success?
+      
       e = MagicBell::Client::HTTPError.new
       e.response_status = response.code
       e.response_headers = response.headers.to_h
       e.response_body = response.body
+      e.errors = []
+      unless e.response_body.nil? || e.response_body.empty?
+        body = JSON.parse(response.body)
+        e.errors = body["errors"]
+        e.errors.each do |error, index|
+          puts "#{error["suggestion"].red}"
+          puts "#{error["help_link"].blue.on_white}"
+        end
+      end
       raise e
     end
   end
-end
+end

data/lib/magicbell/api_resource.rb

@@ -79,7 +79,7 @@ module MagicBell
       response = @client.post(
         create_url,
         body: { name => attributes }.to_json,
-        headers: authentication_headers
+        headers: extra_headers
       )
       parse_response(response)
 
@@ -90,7 +90,7 @@ module MagicBell
       response = @client.put(
         url,
         body: new_attributes.to_json,
-        headers: authentication_headers
+        headers: extra_headers
       )
       parse_response(response)
 
@@ -99,8 +99,8 @@ module MagicBell
 
     protected
 
-    def authentication_headers
-      MagicBell.authentication_headers
+    def extra_headers
+      {}
     end
 
     private

data/lib/magicbell/client.rb

@@ -3,11 +3,17 @@ module MagicBell
     class HTTPError < StandardError
       attr_accessor :response_status,
                     :response_headers,
-                    :response_body
+                    :response_body,
+                    :errors
     end
 
     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
@@ -22,7 +28,19 @@ module MagicBell
     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 = '1.0.1'
+  VERSION = '2.1.0'
 end

metadata

@@ -1,15 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: magicbell
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Hana Mohan
 - Nisanth Chunduru
+- Rahmane Ousmane
+- Josue Montano
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-12-03 00:00:00.000000000 Z
+date: 2021-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -39,6 +41,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: actionmailer
   requirement: !ruby/object:Gem::Requirement
@@ -109,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: []
@@ -139,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
@@ -158,8 +178,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
-summary: Ruby wrapper for MagicBell.io
+summary: Ruby Library for MagicBell
 test_files: []