Docs/Cloud Sync SDK

Cloud Sync SDK

Universal Extension

Cloud Sync SDK

Purpose

Client SDK for Nexus Sync V1. It handles handshake, push/pull, blob upload, quotas, and key management with automatic sync_token handling.

Sync signs in as the account on this device, and the caller supplies the credential and the device ID. Plugins receive neither, so they cannot sync through the account: the CloudSyncSDK exported from @talex-touch/utils/plugin/sdk is deprecated, and every call fails with PLUGIN_SYNC_UNAVAILABLE before anything is sent. A plugin keeps its data in plugin storage, which Tuff syncs once the user turns sync on.

Install

import { CloudSyncSDK } from '@talex-touch/utils'

Quick Start

const sdk = new CloudSyncSDK({
  baseUrl: 'https://api.example.com',
  getAuthToken: async () => authToken,
  getDeviceId: async () => deviceId,
  fetch,
  formDataFactory: () => new FormData(),
})

await sdk.push(items)
const pulled = await sdk.pull({ cursor: 0, limit: 100 })

Token Cache (reduce handshake calls)

const syncTokenCache = {
  token: localStorage.getItem('sync_token') || undefined,
  expiresAt: localStorage.getItem('sync_token_expires_at') || undefined,
}

const sdk = new CloudSyncSDK({
  baseUrl: 'https://api.example.com',
  getAuthToken: async () => authToken,
  getDeviceId: async () => deviceId,
  fetch,
  formDataFactory: () => new FormData(),
  syncTokenCache,
  onSyncTokenUpdate: (token, expiresAt) => {
    localStorage.setItem('sync_token', token)
    localStorage.setItem('sync_token_expires_at', expiresAt)
  },
})

End-to-end Example (delete/conflict/blob)

// sdk as created in Quick Start
const handshake = await sdk.handshake()

const now = new Date().toISOString()

const items = [
  {
    item_id: 'note-1',
    type: 'note',
    schema_version: 1,
    payload_enc: 'ciphertext', // plaintext must be encrypted on the client
    payload_ref: null,
    meta_plain: { title: 'Hello' }, // non-sensitive metadata only
    payload_size: 128,
    updated_at: now,
    op_seq: 1,
    op_hash: 'hash-1',
    op_type: 'upsert',
  },
]

const pushResult = await sdk.push(items)
if (pushResult.conflicts.length > 0) {
  const pulled = await sdk.pull({ cursor: handshake.server_cursor, limit: 100 })
  // apply server wins or merge locally
}

const pulled = await sdk.pull({ cursor: handshake.server_cursor, limit: 100 })

const blob = new Blob(['hello'], { type: 'text/plain' })
const upload = await sdk.uploadBlob(blob, { filename: 'note.txt' })

await sdk.push([
  {
    item_id: 'note-blob',
    type: 'note',
    schema_version: 1,
    payload_enc: 'ciphertext',
    payload_ref: upload.blob_id,
    meta_plain: { filename: 'note.txt' },
    payload_size: upload.size_bytes,
    updated_at: new Date().toISOString(),
    op_seq: 2,
    op_hash: 'hash-2',
    op_type: 'upsert',
  },
  {
    item_id: 'note-legacy',
    type: 'note',
    schema_version: 1,
    payload_enc: null,
    payload_ref: null,
    meta_plain: null,
    payload_size: null,
    updated_at: new Date().toISOString(),
    deleted_at: new Date().toISOString(),
    op_seq: 3,
    op_hash: 'hash-3',
    op_type: 'delete',
  },
])

const quotas = await sdk.getQuotas()

Error Handling

import { CloudSyncError } from '@talex-touch/utils'

try {
  await sdk.push(items)
} catch (error) {
  if (error instanceof CloudSyncError) {
    console.log(error.status, error.errorCode)
  }
}

Notes

  • Requires bearer auth and x-device-id.
  • sync_token is managed automatically and sent via x-sync-token.
  • payload_enc must be ciphertext; meta_plain must not contain sensitive data.
  • op_seq must be monotonic for idempotency and deduplication.
  • For Node/Electron main, pass fetch and formDataFactory if globals are missing.