example wrapping Got inside api client with types

[terinjokes]

Got does a lot of the underlying work I would want to do in an restful API client: promises and streams, cancelation, retries, timeouts, caching, HTTP/2, TypeScript, and more. Looking at the release notes, Got 12 is shaping up to be an exciting release.

One place I'm having difficulty understanding is the best way to wrap Got in an API client with request and response types, but preserving much of the feature-set of Got. The examples provided, and the ecosystem links in the readme don't attempt to provide types, are mostly setting Got options (and so users still need to create requests manually), or return type Promise<any>.

Ideally a user of my library would be able to do something like the following:

import { CancelableEventingPromise } from "got"
import { ExampleAPI } from "example";

interface FizzBuzz {
  fizz: boolean;
  buzz: boolean;
}

const prom: CancelableEventingPromise<FizzBuzz> = ExampleAPI.isFizzBuzz(20);

// `prom.cancel` and `prom.on` should be typed here.

const res = await prom;

// 

console.log(res.fizz) // false
console.log(res.buzz) // true

Is there a recommended pattern for wrapping Got in a TypeScript-friendly way? If this is outside the scope of Got, is the a recommendation of what I might use instead?

[szmarczak]

Related with #1117