@pubtech-ai/core 1.6.0

package/lib/mjs/model/PurposeRestrictionVector.js

@@ -0,0 +1,286 @@
+import { PurposeRestriction } from './PurposeRestriction.js';
+import { BinarySearchTree } from './BinarySearchTree.js';
+import { RestrictionType } from './RestrictionType.js';
+import { Cloneable } from '../Cloneable.js';
+export class PurposeRestrictionVector extends Cloneable {
+    /**
+     * if this originatd from an encoded string we'll need a place to store the
+     * bit length; it can be set and got from here
+     */
+    bitLength = 0;
+    /**
+     * a map indexed by a string which will be a 'hash' of the purpose and
+     * restriction type.
+     *
+     * Using a BST to keep vendors in a sorted order for encoding later
+     */
+    map = new Map();
+    gvl_;
+    has(hash) {
+        return this.map.has(hash);
+    }
+    isOkToHave(restrictionType, purposeId, vendorId) {
+        let result = true;
+        /**
+         * without a gvl set, there's no way to know... in that case we'll return
+         * true but once the GVL is set later we'll go through these and clean up
+         * the mess.
+         */
+        if (this.gvl?.vendors) {
+            const vendor = this.gvl.vendors[vendorId];
+            if (vendor) {
+                if (restrictionType === RestrictionType.NOT_ALLOWED) {
+                    /**
+                     * if it's "not allowed" then flexible declaration is ignored but if
+                     * if it isn't even listed as one of the purposes the vendor uses,
+                     * then there is no reason to encode the value so check both arrays
+                     * to see if it exists.  If it does then we can restrict it.
+                     */
+                    result = (vendor.legIntPurposes.includes(purposeId) || vendor.purposes.includes(purposeId));
+                }
+                else if (vendor.flexiblePurposes.length) {
+                    switch (restrictionType) {
+                        /**
+                         * If the vendor has the purposeId in flexiblePurposes and it is
+                         * listed as a legitimate interest purpose we can set the
+                         * override to require consent.
+                         */
+                        case RestrictionType.REQUIRE_CONSENT:
+                            result = (vendor.flexiblePurposes.includes(purposeId) && vendor.legIntPurposes.includes(purposeId));
+                            break;
+                        /**
+                         * If the vendor has the purposeId in flexiblePurposes and it is
+                         * listed as a consent purpose we can set the
+                         * override to require legitimate interest.
+                         */
+                        case RestrictionType.REQUIRE_LI:
+                            result = (vendor.flexiblePurposes.includes(purposeId) && vendor.purposes.includes(purposeId));
+                            break;
+                    }
+                }
+                else {
+                    result = false;
+                }
+            }
+            else {
+                // this vendor doesn't exist
+                result = false;
+            }
+        }
+        // if the gvl isn't defined, we can't do anything until later
+        return result;
+    }
+    /**
+     * add - adds a given Vendor ID under a given Purpose Restriction
+     *
+     * @param {number} vendorId
+     * @param {PurposeRestriction} purposeRestriction
+     * @return {void}
+     */
+    add(vendorId, purposeRestriction) {
+        if (this.isOkToHave(purposeRestriction.restrictionType, purposeRestriction.purposeId, vendorId)) {
+            const hash = purposeRestriction.hash;
+            if (!this.has(hash)) {
+                this.map.set(hash, new BinarySearchTree());
+                this.bitLength = 0;
+            }
+            /**
+             * Previously I had a check here to remove a duplicate value, but because
+             * we're using a tree the value is guaranteed to be unique so there is no
+             * need to add an additional de-duplication here.
+             */
+            this.map.get(hash).add(vendorId);
+        }
+    }
+    /**
+     * restrictPurposeToLegalBasis - adds all Vendors under a given Purpose Restriction
+     *
+     * @param {PurposeRestriction} purposeRestriction
+     * @return {void}
+     */
+    restrictPurposeToLegalBasis(purposeRestriction) {
+        const vendors = this.gvl.vendorIds;
+        const hash = purposeRestriction.hash;
+        const lastEntry = (function () {
+            let value;
+            for (value of vendors)
+                ;
+            return value;
+        })();
+        /**
+         * Create an ordered array of vendor IDs from `1` (the minimum value for Vendor ID) to `lastEntry`
+         */
+        const values = [...Array(lastEntry).keys()].map((i) => i + 1);
+        for (let i = 1; i <= lastEntry; i++) {
+            if (!this.has(hash)) {
+                this.map.set(hash, BinarySearchTree.build(values)); // use static method `build` to create a `BST` from the ordered array of IDs
+                this.bitLength = 0;
+            }
+            /**
+             * Previously I had a check here to remove a duplicate value, but because
+             * we're using a tree the value is guaranteed to be unique so there is no
+             * need to add an additional de-duplication here.
+             */
+            this.map.get(hash).add(i);
+        }
+    }
+    /**
+     * getVendors - returns array of vendor ids optionally narrowed by a given
+     * Purpose Restriction.  If no purpose restriction is passed then all vendor
+     * ids will be returned.  One can expect this result to be a unique set of
+     * ids no duplicates.
+     *
+     * @param {PurposeRestriction} [purposeRestriction] - optionally passed to
+     * get only Vendor IDs restricted under the given Purpose Restriction
+     * @return {number[]} - Unique ID set of vendors
+     */
+    getVendors(purposeRestriction) {
+        let vendorIds = [];
+        if (purposeRestriction) {
+            const hash = purposeRestriction.hash;
+            if (this.has(hash)) {
+                vendorIds = this.map.get(hash).get();
+            }
+        }
+        else {
+            const vendorSet = new Set();
+            this.map.forEach((bst) => {
+                bst.get().forEach((vendorId) => {
+                    vendorSet.add(vendorId);
+                });
+            });
+            vendorIds = Array.from(vendorSet);
+        }
+        return vendorIds;
+    }
+    getRestrictionType(vendorId, purposeId) {
+        let rType;
+        this.getRestrictions(vendorId).forEach((purposeRestriction) => {
+            if (purposeRestriction.purposeId === purposeId) {
+                if (rType === undefined || rType > purposeRestriction.restrictionType) {
+                    rType = purposeRestriction.restrictionType;
+                }
+            }
+        });
+        return rType;
+    }
+    /**
+     * vendorHasRestriction - determines whether a given Vendor ID is under a
+     * given Purpose Restriction
+     *
+     * @param {number} vendorId
+     * @param {PurposeRestriction} purposeRestriction
+     * @return {boolean} - true if the give Vendor ID is under the given Purpose
+     * Restriction
+     */
+    vendorHasRestriction(vendorId, purposeRestriction) {
+        let has = false;
+        const restrictions = this.getRestrictions(vendorId);
+        for (let i = 0; i < restrictions.length && !has; i++) {
+            has = purposeRestriction.isSameAs(restrictions[i]);
+        }
+        return has;
+    }
+    /**
+     * getMaxVendorId - gets the Maximum Vendor ID regardless of Purpose
+     * Restriction
+     *
+     * @return {number} - maximum Vendor ID
+     */
+    getMaxVendorId() {
+        let retr = 0;
+        this.map.forEach((bst) => {
+            retr = Math.max(bst.max(), retr);
+        });
+        return retr;
+    }
+    getRestrictions(vendorId) {
+        const retr = [];
+        this.map.forEach((bst, hash) => {
+            if (vendorId) {
+                if (bst.contains(vendorId)) {
+                    retr.push(PurposeRestriction.unHash(hash));
+                }
+            }
+            else {
+                retr.push(PurposeRestriction.unHash(hash));
+            }
+        });
+        return retr;
+    }
+    getPurposes() {
+        const purposeIds = new Set();
+        this.map.forEach((bst, hash) => {
+            purposeIds.add(PurposeRestriction.unHash(hash).purposeId);
+        });
+        return Array.from(purposeIds);
+    }
+    /**
+     * remove - removes Vendor ID from a Purpose Restriction
+     *
+     * @param {number} vendorId
+     * @param {PurposeRestriction} purposeRestriction
+     * @return {void}
+     */
+    remove(vendorId, purposeRestriction) {
+        const hash = purposeRestriction.hash;
+        const bst = this.map.get(hash);
+        if (bst) {
+            bst.remove(vendorId);
+            // if it's empty let's delete the key so it doesn't show up empty
+            if (bst.isEmpty()) {
+                this.map.delete(hash);
+                this.bitLength = 0;
+            }
+        }
+    }
+    /**
+     * Essential for being able to determine whether we can actually set a
+     * purpose restriction since they have to have a flexible legal basis
+     *
+     * @param {GVL} value - the GVL instance
+     */
+    set gvl(value) {
+        if (!this.gvl_) {
+            this.gvl_ = value;
+            /**
+             * if we have restrictions set before the gvl is set then we'll have to
+             * go through and remove some if they're not valid
+             */
+            this.map.forEach((bst, hash) => {
+                const purposeRestriction = PurposeRestriction.unHash(hash);
+                const vendors = bst.get();
+                vendors.forEach((vendorId) => {
+                    if (!this.isOkToHave(purposeRestriction.restrictionType, purposeRestriction.purposeId, vendorId)) {
+                        bst.remove(vendorId);
+                    }
+                });
+            });
+        }
+    }
+    /**
+     * gvl returns local copy of the GVL these restrictions apply to
+     *
+     * @return {GVL}
+     */
+    get gvl() {
+        return this.gvl_;
+    }
+    /**
+     * isEmpty - whether or not this vector has any restrictions in it
+     *
+     * @return {boolean}
+     */
+    isEmpty() {
+        return this.map.size === 0;
+    }
+    ;
+    /**
+     * numRestrictions - returns the number of Purpose Restrictions.
+     *
+     * @return {number}
+     */
+    get numRestrictions() {
+        return this.map.size;
+    }
+}

package/lib/mjs/model/RestrictionType.d.ts

@@ -0,0 +1,19 @@
+/**
+ * if a Vendor has declared flexible purposes (see: [[Vendor]] under
+ * `flexiblePurposeIds`) on the Global Vendor List ([[Declarations]]) a CMP may
+ * change their legal basis for processing in the encoding.
+ */
+export declare enum RestrictionType {
+    /**
+     * under no circumstances is this purpose allowed.
+     */
+    NOT_ALLOWED = 0,
+    /**
+     * if the default declaration is legitimate interest then this flips the purpose to consent in the encoding.
+     */
+    REQUIRE_CONSENT = 1,
+    /**
+     * if the default declaration is consent then this flips the purpose to Legitimate Interest in the encoding.
+     */
+    REQUIRE_LI = 2
+}

package/lib/mjs/model/RestrictionType.js

@@ -0,0 +1,20 @@
+/**
+ * if a Vendor has declared flexible purposes (see: [[Vendor]] under
+ * `flexiblePurposeIds`) on the Global Vendor List ([[Declarations]]) a CMP may
+ * change their legal basis for processing in the encoding.
+ */
+export var RestrictionType;
+(function (RestrictionType) {
+    /**
+     * under no circumstances is this purpose allowed.
+     */
+    RestrictionType[RestrictionType["NOT_ALLOWED"] = 0] = "NOT_ALLOWED";
+    /**
+     * if the default declaration is legitimate interest then this flips the purpose to consent in the encoding.
+     */
+    RestrictionType[RestrictionType["REQUIRE_CONSENT"] = 1] = "REQUIRE_CONSENT";
+    /**
+     * if the default declaration is consent then this flips the purpose to Legitimate Interest in the encoding.
+     */
+    RestrictionType[RestrictionType["REQUIRE_LI"] = 2] = "REQUIRE_LI";
+})(RestrictionType || (RestrictionType = {}));

package/lib/mjs/model/Segment.d.ts

@@ -0,0 +1,6 @@
+export declare enum Segment {
+    CORE = "core",
+    VENDORS_DISCLOSED = "vendorsDisclosed",
+    VENDORS_ALLOWED = "vendorsAllowed",
+    PUBLISHER_TC = "publisherTC"
+}

package/lib/mjs/model/Segment.js

@@ -0,0 +1,7 @@
+export var Segment;
+(function (Segment) {
+    Segment["CORE"] = "core";
+    Segment["VENDORS_DISCLOSED"] = "vendorsDisclosed";
+    Segment["VENDORS_ALLOWED"] = "vendorsAllowed";
+    Segment["PUBLISHER_TC"] = "publisherTC";
+})(Segment || (Segment = {}));

package/lib/mjs/model/SegmentIDs.d.ts

@@ -0,0 +1,12 @@
+import { KeyMap } from './KeyMap.js';
+import { Segment } from './Segment.js';
+export declare class SegmentIDs {
+    /**
+     * 0 = default - reserved for core string (does not need to be present in the core string)
+     * 1 = OOB vendors disclosed
+     * 2 = OOB vendors allowed
+     * 3 = PublisherTC
+     */
+    static readonly ID_TO_KEY: Segment[];
+    static readonly KEY_TO_ID: KeyMap<number>;
+}

package/lib/mjs/model/SegmentIDs.js

@@ -0,0 +1,21 @@
+import { Segment } from './Segment.js';
+export class SegmentIDs {
+    /**
+     * 0 = default - reserved for core string (does not need to be present in the core string)
+     * 1 = OOB vendors disclosed
+     * 2 = OOB vendors allowed
+     * 3 = PublisherTC
+     */
+    static ID_TO_KEY = [
+        Segment.CORE,
+        Segment.VENDORS_DISCLOSED,
+        Segment.VENDORS_ALLOWED,
+        Segment.PUBLISHER_TC,
+    ];
+    static KEY_TO_ID = {
+        [Segment.CORE]: 0,
+        [Segment.VENDORS_DISCLOSED]: 1,
+        [Segment.VENDORS_ALLOWED]: 2,
+        [Segment.PUBLISHER_TC]: 3,
+    };
+}

package/lib/mjs/model/Vector.d.ts

@@ -0,0 +1,72 @@
+import { Cloneable } from '../Cloneable.js';
+import { IntMap } from './IntMap.js';
+declare type SingleIDOrCollection = number | number[] | IntMap<unknown> | Set<number | string>;
+export declare type IdBoolTuple = [number, boolean];
+/**
+ * Vector class is like a Set except it keeps track of a max id
+ */
+export declare class Vector extends Cloneable<Vector> implements Iterable<IdBoolTuple> {
+    /**
+     * if this originatd from an encoded string we'll need a place to store the
+     * bit length; it can be set and got from here
+     */
+    bitLength: number;
+    private maxId_;
+    private set_;
+    [Symbol.iterator](): Iterator<IdBoolTuple>;
+    /**
+     * values()
+     *
+     * @return {IterableIterator<number>} - returns an iterator of the positive
+     * values in the set
+     */
+    values(): IterableIterator<number>;
+    /**
+     * maxId
+     *
+     * @return {number} - the highest id in this Vector
+     */
+    get maxId(): number;
+    /**
+     * get
+     *
+     * @param {number} id - key for value to check
+     * @return {boolean} - value of that key, if never set it will be false
+     */
+    has(id: number): boolean;
+    /**
+     * unset
+     *
+     * @param {SingleIDOrCollection} id - id or ids to unset
+     * @return {void}
+     */
+    unset(id: SingleIDOrCollection): void;
+    private isIntMap;
+    private isValidNumber;
+    private isSet;
+    /**
+     * set - sets an item assumed to be a truthy value by its presence
+     *
+     * @param {SingleIDOrCollection} item - May be a single id (positive integer)
+     * or collection of ids in a set, GVL Int Map, or Array.
+     *
+     * @return {void}
+     */
+    set(item: SingleIDOrCollection): void;
+    empty(): void;
+    /**
+     * forEach - to traverse from id=1 to id=maxId in a sequential non-sparse manner
+     *
+     *
+     * @param {forEachCallback} callback - callback to execute
+     * @return {void}
+     *
+     * @callback forEachCallback
+     * @param {boolean} value - whether or not this id exists in the vector
+     * @param {number} id - the id number of the current iteration
+     */
+    forEach(callback: (value: boolean, id: number) => void): void;
+    get size(): number;
+    setAll<T>(intMap: IntMap<T>): void;
+}
+export {};

package/lib/mjs/model/Vector.js

@@ -0,0 +1,161 @@
+import { Cloneable } from '../Cloneable.js';
+import { TCModelError } from '../errors/index.js';
+/**
+ * Vector class is like a Set except it keeps track of a max id
+ */
+export class Vector extends Cloneable {
+    /**
+     * if this originatd from an encoded string we'll need a place to store the
+     * bit length; it can be set and got from here
+     */
+    bitLength = 0;
+    maxId_ = 0;
+    set_ = new Set();
+    *[Symbol.iterator]() {
+        for (let i = 1; i <= this.maxId; i++) {
+            yield [i, this.has(i)];
+        }
+    }
+    /**
+     * values()
+     *
+     * @return {IterableIterator<number>} - returns an iterator of the positive
+     * values in the set
+     */
+    values() {
+        return this.set_.values();
+    }
+    /**
+     * maxId
+     *
+     * @return {number} - the highest id in this Vector
+     */
+    get maxId() {
+        return this.maxId_;
+    }
+    /**
+     * get
+     *
+     * @param {number} id - key for value to check
+     * @return {boolean} - value of that key, if never set it will be false
+     */
+    has(id) {
+        /**
+         * if it exists in the set we'll return true
+         */
+        return this.set_.has(id);
+    }
+    /**
+     * unset
+     *
+     * @param {SingleIDOrCollection} id - id or ids to unset
+     * @return {void}
+     */
+    unset(id) {
+        if (Array.isArray(id)) {
+            id.forEach((id) => this.unset(id));
+        }
+        else if (typeof id === 'object') {
+            this.unset(Object.keys(id).map((strId) => Number(strId)));
+        }
+        else {
+            this.set_.delete(Number(id));
+            /**
+             * if bitLength was set before, it must now be unset
+             */
+            this.bitLength = 0;
+            if (id === this.maxId) {
+                /**
+                 * aww bummer we lost our maxId... now we've got to search through
+                 * all the ids and find the biggest one.
+                 */
+                this.maxId_ = 0;
+                this.set_.forEach((id) => {
+                    this.maxId_ = Math.max(this.maxId, id);
+                });
+            }
+        }
+    }
+    isIntMap(item) {
+        let result = (typeof item === 'object');
+        result = (result && Object.keys(item).every((key) => {
+            let itemResult = Number.isInteger(parseInt(key, 10));
+            itemResult = (itemResult && this.isValidNumber(item[key].id));
+            itemResult = (itemResult && item[key].name !== undefined);
+            return itemResult;
+        }));
+        return result;
+    }
+    isValidNumber(item) {
+        return (parseInt(item, 10) > 0);
+    }
+    isSet(item) {
+        let result = false;
+        if (item instanceof Set) {
+            result = Array.from(item).every(this.isValidNumber);
+        }
+        return result;
+    }
+    /**
+     * set - sets an item assumed to be a truthy value by its presence
+     *
+     * @param {SingleIDOrCollection} item - May be a single id (positive integer)
+     * or collection of ids in a set, GVL Int Map, or Array.
+     *
+     * @return {void}
+     */
+    set(item) {
+        /**
+         * strategy here is to just recursively call set if it's a collection until
+         * we get to the final integer ID
+         */
+        if (Array.isArray(item)) {
+            item.forEach((item) => this.set(item));
+        }
+        else if (this.isSet(item)) {
+            this.set(Array.from(item));
+        }
+        else if (this.isIntMap(item)) {
+            this.set(Object.keys(item).map((strId) => Number(strId)));
+        }
+        else if (this.isValidNumber(item)) {
+            this.set_.add(item);
+            this.maxId_ = Math.max(this.maxId, item);
+            /**
+             * if bitLength was set before, it must now be unset
+             */
+            this.bitLength = 0;
+        }
+        else {
+            /**
+             * Super not cool to try and set something that's not valid
+             */
+            throw new TCModelError('set()', item, 'must be positive integer array, positive integer, Set<number>, or IntMap');
+        }
+    }
+    empty() {
+        this.set_ = new Set();
+    }
+    /**
+     * forEach - to traverse from id=1 to id=maxId in a sequential non-sparse manner
+     *
+     *
+     * @param {forEachCallback} callback - callback to execute
+     * @return {void}
+     *
+     * @callback forEachCallback
+     * @param {boolean} value - whether or not this id exists in the vector
+     * @param {number} id - the id number of the current iteration
+     */
+    forEach(callback) {
+        for (let i = 1; i <= this.maxId; i++) {
+            callback(this.has(i), i);
+        }
+    }
+    get size() {
+        return this.set_.size;
+    }
+    setAll(intMap) {
+        this.set(intMap);
+    }
+}

package/lib/mjs/model/gvl/ByPurposeVendorMap.d.ts

@@ -0,0 +1,7 @@
+export interface ByPurposeVendorMap {
+    [purposeId: string]: {
+        legInt: Set<number>;
+        consent: Set<number>;
+        flexible: Set<number>;
+    };
+}

package/lib/mjs/model/gvl/ByPurposeVendorMap.js

@@ -0,0 +1 @@
+export {};

package/lib/mjs/model/gvl/DataCategory.d.ts

@@ -0,0 +1,4 @@
+import { GVLMapItem } from './GVLMapItem.js';
+export interface DataCategory extends GVLMapItem {
+    description: string;
+}

package/lib/mjs/model/gvl/DataCategory.js

@@ -0,0 +1 @@
+export {};

package/lib/mjs/model/gvl/DataRetention.d.ts

@@ -0,0 +1,6 @@
+import { IntMap } from '../IntMap.js';
+export interface DataRetention {
+    stdRetention?: number;
+    purposes: IntMap<number>;
+    specialPurposes: IntMap<number>;
+}

package/lib/mjs/model/gvl/DataRetention.js

@@ -0,0 +1 @@
+export {};

package/lib/mjs/model/gvl/Declarations.d.ts

@@ -0,0 +1,13 @@
+import { IntMap } from '../IntMap.js';
+import { Feature } from './Feature.js';
+import { Purpose } from './Purpose.js';
+import { Stack } from './Stack.js';
+import { DataCategory } from './DataCategory.js';
+export interface Declarations {
+    purposes: IntMap<Purpose>;
+    specialPurposes: IntMap<Purpose>;
+    features: IntMap<Feature>;
+    specialFeatures: IntMap<Feature>;
+    stacks: IntMap<Stack>;
+    dataCategories?: IntMap<DataCategory>;
+}

package/lib/mjs/model/gvl/Declarations.js

@@ -0,0 +1 @@
+export {};

package/lib/mjs/model/gvl/Feature.d.ts

@@ -0,0 +1,5 @@
+import { GVLMapItem } from './GVLMapItem.js';
+export interface Feature extends GVLMapItem {
+    description: string;
+    descriptionLegal: string;
+}

package/lib/mjs/model/gvl/Feature.js

@@ -0,0 +1,2 @@
+;
+export {};

package/lib/mjs/model/gvl/GVLMapItem.d.ts

@@ -0,0 +1,4 @@
+export interface GVLMapItem {
+    id: number;
+    name: string;
+}

package/lib/mjs/model/gvl/GVLMapItem.js

@@ -0,0 +1 @@
+export {};

package/lib/mjs/model/gvl/IDSetMap.d.ts

@@ -0,0 +1,2 @@
+import { IntMap } from '../IntMap.js';
+export declare type IDSetMap = IntMap<Set<number>>;