@saasquatch/component-environment 1.0.0-0 → 1.0.0-3

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2022-06-16
+
+Initial version.
+
+[unreleased]: https://github.com/saasquatch/program-tools/compare/component-environment@1.0.0...HEAD
+[1.0.0]: https://github.com/saasquatch/program-tools/releases/tag/%40saasquatch%2Fcomponent-environment%401.0.0

package/README.md

@@ -0,0 +1,46 @@
+Provides the environment for running SaaSquatch web components.
+
+SaaSquatch web components can run in a number of different environments, including:
+
+- in a widget via `squatch-js`
+- in a microsite (portal)
+- in a mobile SDK (i.e. `squatch-android`)
+- in the admin portal
+
+In each environment, a different set of context information about the tenant, user and program are provided, and the goal of this package is to normalize the differences in environments to provide a common API.
+
+The environment is provided in a set of contexts through `dom-context`, which provides vanilla global context providers. They can be accessed through a raw `ContextListener` or via `useDomContext` in `dom-context-hooks`.
+
+## General environment
+
+### `getEnvironment()`
+
+Get the environment type. The current possible values are: `SquatchJS2`, `SquatchAndroid`, `SquatchPortal`, `SquatchAdmin` or `None`.
+
+### `isDemo()`
+
+Returns whether components should run in demo/preview mode.
+
+### `getTenantAlias()`
+
+Get the current tenant alias.
+
+### `getAppDomain()`
+
+Get the SaaSquatch app domain.
+
+### `getEngagementMedium()`
+
+Get the current engagement medium. This is particularly important in widgets rendered by `squatch-js` for informing metadata about share link clicks.
+
+## User identity
+
+The user identity context name is exported in a constant `USER_CONTEXT_NAME`. The current value can be retrieved with `getUserIdentity()` and set with `setUserIdentity(identity)`.
+
+## Locale
+
+The locale context name is exported in a constnat `LOCALE_CONTEXT_NAME`. The current value can be retrieved with `getLocale()` and set with `setLocal(locale)`.
+
+## Program ID
+
+The program ID context name is exported in a constant `PROGRAM_CONTEXT_NAME`. The current value can be retrieved with `getProgramId()` and set with `setProgramId(programId)`.

package/dist/index.d.ts

@@ -1,5 +1,226 @@
-export * from "./types";
-export * from "./environment";
-export * from "./contexts/UserIdentityContext";
-export * from "./contexts/LocaleContext";
-export * from "./contexts/ProgramContext";
+import { ContextProvider } from 'dom-context';
+
+declare global {
+    interface Window {
+        SquatchPortal?: PortalEnv;
+        widgetIdent?: WidgetIdent;
+        squatchUserIdentity?: ContextProvider<UserIdentity | undefined>;
+        squatchLocale?: ContextProvider<string | undefined>;
+        squatchProgramId?: ContextProvider<string | undefined>;
+    }
+}
+declare type UserContextName = "sq:user-identity";
+declare type LocaleContextName = "sq:locale";
+declare type ProgramContextName = "sq:program-id";
+declare const USER_CONTEXT_NAME: UserContextName;
+declare const LOCALE_CONTEXT_NAME: LocaleContextName;
+declare const PROGRAM_CONTEXT_NAME: ProgramContextName;
+/**
+ * The value stored in the UserContext
+ */
+declare type UserIdentity = {
+    id: string;
+    accountId: string;
+    jwt?: string;
+    managedIdentity?: {
+        email: string;
+        emailVerified: boolean;
+        sessionData?: {
+            [key: string]: any;
+        };
+    };
+};
+declare type UserId = {
+    id: string;
+    accountId: string;
+};
+interface DecodedSquatchJWT {
+    exp?: number;
+    user: {
+        accountId: string;
+        id: string;
+    };
+}
+interface DecodedWidgetAPIJWT {
+    exp?: number;
+    sub: string;
+}
+declare type EngagementMedium = "EMBED" | "POPUP";
+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
+ *
+ */
+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
+ */
+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.
+ */
+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`
+ */
+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
+ *
+ */
+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;
+}
+declare type Environment = EnvironmentSDK["type"];
+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";
+};
+
+/**
+ * Get the type of environment that this widget is being rendered in
+ *
+ * Should never return null.
+ */
+declare function getEnvironment(): Environment;
+/**
+ * Get the SDK for interacting with the host environment
+ */
+declare function getEnvironmentSDK(): EnvironmentSDK;
+declare function isDemo(): boolean;
+declare function getTenantAlias(): string;
+declare function getAppDomain(): string;
+declare function getEngagementMedium(): EngagementMedium;
+
+/**
+ * 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
+ */
+declare function lazilyStartUserContext(): ContextProvider<UserIdentity | undefined>;
+/**
+ * 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
+ */
+declare function userIdentityFromJwt(jwt?: string): UserIdentity | 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
+ */
+declare function setUserIdentity(identity?: UserIdentity): void;
+/**
+ * Get the current value of the user context
+ */
+declare function getUserIdentity(): UserIdentity | undefined;
+
+/**
+ * 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
+ */
+declare function lazilyStartLocaleContext(): ContextProvider<string | undefined>;
+/**
+ * Overide the globally defined Locale context
+ *
+ * @param locale the new locale used by the user
+ */
+declare function setLocale(locale?: string): void;
+/**
+ * Get the current value of the locale context
+ */
+declare function getLocale(): string | undefined;
+
+/**
+ * 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
+ */
+declare function lazilyStartProgramContext(): ContextProvider<string | undefined>;
+/**
+ * Overide the globally defined Program ID context
+ *
+ * @param programId the new programID used by the user, or undefined if logged out
+ */
+declare function setProgramId(programId: string | undefined): void;
+/**
+ * Get the current value of the program context
+ */
+declare function getProgramId(): string | undefined;
+
+export { DEFAULT_MEDIUM, DecodedSquatchJWT, DecodedWidgetAPIJWT, EngagementMedium, Environment, EnvironmentSDK, LOCALE_CONTEXT_NAME, LocaleContextName, PROGRAM_CONTEXT_NAME, PortalEnv, ProgramContextName, SquatchAdmin, SquatchAndroid, SquatchJS2, USER_CONTEXT_NAME, UserContextName, UserId, UserIdentity, WidgetIdent, getAppDomain, getEngagementMedium, getEnvironment, getEnvironmentSDK, getLocale, getProgramId, getTenantAlias, getUserIdentity, isDemo, lazilyStartLocaleContext, lazilyStartProgramContext, lazilyStartUserContext, setLocale, setProgramId, setUserIdentity, userIdentityFromJwt };