Device API (Device Mesh)

The device-mesh module is the server-side registry, pairing and command queue for a tenant’s local hardware: receipt/kitchen printers, cash drawers, fiscal registers (yazarkasa), POS terminals, KDS/bar screens, waiter/customer tablets, caller-ID, barcode scanners and the local bridge agent (local_bridge) that drives several devices at once.

An admin creates a device slot from the panel; the slot shows a 6-character pair code. The device (or the local_bridge agent) enters that code to pair and receives a long-lived device token in return. From then on the server dispatches commands to the device — print a receipt, open the drawer, issue a fiscal receipt, show an order on a screen — through a per-device command queue.

All endpoints live under the /api global prefix at /api/v1/devices/.... See API Fundamentals for the base URL, error envelope and rate-limit tiers shared across the whole REST surface.

Auth realms

device-mesh hosts two distinct auth surfaces in one controller. Each endpoint expects exactly one of them; the wrong realm returns 401.

The admin routes are branch-scoped and require an X-Branch-Id header (below). The device routes (pair, heartbeat, next-command, ack) are authenticated by the token itself, which already carries the tenant/branch context — they do not take X-Branch-Id.

Branch scope — X-Branch-Id

Slot creation, command dispatch and the device list are branch-scoped: the server resolves the active branch from the X-Branch-Id header.

X-Branch-Id: <branch-uuid>

A MANAGER restricted to one branch can only drive devices in that branch — a device outside the caller’s branch scope returns 404. An ADMIN operates tenant-wide.

Device kinds

The kind field is one value from a closed set:

The capabilities field is an array of free-form tags (max 32 items, each ≤ 64 chars) — e.g. a bridge that carries fiscal + printer + cash-drawer capabilities.

Endpoints

Pairing flow

curl -X POST https://hummytummy.com/api/v1/devices \
  -H "Authorization: Bearer $JWT" \
  -H "X-Branch-Id: $BRANCH_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "receipt_printer",
    "capabilities": ["escpos", "80mm"],
    "model": "Epson TM-T20III",
    "ownership": "byo"
  }'

const res = await fetch("https://hummytummy.com/api/v1/devices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${jwt}`,
    "X-Branch-Id": branchId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    kind: "receipt_printer",
    capabilities: ["escpos", "80mm"],
    model: "Epson TM-T20III",
    ownership: "byo",
  }),
});
const slot = await res.json();
// show slot.pairCode on screen until slot.pairCodeExpiresAt

{
  "id": "01J...",
  "tenantId": "01J...",
  "branchId": "01J...",
  "kind": "receipt_printer",
  "status": "unprovisioned",
  "pairCode": "A4F9K2",
  "pairCodeExpiresAt": "2026-06-22T10:10:00.000Z"
}

curl -X POST https://hummytummy.com/api/v1/devices/pair \
  -H "Content-Type: application/json" \
  -d '{
    "pairCode": "A4F9K2",
    "model": "Epson TM-T20III",
    "capabilities": ["escpos", "80mm"]
  }'

{
  "deviceId": "01J...",
  "tenantId": "01J...",
  "branchId": "01J...",
  "kind": "receipt_printer",
  "token": "018f....base64url",
  "tokenExpiresAt": "2026-06-23T10:05:00.000Z",
  "capabilities": ["escpos", "80mm"]
}

curl -X POST https://hummytummy.com/api/v1/devices/heartbeat \
  -H "Authorization: Device $DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "batteryPct": 100, "agentVersion": "1.0.0", "queueDepth": 0 }'

Pairing rules, TTLs and brute-force protection

Device statuses

unprovisioned → (slot created, awaiting code)
paired        → (first pair, no heartbeat yet)
online        → (within the heartbeat window)
offline       → (no heartbeat for ~45s)
retired       → (admin retired it; token revoked)

The heartbeat window is 45s; a background sweeper (cron) flips online devices that exceed it to offline.

Command queue

An admin drives hardware by sending commands to a device. Commands are held in a per-device FIFO + priority queue; the device pulls the next command via next-command, executes it, and reports the outcome via ack.

Command kinds (kind)

Enqueue a command (admin)

curl -X POST https://hummytummy.com/api/v1/devices/$DEVICE_ID/commands \
  -H "Authorization: Bearer $JWT" \
  -H "X-Branch-Id: $BRANCH_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "print_receipt",
    "payload": { "orderId": "01J...", "copies": 1 },
    "priority": 0,
    "idempotencyKey": "order-01J-receipt"
  }'

• kind must be one of the closed set above; free-form aliases (such as charge.card) are rejected with 400.
• payload must be an object (JSONB); priority is 0–1000 (0 default, higher = first).
• If idempotencyKey is supplied, the command is deduplicated on (deviceId, idempotencyKey); resending returns the same command (no duplicate is created). Always send a stable key when retrying.

Device side: claiming and acking

# Atomically claim the next command (returns null if none)
curl https://hummytummy.com/api/v1/devices/next-command \
  -H "Authorization: Device $DEVICE_TOKEN"
 
# Report the outcome
curl -X POST https://hummytummy.com/api/v1/devices/commands/$COMMAND_ID/ack \
  -H "Authorization: Device $DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "done", "result": { "bytesPrinted": 412 } }'

next-command is atomic via FOR UPDATE SKIP LOCKED — even if a single device opens two connections, a command is never delivered twice. The ack status is done or failed; the error field (≤ 1000 chars) carries the failure reason.

Retry semantics — idempotency and side-effects

Screen commands (KDS / bar displays)

A KDS or bar screen registered with kind: "kds_screen" (or bar_screen) can be driven with the safe screen subset of the command set:

curl -X POST https://hummytummy.com/api/v1/devices/$SCREEN_ID/commands \
  -H "Authorization: Bearer $JWT" \
  -H "X-Branch-Id: $BRANCH_ID" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "show_order", "payload": { "orderId": "01J..." } }'

These are all idempotent / safe — unlike the side-effecting hardware commands, showing or clearing a screen twice causes no harm, so on failure they follow the normal retry path (up to 5 attempts).

Listing devices

curl "https://hummytummy.com/api/v1/devices?branchId=$BRANCH_ID&kind=receipt_printer&status=online" \
  -H "Authorization: Bearer $JWT" \
  -H "X-Branch-Id: $BRANCH_ID"

Filterable by branchId, kind and status. The list response returns identity + status information; sensitive fields such as pairCode and tokenHash are deliberately excluded from the list.

Rate limits

In addition to the global tiers in API Fundamentals, the device endpoints add their own tighter limits:

The per-token limits on heartbeat, next-command and ack stop a compromised device token from hammering the database.

Security notes

• Sending commands and inspecting the queue are branch-scoped: a MANAGER restricted to one branch cannot send charge_card / open_drawer / fiscal_receipt to another branch’s terminal (an out-of-scope device returns 404). An ADMIN operates tenant-wide.
• Retiring a device (DELETE /api/v1/devices/:id) is restricted to the ADMIN role; it revokes the token.
• The raw device token is shown once at pair time and stored only as a sha256 hash; if it is lost, retire the slot and pair again.

Operator screens

Restaurant staff manage devices from the in-app panel, not the API directly:

• Devices screen — create slots, read pairing codes/QR, monitor status, send a capability probe, retire.
• Hardware pairing — the operator-side pairing walkthrough for printers, cash drawers and fiscal registers.
• KDS / kiosk mode — running a kitchen display as a registered screen device.