🧱 File Storage blocks

File Storage blocks are reusable signed-URL and file-normalization operations exported through blocks from @nodeblocks/backend-sdk. They delegate to a FileStorageDriver, return neverthrow results, and do not create HTTP routes or validate MIME types and sizes themselves.

Inventory

Export	Kind	Inputs	Result / behavior / errors
FileStorageServiceError	Error class	Message, optional data	Expected storage-operation failure.
generateSignedUploadUrl	Async block	Driver, content type, byte length, object name	Driver upload URL in Result; driver failure becomes FileStorageServiceError.
generateSignedDownloadUrl	Async block	Driver, object name	Driver download URL in Result; driver failure becomes FileStorageServiceError.
generateSignedDeleteUrl	Async block	Driver, object name	Driver delete URL in Result; declared error type is Error.
generateSignedAvatarUploadUrl	Async block	Driver, content type, byte length	UUID object ID and signed upload URL; declared error type is Error.
deleteFile	Async block	Driver, object name	Driver deletion result in Result; declared error type is inferred.
generateFileUploadUrl	Async block	Driver, content type, byte length	UUID object ID and signed upload URL in Result.
normalizeFile	Async block	Driver, file with objectId and type	Preserves file fields except objectId, adding signed url.

Details

FileStorageServiceError

Implementation

Extends BlockError without an intrinsic HTTP status. The routes that use it select their own mapping; for example, the Organization upload routes map it to 500.

generateSignedUploadUrl

Implementation

Signature: generateSignedUploadUrl(fileStorageDriver: FileStorageDriver, contentType: string, contentLength: number, objectName: string). It returns Promise<Result<string, FileStorageServiceError>>, delegates unchanged arguments to driver.generateSignedUploadUrl, and returns ok(url). A rejected driver call returns err(FileStorageServiceError('Failed to generate signed upload URL.', 'generateSignedUploadUrl')).

Used by generateSignedAvatarUploadUrl, generateFileUploadUrl, and custom Chat/Product block compositions.

generateSignedDownloadUrl

Implementation

Signature: generateSignedDownloadUrl(fileStorageDriver: FileStorageDriver, objectName: string). It returns Promise<Result<string, FileStorageServiceError>>; a driver rejection becomes FileStorageServiceError('Failed to generate signed download URL.', 'generateSignedDownloadUrl').

Used by normalizeFile and custom Avatar, Organization, Product, and Chat block compositions.

generateSignedDeleteUrl

Implementation

Signature: generateSignedDeleteUrl(fileStorageDriver: FileStorageDriver, objectName: string): Promise<Result<Awaited<ReturnType<FileStorageDriver['generateSignedDeleteUrl']>>, Error>>. Returns the driver's signed delete URL; a failure is wrapped in FileStorageServiceError, although the public return signature declares Error as its error type. Custom composition only; no exported SDK route directly invokes this block.

generateSignedAvatarUploadUrl

Implementation

Signature: generateSignedAvatarUploadUrl(fileStorageDriver: FileStorageDriver, contentType: string, contentLength: number): Promise<Result<{objectId: string; url: string}, Error>>. Generates a UUID objectId, appends the extension resolved from contentType, and delegates to generateSignedUploadUrl. On success returns {objectId, url}; errors from the delegated block are returned unchanged.

Used by the source getAvatarUploadUrlRoute; see Profile routes.

deleteFile

Implementation

Signature: deleteFile(fileStorageDriver: FileStorageDriver, objectName: string): Promise<Result<void, FileStorageServiceError>> with the bundled driver. Delegates objectName to driver.deleteFile and returns its resolved value in ok. A rejected driver call returns FileStorageServiceError('Failed to delete file.').

Used by custom Avatar, Profile, Organization, Product, and Chat block/handler compositions; no exported SDK route directly invokes it.

generateFileUploadUrl

Implementation

Signature: generateFileUploadUrl(fileStorageDriver: FileStorageDriver, contentType: string, contentLength: number): Promise<Result<{objectId: string; url: string}, FileStorageServiceError>>. Generates a UUID objectId, derives an extension from contentType, then calls generateSignedUploadUrl. It returns {objectId, url} or the delegated error; an unexpected thrown failure becomes FileStorageServiceError('Failed to generate file upload url.').

Used by the source getLogoUploadUrlRoute and getCertificateUploadUrlRoute; see Organization routes.

normalizeFile

Implementation

Signature: normalizeFile(fileStorageDriver: FileStorageDriver, fileData: {objectId: string; type: string} & Record<string, unknown>): Promise<Result<{type: string; url: string}, FileStorageServiceError>>. It requests a signed download URL for objectId + '.' + extension(file.type), removes objectId, preserves the remaining runtime fields, and adds url. The declared success type contains only type and url, although the runtime object also retains other input fields. Any failure becomes FileStorageServiceError('Failed to normalize file.').

Used by custom Profile, Product, and Chat block compositions; no exported SDK route directly invokes it.