@aacigroup/aaci_shared 2.4.0 → 2.6.0

package/README.md

@@ -15,7 +15,7 @@ npm install @aacigroup/aaci_shared
 ```javascript
 import { LeadTracker } from '@aacigroup/aaci_shared';
 
-const leadTracker = new LeadTracker({
+const tracker = new LeadTracker({
   apiUrl: 'https://your-api.com/leads',
   apiKey: 'your-api-key',
   projectName: 'MyProject',
@@ -23,27 +23,172 @@ const leadTracker = new LeadTracker({
 });
 
 // Track lead only
-await leadTracker.trackLeadAndAddress({
-  lead_type: 'signup',
+await tracker.trackLeadAndAddress({
+  lead_type: 'contact',
   email: 'user@example.com'
 });
 
 // Track address only
-await leadTracker.trackLeadAndAddress(undefined, {
+await tracker.trackLeadAndAddress(undefined, {
   full_address: '123 Main St, New York, NY 10001',
   source: 'address_check'
 });
 
 // Track both together
-await leadTracker.trackLeadAndAddress({
-  lead_type: 'contact',
+await tracker.trackLeadAndAddress({
+  lead_type: 'policy_review',
   email: 'user@example.com'
 }, {
   full_address: '123 Main St, New York, NY 10001',
+  source: 'policy_review'
+});
+```
+
+## 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);
 ```
 
+## Other Components
+
+### React Context (Optional)
+
+For React projects, you can use the provided context for easier integration:
+
+```bash
+npm install react  # Peer dependency
+```
+
+```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()}>
+      <YourApp />
+    </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.tsx - Use tracking in any component
+import { useLeadTracker, usePostHog } from '@aacigroup/aaci_shared/react';
+
+function ContactForm() {
+  const tracker = useLeadTracker();
+  const analytics = usePostHog();
+
+  const handleSubmit = async (formData) => {
+    // Track lead submission
+    await tracker.trackLeadAndAddress({
+      lead_type: 'contact',
+      email: formData.email
+    });
+
+    // Track analytics event
+    analytics.trackEvent('form_submitted', { form_type: 'contact' });
+  };
+
+  return <form onSubmit={handleSubmit}>...</form>;
+}
+```
+
+**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
+```
+
+### 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
@@ -305,7 +450,35 @@ console.log('Current domain:', env.getCurrentDomain());
 
 ## Data Types Reference
 
-### Core Data Types
+### Input Types (for tracking methods)
+
+```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)
+}
+
+// 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
+}
+```
+
+### Database Types (complete records)
 
 ```typescript
 // Complete lead record (from database)
@@ -342,15 +515,19 @@ interface AddressCapture {
   created_at: string;
   updated_at: string;
 }
+```
 
-**Common `source` values (identical to `lead_type`):**
-- `'policy_review'` - Address from policy review requests
-- `'address_check'` - Address from address verification requests
-- `'contact'` - Address from general contact form submissions
-- `'signup'` - Address from user registration/signup
-- `'consultation'` - Address from service consultation requests
-- `'quote'` - Address from price quote requests
+**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
 
+```typescript
 // Session tracking data
 interface SessionData {
   ip?: string;

package/dist/TrackingContext.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { LeadTracker, PostHog } from './index';
+interface TrackingConfig {
+    apiUrl: string;
+    apiKey: string;
+    projectName: string;
+    posthogKey: string;
+    productionDomains: string[];
+}
+export type { TrackingConfig };
+interface TrackingProviderProps {
+    children: ReactNode;
+    config: TrackingConfig;
+}
+export declare const TrackingProvider: ({ children, config }: TrackingProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const useLeadTracker: () => LeadTracker;
+export declare const usePostHog: () => PostHog;
+export declare const createTrackingConfigFromEnv: () => TrackingConfig;
+//# sourceMappingURL=TrackingContext.d.ts.map

package/dist/TrackingContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrackingContext.d.ts","sourceRoot":"","sources":["../src/TrackingContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA6B,SAAS,EAAW,MAAM,OAAO,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAS/C,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,GAAI,sBAAsB,qBAAqB,4CA4B3E,CAAC;AAEF,eAAO,MAAM,cAAc,QAAO,WAMjC,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,OAM7B,CAAC;AAGF,eAAO,MAAM,2BAA2B,QAAO,cAc9C,CAAC"}

package/dist/TrackingContext.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTrackingConfigFromEnv = exports.usePostHog = exports.useLeadTracker = exports.TrackingProvider = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const index_1 = require("./index");
+const TrackingContext = (0, react_1.createContext)(undefined);
+const TrackingProvider = ({ children, config }) => {
+    const trackers = (0, react_1.useMemo)(() => {
+        const leadTracker = new index_1.LeadTracker({
+            apiUrl: config.apiUrl,
+            apiKey: config.apiKey,
+            projectName: config.projectName,
+            productionDomains: config.productionDomains,
+        });
+        const posthog = new index_1.PostHog({
+            apiKey: config.posthogKey,
+            projectName: config.projectName,
+            productionDomains: config.productionDomains,
+        });
+        posthog.init();
+        return { leadTracker, posthog };
+    }, [config]);
+    return ((0, jsx_runtime_1.jsx)(TrackingContext.Provider, { value: trackers, children: children }));
+};
+exports.TrackingProvider = TrackingProvider;
+const useLeadTracker = () => {
+    const context = (0, react_1.useContext)(TrackingContext);
+    if (!context) {
+        throw new Error('useLeadTracker must be used within TrackingProvider');
+    }
+    return context.leadTracker;
+};
+exports.useLeadTracker = useLeadTracker;
+const usePostHog = () => {
+    const context = (0, react_1.useContext)(TrackingContext);
+    if (!context) {
+        throw new Error('usePostHog must be used within TrackingProvider');
+    }
+    return context.posthog;
+};
+exports.usePostHog = usePostHog;
+const createTrackingConfigFromEnv = () => {
+    var _a;
+    if (typeof window !== 'undefined' && 'import' in window && 'meta' in window.import) {
+        const env = window.import.meta.env;
+        return {
+            apiUrl: env.VITE_LEAD_CAPTURE_API_URL,
+            apiKey: env.VITE_LEAD_CAPTURE_API_KEY,
+            projectName: env.VITE_PROJECT_NAME,
+            posthogKey: env.VITE_POSTHOG_KEY,
+            productionDomains: ((_a = env.VITE_PRODUCTION_DOMAINS) === null || _a === void 0 ? void 0 : _a.split(',').map((d) => d.trim()).filter(Boolean)) || [],
+        };
+    }
+    throw new Error('Environment variables not available. Please provide config manually.');
+};
+exports.createTrackingConfigFromEnv = createTrackingConfigFromEnv;
+//# sourceMappingURL=TrackingContext.js.map

package/dist/TrackingContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrackingContext.js","sourceRoot":"","sources":["../src/TrackingContext.tsx"],"names":[],"mappings":";;;;AAAA,iCAAsE;AACtE,mCAA+C;AAO/C,MAAM,eAAe,GAAG,IAAA,qBAAa,EAAkC,SAAS,CAAC,CAAC;AAiB3E,MAAM,gBAAgB,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAyB,EAAE,EAAE;IAC9E,MAAM,QAAQ,GAAG,IAAA,eAAO,EAAC,GAAG,EAAE;QAE5B,MAAM,WAAW,GAAG,IAAI,mBAAW,CAAC;YAClC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;SAC5C,CAAC,CAAC;QAGH,MAAM,OAAO,GAAG,IAAI,eAAO,CAAC;YAC1B,MAAM,EAAE,MAAM,CAAC,UAAU;YACzB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;SAC5C,CAAC,CAAC;QAGH,OAAO,CAAC,IAAI,EAAE,CAAC;QAEf,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IAClC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,OAAO,CACL,uBAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,QAAQ,YACtC,QAAQ,GACgB,CAC5B,CAAC;AACJ,CAAC,CAAC;AA5BW,QAAA,gBAAgB,oBA4B3B;AAEK,MAAM,cAAc,GAAG,GAAgB,EAAE;IAC9C,MAAM,OAAO,GAAG,IAAA,kBAAU,EAAC,eAAe,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,CAAC;AAC7B,CAAC,CAAC;AANW,QAAA,cAAc,kBAMzB;AAEK,MAAM,UAAU,GAAG,GAAY,EAAE;IACtC,MAAM,OAAO,GAAG,IAAA,kBAAU,EAAC,eAAe,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC;AACzB,CAAC,CAAC;AANW,QAAA,UAAU,cAMrB;AAGK,MAAM,2BAA2B,GAAG,GAAmB,EAAE;;IAE9D,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,QAAQ,IAAI,MAAM,IAAI,MAAM,IAAK,MAAc,CAAC,MAAM,EAAE,CAAC;QAC5F,MAAM,GAAG,GAAI,MAAc,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QAC5C,OAAO;YACL,MAAM,EAAE,GAAG,CAAC,yBAAyB;YACrC,MAAM,EAAE,GAAG,CAAC,yBAAyB;YACrC,WAAW,EAAE,GAAG,CAAC,iBAAiB;YAClC,UAAU,EAAE,GAAG,CAAC,gBAAgB;YAChC,iBAAiB,EAAE,CAAA,MAAA,GAAG,CAAC,uBAAuB,0CAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,KAAI,EAAE;SAC9G,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;AAC1F,CAAC,CAAC;AAdW,QAAA,2BAA2B,+BActC"}

package/dist/react.d.ts

@@ -0,0 +1,3 @@
+export { TrackingProvider, useLeadTracker, usePostHog, createTrackingConfigFromEnv } from './TrackingContext';
+export type { TrackingConfig } from './TrackingContext';
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,2BAA2B,EAC5B,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,cAAc,EACf,MAAM,mBAAmB,CAAC"}

package/dist/react.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTrackingConfigFromEnv = exports.usePostHog = exports.useLeadTracker = exports.TrackingProvider = void 0;
+var TrackingContext_1 = require("./TrackingContext");
+Object.defineProperty(exports, "TrackingProvider", { enumerable: true, get: function () { return TrackingContext_1.TrackingProvider; } });
+Object.defineProperty(exports, "useLeadTracker", { enumerable: true, get: function () { return TrackingContext_1.useLeadTracker; } });
+Object.defineProperty(exports, "usePostHog", { enumerable: true, get: function () { return TrackingContext_1.usePostHog; } });
+Object.defineProperty(exports, "createTrackingConfigFromEnv", { enumerable: true, get: function () { return TrackingContext_1.createTrackingConfigFromEnv; } });
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":";;;AAGA,qDAK2B;AAJzB,mHAAA,gBAAgB,OAAA;AAChB,iHAAA,cAAc,OAAA;AACd,6GAAA,UAAU,OAAA;AACV,8HAAA,2BAA2B,OAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aacigroup/aaci_shared",
-  "version": "2.4.0",
-  "description": "Shared tracking utilities for AACI Group projects",
+  "version": "2.6.0",
+  "description": "Shared tracking utilities for AACI Group projects with React Context support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -22,7 +22,10 @@
     "posthog",
     "gtm",
     "lead-capture",
-    "error-tracking"
+    "error-tracking",
+    "react",
+    "context",
+    "hooks"
   ],
   "author": "AACI Group",
   "license": "ISC",
@@ -32,8 +35,18 @@
   },
   "homepage": "https://github.com/AACI-Group/aaci_shared#readme",
   "devDependencies": {
+    "@types/react": "^19.2.0",
+    "react": "^19.2.0",
     "typescript": "^5.9.3"
   },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -48,6 +61,11 @@
       "require": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./react": {
+      "import": "./dist/react.js",
+      "require": "./dist/react.js",
+      "types": "./dist/react.d.ts"
+    },
     "./track/*": {
       "import": "./dist/track/*.js",
       "require": "./dist/track/*.js",