[feat] add sendFailedScreen to envoyResponse typing (#98)

* add sendFailedScreen to envoyResponse typing

* update version to 2.4.1

Author: Zmatarasso

docs/interfaces/envoyresponse.md

@@ -24,6 +24,7 @@ Use to type your `res` object in Envoy event handlers.
 - [sendFailed](envoyresponse.md#sendfailed)
 - [sendIgnored](envoyresponse.md#sendignored)
 - [sendOngoing](envoyresponse.md#sendongoing)
+- [sendFailedScreen](envoyresponse.md#sendFailedScreen)
 
 ## Properties
 
@@ -61,6 +62,12 @@ ___
 
 Marks the job as "failed". The message will be communicated to the Envoy Dashboard user.
 
+### sendFailedScreen
+
+• **sendFailedScreen**: (`message`: `string`, `debugInfo?`: `unknown`, ...`attachments`: `EnvoyPluginScreenerJobAttachment`, ) => `void`
+
+Halts processing of the job. The message will be communicated to the Envoy Dashboard user and a pop up modal for access approval will be displayed. 
+
 #### Type declaration
 
 ▸ (`message`, `debugInfo?`, ...`attachments`): `void`

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@envoy/envoy-integrations-sdk",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "SDK for building Envoy integrations.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package.json

@@ -70,9 +70,9 @@ export default class EnvoyPluginJob {
   }
 
   /**
-   * Reports that the job is ignored.
+   * Reports that the job is failed.
    *
-   * Instead of calling this directly, you can return a 400 response from the job's event handler,
+   * Instead of calling this directly, you can return a 412 response from the job's event handler,
    * using {@link EnvoyRequest.sendFailed}.
    */
   fail(message: string, reason: string): Promise<void> {

src/sdk/EnvoyPluginJob.ts

@@ -9,6 +9,17 @@ export interface EnvoyPluginTextJobAttachment {
   value: string;
 }
 
+/**
+ * Display some JSON data in Envoy's dashboard.
+ *
+ * @category Attachment
+ */
+export interface EnvoyPluginJSONJobAttachment {
+  type: 'json';
+  label: string;
+  value: unknown;
+}
+
 /**
  * Display a link in Envoy's dashboard.
  *
@@ -34,6 +45,50 @@ export interface EnvoyPluginCredentialJobAttachment extends EnvoyPluginTextJobAt
   };
 }
 
+/**
+ * Display a screener report in Envoy's dashboard,
+ * and allow for approval or rejection.
+ *
+ * @category Attachment
+ */
+export interface EnvoyPluginScreenerJobAttachment extends EnvoyPluginJSONJobAttachment {
+  label: string;
+  value: ScreenerDetails;
+}
+
+/**
+ * Screener report definitions
+ */
+export interface ScreenerDetails {
+  input: {
+    fields: ScreenerInputField[];
+  }
+  matches: ScreenerMatch[];
+}
+
+export interface ScreenerMatch {
+  headers: ScreenerMatchHeaders;
+  'visible-fields-count': number;
+  fields: ScreenerMatchField[];
+}
+
+export interface ScreenerMatchHeaders {
+  name: string; // ex: Tags
+  value: string; // ex: Content
+}
+
+export interface ScreenerMatchField {
+  name: string;
+  value: string;
+  type: 'text' | 'image';
+}
+
+export interface ScreenerInputField {
+  name: string;
+  value: string;
+  type: 'text' | 'image';
+}
+
 /**
  * Attachments to jobs, which will be displayed in the Envoy dashboard.
  * Some attachments like `credential_image` can show up in other places,
@@ -44,6 +99,7 @@ export interface EnvoyPluginCredentialJobAttachment extends EnvoyPluginTextJobAt
 type EnvoyPluginJobAttachment =
   | EnvoyPluginTextJobAttachment
   | EnvoyPluginLinkJobAttachment
-  | EnvoyPluginCredentialJobAttachment;
+  | EnvoyPluginCredentialJobAttachment
+  | EnvoyPluginScreenerJobAttachment;
 
 export default EnvoyPluginJobAttachment;

src/sdk/EnvoyPluginJobAttachment.ts

@@ -1,5 +1,5 @@
 import { Response } from 'express';
-import EnvoyPluginJobAttachment from './EnvoyPluginJobAttachment';
+import EnvoyPluginJobAttachment, { EnvoyPluginScreenerJobAttachment } from './EnvoyPluginJobAttachment';
 import EnvoyOptionsRouteResponseBody from '../internal/EnvoyOptionsRouteResponseBody';
 import EnvoySelectedValuesRouteResponseBody from '../internal/EnvoySelectedValuesRouteResponseBody';
 import EnvoyRemoteValueRouteResponseBody from '../internal/EnvoyRemoteValueRouteResponseBody';
@@ -26,6 +26,10 @@ export default interface EnvoyResponse<Body = unknown> extends Response {
    * Marks the job as "failed". The message will be communicated to the Envoy Dashboard user.
    */
   sendFailed: (message: string, debugInfo?: unknown, ...attachments: Array<EnvoyPluginJobAttachment>) => void;
+  /**
+   * Marks the job as "failed". The message will be communicated to the Envoy Dashboard user.
+   */
+  sendFailedScreen: (message: string, debugInfo?: unknown, attachment?: EnvoyPluginScreenerJobAttachment) => void;
 }
 
 /**

src/sdk/EnvoyResponse.ts

@@ -5,7 +5,7 @@ import HttpStatus from '../internal/HttpStatus';
 import EnvoySignatureVerifier, { EnvoySignatureVerifierOptions } from '../util/EnvoySignatureVerifier';
 import EnvoyRequest, { VERIFIED, VerifiedRequest } from './EnvoyRequest';
 import EnvoyResponse from './EnvoyResponse';
-import EnvoyPluginJobAttachment from './EnvoyPluginJobAttachment';
+import EnvoyPluginJobAttachment, { EnvoyPluginScreenerJobAttachment } from './EnvoyPluginJobAttachment';
 import EnvoyPluginSDK from './EnvoyPluginSDK';
 import EnvoyPluginAPI from './EnvoyPluginAPI';
 
@@ -77,6 +77,19 @@ export function envoyMiddleware(options?: EnvoySignatureVerifierOptions): Reques
           envoyResponse.setHeader('Content-Type', 'application/json');
           envoyResponse.end(JSON.stringify({ message, debugInfo, attachments }));
         };
+
+        /**
+         * Respond with "failed" for screener in case of screener matches.
+         */
+        envoyResponse.sendFailedScreen = (
+          message = '',
+          debugInfo: unknown = {},
+          attachment?: EnvoyPluginScreenerJobAttachment,
+        ) => {
+          envoyResponse.statusCode = HttpStatus.FAILED;
+          envoyResponse.setHeader('Content-Type', 'application/json');
+          envoyResponse.end(JSON.stringify({ message, debugInfo, attachment }));
+        };
         next();
       } catch (error) {
         next(error);