Skip to content

README.md

Latest commit

 

History

History
232 lines (179 loc) · 7.24 KB

README.md

File metadata and controls

232 lines (179 loc) · 7.24 KB

Amazon Returns Cost Information - Browser Extension

A browser extension that displays return cost information on Amazon product pages for US (amazon.com) and Germany (amazon.de).

Browser Support

Works in:

  • Chrome, Edge, and other Chromium-based browsers
  • Firefox (version 109+)

Requires Manifest V3 support (Chrome 109+, Firefox 109+).

Features

  • Displays return costs for both defective/damaged items and regular returns
  • Supports Amazon.com (US) and Amazon.de (Germany)
  • Multi-language support (English & German)
  • Detects third-party sellers and fetches their return policies
  • Caches seller policies to reduce repeated fetches
  • Clean, non-intrusive UI that matches Amazon's design

Installation

Development Installation

  1. Install dependencies:
yarn install
  1. Build the extension:
yarn build
  1. Load the extension:

Chrome/Edge:

  • Navigate to chrome://extensions (Chrome) or edge://extensions (Edge)
  • Enable "Developer mode" (toggle in top right)
  • Click "Load unpacked"
  • Select the dist/ folder from this project

Firefox:

  • Navigate to about:debugging#/runtime/this-firefox
  • Click "Load Temporary Add-on"
  • Select the dist/manifest.json file
  • Note: Temporary add-ons in Firefox are removed when the browser closes

Development Mode (Watch)

To automatically rebuild on file changes:

yarn dev

After making changes, reload the extension in chrome://extensions and refresh the Amazon product page.

Testing

Unit Tests (Jest)

yarn test              # Run all tests
yarn test:watch        # Watch mode
yarn test:coverage     # With coverage report

50 tests covering:

  • Policy scraping (Amazon.com and Amazon.de)
  • Seller detection
  • Internationalization (i18n)
  • Edge cases (restocking fees, non-returnable items, paid shipping)

Extension Testing (Puppeteer)

Basic Test

yarn test:extension

Automated integration test:

  • Launches Chrome with the extension loaded
  • Navigates to a real Amazon.de product page
  • Waits for the widget to appear
  • Validates widget content
  • Takes a screenshot (/tmp/extension-test-screenshot.jpg)
  • Keeps browser open for 10 seconds for inspection

Expected output:

🎉 Extension test PASSED!
✓ Defective section: ✅
✓ Regular section: ✅
✓ Cost information: ✅

Dynamic URL Testing

# Test with default URLs
yarn test:dynamic

# Test any Amazon product page
yarn node test-dynamic.js "https://www.amazon.de/dp/PRODUCT_ID"

# Examples
yarn node test-dynamic.js "https://www.amazon.com/dp/B0D1XD1ZV3"
yarn node test-dynamic.js "https://www.amazon.de/dp/B0BNQ66ZN1"

Features:

  • ✅ Test any Amazon product URL dynamically
  • ✅ Multiple test cases in one run
  • ✅ Validates widget content automatically
  • ✅ Screenshots saved for each test
  • ✅ Detailed console logs and extension logs
  • ✅ Pass/fail summary report

See TEST_USAGE.md for detailed testing guide.

Manual Testing

  1. Visit Amazon product pages:

  2. Look for the "Return Cost Information" widget near the buy box

  3. Test cases to verify:

    • Products with "FREE Returns" badge (should show free for both)
    • Products without "FREE Returns" badge (should show €6.50-€13.00 for regular returns)
    • Products sold by third-party sellers
    • Different product categories
    • Both amazon.com and amazon.de domains

Project Structure

src/
├── content/
│   ├── content.ts           # Main orchestrator
│   ├── policyScraper.ts     # Product page policy extraction
│   ├── sellerScraper.ts     # Third-party seller detection & scraping
│   ├── ui.ts                # Widget creation and injection
│   └── styles.css           # Widget styles
├── shared/
│   ├── types.ts             # TypeScript interfaces
│   ├── regionDetector.ts    # Amazon domain detection
│   ├── policyData.ts        # Static policy guidelines
│   └── i18n.ts              # Language patterns & UI text
└── manifest.json            # Chrome extension manifest

How It Works

  1. Detects Amazon region (amazon.com or amazon.de) and language
  2. Checks if the seller is Amazon or a third-party seller
  3. For third-party sellers: Fetches and parses their return policy from their seller details page
  4. For Amazon-sold items: Scrapes return policy from product page
  5. Paid Shipping Detection (Amazon.de):
    • Defective items: Always free per EU consumer law
    • Regular returns: Free only if "FREE Returns" badge is present
    • Without badge: Shows €6.50-€13.00 shipping cost (customer pays)
  6. Falls back to default regional policies if scraping fails
  7. Displays the information in a clean, color-coded widget
  8. Caches third-party seller policies for 7 days to improve performance

Return Policy Logic (Amazon.de)

Defective/Damaged Items

  • ✅ Always free return shipping (EU consumer law requirement)
  • ✅ 14-day return window

Regular Returns

  • ✅ With "FREE Returns" badge: Free shipping, 14 days
  • ⚠️ Without "FREE Returns" badge: €6.50-€13.00 shipping cost, 14 days
  • ℹ️ The extension detects the absence of the badge and displays the cost

Widget Example (Paid Shipping)

┌──────────────────────────────────┐
│ Rücksendekosten-Informationen    │
├──────────────────────────────────┤
│ Defekte/Beschädigte Artikel:     │
│ Kostenlose Rücksendung innerhalb │ ← Green
│ von 14 Tagen                     │
│                                  │
│ Reguläre Rücksendungen:          │
│ Nicht kostenlose Rücksendung     │ ← Red/Orange
│ (€6.50-€13.00 Kosten)            │
│ innerhalb von 14 Tagen           │
│                                  │
│ ⚬ Basierend auf Amazons          │
│   Rückgaberichtlinie             │
└──────────────────────────────────┘

Technologies

  • TypeScript
  • Webpack 5
  • Browser Extension Manifest V3
  • WebExtension Polyfill (cross-browser compatibility)
  • Vanilla JavaScript (no frameworks)

Supported Regions

  • United States (amazon.com) - English
  • Germany (amazon.de) - German

Cross-Browser Compatibility

The extension uses webextension-polyfill to ensure consistent behavior across Chrome, Edge, and Firefox:

  • Single codebase: Same code works in all browsers
  • Unified API: Uses standard browser.* namespace (polyfill translates to chrome.* in Chromium browsers)
  • No browser-specific code: All functionality works identically across browsers
  • Single build: The dist/ folder works for all browsers without modification

Technical details:

  • Chrome uses callback-based chrome.* API
  • Firefox uses promise-based browser.* API
  • WebExtension polyfill provides unified promise-based browser.* API for both
  • Manifest V3 is fully supported in Chrome 109+ and Firefox 109+

Development Documentation

See .claude/CHROME_EXTENSION_TESTING.md for comprehensive testing guide.

License

MIT