@carbonbox/domain 0.48.1 → 0.49.0

package/build/carbonbox/shared/domain/enums/ErrorCode.js

@@ -17,7 +17,7 @@ exports.ErrorCode = void 0;
  * - RPT: Reporting
  * - SHR: Shared/Common
  *
- * Total Codes: 174
+ * Total Codes: 177
  * Total Exceptions Migrated: 171 (100%)
  *
  * @since 1.0.0
@@ -83,6 +83,10 @@ var ErrorCode;
     ErrorCode["MANAGER_REQUIRED"] = "CBX-STK-006";
     ErrorCode["INVALID_CARBON_CLIENT_ACCOUNT_TYPE"] = "CBX-STK-007";
     ErrorCode["INVALID_CARBON_COORDINATOR_AVAILABILITY_STATUS"] = "CBX-STK-008";
+    // User Preferences Errors (CBX-STK-009 to CBX-STK-011)
+    ErrorCode["INVALID_USER_PREFERENCE_CODE"] = "CBX-STK-009";
+    ErrorCode["DUPLICATE_USER_PREFERENCE_CODE"] = "CBX-STK-010";
+    ErrorCode["USER_PREFERENCE_CODE_LIMIT_EXCEEDED"] = "CBX-STK-011";
     // Carbon Footprint Configuration Errors (CBX-CFC-XXX)
     ErrorCode["CONFIGURATION_NOT_FOUND"] = "CBX-CFC-001";
     ErrorCode["INVALID_REPORTING_STANDARD"] = "CBX-CFC-002";

package/build/carbonbox/shared/domain/journeys/enums/CarbonClientJourneyBlockingReason.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CarbonClientJourneyBlockingReason = void 0;
+/**
+ * Carbon client journey blocking reason enumeration
+ * Reason codes attached to a journey step that is not DONE, explaining what keeps it from advancing.
+ * Unmet activation and completion requirements are reported separately (their own enums), so each
+ * array of the step carries a single type of code.
+ */
+var CarbonClientJourneyBlockingReason;
+(function (CarbonClientJourneyBlockingReason) {
+    // Step 1 - Active contract
+    /**
+     * A purchase contract is waiting for the carbon client signature
+     */
+    CarbonClientJourneyBlockingReason["CONTRACT_PENDING_CLIENT_SIGNATURE"] = "CONTRACT_PENDING_CLIENT_SIGNATURE";
+    /**
+     * A purchase contract is waiting for the CarbonBox signature
+     */
+    CarbonClientJourneyBlockingReason["CONTRACT_PENDING_CARBONBOX_SIGNATURE"] = "CONTRACT_PENDING_CARBONBOX_SIGNATURE";
+    /**
+     * A purchase contract is fully signed but not activated yet
+     */
+    CarbonClientJourneyBlockingReason["CONTRACT_PENDING_ACTIVATION"] = "CONTRACT_PENDING_ACTIVATION";
+    /**
+     * The carbon client has no purchase contract
+     */
+    CarbonClientJourneyBlockingReason["NO_CONTRACT"] = "NO_CONTRACT";
+    /**
+     * The validity window of the entitlement already ended
+     */
+    CarbonClientJourneyBlockingReason["ENTITLEMENT_EXPIRED"] = "ENTITLEMENT_EXPIRED";
+    /**
+     * The validity window of the entitlement has not started yet
+     */
+    CarbonClientJourneyBlockingReason["ENTITLEMENT_NOT_YET_ACTIVE"] = "ENTITLEMENT_NOT_YET_ACTIVE";
+    // Step 2 - Facilities
+    /**
+     * The carbon client has no facility
+     */
+    CarbonClientJourneyBlockingReason["NO_FACILITY"] = "NO_FACILITY";
+    /**
+     * The carbon client has facilities but none (or more than one) is marked as primary
+     */
+    CarbonClientJourneyBlockingReason["NO_PRIMARY_FACILITY"] = "NO_PRIMARY_FACILITY";
+    // Steps 3 to 10 - Carbon footprint configuration
+    /**
+     * The carbon client has no carbon footprint configuration for an entitled footprint type
+     */
+    CarbonClientJourneyBlockingReason["NO_CARBON_FOOTPRINT_CONFIGURATION"] = "NO_CARBON_FOOTPRINT_CONFIGURATION";
+    /**
+     * The DRAFT carbon footprint configuration does not meet its activation requirements
+     */
+    CarbonClientJourneyBlockingReason["ACTIVATION_REQUIREMENTS_UNMET"] = "ACTIVATION_REQUIREMENTS_UNMET";
+    // Step 6 - Activity data review
+    /**
+     * Submitted activity data records are waiting for review
+     */
+    CarbonClientJourneyBlockingReason["SUBMISSIONS_AWAITING_REVIEW"] = "SUBMISSIONS_AWAITING_REVIEW";
+    /**
+     * Activity data records were rejected and must be corrected and submitted again
+     */
+    CarbonClientJourneyBlockingReason["SUBMISSIONS_REJECTED"] = "SUBMISSIONS_REJECTED";
+    /**
+     * Activity data records are still in DRAFT and were not submitted
+     */
+    CarbonClientJourneyBlockingReason["DRAFT_SUBMISSIONS_NOT_SUBMITTED"] = "DRAFT_SUBMISSIONS_NOT_SUBMITTED";
+    // Step 7 - Calculation
+    /**
+     * There is no ACTIVE calculation workflow for the carbon client and footprint type
+     */
+    CarbonClientJourneyBlockingReason["NO_ACTIVE_CALCULATION_WORKFLOW"] = "NO_ACTIVE_CALCULATION_WORKFLOW";
+    /**
+     * A calculation process of the carbon footprint configuration is running
+     */
+    CarbonClientJourneyBlockingReason["CALCULATION_RUNNING"] = "CALCULATION_RUNNING";
+    /**
+     * Approved activity data records were not included in a completed calculation yet
+     */
+    CarbonClientJourneyBlockingReason["APPROVED_SUBMISSIONS_NOT_CALCULATED"] = "APPROVED_SUBMISSIONS_NOT_CALCULATED";
+    /**
+     * The calculation workflow exists but the caller is not one of its allowed executors
+     */
+    CarbonClientJourneyBlockingReason["CALLER_NOT_ALLOWED_EXECUTOR"] = "CALLER_NOT_ALLOWED_EXECUTOR";
+    // Step 9 - Report
+    /**
+     * The report is waiting for the internal approval
+     */
+    CarbonClientJourneyBlockingReason["REPORT_AWAITING_INTERNAL_APPROVAL"] = "REPORT_AWAITING_INTERNAL_APPROVAL";
+    /**
+     * The report is waiting for the carbon client approval
+     */
+    CarbonClientJourneyBlockingReason["REPORT_AWAITING_CLIENT_APPROVAL"] = "REPORT_AWAITING_CLIENT_APPROVAL";
+    // Step 10 - Completion
+    /**
+     * The ACTIVE carbon footprint configuration does not meet its completion requirements
+     */
+    CarbonClientJourneyBlockingReason["COMPLETION_REQUIREMENTS_UNMET"] = "COMPLETION_REQUIREMENTS_UNMET";
+    // Any step
+    /**
+     * The caller lacks the view permission of the step owner, so the step is reported as NOT_APPLICABLE
+     */
+    CarbonClientJourneyBlockingReason["CALLER_LACKS_VIEW_PERMISSION"] = "CALLER_LACKS_VIEW_PERMISSION";
+})(CarbonClientJourneyBlockingReason || (exports.CarbonClientJourneyBlockingReason = CarbonClientJourneyBlockingReason = {}));

package/build/carbonbox/shared/domain/journeys/enums/CarbonClientJourneyStep.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CarbonClientJourneyStep = void 0;
+/**
+ * Carbon client journey step enumeration
+ * Ordered steps a carbon client goes through, from an active contract to a completed carbon footprint.
+ * ACTIVE_CONTRACT and FACILITIES are evaluated once per carbon client; the remaining steps are
+ * evaluated per carbon footprint configuration.
+ */
+var CarbonClientJourneyStep;
+(function (CarbonClientJourneyStep) {
+    /**
+     * Step 1 - The carbon client has an entitlement whose validity window is active
+     */
+    CarbonClientJourneyStep["ACTIVE_CONTRACT"] = "ACTIVE_CONTRACT";
+    /**
+     * Step 2 - The carbon client has at least one facility and exactly one primary facility
+     */
+    CarbonClientJourneyStep["FACILITIES"] = "FACILITIES";
+    /**
+     * Step 3 - The carbon footprint configuration meets every activation requirement
+     */
+    CarbonClientJourneyStep["FOOTPRINT_CONFIGURED"] = "FOOTPRINT_CONFIGURED";
+    /**
+     * Step 4 - The carbon footprint configuration is ACTIVE (or already COMPLETED)
+     */
+    CarbonClientJourneyStep["FOOTPRINT_ACTIVE"] = "FOOTPRINT_ACTIVE";
+    /**
+     * Step 5 - Activity data was loaded for every expected emission source
+     */
+    CarbonClientJourneyStep["ACTIVITY_DATA_LOADED"] = "ACTIVITY_DATA_LOADED";
+    /**
+     * Step 6 - Every submitted activity data record was reviewed (none awaiting review nor rejected)
+     */
+    CarbonClientJourneyStep["ACTIVITY_DATA_REVIEWED"] = "ACTIVITY_DATA_REVIEWED";
+    /**
+     * Step 7 - Every approved activity data record was included in a completed calculation
+     */
+    CarbonClientJourneyStep["FOOTPRINT_CALCULATED"] = "FOOTPRINT_CALCULATED";
+    /**
+     * Step 8 - The report preparation questionnaire for the footprint type is COMPLETED
+     */
+    CarbonClientJourneyStep["REPORT_QUESTIONNAIRE_COMPLETED"] = "REPORT_QUESTIONNAIRE_COMPLETED";
+    /**
+     * Step 9 - The report for the footprint type (and period, for corporate footprints) is PUBLISHED
+     */
+    CarbonClientJourneyStep["REPORT_PUBLISHED"] = "REPORT_PUBLISHED";
+    /**
+     * Step 10 - The carbon footprint configuration is COMPLETED
+     */
+    CarbonClientJourneyStep["FOOTPRINT_COMPLETED"] = "FOOTPRINT_COMPLETED";
+})(CarbonClientJourneyStep || (exports.CarbonClientJourneyStep = CarbonClientJourneyStep = {}));

package/build/carbonbox/shared/domain/journeys/enums/CarbonClientJourneyStepStatus.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CarbonClientJourneyStepStatus = void 0;
+/**
+ * Carbon client journey step status enumeration
+ * State of a single step of the carbon client journey, evaluated against the current facts
+ */
+var CarbonClientJourneyStepStatus;
+(function (CarbonClientJourneyStepStatus) {
+    /**
+     * The step condition is met
+     */
+    CarbonClientJourneyStepStatus["DONE"] = "DONE";
+    /**
+     * The step was started but its condition is only partially met
+     */
+    CarbonClientJourneyStepStatus["IN_PROGRESS"] = "IN_PROGRESS";
+    /**
+     * The step cannot advance until the reasons listed in its blocking reason codes are resolved
+     */
+    CarbonClientJourneyStepStatus["BLOCKED"] = "BLOCKED";
+    /**
+     * The step can be performed now but has not been started
+     */
+    CarbonClientJourneyStepStatus["PENDING"] = "PENDING";
+    /**
+     * The step does not apply (e.g. footprint type not entitled, or the caller cannot view its data)
+     */
+    CarbonClientJourneyStepStatus["NOT_APPLICABLE"] = "NOT_APPLICABLE";
+})(CarbonClientJourneyStepStatus || (exports.CarbonClientJourneyStepStatus = CarbonClientJourneyStepStatus = {}));

package/build/carbonbox/shared/domain/journeys/enums/PendingActionType.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PendingActionType = void 0;
+/**
+ * Pending action type enumeration
+ * Kinds of work waiting for the caller, counted per carbon client in the pending actions inbox.
+ * Each type is only reported when the caller holds the permission that acts on it.
+ */
+var PendingActionType;
+(function (PendingActionType) {
+    /**
+     * Activity data records in SUBMITTED status, waiting for review (approve or reject)
+     */
+    PendingActionType["ACTIVITY_DATA_SUBMISSIONS_TO_REVIEW"] = "ACTIVITY_DATA_SUBMISSIONS_TO_REVIEW";
+    /**
+     * Activity data records in DRAFT status, waiting to be submitted
+     */
+    PendingActionType["ACTIVITY_DATA_SUBMISSIONS_TO_SUBMIT"] = "ACTIVITY_DATA_SUBMISSIONS_TO_SUBMIT";
+    /**
+     * Activity data records in REJECTED status, waiting to be corrected and submitted again
+     */
+    PendingActionType["ACTIVITY_DATA_SUBMISSIONS_TO_CORRECT"] = "ACTIVITY_DATA_SUBMISSIONS_TO_CORRECT";
+    /**
+     * Purchase contracts waiting for the carbon client signature
+     */
+    PendingActionType["PURCHASE_CONTRACTS_TO_SIGN_BY_CLIENT"] = "PURCHASE_CONTRACTS_TO_SIGN_BY_CLIENT";
+    /**
+     * Purchase contracts waiting for the CarbonBox signature
+     */
+    PendingActionType["PURCHASE_CONTRACTS_TO_SIGN_BY_CARBONBOX"] = "PURCHASE_CONTRACTS_TO_SIGN_BY_CARBONBOX";
+    /**
+     * Fully signed purchase contracts waiting to be activated
+     */
+    PendingActionType["PURCHASE_CONTRACTS_TO_ACTIVATE"] = "PURCHASE_CONTRACTS_TO_ACTIVATE";
+    /**
+     * Reports in PENDING_INTERNAL status, waiting for the internal approval
+     */
+    PendingActionType["REPORTS_TO_APPROVE_INTERNALLY"] = "REPORTS_TO_APPROVE_INTERNALLY";
+    /**
+     * Reports in PENDING_CLIENT status, waiting for the carbon client approval
+     */
+    PendingActionType["REPORTS_TO_APPROVE_BY_CLIENT"] = "REPORTS_TO_APPROVE_BY_CLIENT";
+    /**
+     * Reports in APPROVED status, waiting to be published
+     */
+    PendingActionType["REPORTS_TO_PUBLISH"] = "REPORTS_TO_PUBLISH";
+    /**
+     * Calculation processes in FAILED or TIMEOUT status with no later COMPLETED process for the same footprint
+     */
+    PendingActionType["FAILED_CALCULATION_PROCESSES"] = "FAILED_CALCULATION_PROCESSES";
+    /**
+     * Approved activity data records not included in a completed calculation yet
+     */
+    PendingActionType["APPROVED_SUBMISSIONS_PENDING_CALCULATION"] = "APPROVED_SUBMISSIONS_PENDING_CALCULATION";
+    /**
+     * Carbon clients with an ACTIVE carbon footprint configuration of a type that has no ACTIVE calculation workflow
+     */
+    PendingActionType["CARBON_CLIENTS_WITHOUT_ACTIVE_CALCULATION_WORKFLOW"] = "CARBON_CLIENTS_WITHOUT_ACTIVE_CALCULATION_WORKFLOW";
+})(PendingActionType || (exports.PendingActionType = PendingActionType = {}));

package/build/carbonbox/stakeholders/user-preferences/domain/entity/IUserPreference.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/carbonbox/stakeholders/user-preferences/domain/entity/UserPreference.js

@@ -0,0 +1,122 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _UserPreference_userId, _UserPreference_seenOnboardingTourCodes, _UserPreference_dismissedChecklistCodes;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserPreference = void 0;
+const AggregateRoot_1 = require("../../../../shared/domain/entities/AggregateRoot");
+const UserPreferenceUserId_1 = require("../value-objects/UserPreferenceUserId");
+const UserPreferenceSeenOnboardingTourCodes_1 = require("../value-objects/UserPreferenceSeenOnboardingTourCodes");
+const UserPreferenceDismissedChecklistCodes_1 = require("../value-objects/UserPreferenceDismissedChecklistCodes");
+/**
+ * UserPreference aggregate: user interface preferences of a stakeholder user
+ * (onboarding tours seen, checklists dismissed). Its identity is the owner user id.
+ *
+ * Changes return a new instance; adding codes is a union (idempotent), so two concurrent
+ * additions never remove each other's codes.
+ */
+class UserPreference extends AggregateRoot_1.AggregateRoot {
+    constructor(props, skipDomainValidation) {
+        const userId = skipDomainValidation
+            ? UserPreferenceUserId_1.UserPreferenceUserId.fromPrimitives(props.id)
+            : UserPreferenceUserId_1.UserPreferenceUserId.create(props.id);
+        super({ id: userId.toPrimitives() }, skipDomainValidation);
+        _UserPreference_userId.set(this, void 0);
+        _UserPreference_seenOnboardingTourCodes.set(this, void 0);
+        _UserPreference_dismissedChecklistCodes.set(this, void 0);
+        __classPrivateFieldSet(this, _UserPreference_userId, userId, "f");
+        if (skipDomainValidation === false) {
+            // Initialize with domain validation
+            __classPrivateFieldSet(this, _UserPreference_seenOnboardingTourCodes, UserPreferenceSeenOnboardingTourCodes_1.UserPreferenceSeenOnboardingTourCodes.create(props.seenOnboardingTourCodes), "f");
+            __classPrivateFieldSet(this, _UserPreference_dismissedChecklistCodes, UserPreferenceDismissedChecklistCodes_1.UserPreferenceDismissedChecklistCodes.create(props.dismissedChecklistCodes), "f");
+        }
+        else {
+            // Initialize from primitives (no domain validation)
+            __classPrivateFieldSet(this, _UserPreference_seenOnboardingTourCodes, UserPreferenceSeenOnboardingTourCodes_1.UserPreferenceSeenOnboardingTourCodes.fromPrimitives(props.seenOnboardingTourCodes), "f");
+            __classPrivateFieldSet(this, _UserPreference_dismissedChecklistCodes, UserPreferenceDismissedChecklistCodes_1.UserPreferenceDismissedChecklistCodes.fromPrimitives(props.dismissedChecklistCodes), "f");
+        }
+    }
+    static create(props) {
+        return new UserPreference(props, false);
+    }
+    /**
+     * Default preferences of a user who never saved any (empty lists). Not persisted by itself:
+     * reading preferences without a stored record returns this without writing.
+     */
+    static createDefault(userId) {
+        const props = {
+            id: userId,
+            seenOnboardingTourCodes: [],
+            dismissedChecklistCodes: [],
+        };
+        return new UserPreference(props, false);
+    }
+    static fromPrimitives(primitives) {
+        const props = {
+            id: primitives.id,
+            seenOnboardingTourCodes: primitives.seenOnboardingTourCodes,
+            dismissedChecklistCodes: primitives.dismissedChecklistCodes,
+        };
+        return new UserPreference(props, true);
+    }
+    get toPrimitives() {
+        return {
+            id: __classPrivateFieldGet(this, _UserPreference_userId, "f").toPrimitives(),
+            seenOnboardingTourCodes: __classPrivateFieldGet(this, _UserPreference_seenOnboardingTourCodes, "f").toPrimitives(),
+            dismissedChecklistCodes: __classPrivateFieldGet(this, _UserPreference_dismissedChecklistCodes, "f").toPrimitives(),
+        };
+    }
+    get userId() {
+        return __classPrivateFieldGet(this, _UserPreference_userId, "f");
+    }
+    get seenOnboardingTourCodes() {
+        return __classPrivateFieldGet(this, _UserPreference_seenOnboardingTourCodes, "f");
+    }
+    get dismissedChecklistCodes() {
+        return __classPrivateFieldGet(this, _UserPreference_dismissedChecklistCodes, "f");
+    }
+    /**
+     * Returns a new preference whose seen onboarding tours are the union of the current and the added codes.
+     * Throws UserPreferenceCodeLimitExceededError when the union exceeds the maximum.
+     */
+    withAddedSeenOnboardingTourCodes(addedCodes) {
+        return UserPreference.create({
+            id: __classPrivateFieldGet(this, _UserPreference_userId, "f").toPrimitives(),
+            seenOnboardingTourCodes: __classPrivateFieldGet(this, _UserPreference_seenOnboardingTourCodes, "f").withAddedCodes(addedCodes).toPrimitives(),
+            dismissedChecklistCodes: __classPrivateFieldGet(this, _UserPreference_dismissedChecklistCodes, "f").toPrimitives(),
+        });
+    }
+    /**
+     * Returns a new preference whose dismissed checklists are the union of the current and the added codes.
+     * Throws UserPreferenceCodeLimitExceededError when the union exceeds the maximum.
+     */
+    withAddedDismissedChecklistCodes(addedCodes) {
+        return UserPreference.create({
+            id: __classPrivateFieldGet(this, _UserPreference_userId, "f").toPrimitives(),
+            seenOnboardingTourCodes: __classPrivateFieldGet(this, _UserPreference_seenOnboardingTourCodes, "f").toPrimitives(),
+            dismissedChecklistCodes: __classPrivateFieldGet(this, _UserPreference_dismissedChecklistCodes, "f").withAddedCodes(addedCodes).toPrimitives(),
+        });
+    }
+    /**
+     * Returns a new preference with no seen onboarding tours ("show the tours again").
+     * Dismissed checklists are kept.
+     */
+    withSeenOnboardingToursReset() {
+        return UserPreference.create({
+            id: __classPrivateFieldGet(this, _UserPreference_userId, "f").toPrimitives(),
+            seenOnboardingTourCodes: [],
+            dismissedChecklistCodes: __classPrivateFieldGet(this, _UserPreference_dismissedChecklistCodes, "f").toPrimitives(),
+        });
+    }
+}
+exports.UserPreference = UserPreference;
+_UserPreference_userId = new WeakMap(), _UserPreference_seenOnboardingTourCodes = new WeakMap(), _UserPreference_dismissedChecklistCodes = new WeakMap();

package/build/carbonbox/stakeholders/user-preferences/domain/exceptions/DuplicateUserPreferenceCodeError.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuplicateUserPreferenceCodeError = void 0;
+const CodedRootError_1 = require("../../../../shared/domain/exceptions/CodedRootError");
+const ErrorCode_1 = require("../../../../shared/domain/enums/ErrorCode");
+class DuplicateUserPreferenceCodeError extends CodedRootError_1.CodedRootError {
+    constructor(propertyName, duplicatedCodes) {
+        const duplicatedCodesList = duplicatedCodes.join(', ');
+        const technicalMessage = `Duplicated user preference codes in '${propertyName}': ${duplicatedCodesList}. Each code can appear only once.`;
+        const context = {
+            propertyName,
+            duplicatedCodes,
+            duplicatedCodesCount: duplicatedCodes.length,
+            timestamp: new Date().toISOString(),
+        };
+        const suggestions = [
+            'Send each code only once',
+            'Remove the repeated codes before sending the request',
+            'Codes already stored are kept, so there is no need to send them again',
+        ];
+        super(ErrorCode_1.ErrorCode.DUPLICATE_USER_PREFERENCE_CODE, technicalMessage, context, suggestions);
+        this.name = 'DuplicateUserPreferenceCodeError';
+    }
+    static create(propertyName, duplicatedCodes) {
+        return new DuplicateUserPreferenceCodeError(propertyName, duplicatedCodes);
+    }
+    logError() {
+        return `${this.name}: ${this.technicalMessage}`;
+    }
+}
+exports.DuplicateUserPreferenceCodeError = DuplicateUserPreferenceCodeError;

package/build/carbonbox/stakeholders/user-preferences/domain/exceptions/InvalidUserPreferenceCodeError.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidUserPreferenceCodeError = void 0;
+const CodedRootError_1 = require("../../../../shared/domain/exceptions/CodedRootError");
+const ErrorCode_1 = require("../../../../shared/domain/enums/ErrorCode");
+class InvalidUserPreferenceCodeError extends CodedRootError_1.CodedRootError {
+    constructor(propertyName, invalidCodes, expectedPattern) {
+        const invalidCodesList = invalidCodes.join(', ');
+        const technicalMessage = `Invalid user preference codes in '${propertyName}': ${invalidCodesList}. Each code must match the pattern ${expectedPattern} (uppercase letters, digits and underscores, 1 to 100 characters).`;
+        const context = {
+            propertyName,
+            invalidCodes,
+            invalidCodesCount: invalidCodes.length,
+            expectedPattern,
+            timestamp: new Date().toISOString(),
+        };
+        const suggestions = [
+            `Use codes that match the pattern ${expectedPattern}`,
+            'Use only uppercase letters, digits and underscores, without spaces',
+            'Keep every code between 1 and 100 characters long',
+            'Verify that the codes come from the user interface catalog of onboarding tours and checklists',
+        ];
+        super(ErrorCode_1.ErrorCode.INVALID_USER_PREFERENCE_CODE, technicalMessage, context, suggestions);
+        this.name = 'InvalidUserPreferenceCodeError';
+    }
+    static create(propertyName, invalidCodes, expectedPattern) {
+        return new InvalidUserPreferenceCodeError(propertyName, invalidCodes, expectedPattern);
+    }
+    logError() {
+        return `${this.name}: ${this.technicalMessage}`;
+    }
+}
+exports.InvalidUserPreferenceCodeError = InvalidUserPreferenceCodeError;

package/build/carbonbox/stakeholders/user-preferences/domain/exceptions/UserPreferenceCodeLimitExceededError.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserPreferenceCodeLimitExceededError = void 0;
+const CodedRootError_1 = require("../../../../shared/domain/exceptions/CodedRootError");
+const ErrorCode_1 = require("../../../../shared/domain/enums/ErrorCode");
+class UserPreferenceCodeLimitExceededError extends CodedRootError_1.CodedRootError {
+    constructor(propertyName, receivedCount, maximumCount) {
+        const technicalMessage = `Too many user preference codes in '${propertyName}': ${receivedCount} codes received, the maximum is ${maximumCount}.`;
+        const context = {
+            propertyName,
+            receivedCount,
+            maximumCount,
+            excessCount: receivedCount - maximumCount,
+            timestamp: new Date().toISOString(),
+        };
+        const suggestions = [
+            `Keep at most ${maximumCount} codes in '${propertyName}'`,
+            'Reset the stored codes before adding new ones',
+            'Verify that the user interface is not generating a new code on every visit',
+        ];
+        super(ErrorCode_1.ErrorCode.USER_PREFERENCE_CODE_LIMIT_EXCEEDED, technicalMessage, context, suggestions);
+        this.name = 'UserPreferenceCodeLimitExceededError';
+    }
+    static create(propertyName, receivedCount, maximumCount) {
+        return new UserPreferenceCodeLimitExceededError(propertyName, receivedCount, maximumCount);
+    }
+    logError() {
+        return `${this.name}: ${this.technicalMessage}`;
+    }
+}
+exports.UserPreferenceCodeLimitExceededError = UserPreferenceCodeLimitExceededError;

package/build/carbonbox/stakeholders/user-preferences/domain/repository/IUserPreferenceRepository.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/carbonbox/stakeholders/user-preferences/domain/types/UserPreferencePrimitives.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/carbonbox/stakeholders/user-preferences/domain/types/UserPreferenceProps.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/carbonbox/stakeholders/user-preferences/domain/value-objects/UserPreferenceCodes.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserPreferenceCodes = void 0;
+const StringList_1 = require("../../../../shared/domain/value-objects/StringList");
+const InvalidUserPreferenceCodeError_1 = require("../exceptions/InvalidUserPreferenceCodeError");
+const DuplicateUserPreferenceCodeError_1 = require("../exceptions/DuplicateUserPreferenceCodeError");
+const UserPreferenceCodeLimitExceededError_1 = require("../exceptions/UserPreferenceCodeLimitExceededError");
+/**
+ * Abstract list of user interface codes stored as a user preference
+ * (e.g. onboarding tours already seen, checklist items dismissed).
+ *
+ * The codes belong to the user interface, so there is no enum: every code must match
+ * `^[A-Z0-9_]{1,100}$`, codes are unique (case-sensitive) and a list holds at most 200 codes.
+ * An empty list is valid (default preferences).
+ */
+class UserPreferenceCodes extends StringList_1.StringList {
+    /**
+     * Constructor protegido para que solo clases hijas puedan instanciar.
+     * Aplica todas las validaciones de dominio al momento de construcción.
+     */
+    constructor(values, skipDomainValidation, propertyName) {
+        super(values, skipDomainValidation, propertyName, { allowEmpty: true });
+        if (skipDomainValidation === false) {
+            UserPreferenceCodes.validateUserPreferenceCodes(values, propertyName);
+        }
+    }
+    /**
+     * Validación estática para reutilización en factory methods y constructores.
+     */
+    static validateUserPreferenceCodes(values, propertyName) {
+        StringList_1.StringList.guardAgainstInvalidStringList(values, propertyName, { allowEmpty: true });
+        UserPreferenceCodes.guardAgainstInvalidCodes(values, propertyName);
+        UserPreferenceCodes.guardAgainstDuplicateCodes(values, propertyName);
+        UserPreferenceCodes.guardAgainstCodeLimitExceeded(values, propertyName);
+    }
+    /**
+     * Valida que todos los códigos cumplan el patrón `^[A-Z0-9_]{1,100}$`.
+     */
+    static guardAgainstInvalidCodes(values, propertyName) {
+        const invalidCodes = values.filter((code) => UserPreferenceCodes.CODE_PATTERN.test(code) === false);
+        if (invalidCodes.length > 0) {
+            throw InvalidUserPreferenceCodeError_1.InvalidUserPreferenceCodeError.create(propertyName, invalidCodes, UserPreferenceCodes.CODE_PATTERN.source);
+        }
+    }
+    /**
+     * Valida que no haya códigos repetidos.
+     */
+    static guardAgainstDuplicateCodes(values, propertyName) {
+        const duplicatedCodes = values.filter((code, index) => values.indexOf(code) !== index);
+        if (duplicatedCodes.length > 0) {
+            throw DuplicateUserPreferenceCodeError_1.DuplicateUserPreferenceCodeError.create(propertyName, Array.from(new Set(duplicatedCodes)));
+        }
+    }
+    /**
+     * Valida que la lista no supere el tope de códigos.
+     */
+    static guardAgainstCodeLimitExceeded(values, propertyName) {
+        if (values.length > UserPreferenceCodes.MAXIMUM_CODE_COUNT) {
+            throw UserPreferenceCodeLimitExceededError_1.UserPreferenceCodeLimitExceededError.create(propertyName, values.length, UserPreferenceCodes.MAXIMUM_CODE_COUNT);
+        }
+    }
+    /**
+     * Unión de códigos: conserva el orden de los actuales y agrega al final los nuevos que no estaban.
+     * Idempotente: agregar códigos ya presentes no cambia la lista.
+     */
+    static mergeCodes(currentCodes, addedCodes) {
+        return Array.from(new Set([...currentCodes, ...addedCodes]));
+    }
+    /**
+     * Verifica si la lista contiene un código (comparación exacta).
+     */
+    includesCode(code) {
+        return this.value.includes(code);
+    }
+    /**
+     * Número de códigos en la lista.
+     */
+    get length() {
+        return this.value.length;
+    }
+    /**
+     * Verifica si la lista está vacía.
+     */
+    isEmpty() {
+        return this.value.length === 0;
+    }
+    toPrimitives() {
+        return [...this.value];
+    }
+}
+exports.UserPreferenceCodes = UserPreferenceCodes;
+UserPreferenceCodes.CODE_PATTERN = /^[A-Z0-9_]{1,100}$/;
+UserPreferenceCodes.MAXIMUM_CODE_COUNT = 200;

package/build/carbonbox/stakeholders/user-preferences/domain/value-objects/UserPreferenceDismissedChecklistCodes.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserPreferenceDismissedChecklistCodes = void 0;
+const UserPreferenceCodes_1 = require("./UserPreferenceCodes");
+/**
+ * Codes of the checklists (or checklist items) the user dismissed (the user interface hides them).
+ */
+class UserPreferenceDismissedChecklistCodes extends UserPreferenceCodes_1.UserPreferenceCodes {
+    constructor(values, skipDomainValidation) {
+        super(values, skipDomainValidation, UserPreferenceDismissedChecklistCodes.PROPERTY_NAME);
+    }
+    static create(values) {
+        UserPreferenceCodes_1.UserPreferenceCodes.validateUserPreferenceCodes(values, UserPreferenceDismissedChecklistCodes.PROPERTY_NAME);
+        return new UserPreferenceDismissedChecklistCodes(values, false);
+    }
+    static fromPrimitives(primitives) {
+        const values = primitives.map((primitive) => primitive);
+        return new UserPreferenceDismissedChecklistCodes(values, true);
+    }
+    /**
+     * Returns a new list with the union of the current codes and the added ones (idempotent).
+     * Throws UserPreferenceCodeLimitExceededError when the union exceeds the maximum.
+     */
+    withAddedCodes(addedCodes) {
+        return UserPreferenceDismissedChecklistCodes.create(UserPreferenceCodes_1.UserPreferenceCodes.mergeCodes(this.toPrimitives(), addedCodes.toPrimitives()));
+    }
+}
+exports.UserPreferenceDismissedChecklistCodes = UserPreferenceDismissedChecklistCodes;
+UserPreferenceDismissedChecklistCodes.PROPERTY_NAME = 'dismissedChecklistCodes';