=== Paapi Product Search for Amazon ===
Contributors: paapiplugin
Tags: products, search, affiliate, ecommerce, amazon
Requires at least: 5.0
Tested up to: 6.9
Stable tag: 2.8.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Search and display Amazon products directly on your WordPress site with live search, filters, and beautiful themes. No ASIN hunting required.

== Description ==

https://www.youtube.com/watch?v=GGCt8w3jfpA

Paapi Product Search for Amazon is a powerful WordPress plugin that lets you search and display Amazon products directly on your website - no ASIN hunting required. Using the Creators API or PA-API 5.0 (your choice), it's perfect for affiliate marketers, product review sites, and content creators who want a clean, fast product search experience.
= Free Features =

* Amazon Creators API and PA-API 5.0 search integration
* Amazon-Inspired theme (default free theme)
* 5 free categories: Electronics, Books, Fashion, Toys & Games, Home & Garden
* 5 pages pagination limit (50 products)
* Grid display mode
* Advanced search with autocomplete suggestions
* Multiple filters: Brand, Price Range, Condition, Merchant, Availability
* Filter visibility settings: Choose which filters to display
* Sorting options: Relevance, Price, Newest Arrivals, Average Customer Reviews, Featured
* Pagination options: Infinite scroll, Load More button, or No pagination
* Responsive mobile-first layout
* Visual shortcode builder in admin
* Shortcode support: `[psfa_search]`

= Premium Features =

* **Premium Themes**: Choose from 4 additional themes (Ocean Blue, Modern, Minimal, Dark)
* **Unlimited Pagination**: Load up to Amazon's API limit (10 pages = 100 products)
* **All 26 Categories**: Access to all Amazon product categories
* **List Display Mode**: Vertical list layout for detailed product comparisons
* **Prime Filter**: Filter by Prime eligible or Free Shipping products
* **Deals Filter**: Filter by minimum discount percentage (10%, 25%, 50% off)
* **Has Deal Filter**: Filter to show only products with active deals
* **Product Badges**: Display Prime badge, Best Seller rank (#1-100), and Discount percentage
* **Lightning Deal Badges**: Show Amazon Lightning Deal and Best Deal badges (OffersV2)
* **Prime Exclusive Deals**: Display Prime Exclusive Deal indicator badge (OffersV2)
* **Low Stock Warnings**: Animated "Low Stock" badge when inventory is scarce (OffersV2)
* **Deal Countdown Timer**: Show countdown for time-limited deals (OffersV2)
* **Badge & Deal Toggles**: Enable/disable individual deal features in admin settings
* **Custom Color Schemes**: Fully customize colors for each theme (primary, secondary, buttons, text, prices)
* **Button Customization**: Customize "Buy on Amazon" button text, size, style, and colors
* **Custom Product Card Layouts**: Choose from Default, Compact, Detailed, and Image Focused layouts
* **Font Customization**: Choose custom fonts from Google Fonts for titles, descriptions, and prices
* **Hide Category Banner**: Option to hide the category header banner
* **White-Label Mode**: Remove "Powered by PSFA" branding for a fully white-labeled experience

= How It Works =

https://www.youtube.com/watch?v=fo0_gKdYJl4

1. Install and activate the plugin
2. Configure your Amazon Product Advertising API credentials in Settings → Paapi Product Search for Amazon
3. Select your preferred theme and customize appearance (premium features available)
4. Add the shortcode `[psfa_search]` to any page or post
5. Users can search and browse Amazon products directly on your site

= Requirements =

* WordPress 5.0 or higher
* PHP 7.4 or higher
* cURL extension enabled
* Amazon Product Advertising API credentials (Access Key ID, Secret Access Key, and Associate Tag)

= Getting Amazon API Credentials =

To use this plugin, you'll need to:

1. Sign up for the [Amazon Associates program](https://affiliate-program.amazon.com)
2. Apply for API access at [Creators API](https://affiliate-program.amazon.com/creatorsapi) or [Product Advertising API (PA-API v5)](https://affiliate-program.amazon.com/assoc_credentials/home) We support both!
3. Once approved, you'll receive your Access Key ID and Secret Access Key
4. Your Associate Tag is your Amazon Associates ID

= Privacy & Security =

* All API credentials are stored securely in WordPress options
* Users must provide their own Amazon API credentials
* No user data is collected or transmitted to third parties
* All product data comes directly from Amazon's API
* All requests use secure HTTPS connections

== Installation ==

= Automatic Installation =

1. Go to **Plugins → Add New** in your WordPress admin.
2. Search for "Paapi Product Search for Amazon" (or upload the ZIP from WordPress.org once approved).
3. Click **Install Now** and then **Activate**.

= Manual Installation =

1. Upload the `paapi-product-search-for-amazon` folder to `/wp-content/plugins/`.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Go to **Settings → Paapi Product Search for Amazon**.
4. Enter your Amazon Product Advertising API credentials.
5. Add the shortcode `[psfa_search]` to any page or post.

= Configuration =

https://www.youtube.com/watch?v=fo0_gKdYJl4

1. Navigate to **Settings → Paapi Product Search for Amazon** in your WordPress admin.
2. Select your **Authentication Type**:
   - **OAuth 2.0 (Creators API)** - Recommended for new users
   - **AWS Signature V4 (PA-API)** - Legacy authentication method
3. For **OAuth 2.0 (Creators API)**:
   - Enter your **Client ID** and **Client Secret** from Creators API
   - Enter your **Credential Version** (typically "1")
   - Select your **Auth Region** and **Marketplace**
4. For **AWS Signature V4 (PA-API)**:
   - Enter your **Access Key ID** and **Secret Access Key**
5. Enter your **Associate Tag** (your Amazon Associates ID).
6. Click **Test Connection** to verify your credentials work.
7. Click **Save Settings**.
8. (Optional) Select a theme, customize colors, fonts, and layouts in the respective sections.

== Frequently Asked Questions ==

= Do I need an Amazon Associates account? =

Yes, you need an Amazon Associates account and Product Advertising API / Creators API access to use this plugin. The plugin requires your API credentials to search Amazon's product catalog.

= Is this plugin free? =

The plugin has both free and premium features. The free version includes basic search functionality, the Amazon-Inspired theme, 5 categories, and 5 pages of results. Premium features include additional themes, unlimited pagination, all categories, list display mode, and extensive customization options.

= How do I get Amazon API credentials? =

1. Sign up for Amazon Associates
2. Apply for Product Advertising API access or Creators API access
3. Once approved, you'll receive your credentials in the Amazon Developer Console

= Can I customize the appearance? =

Yes! Free users can override CSS classes in their theme's stylesheet. Premium users have access to:
* Multiple themes (Ocean Blue, Modern, Minimal, Dark)
* Custom color schemes for all theme elements
* Button customization (text, size, style, colors)
* Custom product card layouts (Default, Compact, Detailed, Image Focused)
* Font customization from Google Fonts

= Does the plugin work with caching plugins? =

Yes, but you may need to exclude pages with the shortcode from full-page caching, as the search functionality requires dynamic content.

= Can I use this on multiple sites? =

Yes, but each site needs its own plugin license and Amazon API credentials. Amazon API credentials are site-specific.

= What happens if my API credentials are invalid? =

The plugin will display an error message asking you to check your credentials in the settings page.

= Can I filter products by category? =

Yes. You can specify a category in the shortcode: `[psfa_search category="Electronics"]`, or let users pick a category from the built‑in dropdown. Free users have access to 5 categories, premium users have access to all 27 categories.

= Does the plugin support infinite scroll? =

Yes! The plugin automatically loads more products as users scroll down the page. Free users can load up to 5 pages (50 products), premium users can load up to 10 pages (100 products, Amazon's API limit).

= Can I search without a query? =

Yes, if you specify a category, the plugin will show popular products from that category.

= What themes are available? =

Free users get the Amazon-Inspired theme. Premium users can choose from:
* Ocean Blue - Clean, modern blue theme
* Modern - Sleek contemporary design
* Minimal - Minimalist black and white theme
* Dark - Dark mode theme with vibrant accents

= What customization options are available for premium users? =

Premium users can customize:
* Colors: Primary, secondary, button, text, and price colors for each theme
* Buttons: Text, size, style, and colors
* Card Layouts: Default, Compact, Detailed, or Image Focused
* Fonts: Choose from Google Fonts for titles, descriptions, and prices
* Display Mode: Grid or List layout
* Badges: Prime badge, Best Seller rank, Discount percentage, Lightning Deal, Best Deal, Prime Exclusive Deal, Low Stock warnings
* Deal Features: Countdown timer for time-limited deals
* White-Label: Remove "Powered by PSFA" branding for a fully branded experience

== Screenshots ==

1. Product results in grid layout with filters (Free feature)
2. Product results in list layout (Premium feature)
3. Search interface with autocomplete suggestions
4. Ocean Blue: Premium theme
5. Minimal: Premium theme
6. Responsive design for mobile devices
7. Plugin settings: Credentials, Themes, Layout, Customization, Features and more
8. Theme selection with preview images (Amazon-Inspired, Ocean Blue, Modern, Minimal, Dark)
9. Layout section showing various options
10. Customization section showing color pickers, button options, card layouts, and fonts
11. Shortcode builder tab showing shortcode builder for easy shortcode generation

== Changelog ==

= 2.8.3 =
* Improved: Welcome video ID now filterable via `psfa_welcome_video_id` hook

= 2.8.2 =
* Improved: Disabled browser autocomplete on API credentials inputs

= 2.8.1 =
* New: Welcome section with setup video for new users on API Credentials page
* Improved: Video player with custom thumbnail and auto-reset on finish

= 2.8.0 =
* New: White-label mode - Premium users can remove "Powered by PSFA" branding
* New: "Powered by PSFA" branding link on frontend search results
* New: White-label toggle in Layout → Display Options (Premium)

= 2.7.0 =
* New: Comparison Tables add-on support - create product comparison tables with winner badges
* New: Winner Highlighting badges (Best Value, Editor's Choice, Best Rated, Budget Pick, Premium Pick)
* New: Responsive table options - stack (cards) or scroll on mobile devices
* New: Custom button text support for comparison tables
* Improved: Documentation updates for add-on shortcode attributes

= 2.6.0 =
* New: Add-on support infrastructure - hooks and filters for extending plugin functionality
* New: Product Boxes add-on compatibility - display individual Amazon products with shortcodes
* New: Admin navigation system for add-on sections
* Improved: Plugin architecture to support modular add-ons

= 2.5.0 =
* Improved: CSS architecture refactored - base styles in style.css, themes contain only color overrides
* Improved: Product card alignment - titles now use line-clamp for consistent card heights
* Improved: Title hover tooltip shows full product name when truncated
* New: Countdown badge shimmer animation effect for time-limited deals
* New: Theme-specific badge colors for all themes (Ocean Blue, Modern, Minimal, Dark, Amazon Inspired)
* Fixed: Badge color overrides now properly apply in all themes

= 2.4.0 =
* New: Display Options settings - Hide Search Bar, Hide Filters, Hide Category Banner toggles in admin
* New: Shortcode overrides - Display options can be overridden per-page using shortcode attributes
* New: Shortcode builder - Added Hide Category Banner toggle to Display Options card
* Improved: Settings priority system - URL params > shortcode attributes > admin settings
* Fixed: Admin settings now properly apply when no shortcode attributes are provided

= 2.3.1 =
* Fixed: Price filter consistency - Initial page load now sends minPrice/maxPrice to Creators API
* Fixed: Creators API 404 handling - No results now gracefully shows empty state instead of error

= 2.3.0 =
* New: OffersV2 API Migration - Full migration from OffersV1 to OffersV2 for enhanced deal data
* New: OAuth 2.0 / Creators API authentication support with admin UI selector
* New: Test Connection button in credentials settings to validate API credentials
* New: Auth type selector - Choose between OAuth 2.0 (Creators API) or AWS Sig V4 (legacy PA-API)
* New: Has Deal filter - Filter products to show only items with active deals
* Improved: Badge & Deal Settings moved to Layout section with consistent UI
* Improved: Badge toggles now match Filter Visibility design (2-column grid, clickable rows)

= 2.2.1 =
* Added: Info tooltips throughout admin settings for better guidance
* Improved: Admin interface polish and styling refinements

= 2.2.0 =
* Added: New Tailwind CSS admin interface with modern styling
* Added: Comprehensive test suite (256 tests, 64% coverage)
* Fixed: Demo panel styling and layout issues
* Fixed: Card selection border states in admin
* Improved: WordPress.org compliance - removed CDN dependencies
* Improved: Code quality and maintainability

= 2.1.3 =
* Added: Stock status filter (In Stock Only, All Items, Out of Stock Only)
* Added: Filter visibility settings - choose which filters to show/hide in the search interface
* Fixed: Filter parameters now correctly propagate to URL on form submission

= 2.1.2 =
* Fixed: Price sorting now correctly handles products with sale/original prices
* Fixed: Sorting accuracy when brand filter is applied
* Changed: Renamed "Pro" to "Premium" in upgrade notices

= 2.1.1 =
* Changed: Shortcode renamed from [product_search_for_amazon] to [psfa_search] for WordPress.org compliance
* Updated: All documentation and shortcode builder to use new shortcode name

= 2.1.0 =
* Added: Product Badges premium feature card in Features tab
* Added: Shortcode Builder admin tab with visual shortcode generator
* Added: Info tooltips to Customization and Shortcode tabs for better UX
* Fixed: WordPress coding standards compliance
* Improved: Plugin zip file structure

= 2.0.6 =
* Restructured: Plugin folder organization (includes → core) for better maintainability and add-on support
* Improved: Filters now always visible when hide_search="true" shortcode attribute is used
* Fixed: Asset paths after folder restructure

= 2.0.5 =
* Fixed: White page issue on production sites when applying filters
* Fixed: JavaScript error with lightbox initialization before DOM ready
* Improved: POST form redirect now runs early via template_redirect hook for faster response

= 2.0.3 =
* Fixed: All CSS class prefixes updated to psfa- (WordPress.org compliance)
* Fixed: All option names updated to psfa_ prefix
* Fixed: All AJAX action hooks updated to psfa_ prefix
* Fixed: JavaScript localization variable renamed to psfaAjax
* Improved: Complete prefix standardization across all plugin files

= 2.0.2 =
* Fixed: Inline scripts and styles now use proper WordPress enqueue functions
* Fixed: Nonce verification now uses proper sanitization
* Fixed: All function prefixes updated to PSFA_ (4+ characters)
* Improved: WordPress.org compliance for plugin guidelines
* Updated: External services documentation
* Updated: Source code documentation for minified JS

= 2.0.1 =
* Fixed: Category limits enforced correctly in free version (5 categories)
* Fixed: Pagination limits enforced correctly in free version (5 pages)
* Fixed: Upgrade notice displays properly for premium categories
* Improved: Build system for free/premium version separation

= 2.0.0 =
* Added premium theme system with 4 additional themes (Ocean Blue, Modern, Minimal, Dark)
* Added list display mode for premium users
* Added comprehensive customization options: custom colors, button customization, card layouts, font customization
* Added all 27 Amazon categories for premium users
* Added unlimited pagination for premium users (up to Amazon's 10-page limit)
* Added hide category banner option
* Improved admin interface with tabbed navigation
* Enhanced CSS generation system for dynamic customizations
* Refined PA‑API filtering support for brand, condition, and merchant
* Stabilized the interaction between price range filters and all sort options
* Improved infinite scroll behaviour with better pagination handling
* Polished the responsive UI (mobile and desktop)
* Added comprehensive PHPUnit test suite
* Updated architecture to follow DRY/SOLID principles

= 1.5.0 =
* Introduced advanced sorting options (Relevance, Price Low → High / High → Low, Newest Arrivals, Average Customer Reviews, Featured).
* Added client‑side sorting fallbacks when PA‑API sorting is not available for a given filter combination.
* Improved integration between brand filtering and sorting so that the overall product list remains globally sorted across AJAX pages.

= 1.4.0 =
* Added support for condition and merchant filters mapped to PA‑API parameters where available.
* Improved "no products found" messaging to distinguish between genuine empty results and API errors.
* Hardened error handling for PA‑API HTTP failures and invalid parameter responses.

= 1.3.0 =
* Reworked infinite scroll to better respect Amazon's 10‑page `ItemPage` limit and to avoid repeated empty page requests.
* Added an explicit upgrade notice when the free plan's page limit is reached, with a link to upgrade to the premium version.
* Improved pagination logic to ensure filters and sorts are preserved across AJAX requests.

= 1.2.0 =
* Enhanced the price range filter with more robust parsing and inclusive min/max boundaries.
* Ensured price filtering works consistently between the initial page load and subsequent AJAX loads.
* Fixed several edge cases where items without prices or with unusual formats could slip through filters.

= 1.1.0 =
* Introduced the brand dropdown filter with dynamic options based on the current result set.
* Added autocomplete suggestions powered by a secure WordPress AJAX endpoint.
* Improved overall accessibility and keyboard navigation within the search experience.

= 1.0.2 =
* Minor bug fixes and internal refactors in preparation for the 1.1.0 feature set.

= 1.0.1 =
* Improved handling of restrictive filter combinations and "No results" cases.
* Added clearer error messaging when PA‑API credentials are missing or invalid.
* Tightened input sanitization and ensured compliance with WordPress coding standards.

= 1.0.0 =
* Initial release.
* Core product search via PA‑API v5.
* Category selection and basic brand/price filters.
* Infinite scroll and autocomplete suggestions.
* `[psfa_search]` shortcode and default responsive styling.

== Support ==

For support, feature requests, or bug reports, please visit the plugin's support forum on WordPress.org.

== Credits ==

This plugin uses the Amazon Product Advertising API 5.0 (PA-API 5.0) to search and retrieve product information.

== Source Code ==

The minified JavaScript file `assets/js/main.js` is built from source files located in `assets/js/src/`. The source code is included in this plugin distribution.

Build tools used:
* **Vite** - For JavaScript bundling and minification
* **Node.js** - Runtime environment

== External Services ==

This plugin connects to the following external services:

= Amazon Product Advertising API (PA-API 5.0) =

This plugin uses Amazon's Product Advertising API to search and retrieve product information. This is the core functionality of the plugin.

* **What it does:** Searches Amazon's product catalog and retrieves product details (title, price, images, etc.)
* **When data is sent:** When a user performs a product search on your website
* **What data is sent:** Search queries, category selections, and filter parameters
* **Service provider:** Amazon.com, Inc.
* **Terms of Service:** https://affiliate-program.amazon.com/help/operating/agreement
* **Privacy Policy:** https://www.amazon.com/gp/help/customer/display.html?nodeId=468496

= Amazon Autocomplete Suggestions =

This plugin uses Amazon's autocomplete API to provide search suggestions as users type.

* **What it does:** Provides real-time search suggestions based on user input
* **When data is sent:** When a user types in the search box (after 2+ characters)
* **What data is sent:** The partial search query text
* **Service provider:** Amazon.com, Inc.
* **Service URL:** https://completion.amazon.com/
* **Terms of Service:** https://www.amazon.com/gp/help/customer/display.html?nodeId=508088
* **Privacy Policy:** https://www.amazon.com/gp/help/customer/display.html?nodeId=468496

= Google Fonts (Premium Feature) =

Premium users can select custom fonts from Google Fonts for product display elements.

* **What it does:** Loads custom font files for typography customization
* **When data is sent:** When a page with the product search is loaded and custom fonts are configured
* **What data is sent:** Font family names
* **Service provider:** Google LLC
* **Terms of Service:** https://developers.google.com/terms
* **Privacy Policy:** https://policies.google.com/privacy

== Privacy Policy ==

This plugin does not collect, store, or transmit any personal user data. All product searches are performed using your Amazon API credentials, and all data comes directly from Amazon's servers. Search queries entered by your site visitors are sent to Amazon's API to retrieve product results. Please refer to the External Services section above for details on third-party services used by this plugin.
