[BUG]: Module @octokit/auth-token declares Token locally, but it is not exported.
#398
Comments
NatoBoram
added
Status: Triage
|
👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labled with |
That is considered using internal APIs. I wouldn't do this in general, it could break at any moment, there are no guarantees.
As mentioned in your pull request, |
|
I see it as valuable documentation. It shows where it comes from when I'm using it in code. In a flow where I have multiple authentication strategies depending on the deployment state (local testing vs deployed to prod), this gives clarity over what it is when I use It could also be used to expose JSDocs with information about what the token is and links to the documentation. A type template could be used to clarify its format, like |
|
I agree that having JSDoc is a useful tool. I really like the idea of the type format. You could narrow down the different token types with the different formats |
|
I got something working with formats: src/create-token-auth.ts | 11 ++++++++---
src/types.ts | 23 +++++++++++++++++++++--
test/index.test.ts | 2 ++
3 files changed, 31 insertions(+), 5 deletions(-)
diff --git a/src/create-token-auth.ts b/src/create-token-auth.ts
index 052c8df..4fac750 100644
--- a/src/create-token-auth.ts
+++ b/src/create-token-auth.ts
@@ -1,9 +1,9 @@
import { auth } from "./auth.js";
import { hook } from "./hook.js";
-import type { StrategyInterface, Token } from "./types.js";
+import type { BearerToken, StrategyInterface, Token } from "./types.js";
export const createTokenAuth: StrategyInterface = function createTokenAuth(
- token: Token,
+ token: Token | BearerToken,
) {
if (!token) {
throw new Error("[@octokit/auth-token] No token passed to createTokenAuth");
@@ -15,9 +15,14 @@ export const createTokenAuth: StrategyInterface = function createTokenAuth(
);
}
- token = token.replace(/^(token|bearer) +/i, "");
+ token = toToken(token);
return Object.assign(auth.bind(null, token), {
hook: hook.bind(null, token),
});
};
+
+/** Turns a {@link BearerToken} into a {@link Token}. */
+function toToken(token: BearerToken | Token): Token {
+ return token.replace(/^(token|bearer) +/i, "") as Token;
+}
diff --git a/src/types.ts b/src/types.ts
index 4dfb392..e912e07 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -2,7 +2,7 @@ import type * as OctokitTypes from "@octokit/types";
export type AnyResponse = OctokitTypes.OctokitResponse<any>;
export type StrategyInterface = OctokitTypes.StrategyInterface<
- [Token],
+ [Token | BearerToken],
[],
Authentication
>;
@@ -12,7 +12,26 @@ export type RequestParameters = OctokitTypes.RequestParameters;
export type RequestInterface = OctokitTypes.RequestInterface;
export type Route = OctokitTypes.Route;
-export type Token = string;
+export type Token =
+ | PersonalAccessToken
+ | InstallallationTokenV1
+ | InstallallationToken
+ | ActionToken
+ | InstallationUserToServerToken
+ | OAuthToken;
+
+export type ActionToken = `ghs_${string}`;
+export type InstallallationToken = `ghs_${string}`;
+export type InstallallationTokenV1 = `v1.${string}`;
+export type InstallationUserToServerToken = `ghu_${string}`;
+export type OAuthToken = `${string}.${string}.${string}`;
+export type PersonalAccessToken = `ghp_${string}`;
+
+export type BearerToken =
+ | `bearer ${Token}`
+ | `Bearer ${Token}`
+ | `token ${Token}`
+ | `Token ${Token}`;
export type OAuthTokenAuthentication = {
type: "token";
diff --git a/test/index.test.ts b/test/index.test.ts
index d01e090..b8de4a8 100644
--- a/test/index.test.ts
+++ b/test/index.test.ts
@@ -62,6 +62,8 @@ test("User-to-server token (User authentication through app installation)", asyn
});
test("invalid token", async () => {
+ // @ts-expect-error Argument of type `"whatislove"` is not assignable to
+ // parameter of type`Token | BearerToken`.
const auth = createTokenAuth("whatislove");
const authentication = await auth();It even highlights the "wrong token" in the tests. A type guard could be added to validate the token format client-side and to lower the burden of string->token conversion on library users. Each token type can be summarily documented: /**
* Personal access tokens are an alternative to using passwords for
* authentication to GitHub when using the [GitHub API](https://docs.github.com/en/rest/overview/authenticating-to-the-rest-api)
* or the [command line](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#using-a-personal-access-token-on-the-command-line).
*
* @see https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
*/
export type PersonalAccessToken = `ghp_${string}`;There's even an article that points to the documentation of many token formats: https://github.blog/changelog/2021-03-31-authentication-token-format-updates-are-generally-available/ I'm not sure in which direction I should modify #400, I just made it for my own purposes, but if there's something clear that your team wants, I can accommodate so we can ship this as early as possible. I think having these docs can heavily facilitate the usage of GitHub's API. |
|
Instead of exporting everything, I think we should simply add in an entry to the |
diff --git a/scripts/build.mjs b/scripts/build.mjs
index a392b44..55156f4 100644
--- a/scripts/build.mjs
+++ b/scripts/build.mjs
@@ -68,6 +68,9 @@ async function main() {
types: "./dist-types/index.d.ts",
import: "./dist-bundle/index.js",
},
+ "./types": {
+ types: "./dist-types/types.d.ts",
+ }
},
sideEffects: false,
},This should do the trick |
What happened?
Previously, I was using this type:
With the conversion to ESModules (I think), the file is no longer accessible, so I have to do with this:
But the type forgot to be exported
Versions
"@octokit/auth-token": "^5.0.1",
Relevant log output
No response
Code of Conduct
The text was updated successfully, but these errors were encountered: