@iabtechlabtcf/core/lib/mjs/GVL.d.ts

Ensures consistent encoding and decoding of TC Signals for the iab. Transparency and Consent Framework (TCF).

import { Cloneable } from './Cloneable.js';
import { GVLError } from './errors/index.js';
import { ConsentLanguages, IntMap } from './model/index.js';
import { Feature, Purpose, Stack, Vendor, VendorList, DataCategory, GvlCreationOptions } from './model/gvl/index.js';
export type VersionOrVendorList = string | number | VendorList;
/**
 * class with utilities for managing the global vendor list.  Will use JSON to
 * fetch the vendor list from specified url and will serialize it into this
 * object and provide accessors.  Provides ways to group vendors on the list by
 * purpose and feature.
 */
export declare class GVL extends Cloneable<GVL> implements VendorList {
    private static LANGUAGE_CACHE;
    private static CACHE;
    private static LATEST_CACHE_KEY;
    static readonly DEFAULT_LANGUAGE: string;
    /**
     * Set of available consent languages published by the IAB
     */
    static readonly consentLanguages: ConsentLanguages;
    private static baseUrl_;
    /**
     * baseUrl - Entities using the vendor-list.json are required by the iab to
     * host their own copy of it to reduce the load on the iab's infrastructure
     * so a 'base' url must be set to be put together with the versioning scheme
     * of the filenames.
     *
     * @static
     * @param {string} url - the base url to load the vendor-list.json from.  This is
     * broken out from the filename because it follows a different scheme for
     * latest file vs versioned files.
     *
     * @throws {GVLError} - If the url is http[s]://vendorlist.consensu.org/...
     * this will throw an error.  IAB Europe requires that that CMPs and Vendors
     * cache their own copies of the GVL to minimize load on their
     * infrastructure.  For more information regarding caching of the
     * vendor-list.json, please see [the TCF documentation on 'Caching the Global
     * Vendor List'
     * ](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20Consent%20string%20and%20vendor%20list%20formats%20v2.md#caching-the-global-vendor-list)
     */
    static set baseUrl(url: string);
    /**
     * baseUrl - Entities using the vendor-list.json are required by the iab to
     * host their own copy of it to reduce the load on the iab's infrastructure
     * so a 'base' url must be set to be put together with the versioning scheme
     * of the filenames.
     *
     * @static
     * @return {string} - returns the previously set baseUrl, the default is
     * `undefined`
     */
    static get baseUrl(): string;
    /**
     * @static
     * @param {string} - the latest is assumed to be vendor-list.json because
     * that is what the iab uses, but it could be different... if you want
     */
    static latestFilename: string;
    /**
     * @static
     * @param {string} - the versioned name is assumed to be
     * vendor-list-v[VERSION].json where [VERSION] will be replaced with the
     * specified version.  But it could be different... if you want just make
     * sure to include the [VERSION] macro if you have a numbering scheme, it's a
     * simple string substitution.
     *
     * eg.
     * ```javascript
     * GVL.baseUrl = "http://www.mydomain.com/iabcmp/";
     * GVL.versionedFilename = "vendorlist?getVersion=[VERSION]";
     * ```
     */
    static versionedFilename: string;
    /**
     * @param {string} - Translations of the names and descriptions for Purposes,
     * Special Purposes, Features, and Special Features to non-English languages
     * are contained in a file where attributes containing English content
     * (except vendor declaration information) are translated.  The iab publishes
     * one following the scheme below where the LANG is the iso639-1 language
     * code.  For a list of available translations
     * [please go here](https://register.consensu.org/Translation).
     *
     * eg.
     * ```javascript
     * GVL.baseUrl = "http://www.mydomain.com/iabcmp/";
     * GVL.languageFilename = "purposes?getPurposes=[LANG]";
     * ```
     */
    static languageFilename: string;
    /**
     * @param {Promise} resolved when this GVL object is populated with the data
     * or rejected if there is an error.
     */
    readyPromise: Promise<void | GVLError>;
    /**
     * @param {number} gvlSpecificationVersion - schema version for the GVL that is used
     */
    gvlSpecificationVersion: number;
    /**
     * @param {number} incremented with each published file change
     */
    vendorListVersion: number;
    /**
     * @param {number} tcfPolicyVersion - The TCF MO will increment this value
     * whenever a GVL change (such as adding a new Purpose or Feature or a change
     * in Purpose wording) legally invalidates existing TC Strings and requires
     * CMPs to re-establish transparency and consent from users. If the policy
     * version number in the latest GVL is different from the value in your TC
     * String, then you need to re-establish transparency and consent for that
     * user. A version 1 format TC String is considered to have a version value
     * of 1.
     */
    tcfPolicyVersion: number;
    /**
     * @param {string | Date} lastUpdated - the date in which the vendor list
     * json file  was last updated.
     */
    lastUpdated: string | Date;
    /**
     * @param {IntMap<Purpose>} a collection of [[Purpose]]s
     */
    purposes: IntMap<Purpose>;
    /**
     * @param {IntMap<Purpose>} a collection of [[Purpose]]s
     */
    specialPurposes: IntMap<Purpose>;
    /**
     * @param {IntMap<Feature>} a collection of [[Feature]]s
     */
    features: IntMap<Feature>;
    /**
     * @param {IntMap<Feature>} a collection of [[Feature]]s
     */
    specialFeatures: IntMap<Feature>;
    /**
     * @param {boolean} internal reference of when the GVL is ready to be used
     */
    private isReady_;
    /**
     * @param {IntMap<Vendor>} a collection of [[Vendor]]s
     */
    private vendors_;
    vendorIds: Set<number>;
    /**
     * @param {IntMap<Vendor>} a collection of [[Vendor]]. Used as a backup if a whitelist is sets
     */
    private fullVendorList;
    /**
     * @param {ByPurposeVendorMap} vendors by purpose
     */
    private byPurposeVendorMap;
    /**
     * @param {IDSetMap} vendors by special purpose
     */
    private bySpecialPurposeVendorMap;
    /**
     * @param {IDSetMap} vendors by feature
     */
    private byFeatureVendorMap;
    /**
     * @param {IDSetMap} vendors by special feature
     */
    private bySpecialFeatureVendorMap;
    /**
     * @param {IntMap<Stack>} a collection of [[Stack]]s
     */
    stacks: IntMap<Stack>;
    /**
     * @param {IntMap<DataCategory>} a collection of [[DataCategory]]s
     */
    dataCategories?: IntMap<DataCategory>;
    private lang_;
    private cacheLang_;
    private isLatest;
    /**
     * @param {VersionOrVendorList} [versionOrVendorList] - can be either a
     * [[VendorList]] object or a version number represented as a string or
     * number to download.  If nothing is passed the latest version of the GVL
     * will be loaded
     * @param {GvlCreationOptions} [options] - it is an optional object where the default language can be set
     */
    constructor(versionOrVendorList?: VersionOrVendorList, options?: GvlCreationOptions);
    /**
     * emptyLanguageCache
     *
     * @param {string} [lang] - Optional language code to remove from
     * the cache.  Should be one of the languages in GVL.consentLanguages set.
     * If not then the whole cache will be deleted.
     * @return {boolean} - true if anything was deleted from the cache
     */
    static emptyLanguageCache(lang?: string): boolean;
    /**
     * emptyCache
     *
     * @param {number} [vendorListVersion] - version of the vendor list to delete
     * from the cache.  If none is specified then the whole cache is deleted.
     * @return {boolean} - true if anything was deleted from the cache
     */
    static emptyCache(vendorListVersion?: number): boolean;
    private cacheLanguage;
    private fetchJson;
    /**
     * getJson - Method for getting the JSON that was downloaded to created this
     * `GVL` object
     *
     * @return {VendorList} - The basic JSON structure without the extra
     * functionality and methods of this class.
     */
    getJson(): VendorList;
    private cloneSpecialFeatures;
    private cloneFeatures;
    private cloneStacks;
    private cloneDataCategories;
    private cloneSpecialPurposes;
    private clonePurposes;
    private static clonePurpose;
    private static cloneFeature;
    private static cloneDataCategory;
    private static cloneStack;
    private static cloneDataRetention;
    private static cloneVendorUrls;
    private static cloneVendor;
    private cloneVendors;
    /**
     * changeLanguage - retrieves the purpose language translation and sets the
     * internal language variable
     *
     * @param {string} lang - language code to change language to
     * @return {Promise<void | GVLError>} - returns the `readyPromise` and
     * resolves when this GVL is populated with the data from the language file.
     */
    changeLanguage(lang: string): Promise<void | GVLError>;
    get language(): string;
    private isVendorList;
    private populate;
    private mapVendors;
    private getFilteredVendors;
    /**
     * getVendorsWithConsentPurpose
     *
     * @param {number} purposeId
     * @return {IntMap<Vendor>} - list of vendors that have declared the consent purpose id
     */
    getVendorsWithConsentPurpose(purposeId: number): IntMap<Vendor>;
    /**
     * getVendorsWithLegIntPurpose
     *
     * @param {number} purposeId
     * @return {IntMap<Vendor>} - list of vendors that have declared the legInt (Legitimate Interest) purpose id
     */
    getVendorsWithLegIntPurpose(purposeId: number): IntMap<Vendor>;
    /**
     * getVendorsWithFlexiblePurpose
     *
     * @param {number} purposeId
     * @return {IntMap<Vendor>} - list of vendors that have declared the flexible purpose id
     */
    getVendorsWithFlexiblePurpose(purposeId: number): IntMap<Vendor>;
    /**
     * getVendorsWithSpecialPurpose
     *
     * @param {number} specialPurposeId
     * @return {IntMap<Vendor>} - list of vendors that have declared the special purpose id
     */
    getVendorsWithSpecialPurpose(specialPurposeId: number): IntMap<Vendor>;
    /**
     * getVendorsWithFeature
     *
     * @param {number} featureId
     * @return {IntMap<Vendor>} - list of vendors that have declared the feature id
     */
    getVendorsWithFeature(featureId: number): IntMap<Vendor>;
    /**
     * getVendorsWithSpecialFeature
     *
     * @param {number} specialFeatureId
     * @return {IntMap<Vendor>} - list of vendors that have declared the special feature id
     */
    getVendorsWithSpecialFeature(specialFeatureId: number): IntMap<Vendor>;
    /**
     * vendors
     *
     * @return {IntMap<Vendor>} - the list of vendors as it would on the JSON file
     * except if `narrowVendorsTo` was called, it would be that narrowed list
     */
    get vendors(): IntMap<Vendor>;
    /**
     * narrowVendorsTo - narrows vendors represented in this GVL to the list of ids passed in
     *
     * @param {number[]} vendorIds - list of ids to narrow this GVL to
     * @return {void}
     */
    narrowVendorsTo(vendorIds: number[]): void;
    /**
     * isReady - Whether or not this instance is ready to be used.  This will be
     * immediately and synchronously true if a vendorlist object is passed into
     * the constructor or once the JSON vendorllist is retrieved.
     *
     * @return {boolean} whether or not the instance is ready to be interacted
     * with and all the data is populated
     */
    get isReady(): boolean;
    /**
     * clone - overrides base `clone()` method since GVL is a special class that
     * represents a JSON structure with some additional functionality.
     *
     * @return {GVL}
     */
    clone(): GVL;
    static isInstanceOf(questionableInstance: unknown): questionableInstance is GVL;
}