GitHub API Utilities

Common errors

• ERR_REQUIRE_ESM: require() of ES Module [path_to_ghutils] not supported.

  cause Attempting to use `ghutils` (v5+) with CommonJS `require()` syntax in a CommonJS module or environment.
  fix Change `const { ghget } = require('ghutils');` to `import { ghget } from 'ghutils';`. Ensure your `package.json` has `"type": "module"` or your file uses the `.mjs` extension.

• TypeError: ghget is not a function

  cause Incorrectly importing named exports, such as attempting a default import when `ghget` is a named export, or attempting to access it on a module object when it's a direct named export.
  fix Ensure you are using named import syntax: `import { ghget } from 'ghutils';`. Do not use `import ghget from 'ghutils';` or `import * as ghutils from 'ghutils'; const ghget = ghutils.ghget;` unless you specifically intend to access it from the module object.

• Error: Not Found (or similar 404/401/403 HTTP error from GitHub API)

  cause The provided GitHub API URL is incorrect, the token lacks sufficient permissions (403 Forbidden), or the token is invalid/expired (401 Unauthorized).
  fix Double-check the URL against GitHub API documentation. Verify your GitHub Personal Access Token has the necessary scopes (e.g., `repo`, `public_repo`, `user`) for the specific API endpoint being called. Regenerate or update your token if necessary.

• ReferenceError: fetch is not defined

  cause Running `ghutils` in a Node.js environment older than v18, which does not natively support the global `fetch` API, or in an environment where `fetch` is not polyfilled. ghutils v5 requires Node.js >= 20.
  fix Upgrade your Node.js runtime to version 20 or newer. `ghutils` v5+ specifically targets Node.js >= 20, which includes native `fetch`.

Warnings

• breaking Version 5.0.0 is a major breaking change, converting the library to ES Modules (ESM) only. CommonJS `require()` is no longer supported and will cause a `ERR_REQUIRE_ESM` error.
  Fix: Migrate your project to use ES Modules `import` syntax. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions. For mixed environments, consider a tool like `cjstoesm` or dynamic `import()` for ESM-only modules.
• breaking All API methods (`ghget`, `ghpost`, `lister`, etc.) now exclusively return Promises. Callback-based patterns from previous major versions are removed.
  Fix: Update your code to use `await` with `async` functions or `.then().catch()` chains to handle asynchronous operations and retrieve results.
• breaking The minimum required Node.js version is now 20. Running `ghutils` on older Node.js versions may lead to errors, particularly related to the native `fetch` API.
  Fix: Upgrade your Node.js environment to version 20 or newer. Consider using a version manager like `nvm` to manage multiple Node.js versions.
• gotcha Authentication requires an `auth` object with a `token` property, e.g., `{ token: 'your-github-token' }`. Incorrect or missing tokens will result in GitHub API authentication failures, often with HTTP 401 or 403 status codes.
  Fix: Ensure your `auth` object is correctly structured and contains a valid GitHub Personal Access Token. Verify the token has the necessary scopes for the API operations you are performing. Consider using `ghauth` for robust token management.
• gotcha The `lister` function for paginated results accepts `afterDate` as a `Date` object, and other options (like `state`, `per_page`) are passed directly as query parameters. Misunderstanding these options can lead to unexpected filtering or pagination behavior.
  Fix: Consult the `lister` API documentation to ensure correct usage of options. For `afterDate`, pass a `Date` object. For query parameters, ensure they match GitHub API specifications (e.g., `per_page` maximum is 100).

Install

• npm install ghutils npm
• yarn add ghutils yarn
• pnpm add ghutils pnpm

Imports

• ghget
  wrong:

  const ghget = require('ghutils').ghget

  correct:

  import { ghget } from 'ghutils'

  ghutils is ESM-only since v5; CommonJS require() will result in an error. All methods return Promises.
• lister
  wrong:

  import lister from 'ghutils'

  correct:

  import { lister } from 'ghutils'

  lister is a named export, not the default export. Attempting to import it as a default will fail. It returns a Promise.
• ghpost
  wrong:

  import * as ghutils from 'ghutils'; const { ghpost } = ghutils;

  correct:

  import { ghpost } from 'ghutils'

  Destructuring directly from the named export is the idiomatic way. ghpost also returns a Promise.
• apiRoot

  import { apiRoot } from 'ghutils'

  apiRoot is a string constant, not a function.

Quickstart

Demonstrates authenticating with a GitHub token, making a single GET request for user data, and listing paginated issues from a repository using `ghget` and `lister`.

import { ghget, lister } from 'ghutils';

const auth = { token: process.env.GITHUB_TOKEN ?? '' };

if (!auth.token) {
  console.error('Please set the GITHUB_TOKEN environment variable.');
  process.exit(1);
}

async function main() {
  try {
    // Make a single GET request to fetch the authenticated user's profile
    const { data: user } = await ghget(auth, 'https://api.github.com/user');
    console.log('Authenticated User:', user.login);

    // List all open issues from a specific repository
    const issues = await lister(auth, 'https://api.github.com/repos/rvagg/ghutils/issues', {
      state: 'open',
      per_page: 100 // Example: fetch 100 items per page
    });
    console.log(`Found ${issues.length} open issues in rvagg/ghutils.`);
    if (issues.length > 0) {
      console.log('First issue title:', issues[0].title);
    }
  } catch (error) {
    console.error('Error interacting with GitHub API:', error.message);
  }
}

main();