shopsavvy-sdk 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4faa444cc609f529b67d86aa8bd5c14dd8e8119888039a9baffa9801105e178e
-  data.tar.gz: 5b61ec2bbc289153cffaef95cd36af9b3dfceb512f18b0a7f0a66222d2ccc4a4
+  metadata.gz: 6179b544c407fb648b93d79b8a0b62e2aacb3bbfbebd7f3b741887065f06cd03
+  data.tar.gz: 8802bfeb393b61ad00d75e139649150cf1b7ed9be50b36b443dd3951c97fd11d
 SHA512:
-  metadata.gz: 46aba76fa5844ac2d89217e2c6d647f2fcd75b5497b442d776b4f23efab1fab48dfdfbaf3e6a295abf93c333dd5856195947948efd8b762d100d1e95e161caa3
-  data.tar.gz: 3ed236f6d857dfe8600b5d3d5ee40e8bb8c6c16066f01df31b8a0f724fabbd3780dd24edfc0150a75c7ba7b03751eaecaf13664a7fc2453f41932a9c8f730f98
+  metadata.gz: 92ebba528d0ba098c7fa731b8fa854cb9945503eb2e9f096d5258c4be33de8dee334d52be21d04a4ba84a06ecf144e6acc05557323a49a91dcff087f7ab3b8aa
+  data.tar.gz: 7c6104eb59e8112921087076bf4794d63e8fc3d0d7ccb29be61c26e53bd2be20d4735aa461693f31fb4016f57445859a35a9e2cf3cbe5c9683276dabdab5439c

data/README.md

@@ -1,172 +1,316 @@
 # ShopSavvy Data API - Ruby SDK
 
-[![Gem Version](https://badge.fury.io/rb/shopsavvy_data_api.svg)](https://badge.fury.io/rb/shopsavvy_data_api)
-[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%202.7.0-red.svg)](https://www.ruby-lang.org/)
+[![Gem Version](https://badge.fury.io/rb/shopsavvy-sdk.svg)](https://badge.fury.io/rb/shopsavvy-sdk)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%202.6.0-red.svg)](https://www.ruby-lang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-shopsavvy.com-blue)](https://shopsavvy.com/data/documentation)
 
-Official Ruby SDK for the [ShopSavvy Data API](https://shopsavvy.com/data). Access product data, pricing information, and price history across thousands of retailers and millions of products.
+Official Ruby SDK for the [ShopSavvy Data API](https://shopsavvy.com/data). Access comprehensive product data, real-time pricing, and historical price trends across **thousands of retailers** and **millions of products**.
 
-## 🚀 Quick Start
-
-### Installation
-
-Add this line to your application's Gemfile:
+## ⚡ 30-Second Quick Start
 
 ```ruby
-gem 'shopsavvy_data_api'
+# Install
+gem install shopsavvy-sdk
+
+# Use
+require 'shopsavvy_data_api'
+client = ShopsavvyDataApi.new(api_key: 'ss_live_your_api_key_here')
+product = client.get_product_details('012345678901')
+puts "#{product.data.name} - Best price: $#{client.get_current_offers('012345678901').data.min_by(&:price).price}"
 ```
 
-And then execute:
+## 📊 Feature Comparison
 
-```bash
-bundle install
-```
+| Feature | Free Tier | Pro | Enterprise |
+|---------|-----------|-----|-----------|
+| **API Calls/Month** | 1,000 | 100,000 | Unlimited |
+| **Product Details** | ✅ | ✅ | ✅ |
+| **Real-time Pricing** | ✅ | ✅ | ✅ |
+| **Price History** | 30 days | 1 year | 5+ years |
+| **Bulk Operations** | 10/batch | 100/batch | 1000/batch |
+| **Retailer Coverage** | 50+ | 500+ | 1000+ |
+| **Rate Limiting** | 60/hour | 1000/hour | Custom |
+| **Support** | Community | Email | Phone + Dedicated |
 
-Or install it yourself as:
+## 🚀 Installation & Setup
 
+### Installation
+
+Add to your Gemfile:
+```ruby
+gem 'shopsavvy-sdk'
+```
+
+Or install directly:
 ```bash
-gem install shopsavvy_data_api
+gem install shopsavvy-sdk
 ```
 
 ### Get Your API Key
 
-1. Visit [shopsavvy.com/data](https://shopsavvy.com/data)
-2. Sign up for an account
-3. Choose a subscription plan
-4. Get your API key from the dashboard
+1. **Sign up**: Visit [shopsavvy.com/data](https://shopsavvy.com/data)
+2. **Choose plan**: Select based on your usage needs
+3. **Get API key**: Copy from your dashboard
+4. **Test**: Run the 30-second example above
 
-### Basic Usage
+### Environment Setup
 
 ```ruby
-require 'shopsavvy_data_api'
-
-# Initialize the client
-client = ShopsavvyDataApi.new(api_key: "ss_live_your_api_key_here")
+# For production, use environment variables
+ENV['SHOPSAVVY_API_KEY'] = 'ss_live_your_api_key_here'
 
-# Look up a product by barcode
-product = client.get_product_details("012345678901")
-puts product.data.name
-
-# Get current prices from all retailers
-offers = client.get_current_offers("012345678901")
-offers.data.each do |offer|
-  puts "#{offer.retailer}: $#{offer.price}"
-end
-
-# Get price history
-history = client.get_price_history(
-  "012345678901",
-  "2024-01-01", 
-  "2024-01-31"
-)
+# Initialize client
+client = ShopsavvyDataApi.new(api_key: ENV['SHOPSAVVY_API_KEY'])
 ```
 
-## 📖 API Reference
+## 📖 Complete API Reference
 
 ### Client Configuration
 
 ```ruby
-# Method 1: Simple initialization
+# Basic configuration
+client = ShopsavvyDataApi.new(
+  api_key: 'ss_live_your_api_key_here',
+  timeout: 30,  # Request timeout in seconds
+  base_url: 'https://api.shopsavvy.com/v1'  # Custom base URL
+)
+
+# Advanced configuration with retry logic
 client = ShopsavvyDataApi.new(
-  api_key: "ss_live_your_api_key_here",
-  timeout: 30,  # optional
-  base_url: "https://api.shopsavvy.com/v1"  # optional
+  api_key: 'ss_live_your_api_key_here',
+  timeout: 60,
+  retry_attempts: 3,
+  retry_delay: 1.0,
+  user_agent: 'MyApp/1.0.0'
 )
 
-# Method 2: Using configuration object
+# Configuration object approach
 config = ShopsavvyDataApi::Configuration.new(
-  api_key: "ss_live_your_api_key_here",
-  timeout: 60
+  api_key: 'ss_live_your_api_key_here',
+  timeout: 120,
+  debug: true  # Enable debug logging
 )
 client = ShopsavvyDataApi.with_config(config)
-
-# Method 3: Direct client instantiation
-client = ShopsavvyDataApi::Client.new(api_key: "ss_live_your_api_key_here")
 ```
 
 ### Product Lookup
 
 #### Single Product
 ```ruby
-# Look up by barcode, ASIN, URL, or model number
+# Look up by barcode, ASIN, URL, model number, or ShopSavvy ID
 product = client.get_product_details("012345678901")
 amazon_product = client.get_product_details("B08N5WRWNW")  
 url_product = client.get_product_details("https://www.amazon.com/dp/B08N5WRWNW")
+model_product = client.get_product_details("MQ023LL/A")  # iPhone model number
 
 puts "Product: #{product.data.name}"
 puts "Brand: #{product.data.brand}"
 puts "Category: #{product.data.category}"
+puts "ASIN: #{product.data.asin}" if product.data.asin
+puts "Model: #{product.data.model}" if product.data.model
+puts "Description: #{product.data.description}" if product.data.description
 ```
 
-#### Multiple Products
+#### Bulk Product Lookup
 ```ruby
-products = client.get_product_details_batch([
-  "012345678901",
-  "B08N5WRWNW",
-  "https://www.bestbuy.com/site/product/123456"
-])
+# Process up to 100 products at once (Pro plan)
+identifiers = [
+  "012345678901", "B08N5WRWNW", "045496590048",
+  "https://www.bestbuy.com/site/product/123456",
+  "MQ023LL/A", "SM-S911U"  # iPhone and Samsung model numbers
+]
+
+products = client.get_product_details_batch(identifiers)
 
 products.data.each do |product|
-  puts "#{product.name} by #{product.brand}"
+  puts "#{product.name} by #{product.brand} - #{product.category}"
+  puts "  Identifiers: #{product.identifiers}" if product.identifiers
+end
+
+# Handle potential errors in batch processing
+products.data.each_with_index do |product, index|
+  if product.nil?
+    puts "Failed to find product: #{identifiers[index]}"
+  else
+    puts "✓ Found: #{product.name}"
+  end
 end
 ```
 
-### Current Pricing
+### Real-Time Pricing
 
-#### All Retailers
+#### All Retailers Analysis
 ```ruby
 offers = client.get_current_offers("012345678901")
-puts "Found #{offers.data.length} offers"
+puts "Found #{offers.data.length} offers across retailers"
 
-# Sort by price
+# Advanced price analysis
 sorted_offers = offers.data.sort_by(&:price)
 cheapest = sorted_offers.first
-puts "Best price: #{cheapest.retailer} - $#{cheapest.price}"
+most_expensive = sorted_offers.last
+
+puts "💰 Best price: #{cheapest.retailer} - $#{cheapest.price}"
+puts "💸 Highest price: #{most_expensive.retailer} - $#{most_expensive.price}"
+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' }
+new_condition_offers = offers.data.select { |offer| offer.condition == 'new' }
+
+puts "✅ In-stock offers: #{in_stock_offers.length}"
+puts "🆕 New condition: #{new_condition_offers.length}"
 ```
 
-#### Specific Retailer
+#### Retailer-Specific Queries
 ```ruby
+# Major retailers
 amazon_offers = client.get_current_offers("012345678901", retailer: "amazon")
+walmart_offers = client.get_current_offers("012345678901", retailer: "walmart")
 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]
+retailer_prices = {}
+
+retailers.each do |retailer|
+  offers = client.get_current_offers("012345678901", retailer: retailer)
+  if offers.data.any?
+    best_offer = offers.data.min_by(&:price)
+    retailer_prices[retailer] = best_offer.price
+  end
+end
+
+puts "Retailer price comparison:"
+retailer_prices.sort_by { |_, price| price }.each do |retailer, price|
+  puts "  #{retailer.capitalize}: $#{price}"
+end
 ```
 
-#### Multiple Products
+#### Bulk Price Monitoring
 ```ruby
-batch_offers = client.get_current_offers_batch([
-  "012345678901",
-  "B08N5WRWNW"
-])
+# Monitor multiple products simultaneously
+product_list = [
+  "012345678901", "B08N5WRWNW", "045496590048",
+  "B07XJ8C8F5", "B09G9FPHY6"
+]
+
+batch_offers = client.get_current_offers_batch(product_list)
 
 batch_offers.data.each do |identifier, offers|
-  puts "#{identifier}: #{offers.length} offers"
+  next if offers.empty?
+  
+  best_offer = offers.min_by(&:price)
+  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
 end
 ```
 
-### Price History
+### Historical Price Analysis
 
+#### Comprehensive Price Trends
 ```ruby
-# Get 30 days of price history
+require 'date'
+
+# Get 90 days of price history for detailed analysis
+end_date = Date.today
+start_date = end_date - 90
+
 history = client.get_price_history(
   "012345678901",
-  "2024-01-01",
-  "2024-01-31"
+  start_date.strftime("%Y-%m-%d"),
+  end_date.strftime("%Y-%m-%d")
 )
 
+puts "📈 90-Day Price Analysis"
+puts "=" * 50
+
 history.data.each do |offer|
-  puts "#{offer.retailer}:"
-  puts "  Current price: $#{offer.price}"
-  puts "  Historical data points: #{offer.price_history.length}"
-  puts "  Average price: $#{offer.average_price.round(2)}" if offer.average_price
-  puts "  Price range: $#{offer.min_price} - $#{offer.max_price}"
+  next if offer.price_history.empty?
+  
+  prices = offer.price_history.map(&:price)
+  current_price = offer.price
+  
+  # Statistical analysis
+  avg_price = prices.sum.to_f / prices.length
+  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)
+  
+  trend = if recent_prices.any? && older_prices.any?
+            recent_avg = recent_prices.sum.to_f / recent_prices.length
+            older_avg = older_prices.sum.to_f / older_prices.length
+            change_pct = ((recent_avg - older_avg) / older_avg * 100).round(1)
+            
+            if change_pct > 5
+              "📈 Rising (+#{change_pct}%)"
+            elsif change_pct < -5
+              "📉 Falling (#{change_pct}%)"
+            else
+              "📊 Stable (#{change_pct}%)"
+            end
+          else
+            "📊 Insufficient data"
+          end
+  
+  puts "🏪 #{offer.retailer.upcase}"
+  puts "  Current: $#{current_price}"
+  puts "  Average: $#{avg_price.round(2)}"
+  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
 end
+```
 
-# Get retailer-specific price history
-amazon_history = client.get_price_history(
-  "012345678901",
-  "2024-01-01",
-  "2024-01-31",
-  retailer: "amazon"
-)
+#### Retailer-Specific Historical Analysis
+```ruby
+# Compare price history across major retailers
+retailers = %w[amazon walmart target bestbuy]
+historical_comparison = {}
+
+retailers.each do |retailer|
+  history = client.get_price_history(
+    "012345678901",
+    "2024-01-01",
+    "2024-12-31",
+    retailer: retailer
+  )
+  
+  next if history.data.empty?
+  
+  offer = history.data.first
+  if offer.price_history.any?
+    prices = offer.price_history.map(&:price)
+    historical_comparison[retailer] = {
+      current: offer.price,
+      average: prices.sum.to_f / prices.length,
+      lowest: prices.min,
+      highest: prices.max,
+      volatility: prices.max - prices.min
+    }
+  end
+end
+
+puts "Retailer Historical Comparison:"
+historical_comparison.each do |retailer, data|
+  puts "#{retailer.capitalize}:"
+  puts "  Current: $#{data[:current]}"
+  puts "  Average: $#{data[:average].round(2)}"
+  puts "  Best ever: $#{data[:lowest]}"
+  puts "  Worst: $#{data[:highest]}"
+  puts "  Volatility: $#{data[:volatility].round(2)}"
+  puts
+end
 ```
 
 ### Product Monitoring
@@ -316,248 +460,477 @@ response_hash = product.to_h
 puts response_hash[:data][:name]
 ```
 
-## 💡 Examples
+## 🚀 Production Deployment
+
+### Ruby on Rails Integration
 
-### Price Comparison Tool
 ```ruby
-def compare_prices(client, identifier)
-  offers = client.get_current_offers(identifier)
-  
-  if offers.data.empty?
-    puts "No offers found"
-    return
+# Gemfile
+gem 'shopsavvy-sdk'
+gem 'sidekiq'  # For background jobs
+
+# config/application.rb
+config.shopsavvy_api_key = Rails.application.credentials.shopsavvy_api_key
+
+# app/services/price_tracking_service.rb
+class PriceTrackingService
+  def initialize
+    @client = ShopsavvyDataApi.new(
+      api_key: Rails.application.config.shopsavvy_api_key,
+      timeout: 60
+    )
   end
+
+  def track_product(product_id, target_price)
+    # Schedule monitoring
+    @client.schedule_product_monitoring(product_id, 'daily')
+    
+    # Create local tracking record
+    PriceAlert.create!(
+      product_identifier: product_id,
+      target_price: target_price,
+      status: 'active'
+    )
+  end
+
+  def check_price_alerts
+    PriceAlert.active.find_each do |alert|
+      CheckPriceAlertJob.perform_later(alert.id)
+    end
+  end
+end
+
+# app/jobs/check_price_alert_job.rb
+class CheckPriceAlertJob < ApplicationJob
+  queue_as :default
   
-  sorted_offers = offers.data.sort_by(&:price)
-  cheapest = sorted_offers.first
-  most_expensive = sorted_offers.last
-  
-  puts "🏆 Best price: #{cheapest.retailer} - $#{cheapest.price}"
-  puts "💸 Highest price: #{most_expensive.retailer} - $#{most_expensive.price}"
-  puts "💰 Potential savings: $#{most_expensive.price - cheapest.price}"
-  
-  {
-    best_offer: cheapest,
-    worst_offer: most_expensive,
-    savings: most_expensive.price - cheapest.price
-  }
+  def perform(alert_id)
+    alert = PriceAlert.find(alert_id)
+    client = ShopsavvyDataApi.new(api_key: Rails.application.config.shopsavvy_api_key)
+    
+    offers = client.get_current_offers(alert.product_identifier)
+    best_offer = offers.data.min_by(&:price)
+    
+    if best_offer && best_offer.price <= alert.target_price
+      # Send notification
+      PriceAlertMailer.target_reached(alert, best_offer).deliver_now
+      alert.update!(status: 'triggered', triggered_at: Time.current)
+    end
+  rescue ShopsavvyDataApi::Error => e
+    Rails.logger.error "ShopSavvy API error: #{e.message}"
+    # Optionally retry or alert administrators
+  end
 end
+```
 
-# Usage
-client = ShopsavvyDataApi.new(api_key: "your_api_key")
-comparison = compare_prices(client, "012345678901")
+### Sinatra Microservice
+
+```ruby
+# app.rb
+require 'sinatra'
+require 'json'
+require 'shopsavvy_data_api'
+
+class PriceAPI < Sinatra::Base
+  configure do
+    set :shopsavvy_client, ShopsavvyDataApi.new(
+      api_key: ENV['SHOPSAVVY_API_KEY'],
+      timeout: 30
+    )
+  end
+
+  before do
+    content_type :json
+  end
+
+  get '/api/product/:identifier/price' do
+    identifier = params[:identifier]
+    
+    begin
+      offers = settings.shopsavvy_client.get_current_offers(identifier)
+      
+      {
+        success: true,
+        product_id: identifier,
+        offers: offers.data.map do |offer|
+          {
+            retailer: offer.retailer,
+            price: offer.price,
+            availability: offer.availability,
+            condition: offer.condition,
+            url: offer.url
+          }
+        end,
+        best_price: offers.data.min_by(&:price)&.price,
+        credits_remaining: offers.credits_remaining
+      }.to_json
+    rescue ShopsavvyDataApi::Error => e
+      status 400
+      { success: false, error: e.message }.to_json
+    end
+  end
+
+  get '/api/product/:identifier/history' do
+    identifier = params[:identifier]
+    days = (params[:days] || 30).to_i
+    
+    end_date = Date.today
+    start_date = end_date - days
+    
+    begin
+      history = settings.shopsavvy_client.get_price_history(
+        identifier,
+        start_date.strftime('%Y-%m-%d'),
+        end_date.strftime('%Y-%m-%d')
+      )
+      
+      {
+        success: true,
+        product_id: identifier,
+        period: "#{days} days",
+        data: history.data
+      }.to_json
+    rescue ShopsavvyDataApi::Error => e
+      status 400
+      { success: false, error: e.message }.to_json
+    end
+  end
+end
 ```
 
-### Price Alert System
+### Background Processing with Sidekiq
+
 ```ruby
-def setup_price_alert(client, identifier, target_price)
-  # Schedule daily monitoring
-  client.schedule_product_monitoring(identifier, "daily")
-  
-  # Check current prices
-  offers = client.get_current_offers(identifier)
-  best_offer = offers.data.min_by(&:price)
-  
-  if best_offer.price <= target_price
-    puts "🎉 Target price reached!"
-    puts "💸 #{best_offer.retailer}: $#{best_offer.price}"
-    puts "🔗 Buy now: #{best_offer.url}"
-    true
-  else
-    puts "⏰ Monitoring #{identifier}"
-    puts "💰 Current best: $#{best_offer.price} (target: $#{target_price})"
-    puts "📈 Need $#{(best_offer.price - target_price).round(2)} price drop"
-    false
+# lib/price_monitor.rb
+class PriceMonitor
+  include Sidekiq::Worker
+  sidekiq_options retry: 3, backtrace: true
+
+  def perform(product_ids)
+    client = ShopsavvyDataApi.new(api_key: ENV['SHOPSAVVY_API_KEY'])
+    
+    product_ids.each do |product_id|
+      begin
+        # Get current prices
+        offers = client.get_current_offers(product_id)
+        next if offers.data.empty?
+
+        # Store in database or cache
+        best_price = offers.data.min_by(&:price).price
+        Redis.current.setex("price:#{product_id}", 3600, best_price)
+        
+        # Check for alerts
+        check_price_alerts(product_id, best_price)
+        
+      rescue ShopsavvyDataApi::RateLimitError => e
+        # Exponential backoff
+        self.class.perform_in(2 ** sidekiq_options['retry_count'], [product_id])
+        raise e
+      rescue ShopsavvyDataApi::Error => e
+        logger.error "API error for #{product_id}: #{e.message}"
+      end
+    end
+  end
+
+  private
+
+  def check_price_alerts(product_id, current_price)
+    # Implementation for checking and triggering alerts
   end
 end
 
-# Usage
-client = ShopsavvyDataApi.new(api_key: "your_api_key")
-setup_price_alert(client, "012345678901", 299.99)
+# Schedule regular monitoring
+PriceMonitor.perform_async(['012345678901', 'B08N5WRWNW'])
 ```
 
-### Historical Price Analysis
+## 💡 Real-World Use Cases
+
+### E-commerce Price Intelligence
 ```ruby
-require 'date'
+# Comprehensive competitive analysis tool
+class CompetitiveAnalyzer
+  def initialize(api_key)
+    @client = ShopsavvyDataApi.new(api_key: api_key)
+  end
 
-def analyze_price_trends(client, identifier, days = 30)
-  end_date = Date.today
-  start_date = end_date - days
-  
-  history = client.get_price_history(
-    identifier,
-    start_date.strftime("%Y-%m-%d"),
-    end_date.strftime("%Y-%m-%d")
-  )
-  
-  analysis = {}
-  
-  history.data.each do |offer|
-    next if offer.price_history.empty?
+  def analyze_market(product_ids, competitors = %w[amazon walmart target bestbuy])
+    analysis = {}
     
-    prices = offer.price_history.map(&:price)
+    product_ids.each do |product_id|
+      product_analysis = analyze_product_competition(product_id, competitors)
+      analysis[product_id] = product_analysis
+    end
     
-    # Calculate trend
-    recent_prices = prices.last(7)  # Last week
-    older_prices = prices.first(prices.length - 7)  # Everything else
+    generate_competitive_report(analysis)
+  end
+
+  private
+
+  def analyze_product_competition(product_id, competitors)
+    # Get product details
+    product = @client.get_product_details(product_id)
     
-    trend = if recent_prices.length > 0 && older_prices.length > 0
-              recent_avg = recent_prices.sum.to_f / recent_prices.length
-              older_avg = older_prices.sum.to_f / older_prices.length
-              recent_avg > older_avg ? "📈 Rising" : "📉 Falling"
-            else
-              "📊 Insufficient data"
-            end
+    # Get current offers from all retailers
+    all_offers = @client.get_current_offers(product_id)
+    
+    # Filter by target competitors
+    competitor_offers = all_offers.data.select do |offer|
+      competitors.include?(offer.retailer.downcase)
+    end
+    
+    # Price analysis
+    prices = competitor_offers.map(&:price)
     
-    analysis[offer.retailer] = {
-      current_price: offer.price,
-      average_price: offer.average_price,
-      min_price: offer.min_price,
-      max_price: offer.max_price,
-      data_points: offer.price_history.length,
-      trend: trend
+    {
+      product_name: product.data.name,
+      brand: product.data.brand,
+      total_offers: all_offers.data.length,
+      competitor_offers: competitor_offers.length,
+      price_range: {
+        min: prices.min,
+        max: prices.max,
+        average: prices.sum.to_f / prices.length
+      },
+      market_position: calculate_market_position(competitor_offers),
+      availability_score: calculate_availability_score(competitor_offers)
     }
   end
-  
-  analysis
+
+  def calculate_market_position(offers)
+    return 'No data' if offers.empty?
+    
+    prices = offers.map(&:price).sort
+    median_price = prices[prices.length / 2]
+    
+    case median_price
+    when 0..50 then 'Budget'
+    when 50..200 then 'Mid-range'
+    when 200..500 then 'Premium'
+    else 'Luxury'
+    end
+  end
+
+  def calculate_availability_score(offers)
+    return 0 if offers.empty?
+    
+    in_stock_count = offers.count { |offer| offer.availability == 'in_stock' }
+    (in_stock_count.to_f / offers.length * 100).round(1)
+  end
 end
 
 # Usage
-client = ShopsavvyDataApi.new(api_key: "your_api_key")
-trends = analyze_price_trends(client, "012345678901", 60)
-
-trends.each do |retailer, data|
-  puts "#{retailer}:"
-  puts "  Current: $#{data[:current_price]}"
-  puts "  Average: $#{data[:average_price].round(2)}"
-  puts "  Range: $#{data[:min_price]} - $#{data[:max_price]}"
-  puts "  Trend: #{data[:trend]}"
-  puts
-end
+analyzer = CompetitiveAnalyzer.new(ENV['SHOPSAVVY_API_KEY'])
+report = analyzer.analyze_market([
+  '012345678901', 'B08N5WRWNW', '045496590048'
+])
 ```
 
-### Bulk Product Monitoring
+### Inventory Management Integration
 ```ruby
-def setup_bulk_monitoring(client, identifiers, frequency = "daily")
-  # Schedule all products
-  result = client.schedule_product_monitoring_batch(identifiers, frequency)
-  
-  successful = []
-  failed = []
-  
-  result.data.each do |item|
-    if item["scheduled"]
-      successful << item["identifier"]
-    else
-      failed << item["identifier"]
+# Integration with inventory management system
+class InventoryPriceManager
+  def initialize(api_key)
+    @client = ShopsavvyDataApi.new(api_key: api_key)
+  end
+
+  def update_competitive_pricing(inventory_items)
+    pricing_updates = []
+    
+    inventory_items.each do |item|
+      next unless item.competitor_tracking_enabled?
+      
+      begin
+        # Get current market prices
+        offers = @client.get_current_offers(item.barcode)
+        next if offers.data.empty?
+        
+        # Calculate competitive price point
+        competitor_prices = offers.data.map(&:price)
+        market_analysis = analyze_market_prices(competitor_prices)
+        
+        suggested_price = calculate_competitive_price(
+          item.cost_price,
+          market_analysis,
+          item.target_margin
+        )
+        
+        pricing_updates << {
+          item_id: item.id,
+          current_price: item.selling_price,
+          suggested_price: suggested_price,
+          market_analysis: market_analysis,
+          reasoning: generate_pricing_reasoning(item, market_analysis, suggested_price)
+        }
+        
+      rescue ShopsavvyDataApi::Error => e
+        Rails.logger.error "Pricing update failed for #{item.id}: #{e.message}"
+        next
+      end
     end
+    
+    pricing_updates
   end
-  
-  puts "✅ Successfully scheduled: #{successful.length} products"
-  puts "❌ Failed to schedule: #{failed.length} products"
-  
-  if failed.any?
-    puts "Failed products:"
-    failed.each { |identifier| puts "  - #{identifier}" }
+
+  private
+
+  def analyze_market_prices(prices)
+    sorted_prices = prices.sort
+    {
+      min: sorted_prices.first,
+      max: sorted_prices.last,
+      median: sorted_prices[sorted_prices.length / 2],
+      average: prices.sum.to_f / prices.length,
+      percentile_25: sorted_prices[(sorted_prices.length * 0.25).round],
+      percentile_75: sorted_prices[(sorted_prices.length * 0.75).round]
+    }
   end
-  
-  { successful: successful, failed: failed }
-end
 
-# Usage
-client = ShopsavvyDataApi.new(api_key: "your_api_key")
-products_to_monitor = [
-  "012345678901",
-  "B08N5WRWNW", 
-  "045496596439"
-]
-setup_bulk_monitoring(client, products_to_monitor, "daily")
+  def calculate_competitive_price(cost_price, market_analysis, target_margin)
+    min_price = cost_price * (1 + target_margin)
+    competitive_price = market_analysis[:percentile_25] * 0.95  # 5% under 25th percentile
+    
+    [min_price, competitive_price].max.round(2)
+  end
+end
 ```
 
-### Rails Integration Example
+### Market Research Analytics
 ```ruby
-# app/models/price_tracker.rb
-class PriceTracker < ApplicationRecord
-  validates :product_identifier, presence: true
-  validates :target_price, presence: true, numericality: { greater_than: 0 }
-  
-  def self.check_all_alerts
-    client = ShopsavvyDataApi.new(api_key: Rails.application.credentials.shopsavvy_api_key)
+# Advanced market research and trend analysis
+class MarketResearcher
+  def initialize(api_key)
+    @client = ShopsavvyDataApi.new(api_key: api_key)
+  end
+
+  def research_category_trends(product_categories, time_periods)
+    research_report = {}
     
-    PriceTracker.active.find_each do |tracker|
-      tracker.check_price_alert(client)
+    product_categories.each do |category, product_list|
+      category_data = analyze_category_trends(product_list, time_periods)
+      research_report[category] = category_data
     end
+    
+    generate_market_intelligence_report(research_report)
   end
-  
-  def check_price_alert(client)
-    offers = client.get_current_offers(product_identifier)
-    best_offer = offers.data.min_by(&:price)
+
+  def track_seasonal_patterns(product_id, months = 12)
+    patterns = {}
     
-    if best_offer && best_offer.price <= target_price
-      # Send notification
-      PriceAlertMailer.target_price_reached(self, best_offer).deliver_later
-      update!(alert_triggered: true, triggered_at: Time.current)
+    (0...months).each do |month_offset|
+      end_date = Date.today - (month_offset * 30)
+      start_date = end_date - 30
+      
+      history = @client.get_price_history(
+        product_id,
+        start_date.strftime('%Y-%m-%d'),
+        end_date.strftime('%Y-%m-%d')
+      )
+      
+      month_name = end_date.strftime('%B %Y')
+      patterns[month_name] = analyze_monthly_patterns(history.data)
     end
-  rescue ShopsavvyDataApi::Error => e
-    Rails.logger.error "ShopSavvy API error for tracker #{id}: #{e.message}"
+    
+    identify_seasonal_trends(patterns)
   end
-end
 
-# Usage in rake task or background job
-# bin/rails runner "PriceTracker.check_all_alerts"
+  private
+
+  def analyze_monthly_patterns(history_data)
+    return { average_price: 0, volatility: 0 } if history_data.empty?
+    
+    all_prices = []
+    
+    history_data.each do |offer|
+      next if offer.price_history.empty?
+      all_prices.concat(offer.price_history.map(&:price))
+    end
+    
+    return { average_price: 0, volatility: 0 } if all_prices.empty?
+    
+    average = all_prices.sum.to_f / all_prices.length
+    variance = all_prices.map { |price| (price - average) ** 2 }.sum / all_prices.length
+    
+    {
+      average_price: average.round(2),
+      volatility: Math.sqrt(variance).round(2),
+      price_points: all_prices.length
+    }
+  end
+end
 ```
 
-## 🛠️ Development
+## 🛠️ Development & Testing
 
-### Installing for Development
+### Local Development Setup
 
-```bash
-git clone https://github.com/shopsavvy/ruby-sdk
-cd ruby-sdk
+```ruby
+# Clone the repository
+git clone https://github.com/shopsavvy/sdk-ruby.git
+cd sdk-ruby
+
+# Install dependencies
 bundle install
-```
 
-### Running Tests
+# Set up environment variables
+echo 'SHOPSAVVY_API_KEY=ss_test_your_test_key_here' > .env
 
-```bash
-# Run all tests
+# Run tests
 bundle exec rspec
 
-# Run with coverage
-bundle exec rspec --format documentation
-
-# Run specific test file
-bundle exec rspec spec/client_spec.rb
+# Run linting
+bundle exec rubocop
 
-# Run with verbose output
-bundle exec rspec --format documentation --color
+# Generate documentation
+bundle exec yard doc
 ```
 
-### Code Quality
-
-```bash
-# Linting
-bundle exec rubocop
+### Testing Your Integration
 
-# Auto-fix issues
-bundle exec rubocop -A
+```ruby
+# Create a test script
+require 'shopsavvy_data_api'
 
-# Type checking (if using Sorbet)
-bundle exec srb tc
+# Use test API key (starts with ss_test_)
+client = ShopsavvyDataApi.new(api_key: 'ss_test_your_test_key_here')
 
-# Generate documentation
-bundle exec yard doc
+# Test basic functionality
+begin
+  # Test product lookup
+  product = client.get_product_details('012345678901')
+  puts "✅ Product lookup: #{product.data.name}"
+  
+  # Test current offers
+  offers = client.get_current_offers('012345678901')
+  puts "✅ Current offers: #{offers.data.length} found"
+  
+  # Test usage info
+  usage = client.get_usage
+  puts "✅ API usage: #{usage.data.credits_remaining} credits remaining"
+  
+  puts "\n🎉 All tests passed! SDK is working correctly."
+  
+rescue ShopsavvyDataApi::Error => e
+  puts "❌ Test failed: #{e.message}"
+end
 ```
 
-### Contributing
+## 📚 Additional Resources
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this project.
+- **[ShopSavvy Data API Documentation](https://shopsavvy.com/data/documentation)** - Complete API reference
+- **[API Dashboard](https://shopsavvy.com/data/dashboard)** - Manage your API keys and usage
+- **[GitHub Repository](https://github.com/shopsavvy/sdk-ruby)** - Source code and issues
+- **[RubyGems Page](https://rubygems.org/gems/shopsavvy-sdk)** - Gem releases and stats
+- **[Support](mailto:business@shopsavvy.com)** - Get help from our team
 
-## 📚 Additional Resources
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
 
-- [ShopSavvy Data API Documentation](https://shopsavvy.com/data/documentation)
-- [API Dashboard](https://shopsavvy.com/data/dashboard)
-- [Support](mailto:business@shopsavvy.com)
+- Reporting bugs
+- Suggesting enhancements  
+- Submitting pull requests
+- Development workflow
+- Code standards
 
 ## 📄 License
 
@@ -565,10 +938,23 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## 🏢 About ShopSavvy
 
-ShopSavvy is a price comparison and shopping app that helps users find the best deals on products across various retailers. Since 2008, ShopSavvy has been downloaded over 40 million times and helps millions of users save money every day.
+**ShopSavvy** is the world's first mobile shopping app, helping consumers find the best deals since 2008. With over **40 million downloads** and millions of active users, ShopSavvy has saved consumers billions of dollars.
+
+### Our Data API Powers:
+- 🛒 **E-commerce platforms** with competitive intelligence  
+- 📊 **Market research** with real-time pricing data
+- 🏪 **Retailers** with inventory and pricing optimization
+- 📱 **Mobile apps** with product lookup and price comparison
+- 🤖 **Business intelligence** with automated price monitoring
 
-Our Data API provides the same powerful product data and pricing intelligence that powers our consumer app, available to developers and businesses worldwide.
+### Why Choose ShopSavvy Data API?
+- ✅ **Trusted by millions** - Proven at scale since 2008
+- ✅ **Comprehensive coverage** - 1000+ retailers, millions of products  
+- ✅ **Real-time accuracy** - Fresh data updated continuously
+- ✅ **Developer-friendly** - Easy integration, great documentation
+- ✅ **Reliable infrastructure** - 99.9% uptime, enterprise-grade
+- ✅ **Flexible pricing** - Plans for every use case and budget
 
 ---
 
-**Need help?** Contact us at [business@shopsavvy.com](mailto:business@shopsavvy.com) or visit [shopsavvy.com/data](https://shopsavvy.com/data) for more information.
+**Ready to get started?** [Sign up for your API key](https://shopsavvy.com/data) • **Need help?** [Contact us](mailto:business@shopsavvy.com)

data/lib/shopsavvy_data_api/version.rb

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

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: shopsavvy-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - ShopSavvy by Monolith Technologies, Inc.
-autorequire: 
 bindir: exe
 cert_chain: []
 date: 2025-07-30 00:00:00.000000000 Z
@@ -2927,7 +2926,6 @@ metadata:
   changelog_uri: https://github.com/shopsavvy/sdk-ruby/blob/main/CHANGELOG.md
   documentation_uri: https://shopsavvy.com/data/documentation
   bug_tracker_uri: https://github.com/shopsavvy/sdk-ruby/issues
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -2942,8 +2940,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Official Ruby SDK for ShopSavvy Data API
 test_files: []