@rachelallyson/planning-center-people-ts 2.9.1 → 2.11.0

package/CHANGELOG.md

@@ -5,6 +5,66 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.11.0] - 2025-01-15
+
+### ✨ **New Features**
+
+- **🔄 Automatic Retry Logic for Contact Verification**: Added built-in retry logic to prevent duplicate person creation
+  - Automatically retries when searching for existing persons with email/phone
+  - Handles PCO contact verification delays (30-90+ seconds)
+  - Uses exponential backoff (10s → 15s → 22.5s → 33.75s → 50.6s)
+  - Configurable retry behavior via `retryConfig` option
+  - Default: 5 retries, 120 seconds max wait time
+  - Logs retry attempts with `[PERSON_MATCH]` prefix for debugging
+  - Prevents duplicate person creation when PCO takes time to verify/index contacts
+
+### 🔧 **Improvements**
+
+- **Duplicate Prevention**: `findOrCreate` now automatically handles PCO contact verification delays
+  - Retry logic activates automatically when `createIfNotFound: false` and email/phone are provided
+  - No manual retry code needed - library handles it automatically
+  - Prevents race conditions where duplicate persons are created
+
+### 📚 **Documentation**
+
+- Added `RETRY_LOGIC_FIX.md` - Detailed explanation of the retry logic fix
+- Added `USING_RETRY_LOGIC.md` - Guide for using retry logic in your app
+- Added `MIGRATION_GUIDE_FOR_YOUR_APP.md` - Migration guide to simplify existing code
+- Added `TEST_FAILURE_ANALYSIS.md` - Troubleshooting guide for test failures
+
+### 🧪 **Testing**
+
+- Added comprehensive integration tests for retry logic
+- Tests verify retry logic prevents duplicate person creation
+- Tests demonstrate bug scenario and fix
+
+## [2.10.0] - 2025-01-15
+
+### ✨ **New Features**
+
+- **📧 Email Normalization & Validation**: Added email normalization and format validation to improve search accuracy
+  - New `normalizeEmail()` helper function (lowercase and trim)
+  - Email is now normalized before search to improve PCO API search results
+  - Email format validation prevents wasted API calls on invalid emails
+- **📱 Phone Normalization**: Added phone normalization to improve search accuracy
+  - New `normalizePhone()` helper function (normalizes to `+1XXXXXXXXXX` format)
+  - Phone numbers are now normalized before search to improve PCO API search results
+- **✅ First Name Validation**: Added firstName validation in person creation
+  - Validates firstName is required before attempting person creation
+  - Provides clearer error messages: "First name is required to create a person"
+  - Fails fast instead of waiting for API error response
+
+### 🔧 **Improvements**
+
+- **Normalization Consistency**: Refactored normalization logic into reusable helper functions
+  - All email/phone normalization now uses consistent helper functions
+  - Updated both `matcher.ts` and `scoring.ts` to use shared normalization functions
+  - Removed duplicate inline normalization code
+
+### 📦 **Exports**
+
+- Exported `normalizeEmail` and `normalizePhone` helper functions from main package index for library users
+
 ## [2.9.1] - 2025-01-14
 
 ### 🐛 **Bug Fixes**

package/dist/helpers.d.ts

@@ -44,10 +44,21 @@ export declare function calculateBirthYearFromAge(age: number): number;
  * Validate email format
  */
 export declare function isValidEmail(email: string): boolean;
+/**
+ * Normalize email address (lowercase and trim)
+ */
+export declare function normalizeEmail(email: string): string;
 /**
  * Validate phone number format (basic validation)
  */
 export declare function isValidPhone(phone: string): boolean;
+/**
+ * Normalize phone number to +1XXXXXXXXXX format
+ * - 10 digits: adds +1 prefix
+ * - 11 digits starting with 1: adds + prefix
+ * - Other lengths: adds + prefix to all digits
+ */
+export declare function normalizePhone(phone: string): string;
 /**
  * Format person name from attributes
  */

package/dist/helpers.js

@@ -8,7 +8,9 @@ exports.isChild = isChild;
 exports.matchesAgeCriteria = matchesAgeCriteria;
 exports.calculateBirthYearFromAge = calculateBirthYearFromAge;
 exports.isValidEmail = isValidEmail;
+exports.normalizeEmail = normalizeEmail;
 exports.isValidPhone = isValidPhone;
+exports.normalizePhone = normalizePhone;
 exports.formatPersonName = formatPersonName;
 exports.formatDate = formatDate;
 exports.validatePersonData = validatePersonData;
@@ -137,6 +139,12 @@ function isValidEmail(email) {
     const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
     return emailRegex.test(email);
 }
+/**
+ * Normalize email address (lowercase and trim)
+ */
+function normalizeEmail(email) {
+    return email.toLowerCase().trim();
+}
 /**
  * Validate phone number format (basic validation)
  */
@@ -144,6 +152,22 @@ function isValidPhone(phone) {
     const phoneRegex = /^[\+]?[1-9][\d]{6,14}$/;
     return phoneRegex.test(phone.replace(/[\s\-\(\)]/g, ''));
 }
+/**
+ * Normalize phone number to +1XXXXXXXXXX format
+ * - 10 digits: adds +1 prefix
+ * - 11 digits starting with 1: adds + prefix
+ * - Other lengths: adds + prefix to all digits
+ */
+function normalizePhone(phone) {
+    const digits = phone.replace(/\D/g, '');
+    if (digits.length === 10) {
+        return `+1${digits}`;
+    }
+    if (digits.length === 11 && digits.startsWith('1')) {
+        return `+${digits}`;
+    }
+    return `+${digits}`;
+}
 /**
  * Format person name from attributes
  */

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export type { ErrorContext } from '@rachelallyson/planning-center-base-ts';
 export { ErrorCategory, ErrorSeverity, handleNetworkError, handleTimeoutError, handleValidationError, PcoError, retryWithBackoff, shouldNotRetry, withErrorBoundary, } from '@rachelallyson/planning-center-base-ts';
 export { createFieldDefinition, createFieldOption, createPerson, createPersonAddress, createPersonEmail, createPersonFieldData, createPersonPhoneNumber, createPersonSocialProfile, createWorkflowCard, createWorkflowCardNote, deleteFieldDefinition, deletePerson, deletePersonFieldData, deleteSocialProfile, getFieldDefinitions, getFieldOptions, getHousehold, getHouseholds, getTabs, getListById, getListCategories, getLists, getNote, getNoteCategories, getNotes, getOrganization, getPeople, getPerson, getPersonAddresses, getPersonEmails, getPersonFieldData, getPersonPhoneNumbers, getPersonSocialProfiles, getWorkflow, getWorkflowCardNotes, getWorkflowCards, getWorkflows, updatePerson, updatePersonAddress, } from './people';
 export { attemptRecovery, CircuitBreaker, classifyError, createErrorReport, DEFAULT_RETRY_CONFIG, executeBulkOperation, retryWithExponentialBackoff, TIMEOUT_CONFIG, withTimeout, } from './error-scenarios';
-export { buildQueryParams, calculateAge, createPersonWithContact, createWorkflowCardWithNote, exportAllPeopleData, extractFileUrl, formatDate, formatPersonName, getCompletePersonProfile, getFileExtension, getFilename, getListsWithCategories, getOrganizationInfo, getPeopleByHousehold, getPersonWorkflowCardsWithNotes, getPrimaryContact, isFileUpload, isFileUrl, isValidEmail, isValidPhone, processFileValue, searchPeople, validatePersonData, } from './helpers';
+export { buildQueryParams, calculateAge, createPersonWithContact, createWorkflowCardWithNote, exportAllPeopleData, extractFileUrl, formatDate, formatPersonName, getCompletePersonProfile, getFileExtension, getFilename, getListsWithCategories, getOrganizationInfo, getPeopleByHousehold, getPersonWorkflowCardsWithNotes, getPrimaryContact, isFileUpload, isFileUrl, isValidEmail, isValidPhone, normalizeEmail, normalizePhone, processFileValue, searchPeople, validatePersonData, } from './helpers';
 export { AdaptiveRateLimiter, ApiCache, batchFetchPersonDetails, fetchAllPages, getCachedPeople, monitorPerformance, PerformanceMonitor, processInBatches, processLargeDataset, streamPeopleData, } from './performance';
 export { MockPcoClient, MockResponseBuilder, RequestRecorder, createMockClient, createRecordingClient, createTestClient, createErrorMockClient, createSlowMockClient, } from './testing';
 export type { MockClientConfig, RecordingConfig } from './testing';

package/dist/index.js

@@ -16,8 +16,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNotes = exports.getNoteCategories = exports.getNote = exports.getLists = exports.getListCategories = exports.getListById = exports.getTabs = exports.getHouseholds = exports.getHousehold = exports.getFieldOptions = exports.getFieldDefinitions = exports.deleteSocialProfile = exports.deletePersonFieldData = exports.deletePerson = exports.deleteFieldDefinition = exports.createWorkflowCardNote = exports.createWorkflowCard = exports.createPersonSocialProfile = exports.createPersonPhoneNumber = exports.createPersonFieldData = exports.createPersonEmail = exports.createPersonAddress = exports.createPerson = exports.createFieldOption = exports.createFieldDefinition = exports.withErrorBoundary = exports.shouldNotRetry = exports.retryWithBackoff = exports.PcoError = exports.handleValidationError = exports.handleTimeoutError = exports.handleNetworkError = exports.ErrorSeverity = exports.ErrorCategory = exports.PcoRateLimiter = exports.PcoApiError = exports.updateClientTokens = exports.refreshAccessToken = exports.hasRefreshTokenCapability = exports.attemptTokenRefresh = exports.post = exports.patch = exports.getSingle = exports.getRateLimitInfo = exports.getList = exports.getAllPages = exports.del = exports.createPcoClient = exports.PcoClientManager = exports.PcoClient = void 0;
-exports.fetchAllPages = exports.batchFetchPersonDetails = exports.ApiCache = exports.AdaptiveRateLimiter = exports.validatePersonData = exports.searchPeople = exports.processFileValue = exports.isValidPhone = exports.isValidEmail = exports.isFileUrl = exports.isFileUpload = exports.getPrimaryContact = exports.getPersonWorkflowCardsWithNotes = exports.getPeopleByHousehold = exports.getOrganizationInfo = exports.getListsWithCategories = exports.getFilename = exports.getFileExtension = exports.getCompletePersonProfile = exports.formatPersonName = exports.formatDate = exports.extractFileUrl = exports.exportAllPeopleData = exports.createWorkflowCardWithNote = exports.createPersonWithContact = exports.calculateAge = exports.buildQueryParams = exports.withTimeout = exports.TIMEOUT_CONFIG = exports.retryWithExponentialBackoff = exports.executeBulkOperation = exports.DEFAULT_RETRY_CONFIG = exports.createErrorReport = exports.classifyError = exports.CircuitBreaker = exports.attemptRecovery = exports.updatePersonAddress = exports.updatePerson = exports.getWorkflows = exports.getWorkflowCards = exports.getWorkflowCardNotes = exports.getWorkflow = exports.getPersonSocialProfiles = exports.getPersonPhoneNumbers = exports.getPersonFieldData = exports.getPersonEmails = exports.getPersonAddresses = exports.getPerson = exports.getPeople = exports.getOrganization = void 0;
-exports.createSlowMockClient = exports.createErrorMockClient = exports.createTestClient = exports.createRecordingClient = exports.createMockClient = exports.RequestRecorder = exports.MockResponseBuilder = exports.MockPcoClient = exports.streamPeopleData = exports.processLargeDataset = exports.processInBatches = exports.PerformanceMonitor = exports.monitorPerformance = exports.getCachedPeople = void 0;
+exports.ApiCache = exports.AdaptiveRateLimiter = exports.validatePersonData = exports.searchPeople = exports.processFileValue = exports.normalizePhone = exports.normalizeEmail = exports.isValidPhone = exports.isValidEmail = exports.isFileUrl = exports.isFileUpload = exports.getPrimaryContact = exports.getPersonWorkflowCardsWithNotes = exports.getPeopleByHousehold = exports.getOrganizationInfo = exports.getListsWithCategories = exports.getFilename = exports.getFileExtension = exports.getCompletePersonProfile = exports.formatPersonName = exports.formatDate = exports.extractFileUrl = exports.exportAllPeopleData = exports.createWorkflowCardWithNote = exports.createPersonWithContact = exports.calculateAge = exports.buildQueryParams = exports.withTimeout = exports.TIMEOUT_CONFIG = exports.retryWithExponentialBackoff = exports.executeBulkOperation = exports.DEFAULT_RETRY_CONFIG = exports.createErrorReport = exports.classifyError = exports.CircuitBreaker = exports.attemptRecovery = exports.updatePersonAddress = exports.updatePerson = exports.getWorkflows = exports.getWorkflowCards = exports.getWorkflowCardNotes = exports.getWorkflow = exports.getPersonSocialProfiles = exports.getPersonPhoneNumbers = exports.getPersonFieldData = exports.getPersonEmails = exports.getPersonAddresses = exports.getPerson = exports.getPeople = exports.getOrganization = void 0;
+exports.createSlowMockClient = exports.createErrorMockClient = exports.createTestClient = exports.createRecordingClient = exports.createMockClient = exports.RequestRecorder = exports.MockResponseBuilder = exports.MockPcoClient = exports.streamPeopleData = exports.processLargeDataset = exports.processInBatches = exports.PerformanceMonitor = exports.monitorPerformance = exports.getCachedPeople = exports.fetchAllPages = exports.batchFetchPersonDetails = void 0;
 // Main client class
 var client_1 = require("./client");
 Object.defineProperty(exports, "PcoClient", { enumerable: true, get: function () { return client_1.PcoClient; } });
@@ -130,6 +130,8 @@ Object.defineProperty(exports, "isFileUpload", { enumerable: true, get: function
 Object.defineProperty(exports, "isFileUrl", { enumerable: true, get: function () { return helpers_1.isFileUrl; } });
 Object.defineProperty(exports, "isValidEmail", { enumerable: true, get: function () { return helpers_1.isValidEmail; } });
 Object.defineProperty(exports, "isValidPhone", { enumerable: true, get: function () { return helpers_1.isValidPhone; } });
+Object.defineProperty(exports, "normalizeEmail", { enumerable: true, get: function () { return helpers_1.normalizeEmail; } });
+Object.defineProperty(exports, "normalizePhone", { enumerable: true, get: function () { return helpers_1.normalizePhone; } });
 Object.defineProperty(exports, "processFileValue", { enumerable: true, get: function () { return helpers_1.processFileValue; } });
 Object.defineProperty(exports, "searchPeople", { enumerable: true, get: function () { return helpers_1.searchPeople; } });
 Object.defineProperty(exports, "validatePersonData", { enumerable: true, get: function () { return helpers_1.validatePersonData; } });

package/dist/matching/matcher.d.ts

@@ -22,11 +22,20 @@ export declare class PersonMatcher {
      * - Verifies email/phone matches by checking actual contact information
      * - Only uses name matching when appropriate (multiple people share contact info, or no contact info provided)
      * - Can automatically add missing contact information when a match is found (if addMissingContactInfo is true)
+     * - Retries with exponential backoff when contacts may not be verified yet (PCO takes 30-90+ seconds)
      *
      * @param options - Matching options
      * @param options.addMissingContactInfo - If true, automatically adds missing email/phone to matched person's profile
+     * @param options.retryConfig - Configuration for retry logic to handle PCO contact verification delays
      */
     findOrCreate(options: PersonMatchOptions): Promise<PersonResource>;
+    /**
+     * Find or create with retry logic to handle PCO contact verification delays
+     *
+     * PCO takes 30-90+ seconds to verify/index contacts after a person is created.
+     * This method retries with exponential backoff to give PCO time to process contacts.
+     */
+    private findOrCreateWithRetry;
     /**
      * Find the best match for a person
      */

package/dist/matching/matcher.js

@@ -20,12 +20,26 @@ class PersonMatcher {
      * - Verifies email/phone matches by checking actual contact information
      * - Only uses name matching when appropriate (multiple people share contact info, or no contact info provided)
      * - Can automatically add missing contact information when a match is found (if addMissingContactInfo is true)
+     * - Retries with exponential backoff when contacts may not be verified yet (PCO takes 30-90+ seconds)
      *
      * @param options - Matching options
      * @param options.addMissingContactInfo - If true, automatically adds missing email/phone to matched person's profile
+     * @param options.retryConfig - Configuration for retry logic to handle PCO contact verification delays
      */
     async findOrCreate(options) {
-        const { createIfNotFound = true, matchStrategy = 'fuzzy', addMissingContactInfo = false, ...searchOptions } = options;
+        const { createIfNotFound = true, matchStrategy = 'fuzzy', addMissingContactInfo = false, retryConfig, ...searchOptions } = options;
+        // Determine if retry logic should be enabled
+        // Retry is useful when:
+        // 1. We have email/phone (these need verification)
+        // 2. createIfNotFound is false (we're trying to find existing, not create new)
+        // 3. retryConfig.enabled is not explicitly false
+        const hasContactInfo = !!(options.email || options.phone);
+        const shouldRetry = hasContactInfo &&
+            !createIfNotFound &&
+            (retryConfig?.enabled !== false);
+        if (shouldRetry) {
+            return this.findOrCreateWithRetry(options);
+        }
         // Try to find existing person
         const match = await this.findMatch({ ...searchOptions, matchStrategy });
         if (match) {
@@ -42,6 +56,79 @@ class PersonMatcher {
         }
         throw new Error(`No matching person found and creation is disabled`);
     }
+    /**
+     * Find or create with retry logic to handle PCO contact verification delays
+     *
+     * PCO takes 30-90+ seconds to verify/index contacts after a person is created.
+     * This method retries with exponential backoff to give PCO time to process contacts.
+     */
+    async findOrCreateWithRetry(options) {
+        const { createIfNotFound = false, matchStrategy = 'fuzzy', addMissingContactInfo = false, retryConfig, ...searchOptions } = options;
+        // Default retry configuration
+        const maxRetries = retryConfig?.maxRetries ?? 5;
+        const maxWaitTime = retryConfig?.maxWaitTime ?? 120000; // 120 seconds
+        const initialDelay = retryConfig?.initialDelay ?? 10000; // 10 seconds
+        const backoffMultiplier = retryConfig?.backoffMultiplier ?? 1.5;
+        let totalWaitTime = 0;
+        let lastError = null;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                // Try to find existing person
+                const match = await this.findMatch({ ...searchOptions, matchStrategy });
+                if (match) {
+                    const person = match.person;
+                    // Add missing contact information if requested
+                    if (addMissingContactInfo) {
+                        await this.addMissingContactInfo(person, options);
+                    }
+                    // Log success if we had to retry
+                    if (attempt > 1) {
+                        console.log(`[PERSON_MATCH] Found person after ${attempt} attempts (waited ${totalWaitTime}ms)`, {
+                            personId: person.id,
+                            attempt,
+                            totalWaitTime
+                        });
+                    }
+                    return person;
+                }
+                // No match found - this might be because contacts aren't verified yet
+                lastError = new Error(`No matching person found and creation is disabled`);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+            }
+            // Don't retry on the last attempt
+            if (attempt === maxRetries) {
+                break;
+            }
+            // Calculate delay with exponential backoff
+            const delay = Math.min(initialDelay * Math.pow(backoffMultiplier, attempt - 1), maxWaitTime - totalWaitTime // Don't exceed maxWaitTime
+            );
+            // Check if we've exceeded max wait time
+            if (totalWaitTime + delay > maxWaitTime) {
+                console.warn(`[PERSON_MATCH] Max wait time (${maxWaitTime}ms) exceeded, stopping retries`, {
+                    attempt,
+                    totalWaitTime,
+                    remainingDelay: maxWaitTime - totalWaitTime
+                });
+                break;
+            }
+            totalWaitTime += delay;
+            // Log retry attempt
+            console.log(`[PERSON_MATCH] Attempt ${attempt} failed, retrying in ${delay}ms`, {
+                attempt,
+                delay,
+                totalWaitTime,
+                errorMessage: lastError?.message,
+                maxRetries,
+                maxWaitTime
+            });
+            // Wait before retrying
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+        // All retries exhausted - throw error
+        throw lastError || new Error(`No matching person found after ${maxRetries} attempts (waited ${totalWaitTime}ms) and creation is disabled`);
+    }
     /**
      * Find the best match for a person
      */
@@ -50,20 +137,30 @@ class PersonMatcher {
         // Step 1: Try email/phone search first
         const emailPhoneMatches = [];
         const nameOnlyMatches = [];
-        // Search by email
+        // Search by email (with normalization and validation)
         if (email) {
-            try {
-                const emailResults = await this.peopleModule.search({ email });
-                emailPhoneMatches.push(...emailResults.data);
+            // Validate email format to avoid wasted API calls
+            if (!(0, helpers_1.isValidEmail)(email)) {
+                console.warn('Invalid email format, skipping email search:', email);
             }
-            catch (error) {
-                console.warn('Email search failed:', error);
+            else {
+                try {
+                    // Normalize email before search to improve PCO search results
+                    const normalizedEmail = (0, helpers_1.normalizeEmail)(email);
+                    const emailResults = await this.peopleModule.search({ email: normalizedEmail });
+                    emailPhoneMatches.push(...emailResults.data);
+                }
+                catch (error) {
+                    console.warn('Email search failed:', error);
+                }
             }
         }
-        // Search by phone
+        // Search by phone (with normalization)
         if (phone) {
             try {
-                const phoneResults = await this.peopleModule.search({ phone });
+                // Normalize phone before search to improve PCO search results
+                const normalizedPhone = (0, helpers_1.normalizePhone)(phone);
+                const phoneResults = await this.peopleModule.search({ phone: normalizedPhone });
                 emailPhoneMatches.push(...phoneResults.data);
             }
             catch (error) {
@@ -203,8 +300,8 @@ class PersonMatcher {
     async verifyEmailMatch(person, email) {
         try {
             const personEmails = await this.peopleModule.getEmails(person.id);
-            const normalizedSearchEmail = email.toLowerCase().trim();
-            const emails = personEmails.data?.map(e => e.attributes?.address?.toLowerCase().trim()).filter(Boolean) || [];
+            const normalizedSearchEmail = (0, helpers_1.normalizeEmail)(email);
+            const emails = personEmails.data?.map(e => (0, helpers_1.normalizeEmail)(e.attributes?.address || '')).filter(Boolean) || [];
             return emails.includes(normalizedSearchEmail);
         }
         catch {
@@ -217,14 +314,8 @@ class PersonMatcher {
     async verifyPhoneMatch(person, phone) {
         try {
             const personPhones = await this.peopleModule.getPhoneNumbers(person.id);
-            const normalizePhone = (num) => {
-                const digits = num.replace(/\D/g, '');
-                return digits.length === 10 ? `+1${digits}` :
-                    digits.length === 11 && digits.startsWith('1') ? `+${digits}` :
-                        `+${digits}`;
-            };
-            const normalizedSearchPhone = normalizePhone(phone);
-            const phones = personPhones.data?.map(p => normalizePhone(p.attributes?.number || '')).filter(Boolean) || [];
+            const normalizedSearchPhone = (0, helpers_1.normalizePhone)(phone);
+            const phones = personPhones.data?.map(p => (0, helpers_1.normalizePhone)(p.attributes?.number || '')).filter(Boolean) || [];
             return phones.includes(normalizedSearchPhone);
         }
         catch {
@@ -294,6 +385,10 @@ class PersonMatcher {
      * Create a new person
      */
     async createPerson(options) {
+        // Validate firstName is required for person creation
+        if (!options.firstName?.trim()) {
+            throw new Error('First name is required to create a person');
+        }
         // Create basic person data (only name fields)
         const personData = {};
         if (options.firstName)

package/dist/matching/scoring.js

@@ -98,9 +98,9 @@ class MatchScorer {
     async scoreEmailMatch(person, email) {
         try {
             const personEmails = await this.peopleModule.getEmails(person.id);
-            const normalizedSearchEmail = email.toLowerCase().trim();
+            const normalizedSearchEmail = (0, helpers_1.normalizeEmail)(email);
             // Check if any of the person's emails match
-            const emails = personEmails.data?.map(e => e.attributes?.address?.toLowerCase().trim()).filter(Boolean) || [];
+            const emails = personEmails.data?.map(e => (0, helpers_1.normalizeEmail)(e.attributes?.address || '')).filter(Boolean) || [];
             return emails.includes(normalizedSearchEmail) ? 1.0 : 0.0;
         }
         catch (error) {
@@ -114,15 +114,8 @@ class MatchScorer {
     async scorePhoneMatch(person, phone) {
         try {
             const personPhones = await this.peopleModule.getPhoneNumbers(person.id);
-            // Normalize phone numbers for comparison
-            const normalizePhone = (num) => {
-                const digits = num.replace(/\D/g, '');
-                return digits.length === 10 ? `+1${digits}` :
-                    digits.length === 11 && digits.startsWith('1') ? `+${digits}` :
-                        `+${digits}`;
-            };
-            const normalizedSearchPhone = normalizePhone(phone);
-            const phones = personPhones.data?.map(p => normalizePhone(p.attributes?.number || '')).filter(Boolean) || [];
+            const normalizedSearchPhone = (0, helpers_1.normalizePhone)(phone);
+            const phones = personPhones.data?.map(p => (0, helpers_1.normalizePhone)(p.attributes?.number || '')).filter(Boolean) || [];
             return phones.includes(normalizedSearchPhone) ? 1.0 : 0.0;
         }
         catch (error) {

package/dist/modules/people.d.ts

@@ -76,6 +76,23 @@ export interface PersonMatchOptions {
     maxAge?: number;
     /** Birth year filter (exact match) */
     birthYear?: number;
+    /**
+     * Retry configuration for handling PCO contact verification delays.
+     * When a person is created, PCO needs time (30-90+ seconds) to verify/index contacts
+     * before they become searchable. This retry logic helps prevent duplicate person creation.
+     */
+    retryConfig?: {
+        /** Maximum number of retry attempts (default: 5) */
+        maxRetries?: number;
+        /** Maximum total wait time in milliseconds (default: 120000 = 120 seconds) */
+        maxWaitTime?: number;
+        /** Initial delay in milliseconds before first retry (default: 10000 = 10 seconds) */
+        initialDelay?: number;
+        /** Multiplier for exponential backoff (default: 1.5) */
+        backoffMultiplier?: number;
+        /** Whether to enable retry logic (default: true when email/phone provided and createIfNotFound: false) */
+        enabled?: boolean;
+    };
 }
 export declare class PeopleModule extends BaseModule {
     private personMatcher;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rachelallyson/planning-center-people-ts",
-    "version": "2.9.1",
+    "version": "2.11.0",
     "description": "A strictly typed TypeScript client for Planning Center Online People API with comprehensive functionality and enhanced developer experience",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",