Uploads and signed URLs
tc.storage works the same in the browser, in server code (as the request's person) and in jobs (as the app). Every call returns { data, error }; error.code names the problem and error.fix says what to do.
Upload
import { tc } from '@tenantcloud/sdk'
const me = await tc.auth.user()
const path = `${me.id}/${crypto.randomUUID()}-${file.name}` // keep people's files under their id
const { data, error } = await tc.storage.from('receipts').upload(path, file)
// data: { path, size, contentType }
if (error) alert(error.message) // e.g. STORAGE_QUOTA_EXCEEDED
- In the browser, pass a
FileorBlob, for example from an<input type="file">or a drop. - On the server, pass a
Buffer, string,Blobor Node stream, and the request:tc.storage.from('receipts', { request: req })(or usetc.middleware()). - Options:
{ contentType, upsert }. Withoutupsert: true, uploading to an existing path fails withSTORAGE_EXISTS, so nothing is overwritten by accident. Only the uploader (or aneditor/admin) can replace a file.
Uploads are streamed: nothing is buffered in full, and the size limits are enforced while streaming, so nothing is stored past a limit.
Download, list and delete
const { data: blob } = await tc.storage.from('receipts').download(path)
const { data: files } = await tc.storage.from('receipts').list(me.id)
// [{ name, path, owner, metadata: { size, mimetype } }]; folders have id null
await tc.storage.from('receipts').remove([path])
const { data: buckets } = await tc.storage.listBuckets()
Downloads support HTTP Range requests (206) and ETag caching (304). Listings return up to 1,000 entries per folder page by default. In private buckets, listings hide other people's files.
Signed URLs
A signed URL lets someone read one file they otherwise couldn't, for example an approver opening a requester's receipt in a bucket without readRoles, or an <img> thumbnail.
const { data } = await tc.storage.from('receipts').createSignedUrl(path, 300) // seconds
// <img src={data.signedUrl}>
const { data: many } = await tc.storage.from('receipts').createSignedUrls([a, b, c], 300)
| Property | Detail |
|---|---|
| Where | On the app's own origin |
| Lifetime | Default 1 hour, at most 7 days |
| What it lifts | The ownership rule only. The person opening it must still be signed in and allowed to open the app |
| Signing | HMAC-SHA256 with a per-project key |
| After expiry | STORAGE_SIGNATURE_EXPIRED |
Store the file's path in your table (for example a receipt_path text column), not a URL. Links expire; sign when you show the file.
Public URLs in app-public buckets
const url = tc.storage.from('exports').getPublicUrl('q3/report.pdf').data.publicUrl
getPublicUrl only works for app-public buckets (STORAGE_NOT_PUBLIC otherwise). "Public" means everyone who can open the app, never the internet.
Python
from tenantcloud import tc
tc.storage.from_("receipts").upload(path, data, content_type="application/pdf", request=request)
data = tc.storage.from_("receipts").download(path, request=request) # bytes
files = tc.storage.from_("receipts").list("folder", request=request)
tc.storage.from_("receipts").remove([path], request=request)
link = tc.storage.from_("receipts").create_signed_url(path, 300, request=request) # {"signedUrl": ...}
Pass request= in web handlers so the call acts as the signed-in person; jobs omit it and act as the app. Python raises TcError instead of returning { error }.
CLI
tc storage buckets # buckets, usage and quota
tc storage buckets create exports --visibility app-public
tc storage buckets create receipts --read-role approver
tc storage put ./report.pdf exports/q3/report.pdf # streamed; --upsert, --content-type
tc storage ls exports/q3
tc storage get exports/q3/report.pdf ./report.pdf
tc storage rm exports/q3/report.pdf
tc storage sign exports/q3/report.pdf --expires 600
HTTP
The SDK calls these on the app's origin:
| Method and path | Does |
|---|---|
POST /_tc/storage/v1/object/<bucket>/<path> | Upload (header x-upsert: true to replace) |
PUT /_tc/storage/v1/object/<bucket>/<path> | Upload or replace |
GET /_tc/storage/v1/object/<bucket>/<path> | Download |
DELETE /_tc/storage/v1/object/<bucket>/<path> | Delete one file |
DELETE /_tc/storage/v1/object/<bucket> | Delete several files |
GET /_tc/storage/v1/object/list/<bucket> | List a folder |
POST /_tc/storage/v1/object/sign/<bucket>/<path> | Create a signed URL |
POST /_tc/storage/v1/object/sign/<bucket> | Create several signed URLs |
GET /_tc/storage/v1/object/public/<bucket>/<path> | Read from an app-public bucket |
GET /_tc/storage/v1/buckets | List buckets |
GET /_tc/storage/v1/usage | Usage and quota |
Error codes
Storage calls fail with a STORAGE_* code and a fix hint. The full list, with fixes, is in the SDK storage reference; codes from every service are in the error code reference.