@flowwright/api-contract

@flowwright/api-contract is the framework-independent wire contract shared by the FlowWright web app, server, and workers. It pairs TypeScript DTOs with Zod schemas and pure parsers so untrusted data is validated at every boundary.

FlowWright · Web app · Server

Use it

import {
  RunDetailDtoSchema,
  parseCreateProjectRequest,
  permissionsForRole,
} from "@flowwright/api-contract";

async function readRun(runId: string) {
  const raw: unknown = await fetch(`/api/runs/${runId}`).then((res) => res.json());
  return RunDetailDtoSchema.parse(raw);
}

const parseProject = (body: unknown) => parseCreateProjectRequest(body);
const permissions = permissionsForRole("member");

Schemas are useful at runtime; their matching TypeScript types provide compile-time contracts without importing server implementation code.

Public surface

| Area | Examples | |---|---| | Response contracts | Runs, projects, workers, users, audit, health, storage, metrics, and configuration DTOs | | Request contracts | Project, run, user, profile, authentication, secret, and runtime-config parsers | | Authorization | Roles, permission union, complete permission list, and role-to-permission mapping | | Errors | Shared result and API-error shapes | | Configuration files | Server and worker YAML/JSON schemas plus secret references | | Versioning | HTTP/SSE contract version and worker-protocol compatibility helpers |

Design boundary

web / clients ◀── typed contract ──▶ server / workers

• This package contains shapes and validation, not business logic.
• It performs no HTTP requests, filesystem access, persistence, or execution.
• Request parsers validate structure; domain services validate business semantics.
• Breaking HTTP/SSE and worker-protocol changes are versioned separately.
• Clients can depend on this package without pulling in the control plane or runtime.

Development

$ pnpm --filter @flowwright/api-contract typecheck
$ pnpm --filter @flowwright/api-contract test
$ pnpm --filter @flowwright/api-contract build

Tests keep DTO schemas, parsers, permissions, configuration files, and protocol contracts in sync.

Requires Node.js 24+. Licensed under MIT.