Merge pull request #12 from Nuvindu/example-docs

Add mock service to grant security tokens

README.md

@@ -39,7 +39,7 @@ In order to use the DocuSign eSignature connector, you need to first create the
 
     <img src="https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-docusign/main/ballerina/resources/add-secret-key.png" alt="Add Secret Key" width="50%">
 
-### Step 3: Generate access token
+### Step 3: Generate refresh token
 
 1. **Add a redirect URI**: Click on "Add URI" and enter your redirect URI (e.g., <http://www.example.com/callback>).
 
@@ -53,9 +53,9 @@ In order to use the DocuSign eSignature connector, you need to first create the
     https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id={iKey}&redirect_uri={redirectUri}
     ```
 
-    This will redirect you to your Redirect URI with a `code` query parameter. This is your Authorization Code.
+    This will redirect you to your Redirect URI with a `code` query parameter. This is your authorization code.
 
-4. **Get the access token**: Use the following `curl` command to get the access token, replacing `{encodedKey}` with your Encoded Key and `{codeFromUrl}` with your authorization code:
+4. **Get the refresh token**: Use the following `curl` command to get the refresh token, replacing `{encodedKey}` with your Encoded Key and `{codeFromUrl}` with your authorization code:
 
     ```bash
     curl --location 'https://account-d.docusign.com/oauth/token' \
@@ -65,7 +65,7 @@ In order to use the DocuSign eSignature connector, you need to first create the
     --data-urlencode 'grant_type=authorization_code'
     ```
 
-    The response will contain your access token.
+    The response will contain your refresh token. Use `https://account-d.docusign.com/oauth/token` as the refresh URL.
 
 Remember to replace `{IntegrationKey:SecretKey}`, `{iKey}`, `{redirectUri}`, `{encodedKey}`, and `{codeFromUrl}` with your actual values.
 

ballerina/Dependencies.toml

@@ -217,6 +217,9 @@ dependencies = [
 	{org = "ballerina", name = "lang.value"},
 	{org = "ballerina", name = "observe"}
 ]
+modules = [
+	{org = "ballerina", packageName = "log", moduleName = "log"}
+]
 
 [[package]]
 org = "ballerina"
@@ -313,6 +316,7 @@ dependencies = [
 	{org = "ballerina", name = "http"},
 	{org = "ballerina", name = "io"},
 	{org = "ballerina", name = "lang.array"},
+	{org = "ballerina", name = "log"},
 	{org = "ballerina", name = "mime"},
 	{org = "ballerina", name = "os"},
 	{org = "ballerina", name = "test"},

ballerina/Module.md

@@ -26,7 +26,7 @@ In order to use the DocuSign eSignature connector, you need to first create the
 
     ![Add secret key](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-docusign/main/ballerina/resources/add-secret-key.png)
 
-### Step 3: Generate access token
+### Step 3: Generate refresh token
 
 1. **Add a redirect URI**: Click on "Add URI" and enter your redirect URI (e.g., <http://www.example.com/callback>).
 
@@ -42,7 +42,7 @@ In order to use the DocuSign eSignature connector, you need to first create the
 
     This will redirect you to your Redirect URI with a `code` query parameter. This is your Authorization Code.
 
-4. **Get the access token**: Use the following `curl` command to get the access token, replacing `{encodedKey}` with your Encoded Key and `{codeFromUrl}` with your authorization code:
+4. **Get the refresh token**: Use the following `curl` command to get the refresh token, replacing `{encodedKey}` with your Encoded Key and `{codeFromUrl}` with your authorization code:
 
     ```bash
     curl --location 'https://account-d.docusign.com/oauth/token' \
@@ -52,7 +52,7 @@ In order to use the DocuSign eSignature connector, you need to first create the
     --data-urlencode 'grant_type=authorization_code'
     ```
 
-    The response will contain your access token.
+    The response will contain your refresh token. Use `https://account-d.docusign.com/oauth/token` as the refresh URL.
 
 Remember to replace `{IntegrationKey:SecretKey}`, `{iKey}`, `{redirectUri}`, `{encodedKey}`, and `{codeFromUrl}` with your actual values.
 

ballerina/Package.md

@@ -26,7 +26,7 @@ In order to use the DocuSign eSignature connector, you need to first create the
 
     ![Add secret key](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-docusign/main/ballerina/resources/add-secret-key.png)
 
-### Step 3: Generate access token
+### Step 3: Generate refresh token
 
 1. **Add a redirect URI**: Click on "Add URI" and enter your redirect URI (e.g., <http://www.example.com/callback>).
 
@@ -42,7 +42,7 @@ In order to use the DocuSign eSignature connector, you need to first create the
 
     This will redirect you to your Redirect URI with a `code` query parameter. This is your Authorization Code.
 
-4. **Get the access token**: Use the following `curl` command to get the access token, replacing `{encodedKey}` with your Encoded Key and `{codeFromUrl}` with your authorization code:
+4. **Get the refresh token**: Use the following `curl` command to get the refresh token, replacing `{encodedKey}` with your Encoded Key and `{codeFromUrl}` with your authorization code:
 
     ```bash
     curl --location 'https://account-d.docusign.com/oauth/token' \
@@ -52,7 +52,7 @@ In order to use the DocuSign eSignature connector, you need to first create the
     --data-urlencode 'grant_type=authorization_code'
     ```
 
-    The response will contain your access token.
+    The response will contain your refresh token. Use `https://account-d.docusign.com/oauth/token` as the refresh URL.
 
 Remember to replace `{IntegrationKey:SecretKey}`, `{iKey}`, `{redirectUri}`, `{encodedKey}`, and `{codeFromUrl}` with your actual values.
 

ballerina/tests/Config.toml

@@ -2,6 +2,6 @@
 clientId = "mock-client-id"
 clientSecret = "mock-client-secret"
 refreshToken = "mock-refresh-token"
-refreshUrl = "http://mock-refresh-url.com/token"
+refreshUrl = "http://localhost:9444/oauth2/token"
 accountId = "mock-account-id"
 userId = "mock-user-id"

ballerina/tests/sts_mock_service.bal

@@ -0,0 +1,41 @@
+// Copyright (c) 2024, WSO2 LLC. (http://www.wso2.com) All Rights Reserved.
+//
+// WSO2 LLC. licenses this file to you under the Apache License,
+// Version 2.0 (the "License"); you may not use this file except
+// in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import ballerina/http;
+import ballerina/log;
+
+configurable int HTTP_SERVER_PORT = 9444;
+configurable int TOKEN_VALIDITY_PERIOD = 10000; // in seconds
+
+listener http:Listener sts = new (HTTP_SERVER_PORT);
+
+service /oauth2 on sts {
+
+    function init() {
+        log:printInfo("Mock security token service started on port: " + HTTP_SERVER_PORT.toString() + " (HTTP)");
+    }
+
+    // This issues an access token with reference to the received grant type (client credentials, password and refresh token grant type).
+    resource function post token(http:Request req) returns json {
+        json response = {
+            "access_token": "dskjbdsfJBDABJDnklsa2p93un03",
+            "token_type": "mock-token",
+            "expires_in": TOKEN_VALIDITY_PERIOD,
+            "example_parameter": "example_value"
+        };
+        return response;
+    }
+}

examples/README.md

@@ -2,22 +2,25 @@
 
 The DocuSign eSignature connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-docusign.dsesign/tree/main/examples).
 
-1. [Send Documents for eSignatures](https://github.com/ballerina-platform/module-ballerinax-docusign.dsesign/tree/main/examples/send-documents-for-esignatures)
+1. [Send documents for esignatures](https://github.com/ballerina-platform/module-ballerinax-docusign.dsesign/tree/main/examples/send-documents-for-esignatures)
     This example shows how to use DocuSign eSignature APIs to send envelope to recipients to add their respective esignatures to documents in the envelope.
 
-2. [Create eSignatures](https://github.com/ballerina-platform/module-ballerinax-docusign.dsesign/tree/main/examples/create-digital-signatures)
+2. [Create esignatures](https://github.com/ballerina-platform/module-ballerinax-docusign.dsesign/tree/main/examples/create-digital-signatures)
     This example shows how to create a eSignature for your DocuSign account.
 
 ## Prerequisites
 
 1. Follow the [instructions](https://github.com/ballerina-platform/module-ballerinax-docusign.dsesign#set-up-guide) to set up the DocuSign eSignature API.
 
-2. For each example, create a `Config.toml` file with your OAuth2 tokens, client ID, and client secret. Here's an example of how your `Config.toml` file should look:
+2. For each example, create a `Config.toml` file with your OAuth2 tokens, account ID, and user ID. Here's an example of how your `Config.toml` file should look:
 
     ```toml
-    accessToken = <Access Token>
-    accountId = <Account ID>
-    userId = <User ID>
+    clientId = <CLIENT_ID>
+    clientSecret = <CLIENT_SECRET>
+    refreshToken = <REFRESH_TOKEN>
+    refreshUrl = <REFRESH_URL>
+    accountId = <ACCOUNT_ID>
+    userId = <USER_ID>
     ```
 
 ## Running an Example

examples/create-digital-signatures/main.bal

@@ -21,15 +21,19 @@ import ballerinax/docusign.dsesign;
 
 configurable string accountId = os:getEnv("ACCOUNT_ID");
 configurable string userId = os:getEnv("USER_ID");
+configurable string clientId = os:getEnv("CLIENT_ID");
+configurable string clientSecret = os:getEnv("CLIENT_SECRET");
+configurable string refreshToken = os:getEnv("REFRESH_TOKEN");
+configurable string refreshUrl = os:getEnv("REFRESH_URL");
 
 public function main() returns error? {
     dsesign:Client docusignClient = check new (
         {
             auth: {
-                clientId: os:getEnv("CLIENT_ID"),
-                clientSecret: os:getEnv("CLIENT_SECRET"),
-                refreshToken: os:getEnv("REFRESH_TOKEN"),
-                refreshUrl: os:getEnv("REFRESH_URL")
+                clientId: clientId,
+                clientSecret: clientSecret,
+                refreshToken: refreshToken,
+                refreshUrl: refreshUrl
             }
         },
         serviceUrl = "https://demo.docusign.net/restapi/"

examples/send-documents-for-esignatures/main.bal

@@ -21,15 +21,19 @@ import ballerinax/docusign.dsesign;
 
 configurable string accountId = os:getEnv("ACCOUNT_ID");
 configurable string userId = os:getEnv("USER_ID");
+configurable string clientId = os:getEnv("CLIENT_ID");
+configurable string clientSecret = os:getEnv("CLIENT_SECRET");
+configurable string refreshToken = os:getEnv("REFRESH_TOKEN");
+configurable string refreshUrl = os:getEnv("REFRESH_URL");
 
 public function main() returns error? {
     dsesign:Client docusignClient = check new (
         {
             auth: {
-                clientId: os:getEnv("CLIENT_ID"),
-                clientSecret: os:getEnv("CLIENT_SECRET"),
-                refreshToken: os:getEnv("REFRESH_TOKEN"),
-                refreshUrl: os:getEnv("REFRESH_URL")
+                clientId: clientId,
+                clientSecret: clientSecret,
+                refreshToken: refreshToken,
+                refreshUrl: refreshUrl
             }
         },
         serviceUrl = "https://demo.docusign.net/restapi/"