@unchainedshop/core-enrollments 5.0.0-alpha.1 → 5.0.0-alpha.10

package/README.md

@@ -13,97 +13,21 @@ npm install @unchainedshop/core-enrollments
 
 ## Usage
 
-```typescript
-import { configureEnrollmentsModule, EnrollmentStatus } from '@unchainedshop/core-enrollments';
+The platform initializes this module as `platform.unchainedAPI.modules.enrollments`.
 
-const enrollmentsModule = await configureEnrollmentsModule({ db });
+```typescript
+import { EnrollmentStatus } from '@unchainedshop/core-enrollments';
 
-// Create an enrollment
-const enrollmentId = await enrollmentsModule.create({
+const { enrollments } = platform.unchainedAPI.modules;
+const activeEnrollments = await enrollments.findEnrollments({
+  status: [EnrollmentStatus.ACTIVE],
   userId: 'user-123',
-  productId: 'plan-product-456',
-  quantity: 1,
-});
-
-// Activate enrollment
-await enrollmentsModule.activate(enrollmentId);
-
-// Find active enrollments
-const enrollments = await enrollmentsModule.findEnrollments({
-  status: EnrollmentStatus.ACTIVE,
 });
 ```
 
-## API Overview
-
-### Module Configuration
-
-| Export | Description |
-|--------|-------------|
-| `configureEnrollmentsModule` | Configure and return the enrollments module |
-
-### Queries
-
-| Method | Description |
-|--------|-------------|
-| `findEnrollment` | Find enrollment by ID |
-| `findEnrollments` | Find enrollments with filtering and pagination |
-| `count` | Count enrollments matching query |
-| `enrollmentExists` | Check if enrollment exists |
-
-### Mutations
-
-| Method | Description |
-|--------|-------------|
-| `create` | Create a new enrollment |
-| `update` | Update enrollment data |
-| `delete` | Delete an enrollment |
-| `activate` | Activate an enrollment |
-| `terminate` | Terminate an enrollment |
-
-### Period Management
-
-| Method | Description |
-|--------|-------------|
-| `addPeriod` | Add a billing period |
-| `findPeriod` | Find a specific period |
-| `isExpired` | Check if enrollment is expired |
-
-### Utilities
-
-| Export | Description |
-|--------|-------------|
-| `addToDate` | Add time interval to date |
-
-### Constants
-
-| Export | Description |
-|--------|-------------|
-| `EnrollmentStatus` | Status values (INITIAL, ACTIVE, PAUSED, TERMINATED) |
-
-### Settings
-
-| Export | Description |
-|--------|-------------|
-| `enrollmentsSettings` | Access enrollment module settings |
-
-### Types
-
-| Export | Description |
-|--------|-------------|
-| `Enrollment` | Enrollment document type |
-| `EnrollmentPeriod` | Period document type |
-| `EnrollmentsModule` | Module interface type |
-
-## Events
+Status filters accept arrays. Enrollment lifecycle operations and recurring order generation are coordinated by `unchainedAPI.services.enrollments` and the registered enrollment and worker plugins. The module stores enrollments and their periods (`addEnrollmentPeriod`).
 
-| Event | Description |
-|-------|-------------|
-| `ENROLLMENT_CREATE` | Enrollment created |
-| `ENROLLMENT_UPDATE` | Enrollment updated |
-| `ENROLLMENT_REMOVE` | Enrollment deleted |
-| `ENROLLMENT_ACTIVATE` | Enrollment activated |
-| `ENROLLMENT_TERMINATE` | Enrollment terminated |
+See the [module guide](https://docs.unchained.shop/platform-configuration/modules/enrollments), [public exports](src/enrollments-index.ts), and [module implementation](src/module/configureEnrollmentsModule.ts).
 
 ## License
 

package/lib/db/EnrollmentsCollection.d.ts

@@ -7,7 +7,7 @@ export interface EnrollmentPeriod {
     isTrial?: boolean;
 }
 export interface EnrollmentPlan {
-    configuration: {
+    configuration?: {
         key: string;
         value: string;
     }[] | null;

package/lib/db/EnrollmentsCollection.js

@@ -1,4 +1,4 @@
-import { mongodb, buildDbIndexes, isDocumentDBCompatModeEnabled } from '@unchainedshop/mongodb';
+import { mongodb, buildDbIndexes } from '@unchainedshop/mongodb';
 import {} from '@unchainedshop/mongodb';
 export const EnrollmentStatus = {
     INITIAL: 'INITIAL',
@@ -8,34 +8,33 @@ export const EnrollmentStatus = {
 };
 export const EnrollmentsCollection = async (db) => {
     const Enrollments = db.collection('enrollments');
-    if (!isDocumentDBCompatModeEnabled()) {
-        await buildDbIndexes(Enrollments, [
-            {
-                index: {
-                    _id: 'text',
-                    userId: 'text',
-                    enrollmentNumber: 'text',
-                    status: 'text',
-                    'contact.telNumber': 'text',
-                    'contact.emailAddress': 'text',
-                },
-                options: {
-                    weights: {
-                        _id: 8,
-                        userId: 3,
-                        enrollmentNumber: 6,
-                        'contact.telNumber': 5,
-                        'contact.emailAddress': 4,
-                        status: 1,
-                    },
-                    name: 'enrollment_fulltext_search',
+    await buildDbIndexes(Enrollments, [
+        {
+            index: {
+                _id: 'text',
+                userId: 'text',
+                enrollmentNumber: 'text',
+                status: 'text',
+                'contact.telNumber': 'text',
+                'contact.emailAddress': 'text',
+            },
+            options: {
+                weights: {
+                    _id: 8,
+                    userId: 3,
+                    enrollmentNumber: 6,
+                    'contact.telNumber': 5,
+                    'contact.emailAddress': 4,
+                    status: 1,
                 },
+                name: 'enrollment_fulltext_search',
             },
-        ]);
-    }
+        },
+    ]);
     await buildDbIndexes(Enrollments, [
-        { index: { userId: 1 } },
-        { index: { productId: 1 } },
+        { index: { 'periods.orderId': 1 } },
+        { index: { userId: 1, status: 1 } },
+        { index: { productId: 1, status: 1 } },
         { index: { status: 1 } },
         { index: { enrollmentNumber: 1 } },
     ]);

package/lib/migrations/20260625120100-normalize-contact-phone.d.ts

@@ -0,0 +1,2 @@
+import type { MigrationRepository } from '@unchainedshop/mongodb';
+export default function normalizeContactPhone(repository: MigrationRepository): void;

package/lib/migrations/20260625120100-normalize-contact-phone.js

@@ -0,0 +1,27 @@
+import { normalizePhoneNumber } from '@unchainedshop/utils';
+import { EnrollmentsCollection } from "../db/EnrollmentsCollection.js";
+export default function normalizeContactPhone(repository) {
+    repository?.register({
+        id: 20260625120100,
+        name: 'Normalize enrollment.contact.telNumber to E.164 format',
+        up: async ({ logger }) => {
+            const Enrollments = await EnrollmentsCollection(repository.db);
+            const enrollments = await Enrollments.find({ 'contact.telNumber': { $exists: true, $nin: [null, ''] } }, { projection: { _id: true, contact: true, billingAddress: true, countryCode: true } }).toArray();
+            let changed = 0;
+            let skipped = 0;
+            for (const enrollment of enrollments) {
+                const current = enrollment.contact?.telNumber;
+                const defaultCountry = enrollment.billingAddress?.countryCode || enrollment.countryCode;
+                const normalized = normalizePhoneNumber(current, defaultCountry);
+                if (!normalized || normalized === current) {
+                    if (!normalized)
+                        skipped += 1;
+                    continue;
+                }
+                await Enrollments.updateOne({ _id: enrollment._id }, { $set: { 'contact.telNumber': normalized } });
+                changed += 1;
+            }
+            logger?.info(`Normalize enrollment.contact.telNumber: ${changed} updated, ${skipped} left unchanged (unparseable)`);
+        },
+    });
+}

package/lib/module/configureEnrollmentsModule.d.ts

@@ -8,7 +8,7 @@ export interface EnrollmentQuery {
     queryString?: string;
 }
 export declare const buildFindSelector: ({ queryString, status, userId }: EnrollmentQuery) => mongodb.Filter<Enrollment>;
-export declare const configureEnrollmentsModule: ({ db, options: enrollmentOptions, }: ModuleInput<EnrollmentsSettingsOptions>) => Promise<{
+export declare const configureEnrollmentsModule: ({ db, migrationRepository, options: enrollmentOptions, }: ModuleInput<EnrollmentsSettingsOptions>) => Promise<{
     count: (query: EnrollmentQuery) => Promise<number>;
     openEnrollmentWithProduct: ({ productId }: {
         productId: string;
@@ -18,6 +18,9 @@ export declare const configureEnrollmentsModule: ({ db, options: enrollmentOptio
     } | {
         orderId: string;
     }, options?: mongodb.FindOptions) => Promise<Enrollment | null>;
+    findEnrollmentsByOrderIds: ({ orderIds }: {
+        orderIds: string[];
+    }, options?: mongodb.FindOptions) => Promise<Enrollment[]>;
     findEnrollments: ({ limit, offset, sort, ...query }: EnrollmentQuery & {
         limit?: number;
         offset?: number;
@@ -32,7 +35,7 @@ export declare const configureEnrollmentsModule: ({ db, options: enrollmentOptio
     delete: (enrollmentId: string) => Promise<number>;
     removeEnrollmentPeriodByOrderId: (enrollmentId: string, orderId: string) => Promise<mongodb.WithId<Enrollment> | null>;
     updateBillingAddress: (enrollmentId: string, fieldValue: Address) => Promise<mongodb.WithId<Enrollment> | null>;
-    updateContact: (enrollmentId: string, fieldValue: Contact) => Promise<mongodb.WithId<Enrollment> | null>;
+    updateContact: (enrollmentId: string, contact: Contact) => Promise<mongodb.WithId<Enrollment> | null>;
     updateContext: (enrollmentId: string, fieldValue: any) => Promise<mongodb.WithId<Enrollment> | null>;
     updateDelivery: (enrollmentId: string, fieldValue: {
         deliveryProviderId?: string;

package/lib/module/configureEnrollmentsModule.js

@@ -1,15 +1,24 @@
-import { SortDirection } from '@unchainedshop/utils';
+import { SortDirection, normalizePhoneNumber } from '@unchainedshop/utils';
 import { EnrollmentStatus, } from "../db/EnrollmentsCollection.js";
 import { emit, registerEvents } from '@unchainedshop/events';
-import { generateDbFilterById, buildSortOptions, mongodb, generateDbObjectId, assertDocumentDBCompatMode, } from '@unchainedshop/mongodb';
+import { generateDbFilterById, buildSortOptions, mongodb, generateDbObjectId, } from '@unchainedshop/mongodb';
 import { EnrollmentsCollection } from "../db/EnrollmentsCollection.js";
 import { enrollmentsSettings } from "../enrollments-settings.js";
+import normalizeContactPhoneMigration from "../migrations/20260625120100-normalize-contact-phone.js";
 const ENROLLMENT_EVENTS = [
     'ENROLLMENT_ADD_PERIOD',
     'ENROLLMENT_CREATE',
     'ENROLLMENT_REMOVE',
     'ENROLLMENT_UPDATE',
 ];
+const normalizeContactPhone = (contact, defaultCountry) => {
+    if (!contact?.telNumber)
+        return contact;
+    return {
+        ...contact,
+        telNumber: normalizePhoneNumber(contact.telNumber, defaultCountry) || contact.telNumber,
+    };
+};
 export const buildFindSelector = ({ queryString, status, userId }) => {
     const selector = {
         deleted: null,
@@ -19,12 +28,12 @@ export const buildFindSelector = ({ queryString, status, userId }) => {
     if (userId)
         selector.userId = userId;
     if (queryString) {
-        assertDocumentDBCompatMode();
         selector.$text = { $search: queryString };
     }
     return selector;
 };
-export const configureEnrollmentsModule = async ({ db, options: enrollmentOptions = {}, }) => {
+export const configureEnrollmentsModule = async ({ db, migrationRepository, options: enrollmentOptions = {}, }) => {
+    normalizeContactPhoneMigration(migrationRepository);
     registerEvents(ENROLLMENT_EVENTS);
     enrollmentsSettings.configureSettings(enrollmentOptions);
     const Enrollments = await EnrollmentsCollection(db);
@@ -102,6 +111,11 @@ export const configureEnrollmentsModule = async ({ db, options: enrollmentOption
             }
             return Enrollments.findOne({ 'periods.orderId': params.orderId, deleted: null }, options);
         },
+        findEnrollmentsByOrderIds: async ({ orderIds }, options) => {
+            if (!orderIds?.length)
+                return [];
+            return Enrollments.find({ 'periods.orderId': { $in: orderIds }, deleted: null }, options).toArray();
+        },
         findEnrollments: async ({ limit, offset, sort, ...query }) => {
             const defaultSortOption = [{ key: 'created', value: SortDirection.ASC }];
             const enrollments = Enrollments.find(buildFindSelector(query), {
@@ -149,6 +163,7 @@ export const configureEnrollmentsModule = async ({ db, options: enrollmentOption
                 periods: [],
                 currencyCode,
                 countryCode,
+                contact: normalizeContactPhone(enrollmentData.contact, enrollmentData.billingAddress?.countryCode || countryCode),
                 configuration: enrollmentData.configuration || [],
                 log: [],
             });
@@ -179,7 +194,13 @@ export const configureEnrollmentsModule = async ({ db, options: enrollmentOption
             }, { returnDocument: 'after' });
         },
         updateBillingAddress: updateEnrollmentField('billingAddress'),
-        updateContact: updateEnrollmentField('contact'),
+        updateContact: async (enrollmentId, contact) => {
+            const existing = await Enrollments.findOne(generateDbFilterById(enrollmentId), {
+                projection: { billingAddress: true, countryCode: true },
+            });
+            const defaultCountry = existing?.billingAddress?.countryCode || existing?.countryCode;
+            return updateEnrollmentField('contact')(enrollmentId, normalizeContactPhone(contact, defaultCountry));
+        },
         updateContext: updateEnrollmentField('meta'),
         updateDelivery: updateEnrollmentField('delivery'),
         updatePayment: updateEnrollmentField('payment'),

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@unchainedshop/core-enrollments",
   "description": "Subscription and recurring billing module for the Unchained Engine",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.10",
+  "files": [
+    "lib"
+  ],
   "main": "lib/enrollments-index.js",
   "types": "lib/enrollments-index.d.ts",
   "type": "module",
@@ -35,12 +38,12 @@
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
-    "@unchainedshop/events": "^5.0.0-alpha.1",
-    "@unchainedshop/logger": "^5.0.0-alpha.1",
-    "@unchainedshop/utils": "^5.0.0-alpha.1"
+    "@unchainedshop/events": "^5.0.0-alpha.10",
+    "@unchainedshop/mongodb": "^5.0.0-alpha.10",
+    "@unchainedshop/utils": "^5.0.0-alpha.10"
   },
   "devDependencies": {
-    "@types/node": "^25.0.0",
-    "typescript": "^5.8.3"
+    "@types/node": "^26.2.0",
+    "typescript": "^6.0.3"
   }
 }