shopsavvy-sdk 1.1.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d423e461903d6f1c9627b3b055a19e3e4ebc25a7145c6a0f6b117067fdf231a6
-  data.tar.gz: 939995fa50338ba615d54e71f87fa75d44023faf4ec2057c5fef93f5a638d403
+  metadata.gz: 991ec78b558c31d845cf0bf81fd057034062700a72d9fe629501f43e9b7396d5
+  data.tar.gz: fa4240edb2b6dd071cf70f74464dc691f310e0e083f21dc1c4f3053e548c22c7
 SHA512:
-  metadata.gz: 16e15e94cdee0d79b3ee20d2ecdf1a86c61cde8c4e2652b3171008fd415be2246611f0478c2dedcde1ed3d78c0e38a859122bd2667f36cde864f6f549a331cbd
-  data.tar.gz: ab8c59540a85e4e412659c4c64dc81f1812f8b339bcfcc6b69211fa39a33cc3dbeded890a72c9717f60fc1d053ae51c12a746722e51fc428bd013ffb63e122c5
+  metadata.gz: 8fda9e5b4b3ce912020aa3d65e4d42d2491b88b5836c33d4bc4d5eb25e52e3ff5b775bc2db938bfbc1a1030d6a64d30c5b751b31d9b251a1faa48c17bb16f47c
+  data.tar.gz: 8aeab34d7762693bf05a998f2a600c90390cf6dd097290dc5fab273e089a4df3953d5efe8755103eaff4df66dfdb8720adb573d2d10033551088b7dddb766370

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to the `shopsavvy-sdk` gem are recorded here.
+
+## 1.4.0
+
+### Changed (breaking for `get_price_history` callers)
+- `get_price_history` now returns `APIResponse<Array<ProductWithOfferHistory>>`: one entry
+  per product found (every product field), each with `offers`, each offer an
+  `OfferWithHistory` carrying its `history` points (newest first). It previously parsed each
+  product as an offer, so every offer and every history point in the response was lost.
+  Iterate `result.data.each { |product| product.offers.each { |offer| offer.history } }`.
+
+### Fixed
+- `Offer#url` and `Offer#to_h` raised `NameError` (a bare `URL` resolves as a constant).
+- `PriceHistoryEntry#price` keeps a missing price as `nil` instead of `0.0`;
+  `OfferWithHistory#min_price` / `#max_price` / `#average_price` ignore `nil` prices.
+- Scheduling actually reaches the API. `schedule_product_monitoring`,
+  `schedule_product_monitoring_batch`, `remove_product_from_schedule` and
+  `remove_products_from_schedule` sent a JSON body (`identifier(s)`, `frequency`, `retailer`)
+  via POST/DELETE to `/products/schedule`; the server reads only the query string, so every
+  call failed with a missing-`ids` error. They now send
+  `PUT /products/scheduled?ids=a,b&schedule=daily[&retailer=amazon.com]` and
+  `DELETE /products/scheduled?ids=a,b` with no body.
+- Scheduling responses are typed to what the server sends. `schedule_product_monitoring`,
+  `schedule_product_monitoring_batch` and `get_scheduled_products` return
+  `APIResponse<Array<ScheduledProduct>>`, and `ScheduledProduct` is now a `ProductDetails`
+  (every product field) plus `schedule` and `retailer`. It previously read `product_id`,
+  `identifier`, `frequency`, `created_at` and `last_refreshed` — keys the API never sends —
+  so every field was nil; `frequency` remains as a deprecated alias of `schedule`. On the
+  list, `schedule` is nil for an interval with no Data API label and `retailer` is nil when
+  the product is watched at every retailer. `remove_product(s)_from_schedule` return
+  `success?`, `message` and `meta`; the server sends no `data`.
+- `Offer#in_stock?`, `#out_of_stock?` and `#limited_stock?` compared `availability` against
+  `"in_stock"` / `"out_of_stock"` / `"limited_stock"`, which the API never sends, so they
+  were always false. They now match the API's tokens (`"in"`, `"out"`, `"limited"`), and
+  `#pre_order?`, `#coming_soon?` and `#discontinued?` were added. README availability
+  examples use the predicates.
+- Internal requests always put `params` in the query string (Faraday's `put`/`post` helpers
+  treat their second argument as the body).
+- The published gem no longer includes the previously-tracked `vendor/bundle` directory.
+
+### Added
+- RSpec suite (`bundle exec rspec`) covering price history against the real wire shape.
+
+## 1.3.0 (unreleased, folded into 1.4.0)
+- `get_price_history` sends `start` / `end` (it sent `start_date` / `end_date`, which the
+  REST endpoint rejected).
+- History points are read from `timestamp` (not `date`) and expose `currency`
+  (`nil` when the archived point has none — never assume USD).
+- `OfferWithHistory` reads `history` instead of a `price_history` key the API never sent.
+
+## 1.2.0
+- `score` documented as a 0-1 scale with a free-form `aspects` hash; `update_webhook`.
+
+## 1.1.0
+- Deals, reviews, batch lookup and webhook endpoints; expanded product fields.

data/README.md

@@ -143,7 +143,7 @@ puts "📊 Average price: $#{offers.data.map(&:price).sum / offers.data.length}"
 puts "💡 Potential savings: $#{most_expensive.price - cheapest.price}"
 
 # Filter by availability and condition
-in_stock_offers = offers.data.select { |offer| offer.availability == 'in_stock' }
+in_stock_offers = offers.data.select(&:in_stock?) # availability == "in"
 new_condition_offers = offers.data.select { |offer| offer.condition == 'new' }
 
 puts "✅ In-stock offers: #{in_stock_offers.length}"
@@ -159,7 +159,7 @@ target_offers = client.get_current_offers("012345678901", retailer: "target")
 bestbuy_offers = client.get_current_offers("012345678901", retailer: "bestbuy")
 
 # Compare specific retailers
-retailers = %w[amazon walmart target bestbuy]
+retailers = %w[amazon.com walmart.com target.com bestbuy.com]
 retailer_prices = {}
 
 retailers.each do |retailer|
@@ -193,7 +193,7 @@ batch_offers.data.each do |identifier, offers|
   puts "#{identifier}:"
   puts "  Best price: #{best_offer.retailer} - $#{best_offer.price}"
   puts "  Total offers: #{offers.length}"
-  puts "  In stock: #{offers.count { |o| o.availability == 'in_stock' }}"
+  puts "  In stock: #{offers.count(&:in_stock?)}"
   puts
 end
 ```
@@ -208,6 +208,8 @@ require 'date'
 end_date = Date.today
 start_date = end_date - 90
 
+# Returns one entry per product found. Each product carries its offers, and each
+# offer carries its `history` points, NEWEST FIRST: { timestamp, price, currency, availability }.
 history = client.get_price_history(
   "012345678901",
   start_date.strftime("%Y-%m-%d"),
@@ -217,10 +219,13 @@ history = client.get_price_history(
 puts "📈 90-Day Price Analysis"
 puts "=" * 50
 
-history.data.each do |offer|
-  next if offer.price_history.empty?
-  
-  prices = offer.price_history.map(&:price)
+product = history.data.first
+puts product.title
+
+product.offers.each do |offer|
+  next if offer.history.empty?
+
+  prices = offer.history.map(&:price) # newest first
   current_price = offer.price
   
   # Statistical analysis
@@ -228,9 +233,9 @@ history.data.each do |offer|
   min_price = prices.min
   max_price = prices.max
   
-  # Price trend calculation
-  recent_prices = prices.last(7)  # Last week
-  older_prices = prices.first([prices.length - 7, 1].max)
+  # Price trend calculation (history is newest first)
+  recent_prices = prices.first(7)
+  older_prices = prices.drop(7)
   
   trend = if recent_prices.any? && older_prices.any?
             recent_avg = recent_prices.sum.to_f / recent_prices.length
@@ -254,7 +259,7 @@ history.data.each do |offer|
   puts "  Range: $#{min_price} - $#{max_price}"
   puts "  Savings opportunity: $#{(current_price - min_price).round(2)}"
   puts "  Trend: #{trend}"
-  puts "  Data points: #{offer.price_history.length}"
+  puts "  Data points: #{offer.history.length}"
   puts
 end
 ```
@@ -273,11 +278,12 @@ retailers.each do |retailer|
     retailer: retailer
   )
   
-  next if history.data.empty?
-  
-  offer = history.data.first
-  if offer.price_history.any?
-    prices = offer.price_history.map(&:price)
+  product = history.data.first
+  next if product.nil? || product.offers.empty?
+
+  offer = product.offers.first
+  if offer.history.any?
+    prices = offer.history.map(&:price)
     historical_comparison[retailer] = {
       current: offer.price,
       average: prices.sum.to_f / prices.length,
@@ -305,15 +311,19 @@ end
 #### Schedule Monitoring
 ```ruby
 # Monitor daily across all retailers
+# Sends PUT /products/scheduled?ids=012345678901&schedule=daily
 result = client.schedule_product_monitoring("012345678901", "daily")
-puts "Scheduled: #{result.data['scheduled']}"
+# result.data is an Array<ScheduledProduct>: every product field plus `schedule`
+result.data.each { |product| puts "#{product.title} (#{product.shopsavvy}): #{product.schedule}" }
 
-# Monitor hourly at Amazon only
-client.schedule_product_monitoring(
-  "012345678901", 
-  "hourly", 
-  retailer: "amazon"
+# Monitor hourly at Amazon only (retailer is a domain)
+amazon_only = client.schedule_product_monitoring(
+  "012345678901",
+  "hourly",
+  retailer: "amazon.com"
 )
+amazon_only.data.first.retailer # => "amazon.com"
+puts "Credits used: #{amazon_only.credits_used}"
 
 # Schedule multiple products
 batch_result = client.schedule_product_monitoring_batch([
@@ -330,13 +340,14 @@ puts "Monitoring #{scheduled.data.length} products"
 
 scheduled.data.each do |product|
   retailer_info = product.retailer || "all retailers"
-  puts "#{product.identifier}: #{product.frequency} at #{retailer_info}"
-  puts "  Created: #{product.created_at}"
-  puts "  Last refreshed: #{product.last_refreshed}" if product.last_refreshed
+  # schedule is nil when the stored interval has no Data API label (e.g. a 4h interval)
+  puts "#{product.title} (#{product.shopsavvy}): #{product.schedule || 'custom interval'} at #{retailer_info}"
 end
 
-# Remove from schedule
-client.remove_product_from_schedule("012345678901")
+# Remove from schedule (DELETE /products/scheduled?ids=012345678901)
+# The response carries success, message and meta only (no data).
+result = client.remove_product_from_schedule("012345678901")
+puts result.message if result.success?
 
 # Remove multiple products
 client.remove_products_from_schedule(["012345678901", "B08N5WRWNW"])
@@ -575,7 +586,7 @@ class PriceAPI < Sinatra::Base
         success: true,
         product_id: identifier,
         period: "#{days} days",
-        data: history.data
+        data: history.data.map(&:to_h) # products, each with offers + history
       }.to_json
     rescue ShopsavvyDataApi::Error => e
       status 400
@@ -700,7 +711,7 @@ class CompetitiveAnalyzer
   def calculate_availability_score(offers)
     return 0 if offers.empty?
     
-    in_stock_count = offers.count { |offer| offer.availability == 'in_stock' }
+    in_stock_count = offers.count(&:in_stock?)
     (in_stock_count.to_f / offers.length * 100).round(1)
   end
 end
@@ -827,9 +838,10 @@ class MarketResearcher
     
     all_prices = []
     
-    history_data.each do |offer|
-      next if offer.price_history.empty?
-      all_prices.concat(offer.price_history.map(&:price))
+    history_data.each do |product|
+      product.offers.each do |offer|
+        all_prices.concat(offer.history.map(&:price))
+      end
     end
     
     return { average_price: 0, volatility: 0 } if all_prices.empty?

data/lib/shopsavvy_data_api/client.rb

@@ -145,24 +145,32 @@ module ShopsavvyDataApi
     # @param end_date [String] End date (YYYY-MM-DD format)
     # @param retailer [String, nil] Optional retailer to filter by
     # @param format [String, nil] Response format ('json' or 'csv')
-    # @return [APIResponse<Array<OfferWithHistory>>] Offers with price history
+    # @return [APIResponse<Array<ProductWithOfferHistory>>] One entry per product found, each
+    #   carrying its offers, each offer carrying its +history+ points (newest first)
     #
     # @example
-    #   history = client.get_price_history("012345678901", "2024-01-01", "2024-01-31")
-    #   history.data.each do |offer|
-    #     puts "#{offer.retailer}: #{offer.price_history.length} price points"
+    #   result = client.get_price_history("012345678901", "2024-01-01", "2024-01-31")
+    #   result.data.each do |product|
+    #     puts product.title
+    #     product.offers.each do |offer|
+    #       puts "  #{offer.retailer}: #{offer.history.length} price points, low $#{offer.min_price}"
+    #     end
     #   end
     def get_price_history(identifier, start_date, end_date, retailer: nil, format: nil)
+      # Wire params are :start/:end — what GET /products/offers/history reads,
+      # and what the OpenAPI spec and public docs document. The old
+      # :start_date/:end_date names came from the MCP tool's argument
+      # convention (a different interface entirely) and 400'd every call.
       params = {
         ids: identifier,
-        start_date: start_date,
-        end_date: end_date
+        start: start_date,
+        end: end_date
       }
       params[:retailer] = retailer if retailer
       params[:format] = format if format
 
       response = make_request(:get, "products/offers/history", params: params)
-      APIResponse.new(response, data_class: OfferWithHistory)
+      APIResponse.new(response, data_class: ProductWithOfferHistory)
     end
 
     # Schedule product monitoring
@@ -170,20 +178,14 @@ module ShopsavvyDataApi
     # @param identifier [String] Product identifier
     # @param frequency [String] How often to refresh ('hourly', 'daily', 'weekly')
     # @param retailer [String, nil] Optional retailer to monitor
-    # @return [APIResponse<Hash>] Scheduling confirmation
+    # @return [APIResponse<Array<ScheduledProduct>>] The scheduled products (every product
+    #   field plus +schedule+, and +retailer+ when one was given)
     #
     # @example
     #   result = client.schedule_product_monitoring("012345678901", "daily")
-    #   puts "Scheduled: #{result.data['scheduled']}"
+    #   result.data.each { |product| puts "#{product.title}: #{product.schedule}" }
     def schedule_product_monitoring(identifier, frequency, retailer: nil)
-      body = {
-        identifier: identifier,
-        frequency: frequency
-      }
-      body[:retailer] = retailer if retailer
-
-      response = make_request(:post, "products/schedule", body: body)
-      APIResponse.new(response)
+      schedule_products([identifier], frequency, retailer: retailer)
     end
 
     # Schedule monitoring for multiple products
@@ -191,25 +193,21 @@ module ShopsavvyDataApi
     # @param identifiers [Array<String>] Array of product identifiers
     # @param frequency [String] How often to refresh ('hourly', 'daily', 'weekly')
     # @param retailer [String, nil] Optional retailer to monitor
-    # @return [APIResponse<Array<Hash>>] Scheduling confirmation for all products
+    # @return [APIResponse<Array<ScheduledProduct>>] The scheduled products (every product
+    #   field plus +schedule+, and +retailer+ when one was given)
     def schedule_product_monitoring_batch(identifiers, frequency, retailer: nil)
-      body = {
-        identifiers: identifiers.join(","),
-        frequency: frequency
-      }
-      body[:retailer] = retailer if retailer
-
-      response = make_request(:post, "products/schedule", body: body)
-      APIResponse.new(response)
+      schedule_products(identifiers, frequency, retailer: retailer)
     end
 
     # Get all scheduled products
     #
-    # @return [APIResponse<Array<ScheduledProduct>>] List of scheduled products
+    # @return [APIResponse<Array<ScheduledProduct>>] Every scheduled product (product fields
+    #   plus +schedule+, which is nil for an interval with no Data API label, and +retailer+
+    #   when the schedule is limited to one retailer)
     #
     # @example
     #   scheduled = client.get_scheduled_products
-    #   puts "Monitoring #{scheduled.data.length} products"
+    #   scheduled.data.each { |product| puts "#{product.title}: #{product.schedule}" }
     def get_scheduled_products
       response = make_request(:get, "products/scheduled")
       APIResponse.new(response, data_class: ScheduledProduct)
@@ -218,26 +216,23 @@ module ShopsavvyDataApi
     # Remove product from monitoring schedule
     #
     # @param identifier [String] Product identifier to remove
-    # @return [APIResponse<Hash>] Removal confirmation
+    # @return [APIResponse] Removal confirmation: +success?+, +message+ and +meta+. The
+    #   server sends no +data+, so +data+ is always nil.
     #
     # @example
     #   result = client.remove_product_from_schedule("012345678901")
-    #   puts "Removed: #{result.data['removed']}"
+    #   puts result.message if result.success?
     def remove_product_from_schedule(identifier)
-      body = { identifier: identifier }
-
-      response = make_request(:delete, "products/schedule", body: body)
-      APIResponse.new(response)
+      remove_products_from_schedule([identifier])
     end
 
     # Remove multiple products from monitoring schedule
     #
     # @param identifiers [Array<String>] Array of product identifiers to remove
-    # @return [APIResponse<Array<Hash>>] Removal confirmation for all products
+    # @return [APIResponse] Removal confirmation: +success?+, +message+ and +meta+ (+data+ is nil)
     def remove_products_from_schedule(identifiers)
-      body = { identifiers: identifiers.join(",") }
-
-      response = make_request(:delete, "products/schedule", body: body)
+      # DELETE /products/scheduled reads only the `ids` query parameter.
+      response = make_request(:delete, "products/scheduled", params: { ids: identifiers.join(",") })
       APIResponse.new(response)
     end
 
@@ -297,12 +292,37 @@ module ShopsavvyDataApi
       make_request(:post, "webhooks/#{webhook_id}/test")
     end
 
+    # Update a webhook. All keyword arguments are optional, but at least one
+    # of url:, events:, or is_active: must be provided.
+    def update_webhook(webhook_id, url: nil, events: nil, is_active: nil)
+      if url.nil? && events.nil? && is_active.nil?
+        raise ArgumentError, "update_webhook requires at least one of url:, events:, or is_active:"
+      end
+      body = {}
+      body[:url] = url unless url.nil?
+      body[:events] = events unless events.nil?
+      body[:is_active] = is_active unless is_active.nil?
+      make_request(:put, "webhooks/#{webhook_id}", body: body)
+    end
+
     def delete_webhook(webhook_id)
       make_request(:delete, "webhooks/#{webhook_id}")
     end
 
     private
 
+    # PUT /products/scheduled reads ONLY query parameters (ids, schedule, retailer). This
+    # used to POST a JSON body of {identifier(s), frequency, retailer} to /products/schedule;
+    # the server ignores request bodies on this route, so every call failed with
+    # "An 'ids' query parameter is required" (and the frequency and retailer never arrived).
+    def schedule_products(identifiers, frequency, retailer: nil)
+      params = { ids: identifiers.join(","), schedule: frequency }
+      params[:retailer] = retailer if retailer
+
+      response = make_request(:put, "products/scheduled", params: params)
+      APIResponse.new(response, data_class: ScheduledProduct)
+    end
+
     def build_connection
       Faraday.new(
         url: config.base_url,
@@ -321,7 +341,11 @@ module ShopsavvyDataApi
     end
 
     def make_request(method, path, params: nil, body: nil)
-      response = @connection.public_send(method, path, params) do |req|
+      # run_request so that `params` is ALWAYS the query string. Faraday's verb helpers
+      # disagree about their second positional argument: get/delete treat it as query
+      # params, but post/put/patch treat it as the request BODY.
+      response = @connection.run_request(method, path, nil, nil) do |req|
+        req.params.update(params) if params
         req.body = body.to_json if body
       end
 

data/lib/shopsavvy_data_api/models.rb

@@ -44,6 +44,10 @@ module ShopsavvyDataApi
   end
 
   # Product details from ShopSavvy API
+  #
+  # score: expert quality scores on a 0-1 scale (multiply by 10 or 100 for
+  # display) — "overall", "customer", "professional", plus an "aspects" hash
+  # keyed by free-form aspect names from the product's professional reviews.
   class ProductDetails
     attr_reader :title, :shopsavvy, :brand, :category, :images, :barcode,
                 :amazon, :model, :mpn, :color,
@@ -147,7 +151,7 @@ module ShopsavvyDataApi
 
     # @deprecated Use `URL` instead
     def url
-      URL
+      @URL
     end
 
     # @deprecated Use `timestamp` instead
@@ -163,23 +167,39 @@ module ShopsavvyDataApi
         currency: currency,
         availability: availability,
         condition: condition,
-        URL: URL,
+        URL: @URL,
         seller: seller,
         timestamp: timestamp,
         history: history.map(&:to_h)
       }
     end
 
+    # Offer availability is one of the API's canonical tokens: "in", "out", "limited",
+    # "pre-order", "coming-soon" or "discontinued" (nil when unknown — the API omits it).
+    # These predicates used to compare against "in_stock" / "out_of_stock" /
+    # "limited_stock", which the API never sends, so they were always false.
     def in_stock?
-      availability == "in_stock"
+      availability == "in"
     end
 
     def out_of_stock?
-      availability == "out_of_stock"
+      availability == "out"
     end
 
     def limited_stock?
-      availability == "limited_stock"
+      availability == "limited"
+    end
+
+    def pre_order?
+      availability == "pre-order"
+    end
+
+    def coming_soon?
+      availability == "coming-soon"
+    end
+
+    def discontinued?
+      availability == "discontinued"
     end
 
     def new_condition?
@@ -195,93 +215,128 @@ module ShopsavvyDataApi
     end
   end
 
-  # Historical price data point
+  # Historical price data point.
+  #
+  # The timestamp field is +timestamp+, matching the parent Offer's own +timestamp+ and the
+  # real wire shape ({availability, price, timestamp}). Every SDK in the fleet read it from
+  # a "date" key — one the API has never sent — until 2026-08-10, so every entry in
+  # +offer.history+ carried a permanently-nil date next to a correct price and availability
+  # (ShopSavvy prospector-audit s28-t2-2 / s28-t2-3).
   class PriceHistoryEntry
-    attr_reader :date, :price, :availability
+    # currency is the ISO 4217 code `price` is denominated in. nil on an archived point with no
+    # recorded currency — never assume a missing value means USD
+    # (ShopSavvy prospector-audit d5-t3-1).
+    attr_reader :timestamp, :price, :currency, :availability
 
     def initialize(data)
-      @date = data["date"]
-      @price = data["price"].to_f
+      @timestamp = data["timestamp"]
+      @price = data["price"]&.to_f
+      @currency = data["currency"]
       @availability = data["availability"]
     end
 
     def to_h
       {
-        date: date,
+        timestamp: timestamp,
         price: price,
+        currency: currency,
         availability: availability
       }
     end
   end
 
-  # Offer with historical price data
+  # Offer returned by +get_price_history+, i.e. one carrying its +history+ array.
+  #
+  # This used to declare its OWN +price_history+ reader, populated from a "price_history"
+  # key the API has never sent — so it was always +[]+, and +min_price+/+max_price+/
+  # +average_price+ always returned nil, while the correctly-keyed +history+ inherited from
+  # Offer sat right next to it holding the real data. The SDK's own README and client
+  # docstring both documented the dead one, so the copy-pasteable example reported "0 price
+  # points" forever. Everything now reads +history+.
   class OfferWithHistory < Offer
-    attr_reader :price_history
-
-    def initialize(data)
-      super(data)
-      @price_history = (data["price_history"] || []).map { |entry| PriceHistoryEntry.new(entry) }
-    end
-
-    def to_h
-      super.merge(price_history: price_history.map(&:to_h))
-    end
-
     def min_price
-      return nil if price_history.empty?
+      return nil if history.empty?
 
-      price_history.map(&:price).min
+      history.map(&:price).compact.min
     end
 
     def max_price
-      return nil if price_history.empty?
+      return nil if history.empty?
 
-      price_history.map(&:price).max
+      history.map(&:price).compact.max
     end
 
     def average_price
-      return nil if price_history.empty?
+      prices = history.map(&:price).compact
+      return nil if prices.empty?
 
-      prices = price_history.map(&:price)
       prices.sum.to_f / prices.length
     end
   end
 
-  # Scheduled product monitoring information
-  class ScheduledProduct
-    attr_reader :product_id, :identifier, :frequency, :retailer,
-                :created_at, :last_refreshed
+  # One product in a +get_price_history+ response.
+  #
+  # GET /products/offers/history returns the same product-with-offers shape as the offers
+  # endpoint — one entry per requested product, carrying every product field — with each
+  # offer additionally carrying its +history+ array. +get_price_history+ used to parse each
+  # PRODUCT as if it were an offer (+OfferWithHistory+), so +id+/+retailer+/+price+ read keys
+  # a product never has and every offer and every history point in the response was
+  # silently dropped.
+  class ProductWithOfferHistory < ProductDetails
+    attr_reader :offers
+
+    def initialize(data)
+      super(data)
+      @offers = (data["offers"] || []).map { |offer| OfferWithHistory.new(offer) }
+    end
+
+    def to_h
+      super.merge(offers: offers.map(&:to_h))
+    end
+  end
+
+  # One product in a scheduling response: every product field (it IS a ProductDetails)
+  # plus the refresh +schedule+ and, when one is set, the +retailer+ it is limited to.
+  #
+  # Returned by both PUT /products/scheduled (+schedule_product_monitoring+ /
+  # +schedule_product_monitoring_batch+) and GET /products/scheduled
+  # (+get_scheduled_products+). The server builds each entry as
+  # +{ ...publicProduct, schedule, retailer? }+.
+  #
+  # +schedule+ is "hourly", "daily" or "weekly". On the list endpoint it is +nil+ when the
+  # stored refresh interval has no Data API label (e.g. a 4h/12h interval set from
+  # ShopSavvy Business). +retailer+ is +nil+ when the product is watched at every retailer.
+  #
+  # This class used to read +product_id+, +identifier+, +frequency+, +created_at+ and
+  # +last_refreshed+ — keys the API has never sent — so every field was nil.
+  class ScheduledProduct < ProductDetails
+    attr_reader :schedule, :retailer
 
     def initialize(data)
-      @product_id = data["product_id"]
-      @identifier = data["identifier"]
-      @frequency = data["frequency"]
+      super(data)
+      @schedule = data["schedule"]
       @retailer = data["retailer"]
-      @created_at = data["created_at"]
-      @last_refreshed = data["last_refreshed"]
+    end
+
+    # @deprecated Use `schedule` instead
+    def frequency
+      schedule
     end
 
     def to_h
-      {
-        product_id: product_id,
-        identifier: identifier,
-        frequency: frequency,
-        retailer: retailer,
-        created_at: created_at,
-        last_refreshed: last_refreshed
-      }
+      super.merge(schedule: schedule, retailer: retailer)
     end
 
     def hourly?
-      frequency == "hourly"
+      schedule == "hourly"
     end
 
     def daily?
-      frequency == "daily"
+      schedule == "daily"
     end
 
     def weekly?
-      frequency == "weekly"
+      schedule == "weekly"
     end
   end
 
@@ -509,6 +564,10 @@ module ShopsavvyDataApi
   end
 
   # TLDR product review
+  #
+  # scores: expert quality scores on a 0-1 scale (multiply by 10 or 100 for
+  # display) — "overall", "customer", "professional", plus an "aspects" hash
+  # keyed by free-form aspect names from the product's professional reviews.
   class TLDRReview
     attr_reader :slug, :headline, :pros, :cons, :bottom_line, :scores