jg-github 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,88 @@
+import { invalidArgument } from '../shared/index.js';
+import { FALLBACK_RETRY_MS, IMF_FIXDATE_PATTERN } from './constants.js';
+/**
+ * Reads one header, by its lowercase name, as a single string.
+ * @param headers The headers.
+ * @param name The header's lowercase name.
+ * @returns Its value, or null when it's missing or repeated.
+ */
+const readHeader = (headers, name) => {
+    const value = headers instanceof Headers ? headers.get(name) : headers[name];
+    return typeof value === 'string' ? value : null;
+};
+/**
+ * Reads Retry-After as a deadline: whole seconds from now, or a strict IMF-fixdate.
+ * @param retryAfter The header's value.
+ * @param now The current time, in milliseconds.
+ * @returns The deadline in milliseconds, or NaN when the value isn't one.
+ */
+const readRetryAfter = (retryAfter, now) => {
+    const seconds = /^\d+$/.test(retryAfter) ? Number(retryAfter) : NaN;
+    if (Number.isSafeInteger(seconds)) {
+        return now + seconds * 1000;
+    }
+    return IMF_FIXDATE_PATTERN.test(retryAfter) ? Date.parse(retryAfter) : NaN;
+};
+/**
+ * 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 const getGithubRateLimitDeadline = ({ status, headers, retryCount, hasRateLimitMessage = false, now = new Date(), }) => {
+    if (!Number.isSafeInteger(status) || status < 100 || status > 599) {
+        throw invalidArgument('status');
+    }
+    if (!(headers instanceof Headers) && (typeof headers !== 'object' || headers === null)) {
+        throw invalidArgument('headers');
+    }
+    if (!Number.isSafeInteger(retryCount) || retryCount < 0) {
+        throw invalidArgument('retryCount');
+    }
+    if (!(now instanceof Date) || Number.isNaN(now.getTime())) {
+        throw invalidArgument('now');
+    }
+    const nowMs = now.getTime();
+    const retryAfter = readHeader(headers, 'retry-after');
+    const remaining = readHeader(headers, 'x-ratelimit-remaining');
+    const reset = readHeader(headers, 'x-ratelimit-reset');
+    // the last successful request can use up the primary limit before GitHub answers with an error
+    const hasExhaustedSuccess = status >= 200 && status < 300 && remaining === '0';
+    if (status !== 403 && status !== 429 && !hasExhaustedSuccess) {
+        return null;
+    }
+    if (status === 403 && retryAfter === null && remaining !== '0' && !hasRateLimitMessage) {
+        return null;
+    }
+    const deadlines = [];
+    if (retryAfter !== null) {
+        const deadline = readRetryAfter(retryAfter, nowMs);
+        if (Number.isSafeInteger(deadline) && deadline > nowMs) {
+            deadlines.push(deadline);
+        }
+    }
+    if (remaining === '0' && reset !== null && /^\d+$/.test(reset)) {
+        const deadline = Number(reset) * 1000;
+        if (Number.isSafeInteger(deadline) && deadline > nowMs) {
+            deadlines.push(deadline);
+        }
+    }
+    return new Date(deadlines.length === 0 ? nowMs + FALLBACK_RETRY_MS * 2 ** retryCount : Math.max(...deadlines));
+};
+//# sourceMappingURL=rate-limit.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/rate-limit/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGxE;;;;;GAKG;AACH,MAAM,UAAU,GAAG,CAAC,OAA+B,EAAE,IAAY,EAAiB,EAAE;IAClF,MAAM,KAAK,GAAG,OAAO,YAAY,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,cAAc,GAAG,CAAC,UAAkB,EAAE,GAAW,EAAU,EAAE;IACjE,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACpE,IAAI,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO,GAAG,GAAG,OAAO,GAAG,IAAI,CAAC;IAC9B,CAAC;IACD,OAAO,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC7E,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,EACzC,MAAM,EACN,OAAO,EACP,UAAU,EACV,mBAAmB,GAAG,KAAK,EAC3B,GAAG,GAAG,IAAI,IAAI,EAAE,GACgB,EAAe,EAAE;IACjD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;QAClE,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,CAAC,OAAO,YAAY,OAAO,CAAC,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QACvF,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,eAAe,CAAC,YAAY,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,CAAC,CAAC,GAAG,YAAY,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC1D,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;IAC5B,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,EAAE,uBAAuB,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IAEvD,+FAA+F;IAC/F,MAAM,mBAAmB,GAAG,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,IAAI,SAAS,KAAK,GAAG,CAAC;IAC/E,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,MAAM,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI,IAAI,SAAS,KAAK,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;QACvF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,QAAQ,GAAG,cAAc,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACnD,IAAI,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,KAAK,EAAE,CAAC;YACvD,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,IAAI,SAAS,KAAK,GAAG,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;QACtC,IAAI,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,KAAK,EAAE,CAAC;YACvD,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,IAAI,CACb,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,iBAAiB,GAAG,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAC9F,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { invalidArgument } from '../shared/index.js';\nimport { FALLBACK_RETRY_MS, IMF_FIXDATE_PATTERN } from './constants.js';\nimport type { IGithubRateLimitDeadlineOptions, IGithubResponseHeaders } from './types.js';\n\n/**\n * Reads one header, by its lowercase name, as a single string.\n * @param headers The headers.\n * @param name The header's lowercase name.\n * @returns Its value, or null when it's missing or repeated.\n */\nconst readHeader = (headers: IGithubResponseHeaders, name: string): string | null => {\n  const value = headers instanceof Headers ? headers.get(name) : headers[name];\n  return typeof value === 'string' ? value : null;\n};\n\n/**\n * Reads Retry-After as a deadline: whole seconds from now, or a strict IMF-fixdate.\n * @param retryAfter The header's value.\n * @param now The current time, in milliseconds.\n * @returns The deadline in milliseconds, or NaN when the value isn't one.\n */\nconst readRetryAfter = (retryAfter: string, now: number): number => {\n  const seconds = /^\\d+$/.test(retryAfter) ? Number(retryAfter) : NaN;\n  if (Number.isSafeInteger(seconds)) {\n    return now + seconds * 1000;\n  }\n  return IMF_FIXDATE_PATTERN.test(retryAfter) ? Date.parse(retryAfter) : NaN;\n};\n\n/**\n * Gives the time to retry a GitHub request at after a rate limit, or null when the response isn't\n * rate limited. A 429 is, and so is a 403 with Retry-After, with no requests remaining, or with a\n * rate-limit message, and a success that used the last remaining request. The deadline is the\n * latest of Retry-After, as whole seconds or a strict IMF-fixdate, and `x-ratelimit-reset` when no\n * requests remain, counting only future times; without one, it's a minute from now, doubled for\n * each retry already made.\n * @param options The response's status and headers, the retries made, and the time.\n * @returns The time to retry at, or null.\n * @example\n * import { getGithubRateLimitDeadline } from 'jg-github';\n *\n * declare const response: Response;\n *\n * const deadline = getGithubRateLimitDeadline({\n *   status: response.status,\n *   headers: response.headers,\n *   retryCount: 0,\n * });\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nexport const getGithubRateLimitDeadline = ({\n  status,\n  headers,\n  retryCount,\n  hasRateLimitMessage = false,\n  now = new Date(),\n}: IGithubRateLimitDeadlineOptions): Date | null => {\n  if (!Number.isSafeInteger(status) || status < 100 || status > 599) {\n    throw invalidArgument('status');\n  }\n  if (!(headers instanceof Headers) && (typeof headers !== 'object' || headers === null)) {\n    throw invalidArgument('headers');\n  }\n  if (!Number.isSafeInteger(retryCount) || retryCount < 0) {\n    throw invalidArgument('retryCount');\n  }\n  if (!(now instanceof Date) || Number.isNaN(now.getTime())) {\n    throw invalidArgument('now');\n  }\n  const nowMs = now.getTime();\n  const retryAfter = readHeader(headers, 'retry-after');\n  const remaining = readHeader(headers, 'x-ratelimit-remaining');\n  const reset = readHeader(headers, 'x-ratelimit-reset');\n\n  // the last successful request can use up the primary limit before GitHub answers with an error\n  const hasExhaustedSuccess = status >= 200 && status < 300 && remaining === '0';\n  if (status !== 403 && status !== 429 && !hasExhaustedSuccess) {\n    return null;\n  }\n  if (status === 403 && retryAfter === null && remaining !== '0' && !hasRateLimitMessage) {\n    return null;\n  }\n\n  const deadlines: number[] = [];\n  if (retryAfter !== null) {\n    const deadline = readRetryAfter(retryAfter, nowMs);\n    if (Number.isSafeInteger(deadline) && deadline > nowMs) {\n      deadlines.push(deadline);\n    }\n  }\n  if (remaining === '0' && reset !== null && /^\\d+$/.test(reset)) {\n    const deadline = Number(reset) * 1000;\n    if (Number.isSafeInteger(deadline) && deadline > nowMs) {\n      deadlines.push(deadline);\n    }\n  }\n  return new Date(\n    deadlines.length === 0 ? nowMs + FALLBACK_RETRY_MS * 2 ** retryCount : Math.max(...deadlines),\n  );\n};\n"]}

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

@@ -0,0 +1,8 @@
+export type IGithubResponseHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+export type IGithubRateLimitDeadlineOptions = {
+    status: number;
+    headers: IGithubResponseHeaders;
+    retryCount: number;
+    hasRateLimitMessage?: boolean | undefined;
+    now?: Date | undefined;
+};

package/dist/rate-limit/types.js

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/rate-limit/types.ts"],"names":[],"mappings":"","sourcesContent":["// a response's headers: a Headers object, or a record with lowercase names, as Node.js's\n// IncomingHttpHeaders has\nexport type IGithubResponseHeaders =\n  Headers | Readonly<Record<string, string | readonly string[] | undefined>>;\n\n// what getGithubRateLimitDeadline takes\nexport type IGithubRateLimitDeadlineOptions = {\n  // the response's HTTP status\n  status: number;\n\n  // the response's headers\n  headers: IGithubResponseHeaders;\n\n  // the retries already made for this request, from 0, which doubles the fallback wait\n  retryCount: number;\n\n  // whether the response's message says a rate limit was hit, which makes a bare 403 count.\n  // Defaults to false\n  hasRateLimitMessage?: boolean | undefined;\n\n  // the current time. Defaults to now\n  now?: Date | undefined;\n};\n"]}

package/dist/shared/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const GITHUB_API_ORIGIN = "https://api.github.com";
+export declare const GITHUB_RAW_CONTENT_ORIGIN = "https://raw.githubusercontent.com";
+export declare const GITHUB_API_VERSION = "2026-03-10";
+export declare const GITHUB_MEDIA_TYPE = "application/vnd.github+json";
+export declare const DEFAULT_GITHUB_TIMEOUT_SECONDS = 10;
+export declare const DEFAULT_GITHUB_MAX_RESPONSE_BYTES = 131072;
+export declare const LOOPBACK_HOSTNAMES: ReadonlySet<string>;

package/dist/shared/constants.js

@@ -0,0 +1,15 @@
+// the origin of GitHub's REST API on github.com
+export const GITHUB_API_ORIGIN = 'https://api.github.com';
+// the origin GitHub serves a repository's raw files from
+export const GITHUB_RAW_CONTENT_ORIGIN = 'https://raw.githubusercontent.com';
+// the REST API version every request asks for, in the X-GitHub-Api-Version header
+export const GITHUB_API_VERSION = '2026-03-10';
+// the media type GitHub's REST API answers with
+export const GITHUB_MEDIA_TYPE = 'application/vnd.github+json';
+// the seconds a request to GitHub may take when the options don't say
+export const DEFAULT_GITHUB_TIMEOUT_SECONDS = 10;
+// the bytes a response from GitHub may take when the options don't say (128 KiB)
+export const DEFAULT_GITHUB_MAX_RESPONSE_BYTES = 131_072;
+// the host names that only this machine can reach, where plain http is allowed for test servers
+export const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+//# sourceMappingURL=constants.js.map

package/dist/shared/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/shared/constants.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,CAAC,MAAM,iBAAiB,GAAG,wBAAwB,CAAC;AAE1D,yDAAyD;AACzD,MAAM,CAAC,MAAM,yBAAyB,GAAG,mCAAmC,CAAC;AAE7E,kFAAkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAE/C,gDAAgD;AAChD,MAAM,CAAC,MAAM,iBAAiB,GAAG,6BAA6B,CAAC;AAE/D,sEAAsE;AACtE,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC;AAEjD,iFAAiF;AACjF,MAAM,CAAC,MAAM,iCAAiC,GAAG,OAAO,CAAC;AAEzD,gGAAgG;AAChG,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC","sourcesContent":["// the origin of GitHub's REST API on github.com\nexport const GITHUB_API_ORIGIN = 'https://api.github.com';\n\n// the origin GitHub serves a repository's raw files from\nexport const GITHUB_RAW_CONTENT_ORIGIN = 'https://raw.githubusercontent.com';\n\n// the REST API version every request asks for, in the X-GitHub-Api-Version header\nexport const GITHUB_API_VERSION = '2026-03-10';\n\n// the media type GitHub's REST API answers with\nexport const GITHUB_MEDIA_TYPE = 'application/vnd.github+json';\n\n// the seconds a request to GitHub may take when the options don't say\nexport const DEFAULT_GITHUB_TIMEOUT_SECONDS = 10;\n\n// the bytes a response from GitHub may take when the options don't say (128 KiB)\nexport const DEFAULT_GITHUB_MAX_RESPONSE_BYTES = 131_072;\n\n// the host names that only this machine can reach, where plain http is allowed for test servers\nexport const LOOPBACK_HOSTNAMES: ReadonlySet<string> = new Set(['localhost', '127.0.0.1', '[::1]']);\n"]}

package/dist/shared/errors.d.ts

@@ -0,0 +1,9 @@
+export declare const ERRORS: {
+    readonly GITHUB_PRIVATE_KEY_INVALID: "GITHUB_PRIVATE_KEY_INVALID";
+    readonly GITHUB_INVALID_ARGUMENT: "GITHUB_INVALID_ARGUMENT";
+    readonly GITHUB_REQUEST_FAILED: "GITHUB_REQUEST_FAILED";
+    readonly GITHUB_RESPONSE_INVALID: "GITHUB_RESPONSE_INVALID";
+    readonly GITHUB_TOKEN_SCOPE_MISMATCH: "GITHUB_TOKEN_SCOPE_MISMATCH";
+    readonly GITHUB_TOKEN_EXPIRED: "GITHUB_TOKEN_EXPIRED";
+    readonly GITHUB_TOKEN_REVOKE_FAILED: "GITHUB_TOKEN_REVOKE_FAILED";
+};

package/dist/shared/errors.js

@@ -0,0 +1,11 @@
+// the codes for every error thrown by the package
+export const ERRORS = {
+    GITHUB_PRIVATE_KEY_INVALID: 'GITHUB_PRIVATE_KEY_INVALID',
+    GITHUB_INVALID_ARGUMENT: 'GITHUB_INVALID_ARGUMENT',
+    GITHUB_REQUEST_FAILED: 'GITHUB_REQUEST_FAILED',
+    GITHUB_RESPONSE_INVALID: 'GITHUB_RESPONSE_INVALID',
+    GITHUB_TOKEN_SCOPE_MISMATCH: 'GITHUB_TOKEN_SCOPE_MISMATCH',
+    GITHUB_TOKEN_EXPIRED: 'GITHUB_TOKEN_EXPIRED',
+    GITHUB_TOKEN_REVOKE_FAILED: 'GITHUB_TOKEN_REVOKE_FAILED',
+};
+//# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,0BAA0B,EAAE,4BAA4B;IACxD,uBAAuB,EAAE,yBAAyB;IAClD,qBAAqB,EAAE,uBAAuB;IAC9C,uBAAuB,EAAE,yBAAyB;IAClD,2BAA2B,EAAE,6BAA6B;IAC1D,oBAAoB,EAAE,sBAAsB;IAC5C,0BAA0B,EAAE,4BAA4B;CAChD,CAAC","sourcesContent":["// the codes for every error thrown by the package\nexport const ERRORS = {\n  GITHUB_PRIVATE_KEY_INVALID: 'GITHUB_PRIVATE_KEY_INVALID',\n  GITHUB_INVALID_ARGUMENT: 'GITHUB_INVALID_ARGUMENT',\n  GITHUB_REQUEST_FAILED: 'GITHUB_REQUEST_FAILED',\n  GITHUB_RESPONSE_INVALID: 'GITHUB_RESPONSE_INVALID',\n  GITHUB_TOKEN_SCOPE_MISMATCH: 'GITHUB_TOKEN_SCOPE_MISMATCH',\n  GITHUB_TOKEN_EXPIRED: 'GITHUB_TOKEN_EXPIRED',\n  GITHUB_TOKEN_REVOKE_FAILED: 'GITHUB_TOKEN_REVOKE_FAILED',\n} as const;\n"]}

package/dist/shared/headers.d.ts

@@ -0,0 +1,19 @@
+import type { IGithubHeadersOptions } from './types.js';
+/**
+ * Builds the headers a request to GitHub's REST API sends: the media type, the token as a bearer
+ * credential, the User-Agent GitHub requires, and the API version.
+ * @param token The token, such as an installation token or an App JWT.
+ * @param options The User-Agent and the API version.
+ * @returns The headers, with lowercase names.
+ * @example
+ * import { createGithubHeaders } from 'jg-github';
+ *
+ * declare const token: string;
+ *
+ * const response = await fetch('https://api.github.com/installation/repositories', {
+ *   headers: createGithubHeaders(token, { userAgent: 'acme-deploy-bot' }),
+ * });
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export declare const createGithubHeaders: (token: string, { userAgent, apiVersion }: IGithubHeadersOptions) => Record<string, string>;

package/dist/shared/headers.js

@@ -0,0 +1,37 @@
+import { GITHUB_API_VERSION, GITHUB_MEDIA_TYPE } from './constants.js';
+import { invalidArgument, isHeaderValue } from './utilities.js';
+/**
+ * Builds the headers a request to GitHub's REST API sends: the media type, the token as a bearer
+ * credential, the User-Agent GitHub requires, and the API version.
+ * @param token The token, such as an installation token or an App JWT.
+ * @param options The User-Agent and the API version.
+ * @returns The headers, with lowercase names.
+ * @example
+ * import { createGithubHeaders } from 'jg-github';
+ *
+ * declare const token: string;
+ *
+ * const response = await fetch('https://api.github.com/installation/repositories', {
+ *   headers: createGithubHeaders(token, { userAgent: 'acme-deploy-bot' }),
+ * });
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export const createGithubHeaders = (token, { userAgent, apiVersion = GITHUB_API_VERSION }) => {
+    if (!isHeaderValue(token) || token.includes(' ')) {
+        throw invalidArgument('token');
+    }
+    if (!isHeaderValue(userAgent)) {
+        throw invalidArgument('userAgent');
+    }
+    if (!isHeaderValue(apiVersion)) {
+        throw invalidArgument('apiVersion');
+    }
+    return {
+        accept: GITHUB_MEDIA_TYPE,
+        authorization: `Bearer ${token}`,
+        'user-agent': userAgent,
+        'x-github-api-version': apiVersion,
+    };
+};
+//# sourceMappingURL=headers.js.map

package/dist/shared/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../../src/shared/headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEvE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,KAAa,EACb,EAAE,SAAS,EAAE,UAAU,GAAG,kBAAkB,EAAyB,EAC7C,EAAE;IAC1B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,MAAM,eAAe,CAAC,WAAW,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,MAAM,eAAe,CAAC,YAAY,CAAC,CAAC;IACtC,CAAC;IACD,OAAO;QACL,MAAM,EAAE,iBAAiB;QACzB,aAAa,EAAE,UAAU,KAAK,EAAE;QAChC,YAAY,EAAE,SAAS;QACvB,sBAAsB,EAAE,UAAU;KACnC,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { GITHUB_API_VERSION, GITHUB_MEDIA_TYPE } from './constants.js';\nimport type { IGithubHeadersOptions } from './types.js';\nimport { invalidArgument, isHeaderValue } from './utilities.js';\n\n/**\n * Builds the headers a request to GitHub's REST API sends: the media type, the token as a bearer\n * credential, the User-Agent GitHub requires, and the API version.\n * @param token The token, such as an installation token or an App JWT.\n * @param options The User-Agent and the API version.\n * @returns The headers, with lowercase names.\n * @example\n * import { createGithubHeaders } from 'jg-github';\n *\n * declare const token: string;\n *\n * const response = await fetch('https://api.github.com/installation/repositories', {\n *   headers: createGithubHeaders(token, { userAgent: 'acme-deploy-bot' }),\n * });\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nexport const createGithubHeaders = (\n  token: string,\n  { userAgent, apiVersion = GITHUB_API_VERSION }: IGithubHeadersOptions,\n): Record<string, string> => {\n  if (!isHeaderValue(token) || token.includes(' ')) {\n    throw invalidArgument('token');\n  }\n  if (!isHeaderValue(userAgent)) {\n    throw invalidArgument('userAgent');\n  }\n  if (!isHeaderValue(apiVersion)) {\n    throw invalidArgument('apiVersion');\n  }\n  return {\n    accept: GITHUB_MEDIA_TYPE,\n    authorization: `Bearer ${token}`,\n    'user-agent': userAgent,\n    'x-github-api-version': apiVersion,\n  };\n};\n"]}

package/dist/shared/index.d.ts

@@ -0,0 +1,6 @@
+export type { IGithubApiUrlOptions, IGithubHeadersOptions, IGithubQuery, IGithubRawContentLocation, IGithubRawContentUrlOptions, } from './types.js';
+export { DEFAULT_GITHUB_MAX_RESPONSE_BYTES, DEFAULT_GITHUB_TIMEOUT_SECONDS, GITHUB_API_ORIGIN, GITHUB_API_VERSION, GITHUB_RAW_CONTENT_ORIGIN, } from './constants.js';
+export { ERRORS } from './errors.js';
+export { invalidArgument, isHeaderValue, isRecord } from './utilities.js';
+export { buildGithubApiUrl, buildGithubRawContentUrl } from './urls.js';
+export { createGithubHeaders } from './headers.js';

package/dist/shared/index.js

@@ -0,0 +1,11 @@
+// constants
+export { DEFAULT_GITHUB_MAX_RESPONSE_BYTES, DEFAULT_GITHUB_TIMEOUT_SECONDS, GITHUB_API_ORIGIN, GITHUB_API_VERSION, GITHUB_RAW_CONTENT_ORIGIN, } from './constants.js';
+// error codes
+export { ERRORS } from './errors.js';
+// errors and checks
+export { invalidArgument, isHeaderValue, isRecord } from './utilities.js';
+// URLs
+export { buildGithubApiUrl, buildGithubRawContentUrl } from './urls.js';
+// headers
+export { createGithubHeaders } from './headers.js';
+//# sourceMappingURL=index.js.map

package/dist/shared/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AASA,YAAY;AACZ,OAAO,EACL,iCAAiC,EACjC,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAExB,cAAc;AACd,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1E,OAAO;AACP,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAExE,UAAU;AACV,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC","sourcesContent":["// types\nexport type {\n  IGithubApiUrlOptions,\n  IGithubHeadersOptions,\n  IGithubQuery,\n  IGithubRawContentLocation,\n  IGithubRawContentUrlOptions,\n} from './types.js';\n\n// constants\nexport {\n  DEFAULT_GITHUB_MAX_RESPONSE_BYTES,\n  DEFAULT_GITHUB_TIMEOUT_SECONDS,\n  GITHUB_API_ORIGIN,\n  GITHUB_API_VERSION,\n  GITHUB_RAW_CONTENT_ORIGIN,\n} from './constants.js';\n\n// error codes\nexport { ERRORS } from './errors.js';\n\n// errors and checks\nexport { invalidArgument, isHeaderValue, isRecord } from './utilities.js';\n\n// URLs\nexport { buildGithubApiUrl, buildGithubRawContentUrl } from './urls.js';\n\n// headers\nexport { createGithubHeaders } from './headers.js';\n"]}

package/dist/shared/types.d.ts

@@ -0,0 +1,17 @@
+export type IGithubHeadersOptions = {
+    userAgent: string;
+    apiVersion?: string | undefined;
+};
+export type IGithubApiUrlOptions = {
+    apiOrigin?: string | undefined;
+};
+export type IGithubQuery = Record<string, string | number | boolean | undefined>;
+export type IGithubRawContentLocation = {
+    owner: string;
+    repository: string;
+    ref: string;
+    path: string;
+};
+export type IGithubRawContentUrlOptions = {
+    rawContentOrigin?: string | undefined;
+};

package/dist/shared/types.js

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

package/dist/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"","sourcesContent":["// what createGithubHeaders takes\nexport type IGithubHeadersOptions = {\n  // the User-Agent GitHub requires on every request, such as the app's name\n  userAgent: string;\n\n  // the REST API version. Defaults to GITHUB_API_VERSION\n  apiVersion?: string | undefined;\n};\n\n// what buildGithubApiUrl takes\nexport type IGithubApiUrlOptions = {\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\n// the query parameters a URL builder appends; undefined ones are left out\nexport type IGithubQuery = Record<string, string | number | boolean | undefined>;\n\n// a file in a repository, at a ref\nexport type IGithubRawContentLocation = {\n  // the account that owns the repository\n  owner: string;\n\n  // the repository's name\n  repository: string;\n\n  // the branch, tag, or commit, such as `main` or `feature/login`\n  ref: string;\n\n  // the file's path from the repository's root, such as `docs/setup.md`\n  path: string;\n};\n\n// what buildGithubRawContentUrl takes\nexport type IGithubRawContentUrlOptions = {\n  // the raw content's base URL. Defaults to GITHUB_RAW_CONTENT_ORIGIN\n  rawContentOrigin?: string | undefined;\n};\n"]}

package/dist/shared/urls.d.ts

@@ -0,0 +1,32 @@
+import type { IGithubApiUrlOptions, IGithubQuery, IGithubRawContentLocation, IGithubRawContentUrlOptions } from './types.js';
+/**
+ * Builds a REST API URL from its path segments, each encoded on its own, so a branch's `/`
+ * becomes `%2F` and no value can climb out of the path, plus the query parameters.
+ * @param segments The path's segments, such as `['repos', owner, repository, 'branches', branch]`.
+ * @param query The query parameters; undefined ones are left out.
+ * @param options The API's base URL, for GitHub Enterprise Server or a test server.
+ * @returns The URL.
+ * @example
+ * import { buildGithubApiUrl } from 'jg-github';
+ *
+ * buildGithubApiUrl(['repos', 'acme', 'app', 'branches', 'feature/login'], { per_page: 100 });
+ * // 'https://api.github.com/repos/acme/app/branches/feature%2Flogin?per_page=100'
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export declare const buildGithubApiUrl: (segments: readonly (string | number)[], query?: IGithubQuery, { apiOrigin }?: IGithubApiUrlOptions) => string;
+/**
+ * Builds the URL of a file's raw content at a ref, with the owner and the repository encoded as
+ * one segment each, and the ref's and the path's `/`s kept.
+ * @param location The repository, the ref, and the file's path.
+ * @param options The raw content's base URL, for a test server.
+ * @returns The URL.
+ * @example
+ * import { buildGithubRawContentUrl } from 'jg-github';
+ *
+ * buildGithubRawContentUrl({ owner: 'acme', repository: 'app', ref: 'main', path: 'docs/setup.md' });
+ * // 'https://raw.githubusercontent.com/acme/app/main/docs/setup.md'
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export declare const buildGithubRawContentUrl: ({ owner, repository, ref, path }: IGithubRawContentLocation, { rawContentOrigin }?: IGithubRawContentUrlOptions) => string;

package/dist/shared/urls.js

@@ -0,0 +1,110 @@
+import { GITHUB_API_ORIGIN, GITHUB_RAW_CONTENT_ORIGIN, LOOPBACK_HOSTNAMES } from './constants.js';
+import { invalidArgument } from './utilities.js';
+/**
+ * Reads a base URL: https, or http on a loopback host for a local test server, without
+ * credentials, a query, or a fragment, and without its trailing slash.
+ * @param value The base URL.
+ * @param name The argument it came from.
+ * @returns The base URL.
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+const readBaseUrl = (value, name) => {
+    let url;
+    try {
+        url = new URL(String(value));
+    }
+    catch {
+        throw invalidArgument(name);
+    }
+    const isAllowedProtocol = url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK_HOSTNAMES.has(url.hostname));
+    if (typeof value !== 'string' ||
+        !isAllowedProtocol ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.search !== '' ||
+        url.hash !== '') {
+        throw invalidArgument(name);
+    }
+    return url.href.replace(/\/+$/, '');
+};
+/**
+ * Encodes one path segment, refusing one that's empty or a dot segment, which a URL would
+ * resolve away.
+ * @param segment The segment.
+ * @param name The argument it came from.
+ * @returns The encoded segment.
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+const encodeSegment = (segment, name) => {
+    if (typeof segment === 'number' && Number.isSafeInteger(segment) && segment >= 0) {
+        return String(segment);
+    }
+    if (typeof segment !== 'string' || segment === '' || segment === '.' || segment === '..') {
+        throw invalidArgument(name);
+    }
+    return encodeURIComponent(segment);
+};
+/**
+ * Encodes a value whose `/`s separate segments, such as a file's path or a branch like
+ * `feature/login`, keeping the `/`s.
+ * @param value The value.
+ * @param name The argument it came from.
+ * @returns The encoded value.
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+const encodePath = (value, name) => {
+    if (typeof value !== 'string') {
+        throw invalidArgument(name);
+    }
+    return value
+        .split('/')
+        .map((segment) => encodeSegment(segment, name))
+        .join('/');
+};
+/**
+ * Builds a REST API URL from its path segments, each encoded on its own, so a branch's `/`
+ * becomes `%2F` and no value can climb out of the path, plus the query parameters.
+ * @param segments The path's segments, such as `['repos', owner, repository, 'branches', branch]`.
+ * @param query The query parameters; undefined ones are left out.
+ * @param options The API's base URL, for GitHub Enterprise Server or a test server.
+ * @returns The URL.
+ * @example
+ * import { buildGithubApiUrl } from 'jg-github';
+ *
+ * buildGithubApiUrl(['repos', 'acme', 'app', 'branches', 'feature/login'], { per_page: 100 });
+ * // 'https://api.github.com/repos/acme/app/branches/feature%2Flogin?per_page=100'
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export const buildGithubApiUrl = (segments, query = {}, { apiOrigin = GITHUB_API_ORIGIN } = {}) => {
+    const base = readBaseUrl(apiOrigin, 'apiOrigin');
+    if (!Array.isArray(segments) || segments.length === 0) {
+        throw invalidArgument('segments');
+    }
+    const url = new URL(`${base}/${segments.map((segment) => encodeSegment(segment, 'segments')).join('/')}`);
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined) {
+            url.searchParams.append(key, String(value));
+        }
+    }
+    return url.href;
+};
+/**
+ * Builds the URL of a file's raw content at a ref, with the owner and the repository encoded as
+ * one segment each, and the ref's and the path's `/`s kept.
+ * @param location The repository, the ref, and the file's path.
+ * @param options The raw content's base URL, for a test server.
+ * @returns The URL.
+ * @example
+ * import { buildGithubRawContentUrl } from 'jg-github';
+ *
+ * buildGithubRawContentUrl({ owner: 'acme', repository: 'app', ref: 'main', path: 'docs/setup.md' });
+ * // 'https://raw.githubusercontent.com/acme/app/main/docs/setup.md'
+ * @throws
+ * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.
+ */
+export const buildGithubRawContentUrl = ({ owner, repository, ref, path }, { rawContentOrigin = GITHUB_RAW_CONTENT_ORIGIN } = {}) => `${readBaseUrl(rawContentOrigin, 'rawContentOrigin')}/${encodeSegment(owner, 'owner')}/${encodeSegment(repository, 'repository')}/${encodePath(ref, 'ref')}/${encodePath(path, 'path')}`;
+//# sourceMappingURL=urls.js.map

package/dist/shared/urls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"urls.js","sourceRoot":"","sources":["../../src/shared/urls.ts"],"names":[],"mappings":"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","sourcesContent":["import { GITHUB_API_ORIGIN, GITHUB_RAW_CONTENT_ORIGIN, LOOPBACK_HOSTNAMES } from './constants.js';\nimport type {\n  IGithubApiUrlOptions,\n  IGithubQuery,\n  IGithubRawContentLocation,\n  IGithubRawContentUrlOptions,\n} from './types.js';\nimport { invalidArgument } from './utilities.js';\n\n/**\n * Reads a base URL: https, or http on a loopback host for a local test server, without\n * credentials, a query, or a fragment, and without its trailing slash.\n * @param value The base URL.\n * @param name The argument it came from.\n * @returns The base URL.\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nconst readBaseUrl = (value: unknown, name: string): string => {\n  let url: URL;\n  try {\n    url = new URL(String(value));\n  } catch {\n    throw invalidArgument(name);\n  }\n  const isAllowedProtocol =\n    url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK_HOSTNAMES.has(url.hostname));\n  if (\n    typeof value !== 'string' ||\n    !isAllowedProtocol ||\n    url.username !== '' ||\n    url.password !== '' ||\n    url.search !== '' ||\n    url.hash !== ''\n  ) {\n    throw invalidArgument(name);\n  }\n  return url.href.replace(/\\/+$/, '');\n};\n\n/**\n * Encodes one path segment, refusing one that's empty or a dot segment, which a URL would\n * resolve away.\n * @param segment The segment.\n * @param name The argument it came from.\n * @returns The encoded segment.\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nconst encodeSegment = (segment: unknown, name: string): string => {\n  if (typeof segment === 'number' && Number.isSafeInteger(segment) && segment >= 0) {\n    return String(segment);\n  }\n  if (typeof segment !== 'string' || segment === '' || segment === '.' || segment === '..') {\n    throw invalidArgument(name);\n  }\n  return encodeURIComponent(segment);\n};\n\n/**\n * Encodes a value whose `/`s separate segments, such as a file's path or a branch like\n * `feature/login`, keeping the `/`s.\n * @param value The value.\n * @param name The argument it came from.\n * @returns The encoded value.\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nconst encodePath = (value: unknown, name: string): string => {\n  if (typeof value !== 'string') {\n    throw invalidArgument(name);\n  }\n  return value\n    .split('/')\n    .map((segment) => encodeSegment(segment, name))\n    .join('/');\n};\n\n/**\n * Builds a REST API URL from its path segments, each encoded on its own, so a branch's `/`\n * becomes `%2F` and no value can climb out of the path, plus the query parameters.\n * @param segments The path's segments, such as `['repos', owner, repository, 'branches', branch]`.\n * @param query The query parameters; undefined ones are left out.\n * @param options The API's base URL, for GitHub Enterprise Server or a test server.\n * @returns The URL.\n * @example\n * import { buildGithubApiUrl } from 'jg-github';\n *\n * buildGithubApiUrl(['repos', 'acme', 'app', 'branches', 'feature/login'], { per_page: 100 });\n * // 'https://api.github.com/repos/acme/app/branches/feature%2Flogin?per_page=100'\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nexport const buildGithubApiUrl = (\n  segments: readonly (string | number)[],\n  query: IGithubQuery = {},\n  { apiOrigin = GITHUB_API_ORIGIN }: IGithubApiUrlOptions = {},\n): string => {\n  const base = readBaseUrl(apiOrigin, 'apiOrigin');\n  if (!Array.isArray(segments) || segments.length === 0) {\n    throw invalidArgument('segments');\n  }\n  const url = new URL(\n    `${base}/${segments.map((segment: unknown) => encodeSegment(segment, 'segments')).join('/')}`,\n  );\n  for (const [key, value] of Object.entries(query)) {\n    if (value !== undefined) {\n      url.searchParams.append(key, String(value));\n    }\n  }\n  return url.href;\n};\n\n/**\n * Builds the URL of a file's raw content at a ref, with the owner and the repository encoded as\n * one segment each, and the ref's and the path's `/`s kept.\n * @param location The repository, the ref, and the file's path.\n * @param options The raw content's base URL, for a test server.\n * @returns The URL.\n * @example\n * import { buildGithubRawContentUrl } from 'jg-github';\n *\n * buildGithubRawContentUrl({ owner: 'acme', repository: 'app', ref: 'main', path: 'docs/setup.md' });\n * // 'https://raw.githubusercontent.com/acme/app/main/docs/setup.md'\n * @throws\n * - GITHUB_INVALID_ARGUMENT: An argument isn't valid.\n */\nexport const buildGithubRawContentUrl = (\n  { owner, repository, ref, path }: IGithubRawContentLocation,\n  { rawContentOrigin = GITHUB_RAW_CONTENT_ORIGIN }: IGithubRawContentUrlOptions = {},\n): string =>\n  `${readBaseUrl(rawContentOrigin, 'rawContentOrigin')}/${encodeSegment(owner, 'owner')}/${encodeSegment(\n    repository,\n    'repository',\n  )}/${encodePath(ref, 'ref')}/${encodePath(path, 'path')}`;\n"]}

package/dist/shared/utilities.d.ts

@@ -0,0 +1,20 @@
+import { Exception } from 'jg-exception';
+/**
+ * Builds the exception for an argument that isn't valid.
+ * @param name The argument, such as `installationId`.
+ * @returns The GITHUB_INVALID_ARGUMENT exception.
+ */
+export declare const invalidArgument: (name: string) => Exception;
+/**
+ * Checks whether a value is a plain object, such as one parsed from JSON.
+ * @param value The value.
+ * @returns Whether it is.
+ */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Checks whether a value can go in an HTTP header: a non-empty string of visible ASCII characters
+ * and spaces, without line breaks.
+ * @param value The value.
+ * @returns Whether it can.
+ */
+export declare const isHeaderValue: (value: unknown) => value is string;

package/dist/shared/utilities.js

@@ -0,0 +1,25 @@
+import { Exception } from 'jg-exception';
+import { ERRORS } from './errors.js';
+/**
+ * Builds the exception for an argument that isn't valid.
+ * @param name The argument, such as `installationId`.
+ * @returns The GITHUB_INVALID_ARGUMENT exception.
+ */
+export const invalidArgument = (name) => new Exception("An argument isn't valid.", {
+    code: ERRORS.GITHUB_INVALID_ARGUMENT,
+    data: { argument: name },
+});
+/**
+ * Checks whether a value is a plain object, such as one parsed from JSON.
+ * @param value The value.
+ * @returns Whether it is.
+ */
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Checks whether a value can go in an HTTP header: a non-empty string of visible ASCII characters
+ * and spaces, without line breaks.
+ * @param value The value.
+ * @returns Whether it can.
+ */
+export const isHeaderValue = (value) => typeof value === 'string' && /^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/.test(value);
+//# sourceMappingURL=utilities.js.map

package/dist/shared/utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../src/shared/utilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAY,EAAa,EAAE,CACzD,IAAI,SAAS,CAAC,0BAA0B,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC,uBAAuB;IACpC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;CACzB,CAAC,CAAC;AAEL;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CAC3E,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAc,EAAmB,EAAE,CAC/D,OAAO,KAAK,KAAK,QAAQ,IAAI,2CAA2C,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC","sourcesContent":["import { Exception } from 'jg-exception';\n\nimport { ERRORS } from './errors.js';\n\n/**\n * Builds the exception for an argument that isn't valid.\n * @param name The argument, such as `installationId`.\n * @returns The GITHUB_INVALID_ARGUMENT exception.\n */\nexport const invalidArgument = (name: string): Exception =>\n  new Exception(\"An argument isn't valid.\", {\n    code: ERRORS.GITHUB_INVALID_ARGUMENT,\n    data: { argument: name },\n  });\n\n/**\n * Checks whether a value is a plain object, such as one parsed from JSON.\n * @param value The value.\n * @returns Whether it is.\n */\nexport const isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/**\n * Checks whether a value can go in an HTTP header: a non-empty string of visible ASCII characters\n * and spaces, without line breaks.\n * @param value The value.\n * @returns Whether it can.\n */\nexport const isHeaderValue = (value: unknown): value is string =>\n  typeof value === 'string' && /^[\\x21-\\x7e](?:[\\x20-\\x7e]*[\\x21-\\x7e])?$/.test(value);\n"]}

package/dist/webhook/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const MAX_SIGNATURE_HEADER_LENGTH = 71;
+export declare const SIGNATURE_HEADER_PATTERN: RegExp;

package/dist/webhook/constants.js

@@ -0,0 +1,5 @@
+// the longest X-Hub-Signature-256 header: 'sha256=' and 64 hexadecimal characters
+export const MAX_SIGNATURE_HEADER_LENGTH = 71;
+// an X-Hub-Signature-256 header
+export const SIGNATURE_HEADER_PATTERN = /^sha256=[0-9a-f]{64}$/;
+//# sourceMappingURL=constants.js.map

package/dist/webhook/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/webhook/constants.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAE9C,gCAAgC;AAChC,MAAM,CAAC,MAAM,wBAAwB,GAAG,uBAAuB,CAAC","sourcesContent":["// the longest X-Hub-Signature-256 header: 'sha256=' and 64 hexadecimal characters\nexport const MAX_SIGNATURE_HEADER_LENGTH = 71;\n\n// an X-Hub-Signature-256 header\nexport const SIGNATURE_HEADER_PATTERN = /^sha256=[0-9a-f]{64}$/;\n"]}

package/dist/webhook/index.d.ts

@@ -0,0 +1 @@
+export { verifyGithubWebhookSignature } from './webhook.js';

package/dist/webhook/index.js

@@ -0,0 +1,3 @@
+// webhook signatures
+export { verifyGithubWebhookSignature } from './webhook.js';
+//# sourceMappingURL=index.js.map

package/dist/webhook/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/webhook/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,OAAO,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC","sourcesContent":["// webhook signatures\nexport { verifyGithubWebhookSignature } from './webhook.js';\n"]}

package/dist/webhook/webhook.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Verifies a GitHub webhook delivery's X-Hub-Signature-256 header against the body's exact
+ * bytes, in constant time. A header that's missing, repeated, longer than 71 characters, or not
+ * `sha256=` and 64 lowercase hexadecimal characters is false, like a wrong signature. Verify the
+ * raw body before parsing it, because parsing and serializing can change its bytes.
+ * @param rawBody The request's body, as received.
+ * @param header The X-Hub-Signature-256 header, as the framework gives it.
+ * @param secret The webhook's secret.
+ * @returns Whether the signature is the body's.
+ * @example
+ * import { verifyGithubWebhookSignature } from 'jg-github';
+ *
+ * declare const rawBody: Buffer;
+ * declare const headers: Record<string, string | string[] | undefined>;
+ * declare const webhookSecret: string;
+ *
+ * if (!verifyGithubWebhookSignature(rawBody, headers['x-hub-signature-256'], webhookSecret)) {
+ *   // answer 401
+ * }
+ * @throws
+ * - INVALID_HMAC_SECRET: The HMAC secret must be a non-empty string or byte array.
+ */
+export declare const verifyGithubWebhookSignature: (rawBody: string | Uint8Array, header: unknown, secret: string | Uint8Array) => boolean;

package/dist/webhook/webhook.js

@@ -0,0 +1,35 @@
+import { verifyHmac } from 'jg-crypto';
+import { MAX_SIGNATURE_HEADER_LENGTH, SIGNATURE_HEADER_PATTERN } from './constants.js';
+/**
+ * Verifies a GitHub webhook delivery's X-Hub-Signature-256 header against the body's exact
+ * bytes, in constant time. A header that's missing, repeated, longer than 71 characters, or not
+ * `sha256=` and 64 lowercase hexadecimal characters is false, like a wrong signature. Verify the
+ * raw body before parsing it, because parsing and serializing can change its bytes.
+ * @param rawBody The request's body, as received.
+ * @param header The X-Hub-Signature-256 header, as the framework gives it.
+ * @param secret The webhook's secret.
+ * @returns Whether the signature is the body's.
+ * @example
+ * import { verifyGithubWebhookSignature } from 'jg-github';
+ *
+ * declare const rawBody: Buffer;
+ * declare const headers: Record<string, string | string[] | undefined>;
+ * declare const webhookSecret: string;
+ *
+ * if (!verifyGithubWebhookSignature(rawBody, headers['x-hub-signature-256'], webhookSecret)) {
+ *   // answer 401
+ * }
+ * @throws
+ * - INVALID_HMAC_SECRET: The HMAC secret must be a non-empty string or byte array.
+ */
+export const verifyGithubWebhookSignature = (rawBody, header, secret) => {
+    if (typeof header !== 'string' ||
+        header.length > MAX_SIGNATURE_HEADER_LENGTH ||
+        !SIGNATURE_HEADER_PATTERN.test(header)) {
+        // still checks the secret, so an empty one fails loudly whatever the header
+        verifyHmac(rawBody, '', secret);
+        return false;
+    }
+    return verifyHmac(rawBody, header.slice('sha256='.length), secret);
+};
+//# sourceMappingURL=webhook.js.map

package/dist/webhook/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../src/webhook/webhook.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAC1C,OAA4B,EAC5B,MAAe,EACf,MAA2B,EAClB,EAAE;IACX,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,CAAC,MAAM,GAAG,2BAA2B;QAC3C,CAAC,wBAAwB,CAAC,IAAI,CAAC,MAAM,CAAC,EACtC,CAAC;QACD,4EAA4E;QAC5E,UAAU,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AACrE,CAAC,CAAC","sourcesContent":["import { verifyHmac } from 'jg-crypto';\n\nimport { MAX_SIGNATURE_HEADER_LENGTH, SIGNATURE_HEADER_PATTERN } from './constants.js';\n\n/**\n * Verifies a GitHub webhook delivery's X-Hub-Signature-256 header against the body's exact\n * bytes, in constant time. A header that's missing, repeated, longer than 71 characters, or not\n * `sha256=` and 64 lowercase hexadecimal characters is false, like a wrong signature. Verify the\n * raw body before parsing it, because parsing and serializing can change its bytes.\n * @param rawBody The request's body, as received.\n * @param header The X-Hub-Signature-256 header, as the framework gives it.\n * @param secret The webhook's secret.\n * @returns Whether the signature is the body's.\n * @example\n * import { verifyGithubWebhookSignature } from 'jg-github';\n *\n * declare const rawBody: Buffer;\n * declare const headers: Record<string, string | string[] | undefined>;\n * declare const webhookSecret: string;\n *\n * if (!verifyGithubWebhookSignature(rawBody, headers['x-hub-signature-256'], webhookSecret)) {\n *   // answer 401\n * }\n * @throws\n * - INVALID_HMAC_SECRET: The HMAC secret must be a non-empty string or byte array.\n */\nexport const verifyGithubWebhookSignature = (\n  rawBody: string | Uint8Array,\n  header: unknown,\n  secret: string | Uint8Array,\n): boolean => {\n  if (\n    typeof header !== 'string' ||\n    header.length > MAX_SIGNATURE_HEADER_LENGTH ||\n    !SIGNATURE_HEADER_PATTERN.test(header)\n  ) {\n    // still checks the secret, so an empty one fails loudly whatever the header\n    verifyHmac(rawBody, '', secret);\n    return false;\n  }\n  return verifyHmac(rawBody, header.slice('sha256='.length), secret);\n};\n"]}