ketch-data-layer

The ketch-data-layer library implements a Watcher and a set of Fetcher and Structure
implementations for fetching and structuring identities.

The following Fetchers are implemented:
* cookie
* dataLayer
* localStorage
* managed
* queryString
* sessionStorage
* window

The following Structures 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.

$3

`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.

$3

`typescript
const name: string = ''
const identity: Identity | (() => Promise = {}
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.

$3

`typescript
await w.start()
`

Starts the Watcher watching based on the interval and timeout provided in the constructor.

$3

`typescript
w.stop()
`

Stops the Watcher.

$3

`typescript
await w.notify()
`

Immediately fetches and notifies about identities by emitting an identities event.

$3

`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.

$3

`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.

$3

`typescript
const listener: (...args: any[]) => void = () => {}
w.removeListener('identities', listener)
w.off('identities', listener)
`

Removes the given listener.

$3

`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
`

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 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.

$3

`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.

$3

`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 limitations.