fix: sdk exploded syntax - take into account request plugin options

packages/@ama-sdk/client-angular/src/api-angular-client.ts

@@ -55,7 +55,8 @@ const DEFAULT_OPTIONS = {
   angularPlugins: [],
   requestPlugins: [],
   enableTokenization: false,
-  disableFallback: false
+  disableFallback: false,
+  enableParameterSerialization: false
 } as const satisfies Omit<BaseApiAngularClientOptions, 'basePath' | 'httpClient'>;
 
 /** Client to process the call to the API using Angular API */
@@ -130,7 +131,7 @@ export class ApiAngularClient implements ApiClient {
   }
 
   /** @inheritdoc */
-  public prepareUrlWithQueryParams(url: string, serializedQueryParams: { [key: string]: string }): string {
+  public prepareUrlWithQueryParams(url: string, serializedQueryParams?: { [key: string]: string }): string {
     return prepareUrlWithQueryParams(url, serializedQueryParams);
   }
 

packages/@ama-sdk/client-beacon/src/api-beacon-client.ts

@@ -35,7 +35,8 @@ export interface BaseApiBeaconClientConstructor extends PartialExcept<Omit<BaseA
 const DEFAULT_OPTIONS = {
   replyPlugins: [] as never[],
   requestPlugins: [],
-  enableTokenization: false
+  enableTokenization: false,
+  enableParameterSerialization: false
 } as const satisfies Omit<BaseApiBeaconClientOptions, 'basePath'>;
 
 /**
@@ -130,7 +131,7 @@ export class ApiBeaconClient implements ApiClient {
   }
 
   /** @inheritdoc */
-  public prepareUrlWithQueryParams(url: string, serializedQueryParams: { [key: string]: string }): string {
+  public prepareUrlWithQueryParams(url: string, serializedQueryParams?: { [key: string]: string }): string {
     return prepareUrlWithQueryParams(url, serializedQueryParams);
   }
 

packages/@ama-sdk/client-fetch/src/api-fetch-client.ts

@@ -51,7 +51,8 @@ const DEFAULT_OPTIONS = {
   fetchPlugins: [],
   requestPlugins: [],
   enableTokenization: false,
-  disableFallback: false
+  disableFallback: false,
+  enableParameterSerialization: false
 } as const satisfies Omit<BaseApiFetchClientOptions, 'basePath'>;
 
 /** Client to process the call to the API using Fetch API */
@@ -131,7 +132,7 @@ export class ApiFetchClient implements ApiClient {
   }
 
   /** @inheritdoc */
-  public prepareUrlWithQueryParams(url: string, serializedQueryParams: { [key: string]: string }): string {
+  public prepareUrlWithQueryParams(url: string, serializedQueryParams?: { [key: string]: string }): string {
     return prepareUrlWithQueryParams(url, serializedQueryParams);
   }
 

packages/@ama-sdk/core/src/clients/api-angular-client.ts

@@ -82,7 +82,8 @@ const DEFAULT_OPTIONS: Omit<BaseApiAngularClientOptions, 'basePath' | 'httpClien
   angularPlugins: [],
   requestPlugins: [],
   enableTokenization: false,
-  disableFallback: false
+  disableFallback: false,
+  enableParameterSerialization: false
 };
 
 /**
@@ -160,7 +161,7 @@ export class ApiAngularClient implements ApiClient {
   }
 
   /** @inheritdoc */
-  public prepareUrlWithQueryParams(url: string, serializedQueryParams: { [key: string]: string }): string {
+  public prepareUrlWithQueryParams(url: string, serializedQueryParams?: { [key: string]: string }): string {
     return prepareUrlWithQueryParams(url, serializedQueryParams);
   }
 

packages/@ama-sdk/core/src/clients/api-beacon-client.ts

@@ -52,7 +52,8 @@
 const DEFAULT_OPTIONS: Omit<BaseApiBeaconClientOptions, 'basePath'> = {
   replyPlugins: [] as never[],
   requestPlugins: [],
-  enableTokenization: false
+  enableTokenization: false,
+  enableParameterSerialization: false
 };
 
 /**
@@ -148,7 +149,7 @@
   }
 
   /** @inheritdoc */
-  public prepareUrlWithQueryParams(url: string, serializedQueryParams: { [key: string]: string }): string {
+  public prepareUrlWithQueryParams(url: string, serializedQueryParams?: { [key: string]: string }): string {
     return prepareUrlWithQueryParams(url, serializedQueryParams);
   }
 

packages/@ama-sdk/core/src/clients/api-fetch-client.ts

@@ -73,7 +73,8 @@
   fetchPlugins: [],
   requestPlugins: [],
   enableTokenization: false,
-  disableFallback: false
+  disableFallback: false,
+  enableParameterSerialization: false
 };
 
 /**
@@ -156,7 +157,7 @@
   }
 
   /** @inheritdoc */
-  public prepareUrlWithQueryParams(url: string, serializedQueryParams: { [key: string]: string }): string {
+  public prepareUrlWithQueryParams(url: string, serializedQueryParams?: { [key: string]: string }): string {
     return prepareUrlWithQueryParams(url, serializedQueryParams);
   }
 

packages/@ama-sdk/core/src/fwk/api.helpers.ts

@@ -13,7 +13,6 @@ import type {
  * Prepares the url to be called
  * @param url Base url to be used
  * @param queryParameters Key value pair with the parameters. If the value is undefined, the key is dropped
- * @deprecated use {@link prepareUrlWithQueryParams} with query parameter serialization, will be removed in v14.
  */
 export function prepareUrl(url: string, queryParameters: { [key: string]: string | undefined } = {}) {
   const queryPart = Object.keys(queryParameters)
@@ -31,7 +30,7 @@ export function prepareUrl(url: string, queryParameters: { [key: string]: string
  * @param url Base url to be used
  * @param serializedQueryParams Key value pairs of query parameter names and their serialized values
  */
-export function prepareUrlWithQueryParams(url: string, serializedQueryParams: { [key: string]: string }): string {
+export function prepareUrlWithQueryParams(url: string, serializedQueryParams: { [key: string]: string } = {}): string {
   const paramsPrefix = url.includes('?') ? '&' : '?';
   const queryPart = Object.values(serializedQueryParams).join('&');
   return url + (queryPart ? paramsPrefix + queryPart : '');

packages/@ama-sdk/core/src/fwk/core/api-client.ts

@@ -1,4 +1,5 @@
 import type {
+  ParamSerializationOptions,
   RequestBody,
   RequestMetadata,
   RequestOptions,
@@ -27,6 +28,8 @@ export interface RequestOptionsParameters {
   basePath: string;
   /** Query Parameters */
   queryParams?: { [key: string]: string | undefined };
+  /** Parameter serialization options */
+  paramSerializationOptions?: ParamSerializationOptions;
   /** Force body to string */
   body?: RequestBody;
   /** Force headers to Headers type */
@@ -91,7 +94,7 @@ export interface ApiClient {
    * @param url Base url to be used
    * @param serializedQueryParams Key value pairs of query parameter names and their serialized values
    */
-  prepareUrlWithQueryParams(url: string, serializedQueryParams: { [key: string]: string }): string;
+  prepareUrlWithQueryParams(url: string, serializedQueryParams?: { [key: string]: string }): string;
 
   /**
    * Serialize query parameters based on the values of exploded and style

packages/@ama-sdk/core/src/fwk/core/base-api-constructor.ts

@@ -27,6 +27,8 @@ export interface BaseApiClientOptions {
   disableFallback?: boolean;
   /** Logger (optional, fallback to console logger if undefined) */
   logger?: Logger;
+  /** Enable parameter serialization with exploded syntax */
+  enableParameterSerialization?: boolean;
   /** Custom query parameter serialization method */
   serializeQueryParams?<T extends { [key: string]: SupportedParamType }>(queryParams: T, queryParamSerialization: { [p in keyof T]: ParamSerialization }): { [p in keyof T]: string };
   /** Custom query parameter serialization method */

packages/@ama-sdk/core/src/fwk/param-serialization.ts

@@ -15,6 +15,15 @@ export type PrimitiveType = string | number | boolean | Date | utils.Date | util
 /** Supported types for the operation parameters - primitives, primitive arrays, and simple non-nested objects */
 export type SupportedParamType = PrimitiveType | PrimitiveType[] | { [key: string]: PrimitiveType };
 
+/** URL encoding of space character, delimiter for spaceDelimited style */
+const SPACE_URL_CODE = encodeURIComponent(' ');
+/** URL encoding of pipe character, delimiter for pipeDelimited style */
+const PIPE_URL_CODE = encodeURIComponent('|');
+/** URL encoding of opening square bracket, used in deepObject style */
+const OPENING_SQUARE_BRACKET_URL_CODE = encodeURIComponent('[');
+/** URL encoding of closing square bracket, used in deepObject style */
+const CLOSING_SQUARE_BRACKET_URL_CODE = encodeURIComponent(']');
+
 /**
  * Verify if property is of type utils.Date or utils.DateTime
  * @param prop
@@ -23,6 +32,31 @@ export function isDateType(prop: any): prop is Date | utils.Date | utils.DateTim
   return prop instanceof Date || prop instanceof utils.Date || prop instanceof utils.DateTime;
 }
 
+/**
+ * Check if the parameter is a record of type <string, string>.
+ * @param param
+ */
+export function isParamValueRecord(param: any): param is { [key: string]: string } {
+  return typeof param === 'object' && Object.values(param).every((item) => typeof item === 'string');
+}
+
+/** Query parameter value and serialization */
+export type QueryParamValueSerialization = { value: SupportedParamType } & ParamSerialization;
+
+/**
+ * Serialize query parameters of request plugins
+ * @param queryParams
+ */
+export function serializeRequestPluginQueryParams(queryParams: { [key: string]: QueryParamValueSerialization }) {
+  const queryParamsValues: { [key: string]: SupportedParamType } = {};
+  const queryParamSerialization: { [key: string]: ParamSerialization } = {};
+  Object.entries(queryParams).forEach(([paramKey, paramValue]) => {
+    queryParamsValues[paramKey] = paramValue.value;
+    queryParamSerialization[paramKey] = { explode: paramValue.explode, style: paramValue.style };
+  });
+  return serializeQueryParams(queryParamsValues, queryParamSerialization);
+}
+
 /**
  * Serialize query parameters of type array
  * OpenAPI Parameter Serialization {@link https://swagger.io/specification | documentation}
@@ -46,13 +80,13 @@ function serializeArrayQueryParams(queryParamName: string, queryParamValue: Prim
         if (emptyArray) {
           break;
         }
-        return encodeURIComponent(queryParamName) + '=' + filteredArray.map((v) => isDateType(v) ? v.toJSON() : encodeURIComponent(v.toString())).join('%20');
+        return encodeURIComponent(queryParamName) + '=' + filteredArray.map((v) => isDateType(v) ? v.toJSON() : encodeURIComponent(v.toString())).join(SPACE_URL_CODE);
       }
       case 'pipeDelimited': {
         if (emptyArray) {
           break;
         }
-        return encodeURIComponent(queryParamName) + '=' + filteredArray.map((v) => isDateType(v) ? v.toJSON() : encodeURIComponent(v.toString())).join('%7C');
+        return encodeURIComponent(queryParamName) + '=' + filteredArray.map((v) => isDateType(v) ? v.toJSON() : encodeURIComponent(v.toString())).join(PIPE_URL_CODE);
       }
     }
   }
@@ -81,15 +115,16 @@ function serializeObjectQueryParams(queryParamName: string, queryParamValue: { [
         encodeURIComponent(propName) + ',' + (isDateType(propValue) ? propValue.toJSON() : encodeURIComponent(propValue.toString()))).join(',');
   } else if (paramSerialization.style === 'spaceDelimited' && !paramSerialization.explode && !emptyObject) {
     return encodeURIComponent(queryParamName) + '=' + Object.entries(filteredObject).map(([propName, propValue]) =>
-      encodeURIComponent(propName) + '%20' + (isDateType(propValue) ? propValue.toJSON() : encodeURIComponent(propValue.toString()))
-    ).join('%20');
+      encodeURIComponent(propName) + SPACE_URL_CODE + (isDateType(propValue) ? propValue.toJSON() : encodeURIComponent(propValue.toString()))
+    ).join(SPACE_URL_CODE);
   } else if (paramSerialization.style === 'pipeDelimited' && !paramSerialization.explode && !emptyObject) {
     return encodeURIComponent(queryParamName) + '=' + Object.entries(filteredObject).map(([propName, propValue]) =>
-      encodeURIComponent(propName) + '%7C' + (isDateType(propValue) ? propValue.toJSON() : encodeURIComponent(propValue.toString()))
-    ).join('%7C');
+      encodeURIComponent(propName) + PIPE_URL_CODE + (isDateType(propValue) ? propValue.toJSON() : encodeURIComponent(propValue.toString()))
+    ).join(PIPE_URL_CODE);
   } else if (paramSerialization.style === 'deepObject' && paramSerialization.explode && !emptyObject) {
     return Object.entries(filteredObject).map(([propName, propValue]) =>
-      encodeURIComponent(queryParamName) + '%5B' + encodeURIComponent(propName) + '%5D=' + (isDateType(propValue) ? propValue.toJSON() : encodeURIComponent(propValue.toString()))
+      encodeURIComponent(queryParamName) + OPENING_SQUARE_BRACKET_URL_CODE + encodeURIComponent(propName) + CLOSING_SQUARE_BRACKET_URL_CODE + '='
+      + (isDateType(propValue) ? propValue.toJSON() : encodeURIComponent(propValue.toString()))
     ).join('&');
   }
 }
@@ -110,9 +145,8 @@ export function serializeQueryParams<T extends { [key: string]: SupportedParamTy
       } else if (typeof queryParamValue === 'object' && !isDateType(queryParamValue)) {
         serializedValue = serializeObjectQueryParams(queryParamName, queryParamValue, paramSerialization);
       } else {
-        if (paramSerialization.style === 'form') {
-          serializedValue = encodeURIComponent(queryParamName) + '=' + (isDateType(queryParamValue) ? queryParamValue.toJSON() : encodeURIComponent(queryParamValue.toString()));
-        }
+        // NOTE: 'form' style is the default value for primitive types
+        serializedValue = encodeURIComponent(queryParamName) + '=' + (isDateType(queryParamValue) ? queryParamValue.toJSON() : encodeURIComponent(queryParamValue.toString()));
       }
       if (serializedValue) {
         acc[queryParamName as keyof T] = serializedValue;

packages/@ama-sdk/core/src/plugins/additional-params/additional-params-sync.request.ts

@@ -1,7 +1,16 @@
+import {
+  stringifyQueryParams,
+} from '../../fwk/api.helpers';
+import {
+  isParamValueRecord,
+  type QueryParamValueSerialization,
+  serializeRequestPluginQueryParams,
+} from '../../fwk/param-serialization';
 import {
   PluginSyncRunner,
   RequestOptions,
   RequestPlugin,
+  RequestPluginContext,
 } from '../core';
 import {
   isStringOrUndefined,
@@ -11,7 +20,8 @@ export interface AdditionalParametersSync {
   /** Additional headers */
   headers?: { [key: string]: string } | ((headers: Headers) => { [key: string]: string });
   /** Additional query params */
-  queryParams?: { [key: string]: string } | ((defaultValues?: { [key: string]: string }) => { [key: string]: string });
+  queryParams?: { [key: string]: string } | { [key: string]: QueryParamValueSerialization }
+    | ((defaultValues?: { [key: string]: string } | { [key: string]: QueryParamValueSerialization }) => { [key: string]: string } | { [key: string]: QueryParamValueSerialization });
   /** Additional body params */
   body?: (defaultValues?: string) => string | null;
 }
@@ -30,15 +40,29 @@ export class AdditionalParamsSyncRequest implements RequestPlugin {
     this.additionalParams = additionalParams;
   }
 
-  public load(): PluginSyncRunner<RequestOptions, RequestOptions> {
+  public load(context?: RequestPluginContext): PluginSyncRunner<RequestOptions, RequestOptions> {
     return {
       transform: (data: RequestOptions) => {
         const queryParams = typeof this.additionalParams.queryParams === 'function' ? this.additionalParams.queryParams(data.queryParams) : this.additionalParams.queryParams;
         const headers = typeof this.additionalParams.headers === 'function' ? this.additionalParams.headers(data.headers) : this.additionalParams.headers;
         const body = this.additionalParams.body && isStringOrUndefined(data.body) ? this.additionalParams.body(data.body) : undefined;
 
         if (queryParams) {
-          data.queryParams = { ...data.queryParams, ...queryParams };
+          if (data.paramSerializationOptions?.enableParameterSerialization) {
+            if (isParamValueRecord(queryParams)) {
+              throw new Error('It is not possible to serialize additional query parameters without their serialization properties `value`, `explode`, and `style`.');
+            } else {
+              data.queryParams = { ...data.queryParams, ...serializeRequestPluginQueryParams(queryParams) };
+            }
+          } else {
+            if (isParamValueRecord(queryParams)) {
+              data.queryParams = { ...data.queryParams, ...queryParams };
+            } else {
+              const queryParamsValues = Object.fromEntries(Object.entries(queryParams).map(([key, value]) => [key, value.value]));
+              data.queryParams = { ...data.queryParams, ...stringifyQueryParams(queryParamsValues) };
+              (context?.logger || console).log('The serialization of additional query parameters has been ignored since parameter serialization is not enabled.');
+            }
+          }
         }
 
         if (body !== undefined) {

packages/@ama-sdk/core/src/plugins/additional-params/additional-params.request.ts

@@ -1,14 +1,26 @@
+import {
+  stringifyQueryParams,
+} from '../../fwk/api.helpers';
+import {
+  isParamValueRecord,
+  type QueryParamValueSerialization,
+  serializeRequestPluginQueryParams,
+} from '../../fwk/param-serialization';
 import {
   PluginRunner,
   RequestOptions,
   RequestPlugin,
+  RequestPluginContext,
 } from '../core';
 
 export interface AdditionalParameters {
   /** Additional headers */
   headers?: { [key: string]: string } | ((headers: Headers) => { [key: string]: string } | Promise<{ [key: string]: string }>);
   /** Additional query params */
-  queryParams?: { [key: string]: string } | ((defaultValues?: { [key: string]: string }) => { [key: string]: string } | Promise<{ [key: string]: string }>);
+  queryParams?: { [key: string]: string } | { [key: string]: QueryParamValueSerialization }
+    | ((defaultValues?: { [key: string]: string } | { [key: string]: QueryParamValueSerialization }) =>
+        { [key: string]: string } | { [key: string]: QueryParamValueSerialization } | Promise<{ [key: string]: string }> | Promise<{ [key: string]: QueryParamValueSerialization }>
+      );
   /** Additional body params */
   body?: (defaultValues?: string) => string | null | Promise<string>;
 }
@@ -37,15 +49,29 @@ export class AdditionalParamsRequest implements RequestPlugin {
     this.additionalParams = additionalParams;
   }
 
-  public load(): PluginRunner<RequestOptions, RequestOptions> {
+  public load(context?: RequestPluginContext): PluginRunner<RequestOptions, RequestOptions> {
     return {
       transform: async (data: RequestOptions) => {
         const queryParams = typeof this.additionalParams.queryParams === 'function' ? await this.additionalParams.queryParams(data.queryParams) : this.additionalParams.queryParams;
         const headers = typeof this.additionalParams.headers === 'function' ? await this.additionalParams.headers(data.headers) : this.additionalParams.headers;
         const body = this.additionalParams.body && isStringOrUndefined(data.body) ? this.additionalParams.body(data.body) : undefined;
 
         if (queryParams) {
-          data.queryParams = { ...data.queryParams, ...queryParams };
+          if (data.paramSerializationOptions?.enableParameterSerialization) {
+            if (isParamValueRecord(queryParams)) {
+              throw new Error('It is not possible to serialize additional query parameters without their serialization properties `value`, `explode`, and `style`.');
+            } else {
+              data.queryParams = { ...data.queryParams, ...serializeRequestPluginQueryParams(queryParams) };
+            }
+          } else {
+            if (isParamValueRecord(queryParams)) {
+              data.queryParams = { ...data.queryParams, ...queryParams };
+            } else {
+              const queryParamsValues = Object.fromEntries(Object.entries(queryParams).map(([key, value]) => [key, value.value]));
+              data.queryParams = { ...data.queryParams, ...stringifyQueryParams(queryParamsValues) };
+              (context?.logger || console).log('The serialization of additional query parameters has been ignored since parameter serialization is not enabled.');
+            }
+          }
         }
 
         if (body !== undefined) {