@defra/forms-engine-plugin 0.1.18 → 0.1.20

package/.server/server/plugins/session.d.ts

@@ -0,0 +1,24 @@
+import yar from '@hapi/yar';
+/**
+ * Yar is used for temporary session data but not form submissions, e.g. UI helpers, session flags.
+ */
+declare const _default: {
+    plugin: import("@hapi/hapi").Plugin<yar.YarOptions>;
+    options: {
+        maxCookieSize: number;
+        cache: {
+            cache: string;
+            segment: string;
+            expiresIn: number;
+        };
+        /**
+         * @todo storeBlank is current commented out as it's a minor efficiency gain but breaks the auth tests if enabled.
+         * this only seems to affect the auth code, which we might remove anyway so it's temporarily disabled.
+         */
+        cookieOptions: {
+            password: string;
+            isSecure: boolean;
+        };
+    };
+};
+export default _default;

package/.server/server/routes/index.d.ts

@@ -0,0 +1 @@
+export { default as publicRoutes } from '~/src/server/routes/public.js';

package/.server/server/routes/public.d.ts

@@ -0,0 +1,15 @@
+declare const _default: {
+    method: "GET";
+    path: string;
+    options: {
+        cache: {
+            otherwise: string;
+        };
+        handler: {
+            directory: {
+                path: string;
+            };
+        };
+    };
+}[];
+export default _default;

package/.server/server/routes/types.d.ts

@@ -0,0 +1,38 @@
+import { type ReqRefDefaults, type Request } from '@hapi/hapi';
+import { type FormPayload } from '~/src/server/plugins/engine/types.js';
+export interface FormQuery extends Partial<Record<string, string>> {
+    /**
+     * Allow preview URL direct access without relevant page checks
+     */
+    force?: string;
+    /**
+     * Redirect location after 'continue' form action
+     */
+    returnUrl?: string;
+}
+export interface FormParams extends Partial<Record<string, string>> {
+    path: string;
+    slug: string;
+    state?: FormStatus;
+}
+export interface FormRequestRefs extends Omit<ReqRefDefaults, 'Params' | 'Payload' | 'Query'> {
+    Params: FormParams;
+    Payload: object | undefined;
+    Query: FormQuery;
+}
+export interface FormRequestPayloadRefs extends FormRequestRefs {
+    Payload: FormPayload;
+}
+export type FormRequest = Request<FormRequestRefs>;
+export type FormRequestPayload = Request<FormRequestPayloadRefs>;
+export declare enum FormAction {
+    Continue = "continue",
+    Validate = "validate",
+    Delete = "delete",
+    AddAnother = "add-another",
+    Send = "send"
+}
+export declare enum FormStatus {
+    Draft = "draft",
+    Live = "live"
+}

package/.server/server/schemas/index.d.ts

@@ -0,0 +1,10 @@
+import Joi from 'joi';
+import { type FormParams } from '~/src/server/plugins/engine/types.js';
+import { FormAction, FormStatus } from '~/src/server/routes/types.js';
+export declare const stateSchema: Joi.StringSchema<FormStatus>;
+export declare const actionSchema: Joi.StringSchema<FormAction>;
+export declare const pathSchema: Joi.StringSchema<string>;
+export declare const itemIdSchema: Joi.StringSchema<string>;
+export declare const crumbSchema: Joi.StringSchema<string>;
+export declare const confirmSchema: Joi.BooleanSchema<boolean>;
+export declare const paramsSchema: Joi.ObjectSchema<FormParams>;

package/.server/server/secure-context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Prepares the TLS secure context
+ * @param {Server} server
+ * @returns
+ */
+export function prepareSecureContext(server: Server): tls.SecureContext;
+/**
+ * @type {SecureContext}
+ */
+export let secureContext: tls.SecureContext;
+import type { Server } from '@hapi/hapi';
+import tls from 'node:tls';

package/.server/server/services/cacheService.d.ts

@@ -0,0 +1,49 @@
+import { type Request, type Server } from '@hapi/hapi';
+import { type FormPayload, type FormState, type FormSubmissionError, type FormSubmissionState } from '~/src/server/plugins/engine/types.js';
+import { type FormRequest, type FormRequestPayload } from '~/src/server/routes/types.js';
+declare enum ADDITIONAL_IDENTIFIER {
+    Confirmation = ":confirmation"
+}
+export declare class CacheService {
+    /**
+     * This service is responsible for getting, storing or deleting a user's session data in the cache. This service has been registered by {@link createServer}
+     */
+    cache: import("@hapi/catbox").Policy<unknown, {
+        cache: string | undefined;
+        segment: string;
+    }>;
+    logger: Server['logger'];
+    constructor(server: Server, cacheName?: string);
+    getState(request: Request | FormRequest | FormRequestPayload): Promise<FormSubmissionState>;
+    setState(request: FormRequest | FormRequestPayload, state: FormSubmissionState): Promise<FormSubmissionState>;
+    getConfirmationState(request: FormRequest | FormRequestPayload): Promise<{
+        confirmed?: true;
+    }>;
+    setConfirmationState(request: FormRequest | FormRequestPayload, confirmationState: {
+        confirmed?: true;
+    }): Promise<void>;
+    clearState(request: FormRequest | FormRequestPayload): Promise<void>;
+    getFlash(request: FormRequest | FormRequestPayload): {
+        errors: FormSubmissionError[];
+    } | undefined;
+    setFlash(request: FormRequest | FormRequestPayload, message: {
+        errors: FormSubmissionError[];
+    }): void;
+    /**
+     * The key used to store user session data against.
+     * If there are multiple forms on the same runner instance, for example `form-a` and `form-a-feedback` this will prevent CacheService from clearing data from `form-a` if a user gave feedback before they finished `form-a`
+     * @param request - hapi request object
+     * @param additionalIdentifier - appended to the id
+     */
+    Key(request: Request | FormRequest | FormRequestPayload, additionalIdentifier?: ADDITIONAL_IDENTIFIER): {
+        segment: string;
+        id: string;
+    };
+}
+/**
+ * State merge helper
+ * 1. Merges objects (form fields)
+ * 2. Overwrites arrays
+ */
+export declare function merge<StateType extends FormState | FormPayload>(state: StateType, update: object): StateType;
+export {};

package/.server/server/services/httpService.d.ts

@@ -0,0 +1,57 @@
+import Wreck from '@hapi/wreck';
+export type Method = keyof Pick<typeof Wreck, 'get' | 'post' | 'put' | 'delete'>;
+export type RequestOptions = Parameters<typeof Wreck.defaults>[0];
+export declare const request: <BodyType = Buffer<ArrayBufferLike>>(method: Method, url: string, options?: RequestOptions) => Promise<{
+    res: import("http").IncomingMessage;
+    error: Error | NonNullable<BodyType>;
+    payload?: undefined;
+} | {
+    res: import("http").IncomingMessage;
+    payload: BodyType;
+    error?: undefined;
+}>;
+export declare const get: <BodyType>(url: string, options?: RequestOptions) => Promise<{
+    res: import("http").IncomingMessage;
+    error: Error | NonNullable<BodyType>;
+    payload?: undefined;
+} | {
+    res: import("http").IncomingMessage;
+    payload: BodyType;
+    error?: undefined;
+}>;
+export declare const getJson: <BodyType extends object>(url: string) => Promise<{
+    res: import("http").IncomingMessage;
+    error: Error | BodyType;
+    payload?: undefined;
+} | {
+    res: import("http").IncomingMessage;
+    payload: BodyType;
+    error?: undefined;
+}>;
+export declare const post: <BodyType>(url: string, options: RequestOptions) => Promise<{
+    res: import("http").IncomingMessage;
+    error: Error | NonNullable<BodyType>;
+    payload?: undefined;
+} | {
+    res: import("http").IncomingMessage;
+    payload: BodyType;
+    error?: undefined;
+}>;
+export declare const postJson: <BodyType extends object>(url: string, options: RequestOptions) => Promise<{
+    res: import("http").IncomingMessage;
+    error: Error | BodyType;
+    payload?: undefined;
+} | {
+    res: import("http").IncomingMessage;
+    payload: BodyType;
+    error?: undefined;
+}>;
+export declare const put: <BodyType>(url: string, options: RequestOptions) => Promise<{
+    res: import("http").IncomingMessage;
+    error: Error | NonNullable<BodyType>;
+    payload?: undefined;
+} | {
+    res: import("http").IncomingMessage;
+    payload: BodyType;
+    error?: undefined;
+}>;

package/.server/server/services/index.d.ts

@@ -0,0 +1 @@
+export { CacheService } from '~/src/server/services/cacheService.js';

package/.server/server/types.d.ts

@@ -0,0 +1,31 @@
+import { type FormDefinition, type FormMetadata, type SubmitPayload, type SubmitResponsePayload } from '@defra/forms-model';
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js';
+import { type DetailItem } from '~/src/server/plugins/engine/models/types.js';
+import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js';
+import { type FormRequestPayload, type FormStatus } from '~/src/server/routes/types.js';
+export interface FormsService {
+    getFormMetadata: (slug: string) => Promise<FormMetadata>;
+    getFormDefinition: (id: string, state: FormStatus) => Promise<FormDefinition | undefined>;
+}
+export interface FormSubmissionService {
+    persistFiles: (files: {
+        fileId: string;
+        initiatedRetrievalKey: string;
+    }[], persistedRetrievalKey: string) => Promise<object>;
+    submit: (data: SubmitPayload) => Promise<SubmitResponsePayload | undefined>;
+}
+export interface Services {
+    formsService: FormsService;
+    formSubmissionService: FormSubmissionService;
+    outputService: OutputService;
+}
+export interface RouteConfig {
+    formFileName?: string;
+    formFilePath?: string;
+    enforceCsrf?: boolean;
+    services?: Services;
+    controllers?: Record<string, typeof PageController>;
+}
+export interface OutputService {
+    submit: (request: FormRequestPayload, model: FormModel, emailAddress: string, items: DetailItem[], submitResponse: SubmitResponsePayload) => Promise<void>;
+}

package/.server/server/utils/file-form-service.d.ts

@@ -0,0 +1,50 @@
+/**
+ * FileFormService class
+ */
+export class FileFormService {
+    /**
+     * Add form from a file
+     * @param {string} filepath - the file path
+     * @param {FormMetadata} metadata - the metadata to use for this form
+     * @returns {Promise<FormDefinition>}
+     */
+    addForm(filepath: string, metadata: FormMetadata): Promise<FormDefinition>;
+    /**
+     * Read the form definition from file
+     * @param {string} filepath - the file path
+     * @returns {Promise<FormDefinition>}
+     */
+    readForm(filepath: string): Promise<FormDefinition>;
+    /**
+     * Read the form definition from a json file
+     * @param {string} filepath - the file path
+     * @returns {Promise<FormDefinition>}
+     */
+    readJsonForm(filepath: string): Promise<FormDefinition>;
+    /**
+     * Read the form definition from a yaml file
+     * @param {string} filepath - the file path
+     * @returns {Promise<FormDefinition>}
+     */
+    readYamlForm(filepath: string): Promise<FormDefinition>;
+    /**
+     * Get the form metadata by slug
+     * @param {string} slug - the form slug
+     * @returns {FormMetadata}
+     */
+    getFormMetadata(slug: string): FormMetadata;
+    /**
+     * Get the form defintion by id
+     * @param {string} id - the form id
+     * @returns {FormDefinition}
+     */
+    getFormDefinition(id: string): FormDefinition;
+    /**
+     * Returns a FormsService compliant interface
+     * @returns {import('~/src/server/types.js').FormsService}
+     */
+    toFormsService(): import("~/src/server/types.js").FormsService;
+    #private;
+}
+import type { FormMetadata } from '@defra/forms-model';
+import type { FormDefinition } from '@defra/forms-model';

package/.server/server/utils/notify.d.ts

@@ -0,0 +1,17 @@
+export interface SendNotificationArgs {
+    templateId: string;
+    emailAddress: string;
+    personalisation: {
+        subject: string;
+        body: string;
+    };
+}
+export declare function sendNotification(args: SendNotificationArgs): Promise<{
+    res: import("http").IncomingMessage;
+    error: object | Error;
+    payload?: undefined;
+} | {
+    res: import("http").IncomingMessage;
+    payload: object;
+    error?: undefined;
+}>;

package/.server/server/utils/secure-context/get-trust-store-certs.d.ts

@@ -0,0 +1 @@
+export function getTrustStoreCerts(envs: NodeJS.ProcessEnv): string[];

package/.server/server/utils/type-utils.d.ts

@@ -0,0 +1,3 @@
+import { type JoiExpression, type LanguageMessages, type LanguageMessagesExt } from 'joi';
+export declare function convertToLanguageMessages(extLanguageMessages: LanguageMessagesExt): LanguageMessages;
+export declare function createJoiExpression(expr: string): JoiExpression;

package/.server/server/utils/utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a set of headers to use in an HTTP request, merging them with any existing headers in options.
+ * @param {Record<string, string> | undefined} [existingHeaders] - Optional existing headers to merge with the tracing headers.
+ * @param {string} [header] - The tracing header name to use.
+ * @returns {Record<string, string> | undefined} The merged headers, or undefined if no tracing header is available.
+ */
+export function applyTraceHeaders(existingHeaders?: Record<string, string> | undefined, header?: string): Record<string, string> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/forms-engine-plugin",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Defra forms engine",
   "type": "module",
   "files": [
@@ -29,9 +29,10 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "npm run build:server && npm run build:client",
+    "build": "rm -rf ./.server && npm run build:server && npm run build:client && npm run build:types",
     "build:client": "NODE_ENV=${NODE_ENV:-production} webpack",
     "build:server": "babel --delete-dir-on-start --extensions \".js\",\".ts\" --ignore \"**/*.test.ts\" --copy-files --no-copy-ignored --source-maps --out-dir ./.server ./src",
+    "build:types": "tsc -p tsconfig.build.json",
     "dev": "concurrently \"npm run client:watch\" \"npm run server:watch:dev\" --kill-others --names \"client,server\" --prefix-colors \"red.dim,blue.dim\"",
     "dev:debug": "concurrently \"npm run client:watch\" \"npm run server:watch:debug\" --kill-others --names \"client,server\" --prefix-colors \"red.dim,blue.dim\"",
     "format": "npm run format:check -- --write",

package/src/config/index.ts

@@ -84,7 +84,7 @@ export const config = convict({
   serviceName: {
     doc: 'Applications Service Name',
     format: String,
-    default: 'Submit a form to Defra'
+    default: 'Digital Express Toolkit'
   },
   serviceVersion: {
     doc: 'The service version, this variable is injected into your docker container in CDP environments',

package/src/server/devserver/dxt-devtool-baselayout.html

@@ -36,7 +36,7 @@
     homepageUrl: currentPath if context.isForceAccess else "https://defra.github.io/forms-engine-plugin/",
     containerClasses: "govuk-width-container",
     productName: productName | safe | trim,
-    serviceName: "Digital Express Toolkit",
+    serviceName: config.serviceName,
     serviceUrl: currentPath if context.isForceAccess else serviceUrl
   }) }}
 {% endblock %}

package/src/server/plugins/nunjucks/context.js

@@ -4,7 +4,6 @@ import { basename, join } from 'node:path'
 import Boom from '@hapi/boom'
 import { StatusCodes } from 'http-status-codes'
 
-import pkg from '~/package.json' with { type: 'json' }
 import { config } from '~/src/config/index.js'
 import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
 import {
@@ -32,6 +31,7 @@ export async function context(request) {
     !Boom.isBoom(response) && response?.statusCode === StatusCodes.OK
 
   const pluginStorage = request?.server.plugins['forms-engine-plugin']
+
   let consumerViewContext = {}
 
   if (!pluginStorage) {
@@ -51,15 +51,6 @@ export async function context(request) {
     // take consumers props first so we can override it
     ...consumerViewContext,
     baseLayoutPath: pluginStorage.baseLayoutPath,
-    appVersion: pkg.version,
-    config: {
-      cdpEnvironment: config.get('cdpEnvironment'),
-      designerUrl: config.get('designerUrl'),
-      feedbackLink: encodeUrl(config.get('feedbackLink')),
-      phaseTag: config.get('phaseTag'),
-      serviceName: config.get('serviceName'),
-      serviceVersion: config.get('serviceVersion')
-    },
     crumb: safeGenerateCrumb(request),
     currentPath: `${request.path}${request.url.search}`,
     previewMode: isPreviewMode ? formState : undefined,
@@ -87,6 +78,14 @@ export function devtoolContext(_request) {
   }
 
   return {
+    config: {
+      cdpEnvironment: config.get('cdpEnvironment'),
+      designerUrl: config.get('designerUrl'),
+      feedbackLink: encodeUrl(config.get('feedbackLink')),
+      phaseTag: config.get('phaseTag'),
+      serviceName: config.get('serviceName'),
+      serviceVersion: config.get('serviceVersion')
+    },
     assetPath: '/assets',
     getDxtAssetPath: (asset = '') => {
       return `/${webpackManifest?.[asset] ?? asset}`

package/src/server/plugins/nunjucks/types.js

@@ -11,20 +11,13 @@
 
 /**
  * @typedef {object} ViewContext - Nunjucks view context
- * @property {string} appVersion - Application version
  * @property {string} [baseLayoutPath] - Base layout path
- * @property {Partial<Config>} config - Application config properties
  * @property {string} [crumb] - Cross-Site Request Forgery (CSRF) token
  * @property {string} [cspNonce] - Content Security Policy (CSP) nonce
  * @property {string} [currentPath] - Current path
  * @property {string} [previewMode] - Preview mode
  * @property {string} [slug] - Form slug
  * @property {FormContext} [context] - the current form context
- * @property {PluginOptions['viewContext']} [injectedViewContext] - the current form context
- */
-
-/**
- * @typedef {ReturnType<typeof config['getProperties']>} Config - Application config properties
  */
 
 /**