@hellotext/hellotext 1.8.7 → 2.0.0

package/__tests__/models/form_test.js

@@ -1,131 +0,0 @@
-/**
- * @jest-environment jsdom
- */
-
-import Hellotext from '../../src/hellotext'
-import { Form } from '../../src/models'
-
-describe('id', () => {
-  it('is the form id', () => {
-    const form = new Form({ id: 1 })
-    expect(form.id).toEqual(1)
-  })
-})
-
-describe('mount', () => {
-  const data = {
-    id: 1,
-    steps: [
-      {
-        header: { content: 'Header' },
-        inputs: [],
-        button: { content: 'Button' },
-        footer: { content: 'Footer' },
-      },
-    ]
-  }
-
-  const form = new Form(data)
-
-  beforeEach(() => {
-    Hellotext.business = {
-      locale: {
-        white_label: {
-          powered_by: 'Powered by Hellotext',
-        }
-      },
-      features: {
-        white_label: false,
-      }
-    }
-
-    document.body.innerHTML = ''
-  })
-
-  it('mounts the form', () => {
-    form.mount()
-    expect(document.body.querySelector('form')).not.toBeNull()
-  })
-
-  describe('when form has been completed', () => {
-    beforeEach(() => {
-      localStorage.setItem('hello-form-1', 'true')
-    })
-
-    it('does not mount the form automatically', () => {
-      form.mount()
-      expect(document.body.querySelector('form')).toBeNull()
-    })
-
-    it('mounts the form when ifCompleted is false', () => {
-      form.mount({ ifCompleted: false })
-      expect(document.body.querySelector('form')).not.toBeNull()
-    })
-  })
-})
-
-describe('markAsCompleted', () => {
-  it('saves the form as completed in localStorage', () => {
-    const form = new Form({ id: 1 })
-    form.markAsCompleted()
-    expect(localStorage.getItem('hello-form-1')).not.toBeNull()
-  })
-
-  it('emits a form:completed event', () => {
-    const form = new Form({ id: 1 })
-    const emit = jest.spyOn(Hellotext.eventEmitter, 'dispatch')
-
-    form.markAsCompleted()
-    expect(emit).toHaveBeenCalled()
-  })
-})
-
-describe('localeAuthKey', () => {
-  it('is email when the first step has an email input', () => {
-    const form = new Form({
-      steps: [
-        {
-          inputs: [{ kind: 'email' }]
-        }
-      ]
-    })
-
-    expect(form.localeAuthKey).toBe('email')
-  })
-
-  it('is phone when the first step has a phone input', () => {
-    const form = new Form({
-      steps: [
-        {
-          inputs: [{ kind: 'phone' }]
-        }
-      ]
-    })
-
-    expect(form.localeAuthKey).toBe('phone')
-  })
-
-  it('is phone_and_email when the first step has both email and phone inputs', () => {
-    const form = new Form({
-      steps: [
-        {
-          inputs: [{ kind: 'email' }, { kind: 'phone' }]
-        }
-      ]
-    })
-
-    expect(form.localeAuthKey).toBe('phone_and_email')
-  })
-
-  it('is none when the first step has neither email nor phone inputs', () => {
-    const form = new Form({
-      steps: [
-        {
-          inputs: [{ kind: 'first_name' }]
-        }
-      ]
-    })
-
-    expect(form.localeAuthKey).toBe('none')
-  })
-})

package/__tests__/models/query_test.js

@@ -1,97 +0,0 @@
-/**
- * @jest-environment jsdom
- */
-
-import { Query } from '../../src/models'
-
-describe('get', () => {
-  beforeEach(() => {
-    const windowMock = {
-      location: { search: "?hello_session=session&hello_preview=1" },
-    }
-
-    jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
-  })
-
-  it('gets the value of a query parameter', () => {
-    const query = new Query()
-
-    expect(query.get("session")).toEqual("session")
-    expect(query.get("preview")).toEqual("1")
-  })
-})
-
-describe('has', () => {
-  beforeEach(() => {
-    const windowMock = {
-      location: { search: "?hello_session=session" },
-    }
-
-    jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
-  })
-
-  it('is true when the query parameter is present', () => {
-    const query = new Query()
-    expect(query.has("session")).toEqual(true)
-  })
-
-  it('is false when the query parameter is not present', () => {
-    const query = new Query()
-    expect(query.has("preview")).toEqual(false)
-  })
-})
-
-describe('inPreviewMode', () => {
-  it('is true when the preview query parameter is present', () => {
-    const windowMock = {
-      location: { search: "?hello_preview" },
-    }
-
-    jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
-
-    expect(Query.inPreviewMode).toEqual(true)
-  })
-
-  it('is false when the preview query parameter is not present', () => {
-    const windowMock = {
-      location: { search: "" },
-    }
-
-    jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
-
-    expect(Query.inPreviewMode).toEqual(false)
-  })
-})
-
-describe('session', () => {
-  it('gets the session from the query parameter when present in query', () => {
-    const windowMock = {
-      location: { search: "?hello_session=session" },
-    }
-
-    jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
-
-    const query = new Query()
-    expect(query.session).toEqual("session")
-  })
-
-  it('gets the session from the cookie when not present in query', () => {
-    const windowMock = {
-      location: { search: "" },
-    }
-
-    jest.spyOn(global, 'window', 'get').mockImplementation(() => windowMock)
-
-    document.cookie = "hello_session=session"
-
-    const query = new Query()
-    expect(query.session).toEqual("session")
-  })
-})
-
-describe("#toHellotextParameter", () => {
-  it("prefixes the argument with hello_", () => {
-    const query = new Query()
-    expect(query.toHellotextParam("preview")).toEqual("hello_preview")
-  });
-})

package/docs/forms.md

@@ -1,176 +0,0 @@
-## Forms
-
-Create dynamic forms based on built-in subscriber attributes such as name, email, phone or other custom properties unique to your business.
-Then let Hellotext handle building the form, collecting, validating and authenticating the data users submit.
-
-For more information on how to create a form from the dashboard, view this [guide](https://help.hellotext.com/forms).
-
-### Configuration 
-
-Hellotext forms have a default configuration that can be overridden by passing an object when initializing the library. It has the following attributes by default:
-
-- `autoMount`: Automatically mount forms to the DOM when a `form` element with the `data-hello-form` attribute is found. Default is `true`.
-- `successMessage`: Display a contextual success message when a form is submitted successfully. Default is `true`.
-You can turn this off by setting it to `false`, or provide your custom success message by setting it to a string.
-
-```javascript
-Hellotext.initialize('HELLOTEXT_BUSINESS_ID', {
-  forms: {
-    autoMount: true,
-    successMessage: 'Thank you for submitting the form'
-  }
-})
-```
-
-### Collection Phase
-
-Hellotext uses the `MutationObserver` API to listen for changes in the DOM, specifically new form elements being added that have the `data-hello-form` attribute.
-
-You can access the forms object to also trigger the form collection phase manually.
-This is useful if you have a Single Page Application(SPA) and cannot hardcode the `data-hello-form` element on the rendered page.
-
-To manually collect forms, do the following.
-
-```javascript
-Hellotext.initialize('HELLOTEXT_BUSINESS_ID')
-Hellotext.forms.collect()
-```
-
-Once loaded, you can access the `FormCollection` object by calling `Hellotext.forms`.
-
-Make sure you have initialized with `Hellotext.initialize` otherwise an error is reported.
-
-Form collection finishes once Hellotext has fetched the data for the form elements present on the page from the Hellotext API.
-Afterwards, it dispatches a `forms:collected` event that you can subscribe to.
-
-```javascript
-Hellotext.on('forms:collected', forms => {
-  console.log(forms) // Instance of FormCollection
-})
-```
-
-The `FormCollection` class is a wrapper around the forms, which providers other useful methods.
-
-- `getById(id: string): Form` - Get a form by it's id
-- `getByIndex(index: number): Form` - Get a form by it's index
-- `includes(id: string): boolean` - Check if a form is included in the collection
-- `excludes(id: string): boolean` - Check if a form is not included in the collection
-- `length` - Get the number of forms in the collection
-- `forEach`, `map` are also supported.
-
-### Mounting forms
-
-Hellotext.js by default automatically mounts forms collected to the DOM. You can disable this behaviour by passing the `autoMountForms` option as `false` when initializing the library.
-
-```javascript
-Hellotext.initialize('HELLOTEXT_BUSINESS_ID', { autoMountForms: false })
-```
-
-If form mounting is disabled, Hellotext does not automatically mount form elements,
-you will have total control on when and where to mount the form elements. To mount a form object, you call the `mount` method on the form object.
-
-```javascript
-Hellotext.on('forms:collected', forms => {
-  forms.getByIndex(0).mount()
-})
-```
-
-Mounting a form creates the form and it's components that are associated to it, and attaches it to the DOM.
-Hellotext looks for a `form` element with the `data-hello-form` attribute and mounts the form inside it.
-If this condition is not met, Hellotext creates the form manually and appends it to the body of the document.
-We recommend to make the criteria met to ensure the form is loaded into an expected place in your page.
-
-Hellotext provides seamless integration with your website, once forms are completed, they are stored in the `localStorage`,
-this ensures that the form is not displayed again to the user if they have already completed it. Of course, sometimes it may be desired to 
-show the form to a user regardless if they have completed the form or not, in these cases, you can adjust the way you call `Form.mount()`,
-
-```javascript
-Hellotext.on('forms:collected', forms => {
-  forms.getByIndex(0).mount({ ifCompleted: false })
-})
-```
-
-This will mount the form regardless if the user has completed the form or not.
-
-### Validation
-
-Hellotext automatically validates the form inputs based on how they were configured on the dashboard
-using browser's native [checkValidity()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement/checkValidity).
-
-Once the user tries to submit the form and there are missing required fields,
-the submission is halted and we display default browser's error message using [HTMLObjectElement.validationMessage](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validationMessage) property.
-
-If the form contains a unique property and the client enters a value that is already taken,
-the submission will not be complete. Instead, an error will be reported to the client and the form will not be submitted.
-
-Uniqueness errors use the browser's native [setCustomValidity()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity)
-method which are reported as normal form validation errors, they can be styled with the `input:invalid` selector.
-
-### Understanding Verification
-
-Hellotext protects you from bot submissions and protects your customers from identity theft and impersonation.
-
-When a subscriber fills the form with an email and/or phone number, Hellotext sends a verification link to the value the submission had at the time of creation. 
-When the customer clicks the link in their email and/or the SMS they receive, the attribute is verified. 
-Once the email/phone number were verified, the data is considered to be _verified_.
-
-Once verification of a submission is complete, Hellotext performs an automatic merge (if needed) of all profiles 
-that have the same email and/or phone number. After automatic merging, if a property has multiple values, 
-it will be visible in the Audience page and the user can see the values that were merged and they can decide which one 
-to ignore and which one to accept.
-
-### Form Completion
-
-Once the form is considered to be complete, it will be sent to the Hellotext API to create(or update) a profile from the submission information.
-The library also dispatches a `form:completed` event that you can subscribe to. In addition, a Session object is set and stored on the browser's cookies.
-Additionally, the `Hellotext.session` is also set if no session was present already, you can listen for the session events by subscribing to `session-set` event.
-
-```javascript
-Hellotext.on('form:completed', (form) => {
-  console.log(form) // An object from FormData
-})
-
-{
-  state: 'completed',
-  completedAt: 1730114734999, // Timestamp when the form was completed
-  id: "xxxxx", // Id of the form that has been completed
-  data: {
-    first_name: "Billy",
-    last_name: "Butcher",
-    email: "theboys@hellotext.com",
-    phone: "+1234567890",
-    property_by_id[xxxxx]: "value"
-  }
-}
-```
-
-The data in the from will differ based on the inputs you have configured on the dashboard.
-
-### Understanding form's layout
-
-Hellotext assumes a fixed layout for forms, which are in order of Header, Inputs, Button and Notice.
-
-But you can override this layout if you want. Overriding a form's layout can be achieved
-by moving the placement of the form's components. For example, if you want to display the Button component after the Footer, here's how you can do that
-
-```html
-<form data-hello-form=":id">
-  <footer data-form-notice></footer>
-
-  <button data-form-button></button>
-</form>
-```
-
-Hellotext would simply load the contents inside the respective elements without creating the default layout.
-If these elements were not defined, Hellotext would render the button then the notice component.
-
-### Customizing the Form's styles
-
-Generated form elements have minimum styles to make them display correctly. No colors, borders or padding are applied.
-You can style the form elements to match your brand guidelines. Hellotext.js ships with a few lines of CSS to apply layout on the components.
-See `styles/index.css` for the default styles applied to the form elements.
-
-### White Labels
-
-As a subscriber to Hellotext, if your package does not support white labels, a `powered by Hellotext` logo is displayed at the bottom-right of the form.
-You are free to move the position of this element if you want, but it should be visible to your subscribers.

package/docs/tracking.md

@@ -1,203 +0,0 @@
-## Tracking Events
-
-Track subscriber events as they happen on your website and let Hellotext report them back to your business.
-
-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',
-})
-```
-
-### Headers 
-
-You can add any custom or additional headers to the request by passing a `headers` object in the parameter.
-
-```javascript
-Hellotext.track('page.viewed', {
-  headers: {
-    'X-Custom-Header': 'value',
-  },
-  // event related parameters
-})
-```
-
-### 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', { object_parameters: { name: null } })
-
-console.log(response.data)
-```
-
-yields
-
-```javascript
-{
-  errors: [
-    {
-      type: 'parameter_invalid_empty',
-      parameter: 'name',
-      description: 'This required parameter has an empty value. Provide a valid value for the parameter.',
-    },
-  ]
-}
-```
-
-For a complete list of errors types. See [Error Types](https://www.hellotext.com/api#errors)
-
-### Event parameters 
-
-Every tracked event has the following parameters which you can pass to the `track` method:
-
-
-| 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. If not specified, the currency default to the business' configured reporting currency.                                            | 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`  |
-
-### Associated object parameters
-
-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), these events require an existing object to be present 
-in order to be tracked aside from [Custom Actions](https://www.hellotext.com/api#create_an_action), which don't require the trackable to be present.
-
-Associated objects are represented by three possible parameters: 
-
-- `object`: An ID of an existing object of the same type. For example, when tracking app events, the `object` must be a previously created app object.
-- `object_parameters`: A set of parameters for creating a new object of the same type. For example, when tracking app events, the `object_parameters` must be a set of parameters for creating a new app object.
-- `object_type`: An ID or `name` of an existing custom object. Only required when tracking custom objects. Lets Hellotext know which type of object is being tracked. Learn more about [Objects](https://www.hellotext.com/api#objects).
-
-You can create the associated object directly by defining its parameters in a hash:
-
-```javascript
-Hellotext.track('order.placed', {
-  amount: 395.0,
-  currency: 'USD',
-  object_parameters: {
-    reference: '654321',
-    source: 'myshop',
-    items: [
-      {
-        product: 'erA2RAXE',
-        quantity: 2,
-      }
-    ]
-  },
-})
-```
-
-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.0,
-  currency: 'USD',
-  object: 'erA2RAXE',
-})
-```
-
-## List of actions
-
-The following is a complete list of built-in actions and their required associated objects. Each associated action accepts a possible set of two parameters 
-
-
-
-| Action                | Description                                              | Required Parameter                                                        |
-| --------------------- | -------------------------------------------------------- |---------------------------------------------------------------------------|
-| **app.installed**     | An app was installed.                                    | `object` or [object_parameters](https://www.hellotext.com/api#app)        |
-| **app.removed**       | An app was removed.                                      | `object` or [object_parameters](https://www.hellotext.com/api#app)              |
-| **app.spent**         | A customer spent on an app.                              | `object` or [object_parameters](https://www.hellotext.com/api#app)              |
-| **cart.abandoned**    | A cart was abandoned.                                    | `object` or [object_parameters](https://www.hellotext.com/api#products) |
-| **cart.added**        | Added an item to the cart.                               | `object` or [object_parameters](https://www.hellotext.com/api#products) |
-| **cart.removed**      | Removed an item from the cart.                           | `object` or [object_parameters](https://www.hellotext.com/api#products) |
-| **coupon.redeemed**   | A coupon was redeem by a customer.                       | `object` or [object_parameters](https://www.hellotext.com/api#coupons)    |
-| **form.completed**    | A form was completed by the customer.                    | `object` or [object_parameters](https://www.hellotext.com/api#forms)          |
-| **order.placed**      | Order has been placed.                                   | `object` or [object_parameters](https://www.hellotext.com/api#orders)       |
-| **order.confirmed**   | Order has been confirmed by you.                         | `object` or [object_parameters](https://www.hellotext.com/api#orders)       |
-| **order.cancelled**   | Order has been cancelled either by you or your customer. | `object` or [object_parameters](https://www.hellotext.com/api#orders)       |
-| **order.shipped**     | Order has been shipped to your customer.                 | `object` or [object_parameters](https://www.hellotext.com/api#orders)       |
-| **order.delivered**   | Order has been delivered to your customer.               | `object` or [object_parameters](https://www.hellotext.com/api#orders)       |
-| **page.viewed**       | A page was viewed by a customer.                         | `url`                                                                     |
-| **product.purchased** | A product has been purchased.                            | `object` or [object_parameters](https://www.hellotext.com/api#products) |
-| **product.viewed**    | A product page has been viewed.                          | `object` or [object_parameters](https://www.hellotext.com/api#products) |
-| **refund.requested**  | A customer requested a refund.                           | `object` or [object_parameters](https://www.hellotext.com/api#refunds)    |
-| **refund.received**   | A refund was issued by you to your customer.             | `object` or [object_parameters](https://www.hellotext.com/api#refunds)    |
-
-You can also create your **[own defined actions](https://www.hellotext.com/api#actions)**.
-
-### Tracking Custom Actions
-
-Once you have created a custom action, you track it by specifying the action's name. Custom actions do not require an associated object to be present in order to be tracked.
-However, it's possible to track custom actions alongside existing Objects, or new objects you introduce. 
-
-```javascript
-// Custom Action without an associated object
-
-Hellotext.track('appointment.booked')
-
-// Custom Action with an existing custom object instance.
-
-Hellotext.track('appointment.booked', {
-  object_type: 'appointment',
-  object: 'erA2RAXE',
-})
-
-// Custom Action with a new custom object instance.
-Hellotext.track('appointment.booked', {
-  object_type: 'appointment',
-  object_parameters: {
-    room: 'AA-101',
-    booked_at: 1632313200,
-  }
-})
-
-// Custom Action with a builtin object instance.
-
-Hellotext.track('appointment.booked', {
-  object_type: 'product',
-  object: 'erA2RAXE',
-})
-```