@happyvertical/smrt-types 0.30.0

package/AGENTS.md

@@ -0,0 +1,18 @@
+# @happyvertical/smrt-types
+
+Shared TypeScript type definitions. Prevents circular dependencies between packages.
+
+## Exports
+
+| File | Types |
+|------|-------|
+| `signals.ts` | `Signal`, `SignalType`, `SignalAdapter` — universal signaling system |
+| `module.ts` | `SmrtModuleMeta`, `ModuleUISlot`, `ModuleComponentType` — module registration and UI slots |
+| `user.ts` | `UserStatus`, `TenantStatus`, `MembershipStatus`, `SessionStatus`, `OverrideEffect` — status enums |
+| `identity.ts` | `User`, `Tenant`, `Role`, `Membership`, `SmrtEntityFields` — cross-package identity data contracts (runtime classes live in smrt-users, which `implements` these) |
+
+## Rules
+
+- **Zero runtime code**: only type definitions and enums
+- **Always `import type`**: use `import type { Signal }` to avoid runtime imports (except enums which have runtime values)
+- **Add shared types here**: if two+ packages need the same type, put it here instead of in `smrt-core`

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,61 @@
+# @happyvertical/smrt-types
+
+Shared TypeScript type definitions for the SMRT framework. Prevents circular dependencies by centralizing types that multiple packages need.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-types
+```
+
+## Usage
+
+```typescript
+// Import types (use `import type` for type-only imports)
+import type { Signal, SignalType, SignalAdapter } from '@happyvertical/smrt-types';
+import type { SmrtModuleMeta, ModuleUISlot } from '@happyvertical/smrt-types';
+
+// Enums have runtime values — use regular import
+import { UserStatus, TenantStatus, MembershipStatus } from '@happyvertical/smrt-types';
+```
+
+## Exports
+
+### Signal System (types)
+
+| Export | Description |
+|--------|------------|
+| `Signal` | Signal payload with lifecycle info (id, className, method, duration, etc.) |
+| `SignalType` | Signal lifecycle stage: `'start'` \| `'step'` \| `'end'` \| `'error'` |
+| `SignalAdapter` | Interface for signal processors (logging, metrics, pub/sub) |
+
+### Module UI (types)
+
+| Export | Description |
+|--------|------------|
+| `SmrtModuleMeta` | Module metadata (name, version, description) |
+| `ModuleUISlot` | UI slot definition for module admin panels |
+| `ModuleComponentType` | Component type classification |
+| `ModuleUIBaseProps` | Base props interface for module UI components |
+| `ModuleUIRegistryInterface` | Registry interface for module UI registration |
+
+### User/Tenant Status (enums — runtime values)
+
+| Export | Description |
+|--------|------------|
+| `UserStatus` | User lifecycle status |
+| `TenantStatus` | Tenant lifecycle status |
+| `MembershipStatus` | Membership lifecycle status |
+| `SessionStatus` | Session lifecycle status |
+| `OverrideEffect` | Permission override effect |
+| `TenantPermissionEffect` | Tenant-level permission effect |
+
+## Rules
+
+- **Zero runtime code** except enums (which require runtime values)
+- **Use `import type`** for non-enum imports to avoid unnecessary runtime dependencies
+- **Add shared types here** if two or more packages need the same type definition
+
+## Dependencies
+
+None. This is a leaf package with zero dependencies.

package/dist/index.d.ts

@@ -0,0 +1,927 @@
+/**
+ * Shared AI usage tracking types for SMRT.
+ *
+ * These types are intentionally provider-agnostic so SMRT can normalize
+ * telemetry emitted by the underlying AI SDK into a stable internal shape.
+ */
+/**
+ * Normalized token usage information for an AI call.
+ */
+export declare interface AiTokenUsage {
+    /** Number of input tokens consumed by the request */
+    promptTokens?: number;
+    /** Number of output tokens produced by the response */
+    completionTokens?: number;
+    /** Total tokens consumed across the call */
+    totalTokens?: number;
+}
+
+/**
+ * Grouping dimensions supported by summary helpers.
+ */
+export declare type AiUsageGroupBy = 'provider' | 'model' | 'class' | 'tenant' | 'operation' | 'day';
+
+/**
+ * Callback interface for handling normalized AI usage events.
+ */
+export declare interface AiUsageHandler {
+    /**
+     * Handle a normalized AI usage event.
+     */
+    handle(event: SmrtAiUsageEvent): Promise<void>;
+}
+
+/**
+ * Options for listing raw AI usage records from persistence.
+ */
+export declare interface AiUsageListOptions {
+    /** Only include records on or after this timestamp */
+    since?: Date;
+    /** Only include records before or at this timestamp */
+    until?: Date;
+    /** Filter by provider */
+    provider?: string;
+    /** Filter by model */
+    model?: string;
+    /** Filter by operation */
+    operation?: string;
+    /** Filter by SMRT class name */
+    className?: string;
+    /** Filter by tenant ID */
+    tenantId?: string | null;
+    /** Maximum number of rows to return */
+    limit?: number;
+    /** Number of rows to skip */
+    offset?: number;
+    /** Sort order */
+    orderBy?: 'timestamp DESC' | 'timestamp ASC';
+}
+
+/**
+ * In-memory snapshot returned by the collector.
+ */
+export declare interface AiUsageSnapshot {
+    /** Usage aggregated by "provider:model" */
+    byModel: Record<string, AiUsageStats>;
+    /** Usage aggregated by "className:operation" */
+    byClass: Record<string, AiUsageStats>;
+    /** Total number of calls observed by the collector */
+    totalCalls: number;
+    /** Collector start time in epoch milliseconds */
+    startTime: number;
+}
+
+/**
+ * Aggregated statistics bucket for AI usage reporting.
+ */
+export declare interface AiUsageStats {
+    /** Number of calls represented in the bucket */
+    callCount: number;
+    /** Sum of prompt/input tokens */
+    promptTokens: number;
+    /** Sum of completion/output tokens */
+    completionTokens: number;
+    /** Sum of total tokens */
+    totalTokens: number;
+    /** Sum of durations in milliseconds */
+    totalDuration: number;
+    /** Sum of estimated costs in USD */
+    estimatedCost: number;
+    /** Timestamp of the most recent event in epoch milliseconds */
+    lastUsed: number;
+}
+
+/**
+ * Options for summarized AI usage queries.
+ */
+export declare interface AiUsageSummaryOptions extends Omit<AiUsageListOptions, 'limit' | 'offset' | 'orderBy'> {
+    /** Dimension to group summary buckets by */
+    groupBy?: AiUsageGroupBy;
+}
+
+/** Per-object configuration controlling domain-knowledge generation and exposure. */
+export declare interface DomainKnowledgeConfig {
+    enabled?: boolean;
+    api?: {
+        /**
+         * Generate HTTP knowledge routes. Disabled by default; prefer CLI/MCP for
+         * agent workflows unless this is a guarded dev/admin endpoint.
+         */
+        enabled?: boolean;
+        basePath?: string;
+        includeDocs?: boolean;
+        includePrompts?: boolean;
+        /**
+         * Require dev mode or admin locals for HTTP knowledge access. Setting this
+         * to false makes the route public and should only be used when sanitized
+         * anonymous schema/surface metadata is acceptable.
+         */
+        requireAdmin?: boolean;
+    };
+    includeDocs?: boolean;
+    includePrompts?: boolean;
+    tags?: string[];
+    summary?: string;
+    risks?: string[];
+}
+
+/** Result of a domain-knowledge freshness check (stale references, error/warning counts). */
+export declare interface DomainKnowledgeFreshnessResult {
+    ok: boolean;
+    checkedAt: string;
+    artifactPath?: string;
+    issueCount: number;
+    errorCount: number;
+    warningCount: number;
+    issues: Array<{
+        severity: 'error' | 'warning';
+        code: string;
+        message: string;
+        file?: string;
+        packageName?: string;
+    }>;
+}
+
+/** The package-level domain-knowledge artifact (`smrt-knowledge.json`) — the agent/developer contract. */
+export declare interface DomainKnowledgeManifest {
+    schemaVersion: 1;
+    generatedAt: string;
+    packageName?: string;
+    packageVersion?: string;
+    sourceManifestPath?: string;
+    agentDocPath?: string;
+    sourceHashes: Record<string, string>;
+    exports: string[];
+    dependencies: Record<string, string>;
+    smrtDependencies: string[];
+    sdkDependencies: string[];
+    tags: string[];
+    summary?: string;
+    risks: string[];
+    objects: DomainKnowledgeObject[];
+    surfaces: DomainKnowledgeSurface[];
+    prompts: Array<{
+        filePath: string;
+        key?: string;
+    }>;
+    relationshipsV2: {
+        foreignKeyFields: number;
+        crossPackageRefFields: number;
+        junctionCollections: number;
+        hierarchicalObjects: number;
+        polymorphicAssociations: number;
+        uuidColumns: number;
+    };
+    agentDoc?: string;
+}
+
+/** One object's entry in the domain-knowledge manifest (fields, relationships, surfaces). */
+export declare interface DomainKnowledgeObject {
+    name: string;
+    qualifiedName?: string;
+    collection: string;
+    tableName?: string;
+    packageName?: string;
+    extends?: string;
+    visibility?: string;
+    fields: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+        related?: string;
+        columnType?: string;
+    }>;
+    relationships: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+        related?: string;
+        columnType?: string;
+    }>;
+    methods: string[];
+    surfaces: DomainKnowledgeSurface[];
+    relationshipFeatures: string[];
+    tags: string[];
+    summary?: string;
+    risks: string[];
+}
+
+/** A single generated surface (one api/cli/mcp/ai operation) exposed by an object. */
+export declare interface DomainKnowledgeSurface {
+    kind: DomainKnowledgeSurfaceKind;
+    name: string;
+    operation: string;
+    path?: string;
+    method?: string;
+    description?: string;
+    objectName?: string;
+}
+
+/** Kind of generated surface a knowledge entry describes (REST/CLI/MCP/AI). */
+export declare type DomainKnowledgeSurfaceKind = 'api' | 'cli' | 'mcp' | 'ai';
+
+/** User↔Tenant↔Role junction. Runtime class: `@happyvertical/smrt-users:Membership`. */
+export declare interface Membership extends SmrtEntityFields {
+    userId?: string;
+    tenantId?: string;
+    roleId?: string;
+    status: MembershipStatus;
+}
+
+/**
+ * Status of a user's membership within a specific tenant.
+ *
+ * A user may hold memberships in multiple tenants simultaneously, each with an
+ * independent `MembershipStatus`.
+ *
+ * @example
+ * ```typescript
+ * const active = memberships.filter(m => m.status === MembershipStatus.ACTIVE);
+ * ```
+ *
+ * @see {@link UserStatus} for the global account-level status
+ * @see {@link TenantStatus} for the status of the tenant itself
+ */
+export declare enum MembershipStatus {
+    /** Active membership */
+    ACTIVE = "active",
+    /** Inactive membership */
+    INACTIVE = "inactive",
+    /** Pending invitation acceptance */
+    PENDING = "pending"
+}
+
+/**
+ * Generic component type for SMRT module UI slots.
+ *
+ * Intentionally opaque — defined as a loose function signature rather than
+ * `import('svelte').ComponentType` to avoid pulling Svelte (and its DOM types)
+ * into server-side Node.js builds. The actual Svelte component constructor
+ * is assignable to this type at runtime.
+ *
+ * @typeParam Props - The props interface the component accepts; defaults to `unknown`.
+ *
+ * @example
+ * ```typescript
+ * import InvoiceCard from './InvoiceCard.svelte';
+ * // InvoiceCard is assignable to ModuleComponentType<InvoiceCardProps>
+ * registry.register('@happyvertical/smrt-commerce', 'invoice-card', InvoiceCard);
+ * ```
+ *
+ * @see {@link ModuleUIBaseProps} for the base props all slot components receive
+ * @see {@link ModuleUIRegistryInterface} for storing and retrieving components
+ */
+export declare type ModuleComponentType<Props = unknown> = (...args: any[]) => any;
+
+/**
+ * Base props contract for all SMRT module UI slot components.
+ *
+ * Every component registered against a `ModuleUISlot` should accept at least
+ * these props. Individual slot components may extend this interface with
+ * slot-specific required props.
+ *
+ * @typeParam TData   - Shape of the primary data object(s) the component renders.
+ * @typeParam TConfig - Shape of the optional configuration/settings object.
+ *
+ * @example
+ * ```typescript
+ * interface InvoiceCardProps extends ModuleUIBaseProps<Invoice> {
+ *   showLineItems?: boolean;
+ * }
+ * ```
+ *
+ * @see {@link ModuleComponentType} for the component type that accepts these props
+ * @see {@link ModuleUISlot} for the slot declaration that names the `propsInterface`
+ */
+export declare interface ModuleUIBaseProps<TData = unknown, TConfig = unknown> {
+    /** Primary data object(s) the component operates on */
+    data?: TData;
+    /** Configuration/settings */
+    config?: TConfig;
+    /** Callback for data changes */
+    onChange?: (data: TData) => void | Promise<void>;
+    /** Callback for saving */
+    onSave?: (data: TData) => Promise<void>;
+    /** Whether component is read-only */
+    readonly?: boolean;
+    /** CSS class for styling */
+    class?: string;
+    /** Loading state */
+    loading?: boolean;
+}
+
+/**
+ * Registry interface for mapping SMRT module slots to Svelte components.
+ *
+ * Implemented by `ModuleUIRegistry` in `@happyvertical/smrt-ui`. Consumers
+ * call `register()` once per slot at Svelte package initialisation time and
+ * `get()` when rendering to retrieve the correct component.
+ *
+ * @example
+ * ```typescript
+ * // Registration (in packages/commerce/src/svelte/index.ts)
+ * ModuleUIRegistry.registerModule(COMMERCE_MODULE_META);
+ * ModuleUIRegistry.register('@happyvertical/smrt-commerce', 'invoice-card', InvoiceCard);
+ *
+ * // Retrieval (in a host Svelte app)
+ * const InvoiceCard = ModuleUIRegistry.get('@happyvertical/smrt-commerce', 'invoice-card');
+ * ```
+ *
+ * @see {@link SmrtModuleMeta} for the module metadata structure passed to `registerModule()`
+ * @see {@link ModuleUISlot} for the slot identifiers used as `slotId`
+ * @see {@link ModuleComponentType} for the component type stored in the registry
+ */
+export declare interface ModuleUIRegistryInterface {
+    /** Register a component for a module's slot */
+    register<TProps extends ModuleUIBaseProps>(moduleName: string, slotId: string, component: ModuleComponentType<TProps>): void;
+    /** Get a component for a module's slot */
+    get<TProps extends ModuleUIBaseProps>(moduleName: string, slotId: string): ModuleComponentType<TProps> | undefined;
+    /** Check if component is registered */
+    has(moduleName: string, slotId: string): boolean;
+    /** Get all registered slot IDs for a module */
+    getSlots(moduleName: string): string[];
+    /** Get all registered module names */
+    getModules(): string[];
+    /** Get module metadata */
+    getModuleMeta(moduleName: string): SmrtModuleMeta | undefined;
+    /** Register module metadata */
+    registerModule(meta: SmrtModuleMeta): void;
+    /** Unregister for testing */
+    unregister(moduleName: string, slotId: string): boolean;
+    /** Clear all for testing */
+    clear(): void;
+}
+
+/**
+ * Module type definitions for SMRT Framework
+ *
+ * These types allow SMRT modules to declare their capabilities,
+ * including models, collections, and optional Svelte UI components.
+ *
+ * @example Module with UI components
+ * ```typescript
+ * // In core module: packages/commerce/src/ui.ts
+ * import type { SmrtModuleMeta, ModuleUISlot } from '@happyvertical/smrt-types';
+ *
+ * export const COMMERCE_UI_SLOTS: Record<string, ModuleUISlot> = {
+ *   'invoice-card': { id: 'invoice-card', label: 'Invoice Card', category: 'display' },
+ * };
+ *
+ * export const COMMERCE_MODULE_META: SmrtModuleMeta = {
+ *   name: '@happyvertical/smrt-commerce',
+ *   displayName: 'Commerce',
+ *   uiSlots: COMMERCE_UI_SLOTS,
+ * };
+ *
+ * // In svelte subpath: packages/commerce/src/svelte/index.ts
+ * import { ModuleUIRegistry } from '@happyvertical/smrt-ui/registry';
+ * import { COMMERCE_MODULE_META } from '../ui.js';
+ * import InvoiceCard from './components/InvoiceCard.svelte';
+ *
+ * ModuleUIRegistry.registerModule(COMMERCE_MODULE_META);
+ * ModuleUIRegistry.register('@happyvertical/smrt-commerce', 'invoice-card', InvoiceCard);
+ * ```
+ */
+/**
+ * UI slot definition for a SMRT module.
+ *
+ * Modules declare the slots they support in their `SmrtModuleMeta`. Svelte UI
+ * packages then implement those slots by registering components against the
+ * same `id` via `ModuleUIRegistryInterface.register()`.
+ *
+ * @example
+ * ```typescript
+ * const slot: ModuleUISlot = {
+ *   id: 'invoice-card',
+ *   label: 'Invoice Card',
+ *   description: 'Compact card view for a single invoice',
+ *   category: 'display',
+ *   order: 10,
+ * };
+ * ```
+ *
+ * @see {@link SmrtModuleMeta} for how slots are declared on a module
+ * @see {@link ModuleUIRegistryInterface} for registering component implementations
+ */
+export declare interface ModuleUISlot {
+    /** Unique identifier (e.g., 'invoice-card', 'customer-form') */
+    id: string;
+    /** Human-readable label */
+    label: string;
+    /** Description of the component's purpose */
+    description?: string;
+    /** Icon identifier (lucide icon names) */
+    icon?: string;
+    /** Display order (lower first) */
+    order?: number;
+    /** Component category for grouping */
+    category?: 'display' | 'form' | 'admin' | 'list' | 'detail' | 'action' | 'dashboard' | 'navigation';
+    /** Required props interface name (for documentation) */
+    propsInterface?: string;
+}
+
+/**
+ * Effect applied by a user-level permission override.
+ *
+ * Overrides target a specific user + permission combination and always win
+ * over role-based grants. `DENY` overrides are checked before `GRANT` in
+ * the 4-level permission cascade.
+ *
+ * @example
+ * ```typescript
+ * await override.create({
+ *   userId,
+ *   permission: 'billing.view',
+ *   effect: OverrideEffect.DENY,
+ * });
+ * ```
+ *
+ * @see {@link TenantPermissionEffect} for the tenant-level equivalent that supports inheritance
+ */
+export declare enum OverrideEffect {
+    /** Grant the permission */
+    GRANT = "grant",
+    /** Deny the permission */
+    DENY = "deny"
+}
+
+/** RBAC role. Runtime class: `@happyvertical/smrt-users:Role`. */
+export declare interface Role extends SmrtEntityFields {
+    /** `null` → system role available to every tenant. */
+    tenantId?: string | null;
+    name: string;
+    description: string;
+    isSystem: boolean;
+}
+
+/**
+ * Status of an authenticated session.
+ *
+ * Sessions transition from `ACTIVE` to either `EXPIRED` (time-based) or
+ * `REVOKED` (explicit action by the user or an administrator).
+ *
+ * @example
+ * ```typescript
+ * if (session.status !== SessionStatus.ACTIVE) {
+ *   redirect(302, '/login');
+ * }
+ * ```
+ *
+ * @see {@link UserStatus} for the account-level status checked before session creation
+ */
+export declare enum SessionStatus {
+    /** Active session */
+    ACTIVE = "active",
+    /** Expired session (past expiresAt) */
+    EXPIRED = "expired",
+    /** Revoked by user or admin */
+    REVOKED = "revoked"
+}
+
+/**
+ * Signal emitted during SMRT method execution.
+ *
+ * Signals provide automatic observability into method execution,
+ * enabling logging, metrics, pub/sub updates, and other integrations
+ * without requiring manual instrumentation.
+ *
+ * @example
+ * ```typescript
+ * // Logging adapter
+ * const loggingAdapter: SignalAdapter = {
+ *   async handle(signal: Signal) {
+ *     const label = `${signal.className}.${signal.method} [${signal.id}]`;
+ *     if (signal.type === 'start')  console.log(`→ ${label}`);
+ *     if (signal.type === 'end')    console.log(`✓ ${label} (${signal.duration}ms)`);
+ *     if (signal.type === 'error')  console.error(`✗ ${label}`, signal.error);
+ *   },
+ * };
+ * ```
+ *
+ * @see {@link SignalType} for the lifecycle stage values
+ * @see {@link SignalAdapter} for implementing a consumer
+ */
+export declare interface Signal {
+    /**
+     * Unique identifier for this specific execution
+     * Generated once per method invocation
+     */
+    id: string;
+    /**
+     * ID of the SMRT object instance
+     */
+    objectId: string;
+    /**
+     * Name of the SMRT class
+     */
+    className: string;
+    /**
+     * Name of the method being executed
+     */
+    method: string;
+    /**
+     * Signal type indicating lifecycle stage:
+     * - 'start': Method execution started
+     * - 'step': Manual step within method (optional)
+     * - 'end': Method execution completed successfully
+     * - 'error': Method execution failed
+     */
+    type: SignalType;
+    /**
+     * Optional step label for manual progress tracking
+     * Developers can emit custom steps within methods using bus.emit()
+     */
+    step?: string;
+    /**
+     * Sanitized method arguments (sensitive data removed)
+     * Objects with @sensitive JSDoc tags are excluded
+     */
+    args?: any[];
+    /**
+     * Method result (only present on 'end' signals)
+     */
+    result?: any;
+    /**
+     * Error that was thrown (only present on 'error' signals)
+     */
+    error?: Error;
+    /**
+     * Method execution duration in milliseconds
+     * Only present on 'end' and 'error' signals
+     */
+    duration?: number;
+    /**
+     * Timestamp when signal was emitted
+     */
+    timestamp: Date;
+    /**
+     * Optional additional context
+     * Can include tracing IDs, user context, request metadata, etc.
+     */
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Adapter interface for consuming signals from the SMRT signaling system.
+ *
+ * Adapters process signals for specific purposes:
+ * - **Logging**: write to console, file, or a logging service
+ * - **Metrics**: track execution counts, durations, and error rates
+ * - **Pub/Sub**: broadcast real-time updates to connected clients
+ * - **Tracing**: forward spans to a distributed tracing system (e.g., OpenTelemetry)
+ *
+ * Adapters are fire-and-forget — errors thrown inside `handle()` are caught
+ * by the SignalBus and do not interrupt the main execution flow.
+ *
+ * @example
+ * ```typescript
+ * class MetricsAdapter implements SignalAdapter {
+ *   async handle(signal: Signal): Promise<void> {
+ *     if (signal.type === 'end') {
+ *       metrics.histogram('smrt.method.duration', signal.duration ?? 0, {
+ *         class: signal.className,
+ *         method: signal.method,
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Signal} for the payload each adapter receives
+ * @see {@link SignalType} for the lifecycle stages
+ */
+export declare interface SignalAdapter {
+    /**
+     * Handle a signal event
+     *
+     * @param signal - The signal to process
+     * @returns Promise that resolves when signal is handled
+     *
+     * @remarks
+     * This method should not throw - errors are caught by the SignalBus.
+     * Implementations should handle their own error logging/recovery.
+     */
+    handle(signal: Signal): Promise<void>;
+}
+
+/**
+ * Universal Signaling System Types
+ *
+ * This module defines the core types for the SMRT signaling system,
+ * which provides automatic method tracking and event distribution
+ * for logging, metrics, pub/sub, and other observability needs.
+ */
+/**
+ * Lifecycle stage of a signal emitted during SMRT method execution.
+ *
+ * - `'start'` — emitted when a tracked method begins executing
+ * - `'step'`  — emitted manually within a method for progress tracking
+ * - `'end'`   — emitted when a method completes successfully
+ * - `'error'` — emitted when a method throws an unhandled exception
+ *
+ * @example
+ * ```typescript
+ * adapter.handle = async (signal: Signal) => {
+ *   if (signal.type === 'error') {
+ *     logger.error(`${signal.className}.${signal.method} failed`, signal.error);
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link Signal} for the full signal payload shape
+ * @see {@link SignalAdapter} for consuming signals
+ */
+export declare type SignalType = 'start' | 'step' | 'end' | 'error';
+
+/**
+ * Stable usage event shape emitted inside SMRT after every AI call.
+ */
+export declare interface SmrtAiUsageEvent {
+    /** AI provider identifier (e.g. "openai", "anthropic") */
+    provider: string;
+    /** Model identifier used for the call */
+    model: string;
+    /** High-level operation name (e.g. "chat", "embed", "stream") */
+    operation: string;
+    /** Token usage reported by the provider, when available */
+    usage?: AiTokenUsage;
+    /** Wall-clock duration in milliseconds */
+    duration: number;
+    /** Event timestamp */
+    timestamp: Date;
+    /** Optional provider- or application-specific tags */
+    tags?: Record<string, string>;
+    /** SMRT class responsible for the call */
+    className?: string;
+    /** Tenant identifier when available */
+    tenantId?: string | null;
+    /** Best-effort estimated cost in USD */
+    estimatedCost?: number;
+}
+
+/**
+ * Persisted AI usage record returned from query helpers.
+ */
+export declare interface SmrtAiUsageRecord extends SmrtAiUsageEvent {
+    /** Persistent record identifier */
+    id: string;
+}
+
+/**
+ * Fields every persisted SMRT entity exposes — a subset of `SmrtObject`'s public
+ * surface. `id`/`slug` are `null`/`undefined` before the first persist, matching
+ * the base getters.
+ */
+export declare interface SmrtEntityFields {
+    /** UUID, assigned on first persist. */
+    id: string | null | undefined;
+    /** URL-safe slug, when the model maintains one. */
+    slug: string | null | undefined;
+    /** Creation timestamp; `null`/`undefined` before first persist. */
+    created_at: Date | null | undefined;
+    /** Last-update timestamp; `null`/`undefined` before first persist. */
+    updated_at: Date | null | undefined;
+}
+
+/**
+ * Metadata declaration for a SMRT module.
+ *
+ * Each module exports a `SmrtModuleMeta` constant describing its package
+ * identity, the UI slots it declares, and the model/collection classes it
+ * provides. The UI registry uses this to resolve component lookups at runtime.
+ *
+ * @example
+ * ```typescript
+ * export const COMMERCE_MODULE_META: SmrtModuleMeta = {
+ *   name: '@happyvertical/smrt-commerce',
+ *   displayName: 'Commerce',
+ *   description: 'Invoicing, contracts, and fulfillment',
+ *   models: ['Customer', 'Invoice', 'Contract'],
+ *   uiSlots: {
+ *     'invoice-card': { id: 'invoice-card', label: 'Invoice Card', category: 'display' },
+ *   },
+ * };
+ * ```
+ *
+ * @see {@link ModuleUISlot} for the shape of each declared slot
+ * @see {@link ModuleUIRegistryInterface} for registering and retrieving module components
+ */
+export declare interface SmrtModuleMeta {
+    /** Package name (e.g., '@happyvertical/smrt-commerce') */
+    name: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Module description */
+    description?: string;
+    /** Module version */
+    version?: string;
+    /** UI slots this module declares */
+    uiSlots?: Record<string, ModuleUISlot>;
+    /** Model classes this module provides */
+    models?: string[];
+    /** Collection classes this module provides */
+    collections?: string[];
+    /** Peer dependencies for UI (e.g., ['@happyvertical/smrt-profiles']) */
+    uiDependencies?: string[];
+}
+
+/**
+ * Package-owned route definition.
+ *
+ * @typeParam TData - Data shape the route component expects.
+ * @typeParam TLoadInput - Input accepted by the optional `load` helper.
+ * @typeParam TProps - Component props shape. Defaults to `{ data?: TData }`.
+ */
+export declare interface SmrtRouteDefinition<TData = unknown, TLoadInput = unknown, TProps = {
+    data?: TData;
+}> {
+    /** Stable route identifier, namespaced by package. */
+    id: string;
+    /** Human-readable page title. */
+    title: string;
+    /** Optional description for docs and tooling. */
+    description?: string;
+    /** Canonical path the package recommends by default. */
+    defaultPath: string;
+    /** Page component exported by the package. */
+    component: ModuleComponentType<TProps>;
+    /** Optional reusable load helper for app-owned route files. */
+    load?: (input: TLoadInput) => Promise<TData> | TData;
+    /** Which SvelteKit route file the `load` helper belongs in. */
+    loadKind?: SmrtRouteLoadKind;
+    /** Optional navigation metadata. */
+    nav?: SmrtRouteNavigationMeta;
+    /** Optional tags for docs, hosts, or filtering. */
+    tags?: string[];
+}
+
+/**
+ * Route load function category.
+ *
+ * `page` maps naturally to SvelteKit's `+page.ts`, while `page-server` maps to
+ * `+page.server.ts`.
+ */
+export declare type SmrtRouteLoadKind = 'page' | 'page-server';
+
+/**
+ * Package-owned route module.
+ *
+ * Consumers import one of these from `@happyvertical/smrt-<pkg>/routes`, then
+ * mount the exported components and loaders inside their own app route tree.
+ *
+ */
+export declare interface SmrtRouteModule {
+    /** Package name, usually `@happyvertical/smrt-<pkg>`. */
+    packageName: string;
+    /** Human-readable module name. */
+    displayName: string;
+    /** Optional module description. */
+    description?: string;
+    /** Route definitions keyed by package-local name. */
+    routes: Record<string, SmrtRouteDefinition<any, any, any>>;
+}
+
+/**
+ * Resolved navigation entry for a mounted route.
+ */
+export declare interface SmrtRouteNavigationItem {
+    /** Stable route identifier. */
+    routeId: string;
+    /** Link href as mounted by the consuming app. */
+    href: string;
+    /** Label shown in the app navigation. */
+    label: string;
+    /** Optional description for menu UI. */
+    description?: string;
+    /** Optional icon identifier. */
+    icon?: string;
+    /** Display order (lower first). */
+    order?: number;
+    /** Optional grouping key for larger menus. */
+    group?: string;
+}
+
+/**
+ * Navigation metadata for a package route.
+ */
+export declare interface SmrtRouteNavigationMeta {
+    /** Label shown in app navigation. */
+    label: string;
+    /** Optional route description for menus or docs. */
+    description?: string;
+    /** Optional icon identifier. */
+    icon?: string;
+    /** Display order (lower first). */
+    order?: number;
+    /** Optional grouping key for larger menus. */
+    group?: string;
+}
+
+/** Hierarchical tenant. Runtime class: `@happyvertical/smrt-users:Tenant`. */
+export declare interface Tenant extends SmrtEntityFields {
+    name: string;
+    status: TenantStatus;
+    description: string;
+    parentTenantId?: string | null;
+    hierarchyLevel: number;
+    hierarchyPath: string;
+    cascadePermissions: boolean;
+    inheritPermissions: boolean;
+}
+
+/**
+ * Effect of a tenant-level permission setting in a hierarchical tenant tree.
+ *
+ * Unlike `OverrideEffect`, tenant-level effects support `INHERIT` — the default
+ * behaviour where a child tenant walks up to its parent to resolve the permission.
+ * `DENY` blocks inheritance, preventing child tenants from acquiring the permission
+ * even if a grandparent grants it.
+ *
+ * @example
+ * ```typescript
+ * // Sub-tenant explicitly blocks billing access regardless of parent settings
+ * await tenantPermission.create({
+ *   tenantId: subTenantId,
+ *   permission: 'billing.manage',
+ *   effect: TenantPermissionEffect.DENY,
+ * });
+ * ```
+ *
+ * @see {@link OverrideEffect} for user-level overrides (no inheritance step)
+ * @see {@link TenantStatus} for the tenant lifecycle status
+ */
+export declare enum TenantPermissionEffect {
+    /** Inherit from parent tenant (default behavior) */
+    INHERIT = "inherit",
+    /** Explicitly grant at this tenant level */
+    GRANT = "grant",
+    /** Explicitly deny at this tenant level (blocks inheritance) */
+    DENY = "deny"
+}
+
+/**
+ * Lifecycle status of a tenant (organization) within the platform.
+ *
+ * @example
+ * ```typescript
+ * if (tenant.status === TenantStatus.ARCHIVED) {
+ *   return; // skip soft-deleted tenants
+ * }
+ * ```
+ *
+ * @see {@link MembershipStatus} for a user's membership status within a tenant
+ * @see {@link TenantPermissionEffect} for permission inheritance across tenant hierarchies
+ */
+export declare enum TenantStatus {
+    /** Active tenant */
+    ACTIVE = "active",
+    /** Inactive tenant */
+    INACTIVE = "inactive",
+    /** Suspended tenant */
+    SUSPENDED = "suspended",
+    /** Archived tenant (soft-deleted) */
+    ARCHIVED = "archived"
+}
+
+/** Auth identity record. Runtime class: `@happyvertical/smrt-users:User`. */
+export declare interface User extends SmrtEntityFields {
+    /** Plain-string reference to the owning `Profile` (not a DB foreign key). */
+    profileId: string;
+    /** Lower-cased email; globally unique. */
+    email: string;
+    status: UserStatus;
+    lastLoginAt: Date | null;
+}
+
+/**
+ * User-related type definitions
+ *
+ * These enums and types are exported from smrt-types to allow
+ * browser-safe packages (like smrt-svelte) to import them without
+ * pulling in server-side dependencies from smrt-users.
+ */
+/**
+ * Lifecycle status of a user account.
+ *
+ * @example
+ * ```typescript
+ * if (user.status === UserStatus.SUSPENDED) {
+ *   throw new ForbiddenError('Account is suspended');
+ * }
+ * ```
+ *
+ * @see {@link MembershipStatus} for a user's status within a specific tenant
+ * @see {@link SessionStatus} for the status of an active session
+ */
+export declare enum UserStatus {
+    /** Active user account */
+    ACTIVE = "active",
+    /** Inactive user account */
+    INACTIVE = "inactive",
+    /** Suspended user account */
+    SUSPENDED = "suspended",
+    /** Pending email verification */
+    PENDING = "pending"
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,46 @@
+var UserStatus = /* @__PURE__ */ ((UserStatus2) => {
+  UserStatus2["ACTIVE"] = "active";
+  UserStatus2["INACTIVE"] = "inactive";
+  UserStatus2["SUSPENDED"] = "suspended";
+  UserStatus2["PENDING"] = "pending";
+  return UserStatus2;
+})(UserStatus || {});
+var TenantStatus = /* @__PURE__ */ ((TenantStatus2) => {
+  TenantStatus2["ACTIVE"] = "active";
+  TenantStatus2["INACTIVE"] = "inactive";
+  TenantStatus2["SUSPENDED"] = "suspended";
+  TenantStatus2["ARCHIVED"] = "archived";
+  return TenantStatus2;
+})(TenantStatus || {});
+var MembershipStatus = /* @__PURE__ */ ((MembershipStatus2) => {
+  MembershipStatus2["ACTIVE"] = "active";
+  MembershipStatus2["INACTIVE"] = "inactive";
+  MembershipStatus2["PENDING"] = "pending";
+  return MembershipStatus2;
+})(MembershipStatus || {});
+var SessionStatus = /* @__PURE__ */ ((SessionStatus2) => {
+  SessionStatus2["ACTIVE"] = "active";
+  SessionStatus2["EXPIRED"] = "expired";
+  SessionStatus2["REVOKED"] = "revoked";
+  return SessionStatus2;
+})(SessionStatus || {});
+var OverrideEffect = /* @__PURE__ */ ((OverrideEffect2) => {
+  OverrideEffect2["GRANT"] = "grant";
+  OverrideEffect2["DENY"] = "deny";
+  return OverrideEffect2;
+})(OverrideEffect || {});
+var TenantPermissionEffect = /* @__PURE__ */ ((TenantPermissionEffect2) => {
+  TenantPermissionEffect2["INHERIT"] = "inherit";
+  TenantPermissionEffect2["GRANT"] = "grant";
+  TenantPermissionEffect2["DENY"] = "deny";
+  return TenantPermissionEffect2;
+})(TenantPermissionEffect || {});
+export {
+  MembershipStatus,
+  OverrideEffect,
+  SessionStatus,
+  TenantPermissionEffect,
+  TenantStatus,
+  UserStatus
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/user.ts"],"sourcesContent":["/**\n * User-related type definitions\n *\n * These enums and types are exported from smrt-types to allow\n * browser-safe packages (like smrt-svelte) to import them without\n * pulling in server-side dependencies from smrt-users.\n */\n\n// ============= User Status =============\n\n/**\n * Lifecycle status of a user account.\n *\n * @example\n * ```typescript\n * if (user.status === UserStatus.SUSPENDED) {\n *   throw new ForbiddenError('Account is suspended');\n * }\n * ```\n *\n * @see {@link MembershipStatus} for a user's status within a specific tenant\n * @see {@link SessionStatus} for the status of an active session\n */\nexport enum UserStatus {\n  /** Active user account */\n  ACTIVE = 'active',\n  /** Inactive user account */\n  INACTIVE = 'inactive',\n  /** Suspended user account */\n  SUSPENDED = 'suspended',\n  /** Pending email verification */\n  PENDING = 'pending',\n}\n\n// ============= Tenant Status =============\n\n/**\n * Lifecycle status of a tenant (organization) within the platform.\n *\n * @example\n * ```typescript\n * if (tenant.status === TenantStatus.ARCHIVED) {\n *   return; // skip soft-deleted tenants\n * }\n * ```\n *\n * @see {@link MembershipStatus} for a user's membership status within a tenant\n * @see {@link TenantPermissionEffect} for permission inheritance across tenant hierarchies\n */\nexport enum TenantStatus {\n  /** Active tenant */\n  ACTIVE = 'active',\n  /** Inactive tenant */\n  INACTIVE = 'inactive',\n  /** Suspended tenant */\n  SUSPENDED = 'suspended',\n  /** Archived tenant (soft-deleted) */\n  ARCHIVED = 'archived',\n}\n\n// ============= Membership Status =============\n\n/**\n * Status of a user's membership within a specific tenant.\n *\n * A user may hold memberships in multiple tenants simultaneously, each with an\n * independent `MembershipStatus`.\n *\n * @example\n * ```typescript\n * const active = memberships.filter(m => m.status === MembershipStatus.ACTIVE);\n * ```\n *\n * @see {@link UserStatus} for the global account-level status\n * @see {@link TenantStatus} for the status of the tenant itself\n */\nexport enum MembershipStatus {\n  /** Active membership */\n  ACTIVE = 'active',\n  /** Inactive membership */\n  INACTIVE = 'inactive',\n  /** Pending invitation acceptance */\n  PENDING = 'pending',\n}\n\n// ============= Session Status =============\n\n/**\n * Status of an authenticated session.\n *\n * Sessions transition from `ACTIVE` to either `EXPIRED` (time-based) or\n * `REVOKED` (explicit action by the user or an administrator).\n *\n * @example\n * ```typescript\n * if (session.status !== SessionStatus.ACTIVE) {\n *   redirect(302, '/login');\n * }\n * ```\n *\n * @see {@link UserStatus} for the account-level status checked before session creation\n */\nexport enum SessionStatus {\n  /** Active session */\n  ACTIVE = 'active',\n  /** Expired session (past expiresAt) */\n  EXPIRED = 'expired',\n  /** Revoked by user or admin */\n  REVOKED = 'revoked',\n}\n\n// ============= Permission Override =============\n\n/**\n * Effect applied by a user-level permission override.\n *\n * Overrides target a specific user + permission combination and always win\n * over role-based grants. `DENY` overrides are checked before `GRANT` in\n * the 4-level permission cascade.\n *\n * @example\n * ```typescript\n * await override.create({\n *   userId,\n *   permission: 'billing.view',\n *   effect: OverrideEffect.DENY,\n * });\n * ```\n *\n * @see {@link TenantPermissionEffect} for the tenant-level equivalent that supports inheritance\n */\nexport enum OverrideEffect {\n  /** Grant the permission */\n  GRANT = 'grant',\n  /** Deny the permission */\n  DENY = 'deny',\n}\n\n// ============= Tenant Permission Override =============\n\n/**\n * Effect of a tenant-level permission setting in a hierarchical tenant tree.\n *\n * Unlike `OverrideEffect`, tenant-level effects support `INHERIT` — the default\n * behaviour where a child tenant walks up to its parent to resolve the permission.\n * `DENY` blocks inheritance, preventing child tenants from acquiring the permission\n * even if a grandparent grants it.\n *\n * @example\n * ```typescript\n * // Sub-tenant explicitly blocks billing access regardless of parent settings\n * await tenantPermission.create({\n *   tenantId: subTenantId,\n *   permission: 'billing.manage',\n *   effect: TenantPermissionEffect.DENY,\n * });\n * ```\n *\n * @see {@link OverrideEffect} for user-level overrides (no inheritance step)\n * @see {@link TenantStatus} for the tenant lifecycle status\n */\nexport enum TenantPermissionEffect {\n  /** Inherit from parent tenant (default behavior) */\n  INHERIT = 'inherit',\n  /** Explicitly grant at this tenant level */\n  GRANT = 'grant',\n  /** Explicitly deny at this tenant level (blocks inheritance) */\n  DENY = 'deny',\n}\n"],"names":["UserStatus","TenantStatus","MembershipStatus","SessionStatus","OverrideEffect","TenantPermissionEffect"],"mappings":"AAuBO,IAAK,+BAAAA,gBAAL;AAELA,cAAA,QAAA,IAAS;AAETA,cAAA,UAAA,IAAW;AAEXA,cAAA,WAAA,IAAY;AAEZA,cAAA,SAAA,IAAU;AARA,SAAAA;AAAA,GAAA,cAAA,CAAA,CAAA;AA0BL,IAAK,iCAAAC,kBAAL;AAELA,gBAAA,QAAA,IAAS;AAETA,gBAAA,UAAA,IAAW;AAEXA,gBAAA,WAAA,IAAY;AAEZA,gBAAA,UAAA,IAAW;AARD,SAAAA;AAAA,GAAA,gBAAA,CAAA,CAAA;AA2BL,IAAK,qCAAAC,sBAAL;AAELA,oBAAA,QAAA,IAAS;AAETA,oBAAA,UAAA,IAAW;AAEXA,oBAAA,SAAA,IAAU;AANA,SAAAA;AAAA,GAAA,oBAAA,CAAA,CAAA;AA0BL,IAAK,kCAAAC,mBAAL;AAELA,iBAAA,QAAA,IAAS;AAETA,iBAAA,SAAA,IAAU;AAEVA,iBAAA,SAAA,IAAU;AANA,SAAAA;AAAA,GAAA,iBAAA,CAAA,CAAA;AA6BL,IAAK,mCAAAC,oBAAL;AAELA,kBAAA,OAAA,IAAQ;AAERA,kBAAA,MAAA,IAAO;AAJG,SAAAA;AAAA,GAAA,kBAAA,CAAA,CAAA;AA8BL,IAAK,2CAAAC,4BAAL;AAELA,0BAAA,SAAA,IAAU;AAEVA,0BAAA,OAAA,IAAQ;AAERA,0BAAA,MAAA,IAAO;AANG,SAAAA;AAAA,GAAA,0BAAA,CAAA,CAAA;"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@happyvertical/smrt-types",
+  "version": "0.30.0",
+  "description": "Shared type definitions for the HAVE SDK",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "25.0.9",
+    "typescript": "^5.9.3",
+    "vite": "7.3.1",
+    "vitest": "^4.0.17"
+  },
+  "files": [
+    "dist",
+    "CLAUDE.md",
+    "AGENTS.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "author": "HappyVertical",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/types"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "vite build",
+    "build:watch": "vite build --watch",
+    "docs": "typedoc --plugin typedoc-plugin-markdown --out docs --entryPoints ./src/index.ts --tsconfig ./tsconfig.json --excludePrivate --excludeInternal --hideGenerator --fileExtension .md --readme none --categorizeByGroup false --includeVersion false --hidePageHeader --hidePageTitle false --outputFileStrategy modules",
+    "docs:watch": "typedoc --plugin typedoc-plugin-markdown --out docs --entryPoints ./src/index.ts --tsconfig ./tsconfig.json --excludePrivate --excludeInternal --hideGenerator --fileExtension .md --readme none --categorizeByGroup false --includeVersion false --hidePageHeader --hidePageTitle false --outputFileStrategy modules --watch",
+    "clean": "rm -rf dist docs",
+    "dev": "npm run build:watch & npm run test:watch"
+  }
+}