@hellotext/hellotext 1.1.0 → 1.1.1

package/.babelrc

@@ -0,0 +1,3 @@
+{
+  "presets": ["@babel/preset-env"]
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: Tests
+
+on:
+  pull_request:
+    branches:
+      - '*'
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: ['14', '16']
+    name: Node ${{ matrix.node }}
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm install
+      - run: npm run test

package/README.md

@@ -43,6 +43,7 @@ Hellotext.track("page.viewed");
 ```
 
 In the example above only the name of the action is required.
+
 The library takes care of handling the `url` parameter with the current URL automatically and is not required to specify it explicitly.
 If you want to provide another url, you can pass a `url` key in the params object when tracking an event.
 
@@ -56,7 +57,19 @@ The `track` method returns a Promise that can be `await`ed using the async/await
 
 ```javascript
 const response = await Hellotext.track("page.viewed");
-// {status: "received", success: true}
+```
+
+The return of the `Hellotext.track` method is an instance of a `Response` object that ships with the package. You can check the status of the response via methods, like
+
+```javascript
+if(response.failed) {
+  console.log("failed because", response.data)
+}
+
+if(response.succeeded) {
+  console.log("success")
+  console.log(response.data) // { status: "received" }
+}
 ```
 
 The parameters passed to the action must be a valid set of parameters as described in
@@ -66,6 +79,13 @@ Failing to provide valid set of parameters will result in an error object being
 
 ```javascript
 const response = await Hellotext.track("app.installed", { app_attributes: { name: "My App" }})
+
+console.log(response.data)
+```
+
+yields
+
+```javascript
 {
   errors: [
     {
@@ -73,15 +93,15 @@ const response = await Hellotext.track("app.installed", { app_attributes: { name
       parameter: 'name',
       description: 'The value must be unique and it is already present in another object of the same type.'
     },
-  ], 
-  success: false
+  ]
 }
 ```
 
-You can use `success` key present in the response object to run code conditionally.
 For a complete list of errors types. See [Error Types](https://www.hellotext.com/api#errors)
 
 Generally, most actions also require an associated object. These can be of type [`app`](https://www.hellotext.com/api#apps), [`coupon`](https://www.hellotext.com/api#coupons), [`form`](https://www.hellotext.com/api#forms), [`order`](https://www.hellotext.com/api#orders), [`product`](https://www.hellotext.com/api#products) and [`refund`](https://www.hellotext.com/api#refunds).
+Aside from [Custom Actions](https://www.hellotext.com/api#create_an_action), which don't require the trackable to be present.
+
 
 You can create the associated object directly by defining its attributes in a hash:
 
@@ -157,6 +177,27 @@ Hellotext.track("product.purchased", {
 | **tracked_at** | Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from `created_at`. | epoch | `null`
 
 
+## Events
+
+This library emits events that you can listen to and perform specific action when the event happens.
+Think of it like `addEventListener` for HTML elements. You can listen for events, and remove events as well.
+
+To listen to an event, you can call the `on` method, like so
+
+```javascript
+Hellotext.on(eventName, callback)
+```
+
+To disconnect an event listener, you can call `disconnect`
+
+```javascript
+Hellotext.disconnect(eventName, callback)
+```
+
+### List of events
+
+- `session-set`: This event is fired when the session value for `Hellotext.session` is set. Either through an API request, or if the session was found in the cookie.
+
 ## Understanding Sessions
 
 The library looks for a session identifier present on the `hellotext_session` query parameter. If the session is not present as a cookie neither it will create a new random session identifier. 
@@ -172,8 +213,24 @@ It is possible to obtain the current session by simply calling `Hellotext.sessio
 await Hellotext.session
 // Returns bBJn9vR15yPaYkWmR2QK0jopMeNxrA6l
 ```
-Calling the `Hellotext.session` for the first time will send a request to Hellotext to create a session,
-then the class stores the value in the `hello_session` cookie. Subsequent calls would not result in requests made to the server,
-because the class stores the value. 
+
+If the session has not been set yet, the result returned will be `undefined`. 
+You can check whether the session has been set or not by calling `Hellotext.isInitialized`.
+
+```javascript
+if(Hellotext.isInitialized) {
+  console.log("session is present")
+} else {
+  console.log("session has not been set")
+}
+```
+
+Moreover, you can hook in and listen for the session being set, such that when it's set, you're notified about the change, like so
+
+```javascript
+Hellotext.on("session-set", (session) => {
+  console.log("session is: ", session)
+})
+```
 
 You may want to store the session on your backend when customers are unidentified so you can later [attach it to a profile](https://www.hellotext.com/api#attach_session) when it becomes known.

package/__tests__/event_emitter_test.js

@@ -0,0 +1,36 @@
+import EventEmitter from "../lib/eventEmitter"
+
+describe("#addSubscriber", function () {
+  const instance = new EventEmitter()
+
+  it("adds the callback to the list of subscribers for an event", () => {
+    const callback = (session) => {}
+    instance.addSubscriber("session-set", callback)
+    expect(instance.subscribers["session-set"].length).toEqual(1)
+  });
+});
+
+describe("#removeSubscriber", function () {
+  const instance = new EventEmitter()
+
+  it("removes the callback from the list of subscribers for an event", () => {
+    const callback = (session) => {}
+    instance.addSubscriber("session-set", callback)
+    instance.removeSubscriber("session-set", callback)
+
+    expect(instance.subscribers["session-set"].length).toEqual(0)
+  });
+});
+
+describe("#emit", () => {
+  const instance = new EventEmitter()
+
+  it("notifies the listeners for an event", () => {
+    const callback = jest.fn()
+
+    instance.addSubscriber("session-set", callback)
+    instance.emit("session-set", "session_payload")
+
+    expect(callback).toHaveBeenCalledTimes(1)
+  });
+});

package/__tests__/event_test.js

@@ -0,0 +1,21 @@
+import Event from "../lib/event"
+
+describe(".valid", function () {
+  it("is true when event name is a valid defined name", () => {
+    expect(Event.valid("session-set")).toEqual(true)
+  });
+
+  it("is false when event name is not defined", () =>  {
+    expect(Event.valid("undefined-event")).toEqual(false)
+  });
+});
+
+describe(".invalid", () => {
+  it("is true when event name is not defined", () =>  {
+    expect(Event.invalid("undefined-event")).toEqual(true)
+  });
+
+  it("is false when event name is a valid defined name", () => {
+    expect(Event.invalid("session-set")).toEqual(false)
+  });
+});

package/__tests__/hellotext_test.js

@@ -0,0 +1,156 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import Hellotext from "../lib/hellotext";
+
+const getCookieValue = name => document.cookie.match('(^|;)\\s*' + name + '\\s*=\\s*([^;]+)')?.pop()
+
+describe("when trying to call methods before initializing the class", () => {
+  it("raises an error when Hellotext.session is called",  () => {
+    expect(() => Hellotext.session).toThrowError()
+  });
+
+  it("raises an error when Hellotext.track is called",  () => {
+    expect(Hellotext.track("page.viewed")).rejects.toThrowError()
+  });
+})
+
+describe("when the class is initialized successfully", () => {
+  const business_id = "xy76ks"
+
+  describe("when hello_session is present in the query params", () => {
+    beforeAll(() => {
+      const windowMock = {
+        location: { search: "?hello_session=session" },
+      }
+
+      jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
+      Hellotext.initialize(business_id)
+    })
+
+    it("sets the cookie as value of the query parameter", () => {
+      expect(getCookieValue("hello_session")).toEqual("session")
+    });
+
+    it("returns the value when Hellotext.session is called", () => {
+      expect(Hellotext.session).toEqual("session")
+    });
+
+    describe("when tracking events", () => {
+      it("success attribute is true when response from the server is received successfully", async () => {
+        global.fetch = jest.fn().mockResolvedValue({
+          json: jest.fn().mockResolvedValue({received: "success"}),
+          status: 200
+        })
+
+        const response = await Hellotext.track("page.viewed")
+
+        expect(response.succeeded).toEqual(true)
+      });
+
+      it("success attribute is false when response from the server is rejected", async () => {
+        global.fetch = jest.fn().mockResolvedValue({
+          json: jest.fn().mockResolvedValue({}),
+          status: 422
+        })
+
+        const response = await Hellotext.track("page.viewed")
+
+        expect(response.failed).toEqual(true)
+      });
+    });
+  });
+
+  describe("when hello_session is not present in the query params", () => {
+    const business_id = "xy76ks"
+
+    beforeAll(() => {
+      const windowMock = {location: { search: "" },}
+      jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
+    })
+
+    it("mints a new session token and sets the cookie as well", () => {
+      global.fetch = jest.fn().mockResolvedValue({
+        json: jest.fn().mockResolvedValue({id: "generated_token"}),
+        status: 200
+      })
+
+      Hellotext.initialize(business_id)
+
+      setTimeout(() => {
+        expect(getCookieValue("hello_session")).toEqual("generated_token")
+        expect(Hellotext.session).toEqual("generated_token")
+      }, 1000)
+    });
+  });
+});
+
+describe(".isInitialized", () => {
+  describe("when session is set", () => {
+    beforeAll(() => {
+      const windowMock = {location: { search: "?hello_session=session" }}
+      jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
+      Hellotext.initialize("123")
+    })
+
+    it("is true", () => {
+      expect(Hellotext.isInitialized).toEqual(true)
+    });
+  });
+});
+
+describe(".on", () => {
+  const business_id = "xy76ks"
+
+  beforeAll(() => {
+    const windowMock = {location: { search: "" },}
+    jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
+  })
+
+  it("registers a callback that is called when the session is set", function () {
+    global.fetch = jest.fn().mockResolvedValue({
+      json: jest.fn().mockResolvedValue({id: "generated_token"}),
+      status: 200
+    })
+
+    const callback = jest.fn()
+
+    Hellotext.on("session-set", callback)
+    Hellotext.initialize(business_id)
+
+    expect(callback).toHaveBeenCalledTimes(1)
+  });
+
+  it("throws an error when event is invalid", () => {
+    expect(
+      () => Hellotext.on("undefined-event", () => {})
+    ).toThrowError()
+  });
+});
+
+describe(".disconnect", () => {
+  const business_id = "xy76ks"
+
+  beforeAll(() => {
+    const windowMock = {location: { search: "?hello_session=123" },}
+    jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
+
+    Hellotext.initialize(123)
+  })
+
+  it("throws an error when event is invalid", () => {
+    expect(
+      () => Hellotext.disconnect("undefined-event", () => {})
+    ).toThrowError()
+  });
+
+  it("removes the callback from the subscribers and will not be notified again", () => {
+    const callback = jest.fn()
+
+    Hellotext.on("session-set", callback)
+    Hellotext.disconnect("session-set", callback)
+
+    expect(callback).toHaveBeenCalledTimes(0)
+  });
+})

package/lib/errors/invalidEvent.js

@@ -0,0 +1,8 @@
+class InvalidEvent extends Error {
+  constructor(event) {
+    super(`${event} is not valid. Please provide a valid event name`)
+    this.name = 'InvalidEvent'
+  }
+}
+
+export { InvalidEvent }

package/lib/event.js

@@ -0,0 +1,15 @@
+export default class Event {
+  static events = ["session-set"]
+
+  static valid(name) {
+    return Event.exists(name)
+  }
+
+  static invalid(name) {
+    return !this.valid(name)
+  }
+
+  static exists(name) {
+    return this.events.find((eventName) => eventName === name) !== undefined
+  }
+}

package/lib/eventEmitter.js

@@ -0,0 +1,28 @@
+export default class EventEmitter {
+  constructor() {
+    this.subscribers = {}
+  }
+
+  addSubscriber(eventName, callback) {
+    this.subscribers = {
+      ...this.subscribers,
+      [eventName]: this.subscribers[eventName] ? [...this.subscribers[eventName], callback] : [callback]
+    }
+  }
+
+  removeSubscriber(eventName, callback) {
+    if(this.subscribers[eventName]) {
+      this.subscribers[eventName] = this.subscribers[eventName].filter((cb) => cb !== callback)
+    }
+  }
+
+  emit(eventName, data) {
+    this.subscribers[eventName].forEach((subscriber) => {
+      subscriber(data)
+    })
+  }
+
+  get listeners() {
+    return Object.keys(this.subscribers).length !== 0
+  }
+}

package/lib/hellotext.js

@@ -1,104 +1,145 @@
+import Event from "./event"
+import EventEmitter from "./eventEmitter"
+import Response from "./response";
+
 import { NotInitializedError } from './errors/notInitializedError'
+import { InvalidEvent } from "./errors/invalidEvent"
 
 const apiUrl = 'https://api.hellotext.com/v1/'
 
 class Hellotext {
-  static #_session
-  static #business_id
+  static #session
+  static #business
+  static #eventEmitter = new EventEmitter()
+
   /**
    * initialize the module.
+   * @param business public business id
    */
-  static initialize(business_id) {
-    this.#business_id = business_id
+  static initialize(business) {
+    this.#business = business
 
     const urlSearchParams = new URLSearchParams(window.location.search)
-    const session = urlSearchParams.get('hello_session') || getCookieValue('hello_session')
+    const session = urlSearchParams.get('hello_session') || this.#cookie
 
     if (session && session !== "undefined" && session !== "null") {
-      this.#_session = session
+      this.#session = session
       this.#setSessionCookie()
+    } else {
+      this.#mintAnonymousSession()
+        .then(response => {
+          this.#session = response.id
+          this.#setSessionCookie()
+        })
     }
   }
 
   /**
+   * Tracks an action that has happened on the page
    *
    * @param { String } action a valid action name
    * @param { Object } params
    * @returns {Promise}
    */
-  static async track(action, params) {
-    if (this.notInitialized) { throw new NotInitializedError() }
+  static async track(action, params = {}) {
+    if (this.#notInitialized) { throw new NotInitializedError() }
 
     const response = await fetch(apiUrl + 'track/events', {
-      headers: this.headers,
+      headers: this.#headers,
       method: 'post',
       body: JSON.stringify({
-        session: await this.session,
+        session: this.session,
         action,
         ...params,
         url: (params && params.url) || window.location.href
       }),
     })
 
-    const body = await response.json()
-    body.success = response.status === 200
+    return new Response(response.status === 200, await response.json)
+  }
+
+  /**
+   * Registers an event listener
+   * @param event the name of the event to listen to
+   * @param callback the callback. This method will be called with the payload
+   */
+  static on(event, callback) {
+    if(Event.invalid(event)) { throw new InvalidEvent(event) }
 
-    return body
+    this.#eventEmitter.addSubscriber(event, callback)
+  }
+
+  /**
+   * Removes an event listener
+   * @param event the name of the event to remove
+   * @param callback the callback to remove
+   */
+  static disconnect(event, callback) {
+    if(Event.invalid(event)) { throw new InvalidEvent(event) }
+
+    this.#eventEmitter.removeSubscriber(event, callback)
   }
 
   /**
    *
-   * @returns {Promise<any>|String}
+   * @returns {String}
    */
   static get session() {
-    if (this.notInitialized) { throw new NotInitializedError() }
+    if (this.#notInitialized) { throw new NotInitializedError() }
 
-    if (this.#_session) return this.#_session
+    return this.#session
+  }
 
-    return this.mintAnonymousSession()
-      .then(response => {
-        this.#_session = response.id
-        this.#setSessionCookie()
-      })
-      .then(() => this.#_session)
+  /**
+   * Determines if the session is set or not
+   * @returns {boolean}
+   */
+  static get isInitialized() {
+    return this.#session !== undefined
   }
 
   // private
 
-  static async mintAnonymousSession() {
-    if (this.notInitialized) { throw new NotInitializedError() }
+  static get #notInitialized() {
+    return this.#business === undefined
+  }
+
+  static async #mintAnonymousSession() {
+    if (this.#notInitialized) { throw new NotInitializedError() }
 
     const trackingUrl = apiUrl + 'track/sessions'
 
     this.mintingPromise = await fetch(trackingUrl, {
       method: 'post',
-      headers: { Authorization: `Bearer ${this.#business_id}` },
+      headers: { Authorization: `Bearer ${this.#business}` },
     })
 
     return this.mintingPromise.json()
   }
 
-  static get headers() {
-    if (this.notInitialized) { throw new NotInitializedError() }
+  static get #headers() {
+    if (this.#notInitialized) { throw new NotInitializedError() }
 
     return {
-      Authorization: `Bearer ${this.#business_id}`,
+      Authorization: `Bearer ${this.#business}`,
       Accept: 'application.json',
       'Content-Type': 'application/json',
     }
   }
 
   static #setSessionCookie() {
-    if (this.notInitialized) { throw new NotInitializedError() }
+    if (this.#notInitialized) { throw new NotInitializedError() }
+
+    if(this.#eventEmitter.listeners) {
+      this.#eventEmitter.emit("session-set", this.#session)
+    }
 
-    document.cookie = `hello_session=${this.#_session}`
+    document.cookie = `hello_session=${this.#session}`
   }
 
-  static get notInitialized() {
-    return this.#business_id === undefined
+  static #cookie() {
+    return document.cookie.match('(^|;)\\s*' + 'hello_session' + '\\s*=\\s*([^;]+)')?.pop()
   }
 }
 
-const getCookieValue = name => document.cookie.match('(^|;)\\s*' + name + '\\s*=\\s*([^;]+)')?.pop()
-
 export default Hellotext

package/lib/response.js

@@ -0,0 +1,21 @@
+export default class Response {
+  #success
+  #response
+
+  constructor(success, response) {
+    this.#success = success
+    this.#response = response
+  }
+
+  data() {
+    return this.#response
+  }
+
+  get failed() {
+    return this.#success === false
+  }
+
+  get succeeded() {
+    return this.#success === true
+  }
+}

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@hellotext/hellotext",
-  "version": "1.1.0",
-  "description": "Hellotext javascript client",
+  "version": "1.1.1",
+  "description": "Hellotext JavaScript Client",
   "main": "index.js",
   "author": "Hellotext",
   "license": "MIT",
   "homepage": "https://github.com/hellotext/hellotext.js",
   "devDependencies": {
+    "@babel/preset-env": "^7.20.2",
+    "@testing-library/jest-dom": "^5.16.5",
+    "jest": "^29.3.1",
+    "jest-environment-jsdom": "^29.3.1",
     "prettier": "2.8.2"
   },
   "directories": {
@@ -20,6 +24,9 @@
     "hellotext",
     "javascript"
   ],
+  "scripts": {
+    "test": "NODE_ENV=test jest"
+  },
   "bugs": {
     "url": "https://github.com/hellotext/hellotext.js/issues"
   }