@saasquatch/squatch-js 2.6.0-4 → 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
@@ -253,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
@@ -475,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");
   }
@@ -682,10 +681,7 @@ class Widget {
 
 function delay(duration) {
   return new Promise(function (resolve, reject) {
-    setTimeout(function () {
-      /* istanbul ignore next */
-      resolve(() => {});
-    }, duration);
+    setTimeout(resolve, duration);
   });
 }
 
@@ -720,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
  */
 
 
@@ -771,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 {
@@ -780,9 +783,10 @@ 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");
@@ -854,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 {
@@ -879,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;
 
@@ -927,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();
@@ -996,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");
@@ -1026,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");
@@ -1056,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.
    *
@@ -1089,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
@@ -1161,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
       };
@@ -1370,9 +1395,6 @@ class Widgets {
 
   static _matchesUrl(rule) {
     // If there were no matches, null is returned.
-    console.log({
-      href: window.location.href
-    });
     return window.location.href.match(new RegExp(rule)) ? true : false;
   }
 
@@ -1667,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;
@@ -1678,8 +1754,8 @@ 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;
 
@@ -1738,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) {
@@ -1787,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;
@@ -1799,15 +1879,23 @@ 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`
@@ -1830,9 +1918,25 @@ class DeclarativeWidget extends HTMLElement {
 
 }
 
+/**
+ * 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";
   }
 
@@ -1861,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)
@@ -1922,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() {
@@ -1934,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() {
@@ -1946,6 +2074,9 @@ function widgets() {
  * Read the {@link EventsApi} docs.
  *
  * @returns EventsApi static instance
+ *
+ * @example
+ * squatch.events().track({ ... })
  */
 
 function events() {
@@ -1954,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) {
@@ -1963,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) {
@@ -1989,7 +2130,9 @@ function _auto(configIn) {
  * @param config Configuration details
  *
  * @example
- * squatch.init({tenantAlias:'test_basbtabstq51v'});
+ * squatch.init({
+ *   tenantAlias:'test_basbtabstq51v',
+ * });
  */
 
 function init(configIn) {
@@ -2034,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) {