@transcommerce/cwm-shared 1.1.88 → 1.1.91

package/lib/helpers/utilities.d.ts

@@ -1,5 +1,25 @@
 import { HttpResponse, HttpResponseBase } from '@angular/common/http';
 import * as i0 from "@angular/core";
+/**
+ * A comprehensive utility service providing static helper methods for common operations across the application.
+ *
+ * This service includes utilities for:
+ * - **Cookie Management**: Getting, setting, removing, and checking cookies with proper encoding
+ * - **Security**: Scrubbing sensitive data from logs to prevent accidental exposure of PII and credentials
+ * - **HTTP Response Handling**: Parsing and extracting meaningful messages from HTTP responses and errors
+ * - **Date/Time Formatting**: Converting dates to various human-readable formats and calculating durations
+ * - **String Manipulation**: Case conversion, text expansion, trimming, and parsing operations
+ * - **Data Processing**: Array operations, deep cloning, searching, and JSON parsing with fallback handling
+ * - **Validation**: Type checking, URL validation, and network connectivity checks
+ *
+ * @example
+ * // Using static utility methods
+ * const scrubbedLog = Utilities.scrubForLog(sensitiveData);
+ * const formattedDate = Utilities.printFriendlyDate(new Date());
+ * const errorMessage = Utilities.getHttpResponseMessage(httpError);
+ *
+ * @injectable
+ */
 export declare class Utilities {
     static readonly captionAndMessageSeparator = ":";
     static readonly noNetworkMessageCaption = "No Network";
@@ -8,11 +28,53 @@ export declare class Utilities {
     static readonly accessDeniedMessageDetail = "";
     static readonly notFoundMessageCaption = "Not Found";
     static readonly notFoundMessageDetail = "The target resource cannot be found";
+    /**
+     * Cookie management utilities providing cross-browser compatible methods for cookie operations.
+     * All cookie keys and values are properly URL-encoded/decoded to handle special characters safely.
+     *
+     * Methods:
+     * - getItem: Retrieves a cookie value by name, returns null if not found
+     * - setItem: Sets a cookie with optional expiration, path, domain, and secure flags
+     * - removeItem: Removes a cookie by setting its expiration to the past
+     * - hasItem: Checks if a cookie exists
+     * - keys: Returns an array of all cookie names
+     */
     static cookies: {
+        /**
+         * Retrieves the value of a cookie by its name with proper URL decoding.
+         * @param sKey The cookie name to retrieve
+         * @returns The decoded cookie value or null if not found
+         */
         getItem: (sKey: string) => string | null;
+        /**
+         * Sets a cookie with optional expiration, domain, path, and secure flag.
+         * @param sKey The cookie name
+         * @param sValue The cookie value
+         * @param vEnd The expiration (Number for max-age in seconds, String for expires date, Date object, or null for session cookie)
+         * @param sPath The path scope for the cookie (defaults to all paths if empty)
+         * @param sDomain The domain scope for the cookie (defaults to current domain if empty)
+         * @param bSecure Whether to set the Secure flag (cookie only sent over HTTPS)
+         * @returns true if the cookie was set successfully, false otherwise
+         */
         setItem: (sKey: string, sValue: string, vEnd: any, sPath: string, sDomain: string, bSecure: unknown) => boolean;
+        /**
+         * Removes a cookie by setting its expiration to a past date.
+         * @param sKey The cookie name to remove
+         * @param sPath The path scope (must match the path used when setting the cookie)
+         * @param sDomain The domain scope (must match the domain used when setting the cookie)
+         * @returns true if the removal was attempted, false if key was invalid
+         */
         removeItem: (sKey: string | number | boolean, sPath: string, sDomain: string) => boolean;
+        /**
+         * Checks if a cookie with the specified name exists.
+         * @param sKey The cookie name to check
+         * @returns true if the cookie exists, false otherwise
+         */
         hasItem: (sKey: string | number | boolean) => boolean;
+        /**
+         * Retrieves all cookie names as an array.
+         * @returns An array of all cookie names with proper URL decoding applied
+         */
         keys: () => string[];
     };
     /** Scrubs sensitive information from logs, such as email addresses, JWTs, tokens, GUIDs, credit card numbers, SSNs, phone numbers, and common password/username patterns.
@@ -30,49 +92,288 @@ export declare class Utilities {
      * console.log(scrubbedData);
      */
     static scrubForLog(input: any): string;
+    /**
+     * Extracts all messages from an HTTP response or error, formatting them as key-value pairs.
+     * Automatically detects network errors, access denied, and not found responses with special formatting.
+     *
+     * @param data The HTTP response or error object
+     * @returns An array of formatted message strings in the format "Key: Value"
+     */
     static getHttpResponseMessages(data: HttpResponseBase): string[];
+    /**
+     * Extracts a single consolidated message from an HTTP response or error.
+     * Searches in priority order: network message, not found message, error_description, error, then general response messages.
+     *
+     * @param data The HTTP response or error object
+     * @returns A single formatted message string
+     */
     static getHttpResponseMessage(data: HttpResponseBase | any): string;
+    /**
+     * Searches for a specific message within HTTP response messages.
+     * Can search in caption only or in full message text, and can optionally include the caption in the result.
+     *
+     * @param messageToFind The message or caption text to search for (case-insensitive)
+     * @param data The HTTP response or error object
+     * @param searchInCaptionOnly If true, only searches in the caption portion (before separator), defaults to true
+     * @param includeCaptionInResult If true, includes the caption in the returned result, defaults to false
+     * @returns The matching message or null if not found
+     */
     static findHttpResponseMessage(messageToFind: string, data: HttpResponse<any> | any, searchInCaptionOnly?: boolean, includeCaptionInResult?: boolean): any;
+    /**
+     * Extracts the response body from an HTTP response or error.
+     * For successful responses, returns the body property. For error responses, prioritizes error over message and statusText.
+     *
+     * @param response The HTTP response or error response
+     * @returns The response body, error, or null if none available
+     */
     static getResponseBody(response: HttpResponseBase): any;
+    /**
+     * Checks if the response indicates a network error (status 0).
+     * @param response The HTTP response to check
+     * @returns true if status is 0 (no network connection), false otherwise
+     */
     static checkNoNetwork(response: HttpResponseBase): boolean;
+    /**
+     * Checks if the response indicates an access denied error (status 403).
+     * @param response The HTTP response to check
+     * @returns true if status is 403 (Forbidden), false otherwise
+     */
     static checkAccessDenied(response: HttpResponseBase): boolean;
+    /**
+     * Checks if the response indicates a not found error (status 404).
+     * @param response The HTTP response to check
+     * @returns true if status is 404 (Not Found), false otherwise
+     */
     static checkNotFound(response: HttpResponseBase): boolean;
+    /**
+     * Validates if a URL points to localhost or 127.0.0.1.
+     * @param url The URL to check
+     * @param base Optional base URL for resolving relative URLs
+     * @returns true if the URL hostname is localhost or 127.0.0.1, false otherwise
+     */
     static checkIsLocalHost(url: string, base?: string): boolean;
+    /**
+     * Parses a query parameter string into a key-value object.
+     * Handles standard URL query string format (key=value&key=value).
+     *
+     * @param paramString The query parameter string (e.g., "id=123&name=test")
+     * @returns An object with key-value pairs, or null if paramString is empty
+     */
     static getQueryParamsFromString(paramString: string): {
         [key: string]: string;
     } | null;
+    /**
+     * Splits a string into two parts based on the first occurrence of a separator.
+     * Both parts are trimmed of whitespace.
+     *
+     * @param text The text to split
+     * @param separator The separator string to split on
+     * @returns An object with firstPart and secondPart (secondPart is null if separator not found)
+     */
     static splitInTwo(text: string, separator: string): {
         firstPart: string;
         secondPart: any;
     };
+    /**
+     * Safely stringifies an object, filtering out complex types and handling circular references.
+     * If direct JSON.stringify fails, creates a sanitized object containing only primitive properties.
+     *
+     * @param object The object to stringify
+     * @returns A JSON string representation of the object, or a sanitized version if stringification fails
+     */
     static safeStringify(object: {
         [x: string]: any;
         hasOwnProperty: (arg0: string) => any;
     }): string;
+    /**
+     * Safely parses a JSON string with fallback handling.
+     * Returns the parsed object if valid JSON, or returns undefined/value if parsing fails.
+     *
+     * @param value The JSON string to parse
+     * @returns The parsed object, 'undefined' if the string is 'undefined', or the original value if parsing fails
+     */
     static JsonTryParse(value: string): any;
+    /**
+     * Checks if an object has no properties.
+     * @param obj The object to check
+     * @returns true if the object is empty (no own properties), false otherwise
+     */
     static TestIsObjectEmpty(obj: any): boolean;
+    /**
+     * Checks if a value is undefined.
+     * @param value The value to check
+     * @returns true if the value is undefined, false otherwise
+     */
     static TestIsUndefined(value: any): value is undefined;
+    /**
+     * Checks if a value is a string.
+     * @param value The value to check
+     * @returns true if the value is a string primitive or String object, false otherwise
+     */
     static TestIsString(value: any): value is string | String;
+    /**
+     * Capitalizes the first letter of a string while leaving the rest unchanged.
+     * @param text The text to capitalize
+     * @returns The text with the first character uppercased, or the original text if empty
+     */
     static capitalizeFirstLetter(text: string): string;
+    /**
+     * Converts a string to title case, capitalizing the first letter of each word.
+     * @param text The text to convert to title case
+     * @returns The text in title case format
+     */
     static toTitleCase(text: string): string;
+    /**
+     * Converts a string or array of strings to lowercase.
+     * Supports overloaded signatures for both single string and array inputs.
+     *
+     * @param items A string or array of strings to convert to lowercase
+     * @returns The lowercased string or array of lowercased strings
+     */
     static toLowerCase(items: string): any;
     static toLowerCase(items: string[]): any;
+    /**
+     * Generates a unique random ID string.
+     * @returns A string representation of a random number between 1,000,000 and 9,000,000
+     */
     static uniqueId(): string;
+    /**
+     * Generates a random integer within a specified range (inclusive).
+     * @param min The minimum value (inclusive)
+     * @param max The maximum value (inclusive)
+     * @returns A random integer between min and max
+     */
     static randomNumber(min: number, max: number): number;
+    /**
+     * Gets the base URL of the current application.
+     * Handles cases where window.location.origin is not available by constructing it from components.
+     *
+     * @returns The base URL without trailing slash (e.g., "http://localhost:4200")
+     */
     static baseUrl(): string;
+    /**
+     * Formats a date to display only the date portion in human-readable format.
+     * Example output: "Monday, 1st January 2024"
+     *
+     * @param date The date to format
+     * @returns A formatted date string with day of week, day of month with ordinal suffix, month name, and year
+     */
     static printDateOnly(date: Date): string;
+    /**
+     * Formats a date to display only the time portion in 12-hour format with AM/PM.
+     * Example output: "2:30 PM"
+     *
+     * @param date The date to format
+     * @returns A formatted time string in HH:MM AM/PM format
+     */
     static printTimeOnly(date: Date): string;
+    /**
+     * Combines date and time formatting into a single readable string.
+     * Example output: "Monday, 1st January 2024 at 2:30 PM"
+     *
+     * @param date The date to format
+     * @param separator The text to insert between date and time (defaults to 'at')
+     * @returns A combined date and time string
+     */
     static printDate(date: Date, separator?: string): string;
+    /**
+     * Formats a date using friendly relative terminology for recent dates.
+     * Returns "Today", "Yesterday", or full date for older dates.
+     *
+     * @param date The date to format
+     * @param separator The text to insert between "Today"/"Yesterday" and time (defaults to '-')
+     * @returns A friendly date string (e.g., "Today - 2:30 PM" or full date for older dates)
+     */
     static printFriendlyDate(date: Date, separator?: string): string;
+    /**
+     * Formats a date to a short format with time.
+     * Example output: "03/01/2024 - 2:30 PM"
+     *
+     * @param date The date to format
+     * @param separator The separator between month, day, and year (defaults to '/')
+     * @param dateTimeSeparator The separator between date and time (defaults to '-')
+     * @returns A formatted short date string with time
+     */
     static printShortDate(date: Date, separator?: string, dateTimeSeparator?: string): string;
+    /**
+     * Parses various date formats into a Date object.
+     * Supports Date objects, ISO strings, and timestamps (milliseconds).
+     * Automatically appends 'Z' to date strings without timezone information.
+     *
+     * @param date The date in various formats (Date, string, or number/timestamp)
+     * @returns A Date object, or an empty string if input is null/undefined
+     */
     static parseDate(date: any): "" | Date;
+    /**
+     * Calculates and formats the duration between two dates.
+     * Breaks down the duration into days, hours, minutes, and seconds.
+     * Example output: "2 days, 3 hours, 15 minutes and 30 seconds"
+     *
+     * @param start The start date
+     * @param end The end date
+     * @returns A human-readable duration string
+     */
     static printDuration(start: Date, end: Date): string;
+    /**
+     * Calculates the age in years between two dates.
+     * Properly accounts for whether the birthday has occurred in the current year.
+     *
+     * @param birthDate The birth date (can be string, number timestamp, or Date object)
+     * @param otherDate The reference date to calculate age from (can be string, number timestamp, or Date object)
+     * @returns The age in years as an integer
+     */
     static getAge(birthDate: string | number | Date, otherDate: string | number | Date): number;
+    /**
+     * Performs a deep clone of an array, recursively copying nested arrays and objects.
+     * Primitive types are returned unchanged, and handles circular references safely.
+     *
+     * @param items The array to clone
+     * @returns A deep copy of the array with all nested structures cloned
+     */
     static deepCloneArray<T>(items: T[]): T[];
+    /**
+     * Searches for a term within an array of values using case-sensitive or case-insensitive matching.
+     * Joins all values into a single string and searches for the term within it.
+     *
+     * @param searchTerm The term to search for
+     * @param caseSensitive Whether the search should be case-sensitive (defaults to false)
+     * @param values Variable number of values to search within
+     * @returns true if the search term is found, false otherwise
+     */
     static searchArray(searchTerm: string, caseSensitive: boolean, ...values: any[]): boolean;
+    /**
+     * Moves an item within an array from one index to another.
+     * Handles negative indices (counts from the end) and automatically extends the array if needed.
+     *
+     * @param array The array to modify
+     * @param oldIndex The current index of the item to move
+     * @param newIndex The target index to move the item to
+     */
     static moveArrayItem(array: any[], oldIndex: number, newIndex: number): void;
+    /**
+     * Expands camelCase text into space-separated words.
+     * Handles both camelCase and PascalCase patterns as well as non-alphanumeric characters.
+     * Example: "myPropertyName" becomes "my Property Name"
+     *
+     * @param text The camelCase text to expand
+     * @returns The expanded text with spaces between words
+     */
     static expandCamelCase(text: string): string;
+    /**
+     * Tests whether a URL is absolute (starts with protocol or //).
+     * Matches URLs like "http://example.com" or "//example.com"
+     *
+     * @param url The URL to test
+     * @returns true if the URL is absolute, false if it's relative
+     */
     static testIsAbsoluteUrl(url: string): boolean;
+    /**
+     * Converts a relative URL to an absolute URL by prepending //.
+     * If the URL is already absolute, it's returned unchanged.
+     *
+     * @param url The URL to convert
+     * @returns The absolute URL (e.g., "//example.com" for "example.com")
+     */
     static convertToAbsoluteUrl(url: string): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<Utilities, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<Utilities>;

package/lib/modules/cwm-shared.module.d.ts

@@ -1,15 +1,30 @@
 import * as i0 from "@angular/core";
-import * as i1 from "../components/external-navigation/external-navigation.component";
-import * as i2 from "../components/navigate-to-route/navigate-to-route.component";
-import * as i3 from "../components/page-not-found/page-not-found.component";
-import * as i4 from "../pipes/safe-html.pipe";
-import * as i5 from "@angular/common";
-import * as i6 from "@angular/router";
-import * as i7 from "@azure/msal-angular";
-import * as i8 from "@angular/platform-browser";
-import * as i9 from "@angular/forms";
+import * as i1 from "@angular/common";
+import * as i2 from "@angular/router";
+import * as i3 from "@azure/msal-angular";
+import * as i4 from "@angular/platform-browser";
+import * as i5 from "@angular/forms";
+import * as i6 from "../components/external-navigation/external-navigation.component";
+import * as i7 from "../components/navigate-to-route/navigate-to-route.component";
+import * as i8 from "../components/page-not-found/page-not-found.component";
+import * as i9 from "../pipes/safe-html.pipe";
+/**
+ * @deprecated Use standalone components directly instead
+ *
+ * This module is maintained for backwards compatibility only.
+ * New applications should import standalone components directly:
+ *
+ * @example
+ * import { PageNotFoundComponent, SafeHtmlPipe } from '@transcommerce/cwm-shared';
+ *
+ * @Component({
+ *   selector: 'app-root',
+ *   standalone: true,
+ *   imports: [PageNotFoundComponent, SafeHtmlPipe]
+ * })
+ */
 export declare class CwmSharedModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<CwmSharedModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<CwmSharedModule, [typeof i1.ExternalNavigationComponent, typeof i2.NavigateToRouteComponent, typeof i3.PageNotFoundComponent, typeof i4.SafeHtmlPipe], [typeof i5.CommonModule, typeof i6.RouterModule, typeof i7.MsalModule, typeof i8.BrowserModule, typeof i9.FormsModule], [typeof i5.CommonModule, typeof i6.RouterModule, typeof i7.MsalModule, typeof i1.ExternalNavigationComponent, typeof i2.NavigateToRouteComponent, typeof i3.PageNotFoundComponent, typeof i4.SafeHtmlPipe]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<CwmSharedModule, never, [typeof i1.CommonModule, typeof i2.RouterModule, typeof i3.MsalModule, typeof i4.BrowserModule, typeof i5.FormsModule, typeof i6.ExternalNavigationComponent, typeof i7.NavigateToRouteComponent, typeof i8.PageNotFoundComponent, typeof i9.SafeHtmlPipe], [typeof i1.CommonModule, typeof i2.RouterModule, typeof i3.MsalModule, typeof i6.ExternalNavigationComponent, typeof i7.NavigateToRouteComponent, typeof i8.PageNotFoundComponent, typeof i9.SafeHtmlPipe]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<CwmSharedModule>;
 }

package/lib/pipes/safe-html.pipe.d.ts

@@ -6,5 +6,5 @@ export declare class SafeHtmlPipe implements PipeTransform {
     constructor(sanitizer: DomSanitizer);
     transform(value: string): SafeHtml;
     static ɵfac: i0.ɵɵFactoryDeclaration<SafeHtmlPipe, never>;
-    static ɵpipe: i0.ɵɵPipeDeclaration<SafeHtmlPipe, "safeHtml", false>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<SafeHtmlPipe, "safeHtml", true>;
 }

package/lib/services/local-storage.service.d.ts

@@ -1,6 +1,8 @@
 import { Observable } from 'rxjs';
 import * as i0 from "@angular/core";
 export declare class LocalStorageService {
+    static readonly USER_DATA = "user_data";
+    static readonly SYNC_KEYS = "sync_keys";
     private static syncListenerInitialized;
     private syncKeys;
     private initEvent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transcommerce/cwm-shared",
-  "version": "1.1.88",
+  "version": "1.1.91",
   "engines": {
     "node": ">=18.0.0 <21.0.0"
   },

package/public-api.d.ts

@@ -1,15 +1,13 @@
-export * from './lib/components/external-navigation/external-navigation.component';
-export * from './lib/components/navigate-to-route/navigate-to-route.component';
-export * from './lib/components/page-not-found/page-not-found.component';
-export * from './lib/factories/msal.guard.config.factory';
-export * from './lib/factories/msal.instance.factory';
-export * from './lib/factories/msal-interceptor-config.factory';
+export { ExternalNavigationComponent } from './lib/components/external-navigation/external-navigation.component';
+export { NavigateToRouteComponent } from './lib/components/navigate-to-route/navigate-to-route.component';
+export { PageNotFoundComponent } from './lib/components/page-not-found/page-not-found.component';
+export { msalInstanceFactory } from './lib/factories/msal.instance.factory';
+export { msalGuardConfigFactory } from './lib/factories/msal.guard.config.factory';
+export { msalInterceptorConfigFactory } from './lib/factories/msal-interceptor-config.factory';
 export * from './lib/helpers/async-utils';
-export * from './lib/helpers/db-keys';
 export * from './lib/helpers/jwt';
 export * from './lib/helpers/stack';
 export * from './lib/helpers/time-span';
-export * from './lib/helpers/time-span-overflow-error';
 export * from './lib/helpers/utilities';
 export * from './lib/models/config/api-config';
 export * from './lib/models/config/auth-config';
@@ -23,6 +21,7 @@ export * from './lib/models/style/font-style';
 export * from './lib/models/style/hex-color';
 export * from './lib/models/style/image-style';
 export * from './lib/models/style/justifications';
+export * from './lib/models/style/named-colors';
 export * from './lib/models/style/ng-style-attribute';
 export * from './lib/models/style/on-style';
 export * from './lib/models/style/rgba-color-style';
@@ -43,10 +42,11 @@ export * from './lib/models/slide';
 export * from './lib/models/subscription';
 export * from './lib/models/user-types';
 export * from './lib/models/weight-tier-information';
+export * from './lib/cwm-shared-standalone';
 export * from './lib/modules/cwm-shared.module';
 export * from '@angular/common';
 export * from '@azure/msal-angular';
-export * from './lib/pipes/safe-html.pipe';
+export { SafeHtmlPipe } from './lib/pipes/safe-html.pipe';
 export * from './lib/services/mocks/mock-inventory-api-response';
 export * from './lib/services/mocks/mock-config';
 export * from './lib/services/mocks/mock-profile';

package/lib/helpers/db-keys.d.ts

@@ -1,18 +0,0 @@
-import * as i0 from "@angular/core";
-export declare class DbKeys {
-    static readonly CURRENT_USER = "current_user";
-    static readonly USER_PERMISSIONS = "user_permissions";
-    static readonly USER_DATA = "user_data";
-    static readonly SYNC_KEYS = "sync_keys";
-    static readonly AUTH_PROVIDER = "auth_provider";
-    static readonly REMEMBER_ME = "remember_me";
-    static readonly LANGUAGE = "language";
-    static readonly HOME_URL = "home_url";
-    static readonly THEME_ID = "themeId";
-    static readonly SHOW_DASHBOARD_STATISTICS = "show_dashboard_statistics";
-    static readonly SHOW_DASHBOARD_NOTIFICATIONS = "show_dashboard_notifications";
-    static readonly SHOW_DASHBOARD_TODO = "show_dashboard_todo";
-    static readonly SHOW_DASHBOARD_BANNER = "show_dashboard_banner";
-    static ɵfac: i0.ɵɵFactoryDeclaration<DbKeys, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<DbKeys>;
-}

package/lib/helpers/time-span-overflow-error.d.ts

@@ -1,2 +0,0 @@
-export declare class TimeSpanOverflowError extends Error {
-}