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

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.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.js

@@ -50,20 +50,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 +213,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 +227,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 +298,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/package.json

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