levrops-contracts 1.3.1 → 1.3.2

package/README.md

@@ -8,6 +8,8 @@ Source of truth for LevrOps API and event contracts, JSON schemas, and generated
 - `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
@@ -134,6 +136,87 @@ export default {
 
 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
+
 ## Versioning
 
 - Use semantic versioning for the repo (`VERSION`) and the TypeScript SDK.

package/contracts/backend/schema/migration_discipline.schema.yaml

@@ -0,0 +1,220 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "https://contracts.levrops.com/schemas/backend/migration_discipline.json"
+title: "Migration Drift Prevention Contract"
+description: |
+  Defines rules and constraints for Django migrations in a multi-tenant
+  django-tenants environment to prevent migration drift, cross-tenancy FK
+  violations, and improper migration ordering.
+
+type: object
+required:
+  - version
+  - rules
+  - enforcement
+
+properties:
+  version:
+    type: string
+    description: "Contract version (semver)"
+    pattern: "^\\d+\\.\\d+\\.\\d+$"
+    default: "1.0.0"
+
+  rules:
+    type: object
+    description: "Migration discipline rules"
+    required:
+      - migration_commands
+      - cross_tenancy_fk
+      - migration_dependencies
+
+    properties:
+      migration_commands:
+        type: object
+        description: "Rules for allowed migration commands"
+        properties:
+          forbidden_patterns:
+            type: array
+            description: |
+              Command patterns that are forbidden. These patterns match
+              app-level migrate commands that bypass schema/tenant isolation.
+            items:
+              type: string
+            default:
+              - "manage.py migrate core"
+              - "manage.py migrate org"
+              - "manage.py migrate [a-z_]+"
+            examples:
+              - "manage.py migrate core"
+              - "manage.py migrate org"
+              - "manage.py migrate api"
+
+          required_patterns:
+            type: array
+            description: |
+              Command patterns that must be used instead. These ensure
+              proper schema/tenant isolation.
+            items:
+              type: string
+            default:
+              - "manage.py migrate"
+              - "manage.py migrate_schemas --shared"
+              - "manage.py migrate_schemas --tenant"
+
+          explanation:
+            type: string
+            description: "Human-readable explanation of why app-level migrations are forbidden"
+            default: |
+              In django-tenants, app-level migrations (e.g., `migrate core`)
+              bypass schema isolation and can cause migration drift. Always use:
+              - `manage.py migrate` (for public schema)
+              - `manage.py migrate_schemas --shared` (for shared apps)
+              - `manage.py migrate_schemas --tenant` (for tenant apps)
+
+      cross_tenancy_fk:
+        type: object
+        description: "Rules preventing cross-tenancy foreign key violations"
+        properties:
+          forbidden:
+            type: boolean
+            description: "Whether cross-tenancy FKs are forbidden"
+            default: true
+
+          definition:
+            type: string
+            description: "What constitutes a cross-tenancy FK violation"
+            default: |
+              A model in SHARED_APPS having a ForeignKey, OneToOneField, or
+              ManyToManyField to a model in TENANT_APPS (or vice versa).
+
+          allowed_exceptions:
+            type: array
+            description: |
+              Specific model/field combinations that are allowed despite
+              being cross-tenancy. Use sparingly and document why.
+            items:
+              type: object
+              properties:
+                app:
+                  type: string
+                model:
+                  type: string
+                field:
+                  type: string
+                reason:
+                  type: string
+            default: []
+
+          explanation:
+            type: string
+            description: "Why cross-tenancy FKs are problematic"
+            default: |
+              Cross-tenancy FKs break schema isolation. Shared apps are
+              schema-agnostic and cannot reference tenant-specific models.
+              Tenant apps cannot reference shared models via FK (use string
+              IDs or separate lookup tables instead).
+
+      migration_dependencies:
+        type: object
+        description: "Rules for migration dependency declarations"
+        properties:
+          require_explicit_dependencies:
+            type: boolean
+            description: |
+              Whether migrations that create cross-app FKs must explicitly
+              declare dependencies on the target app's migrations.
+            default: true
+
+          dependency_detection:
+            type: object
+            description: "How to detect missing dependencies"
+            properties:
+              scan_patterns:
+                type: array
+                description: "File patterns to scan for migrations"
+                items:
+                  type: string
+                default:
+                  - "apps/*/migrations/*.py"
+                  - "*/migrations/*.py"
+
+              field_types:
+                type: array
+                description: "Field types that create dependencies"
+                items:
+                  type: string
+                default:
+                  - "ForeignKey"
+                  - "OneToOneField"
+                  - "ManyToManyField"
+
+          explanation:
+            type: string
+            description: "Why explicit dependencies are required"
+            default: |
+              When a migration in app A creates a FK to app B, it must
+              explicitly depend on app B's latest migration. This ensures
+              migrations run in the correct order and prevents dependency
+              errors in fresh databases.
+
+  enforcement:
+    type: object
+    description: "How these rules are enforced"
+    properties:
+      pre_commit_checks:
+        type: boolean
+        description: "Whether checks run pre-commit"
+        default: true
+
+      ci_checks:
+        type: boolean
+        description: "Whether checks run in CI"
+        default: true
+
+      scripts:
+        type: object
+        description: "Scripts that enforce these rules"
+        properties:
+          guard_migrate_commands:
+            type: string
+            description: "Script that guards against forbidden migrate commands"
+            default: "scripts/guard_migrate_commands.py"
+
+          check_cross_tenancy_fk:
+            type: string
+            description: "Script that checks for cross-tenancy FK violations"
+            default: "scripts/check_cross_tenancy_fk.py"
+
+          check_migration_dependencies:
+            type: string
+            description: "Script that checks migration dependency declarations"
+            default: "scripts/check_migration_dependencies.py"
+
+      make_target:
+        type: string
+        description: "Make target that runs all checks"
+        default: "check-schema-discipline"
+
+examples:
+  - |
+    version: "1.0.0"
+    rules:
+      migration_commands:
+        forbidden_patterns:
+          - "manage.py migrate core"
+          - "manage.py migrate org"
+        required_patterns:
+          - "manage.py migrate"
+          - "manage.py migrate_schemas --shared"
+          - "manage.py migrate_schemas --tenant"
+      cross_tenancy_fk:
+        forbidden: true
+        allowed_exceptions: []
+      migration_dependencies:
+        require_explicit_dependencies: true
+    enforcement:
+      ci_checks: true
+      scripts:
+        guard_migrate_commands: "scripts/guard_migrate_commands.py"
+        check_cross_tenancy_fk: "scripts/check_cross_tenancy_fk.py"
+        check_migration_dependencies: "scripts/check_migration_dependencies.py"
+

package/contracts/content/heirloom/lead-capture.ts

@@ -0,0 +1,212 @@
+/**
+ * Lead Capture Module Content Contract
+ * 
+ * Reusable lead capture form module for Heirloom Supply.
+ * Can be placed inline, in hero, footer, or as a modal.
+ */
+
+import type { ContentContract } from "../types";
+
+export const leadCaptureModuleContract: ContentContract = {
+  id: "lead-capture-module",
+  title: "Lead Capture Module",
+  type: "document",
+  description: "Reusable lead capture form module with configurable variants and messaging",
+  scope: {
+    tenants: ["hewn"],
+  },
+  fields: [
+    {
+      name: "title",
+      type: "string",
+      title: "Title",
+      description: "Internal title for this module (not displayed)",
+      required: true,
+      options: {
+        maxLength: 200,
+      },
+    },
+    {
+      name: "slug",
+      type: "slug",
+      title: "Slug",
+      description: "Unique identifier for this module (used for tracking)",
+      required: true,
+      options: {
+        source: "title",
+      },
+    },
+    {
+      name: "variant",
+      type: "string",
+      title: "Variant",
+      description: "Visual variant/style of the form",
+      required: true,
+      options: {
+        options: ["inline", "hero", "footer", "modal"],
+      },
+    },
+    {
+      name: "headline",
+      type: "string",
+      title: "Headline",
+      description: "Main headline text",
+      required: true,
+      options: {
+        maxLength: 100,
+      },
+    },
+    {
+      name: "subcopy",
+      type: "text",
+      title: "Subcopy",
+      description: "Supporting text below headline",
+      required: false,
+    },
+    {
+      name: "ctaText",
+      type: "string",
+      title: "CTA Text",
+      description: "Button text (e.g., 'Subscribe', 'Get Started')",
+      required: true,
+      options: {
+        maxLength: 50,
+      },
+    },
+    {
+      name: "disclaimer",
+      type: "text",
+      title: "Disclaimer",
+      description: "Optional disclaimer text (privacy, terms, etc.)",
+      required: false,
+    },
+    {
+      name: "listId",
+      type: "string",
+      title: "List ID",
+      description: "Optional email list ID for segmentation",
+      required: false,
+    },
+    {
+      name: "tag",
+      type: "string",
+      title: "Tag",
+      description: "Optional tag for lead categorization",
+      required: false,
+    },
+    {
+      name: "successMessage",
+      type: "string",
+      title: "Success Message",
+      description: "Message shown after successful submission",
+      required: true,
+      options: {
+        maxLength: 200,
+      },
+    },
+    {
+      name: "designOverrides",
+      type: "object",
+      title: "Design Overrides",
+      description: "Optional design system overrides (colors, spacing, etc.)",
+      required: false,
+    },
+  ],
+  preview: {
+    select: {
+      title: "title",
+      variant: "variant",
+      slug: "slug.current",
+    },
+    prepare: (selection) => ({
+      title: selection.title,
+      subtitle: `${selection.variant} • ${selection.slug || "no slug"}`,
+    }),
+  },
+};
+
+export const marketingSettingsContract: ContentContract = {
+  id: "marketing-settings",
+  title: "Marketing Settings",
+  type: "document",
+  description: "Global marketing settings including lead capture placements",
+  scope: {
+    tenants: ["hewn"],
+  },
+  fields: [
+    {
+      name: "globalLeadModule",
+      type: "reference",
+      title: "Global Lead Module",
+      description: "Default lead capture module for global placements",
+      required: false,
+      options: {
+        to: ["lead-capture-module"],
+      },
+    },
+    {
+      name: "showHeaderBar",
+      type: "boolean",
+      title: "Show Header Bar",
+      description: "Display lead capture in header bar",
+      required: false,
+    },
+    {
+      name: "showExitModal",
+      type: "boolean",
+      title: "Show Exit Modal",
+      description: "Display lead capture modal on exit intent",
+      required: false,
+    },
+    {
+      name: "exitModalModule",
+      type: "reference",
+      title: "Exit Modal Module",
+      description: "Lead capture module to show in exit modal",
+      required: false,
+      options: {
+        to: ["lead-capture-module"],
+      },
+    },
+  ],
+  preview: {
+    select: {
+      showHeader: "showHeaderBar",
+      showExit: "showExitModal",
+    },
+    prepare: (selection) => ({
+      title: "Marketing Settings",
+      subtitle: `Header: ${selection.showHeader ? "On" : "Off"} • Exit Modal: ${selection.showExit ? "On" : "Off"}`,
+    }),
+  },
+};
+
+export const moduleRefBlockContract: ContentContract = {
+  id: "module-ref-block",
+  title: "Module Reference Block",
+  type: "object",
+  description: "Block type for referencing a lead capture module in page builder",
+  scope: {
+    tenants: ["hewn"],
+  },
+  fields: [
+    {
+      name: "module",
+      type: "reference",
+      title: "Module",
+      description: "Lead capture module to render",
+      required: true,
+      options: {
+        to: ["lead-capture-module"],
+      },
+    },
+    {
+      name: "anchorId",
+      type: "string",
+      title: "Anchor ID",
+      description: "Optional anchor ID for deep linking",
+      required: false,
+    },
+  ],
+};
+

package/contracts/content/index.ts

@@ -18,6 +18,11 @@
 import type { ContentContract } from "./types";
 import { blogPostContract, heroSectionContract } from "./example";
 import { productContract } from "./heirloom/product";
+import {
+  leadCaptureModuleContract,
+  marketingSettingsContract,
+  moduleRefBlockContract,
+} from "./heirloom/lead-capture";
 import { artistContract } from "./studioops/artist";
 
 /**
@@ -35,6 +40,9 @@ export const contentContracts: ContentContract[] = [
 
   // Heirloom Supply contracts
   productContract,
+  leadCaptureModuleContract,
+  marketingSettingsContract,
+  moduleRefBlockContract,
 
   // StudioOps contracts
   artistContract,

package/creative/README.md

@@ -0,0 +1,21 @@
+# Creative Whisperer Contracts
+
+JSON schemas for Creative Whisperer synthesis—extracting and synthesizing creative signals from artist assets.
+
+## Schemas
+
+| Schema | Description |
+|--------|-------------|
+| `creative_signal_profile.schema.json` | Extracted profile from a single asset (emotions, themes, energy, intensity, etc.) |
+| `creative_edge_alignment.schema.json` | Alignment metrics between two profiles (semantic, emotional, theme overlap) |
+| `creative_cluster.schema.json` | Cluster of related profiles grouped by affinity |
+| `creative_whisper.schema.json` | Synthesis output (cluster summary, patterns, citations, follow-up questions) |
+
+## Enums
+
+- **asset_type**: `note` | `audio` | `url` | `lyric` | `image` | `other`
+- **energy**: `low` | `mid` | `high`
+
+## References
+
+- `$id` base: `https://contracts.levrops.com/creative/`

package/creative/creative_cluster.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.levrops.com/creative/creative_cluster.schema.json",
+  "title": "CreativeCluster",
+  "description": "A cluster of related creative signal profiles grouped by semantic/emotional affinity for Creative Whisperer synthesis.",
+  "type": "object",
+  "required": ["cluster_id", "asset_ids"],
+  "properties": {
+    "cluster_id": {
+      "type": "string",
+      "description": "Unique identifier for the cluster",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "asset_ids": {
+      "type": "array",
+      "description": "IDs of assets in this cluster",
+      "items": { "type": "string", "minLength": 1, "maxLength": 255 },
+      "minItems": 1,
+      "maxItems": 100
+    },
+    "dominant_emotions": {
+      "type": "array",
+      "description": "Dominant emotions across the cluster",
+      "items": { "type": "string", "maxLength": 100 },
+      "maxItems": 10,
+      "default": []
+    },
+    "dominant_themes": {
+      "type": "array",
+      "description": "Dominant themes across the cluster",
+      "items": { "type": "string", "maxLength": 100 },
+      "maxItems": 10,
+      "default": []
+    },
+    "cohesion_score": {
+      "type": "number",
+      "description": "How tightly the cluster coheres (0–1)",
+      "minimum": 0,
+      "maximum": 1
+    }
+  },
+  "additionalProperties": false
+}

package/creative/creative_edge_alignment.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.levrops.com/creative/creative_edge_alignment.schema.json",
+  "title": "CreativeEdgeAlignment",
+  "description": "Alignment metrics between two creative signal profiles. Used to measure semantic, emotional, and thematic overlap for Creative Whisperer synthesis.",
+  "type": "object",
+  "required": [
+    "source_asset_id",
+    "target_asset_id",
+    "semantic_score",
+    "emotional_score",
+    "theme_overlap_count",
+    "motif_overlap_count",
+    "resonance_score"
+  ],
+  "properties": {
+    "source_asset_id": {
+      "type": "string",
+      "description": "ID of the source asset",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "target_asset_id": {
+      "type": "string",
+      "description": "ID of the target asset being aligned",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "semantic_score": {
+      "type": "number",
+      "description": "Semantic similarity score (0–1)",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "emotional_score": {
+      "type": "number",
+      "description": "Emotional alignment score (0–1)",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "theme_overlap_count": {
+      "type": "integer",
+      "description": "Number of overlapping themes",
+      "minimum": 0
+    },
+    "motif_overlap_count": {
+      "type": "integer",
+      "description": "Number of overlapping motifs/imagery",
+      "minimum": 0
+    },
+    "resonance_score": {
+      "type": "number",
+      "description": "Overall resonance score (0–1)",
+      "minimum": 0,
+      "maximum": 1
+    }
+  },
+  "additionalProperties": false
+}