Branch v3 js docs (#1138)

docs-js_versioned_docs/version-v2/features/common/custom-request-config-note.mdx

@@ -0,0 +1,12 @@
+:::note
+
+To ensure API consistency, the SAP Cloud SDK does not allow overriding the following options:
+
+- `method`
+- `url`
+- `baseURL`
+- `data`
+- `headers`
+- `params`
+
+:::

docs-js_versioned_docs/version-v2/features/common/custom-request-config.mdx

@@ -0,0 +1,4 @@
+By default, the SAP Cloud SDK uses [axios](https://github.com/axios/axios) as an HTTP client for executing requests.
+The SAP Cloud SDK derives and configures most request options including `url`, `headers`, etc.
+You can provide a custom request configuration to pass additional options to axios.
+The example below demonstrates how to configure the response data type, typically used when downloading a file from an endpoint.

docs-js_versioned_docs/version-v2/features/common/execute-raw-overview.mdx

@@ -0,0 +1,7 @@
+In addition to the `execute()` method, you can execute a request using the `executeRaw()` method.
+It returns an `HttpResponse` instance, which contains the following properties:
+
+- `status`: the status code of the response
+- `headers`: the response headers
+- `data`: the response body
+- `request`: the original request

docs-js_versioned_docs/version-v2/features/common/execute-raw-use-cases.mdx

@@ -0,0 +1,6 @@
+Typical cases, where you might need to use the `executeRaw()` method are:
+
+- You need additional information about the response, like the status code or response headers.
+- You need additional information about the request, like payload, method, or request headers.
+- The `execute()` method is omitted in some request builders because the response data cannot be deserialized by the request builder.
+- Debugging purposes.

docs-js_versioned_docs/version-v2/features/common/index.jsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import CustomRequestConfigContent from './custom-request-config.mdx';
+import CustomRequestConfigNoteContent from './custom-request-config-note.mdx';
+import ExecuteRawOverviewContent from './execute-raw-overview.mdx';
+import ExecuteRawUseCasesContent from './execute-raw-use-cases.mdx';
+import SkipCsrfContent from './skip-csrf-token.mdx';
+
+export function CustomRequestConfig() {
+  return <CustomRequestConfigContent />;
+}
+
+export function CustomRequestConfigNote() {
+  return <CustomRequestConfigNoteContent />;
+}
+
+export function ExecuteRawOverview() {
+  return <ExecuteRawOverviewContent />;
+}
+
+export function ExecuteRawUseCases() {
+  return <ExecuteRawUseCasesContent />;
+}
+
+export function SkipCsrf() {
+  return <SkipCsrfContent />;
+}

docs-js_versioned_docs/version-v2/features/common/skip-csrf-token.mdx

@@ -0,0 +1,3 @@
+For some services, the `CSRF` token is not required even for non-`GET` requests.
+Therefore, skipping to fetch the `CSRF` token makes sense as a performance improvement.
+You can disable the `CSRF` token request by using `skipCsrfTokenFetching()` like below:

docs-js_versioned_docs/version-v2/features/connectivity/destination-cache-isolation.mdx

@@ -0,0 +1,140 @@
+---
+id: destination-cache
+title: Destination Cache and Isolation
+hide_title: false
+hide_table_of_contents: false
+sidebar_label: Destination Cache
+description: This article describes how destinations are cached and how the cache entries are isolated with respect to Tenant and User.
+keywords:
+  - sap
+  - cloud
+  - sdk
+  - destination
+  - connectivity
+  - JavaScript
+  - TypeScript
+---
+
+The SAP Cloud SDK provides the option to cache destinations for efficiency reasons.
+Cached destination need to be isolated to the correct users.
+
+This guide explains the different options for destination caching with the SAP Cloud SDK.
+The general destination lookup is described in [this guide](./destination.mdx).
+
+## Destination Service Cache
+
+To reduce the number of calls to the destination service, you can enable the destination cache.
+All the discussed options apply to the `execute()` and `getDestination()` methods of the SAP Cloud SDK.
+The destination caching is disabled by default.
+Setting the `useCache` flag to `true` enables it:
+
+```ts
+.execute({ destinationName: 'myDestination', jwt: 'yourJWT', useCache: true })
+```
+
+A cached destination is stored for 5 minutes in the cache.
+The SAP Cloud SDK tries to set the proper isolation strategy for the destination automatically.
+There are two options:
+
+- `Tenant`: The destination is cached for a tenant and different users will hit the same cache entry.
+- `TenantUser`: The destination is cached separately for each user of a tenant.
+
+The SAP Cloud SDK sets the isolation based on the provided JWT:
+
+- No JWT: Isolation is set to `Tenant` and value for the tenant is the provider account.
+- JWT without `user_id`: Isolation is set to `Tenant` and the value for the tenant is the `zid` of the JWT.
+- JWT with `user_id`: Isolation is set to `TenantUser` and values are taken from `zid` and `user_id`.
+
+This is a safe choice which prevents privilege escalation due to caching.
+The first two cases are typical for user-independent authentication flows.
+Examples of such a flow are `BasicAuthentication`, `ClientCertificateAuthentication` or `OAuth2ClientCredentials`.
+
+There are cases where the choice made by the SAP Cloud SDK is not optimal.
+Assume you have a multi-tenant scenario and you need to pass the JWT to obtain the destination for the right tenant.
+
+The JWT contains a `user_id` but the destination flow is user-independent.
+The SAP Cloud SDK would use isolation `TenantUser`, although `Tenant` would be sufficient.
+
+In such a case, you can manually enforce weaker isolation:
+
+```ts
+.execute({
+  destinationName: 'myDestination',
+  jwt: 'yourJWT',
+  isolationStrategy: IsolationStrategy.Tenant
+})
+```
+
+:::caution
+
+Be very careful with this option.
+You should know what you're doing when manually downgrading the isolation strategy from `TenantUser` level.
+An erroneous configuration can have severe consequences like privilege escalation between users.
+
+:::
+
+### Custom Destination Service Cache
+
+When the cache option is enabled, the SAP Cloud SDK stores the fetched destinations in an in-memory cache.
+However, in certain cases, a persistent or distributed cache may be more suitable according to your application architecture.
+
+To create your custom destination cache provider, implement the `DestinationCacheInterface` interface shown below and define the `get`, `set`, and `clear` methods.
+
+```ts
+export interface DestinationCacheInterface {
+  hasKey(key: string): Promise<boolean>;
+  get(key: string | undefined): Promise<Destination | undefined>;
+  set(key: string | undefined, item: CacheEntry<Destination>): Promise<void>;
+  clear(): Promise<void>;
+}
+```
+
+Note that each item in the cache is represented using the type `CacheEntry<T>` which defines two properties:
+
+- `entry`, the item you want to store, and
+- `expires`, the expiration time for an individual cache item, this is optional.
+
+Once you have implemented your custom cache provider, you can tell the SAP Cloud SDK to use it in place of the default one.
+Pass your custom destination cache provider to the `setDestinationCache()` method before the first calls to either the `getDestination()` or the generic client's `executeHttpRequest()` function.
+
+```ts
+class CustomCacheProvide implements DestinationCacheInterface {
+  // your custom implementation
+}
+
+setDestinationCache(new CustomCacheProvider());
+```
+
+All subsequent calls to fetch destinations will use the custom cache.
+
+## Register Destination Cache
+
+The `registerDestination()` function is like a manual cache for destinations.
+This function behaves similarly to the destination service cache discussed above.
+The [destination lookup guide](./destination.mdx) explains the usage of this function in more detail.
+
+```ts
+import { registerDestination } from '@sap-cloud-sdk/connectivity';
+
+const destination = {
+  name: 'FORWARD-DESTINATION',
+  url: 'https://mys4hana.com'
+};
+
+registerDestination(destination, { jwt: 'yourJWT' });
+```
+
+The isolation strategy is automatically detected and applied based on the given JWT:
+
+- No JWT: Isolation is set to `Tenant` and value for the tenant is the provider account.
+- JWT without `user_id`: Isolation is set to `Tenant` and the value for the tenant is the `zid` of the JWT.
+- JWT with `user_id`: Isolation is set to `TenantUser` and values are taken from `zid` and `user_id`.
+
+You can override the automatically detected isolation strategy.
+
+```ts
+registerDestination(destination, {
+  jwt: 'yourJWT',
+  isolationStrategy: IsolationStrategy.Tenant
+});
+```