@epicenter/sync 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# @epicenter/sync
+
+`@epicenter/sync` is the wire-format package for Epicenter sync. It owns the binary framing for Yjs sync, awareness, sync-status, and peer-to-peer RPC messages so the transport layer can stay dumb. `@epicenter/workspace` and `apps/api` use it when they need to turn a `Y.Doc` change into bytes—or turn bytes back into something the app can reason about.
+
+## Installation
+
+Inside this monorepo:
+
+```json
+{
+	"dependencies": {
+		"@epicenter/sync": "workspace:*"
+	}
+}
+```
+
+This package has a peer dependency on `yjs`.
+
+## Quick usage
+
+The core flow is small on purpose: encode a sync message, send it over whatever transport you want, then decode or handle it on the other side.
+
+```typescript
+import * as Y from 'yjs';
+import {
+	MESSAGE_TYPE,
+	SYNC_MESSAGE_TYPE,
+	decodeMessageType,
+	decodeSyncMessage,
+	encodeSyncStep1,
+	handleSyncPayload,
+} from '@epicenter/sync';
+
+const doc = new Y.Doc();
+doc.getMap('users').set('alice', { name: 'Alice', age: 30 });
+
+const step1 = encodeSyncStep1({ doc });
+const messageType = decodeMessageType(step1);
+
+if (messageType === MESSAGE_TYPE.SYNC) {
+	const decoded = decodeSyncMessage(step1);
+
+	if (decoded.type === 'step1') {
+		const response = handleSyncPayload({
+			syncType: SYNC_MESSAGE_TYPE.STEP1,
+			payload: decoded.stateVector,
+			doc,
+			origin: null,
+		});
+
+		// send response over WebSocket, HTTP, BroadcastChannel, or anything else
+	}
+}
+```
+
+That example is the same shape used in the package tests and in the API room bootstrap, where the server starts a connection with `encodeSyncStep1({ doc })`.
+
+## Dumb server, separate transport
+
+This package is strict about one boundary: it handles protocol framing, not connection management. That split is why the same message helpers work over WebSockets, one-shot HTTP sync, or any custom relay you want to write.
+
+The design shows up in a few places:
+
+- `encodeSyncStep1`, `encodeSyncStep2`, and `encodeSyncUpdate` only deal with Yjs payloads.
+- `encodeSyncRequest` and `decodeSyncRequest` collapse the WebSocket handshake into a binary HTTP request/response format.
+- `encodeSyncStatus` uses an echoed version counter for save-state UX; the server can relay the payload unchanged.
+- RPC framing is separate from RPC behavior. The package defines request/response bytes and shared error variants, not the transport policy around retries or timeouts.
+
+If you want lifecycle helpers for a WebSocket server, this package is the protocol layer under them—not the server itself.
+
+## API overview
+
+Main exports from `src/index.ts`:
+
+- Message constants: `MESSAGE_TYPE`, `SYNC_MESSAGE_TYPE`, `RPC_TYPE`
+- Sync encode/decode: `encodeSyncStep1`, `encodeSyncStep2`, `encodeSyncUpdate`, `decodeSyncMessage`, `handleSyncPayload`
+- Awareness helpers: `encodeAwareness`, `encodeAwarenessStates`, `encodeQueryAwareness`
+- HTTP sync helpers: `encodeSyncRequest`, `decodeSyncRequest`
+- Save-status helpers: `encodeSyncStatus`, `decodeSyncStatus`, `stateVectorsEqual`
+- RPC helpers: `encodeRpcRequest`, `encodeRpcResponse`, `decodeRpcMessage`, `decodeRpcPayload`
+- RPC types and guards: `DecodedRpcMessage`, `RpcError`, `isRpcError`
+
+The package exports pure functions. Feed them bytes and docs; they give you bytes or decoded shapes back.
+
+## Relationship to other packages
+
+`@epicenter/sync` sits below the rest of the sync stack.
+
+```text
+apps/api                durable-object rooms, websocket handling
+        │
+@epicenter/workspace    client sync extension, rpc helpers
+        │
+@epicenter/sync         protocol framing and shared rpc error types
+        │
+yjs + y-protocols       crdt state, awareness, update encoding
+```
+
+In practice:
+
+- `apps/api` uses it to compute initial room messages and decode incoming sync traffic.
+- `@epicenter/workspace` uses it in the client sync extension.
+- Other packages do not need to know about the wire format unless they are implementing a transport.
+
+## License
+
+AGPL-3.0. That matches the package manifest and the repository's split-license model for sync infrastructure.

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@epicenter/sync",
+	"version": "0.1.0",
+	"description": "Sync protocol for Epicenter workspaces. Yjs-based encoding, WebSocket transport, and broadcast channel sync.",
+	"keywords": [
+		"local-first",
+		"Yjs",
+		"CRDT",
+		"sync",
+		"epicenter",
+		"WebSocket",
+		"offline-first",
+		"real-time"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/EpicenterHQ/epicenter.git",
+		"directory": "packages/sync"
+	},
+	"homepage": "https://epicenter.so",
+	"main": "./src/index.ts",
+	"types": "./src/index.ts",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"license": "AGPL-3.0",
+	"scripts": {
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"lib0": "catalog:",
+		"wellcrafted": "catalog:",
+		"y-protocols": "catalog:"
+	},
+	"peerDependencies": {
+		"yjs": "catalog:"
+	},
+	"devDependencies": {
+		"@types/bun": "catalog:",
+		"typescript": "catalog:",
+		"yjs": "catalog:"
+	}
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @epicenter/sync — Yjs Sync Protocol Primitives
+ *
+ * Encode/decode functions for the y-websocket wire protocol, plus
+ * RPC error variants shared by both server and client.
+ *
+ * For server-side WebSocket lifecycle handlers, import from
+ * `@epicenter/sync/server` instead.
+ */
+
+// Protocol (encode/decode for WS messages and HTTP sync requests)
+export {
+	decodeMessageType,
+	decodeRpcMessage,
+	decodeRpcPayload,
+	type DecodedRpcMessage,
+	decodeSyncMessage,
+	decodeSyncRequest,
+	decodeSyncStatus,
+	encodeAwareness,
+	encodeAwarenessStates,
+	encodeQueryAwareness,
+	encodeRpcRequest,
+	encodeRpcResponse,
+	encodeSyncRequest,
+	encodeSyncStatus,
+	encodeSyncStep1,
+	encodeSyncStep2,
+	encodeSyncUpdate,
+	handleSyncPayload,
+	MESSAGE_TYPE,
+	RPC_TYPE,
+	SYNC_MESSAGE_TYPE,
+	type SyncMessageType,
+	stateVectorsEqual,
+} from './protocol';
+
+// RPC error variants and type guard (used by both server and client)
+export { isRpcError, RpcError } from './rpc-errors';