@rachelallyson/planning-center-people-ts 1.1.0 → 2.0.0

package/dist/core/pagination.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * v2.0.0 Pagination Utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginationHelper = void 0;
+class PaginationHelper {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async getAllPages(endpoint, params = {}, options = {}) {
+        // Ensure endpoint is a string
+        if (typeof endpoint !== 'string') {
+            throw new Error(`Expected endpoint to be a string, got ${typeof endpoint}`);
+        }
+        const { maxPages = 1000, perPage = 100, onProgress, delay = 50, } = options;
+        const startTime = Date.now();
+        const allData = [];
+        let page = 1;
+        let hasMore = true;
+        let totalCount = 0;
+        while (hasMore && page <= maxPages) {
+            const response = await this.httpClient.request({
+                method: 'GET',
+                endpoint,
+                params: {
+                    ...params,
+                    page,
+                    per_page: perPage,
+                },
+            });
+            if (response.data.data && Array.isArray(response.data.data)) {
+                allData.push(...response.data.data);
+            }
+            if (response.data.meta?.total_count) {
+                totalCount = Number(response.data.meta.total_count) || 0;
+            }
+            hasMore = !!response.data.links?.next;
+            page++;
+            if (onProgress) {
+                onProgress(allData.length, totalCount || allData.length);
+            }
+            // Add delay between requests to respect rate limits
+            if (hasMore && delay > 0) {
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+        return {
+            data: allData,
+            totalCount,
+            pagesFetched: page - 1,
+            duration: Date.now() - startTime,
+        };
+    }
+    async getPage(endpoint, page = 1, perPage = 100, params = {}) {
+        const response = await this.httpClient.request({
+            method: 'GET',
+            endpoint,
+            params: {
+                ...params,
+                page,
+                per_page: perPage,
+            },
+        });
+        return response.data;
+    }
+    async *streamPages(endpoint, params = {}, options = {}) {
+        const { maxPages = 1000, perPage = 100, delay = 50, } = options;
+        let page = 1;
+        let hasMore = true;
+        while (hasMore && page <= maxPages) {
+            const response = await this.httpClient.request({
+                method: 'GET',
+                endpoint,
+                params: {
+                    ...params,
+                    page,
+                    per_page: perPage,
+                },
+            });
+            if (response.data.data && Array.isArray(response.data.data)) {
+                yield response.data.data;
+            }
+            hasMore = !!response.data.links?.next;
+            page++;
+            if (hasMore && delay > 0) {
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+    }
+    /**
+     * Get all pages with parallel processing for better performance
+     */
+    async getAllPagesParallel(endpoint, params = {}, options = {}) {
+        const { maxPages = 1000, perPage = 100, maxConcurrency = 3, onProgress, } = options;
+        const startTime = Date.now();
+        // First, get the first page to determine total count
+        const firstPage = await this.getPage(endpoint, 1, perPage, params);
+        const totalCount = Number(firstPage.meta?.total_count) || 0;
+        const totalPages = Math.min(Math.ceil(totalCount / perPage), maxPages);
+        const allData = [...(firstPage.data || [])];
+        if (totalPages <= 1) {
+            return {
+                data: allData,
+                totalCount,
+                pagesFetched: 1,
+                duration: Date.now() - startTime,
+            };
+        }
+        // Process remaining pages in parallel batches
+        const remainingPages = Array.from({ length: totalPages - 1 }, (_, i) => i + 2);
+        const semaphore = new Semaphore(maxConcurrency);
+        const pagePromises = remainingPages.map(async (pageNum) => {
+            await semaphore.acquire();
+            try {
+                const page = await this.getPage(endpoint, pageNum, perPage, params);
+                return page.data || [];
+            }
+            finally {
+                semaphore.release();
+            }
+        });
+        const pageResults = await Promise.all(pagePromises);
+        for (const pageData of pageResults) {
+            allData.push(...pageData);
+            if (onProgress) {
+                onProgress(allData.length, totalCount);
+            }
+        }
+        return {
+            data: allData,
+            totalCount,
+            pagesFetched: totalPages,
+            duration: Date.now() - startTime,
+        };
+    }
+}
+exports.PaginationHelper = PaginationHelper;
+/**
+ * Semaphore for controlling concurrency
+ */
+class Semaphore {
+    constructor(permits) {
+        this.waiting = [];
+        this.permits = permits;
+    }
+    async acquire() {
+        if (this.permits > 0) {
+            this.permits--;
+            return;
+        }
+        return new Promise(resolve => {
+            this.waiting.push(resolve);
+        });
+    }
+    release() {
+        this.permits++;
+        if (this.waiting.length > 0) {
+            const resolve = this.waiting.shift();
+            this.permits--;
+            resolve();
+        }
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,15 @@
+export { PcoClient } from './client';
+export { PcoClientManager } from './client-manager';
+export type { PcoClientConfig } 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 { 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';
+export type { HouseholdResource, HouseholdAttributes, NoteResource, NoteAttributes, ListResource, ListAttributes, OrganizationResource, OrganizationAttributes, } from './types';
 export * from './types';
-export type { PcoClientConfig, PcoClientState } from './core';
+export type { PcoClientConfig as PcoClientConfigV1, PcoClientState } from './core';
 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';
@@ -9,8 +19,8 @@ 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 { 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 type { Paginated, Relationship, ResourceIdentifier, ResourceObject, } from './types';
-export type { AddressAttributes, AddressesList, AddressResource, AddressSingle, EmailAttributes, EmailResource, EmailSingle, EmailsList, FieldDataList, FieldDataSingle, FieldDatumAttributes, FieldDatumRelationships, FieldDatumResource, FieldDefinitionAttributes, FieldDefinitionResource, FieldDefinitionSingle, FieldDefinitionsList, FieldOptionAttributes, FieldOptionResource, FieldOptionSingle, FieldOptionsList, HouseholdAttributes, HouseholdResource, HouseholdSingle, HouseholdsList, ListAttributes, ListCategoriesList, ListCategoryAttributes, ListCategoryResource, ListCategorySingle, ListResource, ListSingle, ListsList, NoteAttributes, NoteCategoriesList, NoteCategoryAttributes, NoteCategoryResource, NoteCategorySingle, NoteResource, NoteSingle, NotesList, OrganizationAttributes, OrganizationResource, OrganizationSingle, PeopleList, PersonAttributes, PersonRelationships, PersonResource, PersonSingle, PhoneNumberAttributes, PhoneNumberResource, PhoneNumberSingle, PhoneNumbersList, SocialProfileAttributes, SocialProfileResource, SocialProfileSingle, SocialProfilesList, WorkflowAttributes, WorkflowCardAttributes, WorkflowCardNoteAttributes, WorkflowCardNoteResource, WorkflowCardNoteSingle, WorkflowCardNotesList, WorkflowCardRelationships, WorkflowCardResource, WorkflowCardSingle, WorkflowCardsList, WorkflowResource, WorkflowSingle, WorkflowsList, } from './types';
 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 { 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

@@ -1,4 +1,5 @@
 "use strict";
+// ===== v2.0.0 Main Exports =====
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -14,10 +15,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPeople = exports.getOrganization = 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 = void 0;
-exports.monitorPerformance = exports.getCachedPeople = 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 = void 0;
-exports.streamPeopleData = exports.processLargeDataset = exports.processInBatches = exports.PerformanceMonitor = void 0;
-// Export all types
+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;
+// Main client class
+var client_1 = require("./client");
+Object.defineProperty(exports, "PcoClient", { enumerable: true, get: function () { return client_1.PcoClient; } });
+// Client manager for caching and lifecycle management
+var client_manager_1 = require("./client-manager");
+Object.defineProperty(exports, "PcoClientManager", { enumerable: true, get: function () { return client_manager_1.PcoClientManager; } });
+// ===== v1.x Compatibility Exports (Deprecated) =====
+// Export all types for backward compatibility
 __exportStar(require("./types"), exports);
 var core_1 = require("./core");
 Object.defineProperty(exports, "createPcoClient", { enumerable: true, get: function () { return core_1.createPcoClient; } });
@@ -48,7 +56,7 @@ Object.defineProperty(exports, "PcoError", { enumerable: true, get: function ()
 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 People-specific functions
+// Export People-specific functions (deprecated)
 var people_1 = require("./people");
 Object.defineProperty(exports, "createFieldDefinition", { enumerable: true, get: function () { return people_1.createFieldDefinition; } });
 Object.defineProperty(exports, "createFieldOption", { enumerable: true, get: function () { return people_1.createFieldOption; } });
@@ -137,3 +145,13 @@ Object.defineProperty(exports, "PerformanceMonitor", { enumerable: true, get: fu
 Object.defineProperty(exports, "processInBatches", { enumerable: true, get: function () { return performance_1.processInBatches; } });
 Object.defineProperty(exports, "processLargeDataset", { enumerable: true, get: function () { return performance_1.processLargeDataset; } });
 Object.defineProperty(exports, "streamPeopleData", { enumerable: true, get: function () { return performance_1.streamPeopleData; } });
+// ===== Testing Utilities =====
+var testing_1 = require("./testing");
+Object.defineProperty(exports, "MockPcoClient", { enumerable: true, get: function () { return testing_1.MockPcoClient; } });
+Object.defineProperty(exports, "MockResponseBuilder", { enumerable: true, get: function () { return testing_1.MockResponseBuilder; } });
+Object.defineProperty(exports, "RequestRecorder", { enumerable: true, get: function () { return testing_1.RequestRecorder; } });
+Object.defineProperty(exports, "createMockClient", { enumerable: true, get: function () { return testing_1.createMockClient; } });
+Object.defineProperty(exports, "createRecordingClient", { enumerable: true, get: function () { return testing_1.createRecordingClient; } });
+Object.defineProperty(exports, "createTestClient", { enumerable: true, get: function () { return testing_1.createTestClient; } });
+Object.defineProperty(exports, "createErrorMockClient", { enumerable: true, get: function () { return testing_1.createErrorMockClient; } });
+Object.defineProperty(exports, "createSlowMockClient", { enumerable: true, get: function () { return testing_1.createSlowMockClient; } });

package/dist/matching/matcher.d.ts

@@ -0,0 +1,41 @@
+/**
+ * v2.0.0 Person Matching Logic
+ */
+import type { PeopleModule } from '../modules/people';
+import type { PersonResource } from '../types';
+import { PersonMatchOptions } from '../modules/people';
+export interface MatchResult {
+    person: PersonResource;
+    score: number;
+    reason: string;
+}
+export declare class PersonMatcher {
+    private peopleModule;
+    private strategies;
+    private scorer;
+    constructor(peopleModule: PeopleModule);
+    /**
+     * Find or create a person with smart matching
+     */
+    findOrCreate(options: PersonMatchOptions): Promise<PersonResource>;
+    /**
+     * Find the best match for a person
+     */
+    findMatch(options: PersonMatchOptions): Promise<MatchResult | null>;
+    /**
+     * Get potential matching candidates
+     */
+    private getCandidates;
+    /**
+     * Create a new person
+     */
+    private createPerson;
+    /**
+     * Get all potential matches with detailed scoring
+     */
+    getAllMatches(options: PersonMatchOptions): Promise<MatchResult[]>;
+    /**
+     * Check if a person matches the given criteria
+     */
+    isMatch(personId: string, options: PersonMatchOptions): Promise<MatchResult | null>;
+}

package/dist/matching/matcher.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * v2.0.0 Person Matching Logic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersonMatcher = void 0;
+const strategies_1 = require("./strategies");
+const scoring_1 = require("./scoring");
+class PersonMatcher {
+    constructor(peopleModule) {
+        this.peopleModule = peopleModule;
+        this.strategies = new strategies_1.MatchStrategies();
+        this.scorer = new scoring_1.MatchScorer();
+    }
+    /**
+     * Find or create a person with smart matching
+     */
+    async findOrCreate(options) {
+        const { createIfNotFound = true, matchStrategy = 'fuzzy', ...searchOptions } = options;
+        // Try to find existing person
+        const match = await this.findMatch({ ...searchOptions, matchStrategy });
+        if (match) {
+            return match.person;
+        }
+        // Create new person if not found and creation is enabled
+        if (createIfNotFound) {
+            return this.createPerson(options);
+        }
+        throw new Error(`No matching person found and creation is disabled`);
+    }
+    /**
+     * Find the best match for a person
+     */
+    async findMatch(options) {
+        const { matchStrategy = 'fuzzy' } = options;
+        // Get all potential matches
+        const candidates = await this.getCandidates(options);
+        if (candidates.length === 0) {
+            return null;
+        }
+        // Score and rank candidates
+        const scoredCandidates = candidates.map(candidate => ({
+            person: candidate,
+            score: this.scorer.scoreMatch(candidate, options),
+            reason: this.scorer.getMatchReason(candidate, options),
+        }));
+        // Sort by score (highest first)
+        scoredCandidates.sort((a, b) => b.score - a.score);
+        // Apply strategy-specific filtering
+        const bestMatch = this.strategies.selectBestMatch(scoredCandidates, matchStrategy);
+        return bestMatch;
+    }
+    /**
+     * Get potential matching candidates
+     */
+    async getCandidates(options) {
+        const candidates = [];
+        const { email, phone, firstName, lastName } = options;
+        // Strategy 1: Exact email match
+        if (email) {
+            try {
+                const emailMatches = await this.peopleModule.search({ email });
+                candidates.push(...emailMatches.data);
+            }
+            catch (error) {
+                // Email search failed, continue with other strategies
+            }
+        }
+        // Strategy 2: Exact phone match
+        if (phone) {
+            try {
+                const phoneMatches = await this.peopleModule.search({ phone });
+                candidates.push(...phoneMatches.data);
+            }
+            catch (error) {
+                // Phone search failed, continue with other strategies
+            }
+        }
+        // Strategy 3: Name-based search
+        if (firstName && lastName) {
+            try {
+                const nameMatches = await this.peopleModule.search({
+                    name: `${firstName} ${lastName}`
+                });
+                candidates.push(...nameMatches.data);
+            }
+            catch (error) {
+                // Name search failed, continue with other strategies
+            }
+        }
+        // Strategy 4: Broader search if no exact matches
+        if (candidates.length === 0 && (firstName || lastName)) {
+            try {
+                const broadMatches = await this.peopleModule.search({
+                    name: firstName || lastName || '',
+                });
+                candidates.push(...broadMatches.data);
+            }
+            catch (error) {
+                // Broad search failed
+            }
+        }
+        // Remove duplicates based on person ID
+        const uniqueCandidates = candidates.filter((person, index, self) => index === self.findIndex(p => p.id === person.id));
+        return uniqueCandidates;
+    }
+    /**
+     * Create a new person
+     */
+    async createPerson(options) {
+        const personData = {};
+        if (options.firstName)
+            personData.first_name = options.firstName;
+        if (options.lastName)
+            personData.last_name = options.lastName;
+        if (options.email)
+            personData.email = options.email;
+        if (options.phone)
+            personData.phone = options.phone;
+        const person = await this.peopleModule.create(personData);
+        // Add contact information if provided
+        const contacts = {};
+        if (options.email) {
+            contacts.email = { address: options.email, primary: true };
+        }
+        if (options.phone) {
+            contacts.phone = { number: options.phone, primary: true };
+        }
+        if (Object.keys(contacts).length > 0) {
+            await this.peopleModule.createWithContacts(personData, contacts);
+        }
+        return person;
+    }
+    /**
+     * Get all potential matches with detailed scoring
+     */
+    async getAllMatches(options) {
+        const candidates = await this.getCandidates(options);
+        return candidates.map(candidate => ({
+            person: candidate,
+            score: this.scorer.scoreMatch(candidate, options),
+            reason: this.scorer.getMatchReason(candidate, options),
+        })).sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Check if a person matches the given criteria
+     */
+    async isMatch(personId, options) {
+        const person = await this.peopleModule.getById(personId);
+        const score = this.scorer.scoreMatch(person, options);
+        if (score > 0.5) { // Threshold for considering it a match
+            return {
+                person,
+                score,
+                reason: this.scorer.getMatchReason(person, options),
+            };
+        }
+        return null;
+    }
+}
+exports.PersonMatcher = PersonMatcher;

package/dist/matching/scoring.d.ts

@@ -0,0 +1,35 @@
+/**
+ * v2.0.0 Person Match Scoring
+ */
+import type { PersonResource } from '../types';
+import type { PersonMatchOptions } from '../modules/people';
+export declare class MatchScorer {
+    /**
+     * Score a person match based on various criteria
+     */
+    scoreMatch(person: PersonResource, options: PersonMatchOptions): number;
+    /**
+     * Get a human-readable reason for the match
+     */
+    getMatchReason(person: PersonResource, options: PersonMatchOptions): string;
+    /**
+     * Score email matching
+     */
+    private scoreEmailMatch;
+    /**
+     * Score phone matching
+     */
+    private scorePhoneMatch;
+    /**
+     * Score name matching
+     */
+    private scoreNameMatch;
+    /**
+     * Score additional criteria
+     */
+    private scoreAdditionalCriteria;
+    /**
+     * Calculate string similarity using Levenshtein distance
+     */
+    private calculateStringSimilarity;
+}

package/dist/matching/scoring.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * v2.0.0 Person Match Scoring
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MatchScorer = void 0;
+class MatchScorer {
+    /**
+     * Score a person match based on various criteria
+     */
+    scoreMatch(person, options) {
+        let totalScore = 0;
+        let maxScore = 0;
+        // Email matching (highest weight)
+        if (options.email) {
+            const emailScore = this.scoreEmailMatch(person, options.email);
+            totalScore += emailScore * 0.4;
+            maxScore += 0.4;
+        }
+        // Phone matching (high weight)
+        if (options.phone) {
+            const phoneScore = this.scorePhoneMatch(person, options.phone);
+            totalScore += phoneScore * 0.3;
+            maxScore += 0.3;
+        }
+        // Name matching (medium weight)
+        if (options.firstName || options.lastName) {
+            const nameScore = this.scoreNameMatch(person, options);
+            totalScore += nameScore * 0.2;
+            maxScore += 0.2;
+        }
+        // Additional criteria (lower weight)
+        const additionalScore = this.scoreAdditionalCriteria(person, options);
+        totalScore += additionalScore * 0.1;
+        maxScore += 0.1;
+        return maxScore > 0 ? totalScore / maxScore : 0;
+    }
+    /**
+     * Get a human-readable reason for the match
+     */
+    getMatchReason(person, options) {
+        const reasons = [];
+        if (options.email && this.scoreEmailMatch(person, options.email) > 0.8) {
+            reasons.push('exact email match');
+        }
+        if (options.phone && this.scorePhoneMatch(person, options.phone) > 0.8) {
+            reasons.push('exact phone match');
+        }
+        if (options.firstName || options.lastName) {
+            const nameScore = this.scoreNameMatch(person, options);
+            if (nameScore > 0.8) {
+                reasons.push('exact name match');
+            }
+            else if (nameScore > 0.6) {
+                reasons.push('similar name match');
+            }
+        }
+        if (reasons.length === 0) {
+            return 'partial match';
+        }
+        return reasons.join(', ');
+    }
+    /**
+     * Score email matching
+     */
+    scoreEmailMatch(person, email) {
+        // This would need to check the person's emails
+        // For now, return a placeholder score
+        // In a real implementation, you'd fetch the person's emails and compare
+        return 0;
+    }
+    /**
+     * Score phone matching
+     */
+    scorePhoneMatch(person, phone) {
+        // This would need to check the person's phone numbers
+        // For now, return a placeholder score
+        // In a real implementation, you'd fetch the person's phone numbers and compare
+        return 0;
+    }
+    /**
+     * Score name matching
+     */
+    scoreNameMatch(person, options) {
+        const attrs = person.attributes;
+        if (!attrs)
+            return 0;
+        let score = 0;
+        // First name matching
+        if (options.firstName && attrs.first_name) {
+            const firstNameScore = this.calculateStringSimilarity(options.firstName.toLowerCase(), attrs.first_name.toLowerCase());
+            score += firstNameScore * 0.5;
+        }
+        // Last name matching
+        if (options.lastName && attrs.last_name) {
+            const lastNameScore = this.calculateStringSimilarity(options.lastName.toLowerCase(), attrs.last_name.toLowerCase());
+            score += lastNameScore * 0.5;
+        }
+        return score;
+    }
+    /**
+     * Score additional criteria
+     */
+    scoreAdditionalCriteria(person, options) {
+        // Add scoring for other criteria like campus, status, etc.
+        return 0;
+    }
+    /**
+     * Calculate string similarity using Levenshtein distance
+     */
+    calculateStringSimilarity(str1, str2) {
+        if (str1 === str2)
+            return 1;
+        if (str1.length === 0 || str2.length === 0)
+            return 0;
+        const matrix = [];
+        const len1 = str1.length;
+        const len2 = str2.length;
+        // Initialize matrix
+        for (let i = 0; i <= len1; i++) {
+            matrix[i] = [i];
+        }
+        for (let j = 0; j <= len2; j++) {
+            matrix[0][j] = j;
+        }
+        // Fill matrix
+        for (let i = 1; i <= len1; i++) {
+            for (let j = 1; j <= len2; j++) {
+                const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+                matrix[i][j] = Math.min(matrix[i - 1][j] + 1, // deletion
+                matrix[i][j - 1] + 1, // insertion
+                matrix[i - 1][j - 1] + cost // substitution
+                );
+            }
+        }
+        const distance = matrix[len1][len2];
+        const maxLength = Math.max(len1, len2);
+        return 1 - distance / maxLength;
+    }
+}
+exports.MatchScorer = MatchScorer;

package/dist/matching/strategies.d.ts

@@ -0,0 +1,35 @@
+/**
+ * v2.0.0 Person Matching Strategies
+ */
+import type { MatchResult } from './matcher';
+export type MatchStrategy = 'exact' | 'fuzzy' | 'aggressive';
+export declare class MatchStrategies {
+    /**
+     * Select the best match based on strategy
+     */
+    selectBestMatch(candidates: MatchResult[], strategy: MatchStrategy): MatchResult | null;
+    /**
+     * Exact matching strategy - only return matches with very high confidence
+     */
+    private selectExactMatch;
+    /**
+     * Fuzzy matching strategy - return best match above threshold
+     */
+    private selectFuzzyMatch;
+    /**
+     * Aggressive matching strategy - return best match with lower threshold
+     */
+    private selectAggressiveMatch;
+    /**
+     * Get all matches above threshold for a strategy
+     */
+    getAllMatchesAboveThreshold(candidates: MatchResult[], strategy: MatchStrategy): MatchResult[];
+    /**
+     * Get the threshold for a strategy
+     */
+    getThreshold(strategy: MatchStrategy): number;
+    /**
+     * Check if a score meets the strategy threshold
+     */
+    meetsThreshold(score: number, strategy: MatchStrategy): boolean;
+}