Merge branch 'main' into duncan/signing-reason-env

# Conflicts:
#	packages/lib/constants/app.ts

.env.example

@@ -80,6 +80,8 @@ NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET=
 NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL=
 # OPTIONAL: Comma-separated list of timestamp authority URLs for PDF signing (enables LTV and archival timestamps).
 NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY=
+# OPTIONAL: Reason to embed in PDF signatures. Defaults to "Signed by Documenso".
+NEXT_PRIVATE_SIGNING_REASON=
 # OPTIONAL: Contact info to embed in PDF signatures. Defaults to the webapp URL.
 NEXT_PUBLIC_SIGNING_CONTACT_INFO=
 # OPTIONAL: Set to "true" to use the legacy adbe.pkcs7.detached subfilter instead of ETSI.CAdES.detached.

apps/docs/content/docs/developers/api/fields.mdx

@@ -6,8 +6,6 @@ description: Add signature and form fields to documents via API.
 import { Callout } from 'fumadocs-ui/components/callout';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 
-<EnvelopeWarning />
-
 <Callout type="warn">
   This guide may not reflect the latest endpoints or parameters. For an always up-to-date reference,
   see the [OpenAPI Reference](https://openapi.documenso.com).
@@ -21,13 +19,13 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 | `secondaryId`    | string         | Secondary identifier for audit logs          |
 | `type`           | string         | Field type (see [Field Types](#field-types)) |
 | `recipientId`    | number         | ID of the recipient assigned to this field   |
-| `envelopeId`     | string         | ID of the parent envelope                    |
+| `envelopeId`     | number         | ID of the parent envelope                    |
 | `envelopeItemId` | string         | ID of the PDF item the field is placed on    |
 | `page`           | number         | Page number (1-indexed)                      |
-| `positionX`      | string         | X coordinate as percentage (0-100), a decimal serialized as a string |
-| `positionY`      | string         | Y coordinate as percentage (0-100), a decimal serialized as a string |
-| `width`          | string         | Width as percentage of page (0-100), a decimal serialized as a string |
-| `height`         | string         | Height as percentage of page (0-100), a decimal serialized as a string |
+| `positionX`      | number         | X coordinate as percentage (0-100)           |
+| `positionY`      | number         | Y coordinate as percentage (0-100)           |
+| `width`          | number         | Width as percentage of page (0-100)          |
+| `height`         | number         | Height as percentage of page (0-100)         |
 | `customText`     | string         | Value entered by the recipient               |
 | `inserted`       | boolean        | Whether the field has been completed         |
 | `fieldMeta`      | object \| null | Type-specific configuration options          |
@@ -40,19 +38,18 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
   "secondaryId": "field_abc123",
   "type": "SIGNATURE",
   "recipientId": 123,
-  "envelopeId": "envelope_abcdefhiklmnorst",
-  "envelopeItemId": "envelope_item_abcdefhiklmnorst",
+  "envelopeId": 789,
+  "envelopeItemId": "envelope_item_xyz",
   "page": 1,
-  "positionX": "10",
-  "positionY": "80",
-  "width": "30",
-  "height": "5",
+  "positionX": 10,
+  "positionY": 80,
+  "width": 30,
+  "height": 5,
   "customText": "",
   "inserted": false,
   "fieldMeta": {
     "type": "signature",
-    "required": true,
-    "overflow": "auto"
+    "required": true
   }
 }
 ```
@@ -64,7 +61,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 | Type             | Description                               | Auto-filled |
 | ---------------- | ----------------------------------------- | ----------- |
 | `SIGNATURE`      | Drawn, typed, or uploaded signature       | No          |
-| `FREE_SIGNATURE` | Legacy free-form signature. Accepted by the v2 create schema but rejected by the v1 API and unsupported in the signing UI — avoid in new integrations | No          |
+| `FREE_SIGNATURE` | Unrestricted signature without validation | No          |
 | `INITIALS`       | Recipient's initials                      | No          |
 | `NAME`           | Recipient's full name                     | Yes         |
 | `EMAIL`          | Recipient's email address                 | Yes         |
@@ -137,12 +134,10 @@ POST /envelope/field/create-many
 
 ### Request Body
 
-| Field        | Type   | Required | Description                     |
-| ------------ | ------ | -------- | ------------------------------- |
-| `envelopeId` | string | Yes      | The envelope ID                 |
-| `data`       | array  | Yes      | Array of field configurations   |
-
-Each entry in `data` requires a `type`, a `recipientId`, and a position — either explicit coordinates (`page`, `positionX`, `positionY`, `width`, `height`) or a [text placeholder](#placeholder-based-field-positioning) (`placeholder` with optional `width`, `height`, and `matchAll`). Optional per-entry properties: `envelopeItemId` (which PDF in the envelope to place the field on; defaults to the first item) and `fieldMeta`.
+| Field       | Type   | Required | Description                     |
+| ----------- | ------ | -------- | ------------------------------- |
+| `documentId`| number | Yes      | The document ID                 |
+| `fields`    | array  | Yes      | Array of field configurations   |
 
 ### Code Examples
 
@@ -153,32 +148,32 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/field/create-many" \
   -H "Authorization: api_xxxxxxxxxxxxxxxx" \
   -H "Content-Type: application/json" \
   -d '{
-    "envelopeId": "envelope_abcdefhiklmnorst",
-    "data": [
+    "documentId": 123,
+    "fields": [
       {
         "type": "SIGNATURE",
         "recipientId": 456,
-        "page": 1,
-        "positionX": 10,
-        "positionY": 80,
+        "pageNumber": 1,
+        "pageX": 10,
+        "pageY": 80,
         "width": 30,
         "height": 5
       },
       {
         "type": "DATE",
         "recipientId": 456,
-        "page": 1,
-        "positionX": 50,
-        "positionY": 80,
+        "pageNumber": 1,
+        "pageX": 50,
+        "pageY": 80,
         "width": 20,
         "height": 3
       },
       {
         "type": "TEXT",
         "recipientId": 456,
-        "page": 1,
-        "positionX": 10,
-        "positionY": 70,
+        "pageNumber": 1,
+        "pageX": 10,
+        "pageY": 70,
         "width": 40,
         "height": 4,
         "fieldMeta": {
@@ -204,32 +199,32 @@ const response = await fetch(
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
-      envelopeId: 'envelope_abcdefhiklmnorst',
-      data: [
+      documentId: 123,
+      fields: [
         {
           type: 'SIGNATURE',
           recipientId: 456,
-          page: 1,
-          positionX: 10,
-          positionY: 80,
+          pageNumber: 1,
+          pageX: 10,
+          pageY: 80,
           width: 30,
           height: 5,
         },
         {
           type: 'DATE',
           recipientId: 456,
-          page: 1,
-          positionX: 50,
-          positionY: 80,
+          pageNumber: 1,
+          pageX: 50,
+          pageY: 80,
           width: 20,
           height: 3,
         },
         {
           type: 'TEXT',
           recipientId: 456,
-          page: 1,
-          positionX: 10,
-          positionY: 70,
+          pageNumber: 1,
+          pageX: 10,
+          pageY: 70,
           width: 40,
           height: 4,
           fieldMeta: {
@@ -244,8 +239,8 @@ const response = await fetch(
   }
 );
 
-const { data } = await response.json();
-console.log(`Created ${data.length} fields`);
+const { fields } = await response.json();
+console.log(`Created ${fields.length} fields`);
 
 ````
 </Tab>
@@ -255,68 +250,36 @@ console.log(`Created ${data.length} fields`);
 
 ```json
 {
-  "data": [
+  "fields": [
     {
       "id": 101,
-      "secondaryId": "field_abc123",
-      "envelopeId": "envelope_abcdefhiklmnorst",
-      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
       "type": "SIGNATURE",
       "recipientId": 456,
       "page": 1,
-      "positionX": "10",
-      "positionY": "80",
-      "width": "30",
-      "height": "5",
-      "customText": "",
-      "inserted": false,
-      "fieldMeta": {
-        "type": "signature",
-        "fontSize": 18,
-        "overflow": "auto"
-      }
+      "positionX": 10,
+      "positionY": 80,
+      "width": 30,
+      "height": 5
     },
     {
       "id": 102,
-      "secondaryId": "field_def456",
-      "envelopeId": "envelope_abcdefhiklmnorst",
-      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
       "type": "DATE",
       "recipientId": 456,
       "page": 1,
-      "positionX": "50",
-      "positionY": "80",
-      "width": "20",
-      "height": "3",
-      "customText": "",
-      "inserted": false,
-      "fieldMeta": {
-        "type": "date",
-        "fontSize": 12,
-        "textAlign": "left",
-        "overflow": "auto"
-      }
+      "positionX": 50,
+      "positionY": 80,
+      "width": 20,
+      "height": 3
     },
     {
       "id": 103,
-      "secondaryId": "field_ghi789",
-      "envelopeId": "envelope_abcdefhiklmnorst",
-      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
       "type": "TEXT",
       "recipientId": 456,
       "page": 1,
-      "positionX": "10",
-      "positionY": "70",
-      "width": "40",
-      "height": "4",
-      "customText": "",
-      "inserted": false,
-      "fieldMeta": {
-        "type": "text",
-        "label": "Job Title",
-        "placeholder": "Enter your job title",
-        "required": true
-      }
+      "positionX": 10,
+      "positionY": 70,
+      "width": 40,
+      "height": 4
     }
   ]
 }
@@ -336,10 +299,8 @@ POST /envelope/field/update-many
 
 | Field        | Type   | Required | Description                   |
 | ------------ | ------ | -------- | ----------------------------- |
-| `envelopeId` | string | Yes      | The envelope ID               |
-| `data`       | array  | Yes      | Array of field update objects |
-
-Each entry in `data` requires the field `id` and `type`. Position properties (`page`, `positionX`, `positionY`, `width`, `height`), `envelopeItemId`, and `fieldMeta` are optional — only supplied values are updated. Placeholder positioning is not supported when updating; use coordinates.
+| `documentId` | number | Yes      | The document ID               |
+| `fields`     | array  | Yes      | Array of field update objects |
 
 ### Code Examples
 
@@ -350,17 +311,17 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/field/update-many" \
   -H "Authorization: api_xxxxxxxxxxxxxxxx" \
   -H "Content-Type: application/json" \
   -d '{
-    "envelopeId": "envelope_abcdefhiklmnorst",
-    "data": [
+    "documentId": 123,
+    "fields": [
       {
         "id": 101,
         "type": "SIGNATURE",
-        "positionY": 85
+        "pageY": 85
       },
       {
         "id": 102,
         "type": "DATE",
-        "positionY": 85
+        "pageY": 85
       }
     ]
   }'
@@ -377,16 +338,16 @@ const response = await fetch(
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
-      envelopeId: 'envelope_abcdefhiklmnorst',
-      data: [
-        { id: 101, type: 'SIGNATURE', positionY: 85 },
-        { id: 102, type: 'DATE', positionY: 85 },
+      documentId: 123,
+      fields: [
+        { id: 101, type: 'SIGNATURE', pageY: 85 },
+        { id: 102, type: 'DATE', pageY: 85 },
       ],
     }),
   }
 );
 
-const { data } = await response.json();
+const { fields } = await response.json();
 
 ````
 </Tab>
@@ -396,48 +357,9 @@ const { data } = await response.json();
 
 ```json
 {
-  "data": [
-    {
-      "id": 101,
-      "secondaryId": "field_abc123",
-      "envelopeId": "envelope_abcdefhiklmnorst",
-      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
-      "type": "SIGNATURE",
-      "recipientId": 456,
-      "page": 1,
-      "positionX": "10",
-      "positionY": "85",
-      "width": "30",
-      "height": "5",
-      "customText": "",
-      "inserted": false,
-      "fieldMeta": {
-        "type": "signature",
-        "fontSize": 18,
-        "overflow": "auto"
-      }
-    },
-    {
-      "id": 102,
-      "secondaryId": "field_def456",
-      "envelopeId": "envelope_abcdefhiklmnorst",
-      "envelopeItemId": "envelope_item_abcdefhiklmnorst",
-      "type": "DATE",
-      "recipientId": 456,
-      "page": 1,
-      "positionX": "50",
-      "positionY": "85",
-      "width": "20",
-      "height": "3",
-      "customText": "",
-      "inserted": false,
-      "fieldMeta": {
-        "type": "date",
-        "fontSize": 12,
-        "textAlign": "left",
-        "overflow": "auto"
-      }
-    }
+  "fields": [
+    { "id": 101, "type": "SIGNATURE", "positionY": 85 },
+    { "id": 102, "type": "DATE", "positionY": 85 }
   ]
 }
 ````
@@ -521,8 +443,8 @@ Fields use percentage-based coordinates relative to the PDF page dimensions.
 (0,0) ─────────────────────────── (100,0)
   │                                   │
   │    ┌─────────┐                    │
-  │    │  Field  │ (positionX: 10,    │
-  │    │         │  positionY: 20,    │
+  │    │  Field  │ (pageX: 10,        │
+  │    │         │  pageY: 20,        │
   │    └─────────┘  width: 30,        │
   │                 height: 5)        │
   │                                   │
@@ -535,9 +457,9 @@ Fields use percentage-based coordinates relative to the PDF page dimensions.
 const field = {
   type: 'SIGNATURE',
   recipientId: 123,
-  page: 1,
-  positionX: 60, // 60% from left
-  positionY: 85, // 85% from top (near bottom)
+  pageNumber: 1,
+  pageX: 60, // 60% from left
+  pageY: 85, // 85% from top (near bottom)
   width: 30, // 30% of page width
   height: 8, // 8% of page height
 };
@@ -557,33 +479,6 @@ This approach is useful when generating PDFs programmatically or using templates
 
 See the [PDF Placeholders](/docs/users/documents/advanced/pdf-placeholders) guide for the full placeholder format reference, including supported field types, recipient identifiers, and field options.
 
-### Placeholder Positioning via the API
-
-`POST /envelope/field/create-many` accepts a placeholder position in place of coordinates. Instead of `page`, `positionX`, `positionY`, `width`, and `height`, pass:
-
-| Field         | Type    | Required | Description                                                                                                  |
-| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------ |
-| `placeholder` | string  | Yes      | Text to search for in the PDF (e.g. `{{name}}`). The field is placed at the bounding box of the first match. |
-| `width`       | number  | No       | Override the field width. Defaults to the width of the matched text.                                          |
-| `height`      | number  | No       | Override the field height. Defaults to the height of the matched text.                                        |
-| `matchAll`    | boolean | No       | Create a field at every occurrence of the placeholder instead of only the first.                              |
-
-```json
-{
-  "envelopeId": "envelope_abcdefhiklmnorst",
-  "data": [
-    {
-      "type": "SIGNATURE",
-      "recipientId": 456,
-      "placeholder": "{{signature}}",
-      "matchAll": true
-    }
-  ]
-}
-```
-
-`POST /envelope/field/update-many` does not accept placeholders — field updates are coordinate-only.
-
 ---
 
 ## Field Meta Options
@@ -748,15 +643,15 @@ All field types support these base options:
 Create a document with a signature block containing multiple field types:
 
 ```typescript
-async function addSignatureBlock(envelopeId: string, recipientId: number) {
-  const data = [
+async function addSignatureBlock(documentId: number, recipientId: number) {
+  const fields = [
     // Signature
     {
       type: 'SIGNATURE',
       recipientId,
-      page: 1,
-      positionX: 10,
-      positionY: 80,
+      pageNumber: 1,
+      pageX: 10,
+      pageY: 80,
       width: 30,
       height: 8,
       fieldMeta: {
@@ -768,9 +663,9 @@ async function addSignatureBlock(envelopeId: string, recipientId: number) {
     {
       type: 'NAME',
       recipientId,
-      page: 1,
-      positionX: 10,
-      positionY: 90,
+      pageNumber: 1,
+      pageX: 10,
+      pageY: 90,
       width: 30,
       height: 4,
       fieldMeta: {
@@ -782,9 +677,9 @@ async function addSignatureBlock(envelopeId: string, recipientId: number) {
     {
       type: 'DATE',
       recipientId,
-      page: 1,
-      positionX: 50,
-      positionY: 80,
+      pageNumber: 1,
+      pageX: 50,
+      pageY: 80,
       width: 20,
       height: 4,
       fieldMeta: {
@@ -796,9 +691,9 @@ async function addSignatureBlock(envelopeId: string, recipientId: number) {
     {
       type: 'TEXT',
       recipientId,
-      page: 1,
-      positionX: 50,
-      positionY: 90,
+      pageNumber: 1,
+      pageX: 50,
+      pageY: 90,
       width: 30,
       height: 4,
       fieldMeta: {
@@ -815,7 +710,7 @@ async function addSignatureBlock(envelopeId: string, recipientId: number) {
       Authorization: 'api_xxxxxxxxxxxxxxxx',
       'Content-Type': 'application/json',
     },
-    body: JSON.stringify({ envelopeId, data }),
+    body: JSON.stringify({ documentId, fields }),
   });
 
   return response.json();

packages/lib/constants/app.test.ts

@@ -0,0 +1,21 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { NEXT_PRIVATE_SIGNING_REASON } from './app';
+
+describe('NEXT_PRIVATE_SIGNING_REASON', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('defaults to the Documenso signing reason', () => {
+    vi.stubEnv('NEXT_PRIVATE_SIGNING_REASON', undefined);
+
+    expect(NEXT_PRIVATE_SIGNING_REASON()).toBe('Signed by Documenso');
+  });
+
+  it('uses the configured signing reason verbatim', () => {
+    vi.stubEnv('NEXT_PRIVATE_SIGNING_REASON', 'Signed by Objective');
+
+    expect(NEXT_PRIVATE_SIGNING_REASON()).toBe('Signed by Objective');
+  });
+});

packages/lib/constants/app.ts

@@ -92,6 +92,7 @@ export const IS_AI_FEATURES_CONFIGURED = (): boolean => {
 export const NEXT_PRIVATE_USE_PLAYWRIGHT_PDF = () => env('NEXT_PRIVATE_USE_PLAYWRIGHT_PDF') === 'true';
 
 export const NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY = () => env('NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY');
+export const NEXT_PRIVATE_SIGNING_REASON = () => env('NEXT_PRIVATE_SIGNING_REASON') ?? 'Signed by Documenso';
 
 /**
  * Whether this Documenso instance is running in CSC (Cloud Signature Consortium) mode.

packages/signing/index.ts

@@ -1,4 +1,5 @@
 import {
+  NEXT_PRIVATE_SIGNING_REASON,
   NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER,
   NEXT_PUBLIC_SIGNING_CONTACT_INFO,
   NEXT_PUBLIC_WEBAPP_URL,
@@ -42,7 +43,7 @@ export const signPdf = async ({ pdf }: SignOptions) => {
 
   const { bytes } = await pdf.sign({
     signer,
-    reason: 'Signed by Documenso',
+    reason: NEXT_PRIVATE_SIGNING_REASON(),
     location: NEXT_PUBLIC_WEBAPP_URL(),
     contactInfo: NEXT_PUBLIC_SIGNING_CONTACT_INFO(),
     subFilter: NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER() ? 'adbe.pkcs7.detached' : 'ETSI.CAdES.detached',

packages/trpc/server/envelope-router/envelope-fields/update-envelope-fields.ts

@@ -29,17 +29,7 @@ export const updateEnvelopeFieldsRoute = authenticatedProcedure
         id: envelopeId,
       },
       type: null,
-      fields: fields.map((field) => ({
-        id: field.id,
-        type: field.type,
-        pageNumber: field.page,
-        pageX: field.positionX,
-        pageY: field.positionY,
-        width: field.width,
-        height: field.height,
-        fieldMeta: field.fieldMeta,
-        envelopeItemId: field.envelopeItemId,
-      })),
+      fields,
       requestMetadata: ctx.metadata,
     });
 

packages/tsconfig/process-env.d.ts

@@ -59,6 +59,7 @@ declare namespace NodeJS {
     NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET?: string;
     NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL?: 'AES' | 'QES';
     NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY?: string;
+    NEXT_PRIVATE_SIGNING_REASON?: string;
     NEXT_PUBLIC_SIGNING_CONTACT_INFO?: string;
     NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER?: string;