Storage

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 } from '@objectstack/spec/api';
import type { CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CompleteUploadRequest, FileDownloadUrlResponse, FileTypeValidation, FileUploadResponse, GetPresignedUrlRequest, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, PresignedUrlResponse, RawUploadResponse, UploadChunkRequest, UploadChunkResponse, UploadProgress } 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?: number; 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`.
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.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	S3 ETag verification

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?: number; 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`.
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.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?: number; 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`.
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.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)

GetPresignedUrlRequest

Properties

Property	Type	Required	Description
filename	`string`	✅	Original filename
mimeType	`string`	✅	File MIME type
size	`number`	✅	File size in bytes
scope	`string`	optional (default: `"user"`)	Target storage scope (e.g. user, private, public)
bucket	`string`	optional	Specific bucket override (admin only)

InitiateChunkedUploadRequest

Properties

Property	Type	Required	Description
filename	`string`	✅	Original filename
mimeType	`string`	✅	File MIME type
totalSize	`integer`	✅	Total file size in bytes
chunkSize	`integer`	optional (default: `5242880`)	Size of each chunk in bytes (minimum 5MB per S3 spec)
scope	`string`	optional (default: `"user"`)	Target storage scope
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?: number; 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`.
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.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?: number; 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`.
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.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

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?: number; 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`.
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.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?: number; 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`.
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.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?: number; 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`.
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.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

Storage

On this page