@flink-app/sms-plugin 0.12.1-alpha.4 → 0.12.1-alpha.40

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@flink-app/sms-plugin",
-    "version": "0.12.1-alpha.4",
+    "version": "0.12.1-alpha.40",
     "description": "Flink plugin that makes it possible to send sms",
     "scripts": {
         "test": "echo \"Error: no test specified\"",
-        "prepublish": "tsc"
+        "prepare": "tsc"
     },
     "author": "johan@frost.se",
     "publishConfig": {
@@ -17,10 +17,10 @@
         "axios": "^0.27.2"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.4",
+        "@flink-app/flink": "^0.12.1-alpha.40",
         "@types/node": "22.13.10",
         "ts-node": "^9.1.1",
         "typescript": "5.4.5"
     },
-    "gitHead": "8f06a4ab98e7179322d36546756d4305fd196f5a"
+    "gitHead": "456502f273fe9473df05b71a803f3eda1a2f8931"
 }

package/readme.md

@@ -1,60 +1,400 @@
-# Flink API Docs
+# SMS Plugin
 
-A FLINK plugin that makes it possible to send sms
+A Flink plugin that provides SMS sending capabilities with support for 46elks and other SMS providers through a unified client interface.
 
-## Usage
+## Installation
 
-Install plugin to your flink app project:
+Install the plugin to your Flink app project:
 
-```
-npm i -S @flink-app/sms-plugin
+```bash
+npm install @flink-app/sms-plugin
 ```
 
-## Setup
+## Configuration
 
-### With 46 elks
+### Using 46elks
 
-Add and configure plugin in your app startup (probable the `index.ts` in root project):
+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<AppContext>({
     name: "My app",
     plugins: [
-        // Register plugin
-        smsPlugin({
-          client: new sms46elksClient({
-            username: "XX",
-            password: "YY",
-          }),
-        }),
+      smsPlugin({
+        client: new sms46elksClient({
+          username: process.env.SMS_46ELKS_USERNAME!,
+          password: process.env.SMS_46ELKS_PASSWORD!
+        })
+      })
     ],
   }).start();
 }
-
 ```
 
-Add plugin ctx to `Ctx.ts` in root project
+**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<smsPluginContext> {
+  // Your other context properties
+}
+```
+
+**Plugin Context Interface:**
 
+```typescript
+interface smsPluginContext {
+  smsPlugin: {
+    client: client;  // Unified SMS client interface
+  };
 }
+```
+
+## Usage in Handlers
+
+### Basic SMS
 
+Send a simple SMS message:
+
+```typescript
+import { Handler } from "@flink-app/flink";
+import { Ctx } from "../Ctx";
+
+const SendVerificationCode: Handler<Ctx, any, any> = 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;
 ```
-## Send sms
-Send email from your handlers by using the the context
+
+### SMS to Multiple Recipients
+
+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."
+});
 ```
 
- await ctx.plugins.smsPlugin.client.send({
-    to : ["+4612345678"],
-    from : "Sender",
-    message : "Hello world"
-    
-  })
+### SMS with Dynamic Content
+
+```typescript
+const SendOrderConfirmation: Handler<Ctx, OrderRequest, any> = 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
+
+### SMS Type
+
+```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)
+}
+```
+
+### Client Interface
+
+All SMS clients implement this unified interface:
+
+```typescript
+interface client {
+  send(sms: sms): Promise<boolean>;
+}
+```
+
+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<Ctx, SendSMSRequest, SendSMSResponse> = 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
+
+### Phone Number Formatting
+
+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
+```
+
+### Sender ID
+
+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)
+```
+
+### Message Length
+
+- Single SMS: Up to 160 characters
+- Longer messages will be automatically split into multiple SMS
+- Special characters (emojis, etc.) may reduce the character limit
+
+### Rate Limiting
+
+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
+
+### 46elks Provider
+
+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<boolean> {
+    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
+
+### Messages Not Sending
+
+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
+
+### Failed Delivery
+
+- 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
+
+### Character Encoding
+
+- The plugin sends messages in UTF-8 encoding
+- Special characters and emojis may count as multiple characters
+- Some providers may have different encoding rules