@unchainedshop/core 4.8.29 → 5.0.0-alpha.10

package/README.md

@@ -3,7 +3,7 @@
 
 # @unchainedshop/core
 
-Core orchestration package for the Unchained Engine. Integrates all core-* modules, provides business services, directors for plugins, and bulk import functionality.
+Core orchestration for the Unchained Engine: domain modules, cross-module services, plugin directors, and bulk import/export.
 
 ## Installation
 
@@ -13,602 +13,148 @@ npm install @unchainedshop/core
 
 ## Usage
 
-```typescript
-import { initCore, type UnchainedCore } from '@unchainedshop/core';
-
-const unchainedCore = await initCore({
-  db,
-  migrationRepository,
-  options: {
-    // Module-specific options
-  },
-});
-
-// Access modules
-const products = await unchainedCore.modules.products.findProducts({});
-
-// Use services
-const pricing = await unchainedCore.services.orders.pricingSheet(order);
-
-// Bulk import
-await unchainedCore.bulkImporter.prepare('PRODUCT');
-```
-
-## API Overview
-
-### Initialization
-
-| Export | Description |
-|--------|-------------|
-| `initCore` | Initialize the core with all modules and services |
-| `getAllAdapters` | Get all registered adapters across all directors |
-
-### Modules
-
-The `modules` object provides access to all core-* module APIs:
-
-| Module | Description |
-|--------|-------------|
-| `products` | Product management |
-| `assortments` | Category/assortment management |
-| `filters` | Product filtering and search |
-| `orders` | Order management |
-| `users` | User management |
-| `payment` | Payment providers |
-| `delivery` | Delivery providers |
-| `warehousing` | Inventory and stock |
-| `enrollments` | Subscriptions |
-| `quotations` | Quote management |
-| `bookmarks` | User bookmarks |
-| `countries` | Country management |
-| `currencies` | Currency management |
-| `languages` | Language management |
-| `files` | File management |
-| `events` | Event history |
-| `worker` | Background jobs |
-
-### Services
-
-Business logic services that orchestrate multiple modules:
-
-| Service | Description |
-|---------|-------------|
-| `orders` | Order pricing, checkout workflows |
-| `products` | Product pricing calculations |
-| `users` | User-related operations |
-| `files` | File operations with adapters |
-
-### Directors
-
-Plugin directors provide extensibility through the Director/Adapter pattern. Each director manages a collection of adapters that implement specific behaviors.
-
-| Director | Description |
-|----------|-------------|
-| `PaymentDirector` | Payment processing adapters |
-| `DeliveryDirector` | Delivery/shipping adapters |
-| `WarehousingDirector` | Inventory and stock adapters |
-| `WorkerDirector` | Background job workers |
-| `FilterDirector` | Product search and filtering |
-| `EnrollmentDirector` | Subscription plan handling |
-| `QuotationDirector` | Quote/RFQ processing |
-| `ProductPricingDirector` | Product price calculations |
-| `OrderPricingDirector` | Order total calculations |
-| `DeliveryPricingDirector` | Delivery fee calculations |
-| `PaymentPricingDirector` | Payment fee calculations |
-| `ProductDiscountDirector` | Product-level discounts |
-| `OrderDiscountDirector` | Order-level discounts |
-| `MessagingDirector` | Email/notification templates |
-
-## Director/Adapter Architecture
-
-The Unchained Engine uses a Director/Adapter pattern for extensibility. Directors manage collections of adapters, and adapters implement specific behaviors.
-
-### Base Classes
+Most applications initialize core through `startPlatform()` from `@unchainedshop/platform`. Infrastructure integrations can initialize it directly with an existing database and migration repository:
 
 ```typescript
-import { BaseAdapter, BaseDirector } from '@unchainedshop/utils';
-```
-
-- **BaseDirector**: Factory function that creates a generic director with methods to register, unregister, and retrieve adapters
-- **BaseAdapter**: Base implementation providing logging and utility methods for all adapters
-
-### Creating a Custom Adapter
-
-All adapters extend from `BaseAdapter` and must implement:
+import { initCore } from '@unchainedshop/core';
 
-```typescript
-const MyAdapter = {
-  key: 'my-adapter',           // Unique identifier
-  label: 'My Custom Adapter',  // Human-readable label
-  version: '1.0.0',            // Adapter version
-
-  // Adapter-specific methods...
-};
-
-// Register with the appropriate director
-SomeDirector.registerAdapter(MyAdapter);
+const core = await initCore({ db, migrationRepository });
+const products = await core.modules.products.findProducts({});
 ```
 
-### Payment Director
-
-Manages payment processing and orchestrates payment adapters.
-
-```typescript
-import { PaymentDirector, type IPaymentAdapter } from '@unchainedshop/core';
-
-const MyPaymentAdapter: IPaymentAdapter = {
-  key: 'my-payment',
-  label: 'My Payment Gateway',
-  version: '1.0.0',
+`initCore()` accepts `options` for built-in modules, `modules` containing custom `{ configure }` factories, `services` for custom services, and `bulkImporter`/`bulkExporter` handler configuration. Built-in modules are included automatically. Platform startup additionally initializes plugin modules and lifecycle hooks, accounts, templates, HTTP API, and workers.
 
-  typeSupported(type) {
-    return type === 'CARD';
-  },
+## Modules and services
 
-  actions(config, context) {
-    return {
-      configurationError() { return null; },
-      isActive() { return true; },
-      isPayLaterAllowed() { return false; },
-
-      async charge() {
-        // Process payment charge
-        return { transactionId: '...' };
-      },
-      async confirm() {
-        // Confirm payment
-        return { transactionId: '...' };
-      },
-      async cancel() {
-        // Cancel payment
-        return true;
-      },
-      async register() {
-        // Register payment method
-        return { token: '...' };
-      },
-      async sign() {
-        // Sign payment request
-        return '...';
-      },
-      async validate(token) {
-        // Validate payment token
-        return true;
-      },
-    };
-  },
-};
+`core.modules` exposes `products`, `assortments`, `filters`, `orders`, `users`, `payment`, `delivery`, `warehousing`, `enrollments`, `quotations`, `bookmarks`, `countries`, `currencies`, `languages`, `files`, `events`, and `worker`.
 
-PaymentDirector.registerAdapter(MyPaymentAdapter);
-```
+`core.services` coordinates operations across modules, including pricing, checkout, payment, delivery, filtering, files, and enrollment processing. See [module configuration](src/modules.ts) and [service composition](src/services/index.ts) for their current interfaces.
 
-### Delivery Director
+## Plugin registration
 
-Manages delivery operations and coordinates shipping adapters.
+Register built-in plugins explicitly before platform startup. Importing a plugin has no registration side effect:
 
 ```typescript
-import { DeliveryDirector, type IDeliveryAdapter } from '@unchainedshop/core';
-
-const MyDeliveryAdapter: IDeliveryAdapter = {
-  key: 'my-delivery',
-  label: 'My Shipping Provider',
-  version: '1.0.0',
+import { pluginRegistry } from '@unchainedshop/core';
+import { StripePlugin } from '@unchainedshop/plugins/payment/stripe';
 
-  typeSupported(type) {
-    return type === 'SHIPPING';
-  },
-
-  actions(config, context) {
-    return {
-      configurationError() { return null; },
-      isActive() { return true; },
-      isAutoReleaseAllowed() { return false; },
-
-      async send() {
-        // Trigger delivery
-        return { trackingNumber: '...' };
-      },
-      estimatedDeliveryThroughput(warehousingTime) {
-        // Return estimated delivery time in ms
-        return 3 * 24 * 60 * 60 * 1000; // 3 days
-      },
-      async pickUpLocations() {
-        // Return available pickup locations
-        return [];
-      },
-      async pickUpLocationById(locationId) {
-        return null;
-      },
-    };
-  },
-};
-
-DeliveryDirector.registerAdapter(MyDeliveryAdapter);
+pluginRegistry.register(StripePlugin);
 ```
 
-### Warehousing Director
-
-Manages inventory and stock operations, including NFT/token support.
-
-```typescript
-import { WarehousingDirector, type IWarehousingAdapter } from '@unchainedshop/core';
-
-const MyWarehousingAdapter: IWarehousingAdapter = {
-  key: 'my-warehouse',
-  label: 'My Inventory System',
-  version: '1.0.0',
-
-  typeSupported(type) {
-    return type === 'PHYSICAL';
-  },
-
-  actions(config, context) {
-    return {
-      configurationError() { return null; },
-      isActive() { return true; },
-
-      async stock(referenceDate) {
-        // Return current stock quantity
-        return 100;
-      },
-      async productionTime(quantity) {
-        // Return production time in ms
-        return 0;
-      },
-      async commissioningTime(quantity) {
-        // Return commissioning time in ms
-        return 24 * 60 * 60 * 1000; // 1 day
-      },
-      async estimatedStock() {
-        return 100;
-      },
-      async estimatedDispatch() {
-        return new Date();
-      },
-      // For tokenized products (NFTs):
-      async tokenize() { return []; },
-      async tokenMetadata(serial, date) { return {}; },
-      async isInvalidateable(serial, date) { return false; },
-    };
-  },
-};
+Alternatively, call `registerBasePlugins()`, `registerAllPlugins()`, or `registerCryptoPlugins()` from the corresponding `@unchainedshop/plugins/presets/base`, `/all`, or `/crypto` subpath. Package subpaths have no file extension.
 
-WarehousingDirector.registerAdapter(MyWarehousingAdapter);
-```
+Directors resolve adapters from `pluginRegistry` by the `adapterType` symbol provided by each domain's base adapter. `getAllAdapters()` lists the adapters of all registered plugins that were not skipped during startup.
 
-### Worker Director
+### Custom adapters
 
-Manages background job processing and scheduled tasks.
+The typed `registerX()` factories both create and register an `IPlugin`. Call them before platform startup:
 
 ```typescript
-import { WorkerDirector, type IWorkerAdapter } from '@unchainedshop/core';
-
-interface MyInput { email: string; subject: string; }
-interface MyOutput { messageId: string; }
-
-const MyWorkerAdapter: IWorkerAdapter<MyInput, MyOutput> = {
-  key: 'my-worker',
-  label: 'My Background Worker',
-  version: '1.0.0',
-  type: 'MY_WORK_TYPE',          // Work type identifier
-  external: false,                // Runs in-process
-  maxParallelAllocations: 10,     // Max concurrent executions
-
-  async doWork(input, unchainedAPI, workId) {
-    // Process the work item
-    const { email, subject } = input;
-
-    // Return result
-    return {
-      success: true,
-      result: { messageId: 'msg-123' },
-    };
-  },
-};
-
-WorkerDirector.registerAdapter(MyWorkerAdapter);
-
-// Schedule recurring work
-WorkerDirector.configureAutoscheduling({
-  type: 'MY_WORK_TYPE',
-  input: { email: 'test@example.com', subject: 'Test' },
-  schedule: '0 * * * *', // Every hour (cron syntax)
+import {
+  registerPaymentProvider,
+  registerDeliveryProvider,
+  registerPhysicalWarehousing,
+  registerProductPricing,
+} from '@unchainedshop/core';
+
+registerPaymentProvider({
+  adapterId: 'manual-payment',
+  isPayLaterAllowed: true,
+  charge: false,
 });
-```
-
-### Pricing Directors
 
-Pricing directors calculate prices using a chain of adapters. Each adapter can add, modify, or discount prices.
-
-```typescript
-import { ProductPricingDirector, type IProductPricingAdapter } from '@unchainedshop/core';
-
-const MyPricingAdapter: IProductPricingAdapter = {
-  key: 'my-pricing',
-  label: 'My Pricing Logic',
-  version: '1.0.0',
-  orderIndex: 10, // Lower numbers run first
+registerDeliveryProvider({
+  adapterId: 'manual-shipping',
+  autoReleaseAllowed: false,
+  send: true,
+});
 
-  isActivatedFor(context) {
-    // Return true if this adapter should apply
-    return true;
-  },
+registerPhysicalWarehousing({
+  adapterId: 'local-stock',
+  stock: 100,
+  commissioningTime: 24 * 60 * 60 * 1000,
+});
 
-  actions(params) {
-    return {
-      calculate() {
-        // Add price calculations
-        this.calculation.addItem({
-          category: 'BASE',
-          amount: 1000, // in smallest currency unit
-        });
-      },
-    };
+registerProductPricing({
+  adapterId: 'fixed-price',
+  orderIndex: 0,
+  calculate: async (sheet) => {
+    sheet.addItem({ amount: 1000, isTaxable: true, isNetPrice: false });
   },
-};
-
-ProductPricingDirector.registerAdapter(MyPricingAdapter);
+});
 ```
 
-### Discount Directors
+The pricing example supplies a fixed base price in the smallest currency unit. Choose the pricing adapters appropriate to your shop so multiple adapters do not unintentionally add base prices.
 
-Discount directors manage coupon codes and automatic discounts.
+| Concern | Factories |
+|---------|-----------|
+| Payment | `registerPaymentProvider`, `registerInvoicePayment` |
+| Delivery | `registerDeliveryProvider`, `registerShippingDelivery`, `registerPickUpDelivery` |
+| Warehousing | `registerPhysicalWarehousing`, `registerVirtualWarehousing` |
+| Pricing | `registerProductPricing`, `registerOrderPricing`, `registerPaymentPricing`, `registerDeliveryPricing` |
+| Discounts | `registerProductDiscount`, `registerOrderDiscount` |
+| Filtering | `registerProductDiscoverabilityFilter`, `registerProductSearchFilter`, `registerAssortmentSearchFilter` |
+| Files | `registerFileAdapter` |
+| Quotations | `registerQuotation` |
+| Enrollments | `registerEnrollment` |
+| Workers | `registerWorker` |
 
-```typescript
-import { OrderDiscountDirector, type IDiscountAdapter } from '@unchainedshop/core';
+See the [factory implementations](src/factory/index.ts) for typed callback signatures. For capabilities beyond the factories, spread the relevant domain base adapter (for example `PaymentAdapter`) and its `actions()` defaults, then put the adapter in an `IPlugin` and call `pluginRegistry.register(plugin)`. This preserves the adapter's type symbol and required default methods.
 
-const MyDiscountAdapter: IDiscountAdapter = {
-  key: 'my-discount',
-  label: 'My Discount System',
-  version: '1.0.0',
-  orderIndex: 10,
+### Workers and recurring schedules
 
-  isManualAdditionAllowed(code) {
-    return code.startsWith('PROMO');
-  },
-  isManualRemovalAllowed() {
-    return true;
-  },
+```typescript
+import { registerWorker, schedule, WorkerDirector } from '@unchainedshop/core';
 
-  actions(context) {
-    return {
-      isValidForSystemTriggering() {
-        // Auto-apply discount?
-        return false;
-      },
-      isValidForCodeTriggering(code) {
-        // Apply when code entered?
-        return code === 'PROMO10';
-      },
-      discountForPricingAdapterKey(params) {
-        // Return discount configuration for pricing adapter
-        return {
-          isNetPrice: false,
-          rate: 0.1, // 10% off
-        };
-      },
-      async reserve(code) {
-        // Reserve discount (e.g., decrement coupon balance)
-      },
-      async release() {
-        // Release reservation on order cancellation
-      },
-    };
+registerWorker<{ message: string }, { logged: boolean }>({
+  type: 'LOG_MESSAGE',
+  maxParallelAllocations: 1,
+  process: async ({ message }) => {
+    console.log(message);
+    return { logged: true };
   },
-};
+});
 
-OrderDiscountDirector.registerAdapter(MyDiscountAdapter);
+WorkerDirector.configureAutoscheduling({
+  type: 'LOG_MESSAGE',
+  input: async () => ({ message: 'Hourly check' }),
+  schedule: schedule.parse.cron('0 * * * *'),
+});
 ```
 
-### Filter Director
-
-Manages product filtering and search functionality.
-
-```typescript
-import { FilterDirector, type IFilterAdapter } from '@unchainedshop/core';
-
-const MyFilterAdapter: IFilterAdapter = {
-  key: 'my-filter',
-  label: 'My Search Filter',
-  version: '1.0.0',
-  orderIndex: 10,
-
-  actions(context) {
-    return {
-      async aggregateProductIds(params) {
-        // Return product IDs matching filter
-        return ['product-1', 'product-2'];
-      },
-      async searchProducts(params, options) {
-        // Search products
-        return { productIds: [], totalCount: 0 };
-      },
-      async searchAssortments(params, options) {
-        // Search assortments
-        return { assortmentIds: [], totalCount: 0 };
-      },
-      transformProductSelector(selector, options) {
-        // Modify MongoDB product selector
-        return selector;
-      },
-      transformFilterSelector(selector, options) {
-        // Modify MongoDB filter selector
-        return selector;
-      },
-      transformSortStage(sort, options) {
-        // Modify MongoDB sort stage
-        return sort;
-      },
-    };
-  },
-};
-
-FilterDirector.registerAdapter(MyFilterAdapter);
-```
+Autoscheduling accepts parsed `ScheduleData` and an asynchronous input factory. The platform's queue managers enqueue and execute the scheduled work.
 
-### Messaging Director
+### Messaging templates
 
-The Messaging Director uses a template resolver pattern instead of traditional adapters.
+Messaging uses template resolvers registered separately from adapters:
 
 ```typescript
 import { MessagingDirector } from '@unchainedshop/core';
 
-// Register a message template
-MessagingDirector.registerTemplate('ORDER_CONFIRMATION', async (context) => {
-  const { order, user } = context;
-
-  return [
-    {
-      type: 'EMAIL',
-      input: {
-        to: user.email,
-        subject: `Order Confirmation #${order.orderNumber}`,
-        html: '<h1>Thank you for your order!</h1>',
-      },
+MessagingDirector.registerTemplate('CUSTOM_NOTICE', async ({ email }) => [
+  {
+    type: 'EMAIL',
+    input: {
+      from: 'shop@example.com',
+      to: email,
+      subject: 'Shop notice',
+      text: 'Your requested notification.',
     },
-    {
-      type: 'SMS',
-      input: {
-        to: user.phone,
-        text: `Order #${order.orderNumber} confirmed!`,
-      },
-    },
-  ];
-});
-```
-
-### Quotation Director
-
-Handles quotation/RFQ (Request for Quote) operations.
-
-```typescript
-import { QuotationDirector, type IQuotationAdapter } from '@unchainedshop/core';
-
-const MyQuotationAdapter: IQuotationAdapter = {
-  key: 'my-quotation',
-  label: 'My Quote System',
-  version: '1.0.0',
-
-  isActivatedFor(quotationContext, unchainedAPI) {
-    return true;
   },
-
-  actions(context) {
-    return {
-      configurationError() { return null; },
-      isManualProposalRequired() { return true; },
-      isManualRequestVerificationRequired() { return false; },
-
-      async quote() {
-        // Generate quote
-        return { price: 1000, currency: 'CHF' };
-      },
-      async submitRequest(quotationContext) {
-        // Submit RFQ
-      },
-      async verifyRequest(quotationContext) {
-        // Verify RFQ
-      },
-      async rejectRequest(quotationContext) {
-        // Reject RFQ
-      },
-      transformItemConfiguration(params) {
-        return params.configuration;
-      },
-    };
-  },
-};
-
-QuotationDirector.registerAdapter(MyQuotationAdapter);
-```
-
-### Enrollment Director
-
-Manages subscription/enrollment plans and recurring billing.
-
-```typescript
-import { EnrollmentDirector, type IEnrollmentAdapter } from '@unchainedshop/core';
-
-const MyEnrollmentAdapter: IEnrollmentAdapter = {
-  key: 'my-enrollment',
-  label: 'My Subscription System',
-  version: '1.0.0',
-
-  isActivatedFor(productPlan) {
-    return productPlan.type === 'PLAN_PRODUCT';
-  },
-
-  transformOrderItemToEnrollmentPlan(orderPosition, unchainedAPI) {
-    return {
-      configuration: orderPosition.configuration,
-    };
-  },
-
-  actions(context) {
-    return {
-      async nextPeriod() {
-        // Calculate next billing period
-        return {
-          start: new Date(),
-          end: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
-        };
-      },
-      isValidForActivation() {
-        return true;
-      },
-      isOverdue() {
-        return false;
-      },
-      async configurationForOrder(period) {
-        // Return order configuration for period
-        return {};
-      },
-    };
-  },
-};
-
-EnrollmentDirector.registerAdapter(MyEnrollmentAdapter);
+]);
 ```
 
-### Bulk Importer
+Each returned item is work for its registered worker type, such as `EMAIL` or `TWILIO`. Template parameters depend on the caller; they are not automatically populated with order/user documents.
 
-| Method | Description |
-|--------|-------------|
-| `bulkImporter.prepare` | Prepare bulk import for entity type |
-| `bulkImporter.process` | Process prepared import data |
+## Bulk import and export
 
-### Types
+`core.bulkImporter.createBulkImporter(options)` creates an import session with `validate(event)`, `prepare(event, core)`, `execute()`, and `invalidateCaches(core)`. Events carry `entity`, `operation`, and `payload`; the built-in entities are `PRODUCT`, `ASSORTMENT`, and `FILTER`.
 
-| Export | Description |
-|--------|-------------|
-| `UnchainedCore` | Core instance type |
-| `UnchainedCoreOptions` | Initialization options |
-| `Modules` | All modules type |
-| `Services` | All services type |
-| `BulkImporter` | Bulk importer type |
+For streams, use `validateEventStream(readStream)` and `pipeEventStream(readStream, importer, core)`, then execute the import and invalidate caches. See the [importer](src/bulk-importer/createBulkImporter.ts) and [exporter](src/bulk-exporter/index.ts) for the full interfaces.
 
-## Configuration
+## Types
 
-```typescript
-const core = await initCore({
-  db,
-  migrationRepository,
-  modules: {
-    // Custom modules
-  },
-  services: {
-    // Custom services
-  },
-  bulkImporter: {
-    handlers: {
-      // Custom import handlers
-    },
-  },
-  options: {
-    // Module-specific options
-  },
-});
-```
+The package exports `UnchainedCore`, `UnchainedCoreOptions`, `Services`, `BulkImporter`, `BulkExporter`, and `IPlugin`, along with domain adapter/context and pricing sheet types. Access the composed module type through `UnchainedCore['modules']`.
 
 ## License