# LiraScope for WHMCS

Install the `lirascope` directory at `modules/addons/lirascope`, then activate and configure it under **System Settings → Addon Modules**. Public mode requires no credentials. Client mode uses a LiraScope API key pair and forces login for the client-area page so anonymous visitors cannot spend its quota.

The module displays Syrian Pound official and market rates, a dashboard widget, historical rates, a local converter, usage, and signed webhook controls. Its cache never stores credentials or response headers. Request logs contain only status, API path, cache verdict, duration, and `Retry-After`.

## SYP currency feed

The billing feed ships off and is controlled only from **Addons → LiraScope**. Run the dry run before adding SYP or enabling the feed. The enable control runs that dry run again on the server and stays disabled with the exact reason when the base, source, SYP row, precision, or Exchange Rates setting is unsupported. When the row is absent, the dry run calculates the initial base-relative rate without writing it and gives the exact **Configuration → System Settings → Payments → Currencies → Add Additional Currency** fields. Add the row, run the dry run again, and review the stored current rate before enabling the feed.

- Market source uses a fresh direct quote and the sell → mid → buy basis. When WHMCS Exchange Rates auto-update is on, `FetchCurrencyExchangeRates` returns SYP per EUR and WHMCS rebases it. When that automation is off, cron writes SYP per base currency directly.
- The initial **Base Conv. Rate** is always relative to the installation's base currency, so it is shown separately when it differs from the EUR-relative hook value.
- CBS source is available only when USD is the WHMCS base currency. It writes the official USD quote directly and never mixes official and market sources.
- SYP as the base, missing/duplicate SYP rows, unknown storage precision, cached or fallback responses, and quotes older than six hours all fail closed. The existing billing rate stays unchanged.
- Direct writes lock the SYP row and atomically store the verified rate, audit row, and restart-safe idempotency marker. Three consecutive failed UTC dates trigger one WHMCS admin email.
- Product Prices auto-update is never read or changed.

Upgrades from 1.0.0 show a reminder to re-save the addon settings once so WHMCS discovers the new hook. Before publishing or enabling the feed, complete [the licensed WHMCS 9 development-install gate](https://github.com/OMARINO-DE/LiraScope/blob/main/plugins/whmcs/lirascope/tests/dev-install/README.md).

Requires WHMCS 9.x and PHP 8.2 or 8.3. Licensed under GPL-2.0-or-later.