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.

Install

import { CloudSyncSDK, useCloudSyncSDK } from '@talex-touch/utils/plugin/sdk'

For Node/Electron main or custom auth handling:

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

Plugin Quick Start (no token handling)

const sdk = useCloudSyncSDK()

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

Renderer/Node (custom auth)

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

await sdk.push(items)

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)

const sdk = useCloudSyncSDK()

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/plugin/sdk'

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.
• Plugin SDK reads auth token + device id from AccountSDK (account:get-auth-token / account:get-device-id).
• In Prelude, call accountSDK.setChannelSend(send) or pass channelSend in CloudSyncSDK options.