dawanda-dawanda_client 0.1.0

data/README.rdoc

@@ -0,0 +1,72 @@
+= Dawanda
+
+== Description
+
+The Dawanda gem provides a friendly Ruby interface to the Dawanda API
+
+== Installation
+
+Installing the latest stable version is simple:
+
+    sudo gem install dawanda-dawanda_client --source=http://gems.github.com
+
+== Usage
+
+The Dawanda API is read-only - all you need to gain access is an API Key (available 
+from http://dawanda.com/apps).  Once you have your API key, set it in your script:
+
+    require 'rubygems'
+    require 'dawanda'
+    Dawanda.api_key = 'foobar'
+    Dawanda.country = 'de'
+
+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 Dawanda.user method:
+
+    >> user = Dawanda.user('meko')
+    => #<Dawanda::User:0x141bf58 @result={"name"=>"meko", "city"=>"auma", "is_seller"=>true, ...
+    >> user.name
+    => "meko"
+    >> user.id
+    => 13008
+
+For more information about what is available for a user, check out the documentation
+for Dawanda::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
+  => #<Dawanda::Shop:0x14170c0 @result={"is_vacation"=>false, "name"=>"MEKO STORE" ...
+  >> shop.name
+  => "MEKO STORE"
+  
+More information about shops can be found in the documentation for Dawanda::Shop.
+  
+== Products
+
+Shops contain multiple listings:
+
+  >> shop.products
+  => [#<Dawanda::Product:0x1405f3c @result={"price"=>{"cents"=>2500, "currency_code"=>"EUR"}, "name"=>"Harmonie", ... ]
+  >> product = shop.products.first
+  => #<Dawanda::Product:0x1405f3c @result={"price"=>{"cents"=>2500, "currency_code"=>"EUR"}, "name"=>"Harmonie", ...
+  >> product.name
+  => "Harmonie"
+  >> listing.description
+  => "Harmonie \n- Inselsymposium / Gimmlitztal \n- Eiche \n- geölt \n- L:150 / Durchmesser ca. 28cm"
+  >> listing.product_url
+  => ""http://de.dawanda.com/product/1-Harmonie""
+  >> listing.view_count
+  => 155
+  >> listing.created_at
+  => Sat Sep 16 01:35:05 +0200 2006
+
+See the documentation for Dawanda::Listing for more information.

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+task :default => :test
+
+spec = Gem::Specification.new do |s|
+  s.name             = 'dawamda'
+  s.version          = '0.1.0'
+  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 Dawanda API"
+  s.author           = 'Christoph Bünte'
+  s.email            = 'info@christophbuente.de'
+  s.homepage         = 'http://www.christophbuente.de'
+  s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib,test}/**/*")
+  # s.executables    = ['dawanda']
+  
+  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/dawanda/model.rb

@@ -0,0 +1,79 @@
+module Dawanda
+  module Model # :nodoc:all
+    
+    module ClassMethods
+      
+      def attribute(name, options = {})
+        from = parse_from(name,options)
+        if from.is_a? Array
+          class_eval <<-CODE
+            def #{name}
+              @result['#{from.first}']['#{from.last}']
+            end
+          CODE
+        else
+          class_eval <<-CODE
+            def #{name}
+              @result['#{from}']
+            end
+          CODE
+        end
+      end
+      
+      def parse_from(name,options)
+        from = options.fetch(:from,name)
+        return from unless from.is_a? Hash
+        key = from.keys.first
+        value = from.fetch(key)
+        [key,value]
+      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, Dawanda::Model::ClassMethods)
+      other.send(:include, Dawanda::Model::InstanceMethods)
+    end
+    
+    
+  end
+end

data/lib/dawanda/product.rb

@@ -0,0 +1,62 @@
+module Dawanda
+  
+  # = Listing
+  #
+  # Represents a single Dawanda product.  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 Dawanda user)
+  #
+  class Product
+    
+    include Dawanda::Model
+    
+    finder :all, '/shops/:shop_id/products'
+    finder :all, '/categories/:category_id/products'
+    
+    
+    finder :one, '/products/:product_id'
+    
+    attribute :created, :from => :created_at
+    
+    attributes :id, :name, :description, :created_at, :view_count, :tags,
+               :ending, :quantity, :materials, :price, :restful_path, :product_url, :images
+
+ 
+    # Time that this listing was created
+    #
+    def created_at
+      Time.parse(created)
+    end
+    
+    # Time that this listing is ending (will be removed from store)
+    #
+    def ending_at
+      Time.parse(ending)
+    end
+    
+    # The primary image for this listing.  See Dawanda::Image for more
+    # information
+    #
+    def image_25x25
+      images.first['image_25x25']
+    end
+    
+  end
+end

data/lib/dawanda/request.rb

@@ -0,0 +1,54 @@
+module Dawanda
+  
+  # = Request
+  # 
+  # A basic wrapper around GET requests to the Dawanda JSON API
+  #
+  class Request
+    
+    # The base URL for API requests
+    def self.base_url
+      url = "http://#{Dawanda.country}.devanda.com/api/v1"
+      puts url
+      url
+    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 = {})
+      parameters = {:format => 'json'}.update(parameters)
+      request = Request.new(resource_path, parameters)
+      puts request.inspect
+      response = Response.new(request.get)
+      puts response.inspect
+      response
+    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 => Dawanda.api_key)
+    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

data/lib/dawanda/response.rb

@@ -0,0 +1,47 @@
+module Dawanda
+  
+  # = Response
+  # 
+  # Basic wrapper around the Dawanda JSON response data
+  #
+  class Response
+    
+    # Create a new response based on the raw JSON
+    def initialize(data)
+      @data = data
+    end
+    
+    # Convert the raw JSON data to a hash
+    def to_hash
+      @hash ||= JSON.parse(@data)
+      @hash['response']
+    end
+    
+    # Number of records in the response
+    def entries
+      to_hash['entries']
+    end
+    
+    # Number of pages in the response
+    def pages
+      to_hash['pages']
+    end
+    
+    def type
+      to_hash['type']
+    end
+    
+    def pluralized_type
+      type.to_s.pluralize
+    end
+    
+    def params
+      to_hash['params']
+    end
+    # Results of the API request
+    def result
+      entries == 1 ? to_hash['result'][type] : to_hash['result'].values.first
+    end
+    
+  end
+end

data/lib/dawanda/shop.rb

@@ -0,0 +1,52 @@
+module Dawanda
+  
+  # = Shop
+  #
+  # Represents a single Dawanda shop.  Users may or may not have an associated shop - 
+  # check the result of User#seller? to find out.
+  #
+  # A shop has the following attributes:
+  #
+  # [name] The shop's name
+  # [title] A brief heading for the shop's main page
+  # [announcement] An announcement to buyers (displays on the shop's home page)
+  # [message] The message sent to users who buy from this shop
+  # [banner_image_url] The full URL to the shops's banner image
+  # [listing_count] The total number of active listings contained in this shop
+  #
+  class Shop
+    
+    include Dawanda::Model
+
+    finder :one, '/shops/:user_id'
+    
+    attribute :updated, :from => :updated_at
+    attribute :created, :from => :created_at
+    attribute :user_id, :from => {:user => :id }
+
+    attributes :banner_image_url, :listing_count, :title, :announcement, :name
+   
+    # Time that this shop was created
+    #
+    def created_at
+      Time.parse(created)
+    end
+    
+    # Time that this shop was last updated
+    #
+    def updated_at
+      Time.parse(updated)
+    end
+    
+    # A collection of listings in this user's shop. See Dawanda::Listing for
+    # more information
+    #
+    def products
+      @products ||= Product.find_all_by_shop_id(user_id.to_s)
+    end
+    
+    def user
+      @user ||= User.find_by_user_id(user_id)
+    end
+  end
+end

data/lib/dawanda/user.rb

@@ -0,0 +1,53 @@
+module Dawanda
+  
+  # = User
+  #
+  # Represents a single Dawanda user - has the following attributes:
+  #
+  # [id] The unique identifier for this user
+  # [name] This user's username
+  # [city] The user's city / state (optional)
+  # [sex] The user's gender
+  # [transaction_sold_count] How many products have been sold by this user
+  # [is_seller] Is this user a seller?
+  # [bio] User's biography
+  # [restful_path]
+  # [url] The full URL to this user's profile page / shop (if seller)
+  #
+  class User
+    
+    include Dawanda::Model
+    
+    finder :one, '/users/:user_id'
+    
+    # attribute :last_login, :from => :last_login_epoch
+
+    attributes :id, :name, :url, :city, :sex, :bio, :transaction_sold_count, :is_seller, :images
+    
+    # This user's shop, returns nil if user is not a seller. See Dawanda::Shop
+    # for more information.
+    #
+    def shop
+      @shop ||= Shop.find_by_user_id(id) if seller?
+    end
+    
+    # Is this user a seller?
+    #
+    def seller?
+      is_seller
+    end
+    
+    def image_40x40
+      images.first['image_40x40']
+    end
+    
+    def image_80x80
+      images.first['image_80x80']
+    end
+    
+    def image_170x
+      images.first['image_170x']
+    end
+    
+  end
+end

data/lib/dawanda.rb

@@ -0,0 +1,88 @@
+$:.unshift File.dirname(__FILE__)
+
+require 'net/http'
+require 'json'
+require 'time'
+
+require 'dawanda/request'
+require 'dawanda/response'
+
+require 'dawanda/model'
+require 'dawanda/user'
+require 'dawanda/shop'
+require 'dawanda/product'
+require 'dawanda/category'
+
+# = DaWanda Client: A friendly Ruby interface to the DaWanda API
+#
+# == Quick Start
+# 
+# Getting started is easy.  First, you will need a valid API key from the Dawanda 
+# developer site (http://developer.dawanda.com/).  Since the API is read-only at
+# the moment, that's all you need to do.
+# 
+# To start using the API, require the dawanda gem and set it up to use your API key:
+# 
+#     require 'rubygems'
+#     require 'dawanda_client'
+#     
+#     Dawanda.api_key = 'itsasecret'
+#     
+# Now you can make API calls that originate from an Dawanda user:
+# 
+#     # Find a user by username
+#     user = Dawanda.user('littletjane')
+#     
+#     # Grab that user's shop information
+#     user.seller?
+#     user.shop
+#     user.shop.title
+#     
+#     # ... and the listings in the shop
+#     product = user.shop.products.first
+#     product.title
+#     product.description
+#     
+# To see what else is available for a user, check out the full documentation for
+# the Dawanda::User class.
+#
+module Dawanda
+ 
+  # 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
+  
+  # Set the country for all requests
+  def self.country=(country)
+    @country = country
+  end
+  
+  # Retrieve the country
+  def self.country
+    @country || 'de'
+  end
+  
+  # Find a user by username.  See Dawanda::User for more information.
+  def self.user(username)
+    User.find_by_user_id(username)
+  end
+  
+  def self.shop(username)
+    Shop.find_by_user_id(username)
+  end
+  
+  def self.product(product_id)
+    Product.find_by_product_id(product_id)
+  end
+  
+  def self.category(category_id)
+    Category.find_by_category_id(category_id)
+  end
+  
+end

data/test/fixtures/getShopDetails.json

@@ -0,0 +1,67 @@
+{
+    "count": 1,
+    "results": [{
+        "user_name": "littletjane",
+        "user_id": 5327518,
+        "url": "http:\/\/de.dawanda.com\/shops/5327518",
+        "image_url_25x25": "http:\/\/img.dawanda.com\/User/806\/806038\/full\/5874999.jpg",
+        "join_epoch": 1191381757.93,
+        "city": "Washington, DC",
+        "gender": "female",
+        "lat": null,
+        "lon": null,
+        "transaction_buy_count": 199,
+        "transaction_sold_count": 0,
+        "is_seller": true,
+        "was_featured_seller": false,
+        "materials": ["paper", "pen_and_pencil", "crayon_and_coloring_books", "ink_and_stamps", "collage", "decoupage_medium", "paint_and_canvas", "stickers", "magnets", "fabric_and_plush", "toys", "vintage_and_found_objects", "ecofriendly_and_recycled_goods"],
+        "last_login_epoch": 1239797927.39,
+        "feedback_count": "171",
+        "feedback_percent_positive": "100",
+        "referred_user_count": 1,
+        "birth_day": "20",
+        "birth_month": "3",
+        "bio": "hello! :D \r\n\r\n:about me:\r\n\r\nBA, dance \r\ncertified massage therapist\r\nwife & stay-at-home mama to 3 little ones\r\n\r\n:love love love:\r\n\r\nmy family\r\nmy children's drawings\r\nmy dear friends\r\nmusic \r\ndance!\r\nyoga\r\narts & craftiness!\r\nbaking\r\nmy mac\r\ndreaming\r\nlaughing\r\nplaying\r\nreading\r\ncute happy things\r\n=^..^=\r\n\r\nhttp:\/\/littletjane.com\r\nplease say hi!\r\n\r\ni'm flip...hip...zappy zowie zip!",
+        "banner_image_url": "http:\/\/img.dawanda.com\/Shop/806\/806038\/full\/5874999.jpg",
+        "last_updated_epoch": 1239717723.36,
+        "creation_epoch": 1237430331.15,
+        "listing_count": 13,
+        "shop_name": "littletjane",
+        "title": "title text",
+        "sale_message": "message text",
+        "announcement": "announcement text",
+        "is_vacation": "",
+        "vacation_message": "",
+        "currency_code": "USD",
+        "policy_welcome": "oh hi! i'm so glad you've come by my shop! thank you so much for swinging in and taking a peek around :D\r\n\r\nwell, here are the 'ol policy-os. please do read carefully:",
+        "policy_payment": "payment method accepted: \r\npaypal (hooray!)\r\n\r\nterms: \r\nsubmit payment promptly. payment is due 3 days after purchase of the item. \r\n\r\nupon receipt of payment, the order will be shipped within 1 week.",
+        "policy_shipping": "method: usps first-class mail.\r\n \r\nplease feel free to contact me for rates on expedited shipping. \r\n\r\ni am not responsible for taxes or duties for your country.",
+        "policy_refunds": "oh help!\r\nif you are not happy with your item, please let me know. we can work this out! i will try my best to replace the item or refund your money, as the goal of my shop is to create and share in crafty happiness. right on!",
+        "policy_additional": "ok. well, that's about it! mostly, just be good, nice, honest, and fair, and this will return to you tenfold.\r\n\r\nif you have any questions, please don't hesitate to ask me.\r\n\r\nthanks a bunch, you! cheers!",
+        "sections": [{
+            "section_id": 6008529,
+            "title": "matchboxes",
+            "listing_count": 3
+        },
+        {
+            "section_id": 6008530,
+            "title": "original paintings",
+            "listing_count": 3
+        },
+        {
+            "section_id": 6059955,
+            "title": "sachets",
+            "listing_count": 5
+        },
+        {
+            "section_id": 6061498,
+            "title": "hand carved stamps",
+            "listing_count": 2
+        }]
+    }],
+    "params": {
+        "user_id": 5327518,
+        "detail_level": "high"
+    },
+    "type": "shop"
+}

data/test/test_helper.rb

@@ -0,0 +1,49 @@
+# http://sneaq.net/textmate-wtf
+$:.reject! { |e| e.include? 'TextMate' }
+
+require 'rubygems'
+require 'throat_punch'
+
+require File.dirname(__FILE__) + '/../lib/dawanda'
+
+class Test::Unit::TestCase
+
+  def self.read_fixture(method_name)
+    file = File.dirname(__FILE__) + "/fixtures/#{method_name}.json"
+    JSON.parse(File.read(file))['results']
+  end
+
+  def read_fixture(method_name)
+    self.class.read_fixture(method_name)
+  end
+
+  def mock_request_cycle(options)
+    response = Dawanda::Response.new(stub())
+
+    data = read_fixture(options[:data])
+    data = data.first if data.size == 1
+
+    response.stubs(:result).with().returns(data)
+
+    Dawanda::Request.stubs(:get).with(options[:for]).returns(response)
+
+    response
+  end
+
+  def self.when_populating(klass, options, &block)
+    data = options[:from].is_a?(String) ? read_fixture(options[:from])[0] : options[:from].call
+
+    context "with data populated for #{klass}" do
+      setup { @object = klass.new(data) }
+      merge_block(&block)
+    end
+
+  end
+
+  def self.value_for(method_name, options)
+    should "have a value for :#{method_name}" do
+      @object.send(method_name).should == options[:is]
+    end
+  end
+
+end

data/test/unit/dawanda/shop_test.rb

@@ -0,0 +1,63 @@
+require File.dirname(__FILE__) + '/../../test_helper'
+
+module Dawanda
+  class ShopTest < Test::Unit::TestCase
+
+    context "The Shop class" do
+
+      should "be able to find a shop by :user_id" do
+        user_id  = 5327518
+        response = mock_request_cycle :for => "/shops/#{user_id}", :data => 'getShopDetails'
+
+        Shop.expects(:new).with(response.result).returns('shop')
+
+        Shop.find_by_user_id(user_id).should == 'shop'
+      end
+
+    end
+
+    context "An instance of the Shop class" do
+
+      when_populating Shop, :from => 'getShopDetails' do
+
+        value_for :user_id,           :is => 5327518
+        value_for :banner_image_url,  :is => "http://img.dawanda.com/Shop/806/806038/full/5874999.jpg",
+        value_for :products_count,     :is => 13
+        value_for :updated_at,        :is => 1239717723.36
+        value_for :created_at,        :is => 1237430331.15
+        value_for :name,              :is => 'littletjane'
+        value_for :title,             :is => 'title text'
+        value_for :message,           :is => 'message text'
+        value_for :announcement,      :is => 'announcement text'
+
+      end
+      
+      should "know the creation date" do
+        shop = Shop.new
+        shop.stubs(:created_at).with().returns(Time.at(1237430331.15))
+        
+        shop.created_at.should == Time.at(1237430331.15)
+      end
+      
+      should "know the update date" do
+        shop = Shop.new
+        shop.stubs(:updated_at).with().returns(Time.at(1239717723.36))
+        
+        shop.updated_at.should == Time.at(1239717723.36)
+      end
+      
+      should "have a collection of products" do
+        user_id = 123
+        
+        shop = Shop.new
+        shop.expects(:user_id).with().returns(user_id)
+        
+        Product.expects(:find_all_by_user_id).with(user_id).returns('products')
+        
+        shop.products.should == 'products'
+      end
+
+    end
+
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification 
+name: dawanda-dawanda_client
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- "Christoph B\xC3\xBCnte"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-17 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.1.0
+    version: 
+description: 
+email: info@christophbuente.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- lib/dawanda
+- lib/dawanda/product.rb
+- lib/dawanda/model.rb
+- lib/dawanda/request.rb
+- lib/dawanda/response.rb
+- lib/dawanda/shop.rb
+- lib/dawanda/user.rb
+- lib/dawanda.rb
+- test/fixtures
+- test/fixtures/getShopDetails.json
+- test/test_helper.rb
+- test/unit
+- test/unit/dawanda
+- test/unit/dawanda/shop_test.rb
+has_rdoc: true
+homepage: http://sneaq.net
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: Provides a friendly ruby-like interface to the DaWanda API
+test_files: []
+