npm package: @savepoint/bridge
Description: SavePoint Bridge hardware daemon
Author: SavePoint
Latest version: 1.0.5

# 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.