feat: add feature

docs/api.md

@@ -44,8 +44,17 @@ Sync semantics:
   filters. Devices dedupe by command id and re-send the ack for commands they already processed.
 - The first ack for a command wins; later acks are accepted as no-ops.
 - `plannedTabNames` only contains planned customers the device has not opened a tab for yet. Once a sync
-  reports an open tab with exactly that name, the customer is marked delivered and no longer sent.
-  The customer (and their email, used for reminders) is kept.
+  reports an open tab with that name (ignoring case and extra spaces), the customer is marked delivered
+  and no longer sent. The customer (and their email, used for reminders) is kept.
+- `events` (optional) reports what happened on tabs since the last sync, for sales statistics. Each event
+  has a terminal-generated UUID `id`, a `type`, `tabId`, `customerName` and `occurredAt` (ISO-8601, UTC):
+  - `line_added` / `line_removed`: `productName`, `unitPriceInCents`, `quantity` (always positive)
+  - `settled`: `amountInCents`, `paymentMethod` (`cash`, `payconiq`, `payment_pending` or `other`),
+    optional `commandId` (the remote close that caused it) and `items` (the settled lines)
+
+  The response lists `acknowledgedEventIds` (stored, including events already stored by an earlier sync)
+  and `rejectedEvents` (`[{ id, reason }]`, invalid and never stored). The terminal removes both from its
+  outbox. An invalid event never fails the sync. At most 1000 events per sync.
 
 ### Tabs
 `GET /venues/:venueId/tabs` - List open tabs