cakemail-next-gen 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 95edcd5ef79bdd5c936ed0e1796dea3e69a2c0b9c91b7e8c22d4a96a35bdc022
+  data.tar.gz: 6c9771c0061bd3268833293db53f3b5caecadbf09389303333fa4056674cef11
+SHA512:
+  metadata.gz: b7cfcf78af7aed0e39e83d6a507035631046aeeb7eec499b4cf23bbcadcf336ad76083bb5d64c73f65c6a98208a8667c83c421685c6b7785cdb5950a6d3a85cd
+  data.tar.gz: 06db8e184b081f991a2f35bc0ed76affd657a03b91a1545080d627b4a9f576ed261bdf58e02e13c13129e23c9443cbe2667cb681cd91972ba278e18767d7fc6a

data/.env.dist

@@ -0,0 +1,3 @@
+CAKEMAIL_API_KEY="..."
+CAKEMAIL_USERNAME="..."
+CAKEMAIL_PASSWORD="..."

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,52 @@
+Layout/FirstHashElementIndentation:
+  Enabled: false
+Layout/ArgumentAlignment:
+  Enabled: false
+Layout/HashAlignment:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/FrozenStringLiteralComment:
+  Enabled: false
+Style/OptionalBooleanParameter:
+  Enabled: false
+Style/MethodDefParentheses:
+  Enabled: true
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+Style/RescueStandardError:
+  EnforcedStyle: implicit
+Naming/VariableNumber:
+  CheckSymbols: false
+Style/VariableNumber:
+  Enabled: false
+Style/HashSyntax:
+  EnforcedShorthandSyntax: never
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+Style/WordArray:
+  Enabled: false
+Style/SymbolArray:
+  Enabled: false
+Lint/Debugger:
+  Enabled: false
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+Layout/ArrayAlignment:
+  EnforcedStyle: with_fixed_indentation
+Style/ClassVars:
+  Enabled: false
+Metrics/BlockLength:
+  Max: 2000
+Metrics/MethodLength:
+  Max: 25
+Metrics/PerceivedComplexity:
+  Max: 15
+Metrics/AbcSize:
+  Max: 25
+Metrics/CyclomaticComplexity:
+  Max: 20
+Metrics/ClassLength:
+  Max: 250

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Nathan Lopez
+
+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,194 @@
+<p align="center">
+  <img src="images/logo.png" alt="Cakemail Next-gen" />
+</p>
+
+# Cakemail Next-gen Ruby wrapper
+
+<span>[![Gem Version](https://img.shields.io/gem/v/cakemail-next-gen.svg?label=cakemail-next-gen&colorA=D30001&colorB=DF3B3C)](https://rubygems.org/gems/cakemail-next-gen)</span> <span>
+[![ruby](https://img.shields.io/badge/ruby-2.6+-ruby.svg?colorA=D30001&colorB=DF3B3C)](https://github.com/andrewdsilva/cakemail-ruby)</span> <span>
+![Rubocop Status](https://img.shields.io/badge/rubocop-passing-rubocop.svg?colorA=1f7a1f&colorB=2aa22a)</span> <span>
+[![MIT license](https://img.shields.io/badge/license-MIT-mit.svg?colorA=1f7a1f&colorB=2aa22a)](http://opensource.org/licenses/MIT)</span> <span>
+![Downloads](https://img.shields.io/gem/dt/cakemail-next-gen.svg?colorA=004d99&colorB=0073e6)</span>
+
+This library allows you to quickly and easily use the Cakemail Next-gen API via Ruby.
+
+This gem is designed to be community-driven, with the aim of prioritizing the needs and preferences of its users. Your active involvement is crucial in shaping the future development of this project. You can contribute by creating issues and pull requests, as well as engaging with existing ones through upvoting or commenting.
+
+If you need help using Cakemail, please check the Cakemail Support Help Center at https://www.cakemail.com/contact-us.
+
+## Installation
+
+To install the gem add it into a Gemfile (Bundler):
+
+```ruby
+gem "cakemail-next-gen"
+```
+
+And then execute:
+
+```
+bundle install
+```
+
+## API key
+
+You need to set your Cakemail API credentials using environment variables.
+
+```ruby
+# .env
+CAKEMAIL_API_KEY="..."
+CAKEMAIL_USERNAME="..."
+CAKEMAIL_PASSWORD="..."
+```
+
+If you wish to generate a new token, you will need the environment variables `CAKEMAIL_USERNAME` and `CAKEMAIL_PASSWORD`.
+
+If you already have a token, you will only need: `CAKEMAIL_API_KEY`.
+
+### Generating a Token
+
+To generate a token, follow these steps:
+
+1. Set the `CAKEMAIL_USERNAME` and `CAKEMAIL_PASSWORD` environment variables using a `.env` file.
+2. Use the `Cakemail::Token.create` method provided by the gem to generate a token. Here's an example of how to use it :
+
+```ruby
+token = Cakemail::Token.create
+
+pp "Access token created is #{token.access_token}"
+```
+
+## Usage
+
+Cakemail-Ruby was designed with usability as its primary goal, so that you can forget the API and intuitively interact with your lists, contacts, campaigns and so on.
+
+## Lists
+
+Here are some basic usage examples for managing lists:
+
+1. Fetching all lists:
+```ruby
+lists = Cakemail::List.all
+lists.each do |list|
+  puts "List ID: #{list.id}"
+  puts "List Name: #{list.name}"
+  # Additional list attributes can be accessed here
+end
+```
+
+2. Creating a new list:
+```ruby
+new_list = Cakemail::List.create(name: "New List")
+puts "Created List ID: #{new_list.id}"
+puts "Created List Name: #{new_list.name}"
+```
+
+3. Updating an existing list:
+```ruby
+list = Cakemail::List.find(list_id)
+list.update(name: "New name")
+puts "Updated List Name: #{list.name}"
+```
+
+4. Deleting a list:
+```ruby
+list = Cakemail::List.find(list_id)
+list.delete
+puts "List deleted successfully."
+```
+
+5. Archiving or unarchiving a list:
+```ruby
+list = Cakemail::List.find(list_id)
+list.archive
+# List is archived
+list.unarchive
+# List is unarchived
+```
+
+## Handling large data sets
+
+The `find_in_batches` method, similar to its counterpart in ActiveRecord, allows you to retrieve records from a collection in batches. This is useful when dealing with large datasets, as it helps overcome API limitations by retrieving data in batches of 50, rather than loading the entire collection into memory at once.
+
+Here's an example of how to use `find_in_batches` in the Cakemail Ruby Gem:
+
+```ruby
+Cakemail::List.find_in_batches do |list|
+  puts list
+end
+```
+
+## Contacts
+
+Here are some common use cases for managing contacts:
+
+1. Retrieve all contacts in a list
+
+To retrieve all contacts in a given list, you can use the `list` method of the `Cakemail::Contact` class. Make sure to specify the parent list when calling the method:
+
+```ruby
+# Get lists
+lists = Cakemail::List.all
+
+# Retrieve all contacts in a list
+contacts = Cakemail::Contact.list(parent: lists.first)
+
+contacts.each do |contact|
+  puts "Email: #{contact.email}"
+  puts "Status: #{contact.status}"
+  puts "Subscription Date: #{Time.at(contact.subscribed_on)}"
+  puts "---"
+end
+
+# Or directly from a list object
+lists.first.contacts
+```
+
+2. Create a new contact
+
+To create a new contact in a specific list, use the `create` method of the `Cakemail::Contact` class. Provide the necessary information, such as the email address, as a parameter hash:
+
+```ruby
+# Create a new contact
+params = {
+  email: "nathan.lopez042@gmail.com"
+}
+
+new_contact = Cakemail::Contact.create(params, parent: list)
+
+puts "Contact created successfully."
+puts "Email: #{new_contact.email}"
+puts "Status: #{new_contact.status}"
+
+# Or create from list
+
+new_contact = list.create_contact(params)
+puts "Contact created successfully."
+```
+
+3. Updating an existing contact:
+```ruby
+list = Cakemail::List.find(list_id)
+contact = list.contacts.last
+
+contact.update(email: "new_mail@gmail.com")
+puts "Updated contact email: #{contact.email}"
+```
+
+4. Deleting a contact:
+```ruby
+list = Cakemail::List.find(list_id)
+contact = list.contacts.last
+
+contact.delete
+puts "Contact deleted successfully."
+```
+
+5. Unsubscribe a contact:
+```ruby
+list = Cakemail::List.find(list_id)
+contact = list.contacts.last
+
+contact.unsubscribe
+puts "Contact unsubscribed successfully."
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/cakemail.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/cakemail/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "cakemail-next-gen"
+  spec.version = Cakemail::VERSION
+  spec.authors = ["Nathan Lopez"]
+  spec.email = ["nathan.lopez042@gmail.com"]
+
+  spec.summary = "This library allows you to quickly and easily use the Cakemail Next-gen API via Ruby."
+  spec.description = "This library allows you to quickly and easily use the Cakemail Next-gen API via Ruby."
+  spec.homepage = "https://github.com/andrewdsilva/cakemail-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/andrewdsilva/cakemail-ruby"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/lib/cakemail/base.rb

@@ -0,0 +1,248 @@
+module Cakemail
+  # @attr [Integer]       id         Id of the list
+  class Base
+    class NoParentError < StandardError; end
+
+    attr_accessor :id, :parent
+
+    # Returns Cakemail object with id and type provided
+    #
+    # @param id [String]
+    # @return [List, Contact, Campaign, Tags]
+    #
+    # @example
+    #           list = Cakemail::List.find(1)
+    #           list.class #=> Cakemail::User
+    #           list.id    #=> 1
+    def self.find(id, options = {})
+      parent = get_parent(options)
+
+      path = "#{object_class.path}/#{id}"
+      path = path_with_parent(path, parent) if parent
+
+      response = Cakemail.get path
+
+      instantiate_object response["data"] unless response.nil?
+    end
+
+    # Returns Cakemail objects
+    #
+    # @param page [Integer]
+    # @param per_page [Integer]
+    # @return [Array<List>, Array<Contact>, Array<Campaign>, Array<Tags>]
+    #
+    # @example
+    #           contacts = Cakemail::Contact.list(1, 50)
+    def self.list(options = {})
+      page     = options[:page]     || 1
+      per_page = options[:per_page] || 50
+      filters  = options[:filters]  || {}
+      parent   = options[:parent]   || nil
+
+      no_parent_exception if parent_required && parent.nil?
+
+      path = "#{object_class.path}?page=#{page}&per_page=#{per_page}"
+      path = path_with_parent(path, parent) if parent
+
+      unless filters.keys.empty?
+        query = filters.map { |key, value| "filter=#{key}==#{value}" }.join("&")
+
+        path += "&#{query}"
+      end
+
+      response = Cakemail.get path
+
+      instantiate_object_list(response["data"], parent) unless response.nil?
+    end
+
+    # Returns total count
+    #
+    # @return Integer
+    #
+    # @example
+    #           total_contacts = Cakemail::Contact.count
+    def self.count(options = {})
+      parent = get_parent(options)
+
+      path = "#{object_class.path}?page=1&per_page=1&with_count=true"
+      path = path_with_parent(path, parent) if parent
+
+      response = Cakemail.get path
+
+      response["pagination"]["count"] unless response.nil?
+    end
+
+    # Yields each batch of records that was found
+    #
+    # @param block [Block]
+    #
+    # @example
+    #           total_contacts = Cakemail::Contact.count
+    def self.find_in_batches(options = {}, &block)
+      total = count(options)
+
+      per_page = options[:per_page] || 50
+      page = 1
+
+      loop do
+        list(options.merge(page: page, per_page: per_page)).each do |object|
+          block.call(object)
+        end
+
+        break if page * per_page > total
+
+        page += 1
+      end
+    end
+
+    # Create a new object and return it
+    #
+    # @param params [Hash]
+    # @return [List, Contact, Campaign, Tags]
+    #
+    # @example
+    #           my_list = Cakemail::List.create(name: "My list")
+    def self.create(params, options = {})
+      parent = get_parent(options)
+
+      no_parent_exception if parent_required && parent.nil?
+
+      path = object_class.path
+      path = path_with_parent(path, parent) if parent
+
+      response = Cakemail.post path, params.to_json
+
+      return response unless response_ok? response
+
+      instantiate_object(response["data"]) unless response.nil?
+    end
+
+    # Delete Cakemail object
+    #
+    # @return Boolean
+    #
+    # @example
+    #           list = Cakemail::List.find(1)
+    #           list.delete
+    def delete(options = {})
+      parent = get_parent(options)
+
+      path = "#{self.class.object_class.path}/#{id}"
+      path = self.class.path_with_parent(path, parent) if parent
+
+      response = Cakemail.delete path
+
+      self.class.response_ok?(response) && response["deleted"]
+    end
+
+    # Update Cakemail object and return it
+    #
+    # @return [List, Contact, Campaign, Tags]
+    #
+    # @example
+    #           list = Cakemail::List.find(1)
+    #           list.update(name: "My list 2")
+    def update(params, options = {})
+      parent = get_parent(options)
+
+      path = "#{self.class.object_class.path}/#{id}"
+      path = self.class.path_with_parent(path, parent) if parent
+
+      response = Cakemail.patch path, params.to_json
+
+      return response unless self.class.response_ok?(response) && response["updated"]
+
+      self.class.instantiate_object(response["data"]) unless response.nil?
+    end
+
+    # Archive Cakemail object and return it
+    #
+    # @return [List, Contact, Campaign, Tags]
+    #
+    # @example
+    #           list = Cakemail::List.find(1)
+    #           list.archive
+    def archive(options = {})
+      parent = get_parent(options)
+
+      path = "#{self.class.object_class.path}/#{id}/archive"
+      path = self.class.path_with_parent(path, parent) if parent
+
+      response = Cakemail.post path, {}.to_json
+
+      return response unless self.class.response_ok?(response) && response["archived"]
+
+      self.class.instantiate_object(response) unless response.nil?
+    end
+
+    # Unarchive Cakemail object and return it
+    #
+    # @return [List, Contact, Campaign, Tags]
+    #
+    # @example
+    #           list = Cakemail::List.find(1)
+    #           list.unarchive
+    def unarchive(options = {})
+      parent = get_parent(options)
+
+      path = "#{self.class.object_class.path}/#{id}/unarchive"
+      path = self.class.path_with_parent(path, parent) if parent
+
+      response = Cakemail.post path, {}.to_json
+
+      return response unless self.class.response_ok?(response) && !response["archive"]
+
+      self.class.instantiate_object(response) unless response.nil?
+    end
+
+    def self.get_parent(options = {})
+      options[:parent] || nil
+    end
+
+    def get_parent(options = {})
+      @parent || self.class.get_parent(options)
+    end
+
+    def self.no_parent_exception
+      raise NoParentError
+    end
+
+    def self.parent_required
+      false
+    end
+
+    def self.path_with_parent(path, parent)
+      "#{parent.class.path}/#{parent.id}/#{path}"
+    end
+
+    def self.response_ok?(response)
+      [200, 201].include?(response["status_code"])
+    end
+
+    def initialize(options = {})
+      @id = options["id"]
+    end
+
+    def self.object_class; end
+
+    def self.instantiate_object_list(json, parent = nil)
+      json.map { |json_object| instantiate_object(json_object, parent) }
+    end
+
+    def self.instantiate_object(json, parent = nil)
+      object = object_class.new json
+
+      object.parent = parent unless parent.nil?
+
+      object
+    end
+
+    def respond_to?(method_name)
+      attr = "@#{method_name}"
+
+      return super if method_name.match(/[?!]$/) || !instance_variable_defined?(attr)
+
+      true
+    end
+  end
+end

data/lib/cakemail/configuration.rb

@@ -0,0 +1,21 @@
+require "dotenv/load"
+
+module Cakemail
+  module Configuration
+    def self.api_key
+      @api_key
+    end
+
+    def self.api_key=(api_key)
+      @api_key = api_key
+    end
+
+    DEFAULT = {
+      api_key: ENV["CAKEMAIL_API_KEY"]
+    }.freeze
+
+    DEFAULT.each do |param, default_value|
+      send("#{param}=", default_value)
+    end
+  end
+end

data/lib/cakemail/connection.rb

@@ -0,0 +1,52 @@
+require "dotenv/load"
+require "faraday"
+
+module Cakemail
+  class MissingAuthentication < StandardError; end
+  class JsonResponseError < StandardError; end
+
+  API_URI = "https://api.cakemail.dev".freeze
+  VERBS   = %w[get post patch delete].freeze
+
+  class << self
+    attr_accessor :raw_response
+
+    VERBS.each do |verb|
+      define_method verb do |path, params = {}, headers = {}|
+        send_request(verb, path, params, headers)
+      end
+    end
+
+    def api_key
+      Cakemail.config.api_key
+    end
+
+    private
+
+    def parse_json(json)
+      JSON.parse(json)
+    rescue
+      raise JsonResponseError
+    end
+
+    def missing_authentication?(response)
+      parse_json(response.body)&.dig("detail") == "Not authenticated"
+    end
+
+    def auth_header
+      headers = { "accept" => "application/json", "Content-Type" => "application/json" }
+      headers = headers.merge("authorization" => "Bearer #{api_key}") if api_key
+
+      headers
+    end
+
+    def send_request(http_verb, path, params, headers)
+      connection = Faraday.new(url: API_URI)
+      response = connection.send(http_verb.downcase.to_sym, path, params, auth_header.merge(headers))
+
+      raise MissingAuthentication if missing_authentication? response
+
+      parse_json(response.body).merge("status_code" => response.status)
+    end
+  end
+end