guideai-app 0.2.5 → 0.2.6

package/dist/components/TextInput.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+interface TextInputProps {
+    onSubmit: (message: string) => void;
+    onClose: () => void;
+    isVisible: boolean;
+}
+declare const TextInput: React.FC<TextInputProps>;
+export default TextInput;

package/dist/components/TranscriptBox.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { StoredMessage } from '../utils/messageStorage';
+interface TranscriptBoxProps {
+    messages: StoredMessage[];
+    isVisible: boolean;
+    onClose: () => void;
+    showToggleButton?: boolean;
+    onToggle?: () => void;
+    showTextInput?: boolean;
+    textInput?: string;
+    onTextInputChange?: (value: string) => void;
+    onTextSubmit?: () => void;
+    onTextKeyPress?: (event: React.KeyboardEvent) => void;
+    textPlaceholder?: string;
+}
+declare const TranscriptBox: React.FC<TranscriptBoxProps>;
+export default TranscriptBox;

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 import GuideAI from './GuideAI';
+import TranscriptBox from './components/TranscriptBox';
 export default GuideAI;
+export { TranscriptBox };
 export type { GuideAIProps } from './types/GuideAI.types';

package/dist/metric/event-listner.d.ts

@@ -0,0 +1,113 @@
+interface EventData {
+    type: 'click' | 'focus' | 'change' | 'submit' | 'route_change';
+    element?: Element;
+    tagName?: string;
+    className?: string;
+    id?: string;
+    textContent?: string;
+    value?: string;
+    formData?: FormData;
+    timestamp: number;
+    url: string;
+    previousUrl?: string;
+    event?: Event;
+    customerId?: string;
+    customerType?: string;
+    customerSegment?: string;
+    sessionId?: string;
+    deviceType?: 'desktop' | 'mobile' | 'tablet';
+    userAgent?: string;
+    screenResolution?: string;
+    currentPage?: string;
+    userRole?: string;
+    organizationId?: string;
+    timezone?: string;
+    locale?: string;
+}
+declare class EventTracker {
+    private isTracking;
+    private eventData;
+    private batchSize;
+    private batchTimeout;
+    private batchTimer;
+    private pendingEvents;
+    private currentUrl;
+    private organizationKey?;
+    private customerMetadata;
+    constructor(options?: {
+        customerId?: string;
+        customerType?: string;
+        organizationId?: string;
+        organizationKey?: string;
+    });
+    setCustomerMetadata(metadata: Partial<typeof this.customerMetadata>): void;
+    getCustomerMetadata(): typeof this.customerMetadata;
+    clearCustomerMetadata(): void;
+    initialize(): void;
+    private enrichEventData;
+    private getSessionId;
+    private getDeviceType;
+    startTracking(): void;
+    stopTracking(): void;
+    private trackClickEvents;
+    private trackFocusEvents;
+    private trackChangeEvents;
+    private trackSubmitEvents;
+    private trackRouteChanges;
+    private handleClick;
+    private handleFocus;
+    private handleChange;
+    private handleSubmit;
+    private handlePopstate;
+    private handleHashChange;
+    private interceptHistoryAPI;
+    private getPreviousUrl;
+    private getSafeValue;
+    private isFocusable;
+    private isFormElement;
+    private logEvent;
+    private startBatchTimer;
+    private emitBatch;
+    getEventData(): EventData[];
+    clearEventData(): void;
+    getEventDataByType(type: EventData['type']): EventData[];
+    getEventDataByElement(tagName: string): EventData[];
+    getEventDataByUrl(url: string): EventData[];
+    emitPendingEvents(): void;
+    setBatchConfig(batchSize: number, batchTimeout: number): void;
+    getPendingEventsCount(): number;
+    getCustomerAnalytics(): {
+        totalEvents: number;
+        eventsByCustomer: Record<string, number>;
+        eventsByType: Record<string, number>;
+        eventsByPage: Record<string, number>;
+        eventsByDevice: Record<string, number>;
+        sessionDuration: number;
+        lastActivity: number;
+    };
+    private getSessionStartTime;
+    identifyCustomerFromContext(): void;
+    setCustomerFromAuth(authData: {
+        id?: string;
+        role?: string;
+        customerType?: 'individual' | 'business' | 'agent' | 'admin';
+        customerSegment?: string;
+    }): void;
+}
+export default EventTracker;
+export type { EventData };
+export interface CustomerMetadata {
+    customerId?: string;
+    customerType?: 'individual' | 'business' | 'agent' | 'admin';
+    customerSegment?: string;
+    userRole?: string;
+}
+export interface CustomerAnalytics {
+    totalEvents: number;
+    eventsByCustomer: Record<string, number>;
+    eventsByType: Record<string, number>;
+    eventsByPage: Record<string, number>;
+    eventsByDevice: Record<string, number>;
+    sessionDuration: number;
+    lastActivity: number;
+}

package/dist/metric/index.d.ts

@@ -0,0 +1,4 @@
+export { default as EventTracker } from './event-listner';
+export type { EventData } from './event-listner';
+export { default as UserMetadataTracker } from './metadata-tracker';
+export type { UserMetadata, MetadataConfig, MetadataUpdate } from './metadata-tracker';

package/dist/metric/metadata-tracker.d.ts

@@ -0,0 +1,33 @@
+import { UserMetadata, MetadataConfig, MetadataUpdate } from '../types/metadata.types';
+declare class UserMetadataTracker {
+    private config;
+    private metadata;
+    private syncTimer;
+    private pendingUpdates;
+    private isInitialized;
+    private onError?;
+    constructor(organizationKey: string, config?: MetadataConfig, onError?: (error: Error, context: string) => void);
+    private init;
+    updateUserInfo(userInfo: Partial<UserMetadata>): void;
+    trackLogin(additionalInfo?: Partial<UserMetadata>): void;
+    trackVisit(): void;
+    trackCustomEvent(eventType: string, customData: Record<string, any>): void;
+    getMetadata(): UserMetadata;
+    getPendingUpdates(): MetadataUpdate[];
+    clearPendingUpdates(): void;
+    syncNow(): MetadataUpdate[];
+    private loadMetadata;
+    private saveMetadata;
+    private collectBrowserInfo;
+    private parseBrowserInfo;
+    private startSyncTimer;
+    private setupEventTrackerIntegration;
+    private stopSyncTimer;
+    private emitPendingUpdates;
+    private getFromStorage;
+    private setToStorage;
+    private clearStorage;
+    destroy(): void;
+}
+export default UserMetadataTracker;
+export type { UserMetadata, MetadataConfig, MetadataUpdate };

package/dist/styles/GuideAI.styles.d.ts

@@ -1 +1 @@
-export declare const guideAIStyles = "\n.sarge-main-ui {\n  position: relative;\n}\n\n.sarge-welcome-bubble {\n  position: absolute;\n  left: 50%;\n  transform: translateX(-50%);\n  background: #0066ff;\n  color: white;\n  padding: 10px 16px;\n  border-radius: 20px;\n  font-size: 14px;\n  white-space: normal;\n  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);\n  animation: bubble-pulse 2s infinite;\n  max-width: 280px;\n  min-width: 200px;\n  text-align: center;\n  line-height: 1.3;\n}\n\n.sarge-welcome-bubble.above {\n  bottom: calc(100% + 10px);\n}\n\n.sarge-welcome-bubble.below {\n  top: calc(100% + 10px);\n}\n\n.sarge-welcome-bubble.above::after {\n  content: '';\n  position: absolute;\n  top: 100%;\n  left: 50%;\n  transform: translateX(-50%);\n  border-left: 8px solid transparent;\n  border-right: 8px solid transparent;\n  border-top: 8px solid #0066ff;\n}\n\n.sarge-welcome-bubble.below::after {\n  content: '';\n  position: absolute;\n  bottom: 100%;\n  left: 50%;\n  transform: translateX(-50%);\n  border-left: 8px solid transparent;\n  border-right: 8px solid transparent;\n  border-bottom: 8px solid #0066ff;\n}\n\n@keyframes bubble-pulse {\n  0% { transform: translateX(-50%) scale(1); }\n  50% { transform: translateX(-50%) scale(1.05); }\n  100% { transform: translateX(-50%) scale(1); }\n}\n\n.sarge-icon-wrapper {\n  width: 100%;\n  height: 100%;\n  min-width: 30px;\n  min-height: 30px;\n  max-width: 60px;\n  max-height: 60px;\n  display: flex;\n  justify-content: center;\n  align-items: center;\n  background-color: rgba(255, 255, 255, 0.9);\n  border-radius: 50%;\n  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);\n  cursor: pointer;\n  transition: all 0.2s ease;\n}\n\n.sarge-icon-wrapper:not(.initializing):hover {\n  transform: scale(1.1);\n}\n\n.sarge-icon-wrapper.initializing {\n  background-color: rgba(255, 255, 255, 0.9);\n  box-shadow: 0 0 0 2px rgba(128, 128, 128, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);\n  animation: sarge-spin 1.5s linear infinite;\n  opacity: 0.7;\n  cursor: default;\n}\n\n.sarge-icon-wrapper.recording {\n  background-color: rgba(255, 255, 255, 0.9);\n  box-shadow: 0 0 0 2px rgba(255, 0, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);\n  animation: sarge-pulse 1s infinite alternate;\n}\n\n.sarge-icon-wrapper.processing {\n  background-color: rgba(255, 255, 255, 0.9);\n  box-shadow: 0 0 0 2px rgba(255, 165, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);\n  animation: sarge-spin 1s linear infinite;\n}\n\n.sarge-icon-wrapper.playing {\n  background-color: rgba(255, 255, 255, 0.9);\n  box-shadow: 0 0 0 2px rgba(0, 128, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);\n}\n\n@keyframes sarge-pulse {\n  0% { transform: scale(1); }\n  100% { transform: scale(1.05); }\n}\n\n@keyframes sarge-spin {\n  0% {\n    transform: rotate(0deg);\n  }\n  100% {\n    transform: rotate(360deg);\n  }\n}\n\n@keyframes click-ripple-animation {\n  0% { transform: translate(-50%, -50%) scale(0); opacity: 1; }\n  50% { transform: translate(-50%, -50%) scale(1.2); opacity: 0.6; }\n  100% { transform: translate(-50%, -50%) scale(2.5); opacity: 0; }\n}\n\n@keyframes click-dot-animation {\n  0% { transform: translate(-50%, -50%) scale(0); opacity: 1; }\n  60% { transform: translate(-50%, -50%) scale(1); opacity: 1; }\n  100% { transform: translate(-50%, -50%) scale(1); opacity: 0; }\n}\n\n@keyframes cursor-jiggle {\n  0% { transform: translate(-50%, 0) scale(1); }\n  25% { transform: translate(-50%, -5px) scale(1.1); }\n  50% { transform: translate(-50%, 0) scale(1); }\n  75% { transform: translate(-50%, 5px) scale(1.1); }\n  100% { transform: translate(-50%, 0) scale(1); filter: drop-shadow(0 0 8px #0066ff); }\n}\n\n.sarge-icon {\n  width: 60%;\n  height: 60%;\n  min-width: 16px;\n  min-height: 16px;\n  max-width: 40px;\n  max-height: 40px;\n  background-size: contain;\n  background-repeat: no-repeat;\n  background-position: center;\n}\n\n.sarge-icon.initializing {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\"><path fill=\"%23808080\" d=\"M304 48c0 26.51-21.49 48-48 48s-48-21.49-48-48 21.49-48 48-48 48 21.49 48 48zm-48 368c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.49-48-48-48zm208-208c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.49-48-48-48zM96 256c0-26.51-21.49-48-48-48S0 229.49 0 256s21.49 48 48 48 48-21.49 48-48zm12.922 99.078c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48c0-26.509-21.491-48-48-48zm294.156 0c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48c0-26.509-21.49-48-48-48zM108.922 60.922c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.491-48-48-48z\"/></svg>');\n}\n\n.sarge-icon.microphone {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 352 512\"><path fill=\"%230000FF\" d=\"M176 352c53.02 0 96-42.98 96-96V96c0-53.02-42.98-96-96-96S80 42.98 80 96v160c0 53.02 42.98 96 96 96zm160-160h-16c-8.84 0-16 7.16-16 16v48c0 74.8-64.49 134.82-140.79 127.38C96.71 376.89 48 317.11 48 250.3V208c0-8.84-7.16-16-16-16H16c-8.84 0-16 7.16-16 16v40.16c0 89.64 63.97 169.55 152 181.69V464H96c-8.84 0-16 7.16-16 16v16c0 8.84 7.16 16 16 16h160c8.84 0 16-7.16 16-16v-16c0-8.84-7.16-16-16-16h-56v-33.77C285.71 418.47 352 344.9 352 256v-48c0-8.84-7.16-16-16-16z\"/></svg>');\n}\n\n.sarge-icon.recording {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\"><circle cx=\"256\" cy=\"256\" r=\"128\" fill=\"%23FF0000\"/><circle cx=\"256\" cy=\"256\" r=\"200\" stroke=\"%23FF0000\" stroke-width=\"20\" fill=\"none\"/></svg>');\n}\n\n.sarge-icon.processing {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\"><path fill=\"%23FFA500\" d=\"M304 48c0 26.51-21.49 48-48 48s-48-21.49-48-48 21.49-48 48-48 48 21.49 48 48zm-48 368c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.49-48-48-48zm208-208c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.49-48-48-48zM96 256c0-26.51-21.49-48-48-48S0 229.49 0 256s21.49 48 48 48 48-21.49 48-48zm12.922 99.078c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48c0-26.509-21.491-48-48-48zm294.156 0c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48c0-26.509-21.49-48-48-48zM108.922 60.922c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.491-48-48-48z\"/></svg>');\n}\n\n.sarge-icon.playing {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"%23008000\" d=\"M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02zM14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.85-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77z\"/></svg>');\n}\n\n/* Onboarding styles */\n.sarge-onboarding {\n  position: absolute;\n  left: 50%;\n  transform: translateX(-50%);\n  background: white;\n  border-radius: 12px;\n  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);\n  width: 300px;\n  max-width: 90vw;\n  z-index: 1002;\n  animation: onboarding-fade-in 0.3s ease-out;\n}\n\n.sarge-onboarding.above {\n  bottom: calc(100% + 15px);\n}\n\n.sarge-onboarding.below {\n  top: calc(100% + 15px);\n}\n\n.sarge-onboarding.above::after {\n  content: '';\n  position: absolute;\n  top: 100%;\n  left: 50%;\n  transform: translateX(-50%);\n  border-left: 8px solid transparent;\n  border-right: 8px solid transparent;\n  border-top: 8px solid white;\n  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));\n}\n\n.sarge-onboarding.below::after {\n  content: '';\n  position: absolute;\n  bottom: 100%;\n  left: 50%;\n  transform: translateX(-50%);\n  border-left: 8px solid transparent;\n  border-right: 8px solid transparent;\n  border-bottom: 8px solid white;\n  filter: drop-shadow(0 -2px 4px rgba(0, 0, 0, 0.1));\n}\n\n@keyframes onboarding-fade-in {\n  from { opacity: 0; transform: translateX(-50%) translateY(-10px); }\n  to { opacity: 1; transform: translateX(-50%) translateY(0); }\n}\n\n.sarge-onboarding-content {\n  padding: 16px;\n  position: relative;\n}\n\n.sarge-onboarding-close {\n  position: absolute;\n  top: 10px;\n  right: 10px;\n  background: none;\n  border: none;\n  font-size: 20px;\n  cursor: pointer;\n  color: #999;\n  width: 24px;\n  height: 24px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  border-radius: 50%;\n}\n\n.sarge-onboarding-close:hover {\n  background: #f5f5f5;\n  color: #333;\n}\n\n.sarge-onboarding-step {\n  text-align: center;\n  margin-bottom: 12px;\n}\n\n.sarge-onboarding-icon {\n  font-size: 32px;\n  margin-bottom: 8px;\n  display: inline-block;\n}\n\n.sarge-onboarding-step h3 {\n  margin: 0 0 8px;\n  font-size: 16px;\n  color: #333;\n  font-weight: 600;\n}\n\n.sarge-onboarding-step p {\n  margin: 0;\n  font-size: 13px;\n  color: #666;\n  line-height: 1.4;\n}\n\n.sarge-onboarding-dots {\n  display: flex;\n  justify-content: center;\n  margin: 12px 0;\n}\n\n.sarge-onboarding-dots .dot {\n  width: 8px;\n  height: 8px;\n  border-radius: 50%;\n  background: #ddd;\n  margin: 0 4px;\n  transition: all 0.3s ease;\n}\n\n.sarge-onboarding-dots .dot.active {\n  background: #0066ff;\n  transform: scale(1.2);\n}\n\n.sarge-onboarding-next {\n  display: block;\n  width: 100%;\n  padding: 10px;\n  background: #0066ff;\n  color: white;\n  border: none;\n  border-radius: 6px;\n  font-size: 14px;\n  font-weight: 500;\n  cursor: pointer;\n  transition: background 0.2s ease;\n}\n\n.sarge-onboarding-next:hover {\n  background: #0055cc;\n}\n";
+export declare const guideAIStyles = "\n.guideai-main-ui {\n  position: relative;\n}\n\n.guideai-welcome-bubble {\n  position: absolute;\n  left: 50%;\n  transform: translateX(-50%);\n  background: #0066ff;\n  color: white;\n  padding: 10px 16px;\n  border-radius: 20px;\n  font-size: 14px;\n  white-space: normal;\n  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);\n  animation: bubble-pulse 2s infinite;\n  max-width: 280px;\n  min-width: 200px;\n  text-align: center;\n  line-height: 1.3;\n}\n\n.guideai-welcome-bubble.above {\n  bottom: calc(100% + 10px);\n}\n\n.guideai-welcome-bubble.below {\n  top: calc(100% + 10px);\n}\n\n.guideai-welcome-bubble.above::after {\n  content: '';\n  position: absolute;\n  top: 100%;\n  left: 50%;\n  transform: translateX(-50%);\n  border-left: 8px solid transparent;\n  border-right: 8px solid transparent;\n  border-top: 8px solid #0066ff;\n}\n\n.guideai-welcome-bubble.below::after {\n  content: '';\n  position: absolute;\n  bottom: 100%;\n  left: 50%;\n  transform: translateX(-50%);\n  border-left: 8px solid transparent;\n  border-right: 8px solid transparent;\n  border-bottom: 8px solid #0066ff;\n}\n\n@keyframes bubble-pulse {\n  0% { transform: translateX(-50%) scale(1); }\n  50% { transform: translateX(-50%) scale(1.05); }\n  100% { transform: translateX(-50%) scale(1); }\n}\n\n.guideai-icon-wrapper {\n  width: 50px;\n  height: 50px;\n  display: flex;\n  justify-content: center;\n  align-items: center;\n  background-color: rgba(255, 255, 255, 0.9);\n  border: 2px solid transparent;\n  border-radius: 50%;\n  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);\n  cursor: pointer;\n  transition: all 0.2s ease;\n}\n\n.guideai-icon-wrapper:not(.initializing):hover {\n  transform: scale(1.1);\n}\n\n.guideai-icon-wrapper.initializing {\n  background-color: rgba(255, 255, 255, 0.9);\n  box-shadow: 0 0 0 2px rgba(128, 128, 128, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);\n  animation: guideai-spin 1.5s linear infinite;\n  opacity: 0.7;\n  cursor: default;\n}\n\n.guideai-icon-wrapper.recording {\n  background-color: rgba(255, 255, 255, 0.9);\n  box-shadow: 0 0 0 2px rgba(255, 0, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);\n  animation: guideai-pulse 1s infinite alternate;\n}\n\n.guideai-icon-wrapper.processing {\n  background-color: rgba(255, 255, 255, 0.9);\n  box-shadow: 0 0 0 2px rgba(255, 165, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);\n  animation: guideai-spin 1s linear infinite;\n}\n\n.guideai-icon-wrapper.playing {\n  background-color: rgba(255, 255, 255, 0.9);\n  box-shadow: 0 0 0 2px rgba(0, 128, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);\n}\n\n@keyframes guideai-pulse {\n  0% { transform: scale(1); }\n  100% { transform: scale(1.05); }\n}\n\n@keyframes guideai-spin {\n  0% {\n    transform: rotate(0deg);\n  }\n  100% {\n    transform: rotate(360deg);\n  }\n}\n\n@keyframes click-ripple-animation {\n  0% { transform: translate(-50%, -50%) scale(0); opacity: 1; }\n  50% { transform: translate(-50%, -50%) scale(1.2); opacity: 0.6; }\n  100% { transform: translate(-50%, -50%) scale(2.5); opacity: 0; }\n}\n\n@keyframes click-dot-animation {\n  0% { transform: translate(-50%, -50%) scale(0); opacity: 1; }\n  60% { transform: translate(-50%, -50%) scale(1); opacity: 1; }\n  100% { transform: translate(-50%, -50%) scale(1); opacity: 0; }\n}\n\n@keyframes cursor-jiggle {\n  0% { transform: translate(-50%, 0) scale(1); }\n  25% { transform: translate(-50%, -5px) scale(1.1); }\n  50% { transform: translate(-50%, 0) scale(1); }\n  75% { transform: translate(-50%, 5px) scale(1.1); }\n  100% { transform: translate(-50%, 0) scale(1); filter: drop-shadow(0 0 8px #0066ff); }\n}\n\n.guideai-icon {\n  width: 60%;\n  height: 60%;\n  min-width: 16px;\n  min-height: 16px;\n  max-width: 40px;\n  max-height: 40px;\n  background-size: contain;\n  background-repeat: no-repeat;\n  background-position: center;\n}\n\n.guideai-icon.initializing {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\"><path fill=\"%23808080\" d=\"M304 48c0 26.51-21.49 48-48 48s-48-21.49-48-48 21.49-48 48-48 48 21.49 48 48zm-48 368c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.49-48-48-48zm208-208c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.49-48-48-48zM96 256c0-26.51-21.49-48-48-48S0 229.49 0 256s21.49 48 48 48 48-21.49 48-48zm12.922 99.078c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48c0-26.509-21.491-48-48-48zm294.156 0c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48c0-26.509-21.49-48-48-48zM108.922 60.922c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.491-48-48-48z\"/></svg>');\n}\n\n.guideai-icon.microphone {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 352 512\"><path fill=\"%230000FF\" d=\"M176 352c53.02 0 96-42.98 96-96V96c0-53.02-42.98-96-96-96S80 42.98 80 96v160c0 53.02 42.98 96 96 96zm160-160h-16c-8.84 0-16 7.16-16 16v48c0 74.8-64.49 134.82-140.79 127.38C96.71 376.89 48 317.11 48 250.3V208c0-8.84-7.16-16-16-16H16c-8.84 0-16 7.16-16 16v40.16c0 89.64 63.97 169.55 152 181.69V464H96c-8.84 0-16 7.16-16 16v16c0 8.84 7.16 16 16 16h160c8.84 0 16-7.16 16-16v-16c0-8.84-7.16-16-16-16h-56v-33.77C285.71 418.47 352 344.9 352 256v-48c0-8.84-7.16-16-16-16z\"/></svg>');\n}\n\n.guideai-icon.recording {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\"><circle cx=\"256\" cy=\"256\" r=\"128\" fill=\"%23FF0000\"/><circle cx=\"256\" cy=\"256\" r=\"200\" stroke=\"%23FF0000\" stroke-width=\"20\" fill=\"none\"/></svg>');\n}\n\n.guideai-icon.processing {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\"><path fill=\"%23FFA500\" d=\"M304 48c0 26.51-21.49 48-48 48s-48-21.49-48-48 21.49-48 48-48 48 21.49 48 48zm-48 368c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.49-48-48-48zm208-208c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.49-48-48-48zM96 256c0-26.51-21.49-48-48-48S0 229.49 0 256s21.49 48 48 48 48-21.49 48-48zm12.922 99.078c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48c0-26.509-21.491-48-48-48zm294.156 0c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48c0-26.509-21.49-48-48-48zM108.922 60.922c-26.51 0-48 21.49-48 48s21.49 48 48 48 48-21.49 48-48-21.491-48-48-48z\"/></svg>');\n}\n\n.guideai-icon.playing {\n  background-image: url('data:image/svg+xml;utf8,<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"%23008000\" d=\"M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02zM14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.85-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77z\"/></svg>');\n}\n\n/* Onboarding styles */\n.guideai-onboarding {\n  position: absolute;\n  left: 50%;\n  transform: translateX(-50%);\n  background: white;\n  border-radius: 12px;\n  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);\n  width: 300px;\n  max-width: 90vw;\n  z-index: 1002;\n  animation: onboarding-fade-in 0.3s ease-out;\n}\n\n.guideai-onboarding.above {\n  bottom: calc(100% + 15px);\n}\n\n.guideai-onboarding.below {\n  top: calc(100% + 15px);\n}\n\n.guideai-onboarding.above::after {\n  content: '';\n  position: absolute;\n  top: 100%;\n  left: 50%;\n  transform: translateX(-50%);\n  border-left: 8px solid transparent;\n  border-right: 8px solid transparent;\n  border-top: 8px solid white;\n  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));\n}\n\n.guideai-onboarding.below::after {\n  content: '';\n  position: absolute;\n  bottom: 100%;\n  left: 50%;\n  transform: translateX(-50%);\n  border-left: 8px solid transparent;\n  border-right: 8px solid transparent;\n  border-bottom: 8px solid white;\n  filter: drop-shadow(0 -2px 4px rgba(0, 0, 0, 0.1));\n}\n\n@keyframes onboarding-fade-in {\n  from { opacity: 0; transform: translateX(-50%) translateY(-10px); }\n  to { opacity: 1; transform: translateX(-50%) translateY(0); }\n}\n\n.guideai-onboarding-content {\n  padding: 16px;\n  position: relative;\n}\n\n.guideai-onboarding-close {\n  position: absolute;\n  top: 10px;\n  right: 10px;\n  background: none;\n  border: none;\n  font-size: 20px;\n  cursor: pointer;\n  color: #999;\n  width: 24px;\n  height: 24px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  border-radius: 50%;\n}\n\n.guideai-onboarding-close:hover {\n  background: #f5f5f5;\n  color: #333;\n}\n\n.guideai-onboarding-step {\n  text-align: center;\n  margin-bottom: 12px;\n}\n\n.guideai-onboarding-icon {\n  font-size: 32px;\n  margin-bottom: 8px;\n  display: inline-block;\n}\n\n.guideai-onboarding-step h3 {\n  margin: 0 0 8px;\n  font-size: 16px;\n  color: #333;\n  font-weight: 600;\n}\n\n.guideai-onboarding-step p {\n  margin: 0;\n  font-size: 13px;\n  color: #666;\n  line-height: 1.4;\n}\n\n.guideai-onboarding-dots {\n  display: flex;\n  justify-content: center;\n  margin: 12px 0;\n}\n\n.guideai-onboarding-dots .dot {\n  width: 8px;\n  height: 8px;\n  border-radius: 50%;\n  background: #ddd;\n  margin: 0 4px;\n  transition: all 0.3s ease;\n}\n\n.guideai-onboarding-dots .dot.active {\n  background: #0066ff;\n  transform: scale(1.2);\n}\n\n.guideai-onboarding-next {\n  display: block;\n  width: 100%;\n  padding: 10px;\n  background: #0066ff;\n  color: white;\n  border: none;\n  border-radius: 6px;\n  font-size: 14px;\n  font-weight: 500;\n  cursor: pointer;\n  transition: background 0.2s ease;\n}\n\n.guideai-onboarding-next:hover {\n  background: #0055cc;\n}\n\n/* Transcript Box Styles */\n.guideai-transcript-overlay {\n  position: fixed;\n  top: 0;\n  left: 0;\n  right: 0;\n  bottom: 0;\n  background: transparent;\n  display: flex;\n  justify-content: flex-end;\n  align-items: flex-end;\n  padding-bottom: 40px;\n  padding-right: 40px;\n  z-index: 10000;\n  animation: transcript-fade-in 0.3s ease-out;\n  pointer-events: none;\n}\n\n.guideai-transcript-box {\n  background: rgba(40, 44, 52, 0.85);\n  backdrop-filter: blur(20px);\n  -webkit-backdrop-filter: blur(20px);\n  border: 1px solid rgba(255, 255, 255, 0.1);\n  border-radius: 16px;\n  box-shadow: \n    0 8px 32px rgba(0, 0, 0, 0.3),\n    inset 0 1px 0 rgba(255, 255, 255, 0.2),\n    inset 0 -1px 0 rgba(0, 0, 0, 0.1);\n  width: 280px;\n  max-height: 280px;\n  display: flex;\n  flex-direction: column;\n  overflow: hidden;\n  animation: transcript-slide-up 0.4s ease-out;\n  pointer-events: auto;\n  margin-right: 60px;\n  position: relative;\n}\n\n.guideai-transcript-box::before {\n  content: '';\n  position: absolute;\n  top: 0;\n  left: 0;\n  right: 0;\n  height: 1px;\n  background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.4), transparent);\n  border-radius: 16px 16px 0 0;\n}\n\n\n\n.guideai-transcript-messages {\n  flex: 1;\n  overflow-y: auto;\n  padding: 8px 12px;\n  max-height: 200px;\n}\n\n.guideai-transcript-messages::-webkit-scrollbar {\n  width: 6px;\n}\n\n.guideai-transcript-messages::-webkit-scrollbar-track {\n  background: rgba(0, 0, 0, 0.05);\n  border-radius: 3px;\n}\n\n.guideai-transcript-messages::-webkit-scrollbar-thumb {\n  background: rgba(0, 0, 0, 0.2);\n  border-radius: 3px;\n}\n\n.guideai-transcript-messages::-webkit-scrollbar-thumb:hover {\n  background: rgba(0, 0, 0, 0.3);\n}\n\n.guideai-transcript-empty {\n  text-align: center;\n  padding: 20px 12px;\n  color: rgba(255, 255, 255, 0.6);\n}\n\n.guideai-transcript-empty-icon {\n  font-size: 24px;\n  margin-bottom: 8px;\n  opacity: 0.5;\n}\n\n.guideai-transcript-empty p {\n  margin: 0;\n  font-size: 11px;\n  color: rgba(255, 255, 255, 0.6);\n}\n\n.guideai-transcript-message {\n  margin-bottom: 8px;\n  animation: message-fade-in 0.3s ease-out;\n}\n\n.guideai-transcript-message.human {\n  text-align: right;\n}\n\n.guideai-transcript-message.guideai {\n  text-align: left;\n}\n\n.guideai-transcript-message-content {\n  display: inline-block;\n  max-width: 85%;\n  padding: 6px 10px;\n  border-radius: 12px;\n  position: relative;\n}\n\n.guideai-transcript-message.human .guideai-transcript-message-content {\n  background: rgba(255, 255, 255, 0.15);\n  color: rgba(255, 255, 255, 0.95);\n  border: 1px solid rgba(255, 255, 255, 0.2);\n  border-bottom-right-radius: 8px;\n  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);\n}\n\n.guideai-transcript-message.guideai .guideai-transcript-message-content {\n  background: rgba(0, 0, 0, 0.1);\n  color: rgba(255, 255, 255, 0.9);\n  border: 1px solid rgba(255, 255, 255, 0.1);\n  border-bottom-left-radius: 8px;\n  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);\n}\n\n.guideai-transcript-message-sender {\n  font-size: 9px;\n  font-weight: 600;\n  margin-bottom: 2px;\n  opacity: 0.8;\n}\n\n.guideai-transcript-message-text {\n  font-size: 11px;\n  line-height: 1.3;\n  word-wrap: break-word;\n}\n\n.guideai-transcript-message-time {\n  font-size: 8px;\n  opacity: 0.6;\n  margin-top: 2px;\n}\n\n\n\n@keyframes transcript-fade-in {\n  from { opacity: 0; }\n  to { opacity: 1; }\n}\n\n@keyframes transcript-slide-up {\n  from { \n    opacity: 0; \n    transform: translateX(40px) scale(0.95); \n  }\n  to { \n    opacity: 1; \n    transform: translateX(0) scale(1); \n  }\n}\n\n@keyframes message-fade-in {\n  from { \n    opacity: 0; \n    transform: translateY(10px); \n  }\n  to { \n    opacity: 1; \n    transform: translateY(0); \n  }\n}\n\n/* Transcript Toggle Button Styles - positioned at top of transcript area */\n.guideai-transcript-toggle-button {\n  position: fixed;\n  bottom: 60px;\n  right: 40px;\n  width: 36px;\n  height: 36px;\n  background: rgba(40, 44, 52, 0.9);\n  backdrop-filter: blur(10px);\n  -webkit-backdrop-filter: blur(10px);\n  border: 1px solid rgba(255, 255, 255, 0.15);\n  border-radius: 50%;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  cursor: pointer;\n  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);\n  transition: all 0.2s ease;\n  z-index: 10001;\n  font-size: 14px;\n  padding: 0;\n  color: rgba(255, 255, 255, 0.9);\n  animation: toggle-fade-in 0.3s ease-out;\n}\n\n.guideai-transcript-toggle-button:hover {\n  background: rgba(40, 44, 52, 1);\n  transform: scale(1.1);\n  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.4);\n}\n\n.guideai-transcript-toggle-button:active {\n  transform: scale(0.95);\n}\n\n.guideai-transcript-toggle-icon {\n  display: inline-block;\n  transition: all 0.2s ease;\n  filter: none;\n}\n\n/* Position transcript toggle button based on transcript position */\n.guideai-transcript-overlay {\n  pointer-events: none;\n}\n\n.guideai-transcript-toggle-button {\n  pointer-events: auto;\n}\n\n/* Input Options Container - Two Stage Layout */\n.guideai-input-options {\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  position: relative;\n  animation: options-slide-in 0.4s ease-out;\n}\n\n@keyframes options-slide-in {\n  0% {\n    opacity: 0;\n    transform: scale(0.8);\n  }\n  100% {\n    opacity: 1;\n    transform: scale(1);\n  }\n}\n\n/* Individual Input Option Button */\n.guideai-input-option {\n  width: 50px;\n  height: 50px;\n  background: rgba(255, 255, 255, 0.9);\n  border: 2px solid rgba(0, 0, 0, 0.1);\n  border-radius: 50%;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  cursor: pointer;\n  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);\n  transition: all 0.3s ease;\n  font-size: 18px;\n  padding: 0;\n  position: relative;\n}\n\n.guideai-input-option:hover:not(:disabled) {\n  background: rgba(255, 255, 255, 1);\n  transform: scale(1.1);\n  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);\n}\n\n.guideai-input-option:active:not(:disabled) {\n  transform: scale(0.95);\n}\n\n.guideai-input-option:disabled {\n  opacity: 0.5;\n  cursor: not-allowed;\n  transform: none;\n}\n\n/* Voice Option Specific Styling */\n.guideai-input-option.voice-option {\n  background: linear-gradient(135deg, rgba(76, 175, 80, 0.1), rgba(139, 195, 74, 0.1));\n  border-color: rgba(76, 175, 80, 0.3);\n}\n\n.guideai-input-option.voice-option:hover:not(:disabled) {\n  background: linear-gradient(135deg, rgba(76, 175, 80, 0.2), rgba(139, 195, 74, 0.2));\n  border-color: rgba(76, 175, 80, 0.5);\n}\n\n/* Text Option Specific Styling */\n.guideai-input-option.text-option {\n  background: linear-gradient(135deg, rgba(33, 150, 243, 0.1), rgba(63, 81, 181, 0.1));\n  border-color: rgba(33, 150, 243, 0.3);\n}\n\n.guideai-input-option.text-option:hover:not(:disabled) {\n  background: linear-gradient(135deg, rgba(33, 150, 243, 0.2), rgba(63, 81, 181, 0.2));\n  border-color: rgba(33, 150, 243, 0.5);\n}\n\n.guideai-input-option-icon {\n  display: inline-block;\n  transition: all 0.2s ease;\n  filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.1));\n}\n\n/* Text Input integrated into Transcript Box */\n.guideai-transcript-text-input {\n  border-top: 1px solid rgba(255, 255, 255, 0.1);\n  padding: 12px;\n  display: flex;\n  gap: 8px;\n  align-items: flex-end;\n  background: rgba(0, 0, 0, 0.02);\n  border-radius: 0 0 16px 16px;\n  animation: text-input-fade-in 0.3s ease-out;\n}\n\n.guideai-transcript-input-field {\n  flex: 1;\n  background: rgba(255, 255, 255, 0.15);\n  border: 1px solid rgba(255, 255, 255, 0.2);\n  border-radius: 8px;\n  padding: 8px 12px;\n  color: rgba(255, 255, 255, 0.95);\n  font-size: 12px;\n  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;\n  resize: none;\n  outline: none;\n  transition: all 0.2s ease;\n  min-height: 32px;\n}\n\n.guideai-transcript-input-field::placeholder {\n  color: rgba(255, 255, 255, 0.6);\n}\n\n.guideai-transcript-input-field:focus {\n  border-color: rgba(255, 255, 255, 0.4);\n  background: rgba(255, 255, 255, 0.2);\n  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.2);\n}\n\n.guideai-transcript-send-button {\n  background: rgba(255, 255, 255, 0.15);\n  border: 1px solid rgba(255, 255, 255, 0.2);\n  border-radius: 6px;\n  padding: 6px 10px;\n  color: rgba(255, 255, 255, 0.9);\n  cursor: pointer;\n  transition: all 0.2s ease;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  min-width: 36px;\n  height: 32px;\n}\n\n.guideai-transcript-send-button:hover:not(:disabled) {\n  background: rgba(255, 255, 255, 0.25);\n  border-color: rgba(255, 255, 255, 0.3);\n  transform: translateY(-1px);\n}\n\n.guideai-transcript-send-button:active:not(:disabled) {\n  transform: translateY(0);\n}\n\n.guideai-transcript-send-button:disabled {\n  background: rgba(255, 255, 255, 0.05);\n  border-color: rgba(255, 255, 255, 0.1);\n  color: rgba(255, 255, 255, 0.4);\n  cursor: not-allowed;\n  transform: none;\n}\n\n.guideai-transcript-send-icon {\n  font-size: 11px;\n}\n\n/* Animation for text input appearance */\n@keyframes text-input-fade-in {\n  from { \n    opacity: 0; \n    transform: translateY(10px); \n  }\n  to { \n    opacity: 1; \n    transform: translateY(0); \n  }\n}\n\n@keyframes toggle-fade-in {\n  from { \n    opacity: 0; \n    transform: scale(0.8); \n  }\n  to { \n    opacity: 1; \n    transform: scale(1); \n  }\n}\n\n\n";

package/dist/types/GuideAI.types.d.ts

@@ -1,8 +1,10 @@
 import React from 'react';
+import { MetadataConfig, UserMetadata } from './metadata.types';
 export type RecordingStatus = 'idle' | 'recording' | 'processing' | 'playing';
 export type UseStateHook = typeof React.useState;
 export type UseEffectHook = typeof React.useEffect;
 export type UseRefHook = typeof React.useRef;
+export type UseCallbackHook = typeof React.useCallback;
 export interface GuideAIProps {
     organizationKey: string;
     position?: {
@@ -17,5 +19,21 @@ export interface GuideAIProps {
         transform?: string;
     };
     onError?: (error: string | Error, context?: string) => void;
+    metadata?: {
+        config?: MetadataConfig;
+        initialUserData?: Partial<UserMetadata>;
+        onMetadataUpdate?: (metadata: UserMetadata) => void;
+    };
+    transcript?: {
+        enabled?: boolean;
+        showToggleButton?: boolean;
+        position?: 'right' | 'left' | 'top' | 'bottom';
+    };
+    input?: {
+        enableTextInput?: boolean;
+        showInputToggle?: boolean;
+        defaultMode?: 'voice' | 'text';
+        placeholder?: string;
+    };
 }
 export type PopupPosition = 'above' | 'below';

package/dist/types/metadata.types.d.ts

@@ -0,0 +1,46 @@
+export interface UserMetadata {
+    userId?: string;
+    userType?: 'agent' | 'admin' | 'manager' | 'customer' | 'guest' | string;
+    customerType?: 'individual' | 'business' | 'enterprise' | string;
+    customerLicense?: string;
+    firstVisit?: number;
+    lastVisit?: number;
+    visitCount?: number;
+    loginCount?: number;
+    lastLogin?: number;
+    organizationKey: string;
+    sessionId?: string;
+    userAgent?: string;
+    browserInfo?: {
+        name?: string;
+        version?: string;
+        platform?: string;
+    };
+    customFields?: Record<string, string | number | boolean>;
+}
+export interface MetadataUpdate {
+    type: 'visit' | 'login' | 'user_info' | 'session' | 'custom';
+    timestamp: number;
+    data: Partial<UserMetadata>;
+}
+export interface MetadataConfig {
+    trackVisits?: boolean;
+    trackLogins?: boolean;
+    syncInterval?: number;
+    storage?: 'localStorage' | 'sessionStorage' | 'memory';
+    customFields?: string[];
+    collectBrowserInfo?: boolean;
+    collectUserAgent?: boolean;
+}
+export interface MetadataStorageData {
+    metadata: UserMetadata;
+    lastUpdated: number;
+    version: string;
+}
+export type MetadataEventType = 'user_visit' | 'user_login' | 'user_info_update' | 'session_start' | 'session_end' | 'custom_event';
+export interface MetadataEvent {
+    type: MetadataEventType;
+    timestamp: number;
+    metadata: Partial<UserMetadata>;
+    source?: string;
+}

package/dist/utils/api.d.ts

@@ -1,3 +1,4 @@
+import { UserMetadata, MetadataUpdate } from '../types/metadata.types';
 interface ConversationData {
     id: string;
     ephemeralToken: string;
@@ -5,4 +6,7 @@ interface ConversationData {
 }
 export declare const createNewConversation: (organizationKey: string, onError: (error: Error, context: string) => void) => Promise<ConversationData | null>;
 export declare const logMessage: (content: string, sender: "GUIDEAI" | "HUMAN", conversationId: string | null, organizationKey: string, onError: (error: Error, context: string) => void) => Promise<void>;
+export declare const sendUserMetadata: (metadata: UserMetadata, organizationKey: string, onError: (error: Error, context: string) => void) => Promise<boolean>;
+export declare const sendMetadataUpdates: (updates: MetadataUpdate[], organizationKey: string, onError: (error: Error, context: string) => void) => Promise<boolean>;
+export declare const updateUserMetadata: (userId: string, metadataUpdate: Partial<UserMetadata>, organizationKey: string, onError: (error: Error, context: string) => void) => Promise<boolean>;
 export {};

package/dist/utils/messageStorage.d.ts

@@ -11,7 +11,7 @@ export interface StoredConversation {
 }
 export declare const CONVERSATION_STORAGE_KEY = "guideai_conversation";
 export declare const CONVERSATION_EXPIRY_MINUTES = 30;
-export declare const MAX_STORED_MESSAGES = 50;
+export declare const MAX_STORED_MESSAGES = 100;
 export declare const isLocalStorageAvailable: () => boolean;
 export declare const isConversationExpired: (conversation: StoredConversation) => boolean;
 export declare const saveConversationToStorage: (conversation: StoredConversation) => void;

package/metadata-tracking-example.md

@@ -0,0 +1,324 @@
+# User Metadata Tracking - Implementation Guide
+
+## Overview
+
+The GuideAI package now includes comprehensive user metadata tracking capabilities designed for integration with Overproof. This system tracks the following metadata:
+
+- **User's First Visit** - Timestamp of the first time the user interacted with GuideAI
+- **User's Last Visit** - Timestamp of the most recent user interaction
+- **User Logins** - Count and timestamp of login events
+- **User Type** - Classification of the user (agent, admin, manager, customer, guest, etc.)
+- **Customer Type** - Type of customer (individual, business, enterprise, etc.)
+- **Customer License** - License identifier for the customer
+
+## Basic Usage
+
+### 1. Basic Integration
+
+```typescript
+import { GuideAI } from 'guide-ai-package';
+
+function App() {
+  return (
+    <GuideAI 
+      organizationKey="your-org-key"
+      metadata={{
+        config: {
+          trackVisits: true,
+          trackLogins: true,
+          syncInterval: 30000, // Sync every 30 seconds
+          storage: 'localStorage'
+        },
+        initialUserData: {
+          userType: 'agent',
+          customerType: 'business',
+          customerLicense: 'OVERPRF-12345'
+        },
+        onMetadataUpdate: (metadata) => {
+          console.log('Metadata updated:', metadata);
+          // Send to your analytics system
+        }
+      }}
+    />
+  );
+}
+```
+
+### 2. Tracking User Login Events
+
+```typescript
+import { useRef } from 'react';
+
+function LoginComponent() {
+  const guideAIRef = useRef();
+
+  const handleLogin = async (userInfo) => {
+    // Your login logic here
+    const loginResult = await performLogin(userInfo);
+    
+    if (loginResult.success) {
+      // Track the login with GuideAI
+      guideAIRef.current?.trackLogin({
+        userId: loginResult.userId,
+        userType: loginResult.userType,
+        customerType: loginResult.customerType,
+        customerLicense: loginResult.license
+      });
+    }
+  };
+
+  return (
+    <div>
+      <GuideAI 
+        ref={guideAIRef}
+        organizationKey="your-org-key"
+        metadata={{
+          config: { trackLogins: true }
+        }}
+      />
+      <button onClick={handleLogin}>Login</button>
+    </div>
+  );
+}
+```
+
+### 3. Updating User Information
+
+```typescript
+function UserProfileComponent() {
+  const guideAIRef = useRef();
+
+  const updateUserProfile = (newUserData) => {
+    // Update user profile in your system
+    saveUserProfile(newUserData);
+    
+    // Update GuideAI metadata
+    guideAIRef.current?.updateUserInfo({
+      userType: newUserData.role,
+      customerType: newUserData.accountType,
+      customerLicense: newUserData.license,
+      customFields: {
+        department: newUserData.department,
+        region: newUserData.region
+      }
+    });
+  };
+
+  return (
+    <GuideAI 
+      ref={guideAIRef}
+      organizationKey="your-org-key"
+      metadata={{
+        config: {
+          customFields: ['department', 'region'],
+          collectBrowserInfo: true
+        }
+      }}
+    />
+  );
+}
+```
+
+## Configuration Options
+
+### MetadataConfig
+
+```typescript
+interface MetadataConfig {
+  // Whether to automatically track visits (default: true)
+  trackVisits?: boolean;
+  
+  // Whether to automatically track logins (default: true)
+  trackLogins?: boolean;
+  
+  // How often to sync metadata to backend in milliseconds (default: 30000)
+  syncInterval?: number;
+  
+  // Storage strategy (default: 'localStorage')
+  storage?: 'localStorage' | 'sessionStorage' | 'memory';
+  
+  // Custom metadata fields to collect
+  customFields?: string[];
+  
+  // Whether to collect browser information (default: true)
+  collectBrowserInfo?: boolean;
+  
+  // Whether to collect user agent (default: true)
+  collectUserAgent?: boolean;
+}
+```
+
+### UserMetadata Structure
+
+```typescript
+interface UserMetadata {
+  // Core identification
+  userId?: string;
+  userType?: 'agent' | 'admin' | 'manager' | 'customer' | 'guest' | string;
+  
+  // Customer-specific metadata
+  customerType?: 'individual' | 'business' | 'enterprise' | string;
+  customerLicense?: string;
+  
+  // Visit tracking (automatically managed)
+  firstVisit?: number; // timestamp
+  lastVisit?: number; // timestamp
+  visitCount?: number;
+  
+  // Login tracking (requires manual tracking)
+  loginCount?: number;
+  lastLogin?: number; // timestamp
+  
+  // Session metadata (automatically managed)
+  organizationKey: string;
+  sessionId?: string;
+  
+  // Browser information (automatically collected if enabled)
+  userAgent?: string;
+  browserInfo?: {
+    name?: string;
+    version?: string;
+    platform?: string;
+  };
+  
+  // Custom fields for Overproof-specific needs
+  customFields?: Record<string, string | number | boolean>;
+}
+```
+
+## API Integration
+
+The system automatically sends metadata updates to these endpoints:
+
+### POST `/user-metadata`
+Sends complete user metadata object when initially collected.
+
+### POST `/metadata-updates` 
+Sends batched metadata updates periodically.
+
+### PATCH `/users/{userId}/metadata`
+Updates specific user metadata when userId is available.
+
+## Backend Implementation
+
+You'll need to implement these endpoints in your backend:
+
+```typescript
+// Example Express.js implementation
+app.post('/api/user-metadata', (req, res) => {
+  const { organizationKey, metadata, timestamp } = req.body;
+  
+  // Store metadata in your database
+  await UserMetadata.upsert({
+    organizationKey,
+    userId: metadata.userId || 'anonymous',
+    ...metadata,
+    lastUpdated: new Date(timestamp)
+  });
+  
+  res.json({ success: true });
+});
+
+app.post('/api/metadata-updates', (req, res) => {
+  const { organizationKey, updates, batchTimestamp } = req.body;
+  
+  // Process batch updates
+  for (const update of updates) {
+    await processMetadataUpdate(organizationKey, update);
+  }
+  
+  res.json({ success: true });
+});
+```
+
+## Privacy Considerations
+
+- **User Agent Collection**: Can be disabled via `collectUserAgent: false`
+- **Browser Info Collection**: Can be disabled via `collectBrowserInfo: false`
+- **Custom Fields**: Only fields specified in `customFields` array are collected
+- **Storage**: Can be set to `'memory'` for session-only storage without persistence
+
+## Testing
+
+```typescript
+// Get current metadata
+const metadata = guideAIRef.current?.getMetadata();
+console.log('Current metadata:', metadata);
+
+// Force sync metadata now
+await guideAIRef.current?.syncMetadata();
+
+// Track custom events
+guideAIRef.current?.trackCustomEvent('document_viewed', {
+  documentType: 'policy',
+  documentId: 'POL-12345'
+});
+```
+
+## Overproof Integration Example
+
+```typescript
+function OverproofApp() {
+  const guideAIRef = useRef();
+
+  // Track when user logs into Overproof
+  const handleOverproofLogin = (user) => {
+    guideAIRef.current?.trackLogin({
+      userId: user.id,
+      userType: user.role, // 'agent', 'admin', etc.
+      customerType: user.accountType,
+      customerLicense: user.licenseNumber,
+      customFields: {
+        agencyId: user.agencyId,
+        territory: user.territory,
+        permissions: user.permissions.join(',')
+      }
+    });
+  };
+
+  // Track when user profile is updated
+  const handleProfileUpdate = (updatedProfile) => {
+    guideAIRef.current?.updateUserInfo({
+      userType: updatedProfile.role,
+      customerLicense: updatedProfile.licenseNumber,
+      customFields: {
+        agencyId: updatedProfile.agencyId,
+        territory: updatedProfile.territory
+      }
+    });
+  };
+
+  return (
+    <GuideAI 
+      ref={guideAIRef}
+      organizationKey="overproof-org-key"
+      metadata={{
+        config: {
+          trackVisits: true,
+          trackLogins: true,
+          syncInterval: 15000, // More frequent syncing for Overproof
+          customFields: ['agencyId', 'territory', 'permissions'],
+          collectBrowserInfo: true
+        },
+        onMetadataUpdate: (metadata) => {
+          // Send to Overproof analytics
+          window.OverproofAnalytics?.track('guideai_metadata_update', metadata);
+        }
+      }}
+    />
+  );
+}
+```
+
+## Storage and Data Persistence
+
+- **localStorage**: Persists across browser sessions (default)
+- **sessionStorage**: Persists only for current session
+- **memory**: No persistence, data lost on page refresh
+
+Metadata is automatically:
+- Saved locally based on storage configuration
+- Synced to backend at configured intervals
+- Restored when user returns (if using persistent storage)
+
+This implementation provides a robust foundation for tracking user metadata in the Overproof environment while maintaining flexibility for other use cases.