@aacigroup/aaci_shared 2.6.0 → 2.6.1

package/README.md

@@ -1,98 +1,35 @@
 # AACI Shared Library
 
-Simple TypeScript/JavaScript library for tracking and analytics in AACI Group projects.
+React Context-based tracking library for AACI Group projects with lead capture and analytics.
 
 [![npm version](https://badge.fury.io/js/@aacigroup%2Faaci_shared.svg)](https://badge.fury.io/js/@aacigroup%2Faaci_shared)
 
 ## Installation
 
 ```bash
-npm install @aacigroup/aaci_shared
+npm install @aacigroup/aaci_shared react
 ```
 
-## Quick Start
+## React Context Setup
 
-```javascript
-import { LeadTracker } from '@aacigroup/aaci_shared';
-
-const tracker = new LeadTracker({
-  apiUrl: 'https://your-api.com/leads',
-  apiKey: 'your-api-key',
-  projectName: 'MyProject',
-  productionDomains: ['myproject.com']
-});
+### Environment Variables
 
-// Track lead only
-await tracker.trackLeadAndAddress({
-  lead_type: 'contact',
-  email: 'user@example.com'
-});
-
-// Track address only
-await tracker.trackLeadAndAddress(undefined, {
-  full_address: '123 Main St, New York, NY 10001',
-  source: 'address_check'
-});
-
-// Track both together
-await tracker.trackLeadAndAddress({
-  lead_type: 'policy_review',
-  email: 'user@example.com'
-}, {
-  full_address: '123 Main St, New York, NY 10001',
-  source: 'policy_review'
-});
-```
+Add these to your `.env` file:
 
-## Lead Types
-
-Use these values for `lead_type` and `source`:
-- `'policy_review'` - Insurance policy review
-- `'address_check'` - Property address verification  
-- `'contact'` - General contact forms
-- `'signup'` - User registration
-- `'consultation'` - Service consultation
-- `'quote'` - Price quote requests
-
-## Validation (Optional)
-
-Install Zod for input validation:
-```bash
-npm install zod
-```
-
-```javascript
-import { validateTrackLeadParams, validateAddress } from '@aacigroup/aaci_shared';
-
-// Validate before tracking
-const validLead = validateTrackLeadParams({
-  lead_type: 'contact',
-  email: 'user@example.com'
-});
-
-const validAddress = validateAddress({
-  full_address: '123 Main St',
-  source: 'contact'
-});
-
-await tracker.trackLeadAndAddress(validLead, validAddress);
+```env
+VITE_LEAD_CAPTURE_API_URL=https://your-api.com/leads
+VITE_LEAD_CAPTURE_API_KEY=your-api-key
+VITE_PROJECT_NAME=MyProject
+VITE_POSTHOG_KEY=phc_your_posthog_key
+VITE_PRODUCTION_DOMAINS=myproject.com,www.myproject.com
 ```
 
-## Other Components
-
-### React Context (Optional)
-
-For React projects, you can use the provided context for easier integration:
-
-```bash
-npm install react  # Peer dependency
-```
+### App Setup
 
 ```javascript
 // App.tsx
 import { TrackingProvider, createTrackingConfigFromEnv } from '@aacigroup/aaci_shared/react';
 
-// Option 1: Use environment variables (in Vite projects)
 function App() {
   return (
     <TrackingProvider config={createTrackingConfigFromEnv()}>
@@ -100,25 +37,12 @@ function App() {
     </TrackingProvider>
   );
 }
+```
 
-// Option 2: Manual configuration
-function App() {
-  const trackingConfig = {
-    apiUrl: 'https://your-api.com/leads',
-    apiKey: 'your-api-key',
-    projectName: 'MyProject',
-    posthogKey: 'phc_your_key',
-    productionDomains: ['myproject.com']
-  };
-
-  return (
-    <TrackingProvider config={trackingConfig}>
-      <YourApp />
-    </TrackingProvider>
-  );
-}
+### Component Usage
 
-// Component.tsx - Use tracking in any component
+```javascript
+// ContactForm.tsx
 import { useLeadTracker, usePostHog } from '@aacigroup/aaci_shared/react';
 
 function ContactForm() {
@@ -129,7 +53,8 @@ function ContactForm() {
     // Track lead submission
     await tracker.trackLeadAndAddress({
       lead_type: 'contact',
-      email: formData.email
+      email: formData.email,
+      first_name: formData.firstName
     });
 
     // Track analytics event
@@ -140,71 +65,9 @@ function ContactForm() {
 }
 ```
 
-**Environment Variables (for createTrackingConfigFromEnv):**
-```env
-VITE_LEAD_CAPTURE_API_URL=https://your-api.com/leads
-VITE_LEAD_CAPTURE_API_KEY=your-api-key
-VITE_PROJECT_NAME=MyProject
-VITE_POSTHOG_KEY=phc_your_key
-VITE_PRODUCTION_DOMAINS=myproject.com,www.myproject.com
-```
+## Data Types
 
-### PostHog Analytics
-```javascript
-import { PostHog } from '@aacigroup/aaci_shared';
-
-const analytics = new PostHog({
-  apiKey: 'phc_your_key',
-  projectName: 'MyProject',
-  productionDomains: ['myproject.com']
-});
-
-await analytics.init();
-analytics.trackEvent('user_signup', { plan: 'premium' });
-```
-
-### Google Tag Manager
-```javascript
-import { GTM } from '@aacigroup/aaci_shared';
-
-const gtm = new GTM({
-  productionDomains: ['myproject.com']
-});
-
-gtm.trackEvent('purchase', { value: 100, currency: 'USD' });
-```
-
-## TypeScript Types
-
-```javascript
-import type { Lead, AddressCapture, TrackLeadParams, Address } from '@aacigroup/aaci_shared';
-
-// Use types in your application
-function processLead(lead: Lead): void {
-  console.log(`Processing ${lead.email}`);
-}
-```
-
-## License
-
-ISC
-
-## Core API Reference
-
-### LeadTracker
-
-#### `trackLeadAndAddress(lead?, address?)`
-
-**Primary tracking method that accepts lead data, address data, or both.**
-
-**Parameters:**
-- `lead` (optional): Lead information object
-- `address` (optional): Address information object
-- **At least one parameter is required**
-
-**Returns:** `Promise<LeadTrackingResponse>`
-
-#### Lead Capture Types
+### Lead Data
 
 ```typescript
 interface TrackLeadParams {
@@ -214,11 +77,10 @@ interface TrackLeadParams {
   email?: string;                       // Optional: Email address
   phone?: string;                       // Optional: Phone number
   extra_data?: Record<string, any>;     // Optional: Additional custom data
-  session_data?: SessionData;           // Optional: Session tracking data (auto-populated)
 }
 ```
 
-**Common `lead_type` examples:**
+**Common `lead_type` examples (free string):**
 - `'policy_review'` - Insurance policy review requests
 - `'address_check'` - Property address verification
 - `'contact'` - General contact form submissions
@@ -226,11 +88,13 @@ interface TrackLeadParams {
 - `'consultation'` - Service consultation requests
 - `'quote'` - Price quote requests
 
-**Lead Validation:**
-- When tracking a lead, either `email` OR `phone` is required
+Note: `lead_type` is a free string - you can use any value that makes sense for your application.
+
+**Validation Rules:**
 - `lead_type` is always required
+- Either `email` OR `phone` is required when tracking a lead
 
-#### Address Capture Types
+### Address Data
 
 ```typescript
 interface Address {
@@ -246,337 +110,211 @@ interface Address {
 }
 ```
 
-**Address Validation:**
-- `full_address` is always required
-- `source` is always required (uses same values as `lead_type`)
+### Session Data
 
-#### Usage Examples
+```typescript
+interface SessionData {
+  ip?: string;                          // Optional: User's IP address
+  user_agent?: string;                  // Optional: Browser user agent
+  browser?: string;                     // Optional: Browser name
+  browser_version?: string;             // Optional: Browser version
+  os?: string;                          // Optional: Operating system
+  device?: string;                      // Optional: Device type
+  referrer?: string;                    // Optional: Referring page URL
+  utm_source?: string;                  // Optional: UTM source parameter
+  utm_medium?: string;                  // Optional: UTM medium parameter
+  utm_campaign?: string;                // Optional: UTM campaign parameter
+  landing_page?: string;                // Optional: First page visited
+  current_page?: string;                // Optional: Current page URL
+  session_id?: string;                  // Optional: Session identifier
+  timestamp?: string;                   // Optional: Timestamp of action
+  distinct_id?: string;                 // Optional: User identifier
+  gclid?: string;                       // Optional: Google Ads click ID
+  fbclid?: string;                      // Optional: Facebook click ID
+  fbc?: string;                         // Optional: Facebook browser cookie
+  fbp?: string;                         // Optional: Facebook pixel cookie
+}
+```
 
-```javascript
-// 1. Lead only - Basic contact form
-await tracker.trackLeadAndAddress({
-  lead_type: 'contact',
-  email: 'user@example.com',
-  first_name: 'John'
-});
+**Common `source` examples (free string):**
+- `'policy_review'` - When tracking address from policy review forms
+- `'address_check'` - For standalone address verification
+- `'contact'` - From general contact forms
+- `'signup'` - During user registration
+- `'consultation'` - From consultation request forms
+- `'quote'` - From quote request forms
 
-// 2. Lead only - Policy review request
-await tracker.trackLeadAndAddress({
-  lead_type: 'policy_review',
-  phone: '+1234567890',
-  extra_data: { policy_number: 'POL123456' }
-});
+Note: `source` is a free string - you can use any value to identify where the address came from. It may match `lead_type` by design but doesn't have to.
 
-// 3. Address only - Address verification
-await tracker.trackLeadAndAddress(undefined, {
-  full_address: '123 Main St, New York, NY 10001',
-  source: 'address_check',
-  city: 'New York',
-  state: 'NY',
-  zip_code: '10001'
-});
+**Validation Rules:**
+- `full_address` is always required
+- `source` is always required
 
-// 4. Both together - Address check with contact
-await tracker.trackLeadAndAddress({
-  lead_type: 'address_check',
-  email: 'homeowner@example.com',
-  first_name: 'Jane'
-}, {
-  full_address: '456 Oak Ave, Boston, MA 02101',
-  source: 'address_check',
-  city: 'Boston',
-  state: 'MA',
-  zip_code: '02101'
-});
+## Usage Examples
 
-// 5. Multi-step forms - Step 1: Lead info
-await tracker.trackLeadAndAddress({
-  lead_type: 'quote',
-  email: 'customer@example.com'
-});
-// Step 2: Address info (automatically merges with saved lead)
-await tracker.trackLeadAndAddress(undefined, {
-  full_address: '789 Pine St, Chicago, IL 60601',
-  source: 'quote'
-});
-```
+```javascript
+import { useLeadTracker, usePostHog } from '@aacigroup/aaci_shared/react';
 
-## Input Validation
+function MyComponent() {
+  const tracker = useLeadTracker();
+  const analytics = usePostHog();
 
-The library provides Zod validation schemas to validate customer input before tracking.
+  // 1. Track lead only - Basic contact form
+  const handleContactForm = async (formData) => {
+    await tracker.trackLeadAndAddress({
+      lead_type: 'contact',
+      email: formData.email,
+      first_name: formData.firstName
+    });
+    
+    analytics.trackEvent('contact_form_submitted');
+  };
 
-**Note:** Validation functions require the `zod` package to be installed in your project:
-```bash
-npm install zod
-```
+  // 2. Track address only - Address verification
+  const handleAddressCheck = async (address) => {
+    await tracker.trackLeadAndAddress(undefined, {
+      full_address: address,
+      source: 'address_check',
+      city: 'New York',
+      state: 'NY'
+    });
+    
+    analytics.trackEvent('address_checked');
+  };
 
-```javascript
-import { 
-  validateTrackLeadParams, 
-  validateAddress, 
-  safeValidateTrackLeadAndAddress 
-} from '@aacigroup/aaci_shared';
+  // 3. Track both together - Policy review with address
+  const handlePolicyReview = async (leadData, addressData) => {
+    await tracker.trackLeadAndAddress({
+      lead_type: 'policy_review',
+      email: leadData.email,
+      phone: leadData.phone,
+      extra_data: { policy_number: leadData.policyNumber }
+    }, {
+      full_address: addressData.fullAddress,
+      source: 'policy_review',
+      zip_code: addressData.zipCode
+    });
+    
+    analytics.trackEvent('policy_review_started', { 
+      has_phone: !!leadData.phone 
+    });
+  };
 
-// Validate lead data (throws on error)
-try {
-  const validLead = validateTrackLeadParams({
-    lead_type: 'contact',
-    email: 'user@example.com'
-  });
-  await tracker.trackLeadAndAddress(validLead);
-} catch (error) {
-  console.error('Invalid lead data:', error.errors);
-}
+  // 4. Multi-step forms
+  const handleStepOne = async (leadData) => {
+    // Step 1: Collect lead info
+    await tracker.trackLeadAndAddress({
+      lead_type: 'quote',
+      email: leadData.email
+    });
+  };
 
-// Validate address data (throws on error)
-try {
-  const validAddress = validateAddress({
-    full_address: '123 Main St, New York, NY 10001',
-    source: 'address_check'
-  });
-  await tracker.trackLeadAndAddress(undefined, validAddress);
-} catch (error) {
-  console.error('Invalid address data:', error.errors);
-}
+  const handleStepTwo = async (addressData) => {
+    // Step 2: Add address (automatically merges with saved lead)
+    await tracker.trackLeadAndAddress(undefined, {
+      full_address: addressData.address,
+      source: 'quote'
+    });
+    
+    analytics.trackEvent('quote_completed');
+  };
 
-// Safe validation (returns success/error object)
-const result = safeValidateTrackLeadAndAddress(leadData, addressData);
-if (result.success) {
-  await tracker.trackLeadAndAddress(result.data.lead, result.data.address);
-} else {
-  console.error('Validation errors:', result.error.errors);
+  return <div>...</div>;
 }
-
-// Available validation functions:
-// validateTrackLeadParams(data) - throws on error
-// validateAddress(data) - throws on error  
-// validateTrackLeadAndAddress(lead, address) - throws on error
-// safeValidateTrackLeadParams(data) - returns {success, data, error}
-// safeValidateAddress(data) - returns {success, data, error}
-// safeValidateTrackLeadAndAddress(lead, address) - returns {success, data, error}
 ```
 
-#### Response Type
+## Other Functions (Non-React)
 
-```typescript
-interface LeadTrackingResponse {
-  status: 'ok' | 'error';               // Success or error status
-  lead_id?: string;                     // Generated lead ID (on success)
-  address_id?: string;                  // Generated address ID (if address provided)
-  is_first_submission?: boolean;        // Whether this is user's first submission
-  message?: string;                     // Success/error message
-  errors?: Array<{                      // Validation errors (if any)
-    field: string;
-    message: string;
-  }>;
-}
-```
+### Direct Class Usage
 
-#### Other LeadTracker Methods
+For non-React projects or when you need more control:
 
 ```javascript
-// Get current session data
-const sessionData = tracker.getSessionData();
+import { LeadTracker, PostHog, GTM } from '@aacigroup/aaci_shared';
 
-// Check if running in production
-const isProduction = tracker.isProduction();
-```
-
-### PostHog Analytics
-
-```javascript
-import { PostHog } from '@aacigroup/aaci_shared';
+// Initialize LeadTracker
+const tracker = new LeadTracker({
+  apiUrl: 'https://your-api.com/leads',
+  apiKey: 'your-api-key',
+  projectName: 'MyProject',
+  productionDomains: ['myproject.com']
+});
 
+// Initialize PostHog Analytics
 const analytics = new PostHog({
-  apiKey: 'phc_your_posthog_key',
+  apiKey: 'phc_your_key',
   projectName: 'MyProject',
-  productionDomains: ['myproject.com'],
-  apiHost: 'https://us.i.posthog.com',     // Optional: Custom PostHog host
-  autocapture: true,                       // Optional: Enable autocapture (default: true)
-  capturePageview: true                    // Optional: Enable pageview tracking (default: true)
+  productionDomains: ['myproject.com']
 });
-
-// Initialize PostHog
 await analytics.init();
 
-// Track events
-analytics.trackEvent('user_signup', { plan: 'premium', source: 'landing_page' });
-
-// Identify users
-analytics.identify('user_123', { email: 'user@example.com', plan: 'premium' });
-
-// Track errors
-analytics.trackError(new Error('Something went wrong'), 'checkout_process');
-analytics.trackAPIError('https://api.example.com/users', 500, 'Internal Server Error');
-
-// Reset user identity
-analytics.reset();
-```
-
-### Google Tag Manager
-
-```javascript
-import { GTM } from '@aacigroup/aaci_shared';
-
+// Initialize Google Tag Manager
 const gtm = new GTM({
   productionDomains: ['myproject.com']
 });
 
-// Track events
-gtm.trackEvent('purchase', { 
-  value: 99.99, 
-  currency: 'USD', 
-  item_id: 'product_123' 
-});
-
-// Check if GTM is available
-if (gtm.isAvailable()) {
-  gtm.trackEvent('page_view', { page: '/checkout' });
-}
-```
-
-### Environment Detection
-
-```javascript
-import { Environment } from '@aacigroup/aaci_shared';
-
-const env = new Environment({
-  productionDomains: ['myproject.com', 'www.myproject.com']
-});
-
-console.log('Is production:', env.isProduction());
-console.log('Current domain:', env.getCurrentDomain());
+// Use the same trackLeadAndAddress method
+await tracker.trackLeadAndAddress(leadData, addressData);
+analytics.trackEvent('custom_event', { data: 'value' });
+gtm.trackEvent('purchase', { value: 100, currency: 'USD' });
 ```
 
-## Data Types Reference
-
-### Input Types (for tracking methods)
+### Input Validation (Optional)
 
-```typescript
-// Lead data for tracking
-interface TrackLeadParams {
-  lead_type: string;                    // Required: Type of lead
-  first_name?: string;                  // Optional: First name
-  last_name?: string;                   // Optional: Last name  
-  email?: string;                       // Optional: Email address
-  phone?: string;                       // Optional: Phone number
-  extra_data?: Record<string, any>;     // Optional: Additional custom data
-  session_data?: SessionData;           // Optional: Session tracking data (auto-populated)
-}
+Validate data before tracking (requires `zod` package):
 
-// Address data for tracking
-interface Address {
-  full_address: string;                 // Required: Complete address string
-  source: string;                       // Required: Lead type that generated this address
-  street_address?: string;              // Optional: Street address component
-  city?: string;                        // Optional: City
-  state?: string;                       // Optional: State/Province
-  zip_code?: string;                    // Optional: ZIP/Postal code
-  county?: string;                      // Optional: County
-  country?: string;                     // Optional: Country
-  extra_data?: Record<string, any>;     // Optional: Additional address data
-}
+```bash
+npm install zod
 ```
 
-### Database Types (complete records)
-
-```typescript
-// Complete lead record (from database)
-interface Lead {
-  id: string;
-  project_name: string;
-  user_id: string | null;
-  first_name: string | null;
-  last_name: string | null;
-  email: string | null;
-  phone: string | null;
-  lead_type: string | null;
-  first_submission: boolean | null;
-  extra_data: Record<string, any>;
-  session_data: SessionData;
-  created_at: string;
-  updated_at: string;
-}
+```javascript
+import { 
+  validateTrackLeadParams, 
+  validateAddress, 
+  safeValidateTrackLeadAndAddress 
+} from '@aacigroup/aaci_shared';
 
-// Complete address record (from database)
-interface AddressCapture {
-  id: string;
-  project_name: string;
-  user_id: string | null;
-  lead_id: string | null;
-  address: string | null;
-  city: string | null;
-  state: string | null;
-  zip: string | null;
-  source: string | null;                // Lead type source (same values as lead_type)
-  status: string | null;                // Processing status (e.g., 'verified', 'pending', 'invalid')
-  extra_data: Record<string, any>;
-  session_data: SessionData;
-  created_at: string;
-  updated_at: string;
+// Validate lead data
+try {
+  const validLead = validateTrackLeadParams({
+    lead_type: 'contact',
+    email: 'user@example.com'
+  });
+  console.log('Valid lead:', validLead);
+} catch (error) {
+  console.error('Invalid lead data:', error.message);
 }
-```
-
-**Common `lead_type` and `source` values:**
-- `'policy_review'` - Insurance policy review requests
-- `'address_check'` - Property address verification
-- `'contact'` - General contact form submissions
-- `'signup'` - User registration/signup
-- `'consultation'` - Service consultation requests
-- `'quote'` - Price quote requests
 
-### Session Data
+// Safe validation (returns success/error object)
+const result = safeValidateTrackLeadAndAddress({
+  lead: { lead_type: 'contact', email: 'user@example.com' },
+  address: { full_address: '123 Main St', source: 'contact' }
+});
 
-```typescript
-// Session tracking data
-interface SessionData {
-  ip?: string;
-  user_agent?: string;
-  browser?: string;
-  browser_version?: string;
-  os?: string;
-  device?: string;
-  referrer?: string;
-  utm_source?: string;
-  utm_medium?: string;
-  utm_campaign?: string;
-  landing_page?: string;
-  current_page?: string;
-  session_id?: string;
-  timestamp?: string;
-  distinct_id?: string;
-  gclid?: string;                       // Google Ads click ID
-  fbclid?: string;                      // Facebook click ID
-  fbc?: string;                         // Facebook browser cookie
-  fbp?: string;                         // Facebook pixel cookie
+if (result.success) {
+  await tracker.trackLeadAndAddress(result.data.lead, result.data.address);
+} else {
+  console.error('Validation failed:', result.error);
 }
 ```
 
-### Import Types Only
+### TypeScript Types
 
 ```javascript
-import type { Lead, AddressCapture, SessionData, TrackLeadParams, Address } from '@aacigroup/aaci_shared';
-
-// Use in your application
-function saveLead(lead: Lead): Promise<void> {
-  return database.leads.create(lead);
-}
+import type { 
+  Lead, 
+  AddressCapture, 
+  TrackLeadParams, 
+  Address,
+  LeadTrackingResponse 
+} from '@aacigroup/aaci_shared';
 
-function saveAddress(address: AddressCapture): Promise<void> {
-  return database.addresses.create(address);
+// Use types in your application
+function processLead(lead: TrackLeadParams): Promise<LeadTrackingResponse> {
+  return tracker.trackLeadAndAddress(lead);
 }
 ```
 
-## Features
-
-- **Flexible Tracking** - Track leads, addresses, or both in any combination
-- **Smart Data Persistence** - Automatically saves and merges data across form steps
-- **Attribution Tracking** - Captures and persists marketing attribution (gclid, fbclid, UTM)
-- **Session Tracking** - Comprehensive browser and user session data
-- **Production Detection** - Domain-based environment detection
-- **TypeScript Support** - Full type definitions for all data structures
-- **Framework Agnostic** - Works with React, Vue, vanilla JS, or any framework
-
 ## License
 
 ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aacigroup/aaci_shared",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "Shared tracking utilities for AACI Group projects with React Context support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",