Ultra SDK Guide

5-Minute Quickstart

import { UltraClient } from '@ultra/sdk'

const ultra = new UltraClient({
  baseUrl: 'https://ultra.egomonk.com',
  agentKey: 'agk_<keyId>.<secret>'
})

const up = await ultra.uploadFile({
  file: new Blob(['hello from ultra']),
  filename: 'hello.txt',
  ttlSeconds: 120,
  authMode: 'agent',
  allowedAgentIds: ['agent-receiver'],
  metadata: { channel: 'demo' }
})

const share = await ultra.resolveShare(up.shareId)
const grant = await ultra.requestGrant(share.id)
const file = await ultra.downloadWithGrant(grant.targetId, grant.accessToken)
await ultra.deleteTransfer(up.id, up.deleteToken)

For file shares, resolveShare returns filename, mimeType, size, and expiresAt. Use mimeType as the canonical JSON content-type signal; contentType is reserved for HTTP/R2 transport metadata.

const json = await ultra.uploadJSON(
  { task: 'summarize', input: '...' },
  {
    filename: 'task.json',
    authMode: 'agent',
    allowedAgentIds: ['agent-worker'],
    schema: 'https://schemas.example/task.schema.json',
    metadata: { channel: 'research' }
  }
)

uploadJSON uses the ordinary upload path with application/json. The optional schema value is stored as metadata.schema.

const parsed = await ultra.downloadJSON(
  grant.targetId,
  grant.accessToken
)

downloadJSON uses the same grant-bound download path as downloadWithGrant, then decodes and parses JSON.

Authentication Model

• agk_...: root agent credential (store server-side only).
• aat_...: short-lived access token minted automatically.
• agrt_...: one-time grant token to fetch one target.

Primitive API Mapping

• uploadFile → POST /api/upload
• uploadJSON → POST /api/upload with application/json
• uploadFileTurbo → /api/upload/multipart/*
• uploadFiles → bounded-concurrency batch upload, optionally through Turbo multipart
• importUrl → POST /api/import-url
• initMultipartUpload / uploadMultipartPart / completeMultipartUpload → native Turbo multipart endpoints
• resolveShare → GET /api/share/{shareId}
• requestGrant → POST /api/agent/grants
• downloadJSON → GET /api/dl/{id} plus JSON parsing
• downloadWithGrant → GET /api/dl/{id}
• deleteTransfer → DELETE /api/dl/{id} with X-Delete-Token

Large Files And Imports

const large = await ultra.uploadFileTurbo({
  file,
  filename: 'large.mov',
  ttlSeconds: 3600,
  maxUses: 1
})

const resumed = await ultra.uploadFileTurbo({
  file,
  filename: 'large.mov',
  resume: { id: 'trf_...', uploadId: 'mpu_...' }
})

const batch = await ultra.uploadFiles({
  files: [
    { file: reportBlob, filename: 'report.pdf' },
    { file: videoBlob, filename: 'demo.mov' }
  ],
  concurrency: 3,
  turbo: true
})

const imported = await ultra.importUrl({
  url: 'https://example.com/report.pdf',
  filename: 'report.pdf',
  maxUses: 1
})

Turbo multipart and import-from-URL both return normal Ultra shares, so resolve, grant, download, and delete behavior stays the same after creation.

Cookbook

Agent Handoff (A → B)

await ultra.handoff({
  toAgentId: 'agent-b',
  file,
  filename: 'artifact.bin',
  ttlSeconds: 120
})

Channel Fan-Out

await ultra.channelSend({
  channel: 'research',
  file,
  filename: 'result.json',
  allowedAgentIds: ['agent-a', 'agent-b', 'agent-c']
})

Open Share

{
  "mode": "open",
  "allowedAgentIds": [],
  "maxUses": 1,
  "metadata": {}
}

Agent-Gated Share

{
  "mode": "agent",
  "allowedAgentIds": ["agent-a", "agent-b"],
  "maxUses": 1,
  "metadata": { "workflow": "review" }
}

One-Time Handoff

{
  "mode": "agent",
  "allowedAgentIds": ["agent-receiver"],
  "maxUses": 1,
  "metadata": { "step": "handoff" }
}

Channel Fan-Out Policy

{
  "mode": "agent",
  "allowedAgentIds": ["agent-a", "agent-b", "agent-c"],
  "maxUses": 3,
  "metadata": { "channel": "research" }
}

Production Guidance

• Retries: treat grants as one-use and reissue grants for each retry attempt.
• Idempotency: store caller-side operation IDs and short-circuit duplicate upload/grant requests.
• TTL Strategy: map TTL to workflow stage duration plus safety margin, not a single global value.
• Observability: log shareId, targetId, agentId, errorCode, and latency per step (resolve/grant/fetch).

Common Agent Workflows

Secure Handoff (A → B)

const up = await ultra.uploadFile({
  file,
  filename: 'artifact.bin',
  authMode: 'agent',
  allowedAgentIds: ['agent-b'],
  ttlSeconds: 120
})
const grant = await ultra.requestGrant(up.shareId)
await ultra.downloadWithGrant(grant.targetId, grant.accessToken)

Fan-Out to Channel Workers

await ultra.channelSend({
  channel: 'research',
  file,
  filename: 'task.json',
  allowedAgentIds: ['agent-a', 'agent-b', 'agent-c']
})

Grant Failure Recovery

try {
  await ultra.downloadWithGrant(targetId, accessToken)
} catch (err) {
  if (String(err).includes('invalid_grant') || String(err).includes('grant_already_used')) {
    const nextGrant = await ultra.requestGrant(shareId)
    await ultra.downloadWithGrant(nextGrant.targetId, nextGrant.accessToken)
  }
}