=== EgyDevInfo Loyalty Points for WooCommerce ===
Contributors: egydevinfo
Tags: woocommerce, loyalty, points, badges, gamification
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
WC requires at least: 6.0
WC tested up to: 11.1
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A gamified WooCommerce loyalty program where customers earn points, unlock badge milestones (Bronze → Platinum), and redeem for discounts.

== Description ==

**EgyDevInfo Loyalty Points for WooCommerce** adds a progression system — four badge tiers with visual progress bars — so customers have a reason to keep shopping beyond the next discount.

Every purchase earns points. Points unlock badges. Badges give customers a tangible status to work toward, which keeps them coming back.

**No upsell gates. No nag screens. No premium tier.** Everything described here is in the free plugin.

= How the gamification works =

Customers move through four badge tiers as their lifetime points accumulate:

* 🥉 **Bronze Member** — 100 points
* 🥈 **Silver Member** — 500 points
* 🥇 **Gold Member** — 1,000 points
* 💎 **Platinum Member** — 2,500 points

A visual progress bar on the My Account dashboard shows exactly how close they are to the next badge, creating a clear goal for every returning visit.

Thresholds are fully configurable in WooCommerce → Rewards & Loyalty → Badge Management.

= Points system =

* **Earning:** configurable points per dollar spent (default: 1 point / $1)
* **Redemption:** configurable point value (default: 1 point = $0.01)
* **Safe flow:** points are staged at checkout and only permanently deducted when the order is marked complete — no points are lost to abandoned carts
* **Balance tracking:** real-time display in cart, checkout, My Account, and thank-you page

= Admin features =

* Configure earning rate and redemption value
* Adjust badge thresholds without touching code
* View all users' balances and earned badges in one table
* Control the floating engagement button — enable/disable, choose audience (guests, users with points, users without points), set screen position

= Frontend integration =

* Cart totals — current balance with currency value
* Checkout — redemption form above the order review (AJAX, no page reload)
* My Account dashboard — full breakdown: balance, lifetime stats, earned badges, next-badge progress bar
* Thank-you page — estimated points for the order just placed
* Floating button — configurable engagement prompt that can be disabled in settings; off by default for guests

= Technical =

* Namespaced OOP architecture with manual PSR-4 autoloader (no Composer, no build step)
* Nonces + capability checks on every state-changing request
* All input sanitized, all output escaped
* WooCommerce HPOS (High-Performance Order Storage) compatible
* Clean uninstall — removes all plugin data when deleted

== Installation ==

1. Upload the `egydevinfo-loyalty-points-for-woocommerce` folder to `/wp-content/plugins/`.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Go to **WooCommerce → Rewards & Loyalty** to configure your points rate and badge thresholds.
4. The plugin starts tracking points automatically for all new completed orders.

= Requirements =

* WordPress 5.8 or higher
* WooCommerce 6.0 or higher
* PHP 7.4 or higher

== Frequently Asked Questions ==

= How do customers earn points? =

Points are awarded automatically when an order is marked **Completed** in WooCommerce. The default rate is 1 point per $1 spent; change it in WooCommerce → Rewards & Loyalty → Points Settings.

= How does redemption work? =

On the checkout page, logged-in customers with a positive balance see a redemption form. They enter how many points to redeem; the discount is applied as a cart fee via AJAX. The points are only permanently deducted from their balance when the order is marked complete — not at the moment of clicking "Redeem".

= What happens to staged points if the customer abandons checkout? =

The staged redemption lives in the WooCommerce session. If the cart is emptied or the session expires without an order being placed, the session clears and the customer's balance is unchanged.

= Can I change the badge thresholds? =

Yes. Go to WooCommerce → Rewards & Loyalty → Badge Management and edit the threshold for any badge. Changes apply to future assignments only; already-earned badges are not revoked.

= Do points expire? =

Points do not expire in this version. Expiry may be added in a future update.

= Can I manually adjust a customer's points balance? =

Manual adjustment is planned for a future update. Currently, points are only earned through completed orders.

= Is this plugin compatible with WooCommerce HPOS? =

Yes. The plugin declares HPOS compatibility and uses WooCommerce order CRUD methods (`wc_get_order()`, `$order->get_*()`) throughout — no direct database queries on WooCommerce tables.

= Can the floating button be disabled? =

Yes. In WooCommerce → Rewards & Loyalty → Points Settings you can disable the floating button entirely, or choose which audiences see it (guests, logged-in users with points, logged-in users without points).

= Will this conflict with other loyalty plugins? =

Using more than one loyalty plugin at a time may cause unexpected behaviour. This plugin is designed to be a complete standalone solution.

== Screenshots ==

1. Admin settings page — points configuration and floating button controls
2. Badge Management — editable threshold table
3. User Points Overview — all users' balances and earned badges
4. My Account dashboard — current balance, lifetime stats, and badge progress bar
5. Checkout redemption form — AJAX points redemption before order review
6. Thank-you page — estimated points earned for the order

== Changelog ==

= 1.0.2 =
* Fix: Remove comparative claim from plugin description per WordPress.org guidelines
* Fix: Remove "Tested up to" from PHP plugin header (readme.txt only)
* Fix: Rename PHP namespace from RPP\Core to EgyDevInfoLP\Core (proper unique prefix)
* Fix: Rename wp_localize_script object from rpp_ajax to egydevinfo_lp_frontend
* Fix: Update Plugin URI to a live URL

= 1.0.1 =
* Fix: floating button panel modal now renders correctly (CSS was missing)
* Fix: JS now uses safe typeof check to prevent ReferenceError if localized data loads late

= 1.0.0 =
* Initial release
* Points earning on order completion (configurable rate)
* Points redemption at checkout with safe session-based staging
* Four-tier badge system (Bronze → Platinum) with configurable thresholds
* Visual progress bar toward next badge
* Full admin interface: settings, badge management, user points table
* Floating engagement button with audience and position controls
* WooCommerce HPOS compatibility declared

== Upgrade Notice ==

= 1.0.0 =
Initial release.
