@usefidel/contracts

Shared contracts between Fidel surfaces: the run-error taxonomy (typed failure codes, their user-facing messages, retryability, and a presentation helper), and the pipeline wire contract (the runtime-validated request and response envelopes for the Pipeline Lambda).

This package exists so that Fidel's web app, browser extension, GitHub Action and CI runner all describe the same failure with the same code and the same wording, rather than each keeping its own drifting copy.

Why it is public

It is published publicly so build environments can install it without authenticating to a private registry. Public availability is not a licence. See below.

It contains no proprietary logic — no matching, scoring, or diffing code. Error codes and their messages only.

Install

npm install @usefidel/contracts

Use

import { RUN_ERROR_CODES, resolveRunDisplay } from '@usefidel/contracts';
// or
import { resolveRunDisplay } from '@usefidel/contracts/run-errors';

The canonical fidel.config.json builders live behind their own entry point, so importing them is a deliberate act rather than a side effect of importing the package:

import { buildDsConfigJson, nameFromUrl } from '@usefidel/contracts/onboarding-config';

The pipeline wire contract publishes its VERSION here and nothing more:

import { PIPELINE_WIRE_VERSION } from '@usefidel/contracts/pipeline-wire-version';

Plan limits, list prices, and hasFeature(plan, feature, featureFlags) live here too. The function is the pure entitlement decision. It does not read a database, and a feature flag cannot grant a capability the tier table does not already allow unless that flag is an explicit override of a non-revenue-gated feature.

import { hasFeature, PLAN_LIMITS, PRICES_USD_CENTS } from '@usefidel/contracts/entitlements';

The request and response SCHEMAS are deliberately not in this package. A Zod schema is a runtime object, not a type: it survives into whatever bundle imports it. Those schemas describe the design-system mode's internal model (tokenGraph, shadowTokenGraph, projectionMode, applicability), so shipping them from a package that is public on npm would publish that model to anyone who installs it — and public is irreversible.

They live in the monorepo's private packages/pipeline-wire/, which is never published and is imported by relative path from the Lambda and the edge functions: the surfaces allowed to see them. The marketplace Action, whose bundles ship to a public repo, takes import type only, so its payload carries no schema at all.

What a public caller needs is the version string — to stamp on a request, and to read back off a WIRE_SCHEMA_MISMATCH rejection. That reveals nothing about the shape which judged it.

These are the ONE implementation of what fidel init writes. The CLI uses them to write the file and the onboarding UI uses them to render the example a user copies, so the two cannot drift. Their output formatting — two-space indent, key order, trailing newline — is part of the contract and is asserted byte for byte.

Ships ESM with TypeScript declarations.

Peer dependencies

None. This package has no dependencies, peer or otherwise.

An earlier draft made zod a peer, because the request schemas lived here. Moving them to the private packages/pipeline-wire/ removed the reason: nothing this package ships needs a runtime. Adding a peer would widen what a contractor-installable package drags into their tree, and gets the same review bar as adding an export.

Versioning

Semver. The error-code set is additive within a major version: new codes may appear in a minor release, and existing codes are neither removed nor given new meanings without a major bump.

Licence

UNLICENSED — all rights reserved. Being downloadable from npm does not grant permission to use, copy, modify, or redistribute this package. It is published for Fidel's own build and deployment pipelines. If you want to use it, ask first: [email protected]

Contributing

Not open to outside contributions. Issues and pull requests have nowhere to go — the source lives in a private repository.