Node.js SDK

The official Node/TypeScript client for Cheqpoint. Uses async/await to pause your logic until a decision is returned. Also supports short-wait and fire-and-forget async patterns.

Installation

bash

npm install @cheqpoint/sdk

Setup

javascript

import { CheqpointClient } from "@cheqpoint/sdk";

const cheq = new CheqpointClient({
  apiKey: process.env.CHEQPOINT_CONNECTION_KEY,
  timeout: 3600 * 1000, // optional: ms to wait (default 5 min)
});

checkpoint() — block until a human decides

javascript

import { CheqpointClient, RejectedError } from "@cheqpoint/sdk";

try {
  const result = await cheq.checkpoint({
    action: "delete_record",
    summary: "Delete user account for usr_123",
    details: { userId: "usr_123" },
    riskScore: 0.8,  // 0.0–1.0
  });

  // Reviewers can modify details — always prefer modifiedDetails
  const payload = result.modifiedDetails ?? result.details;
  await db.users.delete(payload.userId);
} catch (e) {
  if (e instanceof RejectedError) console.log("Blocked:", e.message);
  else throw e;
}

requestSync() — short-wait with client-side polling fallback

javascript

// The server waits up to 10 s (maxWaitMs) for an inline decision,
// then this method continues polling until timeoutMs elapses.
// Returns the decision, or { status: "pending" } if no decision was made.

const result = await cheq.requestSync({
  action: "process_refund",
  summary: "AI agent requesting refund for order #8842",
  details: { orderId: "8842", amountCents: 12000 },
  justification: "Customer reported item not delivered.",
  timeoutMs: 30_000,  // poll up to 30 s total
});

if (result.status === "approved") {
  const effective = result.modifiedDetails ?? { orderId: "8842", amountCents: 12000 };
  await processRefund(effective);
} else if (result.status === "rejected") {
  console.log("Rejected:", result.decisionNote);
} else {
  // "pending" — no decision in time; use approvalId to track later
  console.log("Pending:", result.approvalId);
}

requestAsync() — fire-and-forget with optional callbackUrl

javascript

// Returns immediately. If the server auto-approves/rejects, decision is
// returned right away. Otherwise status is "pending" and you receive a
// callback POST when a human reviewer decides.

const result = await cheq.requestAsync({
  action: "deploy_to_production",
  summary: "AI agent requesting production deployment of v2.4.1",
  details: { version: "v2.4.1", service: "payments-api", region: "us-east-1" },
  justification: "All CI checks passed. No schema migrations.",
  // Optional: receive the final decision via HTTP POST
  callbackUrl: "https://your-backend.example.com/webhooks/cheqpoint-decision",
});

// result.status    → "approved" | "rejected" | "pending"
// result.approvalId → use to poll getRequest(id) if needed
console.log(`Status: ${result.status}, ID: ${result.approvalId}`);

Callback payload (received at your callbackUrl)

json

// Cheqpoint POSTs this to your callbackUrl when a human reviewer decides:
{
  "approvalId": "req_abc123",
  "status": "approved",
  "modifiedDetails": null,
  "decisionNote": "Approved for off-peak deployment window."
}