Skip to content
ContractSpec
Start here
AI index

Run your first operation

Build a shipping label preview. Define the input and output, bind a handler, then run it with valid and invalid input. The result appears in your terminal.

1. Install two packages

Open a terminal with Bun. This guide was verified with Bun 1.4.2 and the exact public npm package versions below. You need registry access for this step. The operation runs locally without credentials.

bash
mkdir contractspec-first-operation
cd contractspec-first-operation
bun add --exact @lssm-tech/lib.contracts-spec@17.3.5 @lssm-tech/lib.schema@6.0.5

2. Define and bind the query

Create first-operation.ts in the new directory. The contract describes what the query accepts and returns. The handler formats the label. The registry validates the input before invoking that handler.

typescript
import {
  defineQuery,
  OperationSpecRegistry,
} from '@lssm-tech/lib.contracts-spec/operations';
import { ScalarTypeEnum, SchemaModel } from '@lssm-tech/lib.schema';

const input = new SchemaModel({
  name: 'LabelPreviewInput',
  fields: {
    orderId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
    city: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
  },
});

const output = new SchemaModel({
  name: 'LabelPreviewOutput',
  fields: {
    label: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
  },
});

export const PreviewLabel = defineQuery({
  meta: {
    key: 'shipping.previewLabel',
    version: '1.0.0',
    title: 'Preview shipping label',
    description: 'Format an order ID and city for a shipping label.',
    goal: 'Check what a label will say before printing.',
    context: 'Local shipping label preview.',
    owners: ['shipping'],
    tags: ['quickstart'],
    stability: 'stable',
  },
  io: { input, output },
  policy: { auth: 'anonymous' },
});

const operations = new OperationSpecRegistry([PreviewLabel]);
operations.bind(PreviewLabel, async ({ orderId, city }) => ({
  label: orderId + ' / ' + city,
}));

const result = await operations.executeResult(
  PreviewLabel.meta.key,
  PreviewLabel.meta.version,
  { orderId: process.argv[2] ?? 'A-42', city: 'Lyon' },
  { actor: 'anonymous' },
);

if (result.ok) {
  console.log(JSON.stringify(result.data));
} else {
  console.error(result.problem.code);
  process.exitCode = 1;
}

3. Run it and check the result

bash
bun run first-operation.ts

The query should print this label and exit successfully.

json
{"label":"A-42 / Lyon"}

Pass an empty order ID to see the input contract reject it.

bash
bun run first-operation.ts ""

The command should print the validation code and exit with status 1.

text
VALIDATION_FAILED

If you get stuck

If your terminal cannot find bun, install it and confirm with bun --version. If it cannot resolve a ContractSpec package, check that you ran the install in the same directory and that your registry configuration can reach the public npm registry. If the first run returns a validation error, check the copied file and run it without an argument.

More troubleshooting

Where to go next

Try a different order ID, then use the same pattern to describe one operation in your own application. If that operation captures a payment or changes other external state, start with the integration and policy guides for those boundaries.