@appinventiv/aws-s3 1.0.0

package/README.md

@@ -0,0 +1,595 @@
+# @appinventiv/aws-s3
+
+A comprehensive AWS S3 client package for Node.js applications. Provides easy-to-use methods for uploading, reading, deleting files, and generating presigned URLs for both S3 and CloudFront.
+
+## Installation
+
+```bash
+npm install @appinventiv/aws-s3
+```
+
+## Features
+
+- Upload files to S3 using presigned URLs
+- Read files from S3 buckets
+- Delete files from S3 buckets
+- Generate S3 presigned URLs for uploads
+- Generate CloudFront signed URLs for secure file access
+- Generate CloudFront signed cookies for folder access
+- Get file content as Base64 encoded string
+- Support for private key loading from local filesystem or S3
+
+## Prerequisites
+
+- AWS account with S3 access
+- AWS credentials configured (via environment variables, IAM role, or AWS credentials file)
+- `AWS_REGION` environment variable set
+- (Optional) CloudFront distribution for signed URL generation
+
+## AWS Setup
+
+1. Create an S3 bucket in AWS
+2. Ensure your AWS credentials have permissions to access S3
+3. Set the `AWS_REGION` environment variable
+4. (Optional) Configure CloudFront distribution for signed URLs
+
+### Required IAM Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetObject",
+        "s3:PutObject",
+        "s3:DeleteObject",
+        "s3:ListBucket"
+      ],
+      "Resource": [
+        "arn:aws:s3:::your-bucket-name",
+        "arn:aws:s3:::your-bucket-name/*"
+      ]
+    }
+  ]
+}
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { s3Service } from '@appinventiv/aws-s3';
+
+// Set AWS region (required)
+process.env.AWS_REGION = 'us-east-1';
+
+// Initialize S3 service
+s3Service.initialiseS3Manager({
+  cloudfrontDomain: 'https://d1234567890.cloudfront.net',  // Optional
+  cloudfrontKeyPairId: 'APKAIOSFODNN7EXAMPLE'              // Optional
+});
+```
+
+### Generate Presigned URL for Upload
+
+Generate a presigned URL that allows clients to upload files directly to S3:
+
+```typescript
+import { s3Service } from '@appinventiv/aws-s3';
+
+// Initialize S3 service
+s3Service.initialiseS3Manager();
+
+// Generate presigned URL for file upload
+const presignedUrl = await s3Service.getPreSignedUrl(
+  'my-bucket',           // Bucket name
+  'uploads/images',      // Base path/folder
+  'photo.jpg',           // File name
+  3600                   // Expiration in seconds (1 hour)
+);
+
+console.log('Presigned URL:', presignedUrl);
+
+// Client can now upload file using this URL
+// Example: PUT request to presignedUrl with file in body
+```
+
+### Read File from S3
+
+Read a file directly from S3 bucket:
+
+```typescript
+import { s3Service } from '@appinventiv/aws-s3';
+
+// Initialize S3 service
+s3Service.initialiseS3Manager();
+
+// Read file content
+const fileContent = await s3Service.readFile(
+  'uploads/images/photo.jpg',  // S3 object key
+  'my-bucket',                  // Bucket name
+  'utf-8'                       // Optional encoding (default: UTF-8)
+);
+
+console.log('File content:', fileContent);
+```
+
+### Delete File from S3
+
+Delete a file from S3 bucket:
+
+```typescript
+import { s3Service } from '@appinventiv/aws-s3';
+
+// Initialize S3 service
+s3Service.initialiseS3Manager();
+
+// Delete file
+await s3Service.deleteFile(
+  'my-bucket',                  // Bucket name
+  'uploads/images/photo.jpg'    // S3 object key
+);
+
+console.log('File deleted successfully');
+```
+
+### Get File as Base64
+
+Get file content as Base64 encoded string:
+
+```typescript
+import { s3Service } from '@appinventiv/aws-s3';
+
+// Initialize S3 service
+s3Service.initialiseS3Manager();
+
+// Get file as Base64
+const base64Data = await s3Service.getFileBase64Data({
+  bucket: 'my-bucket',
+  path: 'uploads/images/photo.jpg'
+});
+
+console.log('Base64 data:', base64Data);
+// Use this for embedding in HTML, sending via API, etc.
+```
+
+### CloudFront Signed URLs
+
+Generate CloudFront signed URLs for secure file access:
+
+#### Setup CloudFront Private Key
+
+First, load the CloudFront private key:
+
+```typescript
+import { s3Service } from '@appinventiv/aws-s3';
+
+// Load private key from local filesystem
+await s3Service.loadConfigForReadablePresignedUrl(
+  '/path/to/private-key.pem',  // Local file path
+  false                         // Not stored on S3
+);
+
+// Or load private key from S3
+await s3Service.loadConfigForReadablePresignedUrl(
+  'keys/cloudfront-private-key.pem',  // S3 key
+  true,                                // Stored on S3
+  'my-config-bucket'                   // S3 bucket name
+);
+```
+
+#### Generate CloudFront Signed URL for File
+
+```typescript
+import { s3Service } from '@appinventiv/aws-s3';
+
+// Initialize with CloudFront config
+s3Service.initialiseS3Manager({
+  cloudfrontDomain: 'https://d1234567890.cloudfront.net',
+  cloudfrontKeyPairId: 'APKAIOSFODNN7EXAMPLE'
+});
+
+// Load private key
+await s3Service.loadConfigForReadablePresignedUrl(
+  '/path/to/private-key.pem',
+  false
+);
+
+// Generate signed URL for a file
+const signedUrl = await s3Service.getPreSignedUrlToReadFile(
+  '/uploads/images/photo.jpg',  // File path (relative to CloudFront domain)
+  3600000                       // Expiration in milliseconds (1 hour)
+);
+
+console.log('Signed URL:', signedUrl);
+// URL is valid for the specified expiration time
+```
+
+#### Generate CloudFront Signed Cookies for Folder
+
+Generate signed cookies that allow access to all files in a folder:
+
+```typescript
+import { s3Service } from '@appinventiv/aws-s3';
+
+// Initialize with CloudFront config
+s3Service.initialiseS3Manager({
+  cloudfrontDomain: 'https://d1234567890.cloudfront.net',
+  cloudfrontKeyPairId: 'APKAIOSFODNN7EXAMPLE'
+});
+
+// Load private key
+await s3Service.loadConfigForReadablePresignedUrl(
+  '/path/to/private-key.pem',
+  false
+);
+
+// Generate signed cookies for folder access
+const cookies = await s3Service.getPreSignedUrlToReadFolder(
+  '/uploads/images/',  // Folder path (relative to CloudFront domain)
+  3600000              // Expiration in milliseconds (1 hour)
+);
+
+console.log('Signed cookies:', cookies);
+// Set these cookies in the browser to access all files in the folder
+```
+
+### Complete Example
+
+```typescript
+import { s3Service } from '@appinventiv/aws-s3';
+
+async function setupS3Service() {
+  // Set AWS region
+  process.env.AWS_REGION = 'us-east-1';
+
+  // Initialize S3 service with CloudFront config
+  s3Service.initialiseS3Manager({
+    cloudfrontDomain: 'https://d1234567890.cloudfront.net',
+    cloudfrontKeyPairId: 'APKAIOSFODNN7EXAMPLE'
+  });
+
+  // Load CloudFront private key
+  await s3Service.loadConfigForReadablePresignedUrl(
+    './keys/cloudfront-private-key.pem',
+    false
+  );
+
+  // Generate presigned URL for upload
+  const uploadUrl = await s3Service.getPreSignedUrl(
+    'my-bucket',
+    'uploads',
+    'document.pdf',
+    3600
+  );
+  console.log('Upload URL:', uploadUrl);
+
+  // Read file from S3
+  const content = await s3Service.readFile(
+    'uploads/document.pdf',
+    'my-bucket'
+  );
+  console.log('File content:', content);
+
+  // Get file as Base64
+  const base64 = await s3Service.getFileBase64Data({
+    bucket: 'my-bucket',
+    path: 'uploads/document.pdf'
+  });
+  console.log('Base64:', base64);
+
+  // Generate CloudFront signed URL
+  const signedUrl = await s3Service.getPreSignedUrlToReadFile(
+    '/uploads/document.pdf',
+    3600000
+  );
+  console.log('Signed URL:', signedUrl);
+}
+
+setupS3Service().catch(console.error);
+```
+
+### Express.js Integration Example
+
+```typescript
+import express from 'express';
+import { s3Service } from '@appinventiv/aws-s3';
+
+const app = express();
+
+// Initialize S3 on startup
+s3Service.initialiseS3Manager({
+  cloudfrontDomain: process.env.CLOUDFRONT_DOMAIN || '',
+  cloudfrontKeyPairId: process.env.CLOUDFRONT_KEY_PAIR_ID || ''
+});
+
+// Load CloudFront private key
+if (process.env.CLOUDFRONT_PRIVATE_KEY_PATH) {
+  await s3Service.loadConfigForReadablePresignedUrl(
+    process.env.CLOUDFRONT_PRIVATE_KEY_PATH,
+    false
+  );
+}
+
+// Generate upload URL endpoint
+app.post('/api/upload-url', async (req, res) => {
+  try {
+    const { fileName, folder } = req.body;
+    
+    const presignedUrl = await s3Service.getPreSignedUrl(
+      process.env.S3_BUCKET || 'my-bucket',
+      folder || 'uploads',
+      fileName,
+      3600
+    );
+    
+    res.json({ uploadUrl: presignedUrl });
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to generate upload URL' });
+  }
+});
+
+// Get file endpoint
+app.get('/api/file/:key', async (req, res) => {
+  try {
+    const content = await s3Service.readFile(
+      req.params.key,
+      process.env.S3_BUCKET || 'my-bucket'
+    );
+    
+    res.send(content);
+  } catch (error) {
+    res.status(404).json({ error: 'File not found' });
+  }
+});
+
+// Generate signed URL endpoint
+app.post('/api/signed-url', async (req, res) => {
+  try {
+    const { filePath, expiration } = req.body;
+    
+    const signedUrl = await s3Service.getPreSignedUrlToReadFile(
+      filePath,
+      expiration || 3600000
+    );
+    
+    res.json({ signedUrl });
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to generate signed URL' });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Server started on port 3000');
+});
+```
+
+## API Reference
+
+### `s3Service` (Singleton Instance)
+
+Pre-configured S3 service instance ready to use.
+
+### `AWSS3Provider` Class
+
+Main S3 provider class.
+
+#### `initialiseS3Manager(config?: IS3Config)`
+
+Initializes the S3 service with optional CloudFront configuration.
+
+**Parameters:**
+- `config.cloudfrontDomain` (string, optional): CloudFront distribution domain
+- `config.cloudfrontKeyPairId` (string, optional): CloudFront key pair ID
+
+**Example:**
+```typescript
+s3Service.initialiseS3Manager({
+  cloudfrontDomain: 'https://d1234567890.cloudfront.net',
+  cloudfrontKeyPairId: 'APKAIOSFODNN7EXAMPLE'
+});
+```
+
+#### `loadConfigForReadablePresignedUrl(privateKeyPath: string, isStoredOnS3: boolean, bucket?: string)`
+
+Loads CloudFront private key from local filesystem or S3.
+
+**Parameters:**
+- `privateKeyPath` (string): Path to private key (local path or S3 key)
+- `isStoredOnS3` (boolean): Whether key is stored in S3
+- `bucket` (string, optional): S3 bucket name (required if `isStoredOnS3` is true)
+
+**Example:**
+```typescript
+// From local filesystem
+await s3Service.loadConfigForReadablePresignedUrl('/path/to/key.pem', false);
+
+// From S3
+await s3Service.loadConfigForReadablePresignedUrl('keys/key.pem', true, 'my-bucket');
+```
+
+#### `getPreSignedUrl(bucketName: string, basePath: string, fileName: string, expiresIn?: number)`
+
+Generates a presigned URL for uploading files to S3.
+
+**Parameters:**
+- `bucketName` (string): S3 bucket name
+- `basePath` (string): Base path/folder in bucket
+- `fileName` (string): Name of the file
+- `expiresIn` (number, optional): Expiration time in seconds (default: 120)
+
+**Returns:**
+- `Promise<string>`: Presigned URL for upload
+
+**Example:**
+```typescript
+const url = await s3Service.getPreSignedUrl('my-bucket', 'uploads', 'file.jpg', 3600);
+```
+
+#### `readFile(key: string, bucket: string, encoding?: string)`
+
+Reads a file from S3 bucket.
+
+**Parameters:**
+- `key` (string): S3 object key (file path)
+- `bucket` (string): S3 bucket name
+- `encoding` (string, optional): File encoding (default: UTF-8)
+
+**Returns:**
+- `Promise<string>`: File content as string
+
+**Example:**
+```typescript
+const content = await s3Service.readFile('uploads/file.txt', 'my-bucket', 'utf-8');
+```
+
+#### `deleteFile(bucket: string, key: string)`
+
+Deletes a file from S3 bucket.
+
+**Parameters:**
+- `bucket` (string): S3 bucket name
+- `key` (string): S3 object key (file path)
+
+**Returns:**
+- `Promise<object>`: Delete operation result
+
+**Example:**
+```typescript
+await s3Service.deleteFile('my-bucket', 'uploads/file.jpg');
+```
+
+#### `getFileBase64Data(fileData: { bucket: string; path: string })`
+
+Gets file content as Base64 encoded string.
+
+**Parameters:**
+- `fileData.bucket` (string): S3 bucket name
+- `fileData.path` (string): S3 object key (file path)
+
+**Returns:**
+- `Promise<string>`: Base64 encoded file content
+
+**Example:**
+```typescript
+const base64 = await s3Service.getFileBase64Data({
+  bucket: 'my-bucket',
+  path: 'uploads/image.jpg'
+});
+```
+
+#### `getPreSignedUrlToReadFile(filePath: string, expiration: number)`
+
+Generates a CloudFront signed URL for reading a file.
+
+**Parameters:**
+- `filePath` (string): File path relative to CloudFront domain
+- `expiration` (number): Expiration time in milliseconds
+
+**Returns:**
+- `Promise<string>`: CloudFront signed URL
+
+**Example:**
+```typescript
+const signedUrl = await s3Service.getPreSignedUrlToReadFile('/uploads/file.jpg', 3600000);
+```
+
+#### `getPreSignedUrlToReadFolder(folderPath: string, expiration: number)`
+
+Generates CloudFront signed cookies for folder access.
+
+**Parameters:**
+- `folderPath` (string): Folder path relative to CloudFront domain
+- `expiration` (number): Expiration time in milliseconds
+
+**Returns:**
+- `Promise<object>`: CloudFront signed cookies object
+
+**Example:**
+```typescript
+const cookies = await s3Service.getPreSignedUrlToReadFolder('/uploads/images/', 3600000);
+```
+
+## Environment Variables
+
+- `AWS_REGION` (required): AWS region where your S3 bucket is located (e.g., `us-east-1`)
+
+## CloudFront Setup
+
+To use CloudFront signed URLs:
+
+1. Create a CloudFront distribution pointing to your S3 bucket
+2. Create a CloudFront key pair in AWS
+3. Download the private key
+4. Configure the package with CloudFront domain and key pair ID
+5. Load the private key using `loadConfigForReadablePresignedUrl()`
+
+## Error Handling
+
+The package includes structured error handling with `S3Exception` class. All errors are automatically categorized and returned in a consistent format:
+
+```typescript
+import { s3Service, S3Exception } from '@appinventiv/aws-s3';
+
+try {
+    await s3Service.readFile('file.jpg', 'my-bucket');
+} catch (error) {
+    if (error instanceof S3Exception) {
+        const errorResponse = error.getError();
+        // Returns: { status: 404, data: { message, type, originalError, context, ... } }
+    }
+}
+```
+
+Error types include: Connection, Authentication, Not Found, Validation, Timeout, Server, and Operation errors.
+
+## TypeScript Support
+
+The package includes full TypeScript definitions and is written in TypeScript.
+
+## Dependencies
+
+- `@aws-sdk/client-s3`: ^3.975.0
+- `@aws-sdk/cloudfront-signer`: ^3.975.0
+- `@aws-sdk/s3-request-presigner`: ^3.975.0
+
+## Security Best Practices
+
+1. **Never commit AWS credentials** to version control
+2. **Use IAM roles** when running on AWS infrastructure (EC2, ECS, Lambda)
+3. **Set appropriate expiration times** for presigned URLs
+4. **Use CloudFront signed URLs** for secure file access
+5. **Store private keys securely** (use AWS Secrets Manager or environment variables)
+6. **Use least privilege IAM policies** for S3 access
+7. **Enable S3 bucket encryption** for sensitive files
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Unable to Connect Error"**
+   - Verify AWS credentials are configured
+   - Check `AWS_REGION` environment variable is set
+   - Ensure IAM permissions are correct
+
+2. **"File not found" errors**
+   - Verify bucket name is correct
+   - Check S3 object key (path) is correct
+   - Ensure file exists in the bucket
+
+3. **CloudFront signed URL errors**
+   - Verify CloudFront domain and key pair ID are correct
+   - Ensure private key is loaded before generating signed URLs
+   - Check private key format is correct (PEM format)
+
+4. **Presigned URL expiration**
+   - URLs expire after the specified time
+   - Generate new URLs if expired
+   - Consider longer expiration times for production use
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@appinventiv/aws-s3",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.975.0",
+    "@aws-sdk/cloudfront-signer": "^3.975.0",
+    "@aws-sdk/s3-request-presigner": "^3.975.0"
+  }
+}

package/src/exception-handler.ts

@@ -0,0 +1,283 @@
+/**
+ * @description HTTP status messages enum
+ */
+export enum HTTP_STATUS_MESSAGE {
+    BAD_REQUEST = 400,
+    UNAUTHORIZED = 401,
+    FORBIDDEN = 403,
+    NOT_FOUND = 404,
+    CONFLICT = 409,
+    REQUEST_TIMEOUT = 408,
+    TOO_MANY_REQUESTS = 429,
+    INTERNAL_SERVER_ERROR = 500,
+    SERVICE_UNAVAILABLE = 503
+}
+
+/**
+ * @description Exception message types for S3 operations
+ */
+export enum ExceptionMessage {
+    S3_CONNECTION_ERROR = 'S3_CONNECTION_ERROR',
+    S3_OPERATION_ERROR = 'S3_OPERATION_ERROR',
+    S3_AUTH_ERROR = 'S3_AUTH_ERROR',
+    S3_NOT_FOUND = 'S3_NOT_FOUND',
+    S3_SERVER_ERROR = 'S3_SERVER_ERROR',
+    S3_TIMEOUT_ERROR = 'S3_TIMEOUT_ERROR',
+    S3_VALIDATION_ERROR = 'S3_VALIDATION_ERROR',
+    S3_UNKNOWN_ERROR = 'S3_UNKNOWN_ERROR'
+}
+
+/**
+ * @description S3 connection error codes
+ */
+export const S3_CONNECTION_ERROR = {
+    ECONNREFUSED: 'ECONNREFUSED',
+    ENOTFOUND: 'ENOTFOUND',
+    ECONNRESET: 'ECONNRESET',
+    EHOSTUNREACH: 'EHOSTUNREACH',
+    EADDRNOTAVAIL: 'EADDRNOTAVAIL',
+    ETIMEDOUT: 'ETIMEDOUT',
+    NETWORK_ERROR: 'NetworkError',
+    TIMEOUT_ERROR: 'TimeoutError'
+};
+
+/**
+ * @description S3 operation error codes
+ */
+export const S3_OPERATION_ERROR = {
+    NO_SUCH_KEY: 'NoSuchKey',
+    NO_SUCH_BUCKET: 'NoSuchBucket',
+    ACCESS_DENIED: 'AccessDenied',
+    INVALID_BUCKET_NAME: 'InvalidBucketName',
+    BUCKET_ALREADY_EXISTS: 'BucketAlreadyExists',
+    INVALID_OBJECT_STATE: 'InvalidObjectState',
+    KEY_TOO_LONG: 'KeyTooLongError',
+    INVALID_ARGUMENT: 'InvalidArgument'
+};
+
+/**
+ * @description Base exception handler class
+ */
+export class ExceptionHandler {
+    protected code: number;
+    protected status: HTTP_STATUS_MESSAGE;
+    protected data: any;
+
+    /**
+     * @description Get error response object
+     * @returns {object} Error object with status and data
+     */
+    getError() {
+        return {
+            status: this.status || HTTP_STATUS_MESSAGE.BAD_REQUEST,
+            data: this.data
+        };
+    }
+}
+
+/**
+ * @description AWS S3 exception handler
+ * Categorizes and handles AWS S3 SDK errors
+ */
+export class S3Exception extends ExceptionHandler {
+    constructor(error: any, context?: { bucket?: string; key?: string; operation?: string }) {
+        super();
+
+        const { type, status, message, name } = this.categorizeS3Error(error, context);
+
+        this.data = {
+            message: message || type,
+            type: type,
+            originalError: name || 'S3Error',
+            stack: error?.stack,
+            requestId: error?.$metadata?.requestId,
+            context: context || null
+        };
+        this.status = status;
+    }
+
+    /**
+     * @description Categorize S3 error based on error type and code
+     * @param {any} error - AWS SDK error object
+     * @param {object} context - Additional context (bucket, key, operation)
+     * @returns {object} Categorized error information
+     */
+    private categorizeS3Error(error: any, context?: { bucket?: string; key?: string; operation?: string }): {
+        type: ExceptionMessage;
+        message: string;
+        name: string;
+        status: HTTP_STATUS_MESSAGE;
+    } {
+        const message = (error?.message || '').toLowerCase();
+        const name = (error?.name || '').toLowerCase();
+        const code = error?.Code || error?.code || '';
+        const httpStatusCode = error?.$metadata?.httpStatusCode || 500;
+
+        // ------------------
+        // Connection Errors
+        // ------------------
+        const connectionMatches = [
+            S3_CONNECTION_ERROR.ECONNREFUSED,
+            S3_CONNECTION_ERROR.ENOTFOUND,
+            S3_CONNECTION_ERROR.ECONNRESET,
+            S3_CONNECTION_ERROR.EHOSTUNREACH,
+            S3_CONNECTION_ERROR.EADDRNOTAVAIL,
+            S3_CONNECTION_ERROR.ETIMEDOUT,
+            S3_CONNECTION_ERROR.NETWORK_ERROR,
+            S3_CONNECTION_ERROR.TIMEOUT_ERROR,
+            'networkerror',
+            'timeout',
+            'connection'
+        ];
+
+        if (connectionMatches.some((m) => message.includes(m.toLowerCase()) || name.includes(m.toLowerCase()))) {
+            return {
+                type: ExceptionMessage.S3_CONNECTION_ERROR,
+                message: `S3 connection error: ${error?.message || 'Unable to connect to S3'}`,
+                name: name || 'S3ConnectionError',
+                status: HTTP_STATUS_MESSAGE.SERVICE_UNAVAILABLE
+            };
+        }
+
+        // ------------------
+        // Authentication Errors
+        // ------------------
+        const authMatches = [
+            S3_OPERATION_ERROR.ACCESS_DENIED,
+            'InvalidAccessKeyId',
+            'SignatureDoesNotMatch',
+            'InvalidSecurity',
+            'MissingSecurityHeader',
+            'TokenRefreshRequired',
+            'InvalidToken',
+            'ExpiredToken',
+            'accessdenied',
+            'unauthorized',
+            'forbidden'
+        ];
+
+        if (
+            authMatches.some((m) => 
+                code?.toLowerCase().includes(m.toLowerCase()) || 
+                message.includes(m.toLowerCase()) || 
+                name.includes(m.toLowerCase())
+            )
+        ) {
+            return {
+                type: ExceptionMessage.S3_AUTH_ERROR,
+                message: `S3 authentication error: ${error?.message || 'Access denied. Check your IAM permissions'}`,
+                name: name || 'S3AuthError',
+                status: HTTP_STATUS_MESSAGE.UNAUTHORIZED
+            };
+        }
+
+        // ------------------
+        // Not Found Errors
+        // ------------------
+        const notFoundMatches = [
+            S3_OPERATION_ERROR.NO_SUCH_KEY,
+            S3_OPERATION_ERROR.NO_SUCH_BUCKET,
+            'nosuchkey',
+            'nosuchbucket',
+            'notfound'
+        ];
+
+        if (
+            notFoundMatches.some((m) => 
+                code?.toLowerCase().includes(m.toLowerCase()) || 
+                message.includes(m.toLowerCase()) || 
+                name.includes(m.toLowerCase())
+            )
+        ) {
+            const bucketInfo = context?.bucket ? ` in bucket '${context.bucket}'` : '';
+            const keyInfo = context?.key ? ` for key '${context.key}'` : '';
+            
+            return {
+                type: ExceptionMessage.S3_NOT_FOUND,
+                message: `S3 resource not found${keyInfo}${bucketInfo}: ${error?.message || 'Resource does not exist'}`,
+                name: name || 'S3NotFoundError',
+                status: HTTP_STATUS_MESSAGE.NOT_FOUND
+            };
+        }
+
+        // ------------------
+        // Validation Errors
+        // ------------------
+        const validationMatches = [
+            S3_OPERATION_ERROR.INVALID_BUCKET_NAME,
+            S3_OPERATION_ERROR.KEY_TOO_LONG,
+            S3_OPERATION_ERROR.INVALID_ARGUMENT,
+            'InvalidArgument',
+            'MalformedXML',
+            'KeyTooLongError',
+            'validation',
+            'invalid'
+        ];
+
+        if (
+            validationMatches.some((m) => 
+                code?.toLowerCase().includes(m.toLowerCase()) || 
+                message.includes(m.toLowerCase()) || 
+                name.includes(m.toLowerCase())
+            )
+        ) {
+            return {
+                type: ExceptionMessage.S3_VALIDATION_ERROR,
+                message: `S3 validation error: ${error?.message || 'Invalid request parameters'}`,
+                name: name || 'S3ValidationError',
+                status: HTTP_STATUS_MESSAGE.BAD_REQUEST
+            };
+        }
+
+        // ------------------
+        // Timeout Errors
+        // ------------------
+        if (
+            code === 'RequestTimeout' || 
+            message.includes('timeout') || 
+            name.includes('timeout') ||
+            httpStatusCode === 408
+        ) {
+            return {
+                type: ExceptionMessage.S3_TIMEOUT_ERROR,
+                message: `S3 request timeout: ${error?.message || 'Request took too long'}`,
+                name: name || 'S3TimeoutError',
+                status: HTTP_STATUS_MESSAGE.REQUEST_TIMEOUT
+            };
+        }
+
+        // ------------------
+        // Server Errors (5xx)
+        // ------------------
+        if (httpStatusCode >= 500 && httpStatusCode < 600) {
+            return {
+                type: ExceptionMessage.S3_SERVER_ERROR,
+                message: `S3 server error: ${error?.message || 'Internal server error'}`,
+                name: name || 'S3ServerError',
+                status: HTTP_STATUS_MESSAGE.INTERNAL_SERVER_ERROR
+            };
+        }
+
+        // ------------------
+        // Operational Errors (4xx)
+        // ------------------
+        if (httpStatusCode >= 400 && httpStatusCode < 500) {
+            return {
+                type: ExceptionMessage.S3_OPERATION_ERROR,
+                message: `S3 operation error: ${error?.message || 'Operation failed'}`,
+                name: name || 'S3OperationError',
+                status: <HTTP_STATUS_MESSAGE>httpStatusCode || HTTP_STATUS_MESSAGE.BAD_REQUEST
+            };
+        }
+
+        // ------------------
+        // Default / Unknown
+        // ------------------
+        return {
+            type: ExceptionMessage.S3_UNKNOWN_ERROR,
+            message: `S3 error: ${error?.message || 'Unknown error occurred'}`,
+            name: name || 'S3UnknownError',
+            status: HTTP_STATUS_MESSAGE.INTERNAL_SERVER_ERROR
+        };
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './s3';
+export * from './interface';
+export * from './exception-handler';

package/src/interface.ts

@@ -0,0 +1,4 @@
+export interface IS3Config {
+    cloudfrontDomain: string,
+    cloudfrontKeyPairId: string
+}

package/src/s3.ts

@@ -0,0 +1,251 @@
+import { DeleteObjectCommandInput, GetObjectCommand, GetObjectCommandInput, PutObjectCommand, S3, S3ClientConfig } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { CloudfrontSignInput, getSignedUrl as CloudFrontSigner, getSignedCookies } from '@aws-sdk/cloudfront-signer';
+import { IS3Config } from './interface';
+import { readFileSync } from 'node:fs';
+import { S3Exception } from './exception-handler';
+
+/**
+ * @description AWS S3 provider class for managing S3 operations
+ * Provides functionality for uploading, reading, deleting files, and generating presigned URLs
+ * Supports both S3 presigned URLs and CloudFront signed URLs/cookies
+ */
+class AWSS3Provider {
+    private client: S3;
+    private privateKey: string | Buffer;
+    private cloudfrontDomain: string;
+    private cloudfrontKeyPairId: string;
+
+    /**
+     * @description Initialize S3 Manager with optional CloudFront configuration
+     * @param {IS3Config} config - Optional configuration for CloudFront domain and key pair ID
+     */
+    public initialiseS3Manager(config?: IS3Config) {
+        try {
+            this.cloudfrontDomain = config?.cloudfrontDomain ?? '';
+            this.cloudfrontKeyPairId = config?.cloudfrontKeyPairId ?? '';
+            this.client = new S3(this.getConfiguration());
+            console.info('Connected to S3 Manager');
+        } catch (error: unknown) {
+            console.error(`Error--initializeS3Manager-Unable to Connect--msg :: `, error);
+            throw new S3Exception(error, { operation: 'initialiseS3Manager' }).getError();
+        }
+    }
+
+    /**
+     * @description Get S3 client configuration from environment variables
+     * @returns {S3ClientConfig} S3 client configuration object
+     */
+    private getConfiguration(): S3ClientConfig {
+        const creds: S3ClientConfig = {};
+        creds.region = <string>process.env.AWS_REGION;
+        return creds;
+    }
+
+    /**
+     * @description Load private key for CloudFront signed URL generation
+     * @param {string} privateKeyPath - Path to the private key file (local path or S3 key)
+     * @param {boolean} isStoredOnS3 - Whether the private key is stored in S3 or locally
+     * @param {string} bucket - S3 bucket name (required if isStoredOnS3 is true)
+     */
+    public async loadConfigForReadablePresignedUrl(privateKeyPath: string, isStoredOnS3: boolean, bucket?: string ){
+        try {
+            if(isStoredOnS3 && bucket){
+                this.privateKey = <string>await this.readFile(privateKeyPath, bucket);
+            } else {
+                this.privateKey = readFileSync(privateKeyPath, 'utf8');
+            }
+            console.info('Private key Loaded Successfully');
+        } catch (error: unknown) {
+            console.error(`Error--loadConfigForReadablePresignedUrl--msg :: `, error);
+            throw new S3Exception(error, { 
+                operation: 'loadConfigForReadablePresignedUrl',
+                bucket 
+            }).getError();
+        }
+    }
+
+    /**
+     * @description Generate a presigned URL for uploading files to S3
+     * @param {string} bucketName - Name of the S3 bucket
+     * @param {string} basePath - Base path/folder in the bucket
+     * @param {string} fileName - Name of the file to upload
+     * @param {number} expiresIn - Expiration time in seconds (default: 120 seconds / 2 minutes)
+     * @returns {Promise<string>} Presigned URL for uploading the file
+     */
+    public async getPreSignedUrl(
+        bucketName: string,
+        basePath: string,
+        fileName: string,
+        expiresIn: number = 120 // Default expiry set to 2 minutes
+    ): Promise<string> {
+        try {
+            console.info(`Generating presigned URL for - ${basePath}/${fileName} in ${bucketName}`);
+            const command = new PutObjectCommand({
+                Bucket: bucketName,
+                Key: `${basePath}/${fileName}`,
+                ACL: 'private'
+            });
+            return await getSignedUrl(this.client, command, { expiresIn });
+        } catch (error: unknown) {
+            console.error(`Error--getPreSignedUrl--msg :: `, error);
+            throw new S3Exception(error, {
+                operation: 'getPreSignedUrl',
+                bucket: bucketName,
+                key: `${basePath}/${fileName}`
+            }).getError();
+        }
+    }
+
+    /**
+     * @description Generate a CloudFront signed URL for reading a file
+     * @param {string} filePath - Path to the file in CloudFront (relative to domain)
+     * @param {number} expiration - Expiration time in milliseconds
+     * @returns {Promise<string>} CloudFront signed URL for reading the file
+     */
+    public async getPreSignedUrlToReadFile(filePath: string, expiration: number) {
+        try {
+            const cmd: CloudfrontSignInput = {
+                url: `${this.cloudfrontDomain}${filePath}`,
+                keyPairId: this.cloudfrontKeyPairId,
+                dateLessThan: new Date(Date.now() + expiration).toISOString(),
+                privateKey: this.privateKey
+            }
+
+            return CloudFrontSigner(cmd);
+        } catch (error: unknown) {
+            console.error(`Error--getPreSignedUrlToReadFile--msg :: `, error);
+            throw new S3Exception(error, {
+                operation: 'getPreSignedUrlToReadFile',
+                key: filePath
+            }).getError();
+        }
+    }
+
+    /**
+     * @description Generate CloudFront signed cookies for reading files in a folder
+     * @param {string} folderPath - Path to the folder in CloudFront (relative to domain)
+     * @param {number} expiration - Expiration time in milliseconds
+     * @returns {Promise<object>} CloudFront signed cookies object
+     */
+    public async getPreSignedUrlToReadFolder(folderPath: string, expiration: number) {
+        try {
+            const policy = {
+                Statement: [
+                    {
+                        Resource: `${this.cloudfrontDomain}${folderPath}*`,
+                        Condition: {
+                            DateLessThan: {
+                                'AWS:EpochTime': Math.floor((Date.now() + expiration) / 1000) //new Date(Date.now() + expiration).valueOf()
+                            }
+                        }
+                    }
+                ]
+            };
+            const cmd: CloudfrontSignInput = {
+                keyPairId: this.cloudfrontKeyPairId,
+                privateKey: this.privateKey,
+                policy: JSON.stringify(policy)
+            };
+
+            return getSignedCookies(cmd);
+        } catch (error: unknown) {
+            console.error(`Error--getPreSignedUrlToReadFolder--msg :: `, error);
+            throw new S3Exception(error, {
+                operation: 'getPreSignedUrlToReadFolder',
+                key: folderPath
+            }).getError();
+        }
+    }
+
+    /**
+     * @description Read a file from S3 bucket
+     * @param {string} key - S3 object key (file path)
+     * @param {string} bucket - S3 bucket name
+     * @param {string} encoding - Optional encoding for the file content (default: UTF-8)
+     * @returns {Promise<string>} File content as string
+     */
+    async readFile(key: string, bucket: string, encoding?: string) {
+        try {
+            const params: GetObjectCommandInput = {
+                Bucket: bucket,
+                Key: key
+            };
+            const file = await this.client.getObject(params);
+            return await file.Body?.transformToString(encoding);
+        } catch (error: unknown) {
+            console.error(`Error--readFile--msg :: `, error);
+            throw new S3Exception(error, {
+                operation: 'readFile',
+                bucket,
+                key
+            }).getError();
+        }
+    }
+
+    /**
+     * @description Delete a file from S3 bucket
+     * @param {string} bucket - S3 bucket name
+     * @param {string} key - S3 object key (file path)
+     * @returns {Promise<object>} Delete operation result
+     */
+    async deleteFile(bucket: string,key: string) {
+        try {
+            const params: DeleteObjectCommandInput = {
+                Bucket: bucket,
+                Key: key
+            };
+            return await this.client.deleteObject(params);
+        } catch (error: unknown) {
+            console.error(`Error--deleteFile--msg :: `, error);
+            throw new S3Exception(error, {
+                operation: 'deleteFile',
+                bucket,
+                key
+            }).getError();
+        }
+    }
+
+    /**
+     * @description Get file content as Base64 encoded string from S3
+     * @param {object} fileData - File data object
+     * @param {string} fileData.bucket - S3 bucket name
+     * @param {string} fileData.path - S3 object key (file path)
+     * @returns {Promise<string>} Base64 encoded file content
+     * @throws {Error} If file body is empty or unreadable
+     */
+    async getFileBase64Data(fileData: { bucket: string; path: string }) {
+        try {
+            const params: GetObjectCommandInput = {
+                Bucket: fileData.bucket,
+                Key: fileData.path
+            };
+            const file = await this.client.send(new GetObjectCommand(params));
+
+            const bytes = await file.Body?.transformToByteArray();
+
+            if (!bytes || bytes.length === 0) {
+                throw new S3Exception(
+                    { message: `File body is empty or unreadable from S3`, Code: 'EmptyFileBody' },
+                    {
+                        operation: 'getFileBase64Data',
+                        bucket: fileData.bucket,
+                        key: fileData.path
+                    }
+                ).getError();
+            }
+
+            // Convert to Base64 string
+            return Buffer.from(bytes).toString('base64');
+        } catch (error: unknown) {
+            console.error(`Error--getFileBase64Data--msg :: `, error);
+            throw new S3Exception(error, {
+                operation: 'getFileBase64Data',
+                bucket: fileData.bucket,
+                key: fileData.path
+            }).getError();
+        }
+    }
+}
+
+export const s3Service = new AWSS3Provider();

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "compilerOptions": {
+        "declaration": true,
+        "target": "es2022",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+        "module": "commonjs",
+        "incremental": true, 
+        "noEmit": false,                                /* Specify what module code is generated. */
+        "outDir": "./dist",                                  /* Specify an output folder for all emitted files. */
+        "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+        "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+        "strict": true,                                      /* Enable all strict type-checking options. */
+        "skipLibCheck": true,                                /* Skip type checking all .d.ts files. */
+        "strictPropertyInitialization": false,               /* Check for class properties that are declared but not set in the constructor. */
+        "sourceMap": true,                                   /* Create source map files for emitted JavaScript files. */
+        "resolveJsonModule": true,
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true,
+        "baseUrl": ".",
+    }
+}