=== Front of House for Event Espresso ===
Contributors: mmulligan
Tags: event espresso, check-in, point of sale, box office, receipts
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 0.22.2
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn any tablet into a device-trusted Event Espresso front-of-house station: check-in, POS sales, in-person payments, returns, and receipts.

== Description ==

**Front of House for Event Espresso** runs the box office of a live event from a tablet. Each device is trusted by an administrator, every action is attributed to the clerk who took it, and the whole shift is captured in an append-only audit trail. It is an Event Espresso add-on — it reads and writes through Event Espresso's own models, so a sale, a payment, or a return at the door is the same real transaction it would be in wp-admin.

The station runs as an installable PWA with no WordPress chrome: a clerk signs in with a badge, the tablet shows a fast registration search or a sales grid, and the door keeps moving.

= What a station can do =

* **Check-in.** Ranked name/email search, camera or hardware-wedge barcode scanning, cascade check-in across an event's datetimes, check-out, undo, and a manager-authorized force check-in for non-approved registrations. A segmented filter (All / Needs check-in / Needs payment) narrows the line to exactly who needs attention.
* **Sell / POS.** A category-tabbed item grid with per-ticket variations and quantity steppers, a persistent running-total cart, registrant questions, then a real Event Espresso transaction with automatic tax and full rollback if anything fails — no orphaned rows.
* **In-person payments.** Cash (with amount-tendered entry and live change-due), check, and card-present through a pluggable provider add-on. A shared transaction screen carries a role-governed payment gate so only permitted clerks can take money.
* **Returns, exchanges, and customer credit.** Returns and exchanges settle as real Event Espresso transactions — replacement items are genuine ticket purchases, returned goods are a typed return payment, and the server computes the net. Overpayments resolve to a cash refund (role- and event-gated), a forfeit, or store credit parked on the customer's account (via a companion credit plugin).
* **Bluetooth thermal receipts.** Print itemized receipts straight from the tablet to a 58mm thermal printer over Web Bluetooth — templated header and footer with token substitution, money-aligned line items, and a configurable tear feed. On-device test buttons prove the printer without ringing up a sale.
* **Clerk badges + scan-to-login.** Print a badge per clerk carrying a CODE128 barcode and a QR; a clerk signs in by scanning that badge with the device camera or a hardware wedge scanner, or by typing a code.
* **Manager assist.** A permitted manager can log in *over* an active clerk for a single task — a stacked, temporary session that preserves the base clerk's session and resumes it on exit.
* **Per-device themes.** Four CSS themes (a system-following default plus dark, light, and high-contrast variants), chosen per device by a manager.

= Built for the front desk =

* **Device trust.** A device enrolls from an enrollment link, an admin approves it with a nickname and station, and the device then operates on a one-time-delivered secret — the operating credential, not a shared token.
* **Clerks, not WP users.** Clerks are lightweight badge/PIN identities with configurable roles, idle and focus-loss timeouts, multi-login policy, and station scoping — volunteers never touch the WordPress user table or wp-admin.
* **Generic and reusable.** Core stays event-agnostic and ticket-native. Filters let companion plugins layer on ticket categories, row enrichment, payment providers, and customer credit without forking the core.
* **Multisite-ready.** Activate per site on a multisite network.

Full documentation and architecture notes live in the bundled **README.md**.

== Installation ==

1. Install and activate **Event Espresso 5** on the site first — this plugin is an Event Espresso add-on and does nothing without it.
2. Upload the plugin to `wp-content/plugins/` and activate it (activate per site on multisite).
3. Open the **Front of House** admin menu and set up your **Access Profiles**, **Clerk Roles**, **Clerks**, and **Settings** (including receipt header/footer).
4. Create an **Enrollment Link**, open it on a tablet, install the PWA, and approve the device under **Devices**.
5. The site should be served over **HTTPS** — the camera scanner and Bluetooth receipt printing require a secure context.

== Frequently Asked Questions ==

= Does this require Event Espresso? =

Yes. It is an Event Espresso add-on and is tested against Event Espresso 5. Sales, payments, check-ins, and returns are written through Event Espresso's own models, so they are identical to what wp-admin would produce.

= Why does it need HTTPS? =

The camera-based barcode/QR scanner (camera access) and Bluetooth thermal printing (Web Bluetooth) only work in a secure browser context. Serve the site over HTTPS and the station works on tablets and phones.

= How do clerks log in? =

A clerk signs in to a station with a badge — scanned by the device camera, read by a hardware wedge scanner, or typed in as a code. Clerks are not WordPress users; they are managed under **Front of House → Clerks** and governed by configurable roles. Treat a printed badge as a physical login key.

= What happens when the network drops? =

The station distinguishes a genuine network failure (an offline banner) from a server-side response such as a too-short search or an out-of-scope result (shown inline). When the card-present path charges but recording the payment fails, the station does not swallow it: it retries, prints a manager error slip, records an audit incident, and shows a blocking manager modal.

= Can I add card payments or store credit? =

Yes. Cash and check are built in. Card-present payments come from a pluggable provider add-on, and store credit / pay-with-credit come from a companion customer-credit plugin. When those companions are absent, the station hides the affordances entirely.

= Does it work on multisite? =

Yes. Activate it per site on a multisite network.

== Screenshots ==

1. Check-in station — registration search with the All / Needs check-in / Needs payment filter.
2. Sell / POS — category-tabbed item grid with variations and a running-total cart.
3. Transaction screen — cash tender with live change-due and the payment-method buttons.
4. Returns & exchanges — net settlement with cash refund, forfeit, and store-credit options.
5. Bluetooth receipt printer configuration with on-device test buttons.
6. Clerk badge sheet — CODE128 + QR for scan-to-login.
7. wp-admin — the Front of House admin section (profiles, devices, clerks, roles, audit).

== Changelog ==

= 0.22.2 =
* Update-details sections now come from readme.txt (WP-native); base/config renamed to .mu-manifest.yaml + .mu-release.yaml. No functional change.

= 0.22.1 =
* Release now flows through the shared manifest pipeline; the "View details" modal carries a description, changelog, and tags. No functional change to the plugin.

= 0.22.0 =
* Added a color-coded plugin icon (delivered through the update channel) and declared WordPress 7.0 compatibility. No functional change.

The full history is in **CHANGELOG.md** bundled with the plugin.

= 0.21.2 =
* Updates are now handled by the Manifest Updater plugin (via the standard "Update URI" header) instead of a bundled updater. No change to how Front of House works; this lets it run on a single site instead of network-wide. Requires the Manifest Updater plugin to be network-activated to receive update notifications.

= 0.21.1 =
* Fixed for real (multisite): the "payment method Return/Settlement was automatically deactivated" admin notice that kept coming back. Root cause was that Front of House auto-activated its internal Return/Settlement methods on every site in the network and then kept reactivating them, which Event Espresso re-deactivated in a loop. Those methods are now created only on the site that actually records a return/settlement (the desk site), and the stale notice is cleared in every admin context. No effect on how returns/settlements work.

= 0.21.0 =
* Per-method payment options. Settings ▸ Payment Methods now lets you set, per method, a custom button label, whether a check number is required, and (for card) a surcharge. A card surcharge is added to the sale as a real fee line item — it raises the total, prints on the receipt, and is recorded in Event Espresso — so the customer is actually charged it. Card payments include the surcharge in the amount charged on the reader.
* Card is now provided through the Collect for Stripe add-on's registration with Front of House, and Front of House owns enabling/disabling and labelling every method (including card) in one place. Update the Collect add-on to 0.2.0 alongside this release.
* The old "Allow cash refunds" setting is carried forward into the new Payment Methods section automatically; no reconfiguration needed.

= 0.20.1 =
* Fixed a "payment method was automatically deactivated" admin notice that kept reappearing for the Return and Settlement payment methods. The methods themselves were working; the stale warning is now cleared properly (the previous fix was being undone by Event Espresso's own notice save).

= 0.20.0 =
* Per-device payment hardware. Each device now has a "Hardware" block (card reader, cash drawer); unchecking one hides that payment method on that station's point of sale — card needs a card reader, cash needs a cash drawer. Visibility only: it never changes who may take payment, and nothing changes on existing devices (every device is treated as fully equipped until you say otherwise).

= 0.19.0 =
* A single home for payment methods. A new "Payment Methods" settings section turns cash, check, and card on or off and sets cash-refund policy in one place; an access profile can restrict which methods a given station offers. Nothing changes on an existing install — every method stays enabled exactly as before until you adjust it. Under the hood the method set is now data-driven (a registry) so future methods can plug in cleanly.

= 0.18.1 =
* Check payments at the desk (activates Event Espresso's Check method in the admin scope). Server-side event-scope enforcement on every payment/return endpoint (a clerk can only act on their own event's transactions). Clerk/manager codes widened to 10 digits with a per-device brute-force lockout, plus a remote "Clear lockout" admin action.

= 0.18.0 =
* Card-present payments are verified against Stripe before approval (no more trusting the return URL). Every first-touch money write (sales, exchanges, cash, credit, settlements) is now idempotent against a lost-response retry. Audit-log failures are no longer silent.

= 0.17.2 =
* The Return and Settlement payment methods now reactivate themselves automatically after a plugin update — no manual step on the Payment Methods screen, ever.

= 0.17.1 =
* Walk-up Return (card-less return/exchange). Sales and returns now verify the transaction's true status in Event Espresso before completing — no more false "Sale Complete" on an unpaid exit.

= 0.17.0 =
* Admin-configurable branding (receipt logo, app icon, splash, background) and Bluetooth badge printing in wp-admin (one badge at a time, tear between).

= 0.16.2 =
* Service worker REST namespace fix (eea-checkin/v1 -> eea-foh/v1); no behavior change.

= 0.16.1 =
* Update channel + repository URLs moved to the ee-extensions org. Removed a hard-coded external domain from the receipt printer's barcode/QR test page.

= 0.16.0 =
* Taking payment is now a lookup filter (All / Needs check-in / Needs payment), not a separate mode. Sell remains its own mode. No schema or server change.

= 0.15.0 =
* Printable clerk badges plus camera and hardware-wedge scan-to-login, with per-device camera configuration.

= 0.14.x =
* Bluetooth thermal receipt printing with templated header/footer, itemized line items, and configurable tear feed; a dedicated receipt-printer configuration modal with on-device test buttons; loud "charged but unrecorded" incident handling for the card-present path.

= 0.13.0 =
* Returns, exchanges, refunds, and customer credit settled as real Event Espresso transactions, with cash-refund/forfeit/store-credit settlement and exchange tax suppression.

= 0.12.0 =
* Card-present payments via a pluggable, provider-agnostic descriptor model; cash tender with change; on-demand emailed receipts.

= 0.11.0 =
* Sell / POS mode — front-desk sales through a category grid and persistent cart, building real Event Espresso transactions with automatic tax and full rollback.

= 0.9.0 - 0.10.0 =
* Station modes, pluggable in-person payments, the corrected visibility-vs-action check-in model, assistive (stacked) manager login, per-device themes, and a Q&A + payments details modal.

= 0.5.0 - 0.7.x =
* Device-secret authentication and nonce-sealed enrollment, first-class enrollment links, configurable clerk roles and stateful sessions, clerk-to-station scoping, linked-registration reverse lookup, and a role-gated registration details modal.

= 0.1.0 - 0.4.0 =
* Foundation: profiles/devices/clerks/audit data model, REST layer, ranked search, check-in over Event Espresso models, the device approval handshake, and the station PWA.
