(JS) Remove documentation for removed deprecated content in v4 (#2029)

* doc: remove mail-client

* doc: add operation request builder

* fix: lint

* fix: vale

* fix: remove mail-client sidebar

* fix: link

* fix: note annotation

* Apply suggestions from code review

* Apply suggestions from code review

---------

Co-authored-by: Deeksha Sinha <[email protected]>

Author: ZhongpinWang

.vale.ini

@@ -6,6 +6,7 @@ StylesPath = styles
 Vocab = SAP
 ; MinAlertLevel = suggestion
 MinAlertLevel = warning
+WordTemplate = \b(?:%s)\b
 
 [formats]
 mdx = md
@@ -15,6 +16,5 @@ BasedOnStyles = Vale, SAP
 BlockIgnores = (<(img|br|Tabs|Redirect|a|MvnBadge|embed|Csrf)\s[^>]+>+?), \
 (?s) *(import[^\n]+;)
 TokenIgnores = (<(img|br|Tabs|Redirect|a|MvnBadge|embed|Csrf)\s[^\n]+>+?)
-WordTemplate = \b(?:%s)\b
 
 Vale.Terms = warning

README.md

@@ -11,7 +11,7 @@ For the [Support](https://github.com/SAP/cloud-sdk-js/issues) on SAP Cloud SDK f
 
 ## Looking for the repository of the SAP Cloud SDK for JavaScript / TypeScript?
 
-Find it here [here](https://github.com/SAP/cloud-sdk-js).
+Find it [here](https://github.com/SAP/cloud-sdk-js).
 
 ## Getting Support
 

docs-js/features/connectivity/destination.mdx

@@ -33,9 +33,9 @@ Some reasons to separate destinations and the application are:
 - Different customers may want to configure different systems.
 - Multiple applications might want to access the same systems.
 
-Use [destinations](pathname:///api/v3/interfaces/sap_cloud_sdk_connectivity.Destination.html) to execute [arbitrary requests](./generic-http-client.mdx), [OData requests](../odata/overview.mdx), and [OpenAPI requests](../openapi/overview.mdx) as well as to [send e-mails](../mail-client/mail-client.mdx).
+Use [destinations](pathname:///api/v3/interfaces/sap_cloud_sdk_connectivity.Destination.html) to execute [arbitrary requests](./generic-http-client.mdx), [OData requests](../odata/overview.mdx), and [OpenAPI requests](../openapi/overview.mdx).
 The following examples use `req.execute()`, assuming req is an OData or OpenAPI request, to demonstrate options for the destination lookup.
-The same options apply to `executeHttpRequest()` and `sendMail()`.
+The same options apply to `executeHttpRequest()`.
 
 ## Referencing Destinations by Name
 
@@ -328,7 +328,7 @@ In a productive environment, in most cases you will use the [destination service
 To access the destination service, the SAP Cloud SDK will first fetch an access token from the XSUAA service.
 The token retrieved from the XSUAA service is used to make a call to the destination service and receive the destinations.
 The destination service returns a destination with all relevant authentication information depending on the used authentication flow.
-Listed below are the SDK-supported authentication flows, categorized based on whether a user JWT (`jwt` property in [destination fetch options](#destination-fetch-options)) is required to retrieve a destination.
+Listed below are the supported authentication flows in SAP Cloud SDK, categorized based on whether a user JWT (`jwt` property in [destination fetch options](#destination-fetch-options)) is required to retrieve a destination.
 
 - No user JWT required
 
@@ -569,7 +569,7 @@ The SAP Cloud SDK adds those additional headers and query parameters for every c
 
 ### Forwarding Auth Tokens
 
-The SDK provides the option of configuring a destination to directly forward the given JWT to the target system.
+SAP Cloud SDK provides the option of configuring a destination to directly forward the given JWT to the target system.
 This behavior can be enabled by setting the `forwardAuthToken` property on the destination to `true`, as shown in the code snippet below:
 
 ```ts

docs-js/features/mail-client/mail-client.mdx

@@ -0,0 +1,29 @@
+If the response structure does not match the transformation type, the promise from `execute(destination)` will be resolved into `undefined`.
+
+The default transformer expects the following response format:
+
+```json
+{
+  "d": {
+    "Count": 0
+  }
+}
+```
+
+Assume the actual response has an additional layer `Foo`:
+
+```json
+{
+  "d": {
+    "Foo": {
+      "Count": 0
+    }
+  }
+}
+```
+
+In this case, `dataAccessor` can be used in the following way to modify the response into the desired form for further deserialization.
+
+```ts
+operationRequestBuilder.execute(destination, data => data.d.Foo);
+```

docs-js/features/odata/common/operation-imports/data-accessor.mdx

@@ -1,10 +1,10 @@
-Operations do not support ETag handling automatically.
+Function or action imports do not support ETag handling automatically.
 If your service requires the version identifier of an entity to be present, you can pass it to the request on your own using the `addCustomHeaders()` method (see example below).
-With this approach, you have to retrieve the required entity with a `GET` request, before executing the function import.
-Note, that if the function import execution succeeds, the version identifier of your entity will be outdated.
+With this approach, you have to retrieve the required entity with a `GET` request, before executing the operation.
+Note, that if the operation execution succeeds, the version identifier of your entity will be outdated.
 
 ```ts
-myFunction()
+operationRequestBuilder()
   .addCustomHeaders({ 'if-match': entity.versionIdentifier })
   .execute(destination);
 ```

…/function-imports/entity-return-type.mdx …operation-imports/entity-return-type.mdxdocs-js/features/odata/common/function-imports/entity-return-type.mdx renamed to docs-js/features/odata/common/operation-imports/entity-return-type.mdx docs-js/features/odata/common/function-imports/entity-return-type.mdx renamed to docs-js/features/odata/common/operation-imports/entity-return-type.mdx

@@ -1,6 +1,8 @@
 import React from 'react';
 import EtagFunctionImportContent from './etag-function-import.mdx';
 import EntityReturnTypeContent from './entity-return-type.mdx';
+import RequestBuilderContent from './request-builder.mdx';
+import DataAccessorContent from './data-accessor.mdx';
 
 export function EtagFunctionImport() {
   return <EtagFunctionImportContent />;
@@ -9,3 +11,11 @@ export function EtagFunctionImport() {
 export function EntityReturnType() {
   return <EntityReturnTypeContent />;
 }
+
+export function RequestBuilder() {
+  return <RequestBuilderContent />;
+}
+
+export function DataAccessor() {
+  return <DataAccessorContent />;
+}

…unction-imports/etag-function-import.mdx …eration-imports/etag-function-import.mdxdocs-js/features/odata/common/function-imports/etag-function-import.mdx renamed to docs-js/features/odata/common/operation-imports/etag-function-import.mdx docs-js/features/odata/common/function-imports/etag-function-import.mdx renamed to docs-js/features/odata/common/operation-imports/etag-function-import.mdx

@@ -0,0 +1,14 @@
+The operation request builder helps build a request for service operations such as function and action imports if they are exposed.
+
+:::note
+Note that action imports are only supported in OData v4.
+But the usage of function and action imports are similar.
+:::
+
+The example below execute an action import from the [Inbound Delivery (A2X)](https://api.sap.com/api/API_INBOUND_DELIVERY_SRV_0002/overview) service against a destination.
+To learn how to generate an API client from the service definition, look at [this article](../../generate-odata-client.mdx).
+
+```ts
+import { postGoodsReceipt } from './inbound/API_INBOUND_DELIVERY_SRV_0002';
+postGoodsReceipt({ deliveryDocument: '123456' }).execute(destination);
+```

…/odata/common/function-imports/index.jsx …odata/common/operation-imports/index.jsxdocs-js/features/odata/common/function-imports/index.jsx renamed to docs-js/features/odata/common/operation-imports/index.jsx docs-js/features/odata/common/function-imports/index.jsx renamed to docs-js/features/odata/common/operation-imports/index.jsx

@@ -14,7 +14,7 @@ keywords:
 ---
 
 import { SkipCsrf, Csrf } from '../common';
-import { Select, ChangeSetExample, RequestBuilder } from './v2';
+import { Select, ChangeSetExample } from './v2';
 import { SkipCsrfExample, CustomCsrf, ETag } from './common';
 import {
   CustomFields,
@@ -48,9 +48,11 @@ import {
   FilterFunctions
 } from './common/query-parameter';
 import {
+  RequestBuilder,
+  DataAccessor,
   EtagFunctionImport,
   EntityReturnType
-} from './common/function-imports';
+} from './common/operation-imports';
 import {
   BatchIntro,
   RetrieveRequests,
@@ -199,12 +201,12 @@ If you need to adjust the way CSRF tokens are fetched, you can do so by using [m
 
 <FilterFunctions />
 
-## Function Imports
-
-### Request Builder
+## Operation Request Builder
 
 <RequestBuilder />
 
+<DataAccessor />
+
 <EntityReturnType />
 
 ### Setting ETag
@@ -218,15 +220,15 @@ If you need to adjust the way CSRF tokens are fetched, you can do so by using [m
 ### Retrieve Request
 
 A retrieve request represents an HTTP `GET` request.
-In terms of the SAP Cloud SDK this includes all requests built by [`GetAllRequestBuilder`](#getall-request-builder), [`GetByKeyRequestBuilder`](#getbykey-request-builder), and [`FunctionImportRequestBuilder`](#function-imports) using `GET` requests.
+In terms of the SAP Cloud SDK this includes all requests built by [`GetAllRequestBuilder`](#getall-request-builder), [`GetByKeyRequestBuilder`](#getbykey-request-builder), and [`OperationRequestBuilder`](#operation-request-builder) using `GET` requests.
 If you use TypeScript, a type error will appear when including a function import changing the data.
 
 <RetrieveRequests />
 
 ### Changeset
 
 A changeset is a collection of HTTP `POST`, `PUT`, `PATCH` and `DELETE` operations.
-Such operations are built by the [`CreateRequestBuilder`](#create-request-builder), [`UpdateRequestBuilder`](#update-request-builder), [`DeleteRequestBuilder`](#delete-request-builder), or [`FunctionImportRequestBuilder`](#function-imports).
+Such operations are built by the [`CreateRequestBuilder`](#create-request-builder), [`UpdateRequestBuilder`](#update-request-builder), [`DeleteRequestBuilder`](#delete-request-builder), or [`OperationRequestBuilder`](#operation-request-builder).
 If you use TypeScript, a type error will appear when including a function import reading the data.
 
 <ChangeSet />