@envive-ai/react-hooks 0.1.0

package/src/application/models/guards/api/isApiResponse.ts

@@ -0,0 +1,39 @@
+import Logger from 'src/application/logging/logger';
+import { Response, ResponseCategory } from '@spiffy-ai/commerce-api-client';
+import { hasPropertyOfType } from 'src/application/models/guards/utils';
+
+export const isApiResponse = (data: unknown): data is Response => {
+  if (data == null || typeof data !== 'object') {
+    Logger.logError('isApiResponse: data is null or not an object', undefined, { data });
+    return false;
+  }
+
+  if (!hasPropertyOfType(data, 'id', 'string')) {
+    Logger.logError('isApiResponse: id is not a string', undefined, { data });
+    return false;
+  }
+
+  if (
+    !hasPropertyOfType(data, 'category', 'string') ||
+    !Object.values(ResponseCategory).includes(data.category as ResponseCategory)
+  ) {
+    Logger.logError(
+      'isApiResponse: category is not a string or not a valid response category',
+      undefined,
+      { data },
+    );
+    return false;
+  }
+
+  if (!hasPropertyOfType(data, 'created_at', 'string')) {
+    Logger.logError('isApiResponse: created_at is not a string', undefined, { data });
+    return false;
+  }
+
+  if (!hasPropertyOfType(data, 'attributes', 'object', true)) {
+    Logger.logError('isApiResponse: attributes is not an object', undefined, { data });
+    return false;
+  }
+
+  return true;
+};

package/src/application/models/guards/api/isApiReviewResponseAttributes.ts

@@ -0,0 +1,30 @@
+import { ApiReviewResponseAttributes } from 'src/application/models/api/responseGenerics';
+import { isApiReviewRichInformation } from './isApiReviewRichInformation';
+
+export const isApiReviewResponseAttributes = (obj: unknown): obj is ApiReviewResponseAttributes => {
+  if (obj == null || typeof obj !== 'object') {
+    return false;
+  }
+
+  if ('title' in obj && obj.title != null && typeof obj.title !== 'string') {
+    return false;
+  }
+
+  if ('review' in obj && typeof obj.review !== 'string') {
+    return false;
+  }
+
+  if ('reviewer' in obj && typeof obj.reviewer !== 'string') {
+    return false;
+  }
+
+  if ('stars' in obj && typeof obj.stars !== 'number') {
+    return false;
+  }
+
+  if ('rich_information' in obj && !isApiReviewRichInformation(obj.rich_information)) {
+    return false;
+  }
+
+  return true;
+};

package/src/application/models/guards/api/isApiReviewRichInformation.ts

@@ -0,0 +1,37 @@
+import { ApiReviewRichInformation } from 'src/application/models/api/responseGenerics';
+
+export const isApiReviewRichInformation = (
+  richInfo: unknown,
+): richInfo is ApiReviewRichInformation => {
+  if (richInfo == null || typeof richInfo !== 'object') {
+    return false;
+  }
+
+  if (
+    'cons' in richInfo &&
+    (!Array.isArray(richInfo.cons) || richInfo.cons.some((con) => typeof con !== 'string'))
+  ) {
+    return false;
+  }
+
+  if (
+    'pros' in richInfo &&
+    (!Array.isArray(richInfo.pros) || richInfo.pros.some((pro) => typeof pro !== 'string'))
+  ) {
+    return false;
+  }
+
+  if ('review_date' in richInfo && typeof richInfo.review_date !== 'string') {
+    return false;
+  }
+
+  if ('reviewer_title' in richInfo && typeof richInfo.reviewer_title !== 'string') {
+    return false;
+  }
+
+  if ('product_familiarity' in richInfo && typeof richInfo.product_familiarity !== 'string') {
+    return false;
+  }
+
+  return true;
+};

package/src/application/models/guards/api/isApiSearchEventAttributes.ts

@@ -0,0 +1,28 @@
+import { SearchAttributes } from '@spiffy-ai/commerce-api-client';
+
+export const isApiSearchAttributes = (data: unknown): data is SearchAttributes => {
+  if (data == null || typeof data !== 'object') {
+    return false;
+  }
+
+  if (!('search_term' in data) || typeof data.search_term !== 'string') {
+    return false;
+  }
+  if ('selected_filters' in data && !Array.isArray(data.selected_filters)) {
+    return false;
+  }
+
+  if (!!data.search_term) {
+    return true;
+  }
+
+  if (
+    !('search_results' in data) ||
+    !Array.isArray(data.search_results) ||
+    !data.search_results.every((v) => typeof v === 'string')
+  ) {
+    return false;
+  }
+
+  return true;
+};

package/src/application/models/guards/api/isApiSuggestion.ts

@@ -0,0 +1,36 @@
+import {
+  Suggestion as CommerceSuggestion,
+  SuggestionCategory,
+} from '@spiffy-ai/commerce-api-client';
+
+export const isSuggestion = (data: unknown): data is CommerceSuggestion => {
+  if (data == null || typeof data !== 'object') {
+    return false;
+  }
+
+  if (!('id' in data) || typeof data.id !== 'string') {
+    return false;
+  }
+
+  if (
+    !('category' in data) ||
+    typeof data.category !== 'string' ||
+    !Object.values(SuggestionCategory).includes(data.category as SuggestionCategory)
+  ) {
+    return false;
+  }
+
+  if (!('created_at' in data) || typeof data.created_at !== 'string') {
+    return false;
+  }
+
+  if (!('content' in data) || typeof data.content !== 'string') {
+    return false;
+  }
+
+  if ('is_answer' in data && data.is_answer != null && typeof data.is_answer !== 'boolean') {
+    return false;
+  }
+
+  return true;
+};

package/src/application/models/guards/api/isApiSuggestionClickedEventAttributes.ts

@@ -0,0 +1,9 @@
+import { SuggestionClickedAttributes } from '@spiffy-ai/commerce-api-client';
+
+export const isApiSuggestionClickedAttributes = (
+  data: unknown,
+): data is SuggestionClickedAttributes =>
+  data != null &&
+  typeof data === 'object' &&
+  'suggestion_id' in data &&
+  typeof data.suggestion_id === 'string';

package/src/application/models/guards/api/isApiTextResponseAttributes.ts

@@ -0,0 +1,9 @@
+import { ApiTextResponseAttributes } from 'src/application/models/api/responseGenerics';
+
+export const isApiTextResponseAttributes = (
+  attributes: unknown,
+): attributes is ApiTextResponseAttributes =>
+  typeof attributes === 'object' &&
+  attributes != null &&
+  'content' in attributes &&
+  typeof attributes.content === 'string';

package/src/application/models/guards/api/isApiUserEvent.ts

@@ -0,0 +1,25 @@
+import { UserEvent, UserEventCategory } from '@spiffy-ai/commerce-api-client';
+
+export const isApiUserEvent = (data: unknown): data is UserEvent => {
+  if (data == null || typeof data !== 'object') {
+    return false;
+  }
+
+  if (!('event_id' in data) || typeof data.event_id !== 'string') {
+    return false;
+  }
+
+  if (!('created_at' in data) || typeof data.created_at !== 'string') {
+    return false;
+  }
+
+  if (
+    !('category' in data) ||
+    typeof data.category !== 'string' ||
+    !Object.values(UserEventCategory).includes(data.category as UserEventCategory)
+  ) {
+    return false;
+  }
+
+  return true;
+};

package/src/application/models/guards/graphQL/isGraphQLColorsConfig.ts

@@ -0,0 +1,50 @@
+import Logger from 'src/application/logging/logger';
+import { GetMerchantColorsQueryData } from 'src/application/models/graphql';
+
+const REQUIRED_COLOR_FIELDS = [
+  'accent_primary',
+  'accent_secondary',
+  'background_dark',
+  'background_light',
+  'background_primary',
+  'background_saturated',
+  'background_secondary',
+  'background_secondary_dark',
+  'background_tertiary',
+  'border_dark',
+  'border_light',
+  'border_medium',
+  'border_outline',
+  'text_accent',
+  'text_light',
+  'text_link',
+  'text_primary',
+  'text_secondary',
+] as const;
+
+export const isGraphQLColorsConfig = (data: unknown): data is GetMerchantColorsQueryData => {
+  if (typeof data !== 'object' || data === null) {
+    Logger.logError('Invalid graphql response for colors config', undefined, { data });
+    return false;
+  }
+
+  // Check each required field
+  const missingFields = REQUIRED_COLOR_FIELDS.filter(
+    (field) => !(field in data) || typeof (data as Record<string, unknown>)[field] !== 'string',
+  );
+
+  if (missingFields.length === REQUIRED_COLOR_FIELDS.length) {
+    Logger.logError('All color fields are missing or null', undefined);
+    return false;
+  }
+
+  if (missingFields.length > 0) {
+    Logger.logError('Missing or invalid color fields', undefined, {
+      data,
+      missingFields,
+    });
+    return false;
+  }
+
+  return true;
+};

package/src/application/models/guards/isBaseEcommerceEvent.ts

@@ -0,0 +1,17 @@
+import type { BaseEcommerceEvent } from 'src/application/models';
+
+/**
+ * Checks if an event is a base Google Analytics ecommerce event.
+ *
+ * @param data The event to check.
+ *
+ * @returns True if the event is a base ecommerce event, false otherwise.
+ */
+export const isBaseEcommerceEvent = (data: unknown): data is BaseEcommerceEvent =>
+  data != null &&
+  typeof data === 'object' &&
+  'ecommerce' in data &&
+  data.ecommerce != null &&
+  typeof data.ecommerce === 'object' &&
+  'event' in data &&
+  typeof data.event === 'string';

package/src/application/models/guards/isGA4EcommerceEvent.ts

@@ -0,0 +1,17 @@
+import type { GA4EcommerceEvent } from 'src/application/models';
+
+/**
+ * Checks if an event is a Google Analytics 4 ecommerce event.
+ *
+ * @param data The event to check.
+ *
+ * @returns True if the event is a GA4 ecommerce event, false otherwise.
+ */
+export const isGA4EcommerceEvent = (data: unknown): data is GA4EcommerceEvent =>
+  typeof data === 'object' &&
+  data != null &&
+  'ecommerce' in data &&
+  data.ecommerce != null &&
+  typeof data.ecommerce === 'object' &&
+  'items' in data.ecommerce &&
+  Array.isArray(data.ecommerce.items);

package/src/application/models/guards/isLegacyUAEcommerceEvent.ts

@@ -0,0 +1,17 @@
+import type { UAEcommerceEvent } from 'src/application/models';
+
+/**
+ * Checks if an event is a legacy Universal Analytics ecommerce event.
+ *
+ * @param data The event to check.
+ *
+ * @returns True if the event is a legacy UA ecommerce event, false otherwise.
+ */
+export const isLegacyUAEcommerceEvent = (data: unknown): data is UAEcommerceEvent =>
+  data != null &&
+  typeof data === 'object' &&
+  'ecommerce' in data &&
+  data.ecommerce != null &&
+  typeof data.ecommerce === 'object' &&
+  'add' in data.ecommerce &&
+  typeof data.ecommerce.add === 'object';

package/src/application/models/guards/isMobilePLPChatPlacementParameter.ts

@@ -0,0 +1,11 @@
+interface MobilePlpChatPlacementParameter {
+  row_index: number;
+}
+
+export const isMobilePLPChatPlacementParameter = (
+  value: unknown,
+): value is MobilePlpChatPlacementParameter =>
+  value != null &&
+  typeof value === 'object' &&
+  'row_index' in value &&
+  typeof value.row_index === 'number';

package/src/application/models/guards/isSpanxTakeAQuizCtaParameter.ts

@@ -0,0 +1,4 @@
+import { SpanxTakeAQuizCtaParameter } from '../spanxTakeAQuizCtaParameter';
+
+export const isSpanxTakeAQuizCtaParameter = (value: unknown): value is SpanxTakeAQuizCtaParameter =>
+  value != null && typeof value === 'object' && 'text' in value && typeof value.text === 'string';

package/src/application/models/guards/isVariantInfo.ts

@@ -0,0 +1,37 @@
+import { PageVisitCategory } from '@spiffy-ai/commerce-api-client';
+import { PDPVariantInfo, PLPVariantInfo, PageVisitVariantInfo, VariantInfo } from '../variantInfo';
+
+const isPDPVariantInfo = (variantInfo: object): variantInfo is PDPVariantInfo =>
+  'variant' in variantInfo &&
+  variantInfo.variant === 'pdp' &&
+  'productId' in variantInfo &&
+  typeof variantInfo.productId === 'string';
+
+const isPLPVariantInfo = (variantInfo: object): variantInfo is PLPVariantInfo =>
+  'variant' in variantInfo &&
+  variantInfo.variant === 'plp' &&
+  'plpId' in variantInfo &&
+  typeof variantInfo.plpId === 'string';
+
+const isPageVisitVariantInfo = (variantInfo: object): variantInfo is PageVisitVariantInfo =>
+  'variant' in variantInfo &&
+  variantInfo.variant === 'page_visit' &&
+  'url' in variantInfo &&
+  typeof variantInfo.url === 'string' &&
+  'pageVisitCategory' in variantInfo &&
+  Object.values(PageVisitCategory).includes(variantInfo.pageVisitCategory as PageVisitCategory);
+
+/**
+ * Type guard to check if an object is a valid VariantInfo.
+ *
+ * @param variantInfo - The unknown object to check.
+ *
+ * @returns True if the data is a valid VariantInfo object, false otherwise.
+ */
+export const isVariantInfo = (variantInfo: unknown): variantInfo is VariantInfo =>
+  variantInfo != null &&
+  typeof variantInfo === 'object' &&
+  'variantId' in variantInfo &&
+  (isPDPVariantInfo(variantInfo) ||
+    isPLPVariantInfo(variantInfo) ||
+    isPageVisitVariantInfo(variantInfo));

package/src/application/models/guards/utils.ts

@@ -0,0 +1,43 @@
+/**
+ * Checks if an object has a property of a specific type
+ *
+ * @param obj - The object to check
+ * @param prop - The property name to check
+ * @param type - The expected type of the property
+ * @param isOptional - Whether the property is optional (defaults to false)
+ *
+ * @returns boolean indicating if the object has the property of the specified type
+ */
+export const hasPropertyOfType = <T extends object>(
+  obj: unknown,
+  prop: keyof T,
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array',
+  isOptional: boolean = false,
+): obj is T => {
+  try {
+    if (obj == null || typeof obj !== 'object') {
+      return false;
+    }
+
+    // If property is not present, it's valid for an optional property
+    if (!(prop in obj)) {
+      return isOptional;
+    }
+
+    const value = (obj as T)[prop];
+
+    // For optional properties, null or undefined values are valid
+    if (isOptional && value == null) {
+      return true;
+    }
+
+    if (type === 'array') {
+      return Array.isArray(value);
+    }
+
+    return typeof value === type;
+  } catch (err) {
+    // swallow the error as it should be reported in more detail by the caller
+    return false;
+  }
+};

package/src/application/models/index.ts

@@ -0,0 +1,20 @@
+// models
+export * from './api/userEvent';
+export * from './api/response';
+export * from './api/nextMessageRequest';
+export * from './api/context';
+export * from './api/suggestion';
+export * from './api/generationParams';
+export * from './api/supportedEventRequest';
+export * from './message';
+export * from './supportedOrgs';
+export * from './mobilePLPChatPlacementParameter';
+export * from './spanxTakeAQuizCtaParameter';
+export * from './variantInfo';
+export * from './dataLayer';
+export * from './featureGates';
+
+// type guards
+export * from './guards/isLegacyUAEcommerceEvent';
+export * from './guards/isGA4EcommerceEvent';
+export * from './guards/isBaseEcommerceEvent';

package/src/application/models/localStorageEventListener.ts

@@ -0,0 +1,4 @@
+type LocalStorageEventListener = {
+  storageKey: string;
+  listener: (event: StorageEvent) => void;
+}

package/src/application/models/message.ts

@@ -0,0 +1,146 @@
+import { CustServiceAttachment, FormType } from '@spiffy-ai/commerce-api-client';
+import {
+  OrderResponseAttributes,
+  ProductResponseAttributes,
+  ReviewResponseAttributes,
+  PageResponseAttributes,
+  TextResponseAttributes,
+  SearchResponseAttributes,
+  SearchProductResponseAttributes,
+  AcceptableFormFieldType,
+  SearchProductFilterAttributes,
+} from './api/response';
+
+export enum MessageRole {
+  User = 'user',
+  Assistant = 'assistant',
+}
+
+export enum MessageType {
+  Text = 'text',
+  SuggestionClicked = 'suggestion_clicked',
+  Product = 'product',
+  ProductSearch = 'product_search',
+  Review = 'review',
+  QueryTyped = 'query_typed',
+  Separator = 'separator',
+  Page = 'page',
+  Search = 'search',
+  Attachment = 'attachment',
+  CXAgentResponse = 'cx_agent_response',
+  Form = 'form',
+  Order = 'order',
+  ProductSearchFilter = 'product_search_filter',
+}
+
+export type Message = {
+  id: string;
+  role: MessageRole;
+  createdAt: string;
+} & (
+  | TextMessageMetadata
+  | QueryTypedMetadata
+  | SuggestionMessageMetadata
+  | ProductMessageMetadata
+  | ProductSearchMessageMetadata
+  | ReviewMessageMetadata
+  | SeparatorMessageMetadata
+  | PageMessageMetadata
+  | SearchMessageMetadata
+  | AttachmentMetadata
+  | CXAgentResponseMetadata
+  | FormMessageMetadata
+  | OrderMessageMetadata
+  | ProductSearchFilterMetadata
+);
+
+type AttachmentMetadata = {
+  type: MessageType.Attachment;
+  metadata: {
+    message?: string;
+    attachment: CustServiceAttachment[];
+  };
+};
+
+type CXAgentResponseMetadata = {
+  type: MessageType.CXAgentResponse;
+  metadata: {
+    message: string;
+    agentName: string;
+  };
+};
+
+type TextMessageMetadata = {
+  type: MessageType.Text;
+  metadata: TextResponseAttributes['attributes'];
+};
+
+type QueryTypedMetadata = {
+  type: MessageType.QueryTyped;
+  metadata: TextResponseAttributes['attributes'];
+};
+
+type SuggestionMessageMetadata = {
+  type: MessageType.SuggestionClicked;
+  metadata: {
+    suggestionId: string;
+    suggestionContent: string;
+  };
+};
+
+export type ProductMessageMetadata = {
+  type: MessageType.Product;
+  metadata: ProductResponseAttributes['attributes'];
+};
+
+export type ProductSearchMessageMetadata = {
+  type: MessageType.ProductSearch;
+  metadata: SearchProductResponseAttributes['attributes'];
+};
+
+type ReviewMessageMetadata = {
+  type: MessageType.Review;
+  metadata: ReviewResponseAttributes['attributes'];
+};
+
+type SeparatorMessageMetadata = {
+  type: MessageType.Separator;
+};
+
+type PageMessageMetadata = {
+  type: MessageType.Page;
+  metadata: PageResponseAttributes['attributes'];
+};
+
+type SearchMessageMetadata = {
+  type: MessageType.Search;
+  metadata: SearchResponseAttributes['attributes'];
+};
+
+type ProductSearchFilterMetadata = {
+  type: MessageType.ProductSearchFilter;
+  metadata: SearchProductFilterAttributes['attributes'];
+};
+
+export type FormField = {
+  key: string;
+  title: string;
+  type: AcceptableFormFieldType;
+  required: boolean;
+  // this is the only format we currently support
+  format?: 'email';
+  value?: string;
+};
+
+type FormMessageMetadata = {
+  type: MessageType.Form;
+  metadata: {
+    formType?: FormType;
+    fields: FormField[];
+  };
+};
+
+type OrderMessageMetadata = {
+  type: MessageType.Order;
+  metadata: OrderResponseAttributes['attributes'];
+};

package/src/application/models/mobilePLPChatPlacementParameter.ts

@@ -0,0 +1,3 @@
+export interface MobilePLPChatPlacementParameter {
+  rowIndex: number;
+}

package/src/application/models/orgsEnum.ts

@@ -0,0 +1,36 @@
+export const OrgShortName = {
+  Coterie: 'coterie',
+  ForLoveAndLemons: 'for-love-and-lemons',
+  Greenpan: 'greenpan',
+  JordanCraig: 'jordan-craig',
+  LarryAndSerges: 'larry_and_serges',
+  LeapsAndRebounds: 'leaps-and-rebounds',
+  MantraBrand: 'mantra-brand',
+  Spanx: 'spanx',
+  SpanxStaging: 'staging-spanx',
+  Supergoop: 'supergoop',
+  UniqueVintage: 'unique-vintage',
+  JackArcher: 'jack-archer',
+  /* -- Below items are generated by plop -- */
+  SkinPerfection: 'skin-perfection',
+  LookOptic: 'look-optic',
+  FiveCbd: 'five-cbd',
+  SnapSupplements: 'snap-supplements',
+  Longevityrx: 'longevityrx',
+  VenaCbd: 'vena-cbd',
+  Medterra: 'medterra',
+  Modells: 'modells',
+  PressedFloral: 'pressed-floral',
+  KindredBravely: 'kindred-bravely',
+  WineEnthusiast: 'wine-enthusiast',
+  HomegrownCannabis: 'homegrown-cannabis',
+  DreamlandBaby: 'dreamland-baby',
+  Bandolier: 'bandolier',
+  WestonJonBoucher: 'weston-jon-boucher',
+  KutFromTheKloth: 'kut-from-the-kloth',
+  GrooveLife: 'groove-life',
+  Carpe: 'carpe',
+  WolfTactical: 'wolf-tactical',
+  WolfMattress: 'wolfmattress',
+  Default: 'default',
+} as const;

package/src/application/models/productExperiment.ts

@@ -0,0 +1,5 @@
+export enum ProductExperiment {
+  // Default is only used to ensure that the enum is non-empty, otherwise
+  // callers that try to use this enum will generate a typescript error
+  Default = 'default',
+}

package/src/application/models/spanxTakeAQuizCtaParameter.ts

@@ -0,0 +1,4 @@
+export interface SpanxTakeAQuizCtaParameter {
+  text?: string;
+  value?: string;
+}

package/src/application/models/spiffyWidgets.ts

@@ -0,0 +1,16 @@
+/**
+ * Enum of all widget names. These are widgets that are rendered and integrated into
+ * a merchant's website.
+ */
+export enum SpiffyWidgets {
+  ImageBanner = 'image_banner',
+  ImagePromptCard = 'image_prompt_card',
+  SingleImagePrompt = 'single_image_prompt',
+  EmbeddedWidget = 'embedded_widget',
+  FloatingButton = 'floating_button',
+  SuggestionBar = 'suggestion_bar',
+  SearchPrompt = 'search_prompt',
+  GlobalSearch = 'global_search',
+  SearchResults = 'search_results',
+  GlobalSearchEntryPoint = 'global_search_entry_point',
+}