@happyvertical/smrt-properties

Digital property and hierarchical zone management for the s-m-r-t framework. Properties represent websites, apps, or publications. Zones form an arbitrarily nested tree within each property for content and ad placement.

Installation

pnpm add @happyvertical/smrt-properties

Usage

import {
  Property, PropertyCollection,
  Zone, ZoneCollection
} from '@happyvertical/smrt-properties';

// Create a property
const properties = await PropertyCollection.create({ db });
const site = await properties.create({
  name: 'Oak Creek News',
  domain: 'oakcreeknews.com',
  url: 'https://oakcreeknews.com',
  status: 'active',
});
await site.save();

// Build a zone hierarchy: page -> section -> ad slot
const zones = await ZoneCollection.create({ db });
const homePage = await zones.create({
  propertyId: site.id,
  name: 'Home Page',
  type: 'page',
  path: '/',
});
await homePage.save();

const sidebar = await zones.create({
  propertyId: site.id,
  parentId: homePage.id,
  name: 'Sidebar',
  type: 'section',
  selector: '.sidebar',
});
await sidebar.save();

const adSlot = await zones.create({
  propertyId: site.id,
  parentId: sidebar.id,
  name: 'Sidebar Ad',
  type: 'slot',
  width: 300,
  height: 250,
  allowedFormats: ['image', 'html'],
});
await adSlot.save();

// Retrieve the full zone tree for a property
const tree = await zones.getTree(site.id);

// Move a zone (validates against descendant cycles)
await zones.moveZone(adSlot.id, homePage.id);

// Delete a zone — cascade=false moves children to parent
await zones.deleteZone(sidebar.id, false);

Zone hierarchy

Zones use parentId self-referencing to form a tree. Common zone types include page, section, slot, container, and widget. Each zone can specify a URL path pattern, CSS selector, position hint, pixel width/height, and an allowedFormats array for filtering content or ad types. An empty allowedFormats array means all formats are allowed (no restrictions).

The ZoneCollection provides tree operations: getTree() builds a nested structure in memory, getAncestors()/getDescendants() walk the hierarchy, and moveZone() prevents cycles by checking descendants before reparenting. deleteZone(cascade) either removes descendants or orphans children to the deleted zone's parent.

API

Models

| Export | Description | |--------|------------| | Property | Digital property (STI) with domain, URL, status, and owner/repository links | | Zone | Hierarchical zone within a property for content/ad placement |

Collections

| Export | Description | |--------|------------| | PropertyCollection | CRUD and queries for Property records | | ZoneCollection | Zone CRUD plus tree ops: getTree(), moveZone(), deleteZone(), getAncestors(), getDescendants() |

Key Types

PropertyOptions, PropertyStatus, ZoneOptions, ZoneTree, ZoneTreeNode

Dependencies

• @happyvertical/smrt-core -- ORM and code generation
• @happyvertical/smrt-tenancy -- optional multi-tenant scoping
• Peer: @happyvertical/smrt-profiles, @happyvertical/smrt-projects (optional)