@contractspec/lib.contracts-spec

The core library for defining what your application can do. Unified specifications for Operations, Events, Presentations, and Features.

Installation

bun add @contractspec/lib.contracts-spec @contractspec/lib.schema

What lives where

• @contractspec/lib.contracts-spec (root): The core contracts definitions (OperationSpec, PresentationSpec, Registry).
• @contractspec/lib.contracts-runtime-client-react: Browser-safe helpers (React renderers, client SDK). Import this for web/React Native.
• @contractspec/lib.contracts-runtime-server-rest: HTTP/MCP adapters, registries, integrations (Node-only).
• @contractspec/lib.schema: Schema dictionary (SchemaModel, FieldType) for I/O definitions.

Quick Example

import { defineCommand } from '@contractspec/lib.contracts-spec';
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';

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

export const CreateUser = defineCommand({
  meta: {
    key: 'users.createUser',
    version: '1.0.0',
    description: 'Create a new user account',
  },
  io: {
    input: CreateUserInput,
    output: /* ... */,
  },
  policy: { auth: 'admin' },
});

Core Concepts

• OperationSpec: Immutable description of an operation (Command or Query). Defines I/O, policy, and metadata.
• OperationSpecRegistry: Registry of specs + handlers. Use installOp to attach a handler.
• CapabilitySpec: Canonical capability declaration (requires/provides).
• PolicySpec: Declarative policy rules (ABAC/ReBAC, rate limits).
• TelemetrySpec: Analytics definitions and privacy levels.
• PresentationSpec (V2): Describes how data is rendered (Web Components, Markdown, Data).

Lifecycle

1. Define the spec (I/O via SchemaModel or Zod).
2. Register it: installOp(registry, spec, handler).
3. Expose it via an adapter (REST, GraphQL, MCP).
4. Validate at runtime automatically.

Adapters

• server/rest-next-app: Next.js App Router adapter
• server/provider-mcp: Model Context Protocol (MCP) for AI agents
• server/graphql-pothos: GraphQL schema generator