WIP: feat: add core interfaces and classes

src/core/crosslytics.spec.ts

@@ -0,0 +1,42 @@
+import test from "ava";
+import { Crosslytics } from "./crosslytics";
+import { TrackedEvent } from "./trackedEvent";
+import { Tracker } from "./tracker";
+import { Identity } from "./identity";
+
+type TestEventArgs = {
+  "Color": string;
+};
+
+class TestEvent extends TrackedEvent<TestEventArgs> {
+  name = "Test Event";
+  category = "Test Category";
+  organizationId = "abc123";
+  argPriority = new Array<keyof TestEventArgs>();
+}
+
+class TestTracker implements Tracker {
+  public track<T>(identity: Identity, event: TrackedEvent<T>) {
+    return Promise.resolve();
+  }
+}
+
+test("Should only register a Tracker once", t => {
+  const cl = new Crosslytics();
+  const tracker = new TestTracker();
+  cl.registerTracker(tracker);
+  cl.registerTracker(tracker);
+  t.is(cl.trackers.length, 1);
+});
+
+test("Should deregister a Tracker", t => {
+  const cl = new Crosslytics();
+  const trackerA = new TestTracker();
+  const trackerB = new TestTracker();
+  cl.registerTracker(trackerA);
+  cl.registerTracker(trackerB);
+  t.is(cl.trackers.length, 2);
+  cl.deregisterTracker(trackerB);
+  cl.deregisterTracker(trackerB);
+  t.is(cl.trackers.length, 1);
+});

src/core/crosslytics.ts

@@ -0,0 +1,30 @@
+import { Identity } from "./identity";
+import { TrackedEvent } from "./trackedEvent";
+import { Tracker } from "./tracker";
+
+/**
+ * Main API entry point
+ */
+export class Crosslytics {
+  public identity: Identity;
+
+  public readonly trackers = new Array<Tracker>();
+  public registerTracker(tracker: Tracker) {
+    if (~this.trackers.indexOf(tracker)) {
+      return;
+    }
+
+    this.trackers.push(tracker);
+  }
+
+  public deregisterTracker(tracker: Tracker) {
+    const index = this.trackers.indexOf(tracker);
+    if (~index) {
+      this.trackers.splice(index, 1);
+    }
+  }
+
+  public async track<T>(event: TrackedEvent<T>) {
+    return this.trackers.map(t => t.track(this.identity, event));
+  }
+}

src/core/identity.ts

@@ -0,0 +1,16 @@
+import { Organization } from "./organization";
+import { Value } from "./value";
+
+/**
+ * A user that you're tracking. Logically equivalent to an Identity in the Segment spec.
+ * @see {@link https://segment.com/docs/spec/identify/#identities}
+ */
+export interface Identity {
+  userId: string;
+  organization?: Organization;
+  traits?: {
+    email: string;
+    name: string;
+    [key: string]: Value;
+  };
+}

src/core/organization.ts

@@ -0,0 +1,13 @@
+import { Value } from "./value";
+
+/**
+ * A group of users. Logically equivalent to a Group in the Segment spec.
+ * @see {@link https://segment.com/docs/spec/group/}
+ */
+export interface Organization {
+  organizationId: string;
+  traits?: {
+    name: string;
+    [key: string]: Value;
+  };
+}

src/core/trackedEvent.ts

@@ -0,0 +1,45 @@
+import { Value } from "./value";
+
+/**
+ * A user action. Logically equivalent to an Event in the Segment spec.
+ * Pass in a type defining your event's arguments.
+ * @example
+ * type DashboardPanelEventArgs = {
+ *   'Panel ID': string,
+ *   'Panel Color'?: string,
+ *   'Panel Type'?: number,
+ *   'Panel Name'?: string
+ * };
+ * class DashboardPanelCreated extends TrackedEvent<DashboardPanelEventArgs> {
+ *   readonly name = 'DashboardPanel Created';
+ *   readonly category = 'Dashboard';
+ *   readonly argPriority: (keyof DashboardPanelEventArgs)[] = [
+ *     'Panel ID',
+ *     'Panel Type',
+ *     'Panel Name',
+ *     'Panel Color'
+ *   ];
+ * }
+ * @see {@link https://segment.com/docs/spec/track/#event}
+ */
+export abstract class TrackedEvent<T> {
+  /**
+   * We suggest human readable names consisting of noun + past tense verb.
+   * @see {@link https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/}
+   */
+  public abstract readonly name: string;
+  public abstract readonly category: string;
+  public organizationId: string;
+
+  /**
+   * Many trackers only support a limited number of arguments. For example,
+   * Google Analytics only supports 2: a string Event Label and an integer 
+   * Event Value. By defining a priority to your arguments here, trackers
+   * will submit the highest priority args satisfying their constraints. In
+   * the Google Analytics case, the tracker will submit the first string match
+   * as the Label and the first integer match as the Value.
+   */
+  public abstract readonly argPriority: Array<keyof T>;
+
+  constructor(public args: T) {}
+}

src/core/tracker.ts

@@ -0,0 +1,10 @@
+import { Identity } from "./identity";
+import { TrackedEvent } from "./trackedEvent";
+
+/**
+ * A Tracker is a 3rd party analytics service such as Google Analytics or Intercom
+ * that ultimately receives your `TrackedEvent`s.
+ */
+export interface Tracker {
+  track<T>(identity: Identity, event: TrackedEvent<T>): Promise<void>;
+}

src/core/value.ts

@@ -0,0 +1 @@
+export type Value = string | number;

src/index.ts

@@ -1 +1,5 @@
-export * from "./greeter";
+export * from "./core/crosslytics";
+export * from "./core/identity";
+export * from "./core/organization";
+export * from "./core/trackedEvent";
+export * from "./core/tracker";

tsconfig.json

@@ -6,8 +6,9 @@
     "lib": [
       "esnext"
     ],
-    "target": "es2015",
+    "target": "es6",
     "noImplicitAny": true,
+    "strictNullChecks": true,
     "outDir": "./lib",
     "preserveConstEnums": true,
     "removeComments": true,

tsconfig.test.json

@@ -1,7 +1,7 @@
 {
   "compilerOptions": {
     "module": "commonjs",
-    "target": "es5",
+    "target": "es6",
     "outDir": "lib_test",
     "declaration": false,
     "noImplicitAny": true,

tslint.json

@@ -2,5 +2,9 @@
   "extends": [
     "tslint:latest",
     "tslint-config-prettier"
-  ]
+  ],
+  "rules": {
+    "interface-name": [true, "never-prefix"],
+    "quotemark": [ true, "single" ]
+  }
 }