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

package/CHANGELOG.md

@@ -5,6 +5,119 @@ 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**

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/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[];
@@ -86,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
      */
@@ -164,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.4.0",
+    "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",