@hellotext/hellotext 1.0.8 → 1.0.10

package/README.md

@@ -1,7 +1,5 @@
 # Hellotext.js
 
-[![npm version](https://badge.fury.io/js/@hellotext%2Fhellotext.svg)](https://badge.fury.io/js/@hellotext%2Fhellotext)
-
 Track the events happening on your site to [Hellotext](https://www.hellotext.com) in real-time with this library. 
 
 ## Installation 
@@ -44,10 +42,44 @@ Tracking events is straightforward and perhaps the simplest example is tracking
 Hellotext.track("page.viewed");
 ```
 
-In the example above only the name of the action is required. 
+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.
-You can pass another url as the third argument to the `Hellotext.track` method.
+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"
+});
+```
+
+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");
+// {status: "received", success: true}
+```
+
+The parameters passed to the action must be a valid set of parameters as described in
+[Tracking Actions](https://www.hellotext.com/api#tracking).
+
+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_attributes: { name: "My App" }})
+{
+  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.'
+    },
+  ], 
+  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).
 
@@ -119,7 +151,7 @@ Hellotext.track("product.purchased", {
 
 | Property | Description | Type | Default |
 | --- | --- | --- | --- |
-| **amount** | Monetary amount that represents the revenue associated to this tracked event. | float | `null`
+| **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`
@@ -127,17 +159,21 @@ Hellotext.track("product.purchased", {
 
 ## Understanding Sessions
 
-The library looks for a session identifier present on the `hellotext_session` parameter. If the session is not present as a cookie neither it will create a new random session identifier. 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. 
+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` parameter. This will identify all the events back to the customer who opened the link.
+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`. 
 
 ```javascript
-Hellotext.session
+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. 
 
 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/lib/errors/notInitializedError.js

@@ -1,7 +1,9 @@
 class NotInitializedError extends Error {
   constructor() {
-    super("You need to initialize before tracking events. Call Hellotext.initialize and pass your public business id");
-    this.name = "NotInitializedError"
+    super(
+      'You need to initialize before tracking events. Call Hellotext.initialize and pass your public business id',
+    )
+    this.name = 'NotInitializedError'
   }
 }
 

package/lib/hellotext.js

@@ -1,25 +1,22 @@
-import { NotInitializedError } from "./errors/notInitializedError";
+import { NotInitializedError } from './errors/notInitializedError'
 
 const apiUrl = 'https://api.hellotext.com/v1/'
 
 class Hellotext {
+  static #_session
+  static #business_id
   /**
    * initialize the module.
    */
   static initialize(business_id) {
-    this.business_id = business_id
+    this.#business_id = business_id
 
     const urlSearchParams = new URLSearchParams(window.location.search)
     const session = urlSearchParams.get('hello_session') || getCookieValue('hello_session')
 
     if (session) {
-      this._session = session
+      this.#_session = session
       this.setSessionCookie(session)
-    } else {
-      this.mintAnonymousSession().then(response => {
-        this._session = response.id
-        this.setSessionCookie(response.id)
-      })
     }
   }
 
@@ -27,24 +24,26 @@ class Hellotext {
    *
    * @param { String } action a valid action name
    * @param { Object } params
-   * @param { String } url optional url, the url is automatically inferred when the action is tracked
    * @returns {Promise}
    */
-  static async track(action, params, url = null) {
-    if(this.notInitialized) { throw new NotInitializedError() }
+  static async track(action, params) {
+    if (this.notInitialized) { throw new NotInitializedError() }
 
-    const response = await fetch(apiUrl + "track/events", {
+    const response = await fetch(apiUrl + 'track/events', {
       headers: this.headers,
-      method: "post",
+      method: 'post',
       body: JSON.stringify({
-        session: this.session,
-        url: url || window.location.href,
+        session: await this.session,
         action,
         ...params,
-      })
+        url: (params && params.url) || window.location.href
+      }),
     })
 
-    return response.json()
+    const body = await response.json()
+    body.success = response.status === 200
+
+    return body
   }
 
   /**
@@ -52,49 +51,51 @@ class Hellotext {
    * @returns {Promise<any>|String}
    */
   static get session() {
-    if(this.notInitialized) { throw new NotInitializedError() }
+    if (this.notInitialized) { throw new NotInitializedError() }
 
-    if (this._session) return this._session
+    if (this.#_session) return this.#_session
 
-    return this.mintAnonymousSession().then(response => {
-      this._session = response.id
-      return response.id
-    }).then(() => this._session)
+    return this.mintAnonymousSession()
+      .then(response => {
+        this.#_session = response.id
+        this.setSessionCookie(response.id)
+      })
+      .then(() => this.#_session)
   }
 
   // private
 
   static async mintAnonymousSession() {
-    if(this.notInitialized) { throw new NotInitializedError() }
+    if (this.notInitialized) { throw new NotInitializedError() }
 
     const trackingUrl = apiUrl + 'track/sessions'
 
     this.mintingPromise = await fetch(trackingUrl, {
-      method: "post",
-      headers: { Authorization: `Bearer ${this.business_id}` },
+      method: 'post',
+      headers: { Authorization: `Bearer ${this.#business_id}` },
     })
 
     return this.mintingPromise.json()
   }
 
   static get headers() {
-    if(this.notInitialized) { throw new NotInitializedError() }
+    if (this.notInitialized) { throw new NotInitializedError() }
 
     return {
-      Authorization: `Bearer ${this.business_id}`,
+      Authorization: `Bearer ${this.#business_id}`,
       Accept: 'application.json',
-      'Content-Type': 'application/json'
+      'Content-Type': 'application/json',
     }
   }
 
   static setSessionCookie(session) {
-    if(this.notInitialized) { throw new NotInitializedError() }
+    if (this.notInitialized) { throw new NotInitializedError() }
 
     document.cookie = `hello_session=${session}`
   }
 
   static get notInitialized() {
-    return this.business_id === undefined
+    return this.#business_id === undefined
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellotext/hellotext",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Hellotext javascript client",
   "main": "index.js",
   "author": "Hellotext",