All Projects → worldturtlemedia → circleci-api

worldturtlemedia / circleci-api

Licence: MIT license
Wrapper for CircleCI API for web, node, and written in TypeScript

Programming Languages

typescript
32286 projects

Projects that are alternatives of or similar to circleci-api

Express Webpack React Redux Typescript Boilerplate
🎉 A full-stack boilerplate that using express with webpack, react and typescirpt!
Stars: ✭ 156 (+642.86%)
Mutual labels:  circleci
Dockerspec
A small Ruby Gem to run RSpec and Serverspec, Infrataster and Capybara tests against Dockerfiles or Docker images easily.
Stars: ✭ 181 (+761.9%)
Mutual labels:  circleci
Buefy Shop
A sample shop built with Nuxt, Stripe, Firebase and Serverless Functions
Stars: ✭ 207 (+885.71%)
Mutual labels:  circleci
Vue People
VuePeople lists and connects Vue.JS developers around the world.
Stars: ✭ 167 (+695.24%)
Mutual labels:  circleci
Android Kotlin Modulerized Cleanarchitecture
🚀 Example modularized android application with single activity written in Kotlin
Stars: ✭ 180 (+757.14%)
Mutual labels:  circleci
Promu
Prometheus Utility Tool
Stars: ✭ 186 (+785.71%)
Mutual labels:  circleci
Cypress Example Todomvc
The official TodoMVC tests written in Cypress.
Stars: ✭ 143 (+580.95%)
Mutual labels:  circleci
Build Harness
🤖Collection of Makefiles to facilitate building Golang projects, Dockerfiles, Helm charts, and more
Stars: ✭ 236 (+1023.81%)
Mutual labels:  circleci
Env Ci
Get environment variables exposed by CI services
Stars: ✭ 180 (+757.14%)
Mutual labels:  circleci
Circleci Monorepo
An example of monorepo with CircleCI using conditional workflows and pipeline parameters.
Stars: ✭ 205 (+876.19%)
Mutual labels:  circleci
Nevergreen
🐤 A build monitor with attitude
Stars: ✭ 170 (+709.52%)
Mutual labels:  circleci
Testen
✔️ Run tests for multiple versions of Node.js in local env.
Stars: ✭ 176 (+738.1%)
Mutual labels:  circleci
Pupernetes
Spin up a full fledged Kubernetes environment designed for local development & CI
Stars: ✭ 199 (+847.62%)
Mutual labels:  circleci
Cistern
A terminal UI for Unix to monitor Continuous Integration pipelines from the command line. Current integrations include GitLab, Azure DevOps, Travis CI, AppVeyor and CircleCI.
Stars: ✭ 161 (+666.67%)
Mutual labels:  circleci
Unity3d Gitlab Ci Example Mirror
🍴Mirror of the gableroux/unity3d-gitlab-ci-example project for Travis and CircleCI on Github. If you are looking for Github Actions, refer to https://github.com/game-ci/unity-actions-example instead.
Stars: ✭ 210 (+900%)
Mutual labels:  circleci
Hugo Resume
A Hugo theme ported from startbootrap.com's resume template
Stars: ✭ 145 (+590.48%)
Mutual labels:  circleci
Tox
Command line driven CI frontend and development task automation tool.
Stars: ✭ 2,523 (+11914.29%)
Mutual labels:  circleci
Rok8s Scripts
Opinionated scripts for managing application deployment lifecycle in Kubernetes
Stars: ✭ 248 (+1080.95%)
Mutual labels:  circleci
Circleci Demo React Native
A demo React Native project that’s building on CircleCI 2.0 with Workflows
Stars: ✭ 212 (+909.52%)
Mutual labels:  circleci
Android Mvp Architecture
🏛 A basic sample android application to understand MVP in a very simple way. Just clone, build, run and understand MVP.
Stars: ✭ 203 (+866.67%)
Mutual labels:  circleci

CircleCi API Client

A Node and Browser client for the CircleCI API, written in TypeScript.

CircleCI branch CircleCI (all branches) Coverage Status

npm version Downloads npm bundle size License

Renovate enabled

API wrapper for CircleCi API, usable in node and the browser. If used in a TypeScript project, you will get types, and auto-complete for all of the api responses. You will no longer need to tab back and fourth to the API documentation.

I recommend using this library if you are writing a tool or website in TypeScript. I have created definitions for each of the CircleCI endpoints. There may still be some errors, but I am open to contributions on making them better.

If there are any features you would like, please feel free to open up an issue.

Notes

Types

I did my best to correctly add types for all of the supported endpoints. However if you notice an incorrect payload type, or some missing properties, please open up an issue, or submit a pull request.

CircleCI API v2

CircleCI is going to be rolling out a new version of their api (see here). Currently this library does not support v2, but I will update it in the future, see #228 for updates.

Migrating from v3 to v4

There have been some breaking changes, please see MIGRATING.md for more info.

Installation

Add using yarn or npm

yarn add circleci-api

## or

npm install circleci-api

Usage

Get your API token from CircleCi

There are two ways to use this library.

1. CircleCi class

Get instance of the factory.

// Module
import { CircleCI, GitType, CircleCIOptions } from "circleci-api";

// Configure the factory with some defaults
const options: CircleCIOptions = {
  // Required for all requests
  token: "", // Set your CircleCi API token

  // Optional
  // Anything set here can be overriden when making the request

  // Git information is required for project/build/etc endpoints
  vcs: {
    type: GitType.GITHUB, // default: github
    owner: "worldturtlemedia",
    repo: "circleci-api"
  }

  // Optional query params for requests
  options: {
    branch: "master", // default: master
    filter: "completed"
  }
}

// Create the api object
const api = new CircleCI(options)

// Use the api

/**
 * Grab the latest artifacts from a successful build on a certain branch
 * @param [branch="master"] - Artifacts for certain branch
 * @return List of successfully built artifact objects
 */
export async function getLatestArtifacts(branch: string = "master"): Promise<Artifact[]> {
  try {
    // Will use the repo defined in the options above
    const result: Aritfact[] = await api.latestArtifacts({ branch, filter: "successful" })
    console.log(`Found ${result.length} artifacts`)
    return result
  } catch (error) {
    console.log("No build artifacts found")
  }

  return []
}

getLatestArtifacts("develop")
  .then(artifacts => {
    artifacts
      .forEach(({ path, url }: Artifact) => console.log(`${path} -> ${url}`))
  })

// Or override settings set above
api
  .latestArtifacts(
    { branch: "develop" },
    {
      vcs: { repo: "awesome-repo" },
      options: { filter: "successful" }
    }
  )
  .then((artifacts: Artifact[]) => console.log(`Found ${artifacts.length} artifacts`))
  .catch(error => console.error(error))

2. Manually

The individual functions can also be imported if you only need one or two. To help with tree-shaking.

import { getMe, getLatestArtifacts } from "circleci-api";

const CIRCLECI_TOKEN: string = "circle-ci-token";

getMe(CIRCLECI_TOKEN)
  .then(me => console.log("token is valid"))
  .catch(error => console.error("invalid token"));

getLatestArtifacts(CIRCLECI_TOKEN, {
  vcs: {
    owner: "billyBob",
    repo: "super-cool-app"
  },
  options: {
    filter: "failed",
    branch: "feature-smith2"
  }
})
  .then(result => console.log(`Found ${result.length} artifacts`))
  .catch(error => console.error(error));

Self-hosted CircleCI

To override the default API base url https://circleci.com/api/v1.1, you can pass a circleHost to the CircleCI constructor, or to the standalone functions.

// Using the CircleCi class
new CircleCI({
  token: "my-token",
  vcs: { owner: "worldturtlemedia", repo = "circleci-api" },
  circleHost: "https://my-selfhosted-circleci.com/"
}).getLatestArtifacts()

// Using the standalone functions
getLatestArtifacts("my-token", {
  ...
  circleHost: "https://my-selfhosted-circleci.com/"
})

While all of the standalone functions support a custom circleHost property. Using the CircleCI class you must specify it in the constructor.

Demo

There are three similar demos are available in the demo folder.

Note: I recommend VSCode for viewing and editing the examples. It will give you great intellisense about the library.

For the TypeScript & JavaScript follow the steps below:

# Step 1 - Change into demo folder and install dependencies
cd demo
yarn

# Javascript example:
node ./index.js

# Typescript example:
npx ts-node --project ../tsconfig.base.json ./index.ts

# To view Browser example, first build project
yarn build

# Then open `index.html` in your browser

Supported endpoints

Using factory:

Optional properties:

export interface CircleRequest {
  token?: string;
  vcs?: GitInfo;
  options?: Options;
}

Any function with an optional paramater of CircleRequest can override any of the values you assigned when using the circleci() factory.

Name Required Optional Returns
me() none none Me
projects() none CircleRequest Project[]
followProject() { vcs: GitInfo } none FollowNewResult
recentBuilds() none { limit: number, offset: number } BuildSummary[]
builds() none { limit: number, offset: number } BuildSummary[]
buildsFor() branch: string = "master" { limit: number, offset: number } BuildSummary[]
build() buildNumber: number CircleRequest BuildWithSteps
artifacts() buildNumber: number CircleRequest Artifact[]
latestArtifacts() none CircleRequest Artifact[]
retry() buildNumber: number CircleRequest BuildSummary
cancel() buildNumber: number CircleRequest BuildSummary
triggerBuild() none CircleRequest Build
triggerBuildFor() branch: string = "master" CircleRequest Build
clearCache() none CircleRequest ClearCacheResponse
listEnvVars() none CircleRequest EnvVariable[]
addEnvVar() variable: EnvVariable CircleRequest EnvVariable
getEnvVar() envName: string CircleRequest EnvVariable
deleteEnvVar() envName: string CircleRequest MessageResponse
checkoutKeys() none CircleRequest CheckoutKeyResponse
createCheckoutKey() type: CheckoutType CircleRequest CheckoutKeyResponse
checkoutKey() fingerprint: string CircleRequest CheckoutKeyResponse
deleteCheckoutKey() fingerprint: string CircleRequest DeleteCheckoutKeyResponse
getTestMetadata() buildNumber: number CircleRequest TestMetadataResponse
addSSHKey() key: SSHKey CircleRequest none
addHerokuKey() key: HerokuKey CircleRequest none

Missing endpoint

The last remaining endpoint probably won't be added unless there is demand.

Name Link
Add user to build ref

Contributing

See CONTRIBUTING.

License

MIT License

Copyright (c) 2019 WorldTurtleMedia

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].