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.
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.52. 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.
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
bun run first-operation.tsThe query should print this label and exit successfully.
{"label":"A-42 / Lyon"}Pass an empty order ID to see the input contract reject it.
bun run first-operation.ts ""The command should print the validation code and exit with status 1.
VALIDATION_FAILEDIf 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.
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.