@magnet-cms/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,576 @@
+import * as _magnet_cms_common from '@magnet-cms/common';
+import { MagnetModuleOptions, AuthConfig, Model, AuthStrategy, AuthUser, LoginCredentials, AuthResult, RegisterData, StorageAdapter, LocalStorageConfig, UploadOptions, UploadResult, TransformOptions, StorageConfig, MediaQueryOptions, PaginatedMedia, PluginMetadata, PluginFrontendManifest, PluginConfig, EnrichedPluginManifest, RegisteredPluginInfo, PluginModuleOptions } from '@magnet-cms/common';
+import * as _nestjs_common from '@nestjs/common';
+import { DynamicModule, Type, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
+import * as passport_jwt from 'passport-jwt';
+import { Strategy } from 'passport-jwt';
+import { Readable } from 'node:stream';
+import { ModuleRef, ModulesContainer, DiscoveryService } from '@nestjs/core';
+
+declare class MagnetModule {
+    static forRoot(options?: MagnetModuleOptions): DynamicModule;
+    static forFeature(schemas: Type | Type[]): Promise<DynamicModule>;
+}
+
+/**
+ * Injection token for the auth strategy
+ */
+declare const AUTH_STRATEGY = "AUTH_STRATEGY";
+/**
+ * Injection token for auth configuration
+ */
+declare const AUTH_CONFIG = "AUTH_CONFIG";
+
+declare class AuthModule {
+    /**
+     * Register the auth module with configuration.
+     * Supports dynamic strategy registration via config.
+     *
+     * @param authConfig - Auth configuration (optional, uses JWT by default)
+     *
+     * @example
+     * ```typescript
+     * // Default JWT strategy
+     * AuthModule.forRoot()
+     *
+     * // Custom JWT config
+     * AuthModule.forRoot({
+     *   strategy: 'jwt',
+     *   jwt: { secret: 'my-secret', expiresIn: '24h' }
+     * })
+     *
+     * // Custom strategy (register before module init)
+     * AuthStrategyFactory.registerStrategy('custom', CustomAuthStrategy)
+     * AuthModule.forRoot({ strategy: 'custom' })
+     * ```
+     */
+    static forRoot(authConfig?: AuthConfig): DynamicModule;
+}
+
+declare class CreateUserDto {
+    email: string;
+    password: string;
+    name: string;
+    role?: string;
+}
+
+declare class User {
+    email: string;
+    password: string;
+    name: string;
+    role?: string;
+    hashPassword(): Promise<void>;
+}
+
+declare class UserService {
+    private readonly userModel;
+    constructor(userModel: Model<User>);
+    findAll(): Promise<_magnet_cms_common.BaseSchema<User>[]>;
+    findOne(query: Partial<User>): Promise<_magnet_cms_common.BaseSchema<User> | null>;
+    findOneById(id: string): Promise<_magnet_cms_common.BaseSchema<User> | null>;
+    create(userData: CreateUserDto): Promise<_magnet_cms_common.BaseSchema<User>>;
+    update(id: string, updateUserDto: Partial<CreateUserDto>): Promise<_magnet_cms_common.BaseSchema<User>>;
+    remove(id: string): Promise<boolean>;
+}
+
+type AuthStrategyConstructor = new (config: AuthConfig, userService: UserService) => AuthStrategy;
+/**
+ * Factory for creating auth strategy instances based on configuration.
+ * The JWT strategy is built-in, while other strategies can be registered
+ * dynamically or loaded from separate packages.
+ *
+ * @example
+ * ```typescript
+ * // Register a custom strategy before module initialization
+ * AuthStrategyFactory.registerStrategy('custom', CustomAuthStrategy)
+ *
+ * // Later, in MagnetModule.forRoot()
+ * MagnetModule.forRoot({
+ *   auth: { strategy: 'custom', customOption: 'value' }
+ * })
+ * ```
+ */
+declare class AuthStrategyFactory {
+    private static cachedStrategy;
+    private static cachedConfig;
+    private static customStrategies;
+    /**
+     * Register a custom auth strategy class.
+     * Call this before MagnetModule.forRoot() to register custom strategies.
+     *
+     * @param name - Unique name for the strategy (used in config.strategy)
+     * @param strategyClass - Class constructor implementing AuthStrategy
+     *
+     * @example
+     * ```typescript
+     * import { AuthStrategyFactory } from '@magnet-cms/core'
+     * import { SupabaseAuthStrategy } from './strategies/supabase-auth.strategy'
+     *
+     * AuthStrategyFactory.registerStrategy('supabase', SupabaseAuthStrategy)
+     * ```
+     */
+    static registerStrategy(name: string, strategyClass: AuthStrategyConstructor): void;
+    /**
+     * Get or create an auth strategy based on configuration.
+     * This is called internally by AuthModule.forRoot().
+     *
+     * @param config - Auth configuration
+     * @param userService - UserService for database operations
+     * @param jwtSecret - JWT secret (fallback from jwt.secret)
+     */
+    static getStrategy(config: AuthConfig | undefined, userService: UserService, jwtSecret: string): AuthStrategy;
+    /**
+     * Clear the cached strategy (useful for testing)
+     */
+    static clearCache(): void;
+    /**
+     * Clear all registered custom strategies (useful for testing)
+     */
+    static clearStrategies(): void;
+    /**
+     * Check if a strategy is registered
+     */
+    static hasStrategy(name: string): boolean;
+    /**
+     * Check if the provided config matches the cached config
+     */
+    private static configMatches;
+}
+
+declare const JwtAuthStrategy_base: new (...args: [opt: passport_jwt.StrategyOptionsWithRequest] | [opt: passport_jwt.StrategyOptionsWithoutRequest]) => Strategy & {
+    validate(...args: any[]): unknown;
+};
+/**
+ * JWT-based authentication strategy.
+ * This is the default strategy that maintains backward compatibility.
+ *
+ * Extends PassportStrategy for integration with NestJS guards,
+ * and implements AuthStrategy for the extensible auth system.
+ */
+declare class JwtAuthStrategy extends JwtAuthStrategy_base implements AuthStrategy {
+    private readonly userService;
+    readonly name = "jwt";
+    private readonly secret;
+    private readonly expiresIn;
+    constructor(config: AuthConfig, userService: UserService);
+    /**
+     * Passport validate method - called by JwtAuthGuard after JWT is verified.
+     * Also satisfies the AuthStrategy.validate() interface.
+     */
+    validate(payload: {
+        sub: string;
+        email: string;
+        role: string;
+    } | unknown): Promise<AuthUser | null>;
+    /**
+     * Validate user credentials against the database
+     */
+    validateCredentials(email: string, password: string): Promise<AuthUser | null>;
+    /**
+     * Authenticate and return JWT token
+     */
+    login(credentials: LoginCredentials): Promise<AuthResult>;
+    /**
+     * Register a new user and return the user object
+     */
+    register(data: RegisterData): Promise<AuthUser>;
+    getPassportStrategyName(): string;
+}
+
+/**
+ * Media schema for storing file metadata.
+ * This entity has a custom UI (Media Library) and doesn't use the standard content manager.
+ */
+declare class Media {
+    filename: string;
+    originalFilename: string;
+    mimeType: string;
+    size: number;
+    path: string;
+    url: string;
+    folder?: string;
+    tags?: string[];
+    alt?: string;
+    width?: number;
+    height?: number;
+    customFields?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+    createdBy?: string;
+}
+
+declare class LocalStorageAdapter implements StorageAdapter {
+    private readonly logger;
+    private readonly config;
+    private readonly cacheDir;
+    private sharp;
+    constructor(config: LocalStorageConfig);
+    initialize(): Promise<void>;
+    upload(file: Buffer | Readable, originalFilename: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadChunked(stream: Readable, originalFilename: string, totalSize: number, options?: UploadOptions): Promise<UploadResult>;
+    delete(storagePath: string): Promise<boolean>;
+    deleteMany(paths: string[]): Promise<{
+        deleted: number;
+        failed: string[];
+    }>;
+    getUrl(storagePath: string, transform?: TransformOptions): string;
+    getStream(storagePath: string): Promise<Readable>;
+    getBuffer(storagePath: string): Promise<Buffer>;
+    exists(storagePath: string): Promise<boolean>;
+    transform(storagePath: string, options: TransformOptions): Promise<Buffer>;
+    /**
+     * Get the MIME type for a transformed image
+     */
+    getTransformMimeType(originalMimeType: string, transform?: TransformOptions): string;
+    private streamToBuffer;
+    private getMimeType;
+    private isImage;
+    private getCacheKey;
+    private deleteCachedTransforms;
+    private ensureFileExists;
+    private formatSize;
+}
+
+/**
+ * Factory for creating storage adapters based on configuration.
+ * The local adapter is built-in, while S3/R2 adapters are loaded dynamically
+ * from separate packages.
+ */
+declare class StorageAdapterFactory {
+    private static cachedAdapter;
+    private static cachedConfig;
+    /**
+     * Get or create a storage adapter based on configuration.
+     * @param config - Storage configuration (optional, will use defaults if not provided)
+     */
+    static getAdapter(config?: StorageConfig): StorageAdapter;
+    /**
+     * Clear the cached adapter (useful for testing)
+     */
+    static clearCache(): void;
+    /**
+     * Detect the storage adapter to use based on environment variables
+     */
+    private static detectStorageAdapter;
+    /**
+     * Check if the provided config matches the cached config
+     */
+    private static configMatches;
+}
+
+declare class StorageService implements OnModuleInit {
+    private readonly adapter;
+    private readonly moduleRef;
+    private readonly logger;
+    private mediaModel;
+    constructor(adapter: StorageAdapter, moduleRef: ModuleRef);
+    onModuleInit(): Promise<void>;
+    /**
+     * Get the Media model lazily
+     */
+    private getMediaModel;
+    /**
+     * Upload a file and store its metadata
+     */
+    upload(file: Buffer | Readable, originalFilename: string, options?: UploadOptions & {
+        createdBy?: string;
+    }): Promise<Media>;
+    /**
+     * Upload multiple files
+     */
+    uploadMany(files: Array<{
+        file: Buffer | Readable;
+        originalFilename: string;
+    }>, options?: UploadOptions & {
+        createdBy?: string;
+    }): Promise<Media[]>;
+    /**
+     * Upload a large file using chunked/streaming upload
+     */
+    uploadChunked(stream: Readable, originalFilename: string, totalSize: number, options?: UploadOptions & {
+        createdBy?: string;
+    }): Promise<Media>;
+    /**
+     * Delete a media file and its metadata
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Delete multiple media files
+     */
+    deleteMany(ids: string[]): Promise<{
+        deleted: number;
+        failed: string[];
+    }>;
+    /**
+     * Find media by ID
+     */
+    findById(id: string): Promise<Media | null>;
+    /**
+     * Find media by filename
+     */
+    findByFilename(filename: string): Promise<Media | null>;
+    /**
+     * Find media by path
+     */
+    findByPath(path: string): Promise<Media | null>;
+    /**
+     * List media with pagination and filtering
+     */
+    list(options?: MediaQueryOptions): Promise<PaginatedMedia<Media>>;
+    /**
+     * Update media metadata
+     */
+    update(id: string, data: Partial<Pick<Media, 'alt' | 'tags' | 'folder' | 'customFields'>>): Promise<Media | null>;
+    /**
+     * Get the public URL for a media file
+     */
+    getUrl(media: Media, transform?: TransformOptions): string;
+    /**
+     * Get a readable stream for a media file
+     */
+    getStream(id: string): Promise<Readable>;
+    /**
+     * Get a media file as a buffer
+     */
+    getBuffer(id: string): Promise<Buffer>;
+    /**
+     * Get a transformed version of an image
+     */
+    transform(id: string, options: TransformOptions): Promise<Buffer>;
+    /**
+     * Check if a media file exists
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Get all unique folders
+     */
+    getFolders(): Promise<string[]>;
+    /**
+     * Get all unique tags
+     */
+    getTags(): Promise<string[]>;
+    /**
+     * Get storage statistics
+     */
+    getStats(): Promise<{
+        totalFiles: number;
+        totalSize: number;
+        byMimeType: Record<string, {
+            count: number;
+            size: number;
+        }>;
+    }>;
+}
+
+/**
+ * Injection token for the storage adapter
+ */
+declare const STORAGE_ADAPTER = "STORAGE_ADAPTER";
+/**
+ * Injection token for storage configuration
+ */
+declare const STORAGE_CONFIG = "STORAGE_CONFIG";
+
+declare class StorageModule {
+    /**
+     * Register the storage module with configuration
+     * @param config - Storage configuration (optional, uses defaults if not provided)
+     */
+    static forRoot(config?: StorageConfig): DynamicModule;
+}
+
+declare const PLUGIN_METADATA = "plugin:metadata";
+declare const PLUGIN_FRONTEND_MANIFEST = "plugin:frontend:manifest";
+declare const PLUGIN_MODULE = "plugin:module";
+/**
+ * Generate standardized options token for a plugin.
+ *
+ * @param pluginName - The plugin name (e.g., 'content-builder')
+ * @returns Token string (e.g., 'PLUGIN_CONTENT_BUILDER_OPTIONS')
+ *
+ * @example
+ * ```ts
+ * getPluginOptionsToken('content-builder') // 'PLUGIN_CONTENT_BUILDER_OPTIONS'
+ * ```
+ */
+declare function getPluginOptionsToken(pluginName: string): string;
+
+declare function Hook(hookName: string): MethodDecorator;
+
+/**
+ * Decorator to inject plugin options using standardized token.
+ *
+ * @param pluginName - The plugin name (e.g., 'content-builder')
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class MyService {
+ *   constructor(
+ *     @InjectPluginOptions('content-builder')
+ *     private readonly options: ContentBuilderOptions
+ *   ) {}
+ * }
+ * ```
+ */
+declare function InjectPluginOptions(pluginName: string): ParameterDecorator;
+
+interface PluginDecoratorOptions extends Omit<PluginMetadata, 'module'> {
+    /** Frontend manifest for this plugin */
+    frontend?: Omit<PluginFrontendManifest, 'pluginName'>;
+    /** NestJS module containing controllers/services (auto-imported) */
+    module?: Type<unknown>;
+}
+/**
+ * Decorator to mark a class as a Magnet plugin
+ *
+ * @example
+ * ```ts
+ * @Plugin({
+ *   name: 'content-builder',
+ *   description: 'Visual schema builder',
+ *   version: '1.0.0',
+ *   frontend: {
+ *     routes: [{ path: 'playground', componentId: 'PlaygroundIndex' }],
+ *     sidebar: [{ id: 'playground', title: 'Playground', url: '/playground', icon: 'Boxes' }]
+ *   }
+ * })
+ * export class ContentBuilderPlugin {}
+ * ```
+ */
+declare function Plugin(options: PluginDecoratorOptions): ClassDecorator;
+
+interface RegisteredPlugin {
+    metadata: PluginMetadata;
+    instance: unknown;
+    frontendManifest?: PluginFrontendManifest;
+    config: PluginConfig;
+}
+declare class PluginRegistryService implements OnModuleInit {
+    private readonly modulesContainer;
+    private readonly pluginsConfig;
+    private plugins;
+    constructor(modulesContainer: ModulesContainer, pluginsConfig?: PluginConfig[]);
+    onModuleInit(): void;
+    private discoverPlugins;
+    /**
+     * Get a registered plugin by name
+     */
+    getPlugin(name: string): RegisteredPlugin | undefined;
+    /**
+     * Get all registered plugins
+     */
+    getAllPlugins(): RegisteredPlugin[];
+    /**
+     * Get metadata for all plugins
+     */
+    getPluginMetadata(): PluginMetadata[];
+    /**
+     * Get frontend manifests for all plugins with bundle URLs
+     * Used by admin UI to dynamically load plugin frontends at runtime
+     */
+    getFrontendManifests(): EnrichedPluginManifest[];
+    /**
+     * Get full plugin info for API response
+     */
+    getPluginInfo(name: string): RegisteredPluginInfo | null;
+    /**
+     * Get all plugins info for API response
+     */
+    getAllPluginsInfo(): RegisteredPluginInfo[];
+}
+
+declare class PluginController {
+    private readonly registry;
+    constructor(registry: PluginRegistryService);
+    /**
+     * Get all registered plugins
+     * GET /plugins
+     */
+    getPlugins(): _magnet_cms_common.RegisteredPluginInfo[];
+    /**
+     * Get all frontend manifests for registered plugins
+     * Used by admin UI to discover plugin routes and sidebar items
+     * GET /plugins/manifests
+     */
+    getFrontendManifests(): _magnet_cms_common.EnrichedPluginManifest[];
+    /**
+     * Get plugin details by name
+     * GET /plugins/:name
+     */
+    getPlugin(name: string): _magnet_cms_common.RegisteredPluginInfo | {
+        error: string;
+    };
+}
+
+/**
+ * @deprecated Use PluginModuleOptions instead
+ */
+interface PluginOptions$1 {
+    plugins: Type[];
+}
+declare class PluginModule {
+    /**
+     * Configure the plugin module with plugin configurations
+     *
+     * @example
+     * ```ts
+     * PluginModule.forRoot({
+     *   plugins: [
+     *     { plugin: ContentBuilderPlugin, options: { modulesPath: './src/modules' } },
+     *     { plugin: SeoPlugin, enabled: true }
+     *   ]
+     * })
+     * ```
+     */
+    static forRoot(options?: PluginModuleOptions): DynamicModule;
+    /**
+     * @deprecated Use forRoot with PluginConfig[] instead
+     */
+    static forRootLegacy(options?: PluginOptions$1): DynamicModule;
+    /**
+     * Collect NestJS modules from plugins that define them
+     */
+    private static collectPluginModules;
+    private static createPluginProviders;
+}
+
+/**
+ * Service that manages plugin lifecycle hooks.
+ * Calls onPluginInit() after module initialization and onPluginDestroy() on shutdown.
+ */
+declare class PluginLifecycleService implements OnModuleInit, OnApplicationShutdown {
+    private readonly modulesContainer;
+    private readonly pluginsConfig;
+    private readonly logger;
+    private pluginInstances;
+    constructor(modulesContainer: ModulesContainer, pluginsConfig?: PluginConfig[]);
+    onModuleInit(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+}
+
+/**
+ * @deprecated Use PluginModuleOptions instead
+ */
+interface PluginOptions {
+    plugins: Type[];
+}
+declare class PluginService implements OnModuleInit {
+    private readonly discovery;
+    private readonly modulesContainer;
+    private readonly options;
+    private plugins;
+    private hooks;
+    constructor(discovery: DiscoveryService, modulesContainer: ModulesContainer, options: PluginOptions);
+    onModuleInit(): void;
+    private discoverPlugins;
+    private discoverHooks;
+    getPlugin(name: string): any;
+    getAllPlugins(): Map<string, any>;
+    executeHook(hookName: string, ...args: any[]): Promise<any[]>;
+}
+
+declare const IS_RESTRICTED_ROUTE = "IS_RESTRICTED_ROUTE";
+declare function RestrictedRoute(): _nestjs_common.CustomDecorator<string>;
+
+export { AUTH_CONFIG, AUTH_STRATEGY, AuthModule, AuthStrategyFactory, Hook, IS_RESTRICTED_ROUTE, InjectPluginOptions, JwtAuthStrategy, LocalStorageAdapter, MagnetModule, Media, PLUGIN_FRONTEND_MANIFEST, PLUGIN_METADATA, PLUGIN_MODULE, Plugin, PluginController, type PluginDecoratorOptions, PluginLifecycleService, PluginModule, PluginRegistryService, PluginService, RestrictedRoute, STORAGE_ADAPTER, STORAGE_CONFIG, StorageAdapterFactory, StorageModule, StorageService, getPluginOptionsToken };