feat: add payment forms action to paysg integration

Author: justynoh

packages/backend/src/apps/paysg/actions/create-payment-form-submission/index.ts

@@ -0,0 +1,131 @@
+import type { IRawAction } from '@plumber/types'
+
+import { ZodError } from 'zod'
+import { fromZodError } from 'zod-validation-error'
+
+import StepError, { GenericSolution } from '@/errors/step'
+
+import { requestSchema } from './schema'
+
+const action: IRawAction = {
+  name: 'Create payment form submission',
+  key: 'createPaymentFormSubmission',
+  description:
+    'Create a new submission for a payment form, and initiate a payment request',
+  arguments: [
+    {
+      label: 'Payment Form Link',
+      description: 'This can be found on your PaySG payment services dashboard',
+      key: 'formId',
+      type: 'string' as const,
+      required: true,
+    },
+    {
+      label: 'FormSG Form ID',
+      description: 'Input the variable corresponding to form ID here',
+      key: 'formsg_form_id',
+      type: 'string' as const,
+      required: true,
+      variables: true,
+    },
+    {
+      label: 'FormSG Submission ID',
+      key: 'formsg_submission_id',
+      type: 'string' as const,
+      required: true,
+      variables: true,
+    },
+    {
+      label: 'FormSG Reference Field Answer',
+      key: 'nonce',
+      type: 'string' as const,
+      required: true,
+      variables: true,
+    },
+    {
+      label: 'Payer Name',
+      key: 'payer_name',
+      type: 'string' as const,
+      required: true,
+      variables: true,
+    },
+    {
+      label: 'Payer Email',
+      key: 'payer_email',
+      type: 'string' as const,
+      required: false,
+      variables: true,
+    },
+    {
+      label: 'Amount (in cents)',
+      key: 'amount_in_cents',
+      type: 'string' as const,
+      required: true,
+      variables: true,
+    },
+    {
+      label: 'Description',
+      key: 'description',
+      type: 'string' as const,
+      required: false,
+      variables: true,
+    },
+    {
+      label: 'Responses',
+      key: 'responses',
+      type: 'multirow' as const,
+      required: false,
+      subFields: [
+        {
+          label: 'Question',
+          key: 'question',
+          type: 'string' as const,
+          required: true,
+          variables: true,
+        },
+        {
+          label: 'Answer',
+          key: 'answer',
+          type: 'string' as const,
+          required: true,
+          variables: true,
+        },
+      ],
+    },
+  ],
+
+  async run($) {
+    const paymentServiceId = $.auth.data.paymentServiceId as string
+
+    try {
+      const { formId, ...body } = requestSchema.parse($.step.parameters)
+
+      await $.http.post(
+        `/v1/payment-services/:paymentServiceId/forms/:formId/submissions`,
+        body,
+        {
+          urlPathParams: {
+            paymentServiceId,
+            formId,
+          },
+        },
+      )
+      $.setActionItem({ raw: { success: true } })
+    } catch (error) {
+      if (error instanceof ZodError) {
+        const firstError = fromZodError(error).details[0]
+
+        throw new StepError(
+          `${firstError.message} at "${firstError.path}"`,
+          GenericSolution.ReconfigureInvalidField,
+          $.step.position,
+          $.app.name,
+        )
+      }
+
+      throw error
+    }
+  },
+}
+
+export default action

packages/backend/src/apps/paysg/actions/create-payment-form-submission/schema.ts

@@ -0,0 +1,86 @@
+import emailValidator from 'email-validator'
+import { z } from 'zod'
+
+import { FORM_ID_LENGTH } from '@/apps/formsg/common/constants'
+
+import { normalizeSpecialChars } from '../create-payment/normalize-special-chars'
+
+const PAYMENT_FORM_LINK_REGEX = /^https:\/\/(staging.)?pay.gov.sg\/forms\/(.*)$/
+
+export const requestSchema = z.object({
+  formId: z
+    .string()
+    .trim()
+    .min(1, { message: 'Specify a form link' })
+    .transform((value, context) => {
+      const match = value.match(PAYMENT_FORM_LINK_REGEX)
+
+      if (!match || !match[0]) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Invalid payment form link',
+        })
+        return z.NEVER
+      }
+
+      return match[2]
+    }),
+  formsg_form_id: z
+    .string()
+    .trim()
+    .length(FORM_ID_LENGTH, { message: 'Specify a valid FormSG form ID' }),
+  formsg_submission_id: z
+    .string()
+    .trim()
+    .min(1, { message: 'Specify a submission ID' }),
+  nonce: z.string().trim().min(1, { message: 'Specify a nonce field' }),
+  payer_name: z
+    .string()
+    .trim()
+    .min(1, { message: 'Empty payer name' })
+    .max(255, { message: 'Payer name cannot be more than 255 characters' })
+    .transform((value) => normalizeSpecialChars(value)),
+  payer_email: z
+    .string()
+    .trim()
+    .max(255, { message: 'Payer email cannot be more than 255 characters' })
+    .transform((value, context) => {
+      if (!value || value.length === 0) {
+        return undefined
+      }
+      if (!emailValidator.validate(value)) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Invalid payer email',
+        })
+        return z.NEVER
+      }
+
+      return value
+    })
+    .optional(),
+  amount_in_cents: z
+    .string()
+    .trim()
+    .min(1, { message: 'Empty payment amount' })
+    .pipe(
+      z.coerce
+        .number()
+        .int('Payment amount must be round number')
+        .min(50, { message: 'Payment amount must be larger than 50 cents' })
+        .max(99999999, {
+          message: 'Payment amount cannot be larger than $999999.99',
+        }),
+    ),
+  description: z
+    .string()
+    .trim()
+    .max(500, { message: 'Description cannot be more than 500 characters' })
+    .optional(),
+  responses: z.array(
+    z.object({
+      question: z.string().trim().min(1, { message: 'Empty question' }),
+      answer: z.string().trim().min(1, { message: 'Empty answer' }),
+    }),
+  ),
+})

packages/backend/src/apps/paysg/actions/create-payment/schema.ts

@@ -67,7 +67,7 @@ export const requestSchema = z
       .string()
       .trim()
       .min(1, { message: 'Empty description' })
-      .max(500, { message: 'Payer email cannot be more than 500 characters' }),
+      .max(500, { message: 'Description cannot be more than 500 characters' }),
     paymentAmountCents: z
       .string()
       .trim()

packages/backend/src/apps/paysg/actions/index.ts

@@ -1,5 +1,11 @@
 import createPayment from './create-payment'
+import createPaymentFormSubmission from './create-payment-form-submission'
 import getPayment from './get-payment'
 import sendEmail from './send-email'
 
-export default [createPayment, getPayment, sendEmail]
+export default [
+  createPayment,
+  getPayment,
+  sendEmail,
+  createPaymentFormSubmission,
+]