LevrOps Contracts

Source of truth for LevrOps API and event contracts, JSON schemas, and generated SDKs.

Contents

• openapi/ – OpenAPI specifications for the HTTP API (levrops.v1.yaml)
• asyncapi/ – AsyncAPI contracts for event/webhook payloads (events.yaml)
• schemas/ – Shared JSON Schemas for core LevrOps domain objects
• contracts/content/ – Content contracts for Sanity schema generation
• clients/ts/ – TypeScript SDK generated from the OpenAPI specification
• sanity/generated/ – Generated Sanity schema from content contracts
• COMPAT.json – Compatibility matrix between API, events, and SDK releases
• VERSION – Repository release version (mirrors the latest API contract)

Workflow

1. Update JSON schemas and specs
   • Edit openapi/levrops.v1.yaml for HTTP endpoints
   • Edit asyncapi/events.yaml for event stream/webhook contracts
   • Keep shared domain objects in schemas/ aligned with the operational data model
2. Validate contracts
   • Run Spectral or Redocly CLI locally: npx @redocly/cli lint openapi/levrops.v1.yaml
   • Validate AsyncAPI: npx @asyncapi/cli validate asyncapi/events.yaml
3. Generate SDKs
   • From clients/ts: npm install then npm run build
   • Publish to npm: npm publish --access public
4. Bump versions & regenerate artifacts
   • Run python3 scripts/bump_version.py <new-version> (or make release VERSION=<new-version>) to update openapi/levrops.v1.yaml, VERSION, COMPAT.json, and the TypeScript SDK (includes rebuilding docs).
   • Use --events YYYY-MM-DD (or make release VERSION=<new-version> EVENTS=YYYY-MM-DD) to override the events date recorded in COMPAT.json.

TypeScript SDK

The TypeScript SDK lives in clients/ts and is generated via openapi-typescript-codegen. Use the provided scripts:

cd clients/ts
npm install
npm run build   # runs generate + compile
npm publish     # publishes @hewnventures/levrops-sdk

Consumers can instantiate the SDK with:

import { createLevropsClient } from '@hewnventures/levrops-sdk';

const client = createLevropsClient({
  baseUrl: 'https://api.levrops.com',
  accessToken: process.env.LEVROPS_ACCESS_TOKEN,
  tenant: 'heirloom'
});

const contacts = await client.listContacts();

CLI Tool

A command-line tool is available for managing contracts:

# Install the CLI
make install-cli
# or: cd cli && pip install -e .

# Use it
levrops-contracts bump 1.3.0        # Bump version and regenerate
levrops-contracts sync              # Sync contracts across all projects
levrops-contracts validate          # Validate OpenAPI/AsyncAPI specs
levrops-contracts status            # Check versions across projects
levrops-contracts generate-docs     # Regenerate API documentation
levrops-contracts submit-proposal --all  # Submit contract proposals

See cli/README.md for full CLI documentation.

Sanity Integration

Content contracts in contracts/content/ automatically generate Sanity schema definitions with multi-tenant/property support.

For Contract Maintainers

1. Add or modify content contracts in contracts/content/
   • Use shared/ for contracts available to all tenants
   • Use heirloom/, studioops/ for tenant-specific contracts
   • Add scope metadata to filter by tenant/property
2. Generate schemas:

   npm run sanity:codegen                    # All contracts
   npm run sanity:codegen -- --tenant=heirloom    # Tenant-specific
   npm run sanity:codegen -- --tenant=heirloom --property=store1  # Property-specific

3. Commit the generated schema files

For Sanity Studio Repositories

Install the package:

npm install levrops-contracts

Import and use schemas:

Option 1: Import all schemas (use runtime filtering):

import { allSchemas } from "levrops-contracts/sanity/generated/schema";
import { filterSchemas } from "levrops-contracts/sanity/utils";
import { contentContracts } from "levrops-contracts/contracts/content";

const tenant = process.env.SANITY_TENANT || "heirloom";
const tenantSchemas = filterSchemas(allSchemas, tenant, contentContracts);

export default {
  name: "default",
  types: tenantSchemas,
};

Option 2: Import tenant-specific schema:

import { allSchemas } from "levrops-contracts/sanity/generated/schema-heirloom";

export default {
  name: "default",
  types: allSchemas,
};

CI/CD:

• Run npm run sanity:check in CI to prevent schema drift
• Regenerate schemas when contracts update

See docs/sanity-integration.md for detailed integration instructions.

Versioning

• Use semantic versioning for the repo (VERSION) and the TypeScript SDK.
• Use levrops-contracts bump <new-version> (or python3 scripts/bump_version.py <new-version>, or make release VERSION=<new-version>) to keep VERSION, COMPAT.json, and the OpenAPI spec aligned (the script also bumps clients/ts versions and rebuilds).
• When events change, bump the AsyncAPI info.version and note the new target in COMPAT.json (override via --events if needed).

Roadmap

• Add Python SDK generation (e.g., via openapi-python-client)
• Expand coverage to additional endpoints and webhook streams
• Automate validation and SDK publication in CI