=== Riders Delivery for WooCommerce ===
Contributors: alkady22
Tags: woocommerce, delivery, kuwait, riders, shipping
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Sync WooCommerce orders to the Riders Kuwait same-day delivery platform with a full Kuwait address widget at checkout.

== Description ==

**Riders Delivery for WooCommerce** connects your WooCommerce store to the [Riders](https://tryriders.com) Kuwait delivery platform. It handles the entire flow — from address capture at checkout all the way to order delivery and tracking.

= Key Features =

* **Kuwait address widget** at both classic and Blocks (Gutenberg) checkout: Governorate → Area → Block → Street → House cascading dropdowns
* **Civil ID / PACI lookup** — customers can auto-fill their address from their Kuwaiti civil ID number
* **Automatic or manual order sync** to Riders via Action Scheduler background jobs
* **Delivery status polling** — order status updated every 5 minutes; or instantly via webhook push
* **Webhook support** — receive real-time status updates from Riders (HMAC-verified)
* **Admin orders list** — filter by sync status, retry failed orders individually or in bulk
* **Per-order meta box** — view sync status, delivery fee, fleet number, and edit the Kuwait address with cascading dropdowns directly in the WooCommerce order
* **Tracking links** — fleet tracking link appended to WooCommerce order completion emails
* **Proper WC_Shipping_Method** — add Riders Delivery to any shipping zone with configurable flat rate and free-shipping threshold
* **WooCommerce REST API extension** — `/wc/v3/orders` responses include `riders_sync_status`, `riders_uid`, and `riders_fleet_number`
* **English and Arabic (RTL)** support
* **HPOS compatible** — High-Performance Order Storage declared and tested
* **Idempotent sync** — duplicate delivery prevention with syncing-status guard
* **Transient-cached geo data** — governorates/areas/blocks/streets cached for 1 hour to reduce API calls

= Requirements =

* WooCommerce 7.5 or higher
* PHP 8.0 or higher
* A [Riders vendor account](https://tryriders.com) with an API key

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` or install via the WordPress plugins screen.
2. Activate the plugin through the **Plugins** screen.
3. Ensure WooCommerce is installed and active.
4. Go to **WooCommerce → Riders** and enter your Riders API key.
5. Click **Verify API Key**, select your default branch, and configure sync options.
6. (Optional) Enable **Auto-configure Kuwait shipping zone** under **WooCommerce → Riders → Sync** if you want Riders to create a starter Kuwait zone for you.
7. (Optional) Add **Riders Delivery** as a shipping method in **WooCommerce → Settings → Shipping → Zones**.

== Frequently Asked Questions ==

= Does this work with the WooCommerce Blocks checkout? =

Yes. Both the classic shortcode-based checkout and the new Blocks (Gutenberg) checkout are fully supported.

= Is High-Performance Order Storage (HPOS) supported? =

Yes. The plugin declares compatibility and all order data access uses HPOS-safe WooCommerce APIs.

= What phone number format does Riders require? =

Kuwait mobile numbers in E.164 format, e.g. `+96550123456`. The plugin automatically normalises 8-digit local numbers, international prefix variants, and the 9-digit format with a leading zero (e.g. `050123456`).

= How does the webhook work? =

Register `https://your-store.com/wp-json/riders/v1/webhook` as a webhook endpoint in your Riders vendor portal. The plugin verifies the HMAC-SHA256 signature on every request and updates the WooCommerce order status in real time.

= Can I use delivery notes templates? =

Yes. Go to **WooCommerce → Riders → Settings** and set a default delivery notes template. You can use `{order_id}`, `{customer_name}`, and `{items}` as placeholders.

= How do I retry failed syncs? =

Open **WooCommerce → Riders Orders**, click **Retry All Failed** to requeue all failed/review-needed orders at once, or use the per-order **Sync** button.

== External Services ==

This plugin connects to the Riders delivery platform (https://tryriders.com) to sync WooCommerce orders and retrieve Kuwait address data.

API endpoint: https://order-riders.trywebsight.com/api
API documentation: https://order-riders.trywebsight.com/docs/vendor
Vendor portal: https://test-vendor.tryriders.com

Data sent to Riders:

* Order details (items, total, billing/shipping address, customer phone) — when an order is synced
* Kuwait Civil ID number — only when a customer voluntarily uses the PACI lookup to auto-fill their address

All requests are made over HTTPS. A Riders vendor account and API key are required.
Please review the Riders website (https://tryriders.com) for terms and privacy information before using this plugin.

== Screenshots ==

1. Kuwait address widget at checkout with cascading dropdowns
2. Riders Orders admin list page with sync status
3. Per-order meta box with address editor and cascading dropdowns
4. Riders Settings page

== Changelog ==

= 1.1.1 =
* Moved settings page CSS/JS to enqueued admin assets.
* Geo REST endpoints now require a valid wp_rest nonce (PACI lookup included).
* WooCommerce log directory resolved via wc_get_log_directory() / wp_upload_dir().

= 1.0.0 =
* Initial release with full Kuwait address widget, classic + Blocks checkout support, auto/manual sync, PACI lookup, admin orders page, and per-order address editor.

= 1.1.0 =
* Added idempotency guard to prevent duplicate Riders deliveries on concurrent sync jobs.
* Fixed sync status overwrite on already-synced orders.
* Added country guard to classic checkout save — non-Kuwait orders no longer get Kuwait address meta.
* Fixed shipping-address formatter to respect "ship to different address" with non-KW shipping country.
* Fixed COD unpaid order logic in `onOrderProcessing`.
* Added DB migration on plugin update (no longer requires deactivate/reactivate).
* Fixed Blocks checkout silent pass when extension data is null for Kuwait orders.
* Fixed `RiderOrder::updateOrCreate()` race condition on concurrent inserts.
* Added WooCommerce Subscriptions renewal guard — renewal orders skipped from auto-sync.
* Hooked `woocommerce_delete_order` / `woocommerce_trash_order` to clean up `riders_orders` row.
* Deactivation now unschedules all pending sync jobs, not just polling.
* `uninstall.php` now deletes all `_riders_*` order meta from both classic and HPOS tables.
* Fixed `riders_is_cancellable` bool coercion bug (`"0"` was casting to `true`).
* Added `050xxxxxxx` (9-digit with leading zero) to Kuwait phone normalizer.
* Sanitized geo REST endpoint 502 error responses — raw API errors no longer exposed publicly.
* `RidersApiClient` now throws on HTTP 2xx + non-JSON body instead of silently returning empty array.
* After saving address in the admin, sync is now auto-dispatched (no separate Retry Sync click needed).
* Added 1-hour transient caching to all geo endpoints; cache cleared on API key change.
* `wc-shipped` custom status registered as `public => false` (not visible in front-end order queries).
* HTTP timeout now filterable via `riders_api_timeout` filter.
* Added proper `WC_Shipping_Method` subclass (`riders_delivery`) for use in WooCommerce Shipping Zones.
* Added Riders tracking link to WooCommerce order completion emails.
* Added real-time webhook endpoint (`POST /riders/v1/webhook`) with HMAC-SHA256 verification.
* Added delivery notes template variable substitution (`{order_id}`, `{customer_name}`, `{items}`).
* Extended `/wc/v3/orders` REST API with `riders_sync_status`, `riders_uid`, `riders_fleet_number`, `riders_error`.
* Added **Retry All Failed** one-click button on the Riders Orders admin page.
* `AddressValidator` now used as single validation entry point for both classic and Blocks checkout.
* Added checkout notice (not hard block) when block or house is missing from Kuwait address.
