Softypy Media Service

A robust TypeScript/JavaScript package for seamless media file management through a RESTful API. Handle uploads, transformations, thumbnails, and more with ease.

Features

- File uploads with optional transformations and metadata
- File retrieval with on-the-fly transformations
- Automatic thumbnail generation
- Custom file transformations (resize, format conversion, quality adjustment)
- Secure file deletion
- Built-in TypeScript support
- Comprehensive error handling

Installation

Install using npm:

``bash
npm install softypy-media-service
`

Or using yarn:

`bash
yarn add softypy-media-service
`

Quick Start

`typescript
import { configureMediaService, getMediaService } from 'softypy-media-service';

// Configure the service (do this once at app initialization)
configureMediaService({
baseUrl: 'https://api.example.com/media',
apiKey: 'your-api-key'
});

// Get the configured service instance
const mediaService = getMediaService();

// Upload a file
const uploadFile = async () => {
const file = new File(['content'], 'example.jpg', { type: 'image/jpeg' });
try {
const response = await mediaService.uploadFile(file, {
transform: {
width: 800,
height: 600,
format: 'webp',
quality: 85
},
metadata: {
description: 'Product image'
}
});
console.log('File uploaded:', response.publicId);
} catch (error) {
console.error('Upload failed:', error);
}
};
`

API Reference

$3

`typescript
// Configure once at application startup
configureMediaService({
baseUrl: 'https://api.example.com/media',
apiKey: 'your-api-key',
timeout: 60000, // optional, default is 30000ms
retryAttempts: 3 // optional
});

// Get the configured service instance anywhere in your app
const mediaService = getMediaService();
`

$3

#### Upload File

`typescript
uploadFile(
file: File,
options?: {
transform?: TransformOptions;
metadata?: Record;
}
): Promise
`

#### Get File

`typescript
getFile(
publicId: string,
transform?: TransformOptions
): Promise
`

#### Get Thumbnail

`typescript
getThumbnail(
publicId: string
): Promise
`

#### Transform File

`typescript
getTransformedFile(
publicId: string,
transform: TransformOptions
): Promise
`

#### Delete File

`typescript
deleteFile(
publicId: string
): Promise
`

$3

#### MediaServiceConfig

`typescript
interface MediaServiceConfig {
baseUrl: string;
apiKey: string;
timeout?: number;
retryAttempts?: number;
}
`

#### TransformOptions

`typescript
interface TransformOptions {
width?: number;
height?: number;
format?: 'jpeg' | 'png' | 'webp' | 'avif';
quality?: number;
fit?: 'cover' | 'contain' | 'fill';
}
`

#### UploadResponse

`typescript
interface UploadResponse {
_id: string;
filename: string;
originalname: string;
mimetype: string;
size: number;
path: string;
thumbnailPath?: string;
url: string;
thumbnailUrl?: string;
publicId: string;
userId: string;
versions: TransformationRecord[];
createdAt: Date;
updatedAt: Date;
}
`

#### FileResponse

`typescript
interface FileResponse {
url: string;
publicId: string;
metadata: FileMetadata;
mimetype: string;
size: number;
}
`

#### DeleteResponse

`typescript
interface DeleteResponse {
success: boolean;
message: string;
}
`

Examples

$3

`typescript
const uploadImage = async () => {
const file = new File(['content'], 'product.jpg', { type: 'image/jpeg' });

try {
const response = await mediaService.uploadFile(file, {
transform: {
width: 1200,
height: 800,
format: 'webp',
quality: 85,
fit: 'cover'
},
metadata: {
productId: '12345',
category: 'electronics'
}
});

console.log('Upload successful:', response.url);
} catch (error) {
console.error('Upload failed:', error);
}
};
`

$3

`typescript
const getTransformedImage = async (publicId) => {
try {
const response = await mediaService.getFile(publicId, {
width: 300,
height: 300,
format: 'webp',
quality: 75,
fit: 'contain'
});

console.log('Transformed image URL:', response.url);
return response;
} catch (error) {
console.error('Transformation failed:', error);
throw error;
}
};
`

$3

`typescript
const getThumbnail = async (publicId) => {
try {
const thumbnail = await mediaService.getThumbnail(publicId);
console.log('Thumbnail URL:', thumbnail.url);
return thumbnail;
} catch (error) {
console.error('Failed to get thumbnail:', error);
throw error;
}
};
`

$3

`typescript
const removeFile = async (publicId) => {
try {
const result = await mediaService.deleteFile(publicId);
console.log('File deleted:', result.message);
return result.success;
} catch (error) {
console.error('Delete failed:', error);
return false;
}
};
`

Error Handling

The service provides detailed error information through the ErrorResponse interface:

`typescript
interface ErrorResponse {
message: string;
code: string;
status: number;
}
`

Example error handling:

`typescript
try {
await mediaService.uploadFile(file);
} catch (error) {
console.error(Error (${error.code}): ${error.message});

// Handle different error status codes
switch (error.status) {
case 400:
console.error('Bad request - check your input parameters');
break;
case 401:
console.error('Authentication failed - check your API key');
break;
case 413:
console.error('File too large');
break;
case 500:
console.error('Server error');
break;
default:
console.error('Unknown error occurred');
}
}
`

Best Practices

1. Configure once at startup: Call configureMediaService()` once during application initialization.

2. Validate inputs: Although the library validates inputs, it's good practice to validate parameters before making API calls.

3. Error handling: Always wrap API calls in try/catch blocks to gracefully handle errors.

4. Optimize transformations: Use the smallest dimensions and quality settings that meet your needs to reduce bandwidth.

5. Cache results: Consider caching transformed images and thumbnails to reduce API calls.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - feel free to use this package in your projects.

Support

For issues and feature requests, please use the GitHub issue tracker.