medusajs-talksasa-sms-plugin 1.0.3

package/README.md

@@ -0,0 +1,121 @@
+# Medusajs Talksasa SMS plugin
+
+[![Medusa Plugin](https://img.shields.io/badge/Medusa-Plugin-violet.svg)](https://medusajs.com/)
+[![NPM Version](https://img.shields.io/npm/v/medusajs-talksasa-sms-plugin.svg)](https://www.npmjs.com/package/medusajs-talksasa-sms-plugin)
+
+A robust, production-ready SMS notification provider plugin for **MedusaJS v2**. 
+
+This plugin seamlessly integrates the [Talksasa API](https://talksasa.com/) into your Medusa store's Notification Module, allowing you to send transactional SMS messages (like order confirmations, shipping updates, and verification codes) to your customers globally.
+
+---
+
+## 🌟 Features
+
+- **Native Medusa v2 Support**: Built specifically for the Medusa v2 Notification Module architecture (`AbstractNotificationProviderService`).
+- **Cost Saving Guardrails**: Automatically skips sending (and bypasses API calls) if a customer's phone number is missing, preventing unnecessary API errors or costs.
+- **Omni-Channel Ready**: Designed to work flawlessly alongside Email and WhatsApp notification providers in your global subscribers.
+- **Simple Configuration**: Plugs directly into your `medusa-config.ts` without complex setup.
+
+## 📋 Prerequisites
+
+- [Medusa backend](https://docs.medusajs.com/) (version 2.0.0 or higher)
+- A [Talksasa](https://talksasa.com/) account with an active API Token and registered Sender ID.
+
+## 🚀 Installation
+
+Install the plugin using your preferred package manager in your Medusa backend project:
+
+```bash
+npm install medusajs-talksasa-sms-plugin
+# or
+yarn add medusajs-talksasa-sms-plugin
+```
+
+## ⚙️ Configuration
+
+### 1. Environment Variables
+
+Add your Talksasa API credentials to your Medusa backend's `.env` file. You can find these in your Talksasa developer dashboard. 
+
+*(Note: Ensure your API Token includes the ID prefix if provided, e.g., `3318|cjVm7zz...`)*
+
+```env
+TALKSASA_API_TOKEN=your_full_talksasa_api_token
+TALKSASA_SENDER_ID=your_registered_sender_id
+```
+
+### 2. Medusa Config
+
+Next, register the plugin in your `medusa-config.ts` file under the Notification Module:
+
+```typescript
+import { loadEnv, defineConfig } from '@medusajs/framework/utils'
+import { Modules } from "@medusajs/framework/utils"
+
+loadEnv(process.env.NODE_ENV || 'development', process.cwd())
+
+module.exports = defineConfig({
+  projectConfig: {
+    // ... your standard project config
+  },
+  modules: [
+    {
+      resolve: Modules.NOTIFICATION,
+      options: {
+        providers: [
+          // ... your other providers (e.g. Resend, SendGrid)
+          {
+            resolve: "medusajs-talksasa-sms-plugin",
+            id: "talksasa-sms",
+            options: {
+              channels: ["sms"],
+              apiToken: process.env.TALKSASA_API_TOKEN,
+              senderId: process.env.TALKSASA_SENDER_ID,
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+## 💻 Usage Example
+
+Once installed, the plugin listens for notification requests directed to the `"sms"` channel. 
+
+You can dispatch SMS notifications directly from your Medusa Workflows or Subscribers. The plugin will automatically extract the plain-text message from the `text` field in your `data` payload.
+
+### In a Subscriber
+
+```typescript
+import { SubscriberArgs } from "@medusajs/framework"
+import { Modules } from "@medusajs/framework/utils"
+import { INotificationModuleService } from "@medusajs/framework/types"
+
+export default async function orderPlacedHandler({
+  event,
+  container,
+}: SubscriberArgs<any>) {
+  const notificationModuleService: INotificationModuleService = container.resolve(Modules.NOTIFICATION)
+  
+  const customerPhoneNumber = "254700000000" // Fetch this from your order/customer data
+  
+  await notificationModuleService.createNotifications({
+    to: customerPhoneNumber,
+    channel: "sms",
+    template: "order-placed-sms", // Required by Medusa type definitions
+    data: {
+      text: `Great news! Your order #${event.data.id} has been placed successfully.`,
+    },
+  })
+}
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! If you find a bug or have a feature request, please open an issue on the repository.
+
+## 📄 License
+
+This project is licensed under the MIT License.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@medusajs/types").ModuleProviderExports;
+export default _default;

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const service_1 = __importDefault(require("./service"));
+const utils_1 = require("@medusajs/framework/utils");
+exports.default = (0, utils_1.ModuleProvider)(utils_1.Modules.NOTIFICATION, {
+    services: [service_1.default],
+});

package/dist/service.d.ts

@@ -0,0 +1,16 @@
+import { AbstractNotificationProviderService } from "@medusajs/framework/utils";
+import { ProviderSendNotificationDTO, ProviderSendNotificationResultsDTO } from "@medusajs/types";
+type InjectedDependencies = {};
+export type TalksasaSmsServiceOptions = {
+    apiToken: string;
+    senderId: string;
+};
+export declare class TalksasaSmsService extends AbstractNotificationProviderService {
+    static readonly identifier = "talksasa-sms";
+    private readonly apiToken;
+    private readonly senderId;
+    constructor(container: InjectedDependencies, options: TalksasaSmsServiceOptions);
+    static validateOptions(options: Record<any, any>): void | never;
+    send(notification: ProviderSendNotificationDTO): Promise<ProviderSendNotificationResultsDTO>;
+}
+export default TalksasaSmsService;

package/dist/service.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TalksasaSmsService = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+class TalksasaSmsService extends utils_1.AbstractNotificationProviderService {
+    static identifier = "talksasa-sms";
+    apiToken;
+    senderId;
+    constructor(container, options) {
+        super();
+        this.apiToken = options.apiToken;
+        this.senderId = options.senderId;
+    }
+    static validateOptions(options) {
+        if (!options.apiToken) {
+            throw new Error("apiToken is required for talksasa-sms notification provider");
+        }
+        if (!options.senderId) {
+            throw new Error("senderId is required for talksasa-sms notification provider");
+        }
+    }
+    async send(notification) {
+        const { to, content, template, data } = notification;
+        if (!to || to.trim() === "") {
+            return {
+                id: `talksasa-skipped-${Date.now()}`
+            };
+        }
+        // For SMS, we typically just use the content text directly.
+        const contentText = content?.text || data?.text || `Notification from template: ${template}`;
+        try {
+            const response = await fetch("https://bulksms.talksasa.com/api/v3/sms/send", {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${this.apiToken}`,
+                    "Content-Type": "application/json",
+                    "Accept": "application/json"
+                },
+                body: JSON.stringify({
+                    recipient: to,
+                    sender_id: this.senderId,
+                    type: "plain",
+                    message: contentText
+                })
+            });
+            const responseData = await response.json();
+            if (responseData.status === "error") {
+                throw new Error(responseData.message || "Unknown error from Talksasa API");
+            }
+            return {
+                // Talksasa returns a contact object in data, which might contain an id
+                // We can just return a generic success id or extract it if available
+                id: responseData.data?.uid || `talksasa-${Date.now()}`,
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to send SMS via Talksasa: ${error.message}`);
+        }
+    }
+}
+exports.TalksasaSmsService = TalksasaSmsService;
+exports.default = TalksasaSmsService;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "medusajs-talksasa-sms-plugin",
+  "version": "1.0.3",
+  "description": "Talksasa SMS Notification Provider for MedusaJS",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "medusa",
+    "medusa-plugin",
+    "medusa-notification",
+    "medusa-v2",
+    "talksasa",
+    "sms",
+    "notification",
+    "ecommerce"
+  ],
+  "author": "Medusa Community",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/urbandevicecare/medusa-plugin-talksasa-sms.git"
+  },
+  "bugs": {
+    "url": "https://github.com/urbandevicecare/medusa-plugin-talksasa-sms/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@medusajs/framework": "^2.0.0",
+    "@medusajs/types": "^2.0.0",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "@medusajs/framework": "^2.0.0"
+  }
+}