vinc-cdn

Shared CDN upload utilities for VINC applications. Supports S3-compatible storage (AWS S3, IBM Cloud Object Storage, MinIO, etc.).

Installation

pnpm add vinc-cdn @aws-sdk/client-s3

Design Philosophy

This package uses the Provider Pattern: configuration loading is the consumer's responsibility. The package provides pure S3 operations; consumers provide configuration however they want (MongoDB, env vars, API, etc.).

Usage

Basic Upload

import { uploadToCdn, CdnConfig } from 'vinc-cdn';

// Load config from your preferred source
const config: CdnConfig = {
  endpoint: 'https://s3.eu-de.cloud-object-storage.appdomain.cloud',
  region: 'eu-de',
  bucket: 'my-bucket',
  accessKeyId: 'your-access-key',
  secretAccessKey: 'your-secret-key',
  folder: 'uploads',
  deleteEnabled: true,
};

// Upload a file
const result = await uploadToCdn(config, {
  buffer: fileBuffer,
  contentType: 'image/jpeg',
  fileName: 'photo.jpg',
});

console.log(result.url); // https://s3.eu.../my-bucket/uploads/2024-01-15T10-30-photo-jpg

Image Upload with Validation

import { uploadImage, validateImageFile } from 'vinc-cdn';

// Validate first (optional - uploadImage does this internally)
const validation = validateImageFile(file);
if (!validation.valid) {
  console.error(validation.error);
  return;
}

// Upload with automatic validation
const result = await uploadImage(config, file, 'products/123');
console.log(result.url);
console.log(result.sizeBytes);

Media Upload (Documents, Videos, 3D Models)

import { uploadMedia, validateMediaFile } from 'vinc-cdn';

const validation = validateMediaFile(file);
if (!validation.valid) {
  console.error(validation.error);
  return;
}
console.log(`Detected type: ${validation.mediaType}`); // 'document', 'video', or '3d-model'

const result = await uploadMedia(config, file, 'products/123');
console.log(result.mediaType); // 'document', 'video', or '3d-model'

Batch Uploads

import { uploadMultipleImages, uploadMultipleMedia } from 'vinc-cdn';

const { successful, failed } = await uploadMultipleImages(config, files, 'gallery');

console.log(`Uploaded: ${successful.length}`);
console.log(`Failed: ${failed.length}`);
failed.forEach(f => console.error(`${f.file}: ${f.error}`));

Utility Functions

import {
  formatFileSize,
  getFileExtension,
  isImageFile,
  getMediaTypeFromExtension,
  getAcceptString,
} from 'vinc-cdn';

formatFileSize(5 * 1024 * 1024); // "5 MB"
getFileExtension('photo.jpg');   // "jpg"
isImageFile('photo.jpg');        // true
getMediaTypeFromExtension('video.mp4'); // "video"
getAcceptString('document');     // "application/pdf,text/csv,..."

API Reference

Core Functions

| Function | Description | |----------|-------------| | uploadToCdn(config, params) | Upload raw buffer to CDN | | deleteFromCdn(config, key) | Delete file (if deleteEnabled) | | getCdnBaseUrl(config) | Get base URL for bucket | | createS3Client(config) | Create S3Client instance |

Image Functions

| Function | Description | |----------|-------------| | uploadImage(config, file, folder?) | Upload validated image | | uploadMultipleImages(config, files, folder?) | Batch image upload | | validateImageFile(file) | Validate image type and size |

Media Functions

| Function | Description | |----------|-------------| | uploadMedia(config, file, folder?) | Upload validated media | | uploadMultipleMedia(config, files, folder?) | Batch media upload | | validateMediaFile(file) | Validate media type and size | | getMediaTypeFromExtension(filename) | Detect media type from extension | | getMediaTypeFromMime(mimeType) | Detect media type from MIME | | getAcceptString(mediaType?) | Get HTML input accept string |

Utility Functions

| Function | Description | |----------|-------------| | formatFileSize(bytes) | Format bytes as human-readable | | getFileExtension(filename) | Extract file extension | | isImageFile(filename) | Check if file is an image | | sanitizeFilename(filename) | Clean filename for storage | | buildObjectKey(filename, folder?) | Build S3 object key |

Configuration Types

interface CdnConfig {
  endpoint: string;      // S3-compatible endpoint URL
  region: string;        // S3 region
  bucket: string;        // Bucket name
  accessKeyId: string;   // Access key
  secretAccessKey: string; // Secret key
  folder?: string;       // Default folder prefix
  deleteEnabled?: boolean; // Allow deletions (default: false)
}

File Size Limits

| Type | Max Size | |------|----------| | Images | 5 MB | | Documents | 10 MB | | Videos | 100 MB | | 3D Models | 50 MB |

License

MIT