Typescript definition improvement: Added types for payload property

[paustint]

Description of the change

Improve typescript type definition.

Added types for Payload instead of using object
Added comments with links to documentation
Added comments to aid in understanding code_version
Added optional Promise return type for transform

Motivation:
I spent hours trying to troubleshoot and figure out why items were not being matched up with source maps and the typescript definitions left me confused and unsure about how to configure the payload property because the documentation, at times, is not explicit about where a property lives.

For example, this page https://docs.rollbar.com/docs/source-control#serverroot makes it seem like there is a root level configuration option called server (which as far as I can tell that is not the case)
And this example seems to show the server property in the root (I guess?) https://docs.rollbar.com/docs/source-maps#can-i-still-set-up-source-linking-when-using-source-maps

Either way, the payload property is well defined(ish) in the docs, so there is no reason it should be object in the type definition.

I did add [property: string]: any; to ever level in the payload property and all nested children so that typescript users can supply anything they want, but will get type completion and jsdoc comments for known properties. I wasn't sure how else the payload is used outside what the docs mention.

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Maintenance
• New release

Related issues

Shortcut stories and GitHub issues (delete irrelevant)

• Fix [SC-]
• Fix Added ability to send custom stack traces to _ratchet.push #1

Checklists

Development

(These are all N/A since as far as I can tell, there are no tests for the Typescript definition file 😳 )

• Lint rules pass locally
• The code changed/added as part of this pull request has been covered with tests
• All tests related to the changed code pass in development

Code review

• This pull request has a descriptive title and information useful to a reviewer. There may be a screenshot or screencast attached
• "Ready for review" label attached to the PR and reviewers assigned
• Issue from task tracker has a link to this pull request
• Changes have been reviewed by at least one other engineer

[waltjones]

@paustint These are good improvements. Thanks for the PR!

My only concern is about back compatibility with a few of the types. The ones that concern me most are payload.person.id and payload.client.javascript.code_version. In both cases, the Rollbar API, back end, and dashboard filtering all happen to work fine when using a number type and I'd like to avoid that kind of breaking change for people who are currently setting a number value. That said, the correct type is string, so I'd like to allow number but mark it deprecated.

Something like:

    /**
      * @deprecated number is deprecated for this field
      */
    export type DeprecatedNumber = number;

And then

id: string | DeprecatedNumber;

code_version: string | DeprecatedNumber;

Let me know if you see a better way to do this.

I noticed the eslint deprecation plugin won't warn on this as I'd have expected. This appears to be a known issue described here. gund/eslint-plugin-deprecation#13

Separately, to answer the question about usage of the payload key in general. The contents of this key are merged to the root of the payload before sending. So, for example, the payload.server key does get mapped to a root level server key. payload: { foo: 'bar'} will put a foo key in the root of the payload.

Adding [property: string]: any; to each object is a good call, as people may use the payload key in arbitrary ways.

[waltjones]

👍