A media upload service client for Node.js and frontend applications
npm install softypy-media-servicebash
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.