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

package/dist/index.d.ts

@@ -1,14 +1,26 @@
+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';
 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 { createFieldOption, createPerson, createPersonAddress, createPersonEmail, createPersonFieldData, createPersonFileFieldData, createPersonPhoneNumber, createPersonSocialProfile, createWorkflowCard, createWorkflowCardNote, deletePerson, deletePersonFieldData, getFieldDefinitions, getFieldOptions, getHousehold, getHouseholds, 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, WorkflowCardNoteRelationships, WorkflowCardNoteResource, WorkflowCardNoteSingle, WorkflowCardNotesList, WorkflowCardRelationships, WorkflowCardResource, WorkflowCardSingle, WorkflowCardsList, WorkflowResource, WorkflowSingle, WorkflowsList, } from './types';
+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 { calculateAge, createPersonWithContact, createWorkflowCardWithNote, exportAllPeopleData, formatDate, formatPersonName, getCompletePersonProfile, getListsWithCategories, getOrganizationInfo, getPeopleByHousehold, getPersonWorkflowCardsWithNotes, getPrimaryContact, isValidEmail, isValidPhone, 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, 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,9 +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.getWorkflow = exports.getPersonSocialProfiles = exports.getPersonPhoneNumbers = exports.getPersonFieldData = exports.getPersonEmails = exports.getPersonAddresses = exports.getPerson = exports.getPeople = exports.getOrganization = exports.getNotes = exports.getNoteCategories = exports.getNote = exports.getLists = exports.getListCategories = exports.getListById = exports.getHouseholds = exports.getHousehold = exports.getFieldOptions = exports.getFieldDefinitions = exports.deletePersonFieldData = exports.deletePerson = exports.createWorkflowCardNote = exports.createWorkflowCard = exports.createPersonSocialProfile = exports.createPersonPhoneNumber = exports.createPersonFileFieldData = exports.createPersonFieldData = exports.createPersonEmail = exports.createPersonAddress = exports.createPerson = exports.createFieldOption = exports.withErrorBoundary = exports.shouldNotRetry = exports.retryWithBackoff = exports.PcoError = exports.handleValidationError = exports.handleTimeoutError = exports.handleNetworkError = exports.ErrorSeverity = exports.ErrorCategory = exports.PcoRateLimiter = exports.PcoApiError = exports.post = exports.patch = exports.getSingle = exports.getRateLimitInfo = exports.getList = exports.getAllPages = exports.del = exports.createPcoClient = void 0;
-exports.streamPeopleData = exports.processLargeDataset = exports.processInBatches = exports.PerformanceMonitor = exports.monitorPerformance = exports.getCachedPeople = exports.fetchAllPages = exports.batchFetchPersonDetails = exports.ApiCache = exports.AdaptiveRateLimiter = exports.validatePersonData = exports.searchPeople = exports.isValidPhone = exports.isValidEmail = exports.getPrimaryContact = exports.getPersonWorkflowCardsWithNotes = exports.getPeopleByHousehold = exports.getOrganizationInfo = exports.getListsWithCategories = exports.getCompletePersonProfile = exports.formatPersonName = exports.formatDate = exports.exportAllPeopleData = exports.createWorkflowCardWithNote = exports.createPersonWithContact = exports.calculateAge = 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 = 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; } });
@@ -27,6 +36,11 @@ Object.defineProperty(exports, "getRateLimitInfo", { enumerable: true, get: func
 Object.defineProperty(exports, "getSingle", { enumerable: true, get: function () { return core_1.getSingle; } });
 Object.defineProperty(exports, "patch", { enumerable: true, get: function () { return core_1.patch; } });
 Object.defineProperty(exports, "post", { enumerable: true, get: function () { return core_1.post; } });
+var auth_1 = require("./auth");
+Object.defineProperty(exports, "attemptTokenRefresh", { enumerable: true, get: function () { return auth_1.attemptTokenRefresh; } });
+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; } });
@@ -42,24 +56,27 @@ 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; } });
 Object.defineProperty(exports, "createPerson", { enumerable: true, get: function () { return people_1.createPerson; } });
 Object.defineProperty(exports, "createPersonAddress", { enumerable: true, get: function () { return people_1.createPersonAddress; } });
 Object.defineProperty(exports, "createPersonEmail", { enumerable: true, get: function () { return people_1.createPersonEmail; } });
 Object.defineProperty(exports, "createPersonFieldData", { enumerable: true, get: function () { return people_1.createPersonFieldData; } });
-Object.defineProperty(exports, "createPersonFileFieldData", { enumerable: true, get: function () { return people_1.createPersonFileFieldData; } });
 Object.defineProperty(exports, "createPersonPhoneNumber", { enumerable: true, get: function () { return people_1.createPersonPhoneNumber; } });
 Object.defineProperty(exports, "createPersonSocialProfile", { enumerable: true, get: function () { return people_1.createPersonSocialProfile; } });
 Object.defineProperty(exports, "createWorkflowCard", { enumerable: true, get: function () { return people_1.createWorkflowCard; } });
 Object.defineProperty(exports, "createWorkflowCardNote", { enumerable: true, get: function () { return people_1.createWorkflowCardNote; } });
+Object.defineProperty(exports, "deleteFieldDefinition", { enumerable: true, get: function () { return people_1.deleteFieldDefinition; } });
 Object.defineProperty(exports, "deletePerson", { enumerable: true, get: function () { return people_1.deletePerson; } });
 Object.defineProperty(exports, "deletePersonFieldData", { enumerable: true, get: function () { return people_1.deletePersonFieldData; } });
+Object.defineProperty(exports, "deleteSocialProfile", { enumerable: true, get: function () { return people_1.deleteSocialProfile; } });
 Object.defineProperty(exports, "getFieldDefinitions", { enumerable: true, get: function () { return people_1.getFieldDefinitions; } });
 Object.defineProperty(exports, "getFieldOptions", { enumerable: true, get: function () { return people_1.getFieldOptions; } });
 Object.defineProperty(exports, "getHousehold", { enumerable: true, get: function () { return people_1.getHousehold; } });
 Object.defineProperty(exports, "getHouseholds", { enumerable: true, get: function () { return people_1.getHouseholds; } });
+Object.defineProperty(exports, "getTabs", { enumerable: true, get: function () { return people_1.getTabs; } });
 Object.defineProperty(exports, "getListById", { enumerable: true, get: function () { return people_1.getListById; } });
 Object.defineProperty(exports, "getListCategories", { enumerable: true, get: function () { return people_1.getListCategories; } });
 Object.defineProperty(exports, "getLists", { enumerable: true, get: function () { return people_1.getLists; } });
@@ -93,20 +110,27 @@ Object.defineProperty(exports, "TIMEOUT_CONFIG", { enumerable: true, get: functi
 Object.defineProperty(exports, "withTimeout", { enumerable: true, get: function () { return error_scenarios_1.withTimeout; } });
 // ===== Helper Functions =====
 var helpers_1 = require("./helpers");
+Object.defineProperty(exports, "buildQueryParams", { enumerable: true, get: function () { return helpers_1.buildQueryParams; } });
 Object.defineProperty(exports, "calculateAge", { enumerable: true, get: function () { return helpers_1.calculateAge; } });
 Object.defineProperty(exports, "createPersonWithContact", { enumerable: true, get: function () { return helpers_1.createPersonWithContact; } });
 Object.defineProperty(exports, "createWorkflowCardWithNote", { enumerable: true, get: function () { return helpers_1.createWorkflowCardWithNote; } });
 Object.defineProperty(exports, "exportAllPeopleData", { enumerable: true, get: function () { return helpers_1.exportAllPeopleData; } });
+Object.defineProperty(exports, "extractFileUrl", { enumerable: true, get: function () { return helpers_1.extractFileUrl; } });
 Object.defineProperty(exports, "formatDate", { enumerable: true, get: function () { return helpers_1.formatDate; } });
 Object.defineProperty(exports, "formatPersonName", { enumerable: true, get: function () { return helpers_1.formatPersonName; } });
 Object.defineProperty(exports, "getCompletePersonProfile", { enumerable: true, get: function () { return helpers_1.getCompletePersonProfile; } });
+Object.defineProperty(exports, "getFileExtension", { enumerable: true, get: function () { return helpers_1.getFileExtension; } });
+Object.defineProperty(exports, "getFilename", { enumerable: true, get: function () { return helpers_1.getFilename; } });
 Object.defineProperty(exports, "getListsWithCategories", { enumerable: true, get: function () { return helpers_1.getListsWithCategories; } });
 Object.defineProperty(exports, "getOrganizationInfo", { enumerable: true, get: function () { return helpers_1.getOrganizationInfo; } });
 Object.defineProperty(exports, "getPeopleByHousehold", { enumerable: true, get: function () { return helpers_1.getPeopleByHousehold; } });
 Object.defineProperty(exports, "getPersonWorkflowCardsWithNotes", { enumerable: true, get: function () { return helpers_1.getPersonWorkflowCardsWithNotes; } });
 Object.defineProperty(exports, "getPrimaryContact", { enumerable: true, get: function () { return helpers_1.getPrimaryContact; } });
+Object.defineProperty(exports, "isFileUpload", { enumerable: true, get: function () { return helpers_1.isFileUpload; } });
+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, "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; } });
 // ===== Performance Optimization =====
@@ -121,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;
+}

package/dist/matching/strategies.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * v2.0.0 Person Matching Strategies
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MatchStrategies = void 0;
+class MatchStrategies {
+    /**
+     * Select the best match based on strategy
+     */
+    selectBestMatch(candidates, strategy) {
+        if (candidates.length === 0) {
+            return null;
+        }
+        switch (strategy) {
+            case 'exact':
+                return this.selectExactMatch(candidates);
+            case 'fuzzy':
+                return this.selectFuzzyMatch(candidates);
+            case 'aggressive':
+                return this.selectAggressiveMatch(candidates);
+            default:
+                return this.selectFuzzyMatch(candidates);
+        }
+    }
+    /**
+     * Exact matching strategy - only return matches with very high confidence
+     */
+    selectExactMatch(candidates) {
+        // Only return matches with score >= 0.9
+        const exactMatches = candidates.filter(c => c.score >= 0.9);
+        return exactMatches.length > 0 ? exactMatches[0] : null;
+    }
+    /**
+     * Fuzzy matching strategy - return best match above threshold
+     */
+    selectFuzzyMatch(candidates) {
+        // Return best match with score >= 0.7
+        const fuzzyMatches = candidates.filter(c => c.score >= 0.7);
+        return fuzzyMatches.length > 0 ? fuzzyMatches[0] : null;
+    }
+    /**
+     * Aggressive matching strategy - return best match with lower threshold
+     */
+    selectAggressiveMatch(candidates) {
+        // Return best match with score >= 0.5
+        const aggressiveMatches = candidates.filter(c => c.score >= 0.5);
+        return aggressiveMatches.length > 0 ? aggressiveMatches[0] : null;
+    }
+    /**
+     * Get all matches above threshold for a strategy
+     */
+    getAllMatchesAboveThreshold(candidates, strategy) {
+        const threshold = this.getThreshold(strategy);
+        return candidates.filter(c => c.score >= threshold);
+    }
+    /**
+     * Get the threshold for a strategy
+     */
+    getThreshold(strategy) {
+        switch (strategy) {
+            case 'exact':
+                return 0.9;
+            case 'fuzzy':
+                return 0.7;
+            case 'aggressive':
+                return 0.5;
+            default:
+                return 0.7;
+        }
+    }
+    /**
+     * Check if a score meets the strategy threshold
+     */
+    meetsThreshold(score, strategy) {
+        return score >= this.getThreshold(strategy);
+    }
+}
+exports.MatchStrategies = MatchStrategies;