etsy 0.1.0

data/README.rdoc

@@ -0,0 +1,125 @@
+= Etsy
+
+== Description
+
+The Etsy gem provides a friendly Ruby interface to the Etsy API
+
+== Installation
+
+Installing the latest stable version is simple:
+
+    sudo gem install etsy
+
+If you want to be on the bleeding edge, install from GitHub:
+
+    sudo gem install reagent-etsy --source=http://gems.github.com
+
+== Usage
+
+The Etsy API is read-only - all you need to gain access is an API Key (available 
+from http://developer.etsy.com).  Once you have your API key, set it in your script:
+
+    require 'rubygems'
+    require 'etsy'
+    Etsy.api_key = 'foobar'
+
+From there, you can make any calls to the API that you need.
+
+=== Users
+
+If you're starting with a user, the easiest way is to use the Etsy.user method:
+
+    >> user = Etsy.user('littletjane')
+    => #<Etsy::User:0x107f82c @result=[{"city"=>"Washington, DC", ... > 
+    >> user.username
+    => "littletjane"
+    >> user.id
+    => 5327518
+    >> user.url
+    => "http://www.etsy.com/shop.php?user_id=5327518"
+
+For more information about what is available for a user, check out the documentation
+for Etsy::User.
+
+== Shops
+
+Each user may optionally have a shop.  If a user is a seller, he / she also has an
+associated shop object:
+
+  >> user.seller?
+  => true
+  >> shop = user.shop
+  => #<Etsy::Shop:0x102578c @result={"is_vacation"=>"", "announcement"=> ... >
+  >> shop.name
+  => "littletjane"
+  >> shop.title
+  => "a cute and crafty mix of handmade goods."
+  
+More information about shops can be found in the documentation for Etsy::Shop.
+  
+== Listings
+
+Shops contain multiple listings:
+
+  >> shop.listings
+  => [#<Etsy::Listing:0x119acac @result={} ...>, ... ]
+  >> listing = shop.listings.first
+  => #<Etsy::Listing:0x19a981c @result={} ... >
+  >> listing.title
+  => "hanging with the bad boys matchbox"
+  >> listing.description
+  => "standard size matchbox, approx. 1.5 x 2 inches ..."
+  >> listing.url
+  => "http://www.etsy.com/view_listing.php?listing_id=24165902"
+  >> listing.view_count
+  => 19
+  >> listing.created_at
+  => Sat Apr 25 11:31:34 -0400 2009
+
+See the documentation for Etsy::Listing for more information.
+
+== Images
+
+Each listing has one or more images available:
+
+  >> listing.images
+  => [#<Etsy::Image:0x18f85e4 @result={} ... >,
+      #<Etsy::Image:0x18f85d0 @result={} ... >]
+  >> listing.images.first.small_square
+  => "http://ny-image2.etsy.com/il_25x25.67765346.jpg"
+  >> listing.images.first.large
+  => "http://ny-image2.etsy.com/il_430xN.67765346.jpg"
+
+Listings also have a primary image:
+
+  >> listing.image
+  => #<Etsy::Image:0x18c3060 @result={} ... >
+  >> listing.image.large
+  => "http://ny-image2.etsy.com/il_430xN.67765346.jpg"
+
+More information is available in the documentation for Etsy::Image.
+
+== License
+
+Copyright (c) 2009 Patrick Reagan (reaganpr@gmail.com)
+
+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/Rakefile

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/etsy/version'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name             = 'etsy'
+  s.version          = Etsy::Version.to_s
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w(README.rdoc)
+  s.rdoc_options     = %w(--main README.rdoc)
+  s.summary          = "Provides a friendly ruby-like interface to the Etsy API"
+  s.author           = 'Patrick Reagan'
+  s.email            = 'reaganpr@gmail.com'
+  s.homepage         = 'http://sneaq.net'
+  s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
+  # s.executables    = ['etsy']
+  
+  s.add_dependency('json', '~> 1.1.0')
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc 'Generate the gemspec to serve this Gem from Github'
+task :github do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end

data/lib/etsy.rb

@@ -0,0 +1,65 @@
+$:.unshift File.dirname(__FILE__)
+
+require 'net/http'
+require 'json'
+
+require 'etsy/request'
+require 'etsy/response'
+
+require 'etsy/model'
+require 'etsy/user'
+require 'etsy/shop'
+require 'etsy/listing'
+require 'etsy/image'
+
+# = Etsy: A friendly Ruby interface to the Etsy API
+#
+# == Quick Start
+# 
+# Getting started is easy.  First, you will need a valid API key from the Etsy 
+# developer site (http://developer.etsy.com/).  Since the API is read-only at
+# the moment, that's all you need to do.
+# 
+# To start using the API, require the etsy gem and set it up to use your API key:
+# 
+#     require 'rubygems'
+#     require 'etsy'
+#     
+#     Etsy.api_key = 'itsasecret'
+#     
+# Now you can make API calls that originate from an Etsy user:
+# 
+#     # Find a user by username
+#     user = Etsy.user('littletjane')
+#     
+#     # Grab that user's shop information
+#     user.seller?
+#     user.shop
+#     user.shop.title
+#     
+#     # ... and the listings in the shop
+#     listing = user.shop.listings.first
+#     listing.title
+#     listing.description
+#     
+# To see what else is available for a user, check out the full documentation for
+# the Etsy::User class.
+#
+module Etsy
+ 
+  # Set the API key for all requests
+  def self.api_key=(api_key)
+    @api_key = api_key
+  end
+  
+  # Retrieve the API key
+  def self.api_key
+    @api_key
+  end
+  
+  # Find a user by username.  See Etsy::User for more information.
+  def self.user(username)
+    User.find_by_username(username)
+  end
+  
+end

data/lib/etsy/image.rb

@@ -0,0 +1,27 @@
+module Etsy
+  
+  # = Image
+  #
+  # Represents an image resource of an Etsy listing and contains multiple sizes. 
+  # Sizes available are:
+  #
+  # [small_square] The smallest square image (25x25 pixels)
+  # [medium_square] The medium square image (50x50 pixels)
+  # [large_square] The largest square image (75x75 pixels)
+  # [small] The small image for this listing (155x125 pixels)
+  # [medium] The medium image for this listing (200x200 pixels)
+  # [large] The largest image available for this listing (430x? pixels)
+  #
+  class Image
+    
+    include Etsy::Model
+  
+    attribute :small_square, :from => :image_url_25x25
+    attribute :medium_square, :from => :image_url_50x50
+    attribute :large_square, :from => :image_url_75x75 
+    attribute :small, :from => :image_url_155x125
+    attribute :medium, :from => :image_url_200x200
+    attribute :large, :from => :image_url_430xN
+
+  end
+end

data/lib/etsy/listing.rb

@@ -0,0 +1,76 @@
+module Etsy
+  
+  # = Listing
+  #
+  # Represents a single Etsy listing.  Has the following attributes:
+  #
+  # [id] The unique identifier for this listing
+  # [title] The title of this listing
+  # [description] This listing's full description
+  # [view_count] The number of times this listing has been viewed
+  # [url] The full URL to this listing's detail page
+  # [price] The price of this listing item
+  # [currency] The currency that the seller is using for this listing item
+  # [quantity] The number of items available for sale
+  # [tags] An array of tags that the seller has used for this listing
+  # [materials] Any array of materials that was used in the production of this item
+  #
+  # Additionally, the following queries on this item are available:
+  #
+  # [active?] Is this listing active?
+  # [removed?] Has this listing been removed?
+  # [sold_out?] Is this listing sold out?
+  # [expired?] Has this listing expired?
+  # [alchemy?] Is this listing an Alchemy item? (i.e. requested by an Etsy user)
+  #
+  class Listing
+    
+    include Etsy::Model
+    
+    STATES = %w(active removed sold_out expired alchemy)
+    
+    finder :all, '/shops/:user_id/listings'
+    
+    attribute :id, :from => :listing_id
+    attribute :view_count, :from => :views
+    attribute :created, :from => :creation_epoch
+    attribute :currency, :from => :currency_code
+    attribute :ending, :from => :ending_epoch
+    
+    attributes :title, :description, :state, :url, :price, :quantity, 
+               :tags, :materials
+
+    STATES.each do |state|
+      define_method "#{state}?" do
+        self.state == state.sub('_', '')
+      end
+    end
+   
+    # Time that this listing was created
+    #
+    def created_at
+      Time.at(created)
+    end
+    
+    # Time that this listing is ending (will be removed from store)
+    #
+    def ending_at
+      Time.at(ending)
+    end
+    
+    # The list of images associated with this listing.  See Etsy::Image
+    # for more information
+    #
+    def images
+      @result['all_images'].map {|image_data| Image.new(image_data) }
+    end
+    
+    # The primary image for this listing.  See Etsy::Image for more
+    # information
+    #
+    def image
+      images.first
+    end
+    
+  end
+end

data/lib/etsy/model.rb

@@ -0,0 +1,64 @@
+module Etsy
+  module Model # :nodoc:all
+    
+    module ClassMethods
+      
+      def attribute(name, options = {})
+        from = options.fetch(:from, name)
+
+        class_eval <<-CODE
+          def #{name}
+            @result['#{from}']
+          end
+        CODE
+      end
+      
+      def attributes(*names)
+        names.each {|name| attribute(name) }
+      end
+
+      def finder(type, endpoint)
+        parameter = endpoint.scan(/:\w+/).first
+        parameter.sub!(/^:/, '')
+
+        endpoint.sub!(":#{parameter}", '#{' + parameter + '}')
+
+        send("find_#{type}", parameter, endpoint)
+      end
+      
+      def find_all(parameter, endpoint)
+        class_eval <<-CODE
+          def self.find_all_by_#{parameter}(#{parameter})
+            response = Request.get("#{endpoint}")
+            response.result.map {|listing| new(listing) }
+          end
+        CODE
+      end
+      
+      def find_one(parameter, endpoint)
+        class_eval <<-CODE
+          def self.find_by_#{parameter}(#{parameter})
+            response = Request.get("#{endpoint}")
+            new response.result
+          end
+        CODE
+      end
+      
+    end
+    
+    module InstanceMethods
+      
+      def initialize(result = nil)
+        @result = result
+      end
+      
+    end
+    
+    def self.included(other)
+      other.send(:extend, Etsy::Model::ClassMethods)
+      other.send(:include, Etsy::Model::InstanceMethods)
+    end
+    
+    
+  end
+end

data/lib/etsy/request.rb

@@ -0,0 +1,48 @@
+module Etsy
+  
+  # = Request
+  # 
+  # A basic wrapper around GET requests to the Etsy JSON API
+  #
+  class Request
+    
+    # The base URL for API requests
+    def self.base_url
+      "http://beta-api.etsy.com/v1"
+    end
+    
+    # Perform a GET request for the resource with optional parameters - returns
+    # A Response object with the payload data
+    def self.get(resource_path, parameters = {})
+      request = Request.new(resource_path, parameters)
+      Response.new(request.get)
+    end
+    
+    # Create a new request for the resource with optional parameters
+    def initialize(resource_path, parameters = {})
+      @resource_path = resource_path
+      @parameters    = parameters
+    end
+
+    # Perform a GET request against the API endpoint and return the raw
+    # response data
+    def get
+      Net::HTTP.get(endpoint_uri)
+    end
+    
+    def parameters # :nodoc:
+      @parameters.merge(:api_key => Etsy.api_key, :detail_level => 'high')
+    end
+    
+    def query # :nodoc:
+      parameters.map {|k,v| "#{k}=#{v}"}.join('&')
+    end
+    
+    def endpoint_uri # :nodoc:
+      uri = URI.parse("#{self.class.base_url}#{@resource_path}")
+      uri.query = query
+      uri
+    end
+    
+  end
+end