Define SettingsRequest model and enhance getSettingsRequest_v1_schema

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.23.0] - 2026-03-13
+
+### Added
+
+- Define and "publish" new model `SettingsRequest`
+- Enhance `getSettingsRequest_v1_schema` to support multiple keys as well as nested keys
+
 ## [1.22.0] - 2026-03-11
 
 ### Added

docs/events.md

@@ -226,17 +226,60 @@ Request permissions for specified object from the Shell
   SHELL_EVENTS.Version1.GET_SETTINGS
   ```
 
-  Request settings value for specific key from the shell
+  Request settings value for specific key from the Shell
 
   - Request payload
 
-    type: string  
-    Key to read settings from
+    type: SettingsRequest  
+    Key to read settings from or array of (nested) keys
+
+    ```typescript
+    string or Array<string | string[]>
+    ```
+
+    Some keys inside the company settings are organized in nested folders. The structure looks similar to the following:
+
+    ```typescript
+    {
+      key_1: 'value1'
+      key_2: 'value2',
+      folder_1: {
+        key_3: 'value3'
+      },
+      folder_2: {
+        folder_3: {
+          key_4: 'value4'
+        }
+      }
+    }
+    ```
+
+    To fetch `key_1`, it is sufficient to provide the key as a string:
+    ```typescript
+    'key_1'
+    ```
+
+    To fetch multiple keys, provide them as an array:
+    ```typescript
+    ['key_1', 'key_2']
+    ```
+
+    To fetch nested keys, the path must be defined as an array. To distinguish nested keys from a simple array of keys, the path is wrapped in its own array:
+    ```typescript
+    [['folder_1', 'key_3']]
+    ```
+
+    `Hint`: Nested keys can have any depth.
+
+    It is also possible to fetch multiple keys and multiple nested keys in a single request:
+    ```typescript
+    ['key_1', 'key_2', ['folder_1', 'key_3'], ['folder_2', 'folder_3', 'key_4']]
+    ```
 
   - Response payload
 
     type: SettingsResponse\<T\>  
-    settings value which was read from requested key
+    Settings value which was read from requested key. In case an array of (nested) keys is provided as payload, there will be a response for each key.
 
     ```typescript
     {
@@ -390,7 +433,7 @@ Request value stored under specified key in cloud storage
 - Response payload
 
   type: GetFeatureFlagResponse  
-  object(s) containing key name and value for feature flag
+  Object containing key name and value for feature flag. In case array of objects are provided as payload, there will be a response for each object.
 
   ```typescript
   {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "fsm-shell",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "client library for FSM shell",
   "main": "release/fsm-shell-client.js",
   "module": "release/fsm-shell-client.es.js",

src/index.ts

@@ -46,6 +46,7 @@ import {
   RequireContextRequest,
   SetItemRequest,
   SettingsResponse,
+  SettingsRequest,
   SetTitleRequest,
   SetViewStateRequest,
   SetViewStateResponse,
@@ -80,6 +81,7 @@ export {
   RequireContextRequest,
   SetItemRequest,
   SettingsResponse,
+  SettingsRequest,
   SetTitleRequest,
   SetViewStateRequest,
   SetViewStateResponse,

src/models/index.ts

@@ -18,6 +18,7 @@ export {
 } from './modal/modal-open-request.v2.model';
 export { ModalCloseRequest } from './modal/modal-close-request.model';
 
+export { SettingsRequest } from './settings/settings-request.model';
 export { SettingsResponse } from './settings/settings-response.model';
 
 export { GetFeatureFlagRequest } from './feature-flag/get-feature-flag-request.model';

src/models/settings/settings-request.model.ts

@@ -0,0 +1 @@
+export type SettingsRequest = string | Array<string | string[]>;

src/validation/schemas/schemas.spec.ts

@@ -49,7 +49,8 @@ export const validGetItemRequest_v1 = 'string';
 export const validGetItemRequest_v2 = 'string';
 export const validGetItemResponse_v2 = { key: 'string', value: {} };
 export const validSetItemRequest_v1 = { key: 'string', value: {} };
-export const validGetFeatureFlagRequest_v1 = [{ key: 'string', defaultValue: true }];
+export const validGetFeatureFlagRequest_v1_subschema_1 = { key: 'string', defaultValue: true };
+export const validGetFeatureFlagRequest_v1_subschema_2 = [{ key: 'string', defaultValue: true }, { key: 'string', defaultValue: true }];
 export const validGetFeatureFlagResponse_v1 = { key: 'string', value: true };
 export const validSetTitleRequest_v1 = { title: 'string' };
 export const validModalOpenRequest_v1 = { url: 'string', modalSettings: { title: 'string', size: 'l', backdropClickCloseable: true, isScrollbarHidden: true }, data: {} };
@@ -93,7 +94,10 @@ export const validRequireContextRequest_v1 = {
   targetOutletName: 'string',
   targetExtensionAssignmentId: 'string'
 };
-export const validGetSettingsRequest_v1 = 'string';
+export const validGetSettingsRequest_v1_subschema_1 = 'string';
+export const validGetSettingsRequest_v1_subschema_2 = ['string', 'string'];
+export const validGetSettingsRequest_v1_subschema_3 = [['string'],['string', 'string']];
+export const validGetSettingsRequest_v1_subschema_4 = ['string', ['string']];
 export const validGetSettingsResponse_v1 = { key: 'string', value: {} };
 export const validSetViewStateRequest_v1 = { key: 'string', value: {} };
 export const validSetViewStateResponse_v1 = { key: 'string', value: {} };
@@ -311,7 +315,8 @@ describe('Schemas', () => {
     validateValidDataAgainstSchemaHelper(ajv, 'getItemRequest_v2_schema', getItemRequest_v2_schema, validGetItemRequest_v2);
     validateValidDataAgainstSchemaHelper(ajv, 'getItemResponse_v2_schema', getItemResponse_v2_schema, validGetItemResponse_v2);
     validateValidDataAgainstSchemaHelper(ajv, 'setItemRequest_v1_schema', setItemRequest_v1_schema, validSetItemRequest_v1);
-    validateValidDataAgainstSchemaHelper(ajv, 'getFeatureFlagRequest_v1_schema', getFeatureFlagRequest_v1_schema, validGetFeatureFlagRequest_v1);
+    validateValidDataAgainstSchemaHelper(ajv, 'getFeatureFlagRequest_v1_schema', getFeatureFlagRequest_v1_schema, validGetFeatureFlagRequest_v1_subschema_1);
+    validateValidDataAgainstSchemaHelper(ajv, 'getFeatureFlagRequest_v1_schema', getFeatureFlagRequest_v1_schema, validGetFeatureFlagRequest_v1_subschema_2);
     validateValidDataAgainstSchemaHelper(ajv, 'getFeatureFlagResponse_v1_schema', getFeatureFlagResponse_v1_schema, validGetFeatureFlagResponse_v1);
     validateValidDataAgainstSchemaHelper(ajv, 'setTitleRequest_v1_schema', setTitleRequest_v1_schema, validSetTitleRequest_v1);
     validateValidDataAgainstSchemaHelper(ajv, 'modalOpenRequest_v1_schema', modalOpenRequest_v1_schema, validModalOpenRequest_v1);
@@ -324,7 +329,10 @@ describe('Schemas', () => {
     validateValidDataAgainstSchemaHelper(ajv, 'getPermissionsResponse_v2_schema', getPermissionsResponse_v2_schema, validGetPermissionsResponse_v2);
     validateValidDataAgainstSchemaHelper(ajv, 'getPermissionsResponse_v3_schema', getPermissionsResponse_v3_schema, validGetPermissionsResponse_v3);
     validateValidDataAgainstSchemaHelper(ajv, 'requireContextRequest_v1_schema', requireContextRequest_v1_schema, validRequireContextRequest_v1);
-    validateValidDataAgainstSchemaHelper(ajv, 'getSettingsRequest_v1_schema', getSettingsRequest_v1_schema, validGetSettingsRequest_v1);
+    validateValidDataAgainstSchemaHelper(ajv, 'getSettingsRequest_v1_schema', getSettingsRequest_v1_schema, validGetSettingsRequest_v1_subschema_1);
+    validateValidDataAgainstSchemaHelper(ajv, 'getSettingsRequest_v1_schema', getSettingsRequest_v1_schema, validGetSettingsRequest_v1_subschema_2);
+    validateValidDataAgainstSchemaHelper(ajv, 'getSettingsRequest_v1_schema', getSettingsRequest_v1_schema, validGetSettingsRequest_v1_subschema_3);
+    validateValidDataAgainstSchemaHelper(ajv, 'getSettingsRequest_v1_schema', getSettingsRequest_v1_schema, validGetSettingsRequest_v1_subschema_4);
     validateValidDataAgainstSchemaHelper(ajv, 'getSettingsResponse_v1_schema', getSettingsResponse_v1_schema, validGetSettingsResponse_v1);
     validateValidDataAgainstSchemaHelper(ajv, 'setViewStateRequest_v1_schema', setViewStateRequest_v1_schema, validSetViewStateRequest_v1);
     validateValidDataAgainstSchemaHelper(ajv, 'setViewStateResponse_v1_schema', setViewStateResponse_v1_schema, validSetViewStateResponse_v1);

src/validation/schemas/settings/get-settings-request.v1.schema.ts

@@ -1,3 +1,24 @@
 export const getSettingsRequest_v1_schema = {
-  type: 'string',
+  anyOf: [
+    {
+       type: 'string'
+    },
+    {
+      type: 'array',
+      items: {
+        type: ['string', 'array'],
+        anyOf: [
+          {
+            type: 'string'
+          },
+          {
+            type: 'array',
+            items: {
+              type: 'string'
+            }
+          }
+        ]
+      }
+    }
+  ]
 };