@ketch-sdk/ketch-data-layer 1.1.1 → 1.1.3

package/README.md

@@ -0,0 +1,201 @@
+# ketch-data-layer
+
+The `ketch-data-layer` library implements a [Watcher](#Watcher) and a set of [Fetcher](#Fetcher) and [Structure](#Structure)
+implementations for fetching and structuring identities.
+
+The following [Fetchers](#Fetcher) are implemented:
+* cookie
+* dataLayer
+* localStorage
+* managed
+* queryString
+* sessionStorage
+* window
+
+The following [Structures](#Structure) are implemented:
+* json
+* jwt
+* queryString
+* semicolon
+* string
+
+## Identity
+
+An Identity can be described using the following interface:
+
+```typescript
+export interface Identity {
+  /**
+   * type is the location on the page from which to retrieve identity information
+   */
+  type: IdentityType;
+
+  /**
+   * variable is the name to look up the identity value in the specified location
+   */
+  variable: string;
+
+  /**
+   * format is the encoding of the value
+   */
+  format: IdentityFormat;
+
+  /**
+   * key is the identifier to find the identity within the value if the format is IDENTITY_FORMAT_STRING
+   * then key will be undefined
+   */
+  key?: string;
+
+  /**
+   * priority of the identity for consent conflict resolution
+   */
+  priority?: number;
+}
+```
+
+Priority is ignored by this library.
+
+## Watcher
+
+The primary class is the `Watcher` which contains a series of registered identities that it watches for changes to.
+
+### Creating a Watcher
+
+```typescript
+const w = new Watcher(window, {interval, timeout})
+```
+
+Creates a new `Watcher` attached to the given `window`. The watcher will poll every `interval` until `timeout` seconds.
+
+### Add an identity
+
+```typescript
+const name: string = ''
+const identity: Identity | (() => Promise<string[]> = {}
+w.add(name, identity)
+```
+
+Registers an identity with the given `name` using the provided `identity` configuration. There are two
+types of configuration allowed.  The first type is an instance of an `Identity` object. If given this,
+the watcher selects from it's know library based on the specification in the `Identity`. The second option,
+which is a function returning a Promise of string values, can be used if the required identity cannot be
+described using `Identity`.
+
+### Start watching
+
+```typescript
+await w.start()
+```
+
+Starts the [Watcher](#Watcher) watching based on the `interval` and `timeout` provided in the constructor.
+
+### Stop watching
+
+```typescript
+w.stop()
+```
+
+Stops the [Watcher](#Watcher).
+
+### Immediately notifying
+
+```typescript
+await w.notify()
+```
+
+Immediately fetches and notifies about identities by emitting an `identities` event.
+
+### Add a listener
+
+```typescript
+const listener: (...args: any[]) => void = () => {}
+w.addListener('identities', listener)
+w.on('identities', listener)
+```
+
+Add a listener function that gets called each time identities change. The argument to the listener
+will be an `Identities` map.
+
+### Add a one-time listener
+
+```typescript
+const listener: (...args: any[]) => void = () => {}
+w.once('identities', listener)
+```
+
+Adds a one-time listener function. The argument to the listener
+will be an `Identities` map.
+
+### Remove a listener
+
+```typescript
+const listener: (...args: any[]) => void = () => {}
+w.removeListener('identities', listener)
+w.off('identities', listener)
+```
+
+Removes the given listener.
+
+### Remove all listeners
+
+```typescript
+w.removeAllListeners('identities')
+```
+
+Removes all listeners.
+
+## Fetcher
+
+A `Fetcher` is a function with the following signature:
+
+```typescript
+type Fetcher = async (w: Window, name: string) => Promise<any[]>
+```
+
+The `w` parameter is the `Window` to attach to. The `name` is the name of the identity. The return
+must be an array of discovered, structured identities. The structured identities will be destructured
+using a [Structure](#Structure) function to provide the identity value.
+
+## Structure
+
+A `Structure` is a function with the following signature:
+
+```typescript
+type Mapper = {
+  [key: string]: string
+}
+
+type Structure = (value: any) => Mapper
+```
+
+Given some structured value, the job of the `Structure` function is to return a key-value map representing the
+values in that structure. If there is only a single identifiable value, then the key should be `value`.
+
+## Cookie
+
+This library also exposes some utility functions that may be useful outside of the library's core purpose.
+
+### getCookie
+
+```typescript
+import { getCookie } from '@ketch-sdk/ketch-data-layer/cookie'
+
+const name: string = ''
+const value = getCookie(window, name)
+```
+
+Retrieves the full raw value of the cookie with the given name.
+
+### setCookie
+
+```typescript
+import { setCookie } from '@ketch-sdk/ketch-data-layer/cookie'
+
+const name: string = ''
+const value: any = ''
+const ttl: number = 2 // 2 days
+setCookie(window, name, value, ttl)
+```
+
+Sets the value of the cookie with the given name. The TTL of the cookie is set to `ttl` days. Note that
+long-lasting cookies are subject to [Intelligent Tracking Prevention](https://webkit.org/tracking-prevention-policy/) limitations.

package/dist/cookie/fetcher.js

@@ -0,0 +1,26 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const util_1 = require("./util");
+function cookieFetcher(w, name) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!w || name.length === 0) {
+            return [];
+        }
+        const pv = (0, util_1.getCookie)(w, name);
+        if (!pv || pv === '0') {
+            return [];
+        }
+        return [pv];
+    });
+}
+exports.default = cookieFetcher;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmV0Y2hlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9jb29raWUvZmV0Y2hlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7OztBQUFBLGlDQUFrQztBQUVsQyxTQUE4QixhQUFhLENBQUMsQ0FBUyxFQUFFLElBQVk7O1FBQ2pFLElBQUksQ0FBQyxDQUFDLElBQUksSUFBSSxDQUFDLE1BQU0sS0FBSyxDQUFDLEVBQUU7WUFDM0IsT0FBTyxFQUFFLENBQUE7U0FDVjtRQUVELE1BQU0sRUFBRSxHQUFHLElBQUEsZ0JBQVMsRUFBQyxDQUFDLEVBQUUsSUFBSSxDQUFDLENBQUE7UUFDN0IsSUFBSSxDQUFDLEVBQUUsSUFBSSxFQUFFLEtBQUssR0FBRyxFQUFFO1lBQ3JCLE9BQU8sRUFBRSxDQUFBO1NBQ1Y7UUFFRCxPQUFPLENBQUMsRUFBRSxDQUFDLENBQUE7SUFDYixDQUFDO0NBQUE7QUFYRCxnQ0FXQyJ9

package/dist/cookie/index.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setCookie = exports.getCookie = exports.fetcher = void 0;
+const fetcher_1 = __importDefault(require("./fetcher"));
+exports.fetcher = fetcher_1.default;
+const util_1 = require("./util");
+Object.defineProperty(exports, "getCookie", { enumerable: true, get: function () { return util_1.getCookie; } });
+Object.defineProperty(exports, "setCookie", { enumerable: true, get: function () { return util_1.setCookie; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvY29va2llL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7OztBQUFBLHdEQUErQjtBQUd0QixrQkFIRixpQkFBTyxDQUdFO0FBRmhCLGlDQUE2QztBQUUzQiwwRkFGVCxnQkFBUyxPQUVTO0FBQUUsMEZBRlQsZ0JBQVMsT0FFUyJ9

package/dist/cookie/util.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setCookie = exports.getCookie = void 0;
+/**
+ * Get a value from a cookie by the key.
+ *
+ * @param w The window object
+ * @param key The cookie key
+ */
+function getCookie(w, key) {
+    return w.document.cookie.split('; ').reduce((r, v) => {
+        const parts = v.split('=');
+        return parts[0] === key ? decodeURIComponent(parts[1]) : r;
+    }, '');
+}
+exports.getCookie = getCookie;
+/**
+ * Set the value against the given key
+ *
+ * @param w The window object
+ * @param key The cookie key
+ * @param value The value to set
+ * @param ttl The TTL of the cookie value in days
+ */
+function setCookie(w, key, value, ttl) {
+    const days = ttl || 1;
+    const expires = new Date(Date.now() + days * 864e5).toUTCString();
+    const hostnameParts = w.document.location.hostname.split('.');
+    const details = `${key}=${encodeURIComponent(value)}; expires=${expires}; path=/; SameSite=None; Secure`;
+    // try to set cookie for last i parts of the domain
+    // if cookie not found (likely because domain in public suffix list), retry with an additional part on the domain
+    for (let i = 2; i <= hostnameParts.length; i++) {
+        // set cookie
+        w.document.cookie = `${details}; domain=${hostnameParts.slice(-1 * i).join('.')}`;
+        // return if set, otherwise retry with an additional part on the domain
+        if (getCookie(w, key)) {
+            return;
+        }
+    }
+    // set cookie without domain if hostnameParts.length < 2 or other error
+    w.document.cookie = details;
+}
+exports.setCookie = setCookie;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXRpbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9jb29raWUvdXRpbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQTs7Ozs7R0FLRztBQUNILFNBQWdCLFNBQVMsQ0FBQyxDQUFTLEVBQUUsR0FBVztJQUM5QyxPQUFPLENBQUMsQ0FBQyxRQUFRLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxFQUFFLEVBQUU7UUFDbkQsTUFBTSxLQUFLLEdBQUcsQ0FBQyxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsQ0FBQTtRQUMxQixPQUFPLEtBQUssQ0FBQyxDQUFDLENBQUMsS0FBSyxHQUFHLENBQUMsQ0FBQyxDQUFDLGtCQUFrQixDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUE7SUFDNUQsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFBO0FBQ1IsQ0FBQztBQUxELDhCQUtDO0FBRUQ7Ozs7Ozs7R0FPRztBQUNILFNBQWdCLFNBQVMsQ0FBQyxDQUFTLEVBQUUsR0FBVyxFQUFFLEtBQVUsRUFBRSxHQUFZO0lBQ3hFLE1BQU0sSUFBSSxHQUFHLEdBQUcsSUFBSSxDQUFDLENBQUE7SUFDckIsTUFBTSxPQUFPLEdBQUcsSUFBSSxJQUFJLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxHQUFHLElBQUksR0FBRyxLQUFLLENBQUMsQ0FBQyxXQUFXLEVBQUUsQ0FBQTtJQUNqRSxNQUFNLGFBQWEsR0FBRyxDQUFDLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxDQUFBO0lBRTdELE1BQU0sT0FBTyxHQUFHLEdBQUcsR0FBRyxJQUFJLGtCQUFrQixDQUFDLEtBQUssQ0FBQyxhQUFhLE9BQU8saUNBQWlDLENBQUE7SUFFeEcsbURBQW1EO0lBQ25ELGlIQUFpSDtJQUNqSCxLQUFLLElBQUksQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDLElBQUksYUFBYSxDQUFDLE1BQU0sRUFBRSxDQUFDLEVBQUUsRUFBRTtRQUM5QyxhQUFhO1FBQ2IsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxNQUFNLEdBQUcsR0FBRyxPQUFPLFlBQVksYUFBYSxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQTtRQUVqRix1RUFBdUU7UUFDdkUsSUFBSSxTQUFTLENBQUMsQ0FBQyxFQUFFLEdBQUcsQ0FBQyxFQUFFO1lBQ3JCLE9BQU07U0FDUDtLQUNGO0lBRUQsdUVBQXVFO0lBQ3ZFLENBQUMsQ0FBQyxRQUFRLENBQUMsTUFBTSxHQUFHLE9BQU8sQ0FBQTtBQUM3QixDQUFDO0FBckJELDhCQXFCQyJ9

package/dist/dataLayer/fetcher.js

@@ -0,0 +1,30 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+function dataLayerFetcher(w, name) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!w || !w.dataLayer || name.length === 0) {
+            return [];
+        }
+        let out = [];
+        for (const dl of w.dataLayer) {
+            if (Object.prototype.hasOwnProperty.call(dl, name)) {
+                const pv = dl[name];
+                if (pv && pv !== '0') {
+                    out = out.concat(pv);
+                }
+            }
+        }
+        return out;
+    });
+}
+exports.default = dataLayerFetcher;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmV0Y2hlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYXRhTGF5ZXIvZmV0Y2hlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7OztBQU1BLFNBQThCLGdCQUFnQixDQUFDLENBQVMsRUFBRSxJQUFZOztRQUNwRSxJQUFJLENBQUMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLFNBQVMsSUFBSSxJQUFJLENBQUMsTUFBTSxLQUFLLENBQUMsRUFBRTtZQUMzQyxPQUFPLEVBQUUsQ0FBQTtTQUNWO1FBRUQsSUFBSSxHQUFHLEdBQVUsRUFBRSxDQUFBO1FBRW5CLEtBQUssTUFBTSxFQUFFLElBQUksQ0FBQyxDQUFDLFNBQVMsRUFBRTtZQUM1QixJQUFJLE1BQU0sQ0FBQyxTQUFTLENBQUMsY0FBYyxDQUFDLElBQUksQ0FBQyxFQUFFLEVBQUUsSUFBSSxDQUFDLEVBQUU7Z0JBQ2xELE1BQU0sRUFBRSxHQUFHLEVBQUUsQ0FBQyxJQUFJLENBQUMsQ0FBQTtnQkFDbkIsSUFBSSxFQUFFLElBQUksRUFBRSxLQUFLLEdBQUcsRUFBRTtvQkFDcEIsR0FBRyxHQUFHLEdBQUcsQ0FBQyxNQUFNLENBQUMsRUFBRSxDQUFDLENBQUE7aUJBQ3JCO2FBQ0Y7U0FDRjtRQUVELE9BQU8sR0FBRyxDQUFBO0lBQ1osQ0FBQztDQUFBO0FBakJELG1DQWlCQyJ9

package/dist/dataLayer/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetcher = void 0;
+const fetcher_1 = __importDefault(require("./fetcher"));
+exports.fetcher = fetcher_1.default;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZGF0YUxheWVyL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7OztBQUFBLHdEQUErQjtBQUV0QixrQkFGRixpQkFBTyxDQUVFIn0=