# Africa's Talking Libraries and SDKs Open Source Contribution Guideline.

This is a brief outline on coming up with libraries and SDKs for the Africa's Talking platform, happy coding 👨🏾‍💻

The SDK map to each of API endpoints as outlined in the API reference. 
The functionality it exposes should be grouped/namespaced per product i.e. **SMS, Airtime, Voice, USSD Chat and Insights.** Also required of the SDK is a comprehensive **README.md** file outlining available methods, 
arguments and other, requirements as well as a usage guide.

The **README.md** must contain the following sections:
- **Install**: Show/Describe how one can get the SDK into their project using our package managers.
- **Usage**: Show simple sample code that demonstrates the SDK usage; showcase only one product say sms.
- **Initialization**: Describe how to initialize the SDK
- **Services/Products**: Outline methods, params available for every product/service.


## Initialization
The SDK should be initialized from a single **entry point**, with an **app username** and **API key**.
```
AfricasTalking::initialize(APP_USERNAME, API_KEY)
```
>The SDK will always assume sandbox and therefore use sandbox APIs if it is initialized with an app username ```sandbox```.

### Usage
Each **product instance** should be retrieved thereafter from the entry point as follows:
```
val sms = AfricasTalking::SMS // or     
val sms = AfricasTalking::getSms() // or   
val sms = AfricasTalking::getSmsService()
```
Each **product function** will then be used on the product instance as follows:
```
val result = sms.send(options)
```

The result of every function should be an object native to the language instead of the ```json``` or ```xml``` returned by the target API.

Here is a simple 'send SMS' example:
```
AfricasTalking::initialize('sandbox', 'ABDJKEY')   
val sms = AfricasTalking::getSms()    
val result = sms.send('Hi There!', ['+254718767881'], 'AwesomeBot')    
print result
```

## Languages
The following languages are officially supported:

- PHP
- Java
- JavaScript (Node.js)
- Python
- C#
- Ruby
- Android (Java), iOS (Swift)*
Libraries for other languages should be left to the community to build and maintain.

## Distribution
The SDK should be versioned using [semantic versioning](https://semver.org/). Users should be able to access the SDK full source code from [GitHub](https://github.com/AfricasTalkingLtd/). In addition, users should be able to easily import the SDK in their projects using the official/popular package manager for the language they are using:

| Language | Package Manager |
| ----------- | ----------- |
| PHP | [Packagist (Composer)](https://packagist.org/packages/africastalking/africastalking) |
| Java | [Android    Bintray (Maven)](https://bintray.com/africastalking/java) |
| JavaScript | [npm](https://www.npmjs.com/package/africastalking) |
| Python | [PyPi](https://pypi.org/project/africastalking/) |
| C# | [NuGet](https://www.nuget.org/packages/AfricasTalking.NET/) |
| Ruby | [RubyGem](https://rubygems.org/gems/africastalking-ruby) |

## Products
For each product, the SDK should provide the functions outlined below. The functions should be **asynchronous**, depending on the language features.

>The function parameters can be collapsed into one object depending on the language\
>All phone numbers are in the international format. e.g. ```+2439083747754```\
>All amounts are strings containing the currency code and the actual amount. e.g. ```USD 14.56```

## Airtime

- ```send(phoneNumber: String, amount: String)```: Send airtime to a phone number.
- ```send(recipients: List<Map<String,String>>)```: Send airtime to a bunch of phone numbers. The keys in the ```recipients``` map are phone numbers while the values are airtime amounts.

## SMS
- ```send(message: String, recipients: List<String>, senderId: Optional<String>, enqueue: Optional<Boolean>)```: Send a bulk message to ```recipients```, optionally from ```senderId``` (Short Code or Alphanumeric).
- ```sendPremium(message: String, keyword: String, linkId: String, recipients: List<String>, senderId: Optional<String>, retryDurationInHours: Optional<Integer>)```: Send a premium SMS
- ```fetchMessages(lastReceivedId: Optional<Integer>)```: Fetch your messages
- ```fetchSubscriptions(shortCode: String, keyword: String, lastReceivedId: Optional<Integer>)```: Fetch your premium subscription data
- ```createSubscription(shortCode: String, keyword: String, phoneNumber: String, checkoutToken: String)```: Create a premium subscription
- ```deleteSubscription(shortCode: String,keyeord: String, phoneNumber: String)```: Remove a premium subscription.

## Voice
- ```call(phoneNumber: String)```: Initiate a phone call
- ```fetchQueuedCalls(phoneNumber: String)```: Get queued calls
- ```uploadMediaFile(phoneNumber: String, url: String)```: Upload voice media file
- ```ActionBuilder```: Build voice XML when callback URL receives a ```POST``` from the voice API
    - ```say(text: String)```
    - ``` play(url: String)```
    - ```getDigits(text: String, url: String, numDigits: Integer, timeout: Integer, finishOnKey: String, callbackUrl: String)```
    - ```dial(phoneNumbers: String, ringbackTone: String, record: Boolean, sequential: Boolean, callerId: String, maxDuration: Integer)```
    - ```conference()```
    - ```record()```
        - ```record(String text, URL url, int maxLength, long timeout, String finishOnKey, boolean trimSilence, boolean playBeep, URL callbackUrl)```
    - ```enqueue()```
    - ```dequeue()```
    - ```reject()```
    - ```redirect()```
    - ```build()```: Finally, build the XML

## USSD
- ```CON```
- ```END```

## Others
### Application
```fetchApplicationData()```: Fetch app info i.e. balance.

### Token
```generateAuthToken()```: Generate an auth token to use for authentication instead of the API key.