@wiicode/s3-client

Official TypeScript/JavaScript SDK for WiiCode S3 Upload Service.

Installation

NPM (Recommended)

npm install @wiicode/s3-client

Yarn

yarn add @wiicode/s3-client

PNPM

pnpm add @wiicode/s3-client

Quick Start

import { WiiS3Client } from '@wiicode/s3-client';

const s3 = new WiiS3Client({
  endpoint: 'https://your-s3-service.com',
  apiKey: 'your_api_key',
});

// Upload a file
const file = await s3.upload(
  buffer,           // Buffer | Blob | File
  'photo.jpg',      // filename
  'image/jpeg',     // mimetype
  {
    userId: 'user-123',
    metadata: { category: 'avatar' }
  }
);

console.log(file.publicUrl);

Usage Examples

Node.js (Backend)

import { WiiS3Client } from '@wiicode/s3-client';
import * as fs from 'fs';

const s3 = new WiiS3Client({
  endpoint: process.env.WIIS3_ENDPOINT!,
  apiKey: process.env.WIIS3_API_KEY!,
});

// Upload from file system
const buffer = fs.readFileSync('./image.jpg');
const file = await s3.upload(buffer, 'image.jpg', 'image/jpeg');

console.log('Uploaded:', file.publicUrl);

// Get file info
const info = await s3.getFile(file.id);
console.log('File size:', info.size);

// Get presigned download URL (expires in 1 hour)
const { url } = await s3.getDownloadUrl(file.id);
console.log('Download URL:', url);

Note: Install form-data for Node.js:

npm install form-data

Browser/Frontend

import { WiiS3Client } from '@wiicode/s3-client';

const s3 = new WiiS3Client({
  endpoint: 'https://your-s3-service.com',
  apiKey: 'your_api_key',
});

// Upload from file input
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const uploaded = await s3.upload(file, file.name, file.type);
console.log('Uploaded:', uploaded.publicUrl);

// Display the image
document.querySelector('img').src = uploaded.publicUrl;

NestJS Integration

import { Injectable } from '@nestjs/common';
import { WiiS3Client } from '@wiicode/s3-client';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class StorageService {
  private s3Client: WiiS3Client;

  constructor(private config: ConfigService) {
    this.s3Client = new WiiS3Client({
      endpoint: this.config.get('WIIS3_ENDPOINT'),
      apiKey: this.config.get('WIIS3_API_KEY'),
    });
  }

  async uploadFile(file: Express.Multer.File, userId: string) {
    return await this.s3Client.upload(
      file.buffer,
      file.originalname,
      file.mimetype,
      { userId }
    );
  }

  async getFileUrl(fileId: string) {
    const file = await this.s3Client.getFile(fileId);
    return file.publicUrl;
  }
}

API Reference

Constructor

new WiiS3Client(config: WiiS3Config)

WiiS3Config:

• endpoint (string, required) - API endpoint URL
• apiKey (string, required) - Tenant API key
• timeout (number, optional) - Request timeout in ms (default: 30000)

Methods

upload(file, filename, mimetype, options?)

Upload a file to S3.

Parameters:

• file (Buffer | Blob | File) - File data
• filename (string) - Original filename
• mimetype (string) - MIME type
• options (UploadOptions, optional)
  • userId (string) - User identifier for organization
  • metadata (object) - Custom JSON metadata

Returns: Promise<UploadedFile>

{
  id: string;
  originalName: string;
  storedName: string;
  mimeType: string;
  size: number;
  publicUrl: string;
  uploadedAt: string;
}

getFile(fileId)

Get file metadata and public URL.

Parameters:

• fileId (string) - File UUID

Returns: Promise<FileInfo>

{
  id: string;
  originalName: string;
  storedName: string;
  mimeType: string;
  size: number;
  publicUrl: string;
  userId?: string;
  metadata?: Record<string, any>;
  uploadedAt: string;
}

getDownloadUrl(fileId)

Generate a presigned download URL (valid for 1 hour).

Parameters:

• fileId (string) - File UUID

Returns: Promise<DownloadUrlResponse>

{
  url: string;
  expiresIn: number; // 3600 seconds
}

Error Handling

import {
  WiiS3Client,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  QuotaExceededError,
  NetworkError,
} from '@wiicode/s3-client';

try {
  const file = await s3.upload(buffer, 'file.jpg', 'image/jpeg');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('File validation failed:', error.message);
  } else if (error instanceof QuotaExceededError) {
    console.error('Storage quota exceeded');
  } else if (error instanceof NotFoundError) {
    console.error('File not found');
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

Environment Variables

WIIS3_ENDPOINT=https://your-s3-service.com
WIIS3_API_KEY=your_api_key

Obtaining API Keys

Contact your service administrator to create a tenant and obtain an API key.

TypeScript Support

This package includes TypeScript definitions. No additional @types package needed.

License

MIT