=== VoucherCart ===
Contributors: vouchercartltd
Tags: vouchers, gift cards, coupons, woocommerce
Requires at least: 6.5
Tested up to: 7.1
Stable tag: 1.0.7
Requires PHP: 8.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect your WooCommerce store to VoucherCart to sell and redeem vouchers and gift cards as WooCommerce coupons.

== Description ==

VoucherCart is the voucher and gift card sales engine for your business. This plugin connects your WooCommerce store to your [VoucherCart](https://vouchercart.com/) account, so vouchers sold through VoucherCart can be redeemed directly at your WooCommerce checkout.

= Features =

- Vouchers issued by VoucherCart are created automatically as WooCommerce coupons in your store.
- Coupon codes, expiry dates and redemption status stay in sync with VoucherCart.
- Redemptions at your WooCommerce checkout are reported back to VoucherCart, including partial redemptions and refunds when orders change.
- Simple connection management from the Plugins screen — copy your site URL and API secret into VoucherCart and you're done.

= Requirements =

- WordPress 6.5 or newer, and WooCommerce (declared as a required plugin dependency).
- PHP 8.1 or newer.
- A VoucherCart account.

= How it works =

Communication between VoucherCart and your store happens over the WordPress REST API. Every request is authenticated with an HMAC-SHA256 signature using the API secret generated for your site, so only VoucherCart can create or modify vouchers in your store.

== Source code ==

This plugin is not compiled except for one admin stylesheet and one admin script. Everything else runs exactly as it is written.

* The PHP under `app/` is the plugin itself. It has no third-party runtime dependencies, so there is no bundled library and no `vendor` directory.
* The minified admin assets in `dist/assets/` are built from the human-readable TypeScript and CSS in `src/admin/`, which is included in this plugin package. Each built file also carries a comment pointing back here.

= Build tools =

The build is a stock [Vite](https://vite.dev/) setup; the whole configuration is in `vite.config.ts`, shipped with the plugin. To reproduce `dist/` from `src/`, run the following in the plugin directory:

`bun install && bun run build`

`npm install && npm run build` works identically if you prefer npm. Both read `package.json` and `tsconfig.json`, which are also included in this package. The build output is content-hashed, so filenames in `dist/assets/` change whenever the source changes.

== External services ==

This plugin connects your store to VoucherCart, the voucher and gift card platform at [vouchercart.com](https://vouchercart.com/). The integration is the entire purpose of the plugin: without a VoucherCart account it does nothing. Traffic flows in both directions, and in both directions every request is signed with an HMAC-SHA256 signature derived from the API secret that this plugin generates for your site.

**What this plugin sends to VoucherCart**

The plugin contacts `https://api.vouchercart.com/` in exactly two situations, and never on a page view by one of your visitors:

* When a VoucherCart coupon is applied to an order, or an order carrying one is placed or completed, the plugin reports the redemption. It transmits the VoucherCart reference of the voucher and the discount amount that the order actually took.
* When that coupon is removed from the order, or the order is cancelled, the plugin cancels the redemption it previously reported. It transmits the identifier VoucherCart returned for that redemption.

Both requests also carry the client identifier VoucherCart issued to your site, a timestamp and the signature. No customer details, no order contents, and no other store data leave your site.

**What VoucherCart sends to this plugin**

VoucherCart calls your site's REST API under `/wp-json/vouchercart/v1/` to keep the store side in step: creating a WooCommerce coupon for a voucher it has issued, changing that coupon's code, expiry date or remaining value, deleting it, or removing it from orders that already used it. These requests are only accepted when they carry a valid signature.

You choose when this starts: nothing is transmitted until you copy your site URL and API secret into your VoucherCart account, and deactivating the plugin ends it.

Your use of the service is governed by VoucherCart's [privacy policy](https://vouchercart.com/privacy-policy/) and by the terms of the VoucherCart account agreement you enter into when you register.

== Installation ==

1. Install and activate WooCommerce.
2. Upload the plugin files to `/wp-content/plugins/vouchercart`, or install the plugin through the WordPress plugins screen directly.
3. Activate the plugin through the _Plugins_ screen in WordPress.
4. On the _Plugins_ screen, open _Connection management_ under the VoucherCart plugin entry.
5. Copy the website URL and API secret into your VoucherCart account's WooCommerce integration settings.

== Frequently Asked Questions ==

= Do I need a VoucherCart account? =

Yes. The plugin is the store-side half of the integration; vouchers are created and managed from your VoucherCart account at [vouchercart.com](https://vouchercart.com/).

= Does this work without WooCommerce? =

No. Vouchers are redeemed as WooCommerce coupons, so WooCommerce must be installed and active.

= What data is shared with VoucherCart? =

Only what is needed to keep a voucher balance correct: the VoucherCart reference of the voucher and the amount an order discounted with it. No customer details and no other order data are sent. See the _External services_ section above for the full description.

== Changelog ==

= 1.0.6 =

- The readme now documents where the source of the minified admin assets lives and how to rebuild it, and the built files themselves point back at it.

= 1.0.5 =

Security release.

- REST requests are now refused when the site has no API secret, instead of accepting a signature anyone could compute.
- Calls to VoucherCart always verify the TLS certificate, and can no longer be redirected by an environment variable belonging to other software on the server.
- The connection management dialog, which shows the API secret, is restricted to administrators.
- All REST parameters are validated and sanitised.
- Plugin files can no longer be executed by requesting them directly.

= 1.0.4 =

- A voucher detached from a deactivated card gets its coupon back in the store, so it can be redeemed again.
- Creating a coupon for a voucher that already has one now leaves the existing coupon in place instead of adding a second one with the same code.

= 1.0.3 =

- A multi-use voucher with a balance left no longer leaves its coupon without a usage limit, so the same balance cannot be discounted by any number of orders placed before the next sync.

= 1.0.2 =

- Vouchers without a cart value no longer get a coupon, and expiry, code and order updates for them are treated as a no-op instead of an error.
- A coupon whose voucher record is gone from the store is no longer reported as a failure, so the rest of the sync finishes.

= 1.0.1 =

- Coupon balances now follow the voucher balance, so a partly redeemed multi-use voucher keeps working until it is spent.
- Redemption reporting moved into a single service shared by all order hooks, fixing inconsistent reports when an order was edited after placement.
- Deleting a voucher that no longer has a coupon in the store no longer aborts the rest of the sync.

= 1.0.0 =

- Initial release: voucher-to-coupon sync, redemption reporting, HMAC-secured REST API, connection management UI.

== Upgrade Notice ==

= 1.0.6 =
Documentation only: no functional changes.

= 1.0.5 =
Security release: hardens REST authentication, API parameter handling and access to the API secret. Recommended for all sites.

= 1.0.4 =
Restores coupons for vouchers detached from a deactivated card. Recommended for all sites.

= 1.0.3 =
Tightens the usage limit on multi-use voucher coupons. Recommended for all sites.

= 1.0.2 =
Stops failed syncs for vouchers that carry no cart value. Recommended for all sites.

= 1.0.1 =
Fixes voucher balance sync for partial redemptions. Recommended for all sites.

= 1.0.0 =
Initial release.
