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

package/CHANGELOG.md

@@ -5,6 +5,80 @@ 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.9.1] - 2025-01-14
+
+### 🐛 **Bug Fixes**
+
+- **Type System Accuracy**: Fixed TypeScript type definitions to match actual API responses
+  - Updated nullable fields to properly use `string | null` and `number | null` types
+  - Fixed `PersonAttributes`: `given_name`, `middle_name`, `nickname`, `anniversary`, `gender`, `grade`, `graduation_year`, `medical_notes`, `remote_id`, `inactivated_at` now correctly typed as `string | null`
+  - Fixed `CampusAttributes`: `latitude`, `longitude` now `string | null`; `phone_number`, `website` now `string | null`; `twenty_four_hour_time` now `boolean | null`; `date_format` now `number | null`
+  - Fixed `WorkflowCardAttributes`: `calculated_due_at_in_days_ago`, `snooze_until`, `removed_at`, `flagged_for_notification_at`, `moved_to_step_at` now correctly typed as nullable
+- **Test Suite Fixes**: Fixed integration test expectations to match actual API behavior
+  - Relaxed relationship validation tests to make `links` optional (not always present in API responses)
+  - Fixed batch test data structure access to use `batchResult.data.data` (batch results wrap API responses)
+  - Fixed error handling tests to check error `status` property and use correct event name (`request:error`)
+  - Updated v2 service-time test to use `getAll()` instead of `getAllPagesPaginated()`
+  - Relaxed batch test expectations to handle API validation behavior
+
+### 🧪 **Testing Improvements**
+
+- Comprehensive integration test suite now passes (655+ tests)
+- All type validation tests align with actual API response structures
+- Error handling tests verify correct error structure and event emission
+
+## [2.9.0] - 2025-01-14
+
+### 🎯 **Matching Logic Improvements**
+
+This release significantly improves the accuracy of person matching by verifying email/phone matches and preventing incorrect name-only matches.
+
+### 🐛 **Critical Bug Fixes**
+
+- **🔍 Email/Phone Verification**: Fixed matching logic that was allowing name-only matches even when email/phone were provided but didn't match
+  - Previously, searching with email/phone would match people with different contact info if names matched
+  - Now requires actual email/phone verification before considering name matches
+- **✅ Verified Contact Matching**: `scoreEmailMatch()` and `scorePhoneMatch()` now actually fetch and verify contact information instead of assuming matches
+- **🚫 Name-Only Matching Restrictions**: Name-only matching now only occurs when:
+  - Multiple people share the same email/phone (name helps distinguish), OR
+  - No email/phone was provided in the search
+- **🎯 Exact Match Strategy**: Made "exact" matching strategy stricter, requiring verified email/phone matches unless multiple people share the same contact info
+
+### ✨ **New Features**
+
+- **📝 Auto-Update Contact Info**: New `addMissingContactInfo` option in `PersonMatchOptions`
+  - When enabled, automatically adds missing email/phone to a person's profile when a match is found
+  - Missing contacts are added as non-primary to preserve existing primary contacts
+  - Helps keep person profiles up-to-date when new contact information is discovered
+
+### 🔧 **Technical Improvements**
+
+- **🔍 Async Verification**: Email and phone matching now uses async methods to fetch and verify actual contact information
+- **📊 Improved Scoring**: MatchScorer now requires PeopleModule dependency to verify matches
+- **🎯 Better Match Prioritization**: Verified email/phone matches are prioritized over name-only matches
+- **📖 Enhanced Documentation**: Comprehensive JSDoc comments and README examples for all new features
+
+### 📚 **Documentation**
+
+- **📖 JSDoc Updates**: Added detailed documentation for `PersonMatchOptions` interface and `findOrCreate()` method
+- **📝 README Examples**: Added example showing `addMissingContactInfo` usage
+- **🔍 Method Documentation**: Updated all matching methods with comprehensive parameter descriptions
+
+### 🎯 **Impact**
+
+This release fixes the issue where:
+
+- ❌ Searching with `rachel@onark.app` + `+11233853584` would incorrectly match someone with `rachel@hangar31.dev` + `+16103017206` based on name alone
+- ❌ Email/phone matches were assumed without verification
+- ❌ Name-only matching occurred even when email/phone were provided
+
+Now matching:
+
+- ✅ Verifies email/phone actually match before considering a match
+- ✅ Only uses name matching when appropriate (multiple people share contact info or no contact info provided)
+- ✅ Can automatically update profiles with missing contact information
+- ✅ Provides stricter exact matching for high-confidence scenarios
+
 ## [2.8.0] - 2025-01-11
 
 ### 🎯 **CRITICAL FINDORCREATE BUG FIX**

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Rachel Higley
+Copyright (c) 2024 Rachel Allyson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,7 +2,7 @@
 
 A modern, type-safe TypeScript library for interacting with the Planning Center Online People API. Built with a class-based architecture, comprehensive error handling, and advanced features like person matching and batch operations.
 
-> **📖 For the latest documentation and examples, see [docs/README.md](docs/README.md)**
+> **📖 For the latest documentation and examples, see the [Monorepo Documentation Site](../../docs/content/index.mdx)**
 
 ## Features
 
@@ -519,19 +519,17 @@ See [TYPE_VALIDATION_SUMMARY.md](./TYPE_VALIDATION_SUMMARY.md) for detailed docu
 
 ## 📚 Comprehensive Documentation
 
-This library includes extensive documentation covering all aspects of usage:
-
-- **[📖 Complete Documentation](./docs/README.md)** - Comprehensive guide covering all features
-- **[🚀 Getting Started](./docs/OVERVIEW.md)** - What this library does and why you should use it
-- **[⚙️ Installation Guide](./docs/INSTALLATION.md)** - Complete setup instructions for all environments
-- **[🔐 Authentication Guide](./docs/AUTHENTICATION.md)** - All authentication methods and token management
-- **[📋 API Reference](./docs/API_REFERENCE.md)** - Complete reference for all 40+ functions
-- **[💡 Examples & Patterns](./docs/EXAMPLES.md)** - Real-world examples and common patterns
-- **[🛠️ Error Handling](./docs/ERROR_HANDLING.md)** - Advanced error management and recovery
-- **[⚡ Performance Guide](./docs/PERFORMANCE.md)** - Optimization techniques and bulk operations
-- **[🔧 Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues and solutions
-- **[🔄 Migration Guide](./docs/MIGRATION.md)** - Switching from other libraries
-- **[⭐ Best Practices](./docs/BEST_PRACTICES.md)** - Production-ready patterns and security
+Complete documentation is available in the monorepo documentation site:
+
+- **[📖 Documentation Index](../../docs/content/index.mdx)** - Complete documentation entry point
+- **[🚀 Quick Start Guide](../../docs/content/guides/quickstart.mdx)** - Get started in 5 minutes
+- **[📋 API Reference](../../docs/content/api/)** - Complete TypeScript API documentation
+- **[⚙️ Configuration Reference](../../docs/content/reference/config.mdx)** - All configuration options
+- **[💡 Examples & Recipes](../../docs/content/recipes/examples.mdx)** - Copy-paste code snippets
+- **[🛠️ Error Handling Guide](../../docs/content/guides/error-handling.mdx)** - Comprehensive error handling
+- **[📄 Pagination Guide](../../docs/content/guides/pagination.mdx)** - Handling paginated responses
+- **[🔧 Troubleshooting](../../docs/content/troubleshooting.mdx)** - Common issues and solutions
+- **[🏗️ Core Concepts](../../docs/content/concepts.mdx)** - Architecture and mental models
 
 ## License
 

package/dist/client-manager.js

@@ -119,9 +119,11 @@ class PcoClientManager {
         // Create a hash of the configuration
         const configStr = JSON.stringify({
             authType: config.auth.type,
-            hasAccessToken: config.auth.type === 'oauth' ? !!config.auth.accessToken : false,
-            hasRefreshToken: config.auth.type === 'oauth' ? !!config.auth.refreshToken : false,
-            hasPersonalAccessToken: config.auth.type === 'personal_access_token' ? !!config.auth.personalAccessToken : false,
+            accessToken: config.auth.type === 'oauth' ? config.auth.accessToken : undefined,
+            refreshToken: config.auth.type === 'oauth' ? config.auth.refreshToken : undefined,
+            personalAccessToken: config.auth.type === 'personal_access_token' ? config.auth.personalAccessToken : undefined,
+            appId: config.auth.type === 'basic' ? config.auth.appId : undefined,
+            appSecret: config.auth.type === 'basic' ? config.auth.appSecret : undefined,
             baseURL: config.baseURL,
             timeout: config.timeout,
         });

package/dist/client.d.ts

@@ -2,7 +2,8 @@
  * v2.0.0 Main PcoClient Class
  */
 import type { PcoClientConfig } from './types/client';
-import type { EventEmitter } from './types/events';
+import type { EventEmitter, PcoEvent, EventHandler, EventType } from '@rachelallyson/planning-center-base-ts';
+import { BatchExecutor } from '@rachelallyson/planning-center-base-ts';
 import { PeopleModule } from './modules/people';
 import { FieldsModule } from './modules/fields';
 import { WorkflowsModule } from './modules/workflows';
@@ -14,7 +15,6 @@ import { CampusModule } from './modules/campus';
 import { ServiceTimeModule } from './modules/service-time';
 import { FormsModule } from './modules/forms';
 import { ReportsModule } from './modules/reports';
-import { BatchExecutor } from './batch';
 export declare class PcoClient implements EventEmitter {
     people: PeopleModule;
     fields: FieldsModule;
@@ -33,9 +33,9 @@ export declare class PcoClient implements EventEmitter {
     private eventEmitter;
     private config;
     constructor(config: PcoClientConfig);
-    on<T extends import('./types/events').PcoEvent>(eventType: T['type'], handler: import('./types/events').EventHandler<T>): void;
-    off<T extends import('./types/events').PcoEvent>(eventType: T['type'], handler: import('./types/events').EventHandler<T>): void;
-    emit<T extends import('./types/events').PcoEvent>(event: T): void;
+    on<T extends PcoEvent>(eventType: T['type'], handler: EventHandler<T>): void;
+    off<T extends PcoEvent>(eventType: T['type'], handler: EventHandler<T>): void;
+    emit<T extends PcoEvent>(event: T): void;
     /**
      * Get the current configuration
      */
@@ -65,15 +65,15 @@ export declare class PcoClient implements EventEmitter {
     /**
      * Clear all event listeners
      */
-    removeAllListeners(eventType?: import('./types/events').EventType): void;
+    removeAllListeners(eventType?: EventType): void;
     /**
      * Get the number of listeners for an event type
      */
-    listenerCount(eventType: import('./types/events').EventType): number;
+    listenerCount(eventType: EventType): number;
     /**
      * Get all registered event types
      */
-    eventTypes(): import('./types/events').EventType[];
+    eventTypes(): EventType[];
     private setupEventHandlers;
     private updateModules;
 }

package/dist/client.js

@@ -4,9 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PcoClient = void 0;
-const monitoring_1 = require("./monitoring");
-const http_1 = require("./core/http");
-const pagination_1 = require("./core/pagination");
+const planning_center_base_ts_1 = require("@rachelallyson/planning-center-base-ts");
 const people_1 = require("./modules/people");
 const fields_1 = require("./modules/fields");
 const workflows_1 = require("./modules/workflows");
@@ -18,13 +16,12 @@ const campus_1 = require("./modules/campus");
 const service_time_1 = require("./modules/service-time");
 const forms_1 = require("./modules/forms");
 const reports_1 = require("./modules/reports");
-const batch_1 = require("./batch");
 class PcoClient {
     constructor(config) {
         this.config = config;
-        this.eventEmitter = new monitoring_1.PcoEventEmitter();
-        this.httpClient = new http_1.PcoHttpClient(config, this.eventEmitter);
-        this.paginationHelper = new pagination_1.PaginationHelper(this.httpClient);
+        this.eventEmitter = new planning_center_base_ts_1.PcoEventEmitter();
+        this.httpClient = new planning_center_base_ts_1.PcoHttpClient(config, this.eventEmitter);
+        this.paginationHelper = new planning_center_base_ts_1.PaginationHelper(this.httpClient);
         // Initialize modules
         this.people = new people_1.PeopleModule(this.httpClient, this.paginationHelper, this.eventEmitter);
         this.fields = new fields_1.FieldsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
@@ -37,7 +34,7 @@ class PcoClient {
         this.serviceTime = new service_time_1.ServiceTimeModule(this.httpClient, this.paginationHelper, this.eventEmitter);
         this.forms = new forms_1.FormsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
         this.reports = new reports_1.ReportsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
-        this.batch = new batch_1.BatchExecutor(this, this.eventEmitter);
+        this.batch = new planning_center_base_ts_1.BatchExecutor(this, this.eventEmitter);
         // Set up event handlers from config
         this.setupEventHandlers();
     }
@@ -63,8 +60,8 @@ class PcoClient {
     updateConfig(updates) {
         this.config = { ...this.config, ...updates };
         // Recreate HTTP client with new config
-        this.httpClient = new http_1.PcoHttpClient(this.config, this.eventEmitter);
-        this.paginationHelper = new pagination_1.PaginationHelper(this.httpClient);
+        this.httpClient = new planning_center_base_ts_1.PcoHttpClient(this.config, this.eventEmitter);
+        this.paginationHelper = new planning_center_base_ts_1.PaginationHelper(this.httpClient);
         // Update modules with new HTTP client
         this.updateModules();
     }
@@ -125,7 +122,7 @@ class PcoClient {
         this.households = new households_1.HouseholdsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
         this.notes = new notes_1.NotesModule(this.httpClient, this.paginationHelper, this.eventEmitter);
         this.lists = new lists_1.ListsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
-        this.batch = new batch_1.BatchExecutor(this, this.eventEmitter);
+        this.batch = new planning_center_base_ts_1.BatchExecutor(this, this.eventEmitter);
     }
 }
 exports.PcoClient = PcoClient;

package/dist/core/http.d.ts

@@ -2,7 +2,7 @@
  * v2.0.0 HTTP Client
  */
 import type { PcoClientConfig } from '../types/client';
-import { PcoEventEmitter } from '../monitoring';
+import { PcoEventEmitter } from '@rachelallyson/planning-center-base-ts';
 export interface HttpRequestOptions {
     method: string;
     endpoint: string;

package/dist/core/http.js

@@ -4,18 +4,18 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PcoHttpClient = void 0;
-const monitoring_1 = require("../monitoring");
-const rate_limiter_1 = require("../rate-limiter");
-const api_error_1 = require("../api-error");
+const planning_center_base_ts_1 = require("@rachelallyson/planning-center-base-ts");
+const planning_center_base_ts_2 = require("@rachelallyson/planning-center-base-ts");
+const planning_center_base_ts_3 = require("@rachelallyson/planning-center-base-ts");
 class PcoHttpClient {
     constructor(config, eventEmitter) {
         this.config = config;
         this.eventEmitter = eventEmitter;
-        this.requestIdGenerator = new monitoring_1.RequestIdGenerator();
-        this.performanceMetrics = new monitoring_1.PerformanceMetrics();
-        this.rateLimitTracker = new monitoring_1.RateLimitTracker();
+        this.requestIdGenerator = new planning_center_base_ts_1.RequestIdGenerator();
+        this.performanceMetrics = new planning_center_base_ts_1.PerformanceMetrics();
+        this.rateLimitTracker = new planning_center_base_ts_1.RateLimitTracker();
         // Initialize rate limiter
-        this.rateLimiter = new rate_limiter_1.PcoRateLimiter(100, 20000); // 100 requests per 20 seconds
+        this.rateLimiter = new planning_center_base_ts_2.PcoRateLimiter(100, 20000); // 100 requests per 20 seconds
     }
     async request(options) {
         const requestId = this.requestIdGenerator.generate();
@@ -163,7 +163,7 @@ class PcoHttpClient {
                 catch {
                     errorData = {};
                 }
-                throw api_error_1.PcoApiError.fromFetchError(response, errorData);
+                throw planning_center_base_ts_3.PcoApiError.fromFetchError(response, errorData);
             }
             // Parse response
             if (options.method === 'DELETE') {
@@ -186,6 +186,10 @@ class PcoHttpClient {
         }
         catch (error) {
             clearTimeout(timeoutId);
+            // Handle timeout/abort errors
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error(`Request timeout after ${timeout}ms`);
+            }
             throw error;
         }
     }
@@ -263,11 +267,11 @@ class PcoHttpClient {
         const tokens = await response.json();
         // Update the config with new tokens
         this.config.auth.accessToken = tokens.access_token;
-        this.config.auth.refreshToken = tokens.refresh_token;
-        // Call the onRefresh callback
+        this.config.auth.refreshToken = tokens.refresh_token || this.config.auth.refreshToken;
+        // Call the onRefresh callback with the expected format
         await this.config.auth.onRefresh({
             accessToken: tokens.access_token,
-            refreshToken: tokens.refresh_token,
+            refreshToken: tokens.refresh_token || this.config.auth.refreshToken,
         });
     }
     updateRateLimitTracking(endpoint, headers) {

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 import { type ErrorContext, PcoError } from './error-handling';
-import { PcoRateLimiter } from './rate-limiter';
+import { PcoRateLimiter } from '@rachelallyson/planning-center-base-ts';
 import { Paginated, ResourceObject, Response as JsonApiResponse } from './types';
 import { type TokenRefreshCallback, type TokenRefreshFailureCallback } from './auth';
 export interface PcoClientConfig {
@@ -36,7 +36,7 @@ export interface PcoClientConfig {
         onRetry?: (error: PcoError, attempt: number) => void;
     };
 }
-export { PcoApiError } from './api-error';
+export { PcoApiError } from '@rachelallyson/planning-center-base-ts';
 export interface PcoClientState {
     config: PcoClientConfig;
     rateLimiter: PcoRateLimiter;
@@ -72,4 +72,4 @@ export declare function getAllPages<T extends ResourceObject<string, any, any>>(
 /**
  * Get rate limit information
  */
-export declare function getRateLimitInfo(client: PcoClientState): import("./rate-limiter").RateLimitInfo;
+export declare function getRateLimitInfo(client: PcoClientState): import("@rachelallyson/planning-center-base-ts").RateLimitInfo;

package/dist/core.js

@@ -10,11 +10,11 @@ exports.del = del;
 exports.getAllPages = getAllPages;
 exports.getRateLimitInfo = getRateLimitInfo;
 const error_handling_1 = require("./error-handling");
-const rate_limiter_1 = require("./rate-limiter");
+const planning_center_base_ts_1 = require("@rachelallyson/planning-center-base-ts");
 const auth_1 = require("./auth");
 // Re-export PcoApiError for convenience
-var api_error_1 = require("./api-error");
-Object.defineProperty(exports, "PcoApiError", { enumerable: true, get: function () { return api_error_1.PcoApiError; } });
+var planning_center_base_ts_2 = require("@rachelallyson/planning-center-base-ts");
+Object.defineProperty(exports, "PcoApiError", { enumerable: true, get: function () { return planning_center_base_ts_2.PcoApiError; } });
 // ===== Core PCO Client Functions =====
 /**
  * Create a PCO client state
@@ -25,7 +25,7 @@ function createPcoClient(config) {
         maxRequests: 100,
         perMilliseconds: 20000, // 20 seconds
     };
-    const rateLimiter = new rate_limiter_1.PcoRateLimiter(rateLimitConfig.maxRequests, rateLimitConfig.perMilliseconds);
+    const rateLimiter = new planning_center_base_ts_1.PcoRateLimiter(rateLimitConfig.maxRequests, rateLimitConfig.perMilliseconds);
     return {
         config,
         rateLimiter,

package/dist/error-handling.d.ts

@@ -1,4 +1,4 @@
-import { PcoApiError } from './api-error';
+import { PcoApiError } from '@rachelallyson/planning-center-base-ts';
 import type { ErrorObject as JsonApiError } from './types';
 export declare enum ErrorCategory {
     EXTERNAL_API = "external_api",

package/dist/error-handling.js

@@ -7,7 +7,7 @@ exports.withErrorBoundary = withErrorBoundary;
 exports.handleValidationError = handleValidationError;
 exports.handleTimeoutError = handleTimeoutError;
 exports.handleNetworkError = handleNetworkError;
-const api_error_1 = require("./api-error");
+const planning_center_base_ts_1 = require("@rachelallyson/planning-center-base-ts");
 // Error categories for better monitoring
 var ErrorCategory;
 (function (ErrorCategory) {
@@ -29,7 +29,7 @@ var ErrorSeverity;
     ErrorSeverity["CRITICAL"] = "critical";
 })(ErrorSeverity || (exports.ErrorSeverity = ErrorSeverity = {}));
 // Enhanced PCO API Error with additional context
-class PcoError extends api_error_1.PcoApiError {
+class PcoError extends planning_center_base_ts_1.PcoApiError {
     constructor(message, status, statusText, errors, rateLimitHeaders, context = {}) {
         super(message, status, statusText, errors, rateLimitHeaders);
         this.name = 'PcoError';
@@ -170,7 +170,7 @@ function shouldNotRetry(error) {
     if (error instanceof PcoError) {
         return !error.shouldRetry();
     }
-    if (error instanceof api_error_1.PcoApiError) {
+    if (error instanceof planning_center_base_ts_1.PcoApiError) {
         // Don't retry authentication, authorization, or validation errors
         return (error.status === 401 ||
             error.status === 403 ||

package/dist/error-scenarios.js

@@ -13,7 +13,7 @@ exports.withTimeout = withTimeout;
 exports.classifyError = classifyError;
 exports.attemptRecovery = attemptRecovery;
 exports.createErrorReport = createErrorReport;
-const api_error_1 = require("./api-error");
+const planning_center_base_ts_1 = require("@rachelallyson/planning-center-base-ts");
 exports.DEFAULT_RETRY_CONFIG = {
     backoffFactor: 2,
     baseDelay: 1000,
@@ -52,7 +52,7 @@ async function retryWithExponentialBackoff(operation, config = {}) {
  * Check if an error is retryable
  */
 function isRetryableError(error, retryableStatuses) {
-    if (error instanceof api_error_1.PcoApiError) {
+    if (error instanceof planning_center_base_ts_1.PcoApiError) {
         return retryableStatuses.includes(error.status);
     }
     // Network errors are generally retryable
@@ -195,7 +195,7 @@ exports.TIMEOUT_CONFIG = {
  * Classify errors for appropriate handling
  */
 function classifyError(error) {
-    if (error instanceof api_error_1.PcoApiError) {
+    if (error instanceof planning_center_base_ts_1.PcoApiError) {
         return classifyPcoError(error);
     }
     if (error.name === 'TypeError' && error.message.includes('fetch')) {
@@ -300,7 +300,7 @@ async function attemptRecovery(operation, error, context) {
     }
     // Rate limit recovery
     if (classification.category === 'rate_limit' &&
-        error instanceof api_error_1.PcoApiError) {
+        error instanceof planning_center_base_ts_1.PcoApiError) {
         const retryAfter = error.rateLimitHeaders?.['Retry-After'];
         if (retryAfter) {
             const delay = parseInt(retryAfter) * 1000;

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { PcoClient } from './client';
 export { PcoClientManager } from './client-manager';
 export type { PcoClientConfig, PcoAuthConfig, PersonalAccessTokenAuth, OAuthAuth } from './types/client';
-export type { PcoEvent, EventHandler, EventType } from './types/events';
-export type { BatchOperation, BatchResult, BatchOptions, BatchSummary } from './types/batch';
-export type { Paginated, Relationship, ResourceIdentifier, ResourceObject, } from './types';
+export type { PcoEvent, EventHandler, EventType } from '@rachelallyson/planning-center-base-ts';
+export type { BatchOperation, BatchResult, BatchOptions, BatchSummary } from '@rachelallyson/planning-center-base-ts';
+export type { Paginated, Relationship, ResourceIdentifier, ResourceObject, } from '@rachelallyson/planning-center-base-ts';
 export type { PersonResource, PersonAttributes, PersonSingle, PeopleList, EmailResource, EmailAttributes, PhoneNumberResource, PhoneNumberAttributes, AddressResource, AddressAttributes, SocialProfileResource, SocialProfileAttributes, } from './types';
 export type { FieldDefinitionResource, FieldDefinitionAttributes, FieldDatumResource, FieldDatumAttributes, FieldOptionResource, FieldOptionAttributes, TabResource, TabAttributes, } from './types';
 export type { WorkflowResource, WorkflowAttributes, WorkflowCardResource, WorkflowCardAttributes, WorkflowCardNoteResource, WorkflowCardNoteAttributes, } from './types';
@@ -13,11 +13,11 @@ export type { PcoClientConfig as PcoClientConfigV1, PcoClientState } from './cor
 export { createPcoClient, del, getAllPages, getList, getRateLimitInfo, getSingle, patch, post, } from './core';
 export type { TokenResponse, TokenRefreshCallback, TokenRefreshFailureCallback } from './auth';
 export { attemptTokenRefresh, hasRefreshTokenCapability, refreshAccessToken, updateClientTokens, } from './auth';
-export { PcoApiError } from './api-error';
-export type { RateLimitHeaders, RateLimitInfo } from './rate-limiter';
-export { PcoRateLimiter } from './rate-limiter';
-export type { ErrorContext } from './error-handling';
-export { ErrorCategory, ErrorSeverity, handleNetworkError, handleTimeoutError, handleValidationError, PcoError, retryWithBackoff, shouldNotRetry, withErrorBoundary, } from './error-handling';
+export { PcoApiError } from '@rachelallyson/planning-center-base-ts';
+export type { RateLimitHeaders, RateLimitInfo } from '@rachelallyson/planning-center-base-ts';
+export { PcoRateLimiter } from '@rachelallyson/planning-center-base-ts';
+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';

package/dist/index.js

@@ -41,21 +41,21 @@ Object.defineProperty(exports, "attemptTokenRefresh", { enumerable: true, get: f
 Object.defineProperty(exports, "hasRefreshTokenCapability", { enumerable: true, get: function () { return auth_1.hasRefreshTokenCapability; } });
 Object.defineProperty(exports, "refreshAccessToken", { enumerable: true, get: function () { return auth_1.refreshAccessToken; } });
 Object.defineProperty(exports, "updateClientTokens", { enumerable: true, get: function () { return auth_1.updateClientTokens; } });
-// Export API error
-var api_error_1 = require("./api-error");
-Object.defineProperty(exports, "PcoApiError", { enumerable: true, get: function () { return api_error_1.PcoApiError; } });
-var rate_limiter_1 = require("./rate-limiter");
-Object.defineProperty(exports, "PcoRateLimiter", { enumerable: true, get: function () { return rate_limiter_1.PcoRateLimiter; } });
-var error_handling_1 = require("./error-handling");
-Object.defineProperty(exports, "ErrorCategory", { enumerable: true, get: function () { return error_handling_1.ErrorCategory; } });
-Object.defineProperty(exports, "ErrorSeverity", { enumerable: true, get: function () { return error_handling_1.ErrorSeverity; } });
-Object.defineProperty(exports, "handleNetworkError", { enumerable: true, get: function () { return error_handling_1.handleNetworkError; } });
-Object.defineProperty(exports, "handleTimeoutError", { enumerable: true, get: function () { return error_handling_1.handleTimeoutError; } });
-Object.defineProperty(exports, "handleValidationError", { enumerable: true, get: function () { return error_handling_1.handleValidationError; } });
-Object.defineProperty(exports, "PcoError", { enumerable: true, get: function () { return error_handling_1.PcoError; } });
-Object.defineProperty(exports, "retryWithBackoff", { enumerable: true, get: function () { return error_handling_1.retryWithBackoff; } });
-Object.defineProperty(exports, "shouldNotRetry", { enumerable: true, get: function () { return error_handling_1.shouldNotRetry; } });
-Object.defineProperty(exports, "withErrorBoundary", { enumerable: true, get: function () { return error_handling_1.withErrorBoundary; } });
+// Export API error (re-exported from base)
+var planning_center_base_ts_1 = require("@rachelallyson/planning-center-base-ts");
+Object.defineProperty(exports, "PcoApiError", { enumerable: true, get: function () { return planning_center_base_ts_1.PcoApiError; } });
+var planning_center_base_ts_2 = require("@rachelallyson/planning-center-base-ts");
+Object.defineProperty(exports, "PcoRateLimiter", { enumerable: true, get: function () { return planning_center_base_ts_2.PcoRateLimiter; } });
+var planning_center_base_ts_3 = require("@rachelallyson/planning-center-base-ts");
+Object.defineProperty(exports, "ErrorCategory", { enumerable: true, get: function () { return planning_center_base_ts_3.ErrorCategory; } });
+Object.defineProperty(exports, "ErrorSeverity", { enumerable: true, get: function () { return planning_center_base_ts_3.ErrorSeverity; } });
+Object.defineProperty(exports, "handleNetworkError", { enumerable: true, get: function () { return planning_center_base_ts_3.handleNetworkError; } });
+Object.defineProperty(exports, "handleTimeoutError", { enumerable: true, get: function () { return planning_center_base_ts_3.handleTimeoutError; } });
+Object.defineProperty(exports, "handleValidationError", { enumerable: true, get: function () { return planning_center_base_ts_3.handleValidationError; } });
+Object.defineProperty(exports, "PcoError", { enumerable: true, get: function () { return planning_center_base_ts_3.PcoError; } });
+Object.defineProperty(exports, "retryWithBackoff", { enumerable: true, get: function () { return planning_center_base_ts_3.retryWithBackoff; } });
+Object.defineProperty(exports, "shouldNotRetry", { enumerable: true, get: function () { return planning_center_base_ts_3.shouldNotRetry; } });
+Object.defineProperty(exports, "withErrorBoundary", { enumerable: true, get: function () { return planning_center_base_ts_3.withErrorBoundary; } });
 // Export People-specific functions (deprecated)
 var people_1 = require("./people");
 Object.defineProperty(exports, "createFieldDefinition", { enumerable: true, get: function () { return people_1.createFieldDefinition; } });

package/dist/matching/matcher.d.ts

@@ -8,6 +8,7 @@ export interface MatchResult {
     person: PersonResource;
     score: number;
     reason: string;
+    isVerifiedContactMatch?: boolean;
 }
 export declare class PersonMatcher {
     private peopleModule;
@@ -16,6 +17,14 @@ export declare class PersonMatcher {
     constructor(peopleModule: PeopleModule);
     /**
      * Find or create a person with smart matching
+     *
+     * Uses intelligent matching logic that:
+     * - 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)
+     *
+     * @param options - Matching options
+     * @param options.addMissingContactInfo - If true, automatically adds missing email/phone to matched person's profile
      */
     findOrCreate(options: PersonMatchOptions): Promise<PersonResource>;
     /**
@@ -24,8 +33,21 @@ export declare class PersonMatcher {
     findMatch(options: PersonMatchOptions): Promise<MatchResult | null>;
     /**
      * Get potential matching candidates
+     * @deprecated Use findMatch which has improved logic for separating verified matches from name-only matches
      */
     private getCandidates;
+    /**
+     * Verify if a person's email actually matches the search email
+     */
+    private verifyEmailMatch;
+    /**
+     * Verify if a person's phone actually matches the search phone
+     */
+    private verifyPhoneMatch;
+    /**
+     * Add missing contact information to a person's profile
+     */
+    private addMissingContactInfo;
     /**
      * Filter candidates by age preferences
      */