asin 0.0.5 → 0.0.6

Sign up to get free protection for your applications and to get access to all the features.
Files changed (4) hide show
  1. data/lib/asin.rb +74 -1
  2. data/readme.textile +15 -3
  3. data/test/test_asin.rb +14 -6
  4. metadata +13 -12
data/lib/asin.rb CHANGED
@@ -4,8 +4,53 @@ require 'crack/xml'
4
4
  require 'cgi'
5
5
  require 'base64'
6
6
 
7
+ # ASIN (Amazon Simple INterface) is a gem for easy access of the Amazon E-Commerce-API.
8
+ # It is simple to configure and use. Since it's very small and flexible, it is easy to extend it to your needs.
9
+ #
10
+ # Author:: Peter Schröder (mailto:phoetmail@googlemail.com)
11
+ #
12
+ # ==Usage
13
+ #
14
+ # The ASIN module is designed as a mixin.
15
+ #
16
+ # require 'asin'
17
+ # include ASIN
18
+ #
19
+ # In order to use the Amazon API properly, you need to be a registered user (http://aws.amazon.com).
20
+ #
21
+ # The registration process will give you a +secret-key+ and an +access-key+ (AWSAccessKeyId).
22
+ #
23
+ # Both are needed to use ASIN:
24
+ #
25
+ # configure :secret => 'your-secret', :key => 'your-key'
26
+ #
27
+ # After configuring your environment you can call the +lookup+ method to retrieve an +Item+ via the Amazon Standard Identification Number (ASIN):
28
+ #
29
+ # item = lookup '1430218150'
30
+ # item.title
31
+ # => "Learn Objective-C on the Mac (Learn Series)"
32
+ #
33
+ # The +Item+ uses a Hashie::Mash as its internal data representation and you can get fetched data from it:
34
+ #
35
+ # item.raw.ItemAttributes.ListPrice.FormattedPrice
36
+ # => "$39.99"
37
+ #
38
+ # ==Further Configuration
39
+ #
40
+ # If you need more controll over the request that is sent to the Amazon API (http://docs.amazonwebservices.com/AWSEcommerceService/4-0/),
41
+ # you can override some defaults or add additional query-parameters to the REST calls:
42
+ #
43
+ # configure :host => 'webservices.amazon.de'
44
+ # lookup(asin, :ResponseGroup => :Medium)
45
+ #
7
46
  module ASIN
8
47
 
48
+ # =Item
49
+ #
50
+ # The +Item+ class is a wrapper for the Amazon XML-REST-Response.
51
+ #
52
+ # A Hashie::Mash is used for the internal data representation and can be accessed over the +raw+ attribute.
53
+ #
9
54
  class Item
10
55
 
11
56
  attr_reader :raw
@@ -20,6 +65,18 @@ module ASIN
20
65
 
21
66
  end
22
67
 
68
+ # Configures the basic request parameters for ASIN.
69
+ #
70
+ # Expects at least +secret+ and +key+ for the API call:
71
+ #
72
+ # configure :secret => 'your-secret', :key => 'your-key'
73
+ #
74
+ # ==== Options:
75
+ #
76
+ # [secret] the API secret key
77
+ # [key] the API access key
78
+ # [host] the host, which defaults to 'webservices.amazon.com'
79
+ #
23
80
  def configure(options={})
24
81
  @options = {
25
82
  :host => 'webservices.amazon.com',
@@ -31,12 +88,28 @@ module ASIN
31
88
  @options.merge! options
32
89
  end
33
90
 
91
+ # Performs an +ItemLookup+ REST call against the Amazon API.
92
+ #
93
+ # Expects an ASIN (Amazon Standard Identification Number) and returns an +Item+:
94
+ #
95
+ # item = lookup '1430218150'
96
+ # item.title
97
+ # => "Learn Objective-C on the Mac (Learn Series)"
98
+ #
99
+ # ==== Options:
100
+ #
101
+ # Additional parameters for the API call like this:
102
+ #
103
+ # lookup(asin, :ResponseGroup => :Medium)
104
+ #
34
105
  def lookup(asin, params={})
35
106
  Item.new(call(params.merge(:Operation => :ItemLookup, :ItemId => asin)))
36
107
  end
37
108
 
109
+ private
110
+
38
111
  def call(params)
39
- configure if @options.nil?
112
+ raise "you have to configure ASIN: 'configure :secret => 'your-secret', :key => 'your-key''" if @options.nil?
40
113
  signed = create_signed_query_string(params)
41
114
  resp = HTTPClient.new.get_content("http://#{@options[:host]}#{@options[:path]}?#{signed}")
42
115
  resp = resp.force_encoding('UTF-8') # shady workaround cause amazon returns bad utf-8 chars
data/readme.textile CHANGED
@@ -10,11 +10,23 @@ The code currently runs only on __Ruby 1.9__ due to encoding issues with the Ama
10
10
 
11
11
  h2. Usage
12
12
 
13
- <pre>
13
+ <pre lang="ruby">
14
14
  require 'asin'
15
15
  include ASIN
16
+ # use the configure method to setup your api credentials
16
17
  configure :secret => 'your-secret', :key => 'your-key'
17
- item = lookup '1430218150
18
+ # lookup an item with the amazon standard identification number (asin)
19
+ item = lookup '1430218150'
20
+ # have a look at the title of the item
18
21
  item.title
19
22
  => Learn Objective-C on the Mac (Learn Series)
20
- </pre>
23
+ # access the internal data representation (Hashie::Mash)
24
+ item.raw.ItemAttributes.ListPrice.FormattedPrice
25
+ => $39.99
26
+ </pre>
27
+
28
+ h2. TODO
29
+
30
+ * Logging
31
+ * More Docs
32
+ * More Tests
data/test/test_asin.rb CHANGED
@@ -1,5 +1,7 @@
1
1
  require 'test_helper'
2
2
 
3
+ ANY_ASIN = '1430218150'
4
+
3
5
  class TestAsin < Test::Unit::TestCase
4
6
 
5
7
  def setup
@@ -7,11 +9,17 @@ class TestAsin < Test::Unit::TestCase
7
9
  @helper.extend ASIN
8
10
  end
9
11
 
10
- # comment in and add your key to test real calls
11
- # def test_r_type_from_engine
12
- # @helper.configure :secret => 'your-secret', :key => 'your-key'
13
- # p item = @helper.lookup('1430218150')
14
- # assert_match(/Learn Objective/, item.title)
15
- # end
12
+ def test_lookup_with_configured_asin
13
+ secret = ENV['ASIN_SECRET']
14
+ key = ENV['ASIN_KEY']
15
+ puts "configure #{secret} and #{key} for this test"
16
+ @helper.configure :secret => secret, :key => key
17
+ p item = @helper.lookup(ANY_ASIN)
18
+ assert_match(/Learn Objective/, item.title)
19
+ end
20
+
21
+ def test_error_with_not_called_configure
22
+ assert_raise(RuntimeError) { @helper.lookup ANY_ASIN }
23
+ end
16
24
 
17
25
  end
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: asin
3
3
  version: !ruby/object:Gem::Version
4
- hash: 21
4
+ hash: 19
5
5
  prerelease: false
6
6
  segments:
7
7
  - 0
8
8
  - 0
9
- - 5
10
- version: 0.0.5
9
+ - 6
10
+ version: 0.0.6
11
11
  platform: ruby
12
12
  authors:
13
13
  - "Peter Schr\xC3\xB6der"
@@ -15,7 +15,7 @@ autorequire:
15
15
  bindir: bin
16
16
  cert_chain: []
17
17
 
18
- date: 2010-07-06 00:00:00 +02:00
18
+ date: 2010-07-13 00:00:00 +02:00
19
19
  default_executable:
20
20
  dependencies:
21
21
  - !ruby/object:Gem::Dependency
@@ -66,7 +66,7 @@ dependencies:
66
66
  version: 2.1.0
67
67
  type: :runtime
68
68
  version_requirements: *id003
69
- description: Amazon Simple INterface or whatever you want to call this
69
+ description: Amazon Simple INterface or whatever you want to call this.
70
70
  email: phoetmail@googlemail.com
71
71
  executables: []
72
72
 
@@ -75,10 +75,10 @@ extensions: []
75
75
  extra_rdoc_files:
76
76
  - readme.textile
77
77
  files:
78
- - readme.textile
79
78
  - lib/asin.rb
80
- - test/test_helper.rb
81
79
  - test/test_asin.rb
80
+ - test/test_helper.rb
81
+ - readme.textile
82
82
  has_rdoc: true
83
83
  homepage: http://github.com/phoet/asin
84
84
  licenses: []
@@ -95,10 +95,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
95
95
  requirements:
96
96
  - - ">="
97
97
  - !ruby/object:Gem::Version
98
- hash: 3
98
+ hash: 29
99
99
  segments:
100
- - 0
101
- version: "0"
100
+ - 1
101
+ - 9
102
+ version: "1.9"
102
103
  required_rubygems_version: !ruby/object:Gem::Requirement
103
104
  none: false
104
105
  requirements:
@@ -114,7 +115,7 @@ rubyforge_project:
114
115
  rubygems_version: 1.3.7
115
116
  signing_key:
116
117
  specification_version: 3
117
- summary: Simple interface to Amazon Item lookup
118
+ summary: Simple interface to Amazon Item lookup.
118
119
  test_files:
119
- - test/test_helper.rb
120
120
  - test/test_asin.rb
121
+ - test/test_helper.rb