QS

Author: winsmith

README.md

@@ -1,16 +1,52 @@
 # Telemetry Deck JavaScript SDK
 
-This package allows you to send signals to [TelemetryDeck](https://telemetrydeck.com) from your JavaScript code.
+This package allows you to send signals to [TelemetryDeck](https://telemetrydeck.com) from JavaScript code.
+
+> [!NOTE]  
+> If you want to use TelemetryDeck for your blog or static website, we recommend the [TelemetryDeck Web SDK](https://github.com/TelemetryDeck/WebSDK) instead of this JavaScript SDK. 
 
 It has no dependencies and supports **modern evergreen browsers** and modern versions of Node.js with support for [cryptography](https://caniuse.com/cryptography).
 
-Signals sent with this SDK do not send any default values, besides signal `type`, `appID`, `user` and `sessionID`.
+## Usage
 
-If you want to use this package in your web application, see recommended parameters below.
+### Usage in Browser Based Applications that use a bundler (React, Vue, Angular, Svelte, Ember, …)
 
-## Usage
+#### 1. Install the package
 
-### 📦 Advanced usage for applications that use a bundler (like Webpack, Rollup, …)
+Please install the package using npm or the package manager of your choice
+
+#### 2. Initialize TelemetryDeck
+
+Initialize the TelemetryDeck SDK with your app ID and your user's user identifer. 
+
+```javascript
+import TelemetryDeck from '@telemetrydeck/sdk';
+
+const td = new TelemetryDeck({
+  appID: '<YOUR_APP_ID>'
+  user: '<YOUR_USER_IDENTIFIER>',
+});
+```
+
+Please replace `<YOUR_APP_ID>` with the app ID in TelemetryDeck ([Dashboard](https://dashboard.telemetrydeck.com) -> App -> Set Up App). 
+
+You also need to identify your logged in user. Instead of `<YOUR_USER_IDENTIFIER>`, pass in any string that uniquely identifies your user, such as an email address. It will be cryptographically anonymized with a hash function.
+
+```javascript
+// Basic signal
+td.signal('<SIGNAL_TYPE>');
+
+// Advanced: Signal with custom payload
+td.signal('<SIGNAL_TYPE>', {
+  volume: '11',
+});
+```
+
+
+
+If you want to pass optional parameters to the signal being sent, add them to the optional payload object.
+
+### Usage in Node.js Applications
 
 After installing the package via NPM, use it like this:
 
@@ -35,10 +71,29 @@ Please replace `YOUR_APP_ID` with the app ID you received from TelemetryDeck. If
 
 If you want to pass optional parameters to the signal being sent, add them to the optional payload object.
 
-## Usage with React Native
+
+#### Usage with React Native
 
 React Native does not support the `crypto` module, which is required for the SDK to work. We found [react-native-quick-crypto](https://github.com/margelo/react-native-quick-crypto) to be a suitable polyfill. Please note that this is not an officially supported solution.
 
+
+## Advanced Initalization Options
+
+See [Sauce](./src/telemetrydeck.js#L6-L15) for a full list of options.
+
+
+
+
+
+
+
+
+
+### 📦 Advanced usage for applications that use a bundler (like Webpack, Rollup, …)
+
+
+
+
 ## Queueing Signals
 
 The `TelemetryDeck` class comes with a built-in queuing mechanism for storing signals until they are flushed in a single request. Queued signals are sent with `receivedAt` prefilled with the time they were queued.

src/telemetrydeck.js

@@ -9,10 +9,11 @@ import { version } from './utils/version.js';
  * @property {string} appID the app ID to send telemetry data to
  * @property {string} clientUser the clientUser ID to send telemetry data to
  * @property {string} [target] the target URL to send telemetry data to
- * @property {string} [sessionID]
- * @property {string} [salt]
- * @property {boolean} [testMode]
- * @property {Store} [store]
+ * @property {string} [sessionID] An optional session ID to include in each signal
+ * @property {string} [salt] A salt to use when hashing the clientUser ID
+ * @property {boolean} [testMode] If "true", signals will be marked as test signals and only show up in Test Mode in the Dashbaord
+ * @property {Store} [store] A store to use for queueing signals
+ * @property {Function} [cryptoDigest] A function to use for calculating the SHA-256 hash of the clientUser ID. Null to use the browser's built-in crypto.subtle.digest function.
  */
 
 export default class TelemetryDeck {
@@ -27,7 +28,7 @@ export default class TelemetryDeck {
    * @param {TelemetryDeckOptions} options
    */
   constructor(options = {}) {
-    const { target, appID, clientUser, sessionID, salt, testMode, store } = options;
+    const { target, appID, clientUser, sessionID, salt, testMode, store, cryptoDigest } = options;
 
     if (!appID) {
       throw new Error('appID is required');
@@ -40,6 +41,7 @@ export default class TelemetryDeck {
     this.sessionID = sessionID ?? randomString();
     this.salt = salt;
     this.testMode = testMode ?? this.testMode;
+    this.cryptoDigest = cryptoDigest;
   }
 
   /**
@@ -81,6 +83,23 @@ export default class TelemetryDeck {
     return flushPromise;
   }
 
+  _clientUser = ''
+  _clientUserHashed = ''
+
+  /**
+   * Return a hashed version of the clientUser ID, with caching to avoid unnecessary hashing.
+   * 
+   * @param {string} clientUser The clientUser ID to hash
+   */
+  async _hashedClientUser(clientUser) {
+    if (clientUser !== this._clientUser) {
+      this._clientUserHashed = await sha256([this.clientUser, this.salt].join(''), this.cryptoDigest);
+      this._clientUser = this.clientUser;
+    }
+
+    return this._clientUserHashed;
+  }
+
   async _build(type, payload, options, receivedAt) {
     const { appID, salt, testMode } = this;
     let { clientUser, sessionID } = this;
@@ -101,7 +120,7 @@ export default class TelemetryDeck {
       throw new Error(`TelemetryDeck: "clientUser" is not set`);
     }
 
-    clientUser = await sha256([clientUser, salt].join(''));
+    clientUser = await this._hashedClientUser(clientUser);
 
     const body = {
       clientUser,

src/utils/sha256.js

@@ -1,14 +1,19 @@
-import { getCrypto } from './crypto.js';
-
-// https://stackoverflow.com/a/48161723/54547
-export async function sha256(message) {
-  const crypto = await getCrypto();
-
+/**
+ * Calculate the SHA-256 hash of a string using a provided crypto digest function.
+ * Defaults to globalThis.crypto.subtle.digest if available.
+ * 
+ * // https://stackoverflow.com/a/48161723/54547
+ * 
+ * @param {Function} cryptoDigest 
+ * @param {string} message 
+ * @returns {Promise<string>}
+ */
+export async function sha256(message, cryptoDigest = globalThis?.crypto?.subtle?.digest) {
   // encode as UTF-8
   const messageBuffer = new TextEncoder().encode(message);
 
   // hash the message
-  const hashBuffer = await crypto.subtle.digest('SHA-256', messageBuffer);
+  const hashBuffer = await cryptoDigest('SHA-256', messageBuffer);
 
   // convert ArrayBuffer to Array
   const hashArray = [...new Uint8Array(hashBuffer)];