@rachelallyson/planning-center-people-ts 2.12.2 → 2.14.0

package/CHANGELOG.md

@@ -5,6 +5,79 @@ 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.14.0] - 2026-01-21
+
+### ✨ **New Features**
+
+- **🔍 Multi-Step Search Strategy**: New `searchStrategy: 'multi-step'` option for maximum matching success
+  - Tries multiple matching approaches in order until a match is found
+  - Strategy order: fuzzy+age → fuzzy → exact+age → exact
+  - Handles name variations and age preference filtering automatically
+  - Significantly reduces duplicate person creation
+
+- **📛 Name-Based Search Fallback**: New `fallbackToNameSearch` option with contact validation
+  - Falls back to name search when email/phone search fails
+  - Validates contact info to prevent wrong-person matches (e.g., two "John Smith"s)
+  - Configurable validation: `contactValidation: 'strict' | 'domain' | 'similarity'`
+
+- **⚡ Multi-Phase Retry Configurations**: New `retryConfigs` option for phase-specific retry control
+  - `initial`: Quick search phase (default: 30s max wait, 3 retries)
+  - `aggressive`: Final search before create (default: 60s max wait, 6 retries)
+  - Prevents duplicates when PCO hasn't indexed contacts yet (15-30 min delay)
+
+- **✅ Person ID Verification**: New `client.people.verifyPersonExists()` method
+  - Verifies a person exists in PCO with configurable timeout
+  - Handles merged/deleted persons gracefully (returns false for 404)
+  - Useful for validating cached person IDs before use
+
+- **🔐 Trust-Based Caching Helpers**: New utilities for smart person ID caching
+  - `calculateTrust(createdAt, trustWindow)`: Determines if cached personId can be trusted
+  - `DEFAULT_TRUST_WINDOW`: 1-hour default trust window constant
+  - Skip verification for fresh personIds to avoid race conditions
+
+- **📧 Contact Validation Helpers**: New utilities for contact info matching
+  - `emailDomainsMatch(email1, email2)`: Handles aliases (gmail/googlemail) and typos
+  - `phoneNumbersSimilar(phone1, phone2)`: Handles format variations and country codes
+  - `validateContactSimilarity()`: Validates contact info for name-based matches
+  - `extractEmailDomain()`: Extracts domain from email address
+
+### 🔧 **Improvements**
+
+- **Retry Config Refactoring**: Extracted `RetryConfig` interface for reusability
+- **Better Logging**: Multi-step search logs which strategy found the match
+- **Aggressive Final Search**: When `retryConfigs.aggressive` is set, performs final search before creating
+
+### 📚 **Documentation**
+
+- Updated README_V2.md with examples for all new features
+- Added code examples for multi-step search, contact validation, and trust calculation
+
+### 🧪 **Testing**
+
+- Added `tests/helpers/contact-validation.test.ts` - Contact validation helper tests
+- Added `tests/helpers/trust-calculation.test.ts` - Trust calculation tests
+- Added `tests/matching/multi-step.test.ts` - Multi-step search strategy tests
+- Added `tests/modules/people-verify.test.ts` - Person verification tests
+
+### 📦 **Exports**
+
+New exports from the package:
+
+- `emailDomainsMatch`, `extractEmailDomain`, `phoneNumbersSimilar`, `validateContactSimilarity`
+- `calculateTrust`, `DEFAULT_TRUST_WINDOW`, `TrustResult` (type)
+- `RetryConfig` (type), `PersonMatchOptions` (type)
+- `DEFAULT_INITIAL_RETRY_CONFIG`, `DEFAULT_AGGRESSIVE_RETRY_CONFIG`
+
+## [2.13.0] - 2026-01-20
+
+### ✨ **New Features**
+
+- **🎯 Lenient Age Preference Filtering**: Added `agePreferenceLenient` option for flexible age-based filtering
+  - When `agePreferenceLenient: true`, age preferences only filter profiles that have birthdates
+  - Profiles without birthdates are included regardless of `agePreference` setting
+  - Prevents false negatives when searching for existing people with incomplete age data
+  - Backward compatible - default behavior remains strict filtering (only `agePreference: 'any'` includes profiles without birthdates)
+
 ## [2.12.2] - 2026-01-20
 
 ### ✨ **New Features**

package/dist/helpers.d.ts

@@ -35,6 +35,7 @@ export declare function matchesAgeCriteria(birthdate: string | undefined, criter
     minAge?: number;
     maxAge?: number;
     birthYear?: number;
+    agePreferenceLenient?: boolean;
 }): boolean;
 /**
  * Calculate birth year from age
@@ -59,6 +60,90 @@ export declare function isValidPhone(phone: string): boolean;
  * - Other lengths: adds + prefix to all digits
  */
 export declare function normalizePhone(phone: string): string;
+/**
+ * Extract domain from email address
+ */
+export declare function extractEmailDomain(email: string): string;
+/**
+ * Check if two email domains match or are similar
+ * Handles:
+ * - Exact domain matches
+ * - Common aliases (gmail.com vs googlemail.com)
+ * - Prefix matching for similar domains (first 3+ characters)
+ *
+ * @param email1 - First email address
+ * @param email2 - Second email address
+ * @returns True if domains match or are similar
+ */
+export declare function emailDomainsMatch(email1: string, email2: string): boolean;
+/**
+ * Check if two phone numbers are similar
+ * Handles:
+ * - Different formats (+1, 1, or just 10 digits)
+ * - Country code variations
+ *
+ * @param phone1 - First phone number
+ * @param phone2 - Second phone number
+ * @returns True if phone numbers are similar
+ */
+export declare function phoneNumbersSimilar(phone1: string, phone2: string): boolean;
+/**
+ * Validate contact info similarity for name-based matches
+ *
+ * This is useful when falling back to name-based search to ensure
+ * we don't match the wrong person with the same name.
+ *
+ * @param searchEmail - Email being searched for
+ * @param searchPhone - Phone being searched for
+ * @param personEmails - Array of email addresses from the person's profile
+ * @param personPhones - Array of phone numbers from the person's profile
+ * @returns Object with match results and overall validity
+ */
+export declare function validateContactSimilarity(searchEmail: string | undefined, searchPhone: string | undefined, personEmails: string[], personPhones: string[]): {
+    emailMatch: boolean;
+    phoneMatch: boolean;
+    isValid: boolean;
+};
+/**
+ * Default trust window for person IDs (1 hour in milliseconds)
+ * If a personId was saved within this time, it can be trusted without verification
+ */
+export declare const DEFAULT_TRUST_WINDOW: number;
+/**
+ * Result of trust calculation for a person ID
+ */
+export interface TrustResult {
+    /** Whether the person ID should be trusted without verification */
+    shouldTrust: boolean;
+    /** Age of the person ID in milliseconds (null if no timestamp) */
+    age: number | null;
+    /** Human-readable reason for the trust decision */
+    reason: string;
+}
+/**
+ * Calculate whether a person ID can be trusted based on when it was created/verified
+ *
+ * This is useful for caching person IDs to avoid unnecessary API calls.
+ * PCO takes 15-30 minutes to index new contacts, so recently created person IDs
+ * should be trusted without re-verification to avoid race conditions.
+ *
+ * @param createdAt - ISO timestamp when the person ID was created/saved
+ * @param trustWindow - Trust window in milliseconds (default: 1 hour)
+ * @returns Object with trust decision, age, and reason
+ *
+ * @example
+ * ```typescript
+ * const trust = calculateTrust(pcoInfo.personIdCreatedAt);
+ * if (trust.shouldTrust) {
+ *   // Use cached personId without verification
+ *   return cachedPersonId;
+ * } else {
+ *   // Verify personId still exists in PCO
+ *   await client.people.getById(cachedPersonId);
+ * }
+ * ```
+ */
+export declare function calculateTrust(createdAt: string | undefined, trustWindow?: number): TrustResult;
 /**
  * Format person name from attributes
  */

package/dist/helpers.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TRUST_WINDOW = void 0;
 exports.buildQueryParams = buildQueryParams;
 exports.calculateAge = calculateAge;
 exports.calculateAgeSafe = calculateAgeSafe;
@@ -11,6 +12,11 @@ exports.isValidEmail = isValidEmail;
 exports.normalizeEmail = normalizeEmail;
 exports.isValidPhone = isValidPhone;
 exports.normalizePhone = normalizePhone;
+exports.extractEmailDomain = extractEmailDomain;
+exports.emailDomainsMatch = emailDomainsMatch;
+exports.phoneNumbersSimilar = phoneNumbersSimilar;
+exports.validateContactSimilarity = validateContactSimilarity;
+exports.calculateTrust = calculateTrust;
 exports.formatPersonName = formatPersonName;
 exports.formatDate = formatDate;
 exports.validatePersonData = validatePersonData;
@@ -103,8 +109,13 @@ function isChild(birthdate) {
  */
 function matchesAgeCriteria(birthdate, criteria) {
     const age = calculateAgeSafe(birthdate);
-    // If no birthdate, only match if preference is 'any'
+    // If no birthdate, match based on lenient setting
     if (age === null) {
+        if (criteria.agePreferenceLenient) {
+            // Lenient mode: include profiles without birthdates regardless of agePreference
+            return true;
+        }
+        // Strict mode (default): only match if preference is 'any'
         return criteria.agePreference === 'any' || criteria.agePreference === undefined;
     }
     // Check age preference
@@ -168,6 +179,200 @@ function normalizePhone(phone) {
     }
     return `+${digits}`;
 }
+// ===== Contact Validation Helpers =====
+/**
+ * Extract domain from email address
+ */
+function extractEmailDomain(email) {
+    const normalized = normalizeEmail(email);
+    const atIndex = normalized.indexOf('@');
+    return atIndex >= 0 ? normalized.substring(atIndex + 1) : '';
+}
+/**
+ * Common email domain aliases (e.g., gmail.com and googlemail.com are the same)
+ */
+const EMAIL_DOMAIN_ALIASES = {
+    'googlemail.com': 'gmail.com',
+    'google.com': 'gmail.com',
+};
+/**
+ * Normalize email domain to handle common aliases
+ */
+function normalizeEmailDomain(domain) {
+    const lowerDomain = domain.toLowerCase();
+    return EMAIL_DOMAIN_ALIASES[lowerDomain] || lowerDomain;
+}
+/**
+ * Check if two email domains match or are similar
+ * Handles:
+ * - Exact domain matches
+ * - Common aliases (gmail.com vs googlemail.com)
+ * - Prefix matching for similar domains (first 3+ characters)
+ *
+ * @param email1 - First email address
+ * @param email2 - Second email address
+ * @returns True if domains match or are similar
+ */
+function emailDomainsMatch(email1, email2) {
+    const domain1 = normalizeEmailDomain(extractEmailDomain(email1));
+    const domain2 = normalizeEmailDomain(extractEmailDomain(email2));
+    if (!domain1 || !domain2) {
+        return false;
+    }
+    // Exact match after normalization
+    if (domain1 === domain2) {
+        return true;
+    }
+    // Check if domains share a common prefix (at least 3 characters)
+    // This helps catch typos like "gmial.com" vs "gmail.com"
+    const minPrefixLength = 3;
+    if (domain1.length >= minPrefixLength && domain2.length >= minPrefixLength) {
+        const prefix1 = domain1.substring(0, minPrefixLength);
+        const prefix2 = domain2.substring(0, minPrefixLength);
+        if (prefix1 === prefix2) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Normalize phone number to digits only, stripping country code if present
+ */
+function normalizePhoneDigits(phone) {
+    const digits = phone.replace(/\D/g, '');
+    // Strip leading 1 for US numbers (11 digits starting with 1)
+    if (digits.length === 11 && digits.startsWith('1')) {
+        return digits.substring(1);
+    }
+    return digits;
+}
+/**
+ * Check if two phone numbers are similar
+ * Handles:
+ * - Different formats (+1, 1, or just 10 digits)
+ * - Country code variations
+ *
+ * @param phone1 - First phone number
+ * @param phone2 - Second phone number
+ * @returns True if phone numbers are similar
+ */
+function phoneNumbersSimilar(phone1, phone2) {
+    if (!phone1 || !phone2) {
+        return false;
+    }
+    const normalized1 = normalizePhoneDigits(phone1);
+    const normalized2 = normalizePhoneDigits(phone2);
+    // Empty after normalization
+    if (!normalized1 || !normalized2) {
+        return false;
+    }
+    // Exact match after normalization
+    if (normalized1 === normalized2) {
+        return true;
+    }
+    // Also check raw digits (handles international numbers)
+    const digits1 = phone1.replace(/\D/g, '');
+    const digits2 = phone2.replace(/\D/g, '');
+    return digits1 === digits2;
+}
+/**
+ * Validate contact info similarity for name-based matches
+ *
+ * This is useful when falling back to name-based search to ensure
+ * we don't match the wrong person with the same name.
+ *
+ * @param searchEmail - Email being searched for
+ * @param searchPhone - Phone being searched for
+ * @param personEmails - Array of email addresses from the person's profile
+ * @param personPhones - Array of phone numbers from the person's profile
+ * @returns Object with match results and overall validity
+ */
+function validateContactSimilarity(searchEmail, searchPhone, personEmails, personPhones) {
+    let emailMatch = false;
+    let phoneMatch = false;
+    // Check email domain match
+    if (searchEmail) {
+        emailMatch = personEmails.some(personEmail => emailDomainsMatch(searchEmail, personEmail));
+    }
+    // Check phone similarity
+    if (searchPhone) {
+        phoneMatch = personPhones.some(personPhone => phoneNumbersSimilar(searchPhone, personPhone));
+    }
+    // Valid if either email domain matches or phone is similar
+    // (or if we didn't have search criteria to check)
+    const hasSearchCriteria = !!(searchEmail || searchPhone);
+    const isValid = !hasSearchCriteria || emailMatch || phoneMatch;
+    return { emailMatch, phoneMatch, isValid };
+}
+// ===== Person ID Trust Calculation =====
+/**
+ * Default trust window for person IDs (1 hour in milliseconds)
+ * If a personId was saved within this time, it can be trusted without verification
+ */
+exports.DEFAULT_TRUST_WINDOW = 60 * 60 * 1000; // 1 hour
+/**
+ * Calculate whether a person ID can be trusted based on when it was created/verified
+ *
+ * This is useful for caching person IDs to avoid unnecessary API calls.
+ * PCO takes 15-30 minutes to index new contacts, so recently created person IDs
+ * should be trusted without re-verification to avoid race conditions.
+ *
+ * @param createdAt - ISO timestamp when the person ID was created/saved
+ * @param trustWindow - Trust window in milliseconds (default: 1 hour)
+ * @returns Object with trust decision, age, and reason
+ *
+ * @example
+ * ```typescript
+ * const trust = calculateTrust(pcoInfo.personIdCreatedAt);
+ * if (trust.shouldTrust) {
+ *   // Use cached personId without verification
+ *   return cachedPersonId;
+ * } else {
+ *   // Verify personId still exists in PCO
+ *   await client.people.getById(cachedPersonId);
+ * }
+ * ```
+ */
+function calculateTrust(createdAt, trustWindow = exports.DEFAULT_TRUST_WINDOW) {
+    if (!createdAt) {
+        return {
+            shouldTrust: false,
+            age: null,
+            reason: 'No timestamp (legacy data or never saved)',
+        };
+    }
+    const createdDate = new Date(createdAt);
+    if (isNaN(createdDate.getTime())) {
+        return {
+            shouldTrust: false,
+            age: null,
+            reason: 'Invalid timestamp format',
+        };
+    }
+    const age = Date.now() - createdDate.getTime();
+    if (age < 0) {
+        return {
+            shouldTrust: false,
+            age,
+            reason: 'Timestamp is in the future (clock skew)',
+        };
+    }
+    if (age < trustWindow) {
+        const ageSeconds = Math.round(age / 1000);
+        const trustWindowMinutes = Math.round(trustWindow / 1000 / 60);
+        return {
+            shouldTrust: true,
+            age,
+            reason: `Fresh personId (${ageSeconds}s old, within ${trustWindowMinutes}min trust window)`,
+        };
+    }
+    const ageMinutes = Math.round(age / 1000 / 60);
+    return {
+        shouldTrust: false,
+        age,
+        reason: `Old personId (${ageMinutes}min old, needs verification)`,
+    };
+}
 /**
  * Format person name from attributes
  */

package/dist/index.d.ts

@@ -20,7 +20,10 @@ 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, runList, 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, normalizeEmail, normalizePhone, processFileValue, searchPeople, validatePersonData, } from './helpers';
+export { buildQueryParams, calculateAge, calculateTrust, createPersonWithContact, createWorkflowCardWithNote, DEFAULT_TRUST_WINDOW, emailDomainsMatch, exportAllPeopleData, extractEmailDomain, extractFileUrl, formatDate, formatPersonName, getCompletePersonProfile, getFileExtension, getFilename, getListsWithCategories, getOrganizationInfo, getPeopleByHousehold, getPersonWorkflowCardsWithNotes, getPrimaryContact, isFileUpload, isFileUrl, isValidEmail, isValidPhone, normalizeEmail, normalizePhone, phoneNumbersSimilar, processFileValue, searchPeople, validateContactSimilarity, validatePersonData, } from './helpers';
+export type { TrustResult } from './helpers';
+export { DEFAULT_INITIAL_RETRY_CONFIG, DEFAULT_AGGRESSIVE_RETRY_CONFIG, } from './modules/people';
+export type { RetryConfig, PersonMatchOptions } from './modules/people';
 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.getNoteCategories = exports.getNote = exports.runList = 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.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 = exports.getNotes = 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 = exports.ApiCache = void 0;
+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.extractEmailDomain = exports.exportAllPeopleData = exports.emailDomainsMatch = exports.DEFAULT_TRUST_WINDOW = exports.createWorkflowCardWithNote = exports.createPersonWithContact = exports.calculateTrust = 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 = exports.getNotes = 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 = exports.ApiCache = exports.AdaptiveRateLimiter = exports.DEFAULT_AGGRESSIVE_RETRY_CONFIG = exports.DEFAULT_INITIAL_RETRY_CONFIG = exports.validatePersonData = exports.validateContactSimilarity = exports.searchPeople = exports.processFileValue = exports.phoneNumbersSimilar = void 0;
 // Main client class
 var client_1 = require("./client");
 Object.defineProperty(exports, "PcoClient", { enumerable: true, get: function () { return client_1.PcoClient; } });
@@ -113,9 +113,13 @@ Object.defineProperty(exports, "withTimeout", { enumerable: true, get: function
 var helpers_1 = require("./helpers");
 Object.defineProperty(exports, "buildQueryParams", { enumerable: true, get: function () { return helpers_1.buildQueryParams; } });
 Object.defineProperty(exports, "calculateAge", { enumerable: true, get: function () { return helpers_1.calculateAge; } });
+Object.defineProperty(exports, "calculateTrust", { enumerable: true, get: function () { return helpers_1.calculateTrust; } });
 Object.defineProperty(exports, "createPersonWithContact", { enumerable: true, get: function () { return helpers_1.createPersonWithContact; } });
 Object.defineProperty(exports, "createWorkflowCardWithNote", { enumerable: true, get: function () { return helpers_1.createWorkflowCardWithNote; } });
+Object.defineProperty(exports, "DEFAULT_TRUST_WINDOW", { enumerable: true, get: function () { return helpers_1.DEFAULT_TRUST_WINDOW; } });
+Object.defineProperty(exports, "emailDomainsMatch", { enumerable: true, get: function () { return helpers_1.emailDomainsMatch; } });
 Object.defineProperty(exports, "exportAllPeopleData", { enumerable: true, get: function () { return helpers_1.exportAllPeopleData; } });
+Object.defineProperty(exports, "extractEmailDomain", { enumerable: true, get: function () { return helpers_1.extractEmailDomain; } });
 Object.defineProperty(exports, "extractFileUrl", { enumerable: true, get: function () { return helpers_1.extractFileUrl; } });
 Object.defineProperty(exports, "formatDate", { enumerable: true, get: function () { return helpers_1.formatDate; } });
 Object.defineProperty(exports, "formatPersonName", { enumerable: true, get: function () { return helpers_1.formatPersonName; } });
@@ -133,9 +137,15 @@ Object.defineProperty(exports, "isValidEmail", { enumerable: true, get: function
 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, "phoneNumbersSimilar", { enumerable: true, get: function () { return helpers_1.phoneNumbersSimilar; } });
 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, "validateContactSimilarity", { enumerable: true, get: function () { return helpers_1.validateContactSimilarity; } });
 Object.defineProperty(exports, "validatePersonData", { enumerable: true, get: function () { return helpers_1.validatePersonData; } });
+// ===== Matching Configuration =====
+var people_2 = require("./modules/people");
+Object.defineProperty(exports, "DEFAULT_INITIAL_RETRY_CONFIG", { enumerable: true, get: function () { return people_2.DEFAULT_INITIAL_RETRY_CONFIG; } });
+Object.defineProperty(exports, "DEFAULT_AGGRESSIVE_RETRY_CONFIG", { enumerable: true, get: function () { return people_2.DEFAULT_AGGRESSIVE_RETRY_CONFIG; } });
 // ===== Performance Optimization =====
 var performance_1 = require("./performance");
 Object.defineProperty(exports, "AdaptiveRateLimiter", { enumerable: true, get: function () { return performance_1.AdaptiveRateLimiter; } });

package/dist/matching/matcher.d.ts

@@ -15,6 +15,10 @@ export declare class PersonMatcher {
     private strategies;
     private scorer;
     constructor(peopleModule: PeopleModule);
+    /**
+     * Resolve retry configuration from options, with defaults
+     */
+    private resolveRetryConfig;
     /**
      * Find or create a person with smart matching
      *
@@ -23,23 +27,66 @@ export declare class PersonMatcher {
      * - 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)
+     * - Supports multi-step search strategy for maximum matching success
      *
      * @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
+     * @param options.searchStrategy - 'single' for standard search, 'multi-step' for trying multiple strategies
      */
     findOrCreate(options: PersonMatchOptions): Promise<PersonResource>;
+    /**
+     * Final aggressive search before creating a new person
+     *
+     * This is a safeguard to prevent duplicate person creation when:
+     * - PCO hasn't indexed contacts yet (15-30 minute delay)
+     * - Multiple workers are processing the same person
+     * - The fast path didn't find an existing person
+     */
+    private findWithAggressiveRetry;
+    /**
+     * Multi-step search strategy configuration
+     */
+    private static readonly MULTI_STEP_STRATEGIES;
+    /**
+     * Find a match using multi-step search strategy
+     *
+     * Tries multiple matching strategies in order until a match is found:
+     * 1. Fuzzy with age preference (handles name variations, prefers adults)
+     * 2. Fuzzy without age preference (catches single matches filtered by age)
+     * 3. Exact with age preference (high confidence, prefers adults)
+     * 4. Exact without age preference (high confidence, any age)
+     *
+     * This approach maximizes matching success while maintaining quality.
+     */
+    findMatchMultiStep(options: PersonMatchOptions): Promise<MatchResult | null>;
     /**
      * 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.
+     *
+     * Supports phase-specific retry configurations via retryConfigs:
+     * - initial: Quick search (default 30s)
+     * - aggressive: Final search before create (default 60s)
      */
     private findOrCreateWithRetry;
     /**
      * Find the best match for a person
      */
     findMatch(options: PersonMatchOptions): Promise<MatchResult | null>;
+    /**
+     * Find a match by name with contact validation
+     *
+     * This is a fallback when email/phone search fails. It searches by name
+     * but validates that the person's contact info is similar to prevent
+     * wrong-person matches (e.g., two people named "John Smith").
+     */
+    private findMatchByNameWithContactValidation;
+    /**
+     * Validate a candidate's contact info based on the validation strategy
+     */
+    private validateCandidateContact;
     /**
      * Get potential matching candidates
      * @deprecated Use findMatch which has improved logic for separating verified matches from name-only matches

package/dist/matching/matcher.js

@@ -4,6 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PersonMatcher = void 0;
+const people_1 = require("../modules/people");
 const strategies_1 = require("./strategies");
 const scoring_1 = require("./scoring");
 const helpers_1 = require("../helpers");
@@ -13,6 +14,19 @@ class PersonMatcher {
         this.strategies = new strategies_1.MatchStrategies();
         this.scorer = new scoring_1.MatchScorer(peopleModule);
     }
+    /**
+     * Resolve retry configuration from options, with defaults
+     */
+    resolveRetryConfig(explicitConfig, phaseConfig, defaults = people_1.DEFAULT_INITIAL_RETRY_CONFIG) {
+        // Phase config takes precedence over explicit config
+        const config = phaseConfig || explicitConfig;
+        return {
+            maxRetries: config?.maxRetries ?? defaults.maxRetries,
+            maxWaitTime: config?.maxWaitTime ?? defaults.maxWaitTime,
+            initialDelay: config?.initialDelay ?? defaults.initialDelay,
+            backoffMultiplier: config?.backoffMultiplier ?? defaults.backoffMultiplier,
+        };
+    }
     /**
      * Find or create a person with smart matching
      *
@@ -21,13 +35,15 @@ class PersonMatcher {
      * - 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)
+     * - Supports multi-step search strategy for maximum matching success
      *
      * @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
+     * @param options.searchStrategy - 'single' for standard search, 'multi-step' for trying multiple strategies
      */
     async findOrCreate(options) {
-        const { createIfNotFound = true, matchStrategy = 'fuzzy', addMissingContactInfo = false, retryConfig, ...searchOptions } = options;
+        const { createIfNotFound = true, matchStrategy = 'fuzzy', searchStrategy = 'single', addMissingContactInfo = false, retryConfig, ...searchOptions } = options;
         // Determine if retry logic should be enabled
         // Retry is useful when:
         // 1. We have email/phone (these need verification)
@@ -40,8 +56,14 @@ class PersonMatcher {
         if (shouldRetry) {
             return this.findOrCreateWithRetry(options);
         }
-        // Try to find existing person
-        const match = await this.findMatch({ ...searchOptions, matchStrategy });
+        // Try to find existing person using appropriate search strategy
+        let match = null;
+        if (searchStrategy === 'multi-step') {
+            match = await this.findMatchMultiStep(options);
+        }
+        else {
+            match = await this.findMatch({ ...searchOptions, matchStrategy });
+        }
         if (match) {
             const person = match.person;
             // Add missing contact information if requested
@@ -52,29 +74,150 @@ class PersonMatcher {
         }
         // Create new person if not found and creation is enabled
         if (createIfNotFound) {
+            // If aggressive retry config is provided, do a final aggressive search before creating
+            // This is a safeguard to prevent duplicates when PCO hasn't indexed contacts yet
+            if (options.retryConfigs?.aggressive) {
+                const aggressiveMatch = await this.findWithAggressiveRetry(options);
+                if (aggressiveMatch) {
+                    const person = aggressiveMatch.person;
+                    if (addMissingContactInfo) {
+                        await this.addMissingContactInfo(person, options);
+                    }
+                    return person;
+                }
+            }
             return this.createPerson(options);
         }
         throw new Error(`No matching person found and creation is disabled`);
     }
+    /**
+     * Final aggressive search before creating a new person
+     *
+     * This is a safeguard to prevent duplicate person creation when:
+     * - PCO hasn't indexed contacts yet (15-30 minute delay)
+     * - Multiple workers are processing the same person
+     * - The fast path didn't find an existing person
+     */
+    async findWithAggressiveRetry(options) {
+        const { matchStrategy = 'fuzzy', searchStrategy = 'single', retryConfigs } = options;
+        const aggressiveConfig = this.resolveRetryConfig(undefined, retryConfigs?.aggressive, people_1.DEFAULT_AGGRESSIVE_RETRY_CONFIG);
+        console.log(`[PERSON_MATCH] Starting aggressive final search before create`, {
+            maxWaitTime: aggressiveConfig.maxWaitTime,
+            maxRetries: aggressiveConfig.maxRetries,
+        });
+        let totalWaitTime = 0;
+        for (let attempt = 1; attempt <= aggressiveConfig.maxRetries; attempt++) {
+            try {
+                let match = null;
+                if (searchStrategy === 'multi-step') {
+                    match = await this.findMatchMultiStep(options);
+                }
+                else {
+                    match = await this.findMatch({ ...options, matchStrategy });
+                }
+                if (match) {
+                    console.log(`[PERSON_MATCH] Aggressive search found person (would have created duplicate)`, {
+                        personId: match.person.id,
+                        attempt,
+                        totalWaitTime,
+                    });
+                    return match;
+                }
+            }
+            catch (error) {
+                console.warn(`[PERSON_MATCH] Aggressive search attempt ${attempt} failed:`, error);
+            }
+            // Don't wait on the last attempt
+            if (attempt === aggressiveConfig.maxRetries) {
+                break;
+            }
+            // Calculate delay with exponential backoff
+            const delay = Math.min(aggressiveConfig.initialDelay * Math.pow(aggressiveConfig.backoffMultiplier, attempt - 1), aggressiveConfig.maxWaitTime - totalWaitTime);
+            if (totalWaitTime + delay > aggressiveConfig.maxWaitTime) {
+                break;
+            }
+            totalWaitTime += delay;
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+        console.log(`[PERSON_MATCH] Aggressive search completed - no match found, safe to create`, {
+            totalWaitTime,
+            maxRetries: aggressiveConfig.maxRetries,
+        });
+        return null;
+    }
+    /**
+     * Find a match using multi-step search strategy
+     *
+     * Tries multiple matching strategies in order until a match is found:
+     * 1. Fuzzy with age preference (handles name variations, prefers adults)
+     * 2. Fuzzy without age preference (catches single matches filtered by age)
+     * 3. Exact with age preference (high confidence, prefers adults)
+     * 4. Exact without age preference (high confidence, any age)
+     *
+     * This approach maximizes matching success while maintaining quality.
+     */
+    async findMatchMultiStep(options) {
+        const { agePreference, agePreferenceLenient, ...baseOptions } = options;
+        for (const strategy of PersonMatcher.MULTI_STEP_STRATEGIES) {
+            try {
+                const searchOptions = {
+                    ...baseOptions,
+                    matchStrategy: strategy.matchStrategy,
+                };
+                // Apply age preference only when specified by strategy
+                if (strategy.useAgePreference && agePreference) {
+                    searchOptions.agePreference = agePreference;
+                    // Use lenient mode when specified, so profiles without birthdates are included
+                    searchOptions.agePreferenceLenient = agePreferenceLenient ?? true;
+                }
+                const match = await this.findMatch(searchOptions);
+                if (match) {
+                    console.log(`[PERSON_MATCH] Multi-step search found match using ${strategy.description}`, {
+                        personId: match.person.id,
+                        score: match.score,
+                        reason: match.reason,
+                    });
+                    return match;
+                }
+            }
+            catch (error) {
+                // Log but continue to next strategy
+                console.warn(`[PERSON_MATCH] Multi-step strategy "${strategy.description}" failed:`, error);
+            }
+        }
+        return null;
+    }
     /**
      * 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.
+     *
+     * Supports phase-specific retry configurations via retryConfigs:
+     * - initial: Quick search (default 30s)
+     * - aggressive: Final search before create (default 60s)
      */
     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;
+        const { createIfNotFound = false, matchStrategy = 'fuzzy', searchStrategy = 'single', addMissingContactInfo = false, retryConfig, retryConfigs, ...searchOptions } = options;
+        // Determine which retry configuration to use
+        // Priority: retryConfigs.initial > retryConfig > defaults
+        const effectiveRetryConfig = this.resolveRetryConfig(retryConfig, retryConfigs?.initial);
+        const maxRetries = effectiveRetryConfig.maxRetries;
+        const maxWaitTime = effectiveRetryConfig.maxWaitTime;
+        const initialDelay = effectiveRetryConfig.initialDelay;
+        const backoffMultiplier = effectiveRetryConfig.backoffMultiplier;
         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 });
+                // Try to find existing person using appropriate search strategy
+                let match = null;
+                if (searchStrategy === 'multi-step') {
+                    match = await this.findMatchMultiStep(options);
+                }
+                else {
+                    match = await this.findMatch({ ...searchOptions, matchStrategy });
+                }
                 if (match) {
                     const person = match.person;
                     // Add missing contact information if requested
@@ -86,7 +229,8 @@ class PersonMatcher {
                         console.log(`[PERSON_MATCH] Found person after ${attempt} attempts (waited ${totalWaitTime}ms)`, {
                             personId: person.id,
                             attempt,
-                            totalWaitTime
+                            totalWaitTime,
+                            searchStrategy,
                         });
                     }
                     return person;
@@ -133,7 +277,7 @@ class PersonMatcher {
      * Find the best match for a person
      */
     async findMatch(options) {
-        const { matchStrategy = 'fuzzy', email, phone, firstName, lastName } = options;
+        const { matchStrategy = 'fuzzy', email, phone, firstName, lastName, fallbackToNameSearch = false, contactValidation = 'similarity' } = options;
         // Step 1: Try email/phone search first
         const emailPhoneMatches = [];
         const nameOnlyMatches = [];
@@ -231,11 +375,124 @@ class PersonMatcher {
         // For "exact" strategy, only return verified email/phone matches
         if (matchStrategy === 'exact') {
             const exactMatches = scoredCandidates.filter(c => c.isVerifiedContactMatch && c.score >= 0.8);
-            return exactMatches.length > 0 ? exactMatches[0] : null;
+            if (exactMatches.length > 0) {
+                return exactMatches[0];
+            }
+            // Continue to fallback if enabled
+        }
+        else {
+            // Apply strategy-specific filtering
+            const bestMatch = this.strategies.selectBestMatch(scoredCandidates, matchStrategy);
+            if (bestMatch) {
+                return bestMatch;
+            }
+            // Continue to fallback if enabled
+        }
+        // Step 5: Fallback to name-based search with contact validation
+        // Only used when email/phone search fails to find a match
+        if (fallbackToNameSearch && firstName && lastName && (email || phone)) {
+            const nameSearchMatch = await this.findMatchByNameWithContactValidation(firstName, lastName, email, phone, contactValidation, options);
+            if (nameSearchMatch) {
+                return nameSearchMatch;
+            }
+        }
+        return null;
+    }
+    /**
+     * Find a match by name with contact validation
+     *
+     * This is a fallback when email/phone search fails. It searches by name
+     * but validates that the person's contact info is similar to prevent
+     * wrong-person matches (e.g., two people named "John Smith").
+     */
+    async findMatchByNameWithContactValidation(firstName, lastName, searchEmail, searchPhone, validationStrategy, options) {
+        try {
+            console.log(`[PERSON_MATCH] Attempting name-based search fallback for ${firstName} ${lastName}`);
+            const nameResults = await this.peopleModule.search({
+                name: `${firstName} ${lastName}`
+            });
+            if (nameResults.data.length === 0) {
+                return null;
+            }
+            // Validate each candidate's contact info
+            for (const candidate of nameResults.data) {
+                const isValid = await this.validateCandidateContact(candidate, searchEmail, searchPhone, validationStrategy);
+                if (isValid) {
+                    const score = await this.scorer.scoreMatch(candidate, options);
+                    const reason = await this.scorer.getMatchReason(candidate, options);
+                    console.log(`[PERSON_MATCH] Name-based search found validated match`, {
+                        personId: candidate.id,
+                        validationStrategy,
+                        score,
+                    });
+                    return {
+                        person: candidate,
+                        score,
+                        reason: `name match with ${validationStrategy} contact validation, ${reason}`,
+                        isVerifiedContactMatch: false, // Not a direct contact match
+                    };
+                }
+            }
+            console.log(`[PERSON_MATCH] Name-based search found candidates but none passed contact validation`, {
+                candidateCount: nameResults.data.length,
+                validationStrategy,
+            });
+            return null;
+        }
+        catch (error) {
+            console.warn('[PERSON_MATCH] Name-based search fallback failed:', error);
+            return null;
+        }
+    }
+    /**
+     * Validate a candidate's contact info based on the validation strategy
+     */
+    async validateCandidateContact(candidate, searchEmail, searchPhone, validationStrategy) {
+        try {
+            // Get person's contact info
+            const [personEmails, personPhones] = await Promise.all([
+                this.peopleModule.getEmails(candidate.id).then(r => r.data?.map(e => e.attributes?.address || '').filter(Boolean) || []).catch(() => []),
+                this.peopleModule.getPhoneNumbers(candidate.id).then(r => r.data?.map(p => p.attributes?.number || '').filter(Boolean) || []).catch(() => []),
+            ]);
+            switch (validationStrategy) {
+                case 'strict':
+                    // Require exact match
+                    if (searchEmail) {
+                        const normalizedSearch = (0, helpers_1.normalizeEmail)(searchEmail);
+                        if (personEmails.some(e => (0, helpers_1.normalizeEmail)(e) === normalizedSearch)) {
+                            return true;
+                        }
+                    }
+                    if (searchPhone) {
+                        const normalizedSearch = (0, helpers_1.normalizePhone)(searchPhone);
+                        if (personPhones.some(p => (0, helpers_1.normalizePhone)(p) === normalizedSearch)) {
+                            return true;
+                        }
+                    }
+                    return false;
+                case 'domain':
+                    // Require domain match for email or exact match for phone
+                    if (searchEmail && personEmails.some(e => (0, helpers_1.emailDomainsMatch)(searchEmail, e))) {
+                        return true;
+                    }
+                    if (searchPhone) {
+                        const normalizedSearch = (0, helpers_1.normalizePhone)(searchPhone);
+                        if (personPhones.some(p => (0, helpers_1.normalizePhone)(p) === normalizedSearch)) {
+                            return true;
+                        }
+                    }
+                    return false;
+                case 'similarity':
+                default:
+                    // Use domain matching for email and similarity for phone
+                    const validation = (0, helpers_1.validateContactSimilarity)(searchEmail, searchPhone, personEmails, personPhones);
+                    return validation.isValid;
+            }
+        }
+        catch (error) {
+            console.warn(`[PERSON_MATCH] Contact validation failed for person ${candidate.id}:`, error);
+            return false;
         }
-        // Apply strategy-specific filtering
-        const bestMatch = this.strategies.selectBestMatch(scoredCandidates, matchStrategy);
-        return bestMatch;
     }
     /**
      * Get potential matching candidates
@@ -377,7 +634,8 @@ class PersonMatcher {
                 agePreference: options.agePreference,
                 minAge: options.minAge,
                 maxAge: options.maxAge,
-                birthYear: options.birthYear
+                birthYear: options.birthYear,
+                agePreferenceLenient: options.agePreferenceLenient
             });
         });
     }
@@ -531,3 +789,12 @@ class PersonMatcher {
     }
 }
 exports.PersonMatcher = PersonMatcher;
+/**
+ * Multi-step search strategy configuration
+ */
+PersonMatcher.MULTI_STEP_STRATEGIES = [
+    { matchStrategy: 'fuzzy', useAgePreference: true, description: 'fuzzy with age preference' },
+    { matchStrategy: 'fuzzy', useAgePreference: false, description: 'fuzzy without age preference' },
+    { matchStrategy: 'exact', useAgePreference: true, description: 'exact with age preference' },
+    { matchStrategy: 'exact', useAgePreference: false, description: 'exact without age preference' },
+];

package/dist/matching/scoring.js

@@ -164,7 +164,8 @@ class MatchScorer {
             agePreference: options.agePreference,
             minAge: options.minAge,
             maxAge: options.maxAge,
-            birthYear: options.birthYear
+            birthYear: options.birthYear,
+            agePreferenceLenient: options.agePreferenceLenient
         });
         if (!matches) {
             return 0; // No match

package/dist/modules/people.d.ts

@@ -58,6 +58,16 @@ export interface PersonMatchOptions {
      * - 'aggressive': Return best match with lower threshold
      */
     matchStrategy?: 'exact' | 'fuzzy' | 'aggressive';
+    /**
+     * Search strategy for finding matches:
+     * - 'single': Use only the specified matchStrategy (default)
+     * - 'multi-step': Try multiple strategies in order until a match is found:
+     *   1. Fuzzy with age preference
+     *   2. Fuzzy without age preference
+     *   3. Exact with age preference
+     *   4. Exact without age preference
+     */
+    searchStrategy?: 'single' | 'multi-step';
     /** Campus ID to associate with the person */
     campusId?: string;
     /** If true, create a new person if no match is found (default: true) */
@@ -70,6 +80,12 @@ export interface PersonMatchOptions {
     addMissingContactInfo?: boolean;
     /** Age preference filter: 'adults' (18+), 'children' (<18), or 'any' */
     agePreference?: 'adults' | 'children' | 'any';
+    /**
+     * When true, age preference filters only apply to profiles with birthdates.
+     * Profiles without birthdates are included regardless of agePreference.
+     * When false (default), profiles without birthdates only match when agePreference is 'any'.
+     */
+    agePreferenceLenient?: boolean;
     /** Minimum age filter */
     minAge?: number;
     /** Maximum age filter */
@@ -81,19 +97,54 @@ export interface PersonMatchOptions {
      * 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;
+    retryConfig?: RetryConfig;
+    /**
+     * Phase-specific retry configurations for advanced control.
+     * When both retryConfig and retryConfigs are provided, retryConfigs takes precedence.
+     */
+    retryConfigs?: {
+        /** Configuration for initial/quick search phase (default: 30s max wait) */
+        initial?: RetryConfig;
+        /** Configuration for aggressive search before creating (default: 60s max wait) */
+        aggressive?: RetryConfig;
     };
+    /**
+     * If true, fall back to name-based search when email/phone search fails.
+     * Requires both firstName and lastName to be provided.
+     * Uses contact validation to avoid wrong-person matches. (default: false)
+     */
+    fallbackToNameSearch?: boolean;
+    /**
+     * Contact validation strategy for name-based search fallback:
+     * - 'strict': Requires exact email or phone match
+     * - 'domain': Requires matching email domain or similar phone
+     * - 'similarity': Uses domain matching for email, similarity for phone (default)
+     */
+    contactValidation?: 'strict' | 'domain' | 'similarity';
+}
+/**
+ * Retry configuration for handling PCO contact verification delays
+ */
+export interface 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;
 }
+/**
+ * Default retry configuration for initial search phase
+ */
+export declare const DEFAULT_INITIAL_RETRY_CONFIG: Required<Omit<RetryConfig, 'enabled'>>;
+/**
+ * Default retry configuration for aggressive search phase (before creating)
+ */
+export declare const DEFAULT_AGGRESSIVE_RETRY_CONFIG: Required<Omit<RetryConfig, 'enabled'>>;
 export declare class PeopleModule extends BaseModule {
     private personMatcher;
     constructor(httpClient: PcoHttpClient, paginationHelper: PaginationHelper, eventEmitter: PcoEventEmitter);
@@ -113,6 +164,30 @@ export declare class PeopleModule extends BaseModule {
      * Get a single person by ID
      */
     getById(id: string, include?: string[]): Promise<PersonResource>;
+    /**
+     * Verify that a person exists in PCO
+     *
+     * This is useful for validating cached person IDs before use,
+     * especially when person records may have been merged or deleted.
+     *
+     * @param personId - The person ID to verify
+     * @param options - Optional configuration
+     * @param options.timeout - Timeout in milliseconds (default: 30000)
+     * @returns True if person exists, false if not found
+     * @throws Error if request times out or other error occurs (except 404)
+     *
+     * @example
+     * ```typescript
+     * const exists = await client.people.verifyPersonExists(cachedPersonId);
+     * if (!exists) {
+     *   // Person was merged or deleted, need to search again
+     *   const person = await client.people.findOrCreate(options);
+     * }
+     * ```
+     */
+    verifyPersonExists(personId: string, options?: {
+        timeout?: number;
+    }): Promise<boolean>;
     /**
      * Create a new person
      */

package/dist/modules/people.js

@@ -3,9 +3,27 @@
  * v2.0.0 People Module
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PeopleModule = void 0;
+exports.PeopleModule = exports.DEFAULT_AGGRESSIVE_RETRY_CONFIG = exports.DEFAULT_INITIAL_RETRY_CONFIG = void 0;
 const planning_center_base_ts_1 = require("@rachelallyson/planning-center-base-ts");
 const matcher_1 = require("../matching/matcher");
+/**
+ * Default retry configuration for initial search phase
+ */
+exports.DEFAULT_INITIAL_RETRY_CONFIG = {
+    maxRetries: 3,
+    maxWaitTime: 30000, // 30 seconds
+    initialDelay: 3000,
+    backoffMultiplier: 2,
+};
+/**
+ * Default retry configuration for aggressive search phase (before creating)
+ */
+exports.DEFAULT_AGGRESSIVE_RETRY_CONFIG = {
+    maxRetries: 6,
+    maxWaitTime: 60000, // 60 seconds
+    initialDelay: 5000,
+    backoffMultiplier: 2,
+};
 class PeopleModule extends planning_center_base_ts_1.BaseModule {
     constructor(httpClient, paginationHelper, eventEmitter) {
         super(httpClient, paginationHelper, eventEmitter);
@@ -57,6 +75,46 @@ class PeopleModule extends planning_center_base_ts_1.BaseModule {
         }
         return this.getSingle(`/people/${id}`, params);
     }
+    /**
+     * Verify that a person exists in PCO
+     *
+     * This is useful for validating cached person IDs before use,
+     * especially when person records may have been merged or deleted.
+     *
+     * @param personId - The person ID to verify
+     * @param options - Optional configuration
+     * @param options.timeout - Timeout in milliseconds (default: 30000)
+     * @returns True if person exists, false if not found
+     * @throws Error if request times out or other error occurs (except 404)
+     *
+     * @example
+     * ```typescript
+     * const exists = await client.people.verifyPersonExists(cachedPersonId);
+     * if (!exists) {
+     *   // Person was merged or deleted, need to search again
+     *   const person = await client.people.findOrCreate(options);
+     * }
+     * ```
+     */
+    async verifyPersonExists(personId, options) {
+        const timeout = options?.timeout ?? 30000;
+        const verificationPromise = this.getById(personId)
+            .then(() => true)
+            .catch((error) => {
+            // 404 means person doesn't exist (merged or deleted)
+            if (error?.status === 404 || error?.response?.status === 404) {
+                return false;
+            }
+            // Re-throw other errors
+            throw error;
+        });
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Person verification timed out after ${timeout}ms`));
+            }, timeout);
+        });
+        return Promise.race([verificationPromise, timeoutPromise]);
+    }
     /**
      * Create a new person
      */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rachelallyson/planning-center-people-ts",
-    "version": "2.12.2",
+    "version": "2.14.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",