=== MetalflowAPI — Live Precious Metals Prices ===
Contributors: qeras89
Tags: gold price, silver price, precious metals, jewelry, gold api
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.8
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display live and historical Gold, Silver, Platinum and Palladium prices on your WordPress site. Carat-aware (9k–24k), 30+ currencies, EU-hosted.

== Description ==

The official **MetalflowAPI** WordPress plugin makes it dead simple to embed live precious metals prices on any WordPress site — perfect for **jewelers**, **publishers**, **trade-in calculators** and **bullion shops**.

= Features =

*   **Live spot prices** for Gold (XAU), Silver (XAG), Platinum (XPT) and Palladium (XPD)
*   **Carat-aware pricing** for 9k, 10k, 14k, 18k, 20k, 21k, 22k and 24k Gold
*   **30+ currencies** — EUR, USD, GBP, JPY, CHF, CAD, AUD, PLN, CZK, INR, BRL, CNY and many more (sourced daily from European Central Bank)
*   **Units**: gram (g), kilogram (kg), troy ounce (ozt)
*   **7 shortcodes** — drop into any post, page or widget
*   **5 Gutenberg blocks** — Live Price, Carat Calculator, Ticker, Carat Table, Historical Chart
*   **Sidebar widget** — classic widget for the metals ticker
*   **REST proxy** — your API key stays on the server, never exposed to the browser
*   **Smart caching** — built-in WordPress transient cache (configurable, 30s–24h)
*   **Theme-aware styling** — light and dark themes, follows your site's typography
*   **Translation-ready** — all strings localized

= Shortcodes =

`[metalflow_price metal="Gold" currency="EUR" unit="g"]` — live spot price for one metal
`[metalflow_carat carat="14" currency="EUR" unit="g"]` — carat-aware Gold price
`[metalflow_ticker currency="EUR" theme="light"]` — all 4 metals with 24h change
`[metalflow_table currency="EUR" unit="g"]` — full carat table 9k–24k
`[metalflow_change metal="Gold" days="30"]` — % change over N days
`[metalflow_calc currency="EUR"]` — interactive carat-weight calculator
`[metalflow_chart metal="Gold" range="1y" currency="EUR" width="600" height="180"]` — historical sparkline (30d/90d/180d/1y/2y/5y/10y/30y/max)

= Pricing =

The plugin is **100% free**. The MetalflowAPI service offers a free tier (no credit card required):

*   **Free** — 100 requests/month, daily-refreshed prices, 30-day history
*   **Starter** — €9/mo, 10,000 requests, 10-min refresh, 5-year history
*   **Pro** — €29/mo, 100,000 requests, 1-min refresh, 30-year history
*   **Enterprise** — custom, 15s refresh, full 1968+ history

[Sign up free →](https://metalflowapi.com/signup)

= EU & GDPR =

Servers in Strasbourg (France). All data within EU. GDPR-compliant. EUR billing with VAT invoices.

= External Service Disclosure =

This plugin relies on the **MetalflowAPI** service (metalflowapi.com) to fetch real-time and historical precious metals prices. By using this plugin you agree to MetalflowAPI&#39;s terms of service and privacy policy.

**What data is sent to MetalflowAPI from your WordPress server:**

*   Your API key (passed in the `X-API-Key` HTTP header) — used for authentication and rate-limit tracking.
*   Query parameters required to fulfil your shortcode/block (metal symbol, currency, date range, etc.).
*   The IP address of your WordPress server (standard for any outgoing HTTP request).

**What is NOT sent:**

*   No personally-identifiable information about your site visitors. The plugin never collects, transmits or stores visitor IPs, cookies or browsing behaviour.
*   No content of your WordPress posts, comments or user accounts.

**Cache:** all responses are cached locally on your server via WordPress transients (default 5 minutes, configurable) so the same query does not hit MetalflowAPI repeatedly.

**Before you add an API key:** the plugin shows built-in static sample data and makes **no** request to MetalflowAPI. The service is only contacted once a valid API key is saved.

**Service endpoints used:**

*   `https://metalflowapi.com/wp-json/metals/v1/prices` (historical)
*   `https://metalflowapi.com/wp-json/metals/v1/live` (24h intraday)
*   `https://metalflowapi.com/wp-json/metals/v1/all-prices-internal` (spot + FX bulk)
*   `https://metalflowapi.com/wp-json/metals/v1/sparkline` (SVG chart)

**Legal:**

*   Terms of Service: [https://metalflowapi.com/legal/terms](https://metalflowapi.com/legal/terms)
*   Privacy Policy: [https://metalflowapi.com/legal/privacy](https://metalflowapi.com/legal/privacy)

== Installation ==

1.  Upload the plugin to `/wp-content/plugins/metalflowapi-live-precious-metals-prices/` or install it through the WordPress Plugins screen.
2.  Activate the plugin.
3.  Go to **Settings → MetalflowAPI** and paste your API key. Get one free at [metalflowapi.com/signup](https://metalflowapi.com/signup).
4.  Click **Test connection** to verify.
5.  Drop a shortcode into any post or page, e.g. `[metalflow_ticker currency="EUR"]`.

== Frequently Asked Questions ==

= Do I need a paid plan to use this plugin? =

No. The free tier (100 requests/month) is plenty for low-traffic jewelry sites with caching enabled (default 5-min cache).

= Where is my API key stored? =

In your WordPress database (`wp_options`). Requests to MetalflowAPI are made from your WordPress server — the key is never sent to visitor browsers.

= Does this plugin slow down my site? =

No. All API responses are cached server-side via WordPress transients (default 5 min, configurable). On a cache hit, response time is essentially zero.

= Can I use this in a multisite / network? =

Yes. Each site has its own settings and its own API key.

= Does the plugin work without an API key? =

Yes, in preview mode. Until you add a key, every widget renders static **sample data** (clearly labelled "Sample data") so you can see how it looks. This sample is built into the plugin — no network request is made and nothing is sent anywhere. Add a free API key (Settings → MetalflowAPI) to switch to real live prices. The free tier is enough for most jewelry sites.

= Do you support cryptocurrency prices? =

Not in v1.0. BTC/ETH support is on the roadmap for the MetalflowAPI service.

= Can I customize the styling? =

Yes — the plugin emits semantic class names (`mfapi-price`, `mfapi-ticker`, etc.). Override in your theme's CSS.

== Screenshots ==

1.  Settings page with API key, defaults and "Test connection".
2.  Carat-aware price shortcode in a jewelry product page.
3.  Live ticker showing Au/Ag/Pt/Pd in EUR with 24h change.
4.  Carat table 9k–24k for trade-in calculators.
5.  Interactive carat-weight calculator block.

== Changelog ==

= 1.0.8 =
*   Fix: plugin now uses the commerce API (`/api/v1`) so dashboard keys (`mfk_live_*`) from metalflowapi.com/dashboard/keys work correctly. Previous versions incorrectly called the internal WordPress REST API (`/wp-json/metals/v1`), which rejected dashboard keys with "Invalid API key".

= 1.0.7 =
*   Fix: "Test connection" now uses the API key typed in the settings field (no need to save first).

= 1.0.6 =
*   New: offline "Sample data" preview. With no API key configured, widgets now render static sample values (clearly labelled) so you can see how everything looks before signing up. No network request is made and no data is sent in this mode.
*   WP.org review: block editor scripts now register their WordPress core dependencies (wp-blocks, wp-element, wp-block-editor, wp-components, wp-server-side-render, wp-i18n) via wp_register_script() and block.json, instead of manually enqueuing core "wp-" handles.
*   Clarified output-escaping comments in block render templates (output is escaped/sanitized inside the renderer).

= 1.0.5 =
*   WP.org review: admin CSS/JS moved to enqueued assets (no inline tags).
*   Sparkline SVG sanitized with wp_kses before output.
*   "Powered by" credit is off by default — explicit opt-in only.
*   Contributors updated; removed redundant load_plugin_textdomain() call.

= 1.0.4 =
*   **NEW** `[metalflow_chart]` shortcode + "Historical Chart" Gutenberg block — server-side SVG sparkline for any metal/currency, from 30 days up to the full 58-year archive. Light/dark theme, custom width/height, gradient fill, last-value label.
*   Plan history depth is honoured automatically — Free clamps to 30 days, Starter to 5 years, Pro to 30 years, Enterprise to full 1968+.

= 1.0.3 =
*   Live Price block / shortcode now renders the unit suffix (e.g. "€2,089.45/g") so the unit attribute is visible at a glance.

= 1.0.2 =
*   Backward-compat: orphan top-level options set via WP-CLI (mfapi_api_key, mfapi_default_currency etc.) are now auto-migrated into the canonical mfapi_settings array.

= 1.0.1 =
*   Fixed API key placeholder in admin settings to show correct key prefix (mfk_live_...).

= 1.0.0 =
*   Initial release.
*   6 shortcodes: price, carat, ticker, table, change, calc.
*   4 Gutenberg blocks (Live Price, Carat Calculator, Ticker, Carat Table).
*   Sidebar widget.
*   REST proxy `/wp-json/metalflowapi/v1/data` and `/calc`.
*   Server-side transient caching.
*   Settings page with connection tester and cache flush.
*   Translation-ready (i18n).

== Upgrade Notice ==

= 1.0.5 =
Review compliance update. Safe upgrade — "Powered by" now off by default.

= 1.0.4 =
Adds the long-awaited historical chart shortcode + block. Safe upgrade.

= 1.0.3 =
Displays unit suffix (/g, /kg, /ozt) next to single-metal prices. Safe upgrade.

= 1.0.2 =
Adds auto-migration for legacy/orphan options. Safe upgrade.

= 1.0.0 =
First release.
