@happyvertical/smrt-core 0.30.0

package/dist/embeddings/types.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Embedding Types for SMRT Framework
+ *
+ * Types for centralized embedding storage and semantic search.
+ */
+/**
+ * Embedding provider type
+ */
+export type EmbeddingProviderType = 'local' | 'ai' | 'auto';
+/**
+ * Project-level embedding configuration (from smrt.config)
+ */
+export interface ProjectEmbeddingConfig {
+    /**
+     * Standard dimensions for the project
+     * @default 768
+     */
+    dimensions: number;
+    /**
+     * Embedding provider type
+     * - 'local': Use local Node.js model (@huggingface/transformers or
+     *   @xenova/transformers)
+     * - 'ai': Use AI library (OpenAI, etc.)
+     * - 'auto': Prefer configured AI embeddings, otherwise use local embeddings
+     *   when explicitly invoked
+     * @default 'local'
+     */
+    provider: EmbeddingProviderType;
+    /**
+     * Local model to use (when provider is 'local' or 'auto')
+     * @default 'Xenova/bge-base-en-v1.5'
+     */
+    localModel?: string;
+    /**
+     * AI model to use (when provider is 'ai' or fallback)
+     * @default 'text-embedding-3-small'
+     */
+    aiModel?: string;
+    /**
+     * Legacy local-first auto fallback option.
+     *
+     * @deprecated `auto` now selects AI first when available and otherwise uses
+     * local embeddings. This option is accepted for backwards compatibility but
+     * no longer changes provider selection.
+     */
+    fallbackToAI?: boolean;
+    /**
+     * Storage mode for embeddings
+     * - 'json': Store as JSON text, in-memory similarity (works everywhere)
+     * - 'native': Use database vector operations when available, fallback to json
+     * @default 'json'
+     */
+    storage?: 'json' | 'native';
+}
+/**
+ * Per-class embedding configuration (from @smrt decorator)
+ */
+export interface ClassEmbeddingConfig {
+    /**
+     * Fields to generate embeddings for
+     */
+    fields: string[];
+    /**
+     * Override provider for this class
+     */
+    provider?: EmbeddingProviderType;
+    /**
+     * Auto-generate embeddings on save
+     * @default true
+     */
+    autoGenerate?: boolean;
+    /**
+     * Only regenerate if content changed (hash-based detection)
+     * @default true
+     */
+    regenerateOnChange?: boolean;
+    /**
+     * Combined field for semantic search
+     * Creates a virtual embedding from multiple fields
+     */
+    combinedField?: {
+        /**
+         * Name of the virtual field (e.g., 'content')
+         */
+        name: string;
+        /**
+         * Template for combining fields (e.g., '{title}\n\n{body}')
+         */
+        template: string;
+    };
+}
+/**
+ * Resolved embedding configuration (project + class merged)
+ */
+export interface ResolvedEmbeddingConfig extends ClassEmbeddingConfig {
+    /**
+     * Dimensions for this class (from project or override)
+     */
+    dimensions: number;
+    /**
+     * Resolved provider
+     */
+    provider: EmbeddingProviderType;
+    /**
+     * Local model to use
+     */
+    localModel: string;
+    /**
+     * AI model to use
+     */
+    aiModel: string;
+    /**
+     * Legacy fallback behavior retained for compatibility
+     */
+    fallbackToAI: boolean;
+}
+/**
+ * Stored embedding record in _smrt_embeddings table
+ */
+export interface StoredEmbedding {
+    /**
+     * Unique identifier
+     */
+    id: string;
+    /**
+     * Class name of the source object
+     */
+    object_class: string;
+    /**
+     * ID of the source object
+     */
+    object_id: string;
+    /**
+     * Field name that was embedded
+     */
+    field_name: string;
+    /**
+     * SHA-256 hash of the source content
+     */
+    content_hash: string;
+    /**
+     * Embedding vector (as number array)
+     */
+    embedding: number[];
+    /**
+     * Model used to generate the embedding
+     */
+    model: string;
+    /**
+     * Number of dimensions
+     */
+    dimensions: number;
+    /**
+     * Provider used ('local' or 'ai')
+     */
+    provider?: string;
+    /**
+     * Creation timestamp
+     */
+    created_at: Date;
+    /**
+     * Last update timestamp
+     */
+    updated_at: Date;
+}
+/**
+ * Options for embedding generation
+ */
+export interface GenerateEmbeddingsOptions {
+    /**
+     * Override which fields to embed
+     */
+    fields?: string[];
+    /**
+     * Override provider
+     */
+    provider?: EmbeddingProviderType;
+    /**
+     * Force regeneration even if content unchanged
+     */
+    force?: boolean;
+}
+/**
+ * Options for semantic search
+ */
+export interface SemanticSearchOptions {
+    /**
+     * Field to search (default: combined field or first configured field)
+     */
+    field?: string;
+    /**
+     * Maximum results
+     * @default 10
+     */
+    limit?: number;
+    /**
+     * Minimum cosine similarity (0-1)
+     * @default 0
+     */
+    minSimilarity?: number;
+    /**
+     * Additional SQL filters
+     */
+    where?: Record<string, unknown>;
+}
+/**
+ * Options for finding similar objects
+ */
+export interface FindSimilarOptions extends Omit<SemanticSearchOptions, 'where'> {
+    /**
+     * Exclude the source object from results
+     * @default true
+     */
+    excludeSelf?: boolean;
+}
+/**
+ * Result of batch embedding generation
+ */
+export interface BatchGenerateResult {
+    /**
+     * Number of objects that had embeddings generated
+     */
+    generated: number;
+    /**
+     * Number of objects skipped (unchanged content)
+     */
+    skipped: number;
+}
+/**
+ * Progress callback for batch operations
+ */
+export type BatchProgressCallback = (progress: {
+    completed: number;
+    total: number;
+}) => void;
+/**
+ * Options for batch embedding generation
+ */
+export interface BatchGenerateOptions {
+    /**
+     * Number of objects to process at once
+     * @default 50
+     */
+    batchSize?: number;
+    /**
+     * Progress callback
+     */
+    onProgress?: BatchProgressCallback;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/embeddings/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/embeddings/types.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,363 @@
+/**
+ * Comprehensive error handling system for SMRT framework
+ *
+ * Provides specialized error types for different failure scenarios
+ * with proper error codes, messages, and debugging information.
+ */
+export declare abstract class SmrtError extends Error {
+    readonly code: string;
+    readonly category: 'database' | 'ai' | 'filesystem' | 'validation' | 'network' | 'configuration' | 'runtime';
+    readonly details?: Record<string, any>;
+    readonly cause?: Error;
+    constructor(message: string, code: string, category: SmrtError['category'], details?: Record<string, any>, cause?: Error);
+    /**
+     * Converts error to a serializable object for logging/debugging
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        category: "ai" | "database" | "filesystem" | "validation" | "network" | "configuration" | "runtime";
+        details: Record<string, any> | undefined;
+        stack: string | undefined;
+        cause: {
+            name: string;
+            message: string;
+            stack: string | undefined;
+        } | undefined;
+    };
+}
+/**
+ * Errors originating from database operations.
+ *
+ * Use the static factory methods rather than the constructor directly:
+ * - `DatabaseError.connectionFailed(url, cause)` — DB connection failure
+ * - `DatabaseError.queryFailed(query, cause)` — SQL execution error
+ * - `DatabaseError.schemaError(table, op, cause)` — DDL/migration error
+ * - `DatabaseError.constraintViolation(constraint, value, cause)` — FK/CHECK/UNIQUE
+ * - `DatabaseError.corruptedData(field, class, cause)` — unparse-able column data
+ * - `DatabaseError.missingDiscriminator(class, rowId)` — STI row missing `_meta_type`
+ * - `DatabaseError.stiDiscriminatorConflict(...)` — legacy STI discriminator collides during qualification
+ * - `DatabaseError.schemaMissing(table, class)` — table not yet migrated
+ *
+ * All errors have `category: 'database'` and codes prefixed with `DB_`.
+ */
+export declare class DatabaseError extends SmrtError {
+    constructor(message: string, code: string, details?: Record<string, any>, cause?: Error);
+    static connectionFailed(dbUrl: string, cause?: Error): DatabaseError;
+    static queryFailed(query: string, cause?: Error): DatabaseError;
+    static schemaError(tableName: string, operation: string, cause?: Error): DatabaseError;
+    static constraintViolation(constraint: string, value: any, cause?: Error): DatabaseError;
+    static corruptedData(fieldName: string, className: string, cause?: Error): DatabaseError;
+    static missingDiscriminator(className: string, rowId?: string): DatabaseError;
+    static stiDiscriminatorConflict(details: {
+        className: string;
+        tableName: string;
+        id: string;
+        slug: string;
+        context: string;
+        conflictIdentity: Record<string, any>;
+        legacyMetaType: string;
+        qualifiedMetaType: string;
+        duplicateId: string;
+    }): DatabaseError;
+    static schemaMissing(tableName: string, className: string): DatabaseError;
+}
+/**
+ * Errors from AI provider integrations.
+ *
+ * Use the static factory methods:
+ * - `AIError.providerError(provider, operation, cause)` — generic provider failure
+ * - `AIError.rateLimitExceeded(provider, retryAfter)` — rate limit hit
+ * - `AIError.invalidResponse(provider, response)` — unexpected response shape
+ * - `AIError.authenticationFailed(provider)` — bad API key / credentials
+ *
+ * All errors have `category: 'ai'` and codes prefixed with `AI_`.
+ * AI errors are considered retryable by `ErrorUtils.isRetryable()`.
+ */
+export declare class AIError extends SmrtError {
+    constructor(message: string, code: string, details?: Record<string, any>, cause?: Error);
+    static providerError(provider: string, operation: string, cause?: Error): AIError;
+    static rateLimitExceeded(provider: string, retryAfter?: number): AIError;
+    static invalidResponse(provider: string, response: any): AIError;
+    static authenticationFailed(provider: string): AIError;
+}
+/**
+ * Errors from filesystem operations.
+ *
+ * Use the static factory methods:
+ * - `FilesystemError.fileNotFound(path)` — file does not exist
+ * - `FilesystemError.permissionDenied(path, operation)` — access denied
+ * - `FilesystemError.diskSpaceExceeded(path, requiredBytes)` — insufficient space
+ *
+ * All errors have `category: 'filesystem'` and codes prefixed with `FS_`.
+ */
+export declare class FilesystemError extends SmrtError {
+    constructor(message: string, code: string, details?: Record<string, any>, cause?: Error);
+    static fileNotFound(path: string): FilesystemError;
+    static permissionDenied(path: string, operation: string): FilesystemError;
+    static diskSpaceExceeded(path: string, requiredBytes: number): FilesystemError;
+}
+/**
+ * Input/data validation errors thrown before or during a database operation.
+ *
+ * `save()` throws `ValidationError` when field validation fails. The collection's
+ * `convertWhereKeys()` throws it for invalid WHERE clause operators or field names.
+ * `ValidationError` is **not** retried by `ErrorUtils.withRetry()`.
+ *
+ * Use the static factory methods:
+ * - `ValidationError.requiredField(field, objectType)` — missing required field
+ * - `ValidationError.invalidValue(field, value, expected)` — wrong type/format
+ * - `ValidationError.uniqueConstraint(field, value)` — duplicate unique value
+ * - `ValidationError.rangeError(field, value, min?, max?)` — out of allowed range
+ *
+ * All errors have `category: 'validation'` and codes prefixed with `VALIDATION_`.
+ */
+export declare class ValidationError extends SmrtError {
+    constructor(message: string, code: string, details?: Record<string, any>, cause?: Error);
+    static requiredField(fieldName: string, objectType: string): ValidationError;
+    static invalidValue(fieldName: string, value: any, expectedType: string): ValidationError;
+    static uniqueConstraint(fieldName: string, value: any): ValidationError;
+    static rangeError(fieldName: string, value: number, min?: number, max?: number): ValidationError;
+}
+/**
+ * Errors from HTTP and external network operations.
+ *
+ * Use the static factory methods:
+ * - `NetworkError.requestFailed(url, status?, body?)` — non-2xx response or connection failure
+ * - `NetworkError.timeout(url, timeoutMs)` — request exceeded timeout
+ * - `NetworkError.serviceUnavailable(service, reason?)` — external service down
+ *
+ * All errors have `category: 'network'` and codes prefixed with `NETWORK_`.
+ * Network errors are considered retryable by `ErrorUtils.isRetryable()`.
+ */
+export declare class NetworkError extends SmrtError {
+    constructor(message: string, code: string, details?: Record<string, any>, cause?: Error);
+    static requestFailed(url: string, status?: number, responseBody?: string | Error): NetworkError;
+    static timeout(url: string, timeoutMs: number): NetworkError;
+    static serviceUnavailable(service: string, reason?: string): NetworkError;
+}
+/**
+ * Errors from misconfigured or incompatible class/framework setup.
+ *
+ * These are typically thrown during class registration (i.e. at module load time),
+ * not during normal request handling.
+ *
+ * Use the static factory methods:
+ * - `ConfigurationError.missingConfiguration(key, context?)` — missing required config
+ * - `ConfigurationError.invalidConfiguration(key, value, expected)` — wrong config type/value
+ * - `ConfigurationError.initializationFailed(component, cause?)` — component failed to start
+ * - `ConfigurationError.circularInheritance(class, chain)` — circular class inheritance
+ * - `ConfigurationError.incompatibleStrategy(class, strategy, parent, parentStrategy)` — STI mismatch
+ * - `ConfigurationError.unregisteredBaseClass(child, base)` — STI base not yet registered
+ *
+ * All errors have `category: 'configuration'` and codes prefixed with `CONFIG_`.
+ * Configuration errors are **not** retried by `ErrorUtils.withRetry()`.
+ */
+export declare class ConfigurationError extends SmrtError {
+    constructor(message: string, code: string, details?: Record<string, any>, cause?: Error);
+    static missingConfiguration(configKey: string, context?: string): ConfigurationError;
+    static invalidConfiguration(configKey: string, value: any, expected: string): ConfigurationError;
+    static initializationFailed(component: string, cause?: Error): ConfigurationError;
+    static circularInheritance(className: string, inheritanceChain: string[]): ConfigurationError;
+    static incompatibleStrategy(className: string, classStrategy: string, parentClass: string, parentStrategy: string): ConfigurationError;
+    static unregisteredBaseClass(childClass: string, baseClass: string): ConfigurationError;
+}
+/**
+ * Errors representing unexpected runtime failures not covered by other categories.
+ *
+ * `RuntimeError` is the catch-all for internal framework errors — invalid object
+ * state, exhausted resources, or failures in operations like `save()` and `loadFromId()`
+ * that propagate from an unknown cause.
+ *
+ * Use the static factory methods:
+ * - `RuntimeError.operationFailed(operation, context?, cause?)` — generic operation failure
+ * - `RuntimeError.invalidState(message, context?)` — unexpected object/system state
+ * - `RuntimeError.resourceExhausted(resource, limit)` — limit exceeded (e.g. connections)
+ *
+ * All errors have `category: 'runtime'` and codes prefixed with `RUNTIME_`.
+ */
+export declare class RuntimeError extends SmrtError {
+    constructor(message: string, code: string, details?: Record<string, any>, cause?: Error);
+    static operationFailed(operation: string, context?: string, cause?: Error): RuntimeError;
+    static invalidState(message: string, context?: Record<string, any>): RuntimeError;
+    static resourceExhausted(resource: string, limit: number): RuntimeError;
+}
+/**
+ * Error thrown when a tenant isolation boundary is crossed while resolving a
+ * relationship.
+ *
+ * Raised by {@link SmrtObject.loadRelated} / {@link SmrtObject.loadRelatedMany}
+ * (and {@link SmrtObject.getRelated}, which delegates to them) when a
+ * tenant-scoped object resolves a relationship to an object belonging to a
+ * *different*, non-null tenant — the genuine cross-tenant data leak. The guard
+ * is a no-op when either side has a `null` tenant (global / non-tenant-scoped
+ * models) and when both sides share the same tenant, so it only fires on real
+ * leaks. Pass `{ allowCrossTenant: true }` to the loader to deliberately opt out.
+ *
+ * The `code` is always `'TENANT_ISOLATION_VIOLATION'` and the category is
+ * `'validation'`. It is never retried — `ErrorUtils.withRetry()` rethrows it
+ * immediately and `ErrorUtils.isRetryable()` returns `false` — because a tenant
+ * boundary violation is deterministic. `tenantId` is the owning object's tenant
+ * and `attemptedTenantId` is the tenant of the object that was reached.
+ *
+ * This shares its stable `code`, `name`, `tenantId`, and `attemptedTenantId`
+ * shape with the interceptor-level `TenantIsolationError` in
+ * `@happyvertical/smrt-tenancy`, so cross-cutting handlers can match either via
+ * `err.code === 'TENANT_ISOLATION_VIOLATION'`. They are intentionally distinct
+ * classes because `@happyvertical/smrt-core` cannot depend on the tenancy
+ * package (the dependency runs the other way).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await order.loadRelated('customerId');
+ * } catch (err) {
+ *   if (err instanceof TenantIsolationError) {
+ *     // err.tenantId          — the order's tenant
+ *     // err.attemptedTenantId — the customer's tenant
+ *   }
+ * }
+ * ```
+ *
+ * @see SmrtObject.loadRelated
+ * @see SmrtObject.loadRelatedMany
+ */
+export declare class TenantIsolationError extends SmrtError {
+    /** The tenant ID of the object that owns the relationship. */
+    readonly tenantId?: string;
+    /** The tenant ID of the related object that was reached (and rejected). */
+    readonly attemptedTenantId?: string;
+    constructor(message: string, details?: {
+        tenantId?: string;
+        attemptedTenantId?: string;
+        [key: string]: any;
+    }, cause?: Error);
+    /**
+     * Builds a {@link TenantIsolationError} for a blocked cross-tenant
+     * relationship resolution, with a descriptive message and structured details.
+     */
+    static crossTenantReference(details: {
+        sourceClass: string;
+        fieldName: string;
+        sourceTenantId: string;
+        targetClass?: string;
+        targetTenantId: string;
+    }): TenantIsolationError;
+}
+/**
+ * Utility functions for error handling
+ */
+export declare class ErrorUtils {
+    /**
+     * Wraps a function with error handling and automatic retry logic
+     */
+    static withRetry<T>(operation: () => Promise<T>, maxRetries?: number, delay?: number, backoffMultiplier?: number): Promise<T>;
+    /**
+     * Checks if an error is retryable
+     */
+    static isRetryable(error: Error): boolean;
+    /**
+     * Sanitizes an error for safe logging (removes sensitive information)
+     */
+    static sanitizeError(error: Error): Record<string, any>;
+}
+/**
+ * Validation report that collects multiple validation errors
+ *
+ * Useful for validating an entire object and reporting all errors
+ * at once rather than stopping at the first error.
+ *
+ * @example
+ * ```typescript
+ * const report = new ValidationReport('Product');
+ * report.addError(ValidationError.requiredField('name', 'Product'));
+ * report.addError(ValidationError.rangeError('price', -10, 0));
+ *
+ * if (report.hasErrors()) {
+ *   console.error(report.toString());
+ *   // Output:
+ *   // Validation failed for Product with 2 errors:
+ *   // - name: Required field 'name' is missing for Product
+ *   // - price: Value -10 for field 'price' is outside allowed range [0, undefined]
+ * }
+ * ```
+ */
+export declare class ValidationReport {
+    private errors;
+    private objectType;
+    constructor(objectType: string);
+    /**
+     * Add a validation error to the report
+     */
+    addError(error: ValidationError): void;
+    /**
+     * Check if there are any validation errors
+     */
+    hasErrors(): boolean;
+    /**
+     * Get all validation errors
+     */
+    getErrors(): ValidationError[];
+    /**
+     * Get the number of validation errors
+     */
+    getErrorCount(): number;
+    /**
+     * Convert to a human-readable string
+     */
+    toString(): string;
+    /**
+     * Convert to JSON format
+     */
+    toJSON(): object;
+    /**
+     * Throw the first error if there are any errors
+     */
+    throwIfErrors(): void;
+    /**
+     * Clear all errors
+     */
+    clear(): void;
+}
+/**
+ * Validation utility functions
+ */
+export declare class ValidationUtils {
+    /**
+     * Validate a single field value
+     *
+     * @param fieldName - Name of the field
+     * @param value - Value to validate
+     * @param options - Validation options (required, min, max, etc.)
+     * @returns ValidationError if validation fails, null otherwise
+     */
+    static validateField(fieldName: string, value: any, options: {
+        required?: boolean;
+        min?: number;
+        max?: number;
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string | RegExp;
+        type?: string;
+        customValidator?: (value: any) => boolean | Promise<boolean>;
+        customMessage?: string;
+    }, objectType?: string): Promise<ValidationError | null>;
+    /**
+     * Validate required field
+     */
+    static validateRequired(fieldName: string, value: any, objectType?: string): ValidationError | null;
+    /**
+     * Validate numeric range
+     */
+    static validateRange(fieldName: string, value: number, min?: number, max?: number): ValidationError | null;
+    /**
+     * Validate string length
+     */
+    static validateLength(fieldName: string, value: string, minLength?: number, maxLength?: number): ValidationError | null;
+    /**
+     * Validate string pattern
+     */
+    static validatePattern(fieldName: string, value: string, pattern: string | RegExp): ValidationError | null;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}