@contractspec/lib.contracts

Website: https://contractspec.io/

The core of ContractSpec — Define contracts once, generate consistent code across all surfaces.

Unified specifications for Operations (commands/queries), Events, and Presentations. Contracts serve as the canonical source of truth that AI agents and code generators read to understand system constraints.

Purpose

To provide a single, typed source of truth for backend operations (ContractSpec), events (EventSpec), and UI/data presentations. This enables runtime adapters (REST, GraphQL, MCP, UI) to automatically generate endpoints, schemas, and user interfaces without code duplication.

Installation

npm install @contractspec/lib.contracts @contractspec/lib.schema
# or
bun add @contractspec/lib.contracts @contractspec/lib.schema

Key Concepts

• Spec-First, TypeScript-First: Define operations in pure TypeScript (no YAML).
• Runtime Adapters: The OperationSpecRegistry is passed to adapters (e.g., makeNextAppHandler) to serve APIs dynamically. There is no intermediate "compile" step to generate code; the spec is the code.
• Capabilities: defineCommand (writes) and defineQuery (reads) with Zod-backed I/O.
• Events: defineEvent for type-safe side effects.
• Presentations: (V2) Describe how data is rendered (Web Components, Markdown, Data) for automated UI generation.

Exports

• Core: OperationSpecRegistry, defineCommand, defineQuery, defineEvent.
• Config: SchemaFormat ('contractspec' | 'zod' | 'json-schema' | 'graphql').
• Adapters:
  • server/rest-next-app: Next.js App Router adapter.
  • server/provider-mcp: Model Context Protocol (MCP) adapter for AI agents.
  • server/graphql-pothos: GraphQL schema generator.
• Docs: markdown utilities to generate human-readable documentation from specs.

Usage

1. Define a Spec

import { defineCommand, defineQuery } from '@contractspec/lib.contracts';
import * as z from "zod";
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';

const UserInput = new SchemaModel({
  name: 'UserInput',
  fields: {
    email: { type: ScalarTypeEnum.Email(), isOptional: false },
  },
});

export const CreateUser = defineCommand({
  meta: {
    name: 'user.create',
    version: 1,
    description: 'Register a new user',
    owners: ['team-auth'],
    tags: ['auth'],
    goal: 'Onboard users',
    context: 'Public registration',
    stability: 'stable',
  },
  io: {
    input: UserInput,
    output: new SchemaModel({
      name: 'UserOutput',
      fields: {
        id: { type: ScalarTypeEnum.String(), isOptional: false },
      },
    }),
  },
  policy: {
    auth: 'anonymous',
  },
});

2. Register and Implement

import { OperationSpecRegistry, installOp } from '@contractspec/lib.contracts';

const reg = new OperationSpecRegistry();

installOp(reg, CreateUser, async (ctx, input) => {
  // Implementation logic here
  return { id: '123' };
});

3. Serve (Next.js Adapter)

// app/api/[...route]/route.ts
import { makeNextAppHandler } from '@contractspec/lib.contracts/server/rest-next-app';

const handler = makeNextAppHandler(reg, (req) => ({ actor: 'anonymous' }));

export { handler as GET, handler as POST };