tailored-etsy 0.2.2

data/lib/etsy/address.rb

@@ -0,0 +1,47 @@
+module Etsy
+
+  # = Address
+  #
+  # Represents a single Etsy Address.  Users may or may not have associated addresses.
+  #
+  # An address has the following attributes:
+  #
+  # [first_line] Street address
+  # [second_line] Additional street information.
+  # [city]
+  # [state]
+  # [country]
+  # [country_id] The Etsy country id
+  #
+  class Address
+
+    include Etsy::Model
+
+    attributes :name, :first_line, :second_line, :city, :state, :zip, :country_id
+
+    attribute :id, :from => :user_address_id
+    attribute :country, :from => :country_name
+
+    # Retrieve all of a user's addresses by user name or ID:
+    #
+    #   Etsy::Address.find('reagent')
+    #
+    def self.find(*identifiers_and_options)
+      self.append_to_endpoint('addresses', identifiers_and_options)
+      self.find_one_or_more('users', identifiers_and_options)
+    end
+
+    private
+    def oauth
+      oauth = (token && secret) ? {:access_token => token, :access_secret => secret} : {}
+    end
+
+    def self.append_to_endpoint(suffix, arguments)
+      if arguments.last.class == Hash
+        arguments.last[:append_to_endpoint] = suffix
+      else
+        arguments << {:append_to_endpoint => suffix}
+      end
+    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/category.rb

@@ -0,0 +1,84 @@
+module Etsy
+
+  # = Category
+  #
+  # A category of listings for sale, formed from 1 to 3 tags.
+  #
+  # A category has the following attributes:
+  #
+  # [page_description] A short description of the category from the category's landing page
+  # [page_title] The title of the category's landing page
+  # [category_name] The category's string ID
+  # [short_name] A short display name for the category
+  # [long_name] A longer display name for the category
+  # [children_count] The number of subcategories below this one
+  #
+  class Category
+
+    include Etsy::Model
+
+    attribute :id, :from => :category_id
+    attribute :children_count, :from => :num_children
+    attributes :page_description, :page_title, :category_name, :short_name,
+               :long_name
+
+    # Retrieve one or more top-level categories by name:
+    #
+    #   Etsy::Category.find('accessories')
+    #
+    # You can find multiple top-level categories by passing an array of identifiers:
+    #
+    #   Etsy::Category.find(['accessories', 'art'])
+    #
+    def self.find_top(*identifiers_and_options)
+      self.find_one_or_more('categories', identifiers_and_options)
+    end
+
+    # Retrieve a list of all subcategories of the specified category.
+    #
+    #   Etsy::Category.find_all_subcategories('accessories')
+    #
+    # You can also find the subcategories of a subcategory.
+    #
+    #   Etsy::Category.find_all_subcategories('accessories/apron')
+    #
+    # Etsy categories only go three levels deep, so this will return nil past the third level.
+    #
+    #   Etsy::Category.find_all_subcategories('accessories/apron/women')
+    #   => nil
+    #
+    def self.find_all_subcategories(category, options = {})
+      valid?(category) ? self.get_all("/taxonomy/categories/#{category}", options) : nil
+    end
+
+    def self.find(tag)
+      get("/categories/#{tag}")
+    end
+
+    # Retrieve a list of all top-level categories.
+    #
+    #   Etsy::Category.all
+    #
+    def self.all_top(options = {})
+      self.get_all("/taxonomy/categories", options)
+    end
+
+    # The collection of active listings associated with this category.
+    #
+    def active_listings
+      @active_listings ||= Listing.find_all_active_by_category(category_name)
+    end
+
+    # The collection of subcategories associated with this category.
+    #
+    def subcategories
+      @subcategories ||= Category.find_all_subcategories(category_name)
+    end
+
+    private
+
+    def self.valid?(parent_category)
+      parent_category.count("/") < 2
+    end
+  end
+end

data/lib/etsy/country.rb

@@ -0,0 +1,27 @@
+module Etsy
+  class Country
+    include Etsy::Model
+
+    attribute :id, :from => :country_id
+    attributes :iso_country_code, :world_bank_country_code
+    attributes :name, :slug, :lat, :lon
+
+    def self.find_all
+      get("/countries")
+    end
+
+    def self.find(id)
+      get("/countries/#{id}")
+    end
+
+    def self.find_by_alpha2(alpha2)
+      alpha2 = alpha2.upcase
+      find_all.detect { |country| country.iso_country_code == alpha2}
+    end
+
+    def self.find_by_world_bank_country_code(world_bank_country_code)
+      world_bank_country_code = world_bank_country_code.upcase
+      find_all.detect { |country| country.world_bank_country_code == world_bank_country_code}
+    end
+  end
+end

data/lib/etsy/image.rb

@@ -0,0 +1,34 @@
+module Etsy
+
+  # = Image
+  #
+  # Represents an image resource of an Etsy listing and contains multiple sizes.
+  # Sizes available are:
+  #
+  # [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 :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)
+      get_all("/listings/#{listing_id}/images")
+    end
+
+    def self.create(listing, image_path, options = {})
+      options[:image] = File.new(image_path)
+      options[:multipart] = true
+      post("/listings/#{listing.id}/images", options)
+    end
+  end
+end

data/lib/etsy/listing.rb

@@ -0,0 +1,178 @@
+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
+  # [state] The current state of the item
+  # [hue] The hue of the listing's primary image (HSV color).
+  # [saturation] The saturation of the listing's primary image (HSV color).
+  # [brightness] The value of the listing's primary image (HSV color).
+  # [black_and_white?] True if the listing's primary image is in black & white.
+  #
+  # 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)
+    VALID_STATES = [:active, :expired, :inactive, :sold, :featured]
+
+    attribute :id, :from => :listing_id
+    attribute :view_count, :from => :views
+    attribute :created, :from => :creation_tsz
+    attribute :modified, :from => :last_modified_tsz
+    attribute :currency, :from => :currency_code
+    attribute :ending, :from => :ending_tsz
+
+    attributes :title, :description, :state, :url, :price, :quantity,
+               :tags, :materials, :hue, :saturation, :brightness, :is_black_and_white
+
+    association :image, :from => 'Images'
+
+    def self.create(options = {})
+      options.merge!(:require_secure => true)
+      post("/listings", options)
+    end
+
+    def self.update(listing, options = {})
+      options.merge!(:require_secure => true)
+      put("/listings/#{listing.id}", options)
+    end
+
+    # Retrieve one or more listings by ID:
+    #
+    #   Etsy::Listing.find(123)
+    #
+    # You can find multiple listings by passing an array of identifiers:
+    #
+    #   Etsy::Listing.find([123, 456])
+    #
+    def self.find(*identifiers_and_options)
+      find_one_or_more('listings', identifiers_and_options)
+    end
+
+    # Retrieve listings for a given shop.
+    # By default, pulls back the first 25 active listings.
+    # Defaults can be overridden using :limit, :offset, and :state
+    #
+    # Available states are :active, :expired, :inactive, :sold, and :featured
+    # where :featured is a subset of the others.
+    #
+    # options = {
+    #   :state => :expired,
+    #   :limit => 100,
+    #   :offset => 100,
+    #   :token => 'toke',
+    #   :secret => 'secret'
+    # }
+    # Etsy::Listing.find_all_by_shop_id(123, options)
+    #
+    def self.find_all_by_shop_id(shop_id, options = {})
+      state = options.delete(:state) || :active
+
+      raise(ArgumentError, self.invalid_state_message(state)) unless valid?(state)
+
+      if state == :sold
+        sold_listings(shop_id, options)
+      else
+        get_all("/shops/#{shop_id}/listings/#{state}", options)
+      end
+    end
+
+    # Retrieve active listings for a given category.
+    # By default, pulls back the first 25 active listings.
+    # Defaults can be overridden using :limit, :offset, and :state
+    #
+    # options = {
+    #   :limit => 25,
+    #   :offset => 100,
+    #   :token => 'toke',
+    #   :secret => 'secret'
+    # }
+    # Etsy::Listing.find_all_active_by_category("accessories", options)
+    #
+    def self.find_all_active_by_category(category, options = {})
+      options[:category] = category
+      get_all("/listings/active", options)
+    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
+
+    def black_and_white?
+      is_black_and_white
+    end
+
+    STATES.each do |method_name|
+      define_method "#{method_name}?" do
+        state == method_name.sub('_', '')
+      end
+    end
+
+    # Time that this listing was created
+    #
+    def created_at
+      Time.at(created)
+    end
+
+    # Time that this listing was last modified
+    #
+    def modified_at
+      Time.at(modified)
+    end
+
+    # Time that this listing is ending (will be removed from store)
+    #
+    def ending_at
+      Time.at(ending)
+    end
+
+    private
+
+    def self.valid?(state)
+      VALID_STATES.include?(state)
+    end
+
+    def self.invalid_state_message(state)
+      "The state '#{state}' is invalid. Must be one of #{VALID_STATES.join(', ')}"
+    end
+
+    def self.sold_listings(shop_id, options = {})
+      includes = options.delete(:includes)
+
+      transactions = Transaction.find_all_by_shop_id(shop_id, options)
+      listing_ids  = transactions.map {|t| t.listing_id }.uniq
+
+      options = options.merge(:includes => includes) if includes
+      (listing_ids.size > 0) ? Array(find(listing_ids, options)) : []
+    end
+
+  end
+end

data/lib/etsy/model.rb

@@ -0,0 +1,123 @@
+module Etsy
+  module Model # :nodoc:all
+
+    module ClassMethods
+
+      def attribute(name, options = {})
+        define_method name do
+          @result[options.fetch(:from, name).to_s]
+        end
+      end
+
+      def attributes(*names)
+        names.each {|name| attribute(name) }
+      end
+
+      # FIXME: not quite sure where I'm going with this yet. KO.
+      def association(name, options = {})
+        define_method "associated_#{name}" do
+          @result[options.fetch(:from, name).to_s]
+        end
+      end
+
+      def get(endpoint, options = {})
+        objects = get_all(endpoint, options)
+        if objects.length == 0
+          nil
+        elsif objects.length == 1
+          objects[0]
+        else
+          objects
+        end
+      end
+
+      def get_all(endpoint, options={})
+        limit = options[:limit]
+
+        if limit
+          initial_offset = options.fetch(:offset, 0)
+          batch_size = options.fetch(:batch_size, 100)
+
+          result = []
+
+          if limit == :all
+            response = Request.get(endpoint, options.merge(:limit => batch_size, :offset => initial_offset))
+            result << response.result
+            limit = [response.count - batch_size - initial_offset, 0].max
+            initial_offset += batch_size
+          end
+
+          num_batches = limit / batch_size
+
+          num_batches.times do |batch|
+            total_offset = initial_offset + batch * batch_size
+            response = Request.get(endpoint, options.merge(:limit => batch_size, :offset => total_offset))
+            result << response.result
+          end
+
+          remainder = limit % batch_size
+
+          if remainder > 0
+            total_offset = initial_offset + num_batches * batch_size
+            response = Request.get(endpoint, options.merge(:limit => remainder, :offset => total_offset))
+            result << response.result
+          end
+        else
+          response = Request.get(endpoint, options)
+          result = response.result
+        end
+
+        [result].flatten.map do |data|
+          if options[:access_token] && options[:access_secret]
+            new(data, options[:access_token], options[:access_secret])
+          else
+            new(data)
+          end
+        end
+      end
+
+      def post(endpoint, options={})
+        Request.post(endpoint, options)
+      end
+
+      def put(endpoint, options={})
+        Request.put(endpoint, options)
+      end
+
+      def find_one_or_more(endpoint, identifiers_and_options)
+        options = options_from(identifiers_and_options)
+        append = options.delete(:append_to_endpoint)
+        append = append.nil? ? "" : "/#{append}"
+        identifiers = identifiers_and_options
+        get("/#{endpoint}/#{identifiers.join(',')}#{append}", options)
+      end
+
+      def options_from(argument)
+        (argument.last.class == Hash) ? argument.pop : {}
+      end
+
+    end
+
+    def initialize(result = nil, token = nil, secret = nil)
+      @result = result
+      @token = token
+      @secret = secret
+    end
+
+    def token
+      @token
+    end
+
+    def secret
+      @secret
+    end
+
+    def result
+      @result
+    end
+
+    def self.included(other)
+      other.extend ClassMethods
+    end
+  end
+end