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!