seamless-messaging is the public auth-messaging package family for SeamlessAuth.
It gives SeamlessAuth a small, explicit way to deliver auth emails and SMS without forcing adopters to rebuild OTP and magic-link flows themselves. SeamlessAuth owns the auth-message defaults; adopters choose transports, handlers, and optional overrides.
For 0.1.0, the scope is intentionally narrow:
- TypeScript packages only
- the four auth flows already used by SeamlessAuth
- AWS SES email
- AWS SNS SMS
- Twilio SMS
@seamless-auth/messaging@seamless-auth/messaging-aws@seamless-auth/messaging-twilio
SeamlessAuth needs to send exactly these auth-related messages today:
- email OTP
- SMS OTP
- magic link email
- bootstrap invite email
This repo packages that responsibility into:
- a provider-agnostic core service
- channel transports for
emailandsms - optional per-flow custom handlers
- optional message overrides
It is not a general notification platform or a marketing email system.
The intended consumer is a SeamlessAuth server adapter such as createSeamlessAuthServer(...).
At integration time, an adopter should be able to provide:
- official transports like SES, SNS, and Twilio
- or custom per-flow handlers if they already own delivery infrastructure
- plus optional overrides when they want to customize message content
The core service keeps the auth-domain API small:
sendOtpEmail(...)sendOtpSms(...)sendMagicLinkEmail(...)sendBootstrapInviteEmail(...)
npm install @seamless-auth/messaging
npm install @seamless-auth/messaging-aws
npm install @seamless-auth/messaging-twilioInstall only the provider packages you need.
import { createAuthMessagingService } from "@seamless-auth/messaging";
import { createAwsEmailTransport } from "@seamless-auth/messaging-aws";
import { createTwilioSmsTransport } from "@seamless-auth/messaging-twilio";
const authMessaging = createAuthMessagingService({
appName: "Seamless Review",
email: createAwsEmailTransport({
region: process.env.AWS_REGION!,
fromEmail: process.env.AUTH_EMAIL_FROM!,
}),
sms: createTwilioSmsTransport({
accountSid: process.env.TWILIO_ACCOUNT_SID!,
authToken: process.env.TWILIO_AUTH_TOKEN!,
fromNumber: process.env.TWILIO_FROM_NUMBER!,
}),
});
await authMessaging.sendOtpEmail({
to: "user@example.com",
token: "ABCDEF",
});
await authMessaging.sendOtpSms({
to: "+15551234567",
token: 123456,
});Twilio covers SMS, but not the email flows SeamlessAuth needs for launch.
So 0.1.0 is deliberately channel-based:
- AWS email + AWS SMS
- AWS email + Twilio SMS
- custom email handler + Twilio SMS
That keeps the core contract stable as future providers like SendGrid or Resend are added later.
This repo is no longer just a design sketch. It currently includes:
- the published core package
- published AWS email and SMS transports
- a published Twilio SMS transport
- default auth-message rendering
- handler and override support in the core service
- tests covering mixed-provider composition
This package family has also already been used to support a real SeamlessAuth integration path in the wider ecosystem.
This repo was shaped by reviewing and integrating against:
seamless-auth-api-internalseamless-auth-apiseamless-auth-server
That work pushed the design toward:
- small public packages
- explicit typed contracts
- thin provider adapters
- auth-focused defaults
- adopter-controlled transport choice
Use the workspace scripts at the repo root while iterating:
npm run lint
npm run format:check
npm run typecheck
npm testAuto-fix helpers:
npm run format
npm run lint:fixPublish manually after verification:
npm run release:verify
npm run publish:core
npm run publish:aws
npm run publish:twilioThe repo also includes GitHub Actions publish automation for GitHub Releases.
The release tag must match the package version, for example:
v0.1.00.1.0
Required GitHub secret:
NPM_TOKEN
Publish order:
@seamless-auth/messaging@seamless-auth/messaging-aws@seamless-auth/messaging-twilio