@flink-app/email-plugin 0.12.1-alpha.9 → 0.13.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @flink-app/email-plugin
+
+## 0.13.1
+
+### Patch Changes
+
+-   Fixed invalid types and improve typescript error message during schema compilation
+
+## 0.13.0
+
+### Minor Changes
+
+-   Migrate to pnpm and streamlines build process.

package/dist/flowmailerClient.js

@@ -20,8 +20,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");

package/dist/schemas/email.d.ts

@@ -1,7 +1,3 @@
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
 import { Readable } from "stream";
 import { Url } from "url";
 export type email = {

package/dist/sendgridClient.js

@@ -9,8 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");

package/dist/smtpClient.js

@@ -9,8 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");

package/package.json

@@ -1,30 +1,29 @@
 {
-    "name": "@flink-app/email-plugin",
-    "version": "0.12.1-alpha.9",
-    "description": "Flink plugin that makes it possible to send email",
-    "scripts": {
-        "test": "echo \"Error: no test specified\"",
-        "prepare": "tsc"
-    },
-    "author": "johan@frost.se",
-    "publishConfig": {
-        "access": "public"
-    },
-    "license": "MIT",
-    "types": "dist/index.d.ts",
-    "main": "dist/index.js",
-    "dependencies": {
-        "@sendgrid/mail": "^7.4.5",
-        "@types/nodemailer": "^6.4.4",
-        "axios": "^0.27.2",
-        "nodemailer": "^6.6.2",
-        "querystring": "^0.2.1"
-    },
-    "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.9",
-        "@types/node": "22.13.10",
-        "ts-node": "^9.1.1",
-        "typescript": "5.4.5"
-    },
-    "gitHead": "3007ad036607014176930446fde56203bde8d6f5"
-}
+  "name": "@flink-app/email-plugin",
+  "version": "0.13.1",
+  "description": "Flink plugin that makes it possible to send email",
+  "author": "johan@frost.se",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "types": "dist/index.d.ts",
+  "main": "dist/index.js",
+  "dependencies": {
+    "@sendgrid/mail": "^7.4.5",
+    "@types/nodemailer": "^6.4.4",
+    "axios": "^0.27.2",
+    "nodemailer": "^6.6.2",
+    "querystring": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.10",
+    "@flink-app/flink": "0.13.1"
+  },
+  "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
+  "scripts": {
+    "test": "echo \"Error: no test specified\"",
+    "build": "tsc",
+    "clean": "rimraf dist .flink"
+  }
+}

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

package/tsconfig.json

@@ -15,7 +15,7 @@
     "noEmit": false,
     "declaration": true,
     "experimentalDecorators": true,
-    "checkJs": true,
+    "checkJs": false,
     "outDir": "dist"
   },
   "include": ["./src/*"],