vintasend 0.3.0 → 0.4.3

package/README.md

@@ -6,6 +6,7 @@ A flexible package for implementing transactional notifications in TypeScript.
 
 * **Storing notifications in a Database**: This package relies on a data store to record all the notifications that will be sent. It also keeps its state column up to date.
 * **One-off notifications**: Send notifications directly to email addresses or phone numbers without requiring a user account. Perfect for prospects, guests, or external contacts.
+* **File Attachments**: Attach files to notifications with flexible storage backend support (S3, Azure, GCS, local filesystem, etc.), automatic deduplication, and reusable file references.
 * **Scheduling notifications**: Storing notifications to be sent in the future. The notification's context for rendering the template is only evaluated at the moment the notification is sent due to the lib's context generation registry.
 * **Notification context fetched at send time**: On scheduled notifications, the package only gets the notification context (information to render the templates) at the send time, so we always get the most up-to-date information.
 * **Flexible backend**: Your project's database is getting slow after you created the first million notifications? You can migrate to a faster NoSQL database in the blink of an eye without affecting how you send the notifications.
@@ -105,6 +106,81 @@ export function sendWelcomeEmail(userId: number) {
 } 
 ```
 
+## Attachment Support
+
+VintaSend supports file attachments for notifications with an extensible architecture that allows you to choose your preferred storage backend.
+
+### Key Features
+
+- ✅ **Flexible Storage** - Support for multiple backends (AWS S3, Azure Blob, Google Cloud Storage, local filesystem, etc.)
+- ✅ **Reusable Files** - Upload once, attach to multiple notifications
+- ✅ **Automatic Deduplication** - Files with identical content stored only once
+- ✅ **Streaming Support** - Efficient handling of large files
+- ✅ **Presigned URLs** - Secure, time-limited file access (backend-dependent)
+- ✅ **Custom Backends** - Extensible interface to implement any storage service
+
+### Quick Start
+
+```typescript
+// Example using S3 AttachmentManager (see available implementations below)
+import { S3AttachmentManager } from 'vintasend-aws-s3-attachments';
+
+// Create attachment manager (configuration varies by implementation)
+const attachmentManager = new S3AttachmentManager({
+  bucket: 'my-app-notifications',
+  region: 'us-east-1',
+  keyPrefix: 'attachments/',
+});
+
+// Create VintaSend with attachment support
+const vintaSend = factory.create(
+  adapters,
+  backend,
+  templateRenderer,
+  contextGeneratorsMap,
+  logger,
+  attachmentManager, // Pass your chosen attachment manager
+);
+
+// Send notification with inline file upload
+await vintaSend.sendNotification({
+  notificationTypeId: 'order-confirmation',
+  userId: '123',
+  context: { orderNumber: 'ORD-12345' },
+  attachments: [
+    {
+      file: invoiceBuffer,
+      filename: 'invoice.pdf',
+      contentType: 'application/pdf',
+    },
+  ],
+});
+
+// Send notification with pre-uploaded file reference
+await vintaSend.sendNotification({
+  notificationTypeId: 'welcome-email',
+  userId: '456',
+  context: { userName: 'John' },
+  attachments: [
+    {
+      fileId: 'file-abc-123', // Reference to existing file
+      description: 'Company brochure',
+    },
+  ],
+});
+```
+
+### Complete Documentation
+
+For comprehensive guides on attachment support, storage backends, security, and best practices, see [ATTACHMENTS.md](ATTACHMENTS.md).
+
+Topics covered:
+- Available storage backend implementations
+- Creating custom AttachmentManagers for any storage service
+- Security best practices and performance optimization
+- Adapter support for sending attachments
+- Usage examples and patterns
+
 ## One-Off Notifications
 
 One-off notifications allow you to send notifications directly to an email address or phone number without requiring a user account in your system. This is particularly useful for:
@@ -168,7 +244,60 @@ One-off notifications are stored in the same table as regular notifications usin
 - **Regular notifications**: Have `userId` set, `emailOrPhone` is null
 - **One-off notifications**: Have `emailOrPhone` set, `userId` is null
 
-### Migration Guide
+### Migration Guides
+
+#### Migrating to v0.4.0 (Attachment Support)
+
+Version 0.4.0 introduces file attachment support with a **breaking change** to the `VintaSendFactory.create()` method signature.
+
+**Breaking Change**: The `attachmentManager` parameter now comes **before** the `options` parameter.
+
+- **Old signature (v0.3.x)**: `create(adapters, backend, logger, contextGeneratorsMap, queueService?, options?)`
+- **New signature (v0.4.0)**: `create(adapters, backend, logger, contextGeneratorsMap, queueService?, attachmentManager?, options?)`
+
+**Migration Steps**:
+
+1. **If you're NOT passing `options`** - No changes needed:
+   ```typescript
+   // This still works in v0.4.0
+   factory.create(adapters, backend, logger, contextGeneratorsMap);
+   factory.create(adapters, backend, logger, contextGeneratorsMap, queueService);
+   ```
+
+2. **If you ARE passing `options` as the 6th argument** - Add `undefined` for `attachmentManager`:
+   ```typescript
+   // Before (v0.3.x) - THIS WILL BREAK
+   factory.create(adapters, backend, logger, contextGeneratorsMap, queueService, { 
+     raiseErrorOnFailedSend: true 
+   });
+   
+   // After (v0.4.0) - CORRECT
+   factory.create(adapters, backend, logger, contextGeneratorsMap, queueService, undefined, { 
+     raiseErrorOnFailedSend: true 
+   });
+   ```
+
+3. **If you want to use attachments** - Pass the `attachmentManager`:
+   ```typescript
+   import { LocalFileAttachmentManager } from 'vintasend';
+   
+   const attachmentManager = new LocalFileAttachmentManager({ uploadDir: './uploads' });
+   
+   factory.create(adapters, backend, logger, contextGeneratorsMap, queueService, attachmentManager, {
+     raiseErrorOnFailedSend: true
+   });
+   ```
+
+4. **For Prisma users**: Add attachment models to your schema (optional, only if you want attachment support):
+   ```bash
+   # Add AttachmentFile and NotificationAttachment models to schema.prisma
+   # See ATTACHMENTS.md for the complete schema
+   prisma migrate dev --name add-attachment-support
+   ```
+
+**Note**: Attachment methods in `BaseNotificationBackend` are now **optional**. Existing backend implementations continue to work without changes. See [ATTACHMENTS.md](ATTACHMENTS.md) for full documentation.
+
+#### Migrating to v0.3.0 (One-off Notifications)
 
 If you're adding one-off notification support to an existing installation:
 
@@ -195,7 +324,9 @@ If you're adding one-off notification support to an existing installation:
 * **Queue service**: Service for enqueueing notifications so they are sent by an external service.
 * **Logger**: A class that allows the `NotificationService` to create logs following a format defined by its users.
 * **One-off Notification**: A notification sent directly to an email address or phone number without requiring a user account. Used for prospects, guests, or external contacts.
-* **Regular Notification**: A notification associated with a user account (via userId). Used for registered users in your system.  
+* **Regular Notification**: A notification associated with a user account (via userId). Used for registered users in your system.
+* **AttachmentManager**: A class that handles file storage operations (upload, download, delete) for notification attachments. Supports S3, Azure, GCS, and custom storage backends.
+* **Attachment**: A file attached to a notification, either uploaded inline or referenced from previously uploaded files. Supports automatic deduplication and reuse across multiple notifications.  
 
 
 ## Implementations
@@ -209,16 +340,24 @@ VintaSend has many backend, adapter, and template renderer implementations. If y
 ##### Backends
 
 * **[vintasend-prisma](https://github.com/vintasoftware/vintasend-prisma/)**: Uses Prisma Client to manage the notifications in the database.
+* **[vintasend-medplum](https://github.com/vintasoftware/vintasend-medplum/)**: Uses Medplum FHIR resources (Communication, Binary, Media) to manage notifications in healthcare applications.
 
 ##### Adapters
 
-* **[vintasend-nodemailer](https://github.com/vintasoftware/vintasend-nodemailer/)**: Uses nodemailer to send transactional emails to users. 
+* **[vintasend-nodemailer](https://github.com/vintasoftware/vintasend-nodemailer/)**: Uses nodemailer to send transactional emails to users.
+* **[vintasend-medplum](https://github.com/vintasoftware/vintasend-medplum/)**: Uses Medplum's email API to send notifications in healthcare applications.
+
+##### Attachment Managers
+
+* **[vintasend-aws-s3-attachments](https://github.com/vintasoftware/vintasend-aws-s3-attachments/)**: AWS S3 storage backend with presigned URLs and streaming support. Also works with S3-compatible services (MinIO, DigitalOcean Spaces, Cloudflare R2, etc.).
+* **[vintasend-medplum](https://github.com/vintasoftware/vintasend-medplum/)**: FHIR-compliant file storage using Binary and Media resources for healthcare applications.
 
 ##### Template Renderers
 * **[vintasend-pug](https://github.com/vintasoftware/vintasend-pug/)**: Renders emails using Pug.
 
 ##### Loggers
 * **[vintasend-winston](https://github.com/vintasoftware/vintasend-winston/)**: Uses Winston to allow `NotificationService` to create log entries.
+* **[vintasend-medplum](https://github.com/vintasoftware/vintasend-medplum/)**: Simple console-based logger for Medplum applications.
 
 ## Examples
 

package/dist/examples/nextjs-prisma-nodemailer-pug-temporal/next.config.d.ts

@@ -1,3 +1,3 @@
-import type { NextConfig } from "next";
+import type { NextConfig } from 'next';
 declare const nextConfig: NextConfig;
 export default nextConfig;

package/dist/examples/nextjs-prisma-nodemailer-pug-temporal/next.config.js

@@ -1,7 +1,12 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+Object.defineProperty(exports, '__esModule', { value: true });
 const nextConfig = {
-    /* config options here */
-    transpilePackages: ['vintasend', 'vintasend-prisma', 'vintasend-pug', 'vintasend-nodemailer', 'vintasend-winston'],
+  /* config options here */
+  transpilePackages: [
+    'vintasend',
+    'vintasend-prisma',
+    'vintasend-pug',
+    'vintasend-nodemailer',
+    'vintasend-winston',
+  ],
 };
 exports.default = nextConfig;

package/dist/examples/nextjs-prisma-nodemailer-pug-temporal/src/app/api/auth/forgot-password/forgot-password-notification-context.d.ts

@@ -1,9 +1,9 @@
 import type { ContextGenerator } from 'vintasend/src/services/notification-context-registry';
 export declare class ForgotPasswordContextGenerator implements ContextGenerator {
-    generate(params: {
-        token: string;
-    }): Promise<{
-        firstName: string | null;
-        resetPasswordLink: string;
-    }>;
+  generate(params: {
+    token: string;
+  }): Promise<{
+    firstName: string | null;
+    resetPasswordLink: string;
+  }>;
 }

package/dist/examples/nextjs-prisma-nodemailer-pug-temporal/src/app/api/auth/forgot-password/forgot-password-notification-context.js

@@ -1,22 +1,21 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+Object.defineProperty(exports, '__esModule', { value: true });
 exports.ForgotPasswordContextGenerator = void 0;
-const client_1 = require("@prisma/client");
+const client_1 = require('@prisma/client');
 class ForgotPasswordContextGenerator {
-    async generate(params) {
-        const prisma = new client_1.PrismaClient();
-        const APP_DOMAIN = process.env.APP_DOMAIN;
-        const token = await prisma.token.findUnique({
-            where: { token: params.token },
-            select: { user: true },
-        });
-        if (!token || !token.user) {
-            throw new Error('Token not found');
-        }
-        return {
-            firstName: token.user.firstName,
-            resetPasswordLink: `${APP_DOMAIN}/auth/reset-password/${params.token}/`,
-        };
+  async generate(params) {
+    const prisma = new client_1.PrismaClient();
+    const APP_DOMAIN = process.env.APP_DOMAIN;
+    const token = await prisma.token.findUnique({
+      where: { token: params.token },
+      select: { user: true },
+    });
+    if (!token || !token.user) {
+      throw new Error('Token not found');
     }
+    return {
+      firstName: token.user.firstName,
+      resetPasswordLink: `${APP_DOMAIN}/auth/reset-password/${params.token}/`,
+    };
+  }
 }
 exports.ForgotPasswordContextGenerator = ForgotPasswordContextGenerator;

package/dist/examples/nextjs-prisma-nodemailer-pug-temporal/src/app/api/auth/forgot-password/route.d.ts

@@ -1,10 +1,12 @@
-import type { ForgotPasswordValues } from '../../../../lib/schemas/auth';
+import type { NextResponse } from 'next/server';
+import type * as z from 'zod';
 import type { WriteApiResponse } from '../../../../lib/api-clients/core';
-import { NextResponse } from 'next/server';
-import * as z from 'zod';
+import type { ForgotPasswordValues } from '../../../../lib/schemas/auth';
 type ForgotPasswordSuccess = null;
 type ForgotPasswordValidationError = z.typeToFlattenedError<ForgotPasswordValues>;
-export type ForgotPasswordApiResponse = WriteApiResponse<ForgotPasswordSuccess, ForgotPasswordValidationError>;
+export type ForgotPasswordApiResponse = WriteApiResponse<
+  ForgotPasswordSuccess,
+  ForgotPasswordValidationError
+>;
 type ForgotPasswordNextResponse = NextResponse<ForgotPasswordApiResponse>;
 export declare function POST(req: Request): Promise<ForgotPasswordNextResponse>;
-export {};

package/dist/examples/nextjs-prisma-nodemailer-pug-temporal/src/app/api/auth/forgot-password/route.js

@@ -1,86 +1,112 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
+var __createBinding =
+  (this && this.__createBinding) ||
+  (Object.create
+    ? (o, m, k, k2) => {
+        if (k2 === undefined) k2 = k;
+        var desc = Object.getOwnPropertyDescriptor(m, k);
+        if (!desc || ('get' in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+          desc = { enumerable: true, get: () => m[k] };
+        }
+        Object.defineProperty(o, k2, desc);
+      }
+    : (o, m, k, k2) => {
+        if (k2 === undefined) k2 = k;
+        o[k2] = m[k];
+      });
+var __setModuleDefault =
+  (this && this.__setModuleDefault) ||
+  (Object.create
+    ? (o, v) => {
+        Object.defineProperty(o, 'default', { enumerable: true, value: v });
+      }
+    : (o, v) => {
+        o['default'] = v;
+      });
+var __importStar =
+  (this && this.__importStar) ||
+  (() => {
+    var ownKeys = (o) => {
+      ownKeys =
+        Object.getOwnPropertyNames ||
+        ((o) => {
+          var ar = [];
+          for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+          return ar;
+        });
+      return ownKeys(o);
     };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
+    return (mod) => {
+      if (mod && mod.__esModule) return mod;
+      var result = {};
+      if (mod != null)
+        for (var k = ownKeys(mod), i = 0; i < k.length; i++)
+          if (k[i] !== 'default') __createBinding(result, mod, k[i]);
+      __setModuleDefault(result, mod);
+      return result;
     };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
+  })();
+Object.defineProperty(exports, '__esModule', { value: true });
 exports.POST = POST;
-const auth_1 = require("../../../../lib/schemas/auth");
-const client_1 = require("@prisma/client");
-const auth_2 = require("../../../../lib/services/auth");
-const server_1 = require("next/server");
-const z = __importStar(require("zod"));
-const library_1 = require("@prisma/client/runtime/library");
-const notifications_with_queue_1 = require("../../../../lib/services/notifications-with-queue");
+const auth_1 = require('../../../../lib/schemas/auth');
+const client_1 = require('@prisma/client');
+const auth_2 = require('../../../../lib/services/auth');
+const server_1 = require('next/server');
+const z = __importStar(require('zod'));
+const library_1 = require('@prisma/client/runtime/library');
+const notifications_with_queue_1 = require('../../../../lib/services/notifications-with-queue');
 async function POST(req) {
-    try {
-        const body = await req.json();
-        const { email } = auth_1.forgotPasswordSchema.parse(body);
-        const prisma = new client_1.PrismaClient();
-        const user = await prisma.user.findUnique({ where: { email } });
-        if (user) {
-            const resetToken = (0, auth_2.generateToken)({ userId: user.id }, '1h');
-            await prisma.token.create({
-                data: {
-                    token: resetToken,
-                    type: 'PASSWORD_RESET',
-                    userId: user.id,
-                    expiresAt: new Date(Date.now() + 60 * 60 * 1000),
-                },
-            });
-            const notificationService = await (0, notifications_with_queue_1.getNotificationServiceWithQueue)();
-            await notificationService.createNotification({
-                userId: user.id,
-                notificationType: 'EMAIL',
-                title: 'Password Reset',
-                contextName: 'forgotPassword',
-                contextParameters: { token: resetToken },
-                sendAfter: new Date(),
-                bodyTemplate: './src/email-templates/auth/forgot-password/forgot-password-body.html.pug',
-                subjectTemplate: './src/email-templates/auth/forgot-password/forgot-password-subject.txt.pug',
-                extraParams: {},
-            });
-        }
-        return server_1.NextResponse.json({ success: true, message: 'If an account exists, a password reset email has been sent' });
+  try {
+    const body = await req.json();
+    const { email } = auth_1.forgotPasswordSchema.parse(body);
+    const prisma = new client_1.PrismaClient();
+    const user = await prisma.user.findUnique({ where: { email } });
+    if (user) {
+      const resetToken = (0, auth_2.generateToken)({ userId: user.id }, '1h');
+      await prisma.token.create({
+        data: {
+          token: resetToken,
+          type: 'PASSWORD_RESET',
+          userId: user.id,
+          expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+        },
+      });
+      const notificationService = await (0,
+      notifications_with_queue_1.getNotificationServiceWithQueue)();
+      await notificationService.createNotification({
+        userId: user.id,
+        notificationType: 'EMAIL',
+        title: 'Password Reset',
+        contextName: 'forgotPassword',
+        contextParameters: { token: resetToken },
+        sendAfter: new Date(),
+        bodyTemplate: './src/email-templates/auth/forgot-password/forgot-password-body.html.pug',
+        subjectTemplate:
+          './src/email-templates/auth/forgot-password/forgot-password-subject.txt.pug',
+        extraParams: {},
+      });
     }
-    catch (error) {
-        if (error instanceof z.ZodError) {
-            const validationError = error;
-            return server_1.NextResponse.json({ success: false, error: 'Validation error', details: validationError.flatten() }, { status: 400 });
-        }
-        if (error instanceof library_1.PrismaClientKnownRequestError) {
-            return server_1.NextResponse.json({ success: false, error: 'Database error occurred' }, { status: 500 });
-        }
-        console.error('Password reset error:', error);
-        return server_1.NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 });
+    return server_1.NextResponse.json({
+      success: true,
+      message: 'If an account exists, a password reset email has been sent',
+    });
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const validationError = error;
+      return server_1.NextResponse.json(
+        { success: false, error: 'Validation error', details: validationError.flatten() },
+        { status: 400 },
+      );
+    }
+    if (error instanceof library_1.PrismaClientKnownRequestError) {
+      return server_1.NextResponse.json(
+        { success: false, error: 'Database error occurred' },
+        { status: 500 },
+      );
     }
+    console.error('Password reset error:', error);
+    return server_1.NextResponse.json(
+      { success: false, error: 'Internal server error' },
+      { status: 500 },
+    );
+  }
 }

package/dist/examples/nextjs-prisma-nodemailer-pug-temporal/src/app/api/auth/login/route.d.ts

@@ -1,12 +1,11 @@
-import { type LoginValues } from '../../../../lib/schemas/auth';
-import { NextResponse } from 'next/server';
+import type { NextResponse } from 'next/server';
+import type * as z from 'zod';
 import type { WriteApiResponse } from '../../../../lib/api-clients/core';
-import * as z from 'zod';
+import type { LoginValues } from '../../../../lib/schemas/auth';
 type LoginSuccess = {
-    token: string;
+  token: string;
 };
 type LoginValidationError = z.typeToFlattenedError<LoginValues>;
 export type LoginApiResponse = WriteApiResponse<LoginSuccess, LoginValidationError>;
 type LoginNextResponse = NextResponse<LoginApiResponse>;
 export declare function POST(req: Request): Promise<LoginNextResponse>;
-export {};