feat: make the d.ts useful

[JustinBeckwith]

It can always be better, but this is a first crack at closing the loop on #503. This makes some tradeoffs to avoid breaking the API. Thoughts appreciated :)

Note: all the good stuff is at the end. You can safely ignore generated file changes.

Resolves #503.

[andrelaszlo]

@JustinBeckwith This is cool! How can I use this in my code? For example:

  async listEvents(...): Promise<Schema$Event[]> { ... }

But how do I get the compiler to recognize Schema$Event? I could use triple-slash directives/reference path or an ugly import (probably something like import { Schema$Event } from '../../node_modules/googleapis/build/src/apis/calendar/v3.d'; in my case).

Is there a cleaner way?

[JustinBeckwith]

Good point! I am working on a fix to make those interfaces a little more visible as part of #1112.