feat: options.id can be set to Client ID (#98) (#100)

See https://github.blog/changelog/2024-05-01-github-apps-can-now-use-the-client-id-to-fetch-installation-tokens/

Author: gr2m

README.md

@@ -87,10 +87,10 @@ For a complete implementation of GitHub App authentication strategies, see [`@oc
         <code>options.id</code>
       </th>
       <th>
-        <code>number</code>
+        <code>number | string</code>
       </th>
       <td>
-        <strong>Required</strong>. Find <strong>App ID</strong> on the app’s about page in settings.
+        <strong>Required</strong>. The GitHub App's ID or Client ID. For <code>github.com</code> and GHES 3.14+, it is recommended to use the Client ID.
       </td>
     </tr>
     <tr>
@@ -154,7 +154,7 @@ For a complete implementation of GitHub App authentication strategies, see [`@oc
         <code>number</code>
       </th>
       <td>
-        The GitHub App database ID passed in <code>options.id</code>.
+        The GitHub App database ID or Client ID passed in <code>options.id</code>.
       </td>
     </tr>
     <tr>

index.d.ts

@@ -1,13 +1,13 @@
-export type Options = {
-  id: number;
+export type Options<IdType extends number | string = number> = {
+  id: IdType;
   privateKey: string;
   now?: number;
 };
 
-export type Result = {
-  appId: number;
+export type Result<IdType extends number | string = number> = {
+  appId: IdType extends string ? string : number;
   expiration: number;
   token: string;
 };
 
-export default function githubAppJwt(options: Options): Promise<Result>;
+export default function githubAppJwt<T extends number | string = number>(options: Options<T>): Promise<Result<T>>;

index.test-d.ts

@@ -11,3 +11,15 @@ export async function test() {
   expectType<number>(result.expiration);
   expectType<string>(result.token);
 }
+
+// Test case to verify `id` can be set to a string
+export async function testWithStringId() {
+  const resultWithStringId = await githubAppJwt({
+    id: "client_id_string",
+    privateKey: "",
+  });
+
+  expectType<string>(resultWithStringId.appId);
+  expectType<number>(resultWithStringId.expiration);
+  expectType<string>(resultWithStringId.token);
+}

internals.d.ts

@@ -1,7 +1,7 @@
 export type Payload = {
   iat: number;
   exp: number;
-  iss: number;
+  iss: number | string;
 };
 
 export type Header = { alg: "RS256"; typ: "JWT" };

test/node.test.js

@@ -177,3 +177,16 @@ test("Replace escaped line breaks with actual linebreaks", async (t) => {
     token: BEARER,
   });
 });
+
+// New test for id set to Client ID
+test("id set to Client ID", async (t) => {
+  MockDate.set(0);
+
+  const result = await githubAppJwt({
+    id: "client_id_string",
+    privateKey: PRIVATE_KEY_PKCS8,
+  });
+
+  t.is(typeof result.token, "string");
+  t.is(result.appId, "client_id_string");
+});