@socketsecurity/lib 1.0.5 → 1.1.0

package/dist/github.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/github.ts"],
-  "sourcesContent": ["/**\n * @fileoverview GitHub utilities for Socket projects.\n * Provides GitHub API integration for repository operations.\n *\n * Authentication:\n * - getGitHubToken: Retrieve GitHub token from environment variables\n * - fetchGitHub: Authenticated GitHub API requests with rate limit handling\n *\n * Ref Resolution:\n * - resolveRefToSha: Convert tags/branches to commit SHAs (with memoization and persistent cache)\n * - clearRefCache: Clear the in-memory memoization cache\n *\n * Caching:\n * - Uses cacache for persistent storage with in-memory memoization\n * - Two-tier caching: in-memory (Map) for hot data, persistent (cacache) for durability\n * - Default TTL: 5 minutes\n * - Disable with DISABLE_GITHUB_CACHE env var\n *\n * Rate Limiting:\n * - Automatic rate limit detection and error messages\n * - Cache to minimize API calls\n */\n\nimport type { TtlCache } from './cache-with-ttl'\nimport { createTtlCache } from './cache-with-ttl'\nimport { httpRequest } from './http-request'\nimport type { SpawnOptions } from './spawn'\nimport { spawn } from './spawn'\n\n// GitHub API base URL constant (inlined for coverage mode compatibility).\nconst GITHUB_API_BASE_URL = 'https://api.github.com'\n\n// 5 minutes.\nconst DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000\n\n// Create TTL cache instance for GitHub ref resolution.\n// Uses cacache for persistent storage with in-memory memoization.\nlet _githubCache: TtlCache | undefined\n\n/**\n * Get or create the GitHub cache instance.\n */\nfunction getGithubCache(): TtlCache {\n  if (_githubCache === undefined) {\n    _githubCache = createTtlCache({\n      memoize: true,\n      prefix: 'github-refs',\n      ttl: DEFAULT_CACHE_TTL_MS,\n    })\n  }\n  return _githubCache\n}\n\nexport interface GitHubFetchOptions {\n  token?: string | undefined\n  headers?: Record<string, string> | undefined\n}\n\nexport interface GitHubRateLimitError extends Error {\n  status: number\n  resetTime?: Date | undefined\n}\n\n/**\n * Get GitHub token from environment variables.\n */\nexport function getGitHubToken(): string | undefined {\n  const { env } = process\n  return (\n    env['GITHUB_TOKEN'] ||\n    env['GH_TOKEN'] ||\n    env['SOCKET_CLI_GITHUB_TOKEN'] ||\n    undefined\n  )\n}\n\n/**\n * Fetch data from GitHub API with rate limit handling.\n */\nexport async function fetchGitHub<T = unknown>(\n  url: string,\n  options?: GitHubFetchOptions | undefined,\n): Promise<T> {\n  const opts = { __proto__: null, ...options } as GitHubFetchOptions\n  const token = opts.token || getGitHubToken()\n\n  const headers: Record<string, string> = {\n    Accept: 'application/vnd.github.v3+json',\n    'User-Agent': 'socket-registry-github-client',\n    ...opts.headers,\n  }\n\n  if (token) {\n    headers['Authorization'] = `Bearer ${token}`\n  }\n\n  const response = await httpRequest(url, { headers })\n\n  if (!response.ok) {\n    if (response.status === 403) {\n      const rateLimit = response.headers['x-ratelimit-remaining']\n      const rateLimitStr =\n        typeof rateLimit === 'string' ? rateLimit : rateLimit?.[0]\n      if (rateLimitStr === '0') {\n        const resetTime = response.headers['x-ratelimit-reset']\n        const resetTimeStr =\n          typeof resetTime === 'string' ? resetTime : resetTime?.[0]\n        const resetDate = resetTimeStr\n          ? new Date(Number(resetTimeStr) * 1000)\n          : undefined\n        const error = new Error(\n          `GitHub API rate limit exceeded${resetDate ? `. Resets at ${resetDate.toLocaleString()}` : ''}. Use GITHUB_TOKEN environment variable to increase rate limit.`,\n        ) as GitHubRateLimitError\n        error.status = 403\n        error.resetTime = resetDate\n        throw error\n      }\n    }\n    throw new Error(\n      `GitHub API error ${response.status}: ${response.statusText}`,\n    )\n  }\n\n  return JSON.parse(response.body.toString('utf8')) as T\n}\n\nexport interface GitHubRef {\n  object: {\n    sha: string\n    type: string\n    url: string\n  }\n  ref: string\n  url: string\n}\n\nexport interface GitHubTag {\n  message: string\n  object: {\n    sha: string\n    type: string\n    url: string\n  }\n  sha: string\n  tag: string\n  tagger?: {\n    date: string\n    email: string\n    name: string\n  }\n  url: string\n}\n\nexport interface GitHubCommit {\n  sha: string\n  url: string\n  commit: {\n    message: string\n    author: {\n      date: string\n      email: string\n      name: string\n    }\n  }\n}\n\nexport interface ResolveRefOptions {\n  token?: string | undefined\n}\n\n/**\n * Resolve a git ref (tag, branch, or commit SHA) to its full commit SHA.\n * Results are cached in-memory and on disk (with TTL) to minimize API calls.\n */\nexport async function resolveRefToSha(\n  owner: string,\n  repo: string,\n  ref: string,\n  options?: ResolveRefOptions | undefined,\n): Promise<string> {\n  const opts = {\n    __proto__: null,\n    ...options,\n  } as ResolveRefOptions\n\n  const cacheKey = `${owner}/${repo}@${ref}`\n\n  // Optionally disable cache.\n  if (process.env['DISABLE_GITHUB_CACHE']) {\n    return await fetchRefSha(owner, repo, ref, opts)\n  }\n\n  // Use TTL cache for persistent storage and in-memory memoization.\n  const cache = getGithubCache()\n  return await cache.getOrFetch(cacheKey, async () => {\n    return await fetchRefSha(owner, repo, ref, opts)\n  })\n}\n\n/**\n * Fetch the SHA for a git ref from GitHub API.\n */\nasync function fetchRefSha(\n  owner: string,\n  repo: string,\n  ref: string,\n  options: ResolveRefOptions,\n): Promise<string> {\n  const fetchOptions: GitHubFetchOptions = {\n    token: options.token,\n  }\n\n  try {\n    // Try as a tag first.\n    const tagUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/tags/${ref}`\n    const tagData = await fetchGitHub<GitHubRef>(tagUrl, fetchOptions)\n\n    // Tag might point to a tag object or directly to a commit.\n    if (tagData.object.type === 'tag') {\n      // Dereference the tag object to get the commit.\n      const tagObject = await fetchGitHub<GitHubTag>(\n        tagData.object.url,\n        fetchOptions,\n      )\n      return tagObject.object.sha\n    }\n    return tagData.object.sha\n  } catch {\n    // Not a tag, try as a branch.\n    try {\n      const branchUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/heads/${ref}`\n      const branchData = await fetchGitHub<GitHubRef>(branchUrl, fetchOptions)\n      return branchData.object.sha\n    } catch {\n      // Try without refs/ prefix (for commit SHAs or other refs).\n      try {\n        const commitUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/commits/${ref}`\n        const commitData = await fetchGitHub<GitHubCommit>(\n          commitUrl,\n          fetchOptions,\n        )\n        return commitData.sha\n      } catch (e) {\n        throw new Error(\n          `failed to resolve ref \"${ref}\" for ${owner}/${repo}: ${e instanceof Error ? e.message : String(e)}`,\n        )\n      }\n    }\n  }\n}\n\n/**\n * Clear the ref resolution cache (in-memory only).\n */\nexport async function clearRefCache(): Promise<void> {\n  if (_githubCache) {\n    await _githubCache.clear({ memoOnly: true })\n  }\n}\n\n/**\n * Get GitHub token from git config if not in environment.\n * Falls back to checking git config for github.token.\n */\nexport async function getGitHubTokenFromGitConfig(\n  options?: SpawnOptions,\n): Promise<string | undefined> {\n  try {\n    const result = await spawn('git', ['config', 'github.token'], {\n      ...options,\n      stdio: 'pipe',\n    })\n    if (result.code === 0 && result.stdout) {\n      return result.stdout.toString().trim()\n    }\n  } catch {\n    // Ignore errors - git config may not have token.\n  }\n  return undefined\n}\n\n/**\n * Get GitHub token from all available sources.\n * Checks environment variables first, then git config.\n */\nexport async function getGitHubTokenWithFallback(): Promise<\n  string | undefined\n> {\n  return getGitHubToken() || (await getGitHubTokenFromGitConfig())\n}\n\n// GHSA (GitHub Security Advisory) types and utilities.\nexport interface GhsaDetails {\n  ghsaId: string\n  summary: string\n  details: string\n  severity: string\n  aliases: string[]\n  publishedAt: string\n  updatedAt: string\n  withdrawnAt: string | null\n  references: Array<{ url: string }>\n  vulnerabilities: Array<{\n    package: {\n      ecosystem: string\n      name: string\n    }\n    vulnerableVersionRange: string\n    firstPatchedVersion: { identifier: string } | null\n  }>\n  cvss: {\n    score: number\n    vectorString: string\n  } | null\n  cwes: Array<{\n    cweId: string\n    name: string\n    description: string\n  }>\n}\n\n/**\n * Generate GitHub Security Advisory URL from GHSA ID.\n */\nexport function getGhsaUrl(ghsaId: string): string {\n  return `https://github.com/advisories/${ghsaId}`\n}\n\n/**\n * Fetch GitHub Security Advisory details.\n */\nexport async function fetchGhsaDetails(\n  ghsaId: string,\n  options?: GitHubFetchOptions,\n): Promise<GhsaDetails> {\n  const url = `https://api.github.com/advisories/${ghsaId}`\n  const data = await fetchGitHub<{\n    aliases?: string[]\n    cvss: unknown\n    cwes?: Array<{ cweId: string; name: string; description: string }>\n    details: string\n    ghsa_id: string\n    published_at: string\n    references?: Array<{ url: string }>\n    severity: string\n    summary: string\n    updated_at: string\n    vulnerabilities?: Array<{\n      package: { ecosystem: string; name: string }\n      vulnerableVersionRange: string\n      firstPatchedVersion: { identifier: string } | null\n    }>\n    withdrawn_at: string\n  }>(url, options)\n\n  return {\n    ghsaId: data.ghsa_id,\n    summary: data.summary,\n    details: data.details,\n    severity: data.severity,\n    aliases: data.aliases || [],\n    publishedAt: data.published_at,\n    updatedAt: data.updated_at,\n    withdrawnAt: data.withdrawn_at,\n    references: data.references || [],\n    vulnerabilities: data.vulnerabilities || [],\n    cvss: data.cvss as { score: number; vectorString: string } | null,\n    cwes: data.cwes || [],\n  }\n}\n\n/**\n * Cached fetch for GHSA details.\n */\nexport async function cacheFetchGhsa(\n  ghsaId: string,\n  options?: GitHubFetchOptions,\n): Promise<GhsaDetails> {\n  const cache = getGithubCache()\n  const key = `ghsa:${ghsaId}`\n\n  // Check cache first.\n  if (!process.env['DISABLE_GITHUB_CACHE']) {\n    const cached = await cache.get(key)\n    if (cached) {\n      return JSON.parse(cached as string) as GhsaDetails\n    }\n  }\n\n  // Fetch and cache.\n  const data = await fetchGhsaDetails(ghsaId, options)\n  await cache.set(key, JSON.stringify(data))\n  return data\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * @fileoverview GitHub utilities for Socket projects.\n * Provides GitHub API integration for repository operations.\n *\n * Authentication:\n * - getGitHubToken: Retrieve GitHub token from environment variables\n * - fetchGitHub: Authenticated GitHub API requests with rate limit handling\n *\n * Ref Resolution:\n * - resolveRefToSha: Convert tags/branches to commit SHAs (with memoization and persistent cache)\n * - clearRefCache: Clear the in-memory memoization cache\n *\n * Caching:\n * - Uses cacache for persistent storage with in-memory memoization\n * - Two-tier caching: in-memory (Map) for hot data, persistent (cacache) for durability\n * - Default TTL: 5 minutes\n * - Disable with DISABLE_GITHUB_CACHE env var\n *\n * Rate Limiting:\n * - Automatic rate limit detection and error messages\n * - Cache to minimize API calls\n */\n\nimport type { TtlCache } from './cache-with-ttl'\nimport { createTtlCache } from './cache-with-ttl'\nimport { httpRequest } from './http-request'\nimport type { SpawnOptions } from './spawn'\nimport { spawn } from './spawn'\n\n// GitHub API base URL constant (inlined for coverage mode compatibility).\nconst GITHUB_API_BASE_URL = 'https://api.github.com'\n\n// 5 minutes.\nconst DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000\n\n// Create TTL cache instance for GitHub ref resolution.\n// Uses cacache for persistent storage with in-memory memoization.\nlet _githubCache: TtlCache | undefined\n\n/**\n * Get or create the GitHub cache instance.\n * Lazy initializes the cache with default TTL and memoization enabled.\n * Used internally for caching GitHub API responses.\n *\n * @returns The singleton cache instance\n */\nfunction getGithubCache(): TtlCache {\n  if (_githubCache === undefined) {\n    _githubCache = createTtlCache({\n      memoize: true,\n      prefix: 'github-refs',\n      ttl: DEFAULT_CACHE_TTL_MS,\n    })\n  }\n  return _githubCache\n}\n\n/**\n * Options for GitHub API fetch requests.\n */\nexport interface GitHubFetchOptions {\n  /**\n   * GitHub authentication token.\n   * If not provided, will attempt to use token from environment variables.\n   */\n  token?: string | undefined\n  /**\n   * Additional HTTP headers to include in the request.\n   * Will be merged with default headers (Accept, User-Agent, Authorization).\n   */\n  headers?: Record<string, string> | undefined\n}\n\n/**\n * Error thrown when GitHub API rate limit is exceeded.\n * Extends the standard Error with additional rate limit information.\n */\nexport interface GitHubRateLimitError extends Error {\n  /** HTTP status code (always 403 for rate limit errors) */\n  status: number\n  /**\n   * Date when the rate limit will reset.\n   * Undefined if reset time is not available in response headers.\n   */\n  resetTime?: Date | undefined\n}\n\n/**\n * Get GitHub authentication token from environment variables.\n * Checks multiple environment variable names in priority order.\n *\n * Environment variables checked (in order):\n * 1. `GITHUB_TOKEN` - Standard GitHub token variable\n * 2. `GH_TOKEN` - Alternative GitHub CLI token variable\n * 3. `SOCKET_CLI_GITHUB_TOKEN` - Socket-specific token variable\n *\n * @returns The first available GitHub token, or `undefined` if none found\n *\n * @example\n * ```ts\n * const token = getGitHubToken()\n * if (!token) {\n *   console.warn('No GitHub token found')\n * }\n * ```\n */\nexport function getGitHubToken(): string | undefined {\n  const { env } = process\n  return (\n    env['GITHUB_TOKEN'] ||\n    env['GH_TOKEN'] ||\n    env['SOCKET_CLI_GITHUB_TOKEN'] ||\n    undefined\n  )\n}\n\n/**\n * Fetch data from GitHub API with automatic authentication and rate limit handling.\n * Makes authenticated requests to the GitHub REST API with proper error handling.\n *\n * Features:\n * - Automatic token injection from environment if not provided\n * - Rate limit detection with helpful error messages\n * - Standard GitHub API headers (Accept, User-Agent)\n * - JSON response parsing\n *\n * @template T - Expected response type (defaults to `unknown`)\n * @param url - Full GitHub API URL (e.g., 'https://api.github.com/repos/owner/repo')\n * @param options - Fetch options including token and custom headers\n * @returns Parsed JSON response of type `T`\n *\n * @throws {GitHubRateLimitError} When API rate limit is exceeded (status 403)\n * @throws {Error} For other API errors with status code and message\n *\n * @example\n * ```ts\n * // Fetch repository information\n * interface Repo {\n *   name: string\n *   full_name: string\n *   default_branch: string\n * }\n * const repo = await fetchGitHub<Repo>(\n *   'https://api.github.com/repos/owner/repo'\n * )\n * console.log(`Default branch: ${repo.default_branch}`)\n * ```\n *\n * @example\n * ```ts\n * // With custom token and headers\n * const data = await fetchGitHub(\n *   'https://api.github.com/user',\n *   {\n *     token: 'ghp_customtoken',\n *     headers: { 'X-Custom-Header': 'value' }\n *   }\n * )\n * ```\n *\n * @example\n * ```ts\n * // Handle rate limit errors\n * try {\n *   await fetchGitHub('https://api.github.com/repos/owner/repo')\n * } catch (error) {\n *   if (error.status === 403 && error.resetTime) {\n *     console.error(`Rate limited until ${error.resetTime}`)\n *   }\n * }\n * ```\n */\nexport async function fetchGitHub<T = unknown>(\n  url: string,\n  options?: GitHubFetchOptions | undefined,\n): Promise<T> {\n  const opts = { __proto__: null, ...options } as GitHubFetchOptions\n  const token = opts.token || getGitHubToken()\n\n  const headers: Record<string, string> = {\n    Accept: 'application/vnd.github.v3+json',\n    'User-Agent': 'socket-registry-github-client',\n    ...opts.headers,\n  }\n\n  if (token) {\n    headers['Authorization'] = `Bearer ${token}`\n  }\n\n  const response = await httpRequest(url, { headers })\n\n  if (!response.ok) {\n    if (response.status === 403) {\n      const rateLimit = response.headers['x-ratelimit-remaining']\n      const rateLimitStr =\n        typeof rateLimit === 'string' ? rateLimit : rateLimit?.[0]\n      if (rateLimitStr === '0') {\n        const resetTime = response.headers['x-ratelimit-reset']\n        const resetTimeStr =\n          typeof resetTime === 'string' ? resetTime : resetTime?.[0]\n        const resetDate = resetTimeStr\n          ? new Date(Number(resetTimeStr) * 1000)\n          : undefined\n        const error = new Error(\n          `GitHub API rate limit exceeded${resetDate ? `. Resets at ${resetDate.toLocaleString()}` : ''}. Use GITHUB_TOKEN environment variable to increase rate limit.`,\n        ) as GitHubRateLimitError\n        error.status = 403\n        error.resetTime = resetDate\n        throw error\n      }\n    }\n    throw new Error(\n      `GitHub API error ${response.status}: ${response.statusText}`,\n    )\n  }\n\n  return JSON.parse(response.body.toString('utf8')) as T\n}\n\n/**\n * GitHub ref object returned by the API.\n * Represents a git reference (tag or branch).\n */\nexport interface GitHubRef {\n  /** The object this ref points to */\n  object: {\n    /** SHA of the commit or tag object */\n    sha: string\n    /** Type of object ('commit' or 'tag') */\n    type: string\n    /** API URL to fetch the full object details */\n    url: string\n  }\n  /** Full ref path (e.g., 'refs/tags/v1.0.0' or 'refs/heads/main') */\n  ref: string\n  /** API URL for this ref */\n  url: string\n}\n\n/**\n * GitHub annotated tag object returned by the API.\n * Represents a git tag with metadata.\n */\nexport interface GitHubTag {\n  /** Tag annotation message */\n  message: string\n  /** The commit this tag points to */\n  object: {\n    /** SHA of the commit */\n    sha: string\n    /** Type of object (usually 'commit') */\n    type: string\n    /** API URL to fetch the commit details */\n    url: string\n  }\n  /** SHA of this tag object itself */\n  sha: string\n  /** Tag name (e.g., 'v1.0.0') */\n  tag: string\n  /**\n   * Information about who created the tag.\n   * Undefined for lightweight tags.\n   */\n  tagger?: {\n    /** Tag creation date in ISO 8601 format */\n    date: string\n    /** Tagger's email address */\n    email: string\n    /** Tagger's name */\n    name: string\n  }\n  /** API URL for this tag object */\n  url: string\n}\n\n/**\n * GitHub commit object returned by the API.\n * Represents a git commit with metadata.\n */\nexport interface GitHubCommit {\n  /** Full commit SHA */\n  sha: string\n  /** API URL for this commit */\n  url: string\n  /** Commit details */\n  commit: {\n    /** Commit message */\n    message: string\n    /** Author information */\n    author: {\n      /** Commit author date in ISO 8601 format */\n      date: string\n      /** Author's email address */\n      email: string\n      /** Author's name */\n      name: string\n    }\n  }\n}\n\n/**\n * Options for resolving git refs to commit SHAs.\n */\nexport interface ResolveRefOptions {\n  /**\n   * GitHub authentication token.\n   * If not provided, will attempt to use token from environment variables.\n   */\n  token?: string | undefined\n}\n\n/**\n * Resolve a git ref (tag, branch, or commit SHA) to its full commit SHA.\n * Handles tags (annotated and lightweight), branches, and commit SHAs.\n * Results are cached in-memory and on disk (with TTL) to minimize API calls.\n *\n * Resolution strategy:\n * 1. Try as a tag (refs/tags/{ref})\n * 2. If tag is annotated, dereference to get the commit SHA\n * 3. If not a tag, try as a branch (refs/heads/{ref})\n * 4. If not a branch, try as a commit SHA directly\n *\n * Caching behavior:\n * - In-memory cache (Map) for immediate lookups\n * - Persistent disk cache (cacache) for durability across runs\n * - Default TTL: 5 minutes\n * - Disable caching with `DISABLE_GITHUB_CACHE` env var\n *\n * @param owner - Repository owner (user or organization name)\n * @param repo - Repository name\n * @param ref - Git reference to resolve (tag name, branch name, or commit SHA)\n * @param options - Resolution options including authentication token\n * @returns The full commit SHA (40-character hex string)\n *\n * @throws {Error} When ref cannot be resolved after trying all strategies\n * @throws {GitHubRateLimitError} When API rate limit is exceeded\n *\n * @example\n * ```ts\n * // Resolve a tag to commit SHA\n * const sha = await resolveRefToSha('owner', 'repo', 'v1.0.0')\n * console.log(sha) // 'a1b2c3d4e5f6...'\n * ```\n *\n * @example\n * ```ts\n * // Resolve a branch to latest commit SHA\n * const sha = await resolveRefToSha('owner', 'repo', 'main')\n * console.log(sha) // Latest commit on main branch\n * ```\n *\n * @example\n * ```ts\n * // Resolve with custom token\n * const sha = await resolveRefToSha(\n *   'owner',\n *   'repo',\n *   'develop',\n *   { token: 'ghp_customtoken' }\n * )\n * ```\n *\n * @example\n * ```ts\n * // Commit SHA passes through unchanged (but validates it exists)\n * const sha = await resolveRefToSha('owner', 'repo', 'a1b2c3d4')\n * console.log(sha) // Full 40-char SHA\n * ```\n */\nexport async function resolveRefToSha(\n  owner: string,\n  repo: string,\n  ref: string,\n  options?: ResolveRefOptions | undefined,\n): Promise<string> {\n  const opts = {\n    __proto__: null,\n    ...options,\n  } as ResolveRefOptions\n\n  const cacheKey = `${owner}/${repo}@${ref}`\n\n  // Optionally disable cache.\n  if (process.env['DISABLE_GITHUB_CACHE']) {\n    return await fetchRefSha(owner, repo, ref, opts)\n  }\n\n  // Use TTL cache for persistent storage and in-memory memoization.\n  const cache = getGithubCache()\n  return await cache.getOrFetch(cacheKey, async () => {\n    return await fetchRefSha(owner, repo, ref, opts)\n  })\n}\n\n/**\n * Fetch the SHA for a git ref from GitHub API.\n * Internal helper that implements the multi-strategy ref resolution logic.\n * Tries tags, branches, and direct commit lookups in sequence.\n *\n * @param owner - Repository owner\n * @param repo - Repository name\n * @param ref - Git reference to resolve\n * @param options - Resolution options with authentication token\n * @returns The full commit SHA\n *\n * @throws {Error} When ref cannot be resolved after all strategies fail\n */\nasync function fetchRefSha(\n  owner: string,\n  repo: string,\n  ref: string,\n  options: ResolveRefOptions,\n): Promise<string> {\n  const fetchOptions: GitHubFetchOptions = {\n    token: options.token,\n  }\n\n  try {\n    // Try as a tag first.\n    const tagUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/tags/${ref}`\n    const tagData = await fetchGitHub<GitHubRef>(tagUrl, fetchOptions)\n\n    // Tag might point to a tag object or directly to a commit.\n    if (tagData.object.type === 'tag') {\n      // Dereference the tag object to get the commit.\n      const tagObject = await fetchGitHub<GitHubTag>(\n        tagData.object.url,\n        fetchOptions,\n      )\n      return tagObject.object.sha\n    }\n    return tagData.object.sha\n  } catch {\n    // Not a tag, try as a branch.\n    try {\n      const branchUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/git/refs/heads/${ref}`\n      const branchData = await fetchGitHub<GitHubRef>(branchUrl, fetchOptions)\n      return branchData.object.sha\n    } catch {\n      // Try without refs/ prefix (for commit SHAs or other refs).\n      try {\n        const commitUrl = `${GITHUB_API_BASE_URL}/repos/${owner}/${repo}/commits/${ref}`\n        const commitData = await fetchGitHub<GitHubCommit>(\n          commitUrl,\n          fetchOptions,\n        )\n        return commitData.sha\n      } catch (e) {\n        throw new Error(\n          `failed to resolve ref \"${ref}\" for ${owner}/${repo}: ${e instanceof Error ? e.message : String(e)}`,\n        )\n      }\n    }\n  }\n}\n\n/**\n * Clear the ref resolution cache (in-memory only).\n * Clears the in-memory memoization cache without affecting the persistent disk cache.\n * Useful for testing or when you need fresh data from the API.\n *\n * Note: This only clears the in-memory cache. The persistent cacache storage\n * remains intact and will be used to rebuild the in-memory cache on next access.\n *\n * @returns Promise that resolves when cache is cleared\n *\n * @example\n * ```ts\n * // Clear cache to force fresh API calls\n * await clearRefCache()\n * const sha = await resolveRefToSha('owner', 'repo', 'main')\n * // This will hit the persistent cache or API, not in-memory cache\n * ```\n */\nexport async function clearRefCache(): Promise<void> {\n  if (_githubCache) {\n    await _githubCache.clear({ memoOnly: true })\n  }\n}\n\n/**\n * Get GitHub authentication token from git config.\n * Reads the `github.token` configuration value from git config.\n * This is a fallback method when environment variables don't contain a token.\n *\n * @param options - Spawn options for git command execution\n * @returns GitHub token from git config, or `undefined` if not configured\n *\n * @example\n * ```ts\n * const token = await getGitHubTokenFromGitConfig()\n * if (token) {\n *   console.log('Found token in git config')\n * }\n * ```\n *\n * @example\n * ```ts\n * // With custom working directory\n * const token = await getGitHubTokenFromGitConfig({\n *   cwd: '/path/to/repo'\n * })\n * ```\n */\nexport async function getGitHubTokenFromGitConfig(\n  options?: SpawnOptions | undefined,\n): Promise<string | undefined> {\n  try {\n    const result = await spawn('git', ['config', 'github.token'], {\n      ...options,\n      stdio: 'pipe',\n    })\n    if (result.code === 0 && result.stdout) {\n      return result.stdout.toString().trim()\n    }\n  } catch {\n    // Ignore errors - git config may not have token.\n  }\n  return undefined\n}\n\n/**\n * Get GitHub authentication token from all available sources.\n * Checks environment variables first, then falls back to git config.\n * This is the recommended way to get a GitHub token with maximum compatibility.\n *\n * Priority order:\n * 1. Environment variables (GITHUB_TOKEN, GH_TOKEN, SOCKET_CLI_GITHUB_TOKEN)\n * 2. Git config (github.token)\n *\n * @returns GitHub token from first available source, or `undefined` if none found\n *\n * @example\n * ```ts\n * const token = await getGitHubTokenWithFallback()\n * if (!token) {\n *   throw new Error('GitHub token required')\n * }\n * ```\n */\nexport async function getGitHubTokenWithFallback(): Promise<\n  string | undefined\n> {\n  return getGitHubToken() || (await getGitHubTokenFromGitConfig())\n}\n\n/**\n * GitHub Security Advisory (GHSA) details.\n * Represents a complete security advisory from GitHub's database.\n */\nexport interface GhsaDetails {\n  /** GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz') */\n  ghsaId: string\n  /** Short summary of the vulnerability */\n  summary: string\n  /** Detailed description of the vulnerability */\n  details: string\n  /** Severity level ('low', 'moderate', 'high', 'critical') */\n  severity: string\n  /** Alternative identifiers (CVE IDs, etc.) */\n  aliases: string[]\n  /** ISO 8601 timestamp when advisory was published */\n  publishedAt: string\n  /** ISO 8601 timestamp when advisory was last updated */\n  updatedAt: string\n  /**\n   * ISO 8601 timestamp when advisory was withdrawn.\n   * `null` if advisory is still active.\n   */\n  withdrawnAt: string | null\n  /** External reference URLs for more information */\n  references: Array<{ url: string }>\n  /** Affected packages and version ranges */\n  vulnerabilities: Array<{\n    /** Package information */\n    package: {\n      /** Ecosystem (e.g., 'npm', 'pip', 'maven') */\n      ecosystem: string\n      /** Package name */\n      name: string\n    }\n    /** Version range expression for vulnerable versions */\n    vulnerableVersionRange: string\n    /**\n     * First patched version that fixes the vulnerability.\n     * `null` if no patched version exists yet.\n     */\n    firstPatchedVersion: { identifier: string } | null\n  }>\n  /**\n   * CVSS (Common Vulnerability Scoring System) information.\n   * `null` if CVSS score is not available.\n   */\n  cvss: {\n    /** CVSS score (0.0-10.0) */\n    score: number\n    /** CVSS vector string describing the vulnerability characteristics */\n    vectorString: string\n  } | null\n  /** CWE (Common Weakness Enumeration) categories */\n  cwes: Array<{\n    /** CWE identifier (e.g., 'CWE-79') */\n    cweId: string\n    /** Human-readable CWE name */\n    name: string\n    /** Description of the weakness category */\n    description: string\n  }>\n}\n\n/**\n * Generate GitHub Security Advisory URL from GHSA ID.\n * Constructs the public advisory URL for a given GHSA identifier.\n *\n * @param ghsaId - GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz')\n * @returns Full URL to the advisory page\n *\n * @example\n * ```ts\n * const url = getGhsaUrl('GHSA-1234-5678-90ab')\n * console.log(url) // 'https://github.com/advisories/GHSA-1234-5678-90ab'\n * ```\n */\nexport function getGhsaUrl(ghsaId: string): string {\n  return `https://github.com/advisories/${ghsaId}`\n}\n\n/**\n * Fetch GitHub Security Advisory details from the API.\n * Retrieves complete advisory information including severity, affected packages,\n * CVSS scores, and CWE classifications.\n *\n * @param ghsaId - GHSA identifier to fetch (e.g., 'GHSA-xxxx-yyyy-zzzz')\n * @param options - Fetch options including authentication token\n * @returns Complete advisory details with normalized field names\n *\n * @throws {Error} If advisory cannot be found or API request fails\n * @throws {GitHubRateLimitError} When API rate limit is exceeded\n *\n * @example\n * ```ts\n * const advisory = await fetchGhsaDetails('GHSA-1234-5678-90ab')\n * console.log(`Severity: ${advisory.severity}`)\n * console.log(`Affects: ${advisory.vulnerabilities.length} packages`)\n * if (advisory.cvss) {\n *   console.log(`CVSS Score: ${advisory.cvss.score}`)\n * }\n * ```\n *\n * @example\n * ```ts\n * // Check if vulnerability is patched\n * const advisory = await fetchGhsaDetails('GHSA-xxxx-yyyy-zzzz')\n * for (const vuln of advisory.vulnerabilities) {\n *   if (vuln.firstPatchedVersion) {\n *     console.log(\n *       `Patched in ${vuln.package.name}@${vuln.firstPatchedVersion.identifier}`\n *     )\n *   }\n * }\n * ```\n */\nexport async function fetchGhsaDetails(\n  ghsaId: string,\n  options?: GitHubFetchOptions | undefined,\n): Promise<GhsaDetails> {\n  const url = `https://api.github.com/advisories/${ghsaId}`\n  const data = await fetchGitHub<{\n    aliases?: string[]\n    cvss: unknown\n    cwes?: Array<{ cweId: string; name: string; description: string }>\n    details: string\n    ghsa_id: string\n    published_at: string\n    references?: Array<{ url: string }>\n    severity: string\n    summary: string\n    updated_at: string\n    vulnerabilities?: Array<{\n      package: { ecosystem: string; name: string }\n      vulnerableVersionRange: string\n      firstPatchedVersion: { identifier: string } | null\n    }>\n    withdrawn_at: string\n  }>(url, options)\n\n  return {\n    ghsaId: data.ghsa_id,\n    summary: data.summary,\n    details: data.details,\n    severity: data.severity,\n    aliases: data.aliases || [],\n    publishedAt: data.published_at,\n    updatedAt: data.updated_at,\n    withdrawnAt: data.withdrawn_at,\n    references: data.references || [],\n    vulnerabilities: data.vulnerabilities || [],\n    cvss: data.cvss as { score: number; vectorString: string } | null,\n    cwes: data.cwes || [],\n  }\n}\n\n/**\n * Fetch GitHub Security Advisory details with caching.\n * Retrieves advisory information with two-tier caching (in-memory + persistent).\n * Cached results are stored with the default TTL (5 minutes).\n *\n * Caching behavior:\n * - Checks in-memory cache first for immediate response\n * - Falls back to persistent disk cache if not in memory\n * - Fetches from API only if not cached\n * - Stores result in both cache tiers\n * - Respects `DISABLE_GITHUB_CACHE` env var\n *\n * @param ghsaId - GHSA identifier to fetch\n * @param options - Fetch options including authentication token\n * @returns Complete advisory details\n *\n * @throws {Error} If advisory cannot be found or API request fails\n * @throws {GitHubRateLimitError} When API rate limit is exceeded\n *\n * @example\n * ```ts\n * // First call hits API\n * const advisory = await cacheFetchGhsa('GHSA-1234-5678-90ab')\n *\n * // Second call within 5 minutes returns cached data\n * const cached = await cacheFetchGhsa('GHSA-1234-5678-90ab')\n * ```\n *\n * @example\n * ```ts\n * // Disable caching for fresh data\n * process.env.DISABLE_GITHUB_CACHE = '1'\n * const advisory = await cacheFetchGhsa('GHSA-xxxx-yyyy-zzzz')\n * ```\n */\nexport async function cacheFetchGhsa(\n  ghsaId: string,\n  options?: GitHubFetchOptions | undefined,\n): Promise<GhsaDetails> {\n  const cache = getGithubCache()\n  const key = `ghsa:${ghsaId}`\n\n  // Check cache first.\n  if (!process.env['DISABLE_GITHUB_CACHE']) {\n    const cached = await cache.get(key)\n    if (cached) {\n      return JSON.parse(cached as string) as GhsaDetails\n    }\n  }\n\n  // Fetch and cache.\n  const data = await fetchGhsaDetails(ghsaId, options)\n  await cache.set(key, JSON.stringify(data))\n  return data\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/http-request.d.ts

@@ -1,53 +1,512 @@
+/**
+ * Configuration options for HTTP/HTTPS requests.
+ */
 export interface HttpRequestOptions {
+    /**
+     * Request body to send.
+     * Can be a string (e.g., JSON) or Buffer (e.g., binary data).
+     *
+     * @example
+     * ```ts
+     * // Send JSON data
+     * await httpRequest('https://api.example.com/data', {
+     *   method: 'POST',
+     *   body: JSON.stringify({ name: 'Alice' }),
+     *   headers: { 'Content-Type': 'application/json' }
+     * })
+     *
+     * // Send binary data
+     * const buffer = Buffer.from([0x00, 0x01, 0x02])
+     * await httpRequest('https://api.example.com/upload', {
+     *   method: 'POST',
+     *   body: buffer
+     * })
+     * ```
+     */
     body?: Buffer | string | undefined;
+    /**
+     * Whether to automatically follow HTTP redirects (3xx status codes).
+     *
+     * @default true
+     *
+     * @example
+     * ```ts
+     * // Follow redirects (default)
+     * await httpRequest('https://example.com/redirect')
+     *
+     * // Don't follow redirects
+     * const response = await httpRequest('https://example.com/redirect', {
+     *   followRedirects: false
+     * })
+     * console.log(response.status) // 301 or 302
+     * ```
+     */
     followRedirects?: boolean | undefined;
+    /**
+     * HTTP headers to send with the request.
+     * A `User-Agent` header is automatically added if not provided.
+     *
+     * @example
+     * ```ts
+     * await httpRequest('https://api.example.com/data', {
+     *   headers: {
+     *     'Authorization': 'Bearer token123',
+     *     'Content-Type': 'application/json',
+     *     'Accept': 'application/json'
+     *   }
+     * })
+     * ```
+     */
     headers?: Record<string, string> | undefined;
+    /**
+     * Maximum number of redirects to follow before throwing an error.
+     * Only relevant when `followRedirects` is `true`.
+     *
+     * @default 5
+     *
+     * @example
+     * ```ts
+     * // Allow up to 10 redirects
+     * await httpRequest('https://example.com/many-redirects', {
+     *   maxRedirects: 10
+     * })
+     * ```
+     */
     maxRedirects?: number | undefined;
+    /**
+     * HTTP method to use for the request.
+     *
+     * @default 'GET'
+     *
+     * @example
+     * ```ts
+     * // GET request (default)
+     * await httpRequest('https://api.example.com/data')
+     *
+     * // POST request
+     * await httpRequest('https://api.example.com/data', {
+     *   method: 'POST',
+     *   body: JSON.stringify({ name: 'Alice' })
+     * })
+     *
+     * // DELETE request
+     * await httpRequest('https://api.example.com/data/123', {
+     *   method: 'DELETE'
+     * })
+     * ```
+     */
     method?: string | undefined;
+    /**
+     * Number of retry attempts for failed requests.
+     * Uses exponential backoff: delay = `retryDelay` * 2^attempt.
+     *
+     * @default 0
+     *
+     * @example
+     * ```ts
+     * // Retry up to 3 times with exponential backoff
+     * await httpRequest('https://api.example.com/data', {
+     *   retries: 3,
+     *   retryDelay: 1000 // 1s, then 2s, then 4s
+     * })
+     * ```
+     */
     retries?: number | undefined;
+    /**
+     * Initial delay in milliseconds before first retry.
+     * Subsequent retries use exponential backoff.
+     *
+     * @default 1000
+     *
+     * @example
+     * ```ts
+     * // Start with 2 second delay, then 4s, 8s, etc.
+     * await httpRequest('https://api.example.com/data', {
+     *   retries: 3,
+     *   retryDelay: 2000
+     * })
+     * ```
+     */
     retryDelay?: number | undefined;
+    /**
+     * Request timeout in milliseconds.
+     * If the request takes longer than this, it will be aborted.
+     *
+     * @default 30000
+     *
+     * @example
+     * ```ts
+     * // 60 second timeout
+     * await httpRequest('https://api.example.com/slow-endpoint', {
+     *   timeout: 60000
+     * })
+     * ```
+     */
     timeout?: number | undefined;
 }
+/**
+ * HTTP response object with fetch-like interface.
+ * Provides multiple ways to access the response body.
+ */
 export interface HttpResponse {
+    /**
+     * Get response body as ArrayBuffer.
+     * Useful for binary data or when you need compatibility with browser APIs.
+     *
+     * @returns The response body as an ArrayBuffer
+     *
+     * @example
+     * ```ts
+     * const response = await httpRequest('https://example.com/image.png')
+     * const arrayBuffer = response.arrayBuffer()
+     * console.log(arrayBuffer.byteLength)
+     * ```
+     */
     arrayBuffer(): ArrayBuffer;
+    /**
+     * Raw response body as Buffer.
+     * Direct access to the underlying Node.js Buffer.
+     *
+     * @example
+     * ```ts
+     * const response = await httpRequest('https://example.com/data')
+     * console.log(response.body.length) // Size in bytes
+     * console.log(response.body.toString('hex')) // View as hex
+     * ```
+     */
     body: Buffer;
+    /**
+     * HTTP response headers.
+     * Keys are lowercase header names, values can be strings or string arrays.
+     *
+     * @example
+     * ```ts
+     * const response = await httpRequest('https://example.com')
+     * console.log(response.headers['content-type'])
+     * console.log(response.headers['set-cookie']) // May be string[]
+     * ```
+     */
     headers: Record<string, string | string[] | undefined>;
+    /**
+     * Parse response body as JSON.
+     * Type parameter `T` allows specifying the expected JSON structure.
+     *
+     * @template T - Expected JSON type (defaults to `unknown`)
+     * @returns Parsed JSON data
+     * @throws {SyntaxError} When response body is not valid JSON
+     *
+     * @example
+     * ```ts
+     * interface User { name: string; id: number }
+     * const response = await httpRequest('https://api.example.com/user')
+     * const user = response.json<User>()
+     * console.log(user.name, user.id)
+     * ```
+     */
     json<T = unknown>(): T;
+    /**
+     * Whether the request was successful (status code 200-299).
+     *
+     * @example
+     * ```ts
+     * const response = await httpRequest('https://example.com/data')
+     * if (response.ok) {
+     *   console.log('Success:', response.json())
+     * } else {
+     *   console.error('Failed:', response.status, response.statusText)
+     * }
+     * ```
+     */
     ok: boolean;
+    /**
+     * HTTP status code (e.g., 200, 404, 500).
+     *
+     * @example
+     * ```ts
+     * const response = await httpRequest('https://example.com')
+     * console.log(response.status) // 200, 404, etc.
+     * ```
+     */
     status: number;
+    /**
+     * HTTP status message (e.g., "OK", "Not Found", "Internal Server Error").
+     *
+     * @example
+     * ```ts
+     * const response = await httpRequest('https://example.com')
+     * console.log(response.statusText) // "OK"
+     * ```
+     */
     statusText: string;
+    /**
+     * Get response body as UTF-8 text string.
+     *
+     * @returns The response body as a string
+     *
+     * @example
+     * ```ts
+     * const response = await httpRequest('https://example.com')
+     * const html = response.text()
+     * console.log(html.includes('<html>'))
+     * ```
+     */
     text(): string;
 }
+/**
+ * Configuration options for file downloads.
+ */
 export interface HttpDownloadOptions {
+    /**
+     * HTTP headers to send with the download request.
+     * A `User-Agent` header is automatically added if not provided.
+     *
+     * @example
+     * ```ts
+     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *   headers: {
+     *     'Authorization': 'Bearer token123'
+     *   }
+     * })
+     * ```
+     */
     headers?: Record<string, string> | undefined;
+    /**
+     * Callback for tracking download progress.
+     * Called periodically as data is received.
+     *
+     * @param downloaded - Number of bytes downloaded so far
+     * @param total - Total file size in bytes (from Content-Length header)
+     *
+     * @example
+     * ```ts
+     * await httpDownload('https://example.com/large-file.zip', '/tmp/file.zip', {
+     *   onProgress: (downloaded, total) => {
+     *     const percent = ((downloaded / total) * 100).toFixed(1)
+     *     console.log(`Progress: ${percent}%`)
+     *   }
+     * })
+     * ```
+     */
     onProgress?: ((downloaded: number, total: number) => void) | undefined;
+    /**
+     * Number of retry attempts for failed downloads.
+     * Uses exponential backoff: delay = `retryDelay` * 2^attempt.
+     *
+     * @default 0
+     *
+     * @example
+     * ```ts
+     * // Retry up to 3 times for unreliable connections
+     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *   retries: 3,
+     *   retryDelay: 2000
+     * })
+     * ```
+     */
     retries?: number | undefined;
+    /**
+     * Initial delay in milliseconds before first retry.
+     * Subsequent retries use exponential backoff.
+     *
+     * @default 1000
+     */
     retryDelay?: number | undefined;
+    /**
+     * Download timeout in milliseconds.
+     * If the download takes longer than this, it will be aborted.
+     *
+     * @default 120000
+     *
+     * @example
+     * ```ts
+     * // 5 minute timeout for large files
+     * await httpDownload('https://example.com/huge-file.zip', '/tmp/file.zip', {
+     *   timeout: 300000
+     * })
+     * ```
+     */
     timeout?: number | undefined;
 }
+/**
+ * Result of a successful file download.
+ */
 export interface HttpDownloadResult {
+    /**
+     * Absolute path where the file was saved.
+     *
+     * @example
+     * ```ts
+     * const result = await httpDownload('https://example.com/file.zip', '/tmp/file.zip')
+     * console.log(`Downloaded to: ${result.path}`)
+     * ```
+     */
     path: string;
+    /**
+     * Total size of downloaded file in bytes.
+     *
+     * @example
+     * ```ts
+     * const result = await httpDownload('https://example.com/file.zip', '/tmp/file.zip')
+     * console.log(`Downloaded ${result.size} bytes`)
+     * ```
+     */
     size: number;
 }
 /**
  * Make an HTTP/HTTPS request with retry logic and redirect support.
  * Provides a fetch-like API using Node.js native http/https modules.
- * @throws {Error} When all retries are exhausted or non-retryable error occurs.
+ *
+ * This is the main entry point for making HTTP requests. It handles retries,
+ * redirects, timeouts, and provides a fetch-compatible response interface.
+ *
+ * @param url - The URL to request (must start with http:// or https://)
+ * @param options - Request configuration options
+ * @returns Promise resolving to response object with `.json()`, `.text()`, etc.
+ * @throws {Error} When all retries are exhausted, timeout occurs, or non-retryable error happens
+ *
+ * @example
+ * ```ts
+ * // Simple GET request
+ * const response = await httpRequest('https://api.example.com/data')
+ * const data = response.json()
+ *
+ * // POST with JSON body
+ * const response = await httpRequest('https://api.example.com/users', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' })
+ * })
+ *
+ * // With retries and timeout
+ * const response = await httpRequest('https://api.example.com/data', {
+ *   retries: 3,
+ *   retryDelay: 1000,
+ *   timeout: 60000
+ * })
+ *
+ * // Don't follow redirects
+ * const response = await httpRequest('https://example.com/redirect', {
+ *   followRedirects: false
+ * })
+ * console.log(response.status) // 301, 302, etc.
+ * ```
  */
 export declare function httpRequest(url: string, options?: HttpRequestOptions | undefined): Promise<HttpResponse>;
 /**
  * Download a file from a URL to a local path with retry logic and progress callbacks.
  * Uses streaming to avoid loading entire file in memory.
- * @throws {Error} When all retries are exhausted or download fails.
+ *
+ * The download is streamed directly to disk, making it memory-efficient even for
+ * large files. Progress callbacks allow for real-time download status updates.
+ *
+ * @param url - The URL to download from (must start with http:// or https://)
+ * @param destPath - Absolute path where the file should be saved
+ * @param options - Download configuration options
+ * @returns Promise resolving to download result with path and size
+ * @throws {Error} When all retries are exhausted, download fails, or file cannot be written
+ *
+ * @example
+ * ```ts
+ * // Simple download
+ * const result = await httpDownload(
+ *   'https://example.com/file.zip',
+ *   '/tmp/file.zip'
+ * )
+ * console.log(`Downloaded ${result.size} bytes to ${result.path}`)
+ *
+ * // With progress tracking
+ * await httpDownload(
+ *   'https://example.com/large-file.zip',
+ *   '/tmp/file.zip',
+ *   {
+ *     onProgress: (downloaded, total) => {
+ *       const percent = ((downloaded / total) * 100).toFixed(1)
+ *       console.log(`Progress: ${percent}% (${downloaded}/${total} bytes)`)
+ *     }
+ *   }
+ * )
+ *
+ * // With retries and custom timeout
+ * await httpDownload(
+ *   'https://example.com/file.zip',
+ *   '/tmp/file.zip',
+ *   {
+ *     retries: 3,
+ *     retryDelay: 2000,
+ *     timeout: 300000, // 5 minutes
+ *     headers: { 'Authorization': 'Bearer token123' }
+ *   }
+ * )
+ * ```
  */
 export declare function httpDownload(url: string, destPath: string, options?: HttpDownloadOptions | undefined): Promise<HttpDownloadResult>;
 /**
  * Perform a GET request and parse JSON response.
- * @throws {Error} When request fails or JSON parsing fails.
+ * Convenience wrapper around `httpRequest` for common JSON API calls.
+ *
+ * @template T - Expected JSON response type (defaults to `unknown`)
+ * @param url - The URL to request (must start with http:// or https://)
+ * @param options - Request configuration options
+ * @returns Promise resolving to parsed JSON data
+ * @throws {Error} When request fails, response is not ok (status < 200 or >= 300), or JSON parsing fails
+ *
+ * @example
+ * ```ts
+ * // Simple JSON GET
+ * const data = await httpGetJson('https://api.example.com/data')
+ * console.log(data)
+ *
+ * // With type safety
+ * interface User { id: number; name: string; email: string }
+ * const user = await httpGetJson<User>('https://api.example.com/user/123')
+ * console.log(user.name, user.email)
+ *
+ * // With custom headers
+ * const data = await httpGetJson('https://api.example.com/data', {
+ *   headers: {
+ *     'Authorization': 'Bearer token123',
+ *     'Accept': 'application/json'
+ *   }
+ * })
+ *
+ * // With retries
+ * const data = await httpGetJson('https://api.example.com/data', {
+ *   retries: 3,
+ *   retryDelay: 1000
+ * })
+ * ```
  */
 export declare function httpGetJson<T = unknown>(url: string, options?: HttpRequestOptions | undefined): Promise<T>;
 /**
  * Perform a GET request and return text response.
- * @throws {Error} When request fails.
+ * Convenience wrapper around `httpRequest` for fetching text content.
+ *
+ * @param url - The URL to request (must start with http:// or https://)
+ * @param options - Request configuration options
+ * @returns Promise resolving to response body as UTF-8 string
+ * @throws {Error} When request fails or response is not ok (status < 200 or >= 300)
+ *
+ * @example
+ * ```ts
+ * // Fetch HTML
+ * const html = await httpGetText('https://example.com')
+ * console.log(html.includes('<!DOCTYPE html>'))
+ *
+ * // Fetch plain text
+ * const text = await httpGetText('https://example.com/file.txt')
+ * console.log(text)
+ *
+ * // With custom headers
+ * const text = await httpGetText('https://example.com/data.txt', {
+ *   headers: {
+ *     'Authorization': 'Bearer token123'
+ *   }
+ * })
+ *
+ * // With timeout
+ * const text = await httpGetText('https://example.com/large-file.txt', {
+ *   timeout: 60000 // 1 minute
+ * })
+ * ```
  */
 export declare function httpGetText(url: string, options?: HttpRequestOptions | undefined): Promise<string>;