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

package/CHANGELOG.md

@@ -5,6 +5,148 @@ 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.2.0] - 2025-01-17
+
+### 🏢 **NEW FEATURE - Campus Management Support**
+
+This release adds comprehensive Campus management functionality to the Planning Center People API client.
+
+### Added
+
+#### **🏢 Campus Module**
+
+- **Complete Campus CRUD Operations**: Create, read, update, and delete campuses
+- **Campus-Specific Operations**: Get campus lists and service times
+- **Type-Safe Campus Resource**: Full TypeScript support for campus attributes and relationships
+- **Pagination Support**: Automatic pagination for campus listings
+
+#### **📋 Campus Operations**
+
+- `client.campus.getAll()` - Get all campuses with filtering and pagination
+- `client.campus.getById(id, include?)` - Get specific campus by ID
+- `client.campus.create(data)` - Create new campus
+- `client.campus.update(id, data)` - Update existing campus
+- `client.campus.delete(id)` - Delete campus
+- `client.campus.getLists(campusId)` - Get lists for a specific campus
+- `client.campus.getServiceTimes(campusId)` - Get service times for a specific campus
+- `client.campus.getAllPagesPaginated()` - Get all campuses with automatic pagination
+
+#### **🏗️ Campus Resource Structure**
+
+- **Location Data**: `latitude`, `longitude`, `street`, `city`, `state`, `zip`, `country`
+- **Contact Information**: `phone_number`, `website`
+- **Settings**: `twenty_four_hour_time`, `date_format`, `church_center_enabled`
+- **Metadata**: `description`, `created_at`, `updated_at`
+
+### Documentation
+
+- **Updated README.md** with Campus Management examples
+- **Updated EXAMPLES.md** with comprehensive Campus usage patterns
+- **Updated API_REFERENCE.md** with complete Campus Module documentation
+- **Added Campus types** to resource types documentation
+
+### Testing
+
+- **Integration Tests**: Complete test suite for Campus operations
+- **Type Safety**: Full TypeScript coverage for Campus resources
+- **Error Handling**: Comprehensive error handling for Campus operations
+
+### Example Usage
+
+```typescript
+import { PcoClient } from '@rachelallyson/planning-center-people-ts';
+
+const client = new PcoClient({
+  auth: {
+    type: 'personal_access_token',
+    personalAccessToken: 'your-token'
+  }
+});
+
+// Get all campuses
+const campuses = await client.campus.getAll();
+
+// Create new campus
+const newCampus = await client.campus.create({
+  description: 'Main Campus',
+  street: '123 Church Street',
+  city: 'Anytown',
+  state: 'CA',
+  zip: '12345',
+  country: 'US',
+  phone_number: '555-123-4567',
+  website: 'https://maincampus.example.com',
+  twenty_four_hour_time: false,
+  date_format: 1,
+  church_center_enabled: true
+});
+
+// Get campus-specific data
+const campusLists = await client.campus.getLists('campus-id');
+const serviceTimes = await client.campus.getServiceTimes('campus-id');
+```
+
+## [2.1.0] - 2025-01-17
+
+### 🔒 **SECURITY RELEASE - Required Refresh Token Handling**
+
+This release addresses a critical security issue where OAuth 2.0 clients could lose access when tokens expire without proper refresh handling.
+
+### Breaking Changes
+
+- **OAuth 2.0 Authentication**: `onRefresh` and `onRefreshFailure` callbacks are now **required** for OAuth configurations
+- **Type Safety**: Enhanced type-safe authentication configuration prevents invalid configurations at compile time
+
+### Security
+
+- **CRITICAL**: OAuth 2.0 authentication now requires refresh token handling to prevent token loss
+- **BREAKING**: Type-safe authentication configuration enforces required fields
+- Enhanced token refresh implementation with proper error handling
+- Improved authentication type safety with union types
+
+### Fixed
+
+- Fixed person matching to properly handle default fuzzy strategy
+- Fixed mock client to support createWithContacts method
+- Fixed event system tests to work with mock client
+- Fixed phone number builder in mock response builder
+
+### Migration from v2.0.0
+
+**Before (v2.0.0):**
+
+```typescript
+const client = new PcoClient({
+  auth: {
+    type: 'oauth',
+    accessToken: 'access-token',
+    refreshToken: 'refresh-token'
+    // Missing required callbacks - this will now cause TypeScript errors
+  }
+});
+```
+
+**After (v2.1.0):**
+
+```typescript
+const client = new PcoClient({
+  auth: {
+    type: 'oauth',
+    accessToken: 'access-token',
+    refreshToken: 'refresh-token',
+    // REQUIRED: Handle token refresh to prevent token loss
+    onRefresh: async (tokens) => {
+      await saveTokensToDatabase(userId, tokens);
+    },
+    // REQUIRED: Handle refresh failures
+    onRefreshFailure: async (error) => {
+      console.error('Token refresh failed:', error.message);
+      await clearUserTokens(userId);
+    }
+  }
+});
+```
+
 ## [2.0.0] - 2025-01-17
 
 ### 🚀 **MAJOR RELEASE - Complete API Redesign**
@@ -120,6 +262,10 @@ const person = await client.people.create({ first_name: 'John', last_name: 'Doe'
 - **Error Handling**: Improved error handling and retry logic
 - **Rate Limiting**: Fixed rate limiting edge cases
 - **Authentication**: Resolved token refresh and persistence issues
+- Fixed person matching to properly handle default fuzzy strategy
+- Fixed mock client to support createWithContacts method
+- Fixed event system tests to work with mock client
+- Fixed phone number builder in mock response builder
 
 ## [1.1.0] - 2025-10-08
 

package/dist/client-manager.js

@@ -119,9 +119,9 @@ class PcoClientManager {
         // Create a hash of the configuration
         const configStr = JSON.stringify({
             authType: config.auth.type,
-            hasAccessToken: !!config.auth.accessToken,
-            hasRefreshToken: !!config.auth.refreshToken,
-            hasPersonalAccessToken: !!config.auth.personalAccessToken,
+            hasAccessToken: config.auth.type === 'oauth' ? !!config.auth.accessToken : false,
+            hasRefreshToken: config.auth.type === 'oauth' ? !!config.auth.refreshToken : false,
+            hasPersonalAccessToken: config.auth.type === 'personal_access_token' ? !!config.auth.personalAccessToken : false,
             baseURL: config.baseURL,
             timeout: config.timeout,
         });
@@ -139,11 +139,17 @@ class PcoClientManager {
      */
     hasConfigChanged(oldConfig, newConfig) {
         // Compare key configuration properties
-        return (oldConfig.auth.type !== newConfig.auth.type ||
-            oldConfig.auth.accessToken !== newConfig.auth.accessToken ||
-            oldConfig.auth.refreshToken !== newConfig.auth.refreshToken ||
-            oldConfig.auth.personalAccessToken !== newConfig.auth.personalAccessToken ||
-            oldConfig.baseURL !== newConfig.baseURL ||
+        if (oldConfig.auth.type !== newConfig.auth.type) {
+            return true;
+        }
+        if (oldConfig.auth.type === 'oauth' && newConfig.auth.type === 'oauth') {
+            return (oldConfig.auth.accessToken !== newConfig.auth.accessToken ||
+                oldConfig.auth.refreshToken !== newConfig.auth.refreshToken);
+        }
+        if (oldConfig.auth.type === 'personal_access_token' && newConfig.auth.type === 'personal_access_token') {
+            return oldConfig.auth.personalAccessToken !== newConfig.auth.personalAccessToken;
+        }
+        return (oldConfig.baseURL !== newConfig.baseURL ||
             oldConfig.timeout !== newConfig.timeout);
     }
 }

package/dist/client.d.ts

@@ -10,6 +10,7 @@ import { ContactsModule } from './modules/contacts';
 import { HouseholdsModule } from './modules/households';
 import { NotesModule } from './modules/notes';
 import { ListsModule } from './modules/lists';
+import { CampusModule } from './modules/campus';
 import { BatchExecutor } from './batch';
 export declare class PcoClient implements EventEmitter {
     people: PeopleModule;
@@ -19,6 +20,7 @@ export declare class PcoClient implements EventEmitter {
     households: HouseholdsModule;
     notes: NotesModule;
     lists: ListsModule;
+    campus: CampusModule;
     batch: BatchExecutor;
     private httpClient;
     private paginationHelper;

package/dist/client.js

@@ -14,6 +14,7 @@ const contacts_1 = require("./modules/contacts");
 const households_1 = require("./modules/households");
 const notes_1 = require("./modules/notes");
 const lists_1 = require("./modules/lists");
+const campus_1 = require("./modules/campus");
 const batch_1 = require("./batch");
 class PcoClient {
     constructor(config) {
@@ -29,6 +30,7 @@ class PcoClient {
         this.households = new households_1.HouseholdsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
         this.notes = new notes_1.NotesModule(this.httpClient, this.paginationHelper, this.eventEmitter);
         this.lists = new lists_1.ListsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
+        this.campus = new campus_1.CampusModule(this.httpClient, this.paginationHelper, this.eventEmitter);
         this.batch = new batch_1.BatchExecutor(this, this.eventEmitter);
         // Set up event handlers from config
         this.setupEventHandlers();

package/dist/core/http.d.ts

@@ -31,6 +31,7 @@ export declare class PcoHttpClient {
     private addAuthentication;
     private getResourceTypeFromEndpoint;
     private extractHeaders;
+    private attemptTokenRefresh;
     private updateRateLimitTracking;
     getPerformanceMetrics(): Record<string, {
         count: number;

package/dist/core/http.js

@@ -7,7 +7,6 @@ exports.PcoHttpClient = void 0;
 const monitoring_1 = require("../monitoring");
 const rate_limiter_1 = require("../rate-limiter");
 const api_error_1 = require("../api-error");
-const auth_1 = require("../auth");
 class PcoHttpClient {
     constructor(config, eventEmitter) {
         this.config = config;
@@ -139,20 +138,15 @@ class PcoHttpClient {
             // Handle other errors
             if (!response.ok) {
                 // Handle 401 errors with token refresh if available
-                // Convert v2.0 config to v1.x format for auth functions
-                const v1Config = {
-                    refreshToken: this.config.auth.refreshToken,
-                    onTokenRefresh: this.config.auth.onRefresh,
-                    onTokenRefreshFailure: this.config.auth.onRefreshFailure,
-                };
-                const clientState = { config: v1Config, rateLimiter: this.rateLimiter };
-                if (response.status === 401 && (0, auth_1.hasRefreshTokenCapability)(clientState)) {
+                if (response.status === 401 && this.config.auth.type === 'oauth') {
                     try {
-                        await (0, auth_1.attemptTokenRefresh)(clientState, () => this.makeRequest(options, requestId));
+                        await this.attemptTokenRefresh();
                         return this.makeRequest(options, requestId);
                     }
                     catch (refreshError) {
                         console.warn('Token refresh failed:', refreshError);
+                        // Call the onRefreshFailure callback
+                        await this.config.auth.onRefreshFailure(refreshError);
                     }
                 }
                 let errorData;
@@ -189,12 +183,12 @@ class PcoHttpClient {
         }
     }
     addAuthentication(headers) {
-        if (this.config.auth.personalAccessToken) {
+        if (this.config.auth.type === 'personal_access_token') {
             // Personal Access Tokens use HTTP Basic Auth format: app_id:secret
             // The personalAccessToken should be in the format "app_id:secret"
             headers.Authorization = `Basic ${Buffer.from(this.config.auth.personalAccessToken).toString('base64')}`;
         }
-        else if (this.config.auth.accessToken) {
+        else if (this.config.auth.type === 'oauth') {
             headers.Authorization = `Bearer ${this.config.auth.accessToken}`;
         }
     }
@@ -224,6 +218,35 @@ class PcoHttpClient {
         });
         return headers;
     }
+    async attemptTokenRefresh() {
+        if (this.config.auth.type !== 'oauth') {
+            throw new Error('Token refresh is only available for OAuth authentication');
+        }
+        const baseURL = this.config.baseURL || 'https://api.planningcenteronline.com/people/v2';
+        const tokenUrl = baseURL.replace('/people/v2', '/oauth/token');
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({
+                grant_type: 'refresh_token',
+                refresh_token: this.config.auth.refreshToken,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Token refresh failed: ${response.status} ${response.statusText}`);
+        }
+        const tokens = await response.json();
+        // Update the config with new tokens
+        this.config.auth.accessToken = tokens.access_token;
+        this.config.auth.refreshToken = tokens.refresh_token;
+        // Call the onRefresh callback
+        await this.config.auth.onRefresh({
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+        });
+    }
     updateRateLimitTracking(endpoint, headers) {
         const limit = headers['x-pco-api-request-rate-limit'];
         const remaining = headers['x-pco-api-request-rate-count'];

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 export { PcoClient } from './client';
 export { PcoClientManager } from './client-manager';
-export type { PcoClientConfig } from './types/client';
+export type { PcoClientConfig, PcoAuthConfig, PersonalAccessTokenAuth, OAuthAuth } from './types/client';
 export type { PcoEvent, EventHandler, EventType } from './types/events';
 export type { BatchOperation, BatchResult, BatchOptions, BatchSummary } from './types/batch';
 export type { Paginated, Relationship, ResourceIdentifier, ResourceObject, } from './types';
 export type { 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 type { HouseholdResource, HouseholdAttributes, NoteResource, NoteAttributes, ListResource, ListAttributes, OrganizationResource, OrganizationAttributes, CampusResource, CampusAttributes, CampusesList, } from './types';
 export * from './types';
 export type { PcoClientConfig as PcoClientConfigV1, PcoClientState } from './core';
 export { createPcoClient, del, getAllPages, getList, getRateLimitInfo, getSingle, patch, post, } from './core';

package/dist/modules/campus.d.ts

@@ -0,0 +1,63 @@
+import { BaseModule } from './base';
+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 { CampusResource, CampusAttributes, CampusesList } from '../types';
+/**
+ * Campus module for managing campus-related operations
+ */
+export declare class CampusModule extends BaseModule {
+    constructor(httpClient: PcoHttpClient, paginationHelper: PaginationHelper, eventEmitter: PcoEventEmitter);
+    /**
+     * Get all campuses
+     */
+    getAll(params?: {
+        where?: Record<string, any>;
+        include?: string[];
+        per_page?: number;
+        page?: number;
+    }): Promise<CampusesList>;
+    /**
+     * Get a specific campus by ID
+     */
+    getById(id: string, include?: string[]): Promise<CampusResource>;
+    /**
+     * Create a new campus
+     */
+    create(data: CampusAttributes): Promise<CampusResource>;
+    /**
+     * Update an existing campus
+     */
+    update(id: string, data: Partial<CampusAttributes>): Promise<CampusResource>;
+    /**
+     * Delete a campus
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Get lists for a specific campus
+     */
+    getLists(campusId: string, params?: {
+        where?: Record<string, any>;
+        include?: string[];
+        per_page?: number;
+        page?: number;
+    }): Promise<any>;
+    /**
+     * Get service times for a specific campus
+     */
+    getServiceTimes(campusId: string, params?: {
+        where?: Record<string, any>;
+        include?: string[];
+        per_page?: number;
+        page?: number;
+    }): Promise<any>;
+    /**
+     * Get all campuses with pagination support
+     */
+    getAllPagesPaginated(params?: {
+        where?: Record<string, any>;
+        include?: string[];
+        per_page?: number;
+    }, paginationOptions?: PaginationOptions): Promise<PaginationResult<CampusResource>>;
+}

package/dist/modules/campus.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CampusModule = void 0;
+const base_1 = require("./base");
+/**
+ * Campus module for managing campus-related operations
+ */
+class CampusModule extends base_1.BaseModule {
+    constructor(httpClient, paginationHelper, eventEmitter) {
+        super(httpClient, paginationHelper, eventEmitter);
+    }
+    /**
+     * Get all campuses
+     */
+    async getAll(params) {
+        return this.getList('/campuses', params);
+    }
+    /**
+     * Get a specific campus by ID
+     */
+    async getById(id, include) {
+        const params = {};
+        if (include) {
+            params.include = include.join(',');
+        }
+        return this.getSingle(`/campuses/${id}`, params);
+    }
+    /**
+     * Create a new campus
+     */
+    async create(data) {
+        return this.createResource('/campuses', data);
+    }
+    /**
+     * Update an existing campus
+     */
+    async update(id, data) {
+        return this.updateResource(`/campuses/${id}`, data);
+    }
+    /**
+     * Delete a campus
+     */
+    async delete(id) {
+        return this.deleteResource(`/campuses/${id}`);
+    }
+    /**
+     * Get lists for a specific campus
+     */
+    async getLists(campusId, params) {
+        return this.getList(`/campuses/${campusId}/lists`, params);
+    }
+    /**
+     * Get service times for a specific campus
+     */
+    async getServiceTimes(campusId, params) {
+        return this.getList(`/campuses/${campusId}/service_times`, params);
+    }
+    /**
+     * Get all campuses with pagination support
+     */
+    async getAllPagesPaginated(params, paginationOptions) {
+        const queryParams = {};
+        if (params?.where) {
+            Object.entries(params.where).forEach(([key, value]) => {
+                queryParams[`where[${key}]`] = value;
+            });
+        }
+        if (params?.include) {
+            queryParams.include = params.include.join(',');
+        }
+        if (params?.per_page) {
+            queryParams.per_page = params.per_page;
+        }
+        return this.getAllPages('/campuses', queryParams, paginationOptions);
+    }
+}
+exports.CampusModule = CampusModule;

package/dist/testing/simple-factories.js

@@ -181,6 +181,9 @@ function createTestClient(overrides = {}) {
         auth: {
             type: 'oauth',
             accessToken: 'test-token',
+            refreshToken: 'test-refresh-token',
+            onRefresh: async () => { },
+            onRefreshFailure: async () => { },
         },
     };
     const defaultMockConfig = {
@@ -239,6 +242,9 @@ function createErrorMockClient(errorType = 'network') {
         auth: {
             type: 'oauth',
             accessToken: 'test-token',
+            refreshToken: 'test-refresh-token',
+            onRefresh: async () => { },
+            onRefreshFailure: async () => { },
         },
     };
     const errorMockConfig = {
@@ -260,6 +266,9 @@ function createSlowMockClient(delayMs = 1000) {
         auth: {
             type: 'oauth',
             accessToken: 'test-token',
+            refreshToken: 'test-refresh-token',
+            onRefresh: async () => { },
+            onRefreshFailure: async () => { },
         },
     };
     const slowMockConfig = {

package/dist/types/client.d.ts

@@ -1,19 +1,27 @@
 /**
  * v2.0.0 Client Configuration Types
  */
+/** Authentication configuration for Personal Access Token */
+export interface PersonalAccessTokenAuth {
+    type: 'personal_access_token';
+    personalAccessToken: string;
+}
+/** Authentication configuration for OAuth 2.0 with required refresh handling */
+export interface OAuthAuth {
+    type: 'oauth';
+    accessToken: string;
+    refreshToken: string;
+    onRefresh: (tokens: {
+        accessToken: string;
+        refreshToken: string;
+    }) => void | Promise<void>;
+    onRefreshFailure: (error: Error) => void | Promise<void>;
+}
+/** Union type for authentication configurations */
+export type PcoAuthConfig = PersonalAccessTokenAuth | OAuthAuth;
 export interface PcoClientConfig {
     /** Authentication configuration */
-    auth: {
-        type: 'oauth' | 'personal_access_token';
-        accessToken?: string;
-        refreshToken?: string;
-        personalAccessToken?: string;
-        onRefresh?: (tokens: {
-            accessToken: string;
-            refreshToken?: string;
-        }) => void | Promise<void>;
-        onRefreshFailure?: (error: Error) => void | Promise<void>;
-    };
+    auth: PcoAuthConfig;
     /** Caching configuration */
     caching?: {
         fieldDefinitions?: boolean;

package/dist/types/people.d.ts

@@ -376,4 +376,28 @@ export interface OrganizationStatisticResource extends ResourceObject<'Organizat
 }
 export type OrganizationStatisticsList = Paginated<OrganizationStatisticResource>;
 export type OrganizationStatisticSingle = Response<OrganizationStatisticResource>;
-export type PeopleIncluded = EmailResource | AddressResource | PhoneNumberResource | HouseholdResource | SocialProfileResource | FieldDatumResource | TabResource;
+export interface CampusAttributes extends Attributes {
+    latitude?: number;
+    longitude?: number;
+    description?: string;
+    street?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    country?: string;
+    phone_number?: string;
+    website?: string;
+    twenty_four_hour_time?: boolean;
+    date_format?: number;
+    church_center_enabled?: boolean;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface CampusRelationships {
+    organization?: Relationship;
+}
+export interface CampusResource extends ResourceObject<'Campus', CampusAttributes, CampusRelationships> {
+}
+export type CampusesList = Paginated<CampusResource>;
+export type CampusSingle = Response<CampusResource>;
+export type PeopleIncluded = EmailResource | AddressResource | PhoneNumberResource | HouseholdResource | SocialProfileResource | FieldDatumResource | TabResource | CampusResource;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rachelallyson/planning-center-people-ts",
-    "version": "2.0.0",
+    "version": "2.2.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",