The Open Source DocuSign Alternative.
TypeScript digital-signaturedocument-signingdocusign-alternativee-signatureesignesignaturenext-authnextjsopen-sourcepades-standardpdfpdf-signpdf-signaturepostgresqlprismaself-hostedsigningtypescript
fix: improve invalid bulk template upload error handling (#3326)
David Nguyen6a8bb4be04b6
diff --git a/apps/remix/app/components/dialogs/template-bulk-send-dialog.tsx b/apps/remix/app/components/dialogs/template-bulk-send-dialog.tsxindex 7e381c82f..7e610f469 100644--- a/apps/remix/app/components/dialogs/template-bulk-send-dialog.tsx+++ b/apps/remix/app/components/dialogs/template-bulk-send-dialog.tsx@@ -1,4 +1,7 @@+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';+import type { TBulkSendCsvError } from '@documenso/lib/server-only/template/validate-bulk-send-csv';import { trpc } from '@documenso/trpc/react';+import { Alert, AlertDescription } from '@documenso/ui/primitives/alert';import { Button } from '@documenso/ui/primitives/button';import { Checkbox } from '@documenso/ui/primitives/checkbox';import {@@ -17,7 +20,9 @@ import { msg } from '@lingui/core/macro';import { useLingui } from '@lingui/react';import { Trans } from '@lingui/react/macro';import { File as FileIcon, Upload, X } from 'lucide-react';+import { useState } from 'react';import { useForm } from 'react-hook-form';+import { match } from 'ts-pattern';import { z } from 'zod';import { useCurrentTeam } from '~/providers/team';@@ -29,6 +34,8 @@ const ZBulkSendFormSchema = z.object({type TBulkSendFormSchema = z.infer<typeof ZBulkSendFormSchema>;+type TBulkSendValidationError = TBulkSendCsvError | { type: 'UPLOAD_ERROR'; code: string };+export type TemplateBulkSendDialogProps = {templateId: number;recipients: Array<{ email: string; name?: string | null }>;@@ -42,6 +49,9 @@ export const TemplateBulkSendDialog = ({ templateId, recipients, trigger, onSuccconst team = useCurrentTeam();+ const [open, setOpen] = useState(false);+ const [validationError, setValidationError] = useState<TBulkSendValidationError | null>(null);+const form = useForm<TBulkSendFormSchema>({resolver: zodResolver(ZBulkSendFormSchema),defaultValues: {@@ -51,6 +61,20 @@ export const TemplateBulkSendDialog = ({ templateId, recipients, trigger, onSuccconst { mutateAsync: uploadBulkSend } = trpc.template.uploadBulkSend.useMutation();+ const onOpenChange = (value: boolean) => {+ if (form.formState.isSubmitting) {+ return;+ }++ setOpen(value);++ if (!value) {+ setValidationError(null);++ form.reset();+ }+ };+const onDownloadTemplate = () => {const headers = recipients.flatMap((_, index) => [`recipient_${index + 1}_email`, `recipient_${index + 1}_name`]);@@ -71,36 +95,44 @@ export const TemplateBulkSendDialog = ({ templateId, recipients, trigger, onSucc};const onSubmit = async (values: TBulkSendFormSchema) => {+ setValidationError(null);+try {const csv = await values.file.text();- await uploadBulkSend({+ const result = await uploadBulkSend({templateId,teamId: team?.id,csv: csv,sendImmediately: values.sendImmediately,});+ if (!result.success) {+ setValidationError(result.error);++ return;+ }+toast({title: _(msg`Success`),description: _(msg`Your bulk send has been initiated. You will receive an email notification upon completion.`),});+ setOpen(false);form.reset();+onSuccess?.();} catch (err) {console.error(err);- toast({- title: _(msg`Error`),- description: _(msg`Failed to upload CSV. Please check the file format and try again.`),- variant: 'destructive',- });+ const error = AppError.parseError(err);++ setValidationError({ type: 'UPLOAD_ERROR', code: error.code });}};return (- <Dialog>+ <Dialog open={open} onOpenChange={onOpenChange}><DialogTrigger asChild>{trigger ?? (<Button variant="outline" className="shrink-0" size="sm">@@ -174,7 +206,10 @@ export const TemplateBulkSendDialog = ({ templateId, recipients, trigger, onSuccclassName="hidden"onChange={(e) => {const file = e.target.files?.[0];+if (file) {+ setValidationError(null);+onChange(file);}}}@@ -195,7 +230,11 @@ export const TemplateBulkSendDialog = ({ templateId, recipients, trigger, onSucctype="button"variant="link"className="p-0 text-destructive text-xs hover:text-destructive"- onClick={() => onChange(null)}+ onClick={() => {+ setValidationError(null);++ form.resetField('file');+ }}disabled={form.formState.isSubmitting}><X className="h-4 w-4" />@@ -218,6 +257,67 @@ export const TemplateBulkSendDialog = ({ templateId, recipients, trigger, onSucc)}/>+ {validationError !== null && (+ <Alert variant="destructive">+ <AlertDescription className="max-h-32 overflow-y-auto">+ {match(validationError)+ .with({ type: 'PARSE_ERROR' }, () => (+ <Trans>The CSV could not be parsed. Please check the file format and try again.</Trans>+ ))+ .with({ type: 'EMPTY' }, () => (+ <Trans>+ The CSV does not contain any rows. Please add at least one row of recipient details.+ </Trans>+ ))+ .with({ type: 'ROW_LIMIT_EXCEEDED' }, ({ rowCount, maxRows }) => (+ <Trans>+ The CSV contains {rowCount} rows. A maximum of {maxRows} rows is allowed per upload.+ </Trans>+ ))+ .with({ type: 'MISSING_COLUMNS' }, ({ missingColumns }) => (+ <>+ <Trans>+ The CSV is missing the following required columns. Please download the template CSV for the+ correct format.+ </Trans>++ <ul className="mt-1 list-inside list-disc">+ {missingColumns.map((column) => (+ <li key={column} className="font-mono">+ {column}+ </li>+ ))}+ </ul>+ </>+ ))+ .with({ type: 'INVALID_RECIPIENTS' }, ({ rowErrors }) => (+ <>+ <Trans>The CSV contains invalid recipient emails. Please fix the following rows:</Trans>++ <ul className="mt-1 list-inside list-disc">+ {rowErrors.map((rowError, index) => (+ <li key={index}>+ <Trans>+ Row {rowError.row}: <span className="font-mono">{rowError.column}</span> must be a valid+ email or empty+ </Trans>+ </li>+ ))}+ </ul>+ </>+ ))+ .with({ type: 'UPLOAD_ERROR' }, ({ code }) =>+ code === AppErrorCode.LIMIT_EXCEEDED ? (+ <Trans>The CSV exceeds the maximum file size.</Trans>+ ) : (+ <Trans>Failed to upload CSV. Please check the file format and try again.</Trans>+ ),+ )+ .exhaustive()}+ </AlertDescription>+ </Alert>+ )}+<FormFieldcontrol={form.control}name="sendImmediately"@@ -240,7 +340,12 @@ export const TemplateBulkSendDialog = ({ templateId, recipients, trigger, onSucc/><DialogFooter className="mt-4">- <Button variant="secondary" onClick={() => form.reset()} type="button">+ <Button+ variant="secondary"+ onClick={() => onOpenChange(false)}+ disabled={form.formState.isSubmitting}+ type="button"+ ><Trans>Cancel</Trans></Button>diff --git a/packages/lib/jobs/definitions/internal/bulk-send-template.handler.ts b/packages/lib/jobs/definitions/internal/bulk-send-template.handler.tsindex cb57b42a2..3db217eda 100644--- a/packages/lib/jobs/definitions/internal/bulk-send-template.handler.ts+++ b/packages/lib/jobs/definitions/internal/bulk-send-template.handler.ts@@ -2,12 +2,10 @@ import { BulkSendCompleteEmail } from '@documenso/email/templates/bulk-send-compimport { sendDocument } from '@documenso/lib/server-only/document/send-document';import { createDocumentFromTemplate } from '@documenso/lib/server-only/template/create-document-from-template';import { getTemplateById } from '@documenso/lib/server-only/template/get-template-by-id';-import { zEmail } from '@documenso/lib/utils/zod';+import { validateBulkSendCsv } from '@documenso/lib/server-only/template/validate-bulk-send-csv';import { prisma } from '@documenso/prisma';import { msg } from '@lingui/macro';-import { parse } from 'csv-parse/sync';import { createElement } from 'react';-import { z } from 'zod';import { getI18nInstance } from '../../../client-only/providers/i18n-server';import { NEXT_PUBLIC_WEBAPP_URL } from '../../../constants/app';@@ -17,14 +15,6 @@ import { renderEmailWithI18N } from '../../../utils/render-email-with-i18n';import type { JobRunIO } from '../../client/_internal/job';import type { TBulkSendTemplateJobDefinition } from './bulk-send-template';-const ZRecipientRowSchema = z.object({- name: z.string().optional(),- email: z.union([- zEmail('Value must be a valid email or empty string'),- z.string().max(0, { message: 'Value must be a valid email or empty string' }),- ]),-});-export const run = async ({ payload, io }: { payload: TBulkSendTemplateJobDefinition; io: JobRunIO }) => {const { userId, teamId, templateId, csvContent, sendImmediately, requestMetadata } = payload;@@ -41,25 +31,21 @@ export const run = async ({ payload, io }: { payload: TBulkSendTemplateJobDefinithrow new Error('Template not found');}- // eslint-disable-next-line @typescript-eslint/no-explicit-any- const rows = parse<any>(csvContent, { columns: true, skip_empty_lines: true });-- if (rows.length > 100) {- throw new Error('Maximum 100 rows allowed per upload');- }-const { recipients } = template;- // Validate CSV structure- const csvHeaders = Object.keys(rows[0]);- const requiredHeaders = recipients.map((_, index) => `recipient_${index + 1}_email`);+ // The CSV is validated upfront when the bulk send is uploaded, this acts as+ // a final safeguard prior to processing.+ const csvValidationResult = validateBulkSendCsv({+ csvContent,+ recipientCount: recipients.length,+ });- for (const header of requiredHeaders) {- if (!csvHeaders.includes(header)) {- throw new Error(`Missing required column: ${header}`);- }+ if (!csvValidationResult.success) {+ throw new Error(`Bulk send CSV failed validation: ${JSON.stringify(csvValidationResult.error)}`);}+ const rows = csvValidationResult.data;+const user = await prisma.user.findFirstOrThrow({where: {id: userId,@@ -79,22 +65,6 @@ export const run = async ({ payload, io }: { payload: TBulkSendTemplateJobDefini// Process each rowfor (const [rowIndex, row] of rows.entries()) {try {- for (const [recipientIndex] of recipients.entries()) {- const nameKey = `recipient_${recipientIndex + 1}_name`;- const emailKey = `recipient_${recipientIndex + 1}_email`;-- const parsed = ZRecipientRowSchema.safeParse({- name: row[nameKey],- email: row[emailKey],- });-- if (!parsed.success) {- throw new Error(- `Invalid recipient data provided for ${emailKey}, ${nameKey}: ${parsed.error.issues?.[0]?.message}`,- );- }- }-const envelope = await io.runTask(`create-document-${rowIndex}`, async () => {return await createDocumentFromTemplate({id: {diff --git a/packages/lib/server-only/template/validate-bulk-send-csv.test.ts b/packages/lib/server-only/template/validate-bulk-send-csv.test.tsnew file mode 100644index 000000000..799b0c541--- /dev/null+++ b/packages/lib/server-only/template/validate-bulk-send-csv.test.ts@@ -0,0 +1,208 @@+import { describe, expect, it } from 'vitest';++import type { TBulkSendCsvError, TValidateBulkSendCsvResult } from './validate-bulk-send-csv';+import { validateBulkSendCsv } from './validate-bulk-send-csv';++const buildCsv = (headers: string[], rows: string[][]) =>+ [headers.join(','), ...rows.map((row) => row.join(','))].join('\n');++const expectFailure = (result: TValidateBulkSendCsvResult): TBulkSendCsvError => {+ if (result.success) {+ throw new Error('Expected validation to fail, but it passed');+ }++ return result.error;+};++describe('validateBulkSendCsv', () => {+ describe('valid CSVs', () => {+ it('returns the parsed rows for a valid CSV', () => {+ const csvContent = buildCsv(+ ['recipient_1_email', 'recipient_1_name'],+ [+ ['[email protected]', 'Alice'],+ ['[email protected]', 'Bob'],+ ],+ );++ const result = validateBulkSendCsv({ csvContent, recipientCount: 1 });++ expect(result).toEqual({+ success: true,+ data: [+ { recipient_1_email: '[email protected]', recipient_1_name: 'Alice' },+ { recipient_1_email: '[email protected]', recipient_1_name: 'Bob' },+ ],+ });+ });++ it('allows an empty string email so template defaults can be used', () => {+ const csvContent = buildCsv(['recipient_1_email', 'recipient_1_name'], [['', 'Alice']]);++ const result = validateBulkSendCsv({ csvContent, recipientCount: 1 });++ expect(result.success).toBe(true);+ });++ it('allows the optional name column to be omitted entirely', () => {+ const csvContent = buildCsv(['recipient_1_email'], [['[email protected]']]);++ const result = validateBulkSendCsv({ csvContent, recipientCount: 1 });++ expect(result.success).toBe(true);+ });++ it('allows unknown extra columns', () => {+ const csvContent = buildCsv(['recipient_1_email', 'unrelated_column'], [['[email protected]', 'anything']]);++ const result = validateBulkSendCsv({ csvContent, recipientCount: 1 });++ expect(result.success).toBe(true);+ });++ it('validates columns for every configured recipient', () => {+ const csvContent = buildCsv(+ ['recipient_1_email', 'recipient_2_email'],+ [['[email protected]', '[email protected]']],+ );++ const result = validateBulkSendCsv({ csvContent, recipientCount: 2 });++ expect(result.success).toBe(true);+ });++ it('allows exactly the maximum number of rows', () => {+ const csvContent = buildCsv(+ ['recipient_1_email'],+ Array.from({ length: 100 }, (_, index) => [`user${index}@example.com`]),+ );++ const result = validateBulkSendCsv({ csvContent, recipientCount: 1 });++ expect(result.success).toBe(true);+ });+ });++ describe('PARSE_ERROR', () => {+ it('rejects a CSV that cannot be parsed', () => {+ const csvContent = 'recipient_1_email\n"unclosed quote';++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 1 }));++ expect(error).toEqual({ type: 'PARSE_ERROR' });+ });++ it('rejects a CSV with inconsistent column counts', () => {+ const csvContent = buildCsv(+ ['recipient_1_email', 'recipient_1_name'],+ [['[email protected]', 'Alice', 'unexpected-extra-value']],+ );++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 1 }));++ expect(error).toEqual({ type: 'PARSE_ERROR' });+ });+ });++ describe('EMPTY', () => {+ it('rejects an empty file', () => {+ const error = expectFailure(validateBulkSendCsv({ csvContent: '', recipientCount: 1 }));++ expect(error).toEqual({ type: 'EMPTY' });+ });++ it('rejects a CSV containing only a header row', () => {+ const csvContent = buildCsv(['recipient_1_email', 'recipient_1_name'], []);++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 1 }));++ expect(error).toEqual({ type: 'EMPTY' });+ });+ });++ describe('ROW_LIMIT_EXCEEDED', () => {+ it('rejects a CSV exceeding the default limit of 100 rows', () => {+ const csvContent = buildCsv(+ ['recipient_1_email'],+ Array.from({ length: 101 }, (_, index) => [`user${index}@example.com`]),+ );++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 1 }));++ expect(error).toEqual({ type: 'ROW_LIMIT_EXCEEDED', rowCount: 101, maxRows: 100 });+ });++ it('respects a custom maxRows option', () => {+ const csvContent = buildCsv(['recipient_1_email'], [['[email protected]'], ['[email protected]']]);++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 1, maxRows: 1 }));++ expect(error).toEqual({ type: 'ROW_LIMIT_EXCEEDED', rowCount: 2, maxRows: 1 });+ });+ });++ describe('MISSING_COLUMNS', () => {+ it('rejects a CSV missing a required email column', () => {+ const csvContent = buildCsv(['recipient_1_name'], [['Alice']]);++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 1 }));++ expect(error).toEqual({ type: 'MISSING_COLUMNS', missingColumns: ['recipient_1_email'] });+ });++ it('reports every missing column', () => {+ const csvContent = buildCsv(['recipient_1_email'], [['[email protected]']]);++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 3 }));++ expect(error).toEqual({+ type: 'MISSING_COLUMNS',+ missingColumns: ['recipient_2_email', 'recipient_3_email'],+ });+ });+ });++ describe('INVALID_RECIPIENTS', () => {+ it('rejects a CSV containing an invalid email', () => {+ const csvContent = buildCsv(['recipient_1_email'], [['not-an-email']]);++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 1 }));++ expect(error).toMatchObject({+ type: 'INVALID_RECIPIENTS',+ rowErrors: [{ row: 1, column: 'recipient_1_email' }],+ });+ });++ it('references the offending row and column', () => {+ const csvContent = buildCsv(['recipient_1_email'], [['[email protected]'], ['not-an-email']]);++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 1 }));++ expect(error).toMatchObject({+ type: 'INVALID_RECIPIENTS',+ rowErrors: [{ row: 2, column: 'recipient_1_email' }],+ });+ });++ it('aggregates errors across multiple rows and recipients', () => {+ const csvContent = buildCsv(+ ['recipient_1_email', 'recipient_2_email'],+ [+ ['not-an-email', '[email protected]'],+ ['[email protected]', 'also-not-an-email'],+ ],+ );++ const error = expectFailure(validateBulkSendCsv({ csvContent, recipientCount: 2 }));++ expect(error).toMatchObject({+ type: 'INVALID_RECIPIENTS',+ rowErrors: [+ { row: 1, column: 'recipient_1_email' },+ { row: 2, column: 'recipient_2_email' },+ ],+ });+ });+ });+});diff --git a/packages/lib/server-only/template/validate-bulk-send-csv.ts b/packages/lib/server-only/template/validate-bulk-send-csv.tsnew file mode 100644index 000000000..3afc1d7c5--- /dev/null+++ b/packages/lib/server-only/template/validate-bulk-send-csv.ts@@ -0,0 +1,117 @@+import { parse } from 'csv-parse/sync';+import { z } from 'zod';++import { zEmail } from '../../utils/zod';++const ZRecipientRowSchema = z.object({+ name: z.string().optional(),+ email: z.union([+ zEmail('Value must be a valid email or empty string'),+ z.string().max(0, { message: 'Value must be a valid email or empty string' }),+ ]),+});++export type TBulkSendCsvRow = Record<string, string | undefined>;++export type TBulkSendCsvRowError = {+ /**+ * The 1-indexed row number the error occurred on, excluding the header row.+ */+ row: number;++ /**+ * The column the error occurred in, such as `recipient_1_email`.+ */+ column: string;++ message: string;+};++export type TBulkSendCsvError =+ | { type: 'PARSE_ERROR' }+ | { type: 'EMPTY' }+ | { type: 'ROW_LIMIT_EXCEEDED'; rowCount: number; maxRows: number }+ | { type: 'MISSING_COLUMNS'; missingColumns: string[] }+ | { type: 'INVALID_RECIPIENTS'; rowErrors: TBulkSendCsvRowError[] };++export type TValidateBulkSendCsvResult =+ | { success: true; data: TBulkSendCsvRow[] }+ | { success: false; error: TBulkSendCsvError };++export type ValidateBulkSendCsvOptions = {+ csvContent: string;++ /**+ * The number of recipients configured on the template, used to derive the+ * required `recipient_N_email` columns.+ */+ recipientCount: number;++ maxRows?: number;+};++/**+ * Validate the CSV provided for a template bulk send.+ *+ * Returns a discriminated union so callers can surface structured error+ * details, such as which rows contain invalid recipients.+ */+export const validateBulkSendCsv = ({+ csvContent,+ recipientCount,+ maxRows = 100,+}: ValidateBulkSendCsvOptions): TValidateBulkSendCsvResult => {+ let rows: TBulkSendCsvRow[];++ try {+ rows = parse(csvContent, { columns: true, skip_empty_lines: true });+ } catch {+ return { success: false, error: { type: 'PARSE_ERROR' } };+ }++ if (rows.length === 0) {+ return { success: false, error: { type: 'EMPTY' } };+ }++ if (rows.length > maxRows) {+ return { success: false, error: { type: 'ROW_LIMIT_EXCEEDED', rowCount: rows.length, maxRows } };+ }++ const csvHeaders = Object.keys(rows[0]);++ const requiredHeaders = Array.from({ length: recipientCount }, (_, index) => `recipient_${index + 1}_email`);++ const missingColumns = requiredHeaders.filter((header) => !csvHeaders.includes(header));++ if (missingColumns.length > 0) {+ return { success: false, error: { type: 'MISSING_COLUMNS', missingColumns } };+ }++ const rowErrors: TBulkSendCsvRowError[] = [];++ for (const [rowIndex, row] of rows.entries()) {+ for (let recipientIndex = 0; recipientIndex < recipientCount; recipientIndex += 1) {+ const nameKey = `recipient_${recipientIndex + 1}_name`;+ const emailKey = `recipient_${recipientIndex + 1}_email`;++ const parsed = ZRecipientRowSchema.safeParse({+ name: row[nameKey],+ email: row[emailKey],+ });++ if (!parsed.success) {+ rowErrors.push({+ row: rowIndex + 1,+ column: emailKey,+ message: parsed.error.issues?.[0]?.message ?? 'Invalid value',+ });+ }+ }+ }++ if (rowErrors.length > 0) {+ return { success: false, error: { type: 'INVALID_RECIPIENTS', rowErrors } };+ }++ return { success: true, data: rows };+};diff --git a/packages/trpc/server/template-router/router.ts b/packages/trpc/server/template-router/router.tsindex e11e1f25d..00c4816f8 100644--- a/packages/trpc/server/template-router/router.ts+++ b/packages/trpc/server/template-router/router.ts@@ -22,6 +22,7 @@ import { findTemplates } from '@documenso/lib/server-only/template/find-templateimport { getOrganisationTemplateById } from '@documenso/lib/server-only/template/get-organisation-template-by-id';import { getTemplateById } from '@documenso/lib/server-only/template/get-template-by-id';import { toggleTemplateDirectLink } from '@documenso/lib/server-only/template/toggle-template-direct-link';+import { validateBulkSendCsv } from '@documenso/lib/server-only/template/validate-bulk-send-csv';import { fireAndForget } from '@documenso/lib/universal/fire-and-forget';import { putNormalizedPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';import { getPresignPostUrl } from '@documenso/lib/universal/upload/server-actions';@@ -879,6 +880,15 @@ export const templateRouter = router({});}+ const csvValidationResult = validateBulkSendCsv({+ csvContent: csv,+ recipientCount: template.recipients.length,+ });++ if (!csvValidationResult.success) {+ return { success: false as const, error: csvValidationResult.error };+ }+await jobs.triggerJob({name: 'internal.bulk-send-template',payload: {@@ -891,6 +901,6 @@ export const templateRouter = router({},});- return { success: true };+ return { success: true as const };}),});