# 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
```ts
import { CloudSyncSDK, useCloudSyncSDK } from '@talex-touch/utils/plugin/sdk'
```

For Node/Electron main or custom auth handling:
```ts
import { CloudSyncSDK } from '@talex-touch/utils'
```

## Plugin Quick Start (no token handling)
```ts
const sdk = useCloudSyncSDK()

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

## Renderer/Node (custom auth)
```ts
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)
```ts
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)
```ts
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
```ts
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.