@qawolf/api-contracts

Versioned contracts for the QA Wolf public API.

The package is the source of truth for public endpoints, and server implementations must derive their public input and output schemas from these contracts. Contract name values are exact tRPC route paths under the public namespace. Authorization and privileged request state stay in the owning server controller or policy.

import { publicContractsV1 } from "@qawolf/api-contracts/v1";

const contract = publicContractsV1.run.create;

Every contract declares annotations with explicit readOnlyHint, destructiveHint, and openWorldHint booleans. These describe possible side effects for clients; adapters such as MCP pass them through. They do not control authorization. A kind: "read" contract can have readOnlyHint: false when reading also changes resource state, such as refreshing a billed runner's activity timer.

Annotations include downstream effects in connected integrations. Creating an environment can create a remote Git branch, and stopping a run can update external run-status messages and commit statuses, so both declare openWorldHint: true. Browser inspection, journal reads and browser screenshots refresh the runner's inactivity timer and can extend its billed lifetime. Mobile inspection does not refresh that timer and remains read-only; the shared screenshot contract declares readOnlyHint: false because its browser path does refresh it.

Contracts are built by a factory that takes the id schemas as input. External consumers use publicContractsV1, which validates ids loosely (the server is the source of truth for id formats). The server instantiates makeContractsV1 with its own strict id schemas, so the contract shape can never drift between the two sides while validation strictness stays server-owned.

This package must not depend on internal packages or expose internal concepts: it is published publicly.

Publishing

This package is published to the public npm registry so external repositories such as qawolf/cli can consume the public contracts.