Verimor SMS SDK

Source: GitHub Repository Author: Bilal ATLI

A TypeScript SDK for the Verimor SMS API, providing an easy and efficient way to integrate SMS, IYS consent management, and other functionalities into your applications.

Table of Contents

• Features
• Installation
• Getting Started
  • Initializing the Client
• Usage
  • Sending SMS Messages
  • Calculating SMS Credits
  • Checking Account Balance
  • Retrieving Message Status
  • Fetching Inbox Messages
  • Blacklist Management
  • IYS Integration
• Advanced Configuration
  • Proxy Settings
• Error Handling
• License
• Contact

Features

• Comprehensive API Coverage: Access all endpoints provided by the Verimor SMS API.
• Unified Client Interface: Simplified usage through a single Verimor client.
• IYS Integration: Manage IYS consents and campaigns seamlessly.
• Blacklist Management: Easily add, retrieve, and remove blacklisted numbers.
• Proxy Support: Configure proxy settings for network routing.
• TypeScript Support: Fully typed interfaces and enums for robust development.
• Error Handling: Consistent and informative error responses.

Installation

Install the SDK via npm:

npm install verimor-api-sdk

Getting Started

Initializing the Client

Import the Verimor client and initialize it with your API credentials:

import { Verimor } from 'verimor-api-sdk';

const client = new Verimor('your_username', 'your_password');

Usage

Sending SMS Messages

Send SMS messages to one or multiple recipients.

const smsRequest = {
  msg: 'Hello, this is a test message.',
  dest: ['905xxxxxxxxx', '905yyyyyyyyy'],
  iys_recipient_type: 'BIREYSEL',
};

client.smsApi
  .sendSms(smsRequest)
  .then((response) => {
    console.log('SMS sent successfully:', response);
  })
  .catch((error) => {
    console.error('Error sending SMS:', error);
  });

Calculating SMS Credits

Calculate the number of SMS credits required for a message based on its length and character set.

const message = 'Hello, this is a test message.';
const creditsRequired = client.smsUtils.calculateSmsCredits(message);
console.log(`Credits required: ${creditsRequired}`);

Checking Account Balance

Retrieve your account's current SMS credit balance.

client.accountApi
  .getBalance()
  .then((balance) => {
    console.log('Account balance:', balance);
  })
  .catch((error) => {
    console.error('Error fetching balance:', error);
  });

Retrieving Message Status

Get the delivery status of your sent messages.

client.messageApi
  .getMessageStatus({ id: 20121 })
  .then((statuses) => {
    statuses.forEach((status) => {
      console.log(`Message ID: ${status.message_id}, Status: ${status.status}`);
    });
  })
  .catch((error) => {
    console.error('Error fetching message status:', error);
  });

Fetching Inbox Messages

Retrieve SMS messages received in your account's inbox.

client.inboxApi
  .getInboxMessages('2023-01-01T09:00:00', '2023-01-01T12:00:00')
  .then((messages) => {
    messages.forEach((message) => {
      console.log(`From: ${message.source_addr}, Message: ${message.content}`);
    });
  })
  .catch((error) => {
    console.error('Error fetching inbox messages:', error);
  });

Blacklist Management

Adding Numbers to the Blacklist

client.blacklistApi
  .addNumbersToBlacklist(['905444876543', '905335876543'])
  .then((response) => {
    console.log('Numbers added to blacklist:', response);
  })
  .catch((error) => {
    console.error('Error adding numbers to blacklist:', error);
  });

Fetching Blacklisted Numbers

client.blacklistApi
  .getBlacklistedNumbers()
  .then((data) => {
    data.records.forEach((record) => {
      console.log(`Blacklisted Number: ${record.phone}, Source: ${record.source}`);
    });
  })
  .catch((error) => {
    console.error('Error fetching blacklisted numbers:', error);
  });

Deleting Numbers from the Blacklist

client.blacklistApi
  .deleteNumbersFromBlacklist(['905444876543', '905335876543'])
  .then((response) => {
    console.log('Numbers removed from blacklist:', response);
  })
  .catch((error) => {
    console.error('Error removing numbers from blacklist:', error);
  });

IYS Integration

Manage IYS consents and campaigns.

Sending IYS Consents

import {
  IysConsentType,
  IysConsentSource,
  IysConsentStatus,
  IysRecipientType,
} from 'verimor-api-sdk';

const consents = [
  {
    type: IysConsentType.MESSAGE,
    source: IysConsentSource.WEB,
    status: IysConsentStatus.APPROVED,
    recipient_type: IysRecipientType.INDIVIDUAL,
    consent_date: '2022-04-14T13:30:30',
    recipient: '905311234567',
  },
];

client.iysApi
  .sendIysConsents('BASLIGIM', consents)
  .then((campaignId) => {
    console.log('IYS consents sent, campaign ID:', campaignId);
  })
  .catch((error) => {
    console.error('Error sending IYS consents:', error);
  });

Fetching IYS Campaigns

client.iysApi
  .getIysCampaigns()
  .then((data) => {
    data.records.forEach((campaign) => {
      console.log(`Campaign ID: ${campaign.id}, Source: ${campaign.source}`);
    });
  })
  .catch((error) => {
    console.error('Error fetching IYS campaigns:', error);
  });

Fetching IYS Consent Reports

const campaignId = 1234;

client.iysApi
  .getIysConsentReports(campaignId)
  .then((report) => {
    console.log('IYS consent report:', report);
  })
  .catch((error) => {
    console.error('Error fetching IYS consent report:', error);
  });

Advanced Configuration

Proxy Settings

If you need to route API requests through a proxy server, you can configure proxy settings when initializing the client.

import { Verimor, ProxyConfig } from 'verimor-api-sdk';

const proxyConfig: ProxyConfig = {
  host: 'proxy.example.com',
  port: 3128,
  auth: {
    username: 'proxyUser',
    password: 'proxyPass',
  },
};

const client = new Verimor('your_username', 'your_password', proxyConfig);

Error Handling

All API methods throw an ErrorResponse if the API call fails. You can catch these errors to handle them appropriately.

client.smsApi
  .sendSms(smsRequest)
  .catch((error) => {
    if (error instanceof ErrorResponse) {
      console.error('API Error:', error.message);
      console.error('Error Code:', error.code);
      console.error('Detailed Errors:', error.errors);
    } else {
      console.error('Unexpected Error:', error);
    }
  });

License

This project is licensed under the MIT License.