@saasquatch/component-environment 1.0.0-0

package/dist/fetchLocale.js

@@ -0,0 +1,37 @@
+import { getAppDomain, getTenantAlias } from "./environment";
+import { LOCALE_CONTEXT_NAME } from "./types";
+import { debug as _debug } from "./debug";
+const debug = (...args) => _debug(LOCALE_CONTEXT_NAME, ...args);
+const GET_LOCALE = `
+  query {
+    viewer {
+      ... on User {
+        locale
+      }
+    }
+  }
+`;
+export async function fetchLocale() {
+    debug("Fetching locale from GraphQL for current user");
+    try {
+        const result = await fetch(`${getAppDomain()}/api/v1/${getTenantAlias()}/graphql`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                query: GET_LOCALE,
+            }),
+        });
+        if (!result.ok) {
+            throw new Error("Failed to fetch locale");
+        }
+        const json = await result.json();
+        if (json.errors) {
+            throw new Error(JSON.stringify(json.errors, null, 2));
+        }
+        return json.viewer.locale || undefined;
+    }
+    catch (e) {
+        debug(`Failed to fetch locale for current user`, e.message);
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./environment";
+export * from "./contexts/UserIdentityContext";
+export * from "./contexts/LocaleContext";
+export * from "./contexts/ProgramContext";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./environment";
+export * from "./contexts/UserIdentityContext";
+export * from "./contexts/LocaleContext";
+export * from "./contexts/ProgramContext";

package/dist/listeners.d.ts

@@ -0,0 +1 @@
+export declare function startUserContextListenerForLocale(): void;

package/dist/listeners.js

@@ -0,0 +1,44 @@
+import equal from "@wry/equality";
+import { ContextListener } from "dom-context";
+import { USER_CONTEXT_NAME, LOCALE_CONTEXT_NAME } from "./types";
+import { lazilyStartLocaleContext } from "./contexts/LocaleContext";
+import { lazilyStartUserContext } from "./contexts/UserIdentityContext";
+import { fetchLocale } from "./fetchLocale";
+import { debug as _debug } from "./debug";
+const debug = (...args) => _debug(LOCALE_CONTEXT_NAME, ...args);
+const userContextListenerDiv = (() => {
+    const id = "__environment_context_listener";
+    let div = document.getElementById(id);
+    if (!div) {
+        div = document.createElement("div");
+        div.id = id;
+        document.documentElement.appendChild(div);
+    }
+    return div;
+})();
+// Listens to user changes and refetches the locale from GraphQL
+const userContextListenerForLocale = new ContextListener({
+    contextName: USER_CONTEXT_NAME,
+    element: userContextListenerDiv,
+    onChange: async (next) => {
+        if (next) {
+            const userProvider = lazilyStartUserContext();
+            if (!equal(userProvider.context, next)) {
+                debug("User context changed, refetching locale");
+                const locale = await fetchLocale();
+                const localeProvider = lazilyStartLocaleContext();
+                if (localeProvider.context !== locale) {
+                    debug(`New value fetched from GraphQL [${locale}]`);
+                    localeProvider.context =
+                        locale ||
+                            window.widgetIdent?.locale ||
+                            navigator.language.replace("-", "_");
+                }
+            }
+        }
+    },
+});
+export function startUserContextListenerForLocale() {
+    debug("Starting user context listener for locale updates");
+    userContextListenerForLocale.start();
+}

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+import type { ContextProvider } from "dom-context";
+declare global {
+    interface Window {
+        SquatchPortal?: PortalEnv;
+        widgetIdent?: WidgetIdent;
+        squatchUserIdentity?: ContextProvider<UserIdentity | undefined>;
+        squatchLocale?: ContextProvider<string | undefined>;
+        squatchProgramId?: ContextProvider<string | undefined>;
+    }
+}
+export declare type UserContextName = "sq:user-identity";
+export declare type LocaleContextName = "sq:locale";
+export declare type ProgramContextName = "sq:program-id";
+export declare const USER_CONTEXT_NAME: UserContextName;
+export declare const LOCALE_CONTEXT_NAME: LocaleContextName;
+export declare const PROGRAM_CONTEXT_NAME: ProgramContextName;
+/**
+ * The value stored in the UserContext
+ */
+export declare type UserIdentity = {
+    id: string;
+    accountId: string;
+    jwt?: string;
+    managedIdentity?: {
+        email: string;
+        emailVerified: boolean;
+        sessionData?: {
+            [key: string]: any;
+        };
+    };
+};
+export declare type UserId = {
+    id: string;
+    accountId: string;
+};
+export interface DecodedSquatchJWT {
+    exp?: number;
+    user: {
+        accountId: string;
+        id: string;
+    };
+}
+export interface DecodedWidgetAPIJWT {
+    exp?: number;
+    sub: string;
+}
+export declare type EngagementMedium = "EMBED" | "POPUP";
+export declare const DEFAULT_MEDIUM: EngagementMedium;
+/**
+ * Provided by the SaaSquatch GraphQL backend when a widget is rendered.
+ *
+ * Source: https://github.com/saasquatch/saasquatch/blob/805e51284f818f8656b6458bcee6181f378819d3/packages/saasquatch-core/app/saasquatch/controllers/api/widget/WidgetApi.java
+ *
+ */
+export interface WidgetIdent {
+    tenantAlias: string;
+    appDomain: string;
+    token: string;
+    userId: string;
+    accountId: string;
+    locale?: string;
+    engagementMedium?: "POPUP" | "EMBED";
+    programId?: string;
+    env?: string;
+}
+/**
+ * Portal env doesn't include User Id
+ */
+export declare type PortalEnv = Pick<WidgetIdent, "tenantAlias" | "appDomain" | "programId">;
+/**
+ * An interface for interacting with the SaaSquatch Admin Portal.
+ *
+ * Used for rendering widgets in a preview/demo mode.
+ */
+export interface SquatchAdmin {
+    /**
+     * Provides a way of providing user feedback when a widget is rendered in the SaaSquatch admin portal
+     *
+     * @param text
+     */
+    showMessage(text: string): void;
+}
+/**
+ * Type for the Javascript environment added by https://github.com/saasquatch/squatch-android
+ *
+ * Should exist as `window.SquatchAndroid`
+ */
+export interface SquatchAndroid {
+    /**
+     *
+     * @param shareLink
+     * @param messageLink fallback URL to redirect to if the app is not installed
+     */
+    shareOnFacebook(shareLink: string, messageLink: string): void;
+    /**
+     * Shows a native Android toast
+     *
+     * @param text
+     */
+    showToast(text: string): void;
+}
+/**
+ * An interface provided by Squatch.js V2 for widgets.
+ *
+ * See: https://github.com/saasquatch/squatch-js/blob/8f2b218c9d55567e0cc12d27d635a5fb545e6842/src/widgets/Widget.ts#L47
+ *
+ */
+export interface SquatchJS2 {
+    /**
+     * Opens the current popup widget (if loaded as a popup)
+     */
+    open?: () => void;
+    /**
+     * Closes the current popup widget (if loaded as a popup)
+     */
+    close?: () => void;
+    /**
+     * DEPRECATED used to update user details from inside the widget.
+     *
+     * Should no longer be used. Replace with natively using the GraphQL API and re-rendering locally. Will be removed in a future version of Squatch.js
+     *
+     * @deprecated
+     */
+    reload(userDetails: {
+        email: string;
+        firstName: string;
+        lastName: string;
+    }, jwt: string): void;
+}
+export declare type Environment = EnvironmentSDK["type"];
+export declare type EnvironmentSDK = {
+    type: "SquatchJS2";
+    api: SquatchJS2;
+    widgetIdent: WidgetIdent;
+} | {
+    type: "SquatchAndroid";
+    android: SquatchAndroid;
+    widgetIdent: WidgetIdent;
+} | {
+    type: "SquatchPortal";
+    env: PortalEnv;
+} | {
+    type: "SquatchAdmin";
+    adminSDK: SquatchAdmin;
+} | {
+    type: "None";
+};

package/dist/types.js

@@ -0,0 +1,4 @@
+export const USER_CONTEXT_NAME = "sq:user-identity";
+export const LOCALE_CONTEXT_NAME = "sq:locale";
+export const PROGRAM_CONTEXT_NAME = "sq:program-id";
+export const DEFAULT_MEDIUM = "EMBED";

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@saasquatch/component-environment",
+  "version": "1.0.0-0",
+  "description": "Environment and contexts for SaaSquatch components",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "engines": {
+    "node": ">=16.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saasquatch/program-tools.git"
+  },
+  "author": "Johan Venter <johan@saasquatch.com>",
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^4.7.3"
+  },
+  "dependencies": {
+    "@wry/equality": "^0.5.2",
+    "dom-context": "^1.2.0",
+    "jwt-decode": "^3.1.2"
+  }
+}

package/src/contexts/LocaleContext.ts

@@ -0,0 +1,50 @@
+import { ContextProvider } from "dom-context";
+import { LOCALE_CONTEXT_NAME } from "../types";
+import { debug as _debug } from "../debug";
+
+const debug = (...args: any[]) => _debug(LOCALE_CONTEXT_NAME, ...args);
+
+/**
+ * Lazily start the locale context provider. If it already exists, the existing provider is
+ * returned. This function is safe to call multiple times.
+ *
+ * @returns The global locale context provider
+ */
+export function lazilyStartLocaleContext() {
+  let globalProvider = window.squatchLocale;
+
+  if (!globalProvider) {
+    debug("Creating locale context provider");
+
+    globalProvider = new ContextProvider<string | undefined>({
+      element: document.documentElement,
+      initialState:
+        window.widgetIdent?.locale || navigator.language.replace("-", "_"),
+      contextName: LOCALE_CONTEXT_NAME,
+    }).start();
+
+    window.squatchLocale = globalProvider;
+  }
+
+  return globalProvider;
+}
+
+/**
+ * Overide the globally defined Locale context
+ *
+ * @param locale the new locale used by the user
+ */
+export function setLocale(locale?: string) {
+  const globalProvider = lazilyStartLocaleContext();
+  if (globalProvider.context !== locale) {
+    debug(`Setting locale context value [${locale}]`);
+    globalProvider.context = locale;
+  }
+}
+
+/**
+ * Get the current value of the locale context
+ */
+export function getLocale() {
+  return window.squatchLocale?.context;
+}

package/src/contexts/ProgramContext.ts

@@ -0,0 +1,50 @@
+import { ContextProvider } from "dom-context";
+import { PROGRAM_CONTEXT_NAME } from "../types";
+import { debug as _debug } from "../debug";
+
+const debug = (...args: any[]) => _debug(PROGRAM_CONTEXT_NAME, ...args);
+
+/**
+ * Lazily start the program context provider. If it already exists, the existing provider is
+ * returned. This function is safe to call multiple times.
+ *
+ * @returns The global program context provider
+ */
+export function lazilyStartProgramContext() {
+  let globalProvider = window.squatchProgramId;
+
+  if (!globalProvider) {
+    debug("Creating program context provider");
+
+    // Lazily creates a global provider
+    globalProvider = new ContextProvider<string | undefined>({
+      element: document.documentElement,
+      initialState: window.widgetIdent?.programId || undefined,
+      contextName: PROGRAM_CONTEXT_NAME,
+    }).start();
+
+    window.squatchProgramId = globalProvider;
+  }
+
+  return globalProvider;
+}
+
+/**
+ * Overide the globally defined Program ID context
+ *
+ * @param programId the new programID used by the user, or undefined if logged out
+ */
+export function setProgramId(programId: string | undefined) {
+  const globalProvider = lazilyStartProgramContext();
+  if (globalProvider.context !== programId) {
+    debug(`Setting program context value [${programId}]`);
+    globalProvider.context = programId;
+  }
+}
+
+/**
+ * Get the current value of the program context
+ */
+export function getProgramId() {
+  return window.squatchLocale?.context;
+}

package/src/contexts/UserIdentityContext.ts

@@ -0,0 +1,164 @@
+import decode from "jwt-decode";
+import { ContextProvider } from "dom-context";
+import { equal } from "@wry/equality";
+import { getEnvironmentSDK } from "../environment";
+import {
+  USER_CONTEXT_NAME,
+  UserIdentity,
+  DecodedSquatchJWT,
+  DecodedWidgetAPIJWT,
+} from "../types";
+import { startUserContextListenerForLocale } from "../listeners";
+import { debug as _debug } from "../debug";
+
+const debug = (...args: any[]) => _debug(USER_CONTEXT_NAME, ...args);
+
+/**
+ * Lazily start the user context provider. If it already exists, the existing provider is
+ * returned. This function is safe to call multiple times.
+ *
+ * @returns The global user context provider
+ */
+export function lazilyStartUserContext() {
+  let globalProvider = window.squatchUserIdentity;
+
+  if (!globalProvider) {
+    debug("Creating user context provider");
+
+    // Lazily creates a global provider
+    globalProvider = new ContextProvider<UserIdentity | undefined>({
+      element: document.documentElement,
+      initialState: _getInitialValue(),
+      contextName: USER_CONTEXT_NAME,
+    }).start();
+
+    window.squatchUserIdentity = globalProvider;
+    startUserContextListenerForLocale();
+  }
+
+  return globalProvider;
+}
+
+function isDecodedSquatchJWT(decoded: any): decoded is DecodedSquatchJWT {
+  return decoded.user && decoded.user.id && decoded.user.accountId;
+}
+
+function isDecodedWidgetAPIJWT(decoded: any): decoded is DecodedWidgetAPIJWT {
+  return decoded.sub && /.*:.*@.*:users/.test(decoded.sub);
+}
+
+/**
+ * Extract a user identity from a JWT
+ *
+ * @param jwt The JWT to extract a user identity from
+ * @returns The user identity or undefined if the JWT is not valid
+ */
+export function userIdentityFromJwt(jwt?: string): UserIdentity | undefined {
+  if (!jwt) return undefined;
+
+  try {
+    const decoded = decode<DecodedSquatchJWT | DecodedWidgetAPIJWT>(jwt);
+    const exp = decoded.exp;
+
+    let userId: string | undefined = undefined;
+    let accountId: string | undefined = undefined;
+
+    if (isDecodedWidgetAPIJWT(decoded)) {
+      // Pull the accountId and userId from the subject and Base64-decode them
+      // NOTE: This is to support classic theme engine widget token generation
+      const matches = decoded.sub.match(/(.*):(.*)@(.*):users/);
+      if (matches?.[1]) accountId = atob(matches[1]);
+      if (matches?.[2]) userId = atob(matches[2]);
+    } else if (isDecodedSquatchJWT(decoded)) {
+      accountId = decoded.user.accountId;
+      userId = decoded.user.id;
+    }
+
+    if (!userId || !accountId) {
+      return undefined;
+    }
+
+    // Check if the JWT has expired
+    if (exp && Date.now() >= exp * 1000) {
+      return undefined;
+    }
+
+    return {
+      id: userId,
+      accountId: accountId,
+      jwt,
+    };
+  } catch (e) {
+    // Invalid JWT
+    return undefined;
+  }
+}
+
+function _getInitialValue(): UserIdentity | undefined {
+  const sdk = getEnvironmentSDK();
+  switch (sdk.type) {
+    case "SquatchAndroid":
+    case "SquatchJS2":
+      return {
+        id: sdk.widgetIdent.userId,
+        accountId: sdk.widgetIdent.accountId,
+        jwt: sdk.widgetIdent.token,
+      };
+    case "SquatchPortal":
+      // Portals can have the jwt provided as a URL parameter, so look for that first
+      const searchParams = new URLSearchParams(document.location.search);
+      if (searchParams.has("jwt")) {
+        return userIdentityFromJwt(searchParams.get("jwt")!);
+      }
+
+      // Look for user identity in local storage
+      const stored = localStorage.getItem(USER_CONTEXT_NAME);
+      if (!stored) return undefined;
+      try {
+        const potentialUserIdent = JSON.parse(stored) as UserIdentity;
+        const identity = userIdentityFromJwt(potentialUserIdent.jwt);
+        if (identity) {
+          return {
+            ...potentialUserIdent, // for any stored managedIdentity fields
+            ...identity,
+          };
+        }
+        return undefined;
+      } catch (e) {
+        // Not valid JSON
+        return undefined;
+      }
+    case "SquatchAdmin":
+    case "None":
+      // Not logged in for admin portal / none default case
+      return undefined;
+  }
+}
+
+/**
+ * Overide the globally defined user context, and persists the user identity in local storage
+ *
+ * @param identity the new identity of the user, or undefined if logged out
+ */
+export function setUserIdentity(identity?: UserIdentity) {
+  const globalProvider = lazilyStartUserContext();
+
+  if (!equal(globalProvider.context, identity)) {
+    debug(`Setting user context value [${JSON.stringify(identity)}]`);
+    globalProvider.context = identity;
+  }
+
+  // Portals store identity in local storage
+  if (identity && getEnvironmentSDK().type === "SquatchPortal") {
+    localStorage.setItem(USER_CONTEXT_NAME, JSON.stringify(identity));
+  } else if (!identity) {
+    localStorage.removeItem(USER_CONTEXT_NAME);
+  }
+}
+
+/**
+ * Get the current value of the user context
+ */
+export function getUserIdentity() {
+  return window.squatchUserIdentity?.context;
+}

package/src/debug.ts

@@ -0,0 +1,7 @@
+const debugEnabled = localStorage.getItem("debug");
+
+export function debug(ns: string, ...args: any[]) {
+  if (debugEnabled) {
+    console.debug(`sq:environment:${ns}`, ...args);
+  }
+}

package/src/environment.ts

@@ -0,0 +1,114 @@
+import {
+  Environment,
+  EnvironmentSDK,
+  EngagementMedium,
+  DEFAULT_MEDIUM,
+} from "./types";
+
+/**
+ * Get the type of environment that this widget is being rendered in
+ *
+ * Should never return null.
+ */
+export function getEnvironment(): Environment {
+  return getEnvironmentSDK().type;
+}
+
+/**
+ * Get the SDK for interacting with the host environment
+ */
+export function getEnvironmentSDK(): EnvironmentSDK {
+  //@ts-ignore
+  if (window["SquatchAndroid"]) {
+    return {
+      type: "SquatchAndroid",
+      //@ts-ignore
+      android: window["SquatchAndroid"] as SquatchAndroid,
+      //@ts-ignore
+      widgetIdent: window["widgetIdent"],
+    };
+  }
+
+  //@ts-ignore
+  if (window["SquatchPortal"]) {
+    return {
+      type: "SquatchPortal",
+      //@ts-ignore
+      env: window["SquatchPortal"],
+    };
+  }
+
+  //@ts-ignore
+  if (window["SquatchAdmin"]) {
+    return {
+      type: "SquatchAdmin",
+      //@ts-ignore
+      adminSDK: window["SquatchAdmin"] as SquatchAdmin,
+    };
+  }
+
+  // Vanilla components mutates `widgetIdent` for portal, causing boilerplate to render as SquatchJS2
+  if (window["widgetIdent"] && window["widgetIdent"]?.env !== "demo") {
+    return {
+      type: "SquatchJS2",
+      //@ts-ignore
+      api: window.frameElement?.["squatchJsApi"],
+      //@ts-ignore
+      widgetIdent: window["widgetIdent"],
+    };
+  }
+
+  return {
+    type: "None",
+  };
+}
+
+export function isDemo() {
+  const sdk = getEnvironmentSDK();
+  return sdk.type === "None" || sdk.type === "SquatchAdmin";
+}
+
+// Fake tenant alias in demo mode
+const FAKE_TENANT = "demo";
+
+export function getTenantAlias(): string {
+  const sdk = getEnvironmentSDK();
+  switch (sdk.type) {
+    case "SquatchAndroid":
+    case "SquatchJS2":
+      return sdk.widgetIdent.tenantAlias;
+    case "SquatchAdmin":
+    case "None":
+      return FAKE_TENANT;
+    case "SquatchPortal":
+      return sdk.env.tenantAlias;
+  }
+}
+
+const DEFAULT_DOMAIN = "https://app.referralsaasquatch.com";
+export function getAppDomain(): string {
+  const sdk = getEnvironmentSDK();
+  switch (sdk.type) {
+    case "SquatchAndroid":
+    case "SquatchJS2":
+      return sdk.widgetIdent.appDomain;
+    case "SquatchPortal":
+      return sdk.env?.appDomain || DEFAULT_DOMAIN;
+    case "SquatchAdmin":
+    case "None":
+      return DEFAULT_DOMAIN;
+  }
+}
+
+export function getEngagementMedium(): EngagementMedium {
+  const sdk = getEnvironmentSDK();
+  switch (sdk.type) {
+    case "SquatchJS2":
+      return sdk.widgetIdent.engagementMedium || DEFAULT_MEDIUM;
+    case "SquatchAndroid":
+    case "SquatchPortal":
+    case "SquatchAdmin":
+    case "None":
+      return DEFAULT_MEDIUM;
+  }
+}