Merge pull request #49 from codex-team/feature/context

Custom context implemented

Author: neSpecc

README.md

@@ -56,7 +56,7 @@ Create `HawkCatcher` class instance when script will be ready and pass your Inte
 ```js
 const hawk = new HawkCatcher({token: 'INTEGRATION_TOKEN'});
 
-// or 
+// or
 
 const hawk = new HawkCatcher('INTEGRATION_TOKEN');
 ```
@@ -74,10 +74,29 @@ Initialization settings:
 | `token` | string | **required** | Your project's Integration Token |
 | `release` | string/number | optional | Unique identifier of the release. Used for source map consuming (see below) |
 | `user` | {id: string, name?: string, image?: string, url?: string} | optional | Current authenticated user |
+| `context` | object | optional | Any data you want to pass with every message. |
 | `vue` | Vue constructor | optional | Pass Vue constructor to set up the [Vue integration](#integrate-to-vue-application) |
 
 Other available [initial settings](types/hawk-initial-settings.d.ts) are described at the type definition.
 
+## Manual sending
+
+You can send errors or other messages to the Hawk manually, for example at your `catch` blocks or any debug conditions.
+
+Use the `.send(message, context)` method for that. This method accepts the `message` of type `Error` or `string`
+as the first parameter. The second parameter is optional, it allows passing any additional data with the event.
+If you specify the `context` with the `HawkCatcher` constructor, it will be merged with the context passed to the `send` method.
+
+```js
+// init Hawk Catcher instance
+const hawk = new HawkCatcher({token: 'INTEGRATION_TOKEN'});
+
+// somewhere in try-catch block or other custom place
+hawk.send(new Error('Something went wrong'), {
+  myOwnDebugInfo: '1234'
+}))
+```
+
 ## Source maps consuming
 
 If your bundle is minified, it is useful to pass source-map files to the Hawk. After that you will see beautiful original source code lines in Hawk Garage instead of minified code.
@@ -105,7 +124,7 @@ const hawk = new HawkCatcher({
   token: 'INTEGRATION_TOKEN',
   vue: Vue // the Vue constructor you tweak
 });
-``` 
+```
 
 or pass it any moment after Hawk Catcher was instantiated:
 
@@ -118,4 +137,4 @@ const hawk = new HawkCatcher({
 });
 
 hawk.connectVue(Vue)
-``` 
+```

dist/catcher.d.ts

@@ -1,4 +1,5 @@
 import { HawkInitialSettings } from '../types/hawk-initial-settings';
+import { HawkEventContext } from '../types/hawk-event';
 /**
  * Hawk JavaScript Catcher
  * Module for errors and exceptions tracking
@@ -26,6 +27,10 @@ export default class Catcher {
      * Current authenticated user
      */
     private readonly user;
+    /**
+     * Any additional data passed by user for sending with all messages
+     */
+    private readonly context;
     /**
      * Transport for dialog between Catcher and Collector
      * (WebSocket decorator)
@@ -41,17 +46,23 @@ export default class Catcher {
      * @param {HawkInitialSettings|string} settings - If settings is a string, it means an Integration Token
      */
     constructor(settings: HawkInitialSettings | string);
+    /**
+     * Generates user if no one provided via HawkCatcher settings
+     * After generating, stores user for feature requests
+     */
+    private static getGeneratedUser;
     /**
      * Send test event from client
      */
     test(): void;
     /**
-     * This method prepares and sends an Error to Hawk
-     * User can fire it manually on try-catch
+     * Public method for manual sending messages to the Hawk
+     * Can be called in user's try-catch blocks or by other custom logic
      *
-     * @param error - error to catch
+     * @param message - what to send
+     * @param [context] - any additional data to send
      */
-    catchError(error: Error): void;
+    send(message: Error | string, context?: HawkEventContext): void;
     /**
      * Add error handing to the passed Vue app
      *
@@ -72,7 +83,8 @@ export default class Catcher {
      * Format and send an error
      *
      * @param error - error to send
-     * @param {object} integrationAddons - addons spoiled by Integration
+     * @param integrationAddons - addons spoiled by Integration
+     * @param context - any additional data passed by user
      */
     private formatAndSend;
     /**
@@ -85,6 +97,7 @@ export default class Catcher {
      * Formats the event
      *
      * @param error - error to format
+     * @param context - any additional data passed by user
      */
     private prepareErrorFormatted;
     /**
@@ -105,6 +118,8 @@ export default class Catcher {
     private getRelease;
     /**
      * Collects additional information
+     *
+     * @param context - any additional data passed by user
      */
     private getContext;
     /**

dist/hawk.js

@@ -0,0 +1,4 @@
+/**
+ * Returns random string
+ */
+export declare function generateRandomId(): string;

dist/utils.d.ts

@@ -39,11 +39,19 @@
         h2 {
             font-weight: 500;
             margin: 0 0 10px;
-            font-size: 17px;
+            font-size: 13px;
             color: rgba(219,230,255,0.60);
-            letter-spacing: 0.2px;
+            letter-spacing: 0.24px;
             text-align: left;
-            font-variant: all-petite-caps;
+            text-transform: uppercase;
+        }
+
+        h2 small {
+          text-transform: none;
+          font-size: 14px;
+          opacity: .6;
+          font-weight: normal;
+          margin-left: 15px;
         }
 
         button {
@@ -99,6 +107,21 @@ <h2>Send Unhandled promise rejection error</h2>
         Unhandled promise rejection
     </button>
 </section>
+<section>
+  <h2>
+    Send event manually
+    <small>
+      Through the <code>.send(error, context)</code> method
+    </small>
+  </h2>
+  <label for="errorContext">Error context</label>
+  <input type="text" id="errorContext" placeholder="Any data you want">
+  <br>
+  <br>
+  <button id="btn-manual-sending">
+    Send manual message
+  </button>
+</section>
 <section>
     <h2>Send the specified number of errors</h2>
     <label for="errorsNumber">Enter the number of errors to send</label>
@@ -203,11 +226,14 @@ <h2>Test Vue integration: &lt;test-component&gt;</h2>
 <script src="assets/hawk.js"></script>
 <script src="sample-errors.js"></script>
 <script>
-    window.hawk = new HawkCatcher({
-        token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9qZWN0SWQiOiI1ZWFmZWIwN2M3NjU2NDAwMjJmY2IwMjQiLCJpYXQiOjE1ODg1ODcyNzF9.mKBbgyynEApfh4I8VKRMTHR8lJpoauUcyeUfPQMGTO4',
-        collectorEndpoint: 'ws://localhost:3000/ws',
-        vue: window.Vue,
-    })
+  window.hawk = new HawkCatcher({
+    token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9qZWN0SWQiOiI1ZTVhNzVjNzNlM2E5ZDE2YjUzMzczOTMiLCJpYXQiOjE1ODI5ODY2OTV9.oK_LPRxcpRuZE8eSbmdObRX712YXO_Twpq7mgg7-9pw',
+    collectorEndpoint: 'ws://localhost:3000/ws',
+    vue: window.Vue,
+    context: {
+      rootContextSample: '12345'
+    }
+  })
 </script>
 </body>
 </html>

example/index.html

@@ -42,7 +42,7 @@ buttonSendMany.addEventListener('click', function sendManyErrors() {
   const errorsNumber = inputElement.value;
 
   for (let i = 0; i < errorsNumber; i++) {
-    window.hawk.catchError(new window[errorType]('Test many error'));
+    window.hawk.send(new window[errorType]('Test many error'));
   }
 });
 
@@ -56,4 +56,20 @@ buttonConsoleTest.addEventListener('click', function consoleLogPrint() {
   const text = document.getElementById('consoleCatcherTestTextInput').value;
 
   console[consoleMethod](text);
-});
+});
+
+/**
+ * Button for the manual sending
+ */
+const buttonManualSending = document.getElementById('btn-manual-sending');
+
+buttonManualSending.addEventListener('click', () => {
+  const contextSample = document.getElementById('errorContext').value;
+
+  window.hawk.send(
+    new Error('Manual sending example'),
+    contextSample.trim().length
+      ? { contextSample }
+      : undefined
+  );
+});

example/sample-errors.js

@@ -1,6 +1,6 @@
 {
   "name": "@hawk.so/javascript",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "JavaScript errors tracking for Hawk.so",
   "main": "./dist/hawk.js",
   "types": "./dist/index.d.ts",

package.json

@@ -3,7 +3,7 @@ import Sanitizer from './modules/sanitizer';
 import log from './modules/logger';
 import StackParser from './modules/stackParser';
 import { HawkInitialSettings } from '../types/hawk-initial-settings';
-import { BacktraceFrame, HawkEvent, HawkUser } from '../types/hawk-event';
+import { BacktraceFrame, HawkEvent, HawkEventContext, HawkUser } from '../types/hawk-event';
 import { VueIntegration, VueIntegrationAddons } from './integrations/vue';
 import { generateRandomId } from './utils';
 
@@ -44,6 +44,11 @@ export default class Catcher {
    */
   private readonly user: HawkUser;
 
+  /**
+   * Any additional data passed by user for sending with all messages
+   */
+  private readonly context: HawkEventContext;
+
   /**
    * Transport for dialog between Catcher and Collector
    * (WebSocket decorator)
@@ -70,6 +75,7 @@ export default class Catcher {
     this.token = settings.token;
     this.release = settings.release;
     this.user = settings.user || Catcher.getGeneratedUser();
+    this.context = settings.context || undefined;
 
     if (!this.token) {
       log(
@@ -132,17 +138,18 @@ export default class Catcher {
   public test(): void {
     const fakeEvent = new Error('Hawk JavaScript Catcher test message.');
 
-    this.catchError(fakeEvent);
+    this.send(fakeEvent);
   }
 
   /**
-   * This method prepares and sends an Error to Hawk
-   * User can fire it manually on try-catch
+   * Public method for manual sending messages to the Hawk
+   * Can be called in user's try-catch blocks or by other custom logic
    *
-   * @param error - error to catch
+   * @param message - what to send
+   * @param [context] - any additional data to send
    */
-  public catchError(error: Error): void {
-    this.formatAndSend(error);
+  public send(message: Error | string, context?: HawkEventContext): void {
+    this.formatAndSend(message, undefined, context);
   }
 
   /**
@@ -196,12 +203,17 @@ export default class Catcher {
    * Format and send an error
    *
    * @param error - error to send
-   * @param {object} integrationAddons - addons spoiled by Integration
+   * @param integrationAddons - addons spoiled by Integration
+   * @param context - any additional data passed by user
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private async formatAndSend(error: Error | string, integrationAddons?: { [key: string]: any }): Promise<void> {
+  private async formatAndSend(
+    error: Error | string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    integrationAddons?: { [key: string]: any },
+    context?: HawkEventContext
+  ): Promise<void> {
     try {
-      const errorFormatted = await this.prepareErrorFormatted(error);
+      const errorFormatted = await this.prepareErrorFormatted(error, context);
 
       /**
        * If this event catched by integration (Vue or other), it can pass extra addons
@@ -232,16 +244,17 @@ export default class Catcher {
    * Formats the event
    *
    * @param error - error to format
+   * @param context - any additional data passed by user
    */
-  private async prepareErrorFormatted(error: Error | string): Promise<HawkEvent> {
+  private async prepareErrorFormatted(error: Error | string, context?: HawkEventContext): Promise<HawkEvent> {
     return {
       token: this.token,
       catcherType: this.type,
       payload: {
         title: this.getTitle(error),
         type: this.getType(error),
         release: this.getRelease(),
-        context: this.getContext(),
+        context: this.getContext(context),
         user: this.getUser(),
         get: this.getGetParams(),
         addons: this.getAddons(),
@@ -297,9 +310,21 @@ export default class Catcher {
 
   /**
    * Collects additional information
+   *
+   * @param context - any additional data passed by user
    */
-  private getContext(): object {
-    return Sanitizer.sanitize({});
+  private getContext(context?: HawkEventContext): object {
+    const contextMerged = {};
+
+    if (this.context !== undefined) {
+      Object.assign(contextMerged, this.context);
+    }
+
+    if (context !== undefined) {
+      Object.assign(contextMerged, context);
+    }
+
+    return Sanitizer.sanitize(contextMerged);
   }
 
   /**

src/catcher.ts

@@ -262,9 +262,10 @@ export default class Sanitizer {
     /**
      * Represent big object as a "<big object>"
      *
-     * @param _target - object ot format
+     * @param target - object ot format
      */
-    private static formatBigObject(_target: any): string {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-unused-vars-experimental
+    private static formatBigObject(target: any): string {
       return '<big object>';
     }
 }

src/modules/sanitizer.ts

@@ -58,8 +58,8 @@ export default class Socket {
    */
   constructor({
     collectorEndpoint,
-    // eslint-disable-next-line @typescript-eslint/no-empty-function
-    onMessage = (_message: MessageEvent): void => {},
+    // eslint-disable-next-line @typescript-eslint/no-empty-function, @typescript-eslint/no-unused-vars, @typescript-eslint/no-unused-vars-experimental
+    onMessage = (message: MessageEvent): void => {},
     // eslint-disable-next-line @typescript-eslint/no-empty-function
     onClose = (): void => {},
     // eslint-disable-next-line @typescript-eslint/no-empty-function

src/modules/socket.ts

@@ -1,3 +1,3 @@
 
-  Size: 6.86 KB with all dependencies, minified and gzipped
+  Size: 7.1 KB with all dependencies, minified and gzipped
 

stats.txt

@@ -77,6 +77,13 @@ export interface EventData {
   addons?: object;
 }
 
+/**
+ * Any additional data passed by user
+ */
+export interface HawkEventContext {
+  [key: string]: any,
+}
+
 /**
  * Single item of backtrace
  */