Merge pull request #219 from RDPerera/docs

Improve documentation
ballerina-platform · Dec 16, 2023 · a04135e · a04135e
2 parents 4afd7f1 + 86fdd8c
commit a04135e
Show file tree

Hide file tree

Showing 83 changed files with 5,037 additions and 368 deletions.
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ Twilio is a cloud communications platform that allows software developers to pro
 
 The Ballerina Twilio connector supports the [Twilio Basic API version 2010-04-01](https://www.twilio.com/docs/all), enabling users to leverage these communication capabilities within their Ballerina applications.
 
-## Setting up the Twilio
+## Set up guide
 Before using the ballerinax-twilio connector you must have access to Twilio API, If you do not have access to Twilio API please complete the following steps:
 
 ### Step 1: Create a Twilio account.
@@ -49,7 +49,7 @@ Twilio uses two credentials to determine which account an API request is coming
 
 Your account's Auth Token is hidden by default. Click show to display the token, and hide to conceal it again. For further information click [here](https://support.twilio.com/hc/en-us/articles/223136027-Auth-Tokens-and-How-to-Change-Them)
 
-## Sample
+## Quickstart
 
 This sample demonstrates a scenario where the Twilio connector is used to send a text message to a phone number.
 
@@ -66,12 +66,12 @@ import ballerinax/twilio;
 To create a new connector instance, add a configuration as follows (You can use [configurable variables](https://ballerina.io/learn/by-example/configurable.html) to provide the necessary credentials):
 
 ```ballerina
-configurable string accountSID = ?;
+configurable string accountSid = ?;
 configurable string authToken = ?;
 
 twilio:ConnectionConfig twilioConfig = {
     auth: {
-        username: accountSID,
+        username: accountSid,
         password: authToken
     }
 };
@@ -81,7 +81,7 @@ twilio:Client twilio = check new (twilioConfig);
 
 ### Step 3 - Invoke the connector operation
 
-1. Invoke the connector operation using the client as shown below:
+1. Invoke the sending SMS operation using the client as shown below:
 
 ```ballerina
 public function main() returns error? {
@@ -100,7 +100,27 @@ public function main() returns error? {
 
 2. Use `bal run` command to compile and run the Ballerina program.
 
-**[You can find more samples here](https://github.com/ballerina-platform/module-ballerinax-twilio/tree/master/examples)**
+## Examples
+
+The Twilio connector comes equipped with examples that demonstrate its usage across various scenarios. These examples are conveniently organized into three distinct groups based on the functionalities they showcase. For a more hands-on experience and a deeper understanding of these capabilities, we encourage you to experiment with the provided examples in your development environment.
+
+1. Account management
+    - [Create a sub-account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/create-sub-account) - Create a subaccount under a Twilio account
+    - [Fetch an account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/fetch-account) - Get details of a Twilio account
+    - [Fetch balance](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/fetch-balance) - Get the balance of a Twilio account
+    - [List accounts](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/list-accounts) - List all subaccounts under a Twilio account
+    - [Update an account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/update-account) - Update the name of a Twilio account
+2. Call management
+    - [Make a call](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/create-call) - Make a call to a phone number via a Twilio
+    - [Fetch call log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/fetch-call-log) - Get details of a call made via a Twilio
+    - [List call logs](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/list-call-logs) - Get details of all calls made via a Twilio
+    - [Delete a call log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/delete-call-log) - Delete the log of a call made via Twilio
+3. Message management
+    - [Send an SMS message](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/create-sms-message) - Send an SMS to a phone number via a Twilio 
+    - [Send a Whatsapp message](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/create-whatsapp-message) - Send a Whatsapp message to a phone number via a Twilio
+    - [List message logs](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/list-message-logs) - Get details of all messages sent via a Twilio
+    - [Fetch a message log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/fetch-message-log) - Get details of a message sent via a Twilio
+    - [Delete a message log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/delete-message-log) - Delete a message log via a Twilio
 
 ## Issues and projects 
 

diff --git a/ballerina/Dependencies.toml b/ballerina/Dependencies.toml
@@ -5,7 +5,7 @@
 
 [ballerina]
 dependencies-toml-version = "2"
-distribution-version = "2201.8.0-20230830-220400-8a7556d8"
+distribution-version = "2201.8.2"
 
 [[package]]
 org = "ballerina"
@@ -64,7 +64,7 @@ dependencies = [
 [[package]]
 org = "ballerina"
 name = "http"
-version = "2.10.4"
+version = "2.10.5"
 dependencies = [
 	{org = "ballerina", name = "auth"},
 	{org = "ballerina", name = "cache"},

diff --git a/ballerina/Module.md b/ballerina/Module.md
@@ -4,7 +4,7 @@ Twilio is a cloud communications platform that allows software developers to pro
 
 The Ballerina Twilio connector supports the [Twilio Basic API version 2010-04-01](https://www.twilio.com/docs/all), enabling users to leverage these communication capabilities within their Ballerina applications.
 
-## Setting up the Twilio
+## Set up guide
 Before using the ballerinax-twilio connector you must have access to Twilio API, If you do not have access to Twilio API please complete the following steps:
 
 ### Step 1: Create a Twilio account.
@@ -40,7 +40,7 @@ Twilio uses two credentials to determine which account an API request is coming
 
 Your account's Auth Token is hidden by default. Click show to display the token, and hide to conceal it again. For further information click [here](https://support.twilio.com/hc/en-us/articles/223136027-Auth-Tokens-and-How-to-Change-Them)
 
-## Sample
+## Quick Start
 
 This sample demonstrates a scenario where the Twilio connector is used to send a text message to a phone number.
 
@@ -57,12 +57,12 @@ import ballerinax/twilio;
 To create a new connector instance, add a configuration as follows (You can use [configurable variables](https://ballerina.io/learn/by-example/configurable.html) to provide the necessary credentials):
 
 ```ballerina
-configurable string accountSID = ?;
+configurable string accountSid = ?;
 configurable string authToken = ?;
 
 twilio:ConnectionConfig twilioConfig = {
     auth: {
-        username: accountSID,
+        username: accountSid,
         password: authToken
     }
 };
@@ -72,7 +72,7 @@ twilio:Client twilio = check new (twilioConfig);
 
 ### Step 3 - Invoke the connector operation
 
-1. Invoke the connector operation using the client as shown below:
+1. Invoke the sending SMS operation using the client as shown below:
 
 ```ballerina
 public function main() returns error? {
@@ -91,4 +91,24 @@ public function main() returns error? {
 
 2. Use `bal run` command to compile and run the Ballerina program.
 
-**[You can find more samples here](https://github.com/ballerina-platform/module-ballerinax-twilio/tree/master/examples)**
+## Examples
+
+The Twilio connector comes equipped with examples that demonstrate its usage across various scenarios. These examples are conveniently organized into three distinct groups based on the functionalities they showcase. For a more hands-on experience and a deeper understanding of these capabilities, we encourage you to experiment with the provided examples in your development environment.
+
+1. Account management
+    - [Create a sub-account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/create-sub-account) - Create a subaccount under a Twilio account
+    - [Fetch an account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/fetch-account) - Get details of a Twilio account
+    - [Fetch balance](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/fetch-balance) - Get the balance of a Twilio account
+    - [List accounts](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/list-accounts) - List all subaccounts under a Twilio account
+    - [Update an account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/update-account) - Update the name of a Twilio account
+2. Call management
+    - [Make a call](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/create-call) - Make a call to a phone number via a Twilio
+    - [Fetch call log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/fetch-call-log) - Get details of a call made via a Twilio
+    - [List call logs](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/list-call-logs) - Get details of all calls made via a Twilio
+    - [Delete a call log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/delete-call-log) - Delete the log of a call made via Twilio
+3. Message management
+    - [Send an SMS message](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/create-sms-message) - Send an SMS to a phone number via a Twilio 
+    - [Send a Whatsapp message](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/create-whatsapp-message) - Send a Whatsapp message to a phone number via a Twilio
+    - [List message logs](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/list-message-logs) - Get details of all messages sent via a Twilio
+    - [Fetch a message log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/fetch-message-log) - Get details of a message sent via a Twilio
+    - [Delete a message log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/delete-message-log) - Delete a message log via a Twilio
diff --git a/ballerina/Package.md b/ballerina/Package.md
@@ -4,7 +4,7 @@ Twilio is a cloud communications platform that allows software developers to pro
 
 The Ballerina Twilio connector supports the [Twilio Basic API version 2010-04-01](https://www.twilio.com/docs/all), enabling users to leverage these communication capabilities within their Ballerina applications.
 
-## Setting up the Twilio
+## Set up guide
 Before using the ballerinax-twilio connector you must have access to Twilio API, If you do not have access to Twilio API please complete the following steps:
 
 ### Step 1: Create a Twilio account.
@@ -40,7 +40,7 @@ Twilio uses two credentials to determine which account an API request is coming
 
 Your account's Auth Token is hidden by default. Click show to display the token, and hide to conceal it again. For further information click [here](https://support.twilio.com/hc/en-us/articles/223136027-Auth-Tokens-and-How-to-Change-Them)
 
-## Sample
+## Quick Start
 
 This sample demonstrates a scenario where the Twilio connector is used to send a text message to a phone number.
 
@@ -57,12 +57,12 @@ import ballerinax/twilio;
 To create a new connector instance, add a configuration as follows (You can use [configurable variables](https://ballerina.io/learn/by-example/configurable.html) to provide the necessary credentials):
 
 ```ballerina
-configurable string accountSID = ?;
+configurable string accountSid = ?;
 configurable string authToken = ?;
 
 twilio:ConnectionConfig twilioConfig = {
     auth: {
-        username: accountSID,
+        username: accountSid,
         password: authToken
     }
 };
@@ -72,7 +72,7 @@ twilio:Client twilio = check new (twilioConfig);
 
 ### Step 3 - Invoke the connector operation
 
-1. Invoke the connector operation using the client as shown below:
+1. Invoke the sending SMS operation using the client as shown below:
 
 ```ballerina
 public function main() returns error? {
@@ -91,4 +91,25 @@ public function main() returns error? {
 
 2. Use `bal run` command to compile and run the Ballerina program.
 
-**[You can find more samples here](https://github.com/ballerina-platform/module-ballerinax-twilio/tree/master/examples)**
+
+## Examples
+
+The Twilio connector comes equipped with examples that demonstrate its usage across various scenarios. These examples are conveniently organized into three distinct groups based on the functionalities they showcase. For a more hands-on experience and a deeper understanding of these capabilities, we encourage you to experiment with the provided examples in your development environment.
+
+1. Account management
+    - [Create a sub-account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/create-sub-account) - Create a subaccount under a Twilio account
+    - [Fetch an account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/fetch-account) - Get details of a Twilio account
+    - [Fetch balance](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/fetch-balance) - Get the balance of a Twilio account
+    - [List accounts](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/list-accounts) - List all subaccounts under a Twilio account
+    - [Update an account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/update-account) - Update the name of a Twilio account
+2. Call management
+    - [Make a call](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/create-call) - Make a call to a phone number via a Twilio
+    - [Fetch call log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/fetch-call-log) - Get details of a call made via a Twilio
+    - [List call logs](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/list-call-logs) - Get details of all calls made via a Twilio
+    - [Delete a call log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/delete-call-log) - Delete the log of a call made via Twilio
+3. Message management
+    - [Send an SMS message](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/create-sms-message) - Send an SMS to a phone number via a Twilio 
+    - [Send a Whatsapp message](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/create-whatsapp-message) - Send a Whatsapp message to a phone number via a Twilio
+    - [List message logs](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/list-message-logs) - Get details of all messages sent via a Twilio
+    - [Fetch a message log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/fetch-message-log) - Get details of a message sent via a Twilio
+    - [Delete a message log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/delete-message-log) - Delete a message log via a Twilio
diff --git a/examples/README.md b/examples/README.md
@@ -1,7 +1,24 @@
 # Examples
 
-This directory contains a collection of sample code examples written in Ballerina. These examples demonstrate various
-use cases of the module. You can follow the instructions below to build and run these examples.
+This directory contains a collection of sample code examples written in Ballerina, demonstrating various use cases of the module. The examples are categorized into three groups based on the functionality they illustrate.
+
+1. Account management
+    - [Create a sub-account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/create-sub-account) - Create a subaccount under a Twilio account
+    - [Fetch an account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/fetch-account) - Get details of a Twilio account
+    - [Fetch balance](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/fetch-balance) - Get the balance of a Twilio account
+    - [List accounts](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/list-accounts) - List all subaccounts under a Twilio account
+    - [Update an account](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/accounts/update-account) - Update the name of a Twilio account
+2. Call management
+    - [Make a call](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/create-call) - Make a call to a phone number via a Twilio
+    - [Fetch call log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/fetch-call-log) - Get details of a call made via a Twilio
+    - [List call logs](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/list-call-logs) - Get details of all calls made via a Twilio
+    - [Delete a call log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/calls/delete-call-log) - Delete the log of a call made via Twilio
+3. Message management
+    - [Send an SMS message](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/create-sms-message) - Send an SMS to a phone number via a Twilio 
+    - [Send a Whatsapp message](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/create-whatsapp-message) - Send a Whatsapp message to a phone number via a Twilio
+    - [List message logs](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/list-message-logs) - Get details of all messages sent via a Twilio
+    - [Fetch a message log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/fetch-message-log) - Get details of a message sent via a Twilio
+    - [Delete a message log](https://github.com/RDPerera/module-ballerinax-twilio/tree/master/examples/messages/delete-message-log) - Delete a message log via a Twilio
 
 ## Running an Example
 

diff --git a/examples/accounts/create-sub-account/.github/README.md b/examples/accounts/create-sub-account/.github/README.md
@@ -0,0 +1 @@
+../Create sub account.md
diff --git a/examples/accounts/create-sub-account/Ballerina.toml b/examples/accounts/create-sub-account/Ballerina.toml
@@ -0,0 +1,8 @@
+[package]
+org = "dilanperera"
+name = "create_sub_account"
+version = "0.1.0"
+distribution = "2201.8.2"
+
+[build-options]
+observabilityIncluded = true
diff --git a/examples/accounts/create-sub-account/Create sub account.md b/examples/accounts/create-sub-account/Create sub account.md
@@ -0,0 +1,25 @@
+# Create sub account in Twilio
+
+This example demonstrates how to create a sub account under your Twilio account using Ballerina.
+
+## Prerequisites
+
+### 1. Set up
+Refer to the set up guide in [ReadMe](../../../README.md) for necessary credentials.
+
+### 2. Configuration
+
+Configure Twilio API credentials in Config.toml in the example directory:
+
+```toml
+accountSid="<Account Sid>"
+authToken="<Auth Token>"
+```
+
+## Run the Example
+
+Execute the following command to run the example:
+
+```bash
+bal run
+```