Add Examples and Documentation

.gitignore

@@ -45,6 +45,8 @@ generated/
 .ballerina
 **/Config.toml
 
+examples/**/Dependencies.toml
+
 # Ignore Gradle project-specific cache directory
 .gradle
 

README.md

@@ -1,35 +1,133 @@
-# Ballerina Paypal Orders connector
+# Ballerina PayPal Orders connector
 
 [![Build](https://github.com/ballerina-platform/module-ballerinax-paypal.orders/actions/workflows/ci.yml/badge.svg)](https://github.com/ballerina-platform/module-ballerinax-paypal.orders/actions/workflows/ci.yml)
 [![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerinax-paypal.orders.svg)](https://github.com/ballerina-platform/module-ballerinax-paypal.orders/commits/master)
 [![GitHub Issues](https://img.shields.io/github/issues/ballerina-platform/ballerina-library/module/paypal.orders.svg?label=Open%20Issues)](https://github.com/ballerina-platform/ballerina-library/labels/module%paypal.orders)
 
 ## Overview
 
-[//]: # (TODO: Add overview mentioning the purpose of the module, supported REST API versions, and other high-level details.)
+[PayPal](https://www.paypal.com/) is a global online payment platform enabling individuals and businesses to securely send and receive money, process transactions, and access merchant services across multiple currencies.
+
+The `ballerinax/paypal.orders` package provides a Ballerina connector for interacting with the [PayPal Orders API v2](https://developer.paypal.com/docs/api/orders/v2/), allowing you to create, capture, authorize, and manage orders in your Ballerina applications.
 
 ## Setup guide
 
-[//]: # (TODO: Add detailed steps to obtain credentials and configure the module.)
+To use the PayPal Orders connector, you must have access to a [PayPal Developer account](https://developer.paypal.com/).
+
+### Step 1: Create a business account
+
+1. Open the [PayPal Developer Dashboard](https://developer.paypal.com/dashboard).
+
+2. Click on "Sandbox Accounts" under "Testing Tools".
+
+   ![Sandbox accounts](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.orders/main/docs/setup/resources/sandbox-accounts.png)
+
+3. Create a Business account
+
+   > Note: Some PayPal options and features may vary by region or country; check availability before creating an account.
+
+   ![Create business account](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.orders/main/docs/setup/resources/create-account.png)
+
+### Step 2: Create a REST API app
+
+1. Navigate to the "Apps and Credentials" tab and create a new merchant app.
+
+   Provide a name for the application and select the Business account you created earlier.
+
+   ![Create app](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.orders/main/docs/setup/resources/create-app.png)
+
+### Step 3: Obtain Client ID and Client Secret
+
+1. After creating your new app, you will see your **Client ID** and **Client Secret**. Make sure to copy and securely store these credentials.
+
+   ![Credentials](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.orders/main/docs/setup/resources/get-credentials.png)
 
 ## Quickstart
 
-[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.)
+To use the `paypal.orders` connector in your Ballerina application, update the `.bal` file as follows:
+
+### Step 1: Import the module
+
+Import the `paypal.orders` module.
+
+```ballerina
+import ballerinax/paypal.orders;
+```
+
+### Step 2: Instantiate a new connector
+
+1. Create a `Config.toml` file and configure the obtained credentials in the above steps as follows:
+
+```toml
+clientId = "<test-client-id>"
+clientSecret = "<test-client-secret>"
+
+serviceUrl = "<paypal-service-url>"
+tokenUrl = "<paypal-token-url>"
+```
+
+2. Create a `paypal:ConnectionConfig` with the obtained credentials and initialize the connector with it.
+
+```ballerina
+configurable string clientId = ?;
+configurable string clientSecret = ?;
+
+configurable string serviceUrl = ?;
+configurable string tokenUrl = ?;
+```
+
+```ballerina
+final paypal:Client paypal = check new ({
+    auth: {
+        clientId,
+        clientSecret,
+        tokenUrl
+    }
+}, serviceUrl);
+```
+
+### Step 3: Invoke the connector operation
+
+Now, utilize the available connector operations.
+
+#### Create an order
+
+```ballerina
+public function main() returns error? {
+    paypal:Order response = check paypal->/orders.post({
+        intent: "CAPTURE",
+        purchase_units: [{
+                amount: {
+                    currency_code: "USD",
+                    value: "100.00"
+                }
+            }]
+    });
+}
+```
+
+### Step 4: Run the Ballerina application
+
+```bash
+bal run
+```
 
 ## Examples
 
-The `Paypal Orders` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-paypal.orders/tree/main/examples/), covering the following use cases:
+The `PayPal Orders` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-paypal.orders/tree/main/examples/), covering the following use cases:
+
+1. [**Order lifecycle**](https://github.com/ballerina-platform/module-ballerinax-paypal.orders/tree/main/examples/order-lifecycle): Process a complete PayPal order from creation and updates through confirming and capturing payments.
 
-[//]: # (TODO: Add examples)
+2. [**Manage shipping**](https://github.com/ballerina-platform/module-ballerinax-paypal.orders/tree/main/examples/manage-shipping): Enrich an order with shipping details, add or update tracking information, and push shipment updates back to PayPal.
 
 ## Build from the source
 
 ### Setting up the prerequisites
 
 1. Download and install Java SE Development Kit (JDK) version 21. You can download it from either of the following sources:
 
-    * [Oracle JDK](https://www.oracle.com/java/technologies/downloads/)
-    * [OpenJDK](https://adoptium.net/)
+   - [Oracle JDK](https://www.oracle.com/java/technologies/downloads/)
+   - [OpenJDK](https://adoptium.net/)
 
    > **Note:** After installation, remember to set the `JAVA_HOME` environment variable to the directory where JDK was installed.
 
@@ -39,12 +137,12 @@ The `Paypal Orders` connector provides practical examples illustrating usage in
 
    > **Note**: Ensure that the Docker daemon is running before executing any tests.
 
-4. Export Github Personal access token with read package permissions as follows,
+4. Export Github Personal access token with read package permissions as follows:
 
-    ```bash
-    export packageUser=<Username>
-    export packagePAT=<Personal access token>
-    ```
+   ```bash
+   export packageUser=<Username>
+   export packagePAT=<Personal access token>
+   ```
 
 ### Build options
 
@@ -88,9 +186,9 @@ Execute the commands below to build from the source.
 
 7. Publish the generated artifacts to the local Ballerina Central repository:
 
-    ```bash
-    ./gradlew clean build -PpublishToLocalCentral=true
-    ```
+   ```bash
+   ./gradlew clean build -PpublishToLocalCentral=true
+   ```
 
 8. Publish the generated artifacts to the Ballerina Central repository:
 
@@ -110,7 +208,7 @@ All the contributors are encouraged to read the [Ballerina Code of Conduct](http
 
 ## Useful links
 
-* For more information go to the [`paypal.orders` package](https://central.ballerina.io/ballerinax/paypal.orders/latest).
-* For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/learn/by-example/).
-* Chat live with us via our [Discord server](https://discord.gg/ballerinalang).
-* Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.
+- For more information go to the [`paypal.orders` package](https://central.ballerina.io/ballerinax/paypal.orders/latest).
+- For example demonstrations of the usage, go to [Ballerina By Examples](https://ballerina.io/learn/by-example/).
+- Chat live with us via our [Discord server](https://discord.gg/ballerinalang).
+- Post all technical questions on Stack Overflow with the [#ballerina](https://stackoverflow.com/questions/tagged/ballerina) tag.

ballerina/Dependencies.toml

@@ -275,9 +275,6 @@ dependencies = [
 	{org = "ballerina", name = "io"},
 	{org = "ballerina", name = "jballerina.java"}
 ]
-modules = [
-	{org = "ballerina", packageName = "os", moduleName = "os"}
-]
 
 [[package]]
 org = "ballerina"
@@ -358,7 +355,6 @@ dependencies = [
 	{org = "ballerina", name = "http"},
 	{org = "ballerina", name = "lang.runtime"},
 	{org = "ballerina", name = "log"},
-	{org = "ballerina", name = "os"},
 	{org = "ballerina", name = "test"},
 	{org = "ballerina", name = "url"},
 	{org = "ballerina", name = "uuid"},

ballerina/README.md

@@ -1,17 +1,115 @@
 ## Overview
 
-[//]: # (TODO: Add overview mentioning the purpose of the module, supported REST API versions, and other high-level details.)
+[PayPal](https://www.paypal.com/) is a global online payment platform enabling individuals and businesses to securely send and receive money, process transactions, and access merchant services across multiple currencies.
+
+The `ballerinax/paypal.orders` package provides a Ballerina connector for interacting with the [PayPal Orders API v2](https://developer.paypal.com/docs/api/orders/v2/), allowing you to create, capture, authorize, and manage orders in your Ballerina applications.
 
 ## Setup guide
 
-[//]: # (TODO: Add detailed steps to obtain credentials and configure the module.)
+To use the PayPal Orders connector, you must have access to a [PayPal Developer account](https://developer.paypal.com/).
+
+### Step 1: Create a business account
+
+1. Open the [PayPal Developer Dashboard](https://developer.paypal.com/dashboard).
+
+2. Click on "Sandbox Accounts" under "Testing Tools".
+
+   ![Sandbox accounts](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.orders/main/docs/setup/resources/sandbox-accounts.png)
+
+3. Create a Business account
+
+   > Note: Some PayPal options and features may vary by region or country; check availability before creating an account.
+
+   ![Create business account](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.orders/main/docs/setup/resources/create-account.png)
+
+### Step 2: Create a REST API app
+
+1. Navigate to the "Apps and Credentials" tab and create a new merchant app.
+
+   Provide a name for the application and select the Business account you created earlier.
+
+   ![Create app](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.orders/main/docs/setup/resources/create-app.png)
+
+### Step 3: Obtain Client ID and Client Secret
+
+1. After creating your new app, you will see your **Client ID** and **Client Secret**. Make sure to copy and securely store these credentials.
+
+   ![Credentials](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.orders/main/docs/setup/resources/get-credentials.png)
 
 ## Quickstart
 
-[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.)
+To use the `paypal.orders` connector in your Ballerina application, update the `.bal` file as follows:
+
+### Step 1: Import the module
+
+Import the `paypal.orders` module.
+
+```ballerina
+import ballerinax/paypal.orders;
+```
+
+### Step 2: Instantiate a new connector
+
+1. Create a `Config.toml` file and configure the obtained credentials in the above steps as follows:
+
+```toml
+clientId = "<test-client-id>"
+clientSecret = "<test-client-secret>"
+
+serviceUrl = "<paypal-service-url>"
+tokenUrl = "<paypal-token-url>"
+```
+
+2. Create a `paypal:ConnectionConfig` with the obtained credentials and initialize the connector with it.
+
+```ballerina
+configurable string clientId = ?;
+configurable string clientSecret = ?;
+
+configurable string serviceUrl = ?;
+configurable string tokenUrl = ?;
+```
+
+```ballerina
+final paypal:Client paypal = check new ({
+    auth: {
+        clientId,
+        clientSecret,
+        tokenUrl
+    }
+}, serviceUrl);
+```
+
+### Step 3: Invoke the connector operation
+
+Now, utilize the available connector operations.
+
+#### Create an order
+
+```ballerina
+public function main() returns error? {
+    paypal:Order response = check paypal->/orders.post({
+        intent: "CAPTURE",
+        purchase_units: [{
+                amount: {
+                    currency_code: "USD",
+                    value: "100.00"
+                }
+            }]
+    });
+}
+```
+
+### Step 4: Run the Ballerina application
+
+```bash
+bal run
+```
 
 ## Examples
 
-The `Paypal Orders` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-paypal.orders/tree/main/examples/), covering the following use cases:
+The `PayPal Orders` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-paypal.orders/tree/main/examples/), covering the following use cases:
+
+1. [**Order lifecycle**](https://github.com/ballerina-platform/module-ballerinax-paypal.orders/tree/main/examples/order-lifecycle): Process a complete PayPal order from creation and updates through confirming and capturing payments.
 
-[//]: # (TODO: Add examples)
+2. [**Manage shipping**](https://github.com/ballerina-platform/module-ballerinax-paypal.orders/tree/main/examples/manage-shipping): Enrich an order with shipping details, add or update tracking information, and push shipment updates back to PayPal.

ballerina/tests/README.md

@@ -0,0 +1,63 @@
+# Running Tests
+
+## Prerequisites
+
+- OAuth2 credentials (Client ID & Secret) from your PayPal Developer account.
+
+## Test Environments
+
+There are two test environments for the PayPal Orders connector tests:
+
+| Test Group   | Environment                          |
+| ------------ | ------------------------------------ |
+| `mock_tests` | Mock server for PayPal API (default) |
+| `live_tests` | PayPal Sandbox API                   |
+
+## Running Tests with the Mock Server
+
+### Configure the `Config.toml` file
+
+Create a `Config.toml` file in the `/tests` directory with the following content:
+
+```toml
+isLiveServer = false
+```
+
+Then, run the following command to run the tests:
+
+```bash
+./gradlew clean test
+```
+
+## Running Tests with the PayPal Sandbox API
+
+### Configure the `Config.toml` file
+
+Create a `Config.toml` file in the `/tests` directory with the following content:
+
+```toml
+isLiveServer = true
+
+clientId = "<your-paypal-client-id>"
+clientSecret = "<your-paypal-client-secret>"
+```
+
+Then, run the following command to run the tests:
+
+```bash
+./gradlew clean test
+```
+
+## Running Specific Groups or Test Cases
+
+To run only certain test groups or individual test cases, pass the -Pgroups property:
+
+```bash
+./gradlew clean test -Pgroups=<comma-separated-groups-or-test-cases>
+```
+
+For example, to run only the mock tests:
+
+```bash
+./gradlew clean test -Pgroups=mock_tests
+```