feat: autoplace fields from placeholders (#2111)

This PR introduces automatic detection and placement of fields and recipients based on PDF placeholders. The placeholders have the following structure: - `{{fieldType,recipientPosition,fieldMeta}}` - `{{text,r1,required=true,textAlign=right,fontSize=50}}` When the user uploads a PDF document containing such placeholders, they get converted automatically to Documenso fields and assigned to recipients.
2026-07-22 16:03:39 +10:00 · 2026-01-29 04:13:45 +02:00
parent d77f81163b
commit d18dcb4d60
22 changed files with 2045 additions and 50 deletions
@@ -1,8 +1,15 @@
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
 import { getEnvelopeWhereInput } from '@documenso/lib/server-only/envelope/get-envelope-by-id';
+import {
+  convertPlaceholdersToFieldInputs,
+  extractPdfPlaceholders,
+} from '@documenso/lib/server-only/pdf/auto-place-fields';
+import { findRecipientByPlaceholder } from '@documenso/lib/server-only/pdf/helpers';
+import { insertFormValuesInPdf } from '@documenso/lib/server-only/pdf/insert-form-values-in-pdf';
+import { normalizePdf } from '@documenso/lib/server-only/pdf/normalize-pdf';
 import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
 import { prefixedId } from '@documenso/lib/universal/id';
-import { putNormalizedPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
+import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
 import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
 import { canEnvelopeItemsBeModified } from '@documenso/lib/utils/envelope';
 import { prisma } from '@documenso/prisma';
@@ -84,14 +91,31 @@ export const createEnvelopeItemsRoute = authenticatedProcedure
      });
    }

-    // For each file, stream to s3 and create the document data.
+    // For each file: normalize, extract & clean placeholders, then upload.
    const envelopeItems = await Promise.all(
      files.map(async (file) => {
-        const { id: documentDataId } = await putNormalizedPdfFileServerSide(file);
+        let buffer = Buffer.from(await file.arrayBuffer());
+
+        if (envelope.formValues) {
+          buffer = await insertFormValuesInPdf({ pdf: buffer, formValues: envelope.formValues });
+        }
+
+        const normalized = await normalizePdf(buffer, {
+          flattenForm: envelope.type !== 'TEMPLATE',
+        });
+
+        const { cleanedPdf, placeholders } = await extractPdfPlaceholders(normalized);
+
+        const { id: documentDataId } = await putPdfFileServerSide({
+          name: file.name,
+          type: 'application/pdf',
+          arrayBuffer: async () => Promise.resolve(cleanedPdf),
+        });

        return {
          title: file.name,
          documentDataId,
+          placeholders,
        };
      }),
    );
@@ -131,6 +155,65 @@ export const createEnvelopeItemsRoute = authenticatedProcedure
        ),
      });

+      // Create fields from placeholders if the envelope already has recipients.
+      if (envelope.recipients.length > 0) {
+        const orderedRecipients = [...envelope.recipients].sort((a, b) => {
+          const aOrder = a.signingOrder ?? Number.MAX_SAFE_INTEGER;
+          const bOrder = b.signingOrder ?? Number.MAX_SAFE_INTEGER;
+
+          if (aOrder !== bOrder) {
+            return aOrder - bOrder;
+          }
+
+          return a.id - b.id;
+        });
+
+        for (const uploadedItem of envelopeItems) {
+          if (!uploadedItem.placeholders || uploadedItem.placeholders.length === 0) {
+            continue;
+          }
+
+          const createdItem = createdItems.find(
+            (ci) => ci.documentDataId === uploadedItem.documentDataId,
+          );
+
+          if (!createdItem) {
+            continue;
+          }
+
+          const fieldsToCreate = convertPlaceholdersToFieldInputs(
+            uploadedItem.placeholders,
+            (recipientPlaceholder, placeholder) =>
+              findRecipientByPlaceholder(
+                recipientPlaceholder,
+                placeholder,
+                orderedRecipients,
+                orderedRecipients,
+              ),
+            createdItem.id,
+          );
+
+          if (fieldsToCreate.length > 0) {
+            await tx.field.createMany({
+              data: fieldsToCreate.map((field) => ({
+                envelopeId: envelope.id,
+                envelopeItemId: createdItem.id,
+                recipientId: field.recipientId,
+                type: field.type,
+                page: field.page,
+                positionX: field.positionX,
+                positionY: field.positionY,
+                width: field.width,
+                height: field.height,
+                customText: '',
+                inserted: false,
+                fieldMeta: field.fieldMeta || undefined,
+              })),
+            });
+          }
+        }
+      }
+
      return createdItems;
    });

@@ -3,7 +3,9 @@ import { EnvelopeType } from '@prisma/client';
 import { getServerLimits } from '@documenso/ee/server-only/limits/server';
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
 import { createEnvelope } from '@documenso/lib/server-only/envelope/create-envelope';
-import { putNormalizedPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
+import { extractPdfPlaceholders } from '@documenso/lib/server-only/pdf/auto-place-fields';
+import { normalizePdf } from '@documenso/lib/server-only/pdf/normalize-pdf';
+import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';

 import { insertFormValuesInPdf } from '../../../lib/server-only/pdf/insert-form-values-in-pdf';
 import { authenticatedProcedure } from '../trpc';
@@ -69,7 +71,7 @@ export const createEnvelopeRoute = authenticatedProcedure
      });
    }

-    // For each file, stream to s3 and create the document data.
+    // For each file: normalize, extract & clean placeholders, then upload.
    const envelopeItems = await Promise.all(
      files.map(async (file) => {
        let pdf = Buffer.from(await file.arrayBuffer());
@@ -82,20 +84,22 @@ export const createEnvelopeRoute = authenticatedProcedure
          });
        }

-        const { id: documentDataId } = await putNormalizedPdfFileServerSide(
-          {
-            name: file.name,
-            type: 'application/pdf',
-            arrayBuffer: async () => Promise.resolve(pdf),
-          },
-          {
-            flattenForm: type !== EnvelopeType.TEMPLATE,
-          },
-        );
+        const normalized = await normalizePdf(pdf, {
+          flattenForm: type !== EnvelopeType.TEMPLATE,
+        });
+
+        const { cleanedPdf, placeholders } = await extractPdfPlaceholders(normalized);
+
+        const { id: documentDataId } = await putPdfFileServerSide({
+          name: file.name,
+          type: 'application/pdf',
+          arrayBuffer: async () => Promise.resolve(cleanedPdf),
+        });

        return {
          title: file.name,
          documentDataId,
+          placeholders,
        };
      }),
    );
@@ -22,7 +22,7 @@ export const createEnvelopeFieldsMeta: TrpcRouteMeta = {
  },
 };

-const ZCreateFieldSchema = ZEnvelopeFieldAndMetaSchema.and(
+const ZCreateFieldBaseSchema = ZEnvelopeFieldAndMetaSchema.and(
  z.object({
    recipientId: z.number().describe('The ID of the recipient to create the field for'),
    envelopeItemId: z
@@ -31,14 +31,51 @@ const ZCreateFieldSchema = ZEnvelopeFieldAndMetaSchema.and(
      .describe(
        'The ID of the envelope item to put the field on. If not provided, field will be placed on the first item.',
      ),
-    page: ZFieldPageNumberSchema,
-    positionX: ZClampedFieldPositionXSchema,
-    positionY: ZClampedFieldPositionYSchema,
-    width: ZClampedFieldWidthSchema,
-    height: ZClampedFieldHeightSchema,
  }),
 );

+/**
+ * Position a field using explicit percentage-based coordinates.
+ */
+const ZCoordinatePositionSchema = z.object({
+  page: ZFieldPageNumberSchema,
+  positionX: ZClampedFieldPositionXSchema,
+  positionY: ZClampedFieldPositionYSchema,
+  width: ZClampedFieldWidthSchema,
+  height: ZClampedFieldHeightSchema,
+});
+
+/**
+ * Position a field using a PDF text placeholder (e.g. "{{name}}").
+ *
+ * The placeholder text is matched in the envelope item's PDF and the field is
+ * placed at the bounding box of that match. Width and height can optionally be
+ * overridden; when omitted the dimensions of the placeholder text are used.
+ */
+const ZPlaceholderPositionSchema = z.object({
+  placeholder: z
+    .string()
+    .describe(
+      'Text to search for in the PDF (e.g. "{{name}}"). The field will be placed at the location of this text.',
+    ),
+  width: ZClampedFieldWidthSchema.optional().describe(
+    'Override the width of the field. When omitted, the width of the placeholder text is used.',
+  ),
+  height: ZClampedFieldHeightSchema.optional().describe(
+    'Override the height of the field. When omitted, the height of the placeholder text is used.',
+  ),
+  matchAll: z
+    .boolean()
+    .optional()
+    .describe(
+      'When true, creates a field at every occurrence of the placeholder in the PDF. When false or omitted, only the first occurrence is used.',
+    ),
+});
+
+const ZCreateFieldSchema = ZCreateFieldBaseSchema.and(
+  z.union([ZCoordinatePositionSchema, ZPlaceholderPositionSchema]),
+);
+
 export const ZCreateEnvelopeFieldsRequestSchema = z.object({
  envelopeId: z.string(),
  data: ZCreateFieldSchema.array(),