@saasquatch/squatch-js 2.6.0-3 → 2.6.0-5

package/dist/api/WidgetApi.d.ts

@@ -26,7 +26,7 @@ export default class WidgetApi {
      */
     constructor(config?: ConfigOptions);
     /**
-     * Creates/upserts user.
+     * Creates/upserts user, requests widget template.
      *
      * @param {Object} params Parameters for request
      * @param {Object?} params.user The user details
@@ -41,7 +41,7 @@ export default class WidgetApi {
      */
     upsertUser(params: WithRequired<WidgetConfig, "user">): Promise<any>;
     /**
-     * Description here.
+     * Requests widget template
      *
      * @param {Object} params Parameters for request
      * @param {Object} params.user The user details

package/dist/squatch.d.ts

@@ -14,6 +14,10 @@ export { Widgets, EmbedWidget, PopupWidget, DeclarativeEmbedWidget, DeclarativeP
  * Read the {@link WidgetApi} docs.
  *
  * @returns WidgetApi static instance
+ * @example
+ * squatch.api().render({ ... })
+ * squatch.api().upsertUser({ ... })
+ * squatch.api().squatchReferralCookie()
  */
 export declare function api(): WidgetApi | null;
 /**
@@ -22,6 +26,10 @@ export declare function api(): WidgetApi | null;
  * Read the {@link Widgets} docs.
  *
  * @returns static instance
+ * @example
+ * squatch.widgets().render({ widgetType: "w/widget-type" })
+ * squatch.widgets().upsertUser({ user: { ... }, widgetType: "w/widget-type" })
+ * squatch.widgets().autofill(".referral-code")
  */
 export declare function widgets(): Widgets | null;
 /**
@@ -30,14 +38,27 @@ export declare function widgets(): Widgets | null;
  * Read the {@link EventsApi} docs.
  *
  * @returns EventsApi static instance
+ *
+ * @example
+ * squatch.events().track({ ... })
  */
 export declare function events(): EventsApi | null;
 /**
  * Entry-point for high level API to render a widget using the instance of {@link Widgets} created when you call {@link #init init}.
+ *
+ * Read the {@link Widgets.render} docs.
+ *
+ * @example
+ * squatch.widget().then(res => {
+ *   const widget = res.widget
+ * }).catch(e => console.error("Did not render widget:", e))
  */
 export declare function widget(widgetConfig: WidgetConfig): Promise<WidgetResult | undefined> | undefined;
 /**
  * Extracts widget configuration from `_saasquatchExtra` UTM parameter. Initialises `squatch` and renders the widget as a {@link PopupWidget} via static instanct of {@link Widgets}.
+ *
+ * Called by default on startup via the loader script.
+ * @private
  */
 export declare function _auto(configIn: ConfigOptions): Promise<WidgetResult | undefined> | undefined;
 /**
@@ -50,7 +71,9 @@ export declare function _auto(configIn: ConfigOptions): Promise<WidgetResult | u
  * @param config Configuration details
  *
  * @example
- * squatch.init({tenantAlias:'test_basbtabstq51v'});
+ * squatch.init({
+ *   tenantAlias:'test_basbtabstq51v',
+ * });
  */
 export declare function init(configIn: ConfigOptions): void;
 /**
@@ -72,6 +95,10 @@ export declare function ready(fn: () => any): void;
  *
  * @param {string} selector Element class/id
  * @returns {void}
+ *
+ * @example
+ * squatch.autofill("input.referral-code")
+ * squatch.autofill("input#referral-code")
  */
 export declare function autofill(selector: string): void;
 /**

package/dist/squatch.esm.js

@@ -211,7 +211,7 @@ class WidgetApi {
     this.npmCdn = clean.npmCdn;
   }
   /**
-   * Creates/upserts user.
+   * Creates/upserts user, requests widget template.
    *
    * @param {Object} params Parameters for request
    * @param {Object?} params.user The user details
@@ -233,6 +233,7 @@ class WidgetApi {
       widgetType,
       engagementMedium = "POPUP",
       jwt,
+      locale,
       user
     } = clean;
     var tenantAlias = encodeURIComponent(this.tenantAlias);
@@ -241,7 +242,8 @@ class WidgetApi {
 
     var optionalParams = _buildParams({
       widgetType,
-      engagementMedium
+      engagementMedium,
+      locale
     });
 
     var path = "/api/v1/" + tenantAlias + "/widget/account/" + accountId + "/user/" + userId + "/upsert" + optionalParams;
@@ -251,7 +253,7 @@ class WidgetApi {
     return doPut(url, JSON.stringify(user), jwt);
   }
   /**
-   * Description here.
+   * Requests widget template
    *
    * @param {Object} params Parameters for request
    * @param {Object} params.user The user details
@@ -326,12 +328,15 @@ class WidgetApi {
 function _buildParams(_ref) {
   var {
     widgetType,
-    engagementMedium
+    engagementMedium,
+    locale
   } = _ref;
-  var widgetTypeP = widgetType ? "?widgetType=" + encodeURIComponent(widgetType) : "";
-  var engagementMediumP = (widgetType ? "&" : "?") + "engagementMedium=" + encodeURIComponent(engagementMedium);
-  var optionalParams = widgetTypeP + engagementMediumP;
-  return optionalParams;
+  var engagementMediumP = "engagementMedium=" + encodeURIComponent(engagementMedium);
+  var widgetTypeP = widgetType && "widgetType=" + encodeURIComponent(widgetType);
+  var localeP = locale && "locale=" + encodeURIComponent(locale);
+  var params = [engagementMediumP, widgetTypeP, localeP].filter(x => !!x);
+  var queryString = "?" + params.join("&");
+  return queryString;
 }
 
 // @ts-check
@@ -470,8 +475,7 @@ class Widget {
   }
 
   _findFrame() {
-    var element = this._findElement();
-
+    var element = this.container ? this._findElement() : document.body;
     var parent = element.shadowRoot || element;
     return parent.querySelector("iframe#squatchFrame");
   }
@@ -677,10 +681,7 @@ class Widget {
 
 function delay(duration) {
   return new Promise(function (resolve, reject) {
-    setTimeout(function () {
-      /* istanbul ignore next */
-      resolve(() => {});
-    }, duration);
+    setTimeout(resolve, duration);
   });
 }
 
@@ -715,6 +716,11 @@ var _log$6 = debug("squatch-js:EMBEDwidget");
  *
  * To create an EmbedWidget use {@link Widgets}
  *
+ * @example
+ * const widget = new EmbedWidget({ ... })
+ * widget.load() // Loads widget into the DOM
+ * widget.open() // Makes the iframe container visible
+ * widget.close() // Hides the iframe container
  */
 
 
@@ -766,6 +772,8 @@ class EmbedWidget extends Widget {
 
       frame.height = frameDoc.body.scrollHeight; // Adjust frame height when size of body changes
 
+      /* istanbul ignore next: hard to test */
+
       var ro = new contentWindow["ResizeObserver"](entries => {
         for (var entry of entries) {
           var {
@@ -775,15 +783,19 @@ class EmbedWidget extends Widget {
           frame.height = height;
         }
       });
-      ro.observe(await this._findInnerContainer(frame)); // Regular load - trigger event
+      var container = await this._findInnerContainer(frame);
+      ro.observe(container); // Regular load - trigger event
 
-      if (!this.container) {
+      if (!this.container || this.container instanceof HTMLElement && this.container.tagName.startsWith("SQUATCH-")) {
         this._loadEvent(_sqh);
 
         _log$6("loaded");
       }
     });
-  } // Un-hide if element is available and refresh data
+  }
+  /**
+   * Un-hide if element is available and refresh data
+   */
 
 
   open() {
@@ -846,6 +858,11 @@ var popupId = 0;
  *
  * To create a PopupWidget use {@link Widgets}
  *
+ * @example
+ * const widget = new PopupWidget({ ... })
+ * widget.load() // Loads the widget into a dialog element
+ * widget.open() // Opens the dialog element
+ * widget.close() // Hides the dialog element
  */
 
 class PopupWidget extends Widget {
@@ -871,7 +888,7 @@ class PopupWidget extends Widget {
     document.head.insertAdjacentHTML("beforeend", "<style>#" + this.id + "::-webkit-scrollbar { display: none; }</style>");
   }
 
-  _initialiseCTA(frame) {
+  _initialiseCTA() {
     if (!this.trigger) return;
     var triggerElement;
 
@@ -919,10 +936,9 @@ class PopupWidget extends Widget {
 
     var frame = this._createFrame();
 
-    this._initialiseCTA(frame);
-
-    var element = this._findElement();
+    this._initialiseCTA();
 
+    var element = this.container ? this._findElement() : document.body;
     var dialogParent = element.shadowRoot || element;
 
     var dialog = this._createPopupDialog();
@@ -988,8 +1004,7 @@ class PopupWidget extends Widget {
   }
 
   open() {
-    var element = this._findElement();
-
+    var element = this.container ? this._findElement() : document.body;
     var parent = element.shadowRoot || element;
     var dialog = parent.querySelector("#" + this.id);
     if (!dialog) throw new Error("Could not determine container div");
@@ -1018,8 +1033,7 @@ class PopupWidget extends Widget {
   }
 
   close() {
-    var element = this._findElement();
-
+    var element = this.container ? this._findElement() : document.body;
     var parent = element.shadowRoot || element;
     var dialog = parent.querySelector("#" + this.id);
     if (!dialog) throw new Error("Could not determine container div");
@@ -1048,14 +1062,31 @@ class PopupWidget extends Widget {
 
 var _log$4 = debug("squatch-js:widgets");
 /**
- *
  * `Widgets` is a factory for creating widgets. It's possible to build your own widgets using the
  * {@link WidgetApi} but most people will prefer to use these easy methods.
- *
+ * @class
  */
 
 
 class Widgets {
+  /**
+   * Instance of {@link WidgetApi}
+   */
+
+  /**
+   * Tenant alias of SaaSquatch tenant.
+   */
+
+  /**
+   * SaaSquatch domain for API requests.
+   * @default "https://app.referralsaasquatch.com"
+   */
+
+  /**
+   * Hosted CDN for npm packages
+   * @default "https://fast.ssqt.io/npm"
+   */
+
   /**
    * Initialize a new {@link Widgets} instance.
    *
@@ -1081,7 +1112,7 @@ class Widgets {
     this.tenantAlias = config.tenantAlias;
     this.domain = config.domain;
     this.npmCdn = config.npmCdn;
-    this.api = new WidgetApi(config); // listens to a 'submit_email' event in the theme.
+    this.api = new WidgetApi(config);
   }
   /**
    * This function calls the {@link WidgetApi.upsertUser} method, and it renders
@@ -1153,7 +1184,9 @@ class Widgets {
       return {
         widget: this._renderWidget(response, clean, {
           type: "passwordless",
-          engagementMedium: clean.engagementMedium
+          engagementMedium: clean.engagementMedium,
+          container: clean.container,
+          trigger: clean.trigger
         }),
         user: response.user
       };
@@ -1244,13 +1277,7 @@ class Widgets {
         if (Widgets._matchesUrl(rule.url)) {
           var _response$user, _response$user$referr;
 
-          console.log({
-            response,
-            rule
-          });
-
           if (rule.widgetType !== "CONVERSION_WIDGET" || (_response$user = response.user) != null && (_response$user$referr = _response$user.referredBy) != null && _response$user$referr.code) {
-            console.log("HERE");
             displayOnLoad = rule.displayOnLoad;
 
             _log$4("Display " + rule.widgetType + " on " + rule.url);
@@ -1662,8 +1689,62 @@ function decodeUserJwt(tokenStr) {
 }
 
 debug$1("sqh:DeclarativeWidget");
+/**
+ * Abstract class for building web-components that render SaaSquatch widgets to the DOM.
+ * @abstract
+ * @example
+ * class TestWidgetElement extends DeclarativeWidget {}
+ * const testWidget = new TestWidgetElement()
+ * testWidget.widgetType = 'w/widget-type'
+ * testWidget.type = 'EMBED'
+ * testWidget.renderWidget()
+ */
+
 
 class DeclarativeWidget extends HTMLElement {
+  /**
+   * Configuration overrides
+   * @default window.squatchConfig
+   */
+
+  /**
+   * Signed JWT containing user information
+   * @default window.squatchToken
+   */
+
+  /**
+   * Tenant alias of SaaSquatch tenant
+   * @default window.squatchTenant
+   */
+
+  /**
+   * widgetType of widget to load
+   */
+
+  /**
+   * Locale to render the widget in
+   */
+
+  /**
+   * Instance of {@link WidgetApi}
+   */
+
+  /**
+   * Instance of {@link AnalyticsApi}
+   */
+
+  /**
+   * Instance of {@link EmbedWidget} or {@link PopupWidget}
+   */
+
+  /**
+   * Determines whether to render the widget as an embedding widget or popup widget.
+   */
+
+  /**
+   * Container element to contain the widget iframe
+   * @default this
+   */
   constructor() {
     super();
     this.config = void 0;
@@ -1673,11 +1754,10 @@ class DeclarativeWidget extends HTMLElement {
     this.locale = void 0;
     this.widgetApi = void 0;
     this.analyticsApi = void 0;
-    this.type = void 0;
     this.widgetInstance = void 0;
+    this.type = void 0;
     this.container = void 0;
     this.element = void 0;
-    this._hasChildren = void 0;
 
     this._setWidget = (template, config) => {
       var _this$config;
@@ -1724,6 +1804,7 @@ class DeclarativeWidget extends HTMLElement {
       }
     };
 
+    this.reload = this.renderWidget;
     this.show = this.open;
     this.hide = this.close;
     this.attachShadow({
@@ -1733,7 +1814,6 @@ class DeclarativeWidget extends HTMLElement {
     this.token = window.squatchToken;
     this.tenant = window.squatchTenant;
     this.container = this;
-    this.locale = validateLocale(navigator.language.replace(/\-/g, "_"));
   }
 
   _setupApis(config) {
@@ -1772,6 +1852,7 @@ class DeclarativeWidget extends HTMLElement {
     if (!userObj) throw new Error("Could not load user information from jwt");
     var widgetInstance = await this.widgetApi.upsertUser({
       user: userObj,
+      locale: this.locale,
       engagementMedium: this.type,
       widgetType: this.widgetType,
       jwt: this.token
@@ -1781,6 +1862,11 @@ class DeclarativeWidget extends HTMLElement {
     return widgetInstance;
   }
 
+  /**
+   * Fetches widget content from SaaSquatch and builds a Widget instance to support rendering the widget in the DOM.
+   * @returns Instance of either {@link EmbedWidget} or {@link PopupWidget} depending on `this.type`
+   * @throws Throws an Error if `widgetType` is undefined
+   */
   async getWidgetInstance() {
     var widgetInstance;
     this.widgetType = this.getAttribute("widget") || undefined;
@@ -1793,29 +1879,64 @@ class DeclarativeWidget extends HTMLElement {
       widgetInstance = await this.renderUserUpsertVariant();
     }
 
-    if (!widgetInstance) throw new Error("Could not create widget.");
     this.widgetInstance = widgetInstance;
     return widgetInstance;
   }
+  /**
+   * Calls {@link getWidgetInstance} to build the Widget instance and loads the widget iframe into the DOM.
+   */
+
 
   async renderWidget() {
     await this.getWidgetInstance();
     await this.widgetInstance.load();
   }
+  /**
+   * Builds a Widget instance for the default error widget.
+   * @returns Instance of either {@link EmbedWidget} or {@link PopupWidget} depending on `this.type`
+   */
+
 
+  /**
+   * Calls `open` method of `widgetInstance`
+   * @throws Throws an Error if called before the widget has loaded
+   */
   open() {
+    if (!this.widgetInstance) throw new Error("Widget has not loaded yet");
     this.widgetInstance.open();
   }
+  /**
+   * Calls `close` method of `widgetInstance`
+   * @throws Throws an Error if called before the widget has loaded
+   */
+
 
   close() {
+    if (!this.widgetInstance) throw new Error("Widget has not loaded yet");
     this.widgetInstance.close();
   }
 
 }
 
+/**
+ * Base class for `squatch-embed` web-component
+ * @extends {DeclarativeWidget}
+ * @class
+ * @example
+ * window.createCustomElement('squatch-embed', DeclarativeEmbedWidget)
+ * const widget = document.querySelector('squatch-embed') as DeclarativeEmbedWidget
+ * widget.open()
+ * widget.close()
+ * widget.reload()
+ */
+
 class DeclarativeEmbedWidget extends DeclarativeWidget {
   constructor() {
     super();
+    /**
+     * @static
+     */
+
     this.type = "EMBED";
   }
 
@@ -1831,11 +1952,6 @@ class DeclarativeEmbedWidget extends DeclarativeWidget {
       case "widget":
         this.connectedCallback();
         break;
-      // // Specific to embed widgets
-      // case "container":
-      //   if (this.widgetInstance._findElement()) this.close();
-      //   this.connectedCallback();
-      //   break;
     }
   }
 
@@ -1849,9 +1965,25 @@ class DeclarativeEmbedWidget extends DeclarativeWidget {
   }
 
 }
+/**
+ * Base class for `squatch-popup` web-component
+ * @extends {DeclarativeWidget}
+ * @class
+ * @example
+ * window.createCustomElement('squatch-popup', DeclarativePopupWidget)
+ * const widget = document.querySelector('squatch-popup') as DeclarativePopupWidget
+ * widget.open()
+ * widget.close()
+ * widget.reload()
+ */
+
 class DeclarativePopupWidget extends DeclarativeWidget {
   constructor() {
     super();
+    /**
+     * @static
+     */
+
     this.type = "POPUP";
     this.addEventListener("click", e => {
       e.stopPropagation(); // SQUATCH-POPUP target means something in the shadowDOM was clicked (i.e. the dialog element)
@@ -1861,14 +1993,13 @@ class DeclarativePopupWidget extends DeclarativeWidget {
   }
 
   static get observedAttributes() {
-    return ["widget", "id", "open", "locale"];
+    return ["widget", "locale"];
   }
 
   attributeChangedCallback(attr, oldVal, newVal) {
     if (oldVal === newVal || !oldVal) return; // nothing to do
 
     switch (attr) {
-      case "open":
       case "locale":
       case "widget":
         this.connectedCallback();
@@ -1911,6 +2042,10 @@ var _events = null;
  * Read the {@link WidgetApi} docs.
  *
  * @returns WidgetApi static instance
+ * @example
+ * squatch.api().render({ ... })
+ * squatch.api().upsertUser({ ... })
+ * squatch.api().squatchReferralCookie()
  */
 
 function api() {
@@ -1923,6 +2058,10 @@ function api() {
  * Read the {@link Widgets} docs.
  *
  * @returns static instance
+ * @example
+ * squatch.widgets().render({ widgetType: "w/widget-type" })
+ * squatch.widgets().upsertUser({ user: { ... }, widgetType: "w/widget-type" })
+ * squatch.widgets().autofill(".referral-code")
  */
 
 function widgets() {
@@ -1935,6 +2074,9 @@ function widgets() {
  * Read the {@link EventsApi} docs.
  *
  * @returns EventsApi static instance
+ *
+ * @example
+ * squatch.events().track({ ... })
  */
 
 function events() {
@@ -1943,6 +2085,13 @@ function events() {
 }
 /**
  * Entry-point for high level API to render a widget using the instance of {@link Widgets} created when you call {@link #init init}.
+ *
+ * Read the {@link Widgets.render} docs.
+ *
+ * @example
+ * squatch.widget().then(res => {
+ *   const widget = res.widget
+ * }).catch(e => console.error("Did not render widget:", e))
  */
 
 function widget(widgetConfig) {
@@ -1952,6 +2101,9 @@ function widget(widgetConfig) {
 }
 /**
  * Extracts widget configuration from `_saasquatchExtra` UTM parameter. Initialises `squatch` and renders the widget as a {@link PopupWidget} via static instanct of {@link Widgets}.
+ *
+ * Called by default on startup via the loader script.
+ * @private
  */
 
 function _auto(configIn) {
@@ -1978,7 +2130,9 @@ function _auto(configIn) {
  * @param config Configuration details
  *
  * @example
- * squatch.init({tenantAlias:'test_basbtabstq51v'});
+ * squatch.init({
+ *   tenantAlias:'test_basbtabstq51v',
+ * });
  */
 
 function init(configIn) {
@@ -2023,6 +2177,10 @@ function ready(fn) {
  *
  * @param {string} selector Element class/id
  * @returns {void}
+ *
+ * @example
+ * squatch.autofill("input.referral-code")
+ * squatch.autofill("input#referral-code")
  */
 
 function autofill(selector) {