@hellotext/hellotext 1.4.1 → 1.5.1

package/.babelrc

@@ -10,9 +10,12 @@
     ]
   ],
   "plugins": [
-    ["@babel/plugin-proposal-private-methods", {
-      "loose": true
-    }],
+    [
+      "@babel/plugin-proposal-private-methods",
+      {
+        "loose": true
+      }
+    ],
     ["@babel/plugin-proposal-private-property-in-object", { "loose": true }],
     ["@babel/plugin-proposal-class-properties", { "loose": true }],
     "@babel/plugin-transform-classes"

package/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ['16']
+        node: ['20', '22']
     name: Node ${{ matrix.node }}
     steps:
       - uses: actions/checkout@v2

package/.prettierignore

@@ -0,0 +1,2 @@
+__tests__
+dist

package/README.md

@@ -1,8 +1,14 @@
 # Hellotext.js
 
-Track the events happening on your site to [Hellotext](https://www.hellotext.com) in real-time with this library. 
+Official [Hellotext](https://www.hellotext.com) (client-side) JavaScript library. 
 
-## Installation 
+This library allows you the following,
+
+- Track events happening on your site to [Hellotext](https://www.hellotext.com) in real-time.
+- Use Hellotext Forms to dynamically collect data from your customers based on your specific business requirements.
+
+
+## Installation
 
 ### Using NPM
 
@@ -21,7 +27,7 @@ yarn add @hellotext/hellotext
 Import the library into your app.
 
 ```javascript
-import Hellotext from "@hellotext/hellotext";
+import Hellotext from '@hellotext/hellotext'
 ```
 
 Initialize the library passing the public `HELLOTEXT_BUSINESS_ID` identifier that represents the business.
@@ -29,165 +35,17 @@ Initialize the library passing the public `HELLOTEXT_BUSINESS_ID` identifier tha
 You can find it from the business's settings page.
 
 ```javascript
-Hellotext.initialize("HELLOTEXT_BUSINESS_ID");
+Hellotext.initialize('HELLOTEXT_BUSINESS_ID')
 ```
 
 Failing to initialize the class before calling any other method will throw a `NotInitializedError`.
 
-## Usage
-
-Tracking events is straightforward and perhaps the simplest example is tracking a page view:
-
-```javascript
-Hellotext.track("page.viewed");
-```
-
-In the example above only the name of the action is required.
-
-### Handling Responses
-
-The `track` method returns a Promise that can be `await`ed using the async/await syntax. Or using `.then` on the returned Promise.
-
-```javascript
-const response = await Hellotext.track("page.viewed");
-```
-
-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" }
-}
-```
-
-### Parameters
-
-The parameters passed to the action must be a valid set of parameters as described in
-[Tracking Actions](https://www.hellotext.com/api#tracking).
-
-#### URL Parameter
-
-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.
-
-```javascript
-Hellotext.track("page.viewed", {
-  url: "www.example.org"
-});
-```
-
-### Errors
-
-Failing to provide valid set of parameters will result in an error object being returned, describing the parameters that did not satisfy the rules.
-
-```javascript
-const response = await Hellotext.track("app.installed", { app_parameters: { name: "My App" }})
-
-console.log(response.data)
-```
-
-yields
-
-```javascript
-{
-  errors: [
-    {
-      type: 'parameter_not_unique',
-      parameter: 'name',
-      description: 'The value must be unique and it is already present in another object of the same type.'
-    },
-  ]
-}
-```
-
-For a complete list of errors types. See [Error Types](https://www.hellotext.com/api#errors)
-
-### Associated objects
-
-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 parameters in a hash:
-
-```javascript
-Hellotext.track("order.placed", {
-    amount: 395.00, 
-    currency: "USD",
-    order_parameters: {
-        "amount": "395.00",
-        "reference": "654321",
-    }
-});
-```
-
-If you want to reuse existing objects, you must pass the identifier of an existing associated object. For example, to track a product purchase the identifier of a previously created product object as the `product`. 
-For more information about identifiers, view the [Tracking API](https://www.hellotext.com/api#tracking)
-
-```javascript
-Hellotext.track("product.purchased", {
-    amount: 395.00, 
-    currency: "USD",
-    product: "erA2RAXE"
-});
-```
-
-## List of actions
-
-The following is a complete list of built-in actions and their required associated objects. 
-
-| Action                | Description                                              | Required Parameter |
-|-----------------------|----------------------------------------------------------| --- |
-| **app.installed**     | An app was installed.                                    | `app` or [app_parameters](https://www.hellotext.com/api#app)
-| **app.removed**       | An app was removed.                                      | `app` or [app_parameters](https://www.hellotext.com/api#app)
-| **app.spent**         | A customer spent on an app.                              | `app` or [app_parameters](https://www.hellotext.com/api#app)
-| **cart.abandoned**    | A cart was abandoned.                                    | `product` or [product_parameters](https://www.hellotext.com/api#products)
-| **cart.added**        | Added an item to the cart.                               | `product` or [product_parameters](https://www.hellotext.com/api#products)
-| **cart.removed**      | Removed an item from the cart.                           | `product` or [product_parameters](https://www.hellotext.com/api#products)
-| **coupon.redeemed**   | A coupon was redeem by a customer.                       | `coupon` or [coupon_parameters](https://www.hellotext.com/api#coupons)
-| **form.completed**    | A form was completed by the customer.                    | `form` or [form_parameters](https://www.hellotext.com/api#forms)
-| **order.placed**      | Order has been placed.                                   | `order` or [order_parameters](https://www.hellotext.com/api#orders)
-| **order.confirmed**   | Order has been confirmed by you.                         | `order` or [order_parameters](https://www.hellotext.com/api#orders)
-| **order.cancelled**   | Order has been cancelled either by you or your customer. | `order` or [order_parameters](https://www.hellotext.com/api#orders)
-| **order.shipped**     | Order has been shipped to your customer.                 | `order` or [order_parameters](https://www.hellotext.com/api#orders)
-| **order.delivered**   | Order has been delivered to your customer.               | `order` or [order_parameters](https://www.hellotext.com/api#orders)
-| **page.viewed**       | A page was viewed by a customer.                         | `url`
-| **product.purchased** | A product has been purchased.                            | `product` or [product_parameters](https://www.hellotext.com/api#products)
-| **product.viewed**    | A product page has been viewed.                          | `product` or [product_parameters](https://www.hellotext.com/api#products)
-| **refund.requested**  | A customer requested a refund.                           | `refund` or [refund_parameters](https://www.hellotext.com/api#refunds)
-| **refund.received**   | A refund was issued by you to your customer.             | `refund` or [refund_parameters](https://www.hellotext.com/api#refunds)
-
-You can also create your **[own defined actions](https://www.hellotext.com/api#actions)**.
-
-## Additional Properties
-
-You can include additional attributes to the tracked event, additional properties must be included inside the `metadata` object:
-
-```javascript
-Hellotext.track("product.purchased", {
-    amount: 0.20, 
-    currency: "USD",
-    metadata: {
-        myProperty: "custom"
-    },
-    tracked_at: 1665684173
-});
-```
-
-### List of additional attributes
+## Documentation
 
-| Property | Description | Type | Default |
-| --- | --- | --- | --- |
-| **amount** | Monetary amount that represents the revenue associated to this tracked event. | float | `0`
-| **currency** | Currency for the `amount` given in ISO 4217 format.  | currency | `USD`
-| **metadata** | Set of key-value pairs that you can attach to an event. This can be useful for storing additional information about the object in a structured format. | hash | `{}`
-| **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`
+Learn how to leverage the library to track events and collect forms.
 
+- [Tracking Events](/docs/tracking.md)
+- [Forms](/docs/forms.md)
 
 ## Events
 
@@ -209,54 +67,56 @@ Hellotext.removeEventListener(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.
+- `forms:collected` This event is fired when forms are collected. The callback will receive the array of forms collected.
+- `form:completed` This event is fired when a form has been completed. A form is completed when the user fills all required inputs and verifies their OTP(One-Time Password). The callback will receive the form object that was completed, alongside the data the user filled in the form.
 
 ## 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, you can disable this default behaviour via the configuration, see [Configuration Options](#configuration-options) for more information. 
-The session is automatically sent to Hellotext any time the `Hellotext.track` method is called. 
+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, you can disable this default behaviour via the configuration, see [Configuration Options](#configuration-options) for more information.
+The session is automatically sent to Hellotext any time the `Hellotext.track` method is called.
 
 Short links redirections attaches a session identifier to the destination url as `hellotext_session` query parameter. This will identify all the events back to the customer who opened the link.
 
 ### Get session
 
-It is possible to obtain the current session by simply calling `Hellotext.session`. 
+It is possible to obtain the current session by simply calling `Hellotext.session`.
 
 ```javascript
 await Hellotext.session
 // Returns bBJn9vR15yPaYkWmR2QK0jopMeNxrA6l
 ```
 
-If the session has not been set yet, the result returned will be `undefined`. 
+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")
+if (Hellotext.isInitialized) {
+  console.log('session is present')
 } else {
-  console.log("session has not been set")
+  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)
+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.
 
-### Configuration 
+### Configuration
 
-When initializing the library, you may pass an optional configuration object as the second argument. 
+When initializing the library, you may pass an optional configuration object as the second argument.
 
 ```javascript
-Hellotext.initialize("HELLOTEXT_BUSINESS_ID", configurationOptions);
+Hellotext.initialize('HELLOTEXT_BUSINESS_ID', configurationOptions)
 ```
 
 #### Configuration Options
 
 | Property            | Description                                                                                                      | Type    | Default |
-|---------------------|------------------------------------------------------------------------------------------------------------------|---------| --- |
-| autogenerateSession | Whether the library should automatically generate a session when no session is found in the query or the cookies | Boolean | true
+| ------------------- | ---------------------------------------------------------------------------------------------------------------- | ------- | ------- |
+| autogenerateSession | Whether the library should automatically generate a session when no session is found in the query or the cookies | Boolean | true    |

package/__tests__/api/sessions_test.js

@@ -0,0 +1,12 @@
+import API from '../../src/api/sessions'
+
+beforeEach(() => {
+  global.fetch = jest.fn().mockResolvedValue({ json: jest.fn().mockResolvedValue({ id: 1 }) })
+})
+
+describe('create', () => {
+  it('creates a session object', async () => {
+    const response = await new API('M01az53K').create()
+    expect(response.id).toEqual(1)
+  })
+})

package/__tests__/builders/input_builder_test.js

@@ -0,0 +1,117 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import Hellotext from '../../src/hellotext'
+import { InputBuilder } from '../../src/builders/input_builder'
+
+describe('when the input is first_name', () => {
+  const data = {
+    label: 'First Name',
+    type: 'text',
+    required: true,
+    placeholder: 'Enter your first name',
+    kind: 'first_name',
+  }
+
+  it('builds an article element that contains a label and input elements', () => {
+    const article = InputBuilder.build(data)
+    const label = article.querySelector('label')
+    const input = article.querySelector('input')
+
+    expect(label.innerText).toEqual('First Name')
+    expect(label.getAttribute('for')).toEqual('first_name')
+
+    expect(input.id).toEqual('first_name')
+    expect(input.type).toEqual('text')
+    expect(input.required).toEqual(true)
+    expect(input.placeholder).toEqual('Enter your first name')
+    expect(input.name).toEqual('first_name')
+  })
+})
+
+describe('when the input is last_name', () => {
+  const data = {
+    label: 'Last Name',
+    type: 'text',
+    required: false,
+    placeholder: 'Enter your last name',
+    kind: 'last_name',
+  }
+
+  it('builds an article element that contains a label and input elements', () => {
+    const article = InputBuilder.build(data)
+    const label = article.querySelector('label')
+    const input = article.querySelector('input')
+
+    expect(label.innerText).toEqual('Last Name')
+    expect(label.getAttribute('for')).toEqual('last_name')
+
+    expect(input.id).toEqual('last_name')
+    expect(input.type).toEqual('text')
+    expect(input.required).toEqual(false)
+    expect(input.placeholder).toEqual('Enter your last name')
+    expect(input.name).toEqual('last_name')
+  })
+})
+
+describe('when the input belongs to a property', () => {
+  const data = {
+    label: 'Email',
+    type: 'email',
+    required: true,
+    placeholder: 'Enter your email',
+    kind: 'email',
+    property: 'xybz',
+  }
+
+  it('builds an article element that contains a label and input elements', () => {
+    const article = InputBuilder.build(data)
+    const label = article.querySelector('label')
+    const input = article.querySelector('input')
+
+    expect(label.innerText).toEqual('Email')
+    expect(label.getAttribute('for')).toEqual('email')
+
+    expect(input.id).toEqual('email')
+    expect(input.type).toEqual('email')
+    expect(input.required).toEqual(true)
+    expect(input.placeholder).toEqual('Enter your email')
+    expect(input.name).toEqual('email')
+  })
+})
+
+describe('when the input is a phone number', () => {
+  const data = {
+    label: 'Phone',
+    type: 'tel',
+    required: true,
+    placeholder: 'Enter your phone number',
+    kind: 'phone',
+  }
+
+  beforeEach(() => {
+    Hellotext.business = {
+      country: {
+        prefix: '598',
+        code: 'UY',
+      }
+    }
+  })
+
+  it('builds an article element that contains a label and input elements', () => {
+    const article = InputBuilder.build(data)
+    const label = article.querySelector('label')
+    const input = article.querySelector('input')
+
+    expect(label.innerText).toEqual('Phone')
+    expect(label.getAttribute('for')).toEqual('phone')
+
+    expect(input.id).toEqual('phone')
+    expect(input.type).toEqual('tel')
+    expect(input.required).toEqual(true)
+    expect(input.placeholder).toEqual('Enter your phone number')
+    expect(input.name).toEqual('phone')
+    expect(input.value).toEqual('+598')
+  })
+})

package/__tests__/{event_emitter_test.js → core/event_test.js}

@@ -1,7 +1,27 @@
-import EventEmitter from "../src/eventEmitter"
+import Event from "../../src/core/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)
+  });
+});
 
 describe("#addSubscriber", function () {
-  const instance = new EventEmitter()
+  const instance = new Event()
 
   it("adds the callback to the list of subscribers for an event", () => {
     const callback = (session) => {}
@@ -11,7 +31,7 @@ describe("#addSubscriber", function () {
 });
 
 describe("#removeSubscriber", function () {
-  const instance = new EventEmitter()
+  const instance = new Event()
 
   it("removes the callback from the list of subscribers for an event", () => {
     const callback = (session) => {}
@@ -22,14 +42,14 @@ describe("#removeSubscriber", function () {
   });
 });
 
-describe("#emit", () => {
-  const instance = new EventEmitter()
+describe("#dispatch", () => {
+  const instance = new Event()
 
   it("notifies the listeners for an event", () => {
     const callback = jest.fn()
 
     instance.addSubscriber("session-set", callback)
-    instance.emit("session-set", "session_payload")
+    instance.dispatch("session-set", "session_payload")
 
     expect(callback).toHaveBeenCalledTimes(1)
   });

package/__tests__/hellotext_test.js

@@ -3,6 +3,7 @@
  */
 
 import Hellotext from "../src/hellotext";
+import { Business } from "../src/models"
 
 const getCookieValue = name => document.cookie.match('(^|;)\\s*' + name + '\\s*=\\s*([^;]+)')?.pop()
 
@@ -10,6 +11,10 @@ const expireSession = () => {
   document.cookie = "hello_session=;expires=Thu, 01 Jan 1970 00:00:00 GMT"
 }
 
+beforeEach(() => {
+  Business.prototype.fetchPublicData = jest.fn().mockResolvedValue({ whitelist: 'disabled' })
+})
+
 afterEach(() => {
   jest.clearAllMocks();
 });
@@ -204,3 +209,10 @@ describe("when hello_preview query parameter is present", () => {
     });
   })
 })
+
+describe('setSession', () => {
+  it('sets the session', () => {
+    Hellotext.setSession("12345")
+    expect(Hellotext.session).toEqual("12345")
+  })
+})

package/__tests__/models/business_test.js

@@ -0,0 +1,26 @@
+/**
+ * @jest-environment jsdom
+ */
+
+
+import { Business } from '../../src/models'
+
+describe('enabledWhitelist', () => {
+  beforeEach(() => {
+    global.fetch = jest.fn().mockResolvedValue({ json: jest.fn().mockResolvedValue({}) })
+  })
+
+  it('is true when the whitelist is an array', () => {
+    const business = new Business('123')
+    business.data = { whitelist: ['www.example.com'] }
+
+    expect(business.enabledWhitelist).toEqual(true)
+  })
+
+  it('is false when the whitelist is a string', () => {
+    const business = new Business('123')
+    business.data = { whitelist: 'disabled' }
+
+    expect(business.enabledWhitelist).toEqual(false)
+  })
+})

package/__tests__/models/cookies_test.js

@@ -0,0 +1,25 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { Cookies } from '../../src/models'
+
+beforeEach(() => {
+  document.cookie = ''
+})
+
+describe('set', () => {
+  it('sets the value of a cookie', () => {
+    expect(Cookies.get('hello_session')).toEqual(undefined)
+
+    Cookies.set('hello_session', 'session')
+    expect(Cookies.get('hello_session')).toEqual('session')
+  })
+})
+
+describe('get', () => {
+  it('gets the value of a cookie', () => {
+    document.cookie = 'hello_session=session'
+    expect(Cookies.get('hello_session')).toEqual('session')
+  })
+})

package/__tests__/models/form_collection_test.js

@@ -0,0 +1,100 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { Business, FormCollection } from '../../src/models'
+import Hellotext from '../../src/hellotext'
+
+beforeEach(() => {
+  Business.prototype.fetchPublicData = jest.fn().mockResolvedValue({ whitelist: 'disabled' })
+
+  Hellotext.initialize('M01az53K', {
+    autogenerateSession: false
+  })
+})
+
+describe('collect', () => {
+  it('does not fetch forms when there are no forms to fetch', async () => {
+    const fetch = jest.fn()
+    global.fetch = fetch
+
+    await Hellotext.forms.collect()
+
+    expect(fetch).not.toHaveBeenCalled()
+  })
+
+  it('fetches forms when there are forms to fetch', async () => {
+    global.fetch = jest.fn().mockResolvedValue({ json: jest.fn().mockResolvedValue({ id: 1 }) })
+
+    document.body.innerHTML = `
+      <form data-hello-form="1"></form>
+    `
+
+    await Hellotext.forms.collect()
+
+    expect(fetch).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('add', () => {
+  const forms = new FormCollection()
+  const form = { id: 1, name: 'Form 1' }
+
+  it('adds a form to the forms array', () => {
+    forms.add(form)
+    expect(forms.length).toEqual(1)
+  })
+
+  it('does not add a form that is already in the forms array', () => {
+    forms.add(form)
+    forms.add(form)
+
+    expect(forms.length).toEqual(1)
+  })
+})
+
+describe('getting elements', () => {
+  const forms = new FormCollection()
+  forms.add({ id: 1, name: 'Form 1' })
+  forms.add({ id: 2, name: 'Form 1' })
+
+  describe('getById', () => {
+    it('returns the form with the given id', () => {
+      expect(forms.getById(1).id).toEqual(1)
+    })
+  })
+
+  describe('getByIndex', () => {
+    it('returns the form at the given index', () => {
+      expect(forms.getByIndex(1).id).toEqual(2)
+    })
+  })
+})
+
+describe('includes', () => {
+  const forms = new FormCollection()
+  const form = { id: 1, name: 'Form 1' }
+
+  it('is true when the form is in the forms array', () => {
+    forms.add(form)
+    expect(forms.includes(1)).toEqual(true)
+  })
+
+  it('is false when the form is not in the forms array', () => {
+    expect(forms.includes(2)).toEqual(false)
+  })
+})
+
+describe('excludes', () => {
+  const forms = new FormCollection()
+  const form = { id: 1, name: 'Form 1' }
+
+  it('is true when the form is not in the forms array', () => {
+    expect(forms.excludes(2)).toEqual(true)
+  })
+
+  it('is false when the form is in the forms array', () => {
+    forms.add(form)
+    expect(forms.excludes(1)).toEqual(false)
+  })
+})