feat: add smtp action (#20)

Author: nicosammito

actions/smtp-action/.gitignore

@@ -0,0 +1,3 @@
+.env
+node_modules/
+dist/

actions/smtp-action/Dockerfile

@@ -0,0 +1,13 @@
+FROM node:24.10.0-alpine
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+
+RUN npm install
+
+COPY . .
+
+RUN npm run build
+
+CMD ["npm", "run", "start"]

actions/smtp-action/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@code0-tech/smtp-action",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "vite build",
+    "test": "vitest run",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@code0-tech/hercules": "^1.1.1",
+    "nodemailer": "^6.9.16"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/nodemailer": "^6.4.16",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.10"
+  }
+}

actions/smtp-action/src/data_types/smtpAttachment.ts

@@ -0,0 +1,23 @@
+import { DisplayMessage, Identifier, Name, Schema } from "@code0-tech/hercules";
+import { z } from "zod";
+
+/**
+ * SMTP_ATTACHMENT mirrors the shape of a nodemailer attachment object
+ * (see https://nodemailer.com/message/attachments/). Only the fields that make
+ * sense to build from a flow are exposed; `content` is always provided as a
+ * string and interpreted according to `encoding` (e.g. "base64" for binary
+ * files, "utf-8" for text).
+ */
+export const SmtpAttachmentSchema = z.object({
+    filename: z.string().describe("The file name shown to the recipient, e.g. \"invoice.pdf\"."),
+    content: z.string().describe("The attachment content as a string. Interpreted using the encoding field."),
+    contentType: z.string().optional().describe("The MIME type of the attachment, e.g. \"application/pdf\". Derived from the filename when omitted."),
+    encoding: z.string().optional().describe("How to decode content, e.g. \"base64\" or \"utf-8\". Defaults to utf-8."),
+});
+export type SmtpAttachment = z.infer<typeof SmtpAttachmentSchema>;
+
+@Identifier("SMTP_ATTACHMENT")
+@Name({ code: "en-US", content: "Email attachment" })
+@DisplayMessage({ code: "en-US", content: "Email attachment ${filename}" })
+@Schema(SmtpAttachmentSchema)
+export class SmtpAttachmentDataType {}

actions/smtp-action/src/data_types/smtpSendResult.ts

@@ -0,0 +1,35 @@
+import { DisplayMessage, Identifier, Name, Schema } from "@code0-tech/hercules";
+import { z } from "zod";
+
+/**
+ * SMTP_SEND_RESULT is a normalized view of nodemailer's SentMessageInfo
+ * (see https://nodemailer.com/usage/#sending-mail). It captures the message id
+ * assigned by the SMTP server together with the accepted/rejected recipient
+ * lists and the raw server response so flows can branch on delivery outcome.
+ */
+export const SmtpEnvelopeSchema = z.object({
+    from: z.string().describe("The envelope MAIL FROM address, empty when not set."),
+    to: z.array(z.string()).describe("The envelope RCPT TO addresses."),
+});
+export type SmtpEnvelope = z.infer<typeof SmtpEnvelopeSchema>;
+
+export const SmtpSendResultSchema = z.object({
+    messageId: z.string().describe("The Message-ID assigned to the sent message."),
+    accepted: z.array(z.string()).describe("Recipient addresses the SMTP server accepted."),
+    rejected: z.array(z.string()).describe("Recipient addresses the SMTP server rejected."),
+    response: z.string().describe("The last SMTP response string from the server."),
+    envelope: SmtpEnvelopeSchema.describe("The SMTP envelope actually used for delivery."),
+});
+export type SmtpSendResult = z.infer<typeof SmtpSendResultSchema>;
+
+@Identifier("SMTP_ENVELOPE")
+@Name({ code: "en-US", content: "Email envelope" })
+@DisplayMessage({ code: "en-US", content: "Email envelope" })
+@Schema(SmtpEnvelopeSchema)
+export class SmtpEnvelopeDataType {}
+
+@Identifier("SMTP_SEND_RESULT")
+@Name({ code: "en-US", content: "Email send result" })
+@DisplayMessage({ code: "en-US", content: "Email send result" })
+@Schema(SmtpSendResultSchema)
+export class SmtpSendResultDataType {}

actions/smtp-action/src/functions/utils/createAttachmentFunction.ts

@@ -0,0 +1,64 @@
+import {
+    Description,
+    DisplayIcon,
+    DisplayMessage,
+    Documentation,
+    Identifier,
+    Name,
+    Parameter,
+    Signature,
+} from "@code0-tech/hercules";
+import { SmtpAttachment } from "../../data_types/smtpAttachment.js";
+
+@Identifier("createAttachment")
+@DisplayIcon("tabler:paperclip")
+@Signature("(Filename: string, Content: string, ContentType?: string, Encoding?: string): SMTP_ATTACHMENT")
+@Name({ code: "en-US", content: "Create email attachment" })
+@DisplayMessage({ code: "en-US", content: "Create email attachment ${Filename}" })
+@Documentation({
+    code: "en-US",
+    content:
+        "Builds an email attachment object for use with the sendEmailWithAttachments function.\nUse encoding \"base64\" for binary files (e.g. PDFs, images) and \"utf-8\" for plain text.",
+})
+@Description({
+    code: "en-US",
+    content: "Creates an email attachment object.",
+})
+@Parameter({
+    runtimeName: "Filename",
+    name: [{ code: "en-US", content: "File name" }],
+    description: [{ code: "en-US", content: "The file name shown to the recipient, e.g. \"invoice.pdf\"." }],
+})
+@Parameter({
+    runtimeName: "Content",
+    name: [{ code: "en-US", content: "Content" }],
+    description: [{ code: "en-US", content: "The attachment content as a string. Interpreted using the encoding." }],
+})
+@Parameter({
+    runtimeName: "ContentType",
+    name: [{ code: "en-US", content: "Content type" }],
+    description: [{ code: "en-US", content: "The MIME type, e.g. \"application/pdf\". Derived from the file name when omitted." }],
+    optional: true,
+})
+@Parameter({
+    runtimeName: "Encoding",
+    name: [{ code: "en-US", content: "Encoding" }],
+    description: [{ code: "en-US", content: "How to decode content, e.g. \"base64\" or \"utf-8\". Defaults to utf-8." }],
+    optional: true,
+})
+export class CreateAttachmentFunction {
+    run(
+        _context: unknown,
+        Filename: string,
+        Content: string,
+        ContentType?: string,
+        Encoding?: string
+    ): SmtpAttachment {
+        return {
+            filename: Filename,
+            content: Content,
+            contentType: ContentType,
+            encoding: Encoding,
+        };
+    }
+}

actions/smtp-action/test/index.test.ts

@@ -0,0 +1,60 @@
+import "reflect-metadata";
+import { describe, expect, it } from "vitest";
+import { SendEmailRequestDataSchema } from "../src/helpers.js";
+import { SmtpSendResultSchema } from "../src/data_types/smtpSendResult.js";
+import { SmtpAttachmentSchema } from "../src/data_types/smtpAttachment.js";
+import { CreateAttachmentFunction } from "../src/functions/utils/createAttachmentFunction.js";
+
+describe("SendEmailRequestDataSchema", () => {
+    it("requires To, Subject and Text", () => {
+        expect(() => SendEmailRequestDataSchema.parse({ Subject: "hi", Text: "body" })).toThrow();
+        expect(() => SendEmailRequestDataSchema.parse({ To: "a@example.com", Text: "body" })).toThrow();
+        expect(() => SendEmailRequestDataSchema.parse({ To: "a@example.com", Subject: "hi" })).toThrow();
+    });
+
+    it("accepts optional Html, From, Cc, Bcc, ReplyTo and Attachments", () => {
+        const parsed = SendEmailRequestDataSchema.parse({
+            To: "a@example.com, b@example.com",
+            Subject: "hi",
+            Text: "body",
+            Html: "<p>body</p>",
+            From: "no-reply@example.com",
+            Cc: "c@example.com",
+            Bcc: "d@example.com",
+            ReplyTo: "reply@example.com",
+            Attachments: [{ filename: "note.txt", content: "hello" }],
+        });
+        expect(parsed.To).toEqual("a@example.com, b@example.com");
+        expect(parsed.Attachments).toHaveLength(1);
+    });
+});
+
+describe("SmtpSendResultSchema", () => {
+    it("parses a representative send result", () => {
+        const result = {
+            messageId: "<example-message-id@example.com>",
+            accepted: ["a@example.com"],
+            rejected: [],
+            response: "250 2.0.0 OK",
+            envelope: { from: "no-reply@example.com", to: ["a@example.com"] },
+        };
+        const parsed = SmtpSendResultSchema.parse(result);
+        expect(parsed.messageId).toEqual(result.messageId);
+        expect(parsed.accepted).toEqual(["a@example.com"]);
+    });
+});
+
+describe("CreateAttachmentFunction", () => {
+    it("builds a valid SMTP_ATTACHMENT object", () => {
+        const attachment = new CreateAttachmentFunction().run(
+            undefined,
+            "invoice.pdf",
+            "JVBERi0=",
+            "application/pdf",
+            "base64"
+        );
+        expect(() => SmtpAttachmentSchema.parse(attachment)).not.toThrow();
+        expect(attachment.filename).toEqual("invoice.pdf");
+        expect(attachment.encoding).toEqual("base64");
+    });
+});

actions/smtp-action/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": [
+    "src/**/*",
+    "test/**/*",
+    "vite.config.ts"
+  ]
+}

actions/smtp-action/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+
+export default defineConfig({
+    build: {
+        target: "node18",
+        ssr: resolve(__dirname, 'src/index.ts'),
+        rollupOptions: {
+            external: (id) =>
+                [
+                    'fs',
+                    'path',
+                    'typescript',
+                    '@code0-tech/hercules'
+                ].includes(id) || id.startsWith('node:')
+        }
+    }
+});