Install Counterfact for automated workflows

The examples in this manual use Counterfact 3 or newer, including response.status(...) and central generated types with a local Route alias and method annotations such as Route["GET"]. Use Node.js 22 or newer. Install Counterfact in the project that owns the contract, custom handlers, and tests:

npm init -y
npm install --save-dev counterfact@latest

For an existing npm project, skip npm init -y. Commit package.json and the lockfile so teammates and CI use the same version; use npm ci to reproduce that installation. Run npm update counterfact to pick up compatible updates. Keep each recipe’s files in this project directory.

Use npx --no-install counterfact for generation commands so the CLI comes from the project’s installed dependency.

Check the lifecycle API

Save this as check-lifecycle.mjs:

import assert from "node:assert/strict";
import { counterfact } from "counterfact";

const api = await counterfact({ basePath: "api", port: 0 });
assert.equal(typeof api.reset, "function");
assert.equal(typeof api.scenario, "function");
const { stop } = await api.start();
try {
  assert.ok(api.status().address);
  await api.reset();
  console.log("Lifecycle API ready");
} finally {
  await stop();
}

Run node check-lifecycle.mjs. The operating system chooses a free port for this check, and the script awaits shutdown before exiting.

Continue with payment retry, automated integration tests, or AI-assisted workflows.