@socketsecurity/lib 6.0.3 → 6.0.5

package/dist/github/errors.js

@@ -1,40 +1,48 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/github/errors.ts
+/**
+* @file Named errors thrown by `github/*` helpers.
+*/
+/**
+* Thrown by `fetchGitHub` when GitHub returns HTTP 200 OK with a zero-byte body
+* — the "successful empty response" pattern.
+*
+* Why this exists (background for new contributors): GitHub's REST API has a
+* documented failure mode that is _very_ easy to miss in code review. During
+* incidents where the search / Elasticsearch backing index is degraded (see
+* GitHub status pages with titles like "search is degraded" or "Pull Requests
+* degraded"), the REST `/repos/...` GET endpoints return: - HTTP status: 200 OK
+* ← looks like success - Body: "" ← but the payload is empty - Headers: no
+* Retry-After, no rate-limit signal, nothing.
+*
+* Without a typed error, calling code does
+* `JSON.parse(response.body.toString('utf8'))` on an empty string, which throws
+* a confusing `SyntaxError: Unexpected end of JSON input`. That error has
+* nothing to do with bad code on our side; it's GitHub's incident manifesting
+* as a parse failure several frames deep. We surface the actual condition (`200
+* \+ empty body`) as its own typed exception so the call path can either fall
+* through to the GraphQL backend (which queries a different data path and uses
+* a different backend and is unaffected by ES outages), or surface a clean
+* message to the user.
+*
+* The HTTP status is hard-coded to 200 because that's _exactly_ what makes this
+* insidious — a real 4xx/5xx would already be handled by the rate-limit /
+* status-code branch above.
+*/
+var GitHubEmptyBodyError = class extends Error {
+	/**
+	* HTTP status (always 200 — that's what makes this case insidious).
+	*/
+	status;
+	constructor(url) {
+		super(`GitHub API returned HTTP 200 with empty body: ${url}`);
+		this.name = "GitHubEmptyBodyError";
+		this.status = 200;
+	}
 };
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var errors_exports = {};
-__export(errors_exports, {
-  GitHubEmptyBodyError: () => GitHubEmptyBodyError
-});
-module.exports = __toCommonJS(errors_exports);
-class GitHubEmptyBodyError extends Error {
-  /**
-   * HTTP status (always 200 — that's what makes this case insidious).
-   */
-  status;
-  constructor(url) {
-    super(`GitHub API returned HTTP 200 with empty body: ${url}`);
-    this.name = "GitHubEmptyBodyError";
-    this.status = 200;
-  }
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  GitHubEmptyBodyError
-});
+
+//#endregion
+exports.GitHubEmptyBodyError = GitHubEmptyBodyError;

package/dist/github/fetch.js

@@ -1,87 +1,142 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var fetch_exports = {};
-__export(fetch_exports, {
-  fetchGitHub: () => fetchGitHub,
-  getGhsaUrl: () => getGhsaUrl
-});
-module.exports = __toCommonJS(fetch_exports);
-var import_message = require("../errors/message");
-var import_request = require("../http-request/request");
-var import_date = require("../primordials/date");
-var import_error = require("../primordials/error");
-var import_json = require("../primordials/json");
-var import_token = require("./token");
-var import_errors = require("./errors");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_error = require('../primordials/error.js');
+const require_primordials_date = require('../primordials/date.js');
+const require_primordials_json = require('../primordials/json.js');
+const require_errors_message = require('../errors/message.js');
+const require_http_request_request = require('../http-request/request.js');
+const require_github_errors = require('./errors.js');
+const require_github_token = require('./token.js');
+
+//#region src/github/fetch.ts
+/**
+* @file Authenticated GitHub REST fetch. `fetchGitHub` is the single entry
+*   point that the rest of the github/ modules go through for REST calls. It
+*   handles four things the callers shouldn't have to repeat:
+*
+*   1. Token resolution (env → git config) when the caller doesn't pass an
+*      explicit token.
+*   2. Standard headers (Accept, User-Agent) merged with caller- supplied headers.
+*   3. Rate-limit detection — when GitHub returns 403 with `x-ratelimit-remaining:
+*      0`, throw a typed `GitHubRateLimitError` so callers can react (set
+*      GITHUB_TOKEN, retry after reset).
+*   4. Empty-body detection — 200 OK + zero-byte body is the documented incident
+*      shape (see GitHubEmptyBodyError JSDoc). Raised as a typed error so the
+*      ref / GHSA modules can fall back to GraphQL on a different backend.
+*      `getGhsaUrl` lives here because it's the URL counterpart to the GHSA
+*      fetch path — the only other consumer is the GHSA module.
+*/
+/**
+* Fetch data from GitHub API with automatic authentication and rate limit
+* handling. Makes authenticated requests to the GitHub REST API with proper
+* error handling.
+*
+* Features: - Automatic token injection from environment if not provided - Rate
+* limit detection with helpful error messages - Standard GitHub API headers
+* (Accept, User-Agent) - JSON response parsing.
+*
+* @example
+*   ```ts
+*   // Fetch repository information
+*   interface Repo {
+*   name: string
+*   full_name: string
+*   default_branch: string
+*   }
+*   const repo = await fetchGitHub<Repo>(
+*   'https://api.github.com/repos/owner/repo',
+*   )
+*   console.log(`Default branch: ${repo.default_branch}`)
+*   ```
+*
+* @example
+*   ;```ts
+*   // With custom token and headers
+*   const data = await fetchGitHub('https://api.github.com/user', {
+*     token: 'ghp_customtoken',
+*     headers: { 'X-Custom-Header': 'value' },
+*   })
+*   ```
+*
+* @example
+*   ```ts
+*   // Handle rate limit errors
+*   try {
+*   await fetchGitHub('https://api.github.com/repos/owner/repo')
+*   } catch (e) {
+*   if (e.status === 403 && e.resetTime) {
+*   console.error(`Rate limited until ${e.resetTime}`)
+*   }
+*   }
+*   ```
+*
+* @template T - Expected response type (defaults to `unknown`)
+*
+* @param url - Full GitHub API URL (e.g.,
+*   'https://api.github.com/repos/owner/repo')
+* @param options - Fetch options including token and custom headers.
+*
+* @returns Parsed JSON response of type `T`
+*
+* @throws {GitHubRateLimitError} When API rate limit is exceeded (status 403)
+* @throws {Error} For other API errors with status code and message
+*/
 async function fetchGitHub(url, options) {
-  const opts = { __proto__: null, ...options };
-  const token = opts.token || (0, import_token.getGitHubToken)();
-  const headers = {
-    Accept: "application/vnd.github.v3+json",
-    "User-Agent": "socket-registry-github-client",
-    ...opts.headers
-  };
-  if (token) {
-    headers["Authorization"] = `Bearer ${token}`;
-  }
-  const response = await (0, import_request.httpRequest)(url, { headers });
-  if (!response.ok) {
-    if (response.status === 403) {
-      const rateLimit = response.headers["x-ratelimit-remaining"];
-      const rateLimitStr = typeof rateLimit === "string" ? rateLimit : rateLimit?.[0];
-      if (rateLimitStr === "0") {
-        const resetTime = response.headers["x-ratelimit-reset"];
-        const resetTimeStr = typeof resetTime === "string" ? resetTime : resetTime?.[0];
-        const resetDate = resetTimeStr ? new import_date.DateCtor(Number(resetTimeStr) * 1e3) : void 0;
-        const error = new import_error.ErrorCtor(
-          `GitHub API rate limit exceeded${resetDate ? `. Resets at ${resetDate.toLocaleString()}` : ""}. Use GITHUB_TOKEN environment variable to increase rate limit.`
-        );
-        error.status = 403;
-        error.resetTime = resetDate;
-        throw error;
-      }
-    }
-    throw new import_error.ErrorCtor(
-      `GitHub API error ${response.status}: ${response.statusText}`
-    );
-  }
-  if (response.body.byteLength === 0) {
-    throw new import_errors.GitHubEmptyBodyError(url);
-  }
-  try {
-    return (0, import_json.JSONParse)(response.body.toString("utf8"));
-  } catch (e) {
-    throw new import_error.ErrorCtor(
-      `Failed to parse GitHub API response: ${(0, import_message.errorMessage)(e)}
-URL: ${url}
-Response may be malformed or incomplete.`,
-      { cause: e }
-    );
-  }
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const token = opts.token || require_github_token.getGitHubToken();
+	const headers = {
+		Accept: "application/vnd.github.v3+json",
+		"User-Agent": "socket-registry-github-client",
+		...opts.headers
+	};
+	if (token) headers["Authorization"] = `Bearer ${token}`;
+	/* c8 ignore start - External GitHub API call */
+	const response = await require_http_request_request.httpRequest(url, { headers });
+	/* c8 ignore stop */
+	if (!response.ok) {
+		if (response.status === 403) {
+			const rateLimit = response.headers["x-ratelimit-remaining"];
+			if ((typeof rateLimit === "string" ? rateLimit : rateLimit?.[0]) === "0") {
+				const resetTime = response.headers["x-ratelimit-reset"];
+				const resetTimeStr = typeof resetTime === "string" ? resetTime : resetTime?.[0];
+				const resetDate = resetTimeStr ? new require_primordials_date.DateCtor(Number(resetTimeStr) * 1e3) : void 0;
+				const error = new require_primordials_error.ErrorCtor(`GitHub API rate limit exceeded${resetDate ? `. Resets at ${resetDate.toLocaleString()}` : ""}. Use GITHUB_TOKEN environment variable to increase rate limit.`);
+				error.status = 403;
+				error.resetTime = resetDate;
+				throw error;
+			}
+		}
+		throw new require_primordials_error.ErrorCtor(`GitHub API error ${response.status}: ${response.statusText}`);
+	}
+	if (response.body.byteLength === 0) throw new require_github_errors.GitHubEmptyBodyError(url);
+	try {
+		return require_primordials_json.JSONParse(response.body.toString("utf8"));
+	} catch (e) {
+		throw new require_primordials_error.ErrorCtor(`Failed to parse GitHub API response: ${require_errors_message.errorMessage(e)}\nURL: ${url}\nResponse may be malformed or incomplete.`, { cause: e });
+	}
 }
+/**
+* Generate GitHub Security Advisory URL from GHSA ID. Constructs the public
+* advisory URL for a given GHSA identifier.
+*
+* @example
+*   ;```ts
+*   const url = getGhsaUrl('GHSA-1234-5678-90ab')
+*   console.log(url) // 'https://github.com/advisories/GHSA-1234-5678-90ab'
+*   ```
+*
+* @param ghsaId - GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz')
+*
+* @returns Full URL to the advisory page
+*/
 function getGhsaUrl(ghsaId) {
-  return `https://github.com/advisories/${ghsaId}`;
+	return `https://github.com/advisories/${ghsaId}`;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  fetchGitHub,
-  getGhsaUrl
-});
+
+//#endregion
+exports.fetchGitHub = fetchGitHub;
+exports.getGhsaUrl = getGhsaUrl;