@amaster.ai/s3-client

Type-safe client for interacting with Amaster S3 storage service.

Installation

npm install @amaster.ai/s3-client
# or
pnpm add @amaster.ai/s3-client

Usage

import { createS3Client } from '@amaster.ai/s3-client';

const s3Client = createS3Client();

// 1. Upload a file
const fileInput = document.querySelector('input[type="file"]');
if (fileInput.files.length > 0) {
  const file = fileInput.files[0];
  const uploadResult = await s3Client.upload(file, {
    category: 'avatars',
    onProgress: ({ percentage }) => {
      console.log(`Uploading: ${percentage}%`);
    },
  });
  
  if (uploadResult.data) {
    console.log('Uploaded:', uploadResult.data.url);
    console.log('Key:', uploadResult.data.key);
  }
}

// 2. Get file metadata
const metadata = await s3Client.getMetadata('uploads/image.png');
if (metadata.data) {
  console.log('Type:', metadata.data.contentType);
  console.log('Size:', metadata.data.contentLength);
}

// 3. Download a file
const downloadResult = await s3Client.download('uploads/image.png');
if (downloadResult.data) {
  // result.data is a Blob
  const url = URL.createObjectURL(downloadResult.data);
  window.open(url);
}

API Reference

createS3Client(http?: HttpClient)

Creates a new instance of the S3 client. Optionally accepts a custom HTTP client.

upload(file: File | Blob, options?: S3UploadOptions)

Uploads a file to the storage.

Large files automatically switch to multipart upload inside the SDK. The caller still uses the same upload(file, options?) entrypoint. Browser multipart uploads report aggregate progress across all parts.

• Parameters:
  • file: File or Blob object to upload.
  • options.fileName: optional filename override.
  • options.category: optional storage category metadata.
  • options.onProgress: optional callback receiving { loaded, total, percentage, phase }.
• Returns: Promise<ClientResult<UploadRes>>

download(filename: string)

Downloads a file as a Blob.

• Parameters:
  • filename: The key/path of the file to download.
• Returns: Promise<ClientResult<Blob>>

getMetadata(key: string)

Retrieves metadata for a specific file.

• Parameters:
  • key: The key/path of the file.
• Returns: Promise<ClientResult<S3Metadata>>