mailbluster 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89c061011879b9528428b63e1e63487718ee20f457c5f9ae5445785455009830
+  data.tar.gz: 34be79b1a3b0f6227a0acfdf00683b83962198e2897a148852dd7806f9cfd703
+SHA512:
+  metadata.gz: aecf52c361f5576b1d13723972bbd9053dd09ae82f1352c51315fda9a2c75a7247bc9151ca4a2306ee1fee7f704974197fc96f04907057a70b46646517bb9ca2
+  data.tar.gz: 61c30ab79c442ef4df52d64b345a6bf51beec468ace1753b5c6a900d77c5cad64cc2b8ffe49f9040dd3ac3d5ed10658028585230d00aef51f556c28a43a88344

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Tanay Lakhani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# mailbluster
+
+[![Gem Version](https://badge.fury.io/rb/mailbluster.svg)](https://rubygems.org/gems/mailbluster)
+[![CI](https://github.com/tanaylakhani/mailbluster-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/tanaylakhani/mailbluster-ruby/actions/workflows/ci.yml)
+
+Ruby client for the [Mailbluster API](https://app.mailbluster.com/api-doc).
+
+---
+
+- [Quick start](#quick-start)
+- [Usage](#usage)
+- [Demo script](#demo-script)
+- [API Documentation](#api-documentation)
+- [Detailed mailbluster-ruby documentation](#detailed-mailbluster-ruby-documentation)
+- [Support](#support)
+- [License](#license)
+- [Code of conduct](#code-of-conduct)
+- [Contribution guide](#contribution-guide)
+
+## Quick start
+
+```bash
+gem install mailbluster
+```
+
+or with bundler:
+
+```bash
+bundler add mailbluster
+```
+
+then configure the gem:
+
+```ruby
+Mailbluster.configure do |config|
+  config.api_key = 'your-api-key'
+end
+```
+
+or with environment variables:
+
+```bash
+env MAILBLUSTER_API_KEY=your-api-key ruby app.rb
+```
+
+or directly on the Client instance:
+
+```ruby
+mailbluster_client = Mailbluster::Client.new('your-api-key')
+```
+
+## Usage
+
+```ruby
+mailbluster_client = Mailbluster::Client.new
+lead = mailbluster_client.leads.create(email: 'lead@example.org')
+puts lead.inspect # => #<Mailbluster::Resource @resource_type=#<Mailbluster::ResourceType::Lead>, @raw_attributes={"id"=>262093545 ...}>
+
+mailbluster_client.leads.read(lead.email) # => #<Mailbluster::Resource @resource_type=#<Mailbluster::ResourceType::Lead>, @raw_attributes={"id"=>262093545 ...}>
+```
+
+## Sample Attributes to create Lead
+```ruby
+create_lead_attributes = {
+  "firstName" => "Richard",
+  "lastName" => "Hendricks",
+  "fields" => {
+    "gender" => "Male",
+    "address" => "Silicon Valley"
+  },
+  "email" => "richard@example.com",
+  "ipAddress" => "162.213.1.246",
+  "subscribed" => false,
+  "doubleOptIn" => true,
+  "meta" => {
+    "company" => "Pied Piper",
+    "role" => "CEO"
+  },
+  "tags" => [
+    "iPhone User",
+    "Startup"
+  ],
+  "overrideExisting" => true
+}
+
+```
+
+### Demo script
+In the `bin` directory, there is a `demo` script that you can run to see how to use the gem and to create example leads in Mailbluster. You can run it like this:
+
+```bash
+env MAILBLUSTER_API_KEY=your-api-key ruby bin/demo
+```
+
+## Mailbluster API Documentation
+Official documentation for the Mailbluster API can be found at <https://app.mailbluster.com/api-doc>.
+
+## Detailed mailbluster-ruby documentation
+
+- [Detailed: API Documentation](docs/api_documentation.md)
+- [Detailed: Client](docs/client.md)
+- [Detailed: Configuration](docs/configuration.md)
+- [Detailed: Resources](docs/resources.md)
+
+
+## Support
+
+If you want to report a bug, or have ideas, feedback or questions about the gem, [let me know via GitHub issues](https://github.com/tanaylakhani/mailbluster-ruby/issues/new) and I will do my best to provide a helpful answer. Happy hacking!
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Code of conduct
+
+Everyone interacting in this project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Contribution guide
+
+Pull requests are welcome!

data/lib/mailbluster/client.rb

@@ -0,0 +1,106 @@
+require "json"
+require "rest-client"
+
+module Mailbluster
+  class Client
+    Error = Class.new(StandardError)
+    Forbidden = Class.new(Error)
+    NotFound = Class.new(Error)
+    UnprocessableEntity = Class.new(Error)
+
+    RESOURCES = ["leads", "fields", "products", "orders"].freeze
+
+    def initialize(api_key = nil, logger = nil)
+      @api_key = api_key ||
+                 Mailbluster.configuration.api_key ||
+                 ENV["MAILBLUSTER_API_KEY"]
+      @api_url = Mailbluster.configuration.api_url ||
+                 ENV["MAILBLUSTER_API_URL"]
+
+      @logger = logger || Mailbluster.configuration.logger
+    end
+
+    def resource(resource_type)
+      raise ArgumentError, "Invalid resource type" unless RESOURCES.include?(resource_type)
+
+      ResourceType.new(self, resource_type)
+    end
+
+    RESOURCES.each do |resource_type|
+      define_method(resource_type) do
+        resource(resource_type)
+      end
+    end
+
+    def get(subpath, query_params: nil)
+      request(:get, subpath, query_params)
+    end
+
+    def post(subpath, payload)
+      request(:post, subpath, payload)
+    end
+
+    def put(subpath, payload = {})
+      request(:put, subpath, payload)
+    end
+
+    def delete(subpath)
+      request(:delete, subpath)
+    end
+
+    private
+
+    attr_reader :api_key, :api_url, :logger
+
+    def request(method, subpath, payload = {})
+      url = URI.parse(api_url + subpath)
+      if method == :get && payload != {}
+        url = "#{url}?#{URI.encode_www_form(payload.to_a)}"
+        payload = {}
+      end
+
+      log("Request: #{method} #{url} #{payload}")
+      response = ::RestClient::Request.execute(
+        prepare_request_options(method, payload, url)
+      )
+
+      log("Response: #{response.code} #{response.body}")
+
+      JSON.parse(response.body)
+    rescue RestClient::Forbidden => e
+      raise Forbidden, "#{e.message}\nMake sure that you set correct Mailbluster API KEY"
+    rescue RestClient::UnprocessableEntity => e
+      raise UnprocessableEntity, e.response.body || [
+        e.message, "Make sure that you set correct resource attributes"
+      ].join("\n")
+    rescue RestClient::NotFound => e
+      raise NotFound, e.message
+    end
+
+    def prepare_request_options(method, payload, url)
+      {
+        method: method,
+        url: url.to_s,
+        payload: payload&.to_json,
+        headers: {
+          content_type: :json,
+          accept: :json,
+          user_agent: mailbluster_user_agent,
+          authorization: api_key
+        }
+      }
+    end
+
+    def mailbluster_user_agent
+      [
+        "mailbluster-ruby",
+        Mailbluster::VERSION,
+        RestClient::Platform.default_user_agent
+      ].join("/")
+    end
+
+    def log(message, level = :info)
+      logger&.send(level, "[Mailbluster::Client] #{message}")
+    end
+  end
+end

data/lib/mailbluster/configuration.rb

@@ -0,0 +1,9 @@
+module Mailbluster
+  class Configuration
+    attr_accessor :api_key, :api_url, :logger
+
+    def initialize
+      @api_url = "https://api.mailbluster.com/api/"
+    end
+  end
+end

data/lib/mailbluster/resource.rb

@@ -0,0 +1,24 @@
+module Mailbluster
+  class Resource
+    attr_reader :raw_attributes
+
+    def initialize(resource_type, attributes)
+      @resource_type = resource_type
+      @raw_attributes = attributes
+      map_attributes_to_methods
+    end
+
+    private
+
+    attr_reader :resource_type
+
+    def map_attributes_to_methods
+      raw_attributes.each_key do |key|
+        method_name = Utils.underscore(key.to_s)
+        define_singleton_method(method_name) do
+          raw_attributes[key]
+        end
+      end
+    end
+  end
+end

data/lib/mailbluster/resource_type.rb

@@ -0,0 +1,68 @@
+module Mailbluster
+  class ResourceType
+    attr_reader :resource_type
+
+    def initialize(client, resource_type)
+      @client = client
+      @resource_type = resource_type
+    end
+
+    def inspect
+      "#<Mailbluster::ResourceType::#{singular_resource_type.capitalize}>"
+    end
+
+    def create(new_attributes)
+      raw_resource_attributes = @client.post(resource_type, new_attributes)
+      Resource.new(self, raw_resource_attributes[singular_resource_type] || raw_resource_attributes)
+    end
+
+    def read(id_or_email_md5 = "")
+      id_or_email_md5 = Utils.md5(id_or_email_md5) if lead? && id_or_email_md5.include?("@")
+      if id_or_email_md5.is_a?(Hash)
+        query_params = query_parameterize(id_or_email_md5)
+        id_or_email_md5 = ""
+      end
+      raw_resource_attributes = @client.get("#{resource_type}/#{id_or_email_md5}",
+                                            query_params: query_params)
+      map_to_resource(id_or_email_md5, raw_resource_attributes)
+    end
+
+    def update(id_or_email_md5, new_attributes)
+      id_or_email_md5 = Utils.md5(id_or_email_md5) if lead? && id_or_email_md5.include?("@")
+      raw_resource_attributes = @client.put("#{resource_type}/#{id_or_email_md5}", new_attributes)
+      Resource.new(self, raw_resource_attributes[singular_resource_type] || raw_resource_attributes)
+    end
+
+    def delete(id_or_email_md5)
+      id_or_email_md5 = Utils.md5(id_or_email_md5) if lead? && id_or_email_md5.include?("@")
+      @client.delete("#{resource_type}/#{id_or_email_md5}")
+      id_or_email_md5
+    end
+
+    def lead?
+      resource_type == "leads"
+    end
+
+    private
+
+    def query_parameterize(id_or_email_md5)
+      id_or_email_md5.map do |k, v|
+        [Utils.camelize(k.to_s), v]
+      end.to_h
+    end
+
+    def map_to_resource(id_or_email_md5, raw_resource_attributes)
+      if id_or_email_md5 == "" && raw_resource_attributes[resource_type].is_a?(Array)
+        raw_resource_attributes[resource_type].map do |rra|
+          Resource.new(self, rra)
+        end
+      else
+        Resource.new(self, raw_resource_attributes)
+      end
+    end
+
+    def singular_resource_type
+      resource_type[0..-2]
+    end
+  end
+end

data/lib/mailbluster/utils.rb

@@ -0,0 +1,20 @@
+require "digest/md5"
+
+module Mailbluster
+  module Utils
+    def self.md5(string)
+      Digest::MD5.hexdigest(string)
+    end
+
+    def self.underscore(string)
+      string.gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2'.freeze).
+        gsub(/([a-z\d])([A-Z])/, '\1_\2'.freeze).
+        tr("-".freeze, "_".freeze).downcase
+    end
+
+    def self.camelize(string)
+      # camelize string but don't capitalize the first letter
+      string.split("_").map(&:capitalize).join.sub(/^./, &:downcase)
+    end
+  end
+end

data/lib/mailbluster/version.rb

@@ -0,0 +1,3 @@
+module Mailbluster
+  VERSION = "1.0.0".freeze
+end

data/lib/mailbluster.rb

@@ -0,0 +1,16 @@
+module Mailbluster
+  autoload :VERSION, "mailbluster/version"
+  autoload :Utils, "mailbluster/utils"
+  autoload :Client, "mailbluster/client"
+  autoload :Configuration, "mailbluster/configuration"
+  autoload :ResourceType, "mailbluster/resource_type"
+  autoload :Resource, "mailbluster/resource"
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: mailbluster
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tanay Lakhani
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+description:
+email:
+- tpl253@nyu.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/mailbluster.rb
+- lib/mailbluster/client.rb
+- lib/mailbluster/configuration.rb
+- lib/mailbluster/resource.rb
+- lib/mailbluster/resource_type.rb
+- lib/mailbluster/utils.rb
+- lib/mailbluster/version.rb
+homepage: https://github.com/tanaylakhani/mailbluster-ruby
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/tanaylakhani/mailbluster-ruby/issues
+  changelog_uri: https://github.com/tanaylakhani/mailbluster-ruby/releases
+  source_code_uri: https://github.com/tanaylakhani/mailbluster-ruby
+  homepage_uri: https://github.com/tanaylakhani/mailbluster-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: A Ruby wrapper for Mailbluster API
+test_files: []