@rachelallyson/planning-center-people-ts 2.3.1 → 2.5.0

package/CHANGELOG.md

@@ -5,6 +5,185 @@ 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.5.0] - 2025-01-10
+
+### 🎯 **NEW FEATURES - Person Relationship Management & Token Refresh Fix**
+
+This release introduces comprehensive person relationship management endpoints and fixes critical token refresh issues, significantly enhancing the library's functionality and reliability.
+
+### Added
+
+#### **👥 Person Relationship Management**
+
+- **🏢 Campus Management**: Complete campus assignment and retrieval system
+  - `getPrimaryCampus(personId)` - Get person's current campus
+  - `setPrimaryCampus(personId, campusId)` - Assign/update person's campus
+  - `removePrimaryCampus(personId)` - Remove campus assignment
+  - `getByCampus(campusId, options)` - Get all people in a campus
+
+- **🏠 Household Management**: Full household membership system
+  - `getHousehold(personId)` - Get person's household
+  - `setHousehold(personId, householdId)` - Assign person to household
+  - `removeFromHousehold(personId)` - Remove person from household
+  - `getHouseholdMembers(householdId, options)` - Get all household members
+
+- **📋 Related Data Access**: Comprehensive access to person-related data
+  - `getWorkflowCards(personId, options)` - Get person's workflow cards
+  - `getNotes(personId, options)` - Get person's notes
+  - `getFieldData(personId, options)` - Get person's field data
+  - `getSocialProfiles(personId, options)` - Get person's social profiles
+
+#### **🔧 Enhanced Type System**
+
+- **📝 Complete PersonRelationships**: Updated interface with all available relationships
+- **🏷️ Type Safety**: Full TypeScript support for all relationship operations
+- **🛡️ Null Handling**: Proper handling of optional relationships
+- **📊 Resource Validation**: Enhanced relationship data validation
+
+#### **🔐 Token Refresh Fix**
+
+- **🚫 Fixed 401 Unauthorized**: Resolved token refresh failures by including client credentials
+- **🔑 Client Credentials Support**: Added support for `clientId` and `clientSecret` in OAuth config
+- **🌍 Environment Variables**: Support for `PCO_APP_ID` and `PCO_APP_SECRET` environment variables
+- **🔄 Standardized Implementation**: Consistent token refresh across all HTTP clients
+- **🛡️ Enhanced Error Handling**: Better error messages for token refresh failures
+
+### Fixed
+
+- **🔐 Token Refresh 401 Errors**: Fixed "Token refresh failed: 401 Unauthorized" by including required client credentials
+- **🏗️ Missing Auth Types**: Added missing `BasicAuth` type to v2.0.0 client configuration
+- **🔄 Inconsistent Implementations**: Standardized token refresh across `auth.ts` and `http.ts`
+- **📝 Type Definitions**: Enhanced `PersonRelationships` interface with all available relationships
+
+### Usage Examples
+
+```typescript
+// Campus Management
+const campus = await client.people.getPrimaryCampus('person-123');
+await client.people.setPrimaryCampus('person-123', 'campus-456');
+
+// Household Management
+const household = await client.people.getHousehold('person-123');
+await client.people.setHousehold('person-123', 'household-789');
+
+// Related Data Access
+const workflowCards = await client.people.getWorkflowCards('person-123');
+const notes = await client.people.getNotes('person-123');
+const fieldData = await client.people.getFieldData('person-123');
+
+// Token Refresh with Client Credentials
+const client = new PcoClient({
+    auth: {
+        type: 'oauth',
+        accessToken: 'your-token',
+        refreshToken: 'your-refresh-token',
+        clientId: 'your-app-id',        // NEW: Client credentials
+        clientSecret: 'your-app-secret', // NEW: Client credentials
+        onRefresh: async (tokens) => { /* handle refresh */ },
+        onRefreshFailure: async (error) => { /* handle failure */ }
+    }
+});
+```
+
+### Migration Guide
+
+**From Direct API Calls:**
+
+```typescript
+// Before: Complex direct API calls
+const response = await client.httpClient.request({
+    method: 'PATCH',
+    endpoint: `/people/${personId}`,
+    data: { /* complex JSON structure */ }
+});
+
+// After: Simple, intuitive methods
+await client.people.setPrimaryCampus(personId, campusId);
+```
+
+**Token Refresh Configuration:**
+
+```typescript
+// Add client credentials to your OAuth configuration
+const client = new PcoClient({
+    auth: {
+        type: 'oauth',
+        accessToken: 'your-token',
+        refreshToken: 'your-refresh-token',
+        clientId: process.env.PCO_APP_ID,        // NEW
+        clientSecret: process.env.PCO_APP_SECRET, // NEW
+        onRefresh: async (tokens) => { /* save tokens */ },
+        onRefreshFailure: async (error) => { /* handle failure */ }
+    }
+});
+```
+
+## [2.4.0] - 2025-01-10
+
+### 🎯 **NEW FEATURES - Age Preference Matching & Exact Name Matching**
+
+This release introduces intelligent age-based person matching and precise name matching capabilities to enhance person discovery and reduce false positives.
+
+### Added
+
+#### **👥 Age Preference Matching**
+
+- **🎂 Age-Based Filtering**: New `agePreference` option to prefer adults or children
+- **📅 Age Range Matching**: Support for `minAge` and `maxAge` parameters for precise age targeting
+- **🗓️ Birth Year Matching**: `birthYear` parameter for matching people born in specific years
+- **🧮 Smart Age Calculation**: Enhanced age calculation with timezone-safe date handling
+- **📊 Age-Based Scoring**: Age matching contributes 15% to overall match score for better accuracy
+
+#### **🎯 Exact Name Matching**
+
+- **✅ Precise Name Matching**: Only matches exact names, eliminating false positives from similar names
+- **🔤 Case-Insensitive**: Maintains case-insensitive matching while ensuring exact character matching
+- **⚡ Performance Optimized**: Simple string comparison for faster matching than fuzzy algorithms
+- **🛡️ Reduced False Positives**: Prevents matching "Jon" when searching for "John"
+
+#### **🔧 Enhanced Matching System**
+
+- **📈 Improved Scoring Algorithm**: Updated scoring weights for better match prioritization
+- **🎯 Candidate Filtering**: Age-based pre-filtering before scoring for more relevant results
+- **📝 Enhanced Match Reasons**: More descriptive match explanations including age-based reasons
+- **🧪 Comprehensive Testing**: 30+ new test cases covering age preferences and exact name matching
+
+### Usage Examples
+
+```typescript
+// Age preference matching
+const adultPerson = await client.people.findOrCreate({
+  firstName: 'Jane',
+  lastName: 'Smith',
+  agePreference: 'adults', // Prefer 18+ years old
+  matchStrategy: 'fuzzy'
+});
+
+// Age range matching
+const youngAdult = await client.people.findOrCreate({
+  firstName: 'Alice',
+  lastName: 'Brown',
+  minAge: 20,
+  maxAge: 30,
+  matchStrategy: 'fuzzy'
+});
+
+// Birth year matching
+const millennial = await client.people.findOrCreate({
+  firstName: 'David',
+  lastName: 'Wilson',
+  birthYear: 1990,
+  matchStrategy: 'fuzzy'
+});
+```
+
+### Technical Details
+
+- **New Helper Functions**: `calculateAgeSafe()`, `isAdult()`, `isChild()`, `matchesAgeCriteria()`
+- **Enhanced PersonMatchOptions**: Added `agePreference`, `minAge`, `maxAge`, `birthYear` properties
+- **Updated Scoring System**: Age matching now contributes 15% to overall match score
+- **Backward Compatibility**: All existing functionality remains unchanged
+
 ## [2.3.1] - 2025-01-10
 
 ### 🐛 **BUG FIXES & STABILITY IMPROVEMENTS**

package/dist/core/http.js

@@ -191,6 +191,11 @@ class PcoHttpClient {
         else if (this.config.auth.type === 'oauth') {
             headers.Authorization = `Bearer ${this.config.auth.accessToken}`;
         }
+        else if (this.config.auth.type === 'basic') {
+            // Basic auth with app credentials
+            const credentials = Buffer.from(`${this.config.auth.appId}:${this.config.auth.appSecret}`).toString('base64');
+            headers.Authorization = `Basic ${credentials}`;
+        }
     }
     getResourceTypeFromEndpoint(endpoint) {
         // Extract resource type from endpoint
@@ -224,18 +229,29 @@ class PcoHttpClient {
         }
         const baseURL = this.config.baseURL || 'https://api.planningcenteronline.com/people/v2';
         const tokenUrl = baseURL.replace('/people/v2', '/oauth/token');
+        // Prepare the request body for token refresh
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: this.config.auth.refreshToken,
+        });
+        // Add client credentials if available from the config or environment
+        const clientId = this.config.auth.clientId || process.env.PCO_APP_ID;
+        const clientSecret = this.config.auth.clientSecret || process.env.PCO_APP_SECRET;
+        if (clientId && clientSecret) {
+            body.append('client_id', clientId);
+            body.append('client_secret', clientSecret);
+        }
         const response = await fetch(tokenUrl, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/x-www-form-urlencoded',
+                'Accept': 'application/json',
             },
-            body: new URLSearchParams({
-                grant_type: 'refresh_token',
-                refresh_token: this.config.auth.refreshToken,
-            }),
+            body: body.toString(),
         });
         if (!response.ok) {
-            throw new Error(`Token refresh failed: ${response.status} ${response.statusText}`);
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(`Token refresh failed: ${response.status} ${response.statusText}. ${JSON.stringify(errorData)}`);
         }
         const tokens = await response.json();
         // Update the config with new tokens

package/dist/helpers.d.ts

@@ -15,6 +15,31 @@ export declare function buildQueryParams(params?: {
  * Calculate age from birthdate string
  */
 export declare function calculateAge(birthdate: string): number;
+/**
+ * Calculate age from birthdate string, handling invalid dates
+ */
+export declare function calculateAgeSafe(birthdate: string | undefined): number | null;
+/**
+ * Check if a person is an adult (18+ years old)
+ */
+export declare function isAdult(birthdate: string | undefined): boolean;
+/**
+ * Check if a person is a child (under 18 years old)
+ */
+export declare function isChild(birthdate: string | undefined): boolean;
+/**
+ * Check if a person's age matches the given criteria
+ */
+export declare function matchesAgeCriteria(birthdate: string | undefined, criteria: {
+    agePreference?: 'adults' | 'children' | 'any';
+    minAge?: number;
+    maxAge?: number;
+    birthYear?: number;
+}): boolean;
+/**
+ * Calculate birth year from age
+ */
+export declare function calculateBirthYearFromAge(age: number): number;
 /**
  * Validate email format
  */

package/dist/helpers.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildQueryParams = buildQueryParams;
 exports.calculateAge = calculateAge;
+exports.calculateAgeSafe = calculateAgeSafe;
+exports.isAdult = isAdult;
+exports.isChild = isChild;
+exports.matchesAgeCriteria = matchesAgeCriteria;
+exports.calculateBirthYearFromAge = calculateBirthYearFromAge;
 exports.isValidEmail = isValidEmail;
 exports.isValidPhone = isValidPhone;
 exports.formatPersonName = formatPersonName;
@@ -61,6 +66,70 @@ function calculateAge(birthdate) {
     }
     return age;
 }
+/**
+ * Calculate age from birthdate string, handling invalid dates
+ */
+function calculateAgeSafe(birthdate) {
+    if (!birthdate)
+        return null;
+    try {
+        const birth = new Date(birthdate);
+        if (isNaN(birth.getTime()))
+            return null;
+        return calculateAge(birthdate);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a person is an adult (18+ years old)
+ */
+function isAdult(birthdate) {
+    const age = calculateAgeSafe(birthdate);
+    return age !== null && age >= 18;
+}
+/**
+ * Check if a person is a child (under 18 years old)
+ */
+function isChild(birthdate) {
+    const age = calculateAgeSafe(birthdate);
+    return age !== null && age < 18;
+}
+/**
+ * Check if a person's age matches the given criteria
+ */
+function matchesAgeCriteria(birthdate, criteria) {
+    const age = calculateAgeSafe(birthdate);
+    // If no birthdate, only match if preference is 'any'
+    if (age === null) {
+        return criteria.agePreference === 'any' || criteria.agePreference === undefined;
+    }
+    // Check age preference
+    if (criteria.agePreference === 'adults' && age < 18)
+        return false;
+    if (criteria.agePreference === 'children' && age >= 18)
+        return false;
+    // Check age range
+    if (criteria.minAge !== undefined && age < criteria.minAge)
+        return false;
+    if (criteria.maxAge !== undefined && age > criteria.maxAge)
+        return false;
+    // Check birth year
+    if (criteria.birthYear !== undefined) {
+        const birthYear = new Date(birthdate).getFullYear();
+        if (birthYear !== criteria.birthYear)
+            return false;
+    }
+    return true;
+}
+/**
+ * Calculate birth year from age
+ */
+function calculateBirthYearFromAge(age) {
+    const currentYear = new Date().getFullYear();
+    return currentYear - age;
+}
 /**
  * Validate email format
  */

package/dist/matching/matcher.d.ts

@@ -26,6 +26,10 @@ export declare class PersonMatcher {
      * Get potential matching candidates
      */
     private getCandidates;
+    /**
+     * Filter candidates by age preferences
+     */
+    private filterByAgePreferences;
     /**
      * Create a new person
      */

package/dist/matching/matcher.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PersonMatcher = void 0;
 const strategies_1 = require("./strategies");
 const scoring_1 = require("./scoring");
+const helpers_1 = require("../helpers");
 class PersonMatcher {
     constructor(peopleModule) {
         this.peopleModule = peopleModule;
@@ -102,7 +103,30 @@ class PersonMatcher {
         }
         // Remove duplicates based on person ID
         const uniqueCandidates = candidates.filter((person, index, self) => index === self.findIndex(p => p.id === person.id));
-        return uniqueCandidates;
+        // Filter by age preferences if specified
+        const ageFilteredCandidates = this.filterByAgePreferences(uniqueCandidates, options);
+        return ageFilteredCandidates;
+    }
+    /**
+     * Filter candidates by age preferences
+     */
+    filterByAgePreferences(candidates, options) {
+        // If no age criteria specified, return all candidates
+        if (!options.agePreference &&
+            options.minAge === undefined &&
+            options.maxAge === undefined &&
+            options.birthYear === undefined) {
+            return candidates;
+        }
+        return candidates.filter(person => {
+            const birthdate = person.attributes?.birthdate;
+            return (0, helpers_1.matchesAgeCriteria)(birthdate, {
+                agePreference: options.agePreference,
+                minAge: options.minAge,
+                maxAge: options.maxAge,
+                birthYear: options.birthYear
+            });
+        });
     }
     /**
      * Create a new person

package/dist/matching/scoring.d.ts

@@ -21,9 +21,13 @@ export declare class MatchScorer {
      */
     private scorePhoneMatch;
     /**
-     * Score name matching
+     * Score name matching - only exact matches
      */
     private scoreNameMatch;
+    /**
+     * Score age matching
+     */
+    private scoreAgeMatch;
     /**
      * Score additional criteria
      */

package/dist/matching/scoring.js

@@ -4,6 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MatchScorer = void 0;
+const helpers_1 = require("../helpers");
 class MatchScorer {
     /**
      * Score a person match based on various criteria
@@ -14,14 +15,14 @@ class MatchScorer {
         // Email matching (highest weight)
         if (options.email) {
             const emailScore = this.scoreEmailMatch(person, options.email);
-            totalScore += emailScore * 0.4;
-            maxScore += 0.4;
+            totalScore += emailScore * 0.35;
+            maxScore += 0.35;
         }
         // Phone matching (high weight)
         if (options.phone) {
             const phoneScore = this.scorePhoneMatch(person, options.phone);
-            totalScore += phoneScore * 0.3;
-            maxScore += 0.3;
+            totalScore += phoneScore * 0.25;
+            maxScore += 0.25;
         }
         // Name matching (medium weight)
         if (options.firstName || options.lastName) {
@@ -29,10 +30,14 @@ class MatchScorer {
             totalScore += nameScore * 0.2;
             maxScore += 0.2;
         }
+        // Age matching (medium weight)
+        const ageScore = this.scoreAgeMatch(person, options);
+        totalScore += ageScore * 0.15;
+        maxScore += 0.15;
         // Additional criteria (lower weight)
         const additionalScore = this.scoreAdditionalCriteria(person, options);
-        totalScore += additionalScore * 0.1;
-        maxScore += 0.1;
+        totalScore += additionalScore * 0.05;
+        maxScore += 0.05;
         return maxScore > 0 ? totalScore / maxScore : 0;
     }
     /**
@@ -51,8 +56,24 @@ class MatchScorer {
             if (nameScore > 0.8) {
                 reasons.push('exact name match');
             }
-            else if (nameScore > 0.6) {
-                reasons.push('similar name match');
+            else if (nameScore > 0) {
+                reasons.push('partial name match');
+            }
+        }
+        // Add age-based match reasons
+        const ageScore = this.scoreAgeMatch(person, options);
+        if (ageScore > 0.8) {
+            const age = (0, helpers_1.calculateAgeSafe)(person.attributes?.birthdate);
+            if (age !== null) {
+                if (options.agePreference === 'adults') {
+                    reasons.push('adult age match');
+                }
+                else if (options.agePreference === 'children') {
+                    reasons.push('child age match');
+                }
+                else {
+                    reasons.push(`age ${age} match`);
+                }
             }
         }
         if (reasons.length === 0) {
@@ -79,25 +100,72 @@ class MatchScorer {
         return 0;
     }
     /**
-     * Score name matching
+     * Score name matching - only exact matches
      */
     scoreNameMatch(person, options) {
         const attrs = person.attributes;
         if (!attrs)
             return 0;
         let score = 0;
-        // First name matching
+        // First name matching - exact match only
         if (options.firstName && attrs.first_name) {
-            const firstNameScore = this.calculateStringSimilarity(options.firstName.toLowerCase(), attrs.first_name.toLowerCase());
-            score += firstNameScore * 0.5;
+            const firstNameMatch = options.firstName.toLowerCase() === attrs.first_name.toLowerCase();
+            score += firstNameMatch ? 0.5 : 0;
         }
-        // Last name matching
+        // Last name matching - exact match only
         if (options.lastName && attrs.last_name) {
-            const lastNameScore = this.calculateStringSimilarity(options.lastName.toLowerCase(), attrs.last_name.toLowerCase());
-            score += lastNameScore * 0.5;
+            const lastNameMatch = options.lastName.toLowerCase() === attrs.last_name.toLowerCase();
+            score += lastNameMatch ? 0.5 : 0;
         }
         return score;
     }
+    /**
+     * Score age matching
+     */
+    scoreAgeMatch(person, options) {
+        const birthdate = person.attributes?.birthdate;
+        // If no age criteria specified, return neutral score
+        if (!options.agePreference &&
+            options.minAge === undefined &&
+            options.maxAge === undefined &&
+            options.birthYear === undefined) {
+            return 0.5; // Neutral score
+        }
+        // If no birthdate available, return low score
+        if (!birthdate) {
+            return 0.1;
+        }
+        // Check if person matches age criteria
+        const matches = (0, helpers_1.matchesAgeCriteria)(birthdate, {
+            agePreference: options.agePreference,
+            minAge: options.minAge,
+            maxAge: options.maxAge,
+            birthYear: options.birthYear
+        });
+        if (!matches) {
+            return 0; // No match
+        }
+        // Calculate bonus score based on how well the age matches
+        const age = (0, helpers_1.calculateAgeSafe)(birthdate);
+        if (age === null)
+            return 0.5;
+        let bonusScore = 0;
+        // Bonus for exact age range match
+        if (options.minAge !== undefined && options.maxAge !== undefined) {
+            if (age >= options.minAge && age <= options.maxAge) {
+                bonusScore += 0.3;
+            }
+        }
+        // Bonus for exact birth year match
+        if (options.birthYear !== undefined) {
+            const birthYear = new Date(birthdate).getFullYear();
+            if (birthYear === options.birthYear) {
+                bonusScore += 0.4;
+            }
+        }
+        // Base score for matching criteria
+        return Math.min(0.6 + bonusScore, 1.0);
+    }
     /**
      * Score additional criteria
      */

package/dist/modules/people.d.ts

@@ -6,7 +6,7 @@ import type { PcoHttpClient } from '../core/http';
 import type { PaginationHelper } from '../core/pagination';
 import type { PcoEventEmitter } from '../monitoring';
 import type { PaginationOptions, PaginationResult } from '../core/pagination';
-import type { PersonResource, EmailResource, EmailAttributes, PhoneNumberResource, PhoneNumberAttributes, AddressResource, AddressAttributes, SocialProfileResource, SocialProfileAttributes } from '../types';
+import type { PersonResource, EmailResource, EmailAttributes, PhoneNumberResource, PhoneNumberAttributes, AddressResource, AddressAttributes, SocialProfileResource, SocialProfileAttributes, CampusResource, HouseholdResource } from '../types';
 export interface PeopleListOptions {
     where?: Record<string, any>;
     include?: string[];
@@ -50,6 +50,10 @@ export interface PersonMatchOptions {
     matchStrategy?: 'exact' | 'fuzzy' | 'aggressive';
     campus?: string;
     createIfNotFound?: boolean;
+    agePreference?: 'adults' | 'children' | 'any';
+    minAge?: number;
+    maxAge?: number;
+    birthYear?: number;
 }
 export declare class PeopleModule extends BaseModule {
     private personMatcher;
@@ -82,6 +86,94 @@ export declare class PeopleModule extends BaseModule {
      * Delete a person
      */
     delete(id: string): Promise<void>;
+    /**
+     * Get a person's primary campus
+     */
+    getPrimaryCampus(personId: string): Promise<CampusResource | null>;
+    /**
+     * Set a person's primary campus
+     */
+    setPrimaryCampus(personId: string, campusId: string): Promise<PersonResource>;
+    /**
+     * Remove a person's primary campus
+     */
+    removePrimaryCampus(personId: string): Promise<PersonResource>;
+    /**
+     * Get a person's household
+     */
+    getHousehold(personId: string): Promise<HouseholdResource | null>;
+    /**
+     * Set a person's household
+     */
+    setHousehold(personId: string, householdId: string): Promise<PersonResource>;
+    /**
+     * Remove a person from their household
+     */
+    removeFromHousehold(personId: string): Promise<PersonResource>;
+    /**
+     * Get all people in a specific household
+     */
+    getHouseholdMembers(householdId: string, options?: PeopleListOptions): Promise<{
+        data: PersonResource[];
+        meta?: any;
+        links?: any;
+    }>;
+    /**
+     * Get people by campus
+     */
+    getByCampus(campusId: string, options?: PeopleListOptions): Promise<{
+        data: PersonResource[];
+        meta?: any;
+        links?: any;
+    }>;
+    /**
+     * Get a person's workflow cards
+     */
+    getWorkflowCards(personId: string, options?: {
+        include?: string[];
+        perPage?: number;
+        page?: number;
+    }): Promise<{
+        data: any[];
+        meta?: any;
+        links?: any;
+    }>;
+    /**
+     * Get a person's notes
+     */
+    getNotes(personId: string, options?: {
+        include?: string[];
+        perPage?: number;
+        page?: number;
+    }): Promise<{
+        data: any[];
+        meta?: any;
+        links?: any;
+    }>;
+    /**
+     * Get a person's field data
+     */
+    getFieldData(personId: string, options?: {
+        include?: string[];
+        perPage?: number;
+        page?: number;
+    }): Promise<{
+        data: any[];
+        meta?: any;
+        links?: any;
+    }>;
+    /**
+     * Get a person's social profiles
+     */
+    getSocialProfiles(personId: string, options?: {
+        include?: string[];
+        perPage?: number;
+        page?: number;
+    }): Promise<{
+        data: any[];
+        meta?: any;
+        links?: any;
+    }>;
     /**
      * Find or create a person with smart matching
      */
@@ -160,14 +252,6 @@ export declare class PeopleModule extends BaseModule {
      * Delete a person's address
      */
     deleteAddress(personId: string, addressId: string): Promise<void>;
-    /**
-     * Get person's social profiles
-     */
-    getSocialProfiles(personId: string): Promise<{
-        data: SocialProfileResource[];
-        meta?: any;
-        links?: any;
-    }>;
     /**
      * Add a social profile to a person
      */

package/dist/modules/people.js

@@ -75,6 +75,209 @@ class PeopleModule extends base_1.BaseModule {
     async delete(id) {
         return this.deleteResource(`/people/${id}`);
     }
+    // ===== Relationship Management =====
+    /**
+     * Get a person's primary campus
+     */
+    async getPrimaryCampus(personId) {
+        const person = await this.getById(personId, ['primary_campus']);
+        const campusData = person.relationships?.primary_campus?.data;
+        if (!campusData || Array.isArray(campusData) || !campusData.id) {
+            return null;
+        }
+        // Get the full campus resource
+        return this.httpClient.request({
+            method: 'GET',
+            endpoint: `/campuses/${campusData.id}`
+        }).then(response => response.data);
+    }
+    /**
+     * Set a person's primary campus
+     */
+    async setPrimaryCampus(personId, campusId) {
+        return this.httpClient.request({
+            method: 'PATCH',
+            endpoint: `/people/${personId}`,
+            data: {
+                data: {
+                    type: 'Person',
+                    id: personId,
+                    attributes: {
+                        primary_campus_id: campusId
+                    }
+                }
+            }
+        }).then(response => response.data);
+    }
+    /**
+     * Remove a person's primary campus
+     */
+    async removePrimaryCampus(personId) {
+        return this.httpClient.request({
+            method: 'PATCH',
+            endpoint: `/people/${personId}`,
+            data: {
+                data: {
+                    type: 'Person',
+                    id: personId,
+                    attributes: {
+                        primary_campus_id: null
+                    }
+                }
+            }
+        }).then(response => response.data);
+    }
+    /**
+     * Get a person's household
+     */
+    async getHousehold(personId) {
+        const person = await this.getById(personId, ['household']);
+        const householdData = person.relationships?.household?.data;
+        if (!householdData || Array.isArray(householdData) || !householdData.id) {
+            return null;
+        }
+        // Get the full household resource
+        return this.httpClient.request({
+            method: 'GET',
+            endpoint: `/households/${householdData.id}`
+        }).then(response => response.data);
+    }
+    /**
+     * Set a person's household
+     */
+    async setHousehold(personId, householdId) {
+        return this.httpClient.request({
+            method: 'PATCH',
+            endpoint: `/people/${personId}`,
+            data: {
+                data: {
+                    type: 'Person',
+                    id: personId,
+                    attributes: {
+                        household_id: householdId
+                    }
+                }
+            }
+        }).then(response => response.data);
+    }
+    /**
+     * Remove a person from their household
+     */
+    async removeFromHousehold(personId) {
+        return this.httpClient.request({
+            method: 'PATCH',
+            endpoint: `/people/${personId}`,
+            data: {
+                data: {
+                    type: 'Person',
+                    id: personId,
+                    attributes: {
+                        household_id: null
+                    }
+                }
+            }
+        }).then(response => response.data);
+    }
+    /**
+     * Get all people in a specific household
+     */
+    async getHouseholdMembers(householdId, options = {}) {
+        const params = {
+            'where[household_id]': householdId
+        };
+        if (options.include) {
+            params.include = options.include.join(',');
+        }
+        if (options.perPage) {
+            params.per_page = options.perPage;
+        }
+        if (options.page) {
+            params.page = options.page;
+        }
+        return this.getList('/people', params);
+    }
+    /**
+     * Get people by campus
+     */
+    async getByCampus(campusId, options = {}) {
+        const params = {
+            'where[primary_campus_id]': campusId
+        };
+        if (options.include) {
+            params.include = options.include.join(',');
+        }
+        if (options.perPage) {
+            params.per_page = options.perPage;
+        }
+        if (options.page) {
+            params.page = options.page;
+        }
+        return this.getList('/people', params);
+    }
+    /**
+     * Get a person's workflow cards
+     */
+    async getWorkflowCards(personId, options = {}) {
+        const params = {};
+        if (options.include) {
+            params.include = options.include.join(',');
+        }
+        if (options.perPage) {
+            params.per_page = options.perPage;
+        }
+        if (options.page) {
+            params.page = options.page;
+        }
+        return this.getList(`/people/${personId}/workflow_cards`, params);
+    }
+    /**
+     * Get a person's notes
+     */
+    async getNotes(personId, options = {}) {
+        const params = {};
+        if (options.include) {
+            params.include = options.include.join(',');
+        }
+        if (options.perPage) {
+            params.per_page = options.perPage;
+        }
+        if (options.page) {
+            params.page = options.page;
+        }
+        return this.getList(`/people/${personId}/notes`, params);
+    }
+    /**
+     * Get a person's field data
+     */
+    async getFieldData(personId, options = {}) {
+        const params = {};
+        if (options.include) {
+            params.include = options.include.join(',');
+        }
+        if (options.perPage) {
+            params.per_page = options.perPage;
+        }
+        if (options.page) {
+            params.page = options.page;
+        }
+        return this.getList(`/people/${personId}/field_data`, params);
+    }
+    /**
+     * Get a person's social profiles
+     */
+    async getSocialProfiles(personId, options = {}) {
+        const params = {};
+        if (options.include) {
+            params.include = options.include.join(',');
+        }
+        if (options.perPage) {
+            params.per_page = options.perPage;
+        }
+        if (options.page) {
+            params.page = options.page;
+        }
+        return this.getList(`/people/${personId}/social_profiles`, params);
+    }
     /**
      * Find or create a person with smart matching
      */
@@ -176,12 +379,6 @@ class PeopleModule extends base_1.BaseModule {
     async deleteAddress(personId, addressId) {
         return this.deleteResource(`/people/${personId}/addresses/${addressId}`);
     }
-    /**
-     * Get person's social profiles
-     */
-    async getSocialProfiles(personId) {
-        return this.getList(`/people/${personId}/social_profiles`);
-    }
     /**
      * Add a social profile to a person
      */

package/dist/types/client.d.ts

@@ -16,9 +16,19 @@ export interface OAuthAuth {
         refreshToken: string;
     }) => void | Promise<void>;
     onRefreshFailure: (error: Error) => void | Promise<void>;
+    /** Client ID for token refresh (optional, can use environment variable PCO_APP_ID) */
+    clientId?: string;
+    /** Client Secret for token refresh (optional, can use environment variable PCO_APP_SECRET) */
+    clientSecret?: string;
+}
+/** Authentication configuration for Basic Auth with app credentials */
+export interface BasicAuth {
+    type: 'basic';
+    appId: string;
+    appSecret: string;
 }
 /** Union type for authentication configurations */
-export type PcoAuthConfig = PersonalAccessTokenAuth | OAuthAuth;
+export type PcoAuthConfig = PersonalAccessTokenAuth | OAuthAuth | BasicAuth;
 export interface PcoClientConfig {
     /** Authentication configuration */
     auth: PcoAuthConfig;

package/dist/types/people.d.ts

@@ -39,8 +39,14 @@ export interface PersonAttributes extends Attributes {
 export interface PersonRelationships {
     emails?: Relationship;
     phone_numbers?: Relationship;
+    addresses?: Relationship;
+    household?: Relationship;
     primary_campus?: Relationship;
     gender?: Relationship;
+    workflow_cards?: Relationship;
+    notes?: Relationship;
+    field_data?: Relationship;
+    social_profiles?: Relationship;
 }
 export interface PersonResource extends ResourceObject<'Person', PersonAttributes, PersonRelationships> {
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rachelallyson/planning-center-people-ts",
-    "version": "2.3.1",
+    "version": "2.5.0",
     "description": "A strictly typed TypeScript client for Planning Center Online People API with smart matching, batch operations, and enhanced developer experience",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",