mirror of
https://github.com/profullstack/logicsrc.git
synced 2026-08-13 14:37:26 +00:00
Anthony Ettinger
e304eac761
@logicsrc/plugin-agentmail provides read/search/compose/send/flag/delete over an injected MailTransport, gated to Founding Lifetime (paid) members. Returns plain JSON-serializable domain objects so the same API serves a human TUI, the CLI, MCP, and bots. - domain.ts: transport-agnostic types + pure helpers (parse/format address, normalizeDraft, isValidEmail, snippet) - ports.ts: MailTransport seam - service.ts: AgentMailService (inbox/list/read/search/send/reply/flag/delete) - access.ts: paid-member gate (assertPaid) + capability constants - transports/memory.ts: complete in-memory backend (tests/dev/reference) - transports/mailu.ts: self-hosted Mailu seam (mail.profullstack.com IMAP + smtp.profullstack.com submission) with injected IMAP/SMTP drivers - index.ts: PluginDefinition (manifest, routes, capabilities, tuiPanels) - registered in the root build; 20 vitest tests pass Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
62 lines
2.6 KiB
Markdown
62 lines
2.6 KiB
Markdown
# @logicsrc/plugin-agentmail
|
|
|
|
Agent-native mail for LogicSRC: a paid-member mailbox client (read, search,
|
|
compose, send, flag, delete) that works the same for **humans** (a TUI) and
|
|
**bots/agents** (the CLI, MCP, or direct service calls), because every method
|
|
returns plain JSON-serializable domain objects.
|
|
|
|
## Design
|
|
|
|
The plugin follows the LogicSRC plugin pattern (cf. `agentgit`):
|
|
|
|
- **`domain.ts`** — transport-agnostic types (`Mailbox`, `MessageSummary`,
|
|
`Message`, `Draft`, `MailAddress`) and pure helpers (`parseAddress`,
|
|
`formatAddress`, `normalizeDraft`, `isValidEmail`, `snippet`).
|
|
- **`ports.ts`** — the `MailTransport` seam. The service talks only to this.
|
|
- **`service.ts`** — `AgentMailService`: paid-gated, ergonomic operations
|
|
(`inbox`, `list`, `read`, `search`, `send`, `reply`, `flag`, `delete`).
|
|
- **`access.ts`** — mail is a **Founding Lifetime Member** (paid) perk; every
|
|
call runs `assertPaid`.
|
|
- **`transports/memory.ts`** — `InMemoryMailTransport`: a complete, dependency
|
|
free backend for tests, local dev, and as the reference implementation.
|
|
- **`transports/mailu.ts`** — the self-hosted Mailu seam
|
|
(`mail.profullstack.com` IMAP + `smtp.profullstack.com` submission). It takes
|
|
**injected** IMAP/SMTP drivers so heavy network libraries stay out of the
|
|
plugin; a consuming app supplies the concrete drivers (e.g. `imapflow` +
|
|
`nodemailer` in Node, or the Go client on the BBS).
|
|
|
|
## Usage
|
|
|
|
```ts
|
|
import { AgentMailService, InMemoryMailTransport } from "@logicsrc/plugin-agentmail";
|
|
|
|
const transport = new InMemoryMailTransport();
|
|
const mail = new AgentMailService({
|
|
transport,
|
|
identity: { name: "alice", paid: true },
|
|
domain: "mail.profullstack.com"
|
|
});
|
|
|
|
await mail.send({ to: [{ address: "carol@example.com" }], subject: "Hi", text: "hello" });
|
|
const inbox = await mail.inbox();
|
|
```
|
|
|
|
Against the real stack:
|
|
|
|
```ts
|
|
import { AgentMailService, createMailuTransport, resolveMailuConfig } from "@logicsrc/plugin-agentmail";
|
|
|
|
const config = resolveMailuConfig({ user: "alice", pass: process.env.MAIL_PASS! });
|
|
const transport = createMailuTransport({ config, imap, smtp }); // imap/smtp: app-provided drivers
|
|
const mail = new AgentMailService({ transport, identity: { name: "alice", paid: true }, domain: config.domain });
|
|
```
|
|
|
|
## Config / env
|
|
|
|
| Var | Default | Meaning |
|
|
|---|---|---|
|
|
| `AGENTMAIL_DOMAIN` | `mail.profullstack.com` | member address domain |
|
|
| `AGENTMAIL_IMAP_HOST` | `mail.profullstack.com` | IMAP host |
|
|
| `AGENTMAIL_IMAP_PORT` | `993` | IMAPS port |
|
|
| `AGENTMAIL_SMTP_HOST` | `smtp.profullstack.com` | SMTP submission host |
|
|
| `AGENTMAIL_SMTP_PORT` | `587` | submission port (STARTTLS) |
|