@happyvertical/smrt-properties 0.30.0

package/AGENTS.md

@@ -0,0 +1,38 @@
+# @happyvertical/smrt-properties
+
+Digital properties (websites, apps) with hierarchical zones for content/ad placement.
+
+## Models
+
+- **Property** (STI): `domain`, `url`, optional repository/owner links. Status: active/inactive/pending. Methods dynamically import/create ZoneCollection for lazy loading.
+- **Zone**: hierarchical via `parentId`. `path`/`selector`/`dimensions` for placement. `allowedFormats` array. Tree operations: `getAncestors()`, `getDescendants()`, `getFullPath()`, `moveZone()` (with cycle detection).
+
+## ZoneCollection Key Methods
+
+`getTree()` (builds nested structure), `moveZone()` (validates against descendant cycles), `deleteZone(cascade?)` (cascade=false orphans children to parent), `findWithGlobals(tenantId)`.
+
+In-memory depth caching prevents N+1 queries during tree operations.
+
+## Property Key Methods
+
+- `getZones()` / `getZoneTree()` / `createZone()` — ZoneCollection wrappers loaded lazily via dynamic import.
+- `isActive()` — convenience status check.
+- AI: `summarize()` (uses `smrtProperties.property.summarize` prompt via `@happyvertical/smrt-prompts`).
+
+## Prompt Registry
+
+`Property.summarize()` is registered with `@happyvertical/smrt-prompts` so tenants can override the template/model/params at runtime:
+
+```typescript
+import { smrtPropertiesSummarizePrompt } from '@happyvertical/smrt-properties';
+// key: 'smrtProperties.property.summarize'
+```
+
+Only non-PII fields are passed to the AI provider: `name`, `domain`, `description`, `status`, plus aggregate zone information (count + top-level zone names). Internal foreign-key fields (`ownerId`, `repositoryId`, `tenantId`) and the extensible `metadata` blob are intentionally excluded — `metadata` may contain analytics IDs or tenant-private configuration.
+
+## Gotchas
+
+- **Empty allowedFormats = all formats**: empty array means no restrictions, not no formats
+- **Zone dimensions nullable independently**: check `hasDimensions()` before using width/height
+- **deleteZone(cascade=false)**: doesn't delete children — moves them to parent (orphan pattern)
+- **Optional tenancy** on both models

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @happyvertical/smrt-properties
+
+Digital property and hierarchical zone management for the SMRT framework. Properties represent websites, apps, or publications. Zones form an arbitrarily nested tree within each property for content and ad placement.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-properties
+```
+
+## Usage
+
+```typescript
+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)

package/dist/index.d.ts

@@ -0,0 +1,431 @@
+import { PromptDefinition } from '@happyvertical/smrt-prompts';
+import { ResolvedPromptAI } from '@happyvertical/smrt-prompts';
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtHierarchical } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+
+export declare function promptMessageOptions(ai: ResolvedPromptAI): {
+    maxTokens?: number | undefined;
+    temperature?: number | undefined;
+    model?: string | undefined;
+};
+
+export declare class Property extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenant isolation
+     */
+    tenantId: string | null;
+    /**
+     * Display name of the property
+     */
+    name: string;
+    /**
+     * Domain name (e.g., "oakcreeknews.com")
+     */
+    domain: string;
+    /**
+     * Full URL (e.g., "https://oakcreeknews.com")
+     */
+    url: string;
+    /**
+     * Property description
+     */
+    description: string;
+    /**
+     * Link to Repository (from smrt-projects)
+     * Optional - used when property is backed by a git repository
+     */
+    repositoryId: string | null;
+    /**
+     * Link to Profile (from smrt-profiles)
+     * Optional - owner/publisher of the property
+     */
+    ownerId: string | null;
+    /**
+     * Property status
+     */
+    status: PropertyStatus;
+    /**
+     * Extensible metadata (analytics IDs, config, etc.)
+     */
+    metadata: Record<string, unknown>;
+    constructor(options?: PropertyOptions);
+    /**
+     * Get all zones for this property
+     */
+    getZones(): Promise<Zone[]>;
+    /**
+     * Get zone tree for this property
+     */
+    getZoneTree(): Promise<ZoneTree<Zone>>;
+    /**
+     * Create a zone on this property
+     */
+    createZone(options: Omit<ZoneOptions, 'propertyId'>): Promise<Zone>;
+    /**
+     * Check if property is active
+     */
+    isActive(): boolean;
+    /**
+     * AI-powered: Generate a summary of the property and its zones.
+     *
+     * Uses the `smrtProperties.property.summarize` prompt registered via
+     * `@happyvertical/smrt-prompts`, allowing tenant- or instance-level
+     * overrides of the template, model, and parameters at runtime.
+     *
+     * Only non-PII fields (name, domain, description, status) plus aggregate
+     * zone information are sent to the AI provider. Internal foreign-key
+     * fields and the extensible `metadata` blob are intentionally excluded.
+     *
+     * @returns Generated summary text
+     */
+    summarize(): Promise<string>;
+}
+
+export declare class PropertyCollection extends SmrtCollection<Property> {
+    static readonly _itemClass: typeof Property;
+    /**
+     * Find a property by domain
+     *
+     * @param domain - Domain name
+     * @returns Property or null
+     */
+    findByDomain(domain: string): Promise<Property | null>;
+    /**
+     * Find properties by repository ID
+     *
+     * @param repositoryId - Repository ID
+     * @returns Array of properties
+     */
+    findByRepository(repositoryId: string): Promise<Property[]>;
+    /**
+     * Find properties by owner ID
+     *
+     * @param ownerId - Owner profile ID
+     * @returns Array of properties
+     */
+    findByOwner(ownerId: string): Promise<Property[]>;
+    /**
+     * Find active properties
+     *
+     * @returns Array of active properties
+     */
+    findActive(): Promise<Property[]>;
+    /**
+     * Find properties by status
+     *
+     * @param status - Property status
+     * @returns Array of properties with the given status
+     */
+    findByStatus(status: PropertyStatus): Promise<Property[]>;
+    /**
+     * Get or create a property by domain
+     *
+     * @param domain - Domain name
+     * @param defaults - Default values for creation
+     * @returns Property (existing or newly created)
+     */
+    getOrCreateByDomain(domain: string, defaults?: {
+        name?: string;
+        url?: string;
+        repositoryId?: string | null;
+        ownerId?: string | null;
+    }): Promise<Property>;
+    /**
+     * Count properties by status
+     *
+     * @returns Object with counts per status
+     */
+    countByStatus(): Promise<Record<PropertyStatus, number>>;
+    /**
+     * Find properties belonging to a specific tenant
+     *
+     * @param tenantId - Tenant ID to filter by
+     * @returns Array of properties for the tenant
+     */
+    findByTenant(tenantId: string): Promise<Property[]>;
+    /**
+     * Find global properties (no tenant association)
+     *
+     * @returns Array of global properties
+     */
+    findGlobal(): Promise<Property[]>;
+    /**
+     * Find properties for a tenant including global properties
+     *
+     * @param tenantId - Tenant ID to filter by
+     * @returns Array of tenant-specific and global properties
+     */
+    findWithGlobals(tenantId: string): Promise<Property[]>;
+}
+
+/**
+ * Options for creating a Property instance
+ */
+export declare interface PropertyOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    name?: string;
+    domain?: string;
+    url?: string;
+    description?: string;
+    repositoryId?: string | null;
+    ownerId?: string | null;
+    status?: PropertyStatus;
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Status of a digital property
+ */
+export declare type PropertyStatus = 'active' | 'inactive' | 'pending';
+
+export declare const smrtPropertiesSummarizePrompt: PromptDefinition;
+
+export declare class Zone extends SmrtHierarchical {
+    /**
+     * Tenant ID for multi-tenant isolation
+     */
+    tenantId: string | null;
+    /**
+     * Parent property ID (required)
+     */
+    propertyId: string;
+    /**
+     * Display name
+     */
+    name: string;
+    /**
+     * Zone type (descriptive, not structural)
+     * Common values: "page", "section", "slot", "container", "widget"
+     */
+    type: string;
+    /**
+     * URL path pattern (e.g., "/", "/articles/*")
+     */
+    path: string;
+    /**
+     * CSS selector for placement (e.g., "#header", ".sidebar")
+     */
+    selector: string;
+    /**
+     * Position hint (e.g., "top", "after-paragraph-3")
+     */
+    position: string;
+    /**
+     * Width in pixels (null = fluid)
+     */
+    width: number | null;
+    /**
+     * Height in pixels (null = fluid)
+     */
+    height: number | null;
+    /**
+     * Allowed content/ad formats
+     */
+    allowedFormats: string[];
+    /**
+     * Default content/asset ID for fallback
+     */
+    defaultContentId: string | null;
+    /**
+     * Extensible metadata
+     */
+    metadata: Record<string, unknown>;
+    constructor(options?: ZoneOptions);
+    /**
+     * Check if this is a top-level zone (no parent)
+     */
+    isTopLevel(): boolean;
+    /**
+     * Check if this zone has dimensions set
+     */
+    hasDimensions(): boolean;
+    /**
+     * Get dimensions as string (e.g., "728x90")
+     */
+    getDimensionString(): string | null;
+    /**
+     * Get the parent property
+     */
+    getProperty(): Promise<Property | null>;
+    /**
+     * Get the full path from root to this zone
+     */
+    getFullPath(): Promise<string>;
+    /**
+     * Get the depth in the hierarchy (0 = top-level)
+     */
+    getDepth(): Promise<number>;
+    /**
+     * Create a child zone under this zone
+     */
+    createChild(options: Omit<ZoneOptions, 'propertyId' | 'parentId'>): Promise<Zone>;
+    /**
+     * Build tree node for this zone and its children
+     */
+    toTreeNode(): Promise<ZoneTreeNode<Zone>>;
+    /**
+     * Check if a format is allowed in this zone
+     */
+    isFormatAllowed(format: string): boolean;
+}
+
+export declare class ZoneCollection extends SmrtCollection<Zone> {
+    static readonly _itemClass: typeof Zone;
+    /**
+     * Find all zones for a property
+     *
+     * @param propertyId - Property ID
+     * @returns Array of zones
+     */
+    findByProperty(propertyId: string): Promise<Zone[]>;
+    /**
+     * Find top-level zones for a property (no parent)
+     *
+     * @param propertyId - Property ID
+     * @returns Array of top-level zones
+     */
+    findTopLevel(propertyId: string): Promise<Zone[]>;
+    /**
+     * Find direct children of a zone
+     *
+     * @param parentId - Parent zone ID
+     * @returns Array of child zones
+     */
+    findChildren(parentId: string): Promise<Zone[]>;
+    /**
+     * Find zones by path pattern
+     *
+     * @param propertyId - Property ID
+     * @param path - URL path to match
+     * @returns Array of matching zones
+     */
+    findByPath(propertyId: string, path: string): Promise<Zone[]>;
+    /**
+     * Find zones by type
+     *
+     * @param propertyId - Property ID
+     * @param type - Zone type
+     * @returns Array of zones of the given type
+     */
+    findByType(propertyId: string, type: string): Promise<Zone[]>;
+    /**
+     * Get the complete zone tree for a property
+     *
+     * @param propertyId - Property ID
+     * @returns ZoneTree structure
+     */
+    getTree(propertyId: string): Promise<ZoneTree<Zone>>;
+    /**
+     * Get all ancestors of a zone (path to root)
+     *
+     * @param zoneId - Zone ID
+     * @returns Array of ancestors (from root to parent)
+     */
+    getAncestors(zoneId: string): Promise<Zone[]>;
+    /**
+     * Get all descendants of a zone recursively
+     *
+     * @param zoneId - Zone ID
+     * @returns Array of all descendant zones
+     */
+    getDescendants(zoneId: string): Promise<Zone[]>;
+    /**
+     * Get the depth of the deepest zone in a property
+     *
+     * @param propertyId - Property ID
+     * @returns Maximum depth (0 = only top-level zones)
+     */
+    getMaxDepth(propertyId: string): Promise<number>;
+    /**
+     * Find zones with specific dimensions
+     *
+     * @param propertyId - Property ID
+     * @param width - Required width
+     * @param height - Required height
+     * @returns Array of matching zones
+     */
+    findByDimensions(propertyId: string, width: number, height: number): Promise<Zone[]>;
+    /**
+     * Find zones that allow a specific format
+     *
+     * @param propertyId - Property ID
+     * @param format - Format to check
+     * @returns Array of zones allowing the format
+     */
+    findByAllowedFormat(propertyId: string, format: string): Promise<Zone[]>;
+    /**
+     * Move a zone to a new parent
+     *
+     * @param zoneId - Zone ID to move
+     * @param newParentId - New parent ID (null for top-level)
+     * @returns Updated zone
+     */
+    moveZone(zoneId: string, newParentId: string | null): Promise<Zone | null>;
+    /**
+     * Delete a zone and optionally its descendants
+     *
+     * @param zoneId - Zone ID to delete
+     * @param cascade - Whether to delete descendants
+     * @returns Number of zones deleted
+     */
+    deleteZone(zoneId: string, cascade?: boolean): Promise<number>;
+    /**
+     * Find zones belonging to a specific tenant
+     *
+     * @param tenantId - Tenant ID to filter by
+     * @returns Array of zones for the tenant
+     */
+    findByTenant(tenantId: string): Promise<Zone[]>;
+    /**
+     * Find global zones (no tenant association)
+     *
+     * @returns Array of global zones
+     */
+    findGlobal(): Promise<Zone[]>;
+    /**
+     * Find zones for a tenant including global zones
+     *
+     * @param tenantId - Tenant ID to filter by
+     * @returns Array of tenant-specific and global zones
+     */
+    findWithGlobals(tenantId: string): Promise<Zone[]>;
+}
+
+/**
+ * Options for creating a Zone instance
+ */
+export declare interface ZoneOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    propertyId?: string;
+    parentId?: string | null;
+    name?: string;
+    type?: string;
+    path?: string;
+    selector?: string;
+    position?: string;
+    width?: number | null;
+    height?: number | null;
+    allowedFormats?: string[];
+    defaultContentId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Complete zone tree for a property
+ */
+export declare interface ZoneTree<T = unknown> {
+    propertyId: string;
+    roots: ZoneTreeNode<T>[];
+}
+
+/**
+ * A node in the zone tree hierarchy
+ */
+export declare interface ZoneTreeNode<T = unknown> {
+    zone: T;
+    children: ZoneTreeNode<T>[];
+}
+
+export { }