@epigraph/epigraph-std-lib 2.5.1 → 2.5.2-alpha

package/README.md

@@ -1,12 +1,49 @@
-# epigraph-std-lib
-
-Standard library to be used across multiple web components developed and maintained at Epigraph.
-
-### **EXPORTS AVAILABLE**:
-
-| Name  | Version  |
-|---|---|
-| [three](https://threejs.org/) | ![three version](https://img.shields.io/badge/three-0.149.0-green) |
-| [model-viewer](https://modelviewer.dev/) | ![@google/model-viewer version](https://img.shields.io/badge/model--viewer-3.0.2-green) |
-| [@epigraph/epigraph-analytics](https://www.npmjs.com/package/@epigraph/epigraph-analytics)  |![@epigraph/epigraph-analytics version](https://img.shields.io/badge/epigraph--analytics-0.2.6-green)|
-| [qr-creator](https://www.npmjs.com/package/qr-creator)  |![qr-creator version](https://img.shields.io/badge/qr--creator-1.0.0-green)|
+# INTRODUCTION
+
+Epigraph Standard Library or epigraph-std-lib is a collection of standards that we follow across our solutions. The idea is to have a single source of truth across solutions while ensuring that the dependencies are always up to date with the industry standards.
+
+### EPIGRAPH
+A global object that must only be initialized once per session and provides some common functionalities across solutions in that session.
+
+### EPIGRAPH LIBRARY EXPORTS
+
+| Name  | Description  |
+|---|---|
+| EpigraphBaseSolution | A base class intended to enforce some common functionalities across our solutions |
+| EpigraphLogger | A logger class that provides a convenient way for logging info, warning or errors in any given session |
+| EpigraphQrCoreGenerator | A Utility class that allows the generation of a QR code from a give string input |
+| EpigraphUnitsConverter | A Utility class that allows conversion between different standard unit, including but not limited to Distance, Color, etc. |
+| EpigraphUrlProcessor | A Utility class that provides various methods to generate, process, manipulate URLs |
+
+
+### 3rd PARTY LIBRARY EXPORTS
+
+| Name  | Version  |
+|---|---|
+| [three](https://threejs.org/) | ![three version](https://img.shields.io/badge/three-0.169.0-green) |
+| [model-viewer](https://modelviewer.dev/) | ![@google/model-viewer version](https://img.shields.io/badge/model--viewer-4.0.0-green) |
+| [@epigraph/epigraph-analytics](https://www.npmjs.com/package/@epigraph/epigraph-analytics)  |![@epigraph/epigraph-analytics version](https://img.shields.io/badge/epigraph--analytics-1.0.0-green)|
+| [qr-creator](https://www.npmjs.com/package/qr-creator)  |![qr-creator version](https://img.shields.io/badge/qr--creator-1.0.0-green)|
+
+
+# HOW TO:
+
+### Add a new EpigraphLibrary:
+1. Create a new directory under lib/EpigraphLibs/`<MyEpigraphLibrary>`
+2. Create the module file/s. Ensure that the names of these files are in camelCase.
+3. Export this module in lib/EpigraphLibs/epigraph-std-lib.ts as `export * from "./ThirdPartyLibs/main";`
+4. Write a test for this Library under tests/<MyEpigraphLibrary.test.ts>
+
+### Write a test: 
+We use [vitest](https://vitest.dev/guide/) to write tests in this repository using [happy-dom](https://www.npmjs.com/package/happy-dom) to support some but not all browser functionalities. In order to write a new test:
+
+1. Create a new file for a specific test under tests/ as `<MyEpigraphLibrary>`.test.ts
+2. Write a test following the instructions and samples [here](https://vitest.dev/guide/#writing-tests)
+3. Make sure to import the library from "../dist/epigraph-std-lib" to avoid any issues that might come up after bundling.
+4. Open a terminal and execute "npm run test". This will build all the libraries under dist/ and then run tests using those.
+
+
+# REFERENCES
+A huge thanks to everyone who inspired the setup for this repository:
+1. [Andreas Riedmuller's Article](https://dev.to/receter/how-to-create-a-react-component-library-using-vites-library-mode-4lma)
+2. [Vitest Docs](https://vitest.dev/guide/)

package/dist/Epigraph/constants/enums.d.ts

@@ -0,0 +1,5 @@
+export declare const enum ENVIRONMENT_TYPE {
+    DEVELOPMENT = "development",
+    STAGING = "staging",
+    PRODUCTION = "production"
+}

package/dist/Epigraph/epigraph.d.ts

@@ -0,0 +1,80 @@
+import { EpigraphLogger, LoggerModeNames } from '../EpigraphLibs/EpigraphLogger/epigraphLogger';
+import { ENVIRONMENT_TYPE } from './constants/enums';
+import { UrlProcessor } from '../EpigraphLibs/EpigraphUrlProcessor/epigraphUrlProcessor';
+import { EpigraphBaseSolution } from '../EpigraphLibs/EpigraphBaseSolution/epigraphBaseSolution';
+/**
+ * Epigraph component is intended to be a global source of truth/tracker in a given session for all of our components.
+ * This object would be responsible for serving/communicating/validating information, wherever necessary
+ * within or outside of the components.
+ *
+ * Additionally, it even exposes some useful functionality like QR code generation on demand, session tracking,
+ * global analytics tracker, etc.
+ */
+export declare class Epigraph {
+    id: string;
+    private _isReady;
+    private _logger;
+    private _initializer;
+    private _urlProcessor;
+    private _epigraphSessionId;
+    private _environment;
+    private _activeComponentsInSession;
+    private _staleComponentsInSession;
+    constructor(environment: ENVIRONMENT_TYPE, initializer: EpigraphBaseSolution);
+    get isReady(): boolean;
+    get logger(): EpigraphLogger;
+    get urlProcessor(): UrlProcessor;
+    get epigraphSessionId(): string;
+    get environment(): ENVIRONMENT_TYPE;
+    get initializer(): EpigraphBaseSolution;
+    get activeComponentsInSession(): Map<string, EpigraphBaseSolution>;
+    get staleComponentsInSession(): Map<string, EpigraphBaseSolution>;
+    /**
+     * Logs Epigraph Branding in the console to help redirect potential interests in the right direction.
+     */
+    logBranding(): void;
+    /**
+     * Registers a new component that was initialized on this page.
+     * This is optional from the perspective of the initialization flow but highly recommend
+     * registering any component that gets initialized in this session.
+     * Any component that inherits from EpigraphBaseSolution should automatically register itself on initialization.
+     *
+     * @param {EpigraphBaseSolution} solutionRef A type of Epigraph base component that is initialized in the session.
+     */
+    registerActiveComponent(solutionRef: EpigraphBaseSolution): void;
+    /**
+     * De-Registers a component that was initialized on this page.
+     * This is optional from the perspective of the unmount flow but highly recommend
+     * de-registering any component that gets removed in this session.
+     * Any component that inherits from EpigraphBaseSolution should automatically de-register itself on unmount.
+     *
+     * @param {EpigraphBaseSolution} solutionRef A type of Epigraph base component that is initialized in the session.
+     */
+    deregisterActiveComponent(solutionRef: EpigraphBaseSolution): void;
+    /**
+     * Gets the mode that the logger should be executed in, based on the runtime environment.
+     *
+     * @returns {LoggerModeNames} A valid logger mode name.
+     */
+    getLoggerModeNameFromEnvironment(): LoggerModeNames;
+    /**
+     * Generates a random UUID using crypto.randomUUID with a fallback on custom generator,
+     * if the first option fails for any reason in an environment.1
+     *
+     * @returns {string} A random generated ID.
+     */
+    static safeGenerateUuid(): string;
+    /**
+     * Generates an XPath based on a DOM nodes location on the page.
+     *
+     * @param {HTMLElement} element The element that we need the XPath for.
+     * @returns {string} The generated XPath.
+     */
+    static generateXPath(element: HTMLElement): string;
+}
+export { ENVIRONMENT_TYPE, EpigraphBaseSolution };
+declare global {
+    interface Window {
+        epigraph: Epigraph;
+    }
+}

package/dist/Epigraph/interfaces/IReturnTypes.d.ts

@@ -0,0 +1,7 @@
+export declare class ReturnNoPayload {
+    protected _success: boolean;
+    constructor(succees: boolean);
+    get success(): boolean;
+    set success(newValue: boolean);
+    get failed(): boolean;
+}

package/dist/EpigraphLibs/EpigraphBaseSolution/epigraphBaseSolution.d.ts

@@ -0,0 +1,16 @@
+import { ENVIRONMENT_TYPE } from '../../Epigraph/epigraph';
+export declare class EpigraphBaseSolution extends HTMLElement {
+    private _xPath;
+    private _uuid;
+    protected _elementName: string;
+    protected _solutionVersion: string;
+    protected _loggerContextOverride: string;
+    constructor(solutionVersion: string, environment: ENVIRONMENT_TYPE);
+    get elementName(): string;
+    /**
+     * This is the npm package version of this solution.
+     */
+    get solutionVersion(): string;
+    get uuid(): string;
+    get xPath(): string;
+}

package/dist/EpigraphLibs/EpigraphNexusApi/epigraphNexusApi.d.ts

@@ -0,0 +1,82 @@
+import { Result } from '../EpigraphResultFactory/epigraphResultFactory.ts';
+export declare class EpigraphNexusAPI {
+    private readonly baseUrl;
+    private readonly epgLocation;
+    private readonly epigraphSessionId;
+    private readonly epigraphXPath;
+    private readonly epigraphComponentVersion;
+    /**
+     * Constructs a new instance of the class with the provided parameters.
+     *
+     * @param {NexusEndpoints} [baseUrl=NexusEndpoints.PRODUCTION] - The base URL endpoint for the API, defaulting to the production environment.
+     * @param {string} epgLocation - The window.location.href associated with the epigraph data.
+     * @param {string} epigraphSessionId - The session identifier for the epigraph session.
+     * @param {string} epigraphComponentVersion - The version of the Epigraph Component(1.x.x or 1.2.1, etc.).
+     * @param {string} [epigraphXPath=""] - The XPath expression for epigraph data processing, defaults to an empty string.
+     * @param {NexusAPIVersions} [apiVersion=NexusAPIVersions.V1] - The API version to use, defaulting to version 1.
+     * @return {void}
+     */
+    constructor(baseUrl: NexusEndpoints | undefined, epgLocation: string, epigraphSessionId: string, epigraphComponentVersion?: string, epigraphXPath?: string, apiVersion?: NexusAPIVersions);
+    /*******************************************************************************************************************
+     * Configurator API Calls                                                                                          *
+     ******************************************************************************************************************/
+    getConfiguratorByExperienceId(experienceId: string, versionId?: string): Promise<Result>;
+    getConfiguratorByClientAccessKey(clientAccessKey: string, versionId?: string): Promise<Result>;
+    /*******************************************************************************************************************
+     * ConfiguratorLite API Calls                                                                                      *
+     ******************************************************************************************************************/
+    getConfiguratorLiteByExperienceId(experienceId: string, versionId?: string): Promise<Result>;
+    getConfiguratorLiteByProjectId(projectId: string, versionId?: string): Promise<Result>;
+    /*******************************************************************************************************************
+     * Save & Share Calls                                                                                              *
+     ******************************************************************************************************************/
+    postExperienceSaveAndShare(experienceId: string, saveData: object): Promise<Result>;
+    getExperienceSaveAndShare(experienceId: string, saveId: string): Promise<Result>;
+    /**
+     * Makes a call to the Nexus API and ensures the response is returned in JSON format.
+     * Automatically appends the `application/json` accept header if not already provided.
+     *
+     * @param {URL} url - The URL of the Nexus API endpoint to call.
+     * @param method
+     * @param body
+     * @param headers
+     * @return {Promise<Result>} A promise that resolves with the API response, encapsulated in a success or failure result format.
+     */
+    private callNexusAPI;
+    private buildNexusUrl;
+    /**
+     * Adds required headers to the provided headers object if they are not already present.
+     * Ensures that the headers include "accept", "EPG-Location", "EPG-Session-ID",
+     * and "EPG-XPATH" with their respective values.
+     *
+     * @param {Headers} headers - The headers object to which the required headers will be added.
+     * @return {Headers} The updated headers object containing all required headers.
+     */
+    private addRequiredHeaders;
+}
+export type QueryParameters = Record<string, any>;
+export declare enum NexusEndpoints {
+    PRODUCTION = "https://api.myepigraph.com/api/",
+    STAGING = "https://nexus.epigraph.dev/api/",
+    LOCAL = "https://nexus.test/api/"
+}
+export declare enum NexusAPIResourceIdentifier {
+    CLIENT_ACCESS_KEY = "client_access_key",
+    EXPERIENCE_ID = "experience_id",
+    PROJECT_ID = "project_id"
+}
+export declare enum NexusAPIRoutes {
+    CONFIGURATOR = "experience/configurator/",
+    CONFIGURATOR_LITE = "experience/configurator-lite/",
+    EXPERIENCE = "experience/",
+    SAVE = "save/"
+}
+export declare enum NexusAPIVersions {
+    V1 = "v1/"
+}
+export declare enum HTTPMethod {
+    GET = "GET",
+    POST = "POST",
+    PUT = "PUT",
+    DELETE = "DELETE"
+}

package/dist/EpigraphLibs/EpigraphQrCodeGenerator/epigraphQrCodeGenerator.d.ts

@@ -0,0 +1,33 @@
+import { LitElement } from 'lit';
+import { Ref } from 'lit/directives/ref.js';
+import { default as QrCreator } from 'qr-creator';
+export declare class EpigraphQrCodeGenerator extends LitElement {
+    static webComponentName: string;
+    _qrCodeGenCanvasRef: Ref<HTMLCanvasElement>;
+    static styles: import('lit').CSSResult;
+    /**
+     * Converts any given data uri to a blob.
+     *
+     * @param {string} dataUri Raw data URI, either fetched from an HTML Canvas or any other valid source.
+     * @returns {Blob} The generate blob.
+     */
+    dataUritoBlob(dataUri: string): Blob;
+    /**
+     * Generates a QR code as image data url for the qrCodeContent provided.
+     *
+     * @param {string} qrCodeContent The content to be embedded in the QR code.
+     * @returns {string} Session data URL for the generated QR code.
+     */
+    generateQrCode(qrCodeConfig?: QrCreator.Config): string;
+    /**
+     * Override for the LitElement's render method.
+     *
+     * @returns {html} HTML to be rendered by this component.
+     */
+    protected render(): import('lit-html').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "epigraph-qr-code-generator": EpigraphQrCodeGenerator;
+    }
+}

package/dist/EpigraphLibs/EpigraphResultFactory/epigraphResultFactory.d.ts

@@ -0,0 +1,13 @@
+export declare class Result {
+    private readonly _success;
+    private readonly _payload;
+    private readonly _status;
+    private readonly _message;
+    constructor(success: boolean, payload: any, status: number, message?: string);
+    get success(): boolean;
+    get payload(): any;
+    get status(): number;
+    get message(): string;
+}
+export declare function successResult(payload: any, status: number, message?: string): Result;
+export declare function failureResult(payload: any, status: number, error?: string): Result;

package/dist/EpigraphLibs/EpigraphUnitsConverter/{EpigraphUnitsConverter.d.ts → epigraphUnitsConverter.d.ts}

@@ -1,5 +1,5 @@
-import { DistanceUnits, UnitTypes } from "./Enums";
-import { IConvertedUnitResult } from "./Interfaces";
+import { DistanceUnits, UnitTypes } from './enums';
+import { IConvertedUnitResult } from './interfaces';
 /**
  * USAGE: Initialise this class with an initial value of the distance with it's unit.
  * Then use the exposed methods to get the value of the initial value in*() various units supported.

package/dist/EpigraphLibs/EpigraphUnitsConverter/{Interfaces.d.ts → interfaces.d.ts}

@@ -1,4 +1,4 @@
-import { DistanceUnits } from "./Enums";
+import { DistanceUnits } from './enums';
 export interface IConvertedUnitResult {
     value: number;
     valueUnit: DistanceUnits;

package/dist/EpigraphLibs/EpigraphUrlProcessor/epigraphUrlProcessor.d.ts

@@ -0,0 +1,54 @@
+export declare const enum QUERY_PARAMETER_ACTION_NAMES {
+    AR = "ar"
+}
+export declare const enum QUERY_PARAMETER_NAMES {
+    type = "t",
+    identifierType = "idt",
+    identifier = "id",
+    epigraphSessionId = "eid",
+    action = "a"
+}
+export declare class UrlProcessor {
+    private _baseUrl;
+    constructor(baseUrl?: string);
+    get baseUrl(): string;
+    set baseUrl(newBaseUrl: string);
+    /**
+     * Gets the parameters from the baseUrl of this class instance.
+     * This handles both encrypted and decrypted URLs.
+     *
+     * @param {string} parameterToSearch Name of the parameter that needs to be queried from the current URL.
+     * @returns {string | null} Either the value of the parameterToSearch or null if not found.
+     */
+    getParameterInUrl(parameterToSearch: string): string | null;
+    /**
+     * A convenience wrapper to test if the URL has a given parameter name in the query parameters.
+     * This handles both encrypted and decrypted URLs.
+     *
+     * @param {string} parameterToSearch Name of the parameter that needs to be queried from the current URL.
+     * @returns {boolean} Whether the parameter exists in the current URL.
+     */
+    hasParameterInUrl(parameterToSearch: string): boolean;
+    /**
+     * Generate the URL to be shown as View in your space QR code.
+     *
+     * @param {object} parametersToAdd Object containing <key>parameter_name: <value>parameter_value for the URL.
+     * @param {boolean} encryptParameters Whether the parameters be encrypted within the URL.
+     * @returns {URL} The generated URL.
+     */
+    generateQrCodeUrl(parametersToAdd?: object, encryptParameters?: boolean): URL;
+    /**
+     * Encrypts the query parameters in a given URL object using base64 encoding.
+     *
+     * @param {URL} url The original url object with query parameters.
+     * @returns {URL} Process URL object with encrypted parameters
+     */
+    encryptQueryParametersInUrl(url: URL): URL;
+    /**
+     * Decrypts the query parameters in a given URL object using base64 encoding.
+     *
+     * @param {URL} url The original url object with query parameters.
+     * @returns {URL} Process URL object with decrypted parameters
+     */
+    decryptQueryParametersInUrl(url: URL): URL;
+}

package/dist/EpigraphLibs/epigraphLibs.d.ts

@@ -0,0 +1,9 @@
+export * as epigraphLogger from './EpigraphLogger/epigraphLogger';
+export * as epigraphUrlProcessor from './EpigraphUrlProcessor/epigraphUrlProcessor';
+export * as epigraphBaseSolution from './EpigraphBaseSolution/epigraphBaseSolution';
+export * as epgUnitsConverter from './EpigraphUnitsConverter/epigraphUnitsConverter';
+export * as epigraphQrCodeGenerator from './EpigraphQrCodeGenerator/epigraphQrCodeGenerator';
+export { EpigraphAnalytics, GA3AnalyticsPlugin, GA4AnalyticsPlugin, OneTrustConsentPlugin, NexusAnalyticsPlugin, ConsentPluginNames } from '@epigraph/epigraph-analytics';
+export * from './EpigraphResultFactory/epigraphResultFactory';
+export * from './EpigraphNexusApi/epigraphNexusApi';
+export type { AnalyticsEvent } from '@epigraph/epigraph-analytics';

package/dist/ThirdPartyLibs/thirdPartyLibs.d.ts

@@ -0,0 +1,5 @@
+import { default as WebGL } from 'three/addons/capabilities/WebGL.js';
+export * from 'three';
+export * as ModelViewer from '@google/model-viewer';
+export * as MODEL_VIEWER_CONSTANTS from '@google/model-viewer/lib/constants';
+export { WebGL };

package/dist/epigraph-std-lib.d.ts

@@ -0,0 +1,3 @@
+export * from './Epigraph/epigraph';
+export * from './EpigraphLibs/epigraphLibs';
+export * from './ThirdPartyLibs/thirdPartyLibs';