Better documentation for the getEmployees API

[haydn]

SDK you're using (please complete the following information):

• Version 4.18.0

Is your feature request related to a problem? Please describe.

The AU payroll getEmployees() method (and presumably the underlying /Employees API endpoint) does not return all the nested fields. Things like taxDeclaration and homeAddress are undefined in the response. This is not documented clearly.

Describe the solution you'd like

A stricter type for the getEmployees() return value, an explanation in the JSDoc summary that the nested details won't be included and/or an explanation in the API docs that all the employee details won't be returned.

Describe alternatives you've considered

N/A

Additional context

A bit of a side note: The fact that the list API doesn't return all the employees details is a pretty frustrating design. If you want to get all the details for all employees in an organisation (e.g. when you're importing them all into another system) you have to make a separate requests for each and every employee. And because of the 60 requests per minute rate limit, that means it's going to take you about as many seconds as you have employees to do the import. More than 2 minutes to fully load just 120 employees!

[aprilmintacpineda]

On top of this, the library should give us an option on how we want the rate limit to be handled, do we want to wait until next, do we want it to throw error, etc. Xero's API is extremely limited for a company that just reached the billion dollar mark.