abee-adi-core/dist/abee-adi-core.d.ts

Behavioral tracking and device fingerprinting library

declare module "impl/integration/api-client" {
    export interface ApiClient {
        postForText(url: string, json: any, token?: string, applicationKey?: string): Promise<any>;
        postForJSON(url: string, json: any, token?: string, applicationKey?: string): Promise<any>;
        getForText(url: string, token?: string, applicationKey?: string): Promise<any>;
        getForJSON(url: string, token?: string, applicationKey?: string): Promise<any>;
        deleteForJSON(url: string, json: any, token?: string, applicationKey?: string): Promise<any>;
    }
    export class ApiClientBrowserFetch implements ApiClient {
        constructor();
        postForText(url: string, json: any, token?: string, applicationKey?: string): Promise<any>;
        postForJSON(url: string, json: any, token?: string, applicationKey?: string): Promise<any>;
        getForText(url: string, token?: string, applicationKey?: string): Promise<any>;
        getForJSON(url: string, token?: string, applicationKey?: string): Promise<any>;
        deleteForJSON(url: string, json: any, token?: string, applicationKey?: string): Promise<any>;
    }
    export const apiClient: ApiClientBrowserFetch;
}
declare module "iface/model" {
    export interface PatientID {
        journeyId?: string;
        personaId?: string;
        deviceId?: string;
    }
    /**
     * Patient represents an individual whose behaviour may be tracked by the ADI.
     * Patient may be anonimous but also when enough information is captured patient
     * can be identified as a persona.
     * ADI patient id may be stored/calculated either by using cookies or by device fingerprinting activities
     */
    export interface Patient {
        id?: PatientID;
    }
}
declare module "iface/core" {
    import { ApiClient } from "impl/integration/api-client";
    import { Patient } from "iface/model";
    /**
     * Function that shall check if for given patient
     * ADI is allowed to track behaviour.
     * Returns true when tracking is allowed.
     * Usually this function SHOULD ask some external GDPR consent provider
     * for approval to track user behaviour. Sometimes
     */
    export interface GDPRConsentProvider {
        (applicationKey: string, patient: Patient, apiClient?: ApiClient): Promise<boolean>;
    }
    export interface Fingerprint {
        deviceId: string;
    }
    /**
     * Function shall generate unique id using device specifics. It should guarantee to generate the same unique id for the same physical device and also guarantee that for
     * different physical devices different ids shall be returned. It also should return as many as possible device characteristics.
     */
    export interface FingerprintProvider {
        (applicationKey: string, patient: Patient, apiClient?: ApiClient): Promise<Fingerprint | string>;
    }
    /**
     * Function that shall return persona id for given patient ids captured by the
     * ADI engine.
     */
    export interface PersonaProvider {
        (applicationKey: string, patient: Patient, apiClient?: ApiClient): Promise<string | undefined>;
    }
    /**
     * Set of functions for reading/writing data to local storage (cookie, local storage etc depending on the final channel)
     */
    export interface StorageProvider {
        storeObject(name: string, obj: any): void;
        restoreObject(name: string): any;
        storeString(name: string, obj: string): void;
        restoreString(name: string): string | undefined;
        deleteItem(name: string): void;
    }
    export interface ADIIntegrationAware {
        setApiClient: (apiClient: ApiClient) => void;
    }
    export interface ADICoreIface {
        /**
         * Entry point for the ADI engine.
         * @param applicationKey unqiue application key
         * @param gdprProvider provider that will return GDPR related patient/persona consents
         * @param personaProvider provider that will retrieve real persona id
         * @returns {Patient} patient data as recognised by the ADI engine
         */
        boot: (options: ADIOptions) => Promise<Patient>;
        /**
         * Notify ADI about identified persona (for instance when user logs in and is known and
         * identified). When persona id is provided, each event/behaviour will be tracked
         * in the context of the provided persona id provided the GDPR provider allows
         * for tracking of the provided persona.
         * This method MUST make a check with GDPR provider to see if ADI is still
         * allowed to track that persona.
         * @param personaId real user if provided to ADI
         */
        setPersona(personaId: string): Promise<void>;
        /**
         * When invoked it will halt ADI operations. Usually this method will
         * be triggered for anonymous patients who reject popup asking
         * for their consent to track their behaviour. It also cleans all data
         * saved by ADI in storage provider
         */
        revokeGDPRConsent(): void;
        /**
         * Captures provided event (only if there is a patient consent to do so)
         * @param event event to register, events are used to build user behaviour
         * @returns {Promise<void>}
         */
        capture: (event: ADIEvent) => Promise<void>;
    }
    export interface Endpoint {
        adiBaseURL: string;
    }
    export interface ADIOptions {
        applicationKey: string;
        gdprProvider?: GDPRConsentProvider;
        personaProvider?: PersonaProvider;
        fingerprintProvider: FingerprintProvider;
        storageProvider: StorageProvider;
        apiClient?: ApiClient;
        endpoint: Endpoint;
    }
    /**
     * Each event MUST extend Payload interface with it's properties.
     */
    export interface Payload {
        e?: any;
        f?: string;
    }
    export interface ADIEvent {
        v: string;
        c: string;
        i: boolean;
        t?: number;
        p?: Payload;
        u?: Patient;
    }
    export abstract class ADIEventImplV1 implements ADIEvent {
        v: string;
        c: string;
        i: boolean;
        t: number;
        p?: Payload | undefined;
        u?: Patient;
        constructor(code: string, immediate: boolean, ts: number, payload: Payload);
    }
}
declare module "iface/event" {
    import { Fingerprint, Payload, ADIEventImplV1 } from "iface/core";
    export interface PayloadKeyPressed extends Payload {
        v: string;
        i: string;
        n: string;
    }
    export interface PayloadTouched extends Payload {
        i: string;
        n: string;
    }
    /**
     * For web based channel this is a page view, for app this is a view/screen show
     */
    export interface PayloadView extends Payload {
        n: string;
        p: string;
    }
    export interface PayloadElementView extends Payload {
        n: string;
        i: string;
    }
    export interface PayloadDeviceInfo extends Payload {
        d: Fingerprint;
    }
    export interface PayloadChannelLogin extends Payload {
        u: string;
    }
    export class ADIKeyPressed extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadKeyPressed, immediate: boolean);
    }
    export class ADITouch extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadTouched, immediate: boolean);
    }
    export class ADIView extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadView, immediate: boolean);
    }
    export class ADIElementView extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadElementView, immediate: boolean);
    }
    export class ADIDeviceInfo extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadDeviceInfo, immediate: boolean);
    }
    export class ADIChannelLogin extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadChannelLogin, immediate: boolean);
    }
    export class ADIChannelLogOut extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadChannelLogin, immediate: boolean);
    }
    export class ADIChannelLoginFailed extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadChannelLogin, immediate: boolean);
    }
}
declare module "impl/integration/adi-integration" {
    import { ApiClient } from "impl/integration/api-client";
    import { Endpoint, ADIEvent } from "iface/core";
    export class ADIIntegration {
        endpoint?: Endpoint;
        client: ApiClient;
        applicationKey: string;
        constructor(applicationKey: string, client: ApiClient, endpoint: Endpoint);
        sendEvent(event: ADIEvent): Promise<void>;
        sendEvents(events: ADIEvent[]): Promise<void>;
    }
}
declare module "impl/integration/storage-providers" {
    import { StorageProvider } from "iface/core";
    export const STORAGE_PROVIDER_DEFAULTS: {
        JOURNEY_ID_NAME: string;
        DEVICE_ID_NAME: string;
        PERSONA_ID_NAME: string;
        COOKIE_EXPIRY_HRS: number;
    };
    export class DefaultProvider implements StorageProvider {
        storeObject(_name: string, _obj: any): void;
        restoreObject(_name: string): any;
        storeString(_name: string, _obj: string): void;
        restoreString(_name: string): string | undefined;
        deleteItem(_name: string): void;
        getToken(): string | null;
        setToken(_token: string | undefined): void;
        deleteToken(): void;
    }
    export class LocalStorageProvider extends DefaultProvider {
        storeObject(name: string, obj: any): void;
        restoreObject(name: string): any;
        storeString(name: string, obj: string): void;
        restoreString(name: string): string | undefined;
        deleteItem(name: string): void;
    }
}
declare module "impl/adi-core-manager" {
    import { ADICoreIface, ADIEvent, GDPRConsentProvider, Patient, PersonaProvider } from "abee-adi-core";
    import { ADIIntegrationAware, ADIOptions, Endpoint, FingerprintProvider, StorageProvider } from "iface/core";
    import { ADIIntegration } from "impl/integration/adi-integration";
    import { ApiClient } from "impl/integration/api-client";
    export class ADICore implements ADICoreIface, ADIIntegrationAware {
        _apiClient: ApiClient;
        _applicationKey?: string;
        _gdprProvider?: GDPRConsentProvider;
        _personaProvider?: PersonaProvider;
        _fingerprintProvider?: FingerprintProvider;
        _storageProvider?: StorageProvider;
        _api?: ADIIntegration;
        _endpoint?: Endpoint;
        _delayedEvents: ADIEvent[];
        patient?: Patient;
        _consentGranted: boolean;
        constructor();
        boot(options: ADIOptions): Promise<Patient>;
        /**
         * Will try to boot/restore as much as possible patient data locally (without exchanging data with any external provider).
         * For journeyId when none is found in storage a new random one is created.
         */
        _bootPatient(): Promise<void>;
        /**
         * Updates patient personaId from external personaProvider
         */
        _updatePersona(): Promise<void>;
        /**
         * Sets persona from external provider via direct call
         * @param personaId
         */
        setPersona(personaId: string): Promise<void>;
        /**
         * Revokes GDPR consent and cleans all data that was recorded
         */
        revokeGDPRConsent(): void;
        /**
         * method to capture user behaviour
         * @param event
         * @returns
         */
        capture(event: ADIEvent): Promise<void>;
        setApiClient(apiClient: ApiClient): void;
        /**
         * Will ask external GDPR Provider for green light to track user behaviour. When no GDPR Provider is provided
         * it is assumed that the consent is granted and eventual revoke of the consent shall be done by the revokeGDPRConsent() method.
         */
        _updateUserConsent(): Promise<void>;
        _clean(): void;
        _sendEvent(event: ADIEvent): Promise<void>;
    }
}
declare module "iface/events-financial" {
    import { ADIEventImplV1, Payload } from "iface/core";
    export interface PayloadFinTransferCustomData {
        [key: string]: any;
    }
    export interface PayloadFinTransferMetadata {
        customerType?: string;
        originationType?: string;
        authenticationType?: string;
        channelType?: string;
        activityType?: string;
        paymentId?: string;
    }
    export interface PayloadFinTransferMerchant {
        categoryCode?: string;
        country?: string;
        identifier?: string;
    }
    export interface PayloadFinTransferCardInfo {
        number?: string;
        accountNumber?: string;
    }
    export interface PayloadFinTransfer extends Payload {
        a: number;
        c: string;
        t: string;
        ma?: PayloadFinTransferMetadata;
        cd?: PayloadFinTransferCustomData;
    }
    export interface PayloadFinTransferCard extends PayloadFinTransfer {
        m?: PayloadFinTransferMerchant;
        cc?: PayloadFinTransferCardInfo;
    }
    /**
     * Represents the address details for a financial transfer party.
     */
    export interface PayloadFinTransferAddress {
        street: string;
        city: string;
        country: string;
        postal_code: string;
    }
    /**
     * Represents a financial transfer party with their details.
     */
    export interface PayloadFinTransferParty {
        name: string;
        account_number: string;
        bank_code: string;
        bank_name: string;
        address: PayloadFinTransferAddress;
    }
    export interface PayloadFinTransferSEPA extends PayloadFinTransfer {
        /**
         * The sender's details.
         */
        s: PayloadFinTransferParty;
        /**
         * The recipient's details.
         */
        r: PayloadFinTransferParty;
    }
    export class ADIFinTransfer extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadFinTransfer, immediate: boolean);
    }
    export class ADIFinTransferCreditCard extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadFinTransferCard, immediate: boolean);
    }
    export class ADIFinTransferSEPA extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadFinTransferSEPA, immediate: boolean);
    }
}
declare module "impl/providers/fingerprint/fingerprint-base-provider" {
    import { BuiltinComponents } from "@fingerprintjs/fingerprintjs";
    import { ADIEventImplV1, Payload } from "iface/core";
    export interface FingerprintBase extends BuiltinComponents {
        deviceId: string;
    }
    export interface PayloadDevice extends Payload {
        e: FingerprintBase;
    }
    export class ADIDevice extends ADIEventImplV1 {
        static CODE: string;
        constructor(payload: PayloadDevice, immediate: boolean);
    }
    /**
     * FingerprintJS 3.x based device identification.
     * As it requires browser global variables like window tests are disabled
     * @param _applicationKey
     * @param _patient
     * @param _apiClient
     * @returns device id, which "may" be unique
     */
    export const fingerprintProvider: () => Promise<FingerprintBase>;
}
declare module "impl/providers/gdpr/gdpr-base-provider" {
    import { ApiClient, Patient } from "abee-adi-core";
    import { GDPRConsentProvider } from "iface/core";
    export interface BaseGDPRProviderOptions {
        baseURL: string;
    }
    /**
     * Base GDPR Provider implementation that is compatible
     * with version 1 of the gdpr provider api.
     */
    export class BaseGDPRProvider {
        _PATH: string;
        _options: BaseGDPRProviderOptions;
        constructor(options: BaseGDPRProviderOptions);
        static getInstance(options: BaseGDPRProviderOptions): BaseGDPRProvider;
        /**
         * Returns GDPR provider function that may be used to initialize ADI Core
         * @returns function that is compatible with ADI GDPR provider
         */
        buildGDPRProvider(): GDPRConsentProvider;
        /**
         * Gets GDPR consent for provided patient data
         * @param applicationKey application key
         * @param {Patient} patient patient data
         * @param apiClient communication client
         * @returns
         */
        _gdprProvider(applicationKey: string, patient: Patient, apiClient?: ApiClient): Promise<boolean>;
    }
}
declare module "abee-adi-core" {
    import { ADICore } from "impl/adi-core-manager";
    export type { ADIEvent, Payload, } from "iface/core";
    export { ADIEventImplV1 } from "iface/core";
    export type { Patient, PatientID } from "iface/model";
    export type { PayloadElementView, PayloadKeyPressed, PayloadTouched, PayloadView, PayloadDeviceInfo, PayloadChannelLogin } from "iface/event";
    export type { PayloadFinTransferCustomData, PayloadFinTransferMetadata, PayloadFinTransferMerchant, PayloadFinTransfer } from "iface/events-financial";
    export { ADIElementView, ADIKeyPressed, ADITouch, ADIView, ADIChannelLogin, ADIChannelLoginFailed, ADIChannelLogOut, ADIDeviceInfo } from "iface/event";
    export { ADIFinTransfer, ADIFinTransferCreditCard } from "iface/events-financial";
    export type { ADICoreIface, GDPRConsentProvider, PersonaProvider, ADIIntegrationAware, Endpoint, FingerprintProvider, StorageProvider, ADIOptions } from "iface/core";
    export { ADICore } from "impl/adi-core-manager";
    export { ADIIntegration } from "impl/integration/adi-integration";
    export type { ApiClient } from "impl/integration/api-client";
    export { ApiClientBrowserFetch } from "impl/integration/api-client";
    export { DefaultProvider, LocalStorageProvider, STORAGE_PROVIDER_DEFAULTS } from "impl/integration/storage-providers";
    export { fingerprintProvider, ADIDevice } from "impl/providers/fingerprint/fingerprint-base-provider";
    export type { FingerprintBase, PayloadDevice } from "impl/providers/fingerprint/fingerprint-base-provider";
    export { BaseGDPRProvider } from "impl/providers/gdpr/gdpr-base-provider";
    export type { BaseGDPRProviderOptions } from "impl/providers/gdpr/gdpr-base-provider";
    export const core: ADICore;
}