@happyvertical/smrt-sites 0.30.0

package/AGENTS.md

@@ -0,0 +1,18 @@
+# @happyvertical/smrt-sites
+
+Multi-tenant site lifecycle management with agent bindings.
+
+## Models
+
+- **Site**: `domain` (unique per tenant), `tier` (free/standard/premium), `portalConfig` JSON, database connection, `provisioningStatus`/`provisioningTimestamp`. Status: draft/active/suspended/archived.
+- **SiteAgentBinding**: junction linking sites to agent classes. Per-site `config` overrides and `priority` ordering. `conflictColumns: ['site_id', 'agent_class']`.
+
+## SiteService
+
+Stateless lifecycle ops: `activate()`, `suspend()`, `archive()`. `bindAgent()` handles upsert (update config if exists, create if not).
+
+## Gotchas
+
+- **Required tenancy**: both models use `@TenantScoped({ mode: 'required' })` — must have tenant context
+- **portalConfig accepts both object and JSON string** in constructor
+- **SiteAgentBinding.config is nullable**: auto-parsed from JSON on init

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,94 @@
+# @happyvertical/smrt-sites
+
+Site lifecycle management for multi-tenant SMRT networks. Manages deployable websites with provisioning status, tier classification, portal configuration, and agent bindings with priority ordering.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-sites
+```
+
+## Usage
+
+```typescript
+import {
+  Site, SiteCollection,
+  SiteAgentBinding, SiteAgentBindingCollection,
+  SiteService
+} from '@happyvertical/smrt-sites';
+
+// Create collections
+const sites = await SiteCollection.create({ db });
+const bindings = await SiteAgentBindingCollection.create({ db });
+
+// Use SiteService for lifecycle operations
+const service = new SiteService({ sites, bindings });
+
+// Create a site (starts in draft status)
+const site = await service.createSite('tenant-123', {
+  name: 'Community Hub',
+  domain: 'hub.example.com',
+  tier: 'standard',
+});
+
+// Activate after validation (requires name + domain)
+await service.activateSite(site.id);
+
+// Mark infrastructure as provisioned
+await service.markProvisioned(site.id);
+
+// Bind agents with priority ordering (higher = first)
+await service.bindAgent(site.id, 'Praeco', { schedule: '0 * * * *' });
+await service.bindAgent(site.id, 'Caelus', { maxArticles: 50 });
+
+// Get enabled agents sorted by priority descending
+const agents = await service.getEnabledAgents(site.id);
+
+// Suspend or archive a site
+await service.suspendSite(site.id);
+await service.archiveSite(site.id);
+```
+
+### Site lifecycle
+
+Sites progress through four statuses: `draft` -> `active` -> `suspended` -> `archived`. The `SiteService` enforces validation on activation (name and domain required) and tracks provisioning state separately via `provisioningStatus` (pending/provisioning/ready/failed). Sites are uniquely identified by `(tenant_id, domain)`.
+
+### Agent bindings
+
+`SiteAgentBinding` is a junction table linking sites to agent classes. Each binding has a `priority` (higher values execute first), an `enabled` flag, and optional per-site `config` overrides stored as JSON. The `bindAgent()` method upserts -- updating config if a binding already exists, creating one if not. `findEnabled()` returns bindings sorted by priority descending.
+
+### Portal configuration
+
+Sites store theme, branding, and navigation settings in `portalConfig` as JSON. Use `getPortalConfig()`/`setPortalConfig()` for type-safe access. Both models require tenant context (`@TenantScoped({ mode: 'required' })`).
+
+## API
+
+### Models
+
+| Export | Description |
+|--------|------------|
+| `Site` | Site record with domain, status, tier, provisioning tracking, and portal config |
+| `SiteAgentBinding` | Junction binding an agent class to a site with priority and config overrides |
+
+### Collections
+
+| Export | Description |
+|--------|------------|
+| `SiteCollection` | CRUD and queries for Site records |
+| `SiteAgentBindingCollection` | Queries by site, agent class, and enabled state with priority sorting |
+
+### Services
+
+| Export | Description |
+|--------|------------|
+| `SiteService` | High-level lifecycle ops: create, activate, suspend, archive, bind/unbind agents |
+
+### Key Types
+
+`SiteOptions`, `SiteStatus`, `SiteTier`, `ProvisioningStatus`, `SitePortalConfig`, `SiteServiceOptions`, `SiteAgentBindingOptions`, `CreateSiteData`
+
+## Dependencies
+
+- `@happyvertical/smrt-core` -- ORM and code generation
+- `@happyvertical/smrt-tenancy` -- required multi-tenant scoping
+- Peer: `@happyvertical/smrt-agents` (optional)

package/dist/index.d.ts

@@ -0,0 +1,258 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+
+/**
+ * Data required to create a new site
+ */
+export declare interface CreateSiteData {
+    name: string;
+    domain: string;
+    tier?: SiteTier;
+    databaseUrl?: string;
+    databaseType?: string;
+    portalConfig?: SitePortalConfig;
+    repositoryUrl?: string;
+    templateName?: string;
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Infrastructure provisioning status
+ */
+export declare type ProvisioningStatus = 'pending' | 'provisioning' | 'ready' | 'failed';
+
+export declare class Site extends SmrtObject {
+    tenantId: string;
+    /** Display name, e.g. "Bentley Alberta" */
+    name: string;
+    /** Primary domain, e.g. "bentleyalberta.com" */
+    domain: string;
+    /** Lifecycle status */
+    status: SiteStatus;
+    /** Pricing/feature tier */
+    tier: SiteTier;
+    /** Site-specific database connection URL */
+    databaseUrl: string;
+    /** Database type: sqlite, postgres, libsql */
+    databaseType: string;
+    /** Theme, branding, navigation settings (JSON) */
+    portalConfig: string;
+    /** Git repository URL */
+    repositoryUrl: string;
+    /** Starter template name */
+    templateName: string;
+    /** Infrastructure provisioning status */
+    provisioningStatus: ProvisioningStatus | '';
+    /** When provisioning completed */
+    provisionedAt: Date | null;
+    /** Last provisioning error message */
+    provisioningError: string;
+    /** Extensible key-value metadata (JSON) */
+    metadata: string;
+    createdAt: Date;
+    updatedAt: Date;
+    constructor(options?: SiteOptions);
+    /**
+     * Check if the site is active
+     */
+    isActive(): boolean;
+    /**
+     * Check if the site is provisioned and ready
+     */
+    isReady(): boolean;
+    /**
+     * Get portal config as parsed object
+     */
+    getPortalConfig(): SitePortalConfig;
+    /**
+     * Set portal config from object
+     */
+    setPortalConfig(config: SitePortalConfig): void;
+    /**
+     * Get metadata as parsed object
+     */
+    getMetadata(): Record<string, unknown>;
+    /**
+     * Set metadata from object
+     */
+    setMetadata(data: Record<string, unknown>): void;
+    /**
+     * Update metadata by merging with existing values
+     */
+    updateMetadata(updates: Record<string, unknown>): void;
+}
+
+export declare class SiteAgentBinding extends SmrtObject {
+    tenantId: string;
+    /** FK to sites table */
+    siteId: string;
+    /** Agent class name, e.g. "Praeco" */
+    agentClass: string;
+    /** Whether this agent is enabled for the site */
+    enabled: boolean;
+    /** Per-site agent configuration overrides (JSON) */
+    config: Record<string, unknown> | null;
+    /** Sort priority (higher = first) */
+    priority: number;
+    constructor(options?: SiteAgentBindingOptions);
+}
+
+export declare class SiteAgentBindingCollection extends SmrtCollection<SiteAgentBinding> {
+    static readonly _itemClass: typeof SiteAgentBinding;
+    /**
+     * Find all agent bindings for a site
+     */
+    findBySite(siteId: string): Promise<SiteAgentBinding[]>;
+    /**
+     * Find all sites using a specific agent class
+     */
+    findByAgent(agentClass: string): Promise<SiteAgentBinding[]>;
+    /**
+     * Find enabled bindings for a site, ordered by priority descending
+     */
+    findEnabled(siteId: string): Promise<SiteAgentBinding[]>;
+    /**
+     * Find a specific site-agent binding
+     */
+    findBySiteAndAgent(siteId: string, agentClass: string): Promise<SiteAgentBinding | null>;
+}
+
+/**
+ * Options for constructing a SiteAgentBinding instance
+ */
+export declare interface SiteAgentBindingOptions {
+    id?: string;
+    tenantId?: string;
+    siteId?: string;
+    agentClass?: string;
+    enabled?: boolean;
+    config?: Record<string, unknown> | string | null;
+    priority?: number;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+export declare class SiteCollection extends SmrtCollection<Site> {
+    static readonly _itemClass: typeof Site;
+    /**
+     * Find a site by its primary domain
+     */
+    findByDomain(domain: string): Promise<Site | null>;
+    /**
+     * Find all sites belonging to a tenant
+     */
+    findByTenant(tenantId: string): Promise<Site[]>;
+    /**
+     * Find sites by lifecycle status
+     */
+    findByStatus(status: SiteStatus): Promise<Site[]>;
+    /**
+     * Find all active sites
+     */
+    findActive(): Promise<Site[]>;
+}
+
+/**
+ * Options for constructing a Site instance
+ */
+export declare interface SiteOptions {
+    id?: string;
+    tenantId?: string;
+    name?: string;
+    domain?: string;
+    status?: SiteStatus;
+    tier?: SiteTier;
+    databaseUrl?: string;
+    databaseType?: string;
+    portalConfig?: SitePortalConfig | string;
+    repositoryUrl?: string;
+    templateName?: string;
+    provisioningStatus?: ProvisioningStatus;
+    provisionedAt?: Date | null;
+    provisioningError?: string;
+    metadata?: Record<string, unknown> | string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+/**
+ * Portal configuration for theming, branding, and navigation
+ */
+export declare interface SitePortalConfig {
+    theme?: string;
+    branding?: Record<string, unknown>;
+    navigation?: Array<{
+        label: string;
+        path: string;
+        icon?: string;
+    }>;
+}
+
+export declare class SiteService {
+    private sites;
+    private bindings;
+    constructor(options: SiteServiceOptions);
+    /**
+     * Create a new site in draft status
+     */
+    createSite(tenantId: string, data: CreateSiteData): Promise<Site>;
+    /**
+     * Activate a site — validates required fields then sets status to active
+     */
+    activateSite(siteId: string): Promise<Site>;
+    /**
+     * Suspend a site
+     */
+    suspendSite(siteId: string): Promise<Site>;
+    /**
+     * Archive a site
+     */
+    archiveSite(siteId: string): Promise<Site>;
+    /**
+     * Mark site as provisioned and ready
+     */
+    markProvisioned(siteId: string): Promise<Site>;
+    /**
+     * Mark site provisioning as failed
+     */
+    markProvisioningFailed(siteId: string, error: string): Promise<Site>;
+    /**
+     * Bind an agent to a site
+     */
+    bindAgent(siteId: string, agentClass: string, config?: Record<string, unknown>): Promise<SiteAgentBinding>;
+    /**
+     * Unbind an agent from a site
+     */
+    unbindAgent(siteId: string, agentClass: string): Promise<void>;
+    /**
+     * Get all enabled agent bindings for a site
+     */
+    getEnabledAgents(siteId: string): Promise<SiteAgentBinding[]>;
+    /**
+     * Load a site by ID, throwing if not found
+     */
+    private requireSite;
+}
+
+/**
+ * Options for creating a SiteService
+ */
+export declare interface SiteServiceOptions {
+    sites: SiteCollection;
+    bindings: SiteAgentBindingCollection;
+}
+
+/**
+ * Types for smrt-sites package
+ */
+/**
+ * Site lifecycle status
+ */
+export declare type SiteStatus = 'draft' | 'active' | 'suspended' | 'archived';
+
+/**
+ * Site pricing/feature tier
+ */
+export declare type SiteTier = 'free' | 'standard' | 'premium';
+
+export { }