DOCS / SDK

Uploads & SDK

@cubster/assets is a typed, framework-agnostic client — zero React in the core. A client is created with createCubsterClient() and exposes four namespaces plus a set of pure URL builders.

Namespace	Methods
apiKeys	create, list, revoke
services	list
workspaces	list, create
uploads	upload, createGrant, uploadWithGrant
assets	list, get, update, delete
transcribe	transcribe(input)
transcripts	list, get, delete, retry
URL builders	imageUrl, fileUrl, rawImageUrl, assetUrl, imageCascadePath, imageSrcSet, assetSrcSet, assetStorageKey

cubster.uploads

Direct uploads (server, with a key), plus a grant flow for third-party browser uploads.

const asset = await cubster.uploads.upload({

file: new Blob([buffer], { type: 'image/png' }),

filename: 'photo.png',

tags: ['hero', 'landing'],

})

cubster.assets

List (with type/search/tag filters), get, update, or delete assets already uploaded.

const images = await cubster.assets.list({ type: 'image', tags: ['hero'], limit: 20 })

await cubster.assets.update(asset.id, { displayName: 'Hero (v2)' })

await cubster.assets.delete(asset.id)

cubster.apiKeys

Session-only (a key can't mint other keys). The full secret is only ever returned once, on create. create takes an optional services array — the services the key should serve (default: all services) — see Services.

const created = await cubster.apiKeys.create({ label: 'CI', services: ['assets'] })

console.log(created.key) // the full secret — shown exactly once

console.log(created.services) // ['assets']

cubster.workspaces

List or create workspaces you own — see the Workspaces concept page for the full management surface (rename, delete) exposed over REST.

cubster.transcribe

Upload an audio file and get back a durable, speaker-labelled transcript (Deepgram Nova-3 today) — audio up to 4 MB. A failed provider call still keeps the audio; the thrown CubsterError's transcriptFailure() carries the retry id. See the full Transcription page for the endpoint, error table, and the Transcript JSON shape.

const transcript = await cubster.transcribe({

file: new Blob([buffer], { type: 'audio/mp4' }),

filename: 'standup.m4a',

})

cubster.transcripts

list (list items omit text/segments/words, carrying a preview instead), get (includes words), delete (also deletes the underlying audio asset), and retry (re-runs a pending/failed transcript, reusing the stored audio — a completed one 409s).

const { transcripts } = await cubster.transcripts.list({ status: 'failed' })

await cubster.transcripts.retry(transcripts[0].id)

URL builders (pure)

No client needed — these mirror the API's serve-URL cascade exactly. Presets: thumb, avatar, hero, small, medium, large. SVGs and generic files always serve as forced downloads from /f/:key.

import { imageUrl, fileUrl, assetUrl } from '@cubster/assets'

imageUrl('key.png', { preset: 'thumb' }) // /img/thumb/key.png

fileUrl('doc.pdf') // /f/doc.pdf

Errors

Every non-2xx response throws a typed CubsterError carrying the HTTP status and the API's { error } message. A key-authed request outside its service scope 403s; its serviceDenied() narrows that to { service, enabled } without parsing body by hand.

Limits

Max file size: 25 MB
Max audio file size (for transcription): 4 MB
Per-workspace storage cap: 1 GB
Image types: png, jpeg, webp, gif, avif, svg+xml
File types: pdf, text/plain, csv, markdown, json, zip
Audio types: mp3, m4a, aac, wav, webm, ogg, flac