feat(typescript): export types for strategy options, auth options, and the resulting authentication object (#5)

Author: gr2m

README.md

@@ -28,6 +28,7 @@
   - [GitHub APP user authentication token with expiring disabled](#github-app-user-authentication-token-with-expiring-disabled)
   - [GitHub APP user authentication token with expiring enabled](#github-app-user-authentication-token-with-expiring-enabled)
 - [`auth.hook(request, route, parameters)` or `auth.hook(request, options)`](#authhookrequest-route-parameters-or-authhookrequest-options)
+- [Types](#types)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -977,6 +978,27 @@ const requestWithAuth = request.defaults({
 const { data: user } = await requestWithAuth("GET /user");
 ```
 
+## Types
+
+```ts
+import {
+  GitHubAppAuthentication,
+  GitHubAppAuthenticationWithExpiration,
+  GitHubAppAuthOptions,
+  GitHubAppStrategyOptions,
+  GitHubAppStrategyOptionsDeviceFlow,
+  GitHubAppStrategyOptionsExistingAuthentication,
+  GitHubAppStrategyOptionsExistingAuthenticationWithExpiration,
+  GitHubAppStrategyOptionsWebFlow,
+  OAuthAppAuthentication,
+  OAuthAppAuthOptions,
+  OAuthAppStrategyOptions,
+  OAuthAppStrategyOptionsDeviceFlow,
+  OAuthAppStrategyOptionsExistingAuthentication,
+  OAuthAppStrategyOptionsWebFlow,
+} from "@octokit/auth-oauth-user";
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

src/auth.ts

@@ -1,4 +1,12 @@
-import { AuthOptions, Authentication, State, ClientType } from "./types";
+import {
+  OAuthAppAuthOptions,
+  GitHubAppAuthOptions,
+  OAuthAppAuthentication,
+  GitHubAppAuthentication,
+  GitHubAppAuthenticationWithExpiration,
+  OAuthAppState,
+  GitHubAppState,
+} from "./types";
 import { getAuthentication } from "./get-authentication";
 import {
   checkToken,
@@ -8,32 +16,48 @@ import {
   resetToken,
 } from "@octokit/oauth-methods";
 
-export async function auth<TClientType extends ClientType>(
-  state: State,
-  options: AuthOptions = {}
-): Promise<Authentication<TClientType>> {
+export async function auth(
+  state: OAuthAppState,
+  options?: OAuthAppAuthOptions
+): Promise<OAuthAppAuthentication>;
+
+export async function auth(
+  state: GitHubAppState,
+  options?: GitHubAppAuthOptions
+): Promise<GitHubAppAuthentication | GitHubAppAuthenticationWithExpiration>;
+
+export async function auth(
+  state: OAuthAppState | GitHubAppState,
+  options: OAuthAppAuthOptions | GitHubAppAuthOptions = {}
+): Promise<
+  | OAuthAppAuthentication
+  | GitHubAppAuthentication
+  | GitHubAppAuthenticationWithExpiration
+> {
   if (!state.authentication) {
-    state.authentication = await getAuthentication(state);
+    // This is what TS makes us do ¯\_(ツ)_/¯
+    state.authentication =
+      state.clientType === "oauth-app"
+        ? await getAuthentication(state)
+        : await getAuthentication(state);
   }
 
   if (state.authentication.invalid) {
     throw new Error("[@octokit/auth-oauth-user] Token is invalid");
   }
 
-  const currentAuthentication = (state.authentication as unknown) as Authentication<TClientType>;
+  const currentAuthentication = state.authentication;
 
   // (auto) refresh for user-to-server tokens
   if ("expiresAt" in currentAuthentication) {
     if (
       options.type === "refresh" ||
-      // @ts-expect-error TBD
       new Date(currentAuthentication.expiresAt) < new Date()
     ) {
       const { authentication } = await refreshToken({
         clientType: "github-app",
         clientId: state.clientId,
         clientSecret: state.clientSecret,
-        // @ts-expect-error TBD
         refreshToken: currentAuthentication.refreshToken,
         request: state.request,
       });
@@ -77,6 +101,11 @@ export async function auth<TClientType extends ClientType>(
         // @ts-expect-error TBD
         ...authentication,
       };
+
+      return state.authentication as
+        | OAuthAppAuthentication
+        | GitHubAppAuthentication
+        | GitHubAppAuthenticationWithExpiration;
     } catch (error) {
       // istanbul ignore else
       if (error.status === 404) {
@@ -88,8 +117,6 @@ export async function auth<TClientType extends ClientType>(
 
       throw error;
     }
-
-    return state.authentication as Authentication<TClientType>;
   }
 
   // invalidate
@@ -111,8 +138,8 @@ export async function auth<TClientType extends ClientType>(
     }
 
     state.authentication.invalid = true;
-    return state.authentication as Authentication<TClientType>;
+    return state.authentication;
   }
 
-  return state.authentication as Authentication<TClientType>;
+  return state.authentication;
 }

src/get-authentication.ts

@@ -1,13 +1,31 @@
 // @ts-nocheck there is only place for one of us in this file. And it's not you, TS
 
-import { State, ClientType, Authentication } from "./types";
+import {
+  OAuthAppState,
+  GitHubAppState,
+  OAuthAppAuthentication,
+  GitHubAppAuthentication,
+  GitHubAppAuthenticationWithExpiration,
+  Authentication,
+} from "./types";
 
 import { createOAuthDeviceAuth } from "@octokit/auth-oauth-device";
 import { exchangeWebFlowCode } from "@octokit/oauth-methods";
 
-export async function getAuthentication<TClientType extends ClientType>(
-  state: State
-): Promise<Authentication<TClientType>> {
+export async function getAuthentication(
+  state: OAuthAppState
+): Promise<OAuthAppAuthentication>;
+export async function getAuthentication(
+  state: GitHubAppState
+): Promise<GitHubAppAuthentication | GitHubAppAuthenticationWithExpiration>;
+
+export async function getAuthentication(
+  state: OAuthAppState | GitHubAppState
+): Promise<
+  | OAuthAppAuthentication
+  | GitHubAppAuthentication
+  | GitHubAppAuthenticationWithExpiration
+> {
   // handle code exchange form OAuth Web Flow
   if ("code" in state.strategyOptions) {
     const { authentication } = await exchangeWebFlowCode({

src/hook.ts

@@ -6,21 +6,36 @@ import {
   RequestParameters,
   Route,
 } from "@octokit/types";
-import { State } from "./types";
+import { OAuthAppState, GitHubAppState } from "./types";
 import { auth } from "./auth";
 
 type AnyResponse = OctokitResponse<any>;
 
 export async function hook(
-  state: State,
+  state: OAuthAppState,
+  request: RequestInterface,
+  route: Route | EndpointOptions,
+  parameters: RequestParameters
+): Promise<AnyResponse>;
+
+export async function hook(
+  state: GitHubAppState,
+  request: RequestInterface,
+  route: Route | EndpointOptions,
+  parameters: RequestParameters
+): Promise<AnyResponse>;
+
+export async function hook(
+  state: OAuthAppState | GitHubAppState,
   request: RequestInterface,
   route: Route | EndpointOptions,
   parameters: RequestParameters = {}
 ): Promise<AnyResponse> {
-  const { token } = await auth({
-    ...state,
-    request,
-  });
+  // TS makes us do this ¯\_(ツ)_/¯
+  const { token } =
+    state.clientType === "oauth-app"
+      ? await auth({ ...state, request })
+      : await auth({ ...state, request });
 
   const endpoint = request.endpoint.merge(
     route as string,

src/index.ts

@@ -4,11 +4,38 @@ import { request as octokitRequest } from "@octokit/request";
 import { VERSION } from "./version";
 import { auth } from "./auth";
 import { hook } from "./hook";
-import { StrategyOptions, State, ClientType, AuthInterface } from "./types";
+import {
+  State,
+  OAuthAppStrategyOptions,
+  GitHubAppStrategyOptions,
+  OAuthAppAuthInterface,
+  GitHubAppAuthInterface,
+} from "./types";
+export {
+  OAuthAppStrategyOptionsWebFlow,
+  GitHubAppStrategyOptionsWebFlow,
+  OAuthAppStrategyOptionsDeviceFlow,
+  GitHubAppStrategyOptionsDeviceFlow,
+  OAuthAppStrategyOptionsExistingAuthentication,
+  GitHubAppStrategyOptionsExistingAuthentication,
+  GitHubAppStrategyOptionsExistingAuthenticationWithExpiration,
+  OAuthAppStrategyOptions,
+  GitHubAppStrategyOptions,
+  OAuthAppAuthOptions,
+  GitHubAppAuthOptions,
+  OAuthAppAuthentication,
+  GitHubAppAuthentication,
+  GitHubAppAuthenticationWithExpiration,
+} from "./types";
 
-export function createOAuthUserAuth<
-  TClientType extends ClientType = "oauth-app"
->({
+export function createOAuthUserAuth(
+  options: OAuthAppStrategyOptions
+): OAuthAppAuthInterface;
+export function createOAuthUserAuth(
+  options: GitHubAppStrategyOptions
+): GitHubAppAuthInterface;
+
+export function createOAuthUserAuth({
   clientId,
   clientSecret,
   clientType = "oauth-app",
@@ -18,7 +45,9 @@ export function createOAuthUserAuth<
     },
   }),
   ...strategyOptions
-}: StrategyOptions<TClientType>): AuthInterface<TClientType> {
+}: OAuthAppStrategyOptions | GitHubAppStrategyOptions):
+  | OAuthAppAuthInterface
+  | GitHubAppAuthInterface {
   const state: State = Object.assign({
     clientType,
     clientId,
@@ -27,8 +56,9 @@ export function createOAuthUserAuth<
     request,
   });
 
-  // @ts-expect-error the extra code is not worth it just to make TS happpy
+  // @ts-expect-error not worth the extra code needed to appease TS
   return Object.assign(auth.bind(null, state), {
+    // @ts-expect-error not worth the extra code needed to appease TS
     hook: hook.bind(null, state),
   });
 }