@rachelallyson/planning-center-people-ts 2.8.0 → 2.9.1

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@rachelallyson/planning-center-people-ts",
-    "version": "2.8.0",
-    "description": "A strictly typed TypeScript client for Planning Center Online People API with smart matching, batch operations, and enhanced developer experience",
+    "version": "2.9.1",
+    "description": "A strictly typed TypeScript client for Planning Center Online People API with comprehensive functionality and enhanced developer experience",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
@@ -13,11 +13,9 @@
         "test:watch": "jest --watch --testPathIgnorePatterns=integration.test.ts",
         "test:coverage": "jest --coverage --testPathIgnorePatterns=integration.test.ts",
         "test:ci": "jest --ci --coverage --watchAll=false --testPathIgnorePatterns=integration.test.ts",
-        "test:integration": "dotenv -e .env.test -- jest --testPathPatterns=integration.test.ts --setupFilesAfterEnv='<rootDir>/tests/integration-setup.ts' --testTimeout=30000",
-        "test:integration:people-all": "dotenv -e .env.test -- jest --testPathPatterns=integration/people-.*.integration.test.ts --setupFilesAfterEnv='<rootDir>/tests/integration-setup.ts' --testTimeout=30000",
-        "test:integration:v2:all": "dotenv -e .env.test -- jest --testPathPatterns=integration/v2/.*.integration.test.ts --setupFilesAfterEnv='<rootDir>/tests/integration-setup.ts' --testTimeout=30000",
-        "test:edge-cases": "jest --testPathPatterns=edge-cases.test.ts --testTimeout=30000",
-        "test:all": "npm run test && npm run test:edge-cases",
+        "test:integration": "dotenv -e .env.test -- jest --testPathPatterns=integration/.*.integration.test.ts --setupFilesAfterEnv='<rootDir>/tests/integration-setup.ts' --testTimeout=60000",
+        "docs": "typedoc",
+        "docs:watch": "typedoc --watch",
         "prepublishOnly": "npm run build"
     },
     "keywords": [
@@ -29,26 +27,25 @@
         "json-api",
         "people",
         "church",
-        "crm",
         "client",
         "sdk",
         "rate-limiting",
         "error-handling",
-        "performance",
-        "caching",
         "batch-operations",
-        "smart-matching",
         "fluent-api",
-        "event-system",
-        "client-manager"
+        "event-system"
     ],
-    "author": "Rachel Higley",
+    "author": "Rachel Allyson",
     "license": "MIT",
     "devDependencies": {
         "@types/jest": "^30.0.0",
+        "@types/node": "^20.0.0",
         "dotenv": "^16.6.1",
         "jest": "^30.2.0",
         "ts-jest": "^29.4.4",
+        "tslib": "^2.8.1",
+        "typedoc": "^0.28.14",
+        "typedoc-plugin-markdown": "^4.9.0",
         "typescript": "^5.9.3"
     },
     "files": [
@@ -59,12 +56,12 @@
     ],
     "repository": {
         "type": "git",
-        "url": "https://github.com/rachelallyson/planning-center-people-ts.git"
+        "url": "https://github.com/rachelallyson/planning-center-monorepo.git"
     },
     "bugs": {
-        "url": "https://github.com/rachelallyson/planning-center-people-ts/issues"
+        "url": "https://github.com/rachelallyson/planning-center-monorepo/issues"
     },
-    "homepage": "https://github.com/rachelallyson/planning-center-people-ts#readme",
+    "homepage": "https://github.com/rachelallyson/planning-center-monorepo#readme",
     "engines": {
         "node": ">=16.0.0"
     },
@@ -72,6 +69,7 @@
         "access": "public"
     },
     "dependencies": {
+        "@rachelallyson/planning-center-base-ts": "^1.0.0",
         "form-data": "^4.0.4"
     }
 }

package/dist/api-error.d.ts

@@ -1,10 +0,0 @@
-import type { RateLimitHeaders } from './rate-limiter';
-import type { ErrorObject as JsonApiError } from './types';
-export declare class PcoApiError extends Error {
-    readonly status: number;
-    readonly statusText: string;
-    readonly errors: JsonApiError[];
-    readonly rateLimitHeaders?: RateLimitHeaders;
-    constructor(message: string, status: number, statusText: string, errors: JsonApiError[], rateLimitHeaders?: RateLimitHeaders);
-    static fromFetchError(response: Response, data?: unknown): PcoApiError;
-}

package/dist/api-error.js

@@ -1,32 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PcoApiError = void 0;
-// ===== PCO API Error =====
-class PcoApiError extends Error {
-    constructor(message, status, statusText, errors, rateLimitHeaders) {
-        super(message);
-        this.name = 'PcoApiError';
-        this.status = status;
-        this.statusText = statusText;
-        this.errors = errors;
-        this.rateLimitHeaders = rateLimitHeaders;
-    }
-    static fromFetchError(response, data) {
-        const status = response.status;
-        const statusText = response.statusText;
-        const apiErrors = Array.isArray(data?.errors)
-            ? data.errors || []
-            : [];
-        const rateLimitHeaders = {
-            'Retry-After': response.headers.get('retry-after') ?? undefined,
-            'X-PCO-API-Request-Rate-Count': response.headers.get('x-pco-api-request-rate-count') ?? undefined,
-            'X-PCO-API-Request-Rate-Limit': response.headers.get('x-pco-api-request-rate-limit') ?? undefined,
-            'X-PCO-API-Request-Rate-Period': response.headers.get('x-pco-api-request-rate-period') ?? undefined,
-        };
-        const message = apiErrors.length > 0
-            ? apiErrors.map(e => e.detail ?? e.title ?? 'Unknown error').join('; ')
-            : statusText;
-        return new PcoApiError(message, status, statusText, apiErrors, rateLimitHeaders);
-    }
-}
-exports.PcoApiError = PcoApiError;

package/dist/batch.d.ts

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1,376 +0,0 @@
-"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();
-        }
-    }
-}

package/dist/modules/base.d.ts

@@ -1,46 +0,0 @@
-/**
- * v2.0.0 Base Module Class
- */
-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 { ResourceObject } from '../types';
-export declare abstract class BaseModule {
-    protected httpClient: PcoHttpClient;
-    protected paginationHelper: PaginationHelper;
-    protected eventEmitter: PcoEventEmitter;
-    constructor(httpClient: PcoHttpClient, paginationHelper: PaginationHelper, eventEmitter: PcoEventEmitter);
-    /**
-     * Get a single resource
-     */
-    protected getSingle<T extends ResourceObject<string, any, any>>(endpoint: string, params?: Record<string, any>): Promise<T>;
-    /**
-     * Get a list of resources
-     */
-    protected getList<T extends ResourceObject<string, any, any>>(endpoint: string, params?: Record<string, any>): Promise<{
-        data: T[];
-        meta?: any;
-        links?: any;
-    }>;
-    /**
-     * Create a resource
-     */
-    protected createResource<T extends ResourceObject<string, any, any>>(endpoint: string, data: any, params?: Record<string, any>): Promise<T>;
-    /**
-     * Update a resource
-     */
-    protected updateResource<T extends ResourceObject<string, any, any>>(endpoint: string, data: any, params?: Record<string, any>): Promise<T>;
-    /**
-     * Delete a resource
-     */
-    protected deleteResource(endpoint: string, params?: Record<string, any>): Promise<void>;
-    /**
-     * Get all pages of a resource
-     */
-    protected getAllPages<T extends ResourceObject<string, any, any>>(endpoint: string, params?: Record<string, any>, options?: PaginationOptions): Promise<PaginationResult<T>>;
-    /**
-     * Stream pages of a resource
-     */
-    protected streamPages<T extends ResourceObject<string, any, any>>(endpoint: string, params?: Record<string, any>, options?: PaginationOptions): AsyncGenerator<T[], void, unknown>;
-}

package/dist/modules/base.js

@@ -1,82 +0,0 @@
-"use strict";
-/**
- * v2.0.0 Base Module Class
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseModule = void 0;
-class BaseModule {
-    constructor(httpClient, paginationHelper, eventEmitter) {
-        this.httpClient = httpClient;
-        this.paginationHelper = paginationHelper;
-        this.eventEmitter = eventEmitter;
-    }
-    /**
-     * Get a single resource
-     */
-    async getSingle(endpoint, params) {
-        const response = await this.httpClient.request({
-            method: 'GET',
-            endpoint,
-            params,
-        });
-        return response.data.data;
-    }
-    /**
-     * Get a list of resources
-     */
-    async getList(endpoint, params) {
-        const response = await this.httpClient.request({
-            method: 'GET',
-            endpoint,
-            params,
-        });
-        return response.data;
-    }
-    /**
-     * Create a resource
-     */
-    async createResource(endpoint, data, params) {
-        const response = await this.httpClient.request({
-            method: 'POST',
-            endpoint,
-            data,
-            params,
-        });
-        return response.data.data;
-    }
-    /**
-     * Update a resource
-     */
-    async updateResource(endpoint, data, params) {
-        const response = await this.httpClient.request({
-            method: 'PATCH',
-            endpoint,
-            data,
-            params,
-        });
-        return response.data.data;
-    }
-    /**
-     * Delete a resource
-     */
-    async deleteResource(endpoint, params) {
-        await this.httpClient.request({
-            method: 'DELETE',
-            endpoint,
-            params,
-        });
-    }
-    /**
-     * Get all pages of a resource
-     */
-    async getAllPages(endpoint, params, options) {
-        return this.paginationHelper.getAllPages(endpoint, params, options);
-    }
-    /**
-     * Stream pages of a resource
-     */
-    async *streamPages(endpoint, params, options) {
-        yield* this.paginationHelper.streamPages(endpoint, params, options);
-    }
-}
-exports.BaseModule = BaseModule;