Protocol

nu_pos_sync_protocol/src/
├── messages.ts       # TerminalMessage | HubMessage discriminated unions
├── snapshots.ts      # OrderSnapshot, TableStatus types
├── constants.ts      # Timing constants
├── validators.ts     # Zod schemas + parse helpers
└── index.ts          # Re-exports

interface OrderSnapshot {
  posReference: string;          // Required — idempotency key
  lines: OrderLineSnapshot[];    // Order lines
  totals: OrderTotalsSnapshot;   // { subtotal, tax, total }
  updatedAt: string;             // ISO timestamp

  // Optional
  id?: string;                   // Client-side UUID
  odooId?: number;               // Odoo pos.order ID (set after first sync)
  lineIdMap?: Record<string, number>;  // Client line ID → Odoo line ID
  partnerId?: string | null;
  tableId?: number;
  status?: "open" | "sent" | "changed" | "checkout" | "paid" | "closed";
  notes?: string;
  paymentLines?: PaymentLineSnapshot[];
  amountPaid?: number;
  amountReturn?: number;
  terminalId?: string;

  // Order metadata
  guestCount?: number;
  alias?: string;               // Check alias (e.g. "Bar", "Patio")
  staffName?: string;           // Staff member name
  staffUserId?: string;         // Staff member user ID
  createdAt?: string;           // ISO timestamp — order creation time
  orderType?: "dine_in" | "takeout" | "delivery";
  ticketNumber?: string;        // Sequential ticket number for takeout/delivery
  fiscalPositionId?: number | null;

  // Check-level discount audit
  checkDiscount?: {
    presetId?: number;
    presetName?: string;
    type: "percent" | "amount";
    originalValue: number;
    discountPct: number;
    appliedByUserId: string;
    appliedByName: string;
    approvedByUserId?: string;
    approvedByName?: string;
  };
}

interface OrderLineSnapshot {
  id: string;              // Client-generated UUID
  productId: string;
  quantity: number;
  unitPrice: number;
  total: number;
  discount?: number;
  taxIds?: string[];
  totalExcluded?: number;
  totalIncluded?: number;
  taxAmount?: number;
  note?: string;            // Modifier text (side dishes, etc.)
  specialRequest?: string;  // Special request tags

  // Void tracking
  isVoided?: boolean;
  voidReasonId?: number;
  voidedQty?: number;

  // Kitchen provenance
  kitchenSentAt?: string;    // ISO — when item was first sent to kitchen
  sentQuantity?: number;     // Qty sent (detects post-send quantity increases)
  kitchenTicketId?: string;  // Original order ID (split check provenance)

  // Per-line user attribution
  addedByUserId?: string;
  addedByName?: string;

  // Price override
  priceOverride?: number;

  // Discount audit trail
  discountState?: {
    presetId?: number;
    presetName?: string;
    type: "percent" | "amount";
    originalValue: number;
    discountPct: number;
    appliedByUserId: string;
    appliedByName: string;
    approvedByUserId?: string;
    approvedByName?: string;
  };

  // Price override audit trail
  priceOverrideState?: {
    originalPrice: number;
    overriddenByUserId: string;
    overriddenByName: string;
    approvedByUserId?: string;
    approvedByName?: string;
  };
}

interface FiscalData {
  ncf?: string;
  ncfCreationDate?: string;
  ncfAffected?: string;
  fiscalPositionName?: string;
  ncfExpiration?: string;
  stampUrl?: string;
  securityCode?: string;
  validationDate?: string;
  customerName?: string;
  customerRnc?: string;
}

import { parseTerminalMessage, parseHubMessage } from "@nu/sync-protocol";

const result = parseTerminalMessage(rawData);
if (result.ok) {
  // result.message is typed as TerminalMessage
} else {
  // result.error describes what failed
}

  Terminal                              Hub
     │                                   │
     ├──── WS Connect ──────────────────►│
     │                                   │
     ├──── AUTH { token } ──────────────►│
     │                                   │  validate token → Odoo
     │◄─── AUTH_OK { terminalId } ───────┤
     │                                   │
     ├──── LEASE_ACQUIRE { ref } ───────►│
     │◄─── LEASE_GRANTED { version } ────┤
     │                                   │
     ├──── ORDER_SNAPSHOT { snap } ─────►│
     │                                   ├──► broadcast ORDER_UPDATED to others
     │                                   ├──► append to event log
     │                                   │
     │         (every 20s)               │
     ├──── LEASE_HEARTBEAT { ref } ─────►│
     │                                   │  renew lease expiry
     │                                   │
     ├──── LEASE_RELEASE { ref } ───────►│
     │                                   │
     ├──── WS Close ─────────────────────►│
     │                                   │  grace period → revoke leases