[HELPS-3198] document and publish to npm (#6)

* Documentation

* Github workflows

* Fix broken code example

Author: ulricesparra-oliveai

.github/workflows/javascript.yml

@@ -0,0 +1,31 @@
+# This workflow will do a clean install of node dependencies, build the source code,
+# and run linting/tests across different versions of node.
+# For more information see:
+#   https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: Javascript CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [12.x, 14.x]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm set audit false
+      - run: npm ci
+      - run: npm audit --production --audit-level=low
+      - run: npm run build --if-present
+      - run: npm run lint
+      - run: npm run test --if-present

.github/workflows/npm.yml

@@ -0,0 +1,32 @@
+# This workflow will do a clean install of node dependencies, build the source code,
+# and publish to NPM.
+# For more information, see:
+#   https://docs.github.com/en/actions/language-and-framework-guides/publishing-nodejs-packages#publishing-packages-to-the-npm-registry
+
+name: NPM Publish
+
+on:
+  release:
+    types: [ published ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 14
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.x
+      - run: npm set audit false
+      - run: npm ci
+      - run: npm run test --if-present
+      - run: npm run build --if-present
+      - run: printf '\n//registry.npmjs.org/:_authToken=${NPM_TOKEN}' >> .npmrc
+      - run: npm publish --access public
+        env:
+          # `secrets.NPM_TOKEN` references a GitHub Secret configured for this repo or organization,
+          # and is used to authenticate for the NPM publish command.
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -1,49 +1,168 @@
-# Segment LDK
+# Loop Analytics Library
 
-This wrapper library makes use of [Segment](https://segment.com/docs/) to send loop data to analytics services like GA and Mixpanel. Its intent is to make it easier for developers to add analytics to loops, reduce code bloat and most importantly to be consistent with event trigger names/labels. Feel free to change the types to match event trigger names specific for your use case.
+This library makes use of the LDK's Network aptitude to support analytics within loops through builtin analytics services or can be extended to support custom services
 
-## How to use
+Currently supported out of the box:
 
-In the root file that starts the loop, add the following ahead of prior code.
+- [Google Analytics (Universal)](https://developers.google.com/analytics/devguides/collection/protocol/v1)
+- [Segment](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api/)
 
-```js
-import User from '../user';
-import Segment from 'loop-segment';
+## How to Use
 
-  /*
-  * We are using userId from user.jwt() aptitude (part of @oliveai/ldk) which has been
-  * abstracted to a separate class User. But the Segment userId can be populated from other
-  * id sources to fit your use case.
-  */
-  const { userId } = await User.getUser();
-  Segment.init({
-    loopName: 'KnowledgeReference Loop',
-    userId,
-    writeKey: 'this is found in segment sources settings',
-  });
-```
+### 1. Add the necessary aptitude permissions to your loop's `package.json`
 
-You should receive a Segment tracking event in your account, that says "Loop Started"
+The only required aptitude is `network` to make requests to the analytics service you choose. Some other aptitudes that can be helpful are `user` for getting the user's information and `system` for getting the user's operating system.
 
-To use the rest of the methods, add them in where necessary in the code (e.g. `Segment.whisperDisplayed(Markdown, true)`). Be sure to update the `types` when creating new event names to be triggered in the loops.
+> Note: Use the information from `user` and `system` aptitudes at your own risk. PII and PHI should **NEVER** be sent to an analytics service, only the minimum required info that is helpful for metrics should be used. If you are unsure whether your information would be considered PII or PHI or you don't need this info for your metrics, err on the side of caution and omit these aptitudes altogether.
 
-## Important Notes
+#### Network Aptitude URLs for the provided Transports
 
-- Be sure to add the network and user permissions in your loop like so,
+| Transport |         URL          |
+| :-------: | :------------------: |
+|  Google   | google-analytics.com |
+|  Segment  |    api.segment.io    |
 
 ```json
-      "network": {
-        "urlDomains": [
-          {
-            "value": "api.segment.io"
-          }
-        ]
-      },
+{
+  ...
+  "ldk": {
+    "permissions": {
+      "whisper": {},
+      "system": {},
       "user": {
-        "optionalClaims": [
-          {
-            "value": "email"
-          }
-        ]
+        "optionalClaims": [{ "value": "email" }]
+      },
+      "network": {
+        "urlDomains": [{ "value": "google-analytics.com" }]
       }
+    }
+  }
+}
+```
+
+### 2. Set up the Analytics Client with your desired Transport
+
+In this example we setup and export the Google Analytics client in a separate file to make it accessible across the loop
+
+```ts
+// analytics.ts
+import { user, system } from '@oliveai/ldk';
+import { AnalyticsClient, Transports } from '@oliveai/loop-analytics';
+import jwtDecode from 'jwt-decode';
+
+import { LOOP_NAME } from './index';
+
+const createAnalyticsClient = async () => {
+  // Helper function to fetch the user's JWT and decode the payload
+  const getUserInfo = async () =>
+    jwtDecode<{ email: string; org: string; sub: string }>(
+      await user.jwt({ includeEmail: true })
+    );
+
+  // Get the info we need from LDK
+  const { sub: userId, email, org } = await getUserInfo();
+  const os = await system.operatingSystem();
+
+  // Define required and custom category/action pairings
+  // Export outside of this function to use across the loop for custom events if you'd like
+  const categoryActionMap: Transports.GoogleTransportTypes.CategoryActionMap = {
+    // === Required ===
+    whisperDisplayed: {
+      category: 'Whispers',
+      action: 'Whisper Displayed',
+    },
+    whisperClosed: {
+      category: 'Whispers',
+      action: 'Whisper Closed',
+    },
+    componentClicked: {
+      category: 'Click Events',
+      action: 'Component Clicked',
+    },
+    componentCopied: {
+      category: 'Click Events',
+      action: 'Component Copied',
+    },
+    // === Custom (Optional) ===
+    customEvent: {
+      category: 'Custom',
+      action: 'Custom Event',
+    },
+  };
+
+  // An example of how to set custom dimensions, use whatever is appropriate
+  const customDimensions: Transports.GoogleTransportTypes.CustomDimensionOrMetric[] =
+    [
+      {
+        index: 1,
+        name: 'Loop Name',
+        value: LOOP_NAME,
+      },
+      {
+        index: 2,
+        name: 'User ID',
+        value: userId, // The user's generated ID in Loop Library, not considered PII
+      },
+      {
+        index: 3,
+        name: 'Email Domain',
+        value: email.split('@')[1], // ONLY send the email domain, full email would be PII
+      },
+      {
+        index: 4,
+        name: 'Organization',
+        value: org,
+      },
+      {
+        index: 5,
+        name: 'Operating System',
+        value: os,
+      },
+    ];
+
+  const transportConfig: Transports.GoogleTransportTypes.GoogleTransportConfig =
+    {
+      trackingId: 'UA-12345678-90',
+      // Can be whatever you want but is required for Google's request headers
+      userAgent: LOOP_NAME,
+      categoryActionMap,
+      customDimensions,
+    };
+
+  const userConfig: Transports.UserConfig = {
+    id: userId,
+  };
+  const loopConfig: Transports.LoopConfig = {
+    name: LOOP_NAME,
+  };
+
+  return new AnalyticsClient(
+    new Transports.GoogleTransport(transportConfig, userConfig, loopConfig)
+  );
+};
+
+// One example of how to export the client in a way that is accessible across the loop
+export default await createAnalyticsClient();
+```
+
+### 3. Use the new Analytics Client wherever it's needed
+
+```ts
+// index.ts
+import { whisper } from '@oliveai/ldk';
+import GA from './analytics';
+
+export const LOOP_NAME = 'My Awesome Loop';
+
+(async () => {
+  const label = 'Hello World!';
+
+  whisper.create({
+    label,
+    components: [],
+    onClose: () => GA.trackWhisperClosed(label),
+  });
+
+  GA.trackWhisperDisplayed(label, false);
+})();
 ```

src/index.ts

@@ -4,34 +4,65 @@ import { Component, WhisperComponentType } from '@oliveai/ldk/dist/whisper';
 
 import * as Transports from './transports';
 
+/**
+ * Main class for interacting with different analytics providers
+ * Must be provided a Transport at construction or before calling any track methods
+ */
 class AnalyticsClient {
   constructor(public transport?: Transports.BaseTransport) {}
 
+  /** Provided for setting the transport after instancing */
   setTransport(transport: Transports.BaseTransport) {
     this.transport = transport;
   }
 
+  /**
+   * Default method for what to do when a whisper is displayed
+   *
+   * @param whisperName Either the label or a distinct name for the whisper
+   * @param isUpdated Whether the whisper was displayed through create or update
+   */
   async trackWhisperDisplayed(whisperName: string, isUpdated: boolean) {
     if (!this.transport) return;
     await this.transport.trackWhisperDisplayed(whisperName, isUpdated);
   }
 
+  /**
+   * Default method for what to do when a whisper is closed
+   *
+   * @param whisperName Either the label or a distinct name for the whisper
+   */
   async trackWhisperClosed(whisperName: string) {
     if (!this.transport) return;
     await this.transport.trackWhisperClosed(whisperName);
   }
 
+  /**
+   * Default method for what to do when a component's onClick handler is triggered
+   *
+   * @param componentType The LDK provided identifier for the type of component
+   */
   async trackComponentClicked(componentType: WhisperComponentType) {
     if (!this.transport) return;
     await this.transport.trackComponentClicked(componentType);
   }
 
+  /**
+   * Default method for what to do when a component's onCopy handler is triggered
+   *
+   * @param componentType The LDK provided identifier for the type of component
+   */
   async trackComponentCopied(componentType: WhisperComponentType) {
     if (!this.transport) return;
     await this.transport.trackComponentCopied(componentType);
   }
 
-  async trackEvent(props: any) {
+  /**
+   * Generic tracking method, up to the Transport to define what the props should be
+   *
+   * @param props Some kind of object passed through to the Transport for handling events
+   */
+  async trackEvent(props: Record<string, unknown>) {
     if (!this.transport) return;
     await this.transport.trackEvent(props);
   }

src/transports/base/index.ts

@@ -4,33 +4,52 @@ import { LoopConfig, TransportConfig, UserConfig } from './types';
 
 export * from './types';
 
+/**
+ * Abstract for all Transports to extend
+ *
+ * @param TransportConfig Defines properties for the Transport's client itself, such as auth keys, custom parameters, etc
+ * @param UserConfig Defines properties for the user, such as their id, etc
+ * @param LoopConfig Defines properties for the loop, such as the name, etc
+ */
 export abstract class BaseTransport<
   T extends TransportConfig = TransportConfig,
   U extends UserConfig = UserConfig,
   L extends LoopConfig = LoopConfig
 > {
+  // Keep track of which whisper we're on so events can tie to it as a page if needed
   currentWhisperName?: string;
 
+  // All Transports need a baseUrl for the HTTP Requests
   abstract baseUrl: string;
 
+  // Set up the Transport with default or extended configs
   constructor(readonly transportConfig: T, readonly userConfig: U, readonly loopConfig: L) {}
 
+  // All Transports will be using LDK's network call, this helper method reduces redundancy
   protected static async send(request: network.HTTPRequest) {
     const { statusCode } = await network.httpRequest(request);
     if (statusCode < 200 || statusCode >= 300) {
       console.error(`Request failed with status code ${statusCode}: ${request.url}`);
     }
   }
 
+  // === Abstracts for every Transport to implement ===
+
+  /** @see {@link AnalyticsClient.trackWhisperDisplayed} */
   abstract trackWhisperDisplayed(name: string, isUpdated: boolean): Promise<void>;
 
+  /** @see {@link AnalyticsClient.trackWhisperClosed} */
   abstract trackWhisperClosed(name: string): Promise<void>;
 
+  /** @see {@link AnalyticsClient.trackComponentClicked} */
   abstract trackComponentClicked(type: whisper.WhisperComponentType): Promise<void>;
 
+  /** @see {@link AnalyticsClient.trackComponentCopied} */
   abstract trackComponentCopied(type: whisper.WhisperComponentType): Promise<void>;
 
+  /** @see {@link AnalyticsClient.trackEvent} */
   abstract trackEvent(props: any): Promise<void>;
 
+  /** All Transports should have a method for building the request used in Transport.send */
   protected abstract buildRequest(...args: any[]): network.HTTPRequest;
 }