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
• contracts/designops/ – DesignOps contracts for design system orchestration (design systems, projects, artifacts, agents)
• examples/ – Example contract instances for reference
• 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.

DesignOps Contracts

DesignOps contracts enable ConductorOps and other agents to reason about and orchestrate design work (Figma, design systems, UI flows) in the same way they already reason about backend/frontend/ops.

Contract Types:

• DesignSystemContract - Reusable design systems (colors, typography, spacing, components)
• DesignProjectContract - Design projects (apps, features, flows, landing pages)
• DesignArtifactContract - Maps Figma components/frames to code components/tokens
• DesignOpsAgentContract - Agent configuration for orchestrating design workflows

Schema Files:

• schemas/design_system.json - DesignSystemContract schema
• schemas/design_project.json - DesignProjectContract schema
• schemas/design_artifact.json - DesignArtifactContract schema
• schemas/designops_agent.json - DesignOpsAgentContract schema

Examples:

• examples/designops/levrops-core-design-system.json - Example design system
• examples/designops/conductorops-dashboard-project.json - Example design project
• examples/designops/design-artifacts-example.json - Example artifact mappings
• examples/designops/designops-agent-example.json - Example agent configuration

See docs/designops.md for detailed documentation on DesignOps contracts and integration with ConductorOps.

E-commerce Contracts

E-commerce contracts enable reporting and management of preorder deposits across multi-tenant e-commerce integrations.

Contract Types:

• PreorderDepositReport - Aggregated report of preorder deposits with summary statistics
• PreorderDepositOrder - Individual preorder deposit order with deposit and balance information

Schema Files:

• schemas/preorder_deposit_report.json - PreorderDepositReport schema
• schemas/preorder_deposit_order.json - PreorderDepositOrder schema

API Endpoints:

• GET /api/v1/tenants/{tenantId}/ecommerce/preorder-deposits - Get preorder deposit report
• GET /api/v1/tenants/{tenantId}/ecommerce/preorder-deposits/{orderId} - Get order details
• POST /api/v1/tenants/{tenantId}/ecommerce/preorder-deposits/{orderId}/charge-balance - Charge balance

Examples:

• examples/ecommerce/preorder-deposit-report-example.json - Example preorder deposit report

Editorial Content Engine Contracts

The Editorial Content Engine provides standardized content management capabilities for creating, scheduling, and publishing content across multiple channels (social media, blogs, email campaigns) across all LevrOps products.

Contract Types:

• Campaign - Marketing campaigns that organize multiple content assets
• ContentAsset - Content assets (articles, blog posts, social posts, emails, videos) with rich content support
• Channel - Publishing channels (Instagram, Facebook, Newsletter, Sanity, Shopify Blog, etc.)
• ContentTopic - Topics/categories for organizing content

Schema Files:

• schemas/campaign.json - Campaign schema
• schemas/content_asset.json - ContentAsset schema (updated with rich content, media attachments, timezone support)
• schemas/channel.json - Channel schema
• schemas/content_topic.json - ContentTopic schema

API Endpoints: All endpoints are under /api/v1/editorial/:

• Campaign management: /campaigns/, /campaigns/{id}/, /campaigns/{id}/add-assets/, /campaigns/{id}/remove-assets/
• Content asset management: /assets/, /assets/{id}/, /assets/{id}/publish/, /assets/{id}/publish-status/
• Channel management: /channels/, /channels/{id}/
• Topic management: /topics/, /topics/{id}/

Key Features:

• Rich content support (HTML body + structured JSON for Portable Text, Slate, etc.)
• Media attachments with metadata
• Timezone-aware scheduling
• Multi-channel publishing (Instagram, Facebook, TikTok, Newsletter, Sanity, Shopify Blog)
• Campaign organization and performance tracking
• Publishing workflow status tracking

Examples:

• examples/editorial/summer-collection-campaign.json - Example campaign
• examples/editorial/summer-collection-preview-asset.json - Example content asset
• examples/editorial/instagram-channel.json - Example channel
• examples/editorial/fashion-topic.json - Example topic

Audio Generation (Platform) Contracts

Platform-level capability for audio generation: short generated audio from contextual inputs (chords, text, concepts). Reusable by any LevrOps surface (constellation, education, meditation, game cues, coaching, etc.). Product surface constructs a request → LevrOps executes generation → provider produces audio.

Schema Files:

• schemas/audio_generation_enums.json - AudioGenerationStatus, Mood, HarmonicMode, Density, EnergyCurve (guidance)
• schemas/audio_generation_request.json - Request (sourceType, experienceType, sourceRef, inputs, preset, mood, durationMs, options, metadata, optional guidance)
• schemas/audio_generation.json - AudioGenerationResult (generationId, status, audioUrl, durationMs, etc.)
• schemas/audio_generation_regenerate_request.json - Regenerate by generationId with optional overrides
• schemas/audio_generation_error.json - Structured error (invalid_request, source_not_eligible, provider_unavailable, generation_failed, asset_missing)
• schemas/events/audio_generation.*.json - Events: requested, completed, failed, replayed, regenerated

Events (AsyncAPI): audio_generation.requested, audio_generation.completed, audio_generation.failed, audio_generation.replayed, audio_generation.regenerated

Guidance: Optional guidance object on the request provides lightweight hints (harmonicMode, tempoHintBpm, density, energyCurve, instrumentFocus, negativeDirectives) for music-aware or scene-aware use cases without polluting the top-level schema. Fully optional; providers may partially honor. See docs/audio-generation-contracts.md for request/result shapes, guidance field reference, examples, and migration notes.

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