surenotify_rails 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2ff790368b45481416ff8b497480f097a3698ccc3c04272c2e70eaf2599a043
-  data.tar.gz: d286745c8c606c2ba902584663586b3b8e40b17b7ee5145d36b46f5657f38c03
+  metadata.gz: 9dad2191d0d3d3b681ff8b9bff90a6bceda7beeb403178a97660ab08f88288f2
+  data.tar.gz: 01ec276d067483b5076f2acc95d9447a02f17c2f125d78987cddab30cc71e608
 SHA512:
-  metadata.gz: b11f4579e8c6235c0084cc4739fd406b95f07129c67c246764d8e65b079c1d1b487d59c1da2e100abf734762de67d0e33ab96117c03324ad051e5fbf585f678e
-  data.tar.gz: a5c327ba693a6a5e6cb36f388939f38cea51ce58be9b5499833f19b54200296d38106f1c56022f222241e1f8d270cc41281f1b7f7dba52d4ac06a3c05924f7ce
+  metadata.gz: 6f858a3f49158c9b398fa7782f35d51d858b2826a3b907812c97ea4dfbfaec306ac4d1b9c2792a98f579e2b8ff21118a52bfa63db82dc640f6e78d19a71763b7
+  data.tar.gz: 2773f90590e251631519e0dfd6d8bf69689911ed957c88d98afd8e1b73652f313eb4b1352a218b2cafa767ec30a5be99916fe3bb0dc685cade52e6004725b427

data/README.md

@@ -0,0 +1,76 @@
+# surenotify_rails (電子豹非官方 Rails 套件)
+
+*surenotify_rails* is an Action Mailer adapter for using 電子豹 [Surenotify](https://newsleopard.com/surenotify) in Rails apps. It uses the [Surenotify API v1](https://newsleopard.com/surenotify/api/v1/) internally.
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails (Action Mailer) >= 6.0 — tested against Rails 6.1, 7.1, 7.2 and 8.0
+
+## Installing
+
+In your `Gemfile`
+
+```ruby
+gem 'surenotify_rails'
+```
+
+## Usage
+
+To configure your Surenotify credentials place the following code in the corresponding environment file (`development.rb`, `production.rb`...)
+
+```ruby
+config.action_mailer.delivery_method = :surenotify
+config.action_mailer.surenotify_settings = {
+  api_key: '<surenotify api key>',
+  unsubscribed_link: 'https://example.com/unsubscribe' # optional default
+}
+```
+
+Now you can send emails using plain Action Mailer:
+
+```ruby
+email = mail from: 'Your Name <sender@email.com>', to: 'receiver@email.com', subject: 'this is an email'
+```
+
+### Per-recipient merge variables
+
+Set variables per recipient address (rendered by Surenotify templates, max 100 characters per value):
+
+```ruby
+def welcome_email
+  message = mail from: 'sender@email.com', to: 'receiver@email.com', subject: 'welcome'
+  message.surenotify_recipient_variables = {
+    'receiver@email.com' => { 'name' => '小明', 'coupon' => 'ABC123' }
+  }
+  message
+end
+```
+
+### Unsubscribe link
+
+Override the default unsubscribe link per message:
+
+```ruby
+message.surenotify_unsubscribed_link = 'https://example.com/custom-unsubscribe'
+```
+
+### Querying message events
+
+```ruby
+client = SurenotifyRails::Client.new('<surenotify api key>')
+client.events(status: 'open', recipient: 'receiver@email.com')
+# => { "items" => [...] }
+```
+
+Raises `SurenotifyRails::APIError` on API errors. Events are limited to the past 30 days (max 50 results) by the API.
+
+## Notes and limitations
+
+- The Surenotify API allows at most **100 recipients per request**; `SurenotifyRails::TooManyRecipientsError` is raised beyond that (split batches yourself).
+- The API has no cc/bcc concept: cc/bcc addresses are merged into `recipients` (deduplicated), so everyone receives an individual copy.
+- Attachments are not supported by the Surenotify API.
+- `deliver!` raises `SurenotifyRails::APIError` (with `code` and `body`) when the API rejects the request; it no longer silently returns the failed response.
+
+Pull requests are welcomed
+

data/lib/surenotify_rails/client.rb

@@ -1,8 +1,10 @@
-require 'rest_client'
-
+require "net/http"
+require "json"
 
 module SurenotifyRails
   class Client
+    API_URL = "https://mail.surenotifyapi.com/v1".freeze
+
     attr_reader :api_key, :verify_ssl
 
     def initialize(api_key, verify_ssl = true)
@@ -11,25 +13,41 @@ module SurenotifyRails
     end
 
     def send_message(options)
-      RestClient::Request.execute(
-        method: :post,
-        url: surenotify_url,
-        payload: JSON::dump(options),
-        verify_ssl: verify_ssl,
-        headers: {
-          content_type: 'application/json',
-                accept: 'application/json',
-             x_api_key: @api_key
-        }
-      )
+      uri = URI("#{API_URL}/messages")
+      request = Net::HTTP::Post.new(uri)
+      apply_headers(request)
+      request.body = JSON.dump(options)
+      perform(uri, request)
     end
 
-    def surenotify_url
-      api_url + "/messages"
+    def events(filters = {})
+      uri = URI("#{API_URL}/events")
+      uri.query = URI.encode_www_form(filters) unless filters.empty?
+      request = Net::HTTP::Get.new(uri)
+      apply_headers(request)
+      response = perform(uri, request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise APIError.new("Surenotify API error: #{response.code}",
+                           code: response.code, body: response.body)
+      end
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def apply_headers(request)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["x-api-key"] = api_key
     end
 
-    def api_url
-      'https://mail.surenotifyapi.com/v1'
+    def perform(uri, request)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.verify_mode = verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      http.request(request)
     end
   end
 end

data/lib/surenotify_rails/deliverer.rb

@@ -1,5 +1,6 @@
 module SurenotifyRails
   class Deliverer
+    MAX_RECIPIENTS = 100
 
     attr_accessor :settings
 
@@ -8,73 +9,70 @@ module SurenotifyRails
     end
 
     def api_key
-      self.settings[:api_key]
+      settings[:api_key]
     end
 
     def verify_ssl
-      #default value = true
-      self.settings[:verify_ssl] != false
+      # default value = true
+      settings[:verify_ssl] != false
     end
 
     def deliver!(rails_message)
       response = surenotify_client.send_message build_surenotify_message_for(rails_message)
-      if response.code == 200
-        surenotify_message_id = JSON.parse(response.to_str)["id"]
-        rails_message.message_id = surenotify_message_id
+      unless response.is_a?(Net::HTTPSuccess)
+        raise APIError.new("Surenotify API error: #{response.code}",
+                            code: response.code, body: response.body)
       end
+      rails_message.message_id = JSON.parse(response.body)["id"]
       response
     end
 
     private
 
     def build_surenotify_message_for(rails_message)
-      surenotify_message = build_basic_surenotify_message_for rails_message
-      # transform_surenotify_attributes_from_rails rails_message, surenotify_message
-      remove_empty_values surenotify_message
-
-      surenotify_message
-    end
-
-    def transform_surenotify_attributes_from_rails(rails_message, surenotify_message)
-      transform_reply_to rails_message, surenotify_message if rails_message.reply_to
-      transform_surenotify_variables rails_message, surenotify_message
-      transform_surenotify_options rails_message, surenotify_message
-      transform_surenotify_recipient_variables rails_message, surenotify_message
-      transform_custom_headers rails_message, surenotify_message
+      from = rails_message[:from].addrs.first
+      message = {
+        fromName: from.display_name,
+        fromAddress: from.address,
+        recipients: recipients_for(rails_message),
+        subject: rails_message.subject,
+        content: extract_html(rails_message),
+        unsubscribedLink: unsubscribed_link_for(rails_message)
+      }
+      remove_empty_values(message)
     end
 
-    def build_basic_surenotify_message_for(rails_message)
-      surenotify_message = {
-       fromName: rails_message[:from].addrs.first.name,
-       fromAddress: rails_message[:from].addrs.first.address,
-       recipients: formatted_receivers(rails_message[:to]),
-       subject: rails_message.subject,
-       content: extract_html(rails_message)
-      }
+    def recipients_for(rails_message)
+      addrs = [:to, :cc, :bcc].flat_map do |field|
+        rails_message[field] ? rails_message[field].addrs : []
+      end
+      recipients = addrs.uniq(&:address).map { |addr| recipient_for(addr, rails_message) }
 
-      [:cc, :bcc].each do |key|
-        surenotify_message[key] = rails_message[key].formatted if rails_message[key]
+      if recipients.empty?
+        raise NoRecipientsError, "the message has no recipients (to/cc/bcc are all empty)"
       end
 
-      return surenotify_message if rails_message.attachments.empty?
-
-      # RestClient requires attachments to be in file format, use a temp directory and the decoded attachment
-      surenotify_message[:attachment] = []
-      surenotify_message[:inline] = []
-      rails_message.attachments.each do |attachment|
-        # then add as a file object
-        if attachment.inline?
-          surenotify_message[:inline] << surenotifyRails::Attachment.new(attachment, encoding: 'ascii-8bit', inline: true)
-        else
-          surenotify_message[:attachment] << surenotifyRails::Attachment.new(attachment, encoding: 'ascii-8bit')
-        end
+      if recipients.size > MAX_RECIPIENTS
+        raise TooManyRecipientsError,
+              "Surenotify API allows at most #{MAX_RECIPIENTS} recipients per request " \
+              "(got #{recipients.size})"
       end
 
-      return surenotify_message
+      recipients
     end
 
-    def transform_reply_to(rails_message, surenotify_message)
-      surenotify_message['h:Reply-To'] = rails_message[:reply_to].formatted.first
+    def recipient_for(addr, rails_message)
+      recipient = {
+        name: addr.display_name || addr.address.split("@").first,
+        address: addr.address
+      }
+      variables = (rails_message.surenotify_recipient_variables || {})[addr.address]
+      recipient[:variables] = variables if variables
+      recipient
+    end
+
+    def unsubscribed_link_for(rails_message)
+      rails_message.surenotify_unsubscribed_link || settings[:unsubscribed_link]
     end
 
     # @see http://stackoverflow.com/questions/4868205/rails-mail-getting-the-body-as-plain-text
@@ -86,48 +84,15 @@ module SurenotifyRails
       end
     end
 
-    def extract_text(rails_message)
-      if rails_message.multipart?
-        rails_message.text_part ? rails_message.text_part.body.decoded : nil
-      else
-        rails_message.content_type =~ /text\/plain/ ? rails_message.body.decoded : nil
-      end
-    end
-
-    def transform_surenotify_variables(rails_message, surenotify_message)
-      rails_message.surenotify_variables.try(:each) do |name, value|
-        surenotify_message["v:#{name}"] = value
+    def remove_empty_values(message)
+      message.delete_if do |_key, value|
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
       end
     end
 
-    def transform_surenotify_options(rails_message, surenotify_message)
-      rails_message.surenotify_options.try(:each) do |name, value|
-        surenotify_message["o:#{name}"] = value
-      end
-    end
-
-    def transform_custom_headers(rails_message, surenotify_message)
-      rails_message.surenotify_headers.try(:each) do |name, value|
-        surenotify_message["h:#{name}"] = value
-      end
-    end
-
-    def transform_surenotify_recipient_variables(rails_message, surenotify_message)
-      surenotify_message['recipient-variables'] = rails_message.surenotify_recipient_variables.to_json if rails_message.surenotify_recipient_variables
-    end
-
-    def remove_empty_values(surenotify_message)
-      surenotify_message.delete_if { |key, value| value.nil? or
-                                               value.respond_to?(:empty?) && value.empty? }
-    end
-
     def surenotify_client
       @surenotify_client ||= Client.new(api_key, verify_ssl)
     end
-
-    def formatted_receivers(receivers)
-      receivers.addrs.map { |r| { address: r.address } }
-    end
   end
 end
 

data/lib/surenotify_rails/errors.rb

@@ -0,0 +1,17 @@
+module SurenotifyRails
+  class Error < StandardError; end
+
+  class TooManyRecipientsError < Error; end
+
+  class NoRecipientsError < Error; end
+
+  class APIError < Error
+    attr_reader :code, :body
+
+    def initialize(message, code: nil, body: nil)
+      super(message)
+      @code = code
+      @body = body
+    end
+  end
+end

data/lib/surenotify_rails/mail_ext.rb

@@ -4,5 +4,6 @@ module Mail
     attr_accessor :surenotify_options
     attr_accessor :surenotify_recipient_variables
     attr_accessor :surenotify_headers
+    attr_accessor :surenotify_unsubscribed_link
   end
 end

data/lib/surenotify_rails/version.rb

@@ -1,3 +1,3 @@
 module SurenotifyRails
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

data/lib/surenotify_rails.rb

@@ -1,8 +1,11 @@
-require 'action_mailer'
-require 'json'
+require "action_mailer"
+require "json"
 
-
-Dir[File.dirname(__FILE__) + '/surenotify_rails/*.rb'].each {|file| require file }
+require "surenotify_rails/version"
+require "surenotify_rails/errors"
+require "surenotify_rails/mail_ext"
+require "surenotify_rails/client"
+require "surenotify_rails/deliverer"
 
 module SurenotifyRails
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: surenotify_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Leo Chen
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-01-25 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionmailer
@@ -16,70 +15,56 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.2.11
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.2.11
+        version: '6.0'
 - !ruby/object:Gem::Dependency
-  name: json
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.1.0
-- !ruby/object:Gem::Dependency
-  name: rest-client
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.0.2
-  type: :runtime
+        version: '0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.2
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.14.1
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.14.1
+        version: '3.13'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.2.11
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.2.11
+        version: '3.0'
 description: An adapter for using Surenotify with Rails and Action Mailer
 email:
 - pominx@gmail.com
@@ -88,19 +73,20 @@ extensions: []
 extra_rdoc_files: []
 files:
 - MIT-LICENSE
-- README.rdoc
-- Rakefile
+- README.md
 - lib/surenotify_rails.rb
-- lib/surenotify_rails/attachment.rb
 - lib/surenotify_rails/client.rb
 - lib/surenotify_rails/deliverer.rb
+- lib/surenotify_rails/errors.rb
 - lib/surenotify_rails/mail_ext.rb
 - lib/surenotify_rails/version.rb
 homepage: https://github.com/pominx/surenotify_rails
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/pominx/surenotify_rails
+  source_code_uri: https://github.com/pominx/surenotify_rails
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -108,15 +94,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
-signing_key: 
+rubygems_version: 3.7.1
 specification_version: 4
 summary: Rails Action Mailer adapter for Surenotify (NewsLeopard)
 test_files: []

data/README.rdoc

@@ -1,3 +0,0 @@
-= SurenotifyRails
-
-This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -1,23 +0,0 @@
-begin
-  require 'bundler/setup'
-rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-end
-
-require 'rdoc/task'
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'SurenotifyRails'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-Bundler::GemHelper.install_tasks
-
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec

data/lib/surenotify_rails/attachment.rb

@@ -1,16 +0,0 @@
-module SurenotifyRails
-  class Attachment < StringIO
-    attr_reader :original_filename, :content_type, :path
-
-    def initialize (attachment, *rest)
-      @path = ''
-      if rest.detect {|opt| opt[:inline] }
-        basename = @original_filename = attachment.cid
-      else
-        basename = @original_filename = attachment.filename
-      end
-      @content_type = attachment.content_type.split(';')[0]
-      super attachment.body.decoded
-    end
-  end
-end