cimplify
TypeScript SDK

Uploads

Three-step direct-to-storage upload: `init` hands you a presigned URL, ` PUT` the bytes, then `confirm` commits the upload. `upload(file)` is the one-call sugar that runs the whole sequence for you.

Upload a File (sugar)

async function handleFile(file: File) {
  const r = await client.uploads.upload(file)
  if (!r.ok) {
    console.error(r.error.code, r.error.message)
    return
  }

  console.log(r.value.id, r.value.url)
  console.log(r.value.filename, r.value.content_type, r.value.size_bytes)
}

Step-by-step (when you need control)

Use the explicit form when you want to show progress, retry the PUT independently, or upload bytes from a non-File source (Blob, stream, etc.).

// 1. Init: get a presigned URL
const init = await client.uploads.init(file.name, file.type, file.size, {
  idempotencyKey: 'upload-' + file.name + '-' + file.size, // optional
})
if (!init.ok) {
  console.error(init.error.code, init.error.message)
  return
}

const { upload_id, upload_url, expires_in_secs } = init.value

// 2. PUT the bytes directly to storage
const put = await fetch(upload_url, {
  method: 'PUT',
  body: file,
  headers: { 'Content-Type': file.type },
})

if (!put.ok) {
  console.error('PUT failed', put.status)
  return
}

// 3. Confirm: server validates and indexes
const confirmed = await client.uploads.confirm(upload_id)
if (!confirmed.ok) return

console.log(confirmed.value.id, confirmed.value.url)

React: a drop zone

'use client'
import { useState } from 'react'
import { useCimplifyClient } from '@cimplify/sdk/react'
import type { UploadResult } from '@cimplify/sdk'

export function DropZone({ onUploaded }: { onUploaded: (result: UploadResult) => void }) {
  const client = useCimplifyClient()
  const [status, setStatus] = useState<'idle' | 'uploading' | 'error'>('idle')

  async function pick(e: React.ChangeEvent<HTMLInputElement>) {
    const file = e.target.files?.[0]
    if (!file) return

    setStatus('uploading')
    const r = await client.uploads.upload(file)
    if (!r.ok) {
      setStatus('error')
      return
    }

    setStatus('idle')
    onUploaded(r.value)
  }

  return (
    <label>
      <input type="file" onChange={pick} />
      <span>{status === 'uploading' ? 'Uploading…' : 'Choose a file'}</span>
    </label>
  )
}

UploadResult shape

FieldTypeNotes
idstringStable upload id
urlstringPublic, durable URL
filenamestringOriginal filename
content_typestringMIME
size_bytesnumber

Method reference

MethodReturns
init(filename, contentType, sizeBytes, opts?)Result<UploadInitResponse>
confirm(uploadId)Result<UploadResult>
upload(file)Result<UploadResult>

On this page