JSPM

@cheqpoint/sdk

0.1.4
    • ESM via JSPM
    • ES Module Entrypoint
    • Export Map
    • Keywords
    • License
    • Repository URL
    • TypeScript Types
    • README
    • Created
    • Published
    • Downloads 31
    • Score
      100M100P100Q74610F
    • License MIT

    Human-in-the-loop approval SDK for AI agents

    Package Exports

    • @cheqpoint/sdk
    • @cheqpoint/sdk/dist/index.js

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@cheqpoint/sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    @cheqpoint/sdk

    Official JavaScript/TypeScript SDK for Cheqpoint — human-in-the-loop approval queues for AI agents.

    Installation

    npm install @cheqpoint/sdk
# or
pnpm add @cheqpoint/sdk
# or
yarn add @cheqpoint/sdk

    Quick start

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

const cheqpoint = new CheqpointClient({
  apiKey: process.env.CHEQPOINT_CONNECTION_KEY!,
});

// Your agent calls this instead of executing directly.
// checkpoint() submits the request and waits for a human decision.
const result = await cheqpoint.checkpoint({
  action: "refund",
  riskScore: 0.9,
  summary: "Refund $149 to sarah@example.com",
  details: { userId: "usr_123", amount: 149, currency: "USD" },
  justification: "Double-charged on invoice #1821",
});

if (result.status === "APPROVED") {
  // Use modifiedDetails if the reviewer changed the payload, otherwise original details
  const payload = result.modifiedDetails ?? result.details;
  await stripe.refunds.create(payload);
}

    Constructor

    new CheqpointClient({
  apiKey: string;       // Required. Your workspace Connection Key.
  baseUrl?: string;     // Default: "https://app.cheqpoint.co"
  timeout?: number;     // Default poll timeout in ms. Default: 300000 (5 min)
})

    Methods

    checkpoint(options) → Promise<CheckpointResult>

    Submit an action for review and wait for a human decision. Polls the API every pollIntervalMs until approved, rejected, or timed out.

    Option Type Default Description
    action string required Action type (e.g. "refund", "send_email", "deploy_code")
    riskScore number — Risk score 0.0–1.0 shown to reviewers (0.9 = high, 0.5 = medium, 0.2 = low)
    summary string required One-sentence description shown to reviewers
    details Record<string, unknown> required Structured payload. Returned as-is (or modified) on approval
    justification string — Agent's reasoning shown to reviewers
    webhookUrl string — URL for Cheqpoint to POST the decision to
    pollIntervalMs number 3000 How often to poll for a decision
    timeoutMs number 300000 Max time to wait before throwing TimeoutError

    Resolves with a CheckpointResult when approved:

    {
  id: string;
  status: "APPROVED";
  details: Record<string, unknown>;          // original details
  modifiedDetails: Record<string, unknown> | null;  // reviewer edits, if any
  responseNotes: string | null;              // reviewer's note
}

    Throws RejectedError if the request is rejected (includes responseNotes). Throws TimeoutError if no decision is made within timeoutMs.

    createRequest(options) → Promise<{ id: string }>

    Fire-and-forget. Submits the request and returns immediately with the ID. Use this with a webhookUrl or to check status manually with getRequest.

    getRequest(id) → Promise<RequestStatus>

    Fetch the current status of a request.

    {
  id: string;
  status: "PENDING" | "APPROVED" | "REJECTED";
  details: Record<string, unknown>;
  modifiedDetails: Record<string, unknown> | null;
  responseNotes: string | null;
  decidedAt: string | null;
  // ...
}

    Error handling

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

try {
  const result = await cheqpoint.checkpoint({ ... });
  // handle approval
} catch (err) {
  if (err instanceof RejectedError) {
    console.log("Rejected:", err.responseNotes);
  } else if (err instanceof TimeoutError) {
    console.log("No decision within timeout for request:", err.requestId);
  } else if (err instanceof CheqpointError) {
    console.log("API error:", err.statusCode, err.message);
  } else {
    throw err;
  }
}

    Examples

    // Submit without waiting — decision delivered to your webhook endpoint
const { id } = await cheqpoint.createRequest({
  action: "db-write",
  riskScore: 0.5,
  summary: "Delete user account usr_456",
  details: { userId: "usr_456", reason: "GDPR deletion request" },
  webhookUrl: "https://yourapp.com/webhook/cheqpoint",
});

// Store `id` — your webhook handler will receive the decision

    Manual polling

    const { id } = await cheqpoint.createRequest({ ... });

// Check status at any time
const status = await cheqpoint.getRequest(id);
if (status.status !== "PENDING") {
  const payload = status.modifiedDetails ?? status.details;
  // proceed
}

    LangChain / LangGraph agent tool

    import { tool } from "@langchain/core/tools";
import { z } from "zod";

const refundTool = tool(
  async ({ userId, amount, reason }) => {
    const result = await cheqpoint.checkpoint({
      action: "refund",
      riskScore: 0.9,
      summary: `Refund $${amount} to user ${userId}`,
      details: { userId, amount, reason },
    });
    const payload = result.modifiedDetails ?? result.details;
    return `Refund approved for $${payload.amount}`;
  },
  {
    name: "issue_refund",
    description: "Issue a refund to a customer. Requires human approval.",
    schema: z.object({
      userId: z.string(),
      amount: z.number(),
      reason: z.string(),
    }),
  }
);

    Requirements

    • Node.js 18+ (uses native fetch)
    • For Node.js 16/17, polyfill fetch with node-fetch

    License

    MIT