checkpoint-client

javascript checkpoint client

Usage no npm install needed!

<script type="module">
  import checkpointClient from 'https://cdn.skypack.dev/checkpoint-client';
</script>

README

TypeScript Checkpoint Client npm

A TypeScript Checkpoint client for a Checkpoint Server. Checkpoint provides version information and security alerts for your products.

import checkpoint from 'checkpoint-client'

checkpoint.check({
  product: 'prisma',
  version: '2.0.0',
})

Features

  • No impact on the developer experience of your CLI
  • Easily hook into any product
  • Bring your own styles

Install

npm install checkpoint-client

API

checkpoint.check(input: Input): Promise<Result>

Check for the latest version and inform the user of any security notices.

await checkpoint.check({
  product: 'prisma',
  version: '2.0.0',
})

Input

Field Attributes Description
product string, required Name of the product. Current we only support prisma.
version string, required Currently installed version of the product (e.g. 1.0.0-rc0)
cli_path_hash string, required A unique hash of the path in which the CLI is installed
project_hash string, required A unique hash of the project's path, i.e.. the schema.prisma's path
disable boolean, required Disable checking for an update if it's not already cached. Useful for CI.
endpoint string, optional Checkpoint server endpoint URL. Defaults to https://checkpoint.prisma.io.
timeout number, optional Time in milliseconds we should wait for a response before giving up.
arch string, optional Client's operating system architecture (e.g. amd64).
os string, optional Client's operating system (e.g. darwin).
node_version string, optional Client's node version (e.g. v12.12.0).
signature string, optional Random, non-identifiable signature to ensure alerts aren't repeated.
cache_file string, optional File where we store the response for the cache_duration.
cache_duration number, optional Time in milliseconds to store the response. Defaults to 12 hours.
remind_duration number, optional Time in milliseconds to wait for a new reminder. Defaults to 48 hours.
force boolean, optional Force a check regardless of disable or CHECKPOINT_DISABLE.
unref boolean, optional Control when we should unreference the child. Use with care.
cli_install_type string, optional 'local' or 'global'

Result

The result's shape changes depending on the status:

status: "ok" and status: "reminded"

The ok status occurs when we our cached result is available and valid.

type Result = {
  status: 'ok'
  data: Output
}

The reminded status occurs when we recently checked the cache. This status is influenced by the remind_duration.

type Result = {
  status: 'reminded'
  data: Output
}

In both cases, the Output has the following shape:

Field Attributes Description
product string, required Product we're checking on.
current_version string, required Latest version of the product.
current_release_date number, required Release date of the latest version in Unix time.
current_download_url string, required URL to download the latest version.
current_changelog_url string, required URL to the latest version's changelog.
project_website string, required Website for the project.
outdated boolean, required True if the our version is outdated.
alerts[] Alert[], required New security alerts or notices for this version.
.id string, required ID of the alert.
.date string, required Date of the alert in Unix time.
.message string, required Alert message.
.url string, optional URL for more information about the alert.
.level string, required Severity of the alert.
status: "waiting"

The waiting status occurs when we don't have the cached result and we're requesting it from the checkpoint server.

type Result = {
  status: 'waiting'
  data: ChildProcess
}

If you like, you can pass unref: false as input and wait for the ChildProcess to exit. The child process prints out the Output to stdout. You can see an example in check-version.

status: "disabled"

The disabled status occurs when we've explicitly disabled this service. The most common case for this is in CI.

type Result = {
  status: 'disabled'
}

You can see an example for this in is-ci.

Environment variables

Field Attributes Description
CHECKPOINT_DISABLE string, optional Disable the checkpoint client
CHECKPOINT_TIMEOUT string, optional Globally set timeout for our checkpoint client

Clearing the Cache

// macOS
ls ~/Library/Caches/checkpoint-nodejs
rm -rf ~/Library/Caches/checkpoint-nodejs

// Windows
C:\Users\Jan\AppData\Local\checkpoint-nodejs

// Linux
$XDG_CACHE_HOME/checkpoint-nodejs
Or
$HOME - /home/.cache/checkpoint-nodejs

Examples

You can use ts-node to run the examples:

npm install
npm run build
node dist/examples/is-ci.js

Publishing a new Version

  1. Pull latest changes from GitHub
  2. Bump the package version
  3. Update the History.md. We recommend git-changelog. Run git changelog --tag 1.1.XX
  4. Run npm publish
  5. Run git commit -am "Release <version>"
  6. Run git tag <version>
  7. Run git push --tags origin master

You can automate steps 5-7 with git-release.

About Us

The Prisma Team is behind the Checkpoint Client – chat with us on Slack!