zpan-cloud-sdk

Public TypeScript SDK and API contract for ZPan Cloud.

import { createCloudClient } from 'zpan-cloud-sdk'
import type { CommerceFulfillmentEvent } from 'zpan-cloud-sdk'

const cloud = createCloudClient({
  baseUrl: 'https://cloud.example.com',
  token: process.env.ZPAN_CLOUD_TOKEN,
})

Avatars

A licensed + bound instance can host user/team avatars on ZPan Cloud. The endpoint takes the raw image bytes as the request body with a Content-Type header — not a JSON/form payload. Use the typed helpers:

import {
  uploadAvatar,
  deleteAvatar,
  AVATAR_SCOPES, // ['user', 'team']
  AVATAR_CONTENT_TYPES, // ['image/jpeg', 'image/png', 'image/webp', 'image/gif']
  MAX_AVATAR_BYTES, // 1 MiB
  avatarUploadResponseSchema, // { url, key }
} from 'zpan-cloud-sdk'

// PUT /avatars/:scope/:id  →  201 { url, key }
const res = await uploadAvatar(cloud, {
  scope: 'user',
  id: userId,
  body: bytes, // ArrayBuffer | ArrayBufferView | Blob
  contentType: 'image/png',
})
const { url, key } = avatarUploadResponseSchema.parse(await res.json())

// DELETE /avatars/:scope/:id  →  204
await deleteAvatar(cloud, { scope: 'user', id: userId })

Errors are returned as bare codes (AVATAR_UPLOAD_ERROR_CODES): invalid_scope / invalid_entity_id / empty_body (400), unsupported_media_type (415), payload_too_large (413), license_inactive (403).