feat: prefill fields via api (#1261)

## Description

Configure the advanced field via API.

## Checklist

<!--- Please check the boxes that apply to this pull request. -->
<!--- You can add or remove items as needed. -->

- [x] I have tested these changes locally and they work as expected.
- [ ] I have added/updated tests that prove the effectiveness of these
changes.
- [x] I have updated the documentation to reflect these changes, if
applicable.
- [x] I have followed the project's coding style guidelines.
- [ ] I have addressed the code review feedback from the previous
submission, if applicable.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **New Features**
- Enhanced API functionality to support field metadata during field
creation.
- Introduced validation checks for field metadata to ensure necessary
information is provided for advanced field types.

- **Bug Fixes**
- Improved error handling during field creation to return properly
formatted error responses.

- **Documentation**
- Updated API schemas to include field metadata, enhancing data
validation and response structures.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

packages/api/v1/implementation.ts

@@ -31,6 +31,7 @@ import { createDocumentFromTemplateLegacy } from '@documenso/lib/server-only/tem
 import { deleteTemplate } from '@documenso/lib/server-only/template/delete-template';
 import { findTemplates } from '@documenso/lib/server-only/template/find-templates';
 import { getTemplateById } from '@documenso/lib/server-only/template/get-template-by-id';
+import { ZFieldMetaSchema } from '@documenso/lib/types/field-meta';
 import { extractNextApiRequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
 import { getFile } from '@documenso/lib/universal/upload/get-file';
 import { putPdfFile } from '@documenso/lib/universal/upload/put-file';
@@ -869,7 +870,17 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
 
   createField: authenticatedMiddleware(async (args, user, team) => {
     const { id: documentId } = args.params;
-    const { recipientId, type, pageNumber, pageWidth, pageHeight, pageX, pageY } = args.body;
+    const { recipientId, type, pageNumber, pageWidth, pageHeight, pageX, pageY, fieldMeta } =
+      args.body;
+
+    if (pageNumber <= 0) {
+      return {
+        status: 400,
+        body: {
+          message: 'Invalid page number',
+        },
+      };
+    }
 
     const document = await getDocumentById({
       id: Number(documentId),
@@ -918,41 +929,47 @@ export const ApiContractV1Implementation = createNextRoute(ApiContractV1, {
       };
     }
 
-    const field = await createField({
-      documentId: Number(documentId),
-      recipientId: Number(recipientId),
-      userId: user.id,
-      teamId: team?.id,
-      type,
-      pageNumber,
-      pageX,
-      pageY,
-      pageWidth,
-      pageHeight,
-      requestMetadata: extractNextApiRequestMetadata(args.req),
-    });
-
-    const remappedField = {
-      id: field.id,
-      documentId: field.documentId,
-      recipientId: field.recipientId ?? -1,
-      type: field.type,
-      pageNumber: field.page,
-      pageX: Number(field.positionX),
-      pageY: Number(field.positionY),
-      pageWidth: Number(field.width),
-      pageHeight: Number(field.height),
-      customText: field.customText,
-      inserted: field.inserted,
-    };
-
-    return {
-      status: 200,
-      body: {
-        ...remappedField,
+    try {
+      const field = await createField({
         documentId: Number(documentId),
-      },
-    };
+        recipientId: Number(recipientId),
+        userId: user.id,
+        teamId: team?.id,
+        type,
+        pageNumber,
+        pageX,
+        pageY,
+        pageWidth,
+        pageHeight,
+        fieldMeta,
+        requestMetadata: extractNextApiRequestMetadata(args.req),
+      });
+
+      const remappedField = {
+        id: field.id,
+        documentId: field.documentId,
+        recipientId: field.recipientId ?? -1,
+        type: field.type,
+        pageNumber: field.page,
+        pageX: Number(field.positionX),
+        pageY: Number(field.positionY),
+        pageWidth: Number(field.width),
+        pageHeight: Number(field.height),
+        customText: field.customText,
+        fieldMeta: ZFieldMetaSchema.parse(field.fieldMeta),
+        inserted: field.inserted,
+      };
+
+      return {
+        status: 200,
+        body: {
+          ...remappedField,
+          documentId: Number(documentId),
+        },
+      };
+    } catch (err) {
+      return AppError.toRestAPIError(err);
+    }
   }),
 
   updateField: authenticatedMiddleware(async (args, user, team) => {