feat(typescript): auth strategies (#19)

Author: gr2m

packages/types/index.d.ts

@@ -1,11 +1,30 @@
 import { RequestInterface } from "./request";
 export { RequestInterface } from "./request";
 
+interface AuthStrategyInterface {
+  (options?: any): AuthInterface;
+}
+interface AuthInterface {
+  (options?: any): Promise<unknown>;
+}
+
+type AuthStrategyAndOptions<AuthStrategy extends AuthStrategyInterface> = {
+  authStrategy: AuthStrategy;
+  auth: Parameters<AuthStrategy>[0];
+};
+
 /**
  * Global Octokit interfaces that can be extended as needed.
  */
 export namespace Octokit {
   interface Options {
+    /**
+     * API version. Defaults to `"github.com"`.
+     *
+     * In order to set it a GitHub Enterprise Version such as "ghes-3.1",
+     * install the according `@octokit-next/types-rest-api-ghes-*` package,
+     * such as `@octokit-next/types-rest-api-ghes-3.1`.
+     */
     version?: keyof Octokit.ApiVersions;
 
     /**
@@ -22,6 +41,22 @@ export namespace Octokit {
      */
     userAgent?: string;
 
+    // /**
+    //  * Auth strategy function
+    //  *
+    //  * @see https://github.com/octokit/auth.js
+    //  */
+    // authStrategy?: AuthStrategyInterface;
+
+    // /**
+    //  * Auth strategy options. Can be set to an access token. If `authStrategy`
+    //  * option is set, the auth option must be set to the authentication strategy options.
+    //  */
+    // auth?: String | Record<string, unknown>;
+
+    /**
+     * Request options passed as default `{ request }` options to every request.
+     */
     request?: RequestOptions;
   }
 
@@ -120,7 +155,8 @@ export namespace Octokit {
 
 export declare class Octokit<
   TVersion extends keyof Octokit.ApiVersions = "github.com",
-  TOptions extends Octokit.Options = Octokit.Options
+  TOptions extends Octokit.Options = Octokit.Options,
+  TAuthStrategy extends AuthStrategyInterface | never = never
 > {
   /**
    * Pass one or multiple plugin functions to extend the `Octokit` class.
@@ -216,7 +252,23 @@ export declare class Octokit<
    */
   options: { version: TVersion } & TOptions;
 
-  constructor(options: { version?: TVersion } & TOptions);
+  /**
+   * Constructor without setting `authStrategy`
+   *
+   * You can optionally set the `auth` option to an access token string in order
+   * to authenticate requests.
+   */
+  constructor(options: { version?: TVersion } & { auth?: string } & TOptions);
+
+  /**
+   * Constructor with setting `authStrategy`
+   *
+   * The `auth` option must be set to whatever the function passed as `authStrategy` accepts
+   */
+  constructor(
+    options: { version?: TVersion } & AuthStrategyAndOptions<TAuthStrategy> &
+      TOptions
+  );
 
   request: RequestInterface<TVersion>;
 }

tests/js/auth/index.d.ts

@@ -0,0 +1 @@
+export { Octokit } from "@octokit-next/core";

tests/js/auth/index.js

@@ -0,0 +1 @@
+export { Octokit } from "@octokit-next/core";

tests/js/auth/index.test-d.ts

@@ -0,0 +1,58 @@
+import { expectType } from "tsd";
+
+import { Octokit } from "./index.js";
+
+type CallbackStrategyOptions = {
+  callback: () => string | Promise<string>;
+};
+
+type AuthUnauthenticated = {
+  type: "unauthenticated";
+};
+
+type AuthToken = {
+  type: "token";
+  token: string;
+};
+
+interface CallbackAuth {
+  (options?: Record<string, unknown>): Promise<unknown>;
+}
+
+declare function createCallbackAuth(
+  options: CallbackStrategyOptions
+): CallbackAuth;
+
+export async function test() {
+  // set auth to access token
+  new Octokit({
+    auth: "token",
+  });
+
+  // @ts-expect-error - auth is required to be set to `{ callback }`
+  new Octokit({
+    authStrategy: createCallbackAuth,
+  });
+
+  new Octokit({
+    authStrategy: createCallbackAuth,
+    auth: {
+      callback() {
+        return "secret";
+      },
+    },
+  });
+
+  // @ts-expect-error - invalid auth options
+  new Octokit({
+    authStrategy: createCallbackAuth,
+    auth: "token",
+  });
+
+  const OctokitWithCallbackAuth = Octokit.withDefaults({
+    authStrategy: createCallbackAuth,
+  });
+
+  // TODO: @ts-expect-error - auth is required to be set to `{ callback }`
+  new OctokitWithCallbackAuth();
+}

tests/ts/auth/test.ts

@@ -0,0 +1,36 @@
+import { Octokit } from "@octokit-next/core";
+
+type CallbackStrategyOptions = {
+  callback: () => string | Promise<string>;
+};
+
+function createCallbackAuth(options: CallbackStrategyOptions) {
+  return async function auth() {
+    return options.callback();
+  };
+}
+
+export async function test() {
+  // set auth to access token
+  new Octokit({
+    auth: "token",
+  });
+
+  // @ts-expect-error - auth is required to be set to `{ callback }`
+  new Octokit({
+    authStrategy: createCallbackAuth,
+  });
+
+  // @ts-expect-error - invalid auth options
+  new Octokit({
+    authStrategy: createCallbackAuth,
+    auth: "token",
+  });
+
+  new Octokit({
+    authStrategy: createCallbackAuth,
+    auth: {
+      callback: () => "token",
+    },
+  });
+}

tests/ts/auth/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["*.ts"]
+}