Merge pull request #4 from Nuvindu/review-updates

Apply review changes to the connector

README.md

@@ -7,15 +7,9 @@
 [![GitHub Issues](https://img.shields.io/github/issues/ballerina-platform/ballerina-library/module/docusign.dsadmin.svg?label=Open%20Issues)](https://github.com/ballerina-platform/ballerina-library/labels/module%2Fdocusign.dsadmin)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-The DocuSign Admin connector can be used for managing user permissions in accounts and domains. The connector enables you to streamline administrative tasks, ensuring smooth user management and permissions control for enhanced governance.
+DocuSign is a digital transaction management platform that enables users to securely sign, send, and manage documents electronically.
 
-- [docusign.dsadmin](ballerina/Module.md) - Perform DocuSign Admin related operations
-
-## Overview
-
-The Ballerina Docusign Admin Connector efficiently manages DocuSign users and permissions across all your accounts and domains
-
-The Ballerina Docusign Admin module supports [DocuSign Admin API V2](https://github.com/docusign/OpenAPI-Specifications/blob/master/admin.rest.swagger-v2.1.json).
+The Ballerina DocuSign Admin connector integrates with the DocuSign platform, provides APIs to efficiently manages DocuSign users and permissions across all the accounts and domains within Ballerina applications. It supports [DocuSign Admin API V2](https://github.com/docusign/OpenAPI-Specifications/blob/master/admin.rest.swagger-v2.1.json).
 
 ## Setup guide
 

ballerina/Ballerina.toml

@@ -2,10 +2,10 @@
 distribution = "2201.8.4"
 org = "ballerinax"
 name = "docusign.dsadmin"
-version = "1.0.0"
+version = "2.0.0"
 license = ["Apache-2.0"]
 authors = ["Ballerina"]
-keywords = ["eSignature", "Cost/Freemium", "Administration", "Collaboration", "Digital Signature"]
+keywords = ["eSignature", "Cost/Freemium", "Administration", "Admin API", "Collaboration", "Digital Signature"]
 icon = "icon.png"
 repository = "https://github.com/ballerina-platform/module-ballerinax-docusign"
 

ballerina/Dependencies.toml

@@ -5,7 +5,7 @@
 
 [ballerina]
 dependencies-toml-version = "2"
-distribution-version = "2201.8.0-20230830-220400-8a7556d8"
+distribution-version = "2201.8.6"
 
 [[package]]
 org = "ballerina"
@@ -61,7 +61,7 @@ dependencies = [
 [[package]]
 org = "ballerina"
 name = "http"
-version = "2.10.8"
+version = "2.10.11"
 dependencies = [
 	{org = "ballerina", name = "auth"},
 	{org = "ballerina", name = "cache"},
@@ -317,7 +317,7 @@ modules = [
 [[package]]
 org = "ballerinax"
 name = "docusign.dsadmin"
-version = "1.0.0"
+version = "2.0.0"
 dependencies = [
 	{org = "ballerina", name = "http"},
 	{org = "ballerina", name = "log"},

ballerina/Module.md

@@ -1,8 +1,8 @@
 ## Overview
 
-The Ballerina Docusign Admin Connector efficiently manages DocuSign users and permissions across all your accounts and domains
+DocuSign is a digital transaction management platform that enables users to securely sign, send, and manage documents electronically.
 
-The Ballerina Docusign Admin module supports [DocuSign Admin API V2](https://github.com/docusign/OpenAPI-Specifications/blob/master/admin.rest.swagger-v2.1.json).
+The Ballerina DocuSign Admin connector integrates with the DocuSign platform, provides APIs to efficiently manages DocuSign users and permissions across all the accounts and domains within Ballerina applications. It supports [DocuSign Admin API V2](https://github.com/docusign/OpenAPI-Specifications/blob/master/admin.rest.swagger-v2.1.json).
 
 ## Setup guide
 

ballerina/Package.md

@@ -1,8 +1,8 @@
 ## Package overview
 
-The Ballerina Docusign Admin Connector efficiently manages DocuSign users and permissions across all your accounts and domains
+DocuSign is a digital transaction management platform that enables users to securely sign, send, and manage documents electronically.
 
-The Ballerina Docusign Admin module supports [DocuSign Admin API V2](https://github.com/docusign/OpenAPI-Specifications/blob/master/admin.rest.swagger-v2.1.json).
+The Ballerina DocuSign Admin connector integrates with the DocuSign platform, provides APIs to efficiently manages DocuSign users and permissions across all the accounts and domains within Ballerina applications. It supports [DocuSign Admin API V2](https://github.com/docusign/OpenAPI-Specifications/blob/master/admin.rest.swagger-v2.1.json).
 
 ## Setup guide
 

ballerina/client.bal

@@ -25,7 +25,7 @@ public isolated client class Client {
     # + config - The configurations to be used when initializing the `connector` 
     # + serviceUrl - URL of the target service 
     # + return - An error if connector initialization failed 
-    public isolated function init(ConnectionConfig config, string serviceUrl = "https://api-d.docusign.net/management") returns error? {
+    public isolated function init(string serviceUrl, *ConnectionConfig config) returns error? {
         http:ClientConfiguration httpClientConfig = {auth: config.auth, httpVersion: config.httpVersion, timeout: config.timeout, forwarded: config.forwarded, poolConfig: config.poolConfig, compression: config.compression, circuitBreaker: config.circuitBreaker, retryConfig: config.retryConfig, validation: config.validation};
         do {
             if config.http1Settings is ClientHttp1Settings {

ballerina/tests/admin-test.bal

@@ -31,7 +31,7 @@ configurable string email = ?;
 @test:BeforeSuite
 function initializeClientsForDocuSignServer() returns error? {
     if isTestOnLiveServer {
-        docuSignClient = check new(
+        docuSignClient = check new("https://api-d.docusign.net/management/",
             {
                 timeout: 10000,
                 auth: {
@@ -40,11 +40,10 @@ function initializeClientsForDocuSignServer() returns error? {
                     refreshToken: os:getEnv("REFRESH_TOKEN"),
                     refreshUrl: os:getEnv("REFRESH_URL")
                 }
-            },
-            serviceUrl = "https://api-d.docusign.net/management/"
+            }
         );
     } else {
-        docuSignClient = check new(
+        docuSignClient = check new("http://localhost:9090/management",
             {
                 timeout: 10000,
                 auth: {
@@ -53,8 +52,7 @@ function initializeClientsForDocuSignServer() returns error? {
                     refreshToken,
                     refreshUrl
                 }
-            },
-            serviceUrl = "http://localhost:9090/management"
+            }
         );
     }
 }

build-config/resources/Ballerina.toml

@@ -5,7 +5,7 @@ name = "docusign.dsadmin"
 version = "@toml.version@"
 license = ["Apache-2.0"]
 authors = ["Ballerina"]
-keywords = ["eSignature", "Cost/Freemium", "Administration", "Collaboration", "Digital Signature"]
+keywords = ["eSignature", "Cost/Freemium", "Administration", "Admin API", "Collaboration", "Digital Signature"]
 icon = "icon.png"
 repository = "https://github.com/ballerina-platform/module-ballerinax-docusign"
 

docs/spec/sanitations.md

@@ -0,0 +1,23 @@
+# Sanitations for OpenAPI specification
+
+_Authors_: @Nuvindu \
+_Reviewers_: @shafreenAnfar @ThisaruGuruge \
+_Created_: 2024/03/13 \
+_Updated_: 2024/02/13 \
+_Edition_: Swan Lake
+
+## Introduction
+
+The Ballerina DocuSign Admin connector facilitates integration with the [DocuSign Admin API](https://developers.docusign.com/docs/admin-api/reference) through the generation of client code using the [OpenAPI specification](https://github.com/ballerina-platform/module-ballerinax-docusign.dsadmin/blob/main/docs/spec/openapi.json). To enhance usability, the following modifications have been applied to the original specification.
+
+1. Response descriptions
+Previously, all responses for resource functions were labeled with a generic "Successful Response". This has been revised to "A successful response or an error".
+
+2. Avoid path segments with backslashes
+To prevent errors associated with backslashes in the resource path, the functions in the format, `get v2\.1/accounts/.../` have been modified as `get accounts/.../` to avoid broken paths in the API calls.
+
+## OpenAPI cli command
+
+```bash
+bal openapi -i docs/spec/openapi.json --mode client -o ballerina
+```

examples/README.md

@@ -10,7 +10,7 @@ The DocuSign Admin connector provides practical examples illustrating usage in v
 
 ## Prerequisites
 
-1. Follow the [instructions](https://github.com/ballerina-platform/module-ballerinax-docusign.dsadmin#set-up-guide) to set up the DocuSign Click API.
+1. Follow the [instructions](https://github.com/ballerina-platform/module-ballerinax-docusign.dsadmin#set-up-guide) to set up the DocuSign Admin 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:
 

examples/manage-user-information/create-and-retrieve-user-information.md

@@ -2,94 +2,27 @@
 
 This Ballerina program demonstrates the integration of the DocuSign Admin API to create a new user within an organization and retrieve information about that user. The example covers fetching organizations, creating a new user, and retrieving user details.
 
-## Step 1: Import DocuSign connector
+## Prerequisites
 
-Import the `ballerinax/docusign.dsadmin` module into your Ballerina project.
+Follow the guidelines in the [setup guide](https://github.com/ballerina-platform/module-ballerinax-docusign.dsadmin?tab=readme-ov-file#setup-guide) to get access to DocuSign APIs.
 
-```ballerina
-import ballerinax/docusign.dsadmin;
-import ballerina/io;
-```
-
-## Step 2: Setup DocuSign Admin connection
-
-Define configurable parameters such as `accessToken`, `accountId`, and `email` to set up the DocuSign Admin connection.
-
-```ballerina
-configurable string accessToken = ?;
-configurable string accountId = ?;
-configurable string email = ?;
-```
-
-## Step 3: Create DocuSign Admin client
+### Configuration
 
-Initialize the DocuSign Admin client with the specified service URL, connection configuration, and account ID.
+Configure DocuSign API credentials in Config.toml in the example directory.
 
-```ballerina
-dsadmin:Client docuSignClient = check new(
-    {
-        auth: {
-            token: accessToken
-        }
-    },
-    serviceUrl = "https://api-d.docusign.net/management"
-);
+```toml
+accountId = "<ACCOUNT_ID>"
+userId = "<USER_ID>"
+clientId = "<CLIENT_ID>"
+clientSecret = "<CLIENT_SECRET>"
+refreshToken = "<REFRESH_TOKEN>"
+refreshUrl = "<REFRESH_URL>"
 ```
 
-## Step 4: Fetch organizations
+## Run the example
 
-Retrieve information about organizations associated with the provided access token.
+Execute the following command to run the example.
 
 ```ballerina
-dsadmin:OrganizationsResponse orgResponse = check docuSignClient->/v2/organizations();
-io:println("Organizations: ", orgResponse);
-```
-
-## Step 5: Create a new user
-
-Create a new user within the organization and associate them with the specified account.
-
-```ballerina
-dsadmin:OrganizationResponse[]? organizations = orgResponse.organizations;
-if organizations !is dsadmin:OrganizationResponse[] {
-    io:println("Error: organizations not found");
-    return;
-}
-
-dsadmin:OrganizationResponse organization = organizations[0];
-string? organizationId = organization.id;
-if organizationId == () {
-    io:println("Error: organization id not found");
-    return;
-}
-
-dsadmin:NewUserRequest newUserReq = {
-    user_name: "user1",
-    first_name: "name1",
-    email: "user1@docusignmail.com",
-    accounts: [
-        {
-            id: accountId,
-            company_name: "Company"
-        }
-    ]
-};
-
-dsadmin:NewUserResponse newUserResponse = check docuSignClient->/v2/organizations/[organizationId]/users.post(newUserReq);
-io:println("New user created: ", newUserResponse);
-```
-
-## Step 6: Retrieve user information
-
-Retrieve information about a specific user within the organization and account.
-
-```ballerina
-string? userId = newUserResponse.id;
-if userId == () {
-    io:println("Error: user id not found");
-    return;
-}
-
-dsadmin:OrganizationUsersResponse userInformation = check docuSignClient->/v2/organizations/[organizationId]/users(account_id = accountId, email = email);
-io:println("User Information in the Organization: ", userInformation);
+bal run
 ```

examples/manage-user-information/main.bal

@@ -25,16 +25,20 @@ configurable string refreshUrl = os:getEnv("REFRESH_URL");
 configurable string accountId = os:getEnv("ACCOUNT_ID");
 configurable string userId = os:getEnv("USER_ID");
 configurable string email = os:getEnv("EMAIL");
+configurable string serviceUrl = os:getEnv("SERVICE_URL");
 
 public function main() returns error? {
-    dsadmin:Client docuSignClient = check new ({
-        auth: {
-            clientId,
-            clientSecret,
-            refreshToken,
-            refreshUrl
+    dsadmin:Client docuSignClient = check new (
+        serviceUrl,
+        {
+            auth: {
+                clientId,
+                clientSecret,
+                refreshToken,
+                refreshUrl
+            }
         }
-    });
+    );
 
     dsadmin:OrganizationsResponse orgResponse = check docuSignClient->/v2/organizations();
     io:println("Organizations: ", orgResponse);

examples/permissions-in-organizations/main.bal

@@ -24,16 +24,20 @@ configurable string refreshToken = os:getEnv("REFRESH_TOKEN");
 configurable string refreshUrl = os:getEnv("REFRESH_URL");
 configurable string accountId = os:getEnv("ACCOUNT_ID");
 configurable string email = os:getEnv("EMAIL");
+configurable string serviceUrl = os:getEnv("SERVICE_URL");
 
 public function main() returns error? {
-    dsadmin:Client docuSignClient = check new ({
-        auth: {
-            clientId,
-            clientSecret,
-            refreshToken,
-            refreshUrl
+    dsadmin:Client docuSignClient = check new (
+        serviceUrl,
+        {
+            auth: {
+                clientId,
+                clientSecret,
+                refreshToken,
+                refreshUrl
+            }
         }
-    });
+    );
 
     dsadmin:OrganizationsResponse orgResponse = check docuSignClient->/v2/organizations();
     io:println("Organizations: ", orgResponse);