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

package/CHANGELOG.md

@@ -5,6 +5,67 @@ 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.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 +181,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/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,6 +1,6 @@
 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';

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/package.json

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