@aphexcms/cms-core 0.1.7 → 0.1.8

package/src/lib/db/interfaces/index.ts

@@ -0,0 +1,98 @@
+// Combined database interface
+import type { DocumentAdapter } from './document';
+import type { AssetAdapter } from './asset';
+import type { UserProfileAdapter } from './user';
+import type { SchemaAdapter } from './schema';
+import type { OrganizationAdapter } from './organization';
+
+// Re-export individual interfaces
+export type {
+	DocumentAdapter,
+	DocumentFilters,
+	CreateDocumentData,
+	UpdateDocumentData
+} from './document';
+export type { AssetAdapter, CreateAssetData, UpdateAssetData } from './asset';
+export type { UserProfileAdapter, NewUserProfileData } from './user';
+export type { SchemaAdapter } from './schema';
+export type { OrganizationAdapter } from './organization';
+
+/**
+ * Combined database adapter interface
+ * Extends all entity-specific adapters for full database functionality
+ */
+export interface DatabaseAdapter
+	extends DocumentAdapter,
+		AssetAdapter,
+		UserProfileAdapter,
+		SchemaAdapter,
+		OrganizationAdapter {
+	// Connection management
+	connect?(): Promise<void>;
+	disconnect?(): Promise<void>;
+
+	// Health check
+	isHealthy(): Promise<boolean>;
+
+	// Multi-tenancy RLS methods (optional - only for adapters that support RLS)
+	/**
+	 * Initialize RLS (enable/disable) on tables - call after migrations
+	 */
+	initializeRLS?(): Promise<void>;
+
+	/**
+	 * Execute a function within a transaction with organization context set for RLS
+	 * Ensures proper isolation with connection pooling
+	 */
+	withOrgContext?<T>(organizationId: string, fn: () => Promise<T>): Promise<T>;
+
+	/**
+	 * Get all child organizations for a parent (for hierarchy support)
+	 */
+	getChildOrganizations?(parentOrganizationId: string): Promise<string[]>;
+
+	/**
+	 * Check if any user profiles exist in the system (for first-user detection)
+	 */
+	hasAnyUserProfiles?(): Promise<boolean>;
+}
+
+/**
+ * Database provider factory interface
+ * Providers are pre-configured and create adapters on demand
+ */
+export interface DatabaseProvider {
+	name: string;
+	createAdapter(): DatabaseAdapter;
+}
+
+/**
+ * Generic database configuration
+ */
+export interface DatabaseConfig {
+	connectionString?: string; // Optional if client is provided
+	client?: any; // Pre-initialized database client (recommended for database agnosticism)
+	options?: {
+		maxConnections?: number;
+		timeout?: number;
+		ssl?: boolean;
+		[key: string]: any;
+	};
+}
+
+/**
+ * Database transaction interface (optional for advanced providers)
+ */
+export interface DatabaseTransaction {
+	commit(): Promise<void>;
+	rollback(): Promise<void>;
+	isActive(): boolean;
+}
+
+/**
+ * Extended database adapter with transaction support
+ */
+export interface TransactionalDatabaseAdapter extends DatabaseAdapter {
+	beginTransaction(): Promise<DatabaseTransaction>;
+	withTransaction<T>(fn: (adapter: DatabaseAdapter) => Promise<T>): Promise<T>;
+}

package/src/lib/db/interfaces/organization.ts

@@ -0,0 +1,51 @@
+// Organization adapter interface for multi-tenancy operations
+import type {
+	Organization,
+	NewOrganization,
+	OrganizationMember,
+	NewOrganizationMember,
+	Invitation,
+	NewInvitation,
+	UserSession,
+	OrganizationMembership
+} from '../../types/organization';
+
+export interface OrganizationAdapter {
+	// Organization CRUD
+	createOrganization(data: NewOrganization): Promise<Organization>;
+	findOrganizationById(id: string): Promise<Organization | null>;
+	findOrganizationBySlug(slug: string): Promise<Organization | null>;
+	updateOrganization(
+		id: string,
+		data: Partial<Omit<Organization, 'id' | 'createdAt' | 'createdBy'>>
+	): Promise<Organization | null>;
+	deleteOrganization(id: string): Promise<boolean>;
+
+	// Member management
+	addMember(data: NewOrganizationMember): Promise<OrganizationMember>;
+	removeMember(organizationId: string, userId: string): Promise<boolean>;
+	removeAllMembers(organizationId: string): Promise<boolean>;
+	updateMemberRole(
+		organizationId: string,
+		userId: string,
+		role: 'owner' | 'admin' | 'editor' | 'viewer'
+	): Promise<OrganizationMember | null>;
+	findUserMembership(userId: string, organizationId: string): Promise<OrganizationMember | null>;
+	findUserOrganizations(userId: string): Promise<OrganizationMembership[]>;
+	findOrganizationMembers(organizationId: string): Promise<OrganizationMember[]>;
+
+	// Invitation management
+	createInvitation(data: NewInvitation): Promise<Invitation>;
+	findInvitationByToken(token: string): Promise<Invitation | null>;
+	findOrganizationInvitations(organizationId: string): Promise<Invitation[]>;
+	findInvitationsByEmail(email: string): Promise<Invitation[]>;
+	acceptInvitation(token: string, userId: string): Promise<OrganizationMember>;
+	deleteInvitation(id: string): Promise<boolean>;
+	removeAllInvitations(organizationId: string): Promise<boolean>;
+	cleanupExpiredInvitations(): Promise<number>;
+
+	// User session management
+	updateUserSession(userId: string, organizationId: string): Promise<void>;
+	findUserSession(userId: string): Promise<UserSession | null>;
+	deleteUserSession(userId: string): Promise<boolean>;
+}

package/src/lib/db/interfaces/schema.ts

@@ -0,0 +1,13 @@
+import type { SchemaType } from '../../types/index';
+
+/**
+ * Defines database operations for managing schemas.
+ */
+export interface SchemaAdapter {
+	registerSchemaType(schemaType: SchemaType): Promise<void>;
+	getSchemaType(name: string): Promise<SchemaType | null>;
+	listSchemas(): Promise<SchemaType[]>;
+	listDocumentTypes(): Promise<Array<{ name: string; title: string; description?: string }>>;
+	listObjectTypes(): Promise<Array<{ name: string; title: string; description?: string }>>;
+	deleteSchemaType(name: string): Promise<void>;
+}

package/src/lib/db/interfaces/user.ts

@@ -0,0 +1,16 @@
+import type { UserProfile } from '../../types/index';
+
+export interface NewUserProfileData {
+	userId: string;
+	role?: 'super_admin' | 'admin' | 'editor' | 'viewer';
+	preferences?: Record<string, any>;
+}
+
+/**
+ * Defines database operations for managing user profiles.
+ */
+export interface UserProfileAdapter {
+	createUserProfile(data: NewUserProfileData): Promise<UserProfile>;
+	findUserProfileById(userId: string): Promise<UserProfile | null>;
+	deleteUserProfile(userId: string): Promise<boolean>;
+}

package/src/lib/db/utils/reference-resolver.ts

@@ -0,0 +1,119 @@
+// Reference resolution utility for resolving nested document references
+import type { Document } from '../../types/index';
+import type { DocumentAdapter } from '../interfaces/document';
+
+interface ResolveOptions {
+	depth: number;
+	currentDepth?: number;
+	visited?: Set<string>; // Track visited documents to prevent circular references
+}
+
+/**
+ * Recursively resolves reference fields in a document
+ * @param document - The document to resolve references for
+ * @param adapter - Document adapter for fetching referenced documents
+ * @param organizationId - Organization ID for filtering referenced documents
+ * @param options - Resolution options (depth, tracking)
+ * @returns Document with resolved references
+ */
+export async function resolveReferences(
+	document: Document,
+	adapter: DocumentAdapter,
+	organizationId: string,
+	options: ResolveOptions
+): Promise<Document> {
+	const { depth, currentDepth = 0, visited = new Set() } = options;
+
+	// Base case: no more depth to resolve or already visited (circular reference)
+	if (currentDepth >= depth || visited.has(document.id)) {
+		return document;
+	}
+
+	// Mark as visited
+	visited.add(document.id);
+
+	// Clone the document to avoid mutations
+	const resolvedDocument = { ...document };
+
+	// Resolve references in draftData
+	if (document.draftData) {
+		resolvedDocument.draftData = await resolveDataReferences(
+			document.draftData,
+			adapter,
+			organizationId,
+			{
+				depth,
+				currentDepth: currentDepth + 1,
+				visited
+			}
+		);
+	}
+
+	// Resolve references in publishedData
+	if (document.publishedData) {
+		resolvedDocument.publishedData = await resolveDataReferences(
+			document.publishedData,
+			adapter,
+			organizationId,
+			{
+				depth,
+				currentDepth: currentDepth + 1,
+				visited
+			}
+		);
+	}
+
+	return resolvedDocument;
+}
+
+/**
+ * Resolves references within document data (recursive)
+ */
+async function resolveDataReferences(
+	data: any,
+	adapter: DocumentAdapter,
+	organizationId: string,
+	options: ResolveOptions
+): Promise<any> {
+	if (!data || typeof data !== 'object') {
+		return data;
+	}
+
+	// Handle arrays
+	if (Array.isArray(data)) {
+		return Promise.all(
+			data.map((item) => resolveDataReferences(item, adapter, organizationId, options))
+		);
+	}
+
+	// Clone object
+	const resolved: any = {};
+
+	for (const [key, value] of Object.entries(data)) {
+		// Check if this looks like a reference field (string ID)
+		if (typeof value === 'string' && key !== '_type' && key !== '_key') {
+			// Try to fetch the referenced document
+			try {
+				const referencedDoc = await adapter.findByDocId(organizationId, value);
+				if (referencedDoc) {
+					// Recursively resolve nested references
+					resolved[key] = await resolveReferences(referencedDoc, adapter, organizationId, options);
+				} else {
+					// Reference not found, keep the ID
+					resolved[key] = value;
+				}
+			} catch (error) {
+				// On error, keep the original value
+				resolved[key] = value;
+			}
+		} else if (value && typeof value === 'object') {
+			// Recursively resolve nested objects/arrays
+			resolved[key] = await resolveDataReferences(value, adapter, organizationId, options);
+		} else {
+			// Primitive value, keep as is
+			resolved[key] = value;
+		}
+	}
+
+	return resolved;
+}

package/src/lib/define.ts

@@ -0,0 +1,7 @@
+// CMS configuration helper
+import type { CMSConfig } from './types/index';
+
+// CMS config helper
+export function defineCMSConfig(config: CMSConfig): CMSConfig {
+	return config;
+}

package/{dist/email/index.js → src/lib/email/index.ts}

@@ -1,4 +1,5 @@
 // Aphex CMS Email Layer
 // Ports and adapters for email sending operations
+
 // Interfaces
-export * from './interfaces/email.js';
+export * from './interfaces/email';

package/src/lib/email/interfaces/email.ts

@@ -0,0 +1,45 @@
+export interface EmailAddress {
+	email: string;
+	name?: string;
+}
+
+export interface SendEmailOptions {
+	from: string;
+	to: string | string[];
+	subject: string;
+	html?: string;
+	text?: string;
+	cc?: string | string[];
+	bcc?: string | string[];
+	replyTo?: string;
+	tags?: Array<{ name: string; value: string }>;
+	attachments?: Array<{
+		filename: string;
+		content: Buffer | string;
+	}>;
+}
+
+export interface SendEmailResult {
+	id: string;
+	error?: string;
+}
+
+export interface EmailAdapter {
+	readonly name: string;
+
+	send(options: SendEmailOptions): Promise<SendEmailResult>;
+
+	sendBatch?(emails: SendEmailOptions[]): Promise<SendEmailResult[]>;
+}
+
+export interface EmailProvider {
+	name: string;
+	createAdapter(config: EmailConfig): EmailAdapter;
+}
+
+export interface EmailConfig {
+	apiKey?: string;
+	options?: {
+		[key: string]: any;
+	};
+}

package/src/lib/engine.ts

@@ -0,0 +1,85 @@
+import type { CMSConfig } from './types/config';
+import type { SchemaType } from './types/schemas';
+import type { DatabaseAdapter } from './db/interfaces/index';
+
+export class CMSEngine {
+	private db: DatabaseAdapter;
+	public config: CMSConfig;
+
+	constructor(config: CMSConfig, dbAdapter: DatabaseAdapter) {
+		this.config = config;
+		this.db = dbAdapter;
+	}
+
+	// Update config dynamically (for schema hot-reloading)
+	updateConfig(newConfig: CMSConfig): void {
+		this.config = newConfig;
+		console.log('🔄 CMS config updated:', {
+			schemaTypes: newConfig.schemaTypes.length,
+			documents: newConfig.schemaTypes.filter((t) => t.type === 'document').length,
+			objects: newConfig.schemaTypes.filter((t) => t.type === 'object').length
+		});
+	}
+
+	// Initialize CMS - register schema types in database
+	async initialize(): Promise<void> {
+		console.log('🚀 Initializing CMS...');
+
+		// Get existing schemas from database
+		const existingSchemas = await this.db.listSchemas();
+		const existingNames = new Set(existingSchemas.map((s) => s.name));
+		const currentNames = new Set(this.config.schemaTypes.map((s) => s.name));
+
+		// Delete schemas that are no longer in config
+		for (const existingName of existingNames) {
+			if (!currentNames.has(existingName)) {
+				await this.db.deleteSchemaType(existingName);
+			}
+		}
+
+		// Register all schema types (updates if exists, creates if new)
+		for (const schemaType of this.config.schemaTypes) {
+			await this.db.registerSchemaType(schemaType);
+		}
+
+		console.log('✅ CMS initialized successfully');
+	}
+
+	// Schema Type utility methods
+	async getSchemaType(name: string): Promise<SchemaType | null> {
+		return this.db.getSchemaType(name);
+	}
+
+	async listSchemas(): Promise<SchemaType[]> {
+		return this.db.listSchemas();
+	}
+
+	getSchemaTypeByName(name: string): SchemaType | null {
+		return this.config.schemaTypes.find((s) => s.name === name) || null;
+	}
+
+	async listDocumentTypes(): Promise<Array<{ name: string; title: string; description?: string }>> {
+		return this.db.listDocumentTypes();
+	}
+
+	async listObjectTypes(): Promise<Array<{ name: string; title: string; description?: string }>> {
+		return this.db.listObjectTypes();
+	}
+}
+
+// Global CMS instance
+let cmsInstance: CMSEngine | null = null;
+
+export function createCMS(config: CMSConfig, dbAdapter: DatabaseAdapter): CMSEngine {
+	if (!cmsInstance) {
+		cmsInstance = new CMSEngine(config, dbAdapter);
+	}
+	return cmsInstance;
+}
+
+export function getCMS(): CMSEngine {
+	if (!cmsInstance) {
+		throw new Error('CMS not initialized. Call createCMS() first.');
+	}
+	return cmsInstance;
+}