Sync Protocol

interface WireRow {
  t: string          // Type name ('user', 'post')
  id: string         // Record ID
  v: number          // Version number
  p: Record<string, any>  // Payload (field values)
}

{
  "t": "post",
  "id": "post-123",
  "v": 5,
  "p": {
    "title": "My Post",
    "content": "Hello world",
    "authorId": "user-1",
    "createdAt": 1698765432000
  }
}

interface SyncFrame {
  sid: number        // Sync ID (monotonic)
  t: string          // Type name
  id: string         // Record ID
  op: 'i'|'u'|'d'    // Operation (insert, update, delete)
  p?: any            // Patch (for i/u)
  who?: string       // Actor ID
  at: number         // Timestamp
  ctx?: {            // Context
    client_tx_id?: string
  }
}

{
  "sid": 1001,
  "t": "post",
  "id": "post-123",
  "op": "u",
  "p": { "title": "Updated Title" },
  "who": "user-1",
  "at": 1698765432000,
  "ctx": { "client_tx_id": "tx-789" }
}

GET /sync/v1/bootstrap
Authorization: Bearer JWT_TOKEN

Content-Type: application/x-ndjson

{"t":"user","id":"u1","v":1,"p":{...}}
{"t":"post","id":"p1","v":3,"p":{...}}
{"t":"post","id":"p2","v":1,"p":{...}}

GET /sync/v1/delta?since=1000
Authorization: Bearer JWT_TOKEN

Content-Type: application/x-ndjson

{"sid":1001,"t":"post","id":"p1","op":"u","p":{"title":"Updated"},"who":"u1","at":1698765432000}
{"sid":1002,"t":"user","id":"u2","op":"i","p":{...},"who":"u1","at":1698765433000}

GET /sync/v1/ws?token=JWT_TOKEN
Upgrade: websocket

[{"sid":1003,"t":"post","id":"p1","op":"u","p":{"title":"Real-time Update"},"at":1698765434000}]

(No explicit ack - client applies and continues)

POST /sync/v1/tx
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
 
{
  "ops": [
    {
      "t": "post",
      "id": "p1",
      "op": "u",
      "patch": { "title": "New Title" },
      "baseVersion": 3,
      "clientTxId": "tx-456"
    }
  ]
}

{
  "ok": true,
  "results": [
    {
      "ok": true,
      "id": "p1",
      "version": 4,
      "clientTxId": "tx-456"
    }
  ]
}