@flink-app/email-plugin 0.12.1-alpha.4 → 0.12.1-alpha.44

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@flink-app/email-plugin",
-    "version": "0.12.1-alpha.4",
+    "version": "0.12.1-alpha.44",
     "description": "Flink plugin that makes it possible to send email",
     "scripts": {
         "test": "echo \"Error: no test specified\"",
-        "prepublish": "tsc"
+        "prepare": "tsc"
     },
     "author": "johan@frost.se",
     "publishConfig": {
@@ -21,10 +21,10 @@
         "querystring": "^0.2.1"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.4",
+        "@flink-app/flink": "^0.12.1-alpha.44",
         "@types/node": "22.13.10",
         "ts-node": "^9.1.1",
         "typescript": "5.4.5"
     },
-    "gitHead": "8f06a4ab98e7179322d36546756d4305fd196f5a"
+    "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113"
 }

package/readme.md

@@ -1,103 +1,410 @@
-# Flink API Docs
+# Email Plugin
 
-A FLINK plugin that makes it possible to send email.
+A Flink plugin that provides multi-provider email sending capabilities with support for SendGrid, SMTP, and Flowmailer.
 
-## Usage
+## Installation
 
-Install plugin to your flink app project:
+Install the plugin to your Flink app project:
 
-```
-npm i -S @flink-app/email-plugin
+```bash
+npm install @flink-app/email-plugin
 ```
 
-## Setup
+## Configuration
 
-### With Sendgrid
+The email plugin supports three different email providers through a unified client interface:
 
-Add and configure plugin in your app startup (probable the `index.ts` in root project):
+### Option 1: SendGrid
 
-```
+Configure the plugin with SendGrid for API-based email sending:
+
+```typescript
+import { FlinkApp, FlinkContext } from "@flink-app/flink";
 import { emailPlugin, sendgridClient } from "@flink-app/email-plugin";
 
 function start() {
   new FlinkApp<AppContext>({
     name: "My app",
     plugins: [
-        // Register plugin
-        emailPlugin({
-          client : new sendgridClient({
-            apiKey : process.env.SENDGRID_API_KEY
-          })
+      emailPlugin({
+        client: new sendgridClient({
+          apiKey: process.env.SENDGRID_API_KEY!
         })
+      })
     ],
   }).start();
 }
-
 ```
 
-Add plugin ctx to `Ctx.ts` in root project
+**SendGrid Client Options:**
 
+```typescript
+interface sendgridClientOptions {
+  apiKey: string;  // Your SendGrid API key
+}
 ```
-import { emailPluginContext } from "@flink-app/email-plugin";
 
-export interface Ctx extends FlinkContext<emailPluginContext> {
+### Option 2: SMTP
+
+Configure the plugin with any SMTP server:
 
+```typescript
+import { emailPlugin, smtpClient } from "@flink-app/email-plugin";
+
+function start() {
+  new FlinkApp<AppContext>({
+    name: "My app",
+    plugins: [
+      emailPlugin({
+        client: new smtpClient({
+          host: "smtp.example.com",
+          port: 587,
+          secure: false,
+          auth: {
+            user: "username",
+            pass: "password"
+          }
+        })
+      })
+    ],
+  }).start();
 }
+```
+
+**SMTP Client Options:**
 
+```typescript
+interface smtpClientOptions {
+  host: string;        // SMTP server hostname
+  port: number;        // SMTP server port (usually 587 or 465)
+  secure: boolean;     // true for port 465, false for other ports
+  auth?: {
+    user: string;      // SMTP username
+    pass: string;      // SMTP password
+  };
+}
 ```
 
-### With SMTP
+### Option 3: Flowmailer
 
-Add and configure plugin in your app startup (probable the `index.ts` in root project):
+Configure the plugin with Flowmailer:
 
-```
-import { emailPlugin, smtpClient } from "@flink-app/email-plugin";
+```typescript
+import { emailPlugin, flowMailerClient } from "@flink-app/email-plugin";
 
 function start() {
   new FlinkApp<AppContext>({
     name: "My app",
     plugins: [
-        // Register plugin
-        emailPlugin({
-          client : new smtpClient({
-            host: "XYZ",
-            port: 587,
-            secure: false
-            auth: {
-              user: "user"
-              pass: "pass"
-            },
-          })
+      emailPlugin({
+        client: new flowMailerClient({
+          client_id: process.env.FLOWMAILER_CLIENT_ID!,
+          client_secrect: process.env.FLOWMAILER_CLIENT_SECRET!,
+          account_id: process.env.FLOWMAILER_ACCOUNT_ID!
         })
+      })
     ],
   }).start();
 }
-
 ```
 
-Add plugin ctx to `Ctx.ts` in root project
+**Flowmailer Client Options:**
 
+```typescript
+interface flowmailerClientOptions {
+  client_id: string;       // Flowmailer OAuth client ID
+  client_secrect: string;  // Flowmailer OAuth client secret
+  account_id: string;      // Flowmailer account ID
+}
 ```
+
+## TypeScript Setup
+
+Add the plugin context to your app's context type (usually in `Ctx.ts`):
+
+```typescript
+import { FlinkContext } from "@flink-app/flink";
 import { emailPluginContext } from "@flink-app/email-plugin";
 
 export interface Ctx extends FlinkContext<emailPluginContext> {
+  // Your other context properties
+}
+```
+
+**Plugin Context Interface:**
+
+```typescript
+interface emailPluginContext {
+  emailPlugin: {
+    client: client;  // Unified email client interface
+  };
+}
+```
+
+## Usage in Handlers
+
+### Basic Email
+
+Send a simple text email:
+
+```typescript
+import { Handler } from "@flink-app/flink";
+import { Ctx } from "../Ctx";
+
+const SendWelcomeEmail: Handler<Ctx, any, any> = async ({ ctx, req }) => {
+  await ctx.plugins.emailPlugin.client.send({
+    from: "noreply@example.com",
+    to: ["user@example.com"],
+    subject: "Welcome!",
+    text: "Welcome to our service!"
+  });
+
+  return { data: { success: true } };
+};
+
+export default SendWelcomeEmail;
+```
+
+### HTML Email
+
+Send an HTML email:
 
+```typescript
+await ctx.plugins.emailPlugin.client.send({
+  from: "noreply@example.com",
+  to: ["user@example.com"],
+  subject: "Newsletter",
+  html: "<h1>Hello</h1><p>This is an HTML email</p>"
+});
+```
+
+### Email with Multiple Recipients
+
+```typescript
+await ctx.plugins.emailPlugin.client.send({
+  from: "noreply@example.com",
+  to: ["user1@example.com", "user2@example.com", "user3@example.com"],
+  subject: "Team Update",
+  text: "Important team announcement"
+});
+```
+
+### Email with BCC and Reply-To
+
+```typescript
+await ctx.plugins.emailPlugin.client.send({
+  from: "noreply@example.com",
+  to: ["user@example.com"],
+  replyTo: "support@example.com",
+  bcc: ["admin@example.com"],
+  subject: "Support Ticket",
+  html: "<p>Your support ticket has been received.</p>"
+});
+```
+
+### Email with Attachments
+
+```typescript
+await ctx.plugins.emailPlugin.client.send({
+  from: "noreply@example.com",
+  to: ["user@example.com"],
+  subject: "Invoice",
+  html: "<p>Please find your invoice attached.</p>",
+  attachments: [
+    {
+      filename: "invoice.pdf",
+      content: Buffer.from("..."), // File content as Buffer or string
+      contentType: "application/pdf"
+    },
+    {
+      filename: "logo.png",
+      path: "/path/to/logo.png"  // Or provide a file path
+    }
+  ]
+});
+```
+
+## API Reference
+
+### Email Type (Generic)
+
+The generic email type used by SMTP and basic implementations:
+
+```typescript
+type email = {
+  from: string;          // Sender email address
+  to: string[];          // Array of recipient email addresses
+  replyTo?: string;      // Optional reply-to address
+  bcc?: string[];        // Optional blind carbon copy recipients
+  subject: string;       // Email subject line
+  attachments?: Attachment[];  // Optional file attachments
+} & ({ text: string } | { html: string });  // Either text or html is required
+```
+
+### Attachment Type
+
+```typescript
+interface Attachment {
+  content?: string | Buffer | Readable;  // File content
+  filename?: string | false;             // Filename to display
+  path?: string | Url;                   // Path to file on disk
+  href?: string;                         // URL to fetch file from
+  httpHeaders?: string;                  // HTTP headers for href requests
+  contentType?: string;                  // MIME type
+  contentDisposition?: 'attachment' | 'inline';  // How to display
+  cid?: string;                          // Content ID for inline images
+  encoding?: string;                     // Encoding (e.g., 'base64')
+  headers?: { [key: string]: string | string[] };  // Custom headers
+  raw?: string | Buffer;                 // Raw MIME node content
 }
+```
+
+### SendGrid Email Type
+
+SendGrid-specific email format (similar to generic but with SendGrid-specific attachment structure):
 
+```typescript
+type emailSendgrid = {
+  from: string;
+  to: string[];
+  replyTo?: string;
+  bcc?: string[];
+  subject: string;
+  attachments?: {
+    content: string;      // Base64 encoded string
+    filename: string;
+    type?: string;
+    disposition?: string;
+  }[];
+} & ({ text: string } | { html: string });
 ```
 
-## Send email
+### Flowmailer Email Type
 
-Send email from your handlers by using the the context
+Flowmailer-specific email format:
 
+```typescript
+type emailFlowmailer = {
+  from: string;
+  to: string[];
+  replyTo?: string;
+  bcc?: string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  attachments?: {
+    content: string;      // Base64 encoded content
+    contentType: string;  // MIME type
+    filename: string;
+  }[];
+};
 ```
 
- await ctx.plugins.emailPlugin.client.send({
-    from : "from@xxx.com",
-    to : ["to@yyy.com"],
-    subject : "Hello world",
-    text : "Hello world",  //Eiter text or html must be specified
-    html : "Hello <b>world</b>"
-  })
+### Client Interface
 
+All email clients implement this unified interface:
+
+```typescript
+interface client {
+  send(email: email | emailSendgrid | emailFlowmailer): Promise<boolean>;
+}
 ```
+
+The `send` method returns:
+- `true` - Email sent successfully
+- `false` - Email sending failed (errors are logged to console)
+
+## Complete Example
+
+Here's a complete example of a handler that sends different types of emails:
+
+```typescript
+import { Handler } from "@flink-app/flink";
+import { Ctx } from "../Ctx";
+
+interface SendEmailRequest {
+  type: "welcome" | "invoice" | "notification";
+  recipientEmail: string;
+  userName: string;
+}
+
+const SendEmail: Handler<Ctx, SendEmailRequest, { success: boolean }> = async ({ ctx, req }) => {
+  const { type, recipientEmail, userName } = req.body;
+
+  try {
+    switch (type) {
+      case "welcome":
+        await ctx.plugins.emailPlugin.client.send({
+          from: "welcome@example.com",
+          to: [recipientEmail],
+          subject: `Welcome ${userName}!`,
+          html: `
+            <h1>Welcome to our platform, ${userName}!</h1>
+            <p>We're excited to have you on board.</p>
+          `
+        });
+        break;
+
+      case "invoice":
+        await ctx.plugins.emailPlugin.client.send({
+          from: "billing@example.com",
+          to: [recipientEmail],
+          replyTo: "support@example.com",
+          subject: "Your Invoice",
+          html: `<p>Dear ${userName}, your invoice is attached.</p>`,
+          attachments: [
+            {
+              filename: "invoice.pdf",
+              content: Buffer.from("..."),  // Your PDF content
+              contentType: "application/pdf"
+            }
+          ]
+        });
+        break;
+
+      case "notification":
+        await ctx.plugins.emailPlugin.client.send({
+          from: "notifications@example.com",
+          to: [recipientEmail],
+          subject: "New Notification",
+          text: `Hi ${userName}, you have a new notification.`
+        });
+        break;
+    }
+
+    return { data: { success: true } };
+  } catch (error) {
+    console.error("Failed to send email:", error);
+    return { data: { success: false } };
+  }
+};
+
+export default SendEmail;
+```
+
+## Error Handling
+
+All email clients handle errors internally and return `false` on failure. Errors are logged to the console with `JSON.stringify(ex)`. For production use, you may want to implement additional error logging or monitoring.
+
+```typescript
+const success = await ctx.plugins.emailPlugin.client.send({
+  from: "noreply@example.com",
+  to: ["user@example.com"],
+  subject: "Test",
+  text: "Test email"
+});
+
+if (!success) {
+  // Handle email sending failure
+  console.log("Failed to send email");
+}
+```
+
+## Notes
+
+- Either `text` or `html` must be provided (not both required, but at least one)
+- All clients return a boolean indicating success/failure
+- Flowmailer automatically handles OAuth token refresh
+- SendGrid attachments must be base64 encoded
+- SMTP client uses nodemailer internally
+- Multiple recipients are supported by all clients