CircleCI API Client

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in a pure ESM or ES Module-aware Node.js environment where `circle-client` is treated as an ESM module.
  fix Update your import statements to use ES Module syntax: `import CircleCI from 'circle-client';`. Ensure your `package.json` specifies `"type": "module"` if you are running pure ESM in Node.js, or use a transpiler like Babel or TypeScript.

• TypeError: Cannot read properties of undefined (reading 'name') or similar for API response data

  cause Incorrectly handling the structure of paginated API responses or accessing properties on potentially undefined objects.
  fix Remember that `list` methods return a `Paged<T>` object; access results via `response.items`. Always add optional chaining (`?.`) or null checks (`if (item)`) when accessing properties of API response objects, as certain fields might be optional or absent.

• Error: Invalid project slug format. Expected an array like ['vcs', 'owner', 'repo']

  cause Providing the `slug` option in the client constructor or a method as a single string (e.g., 'github/owner/repo') instead of the required array format.
  fix Convert your project slug string into the specified array format: `slug: ['github', 'owner', 'repo']`.

Warnings

• gotcha As a pre-1.0 release (`0.2.4`), any minor version increment (e.g., `0.2.x` to `0.3.0`) may introduce breaking changes without strictly adhering to semantic versioning until a stable 1.0 release.
  Fix: Always pin to exact versions (e.g., `"circle-client": "0.2.4"`) and review the changelog carefully when updating to new minor versions.
• deprecated Certain API endpoints, such as those related to 'User' and 'Job' details, are marked as 'Preview' by CircleCI itself. These endpoints may change or be removed without prior warning, as indicated in the CircleCI API documentation.
  Fix: Exercise caution when building critical functionality on 'Preview' endpoints. Monitor the official CircleCI API documentation for updates and be prepared for potential breaking changes.
• gotcha All methods beginning with `list` (e.g., `listContexts`, `listProjectPipelines`) return a `Paged<T>` object, not directly an array of items. Developers must access the `items` property for results and check `next_page_token` for pagination.
  Fix: Ensure your code explicitly accesses `pagedResult.items` to get the array of results and handles `pagedResult.next_page_token` for iterative fetching of subsequent pages.
• gotcha CircleCI API Tokens grant extensive permissions. Exposing them in client-side code, checking them into version control, or using them insecurely can lead to unauthorized access to your CircleCI projects.
  Fix: Store API tokens securely using environment variables (`process.env`), secret management services, or encrypted configuration files. Never hardcode tokens in your application code.

Install

• npm install circle-client npm
• yarn add circle-client yarn
• pnpm add circle-client pnpm

Imports

• CircleCI
  wrong:

  const CircleCI = require('circle-client');

  correct:

  import CircleCI from 'circle-client';

  The primary `CircleCI` class is exported as a default export, making it primarily designed for ESM consumption. CommonJS `require` will likely not work as expected or require a transpilation step.
• All Types

  import CircleCI, { Paged, Workflow, Pipeline } from 'circle-client';

  While `CircleCI` is a default export, specific types like `Paged`, `Workflow`, and `Pipeline` are exposed as named exports, enhancing type safety in TypeScript projects.
• Configuration options
  wrong:

  const client = new CircleCI(token, 'github/owner/repo');

  correct:

  import CircleCI from 'circle-client';
  const client = new CircleCI(token, { slug: ['github', 'owner', 'repo'], branch: 'main' });

  The `slug` option expects an array of strings `['vcs', 'owner', 'repo']`, not a single concatenated string, for clarity and type safety.

Quickstart

This quickstart initializes the CircleCI client using an API token and demonstrates fetching the current user's details and listing recent project pipelines. It highlights the use of `process.env` for secure token handling and shows how to interact with paginated results.

import CircleCI from 'circle-client';

// Get your CircleCI API token from https://app.circleci.com/settings/user/tokens
const CIRCLECI_API_TOKEN = process.env.CIRCLECI_API_TOKEN ?? 'YOUR_SECRET_TOKEN_HERE';

if (CIRCLECI_API_TOKEN === 'YOUR_SECRET_TOKEN_HERE') {
  console.warn('Please set the CIRCLECI_API_TOKEN environment variable or replace the placeholder.');
}

async function runExample() {
  try {
    const client = new CircleCI(CIRCLECI_API_TOKEN, {
      slug: ['github', 'jodyheavener', 'circle-client'], // Replace with your actual project slug
      branch: 'main',
    });

    console.log('Fetching current user details...');
    const me = await client.getMe();
    console.log('Logged in as:', me.name);

    console.log('Listing recent pipelines for the project...');
    const pipelinesPage = await client.listProjectPipelines({
      projectSlug: ['github', 'jodyheavener', 'circle-client'] // Required for this method
    });
    console.log(`Found ${pipelinesPage.items.length} pipelines. Latest:`, pipelinesPage.items[0]?.id);

    if (pipelinesPage.next_page_token) {
      console.log('More pipelines available. Next page token:', pipelinesPage.next_page_token);
    }

  } catch (error) {
    console.error('An error occurred:', error instanceof Error ? error.message : String(error));
  }
}

runExample();