Cloud Sync SDK
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_tokenis managed automatically and sent viax-sync-token.payload_encmust be ciphertext;meta_plainmust not contain sensitive data.op_seqmust be monotonic for idempotency and deduplication.- For Node/Electron main, pass
fetchandformDataFactoryif globals are missing.