{"id":16784,"library":"circle-client","title":"CircleCI API Client","description":"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.","status":"active","version":"0.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/jodyheavener/circle-client","tags":["javascript","circleci","circle","api","client","ci","cd","rest","typescript"],"install":[{"cmd":"npm install circle-client","lang":"bash","label":"npm"},{"cmd":"yarn add circle-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add circle-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const CircleCI = require('circle-client');","symbol":"CircleCI","correct":"import CircleCI from 'circle-client';"},{"note":"While `CircleCI` is a default export, specific types like `Paged`, `Workflow`, and `Pipeline` are exposed as named exports, enhancing type safety in TypeScript projects.","symbol":"All Types","correct":"import CircleCI, { Paged, Workflow, Pipeline } from 'circle-client';"},{"note":"The `slug` option expects an array of strings `['vcs', 'owner', 'repo']`, not a single concatenated string, for clarity and type safety.","wrong":"const client = new CircleCI(token, 'github/owner/repo');","symbol":"Configuration options","correct":"import CircleCI from 'circle-client';\nconst client = new CircleCI(token, { slug: ['github', 'owner', 'repo'], branch: 'main' });"}],"quickstart":{"code":"import CircleCI from 'circle-client';\n\n// Get your CircleCI API token from https://app.circleci.com/settings/user/tokens\nconst CIRCLECI_API_TOKEN = process.env.CIRCLECI_API_TOKEN ?? 'YOUR_SECRET_TOKEN_HERE';\n\nif (CIRCLECI_API_TOKEN === 'YOUR_SECRET_TOKEN_HERE') {\n  console.warn('Please set the CIRCLECI_API_TOKEN environment variable or replace the placeholder.');\n}\n\nasync function runExample() {\n  try {\n    const client = new CircleCI(CIRCLECI_API_TOKEN, {\n      slug: ['github', 'jodyheavener', 'circle-client'], // Replace with your actual project slug\n      branch: 'main',\n    });\n\n    console.log('Fetching current user details...');\n    const me = await client.getMe();\n    console.log('Logged in as:', me.name);\n\n    console.log('Listing recent pipelines for the project...');\n    const pipelinesPage = await client.listProjectPipelines({\n      projectSlug: ['github', 'jodyheavener', 'circle-client'] // Required for this method\n    });\n    console.log(`Found ${pipelinesPage.items.length} pipelines. Latest:`, pipelinesPage.items[0]?.id);\n\n    if (pipelinesPage.next_page_token) {\n      console.log('More pipelines available. Next page token:', pipelinesPage.next_page_token);\n    }\n\n  } catch (error) {\n    console.error('An error occurred:', error instanceof Error ? error.message : String(error));\n  }\n}\n\nrunExample();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Always pin to exact versions (e.g., `\"circle-client\": \"0.2.4\"`) and review the changelog carefully when updating to new minor versions.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Store API tokens securely using environment variables (`process.env`), secret management services, or encrypted configuration files. Never hardcode tokens in your application code.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: require is not defined"},{"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.","cause":"Incorrectly handling the structure of paginated API responses or accessing properties on potentially undefined objects.","error":"TypeError: Cannot read properties of undefined (reading 'name') or similar for API response data"},{"fix":"Convert your project slug string into the specified array format: `slug: ['github', '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.","error":"Error: Invalid project slug format. Expected an array like ['vcs', 'owner', 'repo']"}],"ecosystem":"npm","meta_description":null}