🔀 Merge pull request #1566 from jovotech/v4/dev

🔖 Prepare latest release

framework/src/index.ts

@@ -1,8 +1,11 @@
 import { JovoLogger } from '@jovotech/common';
 import axios from 'axios';
 
-// eslint-disable-next-line @typescript-eslint/no-var-requires
-require('source-map-support').install();
+// do not use source map support with jest.
+if (process.env.JEST_WORKER_ID === undefined) {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  require('source-map-support').install();
+}
 
 export const Logger = new JovoLogger();
 

integrations/slu-lex/docs/README.md

@@ -47,11 +47,6 @@ const app = new App({
             id: '<your-bot-id>',
             aliasId: '<your-alias-id>',
           },
-          region: '<your-aws-region>',
-          credentials: {
-            accessKeyId: '<your-access-key-id>',
-            secretAccessKey: '<your-secret-access-key>',
-          },
         }),
       ],
     }),
@@ -62,6 +57,48 @@ const app = new App({
 
 For the integration to work, you need to add all configurations shown in the code snippet above. For more information, take a look at the [configuration section](#configuration).
 
+The rest of this section provides an introduction to the steps you need to take depending on where you host your Jovo app:
+
+- [On AWS (e.g. Lambda)](#for-apps-hosted-on-aws)
+- [Outside AWS](#for-apps-hosted-outside-aws)
+
+### For Apps Hosted on AWS
+
+If you host your app on [AWS Lambda](https://www.jovo.tech/marketplace/server-lambda) and want to use Lex v2 in the same region, you only need to add the bot id and aliasId to get started:
+
+```typescript
+new LexSlu({
+  bot: {
+    id: '<your-bot-id>',
+    aliasId: '<your-alias-id>',
+  },
+}),
+```
+
+### For Apps Hosted Outside AWS
+
+If you want to use Lex v2 from outside AWS Lambda, you need to set it up for programmatic access. Learn more in the official guide by Amazon: [Identity and access management for Amazon Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/security-iam.html) and [Setting credentials in Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html).
+
+You can then add the necessary keys using the [`libraryConfig` property](#libraryconfig):
+
+```typescript
+new LexSlu({
+  bot: {
+    id: '<your-bot-id>',
+    aliasId: '<your-alias-id>',
+  },
+  libraryConfig: {
+    lexRuntimeV2Client: {
+      region: 'us-east-1',
+      credentials: {
+        accessKeyId: 'myAccessKeyId',
+        secretAccessKey: 'mySecretAccessKey',
+      },
+    }
+  }
+  // ...
+}),
+```
 ## Configuration
 
 The following configurations can be added:
@@ -72,11 +109,6 @@ new LexSlu({
     id: '',
     aliasId: ''
   },
-  region: '',
-  credentials: {
-    accessKeyId: '',
-    secretAccessKey: '',
-  },
   fallbackLocale: 'en_US',
   localeMap: {
     'en': 'en_US',
@@ -88,13 +120,45 @@ new LexSlu({
 ```
 
 - `bot`: Includes information about your created Lex bot.
-- `region`: The AWS region of the Lex bot, for example `us-east-1`.
-- `credentials`: Your AWS security credentials.
+- `libraryConfig`: Any configuration for the AWS Lex v2 SDK can be passed here. [Learn more below](#libraryconfig).
+- `region`: (deprecated: use `libraryConfig`) The AWS region of the Lex bot, for example `us-east-1`.
+- `credentials`: (deprecated: use `libraryConfig`) Your AWS security credentials.
 - `fallbackLocale`: Locale that should be used if none could be found in the request. Default: `en_US`.
 - `localeMap` (optional): This is used to map a request locale to a Lex localeId.
 - `asr`: Determines whether the Lex [ASR](https://www.jovo.tech/docs/asr) capabilities should be used. Default: `true`.
 - `nlu`: Determines whether the Lex [NLU](https://www.jovo.tech/docs/nlu) capabilities should be used. Default: `true`.
 
+### libraryConfig
+
+The `libraryConfig` property can be used to pass configurations to the AWS Lex v2 SDK that is used by this integration.
+
+Currently, it includes options for the [LexRuntimeV2Client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/lex-runtime-v2/):
+
+```typescript
+new LexSlu({
+  bot: { /* ... */ },
+  libraryConfig: { /* ... */ }
+  // ...
+}),
+```
+
+For example, you can add `credentials` like this:
+
+```typescript
+new LexSlu({
+  libraryConfig: {
+    lexRuntimeV2Client: {
+      region: 'us-east-1',
+      credentials: {
+        accessKeyId: 'myAccessKeyId',
+        secretAccessKey: 'mySecretAccessKey',
+      },
+    }
+  }
+
+}),
+```
+
 ## Entities
 
 You can access Lex slots by using the `$entities` property. You can learn more in the [Jovo Model](https://www.jovo.tech/docs/models) and the [`$entities` documentation](https://www.jovo.tech/docs/entities).

integrations/slu-lex/src/LexSlu.ts

@@ -8,8 +8,9 @@ import {
   RecognizeUtteranceCommand,
   RecognizeUtteranceCommandInput,
   DialogAction,
+  LexRuntimeV2ClientConfig,
 } from '@aws-sdk/client-lex-runtime-v2';
-import type { Credentials } from '@aws-sdk/types';
+import type { AwsCredentialIdentity } from '@aws-sdk/types';
 import {
   AsrData,
   DeepPartial,
@@ -57,17 +58,19 @@ export interface LexSluConfig extends InterpretationPluginConfig {
     id: string;
     aliasId: string;
   };
-  credentials: Credentials;
-  region: string;
+  credentials?: AwsCredentialIdentity; // @deprecated use libraryConfig
+  region?: string; // @deprecated use libraryConfig
   locale?: string;
   localeMap?: Record<string, string>;
   fallbackLocale: string;
   asr: boolean;
   nlu: boolean;
+  libraryConfig?: {
+    lexRuntimeV2Client?: LexRuntimeV2ClientConfig;
+  };
 }
 
-export type LexSluInitConfig = DeepPartial<LexSluConfig> &
-  Pick<LexSluConfig, 'bot' | 'credentials' | 'region'>;
+export type LexSluInitConfig = DeepPartial<LexSluConfig> & Pick<LexSluConfig, 'bot'>;
 
 export class LexSlu extends SluPlugin<LexSluConfig> {
   targetSampleRate = 16000;
@@ -99,35 +102,36 @@ export class LexSlu extends SluPlugin<LexSluConfig> {
   constructor(config: LexSluInitConfig) {
     super(config);
 
-    this.client = new LexRuntimeV2Client({
-      credentials: this.config.credentials,
-      region: this.config.region,
-    });
+    const clientConfig = this.config?.libraryConfig || {};
+    if (!clientConfig.lexRuntimeV2Client) {
+      clientConfig.lexRuntimeV2Client = {};
+    }
+
+    // handle deprecated properties
+    if (this.config.credentials) {
+      clientConfig.lexRuntimeV2Client.credentials = this.config.credentials;
+    }
+
+    if (this.config.region) {
+      clientConfig.lexRuntimeV2Client.region = this.config.region;
+    }
+
+    this.client = new LexRuntimeV2Client(clientConfig.lexRuntimeV2Client);
   }
 
   getDefaultConfig(): LexSluConfig {
     return {
       ...super.getDefaultConfig(),
       bot: { id: '', aliasId: '' },
-      region: '',
-      credentials: {
-        accessKeyId: '',
-        secretAccessKey: '',
-      },
       fallbackLocale: 'en_US',
       asr: true,
       nlu: true,
     };
   }
 
-  getInitConfig(): RequiredOnlyWhere<LexSluConfig, 'credentials' | 'region' | 'bot'> {
+  getInitConfig(): RequiredOnlyWhere<LexSluConfig, 'bot'> {
     return {
       bot: { id: '', aliasId: '' },
-      region: '',
-      credentials: {
-        accessKeyId: '',
-        secretAccessKey: '',
-      },
     };
   }