haystack-contracts

Public API contracts for Haystack Robotics — TypeScript types, path constants, and the OpenAPI document for frontend apps.

Full consumer guide: docs/HAYSTACK_CONTRACTS_CONSUMERS.md

Install

pnpm add haystack-contracts

Pin a specific version in production apps (e.g. "haystack-contracts": "1.0.2").

What ships on npm

| Import | Use | | --------------------------------- | ------------------------------------------------- | | haystack-contracts | Types, PublicApiPath, enums, response envelopes | | haystack-contracts/openapi.json | OpenAPI 3 spec for API reference sites |

Docs frontend (React static API page)

Import the spec and pass it to your OpenAPI renderer:

import openApiSpec from 'haystack-contracts/openapi.json';

Or load from CDN:

https://unpkg.com/[email protected]/openapi.json

Requires resolveJsonModule: true in tsconfig.json for the import pattern.

See the consumer guide for copy-at-build-time and CDN patterns.

Haystack IoT SaaS (typed API calls)

import { HAYSTACK_PRODUCTION_API_URL, PublicApiPath } from 'haystack-contracts';
import type {
  ApiSuccessResponse,
  AuthResponse,
  LoginPayload,
  RobotListItem,
} from 'haystack-contracts';

const res = await fetch(
  `${HAYSTACK_PRODUCTION_API_URL}${PublicApiPath.auth.login}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password } satisfies LoginPayload),
  },
);
const { data }: ApiSuccessResponse<AuthResponse> = await res.json();

See the consumer guide for robots, metrics, disinfection, and analytics examples.

Maintainers (backend monorepo)

After changing public API DTOs or @ApiPublicWebhook() endpoints

pnpm api-check
pnpm --filter haystack-contracts build

pnpm api-check re-exports openapi.json, regenerates src/generated/, and fails if artifacts have drifted. Commit any changed artifacts before publishing:

git add packages_published/contracts/openapi.json
git add packages_published/contracts/src/generated/
git commit -m "chore(contracts): sync openapi artifacts"

Publishing a new version

1. Bump version (from packages_published/contracts/):

npm version patch   # additive types / bugfix  → e.g. 1.0.4
# npm version minor # new public endpoints      → e.g. 1.1.0
# npm version major # breaking type changes     → e.g. 2.0.0

2. Build and verify tarball:

pnpm --filter haystack-contracts build
cd packages_published/contracts
npm pack --dry-run

Confirm the tarball includes dist/, openapi.json, and README.md — not src/ or scripts.

3. Publish:

npm publish

(prepublishOnly runs build again automatically if you skipped step 2.)

4. Commit and notify:

git add packages_published/contracts/package.json
git commit -m "chore(contracts): release haystack-contracts@<version>"

Tell the docs frontend and Haystack IoT SaaS teams to bump haystack-contracts in their package.json and redeploy.

First publish (one-time)

npm login
pnpm api-check
pnpm --filter haystack-contracts build
cd packages_published/contracts
npm pack --dry-run
npm publish --access public

--access public is required the first time for an unscoped package name.

Verify after publish

npm view haystack-contracts version

CDN URL for docs sites:

https://unpkg.com/haystack-contracts@<version>/openapi.json

Package details

• Zero runtime dependencies
• Dual CJS + ESM (dist/index.js, dist/index.mjs)
• Types in dist/index.d.ts