SMS Plugin

A Flink plugin that provides SMS sending capabilities with support for 46elks and other SMS providers through a unified client interface.

Installation

Install the plugin to your Flink app project:

``bash
npm install @flink-app/sms-plugin
`

Configuration

$3

Configure the plugin with 46elks (a Swedish SMS service provider):

`typescript
import { FlinkApp, FlinkContext } from "@flink-app/flink";
import { smsPlugin, sms46elksClient } from "@flink-app/sms-plugin";

function start() {
new FlinkApp({
name: "My app",
plugins: [
smsPlugin({
client: new sms46elksClient({
username: process.env.SMS_46ELKS_USERNAME!,
password: process.env.SMS_46ELKS_PASSWORD!
})
})
],
}).start();
}
`

46elks Client Options:

`typescript
interface sms46elksClientOptions {
username: string; // Your 46elks API username
password: string; // Your 46elks API password
}
`

TypeScript Setup

Add the plugin context to your app's context type (usually in Ctx.ts):

`typescript
import { FlinkContext } from "@flink-app/flink";
import { smsPluginContext } from "@flink-app/sms-plugin";

export interface Ctx extends FlinkContext {
// Your other context properties
}
`

Plugin Context Interface:

`typescript
interface smsPluginContext {
smsPlugin: {
client: client; // Unified SMS client interface
};
}
`

Usage in Handlers

$3

Send a simple SMS message:

`typescript
import { Handler } from "@flink-app/flink";
import { Ctx } from "../Ctx";

const SendVerificationCode: Handler = async ({ ctx, req }) => {
await ctx.plugins.smsPlugin.client.send({
from: "MyApp",
to: ["+46701234567"],
message: "Your verification code is: 123456"
});

return { data: { success: true } };
};

export default SendVerificationCode;
`

$3

Send the same message to multiple phone numbers:

`typescript
await ctx.plugins.smsPlugin.client.send({
from: "MyCompany",
to: ["+46701234567", "+46709876543", "+46708765432"],
message: "Important notification: Service maintenance tonight at 10 PM."
});
`

$3

`typescript
const SendOrderConfirmation: Handler = async ({ ctx, req }) => {
const { phoneNumber, orderNumber, totalAmount } = req.body;

await ctx.plugins.smsPlugin.client.send({
from: "Shop",
to: [phoneNumber],
message: Order ${orderNumber} confirmed! Total: ${totalAmount} SEK. Thank you for your purchase!
});

return { data: { sent: true } };
};
`

API Reference

$3

`typescript
interface sms {
from: string; // Sender name or phone number (max 11 alphanumeric characters or a valid phone number)
to: string[]; // Array of recipient phone numbers (E.164 format recommended, e.g., "+46701234567")
message: string; // SMS message content (max 160 characters for single SMS, longer messages will be split)
}
`

$3

All SMS clients implement this unified interface:

`typescript
interface client {
send(sms: sms): Promise;
}
`

The send method returns:
- true - SMS sent successfully to all recipients
- false - SMS sending failed (errors are logged to console)

Complete Example

Here's a complete example of an SMS handler with error handling:

`typescript
import { Handler } from "@flink-app/flink";
import { Ctx } from "../Ctx";

interface SendSMSRequest {
phoneNumber: string;
messageType: "verification" | "notification" | "alert";
data?: {
code?: string;
message?: string;
};
}

interface SendSMSResponse {
success: boolean;
error?: string;
}

const SendSMS: Handler = async ({ ctx, req }) => {
const { phoneNumber, messageType, data } = req.body;

// Validate phone number format
if (!phoneNumber.startsWith("+")) {
return {
data: {
success: false,
error: "Phone number must be in E.164 format (e.g., +46701234567)"
}
};
}

let message: string;

// Generate message based on type
switch (messageType) {
case "verification":
message = Your verification code is: ${data?.code || "000000"};
break;
case "notification":
message = data?.message || "You have a new notification";
break;
case "alert":
message = ALERT: ${data?.message || "Important system notification"};
break;
default:
return {
data: {
success: false,
error: "Invalid message type"
}
};
}

try {
const success = await ctx.plugins.smsPlugin.client.send({
from: "MyApp",
to: [phoneNumber],
message
});

return {
data: {
success,
error: success ? undefined : "Failed to send SMS"
}
};
} catch (error) {
console.error("SMS sending error:", error);
return {
data: {
success: false,
error: "An error occurred while sending SMS"
}
};
}
};

export default SendSMS;
`

Error Handling

The SMS client handles errors internally and returns false on failure. Errors are logged to the console with JSON.stringify(ex). For production use, you should implement additional error handling and monitoring:

`typescript
const success = await ctx.plugins.smsPlugin.client.send({
from: "MyApp",
to: ["+46701234567"],
message: "Test message"
});

if (!success) {
// Handle SMS sending failure
console.log("Failed to send SMS - check logs for details");
// You might want to:
// - Log to an error tracking service
// - Retry with exponential backoff
// - Alert administrators
// - Store for later retry
}
`

Best Practices

$3

Always use E.164 format for phone numbers:
- Include the country code (e.g., +46 for Sweden)
- Remove spaces, dashes, and parentheses
- Example: +46701234567 (not 070-123 45 67)

`typescript
// Good
to: ["+46701234567"]

// Bad
to: ["070-123 45 67"] // Missing country code and has formatting
`

$3

The from field can be either:
- Alphanumeric: Up to 11 characters (e.g., "MyCompany")
- Numeric: A valid phone number in E.164 format

`typescript
// Good
from: "MyApp" // Short, memorable, alphanumeric
from: "+46701234567" // Valid phone number

// Avoid
from: "MyVeryLongCompanyName" // Too long (>11 chars)
`

$3

- Single SMS: Up to 160 characters
- Longer messages will be automatically split into multiple SMS
- Special characters (emojis, etc.) may reduce the character limit

$3

Consider implementing rate limiting to avoid:
- API throttling
- Excessive costs
- Spam complaints

`typescript
// Example: Track SMS sending per user
const recentSMS = await ctx.repos.smsLogRepo.findByUser(userId);
if (recentSMS.length >= 5) {
return { data: { success: false, error: "Too many SMS sent. Please try again later." } };
}
`

Multiple Recipients

The plugin sends SMS to each recipient individually. Keep in mind:
- Each recipient counts as a separate SMS (costs apply per message)
- Messages are sent sequentially to each number
- Failure for one recipient doesn't stop delivery to others

`typescript
const result = await ctx.plugins.smsPlugin.client.send({
from: "MyApp",
to: ["+46701111111", "+46702222222", "+46703333333"], // 3 separate SMS
message: "Meeting reminder: Tomorrow at 2 PM"
});
// Returns true only if ALL messages were sent successfully
`

Implementation Details

$3

The 46elks client:
- Uses Basic Authentication with username/password
- Sends to the 46elks API endpoint: https://api.46elks.com/a1/sms
- Processes each recipient individually in a loop
- Returns false if any recipient fails

Custom SMS Provider

You can implement your own SMS client by implementing the client interface:

`typescript
import { client } from "@flink-app/sms-plugin";
import { sms } from "@flink-app/sms-plugin";

export class customSMSClient implements client {
private apiKey: string;

constructor(options: { apiKey: string }) {
this.apiKey = options.apiKey;
}

async send(sms: sms): Promise {
try {
// Your custom SMS sending logic here
for (const recipient of sms.to) {
// Send to your provider's API
await yourSMSAPI.send({
from: sms.from,
to: recipient,
text: sms.message
});
}
return true;
} catch (error) {
console.log(JSON.stringify(error));
return false;
}
}
}
`

Then use it with the plugin:

`typescript
import { smsPlugin } from "@flink-app/sms-plugin";
import { customSMSClient } from "./customSMSClient";

smsPlugin({
client: new customSMSClient({
apiKey: process.env.CUSTOM_SMS_API_KEY!
})
})
`

Troubleshooting

$3

1. Check your API credentials are correct
2. Verify phone numbers are in E.164 format
3. Check the console logs for error details
4. Ensure you have sufficient account balance with your SMS provider
5. Verify the sender ID meets provider requirements

$3

- The plugin returns false` if sending fails
- Check provider-specific error codes in console logs
- Some providers may delay delivery - check your provider's dashboard

$3

- The plugin sends messages in UTF-8 encoding
- Special characters and emojis may count as multiple characters
- Some providers may have different encoding rules