flowstate-mail Package Skill

Package: @epicdm/flowstate-mail Repository: epic-flowstate-community Path: packages/flowstate-mail Version: 1.0.7

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

FlowState Mail Adapter Selection

Purpose

Use this skill to choose and configure the right mail transport while preserving optional peer dependency behavior and consistent SendResult semantics.

Read First

• packages/flowstate-mail/src/adapters/interface.ts
• packages/flowstate-mail/src/adapters/console.ts
• packages/flowstate-mail/src/adapters/nodemailer.ts
• packages/flowstate-mail/src/adapters/sendgrid.ts
• packages/flowstate-mail/tests/console-adapter.test.ts
• packages/flowstate-mail/tests/nodemailer-adapter.test.ts
• packages/flowstate-mail/tests/sendgrid-adapter.test.ts

Adapter Choices

Use ConsoleAdapter for local development and tests that do not need external email delivery. It logs email content and returns every recipient as accepted.

Use NodemailerAdapter for SMTP, local mail servers, SES-style SMTP, or sendmail. It supports:

• SMTP config: host, port, optional secure, optional auth, optional tls.
• Sendmail config: sendmail: true, optional path, optional newline.

Use SendGridAdapter when production delivery should go through SendGrid. It requires apiKey and from.

Use a custom adapter when callers need another provider. Implement MailAdapter.send(message) and optional verify().

Optional Peer Rule

nodemailer and @sendgrid/mail are optional peer dependencies. Their adapters dynamically import the SDKs so callers who do not use that provider do not pay module-load cost or need the package installed.

Do not replace dynamic imports with top-level imports unless the package policy changes.

SendResult Semantics

• messageId is provider-specific and can be an empty string if the provider does not return one.
• accepted lists recipients accepted by the adapter/provider.
• rejected lists recipients rejected by the adapter/provider.
• Nodemailer can return partial rejections.
• SendGrid adapter currently treats a successful API send as all requested recipients accepted.

Verification Semantics

• ConsoleAdapter.verify() always returns true.
• NodemailerAdapter.verify() awaits initialization and returns false if transport verification throws.
• SendGridAdapter.verify() awaits initialization and returns true if the client is set.

Common Mistakes

• Do not assume verify() exists on every custom adapter; it is optional.
• Do not log or persist provider secrets in adapter setup errors.
• Do not pass undefined SMTP option keys when building Nodemailer config; the adapter intentionally omits absent auth, secure, and tls.
• Do not use ConsoleAdapter as evidence that real delivery occurred.

Verification

yarn workspace @epicdm/flowstate-mail test --runInBand tests/console-adapter.test.ts tests/nodemailer-adapter.test.ts tests/sendgrid-adapter.test.ts

Package Skill Inventory

@epicdm/flowstate-mail Skill Inventory

Skill Set

Design Notes

The package has only five inventory features, but the useful learning path is workflow-based. Agents need to understand how adapters and templates compose through MailService, how optional peer dependencies are preserved, and how the auth server uses the package in production.

Not Included

• No one-function skilllets for each class. Those do not help agents operate the package.
• No generated Dojo text reused directly. Existing Dojo content is generic and should be rebuilt from reviewed skills.
• No instructions to deep-import adapter files; consumers should use the package entrypoint.

Review Gate

@epicdm/flowstate-mail Skills Review

Verdict

Pass with tracked follow-ups.

The authored skills are source-backed and workflow-oriented. They cover the package's actual operational use: service facade, template rendering, adapter selection, auth-server verification email integration, and maintenance.

Coverage

• Mail service facade: covered from src/mail-service.ts.
• Template lifecycle: covered from src/template-engine.ts and template tests.
• Adapter behavior: covered from src/adapters/* and adapter tests.
• Auth-server integration: covered from packages/flowstate-auth-server/src/server.ts and src/routes/auth.routes.ts.
• Generated content drift: covered from existing README, feature inventory, and Dojo artifacts.

Verification Results

LC_ALL=C rg -n "[^\\x00-\\x7F]" packages/flowstate-mail/.flowstate/skills
rg -n "^name:|^description:" packages/flowstate-mail/.flowstate/skills
yarn workspace @epicdm/flowstate-mail test
yarn workspace @epicdm/flowstate-mail typecheck
yarn workspace @epicdm/flowstate-mail build
yarn workspace @epicdm/flowstate-mail lint
yarn nx build @epicdm/flowstate-mail

Results:

• ASCII scan passed with no non-ASCII matches.
• Frontmatter scan found name and description on all five skills.
• typecheck passed.
• build passed and emitted CJS, ESM, sourcemaps, and DTS outputs.
• test passed: 5 suites, 56 tests.
• lint passed with 55 existing warnings from Console logging/async methods, optional-peer any adapter usage, and test spy call typing.
• yarn nx build @epicdm/flowstate-mail passed. Nx Cloud reported the existing unconnected-workspace 401 warning.

Follow-Ups

• Update README placeholder usage with real MailService examples.
• Rebuild package-local Dojo artifacts from these reviewed workflow skills.
• Align auth-server test mocks with the real SendResult shape when touching that package.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-mail/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.