boldsign

Instructions

Implementation Reference

• src/tools/documentsTools/listDocuments.ts:100-126 (handler)

  The handler function listDocumentsHandler that initializes DocumentApi, calls listDocuments with payload parameters, handles response with handleMcpResponse, and errors with handleMcpError.

  async function listDocumentsHandler(payload: ListDocumentsSchemaType): Promise<McpResponse> {
    try {
      const documentApi = new DocumentApi();
      documentApi.basePath = configuration.getBasePath();
      documentApi.setApiKey(configuration.getApiKey());
      const documentRecords: DocumentRecords = await documentApi.listDocuments(
        payload.page,
        payload.sentBy ?? undefined,
        payload.recipients ?? undefined,
        (payload.transmitType as any) ?? undefined,
        payload.dateFilterType ?? undefined,
        payload.pageSize ?? undefined,
        payload.startDate ?? undefined,
        payload.status ?? undefined,
        payload.endDate ?? undefined,
        payload.searchKey ?? undefined,
        payload.labels ?? undefined,
        payload.nextCursor ?? undefined,
        payload.brandIds ?? undefined,
      );
      return handleMcpResponse({
        data: documentRecords,
      });
    } catch (error: any) {
      return handleMcpError(error);
    }
  }

• src/tools/documentsTools/listDocuments.ts:9-85 (schema)

  Zod schema defining input parameters for the list_documents tool, including pagination, filters by sender, recipients, dates, labels, status, etc.

  const ListDocumentsSchema = z.object({
    pageSize: z.number().int().min(1).max(100),
    page: z.number().int().min(1).default(1),
    searchKey: commonSchema.OptionalStringSchema.describe(
      'Optional. A search term used to filter the document list. The API will return documents matching details like document title, document ID, sender name, or recipient name.',
    ),
    sentBy: z
      .array(commonSchema.EmailSchema.describe('Email address of the sender.'))
      .optional()
      .describe(
        'Optional. Filter documents by sender email addresses. One or more sender email IDs can be specified.',
      ),
    recipients: z
      .array(commonSchema.EmailSchema.describe('Email address of the signer.'))
      .optional()
      .describe(
        'Optional. Filter documents by signer email addresses. One or more signer email IDs can be specified.',
      ),
    startDate: commonSchema.OptionalDateSchema.describe(
      'Optional. Start transmit date range of the document. The date should be in a valid date-time format.',
    ),
    endDate: commonSchema.OptionalDateSchema.describe(
      'Optional. End transmit date range of the document. The date should be in a valid date-time format.',
    ),
    labels: z
      .array(z.string().describe('Label of the document.'))
      .optional()
      .default([])
      .describe(
        'Optional. Labels associated with documents. Used to filter the list by specific document tags.',
      ),
    transmitType: z
      .enum(['Sent', 'Received', 'Both'])
      .optional()
      .default('Both')
      .describe(
        'Optional. Type of transmission to filter documents if the user is both sender, recipient or both.',
      ),
    status: z
      .array(
        z
          .enum([
            'None',
            'WaitingForMe',
            'WaitingForOthers',
            'NeedAttention',
            'Completed',
            'Declined',
            'Revoked',
            'Expired',
            'Scheduled',
            'Draft',
          ])
          .default('None'),
      )
      .optional()
      .default([])
      .describe('Optional. Filter documents based on their current status.'),
    nextCursor: z
      .number()
      .optional()
      .describe(
        'Optional. Cursor value for pagination beyond 10,000 records. Set to the cursor of the last retrieved document.',
      ),
    brandIds: z
      .array(commonSchema.InputIdSchema.describe('Unique identifier (ID) of the brand.'))
      .optional()
      .describe(
        'Optional. Filters documents based on associated brand IDs. Only documents linked to the specified brands will be retrieved.',
      ),
    dateFilterType: z
      .enum(['SentBetween', 'Expiring'])
      .optional()
      .describe(
        "Optional. Type of date filter applied to documents. Available options: 'SentBetween' and 'Expiring'.",
      ),
  });

• src/tools/documentsTools/listDocuments.ts:89-98 (registration)

  Tool definition for 'list_documents' including method name, description, input schema, and wrapper handler that delegates to listDocumentsHandler. Exported and included in higher-level tool arrays.

  export const listDocumentsToolDefinition: BoldSignTool = {
    method: ToolNames.ListDocuments.toString(),
    name: 'List documents',
    description:
      'Retrieve a paginated list of documents available in your My Documents section. This API fetches document details such as status, sender, recipient, labels, transmission type, creation date, and modification date, with options for filtering and paginated navigation.',
    inputSchema: ListDocumentsSchema,
    async handler(args: unknown): Promise<McpResponse> {
      return await listDocumentsHandler(args as ListDocumentsSchemaType);
    },
  };

• src/tools/toolNames.ts:54-54 (helper)

  Enum definition providing the string tool name 'list_documents' used in the tool definition's method field.

  ListDocuments = 'list_documents',

• src/tools/documentsTools/index.ts:8-14 (registration)

  Aggregation of document-related tool definitions into an array, which is then spread into the global tools definitions.

  export const documentsApiToolsDefinitions: BoldSignTool[] = [
    getDocumentPropertiesToolDefinition,
    listDocumentsToolDefinition,
    listTeamDocumentsToolDefinition,
    sendReminderForDocumentToolDefinition,
    revokeDocumentToolDefinition,
  ];