Merge pull request #119 from AfricasTalkingLtd/feature/YODA-T-13

YODA-T-13: Added Mobile Data to the SDK
AfricasTalkingLtd · Nov 9, 2023 · ca9df60 · ca9df60
2 parents c63dcc9 + aebfbbc
commit ca9df60
Show file tree

Hide file tree

Showing 9 changed files with 380 additions and 2,366 deletions.
diff --git a/README.md b/README.md
@@ -55,127 +55,49 @@ See [example](example/) for more usage examples.
 
 Initialize the SDK as a requirement by doing `require('africastalking')(options)`. After initialization, you can get instances of offered services as follows:
 
-- [Application Service](#applicationservice) : `AfricasTalking.APPLICATION`
+- [SMS Service](#sms) : `AfricasTalking.SMS`
 
-- [Airtime Service](#airtimeservice) : `AfricasTalking.AIRTIME`
+- [Airtime Service](#airtime) : `AfricasTalking.AIRTIME`
 
-- [SMS Service](#smsservice) : `AfricasTalking.SMS`
+- [Mobile Data Service](#mobiledata) : `AfricasTalking.MOBILEDATA`
 
-- [Voice Service](#voiceservice) : `AfricasTalking.VOICE`
-
-- [Token Service](#tokenservice) : `AfricasTalking.TOKEN`
+- [Voice Service](#voice) : `AfricasTalking.VOICE`
 
 - [USSD](#ussd) : USSD API
 
-## Services
-
-All methods are asynchronous
-
-All phone numbers use the international format. e.g. `+234xxxxxxxx`.
-
-
-
-### `ApplicationService`
+- [Token Service](#token) : `AfricasTalking.TOKEN`
 
-- `fetchApplicationData()`: Get app information. e.g. balance
-
-For more information, please read [https://developers.africastalking.com/docs/application](https://developers.africastalking.com/docs/application)
+- [Application Service](#application) : `AfricasTalking.APPLICATION`
 
 
+## Services
 
-### `AirtimeService`
-
-  - `airtime.send({ recipients })`: Send airtime to a bunch of phone numbers. 
-
-  - `recipients`: An array of objects containing the following keys:
-    - `phoneNumber`: Recipient of airtime. `REQUIRED`.
-    - `currencyCode`: 3-digit ISO format currency code. `REQUIRED`.
-    - `amount`: Amount to charge. `REQUIRED`.
-
-  - `maxNumRetry`: This allows you to specify the maximum number of retries in case of failed airtime deliveries due to various reasons such as telco unavailability. The default retry period is 8 hours and retries occur every 60seconds. For example, setting `maxNumRetry=4` means the transaction will be retried every 60seconds for the next 4 hours.`OPTIONAL`.
-
-  - Example:
+All methods are asynchronous
 
-  ```javascript
-      airtime.send({
-          recipients: [
-              {
-                  phoneNumber: '+xxxxxxxxxxxx',
-                  currencyCode: 'KES',
-                  amount: 90
-              },
-              {
-                  phoneNumber: '+xxxxxxxxxxxx',
-                  currencyCode: 'KES',
-                  amount: 897
-              }
-          ],
-          maxNumRetry: 3, // Will retry the transaction every 60seconds for the next 3 hours.
-      });
-  ```
+All phone numbers use the international format. e.g. `+234xxxxxxxx`.
 
-  For more information, please read [https://developers.africastalking.com/docs/airtime/sending](https://developers.africastalking.com/docs/airtime/sending)
 
+### `SMS`
 
+- `send({ to, from, message, enqueue })`: Send an SMS to one or more phone numbers
 
-### `SmsService`
-
-- Send a message to one recipient.
-  ```javascript
-      send({
-        to: '+xxxxxxxxxxxx',
-        from: 'XYZ LTD',
-        message: 'Hello world',
-        enqueue: true,
-      });
-    ```
-
-- Send a message to multiple recipients.
-  ```javascript
-      send({
-        to: ['+xxxxxxxxxxxx','+yyyyyyyyyyyy','+zzzzzzzzzzzz'],
-        from: 'XYZ LTD',
-        message: 'Hello world',
-        enqueue: true,
-      });
-    ```
-
-- Send different messages to different recipients.
-  ```javascript
-      send([
-        {
-          to: ['+aaaaaaaaaaaa','+bbbbbbbbbbbb','+cccccccccccc'],
-          from: 'XYZ LTD',
-          message: 'Congratulations team! You have won it!',
-          enqueue: true,
-        },
-        {
-          to: '+xxxxxxxxxxxx',
-          from: 'XYZ LTD',
-          message: 'Congratulations coach! Your team has won!',
-          enqueue: true,
-        }
-      ]);
-    ```
+- `send([{ to, from, message, enqueue }])`: Send multiple SMSes to one or more phone numbers
 
-  - `to`: Recipient(s) phone number. `REQUIRED`
+  - `to`: Recipient(s) phone number. Can either a single phone number or an array of phone numbers `REQUIRED`
   - `from`: Shortcode or alphanumeric ID that is registered with Africa's Talking account
   - `message`: SMS content. `REQUIRED`
   - `enqueue`: Set to true if you would like to deliver as many messages to the API without waiting for an acknowledgement from telcos.
 
 - `sendPremium({ to, from, message, enqueue, keyword, linkId, retryDurationInHours })`: Send premium SMS
 
-  - `send()` parameters plus:
   - `keyword`: You premium product keyword
   - `linkId`: We forward the `linkId` to your application when the user send a message to your service
   - `retryDurationInHours`: It specifies the number of hours your subscription message should be retried in case it's not delivered to the subscriber
 
-
 - `fetchMessages({ lastReceivedId })`: Manually retrieve your messages
 
   - `lastReceivedId`: "This is the id of the message that you last processed". Defaults to `0`
 
-
 - `fetchSubscription({ shortCode, keyword, lastReceivedId })`: Fetch your premium subscription data
 
   - `shortCode`: This is the premium short code mapped to your account. `REQUIRED`
@@ -196,21 +118,56 @@ For more information on:
 - How to listen for subscription notifications: [https://developers.africastalking.com/docs/sms/notifications](https://developers.africastalking.com/docs/sms/notifications)
 
 
-### `VoiceService`
+### `Airtime`
+
+  - `send({ recipients })`: Send airtime to a bunch of phone numbers. 
 
-- `voice.call({ callFrom, callTo })`: Initiate a phone call
+    - `recipients`: An array of objects containing the following keys:
+      - `phoneNumber`: Recipient of airtime. `REQUIRED`.
+      - `currencyCode`: 3-digit ISO format currency code. `REQUIRED`.
+      - `amount`: Amount to charge. `REQUIRED`.
+
+    - `maxNumRetry`: This allows you to specify the maximum number of retries in case of failed airtime deliveries due to various reasons such as telco unavailability. The default retry period is 8 hours and retries occur every 60seconds. For example, setting `maxNumRetry=4` means the transaction will be retried every 60seconds for the next 4 hours.`OPTIONAL`.
+
+
+  For more information, please read [https://developers.africastalking.com/docs/airtime/sending](https://developers.africastalking.com/docs/airtime/sending)
+
+
+### `MobileData`
+
+- `send({ productName, recipients })`
+
+    - `productName`: This is the application's product name.
+    - `recipients`: An array of objects containing the following keys:
+      - `phoneNumber`: Recipient of the mobile data. `REQUIRED`.
+      - `quantity`: a numeric value for the amount of mobile data. It is based on the available mobile data package[(see "Bundle Package" column of mobile data pricing)](https://africastalking.com/pricing). `REQUIRED`.
+      - `unit`: The units for the specified data quantity, the format is: ``MB`` or ``GB``. It is based on the available mobile data package[(see "Bundle Package" column of mobile data pricing)](https://africastalking.com/pricing). `REQUIRED`.
+      - `validity`: The period of the data bundle’s validity this can be `Day`, `Week`, `BiWeek`, `Month`, or `Quarterly`. It is based on the available mobile data package [(see "Validity" column of mobile data pricing)](https://africastalking.com/pricing). `REQUIRED`.
+      - `metadata`:  A JSON object of any metadata that you would like us to associate with the request. `OPTIONAL`.
+
+
+- `findTransaction({ transactionId })`:  Find a mobile data transaction
+
+- `fetchWalletBalance()`: Fetch a mobile data product balance
+
+For more information, please read the [https://developers.africastalking.com/docs/data/overview](https://developers.africastalking.com/docs/data/overview)
+
+
+### `Voice`
+
+- `call({ callFrom, callTo })`: Initiate a phone call
 
     - `callFrom`: Your Africa's Talking issued virtual phone number. `REQUIRED`
     - `callTo`: Comma-separated string of phone numbers to call. `REQUIRED`
     - `clientRequestId`: Additional information that can be used to tag the call in your callback URL.
 
 
-- `voice.fetchQuedCalls({ phoneNumber })`: Get queued calls
+- `fetchQuedCalls({ phoneNumber })`: Get queued calls
 
     - `phoneNumber`: Your Africa's Talking issued virtual phone number. `REQUIRED`
 
 
-- `voice.uploadMediaFile({ phoneNumber, url })`: Upload voice media file
+- `uploadMediaFile({ phoneNumber, url })`: Upload voice media file
 
     - `phoneNumber`: Your Africa's Talking issued virtual phone number. `REQUIRED`
     - `url`: URL to your media file. `REQUIRED`
@@ -222,17 +179,21 @@ For more information on:
 
 For more information, please read [https://developers.africastalking.com/docs/voice/overview](https://developers.africastalking.com/docs/voice/overview) and [issue #15](https://github.com/AfricasTalkingLtd/africastalking-node.js/issues/15)
 
+### `USSD`
 
+For more information, please read [https://developers.africastalking.com/docs/ussd/overview](https://developers.africastalking.com/docs/ussd/overview)
 
-### `TokenService`
+
+### `Token`
 
 - `generateAuthToken()`: Generate an auth token to use for authentication instead of an API key.
 
 
-### `USSD`
+### `Application`
 
-For more information, please read [https://developers.africastalking.com/docs/ussd/overview](https://developers.africastalking.com/docs/ussd/overview)
+- `fetchApplicationData()`: Get app information. e.g. balance
 
+For more information, please read [https://developers.africastalking.com/docs/application](https://developers.africastalking.com/docs/application)
 
 
 ## Development

diff --git a/lib/common.js b/lib/common.js
@@ -22,7 +22,7 @@ const initUrls = function (sandbox) {
 
     exports.VOICE_URL = "https://voice." + baseDomain;
 
-    exports.PAYMENT_URL = "https://payments." + baseDomain;
+    exports.MOBILE_DATA_URL = "https://bundles." + baseDomain;
 
     exports.CONTENT_URL = sandbox
         ? baseUrl

diff --git a/lib/index.js b/lib/index.js
@@ -10,7 +10,7 @@ const SMS       = require('./sms');
 const USSD      = require('./ussd');
 const Airtime   = require('./airtime');
 const Voice     = require('./voice');
-const Payment   = require('./payments');
+const MobileData = require('./mobileData');
 
 
 class AfricasTalking {
@@ -60,9 +60,8 @@ class AfricasTalking {
         /* End */
         this.SMS = new SMS(this.options);
         this.VOICE = new Voice(this.options);
-        this.PAYMENTS = new Payment(this.options);
-        this.PAYMENT = this.PAYMENTS; /* So we don't break apps using old version */
         this.AIRTIME = new Airtime(this.options);
+        this.MOBILE_DATA = new MobileData(this.options);
         this.TOKEN = new Token(this.options);
         this.USSD = USSD;
     }