feat(auth): add onTokenCreated option (#90)

* feat(auth): add onTokenCreated option

* feat(auth): onTokenCreated is called for 'refresh' and 'reset' types

* fix(auth): missing 'onTokenCreated' argument passed down when destructuring arguments

* test(auth): add test coverage for 'onTokenCreated' option

* refactor(types): move shared properties to a common type and re-use it

* docs(readme): add information about onTokenCreated() option

* feat(get-authentication): add 'onTokenCreated' when using 'getAuthentication()'

* Update README.md

Author: oscard0m

README.md

@@ -281,7 +281,7 @@ The unguessable random string you provided in [Step 1 of GitHub's OAuth web appl
         <code>string</code>
       </th>
       <td>
-        
+
 The <code>redirect_uri</code> parameter you provided in [Step 1 of GitHub's OAuth web application flow](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#1-request-a-users-github-identity).
 
 </td>
@@ -709,6 +709,17 @@ The differences are
         array of scope names enabled for the token
       </td>
     </tr>
+    <tr>
+      <th>
+        <code>onTokenCreated</code>
+      </th>
+      <th>
+        <code>function</code>
+      </th>
+      <td>
+        callback invoked when a token is "reset" or "refreshed"
+      </td>
+    </tr>
     <tr>
       <th>
         <code>invalid</code>
@@ -808,6 +819,17 @@ Either `undefined` or `true`. Will be set to `true` if the token was invalided e
         The user access token
       </td>
     </tr>
+    <tr>
+      <th>
+        <code>onTokenCreated</code>
+      </th>
+      <th>
+        <code>function</code>
+      </th>
+      <td>
+        callback invoked when a token is "reset" or "refreshed"
+      </td>
+    </tr>
     <tr>
       <th>
         <code>invalid</code>

src/auth.ts

@@ -80,6 +80,10 @@ export async function auth(
     if (!currentAuthentication.hasOwnProperty("expiresAt")) {
       throw new Error("[@octokit/auth-oauth-user] Refresh token missing");
     }
+
+    await state.onTokenCreated?.(state.authentication, {
+      type: options.type,
+    });
   }
 
   // check or reset token
@@ -102,6 +106,12 @@ export async function auth(
         ...authentication,
       };
 
+      if (options.type === "reset") {
+        await state.onTokenCreated?.(state.authentication, {
+          type: options.type,
+        });
+      }
+
       return state.authentication as
         | OAuthAppAuthentication
         | GitHubAppAuthentication

src/get-authentication.ts

@@ -32,6 +32,7 @@ export async function getAuthentication(
       clientId: state.clientId,
       clientSecret: state.clientSecret,
       clientType: state.clientType,
+      onTokenCreated: state.onTokenCreated,
       ...state.strategyOptions,
       request: state.request,
     });
@@ -48,6 +49,7 @@ export async function getAuthentication(
     const deviceAuth = createOAuthDeviceAuth({
       clientType: state.clientType,
       clientId: state.clientId,
+      onTokenCreated: state.onTokenCreated,
       ...state.strategyOptions,
       request: state.request,
     });
@@ -70,6 +72,7 @@ export async function getAuthentication(
       clientId: state.clientId,
       clientSecret: state.clientSecret,
       clientType: state.clientType,
+      onTokenCreated: state.onTokenCreated,
       ...state.strategyOptions,
     };
   }

src/index.ts

@@ -47,6 +47,7 @@ export function createOAuthUserAuth({
       "user-agent": `octokit-auth-oauth-app.js/${VERSION} ${getUserAgent()}`,
     },
   }),
+  onTokenCreated,
   ...strategyOptions
 }: OAuthAppStrategyOptions | GitHubAppStrategyOptions):
   | OAuthAppAuthInterface
@@ -55,6 +56,7 @@ export function createOAuthUserAuth({
     clientType,
     clientId,
     clientSecret,
+    onTokenCreated,
     strategyOptions,
     request,
   });

src/types.ts

@@ -11,19 +11,21 @@ export type WebFlowOptions = {
 };
 
 // STRATEGY OPTIONS
-
-type CommonOAuthAppStrategyOptions = {
-  clientType?: "oauth-app";
+type CommonAppStrategyOptions = {
+  clientType?: ClientType;
   clientId: string;
   clientSecret: string;
   request?: OctokitTypes.RequestInterface;
+  onTokenCreated?: OnToketCreatedCallback;
 };
+
+type CommonOAuthAppStrategyOptions = {
+  clientType?: "oauth-app";
+} & CommonAppStrategyOptions;
+
 type CommonGitHubAppStrategyOptions = {
   clientType?: "github-app";
-  clientId: string;
-  clientSecret: string;
-  request?: OctokitTypes.RequestInterface;
-};
+} & CommonAppStrategyOptions;
 
 type OAuthAppDeviceFlowOptions = {
   onVerification: DeviceTypes.OAuthAppStrategyOptions["onVerification"];
@@ -119,11 +121,21 @@ export interface GitHubAppAuthInterface {
 
 // INTERNAL STATE
 
+type OnToketCreatedCallback = (
+  authentication:
+    | OAuthAppAuthentication
+    | GitHubAppAuthentication
+    | GitHubAppAuthenticationWithExpiration
+    | undefined,
+  options: OAuthAppAuthOptions | GitHubAppAuthOptions
+) => void | Promise<void>;
+
 export type OAuthAppState = {
   clientId: string;
   clientSecret: string;
   clientType: "oauth-app";
   request: OctokitTypes.RequestInterface;
+  onTokenCreated?: CommonAppStrategyOptions["onTokenCreated"];
   strategyOptions:
     | WebFlowOptions
     | OAuthAppDeviceFlowOptions
@@ -144,6 +156,7 @@ export type GitHubAppState = {
   clientSecret: string;
   clientType: "github-app";
   request: OctokitTypes.RequestInterface;
+  onTokenCreated?: CommonAppStrategyOptions["onTokenCreated"];
   strategyOptions:
     | WebFlowOptions
     | GitHubDeviceFlowOptions