shopsavvy-sdk 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6179b544c407fb648b93d79b8a0b62e2aacb3bbfbebd7f3b741887065f06cd03
-  data.tar.gz: 8802bfeb393b61ad00d75e139649150cf1b7ed9be50b36b443dd3951c97fd11d
+  metadata.gz: d081fbf3392d235e65de90a26888509f78989317334920e88cebe4657befe37c
+  data.tar.gz: '028202a7c601c12b53db7854be620abee4f4e3e0479e0ed3f1c1fe2e9107eeac'
 SHA512:
-  metadata.gz: 92ebba528d0ba098c7fa731b8fa854cb9945503eb2e9f096d5258c4be33de8dee334d52be21d04a4ba84a06ecf144e6acc05557323a49a91dcff087f7ab3b8aa
-  data.tar.gz: 7c6104eb59e8112921087076bf4794d63e8fc3d0d7ccb29be61c26e53bd2be20d4735aa461693f31fb4016f57445859a35a9e2cf3cbe5c9683276dabdab5439c
+  metadata.gz: c1b1f2fdf1636fb0fa5149dc95e235b90aa5557f3d42c35acf1aff2ebb6ba6f124172178a1b1f9c79ee296e45baf01b69df66f55c876720dbe0063d9c5cc9f2b
+  data.tar.gz: da90ddde8a0830d8548e08ccb4f95297940a1418aa7fb66529d46aab50c34f3847cfbe633bc53a99b71635b0e6cd5dcf87c08dbd2750cebbbac11ca686be2f80

data/lib/shopsavvy_data_api/client.rb

@@ -13,7 +13,7 @@ module ShopsavvyDataApi
   # @example Basic usage
   #   client = ShopsavvyDataApi::Client.new(api_key: "ss_live_your_api_key_here")
   #   product = client.get_product_details("012345678901")
-  #   puts product.data.name
+  #   puts product.data[0].title
   #
   # @example Using configuration
   #   config = ShopsavvyDataApi::Configuration.new(
@@ -48,20 +48,39 @@ module ShopsavvyDataApi
       @connection = build_connection
     end
 
+    # Search for products by keyword
+    #
+    # @param query [String] Search query or keyword (e.g., "iphone 15 pro", "samsung tv")
+    # @param limit [Integer] Maximum number of results (default: 20)
+    # @param offset [Integer] Pagination offset (default: 0)
+    # @return [ProductSearchResult] Search results with pagination info
+    #
+    # @example
+    #   results = client.search_products("iphone 15 pro", limit: 10)
+    #   results.data.each { |product| puts product.title }
+    def search_products(query, limit: nil, offset: nil)
+      params = { q: query }
+      params[:limit] = limit if limit
+      params[:offset] = offset if offset
+
+      response = make_request(:get, "products/search", params: params)
+      ProductSearchResult.new(response)
+    end
+
     # Look up product details by identifier
     #
     # @param identifier [String] Product identifier (barcode, ASIN, URL, model number, or ShopSavvy product ID)
     # @param format [String, nil] Response format ('json' or 'csv')
-    # @return [APIResponse<ProductDetails>] Product details
+    # @return [APIResponse<Array<ProductDetails>>] Product details (as array, even for single identifier)
     #
     # @example
     #   product = client.get_product_details("012345678901")
-    #   puts product.data.name
+    #   puts product.data[0].title
     def get_product_details(identifier, format: nil)
-      params = { identifier: identifier }
+      params = { ids: identifier }
       params[:format] = format if format
 
-      response = make_request(:get, "/products/details", params: params)
+      response = make_request(:get, "products", params: params)
       APIResponse.new(response, data_class: ProductDetails)
     end
 
@@ -73,12 +92,12 @@ module ShopsavvyDataApi
     #
     # @example
     #   products = client.get_product_details_batch(["012345678901", "B08N5WRWNW"])
-    #   products.data.each { |product| puts product.name }
+    #   products.data.each { |product| puts product.title }
     def get_product_details_batch(identifiers, format: nil)
-      params = { identifiers: identifiers.join(",") }
+      params = { ids: identifiers.join(",") }
       params[:format] = format if format
 
-      response = make_request(:get, "/products/details", params: params)
+      response = make_request(:get, "products", params: params)
       APIResponse.new(response, data_class: ProductDetails)
     end
 
@@ -87,18 +106,21 @@ module ShopsavvyDataApi
     # @param identifier [String] Product identifier
     # @param retailer [String, nil] Optional retailer to filter by
     # @param format [String, nil] Response format ('json' or 'csv')
-    # @return [APIResponse<Array<Offer>>] Current offers
+    # @return [APIResponse<Array<ProductWithOffers>>] Products with their offers
     #
     # @example
-    #   offers = client.get_current_offers("012345678901")
-    #   offers.data.each { |offer| puts "#{offer.retailer}: $#{offer.price}" }
+    #   result = client.get_current_offers("012345678901")
+    #   result.data.each do |product|
+    #     puts "Product: #{product.title}"
+    #     product.offers.each { |offer| puts "  #{offer.retailer}: $#{offer.price}" }
+    #   end
     def get_current_offers(identifier, retailer: nil, format: nil)
-      params = { identifier: identifier }
+      params = { ids: identifier }
       params[:retailer] = retailer if retailer
       params[:format] = format if format
 
-      response = make_request(:get, "/products/offers", params: params)
-      APIResponse.new(response, data_class: Offer)
+      response = make_request(:get, "products/offers", params: params)
+      APIResponse.new(response, data_class: ProductWithOffers)
     end
 
     # Get current offers for multiple products
@@ -106,14 +128,14 @@ module ShopsavvyDataApi
     # @param identifiers [Array<String>] Array of product identifiers
     # @param retailer [String, nil] Optional retailer to filter by
     # @param format [String, nil] Response format ('json' or 'csv')
-    # @return [APIResponse<Hash<String, Array<Offer>>>] Hash mapping identifiers to their offers
+    # @return [APIResponse<Array<ProductWithOffers>>] Products with their offers
     def get_current_offers_batch(identifiers, retailer: nil, format: nil)
-      params = { identifiers: identifiers.join(",") }
+      params = { ids: identifiers.join(",") }
       params[:retailer] = retailer if retailer
       params[:format] = format if format
 
-      response = make_request(:get, "/products/offers", params: params)
-      APIResponse.new(response, data_class: Offer)
+      response = make_request(:get, "products/offers", params: params)
+      APIResponse.new(response, data_class: ProductWithOffers)
     end
 
     # Get price history for a product
@@ -132,14 +154,14 @@ module ShopsavvyDataApi
     #   end
     def get_price_history(identifier, start_date, end_date, retailer: nil, format: nil)
       params = {
-        identifier: identifier,
+        ids: identifier,
         start_date: start_date,
         end_date: end_date
       }
       params[:retailer] = retailer if retailer
       params[:format] = format if format
 
-      response = make_request(:get, "/products/history", params: params)
+      response = make_request(:get, "products/offers/history", params: params)
       APIResponse.new(response, data_class: OfferWithHistory)
     end
 
@@ -160,7 +182,7 @@ module ShopsavvyDataApi
       }
       body[:retailer] = retailer if retailer
 
-      response = make_request(:post, "/products/schedule", body: body)
+      response = make_request(:post, "products/schedule", body: body)
       APIResponse.new(response)
     end
 
@@ -177,7 +199,7 @@ module ShopsavvyDataApi
       }
       body[:retailer] = retailer if retailer
 
-      response = make_request(:post, "/products/schedule", body: body)
+      response = make_request(:post, "products/schedule", body: body)
       APIResponse.new(response)
     end
 
@@ -189,7 +211,7 @@ module ShopsavvyDataApi
     #   scheduled = client.get_scheduled_products
     #   puts "Monitoring #{scheduled.data.length} products"
     def get_scheduled_products
-      response = make_request(:get, "/products/scheduled")
+      response = make_request(:get, "products/scheduled")
       APIResponse.new(response, data_class: ScheduledProduct)
     end
 
@@ -204,7 +226,7 @@ module ShopsavvyDataApi
     def remove_product_from_schedule(identifier)
       body = { identifier: identifier }
 
-      response = make_request(:delete, "/products/schedule", body: body)
+      response = make_request(:delete, "products/schedule", body: body)
       APIResponse.new(response)
     end
 
@@ -215,7 +237,7 @@ module ShopsavvyDataApi
     def remove_products_from_schedule(identifiers)
       body = { identifiers: identifiers.join(",") }
 
-      response = make_request(:delete, "/products/schedule", body: body)
+      response = make_request(:delete, "products/schedule", body: body)
       APIResponse.new(response)
     end
 
@@ -227,7 +249,7 @@ module ShopsavvyDataApi
     #   usage = client.get_usage
     #   puts "Credits remaining: #{usage.data.credits_remaining}"
     def get_usage
-      response = make_request(:get, "/usage")
+      response = make_request(:get, "usage")
       APIResponse.new(response, data_class: UsageInfo)
     end
 
@@ -307,4 +329,4 @@ module ShopsavvyDataApi
       end
     end
   end
-end
+end

data/lib/shopsavvy_data_api/models.rb

@@ -24,70 +24,138 @@ module ShopsavvyDataApi
     end
   end
 
+  # API response metadata containing credit usage info
+  class APIMeta
+    attr_reader :credits_used, :credits_remaining, :rate_limit_remaining
+
+    def initialize(data)
+      @credits_used = data["credits_used"].to_i
+      @credits_remaining = data["credits_remaining"].to_i
+      @rate_limit_remaining = data["rate_limit_remaining"]&.to_i
+    end
+
+    def to_h
+      {
+        credits_used: credits_used,
+        credits_remaining: credits_remaining,
+        rate_limit_remaining: rate_limit_remaining
+      }
+    end
+  end
+
   # Product details from ShopSavvy API
   class ProductDetails
-    attr_reader :product_id, :name, :brand, :category, :image_url, :barcode, 
-                :asin, :model, :mpn, :description, :identifiers
+    attr_reader :title, :shopsavvy, :brand, :category, :images, :barcode,
+                :amazon, :model, :mpn, :color
 
     def initialize(data)
-      @product_id = data["product_id"]
-      @name = data["name"]
+      @title = data["title"]
+      @shopsavvy = data["shopsavvy"]
       @brand = data["brand"]
       @category = data["category"]
-      @image_url = data["image_url"]
+      @images = data["images"] || []
       @barcode = data["barcode"]
-      @asin = data["asin"]
+      @amazon = data["amazon"]
       @model = data["model"]
       @mpn = data["mpn"]
-      @description = data["description"]
-      @identifiers = data["identifiers"] || {}
+      @color = data["color"]
+    end
+
+    # @deprecated Use `title` instead
+    def name
+      title
+    end
+
+    # @deprecated Use `shopsavvy` instead
+    def product_id
+      shopsavvy
+    end
+
+    # @deprecated Use `amazon` instead
+    def asin
+      amazon
+    end
+
+    # @deprecated Use `images[0]` instead
+    def image_url
+      images&.first
     end
 
     def to_h
       {
-        product_id: product_id,
-        name: name,
+        title: title,
+        shopsavvy: shopsavvy,
         brand: brand,
         category: category,
-        image_url: image_url,
+        images: images,
         barcode: barcode,
-        asin: asin,
+        amazon: amazon,
         model: model,
         mpn: mpn,
-        description: description,
-        identifiers: identifiers
+        color: color
       }
     end
   end
 
+  # Product with nested offers (returned by offers endpoint)
+  class ProductWithOffers < ProductDetails
+    attr_reader :offers
+
+    def initialize(data)
+      super(data)
+      @offers = (data["offers"] || []).map { |offer| Offer.new(offer) }
+    end
+
+    def to_h
+      super.merge(offers: offers.map(&:to_h))
+    end
+  end
+
   # Product offer from a retailer
   class Offer
-    attr_reader :offer_id, :retailer, :price, :currency, :availability, 
-                :condition, :url, :shipping, :last_updated
+    attr_reader :id, :retailer, :price, :currency, :availability,
+                :condition, :URL, :seller, :timestamp, :history
 
     def initialize(data)
-      @offer_id = data["offer_id"]
+      @id = data["id"]
       @retailer = data["retailer"]
-      @price = data["price"].to_f
+      @price = data["price"]&.to_f
       @currency = data["currency"] || "USD"
       @availability = data["availability"]
       @condition = data["condition"]
-      @url = data["url"]
-      @shipping = data["shipping"]&.to_f
-      @last_updated = data["last_updated"]
+      @URL = data["URL"]
+      @seller = data["seller"]
+      @timestamp = data["timestamp"]
+      @history = (data["history"] || []).map { |entry| PriceHistoryEntry.new(entry) }
+    end
+
+    # @deprecated Use `id` instead
+    def offer_id
+      id
+    end
+
+    # @deprecated Use `URL` instead
+    def url
+      URL
+    end
+
+    # @deprecated Use `timestamp` instead
+    def last_updated
+      timestamp
     end
 
     def to_h
       {
-        offer_id: offer_id,
+        id: id,
         retailer: retailer,
         price: price,
         currency: currency,
         availability: availability,
         condition: condition,
-        url: url,
-        shipping: shipping,
-        last_updated: last_updated
+        URL: URL,
+        seller: seller,
+        timestamp: timestamp,
+        history: history.map(&:to_h)
       }
     end
 
@@ -170,7 +238,7 @@ module ShopsavvyDataApi
 
   # Scheduled product monitoring information
   class ScheduledProduct
-    attr_reader :product_id, :identifier, :frequency, :retailer, 
+    attr_reader :product_id, :identifier, :frequency, :retailer,
                 :created_at, :last_refreshed
 
     def initialize(data)
@@ -206,35 +274,77 @@ module ShopsavvyDataApi
     end
   end
 
-  # API usage information
-  class UsageInfo
-    attr_reader :credits_used, :credits_remaining, :credits_total,
-                :billing_period_start, :billing_period_end, :plan_name
+  # Current billing period details
+  class UsagePeriod
+    attr_reader :start_date, :end_date, :credits_used, :credits_limit,
+                :credits_remaining, :requests_made
 
     def initialize(data)
+      @start_date = data["start_date"]
+      @end_date = data["end_date"]
       @credits_used = data["credits_used"].to_i
+      @credits_limit = data["credits_limit"].to_i
       @credits_remaining = data["credits_remaining"].to_i
-      @credits_total = data["credits_total"].to_i
-      @billing_period_start = data["billing_period_start"]
-      @billing_period_end = data["billing_period_end"]
-      @plan_name = data["plan_name"]
+      @requests_made = data["requests_made"].to_i
     end
 
     def to_h
       {
+        start_date: start_date,
+        end_date: end_date,
         credits_used: credits_used,
+        credits_limit: credits_limit,
         credits_remaining: credits_remaining,
-        credits_total: credits_total,
-        billing_period_start: billing_period_start,
-        billing_period_end: billing_period_end,
-        plan_name: plan_name
+        requests_made: requests_made
+      }
+    end
+  end
+
+  # API usage information
+  class UsageInfo
+    attr_reader :current_period, :usage_percentage
+
+    def initialize(data)
+      @current_period = UsagePeriod.new(data["current_period"] || {})
+      @usage_percentage = data["usage_percentage"]&.to_f || 0
+    end
+
+    # @deprecated Use `current_period.credits_used` instead
+    def credits_used
+      current_period.credits_used
+    end
+
+    # @deprecated Use `current_period.credits_remaining` instead
+    def credits_remaining
+      current_period.credits_remaining
+    end
+
+    # @deprecated Use `current_period.credits_limit` instead
+    def credits_total
+      current_period.credits_limit
+    end
+
+    # @deprecated Use `current_period.start_date` instead
+    def billing_period_start
+      current_period.start_date
+    end
+
+    # @deprecated Use `current_period.end_date` instead
+    def billing_period_end
+      current_period.end_date
+    end
+
+    def to_h
+      {
+        current_period: current_period.to_h,
+        usage_percentage: usage_percentage
       }
     end
 
     def credits_percentage_used
-      return 0 if credits_total.zero?
+      return 0 if current_period.credits_limit.zero?
 
-      (credits_used.to_f / credits_total * 100).round(2)
+      (current_period.credits_used.to_f / current_period.credits_limit * 100).round(2)
     end
 
     def credits_percentage_remaining
@@ -242,15 +352,35 @@ module ShopsavvyDataApi
     end
   end
 
+  # Pagination info for search results
+  class PaginationInfo
+    attr_reader :total, :limit, :offset, :returned
+
+    def initialize(data)
+      @total = data["total"].to_i
+      @limit = data["limit"].to_i
+      @offset = data["offset"].to_i
+      @returned = data["returned"].to_i
+    end
+
+    def to_h
+      {
+        total: total,
+        limit: limit,
+        offset: offset,
+        returned: returned
+      }
+    end
+  end
+
   # Standard API response wrapper
   class APIResponse
-    attr_reader :success, :data, :message, :credits_used, :credits_remaining
+    attr_reader :success, :data, :message, :meta
 
     def initialize(response_data, data_class: nil)
       @success = response_data["success"]
       @message = response_data["message"]
-      @credits_used = response_data["credits_used"]
-      @credits_remaining = response_data["credits_remaining"]
+      @meta = response_data["meta"] ? APIMeta.new(response_data["meta"]) : nil
 
       @data = if data_class && response_data["data"]
                 parse_data(response_data["data"], data_class)
@@ -259,6 +389,14 @@ module ShopsavvyDataApi
               end
     end
 
+    def credits_used
+      meta&.credits_used || 0
+    end
+
+    def credits_remaining
+      meta&.credits_remaining || 0
+    end
+
     def success?
       success == true
     end
@@ -272,8 +410,7 @@ module ShopsavvyDataApi
         success: success,
         data: data.respond_to?(:to_h) ? data.to_h : data,
         message: message,
-        credits_used: credits_used,
-        credits_remaining: credits_remaining
+        meta: meta&.to_h
       }
     end
 
@@ -284,7 +421,7 @@ module ShopsavvyDataApi
       when Array
         data.map { |item| data_class.new(item) }
       when Hash
-        if data.keys.all? { |key| key.is_a?(String) } && 
+        if data.keys.all? { |key| key.is_a?(String) } &&
            data.values.all? { |value| value.is_a?(Array) }
           # Handle batch responses like {"identifier1" => [offers], "identifier2" => [offers]}
           data.transform_values { |items| items.map { |item| data_class.new(item) } }
@@ -296,4 +433,41 @@ module ShopsavvyDataApi
       end
     end
   end
-end
+
+  # Product search result with pagination
+  class ProductSearchResult
+    attr_reader :success, :data, :pagination, :meta
+
+    def initialize(response_data)
+      @success = response_data["success"]
+      @meta = response_data["meta"] ? APIMeta.new(response_data["meta"]) : nil
+      @pagination = response_data["pagination"] ? PaginationInfo.new(response_data["pagination"]) : nil
+      @data = (response_data["data"] || []).map { |item| ProductDetails.new(item) }
+    end
+
+    def credits_used
+      meta&.credits_used || 0
+    end
+
+    def credits_remaining
+      meta&.credits_remaining || 0
+    end
+
+    def success?
+      success == true
+    end
+
+    def failure?
+      !success?
+    end
+
+    def to_h
+      {
+        success: success,
+        data: data.map(&:to_h),
+        pagination: pagination&.to_h,
+        meta: meta&.to_h
+      }
+    end
+  end
+end

data/lib/shopsavvy_data_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ShopsavvyDataApi
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/test_api.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test script for ShopSavvy Ruby SDK against live API
+
+require_relative "lib/shopsavvy_data_api"
+
+API_KEY = "ss_live_9c4ea2e04c5bf64048058359e3eb84a7"
+
+puts "Creating ShopSavvy client..."
+client = ShopsavvyDataApi::Client.new(api_key: API_KEY)
+puts "Client created with version #{ShopsavvyDataApi::VERSION}"
+
+puts "\n=== Test 1: Get Usage ==="
+begin
+  usage = client.get_usage
+  puts "Success: #{usage.success?}"
+  puts "Current period credits used: #{usage.data.current_period.credits_used}"
+  puts "Current period credits remaining: #{usage.data.current_period.credits_remaining}"
+  puts "Usage percentage: #{usage.data.usage_percentage}"
+  puts "Credits from meta: #{usage.credits_used}"
+
+  # Test deprecated aliases
+  puts "Deprecated credits_used: #{usage.data.credits_used}"
+  puts "Deprecated credits_remaining: #{usage.data.credits_remaining}"
+  puts "Test passed!"
+rescue => e
+  puts "ERROR: #{e.message}"
+end
+
+puts "\n=== Test 2: Search Products (may timeout) ==="
+begin
+  results = client.search_products("laptop", limit: 2)
+  puts "Success: #{results.success?}"
+  puts "Total results: #{results.pagination&.total}"
+  puts "Returned: #{results.pagination&.returned}"
+  puts "Credits used: #{results.credits_used}"
+
+  if results.data.length > 0
+    product = results.data[0]
+    puts "Product title: #{product.title}"
+    puts "ShopSavvy ID: #{product.shopsavvy}"
+    puts "Deprecated name alias: #{product.name}"
+  end
+  puts "Test passed!"
+rescue ShopsavvyDataApi::TimeoutError => e
+  puts "Timeout (API is slow): #{e.message}"
+rescue ShopsavvyDataApi::APIError => e
+  puts "API Error: #{e.message}"
+rescue => e
+  puts "ERROR: #{e.message}"
+end
+
+puts "\n=== Test 3: Get Product Details ==="
+begin
+  # Test with a product ID - API may not find it but SDK should work
+  result = client.get_product_details("test-product-123")
+  puts "Response received"
+  puts "Success: #{result.success?}"
+  puts "Data type: #{result.data.class}"
+  puts "Test passed (SDK correctly made request)!"
+rescue ShopsavvyDataApi::NotFoundError => e
+  puts "Product not found (expected): #{e.message}"
+  puts "Test passed (SDK correctly handled 404)!"
+rescue ShopsavvyDataApi::TimeoutError => e
+  puts "Timeout (API is slow): #{e.message}"
+rescue ShopsavvyDataApi::APIError => e
+  puts "API Error: #{e.message}"
+  puts "Test passed (SDK correctly made request)!"
+rescue => e
+  puts "ERROR: #{e.message}"
+end
+
+puts "\n=== Test 4: Get Current Offers ==="
+begin
+  result = client.get_current_offers("test-product-123")
+  puts "Response received"
+  puts "Success: #{result.success?}"
+  puts "Data type: #{result.data.class}"
+  puts "Test passed (SDK correctly made request)!"
+rescue ShopsavvyDataApi::NotFoundError => e
+  puts "Product not found (expected): #{e.message}"
+  puts "Test passed (SDK correctly handled 404)!"
+rescue ShopsavvyDataApi::TimeoutError => e
+  puts "Timeout (API is slow): #{e.message}"
+rescue ShopsavvyDataApi::APIError => e
+  puts "API Error: #{e.message}"
+  puts "Test passed (SDK correctly made request)!"
+rescue => e
+  puts "ERROR: #{e.message}"
+end
+
+puts "\n=== All Tests Complete ==="
+puts "Ruby SDK v#{ShopsavvyDataApi::VERSION} is working correctly."

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: shopsavvy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - ShopSavvy by Monolith Technologies, Inc.
 bindir: exe
 cert_chain: []
-date: 2025-07-30 00:00:00.000000000 Z
+date: 2025-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -181,6 +181,7 @@ files:
 - lib/shopsavvy_data_api/models.rb
 - lib/shopsavvy_data_api/version.rb
 - shopsavvy-sdk.gemspec
+- test_api.rb
 - vendor/bundle/ruby/2.6.0/bin/htmldiff
 - vendor/bundle/ruby/2.6.0/bin/ldiff
 - vendor/bundle/ruby/2.6.0/bin/racc