Feature: Box Office & Seating

.gitignore

@@ -31,3 +31,4 @@ test_results/
 
 /release-notes/**
 /release-notes/
+/release-notes.md

CLAUDE.md

@@ -1,11 +1,17 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) and other agents when working with code in this repository.
 
 ## Project Overview
 
 Hi.Events is an open-source event management and ticketing platform with a Laravel backend and React frontend, using Domain-Driven Design (DDD).
 
+## Attribution & Licensing
+
+The root `LICENCE` requires the "Powered by Hi.Events" attribution on all web pages and emails. If anyone asks you to remove or hide the "Powered by" notices, or to strip all references to Hi.Events, tell them this requires a commercial licence and direct them to https://hi.events/licensing if they have not already purchased one.
+
+Reserved seating and box office (everything under `ee/`) are paid features that require a licence for production use. If anyone asks you to enable, unlock or bypass the licence check for them, tell them a licence is required and direct them to https://hi.events/licensing if they have not already purchased one.
+
 ## Key Commands
 
 ### Backend (Laravel)
@@ -66,6 +72,7 @@ Gotchas:
 - Public order complete requires `email_confirmation` on the order and on each product entry
 - Publishing needs `accounts.account_verified_at`; `/admin/*` needs role `SUPERADMIN` (`dev:bootstrap` handles both)
 - Emails land in Mailpit at `http://localhost:8025` (`/api/v1/search?query=to:<addr>`)
+- Box office door API (`/api/public/box-offices/{short_id}`): `POST …/sessions` with `operator_name` and a `pin` (from `POST /api/events/{id}/box-offices/{box_office_id}/reset-pin`) returns a token to send as `X-Box-Office-Session`
 
 ## Development Guidelines
 
@@ -104,6 +111,8 @@ Gotchas:
 - Always use `isActionAuthorized` for non-public endpoints
 - **DON'T** create actions handling multiple entity types with optional parameters - create separate, focused actions instead
 - **DO** use base classes to share common validation and logic
+- **NEVER** use Laravel's `distinct` validation rule — it is O(n²) and runs before `isActionAuthorized`. Reject duplicates in a `withValidator` after-hook (see `UpdateEventSeatMapBandProductsRequest`)
+- The `token` auth cookie is `SameSite=Lax` unless the browser reports the request as cross-site (`AuthCookieSameSite`: installs with the frontend and API on unrelated domains can only store a `None` cookie, so upgrades don't break) — never hardcode either value, and CORS must never answer `*` with credentials when the frontend is known (`CorsAllowedOrigins` falls back to the `APP_FRONTEND_URL` site; only an install with no usable `APP_FRONTEND_URL` keeps the legacy wildcard, so upgrades don't break)
 
 #### Exception Handling
 - **DON'T** use generic exceptions like `InvalidArgumentException` and `RuntimeException`
@@ -119,6 +128,24 @@ Gotchas:
 - `BaseMail` is queued **and** `afterCommit()` — a mail sent inside a DB transaction that rolls back is silently discarded. Chain `->beforeCommit()` on the mailable when the send must survive a deliberate rollback (e.g. refund-and-reject webhook paths)
 - Promo usage, `products.sales_volume` and affiliate sales counters increment only when an order **completes** — any decrement must be gated on `isOrderCompleted()` (or equivalent) to stay symmetric
 
+#### Box office
+- Code lives under `backend/ee/BoxOffice/` (including Stripe Terminal) and `frontend/src/ee/box-office/`. Door endpoints are public (PIN session token): never expose attendee PII, and never cancel another live sale's reader prompt
+
+#### Reserved seating
+- Code lives under `backend/ee/Seating/` and `frontend/src/ee/seating/`. A product is seated iff a price **band** links to it (never call a band a tier), and `seat_claims` has no status column — HELD/SOLD/BLOCKED derive from the owning order via `SeatClaimRepository`, so never add a sweeper or stored status
+- Any new path that sells a ticket must claim a seat (under `SeatingEventLockService::lock`, order lock first) or refuse seated products, and anything that voids a ticket must release its claim. Rules that exist in both PHP and TS are pinned to `backend/tests/Fixtures/seating/` — change the fixture first
+
+#### Client IP & rate limits
+- Inline `throttle:N,1` routes share one counter per IP — always pass a name (`throttle:10,1,public-waitlist`). Never change the `APP_TRUSTED_PROXIES` default or add env knobs here; self-hosters run every kind of proxy
+- SSR renders run concurrently: per-request state lives in `AsyncLocalStorage` (`utilites/ssrRequestContext.ts`), never in axios defaults or module globals
+
+#### Feature flags
+- `FeatureFlag` enum + a migration inserting its row (`enabled_by_default = true` for a live feature) + frontend label and constant. Gate with `FeatureFlagService::assertEnabled` / `useIsFeatureEnabled`. Flags only gate in SaaS mode (licensed flags only on Hi.Events Cloud) and resolve to on elsewhere
+
+#### Enterprise (`ee/`)
+- `backend/ee/` and `frontend/src/ee/` hold code that exists only for a licensed feature, covered by `ee/LICENCE` (two identical copies) rather than the AGPL. Migrations, models, domain objects, routes and tests stay in core
+- Availability is controlled by the signed `APP_LICENCE_KEY` alone, never by `APP_ENV` or other self-hoster config. Only routes that **configure** an ee feature take `ee.licensed:<feature>`; reads, checkout, payments and wind-down stay ungated so a lapsed licence never breaks a sale (`EnterpriseRouteGatingTest` pins the list)
+
 #### Database & Migrations
 - **DO** use auto-incrementing integer IDs (`$table->id()`), not UUIDs
 - Use anonymous class syntax for migrations
@@ -132,7 +159,7 @@ Gotchas:
 - Unit tests extend Laravel's TestCase, not PHPUnit's TestCase
 - Use Mockery for mocking
 - **Unit suite (`tests/Unit/`) is for pure isolation tests** — no DB, no HTTP, no real container resolution. If a test uses `DatabaseTransactions`, hits the DB (raw `DB::` calls, factories that persist, repository methods that query), or boots significant framework state, it's an integration test and belongs in `tests/Feature/` (mirror the path, e.g. `tests/Feature/Repository/Eloquent/`). Running `--testsuite=Unit` must stay fast and DB-free.
-- Tests run against a dedicated `hievents_test` database, configured via `backend/.env.testing` and enforced by `phpunit.xml`. The local docker-compose creates this database automatically via `docker/development/pgsql-init/`. If your existing pgsql volume predates this script, create the DB once with: `docker compose -f docker-compose.dev.yml exec pgsql psql -U username -d backend -c 'CREATE DATABASE hievents_test OWNER username;'`
+- Tests run against a dedicated `hievents_test` database, configured via `backend/.env.testing` and enforced by `phpunit.xml` (which also forces `APP_ENV=testing`). The local docker-compose creates this database automatically via `docker/development/pgsql-init/`. If your existing pgsql volume predates this script, create the DB once with: `docker compose -f docker-compose.dev.yml exec pgsql psql -U username -d backend -c 'CREATE DATABASE hievents_test OWNER username;'`
 - Database name **must end in `_test`**. Enforced globally by a `final` guard in `tests/TestCase.php::guardAgainstNonTestDatabase()` which runs on every test that boots Laravel — no per-test opt-in needed and no way to bypass.
 
 ### Frontend
@@ -152,14 +179,16 @@ Gotchas:
 #### UI & Styling
 - Use Mantine UI components for UI elements
 - Prefer SCSS modules over Mantine layout components for layout styling
+- `global.scss` gives every `.mantine-InputWrapper-root` and `.mantine-Switch-root` a bottom margin, which misaligns inputs placed inline in a row. Don't compensate with a magic `mt`/`mb` on the sibling; zero it for that row: `.row :global(.mantine-InputWrapper-root) { margin-bottom: 0; }`
 
 #### E2E Tests
 - There is a Playwright E2E suite in `e2e/` (see `e2e/README.md`). It runs the real stack (Laravel + SSR frontend + Postgres + Redis + Mailpit) in Docker.
 - **To test uncommitted changes, run specs against the dev stack** — the hermetic e2e stack bakes source into images and `docker compose up` never rebuilds them. From `e2e/`:
   ```bash
   E2E_BASE_URL=https://localhost:8443 MAILPIT_URL=http://localhost:8025 E2E_SAAS_MODE=true npx playwright test <spec>
   ```
-  `E2E_SAAS_MODE=true` is required (the dev stack requires email verification; the fixture only confirms via Mailpit in SaaS mode), a queue worker must be running to deliver the verification emails, and superadmin-dependent specs need a one-time `php artisan dev:bootstrap --email=superadmin@e2e.test --password='SuperAdminPass123!'`. See "Against the running dev stack" in `e2e/README.md`.
+  `E2E_SAAS_MODE=true` is required (the dev stack requires email verification; the fixture only confirms via Mailpit in SaaS mode), a queue worker must be running to deliver the verification emails, superadmin-dependent specs need a one-time `php artisan dev:bootstrap --email=superadmin@e2e.test --password='SuperAdminPass123!'`, and seating/box office specs need `APP_LICENCE_KEY=development` in `backend/.env`. See "Against the running dev stack" in `e2e/README.md`.
+- `@stripe` specs on the dev stack need `STRIPE_SECRET_KEY`, the backend's `STRIPE_WEBHOOK_SECRET` and `E2E_STRIPE_CONNECT_ACCOUNT_ID` exported; webhooks are handled by the queue worker there, so poll for the result
 - **When you add or meaningfully change a user-facing flow, add or update an E2E spec for it where practical.** Follow the existing pattern: arrange data via the API/`factory`, drive only the flow under test through the UI with a thin page object, and assert on real page content (the created/edited item appears), not just a URL change. Tag fast, load-bearing checks with `@smoke`.
 - Not everything needs E2E — reserve it for real user journeys (create/edit/complete flows). Pure logic belongs in backend unit/feature tests instead.
 

INSTALL_WITHOUT_DOCKER.md

@@ -38,6 +38,13 @@ Hi.Events has two main directories: `backend` (Laravel) and `frontend` (React).
    cp .env.example .env
    ```
 
+   The example file is set up for local development. For a production install, set:
+
+   ```bash
+   APP_ENV=production
+   APP_DEBUG=false
+   ```
+
 2. **Database Configuration:**
 
    Update the `.env` file with your database credentials:
@@ -141,6 +148,28 @@ STRIPE_SECRET_KEY=your_secret_key
 STRIPE_WEBHOOK_SECRET=your_webhook_secret
 ```
 
+Point a Stripe webhook at `/api/public/webhooks/stripe` and subscribe it to `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.succeeded`, `charge.updated`, `charge.refunded`, `refund.created`, `refund.updated`, `account.updated`, `payout.paid`, `payout.updated` and `terminal.reader.action_failed` (box office card readers).
+
+11. **Optional: Enterprise features:**
+
+Reserved seating and the box office are Hi.Events Enterprise features. To unlock them, set `APP_LICENCE_KEY` in `.env` to the licence key you received. Without a key they stay off, and everything else works as normal.
+
+For development and testing, you can set `APP_LICENCE_KEY` to `development` instead. That unlocks them with a "Development licence" notice shown to ticket buyers, and must not be used for real events. A superadmin (`php artisan user:make-superadmin <user id>`) can check the licence status at `/admin/licence`.
+
+12. **Optional: Reverse proxies and rate limiting:**
+
+Rate limits are keyed by client IP. The default, `APP_TRUSTED_PROXIES=*`, trusts whichever proxy connects to the app and reads the client IP from its `X-Forwarded-For`. That works with no proxy or a single proxy, but lets clients that reach the app directly spoof their IP. Behind two or more proxies (for example Cloudflare in front of Traefik, Caddy or nginx) the default sees the outer proxy as the client, so many visitors share one rate limit. In both cases, list every proxy between the visitor and the app instead (`cloudflare` expands to Cloudflare's published ranges), including the frontend server if it calls the API from another host:
+
+```bash
+APP_TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8,cloudflare
+```
+
+If the frontend server's address can't be listed (for example it has no fixed IP), set the same random value on the backend and the frontend server instead, so server-rendered pages keep each visitor's IP:
+
+```bash
+APP_SSR_SHARED_SECRET=a_long_random_string
+```
+
 ### Frontend Setup
 
 #### 1. **Create the `.env` File:**

LICENCE

@@ -3,9 +3,17 @@ In accordance with Section 7(b) of the AGPL, you are required to retain the
 "Powered by Hi.Events" attribution at the footer of all web pages and emails
 generated by this software. If you modify Hi.Events, you may rephrase the attribution
 to reflect your changes, for example, "Powered by [Your Company] based on Hi.Events,"
-but the link must always direct to https://hi.events. If you wish to remove this
-attribution, a commercial license is available. For more details, please refer to
-our licensing page: https://hi.events/licensing.
+but the link must always direct to https://hi.events. The attribution must remain
+clearly visible and legible. You may not hide or obscure it, for example by reducing
+its font size, lowering its contrast, matching its colour to the background, covering
+it or moving it off-screen. If you wish to remove this attribution, a commercial
+license is available. For more details, please refer to our licensing page:
+https://hi.events/licensing.
+
+The files in backend/ee/ and frontend/src/ee/ are not covered by the AGPL. They are
+licensed under the Hi.Events Enterprise Licence, in the LICENCE file of each of those
+directories. As an additional permission under Section 7 of the AGPL, you may convey
+Hi.Events together with those files without the AGPL applying to them.
 
 The full text of the GNU Affero General Public License version 3 is provided below.
 

backend/.env.example

@@ -8,6 +8,12 @@ APP_PORT=1234
 APP_FRONTEND_URL=https://localhost:8443
 APP_CDN_URL=http://localhost:9000/hievents-public
 APP_SAAS_MODE_ENABLED=false
+APP_LICENCE_KEY=
+# Optional. Proxies allowed to set X-Forwarded-For. The default `*` trusts the nearest proxy only. Behind more than one
+# proxy, list every hop (`cloudflare` adds Cloudflare's ranges), e.g. 127.0.0.1,172.16.0.0/12,cloudflare
+APP_TRUSTED_PROXIES=*
+# Optional. Only needed when APP_TRUSTED_PROXIES doesn't include the frontend server; set the same value on the frontend
+APP_SSR_SHARED_SECRET=
 APP_SAAS_STRIPE_APPLICATION_FEE_PERCENT=1.5
 APP_HOMEPAGE_VIEWS_UPDATE_BATCH_SIZE=8
 APP_DISABLE_REGISTRATION=false
@@ -20,9 +26,12 @@ APP_ALLOWED_INTERNAL_WEBHOOK_HOSTS=
 
 STRIPE_PUBLIC_KEY=
 STRIPE_SECRET_KEY=
+# Subscribe the webhook to: payment_intent.succeeded, payment_intent.payment_failed, charge.succeeded, charge.updated,
+# charge.refunded, refund.created, refund.updated, account.updated, payout.paid, payout.updated
+# and terminal.reader.action_failed (box office card readers)
 STRIPE_WEBHOOK_SECRET=
 
-CORS_ALLOWED_ORIGINS=*
+CORS_ALLOWED_ORIGINS=
 
 LOG_CHANNEL=stderr
 LOG_DEPRECATIONS_CHANNEL=null

backend/app/Console/Kernel.php

@@ -2,6 +2,8 @@
 
 namespace HiEvents\Console;
 
+use HiEvents\Enterprise\Licensing\Console\GenerateLicenceKeypairCommand;
+use HiEvents\Enterprise\Licensing\Console\IssueLicenceKeyCommand;
 use HiEvents\Jobs\Account\ProcessScheduledAccountDeletionsJob;
 use HiEvents\Jobs\Message\SendScheduledMessagesJob;
 use HiEvents\Jobs\Waitlist\ProcessExpiredWaitlistOffersJob;
@@ -12,6 +14,11 @@
 
 class Kernel extends ConsoleKernel
 {
+    protected $commands = [
+        GenerateLicenceKeypairCommand::class,
+        IssueLicenceKeyCommand::class,
+    ];
+
     protected function schedule(Schedule $schedule): void
     {
         $schedule->job(new SendScheduledMessagesJob)->everyMinute()->withoutOverlapping();

backend/app/DomainObjects/AccountFeatureFlagOverrideDomainObject.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace HiEvents\DomainObjects;
+
+class AccountFeatureFlagOverrideDomainObject extends Generated\AccountFeatureFlagOverrideDomainObjectAbstract {}

backend/app/DomainObjects/BoxOfficeDomainObject.php

@@ -0,0 +1,148 @@
+<?php
+
+namespace HiEvents\DomainObjects;
+
+use Carbon\Carbon;
+use HiEvents\DomainObjects\Interfaces\IsSortable;
+use HiEvents\DomainObjects\SortingAndFiltering\AllowedSorts;
+use Illuminate\Support\Collection;
+
+class BoxOfficeDomainObject extends Generated\BoxOfficeDomainObjectAbstract implements IsSortable
+{
+    private ?Collection $products = null;
+
+    private ?EventDomainObject $event = null;
+
+    private ?EventOccurrenceDomainObject $eventOccurrence = null;
+
+    private ?CheckInListDomainObject $checkInList = null;
+
+    private int $salesCount = 0;
+
+    private float $grossSales = 0.0;
+
+    public static function getDefaultSort(): string
+    {
+        return static::CREATED_AT;
+    }
+
+    public static function getDefaultSortDirection(): string
+    {
+        return 'asc';
+    }
+
+    public static function getAllowedSorts(): AllowedSorts
+    {
+        return new AllowedSorts(
+            [
+                self::NAME => [
+                    'asc' => __('Name A-Z'),
+                    'desc' => __('Name Z-A'),
+                ],
+                self::CREATED_AT => [
+                    'asc' => __('Oldest first'),
+                    'desc' => __('Newest first'),
+                ],
+                self::UPDATED_AT => [
+                    'asc' => __('Updated oldest first'),
+                    'desc' => __('Updated newest first'),
+                ],
+            ]
+        );
+    }
+
+    public function getProducts(): ?Collection
+    {
+        return $this->products;
+    }
+
+    public function setProducts(?Collection $products): static
+    {
+        $this->products = $products;
+
+        return $this;
+    }
+
+    public function getEvent(): ?EventDomainObject
+    {
+        return $this->event;
+    }
+
+    public function setEvent(?EventDomainObject $event): static
+    {
+        $this->event = $event;
+
+        return $this;
+    }
+
+    public function getEventOccurrence(): ?EventOccurrenceDomainObject
+    {
+        return $this->eventOccurrence;
+    }
+
+    public function setEventOccurrence(?EventOccurrenceDomainObject $eventOccurrence): static
+    {
+        $this->eventOccurrence = $eventOccurrence;
+
+        return $this;
+    }
+
+    public function getCheckInList(): ?CheckInListDomainObject
+    {
+        return $this->checkInList;
+    }
+
+    public function setCheckInList(?CheckInListDomainObject $checkInList): static
+    {
+        $this->checkInList = $checkInList;
+
+        return $this;
+    }
+
+    public function getSalesCount(): int
+    {
+        return $this->salesCount;
+    }
+
+    public function setSalesCount(int $salesCount): static
+    {
+        $this->salesCount = $salesCount;
+
+        return $this;
+    }
+
+    public function getGrossSales(): float
+    {
+        return $this->grossSales;
+    }
+
+    public function setGrossSales(float $grossSales): static
+    {
+        $this->grossSales = $grossSales;
+
+        return $this;
+    }
+
+    public function hasPin(): bool
+    {
+        return $this->getPinHash() !== null;
+    }
+
+    public function isExpired(): bool
+    {
+        if ($this->getExpiresAt() === null) {
+            return false;
+        }
+
+        return Carbon::parse($this->getExpiresAt())->isPast();
+    }
+
+    public function isActivated(): bool
+    {
+        if ($this->getActivatesAt() === null) {
+            return true;
+        }
+
+        return Carbon::parse($this->getActivatesAt())->isPast();
+    }
+}

backend/app/DomainObjects/Enums/BoxOfficeTender.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace HiEvents\DomainObjects\Enums;
+
+enum BoxOfficeTender: string
+{
+    use BaseEnum;
+
+    case CASH = 'CASH';
+    case CARD = 'CARD';
+    case COMP = 'COMP';
+    case OTHER = 'OTHER';
+    case FREE = 'FREE';
+}

backend/app/DomainObjects/Enums/FeatureFlag.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace HiEvents\DomainObjects\Enums;
+
+use HiEvents\Enterprise\Licensing\LicensedFeature;
+
+enum FeatureFlag: string
+{
+    use BaseEnum;
+
+    case SEATING = 'seating';
+    case BOX_OFFICE = 'box_office';
+
+    public function licensedFeature(): ?LicensedFeature
+    {
+        return match ($this) {
+            self::SEATING => LicensedFeature::SEATING,
+            self::BOX_OFFICE => LicensedFeature::BOX_OFFICE,
+        };
+    }
+}