vintasend-sendgrid 0.4.3

package/README.md

@@ -0,0 +1,292 @@
+# VintaSend SendGrid Adapter
+
+A VintaSend email notification adapter using [SendGrid](https://sendgrid.com/) for reliable email delivery with attachment support.
+
+## Installation
+
+```bash
+npm install vintasend-sendgrid @sendgrid/mail
+```
+
+## Configuration
+
+```typescript
+import { SendgridNotificationAdapterFactory } from 'vintasend-sendgrid';
+
+const adapter = new SendgridNotificationAdapterFactory().create(
+  templateRenderer,
+  false, // enqueueNotifications
+  {
+    apiKey: process.env.SENDGRID_API_KEY,
+    fromEmail: 'noreply@example.com',
+    fromName: 'My App', // optional
+  }
+);
+```
+
+### Configuration Options
+
+```typescript
+interface SendgridConfig {
+  apiKey: string;        // SendGrid API key
+  fromEmail: string;     // Default sender email address
+  fromName?: string;     // Optional sender name
+}
+```
+
+## Usage
+
+### Basic Email
+
+```typescript
+await notificationService.createNotification({
+  userId: '123',
+  notificationType: 'EMAIL',
+  contextName: 'welcome',
+  contextParameters: { firstName: 'John' },
+  title: 'Welcome!',
+  bodyTemplate: '/templates/welcome.pug',
+  subjectTemplate: '/templates/subjects/welcome.pug',
+  sendAfter: new Date(),
+});
+```
+
+### Email with Attachments
+
+```typescript
+import { readFile } from 'fs/promises';
+
+await notificationService.createNotification({
+  userId: '123',
+  notificationType: 'EMAIL',
+  contextName: 'invoice',
+  contextParameters: { invoiceNumber: 'INV-001' },
+  title: 'Your invoice',
+  bodyTemplate: '/templates/invoice.pug',
+  subjectTemplate: '/templates/subjects/invoice.pug',
+  sendAfter: new Date(),
+  attachments: [
+    {
+      file: await readFile('./invoice.pdf'),
+      filename: 'invoice.pdf',
+      contentType: 'application/pdf',
+    },
+  ],
+});
+```
+
+### One-Off Notifications
+
+Send emails without a user account:
+
+```typescript
+await notificationService.createOneOffNotification({
+  emailOrPhone: 'customer@example.com',
+  firstName: 'Jane',
+  lastName: 'Smith',
+  notificationType: 'EMAIL',
+  contextName: 'order-confirmation',
+  contextParameters: { orderNumber: '12345' },
+  title: 'Order Confirmation',
+  bodyTemplate: '/templates/order-confirmation.pug',
+  subjectTemplate: '/templates/subjects/order-confirmation.pug',
+  sendAfter: new Date(),
+});
+```
+
+## Features
+
+- ✅ Email delivery via SendGrid API
+- ✅ File attachments (automatically base64 encoded)
+- ✅ One-off notifications
+- ✅ Scheduled notifications
+- ✅ Custom sender name and email
+- ✅ HTML email templates
+- ✅ Multiple attachments per email
+
+## API Reference
+
+### SendgridNotificationAdapterFactory
+
+```typescript
+class SendgridNotificationAdapterFactory<Config extends BaseNotificationTypeConfig>
+```
+
+**Methods:**
+- `create<TemplateRenderer>(templateRenderer, enqueueNotifications, config)` - Create adapter instance
+
+### SendgridNotificationAdapter
+
+**Properties:**
+- `key: string` - Returns `'sendgrid'`
+- `notificationType: NotificationType` - Returns `'EMAIL'`
+- `supportsAttachments: boolean` - Returns `true`
+
+**Methods:**
+- `send(notification, context)` - Send an email with optional attachments
+
+## Environment Variables
+
+```bash
+SENDGRID_API_KEY=SG.your-api-key-here
+FROM_EMAIL=noreply@example.com
+FROM_NAME=My Application
+
+The `TemplateAttachmentManager` provides a structure for implementing file attachment storage for notifications.
+
+**Supported Storage Backends:**
+- AWS S3 (see [`vintasend-aws-s3-attachments`](../vintasend-aws-s3-attachments))
+- Azure Blob Storage
+- Google Cloud Storage
+- Local Filesystem (development only)
+- Any S3-compatible storage (MinIO, DigitalOcean Spaces, etc.)
+
+**Implementation Steps:**
+
+1. **Copy this template** to a new package:
+   ```bash
+   cp -r src/implementations/vintasend-implementation-template src/implementations/vintasend-{your-storage}-attachments
+   ```
+
+2. **Update package.json**:
+   - Change package name to match your implementation
+   - Add storage-specific dependencies (e.g., `@aws-sdk/client-s3` for S3)
+   - Update description and keywords
+
+4. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+5. **Rename the class**:
+   - Rename `TemplateAttachmentManager` to your implementation name (e.g., `S3AttachmentManager`)
+   - Update all references in exports and tests
+
+4. **Implement the required methods**:
+
+   - `uploadFile(file, filename, contentType?)` - Upload file to your storage backend
+     - Convert file to Buffer using `this.fileToBuffer(file)`
+     - Calculate checksum using `this.calculateChecksum(buffer)`
+     - Auto-detect content type using `this.detectContentType(filename)`
+     - Upload to storage and return file record
+
+   - `getFile(fileId)` - Retrieve file record from database
+     - Query your backend's database for file metadata
+     - Return `AttachmentFileRecord` or `null`
+
+   - `deleteFile(fileId)` - Delete file from storage
+     - Remove from storage backend
+     - Remove file record from database
+     - Only called for orphaned files (not referenced by any notifications)
+
+   - `reconstructAttachmentFile(storageMetadata)` - Recreate file accessor
+     - Create and return an `AttachmentFile` instance
+     - Use storage metadata to configure access (e.g., S3 bucket/key)
+
+   - `findFileByChecksum(checksum)` _(optional)_ - Enable file deduplication
+     - Query database for existing file with same checksum
+     - Return existing `AttachmentFileRecord` or `null`
+     - Enables automatic deduplication when uploading identical files
+
+5. **Implement the AttachmentFile class**:
+
+   Create a storage-specific implementation of the `AttachmentFile` interface:
+
+   - `read()` - Load entire file into memory as Buffer
+   - `stream()` - Return ReadableStream for large files
+   - `url(expiresIn?)` - Generate presigned/temporary URL for access
+   - `delete()` - Delete file from storage
+
+6. **Write comprehensive tests**:
+   - Use the test template as a starting point
+   - Test all methods with various file types
+   - Test error handling
+   - Use mocks for unit tests
+   - Consider integration tests with real storage (or LocalStack/emulators)
+
+7. **Document configuration**:
+   - Document all configuration options
+   - Provide usage examples
+   - Document authentication methods
+   - Include troubleshooting tips
+
+**Example Implementation:**
+
+See [`vintasend-aws-s3-attachments`](../vintasend-aws-s3-attachments) for a complete AWS S3 implementation that follows this pattern.
+
+**Key Design Patterns:**
+
+- **Reusable Files**: Files are stored once in `AttachmentFile` table and referenced by multiple notifications via `NotificationAttachment` join table
+- **Deduplication**: Implement `findFileByChecksum()` to prevent storing duplicate files
+- **Presigned URLs**: Generate temporary URLs for secure file access without exposing credentials
+- **Streaming**: Support streaming for large files to avoid memory issues
+- **Type Safety**: All methods use strict TypeScript types from `vintasend/dist/types/attachment`
+
+## Other Components
+
+### Adapter
+
+Custom notification delivery adapters (email, SMS, push notifications, etc.)
+
+**Examples:**
+- `vintasend-nodemailer` - Email via Nodemailer
+- Custom SMS adapter
+- Custom push notification adapter
+
+### Backend
+
+Custom database persistence layers
+
+**Examples:**
+- `vintasend-prisma` - Prisma ORM backend
+- Custom MongoDB backend
+- Custom PostgreSQL backend
+
+### Template Renderer
+
+Custom notification content rendering
+
+**Examples:**
+- `vintasend-pug` - Pug template engine
+- Custom Handlebars renderer
+- Custom React email renderer
+
+### Logger
+
+Custom logging implementations
+
+**Examples:**
+- `vintasend-winston` - Winston logger
+- Custom Pino logger
+- Custom cloud logging service
+
+## Getting Started
+
+1. Choose the component type you want to implement
+2. Copy this template package to a new directory
+3. Follow the implementation steps for that component type
+4. Write comprehensive tests
+5. Document your implementation
+6. Publish as a separate npm package (optional)
+
+## Best Practices
+
+- **Type Safety**: Use TypeScript strict mode and leverage VintaSend's type system
+- **Testing**: Aim for high test coverage, including edge cases and error conditions
+- **Documentation**: Document all configuration options and provide clear examples
+- **Error Handling**: Provide clear error messages and proper error types
+- **Performance**: Consider streaming for large files, connection pooling for databases, etc.
+- **Security**: Never expose credentials, use presigned URLs, validate inputs
+
+## Contributing
+
+When creating implementations:
+- Follow the existing code style (use Biome for linting)
+- Include comprehensive tests
+- Document all public APIs
+- Add examples in README
+- Consider adding to the main VintaSend monorepo
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { SendgridNotificationAdapter, SendgridNotificationAdapterFactory } from './sendgrid-notification-adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { SendgridNotificationAdapter, SendgridNotificationAdapterFactory } from './sendgrid-notification-adapter';

package/dist/sendgrid-notification-adapter.d.ts

@@ -0,0 +1,24 @@
+import type { AttachmentData } from '@sendgrid/helpers/classes/attachment';
+import { BaseNotificationAdapter } from 'vintasend/dist/services/notification-adapters/base-notification-adapter';
+import type { BaseEmailTemplateRenderer } from 'vintasend/dist/services/notification-template-renderers/base-email-template-renderer';
+import type { JsonObject } from 'vintasend/dist/types/json-values';
+import type { AnyDatabaseNotification } from 'vintasend/dist/types/notification';
+import type { BaseNotificationTypeConfig } from 'vintasend/dist/types/notification-type-config';
+import type { StoredAttachment } from 'vintasend/dist/types/attachment';
+export interface SendgridConfig {
+    apiKey: string;
+    fromEmail: string;
+    fromName?: string;
+}
+export declare class SendgridNotificationAdapter<TemplateRenderer extends BaseEmailTemplateRenderer<Config>, Config extends BaseNotificationTypeConfig> extends BaseNotificationAdapter<TemplateRenderer, Config> {
+    key: string | null;
+    private config;
+    constructor(templateRenderer: TemplateRenderer, enqueueNotifications: boolean, config: SendgridConfig);
+    get supportsAttachments(): boolean;
+    send(notification: AnyDatabaseNotification<Config>, context: JsonObject): Promise<void>;
+    protected prepareAttachments(attachments: StoredAttachment[]): Promise<AttachmentData[]>;
+}
+export declare class SendgridNotificationAdapterFactory<Config extends BaseNotificationTypeConfig> {
+    create<TemplateRenderer extends BaseEmailTemplateRenderer<Config>>(templateRenderer: TemplateRenderer, enqueueNotifications: boolean, config: SendgridConfig): SendgridNotificationAdapter<TemplateRenderer, Config>;
+}
+//# sourceMappingURL=sendgrid-notification-adapter.d.ts.map

package/dist/sendgrid-notification-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sendgrid-notification-adapter.d.ts","sourceRoot":"","sources":["../src/sendgrid-notification-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAE3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,yEAAyE,CAAC;AAClH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sFAAsF,CAAC;AACtI,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAChG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,2BAA2B,CACtC,gBAAgB,SAAS,yBAAyB,CAAC,MAAM,CAAC,EAC1D,MAAM,SAAS,0BAA0B,CACzC,SAAQ,uBAAuB,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAc;IACvC,OAAO,CAAC,MAAM,CAAiB;gBAG7B,gBAAgB,EAAE,gBAAgB,EAClC,oBAAoB,EAAE,OAAO,EAC7B,MAAM,EAAE,cAAc;IAOxB,IAAI,mBAAmB,IAAI,OAAO,CAEjC;IAEK,IAAI,CAAC,YAAY,EAAE,uBAAuB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;cA+B7E,kBAAkB,CAChC,WAAW,EAAE,gBAAgB,EAAE,GAC9B,OAAO,CAAC,cAAc,EAAE,CAAC;CAa7B;AAED,qBAAa,kCAAkC,CAAC,MAAM,SAAS,0BAA0B;IACvF,MAAM,CAAC,gBAAgB,SAAS,yBAAyB,CAAC,MAAM,CAAC,EAC/D,gBAAgB,EAAE,gBAAgB,EAClC,oBAAoB,EAAE,OAAO,EAC7B,MAAM,EAAE,cAAc;CAQzB"}

package/dist/sendgrid-notification-adapter.js

@@ -0,0 +1,53 @@
+import sgMail from '@sendgrid/mail';
+import { BaseNotificationAdapter } from 'vintasend/dist/services/notification-adapters/base-notification-adapter';
+export class SendgridNotificationAdapter extends BaseNotificationAdapter {
+    constructor(templateRenderer, enqueueNotifications, config) {
+        super(templateRenderer, 'EMAIL', enqueueNotifications);
+        this.key = 'sendgrid';
+        this.config = config;
+        sgMail.setApiKey(config.apiKey);
+    }
+    get supportsAttachments() {
+        return true;
+    }
+    async send(notification, context) {
+        if (!this.backend) {
+            throw new Error('Backend not injected');
+        }
+        const template = await this.templateRenderer.render(notification, context);
+        if (!notification.id) {
+            throw new Error('Notification ID is required');
+        }
+        // Use the helper method to get recipient email (handles both regular and one-off notifications)
+        const recipientEmail = await this.getRecipientEmail(notification);
+        const mailData = {
+            to: recipientEmail,
+            from: this.config.fromName
+                ? { email: this.config.fromEmail, name: this.config.fromName }
+                : this.config.fromEmail,
+            subject: template.subject,
+            html: template.body,
+        };
+        // Add attachments if present
+        if (notification.attachments && notification.attachments.length > 0) {
+            mailData.attachments = await this.prepareAttachments(notification.attachments);
+        }
+        await sgMail.send(mailData);
+    }
+    async prepareAttachments(attachments) {
+        return Promise.all(attachments.map(async (att) => {
+            const content = await att.file.read();
+            return {
+                filename: att.filename,
+                content: content.toString('base64'),
+                type: att.contentType,
+                disposition: 'attachment',
+            };
+        }));
+    }
+}
+export class SendgridNotificationAdapterFactory {
+    create(templateRenderer, enqueueNotifications, config) {
+        return new SendgridNotificationAdapter(templateRenderer, enqueueNotifications, config);
+    }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "vintasend-sendgrid",
+  "version": "0.4.3",
+  "description": "",
+  "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",
+  "peerDependencies": {
+    "vintasend": "^0.4.3",
+    "@sendgrid/mail": "^8.1.6"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  }
+}