@wraps.dev/sms SDK
TypeScript SDK for AWS End User Messaging (Pinpoint SMS) with opt-out management, batch sending, and E.164 validation. Calls your AWS account directly — no proxy, no markup.
Installation
bash
npm install @wraps.dev/sms
# or
pnpm add @wraps.dev/sms
Quick Start
typescript
import { WrapsSMS } from '@wraps.dev/sms';
const sms = new WrapsSMS();
const result = await sms.send({
to: '+14155551234',
message: 'Your verification code is 123456',
});
console.log('Sent:', result.messageId);
Client Configuration
Default (Auto-detect credentials)
typescript
// Uses AWS credential chain (env vars, IAM role, ~/.aws/credentials)
const sms = new WrapsSMS();
With Region
typescript
const sms = new WrapsSMS({
region: 'us-west-2', // defaults to us-east-1
});
With Explicit Credentials
typescript
const sms = new WrapsSMS({
region: 'us-east-1',
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
},
});
With IAM Role (OIDC / Cross-account)
typescript
// For Vercel, EKS, GitHub Actions with OIDC federation
const sms = new WrapsSMS({
region: 'us-east-1',
roleArn: 'arn:aws:iam::123456789012:role/WrapsSMSRole',
roleSessionName: 'my-app-session', // optional
});
With Credential Provider (Advanced)
typescript
import { fromWebToken } from '@aws-sdk/credential-providers';
const credentials = fromWebToken({
roleArn: process.env.AWS_ROLE_ARN!,
webIdentityToken: async () => process.env.VERCEL_OIDC_TOKEN!,
});
const sms = new WrapsSMS({
region: 'us-east-1',
credentials,
});
Sending SMS
Basic Send
typescript
const result = await sms.send({
to: '+14155551234', // E.164 format required
message: 'Hello from Wraps!',
});
console.log('Message ID:', result.messageId);
console.log('Segments:', result.segments);
console.log('Status:', result.status);
Transactional vs Promotional
typescript
// OTP, alerts, notifications (higher priority, opt-out not required)
await sms.send({
to: '+14155551234',
message: 'Your code is 123456',
messageType: 'TRANSACTIONAL', // default
});
// Marketing messages (requires opt-in, subject to quiet hours)
await sms.send({
to: '+14155551234',
message: 'Sale! 20% off today only!',
messageType: 'PROMOTIONAL',
});
With Custom Sender
typescript
// Use a specific origination number from your account
await sms.send({
to: '+14155551234',
message: 'Hello!',
from: '+18005551234', // Your registered number
});
With Tracking Context
typescript
await sms.send({
to: '+14155551234',
message: 'Your order has shipped!',
context: {
orderId: 'order_123',
userId: 'user_456',
type: 'shipping_notification',
},
});
With Price Limit
typescript
// Fail if message would cost more than specified amount
await sms.send({
to: '+14155551234',
message: 'Hello!',
maxPrice: '0.05', // USD per segment
});
With TTL (Time to Live)
typescript
// Message expires if not delivered within TTL
await sms.send({
to: '+14155551234',
message: 'Your OTP is 123456',
ttl: 300, // 5 minutes in seconds
});
Dry Run (Validate without sending)
typescript
const result = await sms.send({
to: '+14155551234',
message: 'Test message',
dryRun: true,
});
console.log('Would use', result.segments, 'segment(s)');
// No message is actually sent
Batch Sending
typescript
const result = await sms.sendBatch({
messages: [
{ to: '+14155551234', message: 'Hello Alice!' },
{ to: '+14155555678', message: 'Hello Bob!' },
{ to: '+14155559012', message: 'Hello Carol!' },
],
messageType: 'TRANSACTIONAL',
});
console.log(`Total: ${result.total}`);
console.log(`Queued: ${result.queued}`);
console.log(`Failed: ${result.failed}`);
// Check individual results
result.results.forEach((r) => {
if (r.status === 'QUEUED') {
console.log(`${r.to}: ${r.messageId}`);
} else {
console.log(`${r.to}: FAILED - ${r.error}`);
}
});
Phone Number Management
List Your Numbers
typescript
const numbers = await sms.numbers.list();
numbers.forEach((n) => {
console.log(`${n.phoneNumber} (${n.numberType})`);
console.log(` Message type: ${n.messageType}`);
console.log(` Two-way enabled: ${n.twoWayEnabled}`);
console.log(` Country: ${n.isoCountryCode}`);
});
Get Number Details
typescript
const number = await sms.numbers.get('phone-number-id-123');
if (number) {
console.log(`Phone: ${number.phoneNumber}`);
console.log(`Type: ${number.numberType}`);
}
Opt-Out Management
TCPA compliance requires honoring opt-out requests.
Check Opt-Out Status
typescript
const isOptedOut = await sms.optOuts.check('+14155551234');
if (isOptedOut) {
console.log('User has opted out, do not send');
} else {
await sms.send({
to: '+14155551234',
message: 'Hello!',
});
}
List Opted-Out Numbers
typescript
const optOuts = await sms.optOuts.list();
optOuts.forEach((entry) => {
console.log(`${entry.phoneNumber} opted out at ${entry.optedOutAt}`);
});
Manually Add to Opt-Out List
typescript
// User requested to stop receiving messages
await sms.optOuts.add('+14155551234');
Remove from Opt-Out List
typescript
// User re-subscribed (must have explicit consent)
await sms.optOuts.remove('+14155551234');
Error Handling
typescript
import { WrapsSMS, SMSError, ValidationError, OptedOutError } from '@wraps.dev/sms';
try {
await sms.send({
to: '+14155551234',
message: 'Hello!',
});
} catch (error) {
if (error instanceof ValidationError) {
// Invalid parameters (e.g., invalid phone number format)
console.error('Validation error:', error.message);
} else if (error instanceof OptedOutError) {
// Recipient has opted out
console.error('User opted out:', error.phoneNumber);
} else if (error instanceof SMSError) {
// AWS SMS service error
console.error('SMS error:', error.message);
console.error('Error code:', error.code);
console.error('Request ID:', error.requestId);
console.error('Is throttled:', error.isThrottled);
} else {
throw error;
}
}
Utility Functions
Validate Phone Number
typescript
import { validatePhoneNumber } from '@wraps.dev/sms';
const isValid = validatePhoneNumber('+14155551234'); // true
const isInvalid = validatePhoneNumber('415-555-1234'); // false (not E.164)
Sanitize Phone Number
typescript
import { sanitizePhoneNumber } from '@wraps.dev/sms';
const clean = sanitizePhoneNumber('(415) 555-1234', 'US');
// Returns: '+14155551234'
Calculate Segments
typescript
import { calculateSegments } from '@wraps.dev/sms';
// GSM-7 encoding: 160 chars = 1 segment
const segments1 = calculateSegments('Hello world!'); // 1
// Unicode: 70 chars = 1 segment
const segments2 = calculateSegments('Hello! emoji here'); // may be more due to encoding
// Long message
const longMsg = 'A'.repeat(200);
const segments3 = calculateSegments(longMsg); // 2 (for GSM-7)
Cleanup
typescript
// When done (e.g., in serverless cleanup or app shutdown)
sms.destroy();
Type Exports
typescript
import type {
WrapsSMSConfig,
SendOptions,
SendResult,
BatchOptions,
BatchResult,
BatchMessage,
BatchMessageResult,
PhoneNumber,
OptOutEntry,
MessageType,
MessageStatus,
} from '@wraps.dev/sms';
Common Patterns
OTP Service
typescript
import { WrapsSMS } from '@wraps.dev/sms';
class OTPService {
private sms: WrapsSMS;
constructor() {
this.sms = new WrapsSMS({
region: process.env.AWS_REGION,
});
}
async sendOTP(phoneNumber: string, code: string) {
return this.sms.send({
to: phoneNumber,
message: `Your verification code is ${code}. Valid for 10 minutes.`,
messageType: 'TRANSACTIONAL',
ttl: 600, // 10 minutes
context: {
type: 'otp',
},
});
}
}
Notification Service with Opt-Out Check
typescript
import { WrapsSMS, OptedOutError } from '@wraps.dev/sms';
class NotificationService {
private sms: WrapsSMS;
constructor() {
this.sms = new WrapsSMS();
}
async sendNotification(phoneNumber: string, message: string) {
// Check opt-out status first
const isOptedOut = await this.sms.optOuts.check(phoneNumber);
if (isOptedOut) {
console.log(`Skipping ${phoneNumber} - opted out`);
return null;
}
try {
return await this.sms.send({
to: phoneNumber,
message,
messageType: 'TRANSACTIONAL',
});
} catch (error) {
if (error instanceof OptedOutError) {
// Race condition: user opted out between check and send
console.log(`User ${phoneNumber} opted out`);
return null;
}
throw error;
}
}
}
Vercel Edge/Serverless
typescript
import { WrapsSMS } from '@wraps.dev/sms';
// Initialize outside handler for connection reuse
const sms = new WrapsSMS({
roleArn: process.env.AWS_ROLE_ARN,
});
export async function POST(request: Request) {
const { to, message } = await request.json();
const result = await sms.send({
to,
message,
messageType: 'TRANSACTIONAL',
});
return Response.json({ messageId: result.messageId });
}
Phone Number Formats
Always use E.164 format:
- US:
+14155551234 (not 415-555-1234) - UK:
+447911123456 (not 07911 123456) - Germany:
+4915112345678
SMS Segments
Messages are billed per segment:
- GSM-7 encoding (basic characters): 160 chars = 1 segment
- Unicode (emojis, non-Latin chars): 70 chars = 1 segment
- Long messages are split: 153 chars/segment (GSM-7) or 67 chars/segment (Unicode)
Requirements
- Node.js 18+
- AWS account with End User Messaging configured
- Phone number (toll-free, 10DLC, or short code) provisioned in AWS