@ketch-sdk/ketch-data-layer 1.1.2 → 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/listener/index.d.ts

@@ -1,4 +1,6 @@
-export type Listener = (name: string, value: any) => void;
+/**
+ * ListenerOptions provide an interval and timeout for listening.
+ */
 export type ListenerOptions = {
     interval?: number;
     timeout?: number;

package/dist/mapper/index.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Mapper is a key/value string map.
+ */
 export type Mapper = {
     [key: string]: string;
 };

package/dist/storage/index.d.ts

@@ -1,3 +1,2 @@
 import fetcher from './fetcher';
-import notifier from './notifier';
-export { fetcher, notifier };
+export { fetcher };

package/dist/storage/index.js

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

package/package.json

@@ -1 +1 @@
-{"name": "@ketch-sdk/ketch-data-layer", "version": "1.1.2", "description": "Ketch Data Layer interface", "main": "dist/index.js", "types": "dist/index.d.ts", "scripts": {"all": "npm run lint && npm run format-check && npm run test && npm run build && npm run docs", "build": "tsc -p .", "format": "prettier --write \"**/*.{ts,tsx,yml,yaml}\"", "format-check": "prettier --check '**/*.ts'", "lint": "eslint src/**/*.ts", "test": "jest --runInBand --passWithNoTests", "docs": "typedoc --githubPages true --excludeExternals --excludeInternal src/index.ts"}, "repository": {"type": "git", "url": "git+https://github.com/ketch-sdk/ketch-data-layer.git"}, "homepage": "https://github.com/ketch-sdk/ketch-data-layer", "bugs": {"url": "https://github.com/ketch-sdk/ketch-data-layer/issues"}, "keywords": ["Ketch", "dataLayer"], "author": "Ketch Kloud, Inc.", "license": "MIT", "devDependencies": {"@ketch-sdk/ketch-types": "^1.4.3", "@types/deep-equal": "^1.0.1", "@types/events": "^3.0.0", "@types/jest": "^29.2.5", "@types/node": "^18.11.18", "@types/uuid": "^9.0.0", "@typescript-eslint/eslint-plugin": "^5.48.0", "@typescript-eslint/parser": "^5.48.0", "eslint": "^8.31.0", "eslint-config-prettier": "^8.6.0", "eslint-plugin-import": "^2.26.0", "eslint-plugin-jest": "^27.2.0", "eslint-plugin-prettier": "^4.2.1", "events": "^3.3.0", "jest": "^29.3.1", "jest-environment-jsdom": "^29.3.1", "jest-junit": "^15.0.0", "js-yaml": "^4.1.0", "prettier": "^2.8.1", "ts-jest": "^29.0.3", "typedoc": "^0.23.23", "typescript": "^4.9.4"}, "dependencies": {"deep-equal": "^2.1.0", "uuid": "^9.0.0"}, "files": ["dist/"]}
+{"name": "@ketch-sdk/ketch-data-layer", "version": "1.1.3", "description": "Ketch Data Layer interface", "main": "dist/index.js", "types": "dist/index.d.ts", "scripts": {"all": "npm run lint && npm run format-check && npm run test && npm run build && npm run docs", "build": "tsc -p .", "format": "prettier --write \"**/*.{ts,tsx,yml,yaml}\"", "format-check": "prettier --check '**/*.ts'", "lint": "eslint src/**/*.ts", "test": "jest --runInBand --passWithNoTests", "docs": "typedoc --githubPages true --excludeExternals --excludeInternal src/index.ts"}, "repository": {"type": "git", "url": "git+https://github.com/ketch-sdk/ketch-data-layer.git"}, "homepage": "https://github.com/ketch-sdk/ketch-data-layer", "bugs": {"url": "https://github.com/ketch-sdk/ketch-data-layer/issues"}, "keywords": ["Ketch", "dataLayer"], "author": "Ketch Kloud, Inc.", "license": "MIT", "devDependencies": {"@ketch-sdk/ketch-types": "^1.4.3", "@types/deep-equal": "^1.0.1", "@types/events": "^3.0.0", "@types/jest": "^29.2.5", "@types/node": "^18.11.18", "@types/uuid": "^9.0.0", "@typescript-eslint/eslint-plugin": "^5.48.1", "@typescript-eslint/parser": "^5.48.1", "eslint": "^8.31.0", "eslint-config-prettier": "^8.6.0", "eslint-plugin-import": "^2.26.0", "eslint-plugin-jest": "^27.2.1", "eslint-plugin-prettier": "^4.2.1", "events": "^3.3.0", "jest": "^29.3.1", "jest-environment-jsdom": "^29.3.1", "jest-junit": "^15.0.0", "js-yaml": "^4.1.0", "prettier": "^2.8.2", "ts-jest": "^29.0.3", "typedoc": "^0.23.24", "typescript": "^4.9.4"}, "dependencies": {"deep-equal": "^2.2.0", "uuid": "^9.0.0"}, "files": ["dist/"]}

package/dist/storage/notifier.d.ts

@@ -1,3 +0,0 @@
-import { Listener, ListenerOptions } from '../listener';
-declare const _default: (w: Window, name: string, listener: Listener, _options?: ListenerOptions) => void;
-export default _default;

package/dist/storage/notifier.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = (w, name, listener, _options) => {
-    w.addEventListener('storage', event => {
-        if (event.key === name) {
-            listener(name, event.newValue);
-        }
-    });
-};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibm90aWZpZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc3RvcmFnZS9ub3RpZmllci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUVBLGtCQUFlLENBQUMsQ0FBUyxFQUFFLElBQVksRUFBRSxRQUFrQixFQUFFLFFBQTBCLEVBQVEsRUFBRTtJQUMvRixDQUFDLENBQUMsZ0JBQWdCLENBQUMsU0FBUyxFQUFFLEtBQUssQ0FBQyxFQUFFO1FBQ3BDLElBQUksS0FBSyxDQUFDLEdBQUcsS0FBSyxJQUFJLEVBQUU7WUFDdEIsUUFBUSxDQUFDLElBQUksRUFBRSxLQUFLLENBQUMsUUFBUSxDQUFDLENBQUE7U0FDL0I7SUFDSCxDQUFDLENBQUMsQ0FBQTtBQUNKLENBQUMsQ0FBQSJ9