npm package: @qrvey/sms
Description: ![install size](https://packagephobia.now.sh/badge?p=%40qrvey%2Fsms) ![coverage](https://img.shields.io/badge/unit_test_coverage-88%25-brightgreen)
Author: Qrvey
Latest version: 1.0.1-949

# @qrvey/sms

![install size](https://packagephobia.now.sh/badge?p=%40qrvey%2Fsms)
![coverage](https://img.shields.io/badge/unit_test_coverage-88%25-brightgreen)

**@qrvey/sms** is a lightweight and reliable library to send manage sms messages. It supports different clients such SNS (AWS), ACS (Azure), Twilio, and Vonage.

## Installation

You can install the **@qrvey/sms** package via npm. Run the following command in your terminal:

```bash
npm install @qrvey/sms
```

## Peer Dependencies

This package has the following peer dependencies:

- `@aws-sdk/client-sns` (v3.x) for interacting with **AWS SNS**.
- `@azure/communication-sms` (v1.x) for interacting with **Azure Communication Services**.
- `@vonage/server-sdk` (v3.x) and `@vonage/auth` (v1.x) for interacting with **Vonage**.
- `twilio` (v5.x) for interacting with **Twilio**.

## Configuration

To work properly, the package need some env variables. To set the sms provider, you must set the `SMS_PROVIDER` env variable with one of these values:
- `AWS`
- `AZURE`
- `TWILIO`
- `VONAGE`

In case the `SMS_PROVIDER` env variable is set with an unknown value, you will get a `UnknownProvider` error. Depending on the provider you must set some variables:

### AWS
If you set `SMS_PROVIDER = AWS`, the following env variables are required:
- `SMS_PROVIDER_USERNAME` which is `AWS_ACCESS_KEY_ID` in aws context.
- `SMS_PROVIDER_PASSWORD` which is `AWS_SECRET_ACCESS_KEY` in aws context.
- `SMS_PROVIDER_REGION` which is `AWS_REGION` in aws context.

### AZURE
If you set `SMS_PROVIDER = AZURE`, the following env variables are required:
- `SMS_PROVIDER_USERNAME` which is `resource-name` in azure `connectionString` context.
- `SMS_PROVIDER_PASSWORD` which is `access-key` in azure `connectionString` context.
- `SMS_PROVIDER_FROM_NUMBER` which is the ACS-registered number in azure context. This must be in E.164 format, example: "+123456789"

**Note**: The azure `connectionString` for `Azure Communication Services` looks like this: `endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>`.

### TWILIO
If you set `SMS_PROVIDER = TWILIO`, the following env variables are required:
- `SMS_PROVIDER_USERNAME` which is `TWILIO_ACCOUNT_SID` in twilio context.
- `SMS_PROVIDER_PASSWORD` which is `TWILIO_AUTH_TOKEN` in twilio context.

### VONAGE
If you set `SMS_PROVIDER = VONAGE`, the following env variables are required:
- `SMS_PROVIDER_USERNAME` which is `VONAGE_API_KEY` in vonage context.
- `SMS_PROVIDER_PASSWORD` which is `VONAGE_API_SECRET` in vonage context.
- `SMS_PROVIDER_FROM_NUMBER` which can be one of the next: 
    - An alphanumeric ID. Example: "MyCompanyBrand"
    - A Vonage-registered number in E.164 format. Example: "+123456789".
    - A local-registered short number. Example: "12345".

## API Documentation

### Available Methods

```ts
send: (phones: string[], message: string) => Promise<SendResult>;
```


## Example Usage

```ts
const phones: string[] = [
    "+123456789",
    "+9876543210"
];
const message = "Hello world!";

const smsSenderService = new SMSSenderService();
await smsSenderService.send(phones, message);
```