Storage

const created = await sentroy.buckets.create({
  name: "User Uploads",
  description: "Avatars and profile media",
  isPublic: false,
})

slug is auto-derived from name if omitted.

Multipart form upload — the SDK builds the form for you. The cURL example below uses -Fto stand in for the SDK's FormData.

Browser — pass a File from an <input type="file">:

const input = document.querySelector<HTMLInputElement>("input[type=file]")!
const file = input.files![0]
const uploaded = await sentroy.media.upload("product-assets", {
  body: file,
  folder: "products",
  tags: ["v1", "cover"],
})
console.log(uploaded.url) // Public CDN URL

Node.js — convert a file to a Blob via openAsBlob:

import { openAsBlob } from "node:fs"

const blob = await openAsBlob("./photo.jpg")
const uploaded = await sentroy.media.upload("product-assets", {
  body: blob,
  filename: "photo.jpg",
  isPublic: true,
})

Video processing — videos can opt into two server-side flags. compressVideo re-encodes the source at the same resolution (typically 30–60% smaller, no visible quality loss) and runs synchronously. transcodeVideo implies compressVideo and additionally generates a 144p / 480p / 720p / 1080p ladder. Ladder generation is asynchronous: the upload response returns immediately with processing.status === "queued", then ladder rungs stream into videoMeta.variants over the next few minutes. Ladder rungs are reachable at /f/<mediaId>/<height> (e.g. /f/abc/720).

const uploaded = await sentroy.media.upload("clips", {
  body: videoFile,
  compressVideo: true,
  transcodeVideo: true,
})

// Response is immediate; ladder fills in over time:
//   uploaded.processing.status        // "queued" | "processing" | "completed"
//   uploaded.processing.variantsTotal // 4
//   uploaded.videoMeta.variants       // [] at first, fills with each rung

// Poll until done:
let media = uploaded
while (
  media.processing &&
  media.processing.status !== "completed" &&
  media.processing.status !== "failed"
) {
  await new Promise((r) => setTimeout(r, 4000))
  media = await sentroy.media.get("clips", media.id)
}
console.log(media.videoMeta?.variants.map((v) => v.height))
// → [144, 480, 720, 1080]

Latency budget: compressVideo roughly doubles the upload handler latency (the request waits for ffmpeg). transcodeVideo only adds a probe + bookkeeping on the request path; the heavy ladder work runs in the background. Plan-tier quotas still meter the final compressed bytes, not the raw upload — a sub-second probe response keeps client UIs snappy even on very long videos.

Streams from the storage backend; works for both public and private buckets (auth-gated for private). Pass quality to fetch a pre-generated thumbnail size.

const blob = await sentroy.media.download("product-assets", mediaId)

const thumb = await sentroy.media.download("product-assets", mediaId, {
  quality: 500,
})

await sentroy.media.delete("product-assets", mediaId)

Removes the original S3 object, every generated thumbnail, and the media record in one call.

The helper picks the smallest thumbnail that still covers the target (so you never upscale), then falls back through:

1. thumbnail.url if the backend exposed it directly
2. CDN-prefix + thumbnail.fileName derived from media.url
3. proxy media.downloadUrl?quality=N for private buckets
4. media.url / media.downloadUrl if no thumbnails exist (non-image, or upload before processing finished)

Returns undefined only when the media has no public URL at all.