@airhornjs/azure 5.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jared Wray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+![Airhorn](https://airhorn.org/logo.svg "Airhorn")
+
+---
+
+[![tests](https://github.com/jaredwray/airhorn/actions/workflows/tests.yml/badge.svg)](https://github.com/jaredwray/airhorn/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/jaredwray/airhorn/branch/main/graph/badge.svg?token=4OJEEB67Q5)](https://codecov.io/gh/jaredwray/airhorn)
+[![license](https://img.shields.io/github/license/jaredwray/airhorn)](https://github.com/jaredwray/airhorn/blob/master/LICENSE)
+[![npm](https://img.shields.io/npm/dm/@airhorn/azure)](https://npmjs.com/package/@airhorn/azure)
+[![npm](https://img.shields.io/npm/v/@airhorn/azure)](https://npmjs.com/package/@airhorn/azure)
+
+# @airhorn/azure
+
+Azure Communication Services and Notification Hubs provider for Airhorn.
+
+## Installation
+
+```bash
+npm install airhorn @airhorn/azure
+```
+
+## Features
+
+- SMS sending via Azure Communication Services
+- Email sending via Azure Communication Services
+- Mobile push notifications to iOS and Android devices via Azure Notification Hubs
+- Automatic error handling and retry support
+- Integration with Airhorn's notification system
+- Support for multiple connection strings
+
+## Usage
+
+### SMS with Azure Communication Services
+
+```typescript
+import { Airhorn } from 'airhorn';
+import { AirhornAzure } from '@airhorn/azure';
+
+// Create Azure provider for SMS
+const azureProvider = new AirhornAzure({
+  connectionString: 'endpoint=https://your-service.communication.azure.com/;accesskey=your-key',
+});
+
+// Create Airhorn instance with Azure provider
+const airhorn = new Airhorn({
+  providers: [azureProvider],
+});
+
+const data = {
+  orderId: '12345',
+  customerName: 'John',
+};
+
+// Send SMS
+const template = {
+  from: '+1234567890', // Your sender phone number (must be provisioned in Azure)
+  content: 'Hello <%= customerName %>!, your order #<%= orderId %> has been shipped!',
+  type: AirhornSendType.SMS,
+};
+
+const result = await airhorn.send(
+  '+0987654321', // to
+  template,
+  data,
+  AirhornSendType.SMS
+);
+```
+
+### Email with Azure Communication Services
+
+```typescript
+import { Airhorn } from 'airhorn';
+import { AirhornAzure } from '@airhorn/azure';
+
+// Create Azure provider with email support
+const azureProvider = new AirhornAzure({
+  connectionString: 'endpoint=https://your-service.communication.azure.com/;accesskey=your-key',
+});
+
+// Create Airhorn instance
+const airhorn = new Airhorn({
+  providers: [azureProvider],
+});
+
+const data = {
+  orderId: '656565',
+  customerName: 'John',
+};
+
+// Send Email
+const template = {
+  from: 'DoNotReply@yourdomain.com', // Must be verified domain in Azure
+  subject: 'Order Confirmation: <%= orderId %>',
+  content: 'Hi <%= customerName %>, your order #<%= orderId %> has been confirmed!',
+};
+
+const result = await airhorn.send(
+  'recipient@example.com', // to
+  template,
+  data,
+  AirhornSendType.Email
+);
+```
+
+### Mobile Push Notifications with Azure Notification Hubs
+
+```typescript
+import { Airhorn } from 'airhorn';
+import { AirhornAzure } from '@airhorn/azure';
+
+const azureProvider = new AirhornAzure({
+  notificationHubConnectionString: 'Endpoint=sb://your-namespace.servicebus.windows.net/;SharedAccessKeyName=DefaultFullSharedAccessSignature;SharedAccessKey=your-key',
+  notificationHubName: 'your-hub-name',
+});
+
+const airhorn = new Airhorn({
+  providers: [azureProvider],
+});
+
+const data = {
+  orderId: '12345',
+  customerName: 'John',
+};
+
+// Send to iOS device via APNs
+const template = {
+  from: 'YourApp',
+  content: JSON.stringify({
+    aps: {
+      alert: {
+        title: 'New Order',
+        body: 'Hi <%= customerName %>You have a new order #<%= orderId %>',
+      },
+      badge: 1,
+      sound: 'default',
+    },
+    // Custom data
+    orderId: '12345',
+  }),
+};
+
+// Send using tag expression
+await airhorn.send(
+  'user:john-doe', // Tag expression
+  template,
+  data,
+  AirhornSendType.MobilePush,
+  {
+    platform: 'apple',
+    tags: 'user:john-doe && ios',
+  },
+);
+```
+
+### Custom Capabilities
+
+You can specify which services to enable using the `capabilities` option:
+
+```typescript
+// SMS only
+const smsProvider = new AirhornAzure({
+  connectionString: 'your-connection-string',
+  capabilities: [AirhornSendType.SMS],
+});
+
+// Email only
+const emailProvider = new AirhornAzure({
+  connectionString: 'your-connection-string',
+  capabilities: [AirhornSendType.Email],
+});
+
+// Mobile Push only
+const pushProvider = new AirhornAzure({
+  notificationHubConnectionString: 'your-hub-connection-string',
+  notificationHubName: 'your-hub-name',
+  capabilities: [AirhornSendType.MobilePush],
+});
+
+// All capabilities (explicit)
+const allProvider = new AirhornAzure({
+  connectionString: 'your-communication-services-connection-string',
+  notificationHubConnectionString: 'your-hub-connection-string',
+  notificationHubName: 'your-hub-name',
+  capabilities: [AirhornSendType.SMS, AirhornSendType.Email, AirhornSendType.MobilePush],
+});
+```
+
+## Configuration
+
+### AirhornAzureOptions
+
+- `connectionString` (optional): Azure Communication Services connection string (used for both SMS and Email if specific strings not provided)
+- `emailConnectionString` (optional): Specific connection string for Email service
+- `smsConnectionString` (optional): Specific connection string for SMS service
+- `notificationHubConnectionString` (optional): Azure Notification Hub connection string
+- `notificationHubName` (optional): Azure Notification Hub name
+- `capabilities` (optional): Array of `AirhornSendType` values to specify which services to enable (defaults to SMS, MobilePush, and Email)
+
+## Additional Options
+
+### SMS Options
+
+```typescript
+await airhorn.send(to, message, {
+  // Additional SMS options from Azure Communication Services
+  deliveryReportTimeoutInSeconds: 300,
+  tag: 'custom-tag',
+});
+```
+
+## Prerequisites
+
+### Azure Communication Services
+
+1. Create an Azure Communication Services resource in Azure Portal
+2. Get your connection string from the resource
+3. For SMS: Provision a phone number through the Azure Portal
+4. For Email: Verify your sending domain
+
+### Azure Notification Hubs
+
+1. Create a Notification Hub namespace and hub in Azure Portal
+2. Configure platform credentials (APNs for iOS, FCM for Android)
+3. Get your connection string and hub name
+4. Implement device registration in your mobile apps
+
+## Azure RBAC Permissions
+
+Minimum required permissions for the service principal or managed identity:
+
+### For Communication Services:
+- `Azure Communication Services Contributor` role
+- Or specific permissions:
+  - `Microsoft.Communication/CommunicationServices/read`
+  - `Microsoft.Communication/CommunicationServices/write`
+
+### For Notification Hubs:
+- `Azure Notification Hubs Contributor` role
+- Or specific permissions:
+  - `Microsoft.NotificationHubs/Namespaces/NotificationHubs/read`
+  - `Microsoft.NotificationHubs/Namespaces/NotificationHubs/write`
+
+## Testing
+
+```bash
+pnpm test
+```
+
+# How to Contribute 
+
+Now that you've set up your workspace, you're ready to contribute changes to the `airhorn` repository you can refer to the [CONTRIBUTING](../../CONTRIBUTING.md) guide. If you have any questions please feel free to ask by creating an issue and label it `question`.
+
+# Licensing and Copyright
+
+This project is [MIT License © Jared Wray](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { AirhornSendType, AirhornProvider, AirhornProviderMessage, AirhornProviderSendResult } from 'airhorn';
+
+type AirhornAzureOptions = {
+    connectionString?: string;
+    emailConnectionString?: string;
+    smsConnectionString?: string;
+    notificationHubConnectionString?: string;
+    notificationHubName?: string;
+    capabilities?: AirhornSendType[];
+};
+declare class AirhornAzure implements AirhornProvider {
+    name: string;
+    capabilities: AirhornSendType[];
+    private emailClient?;
+    private smsClient?;
+    private notificationHubClient?;
+    constructor(options: AirhornAzureOptions);
+    send(message: AirhornProviderMessage, options?: any): Promise<AirhornProviderSendResult>;
+    private sendSMS;
+    private sendEmail;
+    private sendMobilePush;
+}
+
+export { AirhornAzure, type AirhornAzureOptions };

package/dist/index.js

@@ -0,0 +1,253 @@
+// src/index.ts
+import {
+  EmailClient
+} from "@azure/communication-email";
+import { SmsClient } from "@azure/communication-sms";
+import {
+  createAppleNotification,
+  createFcmLegacyNotification,
+  NotificationHubsClient
+} from "@azure/notification-hubs";
+import {
+  AirhornSendType
+} from "airhorn";
+var AirhornAzure = class {
+  name = "azure";
+  capabilities;
+  emailClient;
+  smsClient;
+  notificationHubClient;
+  constructor(options) {
+    this.capabilities = options.capabilities || [
+      AirhornSendType.SMS,
+      AirhornSendType.MobilePush,
+      AirhornSendType.Email
+    ];
+    if (this.capabilities.includes(AirhornSendType.Email)) {
+      const emailConnStr = options.emailConnectionString || options.connectionString;
+      if (emailConnStr) {
+        this.emailClient = new EmailClient(emailConnStr);
+      }
+    }
+    if (this.capabilities.includes(AirhornSendType.SMS)) {
+      const smsConnStr = options.smsConnectionString || options.connectionString;
+      if (smsConnStr) {
+        this.smsClient = new SmsClient(smsConnStr);
+      }
+    }
+    if (this.capabilities.includes(AirhornSendType.MobilePush)) {
+      if (options.notificationHubConnectionString && options.notificationHubName) {
+        this.notificationHubClient = new NotificationHubsClient(
+          options.notificationHubConnectionString,
+          options.notificationHubName
+        );
+      }
+    }
+  }
+  async send(message, options) {
+    const result = {
+      success: false,
+      response: null,
+      errors: []
+    };
+    try {
+      if (message.type === AirhornSendType.SMS) {
+        return this.sendSMS(message, options);
+      }
+      if (message.type === AirhornSendType.Email) {
+        return this.sendEmail(message, options);
+      }
+      if (message.type === AirhornSendType.MobilePush) {
+        return this.sendMobilePush(message, options);
+      }
+      throw new Error(
+        `AirhornAzure does not support message type: ${message.type}`
+      );
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      result.errors.push(err);
+      result.response = {
+        error: err.message,
+        details: error
+      };
+    }
+    return result;
+  }
+  async sendSMS(message, options) {
+    const result = {
+      success: false,
+      response: null,
+      errors: []
+    };
+    try {
+      if (!this.smsClient) {
+        throw new Error("SMS client is not configured");
+      }
+      if (!message.from) {
+        throw new Error("From phone number is required for SMS messages");
+      }
+      const sendResult = await this.smsClient.send({
+        from: message.from,
+        to: [message.to],
+        message: message.content,
+        ...options
+      });
+      const successfulMessages = sendResult.filter(
+        // biome-ignore lint/suspicious/noExplicitAny: Azure SDK type
+        (msg) => msg.successful
+      );
+      const failedMessages = sendResult.filter(
+        // biome-ignore lint/suspicious/noExplicitAny: Azure SDK type
+        (msg) => !msg.successful
+      );
+      if (failedMessages.length > 0) {
+        for (const failed of failedMessages) {
+          result.errors.push(
+            new Error(
+              `Failed to send SMS to ${failed.to}: ${failed.errorMessage}`
+            )
+          );
+        }
+      }
+      result.success = successfulMessages.length > 0;
+      result.response = {
+        successful: successfulMessages.length,
+        failed: failedMessages.length,
+        results: sendResult
+      };
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      result.errors.push(err);
+      result.response = {
+        error: err.message,
+        details: error
+      };
+    }
+    return result;
+  }
+  async sendEmail(message, options) {
+    const result = {
+      success: false,
+      response: null,
+      errors: []
+    };
+    try {
+      if (!this.emailClient) {
+        throw new Error("Email client is not configured");
+      }
+      if (!message.from) {
+        throw new Error("From email address is required for email messages");
+      }
+      const emailMessage = {
+        senderAddress: message.from,
+        recipients: {
+          to: [{ address: message.to }],
+          cc: options?.cc?.map((email) => ({ address: email })),
+          bcc: options?.bcc?.map((email) => ({ address: email }))
+        },
+        content: {
+          subject: message.subject || "Notification",
+          plainText: message.content,
+          html: options?.html || message.content
+        },
+        attachments: options?.attachments,
+        replyTo: options?.replyTo ? [{ address: options.replyTo }] : void 0,
+        headers: options?.headers
+      };
+      const poller = await this.emailClient.beginSend(emailMessage);
+      const sendResult = await poller.pollUntilDone();
+      result.success = sendResult.status === "Succeeded";
+      result.response = {
+        id: sendResult.id,
+        status: sendResult.status,
+        error: sendResult.error
+      };
+      if (sendResult.error) {
+        result.errors.push(
+          new Error(`Email send failed: ${sendResult.error.message}`)
+        );
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      result.errors.push(err);
+      result.response = {
+        error: err.message,
+        details: error
+      };
+    }
+    return result;
+  }
+  async sendMobilePush(message, options) {
+    const result = {
+      success: false,
+      response: null,
+      errors: []
+    };
+    try {
+      if (!this.notificationHubClient) {
+        throw new Error("Notification Hub client is not configured");
+      }
+      if (!message.from) {
+        throw new Error("From identifier is required for mobile push messages");
+      }
+      let notification;
+      const sendOptions = {
+        tagExpression: options?.tags
+      };
+      if (options?.platform === "apple" || message.to.includes("apple")) {
+        const apnsPayload = typeof message.content === "string" ? JSON.parse(message.content) : message.content;
+        notification = createAppleNotification({
+          body: JSON.stringify(apnsPayload),
+          headers: options?.apnsHeaders
+        });
+      } else if (options?.platform === "android" || message.to.includes("android") || message.to.includes("fcm")) {
+        const fcmPayload = typeof message.content === "string" ? JSON.parse(message.content) : message.content;
+        notification = createFcmLegacyNotification({
+          body: JSON.stringify(fcmPayload)
+        });
+      } else {
+        sendOptions.tagExpression = message.to;
+        const payload = typeof message.content === "string" ? JSON.parse(message.content) : message.content;
+        if (payload.aps) {
+          notification = createAppleNotification({
+            body: JSON.stringify(payload)
+          });
+        } else if (payload.notification || payload.data) {
+          notification = createFcmLegacyNotification({
+            body: JSON.stringify(payload)
+          });
+        } else {
+          throw new Error("Invalid notification payload structure");
+        }
+      }
+      const notificationResult = await this.notificationHubClient.sendNotification(
+        notification,
+        sendOptions
+      );
+      result.success = notificationResult.state === "Enqueued";
+      result.response = {
+        notificationId: notificationResult.notificationId,
+        state: notificationResult.state,
+        correlationId: notificationResult.correlationId
+      };
+      if (notificationResult.state !== "Enqueued") {
+        result.errors.push(
+          new Error(
+            `Notification failed with state: ${notificationResult.state}`
+          )
+        );
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      result.errors.push(err);
+      result.response = {
+        error: err.message,
+        details: error
+      };
+    }
+    return result;
+  }
+};
+export {
+  AirhornAzure
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@airhornjs/azure",
+  "version": "5.0.1",
+  "description": "Azure provider for Airhorn",
+  "license": "MIT",
+  "author": "Jared Wray <me@jaredwray.com>",
+  "homepage": "https://github.com/jaredwray/airhorn/tree/main/packages/azure#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@azure/communication-email": "^1.0.0",
+    "@azure/communication-sms": "^1.1.0",
+    "@azure/notification-hubs": "^2.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.2",
+    "@types/node": "^24.3.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "airhorn": "5.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jaredwray/airhorn.git",
+    "directory": "packages/azure"
+  },
+  "keywords": [
+    "airhorn",
+    "notifications",
+    "azure",
+    "communication-services",
+    "notification-hubs",
+    "sms",
+    "email",
+    "push",
+    "mobile"
+  ],
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint": "biome check --write --error-on-warnings",
+    "test": "pnpm lint && vitest run --coverage",
+    "test:ci": "biome check --error-on-warnings && vitest run --coverage",
+    "clean": "rimraf ./dist ./coverage ./node_modules ./package-lock.json ./pnpm-lock.yaml",
+    "build:publish": "pnpm build && pnpm publish --access public",
+    "build": "rimraf ./dist && tsup src/index.ts --format esm --dts --clean"
+  }
+}