circle-client

library0.2.4jsnpmunverified

The `circle-client` package provides a JavaScript and TypeScript client for interacting with the CircleCI v2 API. It allows developers to programmatically manage CI/CD pipelines, retrieve workflow and job insights, manage contexts and environment variables, and access user and project details. Currently at version `0.2.4`, the library is in a pre-1.0 development phase, which implies that minor versions may introduce breaking changes. It ships with comprehensive TypeScript definitions, offering a strongly-typed interface for API interactions, which significantly enhances developer experience and reduces common API-related errors. Key differentiators include its direct mapping of CircleCI v2 API endpoints to client methods, simplified handling of paginated results through a `Paged<T>` object, and a focus on abstracting the underlying HTTP request complexities, making it easier to integrate CircleCI operations into Node.js applications.

devops http-networking

npm install circle-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CIRCLE-CLIENT

circle-client

devopsjavascriptv0.2.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CircleCI

✓ import CircleCI from 'circle-client';

✗ const CircleCI = require('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

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

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

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

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();

Debug

Known issues

gotchaAs 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.

affects: >=0.1.0

deprecatedCertain 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.

affects: >=0.1.0

gotchaAll 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.

affects: >=0.1.0

gotchaCircleCI 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.

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined

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

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']

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']`.

Upgrade

Version history

0.2.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jodyheavener/circle-client ↗

packagehttps://www.npmjs.com/package/circle-client ↗

homepagehttps://circleci.com ↗