feat: add smtp action

[nicosammito]

Summary

Adds an SMTP action so Hercules flows can send transactional and notification emails (with attachments) through any SMTP server. Implements issue #20, mirroring the existing actions' conventions — specifically the function-only shape of the gls-action and the official-SDK + helpers.ts pattern of the twilio-action.

SDK / schema source (rule 1)

Uses nodemailer ^6.9, the de-facto standard SMTP client for Node.js, for all mail logic (transport creation, sendMail, attachment handling) rather than hand-rolling SMTP. The SMTP_SEND_RESULT data type is modeled directly on nodemailer's SentMessageInfo, and SMTP_ATTACHMENT on nodemailer's attachment object. Every value returned to a flow is validated with zod .parse() before being handed back.

Functions (3)

• sendEmail(To, Subject, Text, Html?, From?, Cc?, Bcc?, ReplyTo?): SMTP_SEND_RESULT
• sendEmailWithAttachments(To, Subject, Text, Attachments, Html?, From?, Cc?, Bcc?): SMTP_SEND_RESULT
• createAttachment(Filename, Content, ContentType?, Encoding?): SMTP_ATTACHMENT — util builder (mirrors GLS create* utils)

To/Cc/Bcc accept comma-separated address lists. Errors are wrapped in RuntimeError with stable codes (MISSING_SMTP_HOST, INVALID_SMTP_PORT, MISSING_SMTP_SENDER, ERROR_SENDING_EMAIL).

Data types (3)

SMTP_SEND_RESULT, SMTP_ENVELOPE, SMTP_ATTACHMENT — one zod schema per file with @Identifier/@Name/@Schema decorators.

Triggers

None. SMTP is a send-only protocol, so — like gls-action — this action registers no events. (Inbound mail would require IMAP/POP3 and is out of scope for this issue.)

Config

host (required), port (default 587), secure (default false), username, password, from_address — all TEXT ConfigurationDefinitions on the Action, following the GLS/Twilio pattern. No provider-specific ENV vars beyond the shared HERCULES_* are required.

Registration

• Added smtp-action to the .node-actions list in .gitlab-ci.yml.
• Added an SMTP row to the "Available Actions" table in the root README.md.
• Added a per-action README.md documenting config, functions, data types, and provider setup (Gmail app passwords, port/secure pairing, etc.).

Validation

Run in actions/smtp-action/:

• npm install — OK (188 packages)
• npm run typecheck — ✅ PASS (0 errors; typechecks against the real nodemailer / @types/nodemailer types)
• npm run build — ✅ PASS (dist/index.js, 19.91 kB)
• npm run test — ✅ PASS (4/4 vitest specs)

Notes / choices (autonomous run)

• @types/nodemailer was added to devDependencies (nodemailer ships no bundled types). This is a small, necessary deviation from the otherwise-identical devDependency set.
• package-lock.json is not included in this commit (too large to include via the automation). The CI test-node job runs npm ci, which requires it — please run npm install in actions/smtp-action/ and commit the lockfile before merge. The Dockerfile uses npm install, so the image build is unaffected.
• Files were pushed in two commits (source/config, then registration) rather than one, due to payload-size limits of the push tooling.

⚠️ AI-generated — needs human review before merging.

Closes #20

[github-actions]

GitLab Pipeline Action

General information

Link to pipeline: https://gitlab.com/code0-tech/development/centaurus/-/pipelines/2702802134

Status: Failed
Duration: 3 minutes

Job summaries

docs:preview

Documentation preview available at https://code0-tech.gitlab.io/-/development/telescopium/-/jobs/15516078817/artifacts/out/index.html