=== Tomanify – Smart Toman & Rial Currency Manager ===
Contributors: araoufi
Tags: woocommerce, currency, iran, toman, rial
Requires at least: 5.2
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.3
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Smart currency conversion and Toman/Rial pricing for WooCommerce with configurable live rates, safe fallbacks, and multilingual support.

== Description ==

**Tomanify** helps WooCommerce stores that buy or list products in foreign currencies *(USD / EUR / AED / TRY / CNY)* and need to store the final selling price in Iranian **Toman** or **Rial**.

The plugin is designed to be safe, predictable, and practical for real stores:

* **No external source URLs are pre-filled** inside the plugin.
* External requests happen **only** if an administrator explicitly enters URLs.
* Converted prices are stored using a **TOMAN baseline** to avoid double-conversion when switching between **Toman** and **Rial**.
* You are **not required to buy a paid API** to use the core workflow. Many stores can start with a compatible free-market JSON feed, then add official RSS/XML, manual rates, or offline estimation as fallback layers.

= Start Here =

See the [public Persian documentation](https://tomanify.github.io/) for an overview and full guides.
New here? Follow the [Quick Start](https://tomanify.github.io/docs/quick-start/).
For setup and configuration, open the [plugin documentation](https://tomanify.github.io/docs/).
For rate sources and how they work, see [Source modes (API docs)](https://tomanify.github.io/docs/sources/).
If something doesn't work, check [Troubleshooting](https://tomanify.github.io/docs/troubleshooting/).
Need help? Post your issue on the [Community support](https://wordpress.org/support/plugin/tomanify/) and we’ll respond as soon as possible.

= 2-minute Quick Setup Video =
https://youtu.be/Tf7MEaR9xy0

= What makes Tomanify different? =

Many store owners do not just want a display-only exchange-rate widget. They need WooCommerce to keep a real final price for imported products so sorting, filtering, reporting, and other price-dependent features continue to work correctly.

Tomanify is built for that workflow:

* It stores a final **Toman baseline** per foreign product.
* It stores that baseline in product meta and uses it to rewrite WooCommerce price values.
* It lets you switch between **Toman** and **Rial** without re-fetching rates.
* It supports multiple rate-source strategies instead of forcing one remote service.

= Key Features =

* Per-product foreign pricing: **foreign flag + currency + foreign amount + margin (%)**
* Automatic conversion to **Toman baseline** and storage in WooCommerce price meta
* Switch display unit (Toman/Rial) **without re-fetching rates** *(rewrites from baseline)*
* Rate sources (admin configurable):
  * Live free-market **JSON endpoint** *(Toman values)*
  * Official **RSS/XML** *(per currency)* + premium conversion *(Free/Official)*
  * **Manual rates** *(Toman)*
  * **Offline estimation model** *(reference-based)*
* Bulk editor for all foreign products (**Products tab**)
* Frontend widget shortcode: **[tomanify_rates]** *(frontend assets load only when shortcode is used)*
* Optional cache purge integration (**OFF by default**)
* Backup/Restore (**export/import JSON**) + uninstall cleanup option
* Independent plugin language (**fa_IR / en_US**) regardless of site language
* RTL/LTR aware admin and frontend UI
* Faster admin navigation with direct submenu pages, quick Tour access, and plugin-row links to Settings, Docs, API docs, and Community support

= Supported Currencies =
USD, EUR, AED, TRY, CNY

= How it works (one line) =
Foreign Price × Rate(Toman) × (1 + Margin/100) → *round to nearest 1000 Toman* → store baseline → write WooCommerce price in selected unit.

= Public Documentation =
For user-friendly guides, setup walkthroughs, and practical explanations, see:

* [Main docs](https://tomanify.github.io/docs/)
* [Quick Start](https://tomanify.github.io/docs/quick-start/)
* [Free-market JSON guide *(no built-in provider required)*](https://tomanify.github.io/docs/free-api/)
* [Source modes](https://tomanify.github.io/docs/sources/)
* [Troubleshooting](https://tomanify.github.io/docs/troubleshooting/)

== Installation ==

1. Install and activate the plugin.
2. Go to **WP Admin → Tomanify**.
3. Set your rate source in the **Sources** tab *(JSON / RSS/XML / Manual / Offline)*.
4. Mark products as **Foreign Product (Tomanify)** and enter:
   * Foreign amount
   * Currency
   * Margin (%)
5. Click **Update Rates** *(Dashboard tab)* or rely on Cron schedule.
6. *(Optional)* Add shortcode **[tomanify_rates]** to show a frontend widget.

== Quick Start (Recommended) ==

= Option A: JSON (recommended for many stores) =

1. In **Tomanify → Sources** tab, set **JSON URL**.
2. Your endpoint must return this schema *(values are TOMAN integers)*:

    {"values":{"USD":60000,"EUR":130000,"AED":30000,"TRY":2500,"CNY":22550}}

3. Click **Update Rates**.
4. Mark a product as foreign and enter its foreign amount, currency, and margin.

You can host this JSON on your own server, GitHub Pages, or raw GitHub content.

A compatible free-market JSON feed is often enough for many stores. If your business is more sensitive to timing or smaller rate movements, you can combine it with margin, official RSS/XML fallback, or your own paid/self-hosted source.

= Option B: Official rates (RSS/XML) =

1. In **Tomanify → Sources** tab, set the official **RSS/XML URL for each currency (HTTPS)**.
2. The plugin converts official Rial to free-market Toman using:
   *Premium = Free / Official*
   *Free (Toman) = Official (Rial) / (10 × Premium)*

If you do not know the RSS/XML feed URL, open the [official rates page](https://www.cbi.ir/ExRates/rates_en.aspx) and copy the RSS link for each currency row.

(You will see an RSS icon next to each currency. Open it and copy the XML URL into the matching field.)

= Option C: Manual / Offline =

If you do not want to rely on a live URL all the time, you can also use:

* **Manual mode** for fixed per-currency Toman values
* **Offline mode** for reference-based estimation

These are useful as fallback strategies, not just emergency modes.

== Recommended Source Links (Optional Copy/Paste) ==

Important:
*These links are OPTIONAL suggestions.* Tomanify does **not** pre-fill them automatically.
You may use any valid HTTPS source you trust.

= 1) Example JSON endpoint format =
You need **one** URL that returns the JSON schema shown above.
Example GitHub raw URL format:

https://raw.githubusercontent.com/<OWNER>/<REPO>/<BRANCH>/data.json

Optional community-maintained JSON URL *(free to use as long as GitHub and the underlying free resources remain available)*:
> https://raw.githubusercontent.com/rate-json/default/main/data.json

= 2) Central Bank RSS/XML (Copy/Paste per currency) =

USD — United States Dollar
> https://cbi.ir/ExRatesRSS.aspx?cid=1

EUR — Euro
> https://cbi.ir/ExRatesRSS.aspx?cid=94

AED — United Arab Emirates Dirham
> https://cbi.ir/ExRatesRSS.aspx?cid=14

TRY — Turkish Lira
> https://cbi.ir/ExRatesRSS.aspx?cid=38

CNY — Chinese Yuan
> https://cbi.ir/ExRatesRSS.aspx?cid=85

== Usage ==

= Mark a product as foreign =
Open the product edit screen → **Foreign Product (Tomanify)** box:

* Enable **Is foreign product**
* Enter **Foreign price**
* Choose **Currency**
* Enter **Margin (%)**

Save the product → Tomanify recalculates using stored rates.

= Bulk edit foreign products =
WP Admin → **Tomanify → Products** tab  
Edit foreign price, currency, margin; then **Save**.

= Shortcode Widget =
Add this shortcode to any page/post:

[tomanify_rates]

The widget displays:

* Title + optional last update time
* Unit *(Toman/Rial)*
* Selected currencies table

Frontend CSS/JS assets load **only when the shortcode exists on the page**.

== Frequently Asked Questions ==

= Does Tomanify auto-fill any external URLs by default? =
No. All source URL fields are empty by default. External requests only happen after an admin enters URLs.

= Does Tomanify itself sell or bundle a paid API? =
No. Tomanify is a conversion and pricing engine. It can work with a compatible free-market JSON feed, official RSS/XML, manual rates, offline estimation, or any HTTPS source you choose.

= Do I have to buy an API key to make the plugin useful? =
Not necessarily. Many stores can start with a compatible free-market JSON source and a sensible margin. Stores with stricter requirements can later move to a paid or self-hosted source.

= What JSON structure does Tomanify understand? =
The documented schema is:

    {"values":{"USD":60000,"EUR":130000,"AED":30000,"TRY":2500,"CNY":22550}}

Values must be numeric **Toman** amounts.

= My rates changed a little but products did not update. Why? =
Check **Change threshold %** in the Advanced tab. Small movements below the threshold are ignored to reduce noise.

= Can I use only manual rates? =
Yes. Set Source Mode to **Manual** and fill per-currency values *(Toman)*.

= Can I switch between Toman and Rial later? =
Yes. Tomanify stores a TOMAN baseline per product and rewrites WooCommerce prices when you switch the unit *(no re-fetch needed)*.

= Where can I find the full user-friendly guides? =
See the [public Persian documentation](https://tomanify.github.io/) for full guides and setup walkthroughs.

== Screenshots ==

1. Dashboard: update rates button, last update/source info, cron scheduling, and stored rates table.
2. General tab: source mode selection, display unit (Toman/Rial), plugin language, and cache purge toggle.
3. Sources tab: JSON URL, Central Bank (CBI) RSS/XML URLs, and manual rates inputs.
4. Advanced tab: change threshold (%), global premium (Free/Official), CAGR, and factory reset.
5. Shortcode tab: choose currencies, show last update time, and copy shortcode button.
6. Products tab: bulk editor for foreign products (buy price, currency, margin) + computed final price.
7. Backup & Restore tab: export/import backup, and uninstall data removal option.
8. Product edit screen: “Foreign Product (Tomanify)” meta box (foreign flag, currency, price, margin).
9. Frontend: shortcode widget output (glassmorphism rates card).
10. About tab: overview, documentation links, quick guided tour button, license/credits, and contact info.
11. Plugins screen: tooltip for starting the quick guided tour from the plugin row.

== External Services ==

Tomanify does **not** transmit customer data, order data, or personally identifiable information.
The plugin can fetch currency-rate data only from external URLs that **you provide** in the Sources tab *(JSON and/or RSS/XML)*.
Requests happen only when you update rates *(manually or by scheduled cron)*.

Important:

* The plugin does **not** pre-fill third-party URLs.
* The plugin does **not** require a specific commercial API provider.
* You are responsible for choosing the source that matches your business needs.

== Changelog ==

= 1.0.3 =
* Added direct admin submenu entries for all Tomanify tabs for faster navigation.
* Added documentation links to the About tab.
* Added plugin row links on the Plugins screen: Settings, Tour, Docs, API docs, and Community support.
* Improved guided tour behavior for the new admin submenu pages and quick Tour link.
* Minor admin navigation improvements.

= 1.0.2 =
* Initial public release on WordPress.org.
* Secure admin forms (capability checks + nonces) and full sanitize/validate/escape coverage.
* No pre-filled external URLs; external requests only when admin sets URLs.
* Optional purge feature is OFF by default and restricted to same-host requests.
* Added Backup/Restore and uninstall cleanup option.
* Improved RTL/LTR support and independent plugin locale (fa_IR/en_US).

== Upgrade Notice ==

= 1.0.3 =
Adds direct submenu navigation, About-tab documentation links, and plugin row shortcuts for settings, tour, docs, API docs, and support.

== License ==

GPL-2.0-or-later.