checkpoint-client

Checkpoint Client

A TypeScript Checkpoint Client for the 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

• update-notifier example
• Wait for version example
• CI example

Publishing a new version on npm

1. Create a release in the UI -> https://github.com/prisma/checkpoint-client/releases/new
   • Add a tag, use the version, like 1.1.30
     • Click on "Create new tag: on publish"
   • Add a release title, use the version, like 1.1.30
   • Click "Generate release notes" (add more info if needed)
   • "Target" should be "main" (default)
   • "Set as the latest release" should be checked (default)
   • Click "Publish release"
   • Monitor https://github.com/prisma/checkpoint-client/actions/workflows/release-latest.yml for the publish workflow
2. Update checkpoint-client dependency in:
   • prisma/prisma repository
     • https://github.com/prisma/prisma/blob/main/packages/internals/package.json
     • https://github.com/prisma/prisma/blob/main/packages/cli/package.json
     • Renovate will open a PR automatically, if you want it faster, check the checkbox in https://github.com/prisma/prisma/issues/2985
   • prisma/language-tools repository
     • https://github.com/prisma/language-tools/blob/main/packages/vscode/package.json
     • Renovate will open a PR automatically, if you want it faster, check the checkbox in https://github.com/prisma/language-tools/issues/504
   • prisma/studio-code repository
     • https://github.com/prisma/studio-code/blob/main/packages/server/package.json
     • Renovate will open a PR automatically, if you want it faster, check the checkbox in https://github.com/prisma/studio-code/issues/414

Previous instructions:

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 main

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

About Us

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