levrops-contracts 1.1.0

package/contracts/content/types.ts

@@ -0,0 +1,180 @@
+/**
+ * Content Contract Types
+ *
+ * Defines the structure for content contracts that describe Sanity schema.
+ * LevrOps is the source of truth for content models; Sanity Studio consumes
+ * generated schema from these contracts.
+ */
+
+/**
+ * Supported field types in content contracts.
+ */
+export type ContentFieldType =
+  | "string"
+  | "text"
+  | "number"
+  | "boolean"
+  | "date"
+  | "datetime"
+  | "url"
+  | "email"
+  | "slug"
+  | "richText"
+  | "image"
+  | "file"
+  | "array"
+  | "object"
+  | "reference";
+
+/**
+ * Options for field configuration.
+ * Field type-specific options are provided here.
+ */
+export interface ContentFieldOptions {
+  /**
+   * For string fields: max length
+   * For array fields: max items
+   */
+  maxLength?: number;
+  /**
+   * For string fields: min length
+   * For array fields: min items
+   */
+  minLength?: number;
+  /**
+   * For string fields: pattern/regex validation
+   */
+  pattern?: string;
+  /**
+   * For number fields: min value
+   */
+  min?: number;
+  /**
+   * For number fields: max value
+   */
+  max?: number;
+  /**
+   * For string fields: enum of allowed values
+   */
+  options?: string[];
+  /**
+   * For array fields: the type of items in the array
+   */
+  of?: ContentFieldType;
+  /**
+   * For reference fields: array of document type names this can reference
+   */
+  to?: string[];
+  /**
+   * For slug fields: the field name to use as source (default: "title")
+   */
+  source?: string;
+  /**
+   * For richText fields: allowed annotation types (e.g., ["link", "internalLink"])
+   */
+  annotations?: string[];
+  /**
+   * For richText fields: allowed decorators (e.g., ["strong", "em", "code"])
+   */
+  decorators?: string[];
+}
+
+/**
+ * A field definition within a content contract.
+ */
+export interface ContentField {
+  /**
+   * Field name (camelCase)
+   */
+  name: string;
+  /**
+   * Field type
+   */
+  type: ContentFieldType;
+  /**
+   * Field title (human-readable, used in Sanity Studio)
+   */
+  title?: string;
+  /**
+   * Field description
+   */
+  description?: string;
+  /**
+   * Whether the field is required
+   */
+  required?: boolean;
+  /**
+   * Type-specific field options
+   */
+  options?: ContentFieldOptions;
+}
+
+/**
+ * Multi-tenant scope configuration for content contracts.
+ */
+export interface ContentContractScope {
+  /**
+   * Tenant slugs that can use this contract.
+   * If empty or undefined, the contract is available to all tenants.
+   * Examples: ["heirloom", "studioops"]
+   */
+  tenants?: string[];
+  /**
+   * Property slugs that can use this contract.
+   * If empty or undefined, the contract is available to all properties.
+   * Examples: ["store1", "store2"]
+   */
+  properties?: string[];
+  /**
+   * Whether this contract is required for specific tenants/properties.
+   */
+  requiredFor?: {
+    /**
+     * Tenant slugs where this contract is required.
+     */
+    tenants?: string[];
+    /**
+     * Property slugs where this contract is required.
+     */
+    properties?: string[];
+  };
+}
+
+/**
+ * A content contract defining a document or object type.
+ */
+export interface ContentContract {
+  /**
+   * Unique identifier for the contract (kebab-case, e.g., "blog-post", "hero-section")
+   */
+  id: string;
+  /**
+   * Human-readable title (used in Sanity Studio UI)
+   */
+  title: string;
+  /**
+   * Whether this is a document (can be queried standalone) or object (nested type)
+   */
+  type: "document" | "object";
+  /**
+   * Description of the content type
+   */
+  description?: string;
+  /**
+   * Fields that make up this content type
+   */
+  fields: ContentField[];
+  /**
+   * For document types: preview configuration
+   */
+  preview?: {
+    select: Record<string, string>;
+    prepare?: (selection: Record<string, unknown>) => { title?: string; subtitle?: string };
+  };
+  /**
+   * Multi-tenant/property scope configuration.
+   * If omitted, the contract is available to all tenants and properties.
+   */
+  scope?: ContentContractScope;
+}
+

package/contracts/content/utils.ts

@@ -0,0 +1,148 @@
+/**
+ * Content Contract Utilities
+ *
+ * Utilities for filtering and managing content contracts by tenant and property.
+ */
+
+import type { ContentContract } from "./types";
+
+/**
+ * Filter content contracts by tenant.
+ *
+ * @param contracts - Array of content contracts to filter
+ * @param tenant - Tenant slug to filter by
+ * @returns Filtered contracts that are available to the specified tenant
+ */
+export function filterContractsByTenant(
+  contracts: ContentContract[],
+  tenant: string
+): ContentContract[] {
+  return contracts.filter((contract) => {
+    const scope = contract.scope;
+    
+    // If no scope, available to all tenants
+    if (!scope || !scope.tenants || scope.tenants.length === 0) {
+      return true;
+    }
+    
+    // Check if tenant is in the allowed list
+    return scope.tenants.includes(tenant);
+  });
+}
+
+/**
+ * Filter content contracts by property.
+ *
+ * @param contracts - Array of content contracts to filter
+ * @param property - Property slug to filter by
+ * @returns Filtered contracts that are available to the specified property
+ */
+export function filterContractsByProperty(
+  contracts: ContentContract[],
+  property: string
+): ContentContract[] {
+  return contracts.filter((contract) => {
+    const scope = contract.scope;
+    
+    // If no scope, available to all properties
+    if (!scope || !scope.properties || scope.properties.length === 0) {
+      return true;
+    }
+    
+    // Check if property is in the allowed list
+    return scope.properties.includes(property);
+  });
+}
+
+/**
+ * Filter content contracts by tenant and property.
+ *
+ * @param contracts - Array of content contracts to filter
+ * @param tenant - Tenant slug to filter by
+ * @param property - Optional property slug to filter by
+ * @returns Filtered contracts that are available to the specified tenant (and property if provided)
+ */
+export function filterContracts(
+  contracts: ContentContract[],
+  tenant: string,
+  property?: string
+): ContentContract[] {
+  let filtered = filterContractsByTenant(contracts, tenant);
+  
+  if (property) {
+    filtered = filterContractsByProperty(filtered, property);
+  }
+  
+  return filtered;
+}
+
+/**
+ * Get contracts required for a specific tenant.
+ *
+ * @param contracts - Array of content contracts
+ * @param tenant - Tenant slug
+ * @returns Contracts that are required for the specified tenant
+ */
+export function getRequiredContractsForTenant(
+  contracts: ContentContract[],
+  tenant: string
+): ContentContract[] {
+  return contracts.filter((contract) => {
+    const scope = contract.scope;
+    return scope?.requiredFor?.tenants?.includes(tenant) ?? false;
+  });
+}
+
+/**
+ * Get contracts required for a specific property.
+ *
+ * @param contracts - Array of content contracts
+ * @param property - Property slug
+ * @returns Contracts that are required for the specified property
+ */
+export function getRequiredContractsForProperty(
+  contracts: ContentContract[],
+  property: string
+): ContentContract[] {
+  return contracts.filter((contract) => {
+    const scope = contract.scope;
+    return scope?.requiredFor?.properties?.includes(property) ?? false;
+  });
+}
+
+/**
+ * Group contracts by tenant.
+ *
+ * @param contracts - Array of content contracts
+ * @returns Object mapping tenant slugs to their available contracts
+ */
+export function groupContractsByTenant(
+  contracts: ContentContract[]
+): Record<string, ContentContract[]> {
+  const grouped: Record<string, ContentContract[]> = {};
+  
+  contracts.forEach((contract) => {
+    const scope = contract.scope;
+    
+    // If no scope, add to all tenants (we'll handle this separately)
+    if (!scope || !scope.tenants || scope.tenants.length === 0) {
+      // Shared contracts - add to a special key
+      if (!grouped["_shared"]) {
+        grouped["_shared"] = [];
+      }
+      grouped["_shared"].push(contract);
+      return;
+    }
+    
+    // Add to each tenant's list
+    scope.tenants.forEach((tenant) => {
+      if (!grouped[tenant]) {
+        grouped[tenant] = [];
+      }
+      grouped[tenant].push(contract);
+    });
+  });
+  
+  return grouped;
+}
+

package/index.ts

@@ -0,0 +1,20 @@
+/**
+ * LevrOps Contracts
+ *
+ * Main entry point for consuming content contracts and generated Sanity schemas.
+ */
+
+// Export content contracts
+export * from "./contracts/content";
+
+// Export Sanity utilities
+export * from "./sanity/utils";
+
+// Re-export commonly used types
+export type {
+  ContentContract,
+  ContentField,
+  ContentFieldOptions,
+  ContentContractScope,
+} from "./contracts/content/types";
+

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "levrops-contracts",
+  "version": "1.1.0",
+  "description": "LevrOps API contracts, schemas, code generators, and Sanity content contracts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jackmckracken/levrops-contracts.git"
+  },
+  "homepage": "https://github.com/jackmckracken/levrops-contracts#readme",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts"
+    },
+    "./sanity/generated/schema": "./sanity/generated/schema.ts",
+    "./sanity/generated/schema-*": "./sanity/generated/schema-*.ts",
+    "./sanity/utils": "./sanity/utils.ts",
+    "./contracts/content": "./contracts/content/index.ts"
+  },
+  "files": [
+    "contracts/",
+    "sanity/",
+    "index.ts",
+    "README.md",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "sanity:codegen": "tsx tools/levrops-sanity-codegen.ts",
+    "sanity:check": "tsx tools/sanity-check.ts"
+  },
+  "dependencies": {
+    "sanity": "^3.56.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+

package/sanity/generated/schema-heirloom.ts

@@ -0,0 +1,223 @@
+import { defineType, defineField, string, text, number, boolean, date, datetime, url, email, slug, image, file, array, object, reference } from "sanity";
+
+/**
+ * Generated Sanity Schema
+ *
+ * This file is auto-generated from content contracts in contracts/content/.
+ * DO NOT EDIT THIS FILE DIRECTLY.
+ *
+ * Content contracts for heirloom tenant
+ *
+ * To update the schema:
+ * 1. Update or add contracts in contracts/content/
+ * 2. Run: npm run sanity:codegen
+ *    (or: npm run sanity:codegen -- --tenant=<tenant> --property=<property>)
+ *
+ * Generated: 2025-11-14T19:30:16.455Z
+ */
+
+// Blog Post
+// A blog post article
+export const BlogPost = defineType({
+  name: "blog-post",
+  title: "Blog Post",
+  type: "document",
+  description: "A blog post article",
+  fields: [
+    defineField({
+      name: "title",
+      type: string(),
+      title: "Title",
+      validation: (Rule) => Rule.required().and(Rule.max(200)),
+
+    }),
+    defineField({
+      name: "slug",
+      type: slug({ source: "title" }),
+      title: "Slug",
+      validation: (Rule) => Rule.required(),
+
+    }),
+    defineField({
+      name: "author",
+      type: reference({ to: [{ type: "author" }] }),
+      title: "Author",
+      validation: (Rule) => Rule.required(),
+
+    }),
+    defineField({
+      name: "publishedAt",
+      type: datetime(),
+      title: "Published At",
+      validation: (Rule) => Rule.required(),
+
+    }),
+    defineField({
+      name: "excerpt",
+      type: text(),
+      title: "Excerpt",
+      description: "Short summary for previews",
+
+    }),
+    defineField({
+      name: "content",
+      type: array({
+    of: [{ type: "block" }],
+  }),
+      title: "Content",
+      validation: (Rule) => Rule.required(),
+
+    }),
+    defineField({
+      name: "tags",
+      type: array({
+    of: [string()],
+  }),
+      title: "Tags",
+
+    }),
+    defineField({
+      name: "featuredImage",
+      type: image(),
+      title: "Featured Image",
+
+    }),
+  ],
+  preview: {
+    select: {
+      "title": "title",
+      "author": "author.name",
+      "publishedAt": "publishedAt"
+},
+    // prepare: (selection) => { ... } // Custom prepare function
+  },
+});
+
+// Hero Section
+// Hero banner section for landing pages
+export const HeroSection = defineType({
+  name: "hero-section",
+  title: "Hero Section",
+  type: "object",
+  description: "Hero banner section for landing pages",
+  fields: [
+    defineField({
+      name: "headline",
+      type: string(),
+      title: "Headline",
+      validation: (Rule) => Rule.required().and(Rule.max(100)),
+
+    }),
+    defineField({
+      name: "subheadline",
+      type: text(),
+      title: "Subheadline",
+
+    }),
+    defineField({
+      name: "image",
+      type: image(),
+      title: "Background Image",
+      validation: (Rule) => Rule.required(),
+
+    }),
+    defineField({
+      name: "ctaText",
+      type: string(),
+      title: "CTA Button Text",
+
+    }),
+    defineField({
+      name: "ctaLink",
+      type: url(),
+      title: "CTA Link",
+
+    }),
+  ],
+});
+
+// Product
+// Product for Heirloom Supply catalog
+export const Product = defineType({
+  name: "product",
+  title: "Product",
+  type: "document",
+  description: "Product for Heirloom Supply catalog",
+  fields: [
+    defineField({
+      name: "title",
+      type: string(),
+      title: "Product Name",
+      validation: (Rule) => Rule.required().and(Rule.max(200)),
+
+    }),
+    defineField({
+      name: "slug",
+      type: slug({ source: "title" }),
+      title: "Slug",
+      validation: (Rule) => Rule.required(),
+
+    }),
+    defineField({
+      name: "description",
+      type: array({
+    of: [{ type: "block" }],
+  }),
+      title: "Description",
+      validation: (Rule) => Rule.required(),
+
+    }),
+    defineField({
+      name: "price",
+      type: number(),
+      title: "Price",
+      validation: (Rule) => Rule.required().and(Rule.min(0)),
+
+    }),
+    defineField({
+      name: "images",
+      type: array({
+    of: [image()],
+    validation: (Rule) => Rule.min(1),
+  }),
+      title: "Product Images",
+      validation: (Rule) => Rule.required(),
+
+    }),
+    defineField({
+      name: "category",
+      type: reference({ to: [{ type: "category" }] }),
+      title: "Category",
+
+    }),
+    defineField({
+      name: "tags",
+      type: array({
+    of: [string()],
+  }),
+      title: "Tags",
+
+    }),
+    defineField({
+      name: "inStock",
+      type: boolean(),
+      title: "In Stock",
+
+    }),
+  ],
+  preview: {
+    select: {
+      "title": "title",
+      "price": "price",
+      "inStock": "inStock"
+},
+    // prepare: (selection) => { ... } // Custom prepare function
+  },
+});
+
+// Export all schemas
+export const allSchemas = [
+  BlogPost,
+  HeroSection,
+  Product,
+];