@zergai/zergbox-client 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# `@zergai/zergbox-client`
+
+Node 22.19+ API and local sync client for a single, explicitly selected ZergBox
+folder tree. The selected `rootFolderId` is presented as `/` locally; the
+workspace root and sibling boxes are never scanned.
+
+The `@zergai` release is being prepared. The registry installation below becomes
+available after the first verified publication; until then, use the repository
+checkout and `npm run client:build` from `zapps/zergbox`.
+
+```bash
+npm install @zergai/zergbox-client
+```
+
+```js
+import { createSyncSession } from '@zergai/zergbox-client/sync'
+
+const session = createSyncSession({
+  client,
+  organizationId,
+  rootFolderId,
+  localRoot,
+  statePath,
+  deviceId,
+  afterSync: async (result) => {
+    await reconcileCloudProjection(result)
+  }
+})
+
+await session.syncOnce()
+await session.close()
+```
+
+Pass either an authenticated `ZergBoxClient` or `baseUrl` plus a
+`tokenProvider`. The provider is called for each sync cycle so short-lived
+credentials do not need to be persisted by this package.
+`afterSync(result)` is awaited by the session's internal sync lifecycle, so it
+runs for both direct `syncOnce()` calls and scheduler-triggered `watch()`
+cycles. Embedders should use this hook instead of wrapping the returned
+`syncOnce` method.
+
+For a server-side projection that already owns bytes, use the root-scoped API
+directly:
+
+```js
+import {
+  ZergBoxClient,
+  ZergBoxSyncConflictError
+} from '@zergai/zergbox-client'
+
+const page = await client.listChanges(rootFolderId, { cursor, limit: 100 })
+await client.uploadBytes({
+  orgId,
+  folderId,
+  filename: 'notes.md',
+  bytes,
+  mediaType: 'text/markdown',
+  expectedAbsent: true
+})
+await client.updateFileBytes({ fileId, bytes, expectedRevision })
+const downloaded = await client.downloadFile(fileId, { maxBytes: 1_048_576 })
+```
+
+`ZergBoxClient` bounds metadata, feed, mutation, and error bodies to 1 MiB by
+default and downloads to 64 MiB. Configure `maxResponseBytes` and
+`maxDownloadBytes` on the constructor, or pass a smaller per-download
+`maxBytes`. Oversized streams are cancelled before further bytes are buffered.
+
+Folder and byte creates always send `If-None-Match: *`; update, move, and delete
+methods require `expectedRevision` and send a strong `If-Match` ETag. A `409`
+create collision or `412` stale revision becomes a recoverable
+`ZergBoxSyncConflictError` with resource identity/path and the failed
+precondition. Re-read the remote tree or change feed before planning again.
+`uploadBytes` intentionally has no last-writer-wins mode; use
+`updateFileBytes` with an observed revision.
+
+`watch()` combines filesystem notifications with periodic reconciliation.
+`pause()`, `resume()`, `status()`, `stopWatching()`, and `close()` provide a
+non-daemon lifecycle that embedding CLIs can own directly. `stopWatching()`
+leaves the session open so a caller can perform a final `syncOnce()` before
+closing.
+
+The package supports Node `>=22.19.0 <25` and npm `>=10.9.2 <12`. Releases are
+published from the repository's protected GitHub workflow with npm trusted
+publishing and provenance; no long-lived registry credential is part of that
+workflow.