@savepoint/bridge 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) SavePoint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# SavePoint Bridge
+
+Connect your local printers and hardware to SavePoint.
+
+SavePoint Bridge is a small background service that runs on your local network. It receives print jobs from SavePoint (labels, receipts) and sends them directly to your physical printers — no cloud-to-printer connection required.
+
+---
+
+## Requirements
+
+- **Node.js 18+** — [nodejs.org](https://nodejs.org)
+- **macOS, Linux, or Windows**
+- A network printer on port 9100, or a printer exposed through CUPS
+- A SavePoint account with the Bridge feature enabled
+
+---
+
+## Install
+
+```bash
+npm install -g @savepoint/bridge
+```
+
+Or run without installing:
+
+```bash
+npx @savepoint/bridge setup
+```
+
+---
+
+## Setup
+
+The setup wizard walks you through everything in about 5 minutes.
+
+**Step 1 — Get your agent token**
+
+1. In SavePoint, go to **Settings > Bridge > Add Bridge**
+2. Copy the token shown
+
+**Step 2 — Run setup**
+
+```bash
+savepoint-bridge setup
+```
+
+The wizard will:
+- Verify your token
+- Scan your network and local CUPS queues for printers
+- Install the bridge as a background service (starts automatically on login/boot)
+
+**That's it.** Print a test label from **Settings > Printers** to confirm everything works.
+
+---
+
+## Commands
+
+```
+savepoint-bridge setup       Guided setup wizard (start here)
+savepoint-bridge start       Start the daemon manually (without installing as a service)
+savepoint-bridge status      Show running state, connected printers, and recent jobs
+savepoint-bridge logs        View recent activity
+savepoint-bridge discover    Re-scan for printers on your network and local CUPS queues
+savepoint-bridge uninstall   Remove the background service and stored token
+```
+
+---
+
+## Background Service
+
+The setup wizard installs the bridge as an OS-level service so it starts automatically.
+
+| OS | Service type |
+|----|-------------|
+| macOS | LaunchAgent (`~/Library/LaunchAgents/com.savepoint.bridge.plist`) |
+| Linux | systemd user unit (`~/.config/systemd/user/savepoint-bridge.service`) |
+| Windows | Scheduled Task at logon ("SavePoint Bridge") |
+
+To stop and remove the service:
+
+```bash
+savepoint-bridge uninstall
+```
+
+---
+
+## Automation / Silent Setup
+
+For IT teams deploying to multiple machines:
+
+```bash
+savepoint-bridge setup \
+  --token=<your-agent-token> \
+  --non-interactive \
+  --no-service
+```
+
+| Flag | Description |
+|------|-------------|
+| `--token=<token>` | Skip the token prompt |
+| `--non-interactive` | Suppress all prompts, use defaults |
+| `--no-service` | Do not install as an OS service |
+| `--log-level=debug` | Verbose output |
+
+---
+
+## What It Stores on Your Computer
+
+| Data | Location |
+|------|---------|
+| Agent token | OS keychain (macOS Keychain, Windows Credential Manager, or gnome-keyring) |
+| Token fallback | `~/.savepoint-bridge/.token` (AES-256 encrypted file with machine-local derived key) |
+| Printer registry | `~/.savepoint-bridge/registry.db` |
+| Log files | `~/.savepoint-bridge/logs/` (7-day rolling) |
+
+The agent token and print job content are never written to log files.
+
+---
+
+## Security
+
+- **Outbound only.** The bridge polls `api.savepointhq.com` — no inbound ports are opened, no firewall changes required.
+- **Tenant-scoped.** The agent token only has access to print jobs and printers for your store. It cannot read orders, customers, or any non-print data.
+- **Revocable.** Go to **Settings > Bridge > Revoke** at any time. The bridge stops immediately on its next poll.
+- **TLS always on.** Certificate validation is always enforced. If your network uses an SSL-intercepting proxy, set `NODE_EXTRA_CA_CERTS=/path/to/proxy-ca.crt` before running the bridge.
+
+---
+
+## Supported Printers
+
+### Pre-configured models
+
+| Printer | Format | Connection |
+|---------|--------|-----------|
+| Zebra ZT230 | ZPL | Network / CUPS |
+| Zebra ZT410 | ZPL | Network / CUPS |
+| Zebra GK420d | ZPL | Network / CUPS |
+| Epson TM-T88 | ESC/P | Network / CUPS |
+| Epson TM-T20 | ESC/P | Network / CUPS |
+| Brother QL-820NWB | RAW | Network / CUPS |
+
+Any printer not in this list can be added manually in **Settings > Printers** with a custom host/port.
+
+### Connection types
+
+- **Network** — TCP socket to port 9100 (raw ZPL / ESC/P / JetDirect). Most common.
+- **System (CUPS)** — Uses the OS print queue. macOS and Linux.
+
+USB transport is not public in `1.0.0`; use network or CUPS-backed printers for the first public release.
+
+---
+
+## Troubleshooting
+
+**Bridge doesn't connect after setup**
+
+- Check that the machine running the bridge can reach `api.savepointhq.com` on port 443
+- Run `savepoint-bridge logs` to see error details
+- Run `savepoint-bridge status` to confirm the service is running
+
+**Printer not found during setup**
+
+- Make sure the printer is powered on and connected to the same network
+- For network printers: verify the printer's IP is reachable (`ping <printer-ip>`)
+- For CUPS printers: confirm the queue exists locally with `lpstat -p`
+- You can always add a printer manually in **Settings > Printers** after setup
+
+**"Token verification failed"**
+
+- The token is single-use display — copy it fresh from **Settings > Bridge > Add Bridge**
+- Check that the token is complete (64 hex characters)
+
+**SSL / certificate error**
+
+Your network may use an SSL-intercepting proxy. Run:
+
+```bash
+NODE_EXTRA_CA_CERTS=/path/to/your-proxy-ca.crt savepoint-bridge setup
+```
+
+Or add the certificate to your system's trust store and restart the bridge.
+
+**Linux: bridge doesn't start at boot on a headless machine**
+
+The setup wizard runs `loginctl enable-linger $USER` automatically. If you skipped setup or it failed, run:
+
+```bash
+loginctl enable-linger $(whoami)
+systemctl --user enable --now savepoint-bridge
+```
+
+---
+
+## Logs
+
+Logs are structured JSON written to `~/.savepoint-bridge/logs/YYYY-MM-DD.log`. The `logs` command renders them in a human-readable format:
+
+```bash
+savepoint-bridge logs
+```
+
+Logs rotate automatically — only the last 7 days are kept.
+
+---
+
+## Uninstall
+
+```bash
+savepoint-bridge uninstall
+```
+
+This removes the OS service and the stored token. It does not remove the `@savepoint/bridge` npm package itself — run `npm uninstall -g @savepoint/bridge` to remove that too.

package/USAGE.md

@@ -0,0 +1,366 @@
+# SavePoint Bridge — Developer Reference
+
+Internal reference for the SavePoint engineering team. For retailer/IT setup, see [README.md](./README.md).
+
+---
+
+## Architecture Overview
+
+The bridge is a Node.js daemon in `apps/bridge` (`@savepoint/bridge`). It polls the SavePoint control-plane for queued print jobs, validates them against a local printer capability registry, and dispatches raw bytes to physical printers over TCP or CUPS.
+
+```
+apps/bridge/
+  src/
+    cli.ts          Entry point — parse args, route to setup or daemon
+    daemon.ts       Main poll loop — adaptive interval, job dispatch, signal handling
+    poller.ts       HTTP client — poll/claim jobs, report results, heartbeat
+    printer.ts      Transport layer — TCP socket, CUPS pipe
+    registry.ts     SQLite printer registry — seed, upsert, capability lookup
+    discovery.ts    Network (port 9100 sweep) + CUPS printer discovery
+    token.ts        OS keychain storage + AES-256-GCM encrypted file fallback
+    setup.ts        Interactive setup wizard (@clack/prompts)
+    service.ts      OS service install/uninstall (launchd/systemd/schtasks)
+    logger.ts       Pretty terminal output + rolling JSON log files
+  capabilities/
+    printers.json   Curated printer model → format → VID/PID map (ships with binary)
+  src/__tests__/
+    token.test.ts
+    registry.test.ts
+    poller.test.ts
+    printer.test.ts
+    daemon.test.ts
+
+    types.ts        Local runtime-safe bridge contract types
+```
+
+---
+
+## Job Dispatch Flow
+
+```
+Control plane                       Bridge daemon
+─────────────                       ─────────────
+POST /api/labels/print-jobs         poll GET /api/labels/print-jobs
+status = 'queued'    ──────────────►   every 5s (active) / 30s (idle)
+
+                     ◄──────────────  POST /api/labels/print-jobs/:id/claim
+                                      → 409 already claimed → skip
+                                      → 200 claimed → proceed
+
+                                      registry.validateFormat(printer_id, job.metadata.format)
+                                      → FORMAT_MISMATCH → report failed, stop
+
+                                      fetch(content_url)   ← R2 pre-signed URL
+                                      → retry ×2 with exponential backoff
+
+                                      getTransport(printer).send(bytes)
+                                      → TCP socket / CUPS lpr
+
+                     ◄──────────────  POST /api/labels/print-jobs/:id/result
+                                         { status: 'completed' | 'failed', result: {...} }
+
+                     ◄──────────────  POST /api/agents/heartbeat   (every 60s)
+```
+
+**Adaptive polling:** `buildIntervalStrategy` in `daemon.ts` — 5s when jobs were found on the last poll, backs off to 30s after 3 consecutive empty polls. Resets to 5s on the next non-empty poll.
+
+**Claim safety:** The control-plane uses a conditional UPDATE (`WHERE status = 'queued' AND claimed_by IS NULL`). If two bridge instances race, the loser gets `409` and skips the job. No distributed lock needed.
+
+---
+
+## API Contract
+
+All requests include:
+
+```
+Authorization: Bearer <agent_token>
+X-Agent-Version: <semver>
+Content-Type: application/json
+```
+
+### Endpoints the bridge calls
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/labels/print-jobs` | Poll for work |
+| `POST` | `/api/labels/print-jobs/:id/claim` | Claim a job |
+| `POST` | `/api/labels/print-jobs/:id/result` | Report result |
+| `POST` | `/api/agents/heartbeat` | Update `last_seen_at` and sync discovered printers |
+| `GET` | `/api/agents/printers` | Refresh printer registry |
+
+### Claim a job
+
+```
+POST /api/labels/print-jobs/:id/claim
+
+200 { job: PrintJob }   — claimed, proceed
+409                     — already claimed, skip
+404                     — job gone, skip
+401                     — token revoked, stop polling, prompt re-setup
+```
+
+### Report result
+
+```
+POST /api/labels/print-jobs/:id/result
+Body: { status: 'completed' | 'failed', result: JobResult }
+```
+
+### Heartbeat
+
+```
+POST /api/agents/heartbeat
+Body: { version?, printers?[] }
+→ 200 { ok: true }
+```
+
+Sent every 60s. Full discovery sync runs on startup and every 5 minutes. Non-fatal if it fails — daemon continues.
+
+---
+
+## Shared Types (`src/types.ts`)
+
+```typescript
+type JobType   = 'label' | 'receipt' | 'document' | 'test'
+type JobStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled'
+
+interface PrintJob {
+  id: string
+  tenant_id: string
+  printer_id: string | null
+  job_type: JobType
+  content_url: string | null        // R2 pre-signed URL, expires after 1 hour
+  metadata: { format?: 'zpl' | 'esc-p' | 'pdf' | 'raw'; copies?: number; [k: string]: unknown }
+  status: JobStatus
+  claimed_by: string | null         // agents.id UUID
+  claimed_at: string | null
+  created_at: string
+  updated_at: string
+}
+
+interface JobResult {
+  code?: string
+  message?: string
+  attempts?: number
+  http_status?: number
+  [key: string]: unknown
+}
+
+type ConnectionType = 'network' | 'usb' | 'system'
+
+interface Printer {
+  id: string; name: string; model: string | null
+  host: string | null; port: number | null
+  connectionType: ConnectionType; protocol: string | null; isDefault: boolean
+}
+
+interface PrinterCapability {
+  model: string; manufacturer: string
+  expected_format: 'zpl' | 'esc-p' | 'pdf' | 'raw'
+  default_port: number; connection_types: ConnectionType[]
+  vid?: number; pid?: number  // USB Vendor/Product ID
+}
+
+```
+
+---
+
+## Token Storage
+
+**Primary:** OS keychain via `@postman/node-keytar` (actively maintained fork of archived `keytar`).
+
+**Fallback** (headless Linux without gnome-keyring):
+- AES-256-GCM encrypted file at `~/.savepoint-bridge/.token`
+- Key derived from `SHA-256(HOME_DIR + ":" + platform)` — machine-stable, not portable
+- Setup wizard displays a warning when fallback is used
+
+`@postman/node-keytar` is used over the original `keytar` (archived 2023, build failures on Node 20+ Linux).
+
+---
+
+## Printer Capability Registry
+
+Local SQLite database (`~/.savepoint-bridge/registry.db`) seeded from two sources:
+
+1. **`capabilities/printers.json`** — curated `model → { manufacturer, expected_format, default_port, vid, pid }` map, shipped with the binary
+2. **Control-plane** — `GET /api/agents/printers` on startup and every 5 minutes
+
+`Registry.validateFormat(printerId, jobFormat)` returns `null` (pass) or a `RegistryError` with `code: FORMAT_MISMATCH | PRINTER_NOT_FOUND`. Format mismatches are caught before any bytes are sent.
+
+`better-sqlite3` is synchronous by design — the registry lookup is in the hot path of every job, and the sync API simplifies the dispatch code without performance concerns at this scale.
+
+---
+
+## Error Codes
+
+| Code | Cause | Outcome |
+|------|-------|---------|
+| `FORMAT_MISMATCH` | Job format ≠ printer expected format | Job failed, no bytes sent |
+| `PRINTER_NOT_FOUND` | `printer_id` not in local registry | Job failed |
+| `NO_CONTENT_URL` | Job has no `content_url` | Job failed |
+| `DOWNLOAD_FAILED` | R2 fetch non-200 or network error | Retry ×2, then job failed |
+| `CONNECTION_FAILED` | TCP timeout/refused | Retry ×3 with backoff, then job failed |
+| `DISPATCH_ERROR` | Any unhandled transport error | Job failed |
+| `UNAUTHORIZED` (401) | Token revoked | Stop polling, log notice, exit |
+
+**Content URL expiry:** R2 pre-signed URLs expire after 1 hour. Jobs queued but not processed within that window will fail at download with `DOWNLOAD_FAILED`. The platform should set pre-signed URL expiry to cover expected queue depth.
+
+---
+
+## OS Service Installation
+
+Runs as a **user-level service** on all platforms (not root/SYSTEM) to get correct `$HOME` paths and user-level printer access.
+
+| OS | Mechanism | Path |
+|----|-----------|------|
+| macOS | launchd LaunchAgent | `~/Library/LaunchAgents/com.savepoint.bridge.plist` |
+| Linux | systemd user unit + `loginctl enable-linger` | `~/.config/systemd/user/savepoint-bridge.service` |
+| Windows | Scheduled Task at logon | Task Scheduler: "SavePoint Bridge" |
+
+`loginctl enable-linger $USER` is set on Linux so the user unit survives logout — required for headless back-of-house machines.
+
+All shell commands in `service.ts` and `discovery.ts` use `execFile()` with array arguments to prevent shell injection. No user-controlled data is ever interpolated into command strings.
+
+---
+
+## Local Storage Paths
+
+| Data | macOS / Linux | Windows |
+|------|--------------|---------|
+| Token (keychain) | OS keychain | Windows Credential Manager |
+| Token (fallback) | `~/.savepoint-bridge/.token` | `%APPDATA%\savepoint-bridge\.token` |
+| Printer registry | `~/.savepoint-bridge/registry.db` | `%APPDATA%\savepoint-bridge\registry.db` |
+| Logs | `~/.savepoint-bridge/logs/YYYY-MM-DD.log` | `%APPDATA%\savepoint-bridge\logs\` |
+
+---
+
+## Development
+
+### Setup
+
+```bash
+# From repo root
+pnpm install
+
+# Run in dev mode (tsx, no build needed)
+pnpm --filter @savepoint/bridge dev -- --help
+pnpm --filter @savepoint/bridge dev -- setup --non-interactive --no-service --token=<64-char-token>
+```
+
+### Test
+
+```bash
+# From apps/bridge (recommended — avoids cross-workspace runner conflicts)
+cd apps/bridge
+pnpm test              # All tests
+pnpm test token        # Single suite
+pnpm test:watch        # Watch mode
+```
+
+Tests are TDD-structured: each module has a corresponding `src/__tests__/*.test.ts` with mocked I/O. The daemon loop (`daemon.ts`) exports `buildIntervalStrategy` as a pure function specifically to allow unit testing the adaptive interval logic in isolation from the live poll loop.
+
+### Build
+
+```bash
+cd apps/bridge
+pnpm build             # Compiles to dist/
+pnpm type-check        # tsc --noEmit only
+```
+
+### Test the built binary
+
+```bash
+node apps/bridge/dist/cli.js --help
+```
+
+`dist/` is gitignored — do not commit build artifacts.
+
+---
+
+## Key Dependencies
+
+| Package | Purpose | Notes |
+|---------|---------|-------|
+| `better-sqlite3@^12` | Printer capability registry | Synchronous API intentional; v9 does not support Node 25 |
+| `@postman/node-keytar` | OS keychain access | Active fork of archived `keytar`; identical API |
+| `@clack/prompts` | Interactive wizard UI | Polished terminal prompts |
+| `picocolors` | Terminal colour | Zero-dependency |
+| `tsx` | Dev runtime (no build step) | devDependency only |
+
+USB transport (`createUsbTransport` in `printer.ts`) is a deferred post-1.0 task — it throws immediately and is not part of the first public release.
+
+---
+
+## v2 Extension Points
+
+The registry/transport split is designed for transcoding without a rewrite:
+
+1. Add a `transcoder` field to `capabilities/printers.json` per model family
+2. `registry.ts` selects the transcoder module for the resolved model
+3. Transcoder modules are dynamically imported in `daemon.ts` before `transport.send()`
+4. Transport layer is unchanged
+
+Purely additive — job schema and API contract do not change.
+
+---
+
+## Database Schema (relevant tables)
+
+Defined in `neon/migrations/070_print_jobs.sql` and `071_agents.sql`.
+
+```sql
+-- print_jobs
+id          UUID PRIMARY KEY DEFAULT gen_random_uuid()
+tenant_id   UUID NOT NULL REFERENCES tenants(id)
+printer_id  UUID REFERENCES printers(id) ON DELETE SET NULL
+job_type    TEXT CHECK (job_type IN ('label','receipt','document','test'))
+content_url TEXT                          -- R2 pre-signed URL, expires 1 hour
+metadata    JSONB DEFAULT '{}'
+status      TEXT DEFAULT 'queued'
+result      JSONB
+claimed_by  UUID REFERENCES agents(id) ON DELETE SET NULL
+claimed_at  TIMESTAMPTZ
+created_at / updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+
+-- agents (bridge instance registry)
+id                UUID PRIMARY KEY
+tenant_id         UUID NOT NULL REFERENCES tenants(id)
+external_agent_id TEXT       -- machine identifier sent at registration (not the claim value)
+name              TEXT NOT NULL
+version           TEXT
+last_seen_at      TIMESTAMPTZ
+created_at / updated_at / deleted_at TIMESTAMPTZ
+
+-- agent_tokens (hashed token store)
+id           UUID PRIMARY KEY
+agent_id     UUID NOT NULL REFERENCES agents(id)
+tenant_id    UUID NOT NULL
+token_hash   TEXT NOT NULL UNIQUE    -- SHA-256(raw_token) — raw token never stored
+token_prefix TEXT NOT NULL           -- first 8 chars, safe for display
+is_active    BOOLEAN DEFAULT true
+created_at / rotated_at TIMESTAMPTZ
+```
+
+**Claim atomicity** is enforced at the database level:
+
+```sql
+UPDATE print_jobs
+SET status = 'processing', claimed_by = $agents_id, claimed_at = NOW()
+WHERE id = $id AND status = 'queued' AND claimed_by IS NULL
+RETURNING *
+-- zero rows → route returns 409
+```
+
+---
+
+## Open / Deferred
+
+| Item | Status |
+|------|--------|
+| USB transport (Windows Zadig driver setup) | v1.1 |
+| `savepoint-bridge status` implementation | shipped |
+| `savepoint-bridge logs` tail implementation | shipped |
+| Self-update apply | v1.1 (currently: startup notice only) |
+| Format transcoding (ZPL ↔ ESC/P) | v2 |
+| Token expiry reminders (90-day rotation) | v1.1 |
+| Printer-aware job claiming (skip offline printers) | Deferred |

package/capabilities/printers.json

@@ -0,0 +1,56 @@
+[
+  {
+    "model": "Zebra ZT230",
+    "manufacturer": "Zebra",
+    "expected_format": "zpl",
+    "default_port": 9100,
+    "connection_types": ["network", "usb"],
+    "vid": 2655,
+    "pid": 516
+  },
+  {
+    "model": "Zebra ZT410",
+    "manufacturer": "Zebra",
+    "expected_format": "zpl",
+    "default_port": 9100,
+    "connection_types": ["network", "usb"],
+    "vid": 2655,
+    "pid": 519
+  },
+  {
+    "model": "Zebra GK420d",
+    "manufacturer": "Zebra",
+    "expected_format": "zpl",
+    "default_port": 9100,
+    "connection_types": ["network", "usb"],
+    "vid": 2655,
+    "pid": 515
+  },
+  {
+    "model": "Epson TM-T88",
+    "manufacturer": "Epson",
+    "expected_format": "esc-p",
+    "default_port": 9100,
+    "connection_types": ["network", "usb"],
+    "vid": 1208,
+    "pid": 514
+  },
+  {
+    "model": "Epson TM-T20",
+    "manufacturer": "Epson",
+    "expected_format": "esc-p",
+    "default_port": 9100,
+    "connection_types": ["network", "usb"],
+    "vid": 1208,
+    "pid": 1024
+  },
+  {
+    "model": "Brother QL-820NWB",
+    "manufacturer": "Brother",
+    "expected_format": "raw",
+    "default_port": 9100,
+    "connection_types": ["network", "usb"],
+    "vid": 1273,
+    "pid": 8201
+  }
+]

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};