=== Chit - Download codes for WooCommerce ===
Contributors: jpgleeson
Tags: woocommerce, downloads, redemption, codes, voucher
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.2
Requires Plugins: woocommerce
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Generate printable redemption codes for physical sales that unlock WooCommerce digital downloads.

== Description ==

**Chit** bridges your physical sales and your WooCommerce digital downloads. Print a code on a card, sticker, leaflet, or receipt; the customer enters the code on your site to receive access to the product's downloadable files. Picture this for selling in person at a market - you're selling your books but normally through webstore orders people get a PDF download too. This squares the circle.

It plugs into WooCommerce's existing download system rather than reinventing it. When a code is redeemed, Chit creates a real (zero-total) WooCommerce order for the customer, marks it complete, and WooCommerce grants the download permissions exactly as it would for a paid order. The redemption appears in the customer's **My Account → Downloads** page and in **WooCommerce → Orders** with a note explaining its origin.

= What you get =

* **Batch generation** — generate any number of codes for a product in one go, with optional batch notes (e.g. "Christmas flyer 2025" or "Games day 2026") so you can find them later.
* **Configurable code format** — set your own prefix (or none) and the code body (e.g. 2 groups of 4, 3 groups of 4, 2 groups of 6) under **Chit → Settings**, with a live preview. Defaults to `CHIT-XXXX-XXXX`.
* **Crockford-base32 characters** — no ambiguous characters (no 0/O, 1/I/L, or U/V confusion) so codes are easy to read off prints.
* **Admin code browser** — list table with status, batch, and product filters; sortable columns; per-row Revoke action; pagination.
* **Customer-facing redemption page** — auto-created on activation with the `[chit_redeem]` shortcode. Requires login (codes are tied to user accounts so customers can re-download anytime).
* **CSV import** — migrate codes you issued elsewhere, including their redemption state, under **Chit → Import**. Streams the file in background batches, so six-figure row counts are fine; a dry run validates everything before a single row is written.
* **CSV export** — three-column export (code, product name, redeem URL) suitable for mail merges or label printing.
* **PDF-ready print sheet** — 2×5 grid of cards per A4 page, each card showing product name, SKU, code, and the redeem URL. Uses the browser's native "Save as PDF" so quality is excellent and there are no third-party dependencies.
* **Reports** — at-a-glance counts (unused / activated / revoked) plus a top-products breakdown with activation rates.

= How it integrates with WooCommerce =

Chit does *not* maintain its own download permissions. On activation it creates a WooCommerce order on the customer's account with the redeemed product as a line item and a $0 total, then sets the order status to **completed**. WooCommerce's existing download-permission machinery takes care of the rest: the customer sees the order in their account, the download file appears in **My Account → Downloads**, the download counter and any expiry rules you have configured all behave normally.

== Installation ==

1. Upload the `chit` folder to `wp-content/plugins/` (or install via the Plugins screen).
2. Activate **Chit** through the **Plugins** screen.
3. A "Redeem Chit Code" page is created automatically and assigned the `[chit_redeem]` shortcode. You can find it under **Pages**, rename it, or move it under another menu as you like.
4. Go to **Chit → Settings** to set your code format (prefix, length, grouping) — or keep the default.
5. Generate your first batch under **Chit → Generate**.

= Requirements =

* WordPress 6.0 or newer
* WooCommerce 5.0 or newer
* PHP 7.4 or newer
* At least one **downloadable** WooCommerce product (a product with the "Downloadable" checkbox enabled and one or more files attached)

== Frequently Asked Questions ==

= Where does the customer enter their code? =

On the auto-created **Redeem Chit Code** page (slug `/redeem-chit-code/` by default). The page contains the `[chit_redeem]` shortcode, which renders the redemption form. You can move the shortcode to any other page or post and link to it from your menus.

= Does the customer need an account? =

By default, yes: codes grant download permission to the customer's WooCommerce account, so the files show up under **My Account → Downloads** and can be re-downloaded any time. Guests who try to redeem are sent to the login page first.

If you'd rather not make people register — say the download is a free extra bundled with a physical product — turn on **Allow redemption without an account** under **Chit → Settings**. Guests then enter their email address alongside the code. Chit creates a guest order, the download links appear on the success screen, and WooCommerce's "Completed order" email sends them a copy. Logged-in customers will keep the existing account flow.

= Can I change what the codes look like? =

Yes. **Chit → Settings** lets you set the prefix (including removing it entirely) and the shape of the code body — how many groups of how many characters, e.g. 2 groups of 6. Changing the format only affects newly generated codes — everything you've already issued keeps working exactly as printed, because redemption matches the stored code, not the current format.

= I already have codes from another system. Can I bring them in? =

Yes — **Chit → Import** accepts a CSV with the columns `code,sku,status,activated_at,activated_email` (a sample file is downloadable on that page). Codes keep their status, so already-used codes stay used. The import runs in the background via WooCommerce's scheduler, handles hundreds of thousands of rows, skips duplicates, and every import can be deleted again in one click.

= Can the same code be redeemed twice? =

No. Codes are single-use. Once redeemed, the status flips to `activated` permanently. If you need multi-use license-key behaviour, that's a different use case and not currently supported.

= I generated 50 codes for the wrong product. Can I cancel them? =

Yes. Visit **Chit → View Codes**, filter by the batch number, and click **Revoke** on each (or use the batch dropdown to scope the list). Revoked codes can't be redeemed.

= How are PDFs generated? =

The **Print PDF** action opens a standalone HTML page laid out for A4 print; you then use your browser's **Print → Save as PDF** option.

= The customer gets a "your order is complete" email after redeeming. Is that intentional? =

It's WooCommerce's default behaviour for any order moving to **completed** status. The email is useful as it contains the download link.

= What about uninstalling? =

Deactivating leaves your data intact. **Deleting** the plugin from the Plugins screen runs the uninstall script, which drops the `chit_codes` and `chit_batches` tables and clears the related options. The auto-created redemption page is *not* deleted — you can remove it manually from **Pages → Trash**.

= What capability is required for admin actions? =

`manage_woocommerce` — the same capability WooCommerce uses for its own back-office screens. Shop managers can use Chit; regular subscribers cannot.

== Changelog ==

= 1.2 =
* New: optional guest redemption (**Chit → Settings → Allow redemption without an account**). Guests redeem with their email address; download links are shown on screen and emailed. Off by default.
* New: the redemption success screen now lists the download links directly, for guests and account holders alike.
* Admin: guest redemptions show the customer's email in the "Activated by" column.

= 1.1 =
* New: configurable code format — prefix (or none) and code body shape, with live preview, under **Chit → Settings**.
* New: CSV import (**Chit → Import**) for codes issued elsewhere, including their redemption state. Dry-run validation, background processing via Action Scheduler, resumable, with one-click rollback per import.
* Fix: fatal error on PHP 7.4.
* Fix: redemption orders are now genuinely zero-total by default; previously they always booked the product's catalog price. A new setting under **Chit → Settings → Redemption orders** (or the `chit_redemption_zero_total` filter) restores the old behaviour.
* Database: the codes table now accepts codes up to 64 characters (imported codes); generated codes are unchanged.

= 1.0 =
* Initial release.
