zpan-cloud-sdk

Public TypeScript SDK and API contract for ZPan Cloud.

Publication discovery and the bound-instance x402 order lifecycle require zpan-cloud-sdk >= 2.5.0.

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,
})

Anonymous Agent discovery and x402

An Agent does not need a ZPan Cloud account or Cloud token to discover a published paid resource. Search the public directory by its stable, exact capability identifier:

import {
  STORAGE_CAPACITY_PURCHASE_CAPABILITY,
  publicStorefrontListResponseSchema,
} from 'zpan-cloud-sdk'

const query = new URLSearchParams({
  capability: STORAGE_CAPACITY_PURCHASE_CAPABILITY, // storage.capacity.purchase
  limit: '20',
  offset: '0',
})
const response = await fetch(`https://cloud.zpan.space/api/public/storefronts?${query}`)
if (!response.ok) throw new Error(`directory_failed:${response.status}`)
const directory = publicStorefrontListResponseSchema.parse(await response.json())

const resource = directory.items[0]?.resources.find((item) =>
  item.capabilities.includes(STORAGE_CAPACITY_PURCHASE_CAPABILITY),
)
if (!resource) throw new Error('storage_provider_not_found')

Each resource includes its POST URL, current validated product/price snapshot, public deliverable metadata, and optional Bazaar input/output schemas. Product snapshots are refreshed when the publisher saves its publication; they avoid a live Stripe dependency on anonymous directory reads.

Call resource.postResourceUrl using the resource's documented input. When capacity must be purchased, that resource returns HTTP 402 with x402 payment requirements. The Agent selects an accepted payment option, signs and submits the payment using its x402 wallet, then retries the same resource request with the payment proof:

GET public directory (no identity)
  → POST published resource
  → 402 Payment Required
  → select + sign + pay using x402
  → retry POST with payment proof
  → resource response

ZPan Cloud owns the generic catalog, quote, settlement, and payment audit records. The published resource owns the actual upload/capacity entitlement and the resource-level 402 response. Private or unlisted registered resources can still be paid through a URL already known to an Agent; directory listing only controls anonymous discoverability.

The authenticated order lifecycle uses thin typed helpers over the generated Hono RPC client. The helpers own route details and keep protocol metadata in HTTP headers instead of duplicating it in JSON:

import {
  createX402PaymentAttempt,
  verifyX402PaymentAttempt,
} from 'zpan-cloud-sdk'

const quoteResponse = await createX402PaymentAttempt(cloud, {
  storeId,
  orderId,
  idempotencyKey: quoteKey,
  requestHash,
  resourceId,
  network,
  asset,
})
const quote = await quoteResponse.json()

await verifyX402PaymentAttempt(cloud, {
  storeId,
  orderId,
  attemptId: quote.id,
  paymentSignature,
  requestHash,
})

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).

Commerce Fulfillment Events

commerceFulfillmentEventSchema accepts legacy Stripe fulfillment contexts and provider-neutral payment provenance. Consumers should read context.paymentProvider first, then use context.providerTransactionId for the provider transaction reference. Stripe-specific fields remain available for Stripe events, and x402 events may include context.x402AuditContext.