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

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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**

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
      */

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.10.0",
+    "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",