@unchainedshop/platform 4.8.29 → 5.0.0-alpha.10

package/README.md

@@ -3,146 +3,116 @@
 
 # @unchainedshop/platform
 
-Umbrella package for the Unchained Engine. Provides complete platform setup including database initialization, API server, migrations, templates, and runtime configuration.
+Umbrella package for the Unchained Engine. Initializes the database, core modules and services, plugins, GraphQL server, message templates, and work queue.
 
 ## Installation
 
 ```bash
-npm install @unchainedshop/platform
+npm install @unchainedshop/platform express
 ```
 
-## Usage
+## Quick start
+
+Register plugins, initialize the platform, and connect it to your HTTP server:
 
 ```typescript
-import { startPlatform } from '@unchainedshop/platform';
 import express from 'express';
+import { startPlatform } from '@unchainedshop/platform';
+import { connect } from '@unchainedshop/api/express';
+import { registerBasePlugins } from '@unchainedshop/plugins/presets/base';
 
-const app = express();
+registerBasePlugins();
 
-const { unchainedAPI, graphqlHandler } = await startPlatform({
-  express: app,
-  options: {
-    // Platform options
-  },
-});
+const app = express();
+const platform = await startPlatform({});
+await connect(app, platform);
 
-// Platform is ready
+const products = await platform.unchainedAPI.modules.products.findProducts({});
 app.listen(4010);
 ```
 
-## API Overview
+For Fastify, use `connect` from `@unchainedshop/api/fastify` with a Fastify instance. `connect()` mounts GraphQL, MCP, and registered plugin routes. Pass `{ adminUI: true }` as its third argument to serve an installed `@unchainedshop/admin-ui` package.
 
-### Platform Setup
-
-| Export | Description |
-|--------|-------------|
-| `startPlatform` | Initialize complete Unchained platform |
-| `runMigrations` | Run database migrations |
-| `printRuntimeConfiguration` | Log registered templates, events, and adapters |
-
-### Context Helpers
-
-| Export | Description |
-|--------|-------------|
-| `setAccessToken` | Set access token for user session |
-| `getAccessToken` | Get current access token |
-| `invalidateAccessToken` | Invalidate/logout access token |
-
-### Templates
-
-| Export | Description |
-|--------|-------------|
-| `MessageTypes` | Available message/notification types |
-| `setupTemplates` | Register message templates |
-
-### Message Types
-
-| Type | Description |
-|------|-------------|
-| `ACCOUNT_ACTION` | Account verification, password reset |
-| `DELIVERY` | Delivery notifications |
-| `ORDER_CONFIRMATION` | Order confirmation emails |
-| `ORDER_REJECTION` | Order rejection notifications |
-| `QUOTATION_STATUS` | Quotation status updates |
-| `ENROLLMENT_STATUS` | Subscription status updates |
-| `FORWARD_DELIVERY` | Forward delivery notifications |
-
-## Quick Start
-
-```typescript
-import express from 'express';
-import { startPlatform, MessageTypes } from '@unchainedshop/platform';
-
-const app = express();
-
-const { unchainedAPI, graphqlHandler } = await startPlatform({
-  express: app,
-  options: {
-    modules: {
-      // Module-specific configuration
-    },
-    plugins: [
-      // Plugin imports
-    ],
-  },
-  workQueueConfig: {
-    // Worker queue configuration
-  },
-});
-
-// Access unchained API
-const products = await unchainedAPI.modules.products.findProducts({});
-
-// Start server
-app.use('/graphql', graphqlHandler);
-app.listen(4010);
-```
+Before startup, set `ROOT_URL`, `EMAIL_WEBSITE_NAME`, `EMAIL_WEBSITE_URL`, `EMAIL_FROM`, and `UNCHAINED_TOKEN_SECRET` (at least 32 characters). Set `MONGO_URL` for an external MongoDB; otherwise the database package starts a local instance.
 
 ## Configuration
 
 ```typescript
 const platform = await startPlatform({
-  express: app,
   options: {
-    modules: {
-      orders: {
-        // Order module options
-      },
-      products: {
-        // Product module options
-      },
-    },
-    services: {
-      // Custom services
+    orders: {
+      // Order module settings
     },
-    bulkImporter: {
-      handlers: {
-        // Custom import handlers
-      },
+    products: {
+      // Product module settings
     },
   },
-  workQueueConfig: {
-    batchSize: 10,
-    pollInterval: 1000,
+  modules: {
+    // Custom modules with a configure({ db, migrationRepository, options }) function
+  },
+  services: {
+    // Custom services
+  },
+  bulkImporter: {
+    handlers: {
+      // Custom import handlers
+    },
   },
-  context: (defaultResolver) => async (props, req, res) => {
-    const context = await defaultResolver(props, req, res);
-    return {
-      ...context,
-      // Custom context properties
-    };
+  workQueueOptions: {
+    skipInvalidationOnStartup: true,
   },
+  context: (defaultResolver) => async (props, req, res) => ({
+    ...(await defaultResolver(props, req, res)),
+    // Additional request context
+  }),
 });
 ```
 
-## Returns
+`PlatformOptions` combines core configuration with GraphQL server options, `rolesOptions`, `workQueueOptions`, and `auditLog`. Built-in modules are included automatically. Module settings are direct properties of `options`; module/service overrides and import/export handlers are top-level options.
+
+The work queue runs migrations and starts queue managers during startup unless workers are disabled. See [work queue options](src/setup/setupWorkqueue.ts) and [platform initialization](src/startPlatform.ts) for the current options.
+
+## Download documentation for coding assistants
+
+```bash
+npx --package @unchainedshop/platform unchained download-llm-docs
+```
+
+Requires Git. Downloads docs into `.unchained-docs/` for the installed platform
+version's tag, falling back to `master` when the tag is unavailable. Updates a
+managed file index in existing `CLAUDE.md` and `AGENTS.md` files (legacy `agents.md`
+is also supported), or creates `CLAUDE.md` if none exists. Re-running replaces the
+downloaded docs and index while preserving surrounding instructions. Add
+`.unchained-docs/` to your project's `.gitignore`.
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `startPlatform` | Initialize the platform |
+| `PlatformOptions` | Platform configuration type |
+| `runMigrations` | Run registered database migrations |
+| `printRuntimeConfiguration` | Log registered templates, events, and adapters |
+| `MessageTypes` | Built-in message type constants |
+
+The package also exports the [built-in template resolvers](src/templates/index.ts). Platform startup registers them automatically; custom templates use `MessagingDirector.registerTemplate()` from `@unchainedshop/core`.
+
+| Message type | Purpose |
+|--------------|---------|
+| `ACCOUNT_ACTION` | Email verification and password reset |
+| `DELIVERY` | Forward delivery notifications |
+| `ORDER_CONFIRMATION` | Order confirmations |
+| `ORDER_REJECTION` | Order rejections |
+| `QUOTATION_STATUS` | Quotation status updates |
+| `ENROLLMENT_STATUS` | Enrollment status updates |
+| `ERROR_REPORT` | Error reports |
 
-The `startPlatform` function returns:
+## Return value
 
 | Property | Description |
 |----------|-------------|
-| `unchainedAPI` | Complete Unchained core API instance |
-| `graphqlHandler` | GraphQL Yoga server instance for Express/Fastify |
+| `unchainedAPI` | Core modules, services, bulk importer/exporter, and options |
+| `graphqlHandler` | GraphQL Yoga server instance |
 | `db` | MongoDB database instance |
 
 ## License

package/bin/unchained.js

@@ -28,7 +28,7 @@ if (command !== 'download-llm-docs') {
 Commands:
   download-llm-docs   Download Unchained Engine docs for LLM coding assistants
                       (Claude Code, Cursor, etc.) and inject a file index into
-                      CLAUDE.md and/or agents.md`);
+                      CLAUDE.md and/or AGENTS.md`);
   process.exit(command ? 1 : 0);
 }
 
@@ -114,7 +114,7 @@ const indexSnippet = [
     `[Unchained Engine v${version} Docs Index]`,
     'root: ./.unchained-docs',
     'Search these docs before answering Unchained questions.',
-    'If docs missing, run: npx unchained download-llm-docs',
+    'If docs missing, run: npx --package @unchainedshop/platform unchained download-llm-docs',
     ...[...markdownsByDir]
       .sort(([a], [b]) => a.localeCompare(b))
       .map(
@@ -145,14 +145,17 @@ function upsertIndex(filePath) {
 }
 
 const claudeMdPath = join(process.cwd(), 'CLAUDE.md');
-const agentsMdPath = join(process.cwd(), 'agents.md');
+const agentsMdPath = join(process.cwd(), 'AGENTS.md');
+const legacyAgentsMdPath = join(process.cwd(), 'agents.md');
 const claudeExists = existsSync(claudeMdPath);
 const agentsExists = existsSync(agentsMdPath);
+const legacyAgentsExists = !agentsExists && existsSync(legacyAgentsMdPath);
 
 if (claudeExists) upsertIndex(claudeMdPath);
 if (agentsExists) upsertIndex(agentsMdPath);
+if (legacyAgentsExists) upsertIndex(legacyAgentsMdPath);
 
-if (!claudeExists && !agentsExists) {
+if (!claudeExists && !agentsExists && !legacyAgentsExists) {
   writeFileSync(claudeMdPath, `${indexSnippet}\n`);
   console.log('Created CLAUDE.md with docs index.');
 }

package/lib/migrations/createMigrationRunner.js

@@ -35,14 +35,8 @@ export const createMigrationRunner = ({ currentId, logger = console, migrationRe
             .map(this.operationFactory('up'));
     },
     async run() {
-        try {
-            const migrations = this.migrateToLatest();
-            const mostRecentId = await migrations.reduce((idPromise, migration) => Promise.resolve(idPromise).then(migration), currentId);
-            return [mostRecentId, migrations.length];
-        }
-        catch (e) {
-            logger.error(`Migration failed: ${e.name} - ${e.message}`);
-            return [e.migrationId, null];
-        }
+        const migrations = this.migrateToLatest();
+        const mostRecentId = await migrations.reduce((idPromise, migration) => Promise.resolve(idPromise).then(migration), currentId);
+        return [mostRecentId, migrations.length];
     },
 });

package/lib/migrations/runMigrations.js

@@ -32,15 +32,10 @@ export const runMigrations = async ({ migrationRepository, logger = createLogger
         unchainedAPI,
     });
     const [lastMigrationId, operationCount] = await runner.run();
-    if (operationCount !== null) {
-        if (operationCount > 0) {
-            logger.info(`All ${operationCount} migrations completed with most recent id: ${lastMigrationId}`);
-        }
-        else {
-            logger.debug(`No migrations run, already at latest id: ${currentId}`);
-        }
+    if (operationCount > 0) {
+        logger.info(`All ${operationCount} migrations completed with most recent id: ${lastMigrationId}`);
     }
     else {
-        logger.warn(`Some migrations failed, last successful id: ${lastMigrationId}`);
+        logger.debug(`No migrations run, already at latest id: ${currentId}`);
     }
 };

package/lib/setup/setupUploadHandlers.js

@@ -1,4 +1,4 @@
-import { FileDirector } from '@unchainedshop/file-upload';
+import { FileDirector } from '@unchainedshop/core';
 export const setupUploadHandlers = ({ services, modules }) => {
     FileDirector.registerFileUploadCallback('user-avatars', async (file) => {
         return services.users.updateUserAvatarAfterUpload({ file });

package/lib/setup/setupWorkqueue.js

@@ -12,7 +12,14 @@ export const queueWorkers = [];
 export async function setupWorkqueue({ unchainedAPI, migrationRepository, ...workQueueOptions }) {
     if (workQueueOptions.disableWorker || UNCHAINED_DISABLE_WORKER)
         return;
-    await runMigrations({ migrationRepository, unchainedAPI });
+    try {
+        await runMigrations({ migrationRepository, unchainedAPI });
+    }
+    catch (error) {
+        logger.error('Migration failed; continuing startup', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
     (workQueueOptions?.enabledQueueManagers || defaultQueueManagers).forEach((f) => {
         const handler = f.actions(workQueueOptions, unchainedAPI);
         queueWorkers.push(handler);

package/lib/startPlatform.d.ts

@@ -2,6 +2,7 @@ import { type UnchainedServerOptions } from '@unchainedshop/api';
 import { type UnchainedCoreOptions } from '@unchainedshop/core';
 import { mongodb } from '@unchainedshop/mongodb';
 import type { UnchainedCore } from '@unchainedshop/core';
+import { type AuditLogOptions } from '@unchainedshop/events';
 import { MessageTypes } from './setup/setupTemplates.ts';
 import { type SetupWorkqueueOptions } from './setup/setupWorkqueue.ts';
 import type { IRoleOptionConfig } from '@unchainedshop/roles';
@@ -9,8 +10,9 @@ export { MessageTypes };
 export type PlatformOptions = {
     rolesOptions?: IRoleOptionConfig;
     workQueueOptions?: SetupWorkqueueOptions;
+    auditLog?: AuditLogOptions | false;
 } & Omit<UnchainedCoreOptions, 'migrationRepository' | 'db'> & Omit<UnchainedServerOptions, 'roles' | 'unchainedAPI'>;
-export declare const startPlatform: ({ modules, services, options, rolesOptions, bulkImporter, bulkExporter, workQueueOptions, ...arbitraryAPIServerConfiguration }: PlatformOptions) => Promise<{
+export declare const startPlatform: ({ modules, services, options, rolesOptions, bulkImporter, bulkExporter, workQueueOptions, auditLog: auditLogConfig, ...arbitraryAPIServerConfiguration }: PlatformOptions) => Promise<{
     unchainedAPI: UnchainedCore;
     graphqlHandler: any;
     db: mongodb.Db;

package/lib/startPlatform.js

@@ -1,7 +1,9 @@
 import { startAPIServer, roles } from '@unchainedshop/api';
-import { initCore } from '@unchainedshop/core';
+import { initCore, pluginRegistry } from '@unchainedshop/core';
 import { initDb, mongodb, stopDb } from '@unchainedshop/mongodb';
 import { defaultLogger } from '@unchainedshop/logger';
+import { getEmitAdapter } from '@unchainedshop/events';
+import { createAuditLog, configureAuditIntegration, setAuditLogInstance, } from '@unchainedshop/events';
 import { setupAccounts } from "./setup/setupAccounts.js";
 import { setupUploadHandlers } from "./setup/setupUploadHandlers.js";
 import { setupTemplates, MessageTypes } from "./setup/setupTemplates.js";
@@ -30,22 +32,39 @@ const existOnInvalidEnvironmentVariables = () => {
         process.exit(1);
     }
 };
-export const startPlatform = async ({ modules, services, options, rolesOptions, bulkImporter, bulkExporter, workQueueOptions, ...arbitraryAPIServerConfiguration }) => {
+export const startPlatform = async ({ modules, services, options, rolesOptions, bulkImporter, bulkExporter, workQueueOptions, auditLog: auditLogConfig, ...arbitraryAPIServerConfiguration }) => {
     const start = performance.now();
     exitOnMissingEnvironmentVariables();
     existOnInvalidEnvironmentVariables();
     const configuredRoles = roles.configureRoles(rolesOptions || {});
     const db = await initDb();
     const migrationRepository = createMigrationRepository(db);
+    const pluginModuleFactories = pluginRegistry.getModuleFactories();
+    const pluginModules = pluginModuleFactories.reduce((acc, factory) => {
+        const factoryModules = factory({ db });
+        Object.entries(factoryModules).forEach(([key, moduleInstance]) => {
+            acc[key] = {
+                configure: () => moduleInstance,
+            };
+        });
+        return acc;
+    }, {});
+    const allModules = { ...pluginModules, ...(modules || {}) };
     const unchainedAPI = await initCore({
         db,
         migrationRepository,
         bulkImporter,
-        modules,
+        modules: allModules,
         services,
         options,
         bulkExporter,
     });
+    await pluginRegistry.initialize(unchainedAPI);
+    let auditLog;
+    if (auditLogConfig !== false) {
+        auditLog = createAuditLog(auditLogConfig || {});
+        setAuditLogInstance(auditLog);
+    }
     setupAccounts(unchainedAPI);
     setupTemplates(unchainedAPI);
     setupUploadHandlers(unchainedAPI);
@@ -54,6 +73,9 @@ export const startPlatform = async ({ modules, services, options, rolesOptions,
         roles: configuredRoles,
         ...arbitraryAPIServerConfiguration,
     });
+    if (auditLog) {
+        configureAuditIntegration(auditLog);
+    }
     await setupWorkqueue({
         unchainedAPI,
         migrationRepository,
@@ -77,8 +99,16 @@ export const startPlatform = async ({ modules, services, options, rolesOptions,
         try {
             defaultLogger.debug('Stopping Workqueue', { signal });
             stopWorkqueue();
+            defaultLogger.debug('Shutting down plugins', { signal });
+            await pluginRegistry.shutdown(unchainedAPI);
+            defaultLogger.debug('Shutting down event emitter', { signal });
+            await getEmitAdapter()?.shutdown?.();
             defaultLogger.debug('Stopping GraphQL server', { signal });
             await graphqlHandler.dispose();
+            if (auditLog) {
+                defaultLogger.debug('Closing audit log', { signal });
+                await auditLog.close();
+            }
             defaultLogger.debug('Stopping DB Connection', { signal });
             await stopDb();
             defaultLogger.debug(`Unchained Engine exiting gracefully`, { signal, version });

package/lib/templates/order-parser/getOrderPositionsData.js

@@ -2,7 +2,7 @@ import { ProductPricingSheet } from '@unchainedshop/core';
 import { ch } from '@unchainedshop/utils';
 export const getOrderPositionsData = async (order, params, context) => {
     const { modules } = context;
-    const { useNetPrice, format = ch.priceToString } = params || {};
+    const { useNetPrice, format = (price) => ch.priceToString({ ...price, locale: params?.locale }) } = params || {};
     const orderPositions = await modules.orders.positions.findOrderPositions({
         orderId: order._id,
     });

package/lib/templates/order-parser/getOrderSummaryData.js

@@ -2,7 +2,7 @@ import { OrderPricingSheet, OrderPricingRowCategory } from '@unchainedshop/core'
 import { ch } from '@unchainedshop/utils';
 export const getOrderSummaryData = async (order, params, context) => {
     const { modules } = context;
-    const { useNetPrice, format = ch.priceToString } = params || {};
+    const { useNetPrice, format = (price) => ch.priceToString({ ...price, locale: params?.locale }) } = params || {};
     const orderDelivery = order.deliveryId &&
         (await modules.orders.deliveries.findDelivery({
             orderDeliveryId: order.deliveryId,
@@ -21,7 +21,7 @@ export const getOrderSummaryData = async (order, params, context) => {
     const deliveryProvider = await modules.delivery.findProvider({
         deliveryProviderId: orderDelivery.deliveryProviderId,
     });
-    const deliveryAddress = ch.addressToString(orderDelivery?.context?.deliveryAddress || order.billingAddress);
+    const deliveryAddress = ch.addressToString(orderDelivery?.context?.address || orderDelivery?.context?.deliveryAddress || order.billingAddress);
     const billingAddress = ch.addressToString(order.billingAddress);
     const orderPricing = OrderPricingSheet({
         calculation: order.calculation,

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@unchainedshop/platform",
   "description": "Complete e-commerce platform bundle for the Unchained Engine",
-  "version": "4.8.29",
+  "version": "5.0.0-alpha.10",
+  "files": [
+    "lib",
+    "bin"
+  ],
   "main": "lib/platform-index.js",
   "types": "lib/platform-index.d.ts",
   "type": "module",
@@ -37,23 +41,21 @@
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "engines": {
-    "node": ">=22.0.0",
+    "node": ">=26.0.0",
     "npm": ">=10.0.0"
   },
   "dependencies": {
-    "@unchainedshop/api": "^4.8.27",
-    "@unchainedshop/core": "^4.8.27",
-    "@unchainedshop/core-orders": "^4.8.27",
-    "@unchainedshop/events": "^4.8.27",
-    "@unchainedshop/file-upload": "^4.8.27",
-    "@unchainedshop/logger": "^4.8.27",
-    "@unchainedshop/mongodb": "^4.8.27",
-    "@unchainedshop/plugins": "^4.8.27",
-    "@unchainedshop/roles": "^4.8.27",
-    "@unchainedshop/utils": "^4.8.27"
+    "@unchainedshop/api": "^5.0.0-alpha.10",
+    "@unchainedshop/core": "^5.0.0-alpha.10",
+    "@unchainedshop/events": "^5.0.0-alpha.10",
+    "@unchainedshop/logger": "^5.0.0-alpha.10",
+    "@unchainedshop/mongodb": "^5.0.0-alpha.10",
+    "@unchainedshop/plugins": "^5.0.0-alpha.10",
+    "@unchainedshop/roles": "^5.0.0-alpha.10",
+    "@unchainedshop/utils": "^5.0.0-alpha.10"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.3"
   }
 }