Checkpoint Client

1.1.33 · active · verified Sun Apr 19

The `checkpoint-client` is a TypeScript client library designed to integrate version checking and security alerting into command-line interface (CLI) tools. It connects to a Checkpoint Server to fetch the latest version information and notify users of any security vulnerabilities relevant to their installed product. Currently, version 1.1.33 is stable, and while no explicit release cadence is detailed, such clients typically update in conjunction with the products they monitor, like Prisma. A key differentiator is its design to be non-intrusive, ensuring "no impact on the developer experience of your CLI," allowing easy integration into various products, and supporting custom styling. As of the current documentation, it exclusively supports the `prisma` product, requiring specific product and version strings, along with unique hashes for CLI and project paths to function correctly.

Common errors

```
Error: Missing required field: product
```
cause The `product` field was omitted or provided as an empty string in the `checkpoint.check` input object.

fix Provide `product: 'prisma'` in the input object.
```
Error: Missing required field: cli_path_hash
```
cause The `cli_path_hash` was not provided in the `checkpoint.check` input object.

fix Generate a SHA256 hash of the CLI installation path and include it as `cli_path_hash` in the input.
```
TypeError: checkpoint.check is not a function
```
cause This error typically occurs when attempting to use CommonJS `require()` syntax with `checkpoint-client` in an ES module context, or when the `checkpoint` object is not correctly imported.

fix Ensure you are using `import checkpoint from 'checkpoint-client'` for TypeScript or ES module environments.

Warnings

gotcha The `product` field in the `checkpoint.check` input object currently only supports the string value 'prisma'. Attempting to use other product names will result in an error or unexpected behavior.
Fix: Always set `product: 'prisma'` in the input object when calling `checkpoint.check()`.
gotcha The `cli_path_hash` and `project_hash` fields are explicitly marked as required in the `Input` type. These fields must be provided as unique string hashes (e.g., SHA256) of the CLI installation path and the project's root path, respectively.
Fix: Ensure `cli_path_hash` and `project_hash` are generated (e.g., using `crypto.createHash`) and included in the input object for `checkpoint.check()`.
gotcha The `disable` field is a required boolean in the input object. This can be counter-intuitive for a flag that typically defaults to `false` or is optional. For checkpoint checks to run, `disable` must be explicitly set to `false`.
Fix: Always include `disable: false` in the `checkpoint.check()` input object if you intend for the client to perform a check.

Install

npm install checkpoint-client npm
yarn add checkpoint-client yarn
pnpm add checkpoint-client pnpm

Imports

checkpoint
wrong:
```
const checkpoint = require('checkpoint-client')
```
correct:
```
import checkpoint from 'checkpoint-client'
```
The library primarily uses a default export, typically consumed via ES module imports in TypeScript or modern Node.js projects.

Quickstart

This quickstart demonstrates how to perform a version and security check using `checkpoint-client`. It shows how to correctly import the library, construct the required `Input` object including dynamically generated hashes for `cli_path_hash` and `project_hash`, and handle the `Result` object for updates or security notices.

import checkpoint from 'checkpoint-client';
import { createHash } from 'crypto';
import * as path from 'path';

async function runCheck() {
  const product = 'prisma';
  const version = '2.0.0'; // Replace with actual product version
  const cliPath = process.env.CLI_PATH || path.join(process.cwd(), 'node_modules', '.bin', product);
  const projectPath = process.env.PROJECT_PATH || process.cwd();

  // Generate unique hashes for required fields
  const cli_path_hash = createHash('sha256').update(cliPath).digest('hex');
  const project_hash = createHash('sha256').update(projectPath).digest('hex');

  try {
    const result = await checkpoint.check({
      product,
      version,
      cli_path_hash,
      project_hash,
      disable: false, // Explicitly set if you want to allow network checks
      // endpoint: 'https://checkpoint.prisma.io', // Optional, defaults to Prisma's endpoint
      // timeout: 5000, // Optional timeout in milliseconds
    });

    console.log('Checkpoint check completed:', result);

    if (result.status === 'ok' || result.status === 'reminded') {
      const { data } = result;
      console.log(`Product: ${data.product}`);
      console.log(`Current version: ${data.current_version}`);
      if (data.latest_version && data.latest_version !== data.current_version) {
        console.log(`New version available: ${data.latest_version}`);
      }
      if (data.security_vulnerabilities && data.security_vulnerabilities.length > 0) {
        console.warn('Security vulnerabilities found:', data.security_vulnerabilities);
      }
    } else {
      console.log('Checkpoint status:', result.status, ' - No update or reminder was triggered.');
    }
  } catch (error) {
    console.error('Failed to perform checkpoint check:', error);
  }
}

runCheck();

view raw JSON →