Skip to content
Skills Library
Programming · Building & coding

contract

/contract

Write or change a module's contract package (modules/<name>/contract): the `*Api` interface and moduleApi token, Zod schemas with z.infer, HandledError subclasses and their codes, the tRPC declarations (defineTrpcContract), REST wire schemas, method verbs (get/find/list, ADR-146). Use when someone says 'add an Api operation', 'new *Api method', 'add a schema', 'add an error code', 'HandledError', 'new tRPC procedure', 'declare a procedure', 'contract package', 'what verb should this method use', 'T | null return', or opens modules/*/contract/src.

Repository
langwatch ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Write or change a module's contract package (modules/<name>/contract): the `*Api` interface and moduleApi token, Zod schemas with z.infer, HandledError subclasses and their codes, the tRPC declarations (defineTrpcContract), REST wire schemas, method verbs (get/find/list, ADR-146). Use when someone says 'add an Api operation', 'new *Api method', 'add a schema', 'add an error code', 'HandledError', 'new tRPC procedure', 'declare a procedure', 'contract package', 'what verb should this method use', 'T | null return', or opens modules/*/contract/src.

Triggers from the description

add an Api operationnew *Api methodadd a schemaadd an error codeHandledErrornew tRPC proceduredeclare a procedurecontract package
Original author description

Write or change a module's contract package (modules/<name>/contract): the `*Api` interface and moduleApi token, Zod schemas with z.infer, HandledError subclasses and their codes, the tRPC declarations (defineTrpcContract), REST wire schemas, method verbs (get/find/list, ADR-146). Use when someone says 'add an Api operation', 'new *Api method', 'add a schema', 'add an error code', 'HandledError', 'new tRPC procedure', 'declare a procedure', 'contract package', 'what verb should this method use', 'T | null return', or opens modules/*/contract/src.

How it works

  1. What lives in contract/src/
  2. Rules that matter
  3. Worked example: an error and its code
  4. Worked example: an operation, end to end
  5. Traps
Original SKILL.md headings · 127 lines, 871 words
SKILL.md preview
---
name: contract
description: "Write or change a module's contract package (modules/<name>/contract): the `*Api` interface and moduleApi token, Zod schemas with z.infer, HandledError subclasses and their codes, the tRPC declarations (defineTrpcContract), REST wire schemas, method verbs (get/find/list, ADR-146). Use when someone says 'add an Api operation', 'new *Api method', 'add a schema', 'add an error code', 'HandledError', 'new tRPC procedure', 'declare a procedure', 'contract package', 'what verb should this method use', 'T | null return', or opens modules/*/contract/src."
user-invocable: true
---

# A contract

Record: `dev/docs/ARCHITECTURE.md` §3.1 (the contract), §8 (transports), §12
(errors), `dev/docs/adr/146-method-verb-vocabulary.md` (verbs). Exemplars:
`modules/monitor/contract` (small), `modules/organization/contract` (large),
`modules/automation/contract`.

The contract is **everything another module or a browser may know** about you:
schemas, portable types, errors, the tRPC declarations, the `*Api` interface.
It imports no framework runtime and no other half (see the `module` skill); the light
`@langwatch/module` core is its one framework import, plus the portable surfaces record §2 names
(config and secret handles, errors, `@langwatch/eventing/tables`). A browser also reads a module's
`<name>-client` and lent tokens, which sit beside the contract, not in it.

## What lives in `contract/src/`

| File                                              | Holds                                   | Example                           |
| ------------------------------------------------- | --------------------------------------- | --------------------------------- |
| `<name>.ts`, `<concern>.ts`                       | Zod schemas plus `z.infer` types        | `monitor/contract/src/monitor.ts` |
| `<name>.api.ts`                                   | the `*Api` interface and its token      | `monitor.api.ts`                  |
| `<name>.errors.ts`                                | `HandledError` subclasses               | `monitor.errors.ts`               |
| `<name>.trpc.ts`                                  | `defineTrpcContract` declarations       | `monitor.trpc.ts`                 |
| `<name>-trpc.schemas.ts`                          | tRPC input and answer schemas           | `monitor-trpc.schemas.ts`         |
| `<name>-rest.schemas.ts`                          | REST wire schemas, distinct from domain | `monitor-rest.schemas.ts`         |
| `<name>.events.ts`, `.commands.ts`, `.queries.ts` | eventing vocabulary                     | `automation.events.ts`            |
| `<name>.config.ts`                                | the module's config schema (§6)         | `automation.config.ts`            |
| `index.ts`                                        | `export *` of the above                 | `monitor/contract/src/index.ts`   |

The filename grammar is `packages/oxlint-rules/grammar/feature-layout-policy.mjs`
(contract suffixes: `app`, `commands`, `errors`, `events`, `queries`,
`service`; `<feature>.api.ts` is the one home of the token). A process-only
suffix (`.repository`, `.channel`, `.rules`...) in a contract is refused.

## Rules that matter

1. **Zod, then `infer`.** Declare the schema, derive the type:
   `export type Monitor = z.infer<typeof monitorSchema>`. Never write a TS type
   that restates a schema or another contract's type (CLAUDE.md rule 5).
2. **One options object per operation.** `create(input: MonitorCreateInput)`,
   `findBySlug({ projectId, slug })`. Never positional (`max-params`, §3.2).
   Named parameters carry `projectId`, and the caller's `authorization`
   travels as a parameter, never ambient (§3.2, ADR-166).
3. **Verbs are ADR-146's.** `get*` returns exactly one or throws the module's
   not-found error. `find*` returns an array (empty is absence). `list*`
   returns a page `{ items, cursor }`. Writes: `create`, `update`, `delete`,
   `upsert`, `archive`. No `T | null`, no `try*`, no `resolve*`.
   `MonitorApi` shows the pair: `getById` throws, `findBySlug` returns an
   array.
4. **The token is one line.**
   `export const MonitorApi = moduleApi<MonitorApi>()("monitor");` Interface
   and const share a name. The string is the module id.
5. **A tRPC procedure is declared once, here.**
   `defineTrpcContract("monitors").query("getById").withInput(s).withOutput(s)`.
   The process binds permission and handler; the browser derives its client
   from the same declaration (§8). The procedure name is the browser's cache
   key: renaming or changing kind (query vs mutation) moves the call.
6. **Every wire schema is imported from the contract**, never redefined in a
   transport (§8). REST wire schemas stay distinct from domain schemas.
7. **A known failure is a `HandledError` subclass with a stable code**
   (§12). `message` is customer-safe. Tests assert the `code`, not prose.
   A ported code keeps main's spelling. A 5xx sets `fault` explicitly (`customer` is allowed
   where the customer caused it).
8. **A new `*Api` operation is a design choice.** Ask first, unless it is a
   one-to-one port of logic main kept in a handler (§8: pre-approved).
9. **Contract `package.json` names no runtime**: no `prisma-client`,
   `clickhouse-client`, `redis-client`, the eventing runtime, `group-queue`, `process-*`
   (§3; the `manifests` policy refuses it). The plain-data subpath
   `@langwatch/eventing/tables` is allowed (§2; `modules/data-retention/contract`).

## Worked example: an error and its code

`modules/monitor/contract/src/monitor.errors.ts` (reformatted):

```ts
export class MonitorNotFoundError extends HandledError {
  declare readonly code: "monitor_not_found";
  constructor(readonly monitorId: string) {
    super("monitor_not_found", "Monitor not found.", {
      httpStatus: 404,
      fault: "customer",
      meta: { monitorId },
      ...remediation("monitor_not_found"),
    });
    this.name = "MonitorNotFoundError";
  }
}
```

Then register the code in three places, in the same change: `packages/handled-error/src/app-codes.ts`
(sorted), the customer copy in `presentation.ts`, and the tips and docs link in `remediation.ts`.
`remediation("<code>")` is typed over the remediation registry, so an unregistered code does not
compile. A 404 can also
extend `NotFoundError` (`organization/contract/src/team.errors.ts`).
Presentation copy: `dev/docs/best_practices/error-handling.md`.

## Worked example: an operation, end to end

Adding a hypothetical `monitor.archive` (not in the tree):

1. Schema `monitorArchiveInputSchema` in `monitor-trpc.schemas.ts` or
   `monitor.ts`, with `export type ... = z.infer<...>`.
2. `archive(input: MonitorArchiveInput): Promise<Monitor>` on `MonitorApi`
   (`monitor.api.ts`), with a one-line doc comment.
3. If it has a route: a `.mutation("archive")` in `monitor.trpc.ts`.
4. Implement it in the process half (`process-module` skill). The token
   already exists; nothing else registers the operation.
5. Specs: a scenario in `modules/monitor/specs/` first.

## Traps

- **Restating a type** from another contract. Import it
  (`@langwatch/evaluation-contract`) and name it.
- **Returning `T | null`** or `Promise<X | undefined>` from a lookup. A keyed
  read that may miss is a `get*` that throws; the caller catches the `code`.
- **Putting a transport's permission list in the contract.** Permissions are
  bound in `process/src/transport/<name>.trpc.ts` (§8).
- **Re-parsing.** Parse once where a value enters untyped (a transport, a
  channel's inbound message); it travels as its `z.infer` type afterwards (§3.2).
- **Config and peer-dependency declarations** (the `<name>.config.ts` slice,
  what the module demands of its process) are the `module-dependencies` skill.
  `<name>.config.ts` carries the slice, the secret handles and the browser
  projection (§6); there are no supply tokens (§15).
- **A hand-written client or router type.** The browser client derives from the
  declarations (`@langwatch/api/web`), never a router type (§3.4).
- **Naming from the §15 list.** Look there before inventing any helper name.

Versions

RepositoryScoreLicence
This page · langwatch/langwatch100Apache-2.0
scalus3/scalus100Apache-2.0
railly/skills100MIT
DataWithBaraa/claude-code-data-engineering-skills90MIT

Database snapshot: 13.11.2026 · package version e11e3158ef14 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-transports
    Declare a REST route, a tRPC procedure or an SSE/subscription stream on a module: defineRestRouter, defineTrpcRouter, defineTrpcContract, .withInput/.withOutput/.withPermission/.withDocs, /api/<x> paths (/v1 optional), framework-owned validation (malformed_request 400 vs…
  • 100module-client
    Create or use a <name>-client package (modules/<name>/client): the typed tRPC hooks another module's browser reads. Use when someone says 'read another module's data in the browser', 'prompt-client', 'dataset-client', 'a client package', 'createModuleApi', 'ContractApiMap',…
  • 100type-safe-api
    End-to-end type safety patterns for API development. Covers Zod-to-OpenAPI, ts-rest, Zodios, and contract testing. Use for ensuring type consistency between backend and frontend. USE WHEN: user mentions "type-safe API", "end-to-end types", "Zod to OpenAPI", "ts-rest", "Zodios",…
  • 100factory-api-route-engineer
    Use when designing or implementing API endpoints — server actions, tRPC procedures, REST routes for external consumers. Carries the factory's API conventions — the server actions vs tRPC decision, procedure tier stacking, per-mutation Zod schemas, central router composition with…
  • 86add-resource
    Add a REST resource or endpoint to this Hono API end to end, with its zod schemas, store, createRoute declarations, handlers and contract tests. Use when asked for a new resource, endpoint or route.
  • 100rest-api-design
    Design REST API endpoints with Zod validation and OpenAPI documentation. Use when creating new API routes, validating request/response schemas, or updating API documentation. Activates for endpoint design, schema validation, error handling, and API docs.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.