@defra/forms-model 3.0.52 → 3.0.54

package/dist/types/index.d.ts

@@ -1,4 +1,3 @@
-export * from './schema/index.js';
 export * from './data-model/index.js';
 export * from './utils/logger.js';
 export * from './form/index.js';
@@ -8,5 +7,5 @@ export * from './utils/helpers.js';
 export * from './migration/index.js';
 export type * from './components/types.js';
 export type * from './conditions/types.js';
-export type * from './data-model/types.js';
+export type * from './form/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,2BAA2B,CAAA;AACzC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,2BAA2B,CAAA;AACzC,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,0BAA0B,CAAA;AACxC,mBAAmB,2BAA2B,CAAA;AAC9C,mBAAmB,2BAA2B,CAAA;AAC9C,mBAAmB,2BAA2B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAA;AACzC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,2BAA2B,CAAA;AACzC,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,0BAA0B,CAAA;AACxC,mBAAmB,2BAA2B,CAAA;AAC9C,mBAAmB,2BAA2B,CAAA;AAC9C,mBAAmB,qBAAqB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/forms-model",
-  "version": "3.0.52",
+  "version": "3.0.54",
   "description": "A hapi plugin providing the model for Defra forms",
   "homepage": "https://github.com/DEFRA/forms-designer/tree/main/model#readme",
   "repository": {

package/src/data-model/conditions-wrapper.ts

@@ -2,7 +2,7 @@ import { ConditionsModel } from '~/src/conditions/condition-model.js'
 import {
   type ConditionRawData,
   type ConditionWrapperValue
-} from '~/src/data-model/types.js'
+} from '~/src/form/types.js'
 
 export class ConditionsWrapper {
   name: string

package/src/data-model/helpers.ts

@@ -1,4 +1,4 @@
-import { type MultipleApiKeys } from '~/src/data-model/types.js'
+import { type MultipleApiKeys } from '~/src/form/types.js'
 
 export function isMultipleApiKey(
   payApiKey: string | MultipleApiKeys | undefined

package/src/data-model/input-wrapper.ts

@@ -1,5 +1,5 @@
 import { type ComponentDef } from '~/src/components/types.js'
-import { type Page } from '~/src/data-model/types.js'
+import { type Page } from '~/src/form/types.js'
 import { clone } from '~/src/utils/helpers.js'
 
 export class InputWrapper {

package/src/form/form-definition/index.ts

@@ -0,0 +1,300 @@
+import Joi from 'joi'
+
+import { type FormDefinition } from '~/src/form/form-definition/types.js'
+
+/**
+ * If an optional key is added, CURRENT_VERSION does not need to be incremented.
+ * Only breaking changes will require an increment, as well as a migration script.
+ */
+export const CURRENT_VERSION = 2
+
+const sectionsSchema = Joi.object().keys({
+  name: Joi.string().required(),
+  title: Joi.string().required(),
+  hideTitle: Joi.boolean().default(false)
+})
+
+const conditionFieldSchema = Joi.object().keys({
+  name: Joi.string().required(),
+  type: Joi.string().required(),
+  display: Joi.string().required()
+})
+
+const conditionValueSchema = Joi.object().keys({
+  type: Joi.string().required(),
+  value: Joi.string().required(),
+  display: Joi.string().required()
+})
+
+const relativeTimeValueSchema = Joi.object().keys({
+  type: Joi.string().required(),
+  timePeriod: Joi.string().required(),
+  timeUnit: Joi.string().required(),
+  direction: Joi.string().required(),
+  timeOnly: Joi.boolean().required()
+})
+
+const conditionRefSchema = Joi.object().keys({
+  conditionName: Joi.string().required(),
+  conditionDisplayName: Joi.string().required(),
+  coordinator: Joi.string().optional()
+})
+
+const conditionSchema = Joi.object().keys({
+  field: conditionFieldSchema,
+  operator: Joi.string().required(),
+  value: Joi.alternatives().try(conditionValueSchema, relativeTimeValueSchema),
+  coordinator: Joi.string().optional()
+})
+
+const conditionGroupSchema = Joi.object().keys({
+  conditions: Joi.array().items(
+    Joi.alternatives().try(
+      conditionSchema,
+      conditionRefSchema,
+      Joi.any() /** Should be a joi.link('#conditionGroupSchema') */
+    )
+  )
+})
+
+const conditionsModelSchema = Joi.object().keys({
+  name: Joi.string().required(),
+  conditions: Joi.array().items(
+    Joi.alternatives().try(
+      conditionSchema,
+      conditionRefSchema,
+      conditionGroupSchema
+    )
+  )
+})
+
+const conditionsSchema = Joi.object().keys({
+  name: Joi.string().required(),
+  displayName: Joi.string(),
+  value: Joi.alternatives().try(Joi.string(), conditionsModelSchema).required()
+})
+
+const localisedString = Joi.alternatives().try(
+  Joi.object({ a: Joi.any() }).unknown(),
+  Joi.string().allow('')
+)
+
+export const componentSchema = Joi.object()
+  .keys({
+    type: Joi.string().required(),
+    name: Joi.string(),
+    title: localisedString,
+    hint: localisedString.optional(),
+    options: Joi.object().default({}),
+    schema: Joi.object({ min: Joi.number(), max: Joi.number() })
+      .unknown(true)
+      .default({}),
+    list: Joi.string().optional()
+  })
+  .unknown(true)
+
+const nextSchema = Joi.object().keys({
+  path: Joi.string().required(),
+  condition: Joi.string().allow('').optional(),
+  redirect: Joi.string().uri().optional()
+})
+
+/**
+ * `/status` is a special route for providing a user's application status.
+ *  It should not be configured via the designer.
+ */
+const pageSchema = Joi.object().keys({
+  path: Joi.string().required().disallow('/status'),
+  title: localisedString,
+  section: Joi.string(),
+  controller: Joi.string(),
+  components: Joi.array().items(componentSchema),
+  next: Joi.array().items(nextSchema),
+  repeatField: Joi.string().optional(),
+  options: Joi.object().optional(),
+  backLinkFallback: Joi.string().optional()
+})
+
+const toggleableString = Joi.alternatives().try(Joi.boolean(), Joi.string())
+
+const confirmationPageSchema = Joi.object({
+  customText: Joi.object({
+    title: Joi.string().default('Application complete'),
+    paymentSkipped: toggleableString.default(
+      'Someone will be in touch to make a payment.'
+    ),
+    nextSteps: toggleableString.default(
+      'You will receive an email with details with the next steps.'
+    )
+  }).default(),
+  components: Joi.array().items(componentSchema)
+})
+
+const paymentSkippedWarningPage = Joi.object({
+  customText: Joi.object({
+    title: Joi.string().default('Pay for your application').optional(),
+    caption: Joi.string().default('Payment').optional(),
+    body: Joi.string().default('').optional()
+  })
+})
+
+const specialPagesSchema = Joi.object().keys({
+  confirmationPage: confirmationPageSchema.optional(),
+  paymentSkippedWarningPage: paymentSkippedWarningPage.optional()
+})
+
+const listItemSchema = Joi.object().keys({
+  text: localisedString,
+  value: Joi.alternatives().try(Joi.number(), Joi.string()),
+  description: localisedString.optional(),
+  conditional: Joi.object()
+    .keys({
+      components: Joi.array()
+        .required()
+        .items(componentSchema.unknown(true))
+        .unique('name')
+    })
+    .allow(null)
+    .optional(),
+  condition: Joi.string().allow(null, '').optional()
+})
+
+const listSchema = Joi.object().keys({
+  name: Joi.string().required(),
+  title: localisedString,
+  type: Joi.string().required().valid('string', 'number'),
+  items: Joi.array().items(listItemSchema)
+})
+
+const feeSchema = Joi.object().keys({
+  description: Joi.string().required(),
+  amount: Joi.number().required(),
+  multiplier: Joi.string().optional(),
+  condition: Joi.string().optional(),
+  prefix: Joi.string().optional()
+})
+
+const multiApiKeySchema = Joi.object({
+  test: Joi.string().optional(),
+  production: Joi.string().optional()
+})
+
+const replyToConfigurationSchema = Joi.object({
+  emailReplyToId: Joi.string(),
+  condition: Joi.string().allow('').optional()
+})
+
+const notifySchema = Joi.object().keys({
+  apiKey: [Joi.string().allow('').optional(), multiApiKeySchema],
+  templateId: Joi.string(),
+  emailField: Joi.string(),
+  personalisation: Joi.array().items(Joi.string()),
+  personalisationFieldCustomisation: Joi.object()
+    .pattern(/./, Joi.array().items(Joi.string()))
+    .optional(),
+  addReferencesToPersonalisation: Joi.boolean().optional(),
+  emailReplyToIdConfiguration: Joi.array().items(replyToConfigurationSchema)
+})
+
+const emailSchema = Joi.object().keys({
+  emailAddress: Joi.string()
+})
+
+const webhookSchema = Joi.object().keys({
+  url: Joi.string(),
+  allowRetry: Joi.boolean().default(true)
+})
+
+const outputSchema = Joi.object().keys({
+  name: Joi.string(),
+  title: Joi.string().optional(),
+  type: Joi.string().allow('notify', 'email', 'webhook', 'sheets'),
+  outputConfiguration: Joi.alternatives().try(
+    notifySchema,
+    emailSchema,
+    webhookSchema
+  )
+})
+
+const feedbackSchema = Joi.object().keys({
+  feedbackForm: Joi.boolean().default(false),
+  url: Joi.when('feedbackForm', {
+    is: Joi.boolean().valid(false),
+    then: Joi.string().optional().allow('')
+  }),
+  emailAddress: Joi.string()
+    .email({
+      tlds: {
+        allow: false
+      }
+    })
+    .optional()
+})
+
+const phaseBannerSchema = Joi.object().keys({
+  phase: Joi.string().valid('alpha', 'beta')
+})
+
+const feeOptionSchema = Joi.object()
+  .keys({
+    payApiKey: [Joi.string().allow('').optional(), multiApiKeySchema],
+    paymentReferenceFormat: [Joi.string().optional()],
+    payReturnUrl: Joi.string().optional(),
+    allowSubmissionWithoutPayment: Joi.boolean().optional().default(true),
+    maxAttempts: Joi.number().optional().default(3),
+    customPayErrorMessage: Joi.string().optional(),
+    showPaymentSkippedWarningPage: Joi.when('allowSubmissionWithoutPayment', {
+      is: true,
+      then: Joi.boolean().valid(true, false).default(false),
+      otherwise: Joi.boolean().valid(false).default(false)
+    })
+  })
+  .default(({ payApiKey, paymentReferenceFormat }) => {
+    return {
+      ...(payApiKey && { payApiKey }),
+      ...(paymentReferenceFormat && { paymentReferenceFormat })
+    }
+  })
+
+/**
+ * Joi schema for `FormDefinition` interface
+ * @see {@link FormDefinition}
+ */
+export const formDefinitionSchema = Joi.object()
+  .required()
+  .keys({
+    name: localisedString.optional(),
+    feedback: feedbackSchema,
+    startPage: Joi.string().required(),
+    pages: Joi.array().required().items(pageSchema).unique('path'),
+    sections: Joi.array().items(sectionsSchema).unique('name').required(),
+    conditions: Joi.array().items(conditionsSchema).unique('name'),
+    lists: Joi.array().items(listSchema).unique('name'),
+    fees: Joi.array().items(feeSchema).optional(),
+    paymentReferenceFormat: Joi.string().optional(),
+    metadata: Joi.object({ a: Joi.any() }).unknown().optional(),
+    declaration: Joi.string().allow('').optional(),
+    outputs: Joi.array().items(outputSchema),
+    payApiKey: [Joi.string().allow('').optional(), multiApiKeySchema],
+    skipSummary: Joi.boolean().default(false),
+    version: Joi.number().default(CURRENT_VERSION),
+    phaseBanner: phaseBannerSchema,
+    specialPages: specialPagesSchema.optional(),
+    feeOptions: feeOptionSchema
+  })
+
+// Maintain compatibility with legacy named export
+// E.g. `import { Schema } from '@defra/forms-model'`
+export const Schema = formDefinitionSchema
+
+/**
+ *  Schema versions:
+ *  Undefined / 0 - initial version as at 28/8/20. Conditions may be in object structure or string form.
+ *  1 - Relevant components (radio, checkbox, select, autocomplete) now contain
+ *      options as 'values' rather than referencing a data list
+ *  2 - Reverse v1. Values populating radio, checkboxes, select, autocomplete are defined in Lists only.
+ *  TODO:- merge fees and paymentReferenceFormat
+ *  2 - 2023-05-04 `feeOptions` has been introduced. paymentReferenceFormat and payApiKey can be configured in top level or feeOptions. feeOptions will take precedent.
+ *      if feeOptions are empty, it will pull values from the top level keys.
+ *      WARN: Fee/GOV.UK pay configurations (apart from fees) should no longer be stored in the top level, always within feeOptions.
+ */

package/src/{data-model → form/form-definition}/types.ts

@@ -1,6 +1,7 @@
 import { type ComponentDef } from '~/src/components/types.js'
 import { type Condition } from '~/src/conditions/condition.js'
 import { type OutputType } from '~/src/data-model/enums.js'
+import { formDefinitionSchema } from '~/src/form/form-definition/index.js'
 
 type Toggleable<T> = boolean | T
 
@@ -8,6 +9,7 @@ export interface Next {
   path: string
   condition?: string
 }
+
 export type Link = Next
 
 export interface Page {
@@ -155,7 +157,8 @@ export interface ConditionRawData {
 }
 
 /**
- * `FormDefinition` is a typescript representation of `Schema`
+ * Interface for `formDefinitionSchema` Joi schema
+ * @see {@link formDefinitionSchema}
  */
 export interface FormDefinition {
   pages: (Page | RepeatingFieldPage)[]

package/src/form/form-metadata/index.ts

@@ -0,0 +1,16 @@
+import Joi from 'joi'
+
+import { type FormMetadata } from '~/src/form/form-metadata/types.js'
+
+/**
+ * Joi schema for `FormMetadata` interface
+ * @see {@link FormMetadata}
+ */
+export const formMetadataSchema = Joi.object()
+  .keys({
+    title: Joi.string().max(250).trim().required(),
+    organisation: Joi.string().max(100).trim().required(),
+    teamName: Joi.string().max(100).trim().required(),
+    teamEmail: Joi.string().email().trim().required()
+  })
+  .required()

package/src/form/form-metadata/types.ts

@@ -0,0 +1,41 @@
+import { formMetadataSchema } from '~/src/form/form-metadata/index.js'
+
+/**
+ * Interface for `formMetadataSchema` Joi schema
+ * @see {@link formMetadataSchema}
+ */
+export interface FormMetadata {
+  /**
+   * The id of the form
+   */
+  id: string
+
+  /**
+   * The human-readable slug id of the form
+   */
+  slug: string
+
+  /**
+   * The human-readable title of the form
+   */
+  title: string
+
+  /**
+   * The organisation this form belongs to
+   */
+  organisation: string
+
+  /**
+   * The name of the team who own this form
+   */
+  teamName: string
+
+  /**
+   * The email of the team who own this form
+   */
+  teamEmail: string
+}
+
+export type FormByIdInput = Pick<FormMetadata, 'id'>
+export type FormMetadataDocument = Omit<FormMetadata, 'id'>
+export type FormMetadataInput = Omit<FormMetadata, 'id' | 'slug'>

package/src/form/index.ts

@@ -1 +1,3 @@
-export { FormConfiguration } from '~/src/form/form-configuration.js'
+export * from '~/src/form/form-configuration/index.js'
+export * from '~/src/form/form-definition/index.js'
+export * from '~/src/form/form-metadata/index.js'

package/src/form/types.ts

@@ -0,0 +1,2 @@
+export type * from '~/src/form/form-definition/types.js'
+export type * from '~/src/form/form-metadata/types.js'

package/src/index.ts

@@ -1,4 +1,3 @@
-export * from '~/src/schema/index.js'
 export * from '~/src/data-model/index.js'
 export * from '~/src/utils/logger.js'
 export * from '~/src/form/index.js'
@@ -8,4 +7,4 @@ export * from '~/src/utils/helpers.js'
 export * from '~/src/migration/index.js'
 export type * from '~/src/components/types.js'
 export type * from '~/src/conditions/types.js'
-export type * from '~/src/data-model/types.js'
+export type * from '~/src/form/types.js'

package/dist/module/data-model/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../../src/data-model/types.ts"],"sourcesContent":["import { type ComponentDef } from '~/src/components/types.js'\nimport { type Condition } from '~/src/conditions/condition.js'\nimport { type OutputType } from '~/src/data-model/enums.js'\n\ntype Toggleable<T> = boolean | T\n\nexport interface Next {\n  path: string\n  condition?: string\n}\nexport type Link = Next\n\nexport interface Page {\n  title: string\n  path: string\n  controller: string\n  components?: ComponentDef[]\n  section: string // the section ID\n  next?: { path: string; condition?: string }[]\n}\n\nexport interface RepeatingFieldPage extends Page {\n  controller: 'RepeatingFieldPageController'\n  options: {\n    summaryDisplayMode?: {\n      samePage?: boolean\n      separatePage?: boolean\n      hideRowTitles?: boolean\n    }\n    customText?: {\n      separatePageTitle?: string\n    }\n  }\n}\n\nexport interface Section {\n  name: string\n  title: string\n  hideTitle: boolean\n}\n\nexport interface Item {\n  text: string\n  value: string | number | boolean\n  description?: string\n  condition?: string\n}\n\nexport interface List {\n  name: string\n  title: string\n  type: 'string' | 'number' | 'boolean'\n  items: Item[]\n}\n\nexport interface Feedback {\n  feedbackForm?: boolean\n  url?: string\n  emailAddress?: string\n}\n\nexport interface PhaseBanner {\n  phase?: 'alpha' | 'beta'\n  feedbackUrl?: string\n}\n\nexport interface MultipleApiKeys {\n  test?: string\n  production?: string\n}\n\nexport interface EmailOutputConfiguration {\n  emailAddress: string\n}\n\nexport interface NotifyOutputConfiguration {\n  apiKey: string\n  templateId: string\n  emailField: string\n  personalisation: string[]\n  personalisationFieldCustomisation?: Record<string, string[]>\n  addReferencesToPersonalisation?: boolean\n  emailReplyToIdConfiguration?: {\n    emailReplyToId: string\n    condition?: string | undefined\n  }[]\n}\n\nexport interface WebhookOutputConfiguration {\n  url: string\n}\n\nexport type OutputConfiguration =\n  | EmailOutputConfiguration\n  | NotifyOutputConfiguration\n  | WebhookOutputConfiguration\n\nexport interface Output {\n  name: string\n  title: string\n  type: OutputType\n  outputConfiguration: OutputConfiguration\n}\n\nexport interface ConfirmationPage {\n  customText: {\n    title: string\n    paymentSkipped: Toggleable<string>\n    nextSteps: Toggleable<string>\n  }\n  components: ComponentDef[]\n}\n\nexport interface PaymentSkippedWarningPage {\n  customText: {\n    title: string\n    caption: string\n    body: string\n  }\n}\n\nexport interface SpecialPages {\n  confirmationPage?: ConfirmationPage\n  paymentSkippedWarningPage?: PaymentSkippedWarningPage\n}\n\nexport interface Fee {\n  description: string\n  amount: number\n  multiplier?: string\n  condition?: string\n  prefix?: string\n}\n\nexport interface FeeOptions {\n  paymentReferenceFormat?: string\n  payReturnUrl?: string\n  allowSubmissionWithoutPayment: boolean\n  maxAttempts: number\n  customPayErrorMessage?: string\n  showPaymentSkippedWarningPage: boolean\n}\n\nexport type ConditionWrapperValue =\n  | string\n  | {\n      name: string\n      conditions: Condition[]\n    }\n\nexport interface ConditionRawData {\n  name: string\n  displayName: string\n  value: ConditionWrapperValue\n}\n\n/**\n * `FormDefinition` is a typescript representation of `Schema`\n */\nexport interface FormDefinition {\n  pages: (Page | RepeatingFieldPage)[]\n  conditions: ConditionRawData[]\n  lists: List[]\n  sections: Section[]\n  startPage?: Page['path'] | undefined\n  name?: string | undefined\n  feedback?: Feedback\n  phaseBanner?: PhaseBanner\n  fees: Fee[]\n  skipSummary?: boolean | undefined\n  outputs: Output[]\n  declaration?: string | undefined\n  metadata?: Record<string, unknown>\n  payApiKey?: string | MultipleApiKeys | undefined\n  specialPages?: SpecialPages\n  paymentReferenceFormat?: string\n  feeOptions: FeeOptions\n}\n"],"mappings":"","ignoreList":[]}

package/dist/module/form/form-configuration.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"form-configuration.js","names":["FormConfiguration","constructor","Key","DisplayName","LastModified","feedbackForm","Error"],"sources":["../../../src/form/form-configuration.ts"],"sourcesContent":["export class FormConfiguration {\n  Key: string\n  DisplayName: string\n  LastModified: string | undefined\n  feedbackForm: boolean | undefined\n\n  constructor(\n    Key: string,\n    DisplayName?: string,\n    LastModified?: string,\n    feedbackForm?: boolean\n  ) {\n    if (!Key) {\n      throw Error('Form configuration must have a key')\n    }\n    this.Key = Key\n    this.DisplayName = DisplayName || Key\n    this.LastModified = LastModified\n    this.feedbackForm = feedbackForm || false\n  }\n}\n"],"mappings":"AAAA,OAAO,MAAMA,iBAAiB,CAAC;EAM7BC,WAAWA,CACTC,GAAW,EACXC,WAAoB,EACpBC,YAAqB,EACrBC,YAAsB,EACtB;IACA,IAAI,CAACH,GAAG,EAAE;MACR,MAAMI,KAAK,CAAC,oCAAoC,CAAC;IACnD;IACA,IAAI,CAACJ,GAAG,GAAGA,GAAG;IACd,IAAI,CAACC,WAAW,GAAGA,WAAW,IAAID,GAAG;IACrC,IAAI,CAACE,YAAY,GAAGA,YAAY;IAChC,IAAI,CAACC,YAAY,GAAGA,YAAY,IAAI,KAAK;EAC3C;AACF","ignoreList":[]}

package/dist/module/schema/index.js

@@ -1,2 +0,0 @@
-export { Schema, componentSchema } from "./schema.js";
-//# sourceMappingURL=index.js.map

package/dist/module/schema/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","names":["Schema","componentSchema"],"sources":["../../../src/schema/index.ts"],"sourcesContent":["export { Schema, componentSchema } from '~/src/schema/schema.js'\n"],"mappings":"AAAA,SAASA,MAAM,EAAEC,eAAe","ignoreList":[]}