fix(docusign): page envelope and template lists, ignore missing signing anchors, and guard envelope path ids

Author: waleedlatif1

apps/sim/blocks/blocks/docusign.ts

@@ -287,7 +287,15 @@ export const DocuSignBlock: BlockConfig = {
       id: 'count',
       title: 'Max Results',
       type: 'short-input',
-      placeholder: '25',
+      placeholder: '100',
+      condition: { field: 'operation', value: ['list_envelopes', 'list_templates'] },
+      mode: 'advanced',
+    },
+    {
+      id: 'startPosition',
+      title: 'Start Position',
+      type: 'short-input',
+      placeholder: '0',
       condition: { field: 'operation', value: ['list_envelopes', 'list_templates'] },
       mode: 'advanced',
     },
@@ -359,6 +367,7 @@ export const DocuSignBlock: BlockConfig = {
     toDate: { type: 'string', description: 'End date filter' },
     searchText: { type: 'string', description: 'Search text filter' },
     count: { type: 'string', description: 'Max results to return' },
+    startPosition: { type: 'string', description: 'Zero-based index of the first result' },
   },
   outputs: {
     envelopeId: { type: 'string', description: 'Envelope ID' },
@@ -404,6 +413,18 @@ export const DocuSignBlock: BlockConfig = {
     fileName: { type: 'string', description: 'Document file name' },
     totalSetSize: { type: 'number', description: 'Total matching results' },
     resultSetSize: { type: 'number', description: 'Results returned in this response' },
+    startPosition: {
+      type: 'number',
+      description: 'Zero-based index of the first result in this page',
+    },
+    endPosition: {
+      type: 'number',
+      description: 'Zero-based index of the last result in this page',
+    },
+    nextUri: {
+      type: 'string',
+      description: 'URI of the next page of results (null on the last page)',
+    },
   },
 }
 

apps/sim/lib/internal/docusign/execute-tool.ts

@@ -45,12 +45,14 @@ const schemas = {
     envelopeStatus: z.string().optional(),
     searchText: z.string().optional(),
     count: z.string().optional(),
+    startPosition: z.string().optional(),
   }),
   docusign_list_recipients: z.object({ ...auth, envelopeId: z.string().min(1) }),
   docusign_list_templates: z.object({
     ...auth,
     searchText: z.string().optional(),
     count: z.string().optional(),
+    startPosition: z.string().optional(),
   }),
   docusign_send_envelope: z.object({
     ...auth,

apps/sim/lib/internal/docusign/operations.test.ts

@@ -43,6 +43,9 @@ const { mockProcessFilesToUserFiles } = fileUtilsMockFns
 import { DocuSignOperationError } from '@/lib/internal/docusign/errors'
 import {
   executeDocuSignDownloadDocument,
+  executeDocuSignGetEnvelope,
+  executeDocuSignListEnvelopes,
+  executeDocuSignListTemplates,
   executeDocuSignSendEnvelope,
 } from '@/lib/internal/docusign/operations'
 
@@ -124,4 +127,43 @@ describe('DocuSign operations', () => {
     })
     expect(mockUploadCopilotFile).not.toHaveBeenCalled()
   })
+
+  it('sends a document that lacks the anchor strings instead of failing on missing anchors', async () => {
+    await executeDocuSignSendEnvelope(
+      {
+        accessToken: 'access-token',
+        emailSubject: 'Sign',
+        signerEmail: 'a@example.com',
+        signerName: 'A',
+        file: { id: 'file-1' },
+      },
+      CONTEXT
+    )
+
+    const body = JSON.parse(mocks.json.mock.calls[0][1].body)
+    const tabs = body.recipients.signers[0].tabs
+    expect(tabs.signHereTabs[0].anchorIgnoreIfNotPresent).toBe('true')
+    expect(tabs.dateSignedTabs[0].anchorIgnoreIfNotPresent).toBe('true')
+  })
+
+  it.each([
+    ['envelopes', executeDocuSignListEnvelopes],
+    ['templates', executeDocuSignListTemplates],
+  ] as const)('pages %s with start_position', async (_name, execute) => {
+    await execute({ accessToken: 'access-token', count: '50', startPosition: '100' }, CONTEXT)
+
+    const query = new URL(`https://x${mocks.json.mock.calls[0][0]}`).searchParams
+    expect(query.get('start_position')).toBe('100')
+    expect(query.get('count')).toBe('50')
+  })
+
+  it.each(['..', 'env-1/../../users'])(
+    'rejects envelope id %s before contacting DocuSign',
+    async (envelopeId) => {
+      await expect(
+        executeDocuSignGetEnvelope({ accessToken: 'access-token', envelopeId }, CONTEXT)
+      ).rejects.toMatchObject({ status: 400 })
+      expect(mocks.create).not.toHaveBeenCalled()
+    }
+  )
 })

apps/sim/lib/internal/docusign/operations.ts

@@ -20,6 +20,7 @@ import type {
   DocuSignSendEnvelopeParams,
   DocuSignVoidEnvelopeParams,
 } from '@/tools/docusign/types'
+import { safeUrlPathSegment } from '@/tools/url-path'
 
 const logger = createLogger('DocuSignOperations')
 const MAX_LEGACY_INLINE_DOCUMENT_BYTES = 7 * 1024 * 1024
@@ -37,6 +38,14 @@ function jsonBody(data: Record<string, unknown>): RequestInit {
   return { method: 'POST', body: JSON.stringify(data) }
 }
 
+function pathSegment(value: string, paramName: string): string {
+  try {
+    return safeUrlPathSegment(value, paramName)
+  } catch (error) {
+    throw new DocuSignOperationError(getErrorMessage(error, `Invalid ${paramName}`), 400)
+  }
+}
+
 async function client(
   input: { accessToken: string; instanceUrl?: string },
   signal?: AbortSignal
@@ -141,6 +150,7 @@ export async function executeDocuSignSendEnvelope(
                 anchorUnits: 'pixels',
                 anchorXOffset: '0',
                 anchorYOffset: '0',
+                anchorIgnoreIfNotPresent: 'true',
               },
             ],
             dateSignedTabs: [
@@ -149,6 +159,7 @@ export async function executeDocuSignSendEnvelope(
                 anchorUnits: 'pixels',
                 anchorXOffset: '0',
                 anchorYOffset: '0',
+                anchorIgnoreIfNotPresent: 'true',
               },
             ],
           },
@@ -191,9 +202,10 @@ export async function executeDocuSignGetEnvelope(
   input: DocuSignGetEnvelopeParams,
   context: DocuSignOperationContext
 ) {
+  const envelopeId = pathSegment(input.envelopeId, 'envelopeId')
   const provider = await client(input, context.signal)
   return provider.json(
-    `/envelopes/${input.envelopeId.trim()}?include=recipients,documents`,
+    `/envelopes/${envelopeId}?include=recipients,documents`,
     {},
     'DocuSign envelope response',
     'Failed to get envelope',
@@ -216,6 +228,7 @@ export async function executeDocuSignListEnvelopes(
   if (input.envelopeStatus) query.append('status', input.envelopeStatus)
   if (input.searchText) query.append('search_text', input.searchText)
   if (input.count) query.append('count', input.count)
+  if (input.startPosition) query.append('start_position', input.startPosition)
   const provider = await client(input, context.signal)
   return provider.json(
     `/envelopes?${query}`,
@@ -230,9 +243,10 @@ export async function executeDocuSignVoidEnvelope(
   input: DocuSignVoidEnvelopeParams,
   context: DocuSignOperationContext
 ) {
+  const envelopeId = pathSegment(input.envelopeId, 'envelopeId')
   const provider = await client(input, context.signal)
   await provider.json(
-    `/envelopes/${input.envelopeId.trim()}`,
+    `/envelopes/${envelopeId}`,
     { method: 'PUT', body: JSON.stringify({ status: 'voided', voidedReason: input.voidedReason }) },
     'DocuSign void envelope response',
     'Failed to void envelope',
@@ -245,10 +259,11 @@ export async function executeDocuSignDownloadDocument(
   input: DocuSignDownloadDocumentParams,
   context: DocuSignOperationContext
 ) {
-  const documentId = input.documentId || 'combined'
+  const envelopeId = pathSegment(input.envelopeId, 'envelopeId')
+  const documentId = pathSegment(input.documentId || 'combined', 'documentId')
   const provider = await client(input, context.signal)
   const { buffer, contentType, fileName } = await provider.document(
-    input.envelopeId.trim(),
+    envelopeId,
     documentId,
     context.signal
   )
@@ -281,6 +296,7 @@ export async function executeDocuSignListTemplates(
   const query = new URLSearchParams()
   if (input.searchText) query.append('search_text', input.searchText)
   if (input.count) query.append('count', input.count)
+  if (input.startPosition) query.append('start_position', input.startPosition)
   const suffix = query.size ? `?${query}` : ''
   const provider = await client(input, context.signal)
   return provider.json(
@@ -296,9 +312,10 @@ export async function executeDocuSignListRecipients(
   input: DocuSignListRecipientsParams,
   context: DocuSignOperationContext
 ) {
+  const envelopeId = pathSegment(input.envelopeId, 'envelopeId')
   const provider = await client(input, context.signal)
   return provider.json(
-    `/envelopes/${input.envelopeId.trim()}/recipients`,
+    `/envelopes/${envelopeId}/recipients`,
     {},
     'DocuSign recipients response',
     'Failed to list recipients',

apps/sim/tools/docusign/list_envelopes.ts

@@ -2,7 +2,8 @@ import type {
   DocuSignListEnvelopesParams,
   DocuSignListEnvelopesResponse,
 } from '@/tools/docusign/types'
-import { ENVELOPES_ARRAY_OUTPUT } from '@/tools/docusign/types'
+import { ENVELOPES_ARRAY_OUTPUT, LIST_PAGINATION_OUTPUTS } from '@/tools/docusign/types'
+import { listPagination } from '@/tools/docusign/utils'
 import type { InternalToolConfig } from '@/tools/types'
 
 export const docusignListEnvelopesTool: InternalToolConfig<
@@ -61,7 +62,14 @@ export const docusignListEnvelopesTool: InternalToolConfig<
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Maximum number of envelopes to return (default: 25)',
+      description: 'Maximum number of envelopes to return (max 1000)',
+    },
+    startPosition: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Zero-based index of the first result to return, for paging through envelopes (default: 0)',
     },
   },
 
@@ -74,6 +82,7 @@ export const docusignListEnvelopesTool: InternalToolConfig<
       envelopeStatus: params.envelopeStatus,
       searchText: params.searchText,
       count: params.count,
+      startPosition: params.startPosition,
     }),
   },
 
@@ -97,6 +106,7 @@ export const docusignListEnvelopesTool: InternalToolConfig<
         envelopes,
         totalSetSize: Number(data.totalSetSize) || 0,
         resultSetSize: Number(data.resultSetSize) || envelopes.length,
+        ...listPagination(data),
       },
     }
   },
@@ -105,5 +115,6 @@ export const docusignListEnvelopesTool: InternalToolConfig<
     envelopes: ENVELOPES_ARRAY_OUTPUT,
     totalSetSize: { type: 'number', description: 'Total number of matching envelopes' },
     resultSetSize: { type: 'number', description: 'Number of envelopes returned in this response' },
+    ...LIST_PAGINATION_OUTPUTS,
   },
 }

apps/sim/tools/docusign/list_templates.ts

@@ -2,7 +2,8 @@ import type {
   DocuSignListTemplatesParams,
   DocuSignListTemplatesResponse,
 } from '@/tools/docusign/types'
-import { TEMPLATES_ARRAY_OUTPUT } from '@/tools/docusign/types'
+import { LIST_PAGINATION_OUTPUTS, TEMPLATES_ARRAY_OUTPUT } from '@/tools/docusign/types'
+import { listPagination } from '@/tools/docusign/utils'
 import type { InternalToolConfig } from '@/tools/types'
 
 export const docusignListTemplatesTool: InternalToolConfig<
@@ -43,7 +44,15 @@ export const docusignListTemplatesTool: InternalToolConfig<
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Maximum number of templates to return',
+      description:
+        'Maximum number of templates to return (DocuSign returns up to 2000 when omitted)',
+    },
+    startPosition: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Zero-based index of the first result to return, for paging through templates (default: 0)',
     },
   },
 
@@ -53,6 +62,7 @@ export const docusignListTemplatesTool: InternalToolConfig<
       instanceUrl: params.instanceUrl,
       searchText: params.searchText,
       count: params.count,
+      startPosition: params.startPosition,
     }),
   },
 
@@ -75,6 +85,7 @@ export const docusignListTemplatesTool: InternalToolConfig<
         templates,
         totalSetSize: Number(data.totalSetSize) || 0,
         resultSetSize: Number(data.resultSetSize) || templates.length,
+        ...listPagination(data),
       },
     }
   },
@@ -83,5 +94,6 @@ export const docusignListTemplatesTool: InternalToolConfig<
     templates: TEMPLATES_ARRAY_OUTPUT,
     totalSetSize: { type: 'number', description: 'Total number of matching templates' },
     resultSetSize: { type: 'number', description: 'Number of templates returned in this response' },
+    ...LIST_PAGINATION_OUTPUTS,
   },
 }

apps/sim/tools/docusign/send_envelope.ts

@@ -72,7 +72,8 @@ export const docusignSendEnvelopeTool: InternalToolConfig<
       type: 'file',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Document file to send for signature',
+      description:
+        'Document file to send for signature. Text "/sig1/" and "/date1/" in the document anchor the signature and date fields; without them the signer places fields freely',
     },
     status: {
       type: 'string',

apps/sim/tools/docusign/types.ts

@@ -52,6 +52,25 @@ export const TEMPLATE_OUTPUT_PROPERTIES = {
   lastModified: { type: 'string', description: 'ISO 8601 last modified date' },
 } as const satisfies Record<string, OutputProperty>
 
+/** Pagination outputs shared by the envelope and template list tools */
+export const LIST_PAGINATION_OUTPUTS = {
+  startPosition: {
+    type: 'number',
+    description: 'Zero-based index of the first result in this page',
+    optional: true,
+  },
+  endPosition: {
+    type: 'number',
+    description: 'Zero-based index of the last result in this page',
+    optional: true,
+  },
+  nextUri: {
+    type: 'string',
+    description: 'URI of the next page of results; null on the last page',
+    optional: true,
+  },
+} as const satisfies Record<string, OutputProperty>
+
 export const ENVELOPES_ARRAY_OUTPUT: OutputProperty = {
   type: 'array',
   description: 'Array of DocuSign envelopes',
@@ -117,6 +136,7 @@ export interface DocuSignListEnvelopesParams {
   envelopeStatus?: string
   searchText?: string
   count?: string
+  startPosition?: string
 }
 
 export interface DocuSignVoidEnvelopeParams {
@@ -138,6 +158,7 @@ export interface DocuSignListTemplatesParams {
   instanceUrl?: string
   searchText?: string
   count?: string
+  startPosition?: string
 }
 
 export interface DocuSignListRecipientsParams {
@@ -193,6 +214,9 @@ export interface DocuSignListEnvelopesResponse extends ToolResponse {
     }>
     totalSetSize: number
     resultSetSize: number
+    startPosition: number | null
+    endPosition: number | null
+    nextUri: string | null
   }
 }
 
@@ -224,6 +248,9 @@ export interface DocuSignListTemplatesResponse extends ToolResponse {
     }>
     totalSetSize: number
     resultSetSize: number
+    startPosition: number | null
+    endPosition: number | null
+    nextUri: string | null
   }
 }