Skip to content

Latest commit

 

History

History
523 lines (386 loc) · 31.5 KB

storage.mdx

File metadata and controls

523 lines (386 loc) · 31.5 KB
title Storage schema — API Protocol reference
navTitle Storage
description Storage Service Protocol — Defines the API contract for client-side file operations.

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Storage Service Protocol

Defines the API contract for client-side file operations. Focuses on secure, direct-to-cloud uploads (Presigned URLs) rather than proxying bytes through the API server.

**Source:** `packages/spec/src/api/storage.zod.ts`

TypeScript Usage

import { CompleteChunkedUploadRequestSchema, CompleteChunkedUploadResponseSchema, CompleteUploadRequestSchema, FileDownloadUrlResponseSchema, FileTypeValidationSchema, FileUploadResponseSchema, GetPresignedUrlRequestSchema, InitiateChunkedUploadRequestSchema, InitiateChunkedUploadResponseSchema, PresignedUrlResponseSchema, RawUploadResponseSchema, UploadChunkRequestSchema, UploadChunkResponseSchema, UploadProgressSchema, UploadScopeSchema } from '@objectstack/spec/api';
import type { CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CompleteUploadRequest, FileDownloadUrlResponse, FileTypeValidation, FileUploadResponse, GetPresignedUrlRequest, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, PresignedUrlResponse, RawUploadResponse, UploadChunkRequest, UploadChunkResponse, UploadProgress, UploadScope } from '@objectstack/spec/api';

// Validate data
const result = CompleteChunkedUploadRequestSchema.parse(data);

CompleteChunkedUploadRequest

Properties

Property Type Required Description
uploadId string ✅ Multipart upload session ID
parts { chunkIndex: integer; eTag: string }[] ✅ Ordered list of uploaded parts for assembly

Nested Shape: CompleteChunkedUploadRequest.parts[number]

Property Type Required Description
chunkIndex integer ✅ Chunk index
eTag string ✅ ETag returned from chunk upload

CompleteChunkedUploadResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { fileId: string; key: string; size: integer; mimeType: string; … } ✅

Nested Shape: CompleteChunkedUploadResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: CompleteChunkedUploadResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: CompleteChunkedUploadResponse.data

Property Type Required Description
fileId string ✅ Final file ID
key string ✅ Storage key/path of the assembled file
size integer ✅ Total file size in bytes
mimeType string ✅ File MIME type
eTag string optional Final ETag of the assembled file
url string optional Download URL for the assembled file

CompleteUploadRequest

Properties

Property Type Required Description
fileId string ✅ File ID returned from presigned request
eTag string optional ETag the client reports for the uploaded object. Stored on the file record as sent and not compared with anything: no storage adapter reports a stored object's ETag. Before committing, the door checks that the storage backend holds bytes under the file's key and, when the upload declared a size, that the held size equals it.
attachTo { parentObject: string; parentId: string } optional Attach the uploaded file to this record in the same call, as the signed-in caller: the commit and the attachment row are one unit, and the answer carries the new attachmentId. Only the uploader's own pending upload in the attachments scope can be attached this way. The attachment is judged as the caller's own create: the permission to create an attachment, edit access to the record, and the record object's enable.files opt-in. A refused attach leaves the upload pending and uncommitted.

Nested Shape: CompleteUploadRequest.attachTo

Property Type Required Description
parentObject string ✅ Object of the record the file is attached to (enable.files: true)
parentId string ✅ Id of the record the file is attached to

FileDownloadUrlResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { url: string } ✅

Nested Shape: FileDownloadUrlResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: FileDownloadUrlResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: FileDownloadUrlResponse.data

Property Type Required Description
url string ✅ Short-lived signed download URL; may be server-relative

FileTypeValidation

Properties

Property Type Required Description
mode Enum<'whitelist' | 'blacklist'> ✅ whitelist = only allow listed types, blacklist = block listed types
mimeTypes string[] ✅ List of MIME types to allow or block (e.g., "image/jpeg", "application/pdf")
extensions string[] optional List of file extensions to allow or block (e.g., ".jpg", ".pdf")
maxFileSize integer optional Maximum file size in bytes
minFileSize integer optional Minimum file size in bytes (e.g., reject empty files)

FileUploadResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { path: string; name: string; size: integer; mimeType: string; … } ✅ Uploaded file metadata

Nested Shape: FileUploadResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: FileUploadResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: FileUploadResponse.data

Property Type Required Description
path string ✅ File path
name string ✅ File name
size integer ✅ File size in bytes
mimeType string ✅ MIME type
lastModified string ✅ Last modified timestamp
created string ✅ Creation timestamp
etag string optional Entity tag
fileId string optional Opaque sys_file id (ADR-0104 D3 file-as-reference)
attachmentId string optional Id of the sys_attachment row the commit created, when the request carried attachTo

GetPresignedUrlRequest

Properties

Property Type Required Description
filename string ✅ Original filename (non-empty)
mimeType string ✅ File MIME type (non-empty)
size integer ✅ File size in bytes: a non-negative whole number (0 is an empty file)
scope Enum<'user' | 'tenant' | 'private' | 'temp' | 'attachments'> optional (default: "user") Storage scope the new file is filed under (default user; attachments for the record attachments surface). Not an access setting: the upload doors refuse public, and a file is served without sign-in only when its stored file record carries acl 'public_read' (ADR-0104). The upload request carries no acl; every upload is stored private.
bucket string optional Specific bucket override (admin only)

InitiateChunkedUploadRequest

Properties

Property Type Required Description
filename string ✅ Original filename (non-empty)
mimeType string ✅ File MIME type (non-empty)
totalSize integer ✅ Total file size in bytes
chunkSize integer optional (default: 5242880) Size of each chunk in bytes (minimum 5MB per S3 spec)
scope Enum<'user' | 'tenant' | 'private' | 'temp' | 'attachments'> optional (default: "user") Storage scope the new file is filed under (default user; attachments for the record attachments surface). Not an access setting: the upload doors refuse public, and a file is served without sign-in only when its stored file record carries acl 'public_read' (ADR-0104). The upload request carries no acl; every upload is stored private.
bucket string optional Specific bucket override (admin only)
metadata Record<string, string> optional Custom metadata key-value pairs

InitiateChunkedUploadResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { uploadId: string; resumeToken: string; fileId: string; totalChunks: integer; … } ✅

Nested Shape: InitiateChunkedUploadResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: InitiateChunkedUploadResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: InitiateChunkedUploadResponse.data

Property Type Required Description
uploadId string ✅ Multipart upload session ID
resumeToken string ✅ Opaque token for resuming interrupted uploads
fileId string ✅ Assigned file ID
totalChunks integer ✅ Expected number of chunks
chunkSize integer ✅ Chunk size in bytes
expiresAt string ✅ Upload session expiration timestamp

PresignedUrlResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { uploadUrl: string; downloadUrl?: string; fileId: string; method: Enum<'PUT' | 'POST'>; … } ✅

Nested Shape: PresignedUrlResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: PresignedUrlResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: PresignedUrlResponse.data

Property Type Required Description
uploadUrl string ✅ PUT/POST URL for direct upload
downloadUrl string optional Public/Private preview URL
fileId string ✅ Temporary File ID
method Enum<'PUT' | 'POST'> ✅ HTTP Method to use
headers Record<string, string> optional Required headers for upload
expiresIn number ✅ URL expiry in seconds (unit per AWS S3 presigned URL expiresIn (@aws-sdk/s3-request-presigner))

RawUploadResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { key: string } ✅

Nested Shape: RawUploadResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: RawUploadResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: RawUploadResponse.data

Property Type Required Description
key string ✅ Storage key the bytes were written to

UploadChunkRequest

Properties

Property Type Required Description
uploadId string ✅ Multipart upload session ID
chunkIndex integer ✅ Zero-based chunk index
resumeToken string ✅ Resume token from initiate response

UploadChunkResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { chunkIndex: integer; eTag: string; bytesReceived: integer } ✅

Nested Shape: UploadChunkResponse.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: UploadChunkResponse.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: UploadChunkResponse.data

Property Type Required Description
chunkIndex integer ✅ Chunk index that was uploaded
eTag string ✅ Chunk ETag for multipart completion
bytesReceived integer ✅ Bytes received for this chunk

UploadProgress

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } optional Error details if success is false
meta { timestamp: string; duration?: integer; requestId?: string; traceId?: string } optional Response metadata
data { uploadId: string; fileId: string; filename: string; totalSize: integer; … } ✅

Nested Shape: UploadProgress.error

Property Type Required Description
code Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …> ✅ Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode string optional The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message string ✅ Readable error message
userMessage string optional Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal true optional Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category string optional Error category (e.g. validation, authorization)
httpStatus integer optional HTTP status of the response carrying this error
details any optional Additional error context (e.g. field validation errors)
requestId string optional Request ID for tracking

Nested Shape: UploadProgress.meta

Property Type Required Description
timestamp string ✅
duration integer optional Server-side processing duration in milliseconds
requestId string optional
traceId string optional

Nested Shape: UploadProgress.data

Property Type Required Description
uploadId string ✅ Multipart upload session ID
fileId string ✅ Assigned file ID
filename string ✅ Original filename
totalSize integer ✅ Total file size in bytes
uploadedSize integer ✅ Bytes uploaded so far
totalChunks integer ✅ Total expected chunks
uploadedChunks integer ✅ Number of chunks uploaded
percentComplete number ✅ Upload progress percentage
status Enum<'in_progress' | 'completing' | 'completed' | 'failed' | 'expired'> ✅ Current upload session status
startedAt string ✅ Upload session start timestamp
expiresAt string ✅ Session expiration timestamp

UploadScope

Storage scope an uploaded file is filed under

Allowed Values

  • user
  • tenant
  • private
  • temp
  • attachments