etsy 0.1.0 → 0.2.0

data/README.rdoc

@@ -8,35 +8,103 @@ The Etsy gem provides a friendly Ruby interface to the Etsy API
 
 Installing the latest stable version is simple:
 
-    sudo gem install etsy
+    $ 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
+    $ git clone git://github.com/reagent/etsy.git
+    $ cd etsy
+    $ rake gem && gem install pkg/etsy-<version>.gem
 
 == 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:
+=== Read-Only Mode
+
+The Etsy API has two modes: read-only, and read-write. Read-only mode only requires an
+API key (available from http://developer.etsy.com):
 
     require 'rubygems'
     require 'etsy'
+
     Etsy.api_key = 'foobar'
 
-From there, you can make any calls to the API that you need.
+From there, you can make any non-authenticated calls to the API that you need.
+
+== Authenticated Calls
+
+The Etsy API has support for both retrieval of extended information and write
+support for authenticated users.  Authentication can either be performed from
+the console or from within a Ruby web application.
+
+=== Console
+
+For simple authentication from the console, configure the necessary parameters:
+
+  require 'rubygems'
+  require 'etsy'
+
+  Etsy.api_key = 'key'
+  Etsy.api_secret = 'secret'
+  Etsy.access_mode = :read_write
+
+From there, you will need to paste the verification URL into a browser:
+
+  Etsy.verification_url
+
+Once you have allowed access, you can now generate an access token by supplying
+the verifier displayed on the Etsy site:
+
+  request = Etsy.request_token
+  access  = Etsy.access_token(request.token, request.secret, 'abc123')
+
+Authenticated calls can now be made by passing an access token and secret:
+
+Etsy.myself(access.token, access.secret)
+
+=== Web Application
+
+The process for authenticating via a web application is similar, but requires the
+configuration of a callback URL:
+
+  require 'rubygems'
+  require 'etsy'
+
+  Etsy.api_key = 'key'
+  Etsy.api_secret = 'secret'
+  Etsy.access_mode = :read_write
+  Etsy.callback_url = 'http://localhost:4567/authorize'
+
+In this mode, you'll need to store the request token and secret before redirecting
+to the verification URL.  A simple example using Sinatra:
+
+  enable :sessions
+
+  get '/' do
+    session[:request_token]  = Etsy.request_token.token
+    session[:request_secret] = Etsy.request_token.secret
+    redirect Etsy.verification_url
+  end
+
+  get '/authorize' do
+    access_token = Etsy.access_token(
+      session[:request_token],
+      session[:request_secret],
+      params[:oauth_verifier]
+    )
+
+    # access_token.token and access_token.secret can now be saved for future API calls
+  end
 
 === 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", ... > 
+    => #<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.
@@ -46,17 +114,15 @@ for Etsy::User.
 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:
@@ -85,23 +151,40 @@ 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"
+  >> listing.images.first.square
+  => "http://ny-image0.etsy.com/il_75x75.189111072.jpg"
+  >> listing.images.first.full
+  => "http://ny-image0.etsy.com/il_fullxfull.189111072.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"
+  >> listing.image.full
+  => "http://ny-image0.etsy.com/il_fullxfull.189111072.jpg"
 
 More information is available in the documentation for Etsy::Image.
 
+== Contributing
+
+I have a "commit bit" policy for contributions to this repository. Once I accept
+your patch, I will give you full commit access.  To submit patches:
+
+1. Fork this repository
+2. Implement the desired feature with tests (and documentation if necessary)
+3. Send me a pull request
+
+I ask that you not submit patches that include changes to the version or gemspec.
+
+== Contributors
+
+These people have helped make the Etsy gem what it is today:
+
+* {Katrina Owen}[http://github.com/kowen]
+
 == License
 
-Copyright (c) 2009 Patrick Reagan (reaganpr@gmail.com)
+Copyright (c) 2009 - 2010 Patrick Reagan (reaganpr@gmail.com)
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/Rakefile

@@ -17,9 +17,9 @@ spec = Gem::Specification.new do |s|
   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')
+
+  s.add_dependency('json', '~> 1.4.0')
+  s.add_dependency('oauth', '~> 0.4.0')
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|
@@ -32,8 +32,8 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
-desc 'Generate the gemspec to serve this Gem from Github'
-task :github do
+desc 'Generate the gemspec for this Gem'
+task :gemspec do
   file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
   File.open(file, 'w') {|f| f << spec.to_ruby }
   puts "Created gemspec: #{file}"

data/lib/etsy.rb

@@ -2,10 +2,15 @@ $:.unshift File.dirname(__FILE__)
 
 require 'net/http'
 require 'json'
+require 'oauth'
 
 require 'etsy/request'
 require 'etsy/response'
 
+require 'etsy/basic_client'
+require 'etsy/secure_client'
+require 'etsy/verification_request'
+
 require 'etsy/model'
 require 'etsy/user'
 require 'etsy/shop'
@@ -15,51 +20,124 @@ 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.
-# 
+#
+# Getting started is easy. First, you will need a valid API key from the Etsy
+# developer site (http://developer.etsy.com/).
+#
 # 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.
+# the Etsy::User class. Information about making authenticated calls is available
+# in the README.
 #
 module Etsy
- 
-  # Set the API key for all requests
-  def self.api_key=(api_key)
-    @api_key = api_key
+  class Error < RuntimeError; end
+
+  class << self
+    attr_accessor :api_key, :api_secret
+    attr_writer :callback_url
+  end
+
+  # Set the environment, accepts either :sandbox or :production. Defaults to :sandbox
+  # and will raise an exception when set to an unrecognized environment.
+  #
+  def self.environment=(environment)
+    unless [:sandbox, :production].include?(environment)
+      raise(ArgumentError, "environment must be set to either :sandbox or :production")
+    end
+    @environment = environment
+  end
+
+  # The currently configured environment.
+  #
+  def self.environment
+    @environment || :sandbox
+  end
+
+  # Set the access mode, can either be :read_only or :read_write.  Defaults to :read_only
+  # and will raise an exception when set to an invalid value.
+  #
+  def self.access_mode=(mode)
+    unless [:read_only, :read_write].include?(mode)
+      raise(ArgumentError, "access mode must be set to either :read_only or :read_write")
+    end
+    @access_mode = mode
+  end
+
+  # The currently configured access mode
+  #
+  def self.access_mode
+    @access_mode || :read_only
   end
-  
-  # Retrieve the API key
-  def self.api_key
-    @api_key
+
+  # The configured callback URL or 'oob' if no callback URL is configured. This controls
+  # whether or not we need to pass the OAuth verifier by hand.
+  #
+  def self.callback_url
+    @callback_url || 'oob'
   end
-  
+
   # Find a user by username.  See Etsy::User for more information.
+  #
   def self.user(username)
-    User.find_by_username(username)
+    User.find(username)
+  end
+
+  # Convenience method for accessing the authenticated user's own user information. Requires
+  # authentication.
+  #
+  def self.myself(token, secret)
+    User.myself(token, secret)
+  end
+
+  # Generate a request token for authorization.
+  #
+  def self.request_token
+    verification_request.request_token
+  end
+
+  # Generate an access token from the request token, secret, and verifier. The verifier can
+  # either be passed manually or from the params in the callback URL.
+  #
+  def self.access_token(request_token, request_secret, verifier)
+    @access_token ||= begin
+      client = Etsy::SecureClient.new({
+        :request_token  => request_token,
+        :request_secret => request_secret,
+        :verifier       => verifier
+      })
+      client.client
+    end
+  end
+
+  # Generate the URL to begin the verification process for a user.
+  #
+  def self.verification_url
+    verification_request.url
+  end
+
+  private
+
+  def self.verification_request
+    @verification_request ||= VerificationRequest.new
   end
-  
-end
+end

data/lib/etsy/basic_client.rb

@@ -0,0 +1,26 @@
+module Etsy
+
+  # = BasicClient
+  #
+  # Used for calling public API methods.
+  #
+  class BasicClient
+
+    # Create a new client that will connect to the specified host
+    #
+    def initialize(host)
+      @host = host
+    end
+
+    def client # :nodoc:
+      @client ||= Net::HTTP.new(@host)
+    end
+
+    # Fetch a raw response from the specified endpoint
+    #
+    def get(endpoint)
+      client.get(endpoint)
+    end
+
+  end
+end

data/lib/etsy/image.rb

@@ -1,27 +1,30 @@
 module Etsy
-  
+
   # = Image
   #
-  # Represents an image resource of an Etsy listing and contains multiple sizes. 
+  # 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)
+  # [square] The square image thumbnail (75x75 pixels)
+  # [small] The small image thumbnail (170x135 pixels)
+  # [thumbnail] The thumbnail for the image, no more than 570px wide
+  # [full] The full image for this listing, no more than 1500px wide
   #
   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
+
+    attribute :square, :from => :url_75x75
+    attribute :small, :from => :url_170x135
+    attribute :thumbnail, :from => :url_570xN
+    attribute :full, :from => :url_fullxfull
+
+    # Fetch all images for a given listing.
+    #
+    def self.find_all_by_listing_id(listing_id)
+      response = Request.get("/listings/#{listing_id}/images")
+      [response.result].flatten.map {|data| new(data) }
+    end
 
   end
 end

data/lib/etsy/listing.rb

@@ -1,5 +1,5 @@
 module Etsy
-  
+
   # = Listing
   #
   # Represents a single Etsy listing.  Has the following attributes:
@@ -24,53 +24,56 @@ module Etsy
   # [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 :created, :from => :creation_tsz
     attribute :currency, :from => :currency_code
-    attribute :ending, :from => :ending_epoch
-    
-    attributes :title, :description, :state, :url, :price, :quantity, 
+    attribute :ending, :from => :ending_tsz
+
+    attributes :title, :description, :state, :url, :price, :quantity,
                :tags, :materials
 
+    # Retrieve all active listings for a given shop. Pulls back the first 25 listings.
+    #
+    def self.find_all_by_shop_id(shop_id)
+      response = Request.get("/shops/#{shop_id}/listings/active")
+      [response.result].flatten.map {|data| new(data) }
+    end
+
+    # The collection of images associated with this listing.
+    #
+    def images
+      @images ||= Image.find_all_by_listing_id(id)
+    end
+
+    # The primary image for this listing.
+    #
+    def image
+      images.first
+    end
+
     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