Add Examples and Documentation

.gitignore

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

README.md

@@ -6,30 +6,85 @@
 
 ## Overview
 
-[//]: # (TODO: Add overview mentioning the purpose of the module, supported REST API versions, and other high-level details.)
+[Trello](https://trello.com/) is a popular web-based project management and collaboration platform developed by Atlassian, allowing users to organize tasks, projects, and workflows using boards, lists, and cards.
+
+The `ballerinax/trello` package provides APIs to connect and interact with [Trello's RESTful API endpoints](https://developer.atlassian.com/cloud/trello/rest/api-group-actions/), enabling developers to seamlessly manage boards, lists, cards, and other Trello resources.
 
 ## Setup guide
 
-[//]: # (TODO: Add detailed steps to obtain credentials and configure the module.)
+To use the Trello connector, you must have access to the Trello API through a Trello account and an API key and token generated from it. If you do not have a Trello account, you can sign up for one [here](https://id.atlassian.com/signup). You can generate your Trello API key and token by following the instructions at [Trello API Keys](https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/).
+
+
+1. Visit https://trello.com/power-ups/admin and create a new powerup
+
+   ![trello powerup](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-powerups.png)
+
+2. Enter the required details:
+   * Name of your Power-Up
+   * Iframe Connector URL (can be a placeholder URL during development)
+   Click “Create” to create your Power-Up.
+
+   ![trello powerup form](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-form.png)
+
+3. Navigate to 'API Key' and click on 'Generate'
+
+   ![generate trello apikey](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-generateKey.png)
+
+   Copy and securely store your API Key.
+
+4. Next to the API Key description, there's a link to the token.
+   Click the link, authorize the Power-Up, and you’ll be redirected to a page displaying your OAuth token.
+
+   ![get trello Key](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-key.png)
+
+   ![allow token](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-permission.png)
+
+   Copy and securely store the Token.
+
+   ![trello token](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-token.png)
 
 ## Quickstart
 
-[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.)
+To use the Trello connector in your Ballerina application, update the .bal file as follows:
+
+#### Step 1: Import the module
+
+Import the Trello module.
+
+```bash
+import ballerinax/trello;
+```
+
+#### Step 2: Instantiate a new connector
+
+Create a `Config.toml` file and configure the obtained credentials as follows:
+
+```bash
+key = "your_api_key"
+token = "your_api_token"
+```
+
+#### Step 3: Invoke the connector operation
+
+Now, utilize the available connector operations.
+
+Create a card
 
 ## Examples
 
 The `Trello` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-trello/tree/main/examples/), covering the following use cases:
 
-[//]: # (TODO: Add examples)
+1. [**Create and Retrieve a List and Cards in Trello**](examples/Create_list/) - Create a new list in a specific Trello board and retrieve its details using the list ID.
+2. [**Create, Update fetch add label to a Card in Trello**](examples/Create_card/) - Create a new card in a Trello list and update the card's name and view it.
 
 ## 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.
 
@@ -41,10 +96,10 @@ The `Trello` connector provides practical examples illustrating usage in various
 
 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 +143,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 +165,7 @@ All the contributors are encouraged to read the [Ballerina Code of Conduct](http
 
 ## Useful links
 
-* For more information go to the [`trello` package](https://central.ballerina.io/ballerinax/trello/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 [`trello` package](https://central.ballerina.io/ballerinax/trello/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/README.md

@@ -1,17 +1,74 @@
+# Ballerina Trello connector
+
 ## Overview
 
-[//]: # (TODO: Add overview mentioning the purpose of the module, supported REST API versions, and other high-level details.)
+[Trello](https://trello.com/) is a popular web-based project management and collaboration platform developed by Atlassian, allowing users to organize tasks, projects, and workflows using boards, lists, and cards.
+
+The `ballerinax/trello` package provides APIs to connect and interact with [Trello's RESTful API endpoints](https://developer.atlassian.com/cloud/trello/rest/api-group-actions/), enabling developers to seamlessly manage boards, lists, cards, and other Trello resources.
 
 ## Setup guide
 
-[//]: # (TODO: Add detailed steps to obtain credentials and configure the module.)
+To use the Trello connector, you must have access to the Trello API through a Trello account and an API key and token generated from it. If you do not have a Trello account, you can sign up for one [here](https://id.atlassian.com/signup). You can generate your Trello API key and token by following the instructions at [Trello API Keys](https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/).
+
+
+1. Visit https://trello.com/power-ups/admin and create a new powerup
+
+   ![trello powerup](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-powerups.png)
+
+2. Enter the required details:
+   * Name of your Power-Up
+   * Iframe Connector URL (can be a placeholder URL during development)
+   Click “Create” to create your Power-Up.
+
+   ![trello powerup form](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-form.png)
+
+3. Navigate to 'API Key' and click on 'Generate'
+
+   ![generate trello apikey](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-generateKey.png)
+
+   Copy and securely store your API Key.
+
+4. Next to the API Key description, there's a link to the token.
+   Click the link, authorize the Power-Up, and you’ll be redirected to a page displaying your OAuth token.
+
+   ![get trello Key](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-key.png)
+
+   ![allow token](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-permission.png)
+
+   Copy and securely store the Token.
+
+   ![trello token](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-trello/refs/heads/main/docs/setup/resources/trello-token.png)
 
 ## Quickstart
 
-[//]: # (TODO: Add a quickstart guide to demonstrate a basic functionality of the module, including sample code snippets.)
+To use the Trello connector in your Ballerina application, update the .bal file as follows:
+
+#### Step 1: Import the module
+
+Import the Trello module.
+
+```bash
+import ballerinax/trello;
+```
+
+#### Step 2: Instantiate a new connector
+
+Create a `Config.toml` file and configure the obtained credentials as follows:
+
+```bash
+key = "your_api_key"
+token = "your_api_token"
+```
+
+#### Step 3: Invoke the connector operation
+
+Now, utilize the available connector operations.
+
+Create a card
 
 ## Examples
 
 The `Trello` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-trello/tree/main/examples/), covering the following use cases:
 
-[//]: # (TODO: Add examples)
+1. [**Create and Retrieve a List and Cards in Trello**](examples/Create_list/) - Create a new list in a specific Trello board and retrieve its details using the list ID.
+2. [**Create, Update fetch add label to a Card in Trello**](examples/Create_card/) - Create a new card in a Trello list and update the card's name and view it.

ballerina/tests/README.md

@@ -0,0 +1,105 @@
+# Running Tests
+
+## Prerequisites
+
+To run tests for the Trello connector, you will need:
+
+- A Trello account.
+- A Power-Up created via the Trello Developer Portal.
+- Your API Key and API Token, which you can obtain from the Trello API Key page.
+- The Board ID, List ID, and optionally Card IDs to test live APIs.
+
+## Running Tests
+
+The Trello connector supports two environments for testing:
+
+| Test Group   | Environment                            |
+| ------------ | -------------------------------------- |
+| `mock_tests` | Mock server for Trello API _(default)_ |
+| `live_tests` | Actual Trello API                      |
+
+Use the `isLiveServer` configuration to switch between environments.
+
+Please ensure that the `boardId`, `listId`, and `cardId` values correspond to actual resources in your Trello account and boards when running tests against the live API.
+
+## Running Tests in the Mock Server
+
+### 🔹 Option 1: Using `Config.toml` in the `tests/` Directory
+
+Create a file named `Config.toml` in the `tests/` folder with the following content:
+
+```toml
+[ballerinax.trello]
+key = "api-key"
+token = "api-token"
+isLiveServer = false
+```
+
+Set `isLiveServer` to false in `Config.toml` to set mock test environment
+
+Then, run the following command to run the tests:
+
+```
+   ./gradlew clean test
+
+```
+
+### 🔹Option 2: Using Environment Variables
+
+Linux/macOS
+
+```
+export key="api-key"
+export token="api-token"
+export isLiveServer = false
+```
+
+Windows
+
+```
+setx key "api-key"
+setx token "api-token"
+setx isLiveServer = false
+```
+
+## Running Tests Against Trello Live API
+
+**Using a Config.toml File**
+
+Create a Config.toml file in the tests directory and add your authentication credentials as follows
+
+```
+token = "<your-trellor-access-token>"
+key = "<your-trello-key>"
+isLiveServer = true
+```
+
+Set `isLiveServer` to true in `Config.toml` to set live test environment
+
+Note that you have to use your real trello Board and List IDs when testing in the live environment.
+
+**Using Environment Variables**
+
+Alternatively, you can set your authentication credentials as environment variables:
+
+If you are using linux or mac, you can use following method:
+
+```
+   export token ="<your-trello-access-token>"
+   export key ="<your-trello-key>"
+   export isLiveServeer = true
+```
+
+If you are using Windows you can use following method:
+
+```
+   setx token "<your-trello-access-token>"
+   setx key  "<your-trello-key>"
+   setx isLiveServer = true
+```
+
+Then, run the following command to run the tests:
+
+```
+./gradlew clean test
+```

ballerina/tests/tests.bal

@@ -16,17 +16,14 @@
 
 import ballerina/test;
 
-configurable string key = ?;
-configurable string token = ?;
-configurable boolean isLiveServer = ?;
+configurable boolean isLiveServer = true;
+configurable string key = "1234567890abcdef1234567890abcdef";
+configurable string token = "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890";
+configurable string baseUrl = "http://localhost:9090";
 
 string testBoardID = "8SnkvBJj";
 string testListID = "68539f5c1899d49ed12e804e";
 
-string mockBaseUrl = "http://localhost:9090";
-string liveBaseUrl = "https://api.trello.com/1";
-string baseUrl = isLiveServer ? liveBaseUrl : mockBaseUrl;
-
 ApiKeysConfig apiKeyConfig = {
     key,
     token

examples/Create_card/Ballerina.toml

@@ -0,0 +1,8 @@
+[package]
+org = "wso2"
+name = "create_card"
+version = "0.1.0"
+distribution = "2201.12.7"
+
+[build-options]
+observabilityIncluded = true

examples/Create_card/README.md

@@ -0,0 +1,37 @@
+# Create, Update fetch add label to a Card in Trello
+
+This example demonstrates how to use the Trello API with Ballerina to create a card in a specific Trello list, update its name, and add a label to it. This use case is useful for automating task management workflows where card creation, modification, and labeling are performed programmatically.
+
+---
+
+## Prerequisites
+
+### 1. Trello Developer Access
+
+Refer to the [Setup guide](../../README.md) to obtain necessary credentials (client Id, client secret, tokens).
+
+### 2. Board and List
+
+Before running the example, make sure you have:
+- A valid **Board ID**
+- A **List ID** under that board where the card will be created
+
+You can retrieve the list ID from the URL of the list in Trello or by calling Trello's `GET /boards/{id}/lists` endpoint.
+
+---
+## Configuration
+
+Create a file named `Config.toml` in the root directory of this example with the following content:
+
+```toml
+key = "<Your Trello API Key>"
+token = "<Your Trello API Token>"
+```
+
+## Run the example
+
+Execute the following command to run the example:
+
+```bash
+bal run
+```