netgsm-otp/README.md

Unofficial Node.js/TypeScript client for NetGSM OTP SMS service

# netgsm-otp

Unofficial Node.js/TypeScript client for NetGSM OTP SMS service. This package provides a simple and type-safe way to send OTP (One-Time Password) SMS messages through NetGSM's API.

## Installation

```bash
npm install netgsm-otp
# or
yarn add netgsm-otp
# or
pnpm add netgsm-otp
```

## Usage

```typescript
import { NetGsmOtp } from 'netgsm-otp';

// Initialize the client with your NetGSM credentials
const netgsm = new NetGsmOtp({
  usercode: 'YOUR_USERCODE',
  password: 'YOUR_PASSWORD',
  msgheader: 'YOUR_MESSAGE_HEADER', // Usually your originator/sender ID
  appkey: 'YOUR_APP_KEY'
});

// Send an OTP message
async function sendOtpExample() {
  const result = await netgsm.sendOtp({
    phoneNumber: '5XXXXXXXXX', // Recipient phone number (Turkish mobile number)
    message: 'Your verification code is: {code}', // Message template
    code: '123456' // The OTP code to insert into the message
  });

  // Note: Phone numbers are automatically validated to ensure they are valid Turkish mobile numbers

  if (result.success) {
    console.log('OTP sent successfully!');
    console.log('Message ID:', result.code);
  } else {
    console.error('Failed to send OTP:', result.message);
  }
}

sendOtpExample();
```

## API Reference

### `NetGsmOtp`

The main class for interacting with NetGSM's OTP SMS service.

#### Constructor

```typescript
constructor(options: NetGsmOtpOptions)
```

- `options`: Configuration object with the following properties:
  - `usercode`: Your NetGSM username/usercode
  - `password`: Your NetGSM password
  - `msgheader`: Your message header/originator (sender ID)
  - `appkey`: Your application key

#### Methods

##### `sendOtp(options: SendOtpOptions): Promise<{ success: boolean; message: string; code?: string }>`

Sends an OTP SMS message.

- `options`: Object with the following properties:
  - `phoneNumber`: Recipient's phone number (must be a valid Turkish mobile number)
  - `message`: Message template (use `{code}` placeholder for the OTP code)
  - `code`: (Optional) The OTP code to insert into the message

> **Note:** Phone numbers are automatically validated. Valid formats include:
> - 10 digits starting with '5' (e.g., '5XXXXXXXXX')
> - 12 digits starting with '90' followed by '5' (e.g., '905XXXXXXXXX')
> - Non-digit characters are automatically removed (e.g., '+90 5XX XXX XX XX' is valid)

Returns a Promise that resolves to an object with:
- `success`: Boolean indicating if the operation was successful
- `message`: Status message
- `code`: (Only when successful) The message ID returned by NetGSM

## Response Codes

The package handles the following NetGSM response codes:

- `00`: Success
- `20`: Authentication error
- `30`: Parameter error
- `40`: Balance error
- `70`: System error

## License

ISC

## Disclaimer

This is an unofficial package and is not affiliated with, maintained, authorized, endorsed, or sponsored by NetGSM.