asindotdev 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 170ee5aab5befec0bdc0e4cf1bc00e0e9ded747cf2ea3a28e357c3d945b78274
+  data.tar.gz: 99c1e85a7ec4aa97b72ec8490516bf0f8884a734568f2fd28d00913b5fcaac7e
+SHA512:
+  metadata.gz: 3043522567bc7a0cc8d49d4ad405ffc8a09a4e77b5a87bc7464206e1b5e6b6bd68bd4b28bc64c60fb26cb3e1c3a313d269ff9d1b07f201f130ebeb45394b0e54
+  data.tar.gz: 0d666a57f3fab1f81bf8f442bfbc92b114cd5cea5412c5e3ba312c1e98a3986ee85ecbbefdbc993208dcd22f859716564910604facb16d2fb9a5830d5854d1b8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# Asin Ruby SDK
+
+The official Ruby SDK for the [Asin](https://www.asin.dev) Amazon price tracking API.
+
+Track Amazon prices and products with a scheduled watchlist, price history, offers and alerts.
+
+The SDK exposes **11 methods**, one per documented endpoint, plus a generic `request`. It only uses the Ruby standard library.
+
+## Requirements
+
+- Ruby 3.1 or newer
+
+## Installation
+
+```sh
+gem install asindotdev
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem "asindotdev"
+```
+
+## Get your API key
+
+[Sign up for Asin](https://www.asin.dev/signup) or sign in, then copy your API key from the [dashboard](https://www.asin.dev/app). The client reads `ENV["ASIN_API_KEY"]` when no key is passed.
+
+## Quick start
+
+```ruby
+require "asin"
+
+client = Asin::Client.new(api_key: ENV.fetch("ASIN_API_KEY"))
+response = client.search_amazon(query: "wireless earbuds")
+puts response.data
+```
+
+Keyword arguments use the parameter names of the [API reference](https://www.asin.dev/docs). Unknown names raise `Asin::SerializationError`; use `request` for undocumented parameters.
+
+## HTTP methods
+
+Each method uses the HTTP verb of its endpoint. `GET` and `DELETE` send parameters in the query string; `POST` and `PATCH` send them as a JSON body, except `wait` on `/products/{id}/check`, which stays in the query string. Null values are never sent, so `target_price` cannot be removed through the SDK yet.
+
+`nil` values are omitted, `false` and `0` are sent, and arrays repeat the parameter name.
+
+## Any endpoint
+
+```ruby
+response = client.request("GET", "/account")
+```
+
+## Errors
+
+```ruby
+begin
+  client.search_amazon(query: "wireless earbuds")
+rescue Asin::APIError => e
+  warn "HTTP #{e.status}: #{e.message}"
+end
+```
+
+| Error | When |
+| --- | --- |
+| `Asin::ConfigurationError` | Missing API key, invalid options or unsupported method. |
+| `Asin::SerializationError` | A required parameter is missing, unknown or can't be sent. |
+| `Asin::TransportError` | Network failure or timeout. |
+| `Asin::APIError` | Non-2xx status (`status`, `error_message`, `response_body`, `raw_response`). |
+| `Asin::ResponseDecodingError` | A success response could not be decoded. |
+
+All of them inherit from `Asin::Error`.
+
+## Retries
+
+Requests are retried up to 3 times after a network error, a `408`, `429`, `500`, `502`, `503` or `504`. Other statuses, such as `400`, `401`, `402` or `404`, and client-side timeouts are not retried. The delay starts at 1 second and grows 1.5× per retry (capped at 30 seconds); a `Retry-After` header wins.
+
+```ruby
+client = Asin::Client.new(max_retries: 5, retry_delay: 0.5)
+client.search_amazon(query: "wireless earbuds", request_options: { max_retries: 0 }) # one request without retries
+```
+
+## Batch requests
+
+`batch` runs the block for every item on 10 threads (`concurrency:`) and returns one `BatchResult` per item, in input order. A failing item never stops the others.
+
+```ruby
+inputs = ["wireless earbuds", "mechanical keyboard", "usb-c hub"]
+results = client.batch(inputs, concurrency: 5) { |value| client.search_amazon(query: value) }
+results.each do |result|
+  if result.ok?
+    puts result.value.data
+  else
+    warn "#{inputs[result.index]}: #{result.error.message}"
+  end
+end
+```
+
+| Constant | Default | Description |
+| --- | --- | --- |
+| `Asin::Client::DEFAULT_CONCURRENCY` | `10` | Tasks run at the same time by batch |
+| `Asin::Client::DEFAULT_TIMEOUT` | `120` | Request timeout (seconds) |
+| `Asin::Client::MAX_RETRIES` | `3` | Retry attempts after a network error, a 408/429/5xx |
+| `Asin::Client::RETRY_BACKOFF_FACTOR` | `1.5` | Exponential backoff multiplier |
+| `Asin::Client::DEFAULT_RETRY_DELAY` | `1.0` | Delay before the first retry (seconds) |
+
+## Timeouts and custom transports
+
+```ruby
+client = Asin::Client.new(timeout: 60) # seconds, default 120
+client.search_amazon(query: "wireless earbuds", request_options: { timeout: 30 })
+```
+
+A transport is any object with `call(method:, url:, headers:, body:, timeout:)` returning `[status, headers, body]`; the default is `Asin::NetHTTPTransport`.
+
+## Endpoints
+
+11 methods, generated from the [OpenAPI document](https://www.asin.dev/openapi.json).
+
+| Method | HTTP | Description |
+| --- | --- | --- |
+| `check_product` | POST `/products/{id}/check` | Asks for a check right away (1 credit), at most once per 5 minutes; earlier calls return the product unchanged. A paused product has to be… |
+| `delete_product` | DELETE `/products/{id}` | Removes the product and its price history. |
+| `fetch_offers` | POST `/offers` | Reads the offers on Amazon for 1 credit, refunded if it doesn't answer. A read made in the last 3 hours, by anyone, is returned instead, fo… |
+| `get_account` | GET `/account` | Your plan, the credits left (monthly allowance and packs), how many products you track and the credits they use per month. |
+| `get_asin_history` | GET `/history` | Every price Asin read for an ASIN on a marketplace over the period, whoever tracks it, oldest first, with the lowest, highest and average o… |
+| `get_offers` | GET `/offers` | Who sells the product and at what price, as last read, cheapest first, with Amazon's own price and the cheapest new and used offers (used i… |
+| `get_product` | GET `/products/{id}` | The product's latest state and every price read of the period, oldest first. The history covers every read of this ASIN on this marketplace… |
+| `list_products` | GET `/products` | Your watchlist, newest first, with each product's latest state and its recent prices (trend). Filter with asin (and marketplace) to know if… |
+| `search_amazon` | GET `/search` | Amazon search results (up to 60, sponsored included), to find the ASIN of a product. Free, limited to 30 searches per hour. |
+| `track_product` | POST `/products` | Adds an ASIN, an Amazon link or a short link (amzn.to, a.co…) to your watchlist. The first check runs in the background within seconds (che… |
+| `update_product` | PATCH `/products/{id}` | Target price, drop alerts, check interval, or pause. Send only what changes. |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/examples/README.md

@@ -0,0 +1,10 @@
+# Examples
+
+```sh
+gem install asindotdev
+export ASIN_API_KEY="YOUR_API_KEY"
+ruby examples/json.rb
+```
+
+- `json.rb` — call the featured endpoint and print the JSON result.
+- `request.rb` — call any path with `request` and handle API errors.

data/examples/json.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "json"
+require "asin"
+
+client = Asin::Client.new # reads ASIN_API_KEY
+response = client.search_amazon(query: "wireless earbuds")
+puts JSON.pretty_generate(response.data)

data/examples/request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "asin"
+
+client = Asin::Client.new # reads ASIN_API_KEY
+begin
+  response = client.request("GET", "/account")
+  puts response.data if response.json?
+rescue Asin::APIError => e
+  warn "HTTP #{e.status}: #{e.message}"
+end

data/lib/asin/client.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Asin
+  # Official Asin API client. Create one instance and reuse it.
+  class Client
+    include Operations
+
+    DEFAULT_BASE_URL = "https://www.asin.dev/api/v1"
+    DEFAULT_TIMEOUT = 120
+    # Tasks run at the same time by #batch.
+    DEFAULT_CONCURRENCY = 10
+    # Retries after a network error or a 408, 429, 500, 502, 503 or 504 response.
+    MAX_RETRIES = 3
+    # Each retry waits this many times longer than the previous one (a Retry-After header wins).
+    RETRY_BACKOFF_FACTOR = 1.5
+    # Seconds before the first retry.
+    DEFAULT_RETRY_DELAY = 1.0
+    MAX_RETRY_DELAY = 30.0
+    RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+    API_KEY_ENVIRONMENT_VARIABLE = "ASIN_API_KEY"
+    ERROR_MESSAGE_KEYS = %w[error message error_message detail].freeze
+
+    # @param api_key [String, nil] defaults to ENV["ASIN_API_KEY"]
+    # @param base_url [String] API origin
+    # @param timeout [Numeric, nil] seconds per request; nil disables it
+    # @param headers [Hash] extra headers for every request
+    # @param max_retries [Integer] retries after a network error or a 408/429/5xx response; 0 disables them
+    # @param retry_delay [Numeric] seconds before the first retry, growing 1.5x per retry
+    # @param transport [#call] custom transport, see {NetHTTPTransport}
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, headers: {},
+                   max_retries: MAX_RETRIES, retry_delay: DEFAULT_RETRY_DELAY, transport: nil)
+      api_key = ENV.fetch(API_KEY_ENVIRONMENT_VARIABLE, nil) if api_key.nil?
+      if !api_key.is_a?(String) || api_key.strip.empty?
+        raise ConfigurationError,
+              "A non-blank Asin API key is required. Pass api_key: or set #{API_KEY_ENVIRONMENT_VARIABLE}."
+      end
+      raise ConfigurationError, "The Asin API key cannot be used in an HTTP header." if api_key.match?(/[\r\n]/)
+
+      uri = URI.parse(base_url.to_s)
+      unless %w[http https].include?(uri.scheme) && uri.host
+        raise ConfigurationError, "base_url must be an absolute http or https URL."
+      end
+      raise ConfigurationError, "timeout must be a positive number or nil." if timeout && !(timeout.is_a?(Numeric) && timeout.positive?)
+      raise ConfigurationError, "transport must respond to #call." if transport && !transport.respond_to?(:call)
+
+      @api_key = api_key
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @headers = headers.to_h { |name, value| [name.to_s, value.to_s] }.freeze
+      raise ConfigurationError, "max_retries must be a non-negative Integer." unless max_retries.is_a?(Integer) && max_retries >= 0
+      raise ConfigurationError, "retry_delay must be a non-negative number." unless retry_delay.is_a?(Numeric) && retry_delay >= 0
+
+      @max_retries = max_retries
+      @retry_delay = retry_delay
+      @transport = transport || NetHTTPTransport.new
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+    end
+
+    # Sends any request, including endpoints released after this SDK version.
+    # GET parameters travel in the query string; POST parameters travel in a JSON body.
+    # @return [JsonResponse, BinaryResponse]
+    def request(method, path, params = nil, timeout: nil, headers: nil, max_retries: nil)
+      send_request(method.to_s.upcase, path, params, { timeout: timeout, headers: headers, max_retries: max_retries }, :any)
+    end
+
+    # Runs the block for every item on +concurrency+ threads (default 10) and returns one {BatchResult} per item,
+    # in input order. A failing item never stops the others; the client is thread-safe.
+    #
+    #   results = client.batch(ids, concurrency: 5) { |id| client.some_endpoint(query: id) }
+    # @return [Array<BatchResult>]
+    def batch(items, concurrency: DEFAULT_CONCURRENCY)
+      raise ConfigurationError, "concurrency must be a positive Integer." unless concurrency.is_a?(Integer) && concurrency.positive?
+      raise ArgumentError, "batch needs a block" unless block_given?
+
+      list = items.to_a
+      results = Array.new(list.size)
+      queue = Queue.new
+      list.each_with_index { |item, index| queue << [item, index] }
+      queue.close
+      workers = Array.new([concurrency, list.size].min) do
+        Thread.new do
+          while (job = queue.pop)
+            item, index = job
+            results[index] = begin
+              BatchResult.new(index: index, value: yield(item), error: nil)
+            rescue StandardError => e
+              BatchResult.new(index: index, value: nil, error: e)
+            end
+          end
+        end
+      end
+      workers.each(&:join)
+      results
+    end
+
+    private
+
+    def call_operation(name, params, options)
+      endpoint = ENDPOINTS.fetch(name)
+      options = (options || {}).transform_keys(&:to_sym)
+      method = (options[:method] || endpoint[:methods].first).to_s.upcase
+      unless endpoint[:methods].include?(method)
+        raise ConfigurationError, "#{endpoint[:path]} supports #{endpoint[:methods].join(', ')}, not #{method}."
+      end
+
+      params = params.transform_keys(&:to_s)
+      unknown = params.keys - endpoint[:params]
+      unless unknown.empty?
+        raise SerializationError.new(
+          "Unknown parameter(s) for #{name}: #{unknown.join(', ')}. Use #request for undocumented parameters.",
+          unknown.first
+        )
+      end
+      endpoint[:required].each do |required|
+        raise SerializationError.new("The \"#{required}\" parameter is required.", required) if params[required].nil?
+      end
+      send_request(method, endpoint[:path], params, options, endpoint[:response])
+    end
+
+    def send_request(method, path, params, options, expected)
+      raise ConfigurationError, "Unsupported HTTP method: #{method.inspect}." unless %w[GET POST PATCH DELETE].include?(method)
+      raise ConfigurationError, 'The request path must start with "/".' unless path.is_a?(String) && path.start_with?("/")
+
+      path, pairs, body = Serialization.serialize(method, path, params)
+      url = @base_url + path
+      url += "?#{Serialization.encode_query(pairs)}" unless pairs.empty?
+      headers = {
+        "Accept" => "application/json, */*;q=0.8",
+        "User-Agent" => "asin-ruby/#{VERSION}"
+      }.merge(@headers).merge((options[:headers] || {}).to_h { |k, v| [k.to_s, v.to_s] })
+      headers["Authorization"] = "Bearer #{@api_key}"
+      payload = nil
+      if body
+        headers["Content-Type"] = "application/json"
+        payload = JSON.generate(body)
+      end
+
+      max_retries = options[:max_retries] || @max_retries
+      attempt = 0
+      loop do
+        begin
+          status, response_headers, response_body = @transport.call(
+            method: method, url: url, headers: headers, body: payload, timeout: options[:timeout] || @timeout
+          )
+        rescue Timeout::Error => e
+          raise TransportError, "Asin request timed out: #{e.message}"
+        rescue StandardError => e
+          raise TransportError, "Asin request failed before an HTTP response was received: #{e.message}" if attempt >= max_retries
+
+          sleep(retry_delay(attempt, nil))
+          attempt += 1
+          next
+        end
+        raw = build_raw_response(status, response_headers, response_body)
+        return decode(raw, expected) if (200..299).cover?(raw.status)
+        raise api_error(raw) unless retryable?(raw) && attempt < max_retries
+
+        sleep(retry_delay(attempt, raw.headers["retry-after"]&.first))
+        attempt += 1
+      end
+    end
+
+    def retryable?(raw)
+      RETRYABLE_STATUSES.include?(raw.status)
+    end
+
+    def retry_delay(attempt, retry_after)
+      seconds = Float(retry_after, exception: false) if retry_after
+      return [seconds, 60].min if seconds && seconds >= 0
+
+      [@retry_delay * (RETRY_BACKOFF_FACTOR**attempt), MAX_RETRY_DELAY].min
+    end
+
+    def build_raw_response(status, headers, body)
+      normalized = {}
+      (headers || {}).each { |name, values| normalized[name.to_s.downcase] = Array(values).map(&:to_s).freeze }
+      RawResponse.new(
+        status: status.to_i,
+        headers: normalized.freeze,
+        content_type: normalized["content-type"]&.first,
+        body: body.to_s.b
+      )
+    end
+
+    def api_error(raw)
+      parsed = parse_json(raw.body)
+      message = nil
+      if parsed.is_a?(Hash)
+        # The API answers {"error": {"code", "message"}}.
+        message = parsed["error"]["message"] if parsed["error"].is_a?(Hash) && parsed["error"]["message"].is_a?(String)
+        ERROR_MESSAGE_KEYS.each do |key|
+          value = parsed[key]
+          if value.is_a?(String) && !value.empty?
+            message = value
+            break
+          end
+        end
+      end
+      APIError.new(raw_response: raw, response_body: parsed == NOT_JSON ? nil : parsed, error_message: message)
+    end
+
+    def decode(raw, expected)
+      unless json_media_type?(raw.content_type)
+        if expected == :json
+          raise ResponseDecodingError.new("Asin returned a successful non-JSON response for a JSON operation.", raw)
+        end
+
+        return BinaryResponse.new(bytes: raw.body, content_type: raw.content_type, raw_response: raw)
+      end
+      data = parse_json(raw.body)
+      if data == NOT_JSON
+        raise ResponseDecodingError.new("Asin returned a successful JSON response that could not be decoded.", raw)
+      end
+
+      JsonResponse.new(data: data, raw_response: raw)
+    end
+
+    NOT_JSON = Object.new.freeze
+    private_constant :NOT_JSON
+
+    def parse_json(body)
+      JSON.parse(body.dup.force_encoding(Encoding::UTF_8))
+    rescue JSON::ParserError, EncodingError
+      NOT_JSON
+    end
+
+    def json_media_type?(content_type)
+      return false if content_type.nil?
+
+      media_type = content_type.split(";", 2).first.strip.downcase
+      media_type == "application/json" || media_type.end_with?("+json")
+    end
+  end
+end

data/lib/asin/endpoints.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Generated from the Asin OpenAPI document. Do not edit by hand.
+
+module Asin
+  # Path, methods, response kind and parameter names of every documented operation.
+  ENDPOINTS = {
+    "check_product" => {
+      path: "/products/{id}/check",
+      methods: ["POST"].freeze,
+      response: :json,
+      required: ["id"].freeze,
+      params: ["id", "wait"].freeze
+    }.freeze,
+    "delete_product" => {
+      path: "/products/{id}",
+      methods: ["DELETE"].freeze,
+      response: :json,
+      required: ["id"].freeze,
+      params: ["id"].freeze
+    }.freeze,
+    "fetch_offers" => {
+      path: "/offers",
+      methods: ["POST"].freeze,
+      response: :json,
+      required: ["asin"].freeze,
+      params: ["asin", "marketplace", "refresh"].freeze
+    }.freeze,
+    "get_account" => {
+      path: "/account",
+      methods: ["GET"].freeze,
+      response: :json,
+      required: [].freeze,
+      params: [].freeze
+    }.freeze,
+    "get_asin_history" => {
+      path: "/history",
+      methods: ["GET"].freeze,
+      response: :json,
+      required: ["asin"].freeze,
+      params: ["asin", "marketplace", "days"].freeze
+    }.freeze,
+    "get_offers" => {
+      path: "/offers",
+      methods: ["GET"].freeze,
+      response: :json,
+      required: ["asin"].freeze,
+      params: ["asin", "marketplace"].freeze
+    }.freeze,
+    "get_product" => {
+      path: "/products/{id}",
+      methods: ["GET"].freeze,
+      response: :json,
+      required: ["id"].freeze,
+      params: ["id", "days"].freeze
+    }.freeze,
+    "list_products" => {
+      path: "/products",
+      methods: ["GET"].freeze,
+      response: :json,
+      required: [].freeze,
+      params: ["asin", "marketplace", "filter", "page", "limit"].freeze
+    }.freeze,
+    "search_amazon" => {
+      path: "/search",
+      methods: ["GET"].freeze,
+      response: :json,
+      required: ["query"].freeze,
+      params: ["query", "marketplace"].freeze
+    }.freeze,
+    "track_product" => {
+      path: "/products",
+      methods: ["POST"].freeze,
+      response: :json,
+      required: ["product"].freeze,
+      params: ["product", "marketplace", "target_price", "interval_minutes", "wait"].freeze
+    }.freeze,
+    "update_product" => {
+      path: "/products/{id}",
+      methods: ["PATCH"].freeze,
+      response: :json,
+      required: ["id"].freeze,
+      params: ["id", "target_price", "interval_minutes", "alert_on_drop", "paused"].freeze
+    }.freeze
+  }.freeze
+end

data/lib/asin/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Asin
+  # Base class for every SDK-defined error.
+  class Error < StandardError; end
+
+  # The client configuration is missing or unusable.
+  class ConfigurationError < Error; end
+
+  # A request value cannot be represented safely on the wire.
+  class SerializationError < Error
+    attr_reader :param
+
+    def initialize(message, param = nil)
+      super(message)
+      @param = param
+    end
+  end
+
+  # The request failed before a complete HTTP response was received.
+  class TransportError < Error; end
+
+  # Asin returned a non-success HTTP status.
+  class APIError < Error
+    attr_reader :status, :error_message, :response_body, :raw_response
+
+    def initialize(raw_response:, response_body: nil, error_message: nil)
+      super(error_message || "Asin API request failed with status #{raw_response.status}.")
+      @status = raw_response.status
+      @error_message = error_message
+      @response_body = response_body
+      @raw_response = raw_response
+    end
+  end
+
+  # A successful response could not be decoded as the documented representation.
+  class ResponseDecodingError < Error
+    attr_reader :raw_response
+
+    def initialize(message, raw_response)
+      super(message)
+      @raw_response = raw_response
+    end
+  end
+end

data/lib/asin/operations.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# Generated from the Asin OpenAPI document. Do not edit by hand.
+
+module Asin
+  # One method per documented endpoint. Mixed into {Client}.
+  module Operations
+    # Check the price now. Asks for a check right away (1 credit), at most once per 5 minutes; earlier calls return the product unchanged. A paused product has to be resumed first. The check runs in the background; with wait=true the answer waits for it. Read last_e…
+    #
+    # +POST /products/{id}/check+
+    #
+    # @param id [String] (required) product_id returned when the product was added
+    # @param wait [Boolean] Answer once the check is done (up to 45 seconds)
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def check_product(request_options: nil, **params)
+      call_operation("check_product", params, request_options)
+    end
+
+    # Stop tracking a product. Removes the product and its price history.
+    #
+    # +DELETE /products/{id}+
+    #
+    # @param id [String] (required) product_id returned when the product was added
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def delete_product(request_options: nil, **params)
+      call_operation("delete_product", params, request_options)
+    end
+
+    # Read every offer from Amazon. Reads the offers on Amazon for 1 credit, refunded if it doesn't answer. A read made in the last 3 hours, by anyone, is returned instead, for free (charged: false). The answer is the same as GET /offers.
+    #
+    # +POST /offers+
+    #
+    # @param asin [String] (required) 10-character ASIN
+    # @param marketplace [String] Amazon store, e.g. com for amazon.com
+    # @param refresh [Boolean] Read Amazon again unless the last read is under 5 minutes old (1 credit)
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def fetch_offers(request_options: nil, **params)
+      call_operation("fetch_offers", params, request_options)
+    end
+
+    # Plan and remaining credits. Your plan, the credits left (monthly allowance and packs), how many products you track and the credits they use per month.
+    #
+    # +GET /account+
+    #
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def get_account(request_options: nil, **params)
+      call_operation("get_account", params, request_options)
+    end
+
+    # Price history of any ASIN. Every price Asin read for an ASIN on a marketplace over the period, whoever tracks it, oldest first, with the lowest, highest and average of those prices. A history of more than 5000 points is thinned evenly, keeping its first and last poi…
+    #
+    # +GET /history+
+    #
+    # @param asin [String] (required) 10-character ASIN
+    # @param marketplace [String] Amazon store, e.g. com for amazon.com
+    # @param days [Integer] History period in days
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def get_asin_history(request_options: nil, **params)
+      call_operation("get_asin_history", params, request_options)
+    end
+
+    # Offers already known. Who sells the product and at what price, as last read, cheapest first, with Amazon's own price and the cheapest new and used offers (used is only known for Amazon's own outlet). Free: this never reads Amazon or spends a credit. When nobody…
+    #
+    # +GET /offers+
+    #
+    # @param asin [String] (required) 10-character ASIN
+    # @param marketplace [String] Amazon store, e.g. com for amazon.com
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def get_offers(request_options: nil, **params)
+      call_operation("get_offers", params, request_options)
+    end
+
+    # Get a product and its price history. The product's latest state and every price read of the period, oldest first. The history covers every read of this ASIN on this marketplace, including those made before you added it, so a product added today can come with months of prices;…
+    #
+    # +GET /products/{id}+
+    #
+    # @param id [String] (required) product_id returned when the product was added
+    # @param days [Integer] History period in days
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def get_product(request_options: nil, **params)
+      call_operation("get_product", params, request_options)
+    end
+
+    # List tracked products. Your watchlist, newest first, with each product's latest state and its recent prices (trend). Filter with asin (and marketplace) to know if a product is tracked, or with filter to get the same lists as the app's tabs.
+    #
+    # +GET /products+
+    #
+    # @param asin [String] Only this ASIN
+    # @param marketplace [String] Only this Amazon store
+    # @param filter [String] Only the products of one of the app's watchlist filters. all: Every tracked product (default). drops: Cheaper now than when the product was added. target: At or below its target price. out_of_stock:…
+    # @param page [Integer] Page number
+    # @param limit [Integer] Products per page
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def list_products(request_options: nil, **params)
+      call_operation("list_products", params, request_options)
+    end
+
+    # Search Amazon. Amazon search results (up to 60, sponsored included), to find the ASIN of a product. Free, limited to 30 searches per hour.
+    #
+    # +GET /search+
+    #
+    # @param query [String] (required) Keywords
+    # @param marketplace [String] Amazon store, e.g. com for amazon.com
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def search_amazon(request_options: nil, **params)
+      call_operation("search_amazon", params, request_options)
+    end
+
+    # Track a product. Adds an ASIN, an Amazon link or a short link (amzn.to, a.co…) to your watchlist. The first check runs in the background within seconds (checking is true until then): poll GET /products/{id}, or send wait: true to get the answer once it's d…
+    #
+    # +POST /products+
+    #
+    # @param product [String] (required) ASIN (B09DFCB66S) or Amazon product link
+    # @param marketplace [String] Amazon store, e.g. com for amazon.com. A product link sets it on its own.
+    # @param target_price [Numeric] Email the owner when the price goes at or below this amount. null removes it.
+    # @param interval_minutes [Integer] Minutes between two checks (1440 = daily). Checks faster than daily need a plan or a credit pack: every 60 minutes with a pack or Starter, 30 with Pro, 5 with Business.
+    # @param wait [Boolean] Answer once the first check is done (up to 45 seconds)
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def track_product(request_options: nil, **params)
+      call_operation("track_product", params, request_options)
+    end
+
+    # Change alerts and checks. Target price, drop alerts, check interval, or pause. Send only what changes.
+    #
+    # +PATCH /products/{id}+
+    #
+    # @param id [String] (required) product_id returned when the product was added
+    # @param target_price [Numeric] Email the owner when the price goes at or below this amount. null removes it.
+    # @param interval_minutes [Integer] Minutes between two checks (1440 = daily). Checks faster than daily need a plan or a credit pack: every 60 minutes with a pack or Starter, 30 with Pro, 5 with Business.
+    # @param alert_on_drop [Boolean] Email when the price drops or the product is back in stock
+    # @param paused [Boolean] Stop checking (and charging) for now; false resumes
+    # @param request_options [Hash, nil] +:method+ ("GET"/"POST"), +:timeout+ (seconds), +:headers+
+    # @return [JsonResponse]
+    def update_product(request_options: nil, **params)
+      call_operation("update_product", params, request_options)
+    end
+  end
+end

data/lib/asin/responses.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Asin
+  # Buffered HTTP response: status, lower-cased multi-value headers, content type and body bytes.
+  RawResponse = Struct.new(:status, :headers, :content_type, :body, keyword_init: true)
+
+  # Outcome of one Client#batch item: +value+ when +ok?+, else +error+.
+  BatchResult = Struct.new(:index, :value, :error, keyword_init: true) do
+    def ok? = error.nil?
+  end
+
+  # A successful JSON response; +data+ is the parsed body (string keys).
+  class JsonResponse
+    attr_reader :data, :raw_response
+
+    def initialize(data:, raw_response:)
+      @data = data
+      @raw_response = raw_response
+    end
+
+    def kind = :json
+    def json? = true
+    def binary? = false
+  end
+
+  # A successful non-JSON response (image, PDF, HTML…).
+  class BinaryResponse
+    attr_reader :bytes, :content_type, :raw_response
+
+    def initialize(bytes:, content_type:, raw_response:)
+      @bytes = bytes
+      @content_type = content_type
+      @raw_response = raw_response
+    end
+
+    def kind = :binary
+    def json? = false
+    def binary? = true
+
+    # Writes the body to +path+ and returns the number of bytes written.
+    def save(path)
+      File.binwrite(path, bytes)
+    end
+  end
+end

data/lib/asin/serialization.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Asin
+  # Request serialization: path filling, query pairs and JSON bodies.
+  module Serialization
+    QUERY_STRING_PARAMS = { "/products/{id}/check" => %w[wait] }.freeze
+
+    module_function
+
+    # Fills {name} path segments, then returns [path, query_pairs, body].
+    # nil values are omitted; false and 0 are sent.
+    def serialize(method, path_template, params)
+      raise SerializationError, "Request parameters must be a Hash." unless params.nil? || params.is_a?(Hash)
+
+      remaining = {}
+      (params || {}).each { |name, value| remaining[name.to_s] = value unless value.nil? }
+      path = path_template.gsub(/\{([^}]+)\}/) do
+        name = Regexp.last_match(1)
+        raise SerializationError.new("The \"#{name}\" path parameter is required.", name) unless remaining.key?(name)
+
+        URI.encode_www_form_component(wire_string(name, remaining.delete(name))).gsub("+", "%20")
+      end
+
+      if %w[POST PATCH].include?(method)
+        # The API reads wait from the query string on POST /products/{id}/check.
+        globals = QUERY_STRING_PARAMS.fetch(path_template, []).filter_map { |name| [name, wire_string(name, remaining.delete(name))] if remaining.key?(name) }
+        return [path, globals, remaining]
+      end
+
+      pairs = []
+      remaining.each do |name, value|
+        if value.is_a?(Array)
+          value.each { |item| pairs << [name, wire_string(name, item)] unless item.nil? }
+        else
+          pairs << [name, wire_string(name, value)]
+        end
+      end
+      [path, pairs, nil]
+    end
+
+    def wire_string(name, value)
+      case value
+      when String then value
+      when true, false, Integer, Symbol then value.to_s
+      when Float
+        raise SerializationError.new("The \"#{name}\" parameter must be a finite number.", name) unless value.finite?
+
+        value == value.floor ? value.to_i.to_s : value.to_s
+      when Hash, Array then JSON.generate(value)
+      else
+        raise SerializationError.new("The \"#{name}\" parameter has an unsupported type (#{value.class}).", name)
+      end
+    end
+
+    def encode_query(pairs)
+      pairs.map { |name, value| "#{escape(name)}=#{escape(value)}" }.join("&")
+    end
+
+    def escape(value)
+      URI.encode_www_form_component(value).gsub("+", "%20")
+    end
+  end
+end

data/lib/asin/transport.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Asin
+  # Default transport on Net::HTTP. A custom transport is any object with
+  # +call(method:, url:, headers:, body:, timeout:)+ returning +[status, headers, body]+,
+  # where headers is a Hash of lower-cased names to arrays of values.
+  class NetHTTPTransport
+    def call(method:, url:, headers:, body:, timeout:)
+      uri = URI(url)
+      request = Net::HTTP.const_get(method.capitalize).new(uri)
+      headers.each { |name, value| request[name] = value }
+      request.body = body if body
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      if timeout
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+      end
+      response = http.start { |connection| connection.request(request) }
+      [response.code.to_i, response.to_hash, response.body || ""]
+    end
+  end
+end

data/lib/asin/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Asin
+  VERSION = "0.1.0"
+end

data/lib/asin.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "asin/version"
+require_relative "asin/errors"
+require_relative "asin/responses"
+require_relative "asin/serialization"
+require_relative "asin/transport"
+require_relative "asin/endpoints"
+require_relative "asin/operations"
+require_relative "asin/client"
+
+# Official Ruby SDK for the Asin API (https://www.asin.dev).
+module Asin
+end

data/lib/asindotdev.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Lets Bundler auto-require the gem by its name.
+require_relative "asin"

data/sig/asin.rbs

@@ -0,0 +1,84 @@
+module Asin
+  VERSION: String
+  ENDPOINTS: Hash[String, Hash[Symbol, untyped]]
+
+  class Error < StandardError
+  end
+  class ConfigurationError < Error
+  end
+  class SerializationError < Error
+    attr_reader param: String?
+    def initialize: (String message, ?String? param) -> void
+  end
+  class TransportError < Error
+  end
+  class APIError < Error
+    attr_reader status: Integer
+    attr_reader error_message: String?
+    attr_reader response_body: untyped
+    attr_reader raw_response: RawResponse
+  end
+  class ResponseDecodingError < Error
+    attr_reader raw_response: RawResponse
+  end
+
+  class RawResponse < Struct[untyped]
+    attr_accessor status: Integer
+    attr_accessor headers: Hash[String, Array[String]]
+    attr_accessor content_type: String?
+    attr_accessor body: String
+  end
+
+  class JsonResponse
+    attr_reader data: untyped
+    attr_reader raw_response: RawResponse
+    def kind: () -> :json
+    def json?: () -> true
+    def binary?: () -> false
+  end
+  class BinaryResponse
+    attr_reader bytes: String
+    attr_reader content_type: String?
+    attr_reader raw_response: RawResponse
+    def kind: () -> :binary
+    def json?: () -> false
+    def binary?: () -> true
+    def save: (String path) -> Integer
+  end
+
+  class BatchResult < Struct[untyped]
+    attr_accessor index: Integer
+    attr_accessor value: untyped
+    attr_accessor error: StandardError?
+    def ok?: () -> bool
+  end
+
+  type response = JsonResponse | BinaryResponse
+  type request_options = { ?method: String, ?timeout: Numeric?, ?headers: Hash[String, String], ?max_retries: Integer }
+
+  module Operations
+    def check_product: (id: String, ?wait: bool, ?request_options: request_options?) -> JsonResponse
+    def delete_product: (id: String, ?request_options: request_options?) -> JsonResponse
+    def fetch_offers: (asin: String, ?marketplace: String, ?refresh: bool, ?request_options: request_options?) -> JsonResponse
+    def get_account: (?request_options: request_options?) -> JsonResponse
+    def get_asin_history: (asin: String, ?marketplace: String, ?days: Integer, ?request_options: request_options?) -> JsonResponse
+    def get_offers: (asin: String, ?marketplace: String, ?request_options: request_options?) -> JsonResponse
+    def get_product: (id: String, ?days: Integer, ?request_options: request_options?) -> JsonResponse
+    def list_products: (?asin: String, ?marketplace: String, ?filter: String, ?page: Integer, ?limit: Integer, ?request_options: request_options?) -> JsonResponse
+    def search_amazon: (query: String, ?marketplace: String, ?request_options: request_options?) -> JsonResponse
+    def track_product: (product: String, ?marketplace: String, ?target_price: Numeric, ?interval_minutes: Integer, ?wait: bool, ?request_options: request_options?) -> JsonResponse
+    def update_product: (id: String, ?target_price: Numeric, ?interval_minutes: Integer, ?alert_on_drop: bool, ?paused: bool, ?request_options: request_options?) -> JsonResponse
+  end
+
+  class Client
+    include Operations
+    DEFAULT_CONCURRENCY: Integer
+    MAX_RETRIES: Integer
+    RETRY_BACKOFF_FACTOR: Float
+    DEFAULT_RETRY_DELAY: Float
+    DEFAULT_TIMEOUT: Integer
+    def initialize: (?api_key: String?, ?base_url: String, ?timeout: Numeric?, ?headers: Hash[untyped, untyped], ?max_retries: Integer, ?retry_delay: Numeric, ?transport: untyped) -> void
+    def request: (String | Symbol method, String path, ?Hash[untyped, untyped]? params, ?timeout: Numeric?, ?headers: Hash[untyped, untyped]?, ?max_retries: Integer?) -> response
+    def batch: [I, T] (Enumerable[I] items, ?concurrency: Integer) { (I item) -> T } -> Array[BatchResult]
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: asindotdev
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Asin
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: Track Amazon prices and products with a scheduled watchlist, price history,
+  offers and alerts.
+email:
+- contact@asin.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- examples/README.md
+- examples/json.rb
+- examples/request.rb
+- lib/asin.rb
+- lib/asin/client.rb
+- lib/asin/endpoints.rb
+- lib/asin/errors.rb
+- lib/asin/operations.rb
+- lib/asin/responses.rb
+- lib/asin/serialization.rb
+- lib/asin/transport.rb
+- lib/asin/version.rb
+- lib/asindotdev.rb
+- sig/asin.rbs
+homepage: https://www.asin.dev
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/asindotdev/asin-ruby/issues
+  documentation_uri: https://www.asin.dev/docs
+  homepage_uri: https://www.asin.dev
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/asindotdev/asin-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Asin Amazon price tracking API.
+test_files: []