Ticket vouchers now return remaining and decrement on use

The ticket-vouchers lookup previously returned the tier entitlement
every time, so a donor could keep claiming free tickets by re-
submitting the form. It now subtracts vouchers already consumed:

  remaining = entitled - used

where `used` is the sum of the Vouchers column across that donor's
prior ticket orders (each checkout stores what it applied). Response
gains entitled/used/remaining; `vouchers` is now the remaining count
the form should grant. Consumption is implicit — no counter to keep in
sync — and resets by zeroing/deleting the Vouchers value on the order
row in NocoDB.

- nocodb: findByEmail + vouchersUsedByEmail (case-insensitive).
- 8 new tests (36 total). Doc updated with the new response + reset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/fluentforms-ticket-vouchers.md

@@ -14,16 +14,32 @@ ticketing backend.
 GET https://scan.beartariacampgrounds.com/api/public/ticket-vouchers?key=<SECRET>&email=<email>
 ```
 
-Returns only the count — never names or dollar amounts:
+Returns the **remaining** free-ticket count — never names or dollar amounts:
 
 ```json
-{ "vouchers": 0 }   // or 1, or 2
+{ "vouchers": 1, "entitled": 2, "used": 1, "remaining": 1 }
 ```
 
+- `vouchers` / `remaining` — how many free tickets are **still available** (this
+  is what the form should grant). Use `vouchers`; `remaining` is an alias.
+- `entitled` — the tier entitlement earned from giving (0/1/2).
+- `used` — vouchers already consumed by this donor's prior ticket orders.
 - `key` = the value of `PUBLIC_LOOKUP_SECRET` (set in the backend `.env`).
 - `email` = the donor's email (URL-encoded).
 - Rate-limited (30 requests / minute / IP) and CORS-restricted to
-  `PUBLIC_LOOKUP_ORIGIN` (default `https://tickets.beartariacampgrounds.com`).
+  `PUBLIC_LOOKUP_ORIGIN` (`tickets.` + `vendors.beartariacampgrounds.com`).
+
+### Vouchers decrement as they're used
+
+`remaining = entitled − used`, where `used` is the sum of the **Vouchers**
+column across every ticket order placed with that email. Each checkout stores
+the vouchers it applied, so the next lookup returns fewer — a donor can't keep
+claiming free tickets by re-submitting the form. Once `used ≥ entitled`,
+`vouchers` is `0`.
+
+**To reset for testing:** in NocoDB, zero out (or delete) the **Vouchers**
+value on that donor's ticket order row(s). `used` drops and `remaining` rises on
+the next lookup — no redeploy needed.
 
 > The secret is visible in page source, so treat it as **deterrence, not
 > security** — it only gates a 0/1/2 count. Rotate it by changing
@@ -107,9 +123,8 @@ field `free_tickets` you can use for conditional logic or to cap a quantity.
 
 ```
 curl "https://scan.beartariacampgrounds.com/api/public/ticket-vouchers?key=<SECRET>&email=<a-real-donor-email>"
-# >= $1000 since cutoff -> {"vouchers":2}
-# >= $400  since cutoff -> {"vouchers":1}
-# otherwise             -> {"vouchers":0}
+# entitled 2, none used yet -> {"vouchers":2,"entitled":2,"used":0,"remaining":2}
+# after a checkout using 2  -> {"vouchers":0,"entitled":2,"used":2,"remaining":0}
 ```
 
 Related: [`fluentforms-donor-discount.md`](./fluentforms-donor-discount.md) — the