=== WaffarAD Affiliate Network ===
Contributors: waffarx
Tags: affiliate, woocommerce, cashback, payment, gateway
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
WC requires at least: 6.0
WC tested up to: 10.8
Stable tag: 2.0.1
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html

WaffarAD (WaffarX's affiliate network) integration for WooCommerce: affiliate order tracking plus the WaffarX In-App Order payment gateway.

== Description ==

WaffarAD is WaffarX's affiliate network. WaffarX is the first cashback aggregator in the MENA region. This plugin connects your WooCommerce store to WaffarAD/WaffarX and provides three features, each of which can be enabled independently:

1. Affiliate order tracking — reports orders referred through WaffarAD (and their status changes) to the WaffarX conversion server so conversions and cashback can be attributed and reconciled.

2. In-App Order payment gateway — an API-only gateway (hidden from the storefront checkout) that lets WaffarX place orders on your store via a private REST API, carrying installment/BNPL transaction metadata (e.g. ValU).

3. WaffarX Coupons — an API-only feature that lets WaffarX mint single-use WooCommerce coupons when a customer redeems a WaffarX gift-card voucher. Issuance, redemption (with the actual discount applied), and reversal are reported to WaffarX for billing reconciliation.

4. WaffarX Platform API — a private REST API that lets WaffarX run the full in-app commerce flow (browse products, read payment gateways and shipping data, quote shipping rates, place/fetch/cancel/refund orders, and manage a cart) authenticated by the single WaffarX credential. This means WaffarX does not need separate WooCommerce REST consumer keys; the merchant only configures one API Key and API Secret.

== External services ==

This plugin connects to services operated by WaffarAD/WaffarX:

1. Tracking script — https://waffarad.com/integration/general.js
   A JavaScript file loaded on the front end that sets and reads the WaffarAD affiliate tracking cookies. Loaded only while affiliate tracking is enabled.

2. Conversion server — https://conversion.waffarx.com
   The plugin POSTs to this server:
   * Woo/AddOrder — when a tracked order is created (the order details and affiliate identifiers).
   * Woo/UpdateOrder — when a tracked order changes status (updated status and totals).
   * Woo/PluginState — when the plugin or a feature is activated, deactivated, toggled, or uninstalled.
   * Woo/Settings — read periodically (hourly) for WaffarX-controlled settings, such as whether to report updates for all orders.
   * Woo/Coupon — when a WaffarX-issued coupon is created (issued), redeemed on an order, or reversed (the order is cancelled/refunded). Each event carries a unique event id and, for redemptions/reversals, the actual discount applied.

   When an API secret is configured, requests are signed with HMAC-SHA256 (X-WaffarX-Key / X-WaffarX-Timestamp / X-WaffarX-Signature); the secret itself is never transmitted.

The plugin also exposes an inbound REST API (namespace waffarx/v1) that WaffarX calls to place/fetch/cancel/refund orders, mint/fetch/void coupons, and read catalog/shipping/payment data (the WaffarX Platform API). All of it is authenticated with the single WaffarX API credential — either a Bearer token (the API Secret) or an HMAC signature — so no WooCommerce consumer keys are required. See the FAQ.

These services are provided by WaffarAD. For details, see https://waffarad.com/Home/PrivacyPolicy

== Frequently Asked Questions ==

= How do I enable or disable each feature? =

Affiliate tracking: Settings → WaffarAD Tracking → "Enable affiliate order tracking" (on by default).
In-App Order gateway: WooCommerce → Settings → Payments → In-App Order → Enable/Disable.
WaffarX Coupons: Settings → WaffarAD Tracking → "Enable WaffarX Coupons" (on by default).
WaffarX Platform API: Settings → WaffarAD Tracking → "Enable the WaffarX Platform API" (on by default). Turn this off if you do not want the catalog/cart/shipping/order-list/refund API exposed.
Each toggle notifies WaffarX.

= Where do I configure the credentials? =

Settings → WaffarAD Tracking → "WaffarX API Credentials": a single API Key and API Secret, provided to you by WaffarX. This one pair powers everything — it identifies your store, signs outbound reporting, and authenticates every inbound WaffarX API call. Alternatively, define WAFFARAD_API_KEY and WAFFARAD_API_SECRET in wp-config.php; those constants take precedence. No WooCommerce REST consumer keys are needed. Inbound requests are not run as any WordPress user; the Platform API authorizes its internal WooCommerce calls only for the duration of each request.

= How does WaffarX authenticate to the API? =

With the single API Secret, either way:
* Bearer token: Authorization: Bearer <api_secret>
* HMAC signature: X-WaffarX-Key + X-WaffarX-Timestamp + X-WaffarX-Signature, where the signature is HMAC-SHA256 of "timestamp.rawBody" using the secret (a short timestamp window guards against replay).

= Where do I configure the In-App Order gateway? =

WooCommerce → Settings → Payments → In-App Order: the allowed gateway values and allowed gateway statuses. (Authentication uses the unified WaffarX API Secret above — there is no separate gateway token.)

= What are the In-App Order REST endpoints? =

Base: https://your-domain.com/wp-json/waffarx/v1
* POST /order — place an order (requires gateway + transaction metadata; accepts optional affiliate attribution).
* GET  /order/{id} — fetch an order.
* GET  /order/by-idempotency-key?key=… — look up an order by idempotency key (full WooCommerce data).
* POST /order/{id}/cancel — cancel an order.
All require the unified WaffarX authentication (Bearer token = the API Secret, or an X-WaffarX HMAC signature).

= What are the WaffarX Platform API endpoints? =

Base: https://your-domain.com/wp-json/waffarx/v1 (all authenticated with the unified WaffarX credential; enabled via Settings → WaffarAD Tracking → "WaffarX Platform API"):
* GET  /products, GET /products/{id}, GET /products/{id}/variations — catalog.
* GET  /payment-gateways — available payment methods.
* GET  /data/countries, GET /data/countries/{code} — countries and provinces.
* GET  /shipping/zones, GET /shipping/zones/{id}/methods — shipping configuration.
* POST /shipping-rates — stateless shipping quote for given line_items + destination.
* GET  /orders — list orders.
* POST /order/{id}/refund — refund an order (send api_refund=false for a manual/records-only refund).
* GET  /cart, POST /cart/add-item, POST /cart/update-customer, POST /cart/select-shipping-rate — cart (Store API; pass the Cart-Token header returned by GET /cart).
These forward to WooCommerce's own REST endpoints internally, so behavior and schemas match core WooCommerce.

= What are the WaffarX Coupons REST endpoints? =

Base: https://your-domain.com/wp-json/waffarx/v1
* POST /coupon — mint a single-use coupon. Body: amount (required), waffarx_reference (required object with voucher_id and optional batch_id/third_party_id/partner_id), and optional code, discount_type (default fixed_cart), expiry_date (YYYY-MM-DD), and individual_use (default false). If no code is supplied the plugin generates one and returns it. Minting is idempotent per voucher_id; a supplied code that already exists is rejected.
* GET  /coupon/{code} — fetch a WaffarX-issued coupon.
* POST /coupon/{code}/void — disable an unused WaffarX-issued coupon.
The same authentication as the In-App Order API applies; mutating routes (create, void) require the feature to be enabled.

== Changelog ==

= 2.0.1 =
* In-App Order gateway orders: any order update is now mirrored (signed, non-blocking) to the WaffarX order-update webhook, when the new "Order-Update Webhook af_id" setting is filled. Payload is the full order plus a "waffarx" block (affiliate attribution + gateway metadata such as loan id). Sent once per order per request.

= 2.0.0 =
* Renamed to "WaffarAD Affiliate Network" and merged in the WaffarX In-App Order payment gateway.
* Affiliate tracking, the In-App Order gateway, and WaffarX Coupons can each be enabled/disabled independently; each toggle notifies WaffarX.
* In-App Order: API-only WooCommerce gateway (hidden from checkout) with REST endpoints to place/fetch/cancel orders, idempotency, and a custom transactions table.
* Orders placed via the gateway are marked paid + processing (BNPL authorized & captured) and reported to the conversion server; the order API accepts optional affiliate attribution.
* WaffarX Coupons: API-only minting of single-use WooCommerce coupons (REST endpoints to create/fetch/void), idempotent per voucher, with issuance, redemption (actual discount applied), and reversal reported to the conversion server on a single Woo/Coupon route carrying an event field and a unique event id.
* Unified credentials: a single WaffarX API Key + API Secret powers every feature (signing outbound reporting AND authenticating all inbound calls). Inbound authentication accepts either a Bearer token (the API Secret) or an HMAC signature (X-WaffarX-Key / X-WaffarX-Timestamp / X-WaffarX-Signature) with replay protection.
* WaffarX Platform API (namespace waffarx/v1, separately toggleable): products, payment gateways, countries/provinces, shipping zones, a stateless shipping-rate quote, order listing and refunds, and cart (Store API) — all authenticated by the single WaffarX credential, with WooCommerce calls authorized per-request (no user impersonation), so WooCommerce REST consumer keys are not required.
* Webhook on plugin/feature activate, deactivate, toggle, and uninstall.
* Class-based structure; HPOS compatible.

= 1.0.5 =
* Order-insertion rewrite: send on order creation (classic + block checkout), idempotency guard, presence-based attribution check, paid-price fix, HMAC signing, settings screen, status-change reporting (UpdateOrder), optional all-orders reporting via a remote switch, privacy disclosure.

= 1.0.4 =
* WordPress.org standards/security pass (ABSPATH guard, GPL header, escaping, cookie sanitization, documented external services).