jg-github 0.0.0-stage → 0.2.0

package/dist/installation-token/index.d.ts

@@ -0,0 +1,2 @@
+export type { ICreateInstallationTokenOptions, IGithubPermissionLevel, IGithubPermissions, IGithubRepository, IGithubRequestOptions, IInstallationToken, IInstallationTokenRepositories, } from './types.js';
+export { createInstallationToken, revokeInstallationToken } from './installation-token.js';

package/dist/installation-token/index.js

@@ -0,0 +1,3 @@
+// installation tokens
+export { createInstallationToken, revokeInstallationToken } from './installation-token.js';
+//# sourceMappingURL=index.js.map

package/dist/installation-token/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/installation-token/index.ts"],"names":[],"mappings":"AAWA,sBAAsB;AACtB,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC","sourcesContent":["// types\nexport type {\n  ICreateInstallationTokenOptions,\n  IGithubPermissionLevel,\n  IGithubPermissions,\n  IGithubRepository,\n  IGithubRequestOptions,\n  IInstallationToken,\n  IInstallationTokenRepositories,\n} from './types.js';\n\n// installation tokens\nexport { createInstallationToken, revokeInstallationToken } from './installation-token.js';\n"]}

package/dist/installation-token/installation-token.d.ts

@@ -0,0 +1,57 @@
+import type { ICreateInstallationTokenOptions, IGithubRequestOptions, IInstallationToken } from './types.js';
+/**
+ * Revokes an installation token before it expires, such as when the work it was for is done,
+ * with `DELETE /installation/token`, which GitHub answers with 204. It never retries. The error
+ * never holds the token.
+ * @param token The installation token.
+ * @param options The User-Agent, the API's base URL and version, and the limits.
+ * @returns A promise that resolves once GitHub has revoked it.
+ * @example
+ * import { revokeInstallationToken } from 'jg-github';
+ *
+ * declare const token: string;
+ *
+ * await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ * - GITHUB_TOKEN_REVOKE_FAILED: The installation token couldn't be revoked.
+ */
+export declare const revokeInstallationToken: (token: string, { userAgent, apiOrigin, apiVersion, timeoutSeconds, signal, }: IGithubRequestOptions) => Promise<void>;
+/**
+ * Creates an installation token for exactly the repositories and the permissions asked for, with
+ * `POST /app/installations/{id}/access_tokens`, authenticated as the App. `permissions` is
+ * required, because GitHub grants every permission of the installation without it, and the
+ * repositories are named by name or by ID, never both. The granted token must reach exactly
+ * those repositories, only the selected ones, with exactly those permissions, plus
+ * `metadata: 'read'`, and must not have expired; otherwise it's revoked before the error is
+ * thrown, and the error's data says whether that worked. Nothing is retried, and no error holds
+ * the token or the App's JWT.
+ * @param options The App, the installation, the scope, and the request's limits.
+ * @returns A promise that resolves to the token, when it expires, and what it reaches.
+ * @example
+ * import { createInstallationToken, revokeInstallationToken } from 'jg-github';
+ *
+ * declare const privateKey: string;
+ *
+ * const { token } = await createInstallationToken({
+ *   appId: 123456,
+ *   privateKey,
+ *   installationId: 12345678,
+ *   repositories: ['app'],
+ *   permissions: { contents: 'read' },
+ *   userAgent: 'acme-deploy-bot',
+ * });
+ * try {
+ *   // read the repository's contents with the token
+ * } finally {
+ *   await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });
+ * }
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ * - GITHUB_PRIVATE_KEY_INVALID: The GitHub App's private key isn't an unencrypted RSA private key.
+ * - GITHUB_REQUEST_FAILED: The GitHub request failed.
+ * - GITHUB_RESPONSE_INVALID: GitHub's response isn't in the expected format.
+ * - GITHUB_TOKEN_SCOPE_MISMATCH: The installation token's scope isn't the one requested.
+ * - GITHUB_TOKEN_EXPIRED: The installation token had already expired.
+ */
+export declare const createInstallationToken: (options: ICreateInstallationTokenOptions) => Promise<IInstallationToken>;

package/dist/installation-token/installation-token.js

@@ -0,0 +1,152 @@
+import { request } from 'jg-fetch';
+import { createGithubAppJwt } from '../app-auth/index.js';
+import { DEFAULT_GITHUB_MAX_RESPONSE_BYTES, DEFAULT_GITHUB_TIMEOUT_SECONDS, buildGithubApiUrl, createGithubHeaders, } from '../shared/index.js';
+import { INVALID_ARGUMENT_KINDS } from './constants.js';
+import { fromFetchError, responseInvalid, revokeFailed, scopeMismatch, tokenExpired, } from './errors.js';
+import { findScopeMismatch, readToken, readTokenDetails } from './utilities.js';
+import { readInstallationId, readPermissions, readRequestedRepositories } from './validations.js';
+/**
+ * Revokes an installation token before it expires, such as when the work it was for is done,
+ * with `DELETE /installation/token`, which GitHub answers with 204. It never retries. The error
+ * never holds the token.
+ * @param token The installation token.
+ * @param options The User-Agent, the API's base URL and version, and the limits.
+ * @returns A promise that resolves once GitHub has revoked it.
+ * @example
+ * import { revokeInstallationToken } from 'jg-github';
+ *
+ * declare const token: string;
+ *
+ * await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ * - GITHUB_TOKEN_REVOKE_FAILED: The installation token couldn't be revoked.
+ */
+export const revokeInstallationToken = async (token, { userAgent, apiOrigin, apiVersion, timeoutSeconds = DEFAULT_GITHUB_TIMEOUT_SECONDS, signal, }) => {
+    const headers = createGithubHeaders(token, { userAgent, apiVersion });
+    const { error, meta } = await request(buildGithubApiUrl(['installation', 'token'], {}, { apiOrigin }), {
+        method: 'DELETE',
+        headers,
+        parseAs: 'none',
+        retryDelaysSeconds: [],
+        timeoutSeconds,
+        init: { redirect: 'error' },
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (error !== null) {
+        throw INVALID_ARGUMENT_KINDS.has(error.kind)
+            ? fromFetchError(error, [token])
+            : revokeFailed(error.kind, error.status, [token]);
+    }
+    if (meta.status !== 204) {
+        throw revokeFailed('UNEXPECTED_STATUS', meta.status, [token]);
+    }
+};
+/**
+ * Revokes a token jg-github received but won't hand over, with its own timeout and without the
+ * caller's signal, so a cancelled call still revokes it.
+ * @param token The token.
+ * @param options The request's options.
+ * @returns A promise that resolves to whether GitHub revoked it.
+ */
+const revokeUnusedToken = async (token, { userAgent, apiOrigin, apiVersion, timeoutSeconds }) => {
+    try {
+        await revokeInstallationToken(token, { userAgent, apiOrigin, apiVersion, timeoutSeconds });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Creates an installation token for exactly the repositories and the permissions asked for, with
+ * `POST /app/installations/{id}/access_tokens`, authenticated as the App. `permissions` is
+ * required, because GitHub grants every permission of the installation without it, and the
+ * repositories are named by name or by ID, never both. The granted token must reach exactly
+ * those repositories, only the selected ones, with exactly those permissions, plus
+ * `metadata: 'read'`, and must not have expired; otherwise it's revoked before the error is
+ * thrown, and the error's data says whether that worked. Nothing is retried, and no error holds
+ * the token or the App's JWT.
+ * @param options The App, the installation, the scope, and the request's limits.
+ * @returns A promise that resolves to the token, when it expires, and what it reaches.
+ * @example
+ * import { createInstallationToken, revokeInstallationToken } from 'jg-github';
+ *
+ * declare const privateKey: string;
+ *
+ * const { token } = await createInstallationToken({
+ *   appId: 123456,
+ *   privateKey,
+ *   installationId: 12345678,
+ *   repositories: ['app'],
+ *   permissions: { contents: 'read' },
+ *   userAgent: 'acme-deploy-bot',
+ * });
+ * try {
+ *   // read the repository's contents with the token
+ * } finally {
+ *   await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });
+ * }
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ * - GITHUB_PRIVATE_KEY_INVALID: The GitHub App's private key isn't an unencrypted RSA private key.
+ * - GITHUB_REQUEST_FAILED: The GitHub request failed.
+ * - GITHUB_RESPONSE_INVALID: GitHub's response isn't in the expected format.
+ * - GITHUB_TOKEN_SCOPE_MISMATCH: The installation token's scope isn't the one requested.
+ * - GITHUB_TOKEN_EXPIRED: The installation token had already expired.
+ */
+export const createInstallationToken = async (options) => {
+    const { appId, privateKey, installationId, permissions, repositories, repositoryIds, userAgent, apiOrigin, apiVersion, timeoutSeconds = DEFAULT_GITHUB_TIMEOUT_SECONDS, maxResponseBytes = DEFAULT_GITHUB_MAX_RESPONSE_BYTES, signal, } = options;
+    const id = readInstallationId(installationId);
+    const requestedPermissions = readPermissions(permissions);
+    const requested = readRequestedRepositories(repositories, repositoryIds);
+    const url = buildGithubApiUrl(['app', 'installations', id, 'access_tokens'], {}, { apiOrigin });
+    const jwt = createGithubAppJwt({ appId, privateKey });
+    const { data, error, meta } = await request(url, {
+        method: 'POST',
+        headers: createGithubHeaders(jwt, { userAgent, apiVersion }),
+        body: {
+            permissions: requestedPermissions,
+            ...(requested.kind === 'names'
+                ? { repositories: requested.values }
+                : { repository_ids: requested.values }),
+        },
+        parseAs: 'json',
+        retryDelaysSeconds: [],
+        timeoutSeconds,
+        maxResponseBytes,
+        init: { redirect: 'error' },
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (error !== null) {
+        throw fromFetchError(error, [jwt]);
+    }
+    const token = readToken(data);
+    if (token === undefined) {
+        throw responseInvalid([jwt]);
+    }
+    // from here on GitHub granted a token, which is revoked before any error is thrown
+    const redact = [jwt, token];
+    const revokeOptions = { userAgent, apiOrigin, apiVersion, timeoutSeconds };
+    const details = meta.status === 201 ? readTokenDetails(data) : undefined;
+    if (details === undefined) {
+        throw responseInvalid(redact, await revokeUnusedToken(token, revokeOptions));
+    }
+    const mismatch = findScopeMismatch(details, requested, requestedPermissions);
+    if (mismatch !== null) {
+        throw scopeMismatch(mismatch, await revokeUnusedToken(token, revokeOptions), redact);
+    }
+    if (details.expiresAt.getTime() <= Date.now()) {
+        throw tokenExpired(await revokeUnusedToken(token, revokeOptions), redact);
+    }
+    return {
+        token,
+        expiresAt: details.expiresAt,
+        permissions: details.permissions,
+        repositories: details.repositories.map(({ id: repositoryId, fullName }) => ({
+            id: repositoryId,
+            fullName,
+        })),
+    };
+};
+//# sourceMappingURL=installation-token.js.map

package/dist/installation-token/installation-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installation-token.js","sourceRoot":"","sources":["../../src/installation-token/installation-token.ts"],"names":[],"mappings":"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","sourcesContent":["import { request } from 'jg-fetch';\n\nimport { createGithubAppJwt } from '../app-auth/index.js';\nimport {\n  DEFAULT_GITHUB_MAX_RESPONSE_BYTES,\n  DEFAULT_GITHUB_TIMEOUT_SECONDS,\n  buildGithubApiUrl,\n  createGithubHeaders,\n} from '../shared/index.js';\nimport { INVALID_ARGUMENT_KINDS } from './constants.js';\nimport {\n  fromFetchError,\n  responseInvalid,\n  revokeFailed,\n  scopeMismatch,\n  tokenExpired,\n} from './errors.js';\nimport type {\n  ICreateInstallationTokenOptions,\n  IGithubRequestOptions,\n  IInstallationToken,\n} from './types.js';\nimport { findScopeMismatch, readToken, readTokenDetails } from './utilities.js';\nimport { readInstallationId, readPermissions, readRequestedRepositories } from './validations.js';\n\n/**\n * Revokes an installation token before it expires, such as when the work it was for is done,\n * with `DELETE /installation/token`, which GitHub answers with 204. It never retries. The error\n * never holds the token.\n * @param token The installation token.\n * @param options The User-Agent, the API's base URL and version, and the limits.\n * @returns A promise that resolves once GitHub has revoked it.\n * @example\n * import { revokeInstallationToken } from 'jg-github';\n *\n * declare const token: string;\n *\n * await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n * - GITHUB_TOKEN_REVOKE_FAILED: The installation token couldn't be revoked.\n */\nexport const revokeInstallationToken = async (\n  token: string,\n  {\n    userAgent,\n    apiOrigin,\n    apiVersion,\n    timeoutSeconds = DEFAULT_GITHUB_TIMEOUT_SECONDS,\n    signal,\n  }: IGithubRequestOptions,\n): Promise<void> => {\n  const headers = createGithubHeaders(token, { userAgent, apiVersion });\n  const { error, meta } = await request(\n    buildGithubApiUrl(['installation', 'token'], {}, { apiOrigin }),\n    {\n      method: 'DELETE',\n      headers,\n      parseAs: 'none',\n      retryDelaysSeconds: [],\n      timeoutSeconds,\n      init: { redirect: 'error' },\n      ...(signal === undefined ? {} : { signal }),\n    },\n  );\n  if (error !== null) {\n    throw INVALID_ARGUMENT_KINDS.has(error.kind)\n      ? fromFetchError(error, [token])\n      : revokeFailed(error.kind, error.status, [token]);\n  }\n  if (meta.status !== 204) {\n    throw revokeFailed('UNEXPECTED_STATUS', meta.status, [token]);\n  }\n};\n\n/**\n * Revokes a token jg-github received but won't hand over, with its own timeout and without the\n * caller's signal, so a cancelled call still revokes it.\n * @param token The token.\n * @param options The request's options.\n * @returns A promise that resolves to whether GitHub revoked it.\n */\nconst revokeUnusedToken = async (\n  token: string,\n  { userAgent, apiOrigin, apiVersion, timeoutSeconds }: IGithubRequestOptions,\n): Promise<boolean> => {\n  try {\n    await revokeInstallationToken(token, { userAgent, apiOrigin, apiVersion, timeoutSeconds });\n    return true;\n  } catch {\n    return false;\n  }\n};\n\n/**\n * Creates an installation token for exactly the repositories and the permissions asked for, with\n * `POST /app/installations/{id}/access_tokens`, authenticated as the App. `permissions` is\n * required, because GitHub grants every permission of the installation without it, and the\n * repositories are named by name or by ID, never both. The granted token must reach exactly\n * those repositories, only the selected ones, with exactly those permissions, plus\n * `metadata: 'read'`, and must not have expired; otherwise it's revoked before the error is\n * thrown, and the error's data says whether that worked. Nothing is retried, and no error holds\n * the token or the App's JWT.\n * @param options The App, the installation, the scope, and the request's limits.\n * @returns A promise that resolves to the token, when it expires, and what it reaches.\n * @example\n * import { createInstallationToken, revokeInstallationToken } from 'jg-github';\n *\n * declare const privateKey: string;\n *\n * const { token } = await createInstallationToken({\n *   appId: 123456,\n *   privateKey,\n *   installationId: 12345678,\n *   repositories: ['app'],\n *   permissions: { contents: 'read' },\n *   userAgent: 'acme-deploy-bot',\n * });\n * try {\n *   // read the repository's contents with the token\n * } finally {\n *   await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });\n * }\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n * - GITHUB_PRIVATE_KEY_INVALID: The GitHub App's private key isn't an unencrypted RSA private key.\n * - GITHUB_REQUEST_FAILED: The GitHub request failed.\n * - GITHUB_RESPONSE_INVALID: GitHub's response isn't in the expected format.\n * - GITHUB_TOKEN_SCOPE_MISMATCH: The installation token's scope isn't the one requested.\n * - GITHUB_TOKEN_EXPIRED: The installation token had already expired.\n */\nexport const createInstallationToken = async (\n  options: ICreateInstallationTokenOptions,\n): Promise<IInstallationToken> => {\n  const {\n    appId,\n    privateKey,\n    installationId,\n    permissions,\n    repositories,\n    repositoryIds,\n    userAgent,\n    apiOrigin,\n    apiVersion,\n    timeoutSeconds = DEFAULT_GITHUB_TIMEOUT_SECONDS,\n    maxResponseBytes = DEFAULT_GITHUB_MAX_RESPONSE_BYTES,\n    signal,\n  } = options;\n  const id = readInstallationId(installationId);\n  const requestedPermissions = readPermissions(permissions);\n  const requested = readRequestedRepositories(repositories, repositoryIds);\n  const url = buildGithubApiUrl(['app', 'installations', id, 'access_tokens'], {}, { apiOrigin });\n  const jwt = createGithubAppJwt({ appId, privateKey });\n  const { data, error, meta } = await request(url, {\n    method: 'POST',\n    headers: createGithubHeaders(jwt, { userAgent, apiVersion }),\n    body: {\n      permissions: requestedPermissions,\n      ...(requested.kind === 'names'\n        ? { repositories: requested.values }\n        : { repository_ids: requested.values }),\n    },\n    parseAs: 'json',\n    retryDelaysSeconds: [],\n    timeoutSeconds,\n    maxResponseBytes,\n    init: { redirect: 'error' },\n    ...(signal === undefined ? {} : { signal }),\n  });\n  if (error !== null) {\n    throw fromFetchError(error, [jwt]);\n  }\n  const token = readToken(data);\n  if (token === undefined) {\n    throw responseInvalid([jwt]);\n  }\n\n  // from here on GitHub granted a token, which is revoked before any error is thrown\n  const redact = [jwt, token];\n  const revokeOptions = { userAgent, apiOrigin, apiVersion, timeoutSeconds };\n  const details = meta.status === 201 ? readTokenDetails(data) : undefined;\n  if (details === undefined) {\n    throw responseInvalid(redact, await revokeUnusedToken(token, revokeOptions));\n  }\n  const mismatch = findScopeMismatch(details, requested, requestedPermissions);\n  if (mismatch !== null) {\n    throw scopeMismatch(mismatch, await revokeUnusedToken(token, revokeOptions), redact);\n  }\n  if (details.expiresAt.getTime() <= Date.now()) {\n    throw tokenExpired(await revokeUnusedToken(token, revokeOptions), redact);\n  }\n  return {\n    token,\n    expiresAt: details.expiresAt,\n    permissions: details.permissions,\n    repositories: details.repositories.map(({ id: repositoryId, fullName }) => ({\n      id: repositoryId,\n      fullName,\n    })),\n  };\n};\n"]}

package/dist/installation-token/types.d.ts

@@ -0,0 +1,33 @@
+export type IGithubPermissionLevel = 'read' | 'write' | 'admin';
+export type IGithubPermissions = Record<string, IGithubPermissionLevel>;
+export type IGithubRepository = {
+    id: number;
+    fullName: string;
+};
+export type IGithubRequestOptions = {
+    userAgent: string;
+    apiOrigin?: string | undefined;
+    apiVersion?: string | undefined;
+    timeoutSeconds?: number | undefined;
+    signal?: AbortSignal | undefined;
+};
+export type IInstallationTokenRepositories = {
+    repositories: readonly string[];
+    repositoryIds?: undefined;
+} | {
+    repositoryIds: readonly number[];
+    repositories?: undefined;
+};
+export type ICreateInstallationTokenOptions = IGithubRequestOptions & IInstallationTokenRepositories & {
+    appId: string | number;
+    privateKey: string;
+    installationId: string | number;
+    permissions: IGithubPermissions;
+    maxResponseBytes?: number | undefined;
+};
+export type IInstallationToken = {
+    token: string;
+    expiresAt: Date;
+    permissions: Record<string, string>;
+    repositories: IGithubRepository[];
+};

package/dist/installation-token/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/installation-token/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/installation-token/types.ts"],"names":[],"mappings":"","sourcesContent":["// the access a GitHub App permission grants\nexport type IGithubPermissionLevel = 'read' | 'write' | 'admin';\n\n// the permissions of an installation token, by GitHub's names, such as { contents: 'read' }\nexport type IGithubPermissions = Record<string, IGithubPermissionLevel>;\n\n// a repository an installation token can reach\nexport type IGithubRepository = {\n  // the repository's ID\n  id: number;\n\n  // the repository's owner and name, such as 'acme/app'\n  fullName: string;\n};\n\n// what every request to GitHub's REST API takes\nexport type IGithubRequestOptions = {\n  // the User-Agent GitHub requires on every request, such as the app's name\n  userAgent: string;\n\n  // the API's base URL, such as `https://ghe.example.com/api/v3` for GitHub Enterprise Server.\n  // Defaults to GITHUB_API_ORIGIN\n  apiOrigin?: string | undefined;\n\n  // the REST API version. Defaults to GITHUB_API_VERSION\n  apiVersion?: string | undefined;\n\n  // the seconds the request may take. Defaults to 10\n  timeoutSeconds?: number | undefined;\n\n  // stops the request when it aborts\n  signal?: AbortSignal | undefined;\n};\n\n// the repositories an installation token is for: by name or by ID, never both\nexport type IInstallationTokenRepositories =\n  | {\n      // the repositories' names, without the owner, such as ['app', 'docs']\n      repositories: readonly string[];\n      repositoryIds?: undefined;\n    }\n  | {\n      // the repositories' IDs\n      repositoryIds: readonly number[];\n      repositories?: undefined;\n    };\n\n// what createInstallationToken takes\nexport type ICreateInstallationTokenOptions = IGithubRequestOptions &\n  IInstallationTokenRepositories & {\n    // the App's ID, such as 123456, or its client ID\n    appId: string | number;\n\n    // the App's private key, PEM-encoded\n    privateKey: string;\n\n    // the installation's ID, such as 12345678\n    installationId: string | number;\n\n    // the permissions the token needs, at least one; GitHub would grant every permission of the\n    // installation without them\n    permissions: IGithubPermissions;\n\n    // the bytes GitHub's answer may take. Defaults to 128 KiB\n    maxResponseBytes?: number | undefined;\n  };\n\n// an installation token, scoped as requested\nexport type IInstallationToken = {\n  // the token, sent as a bearer credential\n  token: string;\n\n  // when it expires, an hour after it was created\n  expiresAt: Date;\n\n  // the permissions it grants: the ones requested, and `metadata: 'read'` when GitHub adds it\n  permissions: Record<string, string>;\n\n  // the repositories it reaches, exactly the ones requested\n  repositories: IGithubRepository[];\n};\n"]}

package/dist/installation-token/utilities.d.ts

@@ -0,0 +1,36 @@
+import type { IGithubPermissions, IGithubRepository } from './types.js';
+import type { IRequestedRepositories } from './validations.js';
+export type IGrantedRepository = IGithubRepository & {
+    name: string;
+};
+export type ITokenDetails = {
+    expiresAt: Date;
+    permissions: Record<string, string>;
+    repositorySelection: string;
+    repositories: IGrantedRepository[];
+};
+export type IScopeMismatch = 'repository_selection' | 'repositories' | 'permissions';
+/**
+ * Reads the token from GitHub's answer to a token request.
+ * @param data The answer, parsed from JSON.
+ * @returns The token, or undefined when there's none.
+ */
+export declare const readToken: (data: unknown) => string | undefined;
+/**
+ * Reads the rest of GitHub's answer to a token request: when it expires, its permissions, and
+ * the repositories it reaches, which an answer for every repository leaves out.
+ * @param data The answer, parsed from JSON.
+ * @returns The details, or undefined when the answer isn't valid.
+ */
+export declare const readTokenDetails: (data: unknown) => ITokenDetails | undefined;
+/**
+ * Compares a granted token's scope with the request: it must reach only the selected
+ * repositories, exactly the requested ones, by name ignoring case or by ID, as they were
+ * requested, and grant exactly the requested permissions, plus `metadata: 'read'` when GitHub
+ * adds it.
+ * @param details The granted token's details.
+ * @param requested The requested repositories.
+ * @param permissions The requested permissions.
+ * @returns What differs, or null when nothing does.
+ */
+export declare const findScopeMismatch: (details: ITokenDetails, requested: IRequestedRepositories, permissions: IGithubPermissions) => IScopeMismatch | null;

package/dist/installation-token/utilities.js

@@ -0,0 +1,93 @@
+import { isHeaderValue, isRecord } from '../shared/index.js';
+import { IMPLICIT_PERMISSION } from './constants.js';
+/**
+ * Reads the token from GitHub's answer to a token request.
+ * @param data The answer, parsed from JSON.
+ * @returns The token, or undefined when there's none.
+ */
+export const readToken = (data) => isRecord(data) && isHeaderValue(data['token']) && !data['token'].includes(' ')
+    ? data['token']
+    : undefined;
+/**
+ * Reads a granted repository.
+ * @param value The repository, parsed from JSON.
+ * @returns The repository, or undefined when it isn't one.
+ */
+const readRepository = (value) => isRecord(value) &&
+    Number.isSafeInteger(value['id']) &&
+    value['id'] > 0 &&
+    typeof value['name'] === 'string' &&
+    typeof value['full_name'] === 'string'
+    ? { id: value['id'], name: value['name'], fullName: value['full_name'] }
+    : undefined;
+/**
+ * Reads the rest of GitHub's answer to a token request: when it expires, its permissions, and
+ * the repositories it reaches, which an answer for every repository leaves out.
+ * @param data The answer, parsed from JSON.
+ * @returns The details, or undefined when the answer isn't valid.
+ */
+export const readTokenDetails = (data) => {
+    if (!isRecord(data) || typeof data['expires_at'] !== 'string') {
+        return undefined;
+    }
+    const expiresAt = new Date(data['expires_at']);
+    const permissions = data['permissions'];
+    const repositorySelection = data['repository_selection'];
+    const rawRepositories = data['repositories'] ?? [];
+    if (Number.isNaN(expiresAt.getTime()) ||
+        !isRecord(permissions) ||
+        !Object.values(permissions).every((level) => typeof level === 'string') ||
+        typeof repositorySelection !== 'string' ||
+        !Array.isArray(rawRepositories)) {
+        return undefined;
+    }
+    const repositories = rawRepositories.map(readRepository);
+    if (repositories.includes(undefined)) {
+        return undefined;
+    }
+    return {
+        expiresAt,
+        permissions: permissions,
+        repositorySelection,
+        repositories: repositories,
+    };
+};
+/**
+ * Checks whether two lists hold the same values, each once.
+ * @param granted The granted values.
+ * @param requested The requested values, without repeats.
+ * @returns Whether they're the same set.
+ */
+const isSameSet = (granted, requested) => {
+    const grantedSet = new Set(granted);
+    return (grantedSet.size === granted.length &&
+        grantedSet.size === requested.length &&
+        requested.every((value) => grantedSet.has(value)));
+};
+/**
+ * Compares a granted token's scope with the request: it must reach only the selected
+ * repositories, exactly the requested ones, by name ignoring case or by ID, as they were
+ * requested, and grant exactly the requested permissions, plus `metadata: 'read'` when GitHub
+ * adds it.
+ * @param details The granted token's details.
+ * @param requested The requested repositories.
+ * @param permissions The requested permissions.
+ * @returns What differs, or null when nothing does.
+ */
+export const findScopeMismatch = (details, requested, permissions) => {
+    if (details.repositorySelection !== 'selected') {
+        return 'repository_selection';
+    }
+    const isSameRepositories = requested.kind === 'names'
+        ? isSameSet(details.repositories.map(({ name }) => name.toLowerCase()), requested.values.map((name) => name.toLowerCase()))
+        : isSameSet(details.repositories.map(({ id }) => id), requested.values);
+    if (!isSameRepositories) {
+        return 'repositories';
+    }
+    const granted = Object.entries(details.permissions);
+    const isSamePermissions = Object.entries(permissions).every(([name, level]) => Object.hasOwn(details.permissions, name) && details.permissions[name] === level) &&
+        granted.every(([name, level]) => Object.hasOwn(permissions, name) ||
+            (name === IMPLICIT_PERMISSION.name && level === IMPLICIT_PERMISSION.level));
+    return isSamePermissions ? null : 'permissions';
+};
+//# sourceMappingURL=utilities.js.map

package/dist/installation-token/utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../src/installation-token/utilities.ts"],"names":[],"mappings":"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","sourcesContent":["import { isHeaderValue, isRecord } from '../shared/index.js';\nimport { IMPLICIT_PERMISSION } from './constants.js';\nimport type { IGithubPermissions, IGithubRepository } from './types.js';\nimport type { IRequestedRepositories } from './validations.js';\n\n// a granted repository, as GitHub describes it\nexport type IGrantedRepository = IGithubRepository & {\n  // the repository's name, without its owner\n  name: string;\n};\n\n// what GitHub's answer to a token request says, once read\nexport type ITokenDetails = {\n  expiresAt: Date;\n  permissions: Record<string, string>;\n  repositorySelection: string;\n  repositories: IGrantedRepository[];\n};\n\n// what in a granted token differs from the request\nexport type IScopeMismatch = 'repository_selection' | 'repositories' | 'permissions';\n\n/**\n * Reads the token from GitHub's answer to a token request.\n * @param data The answer, parsed from JSON.\n * @returns The token, or undefined when there's none.\n */\nexport const readToken = (data: unknown): string | undefined =>\n  isRecord(data) && isHeaderValue(data['token']) && !data['token'].includes(' ')\n    ? data['token']\n    : undefined;\n\n/**\n * Reads a granted repository.\n * @param value The repository, parsed from JSON.\n * @returns The repository, or undefined when it isn't one.\n */\nconst readRepository = (value: unknown): IGrantedRepository | undefined =>\n  isRecord(value) &&\n  Number.isSafeInteger(value['id']) &&\n  (value['id'] as number) > 0 &&\n  typeof value['name'] === 'string' &&\n  typeof value['full_name'] === 'string'\n    ? { id: value['id'] as number, name: value['name'], fullName: value['full_name'] }\n    : undefined;\n\n/**\n * Reads the rest of GitHub's answer to a token request: when it expires, its permissions, and\n * the repositories it reaches, which an answer for every repository leaves out.\n * @param data The answer, parsed from JSON.\n * @returns The details, or undefined when the answer isn't valid.\n */\nexport const readTokenDetails = (data: unknown): ITokenDetails | undefined => {\n  if (!isRecord(data) || typeof data['expires_at'] !== 'string') {\n    return undefined;\n  }\n  const expiresAt = new Date(data['expires_at']);\n  const permissions = data['permissions'];\n  const repositorySelection = data['repository_selection'];\n  const rawRepositories = data['repositories'] ?? [];\n  if (\n    Number.isNaN(expiresAt.getTime()) ||\n    !isRecord(permissions) ||\n    !Object.values(permissions).every((level) => typeof level === 'string') ||\n    typeof repositorySelection !== 'string' ||\n    !Array.isArray(rawRepositories)\n  ) {\n    return undefined;\n  }\n  const repositories = rawRepositories.map(readRepository);\n  if (repositories.includes(undefined)) {\n    return undefined;\n  }\n  return {\n    expiresAt,\n    permissions: permissions as Record<string, string>,\n    repositorySelection,\n    repositories: repositories as IGrantedRepository[],\n  };\n};\n\n/**\n * Checks whether two lists hold the same values, each once.\n * @param granted The granted values.\n * @param requested The requested values, without repeats.\n * @returns Whether they're the same set.\n */\nconst isSameSet = <T>(granted: readonly T[], requested: readonly T[]): boolean => {\n  const grantedSet = new Set(granted);\n  return (\n    grantedSet.size === granted.length &&\n    grantedSet.size === requested.length &&\n    requested.every((value) => grantedSet.has(value))\n  );\n};\n\n/**\n * Compares a granted token's scope with the request: it must reach only the selected\n * repositories, exactly the requested ones, by name ignoring case or by ID, as they were\n * requested, and grant exactly the requested permissions, plus `metadata: 'read'` when GitHub\n * adds it.\n * @param details The granted token's details.\n * @param requested The requested repositories.\n * @param permissions The requested permissions.\n * @returns What differs, or null when nothing does.\n */\nexport const findScopeMismatch = (\n  details: ITokenDetails,\n  requested: IRequestedRepositories,\n  permissions: IGithubPermissions,\n): IScopeMismatch | null => {\n  if (details.repositorySelection !== 'selected') {\n    return 'repository_selection';\n  }\n  const isSameRepositories =\n    requested.kind === 'names'\n      ? isSameSet(\n          details.repositories.map(({ name }) => name.toLowerCase()),\n          requested.values.map((name) => name.toLowerCase()),\n        )\n      : isSameSet(\n          details.repositories.map(({ id }) => id),\n          requested.values,\n        );\n  if (!isSameRepositories) {\n    return 'repositories';\n  }\n  const granted = Object.entries(details.permissions);\n  const isSamePermissions =\n    Object.entries(permissions).every(\n      ([name, level]) =>\n        Object.hasOwn(details.permissions, name) && details.permissions[name] === level,\n    ) &&\n    granted.every(\n      ([name, level]) =>\n        Object.hasOwn(permissions, name) ||\n        (name === IMPLICIT_PERMISSION.name && level === IMPLICIT_PERMISSION.level),\n    );\n  return isSamePermissions ? null : 'permissions';\n};\n"]}

package/dist/installation-token/validations.d.ts

@@ -0,0 +1,35 @@
+import type { IGithubPermissions } from './types.js';
+export type IRequestedRepositories = {
+    kind: 'names';
+    values: string[];
+} | {
+    kind: 'ids';
+    values: number[];
+};
+/**
+ * Reads an installation's ID as the string the URL takes.
+ * @param installationId The ID.
+ * @returns The ID.
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export declare const readInstallationId: (installationId: unknown) => string;
+/**
+ * Checks the permissions a token is requested with: at least one, each a known level, because
+ * GitHub reads no permissions as every permission of the installation.
+ * @param permissions The permissions.
+ * @returns The permissions.
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export declare const readPermissions: (permissions: unknown) => IGithubPermissions;
+/**
+ * Checks the repositories a token is requested for: by name or by ID, exactly one of them, with
+ * at least one repository and no repeats; names are compared ignoring case, as GitHub does.
+ * @param repositories The names, or undefined.
+ * @param repositoryIds The IDs, or undefined.
+ * @returns The repositories.
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export declare const readRequestedRepositories: (repositories: unknown, repositoryIds: unknown) => IRequestedRepositories;

package/dist/installation-token/validations.js

@@ -0,0 +1,74 @@
+import { invalidArgument, isRecord } from '../shared/index.js';
+import { INSTALLATION_ID_PATTERN, PERMISSION_LEVELS, PERMISSION_NAME_PATTERN, REPOSITORY_NAME_PATTERN, } from './constants.js';
+/**
+ * Reads an installation's ID as the string the URL takes.
+ * @param installationId The ID.
+ * @returns The ID.
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export const readInstallationId = (installationId) => {
+    const value = typeof installationId === 'number' && Number.isSafeInteger(installationId)
+        ? String(installationId)
+        : installationId;
+    if (typeof value !== 'string' || !INSTALLATION_ID_PATTERN.test(value)) {
+        throw invalidArgument('installationId');
+    }
+    return value;
+};
+/**
+ * Checks the permissions a token is requested with: at least one, each a known level, because
+ * GitHub reads no permissions as every permission of the installation.
+ * @param permissions The permissions.
+ * @returns The permissions.
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export const readPermissions = (permissions) => {
+    if (!isRecord(permissions) ||
+        Object.keys(permissions).length === 0 ||
+        !Object.entries(permissions).every(([name, level]) => PERMISSION_NAME_PATTERN.test(name) &&
+            PERMISSION_LEVELS.has(level))) {
+        throw invalidArgument('permissions');
+    }
+    return { ...permissions };
+};
+/**
+ * Checks that a list has at least one item, each valid, and no two the same once normalized.
+ * @param values The list.
+ * @param isValid Whether an item is valid.
+ * @param normalize What two items are compared by.
+ * @returns Whether the list is valid.
+ */
+const isUniqueList = (values, isValid, normalize) => Array.isArray(values) &&
+    values.length > 0 &&
+    values.every(isValid) &&
+    new Set(values.map(normalize)).size === values.length;
+/**
+ * Checks the repositories a token is requested for: by name or by ID, exactly one of them, with
+ * at least one repository and no repeats; names are compared ignoring case, as GitHub does.
+ * @param repositories The names, or undefined.
+ * @param repositoryIds The IDs, or undefined.
+ * @returns The repositories.
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export const readRequestedRepositories = (repositories, repositoryIds) => {
+    if ((repositories === undefined) === (repositoryIds === undefined)) {
+        throw invalidArgument('repositories');
+    }
+    if (repositories !== undefined) {
+        if (!isUniqueList(repositories, (name) => typeof name === 'string' &&
+            REPOSITORY_NAME_PATTERN.test(name) &&
+            name !== '.' &&
+            name !== '..', (name) => name.toLowerCase())) {
+            throw invalidArgument('repositories');
+        }
+        return { kind: 'names', values: [...repositories] };
+    }
+    if (!isUniqueList(repositoryIds, (id) => Number.isSafeInteger(id) && id > 0, (id) => id)) {
+        throw invalidArgument('repositoryIds');
+    }
+    return { kind: 'ids', values: [...repositoryIds] };
+};
+//# sourceMappingURL=validations.js.map

package/dist/installation-token/validations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validations.js","sourceRoot":"","sources":["../../src/installation-token/validations.ts"],"names":[],"mappings":"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","sourcesContent":["import { invalidArgument, isRecord } from '../shared/index.js';\nimport {\n  INSTALLATION_ID_PATTERN,\n  PERMISSION_LEVELS,\n  PERMISSION_NAME_PATTERN,\n  REPOSITORY_NAME_PATTERN,\n} from './constants.js';\nimport type { IGithubPermissionLevel, IGithubPermissions } from './types.js';\n\n// the repositories a token is requested for, checked\nexport type IRequestedRepositories =\n  { kind: 'names'; values: string[] } | { kind: 'ids'; values: number[] };\n\n/**\n * Reads an installation's ID as the string the URL takes.\n * @param installationId The ID.\n * @returns The ID.\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nexport const readInstallationId = (installationId: unknown): string => {\n  const value =\n    typeof installationId === 'number' && Number.isSafeInteger(installationId)\n      ? String(installationId)\n      : installationId;\n  if (typeof value !== 'string' || !INSTALLATION_ID_PATTERN.test(value)) {\n    throw invalidArgument('installationId');\n  }\n  return value;\n};\n\n/**\n * Checks the permissions a token is requested with: at least one, each a known level, because\n * GitHub reads no permissions as every permission of the installation.\n * @param permissions The permissions.\n * @returns The permissions.\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nexport const readPermissions = (permissions: unknown): IGithubPermissions => {\n  if (\n    !isRecord(permissions) ||\n    Object.keys(permissions).length === 0 ||\n    !Object.entries(permissions).every(\n      ([name, level]) =>\n        PERMISSION_NAME_PATTERN.test(name) &&\n        PERMISSION_LEVELS.has(level as IGithubPermissionLevel),\n    )\n  ) {\n    throw invalidArgument('permissions');\n  }\n  return { ...(permissions as IGithubPermissions) };\n};\n\n/**\n * Checks that a list has at least one item, each valid, and no two the same once normalized.\n * @param values The list.\n * @param isValid Whether an item is valid.\n * @param normalize What two items are compared by.\n * @returns Whether the list is valid.\n */\nconst isUniqueList = (\n  values: unknown,\n  isValid: (value: unknown) => boolean,\n  normalize: (value: unknown) => unknown,\n): boolean =>\n  Array.isArray(values) &&\n  values.length > 0 &&\n  values.every(isValid) &&\n  new Set(values.map(normalize)).size === values.length;\n\n/**\n * Checks the repositories a token is requested for: by name or by ID, exactly one of them, with\n * at least one repository and no repeats; names are compared ignoring case, as GitHub does.\n * @param repositories The names, or undefined.\n * @param repositoryIds The IDs, or undefined.\n * @returns The repositories.\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nexport const readRequestedRepositories = (\n  repositories: unknown,\n  repositoryIds: unknown,\n): IRequestedRepositories => {\n  if ((repositories === undefined) === (repositoryIds === undefined)) {\n    throw invalidArgument('repositories');\n  }\n  if (repositories !== undefined) {\n    if (\n      !isUniqueList(\n        repositories,\n        (name) =>\n          typeof name === 'string' &&\n          REPOSITORY_NAME_PATTERN.test(name) &&\n          name !== '.' &&\n          name !== '..',\n        (name) => (name as string).toLowerCase(),\n      )\n    ) {\n      throw invalidArgument('repositories');\n    }\n    return { kind: 'names', values: [...(repositories as string[])] };\n  }\n  if (\n    !isUniqueList(\n      repositoryIds,\n      (id) => Number.isSafeInteger(id) && (id as number) > 0,\n      (id) => id,\n    )\n  ) {\n    throw invalidArgument('repositoryIds');\n  }\n  return { kind: 'ids', values: [...(repositoryIds as number[])] };\n};\n"]}

package/dist/rate-limit/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const FALLBACK_RETRY_MS = 60000;
+export declare const IMF_FIXDATE_PATTERN: RegExp;

package/dist/rate-limit/constants.js

@@ -0,0 +1,5 @@
+// the wait before the first retry when GitHub doesn't say how long, doubled for each later one
+export const FALLBACK_RETRY_MS = 60_000;
+// a Retry-After date, in the strict IMF-fixdate form, such as 'Wed, 21 Oct 2026 07:28:00 GMT'
+export const IMF_FIXDATE_PATTERN = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+//# sourceMappingURL=constants.js.map

package/dist/rate-limit/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/rate-limit/constants.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAExC,8FAA8F;AAC9F,MAAM,CAAC,MAAM,mBAAmB,GAC9B,kEAAkE,CAAC","sourcesContent":["// the wait before the first retry when GitHub doesn't say how long, doubled for each later one\nexport const FALLBACK_RETRY_MS = 60_000;\n\n// a Retry-After date, in the strict IMF-fixdate form, such as 'Wed, 21 Oct 2026 07:28:00 GMT'\nexport const IMF_FIXDATE_PATTERN =\n  /^[A-Z][a-z]{2}, \\d{2} [A-Z][a-z]{2} \\d{4} \\d{2}:\\d{2}:\\d{2} GMT$/;\n"]}

package/dist/rate-limit/index.d.ts

@@ -0,0 +1,2 @@
+export type { IGithubRateLimitDeadlineOptions, IGithubResponseHeaders } from './types.js';
+export { getGithubRateLimitDeadline } from './rate-limit.js';

package/dist/rate-limit/index.js

@@ -0,0 +1,3 @@
+// rate limits
+export { getGithubRateLimitDeadline } from './rate-limit.js';
+//# sourceMappingURL=index.js.map

package/dist/rate-limit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rate-limit/index.ts"],"names":[],"mappings":"AAGA,cAAc;AACd,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC","sourcesContent":["// types\nexport type { IGithubRateLimitDeadlineOptions, IGithubResponseHeaders } from './types.js';\n\n// rate limits\nexport { getGithubRateLimitDeadline } from './rate-limit.js';\n"]}

package/dist/rate-limit/rate-limit.d.ts

@@ -0,0 +1,24 @@
+import type { IGithubRateLimitDeadlineOptions } from './types.js';
+/**
+ * Gives the time to retry a GitHub request at after a rate limit, or null when the response isn't
+ * rate limited. A 429 is, and so is a 403 with Retry-After, with no requests remaining, or with a
+ * rate-limit message, and a success that used the last remaining request. The deadline is the
+ * latest of Retry-After, as whole seconds or a strict IMF-fixdate, and `x-ratelimit-reset` when no
+ * requests remain, counting only future times; without one, it's a minute from now, doubled for
+ * each retry already made.
+ * @param options The response's status and headers, the retries made, and the time.
+ * @returns The time to retry at, or null.
+ * @example
+ * import { getGithubRateLimitDeadline } from 'jg-github';
+ *
+ * declare const response: Response;
+ *
+ * const deadline = getGithubRateLimitDeadline({
+ *   status: response.status,
+ *   headers: response.headers,
+ *   retryCount: 0,
+ * });
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export declare const getGithubRateLimitDeadline: ({ status, headers, retryCount, hasRateLimitMessage, now, }: IGithubRateLimitDeadlineOptions) => Date | null;