@happyvertical/smrt-messages
A unified STI hierarchy for email, social, and other communication channels, plus in-app notifications.
What it gives you
A unified STI hierarchy for email, social, and other communication channels, plus in-app notifications.
This package is one focused part of the smrt stack. Its decorated models participate in the same manifest, tenancy, persistence, and generated-interface conventions as the rest of the framework.
Channels and accounts are polymorphic
Message has Email, Tweet, and SlackMessage subtypes; Account has Email, Twitter, Slack, Zulip, and Telegram subtypes. Import a provider from smrt-messages/providers/email, slack, twitter, or all when needed. The root import remains free of provider SDK weight, and credentialSecretId points to write-only smrt-secrets storage.
Persona routes are wired by a trusted caller
MessagingEndpoint, PersonaMessageRoute, and PersonaMessagingService operate behind messages.send and messages.manage-routes. createPersonaMessagingTool fixes personaId in trusted wiring so an agent-provided argument cannot choose a different persona. EmailAccount.readIntakeMessage is the authorized seam for opt-in ingestion of full message bytes; it never advances sync checkpoints.
In-app notifications are a closed service
UserNotification stores one row per recipient with kind, title, body, link, severity, a source reference, and read and dismissed state. UserNotificationService is the only access path: notify and notifyMany deduplicate on the source reference, and listForUser, countUnread, markRead, dismiss, and markAllRead filter on the recipient. Generated REST, MCP, and CLI are off, because a tenant-scoped list would expose every member. Hosts expose their own routes with the signed-in user id.
A mail account can have an owner
Account.ownerUserId is null by default, and an account without an owner stays open to its tenant. The mail of an account is closed as soon as the account has an owner. configureMailAccess, called once at startup, takes the database options and an optional resolvePrincipal function. That function returns the acting MailPrincipal: an id, a tenant, a user, and optional scopes and accountIds ceilings. The owner holds every scope on the account without a grant. Tenant administrators and super-admins get no bypass; trusted server work such as sync runs inside runWithMailSystemAccess.
Four scopes, each a grant under a tenant permission
The scopes are read, triage, draft, and send. The read scope opens the emails, folders, and attachments of an owned account. Triage write-back needs read and triage together, and Message.send needs send. The package does not check draft itself; a host can check it with assertMailAccess. A grant is a smrt-users ResourceGrant row on one account, and the grantee also needs the matching tenant permission, such as messages.read. The tenant check and the scopes and accountIds ceilings of a principal apply to every account, including one without an owner.
Without configuration, owned mail stays closed
The read rule is a collection interceptor that the package registers when it loads, not a UI check. If configureMailAccess was never called or has no resolvePrincipal, the mail of every owned account is hidden from everyone, the owner included. The same result applies when no principal resolves or the principal belongs to another tenant. A raw query on a mail class throws MailAccessError while any account is closed to the principal. Account rows are not filtered. MessagingSettingsService.listAccounts returns the accounts a principal owns or holds a grant on, with the effective scopes.
Only the owner shares a mailbox
MailAccessService has grant, revoke, list, and setOwner. The tenant permission messages.manage-access is required, and the actor must also own the account. The one exception is a grantee whose own grant is delegable: that grantee can pass on a plain grant. An administrator therefore cannot read or take over a mailbox that another person owns. A user with messages.manage-credentials can set the first owner of an account that has none, to any active member of the tenant. seedMessagesRolePermissions gives the system roles their messages permissions.
Package UI
Components in this package
Import these public components directly. When the package also exports playground entries, the next tab renders its real components with package-owned example data.
Package previews
Try the working views
These previews are owned by the package and use its public components. Mock mode is intended for safe browsing; live mode appears only where the package supports it.
Generated interface
REST
The exact route set comes from each model's @smrt({ api }) policy
and the application manifest—not from a second controller definition.
GET /api/messages
GET /api/messages/:id
POST /api/messages
PATCH /api/messages/:idWhat stays consistent
- Tenant scope and operation permissions run before model access.
- OpenAPI and generated clients use the same manifest fields.
- Packages can expose read-only or custom action sets.
Generated interface
MCP
AI tools are generated from the methods you explicitly include. Their inputs are validated against the same model metadata used by REST and CLI.
messages_list({ where, limit, orderBy })
messages_get({ id })
messages_create({ data })
messages_update({ id, data })Agent-safe by construction
- Tool availability can be narrower than the HTTP API.
- Principal execution intersects RBAC, agent ceilings, and persona tools.
- Descriptions and schemas are emitted from source metadata.
Browser-native agent interface
WebMCP
The generated web definitions carry the same tool names, descriptions, and JSON Schema
inputs as MCP. smrt-web registers them with document.modelContext.
import { webMcpToolDefinitions } from '@happyvertical/smrt-virt-web';
import { registerWebMcpTools } from '@happyvertical/smrt-web';
// Omitting an exposure policy registers read-only tools only.
const dispose = registerWebMcpTools(webMcpToolDefinitions);The page keeps its security boundary
- Tools execute through generated REST fetchers as the signed-in page user.
- Authentication, tenant gates, permissions, and field policy stay server-side.
- Feature detection makes registration a safe no-op outside supported browsers.
Generated interface
CLI
The app CLI turns manifest resources into predictable operator commands while keeping package-specific actions close to their models.
smrt messages list --limit 25 --order-by created_at:desc
smrt messages get <id>
smrt messages create --from-file ./record.jsonMade for automation
- Machine-readable output and file-based input.
- The same include/exclude policy as other surfaces.
- Migration, introspection, dispatch, and knowledge commands stay in smrt-cli.