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

package/README.md

@@ -25,7 +25,9 @@ const activeEnrollments = await enrollments.findEnrollments({
 });
 ```
 
-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`).
+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`) together with the lifecycle fields the services maintain: `expires` (when the enrollment ends), `resumeAt`, `contractStartDate`, `minimumCommitmentEnd` and the cancellation reason.
+
+`EnrollmentStatus` covers `INITIAL`, `ACTIVE`, `PAUSED`, `SUSPENDED` and `TERMINATED`; `EnrollmentTerminationReason` lists the cancellation reasons. Emitted events: `ENROLLMENT_CREATE`, `ENROLLMENT_UPDATE`, `ENROLLMENT_REMOVE`, `ENROLLMENT_ADD_PERIOD`, `ENROLLMENT_SUSPEND`, `ENROLLMENT_RESUME`, `ENROLLMENT_PLAN_CHANGE` and `ENROLLMENT_TRIAL_ENDING`.
 
 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).
 

package/lib/db/EnrollmentsCollection.d.ts

@@ -5,6 +5,7 @@ export interface EnrollmentPeriod {
     end: Date;
     orderId?: string;
     isTrial?: boolean;
+    trialEndingNotifiedAt?: Date;
 }
 export interface EnrollmentPlan {
     configuration?: {
@@ -18,8 +19,17 @@ export declare const EnrollmentStatus: {
     readonly INITIAL: "INITIAL";
     readonly ACTIVE: "ACTIVE";
     readonly PAUSED: "PAUSED";
+    readonly SUSPENDED: "SUSPENDED";
     readonly TERMINATED: "TERMINATED";
 };
+export declare const EnrollmentTerminationReason: {
+    readonly USER_REQUESTED: "USER_REQUESTED";
+    readonly PAYMENT_FAILED: "PAYMENT_FAILED";
+    readonly EXPIRED: "EXPIRED";
+    readonly ADMIN_ACTION: "ADMIN_ACTION";
+    readonly OTHER: "OTHER";
+};
+export type EnrollmentTerminationReason = (typeof EnrollmentTerminationReason)[keyof typeof EnrollmentTerminationReason];
 export type EnrollmentStatus = (typeof EnrollmentStatus)[keyof typeof EnrollmentStatus];
 export interface EnrollmentOrderPositionTemplate {
     context?: any;
@@ -50,6 +60,11 @@ export type Enrollment = {
     enrollmentNumber?: string;
     orderIdForFirstPeriod?: string;
     expires?: Date;
+    resumeAt?: Date;
+    contractStartDate?: Date;
+    minimumCommitmentEnd?: Date;
+    cancellationReason?: EnrollmentTerminationReason;
+    cancellationComment?: string;
     meta?: any;
     payment?: {
         paymentProviderId: string;

package/lib/db/EnrollmentsCollection.js

@@ -4,8 +4,16 @@ export const EnrollmentStatus = {
     INITIAL: 'INITIAL',
     ACTIVE: 'ACTIVE',
     PAUSED: 'PAUSED',
+    SUSPENDED: 'SUSPENDED',
     TERMINATED: 'TERMINATED',
 };
+export const EnrollmentTerminationReason = {
+    USER_REQUESTED: 'USER_REQUESTED',
+    PAYMENT_FAILED: 'PAYMENT_FAILED',
+    EXPIRED: 'EXPIRED',
+    ADMIN_ACTION: 'ADMIN_ACTION',
+    OTHER: 'OTHER',
+};
 export const EnrollmentsCollection = async (db) => {
     const Enrollments = db.collection('enrollments');
     await buildDbIndexes(Enrollments, [

package/lib/enrollments-settings.d.ts

@@ -12,6 +12,7 @@ export interface ScheduleData {
 export interface EnrollmentSettings {
     autoSchedulingSchedule: ScheduleData;
     enrollmentNumberHashFn: (enrollment: Enrollment, index: number) => string;
+    trialEndingNoticeDays: number;
     configureSettings: (options?: EnrollmentsSettingsOptions) => void;
 }
 export type EnrollmentsSettingsOptions = Omit<Partial<EnrollmentSettings>, 'configureSettings'>;

package/lib/enrollments-settings.js

@@ -5,8 +5,10 @@ const everyHourSchedule = {
 export const enrollmentsSettings = {
     autoSchedulingSchedule: everyHourSchedule,
     enrollmentNumberHashFn: generateRandomHash,
-    configureSettings({ autoSchedulingSchedule, enrollmentNumberHashFn } = {}) {
+    trialEndingNoticeDays: 3,
+    configureSettings({ autoSchedulingSchedule, enrollmentNumberHashFn, trialEndingNoticeDays } = {}) {
         this.autoSchedulingSchedule = autoSchedulingSchedule || everyHourSchedule;
         this.enrollmentNumberHashFn = enrollmentNumberHashFn || generateRandomHash;
+        this.trialEndingNoticeDays = trialEndingNoticeDays ?? 3;
     },
 };

package/lib/module/configureEnrollmentsModule.d.ts

@@ -1,5 +1,5 @@
 import { type SortOption } from '@unchainedshop/utils';
-import { type Enrollment, type EnrollmentPeriod, type EnrollmentPlan, EnrollmentStatus } from '../db/EnrollmentsCollection.ts';
+import { type Enrollment, type EnrollmentPeriod, type EnrollmentPlan, type EnrollmentTerminationReason, EnrollmentStatus } from '../db/EnrollmentsCollection.ts';
 import { mongodb, type Address, type Contact, type ModuleInput } from '@unchainedshop/mongodb';
 import { type EnrollmentsSettingsOptions } from '../enrollments-settings.ts';
 export interface EnrollmentQuery {
@@ -31,6 +31,7 @@ export declare const configureEnrollmentsModule: ({ db, migrationRepository, opt
         referenceDate?: Date;
     }) => boolean;
     addEnrollmentPeriod: (enrollmentId: string, period: EnrollmentPeriod) => Promise<mongodb.WithId<Enrollment> | null>;
+    markEnrollmentTrialEndingNotified: (enrollmentId: string, { start, end }: EnrollmentPeriod) => Promise<mongodb.WithId<Enrollment> | null>;
     create: ({ countryCode, currencyCode, ...enrollmentData }: Omit<Enrollment, "status" | "periods" | "log" | "_id" | "created"> & Pick<Partial<Enrollment>, "_id" | "created">) => Promise<Enrollment>;
     delete: (enrollmentId: string) => Promise<number>;
     removeEnrollmentPeriodByOrderId: (enrollmentId: string, orderId: string) => Promise<mongodb.WithId<Enrollment> | null>;
@@ -45,6 +46,16 @@ export declare const configureEnrollmentsModule: ({ db, migrationRepository, opt
         paymentProviderId: string;
         context?: any;
     } | undefined) => Promise<mongodb.WithId<Enrollment> | null>;
+    updateExpiry: (enrollmentId: string, fieldValue: Date | null) => Promise<mongodb.WithId<Enrollment> | null>;
+    updateResumeAt: (enrollmentId: string, fieldValue: Date) => Promise<mongodb.WithId<Enrollment> | null>;
+    updateCommitment: (enrollmentId: string, { contractStartDate, minimumCommitmentEnd, }: {
+        contractStartDate: Date;
+        minimumCommitmentEnd: Date;
+    }) => Promise<mongodb.WithId<Enrollment> | null>;
+    updateCancellation: (enrollmentId: string, params: {
+        reason?: EnrollmentTerminationReason;
+        comment?: string;
+    }) => Promise<mongodb.WithId<Enrollment> | null>;
     updatePlan: (enrollmentId: string, plan: EnrollmentPlan) => Promise<mongodb.WithId<Enrollment> | null>;
     updateStatus: (enrollmentId: string, { status, info }: {
         status: EnrollmentStatus;

package/lib/module/configureEnrollmentsModule.js

@@ -10,6 +10,10 @@ const ENROLLMENT_EVENTS = [
     'ENROLLMENT_CREATE',
     'ENROLLMENT_REMOVE',
     'ENROLLMENT_UPDATE',
+    'ENROLLMENT_SUSPEND',
+    'ENROLLMENT_RESUME',
+    'ENROLLMENT_PLAN_CHANGE',
+    'ENROLLMENT_TRIAL_ENDING',
 ];
 const normalizeContactPhone = (contact, defaultCountry) => {
     if (!contact?.telNumber)
@@ -71,18 +75,30 @@ export const configureEnrollmentsModule = async ({ db, migrationRepository, opti
         };
         switch (status) {
             case EnrollmentStatus.ACTIVE:
-                modifier.$set.enrollmentNumber = await findNewEnrollmentNumber(enrollment);
+                modifier.$set.enrollmentNumber =
+                    enrollment.enrollmentNumber || (await findNewEnrollmentNumber(enrollment));
                 break;
-            case EnrollmentStatus.TERMINATED:
-                modifier.$set.expires = enrollment.periods?.pop()?.end || new Date();
+            case EnrollmentStatus.TERMINATED: {
+                const periodEnds = (enrollment.periods || []).map(({ end }) => new Date(end).getTime());
+                modifier.$set.expires =
+                    enrollment.expires || (periodEnds.length ? new Date(Math.max(...periodEnds)) : date);
                 break;
+            }
             default:
                 break;
         }
+        if (enrollment.status === EnrollmentStatus.SUSPENDED)
+            modifier.$unset = { resumeAt: 1 };
         const updatedEnrollment = await Enrollments.findOneAndUpdate(selector, modifier, {
             returnDocument: 'after',
         });
         await emit('ENROLLMENT_UPDATE', { enrollment, field: 'status' });
+        if (status === EnrollmentStatus.SUSPENDED) {
+            await emit('ENROLLMENT_SUSPEND', { enrollment: updatedEnrollment });
+        }
+        else if (enrollment.status === EnrollmentStatus.SUSPENDED && status === EnrollmentStatus.ACTIVE) {
+            await emit('ENROLLMENT_RESUME', { enrollment: updatedEnrollment });
+        }
         return updatedEnrollment;
     };
     const updateEnrollmentField = (fieldKey) => async (enrollmentId, fieldValue) => {
@@ -102,7 +118,9 @@ export const configureEnrollmentsModule = async ({ db, migrationRepository, opti
         },
         openEnrollmentWithProduct: async ({ productId }) => {
             const selector = { productId };
-            selector.status = { $in: [EnrollmentStatus.ACTIVE, EnrollmentStatus.PAUSED] };
+            selector.status = {
+                $in: [EnrollmentStatus.ACTIVE, EnrollmentStatus.PAUSED, EnrollmentStatus.SUSPENDED],
+            };
             return Enrollments.findOne(selector);
         },
         findEnrollment: async (params, options) => {
@@ -154,6 +172,16 @@ export const configureEnrollmentsModule = async ({ db, migrationRepository, opti
             await emit('ENROLLMENT_ADD_PERIOD', { enrollment });
             return enrollment;
         },
+        markEnrollmentTrialEndingNotified: async (enrollmentId, { start, end }) => {
+            const enrollment = await Enrollments.findOneAndUpdate({
+                ...generateDbFilterById(enrollmentId),
+                periods: { $elemMatch: { start, end, trialEndingNotifiedAt: null } },
+            }, { $set: { 'periods.$.trialEndingNotifiedAt': new Date(), updated: new Date() } }, { returnDocument: 'after' });
+            if (!enrollment)
+                return null;
+            await emit('ENROLLMENT_UPDATE', { enrollment, field: 'periods' });
+            return enrollment;
+        },
         create: async ({ countryCode, currencyCode, ...enrollmentData }) => {
             const { insertedId: enrollmentId } = await Enrollments.insertOne({
                 _id: generateDbObjectId(),
@@ -204,6 +232,24 @@ export const configureEnrollmentsModule = async ({ db, migrationRepository, opti
         updateContext: updateEnrollmentField('meta'),
         updateDelivery: updateEnrollmentField('delivery'),
         updatePayment: updateEnrollmentField('payment'),
+        updateExpiry: updateEnrollmentField('expires'),
+        updateResumeAt: updateEnrollmentField('resumeAt'),
+        updateCommitment: async (enrollmentId, { contractStartDate, minimumCommitmentEnd, }) => {
+            const enrollment = await Enrollments.findOneAndUpdate(generateDbFilterById(enrollmentId), { $set: { updated: new Date(), contractStartDate, minimumCommitmentEnd } }, { returnDocument: 'after' });
+            await emit('ENROLLMENT_UPDATE', { enrollment, field: 'commitment' });
+            return enrollment;
+        },
+        updateCancellation: async (enrollmentId, params) => {
+            const enrollment = await Enrollments.findOneAndUpdate(generateDbFilterById(enrollmentId), {
+                $set: {
+                    updated: new Date(),
+                    ...(params.reason && { cancellationReason: params.reason }),
+                    ...(params.comment !== undefined && { cancellationComment: params.comment }),
+                },
+            }, { returnDocument: 'after' });
+            await emit('ENROLLMENT_UPDATE', { enrollment, field: 'cancellation' });
+            return enrollment;
+        },
         updatePlan: async (enrollmentId, plan) => {
             const enrollment = await Enrollments.findOneAndUpdate(generateDbFilterById(enrollmentId), {
                 $set: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unchainedshop/core-enrollments",
   "description": "Subscription and recurring billing module for the Unchained Engine",
-  "version": "5.0.0-alpha.10",
+  "version": "5.0.0-alpha.11",
   "files": [
     "lib"
   ],
@@ -38,9 +38,9 @@
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
-    "@unchainedshop/events": "^5.0.0-alpha.10",
-    "@unchainedshop/mongodb": "^5.0.0-alpha.10",
-    "@unchainedshop/utils": "^5.0.0-alpha.10"
+    "@unchainedshop/events": "^5.0.0-alpha.11",
+    "@unchainedshop/mongodb": "^5.0.0-alpha.11",
+    "@unchainedshop/utils": "^5.0.0-alpha.11"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",