Add typescript definition file for public API

[tatethurston]

Fixes #35.

Summary

Describe the goal of this PR. Mention any related Issue numbers.

Requirements (place an x in each [ ])

• I've read and understood the Contributing guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission, we really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codecov]

Codecov Report

Merging #52 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #52   +/-   ##
=======================================
  Coverage   94.26%   94.26%           
=======================================
  Files           4        4           
  Lines         122      122           
=======================================
  Hits          115      115           
  Misses          7        7

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 479b48c...d7e43f2. Read the comment docs.

[tatethurston]

Using "types" in package.json as suggested by the TS team http://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html.

I followed DefinitelyTyped's https://github.com/DefinitelyTyped/DefinitelyTyped project structure. As a type test, I'm using the first example from the readme.

[boazj]

Is something preventing this from being merged?

[aoberoi]

😮 i'm sorry i missed this PR earlier! thank you so much for taking the time to add some typing. i'll review and give you some feedback now.

[aoberoi]

i think this is a great start on getting types into this package. i'd like to also start thinking about whether we can leverage the AsyncAPI Spec to generate some of the types, so that re-syncing with the platform when additions or modifications are made becomes trivial. some of these ideas are also discussed here: slackapi/node-slack-sdk#496

[aoberoi]

its an interesting choice to essentially deliver the types in a separate package. i'm not certain what the advantages are to this approach over simply adding an index.d.ts to the root of the package. can you explain? one disadvantage i see is that its common practice to list the @types/* dependencies in the top-level package.json, see this section of the manual.

is the intention that we would publish two separate modules to npm? if so, i think that would be confusing, and at that point we might as well only offer ambient declarations via DefinitelyTyped.

[tatethurston]

Typescript's publishing documentation suggests publishing to the @types organization on npm if the package is not written in TypeScript.

I believe the intent is to avoid shipping type definitions to those who don't need them.

That said, I'm happy to instead add index.d.ts if that is your preferred approach.

[aoberoi]

i have some apprehension to committing an exhaustive list of event types into this repo. these values are bound to change over time, and that means developers would have to deal with a compiler error if an up to date set is not available. we came up with a technique to allow flexibility using generics in this issue. i'd prefer a solution that allowed unknown event types to work without a compiler error.

[tatethurston]

Sure, if that's a goal then we could union String at the end or simply define EventType as a string.