@satori-sh/upload

A simple file upload utility for Satori applications.

Installation

bun add @satori-sh/upload

Usage

import { upload } from '@satori-sh/upload';

// Upload a file
const result = await upload({
  file: fileObject, // File, Blob, or Buffer
  filename: 'document.pdf',
  contentType: 'application/pdf',
  metadata: {
    userId: '123',
    category: 'documents'
  }
});

console.log('File uploaded:', result.url);

Configuration

You can configure the upload behavior via environment variables or by passing a config object:

Environment Variables

• SATORI_UPLOAD_ENDPOINT - Upload endpoint URL (default: https://api.satori.sh/upload)
• SATORI_UPLOAD_API_KEY - API key for authentication
• SATORI_UPLOAD_BUCKET - Bucket name (default: default)
• SATORI_UPLOAD_REGION - AWS region (default: us-east-1)

Config Object

const result = await upload(options, {
  endpoint: 'https://your-endpoint.com/upload',
  apiKey: 'your-api-key',
  bucket: 'your-bucket',
  region: 'us-west-2'
});

API

upload(options, config?)

Uploads a file to the configured storage service.

Parameters:

• options - Upload options
  • file - File, Blob, or Buffer to upload
  • filename - Optional filename (default: 'upload')
  • contentType - Optional content type (default: 'application/octet-stream')
  • metadata - Optional metadata object
• config - Optional configuration object

Returns: Promise resolving to an UploadResult object with:

• url - Public URL of the uploaded file
• key - Storage key
• size - File size in bytes
• contentType - Content type
• metadata - Metadata object

Types

interface UploadOptions {
  file: File | Blob | Buffer;
  filename?: string;
  contentType?: string;
  metadata?: Record<string, string>;
}

interface UploadResult {
  url: string;
  key: string;
  size: number;
  contentType: string;
  metadata?: Record<string, string>;
}

interface UploadConfig {
  endpoint?: string;
  apiKey?: string;
  bucket?: string;
  region?: string;
}

Error Handling

The upload function throws UploadError instances with error codes:

• MISSING_API_KEY - No API key provided
• UPLOAD_FAILED - Server rejected the upload
• NETWORK_ERROR - Network-related error
• UNKNOWN_ERROR - Unexpected error

import { upload, UploadError } from '@satori-sh/upload';

try {
  const result = await upload(options);
} catch (error) {
  if (error instanceof UploadError) {
    console.error('Upload failed:', error.message, error.code);
  }
}