levrops-contracts 1.1.0

package/README.md

@@ -0,0 +1,149 @@
+# 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:
+
+```sh
+cd clients/ts
+npm install
+npm run build   # runs generate + compile
+npm publish     # publishes @hewnventures/levrops-sdk
+```
+
+Consumers can instantiate the SDK with:
+
+```ts
+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:
+
+```bash
+# Install the CLI
+make install-cli
+# or: cd cli && pip install -e .
+
+# Use it
+levrops-contracts bump 1.2.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
+```
+
+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:
+   ```bash
+   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:**
+```bash
+npm install levrops-contracts
+```
+
+**Import and use schemas:**
+
+Option 1: Import all schemas (use runtime filtering):
+```typescript
+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:
+```typescript
+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
+

package/contracts/content/README.md

@@ -0,0 +1,108 @@
+# Content Contracts
+
+This directory contains content contracts that define Sanity schema models. LevrOps is the source of truth for content models; Sanity Studio consumes generated schema from these contracts.
+
+## Structure
+
+- `types.ts` - TypeScript types for content contracts
+- `example.ts` - Example content contracts (can be removed/replaced)
+- `index.ts` - Registry that exports all content contracts
+
+## Multi-Tenant/Property Scoping
+
+Contracts can be scoped to specific tenants or properties:
+
+```typescript
+export const myContentContract: ContentContract = {
+  id: "my-content",
+  title: "My Content",
+  type: "document",
+  scope: {
+    tenants: ["heirloom", "studioops"],  // Only available to these tenants
+    properties: ["store1"],                // Only available to this property
+    requiredFor: {
+      tenants: ["heirloom"],              // Required for Heirloom tenant
+    },
+  },
+  fields: [
+    // ... fields
+  ],
+};
+```
+
+If `scope` is omitted, the contract is available to all tenants and properties.
+
+## Organization
+
+Contracts are organized by namespace:
+- `shared/` - Contracts available to all tenants/properties
+- `heirloom/` - Contracts specific to Heirloom Supply tenant
+- `studioops/` - Contracts specific to StudioOps tenant
+
+## Adding a Content Contract
+
+1. Create a new file in the appropriate directory (shared, tenant-specific, or root)
+2. Define your contract using the `ContentContract` type:
+
+```typescript
+import type { ContentContract } from "./types";
+
+export const myContentContract: ContentContract = {
+  id: "my-content",
+  title: "My Content",
+  type: "document", // or "object"
+  description: "Description of this content type",
+  fields: [
+    {
+      name: "title",
+      type: "string",
+      title: "Title",
+      required: true,
+    },
+    // ... more fields
+  ],
+};
+```
+
+3. Import and add it to `index.ts`:
+
+```typescript
+import { myContentContract } from "./my-content";
+// or for tenant-specific contracts:
+import { myContentContract } from "./heirloom/my-content";
+
+export const contentContracts: ContentContract[] = [
+  // ... existing contracts
+  myContentContract,
+];
+```
+
+## Field Types
+
+Supported field types:
+- `string` - Single line text
+- `text` - Multi-line text
+- `number` - Numeric value
+- `boolean` - True/false
+- `date` - Date only
+- `datetime` - Date and time
+- `url` - URL
+- `email` - Email address
+- `slug` - URL slug (requires `source` option)
+- `richText` - Portable text/rich text
+- `image` - Image upload
+- `file` - File upload
+- `array` - Array of items (requires `of` option)
+- `object` - Nested object
+- `reference` - Reference to another document (requires `to` option)
+
+## Generating Sanity Schema
+
+After adding or modifying contracts, run:
+
+```bash
+npm run sanity:codegen
+```
+
+This generates `sanity/generated/schema.ts` which can be imported in your Sanity Studio project.
+

package/contracts/content/example.ts

@@ -0,0 +1,142 @@
+/**
+ * Example Content Contracts
+ *
+ * These are example contracts to demonstrate the structure.
+ * Remove or replace these with actual content contracts for your project.
+ */
+
+import type { ContentContract } from "./types";
+
+/**
+ * Example: Blog Post document
+ */
+export const blogPostContract: ContentContract = {
+  id: "blog-post",
+  title: "Blog Post",
+  type: "document",
+  description: "A blog post article",
+  fields: [
+    {
+      name: "title",
+      type: "string",
+      title: "Title",
+      required: true,
+      options: {
+        maxLength: 200,
+      },
+    },
+    {
+      name: "slug",
+      type: "slug",
+      title: "Slug",
+      required: true,
+      options: {
+        source: "title",
+      },
+    },
+    {
+      name: "author",
+      type: "reference",
+      title: "Author",
+      required: true,
+      options: {
+        to: ["author"],
+      },
+    },
+    {
+      name: "publishedAt",
+      type: "datetime",
+      title: "Published At",
+      required: true,
+    },
+    {
+      name: "excerpt",
+      type: "text",
+      title: "Excerpt",
+      description: "Short summary for previews",
+      options: {
+        maxLength: 300,
+      },
+    },
+    {
+      name: "content",
+      type: "richText",
+      title: "Content",
+      required: true,
+      options: {
+        annotations: ["link", "internalLink"],
+        decorators: ["strong", "em", "code"],
+      },
+    },
+    {
+      name: "tags",
+      type: "array",
+      title: "Tags",
+      options: {
+        of: "string",
+      },
+    },
+    {
+      name: "featuredImage",
+      type: "image",
+      title: "Featured Image",
+    },
+  ],
+  preview: {
+    select: {
+      title: "title",
+      author: "author.name",
+      publishedAt: "publishedAt",
+    },
+    prepare: (selection) => ({
+      title: selection.title as string,
+      subtitle: `${selection.author as string} • ${new Date(selection.publishedAt as string).toLocaleDateString()}`,
+    }),
+  },
+};
+
+/**
+ * Example: Hero Section object (nested/reusable component)
+ */
+export const heroSectionContract: ContentContract = {
+  id: "hero-section",
+  title: "Hero Section",
+  type: "object",
+  description: "Hero banner section for landing pages",
+  fields: [
+    {
+      name: "headline",
+      type: "string",
+      title: "Headline",
+      required: true,
+      options: {
+        maxLength: 100,
+      },
+    },
+    {
+      name: "subheadline",
+      type: "text",
+      title: "Subheadline",
+      options: {
+        maxLength: 200,
+      },
+    },
+    {
+      name: "image",
+      type: "image",
+      title: "Background Image",
+      required: true,
+    },
+    {
+      name: "ctaText",
+      type: "string",
+      title: "CTA Button Text",
+    },
+    {
+      name: "ctaLink",
+      type: "url",
+      title: "CTA Link",
+    },
+  ],
+};
+

package/contracts/content/heirloom/product.ts

@@ -0,0 +1,98 @@
+/**
+ * Heirloom Supply Content Contracts
+ *
+ * Content contracts specific to Heirloom Supply tenant.
+ */
+
+import type { ContentContract } from "../types";
+
+/**
+ * Product document for Heirloom Supply
+ */
+export const productContract: ContentContract = {
+  id: "product",
+  title: "Product",
+  type: "document",
+  description: "Product for Heirloom Supply catalog",
+  scope: {
+    tenants: ["heirloom"],
+  },
+  fields: [
+    {
+      name: "title",
+      type: "string",
+      title: "Product Name",
+      required: true,
+      options: {
+        maxLength: 200,
+      },
+    },
+    {
+      name: "slug",
+      type: "slug",
+      title: "Slug",
+      required: true,
+      options: {
+        source: "title",
+      },
+    },
+    {
+      name: "description",
+      type: "richText",
+      title: "Description",
+      required: true,
+    },
+    {
+      name: "price",
+      type: "number",
+      title: "Price",
+      required: true,
+      options: {
+        min: 0,
+      },
+    },
+    {
+      name: "images",
+      type: "array",
+      title: "Product Images",
+      required: true,
+      options: {
+        of: "image",
+        minLength: 1,
+      },
+    },
+    {
+      name: "category",
+      type: "reference",
+      title: "Category",
+      options: {
+        to: ["category"],
+      },
+    },
+    {
+      name: "tags",
+      type: "array",
+      title: "Tags",
+      options: {
+        of: "string",
+      },
+    },
+    {
+      name: "inStock",
+      type: "boolean",
+      title: "In Stock",
+    },
+  ],
+  preview: {
+    select: {
+      title: "title",
+      price: "price",
+      inStock: "inStock",
+    },
+    prepare: (selection) => ({
+      title: selection.title as string,
+      subtitle: `$${selection.price as number} ${(selection.inStock as boolean) ? "✓ In Stock" : "✗ Out of Stock"}`,
+    }),
+  },
+};
+

package/contracts/content/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Content Contracts Registry
+ *
+ * This file exports all content contracts. Add your project's content contracts
+ * here to have them included in the generated Sanity schema.
+ *
+ * Organization:
+ * - `shared/` - Contracts available to all tenants/properties
+ * - `heirloom/` - Contracts specific to Heirloom Supply tenant
+ * - `studioops/` - Contracts specific to StudioOps tenant
+ * - `example.ts` - Example contracts (replace with your actual contracts)
+ *
+ * For new contracts:
+ * 1. Create a contract file in the appropriate directory (tenant-specific or shared)
+ * 2. Import and add it to the `contentContracts` array below
+ */
+
+import type { ContentContract } from "./types";
+import { blogPostContract, heroSectionContract } from "./example";
+import { productContract } from "./heirloom/product";
+import { artistContract } from "./studioops/artist";
+
+/**
+ * Registry of all content contracts.
+ * Add your contracts here to include them in generated Sanity schema.
+ *
+ * Contracts are organized by tenant scope:
+ * - Shared contracts (no scope) - available to all tenants
+ * - Tenant-specific contracts - only available to specified tenants
+ */
+export const contentContracts: ContentContract[] = [
+  // Shared contracts (available to all tenants)
+  blogPostContract,
+  heroSectionContract,
+
+  // Heirloom Supply contracts
+  productContract,
+
+  // StudioOps contracts
+  artistContract,
+
+  // Add your project's content contracts here:
+  // import { myContentContract } from "./my-content";
+  // myContentContract,
+];
+
+/**
+ * Get a content contract by ID.
+ */
+export function getContentContract(id: string): ContentContract | undefined {
+  return contentContracts.find((contract) => contract.id === id);
+}
+
+/**
+ * Get all document contracts (type === "document").
+ */
+export function getDocumentContracts(): ContentContract[] {
+  return contentContracts.filter((contract) => contract.type === "document");
+}
+
+/**
+ * Get all object contracts (type === "object").
+ */
+export function getObjectContracts(): ContentContract[] {
+  return contentContracts.filter((contract) => contract.type === "object");
+}
+
+// Re-export utilities for convenience
+export * from "./utils";
+

package/contracts/content/shared/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared Content Contracts
+ *
+ * Content contracts available to all tenants and properties.
+ */
+
+import { blogPostContract, heroSectionContract } from "../example";
+
+// Mark example contracts as shared (no scope = available to all)
+// In practice, you'd update these in example.ts or create new shared contracts here
+
+export { blogPostContract, heroSectionContract };
+

package/contracts/content/studioops/artist.ts

@@ -0,0 +1,102 @@
+/**
+ * StudioOps Content Contracts
+ *
+ * Content contracts specific to StudioOps tenant.
+ */
+
+import type { ContentContract } from "../types";
+
+/**
+ * Artist profile document for StudioOps
+ */
+export const artistContract: ContentContract = {
+  id: "artist",
+  title: "Artist",
+  type: "document",
+  description: "Artist profile for StudioOps",
+  scope: {
+    tenants: ["studioops"],
+  },
+  fields: [
+    {
+      name: "name",
+      type: "string",
+      title: "Artist Name",
+      required: true,
+      options: {
+        maxLength: 200,
+      },
+    },
+    {
+      name: "slug",
+      type: "slug",
+      title: "Slug",
+      required: true,
+      options: {
+        source: "name",
+      },
+    },
+    {
+      name: "bio",
+      type: "richText",
+      title: "Biography",
+      description: "Artist biography and background",
+    },
+    {
+      name: "photo",
+      type: "image",
+      title: "Artist Photo",
+    },
+    {
+      name: "genre",
+      type: "string",
+      title: "Genre",
+      options: {
+        options: ["rock", "pop", "jazz", "classical", "electronic", "hip-hop", "country"],
+      },
+    },
+    {
+      name: "albums",
+      type: "array",
+      title: "Albums",
+      options: {
+        of: "reference",
+        to: ["album"],
+      },
+    },
+    {
+      name: "socialLinks",
+      type: "object",
+      title: "Social Links",
+      fields: [
+        {
+          name: "website",
+          type: "url",
+          title: "Website",
+        },
+        {
+          name: "spotify",
+          type: "url",
+          title: "Spotify",
+        },
+        {
+          name: "youtube",
+          type: "url",
+          title: "YouTube",
+        },
+      ],
+    },
+  ],
+  preview: {
+    select: {
+      title: "name",
+      genre: "genre",
+      photo: "photo",
+    },
+    prepare: (selection) => ({
+      title: selection.title as string,
+      subtitle: selection.genre as string,
+    }),
+  },
+};
+