crawlora-amazon 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5afb0a3acf7590df4deb43e220396558454dfc03d493ebd336d1f3cff199263
-  data.tar.gz: '058e6879c4012ff9f01cfc49485bafa377aaa9ee9d08484329f4e4ebfbdbdc6a'
+  metadata.gz: aee6c9db34ea55a3939500c3aaa3afa068cbe8793192c41fe0469ec9f4e1bad5
+  data.tar.gz: e075e45c55b0d68aa0073042fdb486df964ab8e96766c836cd8cd81e1ca24c4f
 SHA512:
-  metadata.gz: fd74cca6ae35f4a40844c2274f51bb5d136c6f0b292d353078c510230a7e54ccbe37d8869890f5ef50f246ab8f05af67a4d303797c86fca7f44c6ab8d59d5900
-  data.tar.gz: 6410588b9c1b293c58911020560d1663e3e023ffece5464fa9b031c613a763ee2a26769b4ceaf2b6b57f263612a0740b3adc50133f720f7f7506d45e93cf084b
+  metadata.gz: db8f5b5aaf1a3b0b8ed945c9cfee7fdfb0f2bdb6db4f2541b8d92b96d5bc78589181c01c308eb24d4d3edd47da21537a3a744715da0d6b926bd5edf7668c5673
+  data.tar.gz: 25c5060806da56976123ac57cf3120150fd333f15730e55daea1a2e29ff5b1c0b24cc7fb897046537e81447dd0afc79b6a5a827a7e002e2567fc44ae716560c2

data/README.md

@@ -1,6 +1,6 @@
-# Crawlora Amazon Ruby client
+# Crawlora Amazon API client for Ruby (`crawlora-amazon`)
 
-This gem calls the Crawlora hosted API at `https://api.crawlora.net/api/v1`. It does not call or scrape Amazon directly. Requests require your Crawlora API key and use your account's service plan.
+This Ruby gem calls Crawlora's hosted Amazon API at `https://api.crawlora.net/api/v1`. It exposes 5 endpoints covering product search, suggestions, product details, and chart/category discovery; it does not call or scrape Amazon directly. Requests require your Crawlora API key and use your account's service plan.
 
 ## Install
 
@@ -30,4 +30,16 @@ client.close
 
 Client options include `api_key`, `base_url`, and `timeout`. Ruby stdlib provides the HTTP and JSON support.
 
+## Supported Amazon API endpoints
+
+Browse every route included in this gem. The [endpoint reference](https://github.com/Crawlora-org/crawlora-amazon/blob/main/docs/usage.md) includes parameter and response details.
+
+| Method | Endpoint | API operation | Description |
+| --- | --- | --- | --- |
+| `GET` | `/amazon/charts` | `amazon-charts` | Amazon product charts |
+| `GET` | `/amazon/charts/categories` | `amazon-charts-categories` | Amazon chart categories |
+| `GET` | `/amazon/product/{asin}` | `amazon-product` | Retrieve Amazon product details |
+| `GET` | `/amazon/search` | `amazon-search` | Search Amazon products |
+| `GET` | `/amazon/suggest/{keyword}` | `amazon-suggest` | Retrieve Amazon search suggestions |
+
 See [Crawlora](https://crawlora.net/?utm_source=rubygems&utm_medium=referral&utm_campaign=platform-clients&utm_content=amazon-ruby-homepage), the [API documentation](https://crawlora.net/docs?utm_source=rubygems&utm_medium=referral&utm_campaign=platform-clients&utm_content=amazon-ruby-api-docs), and [the package repository](https://github.com/Crawlora-org/crawlora-amazon) for account setup, the API operation reference, and release history.

data/lib/crawlora/amazon/client.rb

@@ -19,7 +19,7 @@ module Crawlora
     end
 
     OPERATIONS = JSON.parse(<<~'JSON').freeze
-      {"amazon-charts": {"id": "amazon-charts", "method": "GET", "params": [{"description": "Chart type", "enum": ["best_sellers", "new_releases", "most_wished_for"], "in": "query", "name": "chart", "required": true, "type": "string", "x-example": "best_sellers"}, {"description": "Amazon department slug", "in": "query", "name": "department", "required": true, "type": "string", "x-example": "electronics"}, {"description": "Numeric browse node id", "in": "query", "name": "node", "type": "string", "x-example": "172541"}, {"description": "1-based page number", "in": "query", "name": "page", "type": "integer", "x-example": 1}], "path": "/amazon/charts", "pathParams": [], "produces": ["application/json"], "queryParams": [{"enum": ["best_sellers", "new_releases", "most_wished_for"], "in": "query", "name": "chart", "required": true, "type": "string"}, {"in": "query", "name": "department", "required": true, "type": "string"}, {"in": "query", "name": "node", "type": "string"}, {"in": "query", "name": "page", "type": "integer"}], "security": ["ApiKeyAuth"]}, "amazon-charts-categories": {"id": "amazon-charts-categories", "method": "GET", "params": [{"description": "Chart type", "enum": ["best_sellers", "new_releases", "most_wished_for"], "in": "query", "name": "chart", "required": true, "type": "string", "x-example": "best_sellers"}, {"description": "Amazon department slug", "in": "query", "name": "department", "type": "string", "x-example": "electronics"}, {"description": "Numeric browse node id (requires department)", "in": "query", "name": "node", "type": "string", "x-example": "172541"}], "path": "/amazon/charts/categories", "pathParams": [], "produces": ["application/json"], "queryParams": [{"enum": ["best_sellers", "new_releases", "most_wished_for"], "in": "query", "name": "chart", "required": true, "type": "string"}, {"in": "query", "name": "department", "type": "string"}, {"in": "query", "name": "node", "type": "string"}], "security": ["ApiKeyAuth"]}, "amazon-product": {"id": "amazon-product", "method": "GET", "params": [{"description": "Amazon ASIN", "in": "path", "name": "asin", "required": true, "type": "string", "x-example": "B0DGJ736JM"}, {"default": "en_US", "description": "Amazon language", "enum": ["en_US"], "in": "query", "name": "language", "type": "string"}, {"default": "USD", "description": "Amazon currency", "enum": ["USD"], "in": "query", "name": "currency", "type": "string"}], "path": "/amazon/product/{asin}", "pathParams": ["asin"], "produces": ["application/json"], "queryParams": [{"enum": ["en_US"], "in": "query", "name": "language", "type": "string"}, {"enum": ["USD"], "in": "query", "name": "currency", "type": "string"}], "security": ["ApiKeyAuth"]}, "amazon-search": {"id": "amazon-search", "method": "GET", "params": [{"description": "Search keyword", "in": "query", "name": "k", "required": true, "type": "string", "x-example": "apple watch"}, {"description": "Sort order", "in": "query", "name": "s", "type": "string", "x-example": "review-rank"}, {"description": "1-based page number", "in": "query", "name": "page", "type": "integer", "x-example": 1}], "path": "/amazon/search", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "k", "required": true, "type": "string"}, {"in": "query", "name": "s", "type": "string"}, {"in": "query", "name": "page", "type": "integer"}], "security": ["ApiKeyAuth"]}, "amazon-suggest": {"id": "amazon-suggest", "method": "GET", "params": [{"description": "Suggestion prefix", "in": "path", "name": "keyword", "required": true, "type": "string", "x-example": "apple"}], "path": "/amazon/suggest/{keyword}", "pathParams": ["keyword"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}}
+      {"amazon-charts": {"bodyParam": null, "bodyRequired": false, "id": "amazon-charts", "method": "GET", "params": [{"description": "Chart type", "enum": ["best_sellers", "new_releases", "most_wished_for"], "in": "query", "name": "chart", "required": true, "type": "string", "x-example": "best_sellers"}, {"description": "Amazon department slug", "in": "query", "name": "department", "required": true, "type": "string", "x-example": "electronics"}, {"description": "Numeric browse node id", "in": "query", "name": "node", "type": "string", "x-example": "172541"}, {"description": "1-based page number", "in": "query", "name": "page", "type": "integer", "x-example": 1}], "path": "/amazon/charts", "pathParams": [], "produces": ["application/json"], "queryParams": [{"enum": ["best_sellers", "new_releases", "most_wished_for"], "in": "query", "name": "chart", "required": true, "type": "string"}, {"in": "query", "name": "department", "required": true, "type": "string"}, {"in": "query", "name": "node", "type": "string"}, {"in": "query", "name": "page", "type": "integer"}], "security": ["ApiKeyAuth"]}, "amazon-charts-categories": {"bodyParam": null, "bodyRequired": false, "id": "amazon-charts-categories", "method": "GET", "params": [{"description": "Chart type", "enum": ["best_sellers", "new_releases", "most_wished_for"], "in": "query", "name": "chart", "required": true, "type": "string", "x-example": "best_sellers"}, {"description": "Amazon department slug", "in": "query", "name": "department", "type": "string", "x-example": "electronics"}, {"description": "Numeric browse node id (requires department)", "in": "query", "name": "node", "type": "string", "x-example": "172541"}], "path": "/amazon/charts/categories", "pathParams": [], "produces": ["application/json"], "queryParams": [{"enum": ["best_sellers", "new_releases", "most_wished_for"], "in": "query", "name": "chart", "required": true, "type": "string"}, {"in": "query", "name": "department", "type": "string"}, {"in": "query", "name": "node", "type": "string"}], "security": ["ApiKeyAuth"]}, "amazon-product": {"bodyParam": null, "bodyRequired": false, "id": "amazon-product", "method": "GET", "params": [{"description": "Amazon ASIN", "in": "path", "name": "asin", "required": true, "type": "string", "x-example": "B0DGJ736JM"}, {"default": "en_US", "description": "Amazon language", "enum": ["en_US"], "in": "query", "name": "language", "type": "string"}, {"default": "USD", "description": "Amazon currency", "enum": ["USD"], "in": "query", "name": "currency", "type": "string"}], "path": "/amazon/product/{asin}", "pathParams": ["asin"], "produces": ["application/json"], "queryParams": [{"enum": ["en_US"], "in": "query", "name": "language", "type": "string"}, {"enum": ["USD"], "in": "query", "name": "currency", "type": "string"}], "security": ["ApiKeyAuth"]}, "amazon-search": {"bodyParam": null, "bodyRequired": false, "id": "amazon-search", "method": "GET", "params": [{"description": "Search keyword", "in": "query", "name": "k", "required": true, "type": "string", "x-example": "apple watch"}, {"description": "Sort order", "in": "query", "name": "s", "type": "string", "x-example": "review-rank"}, {"description": "1-based page number", "in": "query", "name": "page", "type": "integer", "x-example": 1}], "path": "/amazon/search", "pathParams": [], "produces": ["application/json"], "queryParams": [{"in": "query", "name": "k", "required": true, "type": "string"}, {"in": "query", "name": "s", "type": "string"}, {"in": "query", "name": "page", "type": "integer"}], "security": ["ApiKeyAuth"]}, "amazon-suggest": {"bodyParam": null, "bodyRequired": false, "id": "amazon-suggest", "method": "GET", "params": [{"description": "Suggestion prefix", "in": "path", "name": "keyword", "required": true, "type": "string", "x-example": "apple"}], "path": "/amazon/suggest/{keyword}", "pathParams": ["keyword"], "produces": ["application/json"], "queryParams": [], "security": ["ApiKeyAuth"]}}
     JSON
     OPERATION_IDS = JSON.parse(<<~'JSON').freeze
       ["amazon-charts", "amazon-charts-categories", "amazon-product", "amazon-search", "amazon-suggest"]
@@ -29,7 +29,7 @@ module Crawlora
     class Client
       attr_reader :base_url
 
-      def initialize(api_key: ENV["CRAWLORA_API_KEY"], base_url: "https://api.crawlora.net/api/v1", timeout: 30, user_agent: "crawlora-amazon-ruby/0.1.1", transport: nil)
+      def initialize(api_key: ENV["CRAWLORA_API_KEY"], base_url: "https://api.crawlora.net/api/v1", timeout: 30, user_agent: "crawlora-amazon-ruby/0.1.2", transport: nil)
         @api_key = api_key
         @base_url = base_url.to_s.sub(%r{/+$}, "")
         @timeout = Float(timeout)
@@ -45,15 +45,24 @@ module Crawlora
         raise Errors::ClientError.new("unknown operation: #{operation_id}", operation_id: operation_id) unless operation
         raise Errors::ClientError.new("Crawlora API key is required", operation_id: operation_id) if @api_key.nil? || @api_key.to_s.empty?
         normalized = params.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+        payload = request_body(operation, normalized)
         url = build_url(operation, normalized)
         uri = URI.parse(url)
-        request = Net::HTTP::Get.new(uri)
+        request = operation["method"] == "POST" ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
+        unless payload.nil?
+          request.body = payload
+          request["Content-Type"] = "application/json"
+        end
         request["x-api-key"] = @api_key
         request["User-Agent"] = @user_agent
         request["Accept"] = operation["produces"].include?("text/plain") ? "application/json, text/plain" : "application/json"
         begin
           if @transport
-            response = @transport.call(url, request.to_hash, @timeout)
+            response = if operation["method"] == "POST"
+              @transport.call(url, request.to_hash, @timeout, "POST", payload)
+            else
+              @transport.call(url, request.to_hash, @timeout)
+            end
             status = Integer(response.fetch(:status) { response.fetch("status") })
             body = response.fetch(:body) { response.fetch("body", "") }
             headers = response.fetch(:headers) { response.fetch("headers", {}) }
@@ -128,8 +137,21 @@ module Crawlora
 
       private
 
+      # POST operations take their JSON body under the body parameter name or "body".
+      def request_body(operation, params)
+        name = operation["bodyParam"]
+        return nil if name.nil?
+        value = params.key?(name) ? params[name] : params["body"]
+        if value.nil?
+          raise Errors::ClientError.new("missing request body: #{name}", operation_id: operation["id"]) if operation["bodyRequired"]
+          return nil
+        end
+        value.is_a?(String) ? value : JSON.generate(value)
+      end
+
       def build_url(operation, params)
         known = operation["params"].map { |param| param["name"] }
+        known << "body" if operation["bodyParam"]
         unknown = params.keys - known
         raise Errors::ClientError.new("unknown parameters: #{unknown.join(', ')}", operation_id: operation["id"]) unless unknown.empty?
         path = operation["path"].dup

data/lib/crawlora/amazon/version.rb

@@ -1,5 +1,5 @@
 module Crawlora
   module Amazon
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: crawlora-amazon
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Crawlora
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-09 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies: []
-description: Credential-free Amazon API access through Crawlora's hosted service.
+description: Ruby client for Crawlora's hosted Amazon API. Covers product search,
+  suggestions, product details, and chart/category discovery across 5 endpoints.
 email:
 executables: []
 extensions: []
@@ -47,5 +48,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Amazon client for the Crawlora hosted API
+summary: Amazon API client for Crawlora (5 endpoints)
 test_files: []