jammed 0.1.0

data/.gitignore

@@ -0,0 +1,6 @@
+coverage
+rdoc
+pkg/*
+*.gem
+.bundle
+Gemfile.lock

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem "httparty", ">= 0.8.2"
+
+group :development do
+  gem "rake", ">= 0.8.7"
+  gem "jeweler", ">= 1.8.3"
+  gem "rspec", ">= 2.9.0"
+  gem "webmock", ">= 1.8.6"
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Sean S. Lerner
+
+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,54 @@
+#Jammed [![Build Status](https://secure.travis-ci.org/seanslerner/Jammed.png?branch=master)](http://travis-ci.org/seanslerner/Jammed)
+###A Ruby API wrapper for [This Is My Jam](http://www.thisismyjam.com/).
+
+Note: The API for This Is My Jam is stil in beta, so if you'd like to use it please email the Jam team at api@thisismyjam.com to get on their mailing list.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'jammed'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install jammed
+
+## Usage
+
+Note: Right now, since the API is in beta, `Jammed.new` can be called without supplying an API key (it defaults to the beta key). Once individual dev keys are available this will change.
+
+```ruby
+require 'jammed'
+
+jammed = Jammed.new('987bcab01b929eb2c07877b224215c92')
+
+pop_jams = jammed.popular_jams
+
+iftfom_profile = jammed.profile('IFTFOM')
+iftfom_likes = jammed.likes('IFTFOM', :show => :current)
+
+iftfom = jammed.user('IFTFOM')
+iftfom.profile # same as jammed.profile('IFTFOM')
+iftfom.likes(:show => :current) # same as jammed.likes('IFTFOM', :show => :current)
+iftfom.likes! #resets cached likes and return all of IFTFOM's like
+```
+
+Also, pagination is not supported at the moment. So, at most you will get the first 60 results for any API call that returns a list. Automatically handling pagination is a first priority for the next release.
+
+## Links
+
+* [This Is My Jam](http://www.thisismyjam.com/)
+* [This Is My Jam API Documentation](http://www.thisismyjam.com/developers/beta)
+* [This Is My Jam API Google Group](https://groups.google.com/forum/?fromgroups#!forum/thisismyapi)
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,44 @@
+#!/usr/bin/env rake
+
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require File.expand_path('../lib/jammed/version', __FILE__)
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name          = "jammed"
+  gem.homepage      = "https://github.com/seanslerner/Jammed"
+  gem.license       = "MIT"
+  gem.summary       = %q{A Ruby wrapper for This Is My Jam's API}
+  gem.description   = %q{Jammed wraps the This Is My Jam API. More information about the This Is My Jam API can be found on their website (http://www.thisismyjam.com/developers).}
+  gem.email         = ["seanslerner@gmail.com"]
+  gem.authors       = ["Sean Lerner", "Rob Young", "Mike Chlipala"]
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(spec)/})
+  gem.require_paths = ["lib"]
+  gem.version       = Jammed::VERSION
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Jammed #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/examples/basics.rb

@@ -0,0 +1,60 @@
+require 'jammed'
+
+api_key = '987bcab01b929eb2c07877b224215c92'
+
+jammed = Jammed.new(api_key)
+
+# Print out a user's profile data
+puts "IFTFOM's Profile:"
+jammed.profile('IFTFOM').each {|k, v| puts "#{k} : #{v}"}
+
+# Print out the names of all followers, followings, jams, and likes
+puts "Followers:"
+jammed.followers('IFTFOM').each { |f| puts f['name']}
+
+puts "Followings:"
+jammed.following('IFTFOM').each { |f| puts f['name']}
+
+puts "Jams:"
+jammed.jams('IFTFOM').each { |j| puts "#{j['artist']}: #{j['title']}"}
+
+puts "Likes:"
+jammed.likes('IFTFOM').each { |l| puts "#{l['artist']}: #{l['title']}"}
+
+# Alternative way to access user-specific data:
+# The Jammed::User object caches data, so each method 
+# has a 'dangerous' version (ie #followers!) that clears
+# and resets the cached data
+iftfom = jammed.user('IFTFOM')
+
+puts "Followers:"
+iftfom.followers.each { |f| puts f['name']}
+
+puts "Followings:"
+iftfom.following.each { |f| puts f['name']}
+
+puts "Jams:"
+iftfom.jams.each { |j| puts "#{j['artist']}: #{j['title']}"}
+
+puts "Likes:"
+iftfom.likes.each { |l| puts "#{l['artist']}: #{l['title']}"}
+
+puts "IFTFOM's Profile:"
+iftfom.profile.each {|k, v| puts "#{k} : #{v}"}
+
+# Non-user specific data
+puts "Popular Jams:"
+jammed.popular_jams.each { |j| puts "#{j['artist']}: #{j['title']}"}
+
+puts "Suggested People:"
+jammed.suggested_people.each { |p| puts p['name']}
+
+#Searches
+puts "Search by Name:"
+jammed.search_name('IFTFOM').each {|p| puts p['name']}
+
+puts "Search by Artist:"
+jammed.search_artist('Talking Heads').each {|p| puts p['name']}
+
+puts "Search by Track:"
+jammed.search_track('The The', 'This is the Day').each {|p| puts p['name']}

data/lib/jammed/base.rb

@@ -0,0 +1,182 @@
+module Jammed
+  # A base class for interacting with the API
+  class Base
+
+    #Stores the API key to be used for all method calls on the Jammed::Base object
+    attr_reader :api_key
+
+    #Sets the API key + any options
+    def initialize(api_key, opts={})
+      @api_key = api_key
+    end
+
+    # Calls Jammed::Followers
+    #
+    # ==== Attributes
+    #
+    # * +username+ - Username of user whose followers you want to retrieve
+    # * +opts+ - Options for ordering Followers data
+    #
+    # ==== Options
+    #
+    # * +:order+ - A symbol determining how the data is orderd like :date, :affinity, or :alpha
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035') 
+    #     jammed.followers('IFTFOM', :order => :date)
+    def followers(username, opts={})
+      Followers.followers(username, @api_key, opts)
+    end
+
+    # Calls Jammed::Following
+    #
+    # ==== Attributes
+    #
+    # * +username+ - Username of user whose followings you want to retrieve
+    # * +opts+ - Options for ordering Following data
+    #
+    # ==== Options
+    #
+    # * +:order+ - A symbol determining how the data is orderd like :date, :affinity, or :alpha
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035') 
+    #     jammed.following('IFTFOM', :order => :date)
+    def following(username, opts={})
+      Following.following(username, @api_key, opts)
+    end
+
+    # Calls Jammed::Jams
+    #
+    # ==== Attributes
+    #
+    # * +username+ - Username of user whose jams you want to retrieve
+    # * +opts+ - Options for which jams to retrieve
+    #
+    # ==== Options
+    #
+    # * +:show+ - A symbol determining which data is shown (:past | :current)
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035') 
+    #     jammed.jams('IFTFOM', :show => :current)
+    def jams(username, opts={})
+      Jams.jams(username, @api_key, opts)
+    end
+
+    # Calls Jammed::Likes.likes
+    #
+    # ==== Attributes
+    #
+    # * +username+ - Username of user whose likes you want to retrieve
+    # * +opts+ - Options for which likes to retrieve
+    #
+    # ==== Options
+    #
+    # * +:show+ - A symbol determining which data is shown (:past | :current)
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035') 
+    #     jammed.likes('IFTFOM', :show => :current)
+    def likes(username, opts={})
+      Likes.likes(username, @api_key, opts)
+    end
+
+    # Calls Jammed::PopularJams.popular_jams
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035')
+    #     jammed.popular_jams
+    def popular_jams
+      PopularJams.popular_jams(@api_key)
+    end
+
+    # Calls Jammed::Person.profile
+    #
+    # ==== Attributes
+    #
+    # * +username+ - Username of user profile want to retrieve
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035') 
+    #     jammed.profile('IFTFOM')
+    def profile(username)
+      Person.profile(username, @api_key)
+    end
+
+    # Calls Jammed::PeopleSearch.search_name
+    #
+    # ==== Attributes
+    #
+    # *+name+ - Name you want to search by
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035')
+    #     jammed.search_name('IFTFOM')
+    def search_name(name)
+      PeopleSearch.search_name(name, @api_key)
+    end
+
+    # Calls Jammed::PeopleSearch.search_artist
+    #
+    # ==== Attributes
+    #
+    # *+artist+ - Artist you want to search by
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035')
+    #     jammed.search_artist('IFTFOM')
+    def search_artist(artist)
+      PeopleSearch.search_artist(artist, @api_key)
+    end
+
+    # Calls Jammed::PeopleSearch.search_track
+    #
+    # ==== Attributes
+    #
+    # *+artist+ - Artist you want to search by
+    # *+track+ - Track you want to search by
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035')
+    #     jammed.search_track('IFTFOM')
+    def search_track(artist, track)
+      PeopleSearch.search_track(artist, track, @api_key)
+    end
+
+    # Calls Jammed::SuggestedPeople.people
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035')
+    #     jammed.suggest_people
+    def suggested_people
+      SuggestedPeople.people(@api_key)
+    end
+
+    # Calls Jammed::User.new and creates a new User object for interacting with user specific data. It provides methods for interacting with user-specific data.
+    #
+    # ==== Attributes
+    #
+    # * +username+ - Username of user you want the object oriented with
+    #
+    # ==== Examples
+    #
+    #     jammed = Jammed.new('08972935872035') 
+    #     ift = jammed.user('IFTFOM')
+    #     ift.profile
+    #     ift.jams(:show => :past)
+    def user(username)
+      User.new(username, @api_key)
+    end
+  end
+end

data/lib/jammed/followers.rb

@@ -0,0 +1,36 @@
+module Jammed #:nodoc: 
+  # Provides methods for calling API endpoint /follower.json?
+  class Followers
+    # Calls API for user specific data concerning followers
+    #
+    # ==== Attributes
+    #
+    # * +username+ - The username of the user whose followers you want to retrieve
+    # * +api_key+ - The key to use with the API call
+    # * +opts+ - Options for ordering the data
+    #
+    # ==== Options
+    #
+    # * +:order+ - A symbol determining how the data is orderd like :date, :affinity, or :alpha
+    #
+    # ==== Examples
+    #
+    #     Jammed::Followers.followers('IFTFOM', '08972935872035') #returns followers unorderd
+    #     Jammed::Followers.followers('IFTFOM', '08972935872035', :order => :date) # returns followers ordered by date
+    def self.followers(username, api_key, opts={})
+      case(opts[:order])
+      when nil
+        followers = Search.get "/#{username}/followers.json?key=#{api_key}"
+      when :date
+        followers = Search.get "/#{username}/followers.json?order=followedDate&key=#{api_key}"
+      when :affinity
+        followers = Search.get "/#{username}/followers.json?order=affinity&key=#{api_key}"
+      when :alpha
+        followers = Search.get "/#{username}/followers.json?order=name&key=#{api_key}"
+      else
+        return "Cannot order Followers by #{opts[:order]}"
+      end
+      followers["people"] ? followers["people"] : "404 Not Found" 
+    end
+  end
+end

data/lib/jammed/following.rb

@@ -0,0 +1,36 @@
+module Jammed #:nodoc:
+  # Provides methods for calling API endpoint /following.json?
+  class Following
+    # Calls API for user specific data concerning who the user is following
+    #
+    # ==== Attributes
+    #
+    # * +username+ - The username of the user whose followings you want to retrieve
+    # * +api_key+ - The key to use with the API call
+    # * +opts+ - Options for ordering the data
+    #
+    # ==== Options
+    #
+    # * +:order+ - A symbol determining how the data is orderd like :date, :affinity, or :alpha
+    #
+    # ==== Examples
+    #
+    #     Jammed::Following.following('IFTFOM', '08972935872035') #returns followings unorderd
+    #     Jammed::Following.following('IFTFOM', '08972935872035', :order => :date) # returns followings ordered by date
+    def self.following(username, api_key, opts={})
+      case(opts[:order])
+      when nil
+        followings = Search.get "/#{username}/following.json?key=#{api_key}"
+      when :date
+        followings = Search.get "/#{username}/following.json?order=followedDate&key=#{api_key}"
+      when :affinity
+        followings = Search.get "/#{username}/following.json?order=affinity&key=#{api_key}"
+      when :alpha
+        followings = Search.get "/#{username}/following.json?order=name&key=#{api_key}"
+      else
+        return "Cannot order Followings by #{opts[:order]}"
+      end
+      followings["people"] ? followings["people"] : "404 Not Found" 
+    end
+  end
+end

data/lib/jammed/jams.rb

@@ -0,0 +1,34 @@
+module Jammed #:nodoc:
+  # Provides methods for calling API endpoint /jams.json?
+  class Jams
+    # Calls API for user specific data concerning jams
+    #
+    # ==== Attributes
+    #
+    # * +username+ - The username of the user whose followings you want to retrieve
+    # * +api_key+ - The key to use with the API call
+    # * +opts+ - Options for which data is shown
+    #
+    # ==== Options
+    #
+    # * +:show+ - A symbol determining what data is shown like :past or :current
+    #
+    # ==== Examples
+    #
+    #     Jammed::Jams.jams('IFTFOM', '08972935872035') #returns all jams
+    #     Jammed::Jams.jams('IFTFOM', '08972935872035', :show => :past) # returns only past jams
+    def self.jams(username, api_key, opts={})
+      case(opts[:show])
+      when nil
+        jams = Search.get "/#{username}/jams.json?key=#{api_key}"
+        jams["jams"] ? jams["jams"] : "404: User Not Found"
+      when :past
+        jams = Search.get "/#{username}/jams.json?show=past&key=#{api_key}"
+        jams["jams"] ? jams["jams"] : "404: User Not Found"
+      when :current
+        jams = Search.get "/#{username}/jams.json?key=#{api_key}"
+        jams["jams"][0]['current'] ? jams["jams"][0] : "No Current Jam"
+      end
+    end
+  end
+end

data/lib/jammed/likes.rb

@@ -0,0 +1,32 @@
+module Jammed #:nodoc:
+  # Provides methods for calling API endpoint /likes.json?
+  class Likes
+    # Calls API for user specific data concerning likes
+    #
+    # ==== Attributes
+    #
+    # * +username+ - The username of the user whose followings you want to retrieve
+    # * +api_key+ - The key to use with the API call
+    # * +opts+ - Options for which data is shown
+    #
+    # ==== Options
+    #
+    # * +:show+ - A symbol determining what data is shown like :past or :current
+    #
+    # ==== Examples
+    #
+    #     Jammed::Likes.likes('IFTFOM', '08972935872035') #returns all likes
+    #     Jammed::Likes.likes('IFTFOM', '08972935872035', :show => :past) # returns only past likes
+    def self.likes(username, api_key, opts={})
+      case(opts[:show])
+      when nil
+        likes = Search.get "/#{username}/likes.json?key=#{api_key}"
+      when :current
+        likes = Search.get "/#{username}/likes.json?show=current&key=#{api_key}"
+      when :past
+        likes = Search.get "/#{username}/likes.json?show=past&key=#{api_key}"
+      end
+      likes["jams"] ? likes["jams"] : "404: Not Found"
+    end
+  end
+end

data/lib/jammed/people_search.rb

@@ -0,0 +1,55 @@
+require 'uri'
+
+module Jammed #:nodoc:
+  # Provides methods for calling API endpoint /person.json?by=
+  class PeopleSearch
+
+    # Calls API for a search by username
+    #
+    # ==== Attributes
+    #
+    # * +name+ - Username to search by
+    # * +api_key+ - The key to use with the API call
+    #
+    # ==== Examples
+    #
+    #     Jammed::PeopleSearch.search_name('IFTFOM', '08972935872035')
+    def self.search_name(name, api_key)
+      search = Search.get "/search/person.json?by=name&q=#{name.split.join('+')}&key=#{api_key}"
+      search["people"][0] ? search["people"] : "No people found"
+    end
+
+    # Calls API for a search by artist
+    #
+    # ==== Attributes
+    #
+    # * +artist+ - Artist to search by
+    # * +api_key+ - The key to use with the API call
+    #
+    # ==== Examples
+    #
+    #     Jammed::PeopleSearch.search_artist('beach boys', '08972935872035')
+    def self.search_artist(artist, api_key)
+      search = Search.get "/search/person.json?by=artist&q=#{artist.split.join('+')}&key=#{api_key}"
+      search["people"][0] ? search["people"] : "No artists found"
+    end
+
+    # Calls API for a search by track
+    #
+    # ==== Attributes
+    #
+    # * +artist+ - Artist to search by
+    # * +track+ - Track to search by
+    # * +api_key+ - The key to use with the API call
+    #
+    # ==== Examples
+    #
+    #     Jammed::PeopleSearch.search_track('beach boys', 'good vibrations', '08972935872035')
+    def self.search_track(artist, track, api_key)
+      uri = URI.escape("/search/person.json?by=track&q=#{artist.split.join('+')}|#{track.split.join('+')}&key=#{api_key}", '|')
+      search = Search.get uri   
+      search["people"][0] ? search["people"] : "No tracks found"  
+    end
+
+  end
+end

data/lib/jammed/person.rb

@@ -0,0 +1,32 @@
+module Jammed #:nodoc:
+  # Provides methods for calling API endpoint /username.json? and accessing user specific data
+  class Person
+    # Calls API for a specific user's profile
+    #
+    # ==== Examples
+    #
+    #     Jammed::Person.profile('IFTFOM', '08972935872035') #returns IFTFOM's profile data
+    def self.profile(username, api_key)
+      profile = Search.get "/#{username}.json?key=#{api_key}"
+      profile["person"] ? profile["person"] : "404: User Not Found"
+    end
+
+    # Calls API for a specific user's name
+    #
+    # ==== Examples
+    #
+    #     Jammed::Person.name('IFTFOM', '08972935872035') #returns 'IFTFOM'
+    def self.name(username, api_key)
+      self.profile(username, api_key)['name']
+    end
+
+    # Calls API for a specific attribute of a user's profile
+    #
+    # ==== Examples
+    #
+    #     Jammed::Person.joinedDate('IFTFOM', '08972935872035') #returns IFTFOM's joined date
+    def self.method_missing(name, *args, &block)
+      self.profile(args[0],args[1]).has_key?(name.to_s) ? self.profile(args[0],args[1])[name.to_s] : super
+    end
+  end
+end

data/lib/jammed/popular_jams.rb

@@ -0,0 +1,14 @@
+module Jammed #:nodoc:
+  # Provides method for calling API endpoint /popular.json?
+  class PopularJams
+    # Calls API for popular jams
+    #
+    # ==== Examples
+    #
+    #     Jammed::PopularJams.popular_jams('08972935872035') #returns a sample of popular jams
+    def self.popular_jams(api_key)
+      search = Search.get "/popular.json?key=#{api_key}"
+      search['jams'] ? search['jams'] : "404 Not Found"
+    end
+  end
+end

data/lib/jammed/suggested_people.rb

@@ -0,0 +1,14 @@
+module Jammed #:nodoc:
+  # Provides method for calling API endpoint /suggestedPeople.json?
+  class SuggestedPeople
+    # Calls API for suggested people
+    #
+    # ==== Examples
+    #
+    #     Jammed::SuggestedPeople.people('08972935872035') #returns a list of users with many followers/likes
+    def self.people(api_key)
+      response = Search.get "/suggestedPeople.json?key=#{api_key}"
+      response["people"][0] ? response["people"] : "No people found"
+    end
+  end
+end