mailchimp_api_v3 0.0.0 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cea605da8196d54280fa8b3b52f804643720a4cc
-  data.tar.gz: 9adf62426b975cf8f73e98a52f571a04fe335b57
+  metadata.gz: 84ec2a80c75ddcdd36c7096af5a44bced1e7104f
+  data.tar.gz: bac88f5b0e1e56d5a68f8e8efc35c08e43799198
 SHA512:
-  metadata.gz: 5aa0078062716c9af0a986c84669a29eebc2cf982f5de986016b23a70a19e3aa6e19bcb3b8608fd254109f48614b736f86602183c8f24eab4086d77db5e9440b
-  data.tar.gz: 5fc82ff959426f5d6ad832747301c6bdf536feeaf95d080645f2ef0b5c6c565a71268e7b5c3bed8f2764f2448f2e7bcc030954b3d7f88677380dc18b16811632
+  metadata.gz: f3154cb67c37dfe49e1b967174b159d6c5984737ef609a87876e4d070267d917b713b4622457f7808b7f9b7367d8cd1da3b1cc741317078731b89c6404ecbed9
+  data.tar.gz: f8bb921863f744878b8b875f8e046beae6a9d9e2e51055b1ac54e8293440497544cb470c9747a1e3c6edfd299253deee726ff696c7282bbfbcdd9f3fc505fb53

data/README.md

@@ -1,13 +1,19 @@
 ## Mailchimp API v3
 
-![Gem Version(https://rubygems.org/gems/mailchimp_api_v3)](http://img.shields.io/gem/v/mailchimp_api_v3.svg?style=flat)
-![build status(https://circleci.com/gh/Xenapto/mailchimp_api_v3)](https://img.shields.io/circleci/project/Xenapto/mailchimp_api_v3/develop.svg)
-[![Code Climate](http://img.shields.io/codeclimate/github/Xenapto/mailchimp_api_v3.svg?style=flat)](https://codeclimate.com/github/Xenapto/mailchimp_api_v3)
-[![Coverage Status](https://img.shields.io/coveralls/Xenapto/mailchimp_api_v3/develop.svg?style=flat)](https://coveralls.io/r/Xenapto/mailchimp_api_v3?branch=develop)
-[![Developer status](http://img.shields.io/badge/developer-awesome-brightgreen.svg?style=flat)](http://xenapto.com)
+[![](http://img.shields.io/gem/v/mailchimp_api_v3.svg?style=flat)](https://rubygems.org/gems/mailchimp_api_v3)
+[![](https://img.shields.io/circleci/project/Xenapto/mailchimp_api_v3/develop.svg)](https://circleci.com/gh/Xenapto/mailchimp_api_v3)
+[![](http://img.shields.io/codeclimate/github/Xenapto/mailchimp_api_v3.svg?style=flat)](https://codeclimate.com/github/Xenapto/mailchimp_api_v3)
+[![](https://img.shields.io/coveralls/Xenapto/mailchimp_api_v3/develop.svg?style=flat)](https://coveralls.io/r/Xenapto/mailchimp_api_v3?branch=develop)
+[![](http://img.shields.io/badge/developer-awesome-brightgreen.svg?style=flat)](http://xenapto.com)
 
 A simple gem to interact with Mailchimp through their API v3
 
+### Project status
+
+This gem currently does everything I need for my project but it is far from complete. I will willingly accept good quality pull requests to complete the feature set.
+
+My own requirements are for subscription management for my mailing list, so the gem can add and remove members from a list and manage their interests.
+
 ### Installation
 
 Add this line to your application's Gemfile:
@@ -24,10 +30,30 @@ Or install it yourself as:
 
 ### Usage
 
+The Mailchimp API documentation is here: http://kb.mailchimp.com/api. Their suggstions for subscriber management are here: http://kb.mailchimp.com/api/article/how-to-manage-subscribers.
+
+To connect to the Mailchimp API you need to supply an API key. You can do this explicitly when you connect, or you can set an environment variable `MAILCHIMP_API_KEY`.
+
 Examples:
 
 ```ruby
-Mailchimp.connect(mc_key).lists
+MailchimpAPIV3.connect(my_api_key) # Uses the API key in my_api_key
+MailchimpAPIV3.connect # Uses ENV['MAILCHIMP_API_KEY']
+```
+
+```ruby
+MailchimpAPIV3.connect.lists
+```
+
+```ruby
+mailchimp = MailchimpAPIV3.connect
+list = mailchimp.lists.find_by name: 'My first list'
+```
+
+```ruby
+mailchimp = MailchimpAPIV3.connect
+member = mailchimp.lists('e73f5910ca').members('ann@example.com')
+member.name # => "Ann Example"
 ```
 
 ### Contributing
@@ -38,6 +64,12 @@ Mailchimp.connect(mc_key).lists
 1.  Push to the branch (`git push origin my-new-feature`)
 1.  Create new Pull Request
 
+### Testing
+
+The tests use Rspec and VCR. To avoid including my test API key in the VCR cassettes the tests use Erb to insert an api key at runtime. Whatever API key is available will allow the tests to pass.
+
+If you need to add more cassettes you can use your own test API key then edit the VCR cassette in the same way before you issue the pull request.
+
 ### Acknowledgements
 
 I used the sample code in https://github.com/mailchimp/APIv3-examples as my starting point for this gem. Thanks to

data/circle.yml

@@ -0,0 +1,5 @@
+---
+notify:
+  webhooks:
+    # A list of hook hashes, containing the url field
+    - url: https://coveralls.io/webhook?repo_token=SFdYC8cgEnwclAC8K7dzccQ5e16ZBDlPj

data/lib/{mailchimp → mailchimp_api_v3}/account.rb

@@ -1,7 +1,6 @@
-module Mailchimp
+module MailchimpAPIV3
   class Account
-    PATH_KEY = DATA_KEY = ''
-    include Instance
+    include Instance::InstanceMethods
 
     def id
       account_id

data/lib/{mailchimp → mailchimp_api_v3}/client/remote.rb

@@ -1,7 +1,7 @@
 require 'yaml'
 require 'restclient'
 
-module Mailchimp
+module MailchimpAPIV3
   class Client
     module Remote
       def get(path = '', options = {})
@@ -22,9 +22,7 @@ module Mailchimp
 
       def managed_remote(path = '', options = {}, method = :get, payload = nil)
         headers_and_params = headers.merge params_from(options)
-        url = "#{url_stub}#{path}"
-        # puts url # debug
-        YAML.load naked_remote(url, method, headers_and_params, payload)
+        YAML.load naked_remote("#{url_stub}#{path}", method, headers_and_params, payload)
       rescue *RETRY_EXCEPTIONS => e
         @retries ||= 0
         raise e if (@retries += 1) > 3
@@ -36,15 +34,16 @@ module Mailchimp
       def managed_remote_exception(e)
         case e.class.to_s # TODO: Find out why this won't match the class except by name string
         when 'RestClient::Unauthorized'
-          fail Mailchimp::Exception::APIKeyError, YAML.load(e.http_body)
+          fail MailchimpAPIV3::Exception::APIKeyError, YAML.load(e.http_body)
         when 'RestClient::BadRequest'
-          Mailchimp::Exception.parse_invalid_resource_exception YAML.load(e.http_body)
+          MailchimpAPIV3::Exception.parse_invalid_resource_exception YAML.load(e.http_body)
         else
           fail e
         end
       end
 
       def naked_remote(url, method, headers_and_params, payload = nil)
+        # puts url # debug
         if [:get, :delete, :head, :options].include? method
           remote_no_payload(url, method, headers_and_params)
         else

data/lib/{mailchimp → mailchimp_api_v3}/client.rb

@@ -1,11 +1,11 @@
-require 'mailchimp/exception'
-require 'mailchimp/collection'
-require 'mailchimp/instance'
-require 'mailchimp/account'
-require 'mailchimp/lists'
-require 'mailchimp/client/remote'
-
-module Mailchimp
+require 'mailchimp_api_v3/exception'
+require 'mailchimp_api_v3/collection'
+require 'mailchimp_api_v3/instance'
+require 'mailchimp_api_v3/account'
+require 'mailchimp_api_v3/lists'
+require 'mailchimp_api_v3/client/remote'
+
+module MailchimpAPIV3
   class Client
     include Remote
 
@@ -19,7 +19,7 @@ module Mailchimp
 
     def connected?
       account
-    rescue Mailchimp::Exception::APIKeyError
+    rescue MailchimpAPIV3::Exception::APIKeyError
       false
     else
       true
@@ -29,7 +29,12 @@ module Mailchimp
 
     def initialize(api_key = nil, extra_headers = {})
       @api_key = api_key || ENV['MAILCHIMP_API_KEY']
-      fail Mailchimp::Exception::APIKeyError, 'title' => 'Invalid API key format' unless api_key_valid?
+
+      fail(
+        MailchimpAPIV3::Exception::APIKeyError,
+        'title' => "Invalid API key format: #{@api_key}"
+      ) unless api_key_valid?
+
       @extra_headers = extra_headers
     end
 

data/lib/{mailchimp → mailchimp_api_v3}/collection/paging.rb

@@ -1,4 +1,4 @@
-module Mailchimp
+module MailchimpAPIV3
   module Collection
     module Paging
       DEFAULT_PAGE_SIZE = 500

data/lib/{mailchimp → mailchimp_api_v3}/collection.rb

@@ -1,6 +1,6 @@
-require 'mailchimp/collection/paging'
+require 'mailchimp_api_v3/collection/paging'
 
-module Mailchimp
+module MailchimpAPIV3
   module Collection
     include Paging
 
@@ -20,15 +20,22 @@ module Mailchimp
       @path ||= "#{@parent_path}/#{self.class.path_key}"
     end
 
-    def find(data)
+    def where(data, limit = nil)
+      instances = []
+
       find_each do |instance|
-        matches = data.each do |k, v|
-          break false unless instance.__send__(k).casecmp(v).zero? # case-insensitive comparison
-          true
+        if instance.matches? data
+          instances << instance
+          break if instances.count == limit
         end
-
-        break instance if matches
       end
+
+      instances
+    end
+
+    def find_by(data)
+      instances = where(data, 1)
+      instances ? instances.first : nil
     end
 
     def create(data)
@@ -37,7 +44,7 @@ module Mailchimp
     end
 
     def first_or_create(data)
-      instance = find(data)
+      instance = find_by(data)
       return instance if instance
       create(data)
     end

data/lib/{mailchimp → mailchimp_api_v3}/exception.rb

@@ -1,14 +1,18 @@
-module Mailchimp
+module MailchimpAPIV3
   module Exception
     def self.parse_invalid_resource_exception(data)
-      if data['detail'].include? 'already exists'
+      detail = data['detail']
+
+      if detail.include? 'already exists'
         fail Duplicate, data
+      elsif detail.include? 'can\'t be blank'
+        fail MissingField, data
       else
         fail BadRequest, data
       end
     end
 
-    module DataException
+    class DataException < RuntimeError
       def initialize(data)
         @data = data
         super name || title
@@ -19,16 +23,16 @@ module Mailchimp
       end
     end
 
-    class APIKeyError < RuntimeError
-      include DataException
+    class APIKeyError < DataException
+    end
+
+    class Duplicate < DataException
     end
 
-    class Duplicate < RuntimeError
-      include DataException
+    class MissingField < DataException
     end
 
-    class BadRequest < RuntimeError
-      include DataException
+    class BadRequest < DataException
     end
 
     class UnknownAttribute < RuntimeError

data/lib/mailchimp_api_v3/instance.rb

@@ -0,0 +1,62 @@
+module MailchimpAPIV3
+  module Instance
+    module InstanceMethods
+      def initialize(client, data, collection_path = '')
+        @client = client
+        @collection_path = collection_path
+        @data = data
+        #- puts @data # debug
+      end
+
+      def update(new_data)
+        @data = @client.patch(new_data, path)
+        self
+      end
+
+      def path
+        @path ||= "#{@collection_path}/#{@data['id']}"
+      end
+
+      def matches?(match_data)
+        match_data.each do |k, v|
+          break false unless __send__(k).casecmp(v).zero? # case-insensitive comparison
+          true
+        end
+      end
+
+      def subclass_from(collection_class, options = {})
+        if options.is_a? String
+          # Use it as an id for an instance
+          child_path = "#{path}/#{collection_class.path_key}"
+          collection_class.child_class.get @client, child_path, options
+        else
+          # Get the collection
+          collection_class.new @client, path, options
+        end
+      end
+
+      private
+
+      attr_reader :data
+
+      def method_missing(symbol, options = {})
+        key = symbol.id2name
+        fail_unless_exists key, options
+        @data[key]
+      end
+
+      def fail_unless_exists(key, options = {})
+        return if @data.key? key
+        message = options == {} ? key : "#{key}: #{options}"
+        fail MailchimpAPIV3::Exception::UnknownAttribute, message
+      end
+    end
+
+    module ClassMethods
+      def get(client, collection_path, id)
+        data = client.get "#{collection_path}/#{id}"
+        new client, data, collection_path
+      end
+    end
+  end
+end

data/lib/mailchimp_api_v3/interest.rb

@@ -0,0 +1,10 @@
+module MailchimpAPIV3
+  class List
+    class InterestCategory
+      class Interest
+        include Instance::InstanceMethods
+        extend Instance::ClassMethods
+      end
+    end
+  end
+end

data/lib/{mailchimp → mailchimp_api_v3}/interest_categories.rb

@@ -1,8 +1,10 @@
-require 'mailchimp/interest_category'
+require 'mailchimp_api_v3/interest_category'
 
-module Mailchimp
+module MailchimpAPIV3
   class List
     class InterestCategories < Array
+      include Collection
+
       class << self
         def path_key
           'interest-categories'
@@ -16,8 +18,6 @@ module Mailchimp
           InterestCategory
         end
       end
-
-      include Collection
     end
   end
 end

data/lib/mailchimp_api_v3/interest_category.rb

@@ -0,0 +1,16 @@
+require 'mailchimp_api_v3/interests'
+
+module MailchimpAPIV3
+  class List
+    class InterestCategory
+      #- VALID_TYPES = %w(checkboxes dropdown radio hidden)
+
+      include Instance::InstanceMethods
+      extend Instance::ClassMethods
+
+      def interests(options = {})
+        subclass_from Interests, options
+      end
+    end
+  end
+end

data/lib/{mailchimp → mailchimp_api_v3}/interests.rb

@@ -1,9 +1,11 @@
-require 'mailchimp/interest'
+require 'mailchimp_api_v3/interest'
 
-module Mailchimp
+module MailchimpAPIV3
   class List
     class InterestCategory
       class Interests < Array
+        include Collection
+
         class << self
           def path_key
             'interests'
@@ -17,8 +19,6 @@ module Mailchimp
             Interest
           end
         end
-
-        include Collection
       end
     end
   end

data/lib/mailchimp_api_v3/list.rb

@@ -0,0 +1,26 @@
+require 'mailchimp_api_v3/members'
+require 'mailchimp_api_v3/interest_categories'
+
+module MailchimpAPIV3
+  class List
+    include Instance::InstanceMethods
+    extend Instance::ClassMethods
+
+    def members(options = {})
+      # Turn an email into an id
+      if options.is_a?(String) && (options =~ /\A[^@]+@[^@]+\z/)
+        options = OpenSSL::Digest.digest('MD5', options).unpack('H*').first
+      end
+
+      subclass_from Members, options
+    end
+
+    def interest_categories(options = {})
+      subclass_from InterestCategories, options
+    end
+
+    def id_and_name
+      "#{id}___#{name}"
+    end
+  end
+end

data/lib/{mailchimp → mailchimp_api_v3}/lists.rb

@@ -1,7 +1,9 @@
-require 'mailchimp/list'
+require 'mailchimp_api_v3/list'
 
-module Mailchimp
+module MailchimpAPIV3
   class Lists < Array
+    include Collection
+
     class << self
       def path_key
         'lists'
@@ -15,7 +17,5 @@ module Mailchimp
         List
       end
     end
-
-    include Collection
   end
 end

data/lib/mailchimp_api_v3/member.rb

@@ -0,0 +1,55 @@
+module MailchimpAPIV3
+  class List
+    class Member
+      include Instance::InstanceMethods
+      extend Instance::ClassMethods
+
+      def first_name
+        @first_name ||= merge_fields['FNAME']
+      end
+
+      def last_name
+        @last_name ||= merge_fields['LNAME']
+      end
+
+      def name
+        return @name if @name
+        delim = first_name && last_name ? ' ' : ''
+        @name = "#{first_name}#{delim}#{last_name}"
+      end
+
+      def update(new_data)
+        invalidate_derived_fields
+        super parse_name_from(new_data)
+      end
+
+      private
+
+      def invalidate_derived_fields
+        @first_name = @last_name = @name = nil
+      end
+
+      def parse_name_from(new_data)
+        clean_data = new_data.deep_stringify_keys
+        fname, lname = name_parts_from clean_data
+
+        merge_fields = {}
+        merge_fields['FNAME'] = fname if fname
+        merge_fields['LNAME'] = lname if lname
+        additional_data = merge_fields.empty? ? {} : { 'merge_fields' => merge_fields }
+
+        additional_data.merge clean_data
+      end
+
+      def name_parts_from(clean_data)
+        new_name = clean_data.delete('name')
+        name_parts = new_name ? new_name.split : []
+
+        [
+          clean_data.delete('first_name') || name_parts[0],
+          clean_data.delete('last_name') || name_parts[1]
+        ]
+      end
+    end
+  end
+end

data/lib/{mailchimp → mailchimp_api_v3}/members.rb

@@ -1,8 +1,10 @@
-require 'mailchimp/member'
+require 'mailchimp_api_v3/member'
 
-module Mailchimp
+module MailchimpAPIV3
   class List
     class Members < Array
+      include Collection
+
       class << self
         def path_key
           'members'
@@ -16,8 +18,6 @@ module Mailchimp
           Member
         end
       end
-
-      include Collection
     end
   end
 end

data/lib/mailchimp_api_v3/version.rb

@@ -0,0 +1,3 @@
+module MailchimpAPIV3
+  VERSION = '0.0.4'
+end

data/mailchimp_api_v3.gemspec

@@ -1,14 +1,14 @@
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'mailchimp/version'
+require 'mailchimp_api_v3/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'mailchimp_api_v3'
-  spec.version       = Mailchimp::VERSION
+  spec.version       = MailchimpAPIV3::VERSION
   spec.authors       = ['Xenapto']
   spec.email         = ['developers@xenapto.com']
   spec.description   = 'A simple gem to interact with Mailchimp through their API v3'
-  spec.summary       = 'Example: Mailchimp.new(mc_key).lists'
+  spec.summary       = 'Example: mailchimp.lists("My first list").member("ann@example.com")'
   spec.homepage      = 'https://github.com/Xenapto/mailchimp_api_v3'
   spec.license       = 'BSD'
 
@@ -17,9 +17,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features|coverage)\/})
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'rest-client', '> 1.6'
+  spec.add_runtime_dependency 'rest-client', '~> 1.6', '> 1.6'
 
-  spec.add_development_dependency 'bundler', '> 1.8'
+  spec.add_development_dependency 'bundler', '~> 1.8', '> 1.8'
   spec.add_development_dependency 'rspec', '~> 3.3'
   spec.add_development_dependency 'rspec_junit_formatter', '~> 0.2'
   spec.add_development_dependency 'gem-release', '~> 0.7'