Merge pull request #264 from niveathika/master

Improve documentations

README.md

@@ -11,7 +11,7 @@
 
 The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints, specifically based on [Gmail API v1](https://gmail.googleapis.com/$discovery/rest?version=v1).
 
-## Set up guide
+## Setup guide
 
 To use the Gmail connector, you must have access to the Gmail REST API through a [Google Cloud Platform (GCP)](https://console.cloud.google.com/) account and a project under it. If you do not have a GCP account, you can sign up for one [here](https://cloud.google.com/).
 
@@ -79,7 +79,7 @@ To use the `gmail` connector in your Ballerina application, modify the `.bal` fi
 
 ### Step 1: Import the connector
 
-Import the `ballerinax/googleapis.gmail` package into your Ballerina project.
+Import the `ballerinax/googleapis.gmail` package.
 
 ```ballerina
 import ballerinax/googleapis.gmail;
@@ -90,7 +90,7 @@ import ballerinax/googleapis.gmail;
 Create a `gmail:ConnectionConfig` with the obtained OAuth2.0 tokens and initialize the connector with it.
 
 ```ballerina
-gmail:Client gmailClient = check new gmail:Client(
+gmail:Client gmail = check new gmail:Client(
     config = {
         auth: {
             refreshToken,
@@ -108,7 +108,7 @@ Now, utilize the available connector operations.
 #### Get unread emails in INBOX
 
 ```ballerina
-gmail:MessageListPage messageList = check gmailClient->/users/me/messages(q = "label:INBOX is:unread");
+gmail:MessageListPage messageList = check gmail->/users/me/messages(q = "label:INBOX is:unread");
 ```
 
 #### Send email
@@ -124,7 +124,7 @@ gmail:MessageRequest message = {
                         </html>`;
 };
 
-gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message);
+gmail:Message sendResult = check gmail->/users/me/messages/send.post(message);
 ```
 
 ## Examples

ballerina/Module.md

@@ -4,7 +4,7 @@
 
 The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints, specifically based on [Gmail API v1](https://gmail.googleapis.com/$discovery/rest?version=v1).
 
-## Set up guide
+## Setup guide
 
 To use the Gmail connector, you must have access to the Gmail REST API through a [Google Cloud Platform (GCP)](https://console.cloud.google.com/) account and a project under it. If you do not have a GCP account, you can sign up for one [here](https://cloud.google.com/).
 
@@ -72,7 +72,7 @@ To use the `gmail` connector in your Ballerina application, modify the `.bal` fi
 
 ### Step 1: Import the connector
 
-Import the `ballerinax/googleapis.gmail` package into your Ballerina project.
+Import the `ballerinax/googleapis.gmail` package.
 
 ```ballerina
 import ballerinax/googleapis.gmail;
@@ -83,7 +83,7 @@ import ballerinax/googleapis.gmail;
 Create a `gmail:ConnectionConfig` with the obtained OAuth2.0 tokens and initialize the connector with it.
 
 ```ballerina
-gmail:Client gmailClient = check new gmail:Client(
+gmail:Client gmail = check new gmail:Client(
     config = {
         auth: {
             refreshToken,
@@ -101,7 +101,7 @@ Now, utilize the available connector operations.
 #### Get unread emails in INBOX
 
 ```ballerina
-gmail:MessageListPage messageList = check gmailClient->/users/me/messages(q = "label:INBOX is:unread");
+gmail:MessageListPage messageList = check gmail->/users/me/messages(q = "label:INBOX is:unread");
 ```
 
 #### Send email
@@ -117,7 +117,7 @@ gmail:MessageRequest message = {
                         </html>`;
 };
 
-gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message);
+gmail:Message sendResult = check gmail->/users/me/messages/send.post(message);
 ```
 
 ## Examples

ballerina/Package.md

@@ -4,7 +4,7 @@
 
 The `ballerinax/googleapis.gmail` package offers APIs to connect and interact with [Gmail API](https://developers.google.com/gmail/api/guides) endpoints, specifically based on [Gmail API v1](https://gmail.googleapis.com/$discovery/rest?version=v1).
 
-## Set up guide
+## Setup guide
 
 To use the Gmail connector, you must have access to the Gmail REST API through a [Google Cloud Platform (GCP)](https://console.cloud.google.com/) account and a project under it. If you do not have a GCP account, you can sign up for one [here](https://cloud.google.com/).
 
@@ -72,7 +72,7 @@ To use the `gmail` connector in your Ballerina application, modify the `.bal` fi
 
 ### Step 1: Import the connector
 
-Import the `ballerinax/googleapis.gmail` package into your Ballerina project.
+Import the `ballerinax/googleapis.gmail` package.
 
 ```ballerina
 import ballerinax/googleapis.gmail;
@@ -83,7 +83,7 @@ import ballerinax/googleapis.gmail;
 Create a `gmail:ConnectionConfig` with the obtained OAuth2.0 tokens and initialize the connector with it.
 
 ```ballerina
-gmail:Client gmailClient = check new gmail:Client(
+gmail:Client gmail = check new gmail:Client(
     config = {
         auth: {
             refreshToken,
@@ -101,7 +101,7 @@ Now, utilize the available connector operations.
 #### Get unread emails in INBOX
 
 ```ballerina
-gmail:MessageListPage messageList = check gmailClient->/users/me/messages(q = "label:INBOX is:unread");
+gmail:MessageListPage messageList = check gmail->/users/me/messages(q = "label:INBOX is:unread");
 ```
 
 #### Send email
@@ -117,7 +117,7 @@ gmail:MessageRequest message = {
                         </html>`;
 };
 
-gmail:Message sendResult = check gmailClient->/users/me/messages/send.post(message);
+gmail:Message sendResult = check gmail->/users/me/messages/send.post(message);
 ```
 
 ## Examples

ballerina/modules/oas/client.bal

@@ -1,6 +1,22 @@
 // AUTO-GENERATED FILE. DO NOT MODIFY.
 // This file is auto-generated by the Ballerina OpenAPI tool.
 
+// Copyright (c) 2024, WSO2 LLC. (http://www.wso2.org).
+//
+// 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;
 
 # The Gmail API lets you view and manage Gmail mailbox data like threads, messages, and labels.

ballerina/modules/oas/types.bal

@@ -1,6 +1,22 @@
 // AUTO-GENERATED FILE. DO NOT MODIFY.
 // This file is auto-generated by the Ballerina OpenAPI tool.
 
+// Copyright (c) 2024, WSO2 LLC. (http://www.wso2.org).
+//
+// 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;
 
 # Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.

ballerina/modules/oas/utils.bal

@@ -1,6 +1,22 @@
 // AUTO-GENERATED FILE. DO NOT MODIFY.
 // This file is auto-generated by the Ballerina OpenAPI tool.
 
+// Copyright (c) 2024, WSO2 LLC. (http://www.wso2.org).
+//
+// 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/url;
 
 type SimpleBasicType string|boolean|int|float|decimal;

docs/license.txt

@@ -0,0 +1,18 @@
+// AUTO-GENERATED FILE. DO NOT MODIFY.
+// This file is auto-generated by the Ballerina OpenAPI tool.
+
+// Copyright (c) 2024, WSO2 LLC. (http://www.wso2.org).
+//
+// 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.

docs/open-api-spec/Sanitations.md → docs/spec/sanitizations.md

@@ -1,6 +1,6 @@
 # Introduction
 
-This file records the sanitation done on top of the OAS from APIs guru. Google uses Google discovery format to expose API details. APIs guru uses a conversion tool to change the discovery documentation to OAS. These sanitation's are done for improving usability and as workaround for known limitations in language side.
+This file records the sanitization done on top of the OAS from APIs guru. Google uses Google discovery format to expose API details. APIs guru uses a conversion tool to change the discovery documentation to OAS. These sanitization's are done for improving usability and as workaround for known limitations in language side.
 
 1. Fix request body content types. Here, Gmail API accepts all content type. AS per [Discovery Doc](https://developers.google.com/discovery/v1/reference/apis) only media upload content type is specified. This is mistakenly mapped to request body content type in APIs guru transformation.
 
@@ -19,5 +19,7 @@ This file records the sanitation done on top of the OAS from APIs guru. Google u
 ## OpenAPI cli command
 
 ```bash
-bal openapi -i docs/open-api-spec/openapi.yaml --mode client -o ballerina/modules/oas
+bal openapi -i docs/spec/openapi.yaml --mode client  --license docs/license.txt -o ballerina/modules/oas
 ```
+
+Note: The license year is hardcoded to 2024, change if necessary

docs/spec/spec.md

@@ -52,7 +52,7 @@ The `gmail:Client` allows you to connect to the Gmail RESTful API. The client cu
 The `gmail:Client` initialization method requires valid authentication credentials.
 
 ```ballerina
-gmail:Client gmailClient = check new gmail:Client (
+gmail:Client gmail = check new gmail:Client (
     config = {
         auth: {
             refreshToken,
@@ -81,7 +81,7 @@ public type Profile record {
 ### Example: Retrieving the Gmail profile
 
 ```ballerina
-Profile profile = check gmailClient->/users/me/profile();
+Profile profile = check gmail->/users/me/profile();
 ```
 
 In this example, the `getProfile` method retrieves the profile of the authenticated user. The `me` parameter represents the authenticated user.

docs/spec/wrapperClient.md

@@ -0,0 +1,83 @@
+# Introduction
+
+This document outlines significant enhancements made to the OpenAPI specification for the wrapper client. These updates introduce new functionalities and modify existing ones to enhance useability.
+
+## `MessageRequest` parameter
+
+The module will require `MessageRequest` record for users to give email data easily. These inputs are then transformed into RFC822 formatted encoded strings, facilitating integration with the generated client's operations. This enhancement has been applied across various resource functions, including draft, message, and thread.
+
+```ballerina
+# Message Send Request-Payload (Charset UTF-8 will be used to encode the message body).
+public type MessageRequest record {|
+    # The recipients of the mail
+    string[] to?;
+    # The sender of the mail
+    string 'from?;
+    # The subject of the mail
+    string subject?;
+    # The cc recipients of the mail.
+    string[] cc?;
+    # The bcc recipients of the mail.
+    string[] bcc?;
+    # Message body of content type ```text/plain```. 
+    string bodyInText?;
+    # Message body of content type ```text/html```.
+    string bodyInHtml?;
+    # The file array consisting the inline images.
+    ImageFile[] inlineImages?;
+    # The file array consisting the attachments.
+    AttachmentFile[] attachments?;
+    # ID of the thread the message must be replied to.
+    string threadId?;
+    # **Message-ID** header of the message being replied to.
+    string initialMessageId?;
+    # List of **Message-ID** headers identifying ancestors of the message being replied to.
+    string[] references?;
+|};
+```
+
+## `Message` payload
+
+The module will return `Message` record for any retrieved emails. This record includes wider array of email-related data, ensuring comprehensive coverage of email attributes. This refinement affects resource functions such as draft, message, and thread, ensuring a more structured and accessible presentation of email data.
+
+```ballerina
+# An email message.
+public type Message record {
+    # The ID of the thread the message belongs to. 
+    string threadId;
+    # The immutable ID of the message.
+    string id;
+    # List of IDs of labels applied to this message.
+    string[] labelIds?;
+    # The entire email message in an RFC 2822 formatted. Returned in `messages.get` and `drafts.get` responses when the `format=RAW` parameter is supplied.
+    string raw?;
+    # A short part of the message text.
+    string snippet?;
+    # The ID of the last history record that modified this message.
+    string historyId?;
+    # The internal message creation timestamp (epoch ms), which determines ordering in the inbox. For normal SMTP-received email, this represents the time the message was originally accepted by Google, which is more reliable than the `Date` header. However, for API-migrated mail, it can be configured by client to be based on the `Date` header.
+    string internalDate?;
+    # Estimated size in bytes of the message.
+    int:Signed32 sizeEstimate?;
+    # Email header **To**
+    string[] to?;
+    # Email header **From**
+    string 'from?;
+    # Email header **Bcc**
+    string[] bcc?;
+    # Email header **Cc**
+    string[] cc?;
+    # Email header **Subject**
+    string subject?;
+    # Email header **Date**
+    string date?;
+    # Email header **Message-ID**
+    string messageId?;
+    # Email header **ContentType**
+    string contentType?;
+    # MIME type of the top level message part. Values in `multipart/alternative` such as `text/plain` and `text/html` and in `multipart/*` including `multipart/mixed` and `multipart/related` indicate that the message contains a structured body with MIME parts. Values in `message/rfc822` indicate that the message is a container for the message parts that follow after the header.    
+    string mimeType?;
+    # Body of the message.
+    MessagePart payload?;
+};
+```

examples/README.md

@@ -13,7 +13,7 @@ The `gmail` connector provides practical examples illustrating usage in various
 
 ## Prerequisites
 
-1. Follow the [instructions](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail#set-up-guide) to set up the Gmail API.
+1. Follow the [instructions](https://github.com/ballerina-platform/module-ballerinax-googleapis.gmail#setup-guide) to set up the Gmail 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/process-mails/Process customer feedback emails.md

@@ -4,9 +4,9 @@ This example demonstrates how to efficiently manage customer feedback emails. Th
 
 ## Prerequisites
 
-### 1. Set up Gmail API
+### 1. Setup Gmail API
 
-Refer to the [Set up Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#set-up-guide) for necessary credentials (client ID, secret, tokens).
+Refer to the [Setup Guide](https://central.ballerina.io/ballerinax/googleapis.gmail/latest#setup-guide) for necessary credentials (client ID, secret, tokens).
 
 ### 2. Configuration
 

examples/process-mails/main.bal

@@ -22,7 +22,7 @@ configurable string clientId = os:getEnv("CLIENT_ID");
 configurable string clientSecret = os:getEnv("CLIENT_SECRET");
 
 public function main() returns error? {
-    gmail:Client gmailClient = check new gmail:Client(
+    gmail:Client gmail = check new gmail:Client(
         config = {
             auth: {
                 refreshToken,
@@ -32,15 +32,15 @@ public function main() returns error? {
         }
     );
 
-    gmail:ListMessagesResponse messageList = check gmailClient->/users/me/messages(q = "label:INBOX is:unread");
+    gmail:ListMessagesResponse messageList = check gmail->/users/me/messages(q = "label:INBOX is:unread");
 
     // Results from list messages only contains id and threadId.
     gmail:Message[] messageIds = messageList.messages ?: [];
 
     string[] ids = [];
     gmail:Message[] completeMessages = [];
     foreach gmail:Message message in messageIds {
-        gmail:Message completeMsg = check gmailClient->/users/me/messages/[message.id](format = "full");
+        gmail:Message completeMsg = check gmail->/users/me/messages/[message.id](format = "full");
         ids.push(message.id);
         completeMessages.push(completeMsg);
     }
@@ -52,7 +52,7 @@ public function main() returns error? {
     check io:fileWriteCsv("feedback.csv", processedData, io:APPEND);
 
     // Mark the messages as read.
-    check gmailClient->/users/me/messages/batchModify.post({
+    check gmail->/users/me/messages/batchModify.post({
         ids: ids,
         removeLabelIds: ["UNREAD"]
     });