Add witness API, used to send events to sandbox. (#12)

Author: bmilekic

README.md

@@ -101,6 +101,32 @@ sdk
 
 On success, the resulting key values are typically sent as part of a subsequent ad call. Therefore we recommend that you either call targeting() before each ad call, or in parallel periodically, caching the resulting key values which you then provide in ad calls.
 
+### Witness API
+
+To send real-time event data from the user's browser to the sandbox for eventual audience assembly, you can call the witness API as follows:
+
+```js
+const onSuccess = () => console.log("Witness API success!");
+const onFailure = (err) => console.warn("Witness API error: ${err.message}");
+
+const eventProperties = {
+  property_one: "some_value",
+  property_two: "some other value",
+};
+
+sdk.witness("event.type.here", eventProperties).then(onSuccess).catch(onFailure);
+```
+
+The specified event type and properties are associated with the logged event and which can be used for matching during audience assembly.
+
+Note that event properties are string keyvalue pairs and have type `WitnessProperties`:
+
+```typescript
+type WitnessProperties = {
+  [key: string]: string;
+};
+```
+
 ## Usage (script tag)
 
 For each [SDK release](https://github.com/Optable/optable-web-sdk/releases), a webpack generated browser bundle targeting the browsers list described by `npx browserslist "> 0.25%, not dead"` can be loaded on a web site via a `script` tag. As previously mentioned, your sandbox is configured to serve such a released browser bundle via the `https://sandbox.customer.com/static/web/sdk.js` URL by default.

lib/edge/witness.ts

@@ -0,0 +1,24 @@
+import type { SandboxConfig } from "../config";
+import { fetch } from "../core/network";
+
+type WitnessProperties = {
+  [key: string]: string;
+};
+
+function Witness(config: SandboxConfig, event: string, properties: WitnessProperties): Promise<void> {
+  const evt = {
+    event: event,
+    properties: properties,
+  };
+
+  return fetch("/witness", config, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(evt),
+  });
+}
+
+export { Witness, WitnessProperties };
+export default Witness;

lib/sdk.ts

@@ -1,8 +1,10 @@
 import type { SandboxConfig } from "./config";
 import type { TargetingKeyValues } from "./edge/targeting";
+import type { WitnessProperties } from "./edge/witness";
 import type { AuthModalDOMConfig, MicroModalConfig } from "./ui/auth_modal";
 import Identify from "./edge/identify";
 import Targeting from "./edge/targeting";
+import Witness from "./edge/witness";
 import AuthModal from "./ui/auth_modal";
 import { sha256 } from "js-sha256";
 
@@ -28,6 +30,10 @@ class SDK {
     return Targeting(this.sandbox);
   }
 
+  witness(event: string, properties: WitnessProperties = {}): Promise<void> {
+    return Witness(this.sandbox, event, properties);
+  }
+
   authenticator(DOMConfig?: AuthModalDOMConfig, MicroModalConfig?: MicroModalConfig): AuthModal {
     return new AuthModal(this.sandbox, DOMConfig, MicroModalConfig);
   }