@memberjunction/server-extensions-core 0.0.1 → 5.17.0

package/README.md

@@ -1,45 +1,175 @@
 # @memberjunction/server-extensions-core
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Plugin architecture for MJServer that enables auto-discovery and lifecycle management of extension modules. Extensions register Express routes, handle their own authentication, and participate in health checks and graceful shutdown — all without modifying MJServer source code.
+
+## Overview
+
+This package provides two main exports:
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+- **`BaseServerExtension`** — Abstract base class that all extensions implement. Defines the `Initialize`, `Shutdown`, and `HealthCheck` lifecycle methods.
+- **`ServerExtensionLoader`** — Discovers registered extension classes via MJ's `ClassFactory`, matches them to config entries, and manages their lifecycle.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+Extensions are discovered automatically using MemberJunction's standard `@RegisterClass` + `ClassFactory` pattern. You register your extension class, add an entry to `mj.config.cjs`, and MJServer loads it at startup — zero source code changes to MJServer required per new extension.
 
-## Purpose
+## Installation
+
+```bash
+npm install @memberjunction/server-extensions-core
+```
+
+## Quick Start
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/server-extensions-core`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+### 1. Create an Extension
+
+```typescript
+import { Application } from 'express';
+import { RegisterClass } from '@memberjunction/global';
+import {
+    BaseServerExtension,
+    ServerExtensionConfig,
+    ExtensionInitResult,
+    ExtensionHealthResult
+} from '@memberjunction/server-extensions-core';
+
+@RegisterClass(BaseServerExtension, 'MyCustomExtension')
+export class MyCustomExtension extends BaseServerExtension {
+    async Initialize(app: Application, config: ServerExtensionConfig): Promise<ExtensionInitResult> {
+        // Register your Express routes
+        app.get(config.RootPath + '/hello', (_req, res) => {
+            res.json({ message: 'Hello from my extension!' });
+        });
+
+        return {
+            Success: true,
+            Message: 'Custom extension loaded',
+            RegisteredRoutes: [`GET ${config.RootPath}/hello`]
+        };
+    }
+
+    async Shutdown(): Promise<void> {
+        // Clean up connections, drain requests, release resources
+    }
+
+    async HealthCheck(): Promise<ExtensionHealthResult> {
+        return { Healthy: true, Name: 'MyCustomExtension' };
+    }
+}
+```
+
+### 2. Configure in `mj.config.cjs`
+
+```javascript
+module.exports = {
+    // ... other MJServer config ...
+    serverExtensions: [
+        {
+            Enabled: true,
+            DriverClass: 'MyCustomExtension',
+            RootPath: '/api/my-extension',
+            Settings: {
+                apiKey: process.env.MY_EXTENSION_API_KEY,
+                // Any extension-specific settings
+            }
+        }
+    ]
+};
+```
 
-## What is OIDC Trusted Publishing?
+### 3. Import Your Extension Package
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+Ensure your extension package is imported in your application so the `@RegisterClass` decorator fires at module load time. Add it as a dependency in your MJAPI project.
 
-## Setup Instructions
+## API Reference
 
-To properly configure OIDC trusted publishing for this package:
+### `BaseServerExtension`
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+Abstract base class for all server extensions.
 
-## DO NOT USE THIS PACKAGE
+| Method | Description |
+|--------|-------------|
+| `Initialize(app, config)` | Called once at MJServer startup. Register routes, open connections. |
+| `Shutdown()` | Called during graceful shutdown (SIGTERM/SIGINT). Clean up resources. |
+| `HealthCheck()` | Called periodically. Return health status quickly (< 100ms). |
+| `OnConfigurationChange?(config)` | Optional. Called when config changes at runtime. |
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+### `ServerExtensionLoader`
 
-## More Information
+Manages the extension lifecycle.
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+| Method | Description |
+|--------|-------------|
+| `LoadExtensions(app, configs)` | Discover and initialize all enabled extensions from config. |
+| `HealthCheckAll()` | Run health checks on all loaded extensions. |
+| `ShutdownAll()` | Shut down all extensions in reverse order (LIFO). |
+| `Extensions` | Read-only array of loaded extension instances. |
+| `ExtensionCount` | Number of currently loaded extensions. |
 
----
+### Type Interfaces
+
+#### `ServerExtensionConfig`
+
+```typescript
+interface ServerExtensionConfig {
+    Enabled: boolean;        // Skip loading if false
+    DriverClass: string;     // Must match @RegisterClass key
+    RootPath: string;        // URL prefix for extension routes
+    Settings: Record<string, unknown>;  // Extension-specific config
+}
+```
+
+#### `ExtensionInitResult`
+
+```typescript
+interface ExtensionInitResult {
+    Success: boolean;
+    Message: string;
+    RegisteredRoutes?: string[];
+}
+```
+
+#### `ExtensionHealthResult`
+
+```typescript
+interface ExtensionHealthResult {
+    Healthy: boolean;
+    Name: string;
+    Details?: Record<string, unknown>;
+}
+```
+
+## Lifecycle
 
-**Maintained for OIDC setup purposes only**
+1. MJServer reads `serverExtensions[]` from `mj.config.cjs`
+2. For each enabled entry, `ServerExtensionLoader` uses `ClassFactory.CreateInstance(BaseServerExtension, driverClass)` to find the registered class
+3. Creates an instance and calls `Initialize(app, config)`
+4. Extension registers its Express routes under `config.RootPath`
+5. MJServer exposes `GET /health/extensions` for aggregate health checks
+6. On SIGTERM/SIGINT, `ShutdownAll()` calls each extension's `Shutdown()` in reverse order
+
+## Error Handling
+
+- Extensions that fail to initialize are logged and skipped — they don't prevent other extensions from loading
+- Health check exceptions are caught and reported as unhealthy
+- Shutdown exceptions are logged but don't prevent other extensions from shutting down
+
+## Authentication
+
+Extensions handle their own authentication by default. Common patterns:
+
+- **Platform-specific auth** (Slack HMAC signatures, Teams Bot Framework JWT)
+- **MJServer auth middleware** — import from `@memberjunction/server` if you want to reuse MJServer's built-in auth
+- **Custom auth** — API keys, OAuth, etc.
+
+This is opt-in — extensions are not forced to use MJServer's auth middleware.
+
+## Testing
+
+```bash
+npm run test        # Run all tests
+npm run test:watch  # Watch mode
+```
+
+## Related Packages
+
+- [`@memberjunction/messaging-adapters`](../MessagingAdapters/) — Slack and Teams adapters built on this framework
+- [`@memberjunction/server`](../MJServer/) — MJServer that loads and manages extensions

package/dist/BaseServerExtension.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @module @memberjunction/server-extensions-core
+ * @description Abstract base class for MJServer extensions.
+ */
+import { Application } from 'express';
+import { ServerExtensionConfig, ExtensionInitResult, ExtensionHealthResult } from './types.js';
+/**
+ * Abstract base class for MJServer extensions.
+ *
+ * Extensions are discovered via `@RegisterClass(BaseServerExtension, 'DriverClassName')`
+ * and matched to config entries in `mj.config.cjs` by their `DriverClass` name.
+ *
+ * MJServer calls `Initialize()` during startup, passing the Express app so the
+ * extension can register its own routes, middleware, and lifecycle hooks.
+ *
+ * ## Lifecycle
+ *
+ * 1. MJServer reads `serverExtensions[]` from `mj.config.cjs`
+ * 2. For each enabled entry, looks up `@RegisterClass(BaseServerExtension, driverClass)`
+ * 3. Creates instance via `ClassFactory.CreateInstance()`
+ * 4. Calls `Initialize(app, config)` — extension registers routes
+ * 5. Periodic `HealthCheck()` calls for monitoring
+ * 6. On server shutdown, calls `Shutdown()` for cleanup
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { RegisterClass } from '@memberjunction/global';
+ * import { BaseServerExtension, ServerExtensionConfig, ExtensionInitResult } from '@memberjunction/server-extensions-core';
+ *
+ * @RegisterClass(BaseServerExtension, 'MyCustomExtension')
+ * export class MyCustomExtension extends BaseServerExtension {
+ *     async Initialize(app: Application, config: ServerExtensionConfig): Promise<ExtensionInitResult> {
+ *         app.get(config.RootPath + '/hello', (_req, res) => {
+ *             res.json({ message: 'Hello from my extension!' });
+ *         });
+ *         return { Success: true, Message: 'Custom extension loaded', RegisteredRoutes: [`GET ${config.RootPath}/hello`] };
+ *     }
+ *
+ *     async Shutdown(): Promise<void> {
+ *         // Clean up resources
+ *     }
+ *
+ *     async HealthCheck(): Promise<ExtensionHealthResult> {
+ *         return { Healthy: true, Name: 'MyCustomExtension' };
+ *     }
+ * }
+ * ```
+ *
+ * ## Auth Middleware
+ *
+ * Extensions handle their own authentication by default. If you want to leverage
+ * MJServer's built-in auth middleware, import it from `@memberjunction/server`:
+ *
+ * ```typescript
+ * import { getSystemUser, verifyUserRecord } from '@memberjunction/server';
+ * ```
+ *
+ * This is opt-in — extensions like Slack/Teams use platform-specific auth
+ * (signature verification, Bot Framework JWT) instead.
+ */
+export declare abstract class BaseServerExtension {
+    /**
+     * Initialize the extension. Called once during MJServer startup.
+     *
+     * Use this to register Express routes, set up WebSocket handlers,
+     * initialize connections, and prepare the extension for operation.
+     *
+     * @param app - The Express application instance to register routes on.
+     *              Routes should be registered under `config.RootPath`.
+     * @param config - Extension-specific configuration from `mj.config.cjs`.
+     *                 The `Settings` object contains extension-specific config.
+     * @returns A result indicating whether initialization succeeded.
+     *          On failure, the extension is skipped but other extensions still load.
+     */
+    abstract Initialize(app: Application, config: ServerExtensionConfig): Promise<ExtensionInitResult>;
+    /**
+     * Graceful shutdown. Called when MJServer is shutting down (SIGTERM/SIGINT).
+     *
+     * Clean up connections, drain in-flight requests, close WebSocket connections,
+     * and release any resources held by the extension.
+     *
+     * This method should complete within a reasonable timeout (< 5 seconds).
+     * MJServer enforces a 10-second forced shutdown if graceful shutdown hangs.
+     */
+    abstract Shutdown(): Promise<void>;
+    /**
+     * Health check for this extension.
+     *
+     * Called by MJServer's aggregate `/health/extensions` endpoint.
+     * Should be fast (< 100ms) and non-blocking.
+     *
+     * @returns Health status including whether the extension is operational.
+     */
+    abstract HealthCheck(): Promise<ExtensionHealthResult>;
+    /**
+     * Optional: Called when configuration changes at runtime.
+     *
+     * Not all extensions need to support hot-reloading of configuration.
+     * Override this method if your extension can dynamically adjust its
+     * behavior without a full restart.
+     *
+     * @param newConfig - The updated configuration from `mj.config.cjs`.
+     */
+    OnConfigurationChange?(newConfig: ServerExtensionConfig): Promise<void>;
+}
+//# sourceMappingURL=BaseServerExtension.d.ts.map

package/dist/BaseServerExtension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseServerExtension.d.ts","sourceRoot":"","sources":["../src/BaseServerExtension.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,8BAAsB,mBAAmB;IACrC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAElG;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAElC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAEtD;;;;;;;;OAQG;IACH,qBAAqB,CAAC,CAAC,SAAS,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;CAC1E"}

package/dist/BaseServerExtension.js

@@ -0,0 +1,62 @@
+/**
+ * @module @memberjunction/server-extensions-core
+ * @description Abstract base class for MJServer extensions.
+ */
+/**
+ * Abstract base class for MJServer extensions.
+ *
+ * Extensions are discovered via `@RegisterClass(BaseServerExtension, 'DriverClassName')`
+ * and matched to config entries in `mj.config.cjs` by their `DriverClass` name.
+ *
+ * MJServer calls `Initialize()` during startup, passing the Express app so the
+ * extension can register its own routes, middleware, and lifecycle hooks.
+ *
+ * ## Lifecycle
+ *
+ * 1. MJServer reads `serverExtensions[]` from `mj.config.cjs`
+ * 2. For each enabled entry, looks up `@RegisterClass(BaseServerExtension, driverClass)`
+ * 3. Creates instance via `ClassFactory.CreateInstance()`
+ * 4. Calls `Initialize(app, config)` — extension registers routes
+ * 5. Periodic `HealthCheck()` calls for monitoring
+ * 6. On server shutdown, calls `Shutdown()` for cleanup
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { RegisterClass } from '@memberjunction/global';
+ * import { BaseServerExtension, ServerExtensionConfig, ExtensionInitResult } from '@memberjunction/server-extensions-core';
+ *
+ * @RegisterClass(BaseServerExtension, 'MyCustomExtension')
+ * export class MyCustomExtension extends BaseServerExtension {
+ *     async Initialize(app: Application, config: ServerExtensionConfig): Promise<ExtensionInitResult> {
+ *         app.get(config.RootPath + '/hello', (_req, res) => {
+ *             res.json({ message: 'Hello from my extension!' });
+ *         });
+ *         return { Success: true, Message: 'Custom extension loaded', RegisteredRoutes: [`GET ${config.RootPath}/hello`] };
+ *     }
+ *
+ *     async Shutdown(): Promise<void> {
+ *         // Clean up resources
+ *     }
+ *
+ *     async HealthCheck(): Promise<ExtensionHealthResult> {
+ *         return { Healthy: true, Name: 'MyCustomExtension' };
+ *     }
+ * }
+ * ```
+ *
+ * ## Auth Middleware
+ *
+ * Extensions handle their own authentication by default. If you want to leverage
+ * MJServer's built-in auth middleware, import it from `@memberjunction/server`:
+ *
+ * ```typescript
+ * import { getSystemUser, verifyUserRecord } from '@memberjunction/server';
+ * ```
+ *
+ * This is opt-in — extensions like Slack/Teams use platform-specific auth
+ * (signature verification, Bot Framework JWT) instead.
+ */
+export class BaseServerExtension {
+}
+//# sourceMappingURL=BaseServerExtension.js.map

package/dist/BaseServerExtension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseServerExtension.js","sourceRoot":"","sources":["../src/BaseServerExtension.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,OAAgB,mBAAmB;CA+CxC"}

package/dist/ServerExtensionLoader.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @module @memberjunction/server-extensions-core
+ * @description Discovers, initializes, and manages server extensions.
+ */
+import { Application } from 'express';
+import { BaseServerExtension } from './BaseServerExtension.js';
+import { ServerExtensionConfig, ExtensionHealthResult } from './types.js';
+/**
+ * Discovers, initializes, and manages the lifecycle of server extensions.
+ *
+ * Called by MJServer's `serve()` function during startup. The loader reads the
+ * `serverExtensions` array from `mj.config.cjs`, uses MJ's `ClassFactory` to
+ * find registered extension classes, and calls `Initialize()` on each.
+ *
+ * ## Discovery Flow
+ *
+ * 1. Reads `serverExtensions[]` array from `mj.config.cjs`
+ * 2. For each enabled entry, uses `ClassFactory.CreateInstance(BaseServerExtension, driverClass)`
+ * 3. Creates an instance and calls `Initialize(app, config)`
+ * 4. Tracks all loaded extensions for health checks and shutdown
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { ServerExtensionLoader } from '@memberjunction/server-extensions-core';
+ *
+ * const loader = new ServerExtensionLoader();
+ * await loader.LoadExtensions(app, configInfo.serverExtensions);
+ *
+ * // Health check
+ * const health = await loader.HealthCheckAll();
+ *
+ * // Graceful shutdown
+ * await loader.ShutdownAll();
+ * ```
+ */
+export declare class ServerExtensionLoader {
+    private _loadedExtensions;
+    /**
+     * Load and initialize all enabled extensions from config.
+     *
+     * Extensions that fail to initialize are logged and skipped — they do not
+     * prevent other extensions from loading. This ensures one broken extension
+     * doesn't take down the entire server.
+     *
+     * @param app - Express application for route registration.
+     * @param extensionConfigs - Array of extension configs from `mj.config.cjs`.
+     */
+    LoadExtensions(app: Application, extensionConfigs: ServerExtensionConfig[]): Promise<void>;
+    /**
+     * Run health checks on all loaded extensions.
+     *
+     * Each extension's `HealthCheck()` is called independently. If one extension's
+     * health check throws, it is reported as unhealthy without affecting others.
+     *
+     * @returns Array of health results, one per loaded extension.
+     */
+    HealthCheckAll(): Promise<ExtensionHealthResult[]>;
+    /**
+     * Shut down all loaded extensions gracefully.
+     *
+     * Called during MJServer's shutdown sequence (SIGTERM/SIGINT).
+     * Extensions are shut down in reverse order of loading.
+     * Errors during shutdown are logged but do not prevent other extensions from shutting down.
+     */
+    ShutdownAll(): Promise<void>;
+    /**
+     * Get all loaded extension instances for inspection or testing.
+     *
+     * @returns Read-only array of loaded extensions with their driver class names.
+     */
+    get Extensions(): ReadonlyArray<{
+        Instance: BaseServerExtension;
+        DriverClass: string;
+    }>;
+    /**
+     * Get the number of currently loaded extensions.
+     */
+    get ExtensionCount(): number;
+    /**
+     * Load and initialize a single extension from config.
+     *
+     * Uses MJ's `ClassFactory` to look up the registered class by `DriverClass` name,
+     * creates an instance, and calls `Initialize()`. On failure, logs the error and
+     * continues without throwing.
+     */
+    private loadSingleExtension;
+}
+//# sourceMappingURL=ServerExtensionLoader.d.ts.map

package/dist/ServerExtensionLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerExtensionLoader.d.ts","sourceRoot":"","sources":["../src/ServerExtensionLoader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EACH,qBAAqB,EACrB,qBAAqB,EACxB,MAAM,YAAY,CAAC;AAgBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,qBAAqB;IAC9B,OAAO,CAAC,iBAAiB,CAAyB;IAElD;;;;;;;;;OASG;IACU,cAAc,CACvB,GAAG,EAAE,WAAW,EAChB,gBAAgB,EAAE,qBAAqB,EAAE,GAC1C,OAAO,CAAC,IAAI,CAAC;IAkBhB;;;;;;;OAOG;IACU,cAAc,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAmB/D;;;;;;OAMG;IACU,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAczC;;;;OAIG;IACH,IAAW,UAAU,IAAI,aAAa,CAAC;QAAE,QAAQ,EAAE,mBAAmB,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAE7F;IAED;;OAEG;IACH,IAAW,cAAc,IAAI,MAAM,CAElC;IAED;;;;;;OAMG;YACW,mBAAmB;CA0CpC"}

package/dist/ServerExtensionLoader.js

@@ -0,0 +1,164 @@
+/**
+ * @module @memberjunction/server-extensions-core
+ * @description Discovers, initializes, and manages server extensions.
+ */
+import { MJGlobal } from '@memberjunction/global';
+import { LogError, LogStatus } from '@memberjunction/core';
+import { BaseServerExtension } from './BaseServerExtension.js';
+/**
+ * Discovers, initializes, and manages the lifecycle of server extensions.
+ *
+ * Called by MJServer's `serve()` function during startup. The loader reads the
+ * `serverExtensions` array from `mj.config.cjs`, uses MJ's `ClassFactory` to
+ * find registered extension classes, and calls `Initialize()` on each.
+ *
+ * ## Discovery Flow
+ *
+ * 1. Reads `serverExtensions[]` array from `mj.config.cjs`
+ * 2. For each enabled entry, uses `ClassFactory.CreateInstance(BaseServerExtension, driverClass)`
+ * 3. Creates an instance and calls `Initialize(app, config)`
+ * 4. Tracks all loaded extensions for health checks and shutdown
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { ServerExtensionLoader } from '@memberjunction/server-extensions-core';
+ *
+ * const loader = new ServerExtensionLoader();
+ * await loader.LoadExtensions(app, configInfo.serverExtensions);
+ *
+ * // Health check
+ * const health = await loader.HealthCheckAll();
+ *
+ * // Graceful shutdown
+ * await loader.ShutdownAll();
+ * ```
+ */
+export class ServerExtensionLoader {
+    constructor() {
+        this._loadedExtensions = [];
+    }
+    /**
+     * Load and initialize all enabled extensions from config.
+     *
+     * Extensions that fail to initialize are logged and skipped — they do not
+     * prevent other extensions from loading. This ensures one broken extension
+     * doesn't take down the entire server.
+     *
+     * @param app - Express application for route registration.
+     * @param extensionConfigs - Array of extension configs from `mj.config.cjs`.
+     */
+    async LoadExtensions(app, extensionConfigs) {
+        if (!extensionConfigs || extensionConfigs.length === 0) {
+            LogStatus('No server extensions configured');
+            return;
+        }
+        for (const config of extensionConfigs) {
+            if (!config.Enabled) {
+                LogStatus(`Server extension '${config.DriverClass}' is disabled, skipping`);
+                continue;
+            }
+            await this.loadSingleExtension(app, config);
+        }
+        LogStatus(`Loaded ${this._loadedExtensions.length} server extension(s)`);
+    }
+    /**
+     * Run health checks on all loaded extensions.
+     *
+     * Each extension's `HealthCheck()` is called independently. If one extension's
+     * health check throws, it is reported as unhealthy without affecting others.
+     *
+     * @returns Array of health results, one per loaded extension.
+     */
+    async HealthCheckAll() {
+        const results = [];
+        for (const ext of this._loadedExtensions) {
+            try {
+                const health = await ext.Instance.HealthCheck();
+                results.push(health);
+            }
+            catch (error) {
+                results.push({
+                    Healthy: false,
+                    Name: ext.DriverClass,
+                    Details: { error: error instanceof Error ? error.message : String(error) }
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Shut down all loaded extensions gracefully.
+     *
+     * Called during MJServer's shutdown sequence (SIGTERM/SIGINT).
+     * Extensions are shut down in reverse order of loading.
+     * Errors during shutdown are logged but do not prevent other extensions from shutting down.
+     */
+    async ShutdownAll() {
+        // Shut down in reverse order of loading (LIFO)
+        for (let i = this._loadedExtensions.length - 1; i >= 0; i--) {
+            const ext = this._loadedExtensions[i];
+            try {
+                await ext.Instance.Shutdown();
+                LogStatus(`Server extension '${ext.DriverClass}' shut down`);
+            }
+            catch (error) {
+                LogError(`Error shutting down extension '${ext.DriverClass}':`, undefined, error);
+            }
+        }
+        this._loadedExtensions = [];
+    }
+    /**
+     * Get all loaded extension instances for inspection or testing.
+     *
+     * @returns Read-only array of loaded extensions with their driver class names.
+     */
+    get Extensions() {
+        return this._loadedExtensions;
+    }
+    /**
+     * Get the number of currently loaded extensions.
+     */
+    get ExtensionCount() {
+        return this._loadedExtensions.length;
+    }
+    /**
+     * Load and initialize a single extension from config.
+     *
+     * Uses MJ's `ClassFactory` to look up the registered class by `DriverClass` name,
+     * creates an instance, and calls `Initialize()`. On failure, logs the error and
+     * continues without throwing.
+     */
+    async loadSingleExtension(app, config) {
+        const driverClass = config.DriverClass;
+        if (!driverClass) {
+            LogError('Server extension config missing DriverClass, skipping');
+            return;
+        }
+        try {
+            // Use MJ's ClassFactory to find the registered extension class
+            const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseServerExtension, driverClass);
+            if (!instance) {
+                LogError(`Server extension '${driverClass}' not found in ClassFactory. ` +
+                    `Ensure the package is imported and the class uses ` +
+                    `@RegisterClass(BaseServerExtension, '${driverClass}')`);
+                return;
+            }
+            const result = await instance.Initialize(app, config);
+            if (result.Success) {
+                this._loadedExtensions.push({ Instance: instance, Config: config, DriverClass: driverClass });
+                LogStatus(`Server extension '${driverClass}' initialized: ${result.Message}`);
+                if (result.RegisteredRoutes && result.RegisteredRoutes.length > 0) {
+                    LogStatus(`  Routes: ${result.RegisteredRoutes.join(', ')}`);
+                }
+            }
+            else {
+                LogError(`Server extension '${driverClass}' failed to initialize: ${result.Message}`);
+            }
+        }
+        catch (error) {
+            LogError(`Error loading server extension '${driverClass}':`, undefined, error);
+        }
+    }
+}
+//# sourceMappingURL=ServerExtensionLoader.js.map

package/dist/ServerExtensionLoader.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module @memberjunction/server-extensions-core
+ *
+ * Server Extension framework for MJServer. Provides the abstract base class
+ * and loader for auto-discovering and managing server extension plugins.
+ *
+ * ## Overview
+ *
+ * This package defines the plugin architecture that allows any package to register
+ * Express routes and lifecycle hooks on a running MJServer instance. Extensions
+ * are discovered via MJ's standard `@RegisterClass` + `ClassFactory` pattern and
+ * configured in `mj.config.cjs`.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { RegisterClass } from '@memberjunction/global';
+ * import { BaseServerExtension } from '@memberjunction/server-extensions-core';
+ *
+ * @RegisterClass(BaseServerExtension, 'MyExtension')
+ * export class MyExtension extends BaseServerExtension {
+ *     // ... implement Initialize, Shutdown, HealthCheck
+ * }
+ * ```
+ *
+ * @see {@link BaseServerExtension} for the extension base class
+ * @see {@link ServerExtensionLoader} for the discovery and lifecycle manager
+ */
+export { BaseServerExtension } from './BaseServerExtension.js';
+export { ServerExtensionLoader } from './ServerExtensionLoader.js';
+export { ServerExtensionConfig, ExtensionInitResult, ExtensionHealthResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EACH,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,GACxB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * @module @memberjunction/server-extensions-core
+ *
+ * Server Extension framework for MJServer. Provides the abstract base class
+ * and loader for auto-discovering and managing server extension plugins.
+ *
+ * ## Overview
+ *
+ * This package defines the plugin architecture that allows any package to register
+ * Express routes and lifecycle hooks on a running MJServer instance. Extensions
+ * are discovered via MJ's standard `@RegisterClass` + `ClassFactory` pattern and
+ * configured in `mj.config.cjs`.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { RegisterClass } from '@memberjunction/global';
+ * import { BaseServerExtension } from '@memberjunction/server-extensions-core';
+ *
+ * @RegisterClass(BaseServerExtension, 'MyExtension')
+ * export class MyExtension extends BaseServerExtension {
+ *     // ... implement Initialize, Shutdown, HealthCheck
+ * }
+ * ```
+ *
+ * @see {@link BaseServerExtension} for the extension base class
+ * @see {@link ServerExtensionLoader} for the discovery and lifecycle manager
+ */
+export { BaseServerExtension } from './BaseServerExtension.js';
+export { ServerExtensionLoader } from './ServerExtensionLoader.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @module @memberjunction/server-extensions-core
+ * @description Core types for the MJServer extension framework.
+ */
+/**
+ * Configuration for a server extension instance, loaded from the `serverExtensions`
+ * array in `mj.config.cjs`.
+ *
+ * Each entry in the array corresponds to one extension instance. The `DriverClass`
+ * field is used to look up the registered class via `ClassFactory.CreateInstance()`.
+ *
+ * @example
+ * ```javascript
+ * // mj.config.cjs
+ * module.exports = {
+ *     serverExtensions: [
+ *         {
+ *             Enabled: true,
+ *             DriverClass: 'SlackMessagingExtension',
+ *             RootPath: '/webhook/slack',
+ *             Settings: {
+ *                 AgentID: '...',
+ *                 BotToken: process.env.SLACK_BOT_TOKEN,
+ *             }
+ *         }
+ *     ]
+ * };
+ * ```
+ */
+export interface ServerExtensionConfig {
+    /** Whether this extension is enabled. Disabled extensions are skipped during loading. */
+    Enabled: boolean;
+    /**
+     * The `@RegisterClass` key used to look up this extension in ClassFactory.
+     * Must match the second argument of `@RegisterClass(BaseServerExtension, 'DriverClass')`.
+     */
+    DriverClass: string;
+    /**
+     * URL path prefix for this extension's routes (e.g., `'/webhook/slack'`).
+     * The extension registers its routes under this prefix on the Express app.
+     */
+    RootPath: string;
+    /**
+     * Extension-specific configuration. The shape varies by extension type.
+     * For messaging adapters, this contains `AgentID`, `BotToken`, etc.
+     * The extension is responsible for parsing and validating its own settings.
+     */
+    Settings: Record<string, unknown>;
+}
+/**
+ * Result returned from extension initialization.
+ * Extensions report whether startup succeeded and what routes they registered.
+ */
+export interface ExtensionInitResult {
+    /** Whether initialization succeeded. If `false`, the extension is not loaded. */
+    Success: boolean;
+    /** Human-readable status message, logged by the extension loader. */
+    Message: string;
+    /**
+     * Routes registered by this extension. Used for logging and health check reporting.
+     * @example `['POST /webhook/slack', 'GET /webhook/slack/health']`
+     */
+    RegisteredRoutes?: string[];
+}
+/**
+ * Health check result for a single extension.
+ * Returned by `BaseServerExtension.HealthCheck()` and aggregated by `ServerExtensionLoader`.
+ */
+export interface ExtensionHealthResult {
+    /** Whether the extension is healthy and able to process requests. */
+    Healthy: boolean;
+    /** Human-readable name of the extension (typically the DriverClass). */
+    Name: string;
+    /** Optional details about the health status (uptime, last error, queue depth, etc.). */
+    Details?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,qBAAqB;IAClC,yFAAyF;IACzF,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;IAEjB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IAClC,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IAEjB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IAEb,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * @module @memberjunction/server-extensions-core
+ * @description Core types for the MJServer extension framework.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -1,10 +1,33 @@
 {
   "name": "@memberjunction/server-extensions-core",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/server-extensions-core",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "version": "5.17.0",
+  "description": "MemberJunction: Server Extension framework - plugin architecture for MJServer that enables auto-discovery and lifecycle management of extension modules",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "dependencies": {
+    "@memberjunction/global": "5.17.0",
+    "@memberjunction/core": "5.17.0",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.1.1",
+    "vite-tsconfig-paths": "^5.1.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }