vintasend-aws-s3-attachments 0.4.0

package/README.md

@@ -0,0 +1,93 @@
+# VintaSend AWS S3 Attachments
+
+AWS S3 attachment manager for VintaSend notifications. Provides production-ready file storage with presigned URLs and streaming support.
+
+## Installation
+
+```bash
+npm install vintasend-aws-s3-attachments
+```
+
+## Features
+
+- ✅ Upload attachments to AWS S3
+- ✅ Generate presigned URLs for secure access
+- ✅ Stream large files efficiently
+- ✅ Automatic content type detection
+- ✅ SHA-256 checksum calculation
+- ✅ Works with S3-compatible services (MinIO, DigitalOcean Spaces, etc.)
+- ✅ TypeScript support with full type safety
+
+## Quick Start
+
+```typescript
+import { S3AttachmentManager } from 'vintasend-aws-s3-attachments';
+import { PrismaNotificationBackend } from 'vintasend-prisma';
+import { VintaSendFactory } from 'vintasend';
+
+// Create S3 attachment manager
+const attachmentManager = new S3AttachmentManager({
+  bucket: 'my-app-notifications',
+  region: 'us-east-1',
+  keyPrefix: 'attachments/',
+});
+
+// Create backend with attachment manager
+const backend = new PrismaNotificationBackend(prisma, attachmentManager);
+
+// Create VintaSend instance
+const vintaSend = factory.create(
+  adapters,
+  backend,
+  contextGeneratorsMap,
+  logger,
+);
+
+// Send notification with attachment
+await vintaSend.sendNotification({
+  userId: 'user-123',
+  notificationType: 'email',
+  title: 'Welcome!',
+  bodyTemplate: 'Welcome to our service',
+  contextName: 'welcome',
+  contextParameters: {},
+  sendAfter: null,
+  subjectTemplate: 'Welcome',
+  extraParams: null,
+  attachments: [
+    {
+      file: Buffer.from('PDF content here'),
+      filename: 'welcome.pdf',
+      contentType: 'application/pdf',
+    },
+  ],
+});
+```
+
+## Configuration
+
+### S3AttachmentManagerConfig
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `bucket` | `string` | Yes | S3 bucket name where attachments will be stored |
+| `region` | `string` | Yes | AWS region for the S3 bucket |
+| `keyPrefix` | `string` | No | Optional prefix for all S3 keys (e.g., 'attachments/') |
+| `credentials` | `object` | No | AWS credentials (accessKeyId, secretAccessKey) |
+| `endpoint` | `string` | No | Custom endpoint for S3-compatible services |
+| `s3ClientConfig` | `object` | No | Additional S3 client configuration |
+
+### AWS Credentials
+
+The manager uses the standard AWS SDK credential chain:
+
+1. **Environment variables**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
+2. **IAM roles**: Recommended for EC2/ECS/Lambda deployments
+3. **Constructor credentials**: Passed directly to the manager
+4. **AWS credentials file**: `~/.aws/credentials`
+
+For more details, see the full README in the repository.
+
+## License
+
+MIT

package/dist/aws-s3-attachment-manager.d.ts

@@ -0,0 +1,100 @@
+import { BaseAttachmentManager } from 'vintasend/dist/services/attachment-manager/base-attachment-manager';
+import type { AttachmentFileRecord, AttachmentFile, FileAttachment } from 'vintasend/dist/types/attachment';
+export interface S3AttachmentManagerConfig {
+    /**
+     * S3 bucket name where attachments will be stored
+     */
+    bucket: string;
+    /**
+     * AWS region for the S3 bucket
+     */
+    region: string;
+    /**
+     * Optional prefix for all S3 keys (e.g., 'attachments/')
+     * Helps organize files within the bucket
+     */
+    keyPrefix?: string;
+    /**
+     * Optional AWS credentials
+     * If not provided, uses default credential chain (env vars, IAM roles, etc.)
+     */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    /**
+     * Optional custom endpoint for S3-compatible services
+     * (e.g., MinIO, DigitalOcean Spaces)
+     */
+    endpoint?: string;
+    /**
+     * Optional S3 client configuration
+     */
+    s3ClientConfig?: Record<string, unknown>;
+}
+/**
+ * AWS S3 AttachmentManager implementation for VintaSend.
+ *
+ * Provides production-ready file storage with:
+ * - Secure presigned URLs for file access
+ * - Streaming support for large files
+ * - Works with S3-compatible services (MinIO, DigitalOcean Spaces, etc.)
+ *
+ * Note: This manager handles S3 storage only. File metadata (AttachmentFileRecord)
+ * is stored by the Backend in its database. The Backend calls this manager's
+ * uploadFile() method and stores the returned metadata.
+ */
+export declare class S3AttachmentManager extends BaseAttachmentManager {
+    private s3Client;
+    private bucket;
+    private keyPrefix;
+    constructor(config: S3AttachmentManagerConfig);
+    /**
+     * Upload a file to S3 and return metadata.
+     *
+     * @param file - The file data (Buffer, ReadableStream, or file path)
+     * @param filename - The filename to use for storage
+     * @param contentType - Optional MIME type (auto-detected if not provided)
+     * @returns AttachmentFileRecord with S3 storage metadata
+     */
+    uploadFile(file: FileAttachment, filename: string, contentType?: string): Promise<AttachmentFileRecord>;
+    /**
+     * Reconstruct an AttachmentFile accessor from storage metadata.
+     *
+     * This allows the system to recreate file access objects when loading
+     * notifications from the database.
+     *
+     * @param storageMetadata - S3 storage metadata (bucket, key, region)
+     * @returns An S3AttachmentFile instance for accessing the file
+     */
+    reconstructAttachmentFile(storageMetadata: Record<string, unknown>): AttachmentFile;
+    /**
+     * Delete a file from S3.
+     *
+     * Note: This implementation requires the Backend to pass full storage metadata
+     * through a separate deleteFileWithMetadata() method, since the fileId alone
+     * doesn't contain the S3 key needed for deletion.
+     *
+     * For S3, the Backend should call deleteFileWithMetadata() instead.
+     *
+     * @param fileId - The unique identifier of the file
+     */
+    deleteFile(fileId: string): Promise<void>;
+    /**
+     * Delete a file from S3 using storage metadata.
+     *
+     * The Backend should call this method instead of deleteFile() for S3.
+     *
+     * @param fileId - The unique identifier of the file
+     * @param storageMetadata - The storage metadata containing S3 key
+     */
+    deleteFileWithMetadata(fileId: string, storageMetadata: Record<string, unknown>): Promise<void>;
+    /**
+     * Build the S3 key for a file.
+     *
+     * @param fileId - The unique file identifier
+     * @param filename - The original filename
+     * @returns The full S3 key including prefix
+     */
+    private buildS3Key;
+}

package/dist/aws-s3-attachment-manager.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3AttachmentManager = void 0;
+const base_attachment_manager_1 = require("vintasend/dist/services/attachment-manager/base-attachment-manager");
+const client_s3_1 = require("@aws-sdk/client-s3");
+const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
+const node_stream_1 = require("node:stream");
+const node_crypto_1 = require("node:crypto");
+/**
+ * AWS S3 AttachmentManager implementation for VintaSend.
+ *
+ * Provides production-ready file storage with:
+ * - Secure presigned URLs for file access
+ * - Streaming support for large files
+ * - Works with S3-compatible services (MinIO, DigitalOcean Spaces, etc.)
+ *
+ * Note: This manager handles S3 storage only. File metadata (AttachmentFileRecord)
+ * is stored by the Backend in its database. The Backend calls this manager's
+ * uploadFile() method and stores the returned metadata.
+ */
+class S3AttachmentManager extends base_attachment_manager_1.BaseAttachmentManager {
+    constructor(config) {
+        super();
+        this.bucket = config.bucket;
+        this.keyPrefix = config.keyPrefix || '';
+        this.s3Client = new client_s3_1.S3Client({
+            region: config.region,
+            credentials: config.credentials,
+            endpoint: config.endpoint,
+            ...config.s3ClientConfig,
+        });
+    }
+    /**
+     * Upload a file to S3 and return metadata.
+     *
+     * @param file - The file data (Buffer, ReadableStream, or file path)
+     * @param filename - The filename to use for storage
+     * @param contentType - Optional MIME type (auto-detected if not provided)
+     * @returns AttachmentFileRecord with S3 storage metadata
+     */
+    async uploadFile(file, filename, contentType) {
+        // Convert file to Buffer
+        const buffer = await this.fileToBuffer(file);
+        // Calculate checksum
+        const checksum = this.calculateChecksum(buffer);
+        // Detect content type if not provided
+        const finalContentType = contentType || this.detectContentType(filename);
+        // Generate unique S3 key
+        const fileId = (0, node_crypto_1.randomUUID)();
+        const key = this.buildS3Key(fileId, filename);
+        // Upload to S3
+        const putCommand = new client_s3_1.PutObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+            Body: buffer,
+            ContentType: finalContentType,
+            Metadata: {
+                originalFilename: filename,
+                checksum: checksum,
+            },
+        });
+        await this.s3Client.send(putCommand);
+        // Return file record with S3 metadata
+        return {
+            id: fileId,
+            filename,
+            contentType: finalContentType,
+            size: buffer.length,
+            checksum,
+            storageMetadata: {
+                bucket: this.bucket,
+                key,
+                region: this.s3Client.config.region,
+            },
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+    }
+    /**
+     * Reconstruct an AttachmentFile accessor from storage metadata.
+     *
+     * This allows the system to recreate file access objects when loading
+     * notifications from the database.
+     *
+     * @param storageMetadata - S3 storage metadata (bucket, key, region)
+     * @returns An S3AttachmentFile instance for accessing the file
+     */
+    reconstructAttachmentFile(storageMetadata) {
+        if (!storageMetadata.key || !storageMetadata.bucket) {
+            throw new Error('Storage metadata must contain bucket and key for S3 files');
+        }
+        return new S3AttachmentFile(this.s3Client, storageMetadata.bucket, storageMetadata.key);
+    }
+    /**
+     * Delete a file from S3.
+     *
+     * Note: This implementation requires the Backend to pass full storage metadata
+     * through a separate deleteFileWithMetadata() method, since the fileId alone
+     * doesn't contain the S3 key needed for deletion.
+     *
+     * For S3, the Backend should call deleteFileWithMetadata() instead.
+     *
+     * @param fileId - The unique identifier of the file
+     */
+    async deleteFile(fileId) {
+        throw new Error('deleteFile() requires storage metadata for S3. Use deleteFileWithMetadata() or delete directly via AttachmentFile.delete()');
+    }
+    /**
+     * Delete a file from S3 using storage metadata.
+     *
+     * The Backend should call this method instead of deleteFile() for S3.
+     *
+     * @param fileId - The unique identifier of the file
+     * @param storageMetadata - The storage metadata containing S3 key
+     */
+    async deleteFileWithMetadata(fileId, storageMetadata) {
+        if (!storageMetadata.key) {
+            throw new Error('Storage metadata must contain key for S3 file deletion');
+        }
+        const deleteCommand = new client_s3_1.DeleteObjectCommand({
+            Bucket: this.bucket,
+            Key: storageMetadata.key,
+        });
+        await this.s3Client.send(deleteCommand);
+    }
+    /**
+     * Build the S3 key for a file.
+     *
+     * @param fileId - The unique file identifier
+     * @param filename - The original filename
+     * @returns The full S3 key including prefix
+     */
+    buildS3Key(fileId, filename) {
+        // Use fileId as the primary key component to ensure uniqueness
+        // Include original filename for better organization and debugging
+        const sanitizedFilename = filename.replace(/[^a-zA-Z0-9.-]/g, '_');
+        return `${this.keyPrefix}${fileId}/${sanitizedFilename}`;
+    }
+}
+exports.S3AttachmentManager = S3AttachmentManager;
+/**
+ * S3 AttachmentFile implementation.
+ *
+ * Provides access to files stored in AWS S3 with support for:
+ * - Reading entire files into memory
+ * - Streaming large files
+ * - Generating presigned URLs for secure access
+ */
+class S3AttachmentFile {
+    constructor(s3Client, bucket, key) {
+        this.s3Client = s3Client;
+        this.bucket = bucket;
+        this.key = key;
+    }
+    /**
+     * Read the entire file into memory as a Buffer.
+     *
+     * Use this for small files. For large files, prefer streaming.
+     */
+    async read() {
+        const getCommand = new client_s3_1.GetObjectCommand({
+            Bucket: this.bucket,
+            Key: this.key,
+        });
+        const response = await this.s3Client.send(getCommand);
+        if (!response.Body) {
+            throw new Error('S3 object has no body');
+        }
+        // Convert stream to buffer
+        return this.streamToBuffer(response.Body);
+    }
+    /**
+     * Get a readable stream for the file.
+     *
+     * Use this for large files to avoid loading everything into memory.
+     */
+    async stream() {
+        const getCommand = new client_s3_1.GetObjectCommand({
+            Bucket: this.bucket,
+            Key: this.key,
+        });
+        const response = await this.s3Client.send(getCommand);
+        if (!response.Body) {
+            throw new Error('S3 object has no body');
+        }
+        // Convert Node.js Readable to Web ReadableStream
+        const nodeStream = response.Body;
+        return node_stream_1.Readable.toWeb(nodeStream);
+    }
+    /**
+     * Generate a presigned URL for accessing the file.
+     *
+     * @param expiresIn - Seconds until the URL expires (default: 3600 = 1 hour)
+     * @returns A presigned URL for secure file access
+     */
+    async url(expiresIn = 3600) {
+        const getCommand = new client_s3_1.GetObjectCommand({
+            Bucket: this.bucket,
+            Key: this.key,
+        });
+        return (0, s3_request_presigner_1.getSignedUrl)(this.s3Client, getCommand, { expiresIn });
+    }
+    /**
+     * Delete this file from S3.
+     *
+     * Note: This is typically called by the AttachmentManager, not directly.
+     */
+    async delete() {
+        const deleteCommand = new client_s3_1.DeleteObjectCommand({
+            Bucket: this.bucket,
+            Key: this.key,
+        });
+        await this.s3Client.send(deleteCommand);
+    }
+    /**
+     * Convert a Node.js Readable stream to a Buffer.
+     */
+    async streamToBuffer(stream) {
+        const chunks = [];
+        for await (const chunk of stream) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { S3AttachmentManager, type S3AttachmentManagerConfig, } from './aws-s3-attachment-manager';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3AttachmentManager = void 0;
+var aws_s3_attachment_manager_1 = require("./aws-s3-attachment-manager");
+Object.defineProperty(exports, "S3AttachmentManager", { enumerable: true, get: function () { return aws_s3_attachment_manager_1.S3AttachmentManager; } });

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "vintasend-aws-s3-attachments",
+  "version": "0.4.0",
+  "description": "Implementation of AWS S3 Attachments for VintaSend",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "Hugo Bessa",
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.967.0",
+    "@aws-sdk/s3-request-presigner": "^3.967.0",
+    "vintasend": "^0.4.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.6",
+    "typescript": "^5.8.2"
+  }
+}