smrt
Open the smrt source on GitHub Switch to dark color scheme
← All packages
Content & media v0.62.10

@happyvertical/smrt-messages

A unified STI hierarchy for email, social, and other communication channels, plus in-app notifications.

Source ↗

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.