@lssm/lib.contracts

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

Installation

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

Key Concepts

Spec-First, TypeScript-First: Define operations in pure TypeScript (no YAML).
Runtime Adapters: The `SpecRegistry` is passed to adapters to serve APIs dynamically. There is no intermediate "compile" step.
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).

Example: Define a Command

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

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

const UserOutput = new SchemaModel({
  name: 'UserOutput',
  fields: {
    id: { type: ScalarTypeEnum.String(), 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: UserOutput,
  },
  policy: {
    auth: 'anonymous',
  },
});

Example: Register and Serve

import { SpecRegistry, installOp } from '@lssm/lib.contracts';
import { makeNextAppHandler } from '@lssm/lib.contracts/server/rest-next-app';

const reg = new SpecRegistry();

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

// Serve via Next.js App Router
export const handler = makeNextAppHandler(reg, (req) => ({ 
  actor: 'anonymous' 
}));

export { handler as GET, handler as POST };

Available 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
server/rest-elysia: Elysia (Bun) adapter

Next: Schema Core Concepts