@zykeco/sync-server 0.3.0 → 0.5.0

package/README.md

@@ -0,0 +1,131 @@
+# @zykeco/sync-server
+
+Self-hosted sync server for the Zyke mobile app. A small [Hono](https://hono.dev) HTTP service backed by [libsql](https://github.com/tursodatabase/libsql) and [Drizzle ORM](https://orm.drizzle.team), validated end-to-end with [TypeBox](https://github.com/sinclairzx81/typebox) schemas from [`@zykeco/sync-protocol`](https://www.npmjs.com/package/@zykeco/sync-protocol).
+
+- **Single-tenant, secret-gated.** One server per deployment; two bearer secrets (`READ_SECRET`, `WRITE_SECRET`).
+- **Writes + hard-deletes only.** No read API surface — the mobile client is the source of truth, the server is a durable buffer for backup/restore.
+- **Schemaless `sleep_sessions`.** Domain fields live inside a JSON `payload`, so the mobile app evolves the shape without a server release.
+- **Three CLI bins.** `zyke-sync-startup`, `zyke-sync-upgrade`, and `zyke-sync-migrate` cover first-run setup, version bumps, and ad-hoc migrations.
+
+Requires **Node ≥ 24** and **npm ≥ 11**.
+
+## Install
+
+```bash
+npm install @zykeco/sync-server
+```
+
+For a deployment-ready starter that already wires up `startup` / `start` / `upgrade`, see the [`@zykeco/sync-self-host`](https://github.com/zykeco/sync/tree/main/apps/self-host) template — copy it onto your server and you're done.
+
+## Quick start (manual)
+
+```bash
+# 1. Create a project directory with @zykeco/sync-server installed.
+mkdir my-sync && cd my-sync
+npm init -y && npm pkg set type=module
+npm install @zykeco/sync-server
+
+# 2. Generate .env (READ_SECRET / WRITE_SECRET) and run migrations.
+npx zyke-sync-startup
+
+# 3. Create index.js with one line, then start.
+echo "import '@zykeco/sync-server';" > index.js
+node index.js
+# → zyke-sync listening on http://localhost:3000
+```
+
+## Bins
+
+| Command             | Purpose                                                                                                                                                                                         |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `zyke-sync-startup` | First-run setup. Runs `npm install`, generates/updates `.env` with crypto-random `READ_SECRET` and `WRITE_SECRET` (mode `0600`), creates the libsql data dir, then runs migrations. Idempotent. |
+| `zyke-sync-upgrade` | Upgrades the package and migrates. `zyke-sync-upgrade --to 0.5.0` for a specific version; no arg defaults to `latest`.                                                                          |
+| `zyke-sync-migrate` | Applies all pending Drizzle migrations against `DATABASE_URL`. Run by `startup` / `upgrade`; useful on its own for ad-hoc migrations.                                                           |
+
+## Environment
+
+The server reads these via `process.env` (and `.env` if present):
+
+| Var            | Default               | Purpose                                                                          |
+| -------------- | --------------------- | -------------------------------------------------------------------------------- |
+| `PORT`         | `3000`                | HTTP listen port.                                                                |
+| `DATABASE_URL` | `file:./data/sync.db` | libsql connection string. Accepts local SQLite (`file:`) or remote libsql/Turso. |
+| `READ_SECRET`  | _required_            | Bearer token for read endpoints (currently unused — reads are not exposed).      |
+| `WRITE_SECRET` | _required_            | Bearer token for write + delete + wipe endpoints.                                |
+
+`zyke-sync-startup` generates 32-byte hex values for both secrets if they're missing, writes the file with mode `0600`, and leaves existing values alone on subsequent runs.
+
+## HTTP API
+
+All write endpoints take `Authorization: Bearer ${WRITE_SECRET}` and respond with JSON.
+
+### Health
+
+```
+GET /v1/health  →  { ok: true }
+```
+
+### Per-namespace batch upsert
+
+```
+POST /v1/sync/daily-metrics/batch
+POST /v1/sync/weekly-metrics/batch
+POST /v1/sync/sleep-sessions/batch
+
+body:  { rows: [...] }         // max 500 daily/weekly, 200 sleep
+reply: { stored: number[], serverNowMs: number }
+```
+
+Upserts by `id` (client-generated integer PK) with a **last-write-wins** guard on `updatedAt` — older writes are silently ignored.
+
+### Per-namespace hard-delete
+
+```
+POST /v1/sync/daily-metrics/delete
+POST /v1/sync/weekly-metrics/delete
+POST /v1/sync/sleep-sessions/delete
+
+body:  { ids: number[] }        // max 200
+reply: { deleted: number[], serverNowMs: number }
+```
+
+Missing ids are silent successes — safe to retry.
+
+### Wipe everything (destructive)
+
+```
+POST /v1/sync/wipe
+
+body:  { confirm: "wipe-all-data" }
+reply: { wiped: { dailyMetrics, weeklyMetrics, sleepSessions: number }, serverNowMs }
+```
+
+Deletes every row across the three sync namespaces (blobs untouched). The literal `confirm` string is enforced at the protocol layer.
+
+## Data model
+
+- **`daily_metrics`**, **`weekly_metrics`** — `{ id (PK), isoDate / weekStartIsoDate, metricKey, value, createdAt, updatedAt }`. Composite unique on `(date, metricKey)`.
+- **`sleep_sessions`** — schemaless envelope: `{ id (PK), isoDate, updatedAt, payloadVersion, payload (JSON) }`.
+
+All timestamps are epoch milliseconds. `id`s are client-generated integers (no autoincrement on the server).
+
+## Programmatic use
+
+```ts
+import '@zykeco/sync-server'; // auto-starts on import using process.env
+```
+
+There is no module API to embed the server in another process — the package is import-to-run by design.
+
+## Compatibility
+
+| Runtime    | Status                     |
+| ---------- | -------------------------- |
+| Node ≥ 24  | ✅                         |
+| Bun / Deno | ❌ (libsql native binding) |
+
+For embedded/edge runtimes, point a stock Node deployment at a remote libsql (Turso) URL.
+
+## License
+
+AGPL-3.0-or-later — see [LICENSE](./LICENSE).