spigot 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a336365a8fdebfc3d1bd45fa11afea3c0a489ba6
+  data.tar.gz: 30a5f6d8ce9c7fce3644233db8d35ff57cc45f17
+SHA512:
+  metadata.gz: b9df09433c59668681cfe6bd9ddb3c1c591b9e3d31c0aff96596477da1ca6144ecd94f1fcbed2b587a54e47bd6d2596cf9bfd6258020939d5229831c31711d96
+  data.tar.gz: e725567b5260a2b0d9e358191cdb5dee627c6a36e844d49582de010d3f1795e8a6d2dcb8e304ece3e24962de3752aa9a78cf1d369a813f55d9faaed5e2b49a11

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rspec
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in spigot.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Matthew Werner
+
+MIT License
+
+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,221 @@
+# Spigot
+
+Spigot provides a clean interface translating API data into context relevant objects
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'spigot'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install spigot
+
+## Usage
+
+You express the mapping between your model's data and the data received from an API in
+a yaml file. The mappings follow the structure of the data received. Any attribute you wish
+to retain, assign the name of your model's attribute to the name of the key received.
+
+Remember, the key is their attribute, the value is yours:
+
+    user:
+      login: 'email'
+      full_name: 'name'
+
+Reads as: "For Users, their `login` is my `email` and their `full_name` is my `name`"
+
+## Example
+
+    # Our Model
+    class User
+      include Spigot::Base
+      attr_accessor :name, :email, :auth
+    end
+
+    # Api Data Received
+    data = {"full_name":"Dean Martin","login":"dino@amore.io","token":"abc123"}
+
+    # Spigot yaml file to map this data correctly
+    user:
+      full_name: name
+      login: email
+      token: auth
+
+    # Usage
+    User.new_by_api(data).inspect
+    #=> #<User:0x007ffa2918c7b8 @name="Dean Martin", @email="dino@amore.io", @auth="abc123">
+
+## Map Format
+
+Each Spigot map file represents one service, with as many resources defined as you like.
+
+##### Basic Map
+
+    user:
+      name: 'full_name'
+      email: 'login'
+      username: 'username'
+
+##### Multiple Resources
+
+Spigot will look up the map for the name of the class implementing the method. This let's you map
+several of your resources that you're getting from the same service.
+
+    # ./config/github.yml
+    user:
+      name: 'full_name'
+      email: 'login'
+      username: 'username'
+
+    post:
+      title: 'title'
+      body: 'description'
+      created_at: 'timestamp'
+
+##### Options
+
+Spigot will look for an options key named `spigot` in the defined map.
+Those options let you configure additional options for that resource,
+such as denoting the identification in the data received.
+
+    user:
+      name: 'full_name'
+      email: 'login'
+      username: 'username'
+      spigot:
+        primary_key: 'service_id'
+        foreign_key: 'id'
+
+## ActiveRecord
+
+If you include Spigot on an ActiveRecord class, you get a few more methods.
+
+##### `find_by_api`
+
+This uses the primary key defined in that resource's options to query the database
+with the value taken from the api data. (**Note** Does not update any values on the
+record received from the database.)
+
+    # Spigot yaml file for the github service
+    user:
+      full_name: name
+      login: email
+      token: auth
+      spigot:
+        primary_key: email
+
+    # API Data
+    data = {"full_name":"Dean","login":"dino@amore.io","token":"bcd456"}
+
+    #=> User.find_by_api(:github, data)
+    User Load (0.1ms)  SELECT "users".* FROM "users" WHERE "users"."email" = 'dino@amore.io' ORDER BY "users"."id" ASC LIMIT 1
+    #=> #<User id: 1, name: "Dean Martin", email: "dino@amore.io", token: "abc123">
+
+##### `find_all_by_api`
+
+Operates just like `find_by_api`, but returns all matches on the primary key. The method
+returns an `ActveRecord::Relation` allowing you to chain other constraints if you need.
+
+    # Spigot yaml file for the github service
+    user:
+      full_name: name
+      login: email
+      token: auth
+      spigot:
+        primary_key: full_name
+
+    # API Data
+    data = {"full_name":"Dean","login":"dino@amore.io","token":"bcd456"}
+
+    #=> User.find_all_by_api(:github, data)
+    User Load (0.1ms)  SELECT "users".* FROM "users" WHERE "users"."name" = 'Dean'
+    => #<ActiveRecord::Relation [#<User id: 1, name: "Dean", email: "dino@amore.io", token: "abc123">, #<User id: 2, name: "Dean", email: "minerals@notrocks.io", token: '92fnd'>]>
+
+##### `create_by_api`
+
+Creates a record in your database using the provided API data, without doing
+any kind of query before, beyond your model's defined validations. Notice the
+creation does not use any of the API that isn't defined in the map.
+
+    # Spigot yaml file for the github service
+    user:
+      full_name: name
+      login: email
+      token: auth
+      spigot:
+        primary_key: email
+
+    # API Data
+    data = {"full_name":"Frank Sinatra","login":"live@tilidie.io","id":"3"}
+
+    #=> User.create_by_api(:github, data)
+    SQL (0.1ms)  INSERT INTO "users" ("name", "email") VALUES (?, ?)  [["name", "Frank Sinatra"], ["email", "live@tilidie.io"]]
+    => #<User id: 4, name: "Frank Sinatra", email: "live@tilidie.io", token: nil>
+
+##### `update_by_api`
+
+Updates a record in your database. If no record matching the primary key is found, nothing happens.
+
+    # Spigot yaml file for the github service
+    user:
+      full_name: name
+      login: email
+      token: auth
+      spigot:
+        primary_key: email
+
+    # API Data
+    data = {"full_name":"Dino Baby","login":"dean@amore.io","token":"bcd456"}
+
+    #=> User.update_by_api(:github, data)
+    User Load (0.2ms)  SELECT "users".* FROM "users" WHERE "users"."email" = 'livetilidie' ORDER BY "active_users"."id" ASC LIMIT 1
+    SQL (0.1ms)  UPDATE "users" SET "name" = ?, token = ? WHERE "users"."id" = 3  [["name", "Dino Baby"], ["token", "bcd456"]]
+    => #<User id: 3, name: "Dino Baby", email: "dean@amore.io", token: "bcd456">
+
+##### `find_or_create_by_api`
+
+Query the database to find an existing record. If none is found, create one with the provided API data.
+
+##### `create_or_update_by_api`
+
+Query the database to find an existing record. If a record is found, update
+the record with the received API data. If no record is found, create one with
+the provided API data.
+
+## Configuration
+
+There are a handful of options that let you make spigot work the way you need.
+
+    logger:
+      Specify a logger you would like Spigot to log to.
+      type:    Object
+      default: Logger.new(STDOUT)
+
+    options_key:
+      The key which Spigot uses for configuring a resource map.
+      type:    String
+      default: 'spigot'
+
+    path:
+      The directory which holds all the yaml files for the implemented services
+      type:    String
+      default: 'config/spigot'
+
+    translations:
+      A map that, if present, overrides the resource maps found in the `path` directory
+      type:    Hash
+      default: nil
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/examples/active_record.rb

@@ -0,0 +1,57 @@
+require 'active_record'
+require 'spigot'
+require 'net/http'
+require 'uri'
+
+ActiveRecord::Base.logger = Spigot.logger
+ActiveRecord::Base.establish_connection({
+  :adapter => "sqlite3",
+  :database => ':memory:'
+})
+
+ActiveRecord::Schema.define do
+  self.verbose = false
+  create_table :users, :force => true do |t|
+    t.integer :github_id
+    t.string  :username
+    t.string  :image_url
+    t.string  :profile_url
+  end
+end
+
+class User < ActiveRecord::Base
+  include Spigot::Base
+end
+
+Spigot.configure do |config|
+  config.translations = {'user' => {
+    'id'         => 'github_id',
+    'login'      => 'username',
+    'avatar_url' => 'image_url',
+    'url'        => 'profile_url',
+    'spigot' => {
+      'primary_key' => 'username'
+    }
+  }}
+end
+
+puts "Making a request to an external API (Github)"
+response = Net::HTTP.get_response URI.parse("https://api.github.com/users/mwerner")
+puts "Parse the response: `data = JSON.parse(response.body)`"
+data = JSON.parse(response.body)
+
+puts "\nReceived a whole bunch of data: "
+puts "#{data.inspect[0..100]}... etc, etc, etc (#{data.keys.length} more keys received)"
+
+puts "\nWe don't want to use all of it. We can define a map on Spigot:"
+puts User.spigot(:github).map.inspect
+puts "Each key is an attribute received from the API, and the corresponding value is our column name."
+
+puts "\nWe define our primary key in the spigot `User` options, so we know how to check if the record already exists:"
+puts User.spigot(:github).options.inspect
+
+
+puts "\nWe can create a new user with one nice and easy line: `User.find_or_create_by_api(:github, data)`"
+puts User.find_or_create_by_api(:github, data).inspect
+
+puts "\nEnjoy!"

data/examples/model.rb

@@ -0,0 +1,34 @@
+require 'spigot'
+
+Spigot.configure do |config|
+  config.translations = {
+    'user' => {
+      'full_name' => 'name',
+      'login' => 'username'
+    }
+  }
+end
+
+class User
+  include Spigot::Base
+
+  attr_reader :name, :username
+
+  def initialize(params={})
+    params.each_pair do |k, v|
+      instance_variable_set("@#{k}".to_sym, v)
+    end
+  end
+
+  def self.api_data
+    { full_name: 'matthew', login: 'mwerner' }
+  end
+
+  def self.build
+    new_by_api(:github, api_data)
+  end
+end
+
+user = User.build
+puts user.name
+puts user.inspect

data/lib/spigot.rb

@@ -0,0 +1,32 @@
+require "spigot/version"
+require "spigot/errors"
+
+module Spigot
+  autoload :Configuration, 'spigot/configuration'
+  autoload :Translator,    'spigot/translator'
+  autoload :Record,        'spigot/record'
+  autoload :Base,          'spigot/base'
+  autoload :ActiveRecord,  'spigot/active_record'
+  autoload :Proxy,         'spigot/proxy'
+
+  def self.config
+    Configuration.instance
+  end
+
+  def self.configure
+    yield config
+  end
+
+  def self.root
+    File.expand_path('../..', __FILE__)
+  end
+
+  def self.logger
+    @log ||= Spigot.config.logger || begin
+      buffer = Logger.new(STDOUT)
+      buffer.level = $0 == 'irb' ? Logger::DEBUG : Logger::INFO
+      buffer.formatter = proc{|severity, datetime, progname, msg| "#{msg}\n"}
+      buffer
+    end
+  end
+end

data/lib/spigot/active_record.rb

@@ -0,0 +1,106 @@
+module Spigot
+  module ActiveRecord
+    module ClassMethods
+
+      ## #find_by_api(service, api_data)
+      # Build a query based on the defined map for this resource
+      # to find a single matching record in the database
+      #
+      # @param service [Symbol] Service from which the data was received
+      # @param api_data [Hash] The data as received from the remote api, unformatted.
+      def find_by_api(service, api_data)
+        find_all_by_api(service, api_data).first
+      end
+
+      ## #find_all_by_api(service, api_data)
+      # Build a query based on the defined map for this resource
+      # to find all matching records in the database
+      #
+      # @param service [Symbol] Service from which the data was received
+      # @param api_data [Hash] The data as received from the remote api, unformatted.
+      def find_all_by_api(service, api_data)
+        find_by_translator Translator.new(service, self, api_data)
+      end
+
+      ## #create_by_api(service, api_data)
+      # Insert mapped data into the calling model's table. Does not
+      # do any checks on existing content already present in the database
+      #
+      # @param service [Symbol] Service from which the data was received
+      # @param api_data [Hash] The data as received from the remote api, unformatted.
+      def create_by_api(service, api_data)
+        create_by_translator Translator.new(service, self, api_data)
+      end
+
+      ## #update_by_api(service, api_data)
+      # Queries the database to find an existing record, based on the options
+      # provided to spigot. If a record is found, it updates that record
+      # with any new data received by the API
+      #
+      # @param service [Symbol] Service from which the data was received
+      # @param api_data [Hash] The data as received from the remote api, unformatted.
+      def update_by_api(service, api_data)
+        babel = Translator.new(service, self, api_data)
+        record = find_by_translator(babel).first
+        update_by_translator(babel, record) if record.present?
+      end
+
+      ## #find_or_create_by_api(service, api_data)
+      # Queries the database to find an existing record. If that record is found
+      # simply return it, otherwise create a new record and return it. This does
+      # not update any existing record. If you want that, use `create_or_update_by_api`
+      #
+      # @param service [Symbol] Service from which the data was received
+      # @param api_data [Hash] The data as received from the remote api, unformatted.
+      def find_or_create_by_api(service, api_data)
+        babel = Translator.new(service, self, api_data)
+        find_by_translator(babel).first || create_by_translator(babel)
+      end
+
+      ## #create_or_update_by_api(service, api_data)
+      # Queries the database to find an existing record. If that record is found
+      # it updates it with passed api_data and returns the record. Otherwise it
+      # creates a new record and returns the newly created record.
+      #
+      # @param service [Symbol] Service from which the data was received
+      # @param api_data [Hash] The data as received from the remote api, unformatted.
+      def create_or_update_by_api(service, api_data)
+        babel = Translator.new(service, self, api_data)
+        record = find_by_translator(babel).first
+        record.present? ? update_by_translator(babel, record) : create_by_translator(babel)
+      end
+
+      private
+
+      def find_by_translator(translator)
+        if invalid_primary_keys?(translator)
+          raise Spigot::InvalidSchemaError, "The #{translator.primary_key} column does not exist on #{self.to_s}"
+        end
+
+        if translator.id.blank?
+          Spigot.logger.warn "   <Spigot::Warning> No #{translator.service} API data found at :#{translator.foreign_key}"
+        end
+
+        return [] if translator.conditions.blank?
+        self.where(translator.conditions)
+      end
+
+      def create_by_translator(translator)
+        Record.create(self, translator.format)
+      end
+
+      def update_by_translator(translator, record)
+        Record.update(self, record, translator.format)
+        record
+      end
+
+      def invalid_primary_keys?(translator)
+        [*translator.primary_key].each do |key|
+          return true unless self.column_names.include?(key.to_s)
+        end
+        false
+      end
+    end
+
+  end
+end