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

package/CHANGELOG.md

@@ -5,6 +5,187 @@ 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**
+
+This is a **breaking change** release that completely redesigns the API for better developer experience, type safety, and maintainability.
+
+### Added
+
+#### **🏗️ New Class-Based Architecture**
+
+- **PcoClient Class**: Main client with modular architecture
+- **PcoClientManager**: Automatic client caching and lifecycle management
+- **Event System**: Comprehensive event emission for monitoring and debugging
+- **Module Architecture**: Organized API interactions into focused modules
+
+#### **🔧 Core Utilities**
+
+- **Built-in Pagination**: `getAllPages()` method for automatic pagination
+- **Batch Operations**: Execute multiple operations with dependency resolution
+- **Person Matching**: Smart person matching with fuzzy logic and `findOrCreate`
+- **Type-Safe Field Operations**: Enhanced custom field operations with caching
+- **Workflow State Management**: Smart workflow operations with duplicate detection
+
+#### **📦 New Modules**
+
+- **PeopleModule**: Core person operations with smart matching
+- **FieldsModule**: Type-safe custom field operations with caching
+- **WorkflowsModule**: Complete workflow and workflow card management
+- **ContactsModule**: Email, phone, address, and social profile management
+- **HouseholdsModule**: Household operations and member management
+- **NotesModule**: Note and note category operations
+- **ListsModule**: List and list category operations with rule-based membership
+
+#### **🔐 Enhanced Authentication**
+
+- **OAuth 2.0 Support**: Full OAuth with automatic token refresh
+- **Personal Access Token**: HTTP Basic Auth support
+- **Token Refresh**: Automatic refresh with callback support
+- **Environment Persistence**: Automatic token persistence in test environments
+
+#### **⚡ Performance & Reliability**
+
+- **Rate Limiting**: Built-in rate limiting (100 req/min)
+- **Error Handling**: Comprehensive error handling with retry logic
+- **Request Timeouts**: Configurable request timeouts
+- **Event Monitoring**: Real-time request/response monitoring
+
+#### **🧪 Testing Infrastructure**
+
+- **MockPcoClient**: Complete mock implementation for testing
+- **MockResponseBuilder**: Response building utilities
+- **RequestRecorder**: Request recording for testing
+- **Integration Tests**: 129 comprehensive integration tests
+
+### Changed
+
+#### **🔄 Breaking Changes**
+
+- **API Design**: Complete redesign from functional to class-based approach
+- **Import Structure**: New import structure with `PcoClient` class
+- **Method Names**: Updated method names for consistency
+- **Type Definitions**: Enhanced type definitions with better type safety
+
+#### **📈 Improvements**
+
+- **Type Safety**: Enhanced TypeScript support with strict typing
+- **Error Messages**: More descriptive error messages and handling
+- **Documentation**: Comprehensive inline documentation
+- **Performance**: Optimized request handling and caching
+
+### Migration Guide
+
+#### **Before (v1.x)**
+
+```typescript
+import { createPcoClient, getPeople, createPerson } from '@rachelallyson/planning-center-people-ts';
+
+const client = createPcoClient({
+    personalAccessToken: 'your-token',
+    appId: 'your-app-id',
+    appSecret: 'your-app-secret'
+});
+
+const people = await getPeople(client, { per_page: 10 });
+const person = await createPerson(client, { first_name: 'John', last_name: 'Doe' });
+```
+
+#### **After (v2.0.0)**
+
+```typescript
+import { PcoClient } from '@rachelallyson/planning-center-people-ts';
+
+const client = new PcoClient({
+    auth: {
+        type: 'personal_access_token',
+        personalAccessToken: 'your-token'
+    }
+});
+
+const people = await client.people.getAll({ perPage: 10 });
+const person = await client.people.create({ first_name: 'John', last_name: 'Doe' });
+```
+
+### Removed
+
+- **Functional API**: All functional API methods removed in favor of class-based approach
+- **Legacy Types**: Old type definitions replaced with enhanced versions
+- **Deprecated Methods**: All deprecated methods removed
+
+### Fixed
+
+- **Type Safety**: Resolved all TypeScript strict mode issues
+- **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
 
 ### Added

package/README.md

@@ -515,6 +515,22 @@ See [TYPE_VALIDATION_SUMMARY.md](./TYPE_VALIDATION_SUMMARY.md) for detailed docu
 4. Add tests (both unit and integration)
 5. Submit a pull request
 
+## 📚 Comprehensive Documentation
+
+This library includes extensive documentation covering all aspects of usage:
+
+- **[📖 Complete Documentation](./docs/README.md)** - Comprehensive guide covering all features
+- **[🚀 Getting Started](./docs/OVERVIEW.md)** - What this library does and why you should use it
+- **[⚙️ Installation Guide](./docs/INSTALLATION.md)** - Complete setup instructions for all environments
+- **[🔐 Authentication Guide](./docs/AUTHENTICATION.md)** - All authentication methods and token management
+- **[📋 API Reference](./docs/API_REFERENCE.md)** - Complete reference for all 40+ functions
+- **[💡 Examples & Patterns](./docs/EXAMPLES.md)** - Real-world examples and common patterns
+- **[🛠️ Error Handling](./docs/ERROR_HANDLING.md)** - Advanced error management and recovery
+- **[⚡ Performance Guide](./docs/PERFORMANCE.md)** - Optimization techniques and bulk operations
+- **[🔧 Troubleshooting](./docs/TROUBLESHOOTING.md)** - Common issues and solutions
+- **[🔄 Migration Guide](./docs/MIGRATION.md)** - Switching from other libraries
+- **[⭐ Best Practices](./docs/BEST_PRACTICES.md)** - Production-ready patterns and security
+
 ## License
 
 MIT

package/dist/batch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * v2.0.0 Batch Operations Executor
+ */
+import type { PcoClient } from './client';
+import type { PcoEventEmitter } from './monitoring';
+import type { BatchOperation, BatchOptions, BatchSummary } from './types/batch';
+export declare class BatchExecutor {
+    private client;
+    private eventEmitter;
+    constructor(client: PcoClient, eventEmitter: PcoEventEmitter);
+    /**
+     * Execute a batch of operations
+     */
+    execute<T = any>(operations: BatchOperation[], options?: BatchOptions): Promise<BatchSummary>;
+    /**
+     * Resolve operation dependencies and references
+     */
+    private resolveOperations;
+    /**
+     * Resolve references in operation data
+     */
+    private resolveReferences;
+    /**
+     * Resolve string references like "$0.id" or "$1.data.attributes.name"
+     */
+    private resolveStringReferences;
+    /**
+     * Get nested value from object using dot notation
+     */
+    private getNestedValue;
+    /**
+     * Find dependencies for an operation
+     */
+    private findDependencies;
+    /**
+     * Execute a single operation
+     */
+    private executeOperation;
+    /**
+     * Rollback successful operations
+     */
+    private rollbackOperations;
+    /**
+     * Rollback a single operation
+     */
+    private rollbackOperation;
+}

package/dist/batch.js

@@ -0,0 +1,376 @@
+"use strict";
+/**
+ * v2.0.0 Batch Operations Executor
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchExecutor = void 0;
+class BatchExecutor {
+    constructor(client, eventEmitter) {
+        this.client = client;
+        this.eventEmitter = eventEmitter;
+    }
+    /**
+     * Execute a batch of operations
+     */
+    async execute(operations, options = {}) {
+        const { continueOnError = true, maxConcurrency = 5, enableRollback = false, onOperationComplete, onBatchComplete, } = options;
+        const startTime = Date.now();
+        const results = [];
+        const successfulOperations = [];
+        try {
+            // Resolve operation dependencies and references
+            const resolvedOperations = await this.resolveOperations(operations);
+            // Execute operations with dependency resolution
+            const semaphore = new Semaphore(maxConcurrency);
+            const operationResults = new Map();
+            const executeOperationWithDependencies = async (operation, index) => {
+                // Wait for dependencies to complete
+                if (operation.dependencies && operation.dependencies.length > 0) {
+                    const dependencyPromises = operation.dependencies.map(depId => {
+                        // Handle index-based dependencies
+                        if (depId.startsWith('$index_')) {
+                            const depIndex = parseInt(depId.substring(7));
+                            const depOperation = resolvedOperations[depIndex];
+                            if (!depOperation) {
+                                throw new Error(`Dependency at index ${depIndex} not found`);
+                            }
+                            const depResult = operationResults.get(depOperation.id);
+                            if (!depResult) {
+                                throw new Error(`Dependency '${depOperation.id}' not found in operations list`);
+                            }
+                            return depResult;
+                        }
+                        else {
+                            // Handle operation ID-based dependencies
+                            const depResult = operationResults.get(depId);
+                            if (!depResult) {
+                                throw new Error(`Dependency '${depId}' not found in operations list`);
+                            }
+                            return depResult;
+                        }
+                    });
+                    await Promise.all(dependencyPromises);
+                }
+                await semaphore.acquire();
+                try {
+                    // Create a function to get current results for reference resolution
+                    const getCurrentResults = () => results;
+                    const result = await this.executeOperation(operation, getCurrentResults);
+                    const batchResult = {
+                        index,
+                        operation,
+                        success: true,
+                        data: result,
+                    };
+                    results.push(batchResult);
+                    successfulOperations.push(operation);
+                    onOperationComplete?.(batchResult);
+                    return batchResult;
+                }
+                catch (error) {
+                    const batchResult = {
+                        index,
+                        operation,
+                        success: false,
+                        error: error,
+                    };
+                    results.push(batchResult);
+                    if (!continueOnError) {
+                        throw error;
+                    }
+                    onOperationComplete?.(batchResult);
+                    return batchResult;
+                }
+                finally {
+                    semaphore.release();
+                }
+            };
+            // Create promises for all operations
+            const operationPromises = resolvedOperations.map((operation, index) => {
+                const promise = executeOperationWithDependencies(operation, index);
+                operationResults.set(operation.id, promise);
+                return promise;
+            });
+            await Promise.all(operationPromises);
+            const summary = {
+                total: operations.length,
+                successful: results.filter(r => r.success).length,
+                failed: results.filter(r => !r.success).length,
+                successRate: results.length > 0 ? results.filter(r => r.success).length / results.length : 0,
+                duration: Date.now() - startTime,
+                results,
+            };
+            onBatchComplete?.(results);
+            return summary;
+        }
+        catch (error) {
+            // Rollback successful operations if enabled
+            if (enableRollback && successfulOperations.length > 0) {
+                await this.rollbackOperations(successfulOperations);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Resolve operation dependencies and references
+     */
+    async resolveOperations(operations) {
+        const resolved = [];
+        for (let i = 0; i < operations.length; i++) {
+            const operation = operations[i];
+            const resolvedOperation = { ...operation };
+            // Resolve references in data
+            if (operation.data) {
+                resolvedOperation.resolvedData = await this.resolveReferences(operation.data, resolved);
+            }
+            // Determine dependencies
+            resolvedOperation.dependencies = this.findDependencies(operation, i);
+            resolved.push(resolvedOperation);
+        }
+        return resolved;
+    }
+    /**
+     * Resolve references in operation data
+     */
+    async resolveReferences(data, previousResults) {
+        if (typeof data === 'string') {
+            // Convert ResolvedBatchOperation[] to BatchResult[] for resolveStringReferences
+            const batchResults = previousResults.map((op, index) => ({
+                index,
+                operation: op,
+                success: true,
+                data: op.resolvedData || op.data,
+            }));
+            return this.resolveStringReferences(data, batchResults);
+        }
+        if (Array.isArray(data)) {
+            return Promise.all(data.map(item => this.resolveReferences(item, previousResults)));
+        }
+        if (data && typeof data === 'object') {
+            const resolved = {};
+            for (const [key, value] of Object.entries(data)) {
+                resolved[key] = await this.resolveReferences(value, previousResults);
+            }
+            return resolved;
+        }
+        return data;
+    }
+    /**
+     * Resolve string references like "$0.id" or "$1.data.attributes.name"
+     */
+    resolveStringReferences(str, previousResults) {
+        return str.replace(/\$(\d+)\.([\w.]+)/g, (match, indexStr, path) => {
+            const index = parseInt(indexStr);
+            if (index < previousResults.length) {
+                const result = previousResults[index];
+                // For simple references like $0.id, look in result.data.id
+                if (path === 'id' && result.data?.id) {
+                    return String(result.data.id);
+                }
+                // For other paths, look in result.data
+                const value = this.getNestedValue(result.data, path);
+                return value !== undefined ? String(value) : match;
+            }
+            return match;
+        });
+    }
+    /**
+     * Get nested value from object using dot notation
+     */
+    getNestedValue(obj, path) {
+        return path.split('.').reduce((current, key) => {
+            return current && current[key] !== undefined ? current[key] : undefined;
+        }, obj);
+    }
+    /**
+     * Find dependencies for an operation
+     */
+    findDependencies(operation, currentIndex) {
+        const dependencies = [];
+        // If operation has explicit dependencies, use those
+        if (operation.dependencies && Array.isArray(operation.dependencies)) {
+            dependencies.push(...operation.dependencies);
+        }
+        // Also find references to previous operations by index
+        const operationStr = JSON.stringify(operation);
+        const referenceMatches = operationStr.match(/\$(\d+)/g);
+        if (referenceMatches) {
+            for (const match of referenceMatches) {
+                const index = parseInt(match.substring(1));
+                if (index < currentIndex) {
+                    // Convert index to operation ID reference
+                    const depRef = `$index_${index}`;
+                    if (!dependencies.includes(depRef)) {
+                        dependencies.push(depRef);
+                    }
+                }
+            }
+        }
+        return dependencies;
+    }
+    /**
+     * Execute a single operation
+     */
+    async executeOperation(operation, getPreviousResults) {
+        const { type, resolvedData, data, endpoint, resourceType } = operation;
+        const operationData = resolvedData || data;
+        // Check if type is module.method format
+        if (type.includes('.')) {
+            // Existing module.method approach
+            const [module, method] = type.split('.');
+            if (!module || !method) {
+                throw new Error(`Invalid operation type: ${type}`);
+            }
+            // Get the appropriate module
+            const moduleInstance = this.client[module];
+            if (!moduleInstance) {
+                throw new Error(`Unknown module: ${module}`);
+            }
+            // Execute the method
+            const methodFunc = moduleInstance[method];
+            if (typeof methodFunc !== 'function') {
+                throw new Error(`Unknown method: ${module}.${method}`);
+            }
+            return methodFunc.call(moduleInstance, operationData);
+        }
+        else {
+            // New endpoint-based approach
+            const methodMap = {
+                'create': 'POST',
+                'update': 'PATCH',
+                'delete': 'DELETE'
+            };
+            const httpMethod = methodMap[type];
+            if (!httpMethod || !endpoint) {
+                throw new Error(`Invalid operation: ${type} requires endpoint`);
+            }
+            // Resolve endpoint references
+            const previousResults = getPreviousResults();
+            const resolvedEndpoint = this.resolveStringReferences(endpoint, previousResults);
+            // Map endpoint to module and method
+            if (resolvedEndpoint === '/people') {
+                // /people endpoint
+                if (type === 'create') {
+                    return this.client.people.create(operationData);
+                }
+            }
+            else if (resolvedEndpoint.startsWith('/people/') && resolvedEndpoint.includes('/emails')) {
+                // /people/{id}/emails endpoint
+                if (type === 'create') {
+                    const personId = resolvedEndpoint.split('/')[2];
+                    return this.client.people.addEmail(personId, operationData);
+                }
+                else if (type === 'update') {
+                    const parts = resolvedEndpoint.split('/');
+                    const personId = parts[2];
+                    const emailId = parts[4];
+                    return this.client.people.updateEmail(personId, emailId, operationData);
+                }
+                else if (type === 'delete') {
+                    const parts = resolvedEndpoint.split('/');
+                    const personId = parts[2];
+                    const emailId = parts[4];
+                    return this.client.people.deleteEmail(personId, emailId);
+                }
+            }
+            else if (resolvedEndpoint.startsWith('/people/') && resolvedEndpoint.includes('/phone_numbers')) {
+                // /people/{id}/phone_numbers endpoint
+                if (type === 'create') {
+                    const personId = resolvedEndpoint.split('/')[2];
+                    return this.client.people.addPhoneNumber(personId, operationData);
+                }
+                else if (type === 'update') {
+                    const parts = resolvedEndpoint.split('/');
+                    const personId = parts[2];
+                    const phoneId = parts[4];
+                    return this.client.people.updatePhoneNumber(personId, phoneId, operationData);
+                }
+                else if (type === 'delete') {
+                    const parts = resolvedEndpoint.split('/');
+                    const personId = parts[2];
+                    const phoneId = parts[4];
+                    return this.client.people.deletePhoneNumber(personId, phoneId);
+                }
+            }
+            else if (resolvedEndpoint.startsWith('/people/') && !resolvedEndpoint.includes('/emails') && !resolvedEndpoint.includes('/phone_numbers')) {
+                // /people/{id} endpoint
+                if (type === 'update') {
+                    const personId = resolvedEndpoint.split('/')[2];
+                    return this.client.people.update(personId, operationData);
+                }
+                else if (type === 'delete') {
+                    const personId = resolvedEndpoint.split('/')[2];
+                    return this.client.people.delete(personId);
+                }
+            }
+            throw new Error(`Unsupported endpoint for batch operation: ${resolvedEndpoint}`);
+        }
+    }
+    /**
+     * Rollback successful operations
+     */
+    async rollbackOperations(operations) {
+        // Reverse the order for rollback
+        const rollbackOps = [...operations].reverse();
+        for (const operation of rollbackOps) {
+            try {
+                await this.rollbackOperation(operation);
+            }
+            catch (error) {
+                console.error(`Failed to rollback operation ${operation.type}:`, error);
+            }
+        }
+    }
+    /**
+     * Rollback a single operation
+     */
+    async rollbackOperation(operation) {
+        const { type } = operation;
+        const [module, method] = type.split('.');
+        // Determine rollback method based on operation type
+        let rollbackMethod;
+        if (method.startsWith('create')) {
+            rollbackMethod = method.replace('create', 'delete');
+        }
+        else if (method.startsWith('add')) {
+            rollbackMethod = method.replace('add', 'delete');
+        }
+        else {
+            // For other operations, we might need to implement specific rollback logic
+            return;
+        }
+        const moduleInstance = this.client[module];
+        if (moduleInstance && typeof moduleInstance[rollbackMethod] === 'function') {
+            // This is a simplified rollback - in practice, you'd need to store
+            // the created resource IDs to properly rollback
+            console.warn(`Rollback not fully implemented for ${type}`);
+        }
+    }
+}
+exports.BatchExecutor = BatchExecutor;
+/**
+ * Semaphore for controlling concurrency
+ */
+class Semaphore {
+    constructor(permits) {
+        this.waiting = [];
+        this.permits = permits;
+    }
+    async acquire() {
+        if (this.permits > 0) {
+            this.permits--;
+            return;
+        }
+        return new Promise(resolve => {
+            this.waiting.push(resolve);
+        });
+    }
+    release() {
+        this.permits++;
+        if (this.waiting.length > 0) {
+            const resolve = this.waiting.shift();
+            this.permits--;
+            resolve();
+        }
+    }
+}