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

package/CHANGELOG.md

@@ -5,7 +5,254 @@ 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).
 
-## [1.0.0] - 2024-01-XX
+## [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
+
+## [1.1.0] - 2025-10-08
+
+### Added
+
+- **Complete API Modularization**: Split monolithic `people.ts` into 9 focused modules for better maintainability
+- **36 New API Functions**: Complete coverage of all PCO People API endpoints
+- **File Upload Support**: New file handling capabilities with smart field type detection
+- **Comprehensive Integration Tests**: 9 new integration test suites with 2,660+ lines of test coverage
+- **Enhanced Helper Functions**: New file processing utilities and validation functions
+- **Complete Function Checklist**: Comprehensive documentation of all available functions
+
+### New API Functions
+
+#### Core People Operations (`src/people/core.ts`)
+
+- `getPeople()` - Get all people with filtering and pagination
+- `getPerson()` - Get single person by ID
+- `createPerson()` - Create new person
+- `updatePerson()` - Update existing person
+- `deletePerson()` - Delete person
+
+#### Contact Management (`src/people/contacts.ts`)
+
+- `getPersonEmails()` - Get all emails for a person
+- `createPersonEmail()` - Create email for a person
+- `getPersonPhoneNumbers()` - Get all phone numbers for a person
+- `createPersonPhoneNumber()` - Create phone number for a person
+- `getPersonAddresses()` - Get all addresses for a person
+- `createPersonAddress()` - Create address for a person
+- `updatePersonAddress()` - Update existing address
+- `getPersonSocialProfiles()` - Get social profiles for a person
+- `createPersonSocialProfile()` - Create social profile for a person
+- `deleteSocialProfile()` - Delete social profile
+
+#### Field Data Management (`src/people/fields.ts`)
+
+- `createPersonFieldData()` - Create field data with smart file handling
+- `deletePersonFieldData()` - Delete field data
+- `getPersonFieldData()` - Get custom field data for a person
+- `getFieldDefinitions()` - Get all field definitions
+- `getFieldDefinition()` - Get single field definition
+- `getFieldOptions()` - Get field options for a field definition
+- `createFieldOption()` - Create field option
+- `getTabs()` - Get field definition tabs
+- `createFieldDefinition()` - Create new field definition
+- `deleteFieldDefinition()` - Delete field definition
+
+#### Household Operations (`src/people/households.ts`)
+
+- `getHouseholds()` - Get all households
+- `getHousehold()` - Get single household by ID
+
+#### List Management (`src/people/lists.ts`)
+
+- `getLists()` - Get all people lists
+- `getListById()` - Get single list by ID
+- `getListCategories()` - Get all list categories
+
+#### Note Operations (`src/people/notes.ts`)
+
+- `getNotes()` - Get all notes
+- `getNote()` - Get single note by ID
+- `getNoteCategories()` - Get all note categories
+
+#### Workflow Management (`src/people/workflows.ts`)
+
+- `getWorkflowCardNotes()` - Get notes for a workflow card
+- `createWorkflowCardNote()` - Create note for workflow card
+- `getWorkflowCards()` - Get workflow cards for a person
+- `createWorkflowCard()` - Create workflow card for a person
+- `getWorkflows()` - Get all workflows
+- `getWorkflow()` - Get single workflow by ID
+
+#### Organization Operations (`src/people/organization.ts`)
+
+- `getOrganization()` - Get organization information
+
+### New Helper Functions
+
+#### File Upload Utilities
+
+- `extractFileUrl()` - Extract clean URLs from HTML markup
+- `isFileUrl()` - Check if string is a valid file URL
+- `getFileExtension()` - Extract file extension from URL
+- `getFilename()` - Extract filename from URL
+- `isFileUpload()` - Detect if value contains file upload
+- `processFileValue()` - Smart processing of file values based on field type
+
+#### Enhanced Validation
+
+- `validatePersonData()` - Comprehensive person data validation
+- `isValidEmail()` - Email format validation
+- `isValidPhone()` - Phone number format validation
+
+#### Utility Functions
+
+- `formatPersonName()` - Format person names with nickname support
+- `formatDate()` - Flexible date formatting
+- `calculateAge()` - Calculate age from birthdate
+- `buildQueryParams()` - Transform complex params to flat query params
+
+### Testing
+
+- **9 New Integration Test Suites**: Complete integration testing for all API modules
+- **2,660+ Lines of Test Code**: Comprehensive test coverage for all new functions
+- **File Upload Testing**: Dedicated tests for file handling functionality
+- **Edge Case Coverage**: Testing for error scenarios and edge cases
+- **Type Validation**: Runtime validation of all API responses
+
+### Documentation
+
+- **Function Checklist**: Complete documentation of all 36 available functions
+- **File Upload Examples**: New example showing file upload usage patterns
+- **Updated API Guide**: Enhanced documentation with new function examples
+- **Usage Examples**: Comprehensive examples for all new functionality
+
+### Changed
+
+- **Modular Architecture**: Restructured codebase for better maintainability and organization
+- **Enhanced Error Handling**: Improved error handling across all new functions
+- **Type Safety**: Enhanced TypeScript definitions for all new functions
+- **Performance**: Optimized API calls with better parameter handling
+
+### Technical Improvements
+
+- **Better Code Organization**: Logical separation of concerns across modules
+- **Consistent Patterns**: Standardized function signatures and error handling
+- **Enhanced TypeScript**: Improved type definitions and inference
+- **Comprehensive Testing**: Full test coverage for all new functionality
+- **Documentation**: Complete API documentation and usage examples
+
+## [1.0.0] - 2025-01-08
 
 ### Added
 

package/README.md

@@ -14,6 +14,7 @@ A strictly typed TypeScript client for Planning Center Online People API, built
 - ✅ **Automatic Retries**: Configurable exponential backoff with smart retry logic
 - ✅ **Request Timeouts**: Configurable request timeouts
 - ✅ **Pagination**: Automatic pagination support
+- ✅ **File Upload Handling**: Intelligent file upload detection and processing for custom fields
 - ✅ **No Index Signatures**: Clean type definitions without index signatures
 
 ## Installation
@@ -68,6 +69,17 @@ const updatedPerson = await updatePerson(client, 'person-id', {
 
 // Delete a person
 await deletePerson(client, 'person-id');
+
+// Smart file upload handling for custom fields
+import { createPersonFieldData } from '@planning-center-people-ts';
+
+// Automatically determines field type and handles file uploads appropriately
+await createPersonFieldData(
+    client,
+    'person-id',
+    'field-definition-id',
+    '<a href="https://example.com/document.pdf" download>View File</a>'
+);
 ```
 
 ## Configuration
@@ -503,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/auth.d.ts

@@ -0,0 +1,64 @@
+import type { PcoClientState } from './core';
+export interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+}
+export type TokenRefreshCallback = (newTokens: TokenResponse) => void | Promise<void>;
+export type TokenRefreshFailureCallback = (error: Error, context: {
+    originalError?: Error;
+    refreshToken?: string;
+    attemptCount?: number;
+}) => void | Promise<void>;
+export interface PcoClientConfigWithRefresh {
+    /** Personal Access Token (for single-user apps) */
+    personalAccessToken?: string;
+    /** OAuth 2.0 Access Token (for multi-user apps) */
+    accessToken?: string;
+    /** OAuth 2.0 Refresh Token (for multi-user apps) */
+    refreshToken?: string;
+    /** App ID (for Personal Access Token auth) */
+    appId?: string;
+    /** App Secret (for Personal Access Token auth) */
+    appSecret?: string;
+    /** Callback to handle token refresh */
+    onTokenRefresh?: TokenRefreshCallback;
+    /** Callback to handle token refresh failures */
+    onTokenRefreshFailure?: TokenRefreshFailureCallback;
+    /** Base URL override (defaults to people/v2) */
+    baseURL?: string;
+    /** Rate limiting configuration */
+    rateLimit?: {
+        maxRequests: number;
+        perMilliseconds: number;
+    };
+    /** Custom headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: {
+        maxRetries?: number;
+        baseDelay?: number;
+        maxDelay?: number;
+        onRetry?: (error: any, attempt: number) => void;
+    };
+}
+/**
+ * Refresh an OAuth access token using the refresh token
+ */
+export declare function refreshAccessToken(client: PcoClientState, refreshToken: string): Promise<TokenResponse>;
+/**
+ * Update client configuration with new tokens
+ */
+export declare function updateClientTokens(client: PcoClientState, newTokens: TokenResponse): void;
+/**
+ * Check if a client has refresh token capability
+ */
+export declare function hasRefreshTokenCapability(client: PcoClientState): boolean;
+/**
+ * Attempt to refresh tokens and retry the original request
+ */
+export declare function attemptTokenRefresh<T>(client: PcoClientState, originalRequest: () => Promise<T>): Promise<T>;

package/dist/auth.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshAccessToken = refreshAccessToken;
+exports.updateClientTokens = updateClientTokens;
+exports.hasRefreshTokenCapability = hasRefreshTokenCapability;
+exports.attemptTokenRefresh = attemptTokenRefresh;
+/**
+ * Refresh an OAuth access token using the refresh token
+ */
+async function refreshAccessToken(client, refreshToken) {
+    const baseURL = client.config.baseURL ?? 'https://api.planningcenteronline.com';
+    const tokenUrl = `${baseURL}/oauth/token`;
+    // Prepare the request body for token refresh
+    const body = new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+    });
+    // Add client credentials if available
+    if (client.config.appId && client.config.appSecret) {
+        body.append('client_id', client.config.appId);
+        body.append('client_secret', client.config.appSecret);
+    }
+    const response = await fetch(tokenUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'Accept': 'application/json',
+        },
+        body: body.toString(),
+    });
+    if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(`Token refresh failed: ${response.status} ${response.statusText}. ${JSON.stringify(errorData)}`);
+    }
+    const tokenData = await response.json();
+    return tokenData;
+}
+/**
+ * Update client configuration with new tokens
+ */
+function updateClientTokens(client, newTokens) {
+    // Update the client's access token
+    client.config.accessToken = newTokens.access_token;
+    // Update refresh token if provided
+    if (newTokens.refresh_token) {
+        client.config.refreshToken = newTokens.refresh_token;
+    }
+}
+/**
+ * Check if a client has refresh token capability
+ */
+function hasRefreshTokenCapability(client) {
+    return !!(client.config.refreshToken && (client.config.onTokenRefresh || client.config.onTokenRefreshFailure));
+}
+/**
+ * Attempt to refresh tokens and retry the original request
+ */
+async function attemptTokenRefresh(client, originalRequest) {
+    if (!hasRefreshTokenCapability(client)) {
+        throw new Error('No refresh token or callback configured');
+    }
+    try {
+        // Attempt to refresh the token
+        const newTokens = await refreshAccessToken(client, client.config.refreshToken);
+        // Update the client with new tokens
+        updateClientTokens(client, newTokens);
+        // Call the token refresh callback if provided
+        if (client.config.onTokenRefresh) {
+            try {
+                await client.config.onTokenRefresh(newTokens);
+            }
+            catch (callbackError) {
+                // Log callback error but don't fail the token refresh
+                console.warn('Token refresh callback failed:', callbackError);
+            }
+        }
+        // Retry the original request with the new token
+        return await originalRequest();
+    }
+    catch (error) {
+        const refreshError = new Error(`Token refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+        // Call the failure callback if provided
+        if (client.config.onTokenRefreshFailure) {
+            try {
+                await client.config.onTokenRefreshFailure(refreshError, {
+                    originalError: error instanceof Error ? error : undefined,
+                    refreshToken: client.config.refreshToken,
+                    attemptCount: 1, // Could be enhanced to track retry attempts
+                });
+            }
+            catch (callbackError) {
+                // Log callback error but don't fail the refresh error
+                console.warn('Token refresh failure callback failed:', callbackError);
+            }
+        }
+        throw refreshError;
+    }
+}

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;
+}