=== Shills Multi Currency Manager ===
Author: Shawn Hills
Author URI: https://profiles.wordpress.org/shawnhills
License: GPL2
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: shills-multi-currency-manager
Requires at least: 6.0
Tested up to:      7.0
Requires PHP:      7.4
Stable tag:       1.0.0
Domain Path: /languages

Tags:   currency switcher, woocommerce, exchange rates, multilingual, multi-currency

License:           GPLv2 or later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Lightweight multi-currency manager for WooCommerce with real-time rates, WPML/Polylang support, GeoIP detection, and frontend switcher.

== Description ==

Shills Multi Currency Manager is a powerful yet lightweight currency switcher plugin for WordPress that allows your visitors to switch between multiple currencies seamlessly. Perfect for e-commerce stores, international businesses, and multilingual websites.

**Key Features:**

* **Multi-Currency Management** - Add unlimited currencies with custom symbols, positions, and exchange rates
* **Real-Time Exchange Rates** - Automatic rate updates from ExchangeRate-API.com or Open Exchange Rates
* **WooCommerce Integration** - Full compatibility with WooCommerce product prices, cart, and checkout
* **WPML & Polylang Support** - Automatic currency switching based on language selection
* **Language-Currency Mapping** - Map specific currencies to languages (e.g., English → USD, Chinese → CNY)
* **GeoIP Detection** - Auto-detect visitor location and set appropriate currency
* **Multiple Display Styles** - Choose between dropdown or button display formats
* **REST API** - Complete REST API for currency operations and frontend integration
* **Widget & Shortcode** - Easy implementation via widget or `[shmcm_switcher]` shortcode
* **Theme Integration** - Auto-detect theme colors or set custom colors
* **User Choice Persistence** - Remember visitor currency selection for 30 days
* **Cache Compatible** - Works with WP Rocket, W3 Total Cache, and other caching plugins
* **Modern JavaScript** - Built with Webpack and modern ES6+ JavaScript

**Currency Features:**

* Custom currency symbols and positions (left, right, left_space, right_space)
* Configurable decimal places per currency
* Manual or automatic exchange rate updates
* Base currency support with rate normalization
* Currency validation and error handling

**WooCommerce Features:**

* Automatic price conversion on product pages
* Cart and checkout price formatting
* Order currency metadata storage
* Currency display in admin order details
* AJAX fragment support for dynamic updates

**Multilingual Features:**

* Automatic currency sync when switching languages
* Respect user manual currency selection
* Configurable language-currency mappings
* Compatible with WPML and Polylang language switchers

== Installation ==

1. Upload the `shills-multi-currency-manager` folder to the `/wp-content/plugins/` directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Go to **Settings → Currency Switcher** to configure currencies and settings
4. Add the currency switcher to your site using:
   * Widget: Go to **Appearance → Widgets** and add "Currency Switcher"
   * Shortcode: `[shmcm_switcher]` in posts, pages, or templates
   * PHP: `<?php echo do_shortcode('[shmcm_switcher]'); ?>`

== Frequently Asked Questions ==

= How do I add a new currency? =

Go to **Settings → Currency Switcher → Currencies** and click "Add Currency". Enter the currency code, symbol, exchange rate, and other settings.

= How do I enable automatic exchange rate updates? =

Go to **Settings → Currency Switcher → General Settings** and select an API provider (ExchangeRate-API.com or Open Exchange Rates). You can also set the auto-update frequency.

= Does this plugin work with WooCommerce? =

Yes! The plugin fully integrates with WooCommerce and automatically converts product prices, cart totals, and checkout amounts.

= Can I sync currency with language selection? =

Yes! Go to **Settings → Currency Switcher → Multilingual Settings** and enable "Auto Sync". Then map languages to currencies (e.g., English → USD, Spanish → EUR).

= What multilingual plugins are supported? =

WPML and Polylang are fully supported with automatic currency switching.

= Can I display the switcher as buttons instead of dropdown? =

Yes! Use the shortcode `[shmcm_switcher display="buttons"]` or select "Buttons" in the widget settings.

= How do I set a custom color for the switcher? =

Go to **Settings → Currency Switcher → Appearance** and select "Custom" theme mode, then choose your color.

= Is this plugin compatible with caching plugins? =

Yes! The plugin adds `Vary: Cookie` headers and works with WP Rocket, W3 Total Cache, and other caching plugins.

== Screenshots ==

1. Currency management interface with add/edit/delete functionality
2. Exchange rate settings with multiple API providers
3. Multilingual settings with language-currency mapping
4. Frontend switcher showing dropdown and button styles
5. WooCommerce integration showing converted prices
6. Widget configuration in the block editor

== Changelog ==

= 1.0.0 =
* Initial release
* Multi-currency management with unlimited currencies
* Real-time exchange rate updates from multiple providers
* WooCommerce integration with price conversion
* WPML and Polylang multilingual support
* Language-currency automatic sync
* REST API for all currency operations
* Widget and shortcode support
* GeoIP detection for automatic currency selection
* Modern JavaScript with Webpack build system
* Cache compatibility with major caching plugins

== Upgrade Notice ==

= 1.0.0 =
First release - no upgrade needed!

== Arbitrary section ==

**Development**

This plugin is built with modern development practices:

* PHP 7.4+ with strict types
* WordPress Coding Standards
* Webpack for asset building
* ES6+ JavaScript
* SCSS for styling
* REST API architecture
* Comprehensive error handling and logging


== External Services ==

This plugin may connect to the following third-party services. All are optional.

**ExchangeRate-API.com**
* Purpose: Fetches real-time exchange rates when automatic rate updates are enabled.
* Data sent: Only the base currency code (e.g., "USD") as part of the request URL. No API key or personal data is transmitted.
* When: Only when the admin manually triggers a rate update or when the scheduled auto-update cron runs.
* Service URL: https://www.exchangerate-api.com
* Terms of Service: https://www.exchangerate-api.com/terms
* Privacy Policy: https://www.exchangerate-api.com/privacy

**Open Exchange Rates**
* Purpose: Fetches real-time exchange rates as an alternative provider when automatic rate updates are enabled.
* Data sent: The API key (configured by the site admin) and base currency code as URL parameters. No user data is transmitted.
* When: Only when the admin manually triggers a rate update or when the scheduled auto-update cron runs.
* Service URL: https://openexchangerates.org
* Terms of Service: https://openexchangerates.org/terms
* Privacy Policy: https://openexchangerates.org/privacy

**ipapi.co**
* Purpose: GeoIP detection to automatically suggest the visitor's local currency on their first visit.
* Data sent: The visitor's IP address is transmitted as part of the HTTP request to ipapi.co. No API key, personal information, or cookies are sent.
* When: Only when a visitor first loads the site and no currency preference cookie is set. Once set, no further GeoIP requests are made.
* Service URL: https://ipapi.co
* Terms of Service: https://ipapi.co/terms/
* Privacy Policy: https://ipapi.co/privacy/

All external services are optional. Select "None - Use Manual Rates" in the General Settings tab to disable all exchange rate API calls. Rate updates only occur on admin-initiated actions or scheduled WordPress cron events; no exchange rate API requests are made during regular frontend visits. GeoIP detection can be disabled in the Multilingual Settings.

== Filter Reference ==

* `shmcm_currencies` - Filter the currencies array
* `shmcm_exchange_rates` - Filter exchange rates before storage
* `shmcm_price_format` - Filter price formatting
* `shmcm_api_providers` - Filter available API providers
* `shmcm_geo_country_currency_map` - Filter GeoIP country-currency mapping

== Action Reference ==

* `shmcm_currency_switched` - Fires when currency is switched
* `shmcm_rates_updated` - Fires when exchange rates are updated
* `shmcm_language_currency_synced` - Fires when language-currency sync occurs
* `shmcm_activated` - Fires on plugin activation
* `shmcm_deactivated` - Fires on plugin deactivation
* `shmcm_components_loaded` - Fires after all components are loaded

== REST API Endpoints ==

All endpoints are under `/wp-json/shmcm/v1/`:

* `GET /settings` - Get currency switcher settings
* `POST /switch` - Switch currency (sets cookie)
* `POST /update-rates` - Update exchange rates from API
* `GET /theme-color` - Get current theme color
* `GET /lang-map` - Get language-currency mapping
* `POST /sync-lang` - Sync language with currency
* `GET /currencies` - Get all currencies (admin)
* `POST /currencies` - Add new currency (admin)
* `GET /currency/{code}` - Get single currency (admin)
* `POST /currency/{code}` - Update currency (admin)
* `DELETE /currency/{code}` - Delete currency (admin)

== Shortcode Parameters ==

`[shmcm_switcher]`

* `display` - Display style: `dropdown` (default) or `buttons`
* `theme` - Theme mode: `auto` (default), `light`, `dark`, or `custom`

Example: `[shmcm_switcher display="buttons" theme="dark"]`

== Requirements ==

* PHP 7.4 or higher
* WordPress 6.0 or higher
* WooCommerce 6.0 or higher (optional, for e-commerce features)
* WPML or Polylang (optional, for multilingual features)

== Credits ==

Built with love by Shawn Hills

Special thanks to:
* The WordPress community
* Contributors and testers
* ExchangeRate-API.com and Open Exchange Rates for exchange rate data
* ipapi.co for GeoIP detection
