=== LuckyFlow - Raffles for WooCommerce ===
Contributors: racmanuel
Donate link: https://racmanuel.dev/
Tags: woocommerce raffle, raffle plugin, giveaway, competition, sweepstakes, ticket raffle, numbered tickets, lottery, contest, sorteo, rifa, concurso
Requires at least: 6.0
Requires PHP: 7.4
Requires Plugins: woocommerce
Tested up to: 7.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Run ticket-based raffles and competitions in WooCommerce with numbered tickets, interactive number selection, automatic winner draws, and email notifications.

== Description ==

LuckyFlow adds a powerful "Raffle" product type to WooCommerce, allowing you to run ticket-based raffles, giveaways, and competitions directly from your online store — no third-party services needed.

Each raffle product gets a configurable range of numbered tickets (e.g., #0001 to #1000). Customers browse available numbers using an interactive visual selector with search and range filters, pick their lucky numbers, and pay at checkout. Tickets are reserved atomically during the purchase process to prevent double-selling.

When the competition reaches its end date, winners are drawn automatically — or you can trigger winner selection manually at any time from the product edit screen. Both winners and store admins receive customizable WooCommerce email notifications with ticket and order details.

= Perfect for =

* Charity raffles and fundraising events
* Product launches, promotional giveaways, and limited-edition drops
* Sports clubs, community associations, and school competitions
* Paid-entry sweepstakes and contests
* Any event requiring fair, numbered ticket sales with automated winner selection

= Key Features =

* **Custom WooCommerce product type** — "Raffle" appears alongside Simple, Variable, and other product types in the dropdown.
* **Configurable ticket range** — Define start and end numbers per product. Tickets are auto-generated on save and the range is permanently locked after generation.
* **Interactive ticket selector** — Responsive numbered grid with real-time availability colors, search-by-number, and range filters (e.g., show only tickets #100–#200).
* **Atomic ticket reservation** — Tickets are reserved during checkout and held for a configurable timeout (in minutes per product). Expired reservations release automatically.
* **Per-product max tickets per user** — Limit how many tickets a single customer can purchase.
* **Automatic winner selection** — When the competition end date passes, winners are selected automatically from paid tickets. The count of winners is configurable per product.
* **Manual raffle actions** — From the product edit screen, shop managers can close a raffle immediately or trigger winner selection anytime via AJAX-powered metabox buttons.
* **WooCommerce email notifications** — Two built-in emails: Winner notification (to customer) and Admin winner summary. Both appear in WooCommerce > Settings > Emails and support standard template overrides.
* **Public participants list** — Optional tab on the product page showing who entered the raffle. You can toggle visibility and choose which columns appear: order number, customer name, ticket numbers, and join date.
* **Progress bar and stats** — Real-time ticket sales progress with percentage and count, displayed on the product page and optionally on the shop loop. Can be toggled per product.
* **Sold-out behavior** — Three configurable actions when all tickets sell: do nothing, close the raffle, or close and select winners immediately.
* **Configurable scheduler** — Fine-tune how often the system checks for expired reservations, closed competitions, and winner selection via **Settings > LuckyFlow**. Defaults: 1 min / 60 min / 60 min.
* **Admin order integration** — Ticket numbers appear in WooCommerce order item details. Internal reservation metadata is hidden from the customer-facing order view.
* **Winners overview metabox** — Readonly panel on each raffle product showing selected winners with ticket numbers, order IDs, and customer links.
* **Full translation ready** — Includes `.pot` file and complete Spanish (es_ES) translation. Compatible with Loco Translate and Poedit.
* **Clean uninstall** — Deletes the custom database table (`luckyflow_tickets`), plugin options, scheduled tasks, and flushes cache on uninstall.

= Technical Notes =

* Uses a custom database table (`wp_luckyflow_tickets`) for ticket tracking with indexes on product_id, status, reservation_key, and reserved_until.
* Scheduled tasks run via Action Scheduler (bundled with WooCommerce) under the `luckyflow` group. View runs in **WooCommerce > Status > Scheduled Actions**.
* Ticket range locking is enforced: once tickets are generated for a product, the range fields become read-only to prevent data corruption.
* The plugin hooks into `woocommerce_product_data_tabs`, `woocommerce_product_data_panels`, `woocommerce_process_product_meta`, and `woocommerce_email_classes` for native integration.
* Filter available: `LuckyFlow_Tickets_per_page` (int) — controls how many tickets per page in the frontend selector (default: 100).

= Requirements =

* WordPress 6.0 or higher
* PHP 7.4 or higher
* WooCommerce (any recent version supporting Action Scheduler)

== Installation ==

1. Upload the `luckyflow-raffles` folder to `/wp-content/plugins/`, or install via the WordPress plugin installer.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Verify that WooCommerce is installed and active.
4. Go to **Products > Add New** and select "Raffle" from the product type dropdown.
5. In the **Raffle** tab, configure:
   * Competition start and end dates
   * Ticket number range (start and end)
   * Maximum tickets per user
   * Number of winners to select
   * Reservation timeout in minutes
   * Frontend stats and participants tab visibility
   * Sold-out behavior
6. Optionally, adjust the scheduler intervals at **Settings > LuckyFlow**.
7. Publish the product — tickets are generated automatically and the range is locked.

== Frequently Asked Questions ==

= How do I create a raffle product? =

Go to **Products > Add New**. In the Product Data metabox, select **Raffle** from the product type dropdown. Fill in the Raffle tab fields (ticket range, dates, winner count, etc.), publish, and tickets are auto-generated.

= Can customers pick their own ticket numbers? =

Yes. The frontend displays an interactive grid of numbered tickets with a color-coded legend (available, reserved, sold, winner). Customers can click individual numbers, search by number, or filter by range.

= What happens if a customer abandons checkout? =

Tickets reserved during checkout are automatically released after the configured timeout (in minutes, set per product). You can configure the cleanup interval at **Settings > LuckyFlow**.

= How are winners selected? =

Winners are drawn automatically from paid tickets when the competition end date passes. You can also trigger winner selection manually from the product edit screen via the "Raffle actions" metabox. The number of winners is set per product.

= Can I change the ticket range after tickets are sold? =

No. Once tickets are generated, the range fields become read-only to ensure data integrity and fairness. This is enforced automatically.

= How are winners notified? =

Two WooCommerce emails are sent: a Winner email to the customer (with winning ticket number and order details) and an Admin email to the store admin (listing all winners). Both emails appear under **WooCommerce > Settings > Emails** and support template overrides.

= Does it work with any WooCommerce theme? =

Yes. LuckyFlow uses standard WooCommerce hooks and templates. It works with any theme that supports WooCommerce, including block-based (FSE) themes.

= How do I translate LuckyFlow? =

The plugin includes a `.pot` file and a complete Spanish (es_ES) translation. Use Loco Translate or Poedit for other languages. Place `.po`/`.mo` files in `/wp-content/languages/plugins/`.

= How do I monitor scheduled tasks? =

Go to **WooCommerce > Status > Scheduled Actions** and filter by the `luckyflow` group. You'll see the three recurring tasks: release expired reservations, close expired competitions, and select winners.

= What data does the plugin store? =

Ticket purchase data (ticket numbers, order IDs, user IDs) is stored in a custom database table (`wp_luckyflow_tickets`). This data is used exclusively for raffle operations. No personal data beyond what WooCommerce already collects is stored. No data is sent externally.

== Screenshots ==

1. **Raffle product data tab** — Configure ticket range, competition dates, winners count, reservation timeout, frontend visibility, and sold-out actions.
2. **Interactive ticket selector** — Responsive grid with color legend, search bar, and range filters on the product page.
3. **Cart and checkout** — Selected ticket numbers displayed with reservation countdown.
4. **Winners overview metabox** — Admin panel showing winners with ticket numbers, order IDs, and customer details.
5. **Raffle actions metabox** — Manual close and select-winners buttons in the product sidebar.
6. **Settings > LuckyFlow** — Scheduler interval configuration for the three automated tasks.

== Support ==

For support, please use the [WordPress.org support forums](https://wordpress.org/support/plugin/luckyflow-raffles/).

For documentation and updates, visit [racmanuel.dev](https://racmanuel.dev/).

== Privacy Policy ==

LuckyFlow stores ticket purchase data (ticket numbers, order IDs, user IDs) in a custom database table (`wp_luckyflow_tickets`). This data is used exclusively for raffle functionality: ticket reservation, payment tracking, and winner selection.

When the plugin is uninstalled, all stored data (table, options, scheduled tasks) is permanently deleted.

LuckyFlow does not:
* Collect or store any personal data beyond what WooCommerce already collects during checkout.
* Send any data to external servers or third-party services.
* Use cookies beyond what WordPress and WooCommerce already set.

== Changelog ==

= 1.0.0 =
* Initial release.
* Custom WooCommerce "Raffle" product type.
* Interactive numbered ticket selector with search and range filters.
* Atomic ticket reservation with configurable timeout.
* Per-product max tickets per user.
* Automatic and manual winner selection (AJAX-powered metabox).
* WooCommerce email notifications (Winner + Admin Winner).
* Public participants tab with configurable display columns.
* Progress bar and stats on product and shop loop pages.
* Sold-out actions: none, close, close and select winners.
* Configurable scheduler intervals via Settings > LuckyFlow.
* Admin order item integration with ticket number display.
* Spanish (es_ES) translation included.
* Clean uninstall with full data removal.
* Action Scheduler integration under the `luckyflow` group.

== Upgrade Notice ==

= 1.0.0 =
Initial release. No upgrade steps needed. Install, activate, and create your first raffle product.