=== Call Verification for WooCommerce ===

Contributors: callverification
Tags: woocommerce, order, verification, webhook, phone
Requires at least: 5.8
Tested up to: 6.8
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.0.8
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect WooCommerce orders to the Call Verification platform. Send new orders for phone verification and sync order status from call confirmations.

== Description ==

This plugin connects your WooCommerce store to the Call Verification platform using your API key and secret. When a new order is created, the order is sent to the platform so a verification call can be placed. When the customer confirms or cancels the call (via DTMF), the platform sends a webhook and the plugin updates the WooCommerce order status according to your mapping.

Features:

* **Connection**: Enter your API key and API secret (API endpoint is https://api.textbari.com). Test the connection and see your account email.
* **Webhook**: On activation or when you save settings, the plugin registers your site's webhook URL with the platform so order updates are received.
* **New orders**: Each new WooCommerce order is sent to the platform with customer name, phone, total price, and quantity. The platform places the verification call.
* **Status mapping**: Choose which WooCommerce order status to set when the customer confirms (DTMF 1) and when the customer cancels (DTMF 2). Custom order statuses are supported.
* **Recent events**: View a log of recent webhook events in the settings page.
* **Order metabox**: On each order edit screen, see whether the order was sent to the platform and its verification status.

Requirements:

* WooCommerce 5.0 or later
* PHP 7.4 or later
* A Call Verification platform account and API key with scopes: verify:create, verify:read, webhooks:manage

Data handling and privacy:

* This plugin sends order verification data to the Call Verification service (`https://api.textbari.com`) after you configure API credentials.
* Data sent includes: order reference, customer first/last name, billing phone number, quantity, and order value.
* Incoming webhooks must carry a valid HMAC-SHA256 signature made with your API secret (plus a fresh timestamp); the per-site shared secret in the webhook URL is checked in addition. Webhooks are rejected while no API secret is configured.
* The plugin stores recent webhook events locally in WordPress options for admin display. Credentials are stored with autoload disabled, and customer phone numbers are masked in the WooCommerce log (WooCommerce → Status → Logs).
* Site owners should review and publish their own privacy disclosures for customers where required.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` or install via WordPress admin.
2. Activate the plugin through the 'Plugins' screen. WooCommerce must be active.
3. Go to WooCommerce → Call Verification and enter your API key and API secret.
4. Save settings to register your webhook URL with the platform.
5. Configure "When customer confirms" and "When customer cancels" order status mapping.
6. New WooCommerce orders will be sent to the platform automatically.

== Frequently Asked Questions ==

= Where do I get an API key? =

Log in to your Call Verification dashboard, go to API Keys, and create a new key. Copy the key ID and secret (the secret is shown only once). Ensure the key has scopes: verify:create, verify:read, webhooks:manage.

= Can I keep the API secret out of the database? =

Yes. Add this line to `wp-config.php` (above "That's all, stop editing!"):

`define( 'CALL_VERIFICATION_API_SECRET', 'your-api-secret' );`

When the constant is defined it overrides any secret saved on the settings page, and the API secret field is disabled. Enter only the API key on the settings page and save to register the webhook.

= Who can open the settings page? =

Only Administrators (the `manage_options` capability), because the page holds the API credentials. Shop managers can still use the "Send / Resend now" button on individual orders.

= My site uses HTTP, not HTTPS. Will webhooks work? =

The platform requires HTTPS for webhook URLs. Use HTTPS for your site so the webhook can be registered.

= Can I use custom order statuses? =

Yes. The status mapping dropdowns include all WooCommerce order statuses, including any custom statuses you have registered.

== Screenshots ==

1. Settings page: Connection and API credentials
2. Settings page: Order status mapping and recent events

== Changelog ==

= 1.0.8 =
* Security: Incoming webhooks now always require the HMAC signature made with your API secret. The secret in the webhook URL alone is no longer accepted; webhooks are rejected while no API secret is configured.
* Security: The settings page, "Test connection" and "Send test order" are restricted to Administrators (`manage_options`). The order "Send / Resend now" button still works for shop managers.
* Security: Requests to the platform no longer follow HTTP redirects, so credentials and order data can never be forwarded to another host. A redirect is reported as an error.
* Security: The API key/secret and webhook secret are stored with autoload disabled (existing installs are migrated automatically). New optional `CALL_VERIFICATION_API_SECRET` constant in wp-config.php keeps the secret out of the database.
* Privacy: Customer phone numbers are masked in the WooCommerce log (e.g. 01*******49). Order notes, which only staff can see, still show the number.
* Hardening: Messages from the platform are stripped of markup before they are stored in order notes, order meta or admin notices.
* Fix: Saving the settings registers the webhook with the NEW credentials (previously it ran before the new values were saved and used the old ones).
* Uninstall also removes the clock-offset options, pending background sends, webhook replay-guard data and the plugin's order meta.
* Removed leftover signature-debugging code.

= 1.0.7 =
* Security: Requests are signed with signature version 2, which also covers the per-request nonce (a captured request can no longer be replayed with a new nonce). Falls back to the previous signature automatically if the platform does not support version 2 yet.
* Reliability: "Rate limited" (429) answers — including the platform's concurrent-call limit — keep being retried past the normal 5 attempts, honouring the platform's Retry-After, for up to 24 hours.
* Reliability: Incoming webhooks check freshness against the platform's clock (the same learned clock offset used for outgoing requests), so a drifting server clock no longer rejects them.
* Reliability: A webhook is recorded as processed only after the order was actually updated, so a delivery that failed half-way can be retried by the platform.
* Phones written with the international "00" prefix (e.g. 00880 1XXXXXXXXX) are now sent correctly.
* Clearer messages when the platform account is suspended.
* Fixes: the clock-skew retry and the signature-version fallback can now both happen once on the same request; a 429 "anomaly detected" answer is retried on the normal 5-attempt schedule (not for 24 hours); "Send now" on an order the platform already finished adds an accurate note ("already processed on the platform (status: …)") instead of "Verification call queued".

= 1.0.6 =
* "Send now" on an order always re-posts it to the platform, even if a platform order id was stored earlier. The platform is now idempotent: the same order number with the same phone returns the existing order (and queues its call if it never went out); a reused order number with a different phone creates a new order.

= 1.0.5 =
* Reliability: Automatic clock-skew correction. If this server's clock differs from the platform's by more than the platform's replay-protection window, requests are no longer rejected — the plugin learns the platform's time from its responses, signs with the corrected time, and transparently retries. Fixes "no orders delivered" when the WordPress host and the platform run on different servers with unsynced clocks.
* Diagnostics: The settings page now shows the measured clock difference vs the platform ("in sync" / "X s behind|ahead") with an NTP hint.

= 1.0.4 =
* Reliability: Order sends now use WooCommerce Action Scheduler (with WP-Cron fallback) so orders are delivered even when WP-Cron is unreliable.
* Reliability: Failed order sends are retried automatically with backoff (up to 5 attempts) on transient errors (network, 429, 5xx).
* Diagnostics: New "Send test order" button on the settings page exercises the real order path and shows the exact failure reason (missing verify:create scope, out of credit, invalid phone, etc.).
* Diagnostics: New background-queue health indicator and a "Recent order send failures" list on the settings page.
* Diagnostics: Each order shows attempt count and a clear error, with a "Send / Resend now" button.
* UX: Order send results are now written as order notes for a visible audit trail.

= 1.0.3 =
* Added admin environment compatibility notice for unsupported WP/PHP/WooCommerce versions.

= 1.0.2 =
* Compatibility: Added metabox support for WooCommerce HPOS/new order editor screen (`woocommerce_page_wc-orders`).
* Compatibility: Updated tested metadata for current WordPress/WooCommerce releases.

= 1.0.1 =
* Security: Added webhook request authentication with a per-site shared secret.
* Security: Hardened order status option sanitization and validation.
* Compliance: Improved readme privacy disclosure and reduced tags to 5.

= 1.0.0 =
* Initial release. Connection, webhook registration, send orders to platform, receive webhooks, status mapping, events log, order metabox.

== Upgrade Notice ==

= 1.0.8 =
Security release: webhooks always require the API-secret signature, settings are Administrator-only, redirects are never followed, credentials are no longer autoloaded and phone numbers are masked in logs. Make sure your API secret is saved (or defined in wp-config.php) so webhooks keep working.

= 1.0.7 =
Stronger request signing, automatic retries while the platform's concurrent-call limit is reached, and more reliable webhooks — recommended for all installs.

= 1.0.5 =
Orders keep flowing even when this server's clock is out of sync with the platform (automatic clock-skew correction) — recommended for all installs where WordPress and the platform run on different servers.

= 1.0.4 =
Makes order delivery reliable (Action Scheduler + auto-retry) and adds a "Send test order" diagnostic that shows exactly why an order failed to send.

= 1.0.3 =
Adds compatibility warnings for unsupported environments.
