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

package/dist/client-manager.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * v2.0.0 Client Manager with Caching
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PcoClientManager = void 0;
+const client_1 = require("./client");
+class PcoClientManager {
+    constructor() {
+        this.clientCache = new Map();
+        this.configCache = new Map();
+    }
+    /**
+     * Get the singleton instance
+     */
+    static getInstance() {
+        if (!PcoClientManager.instance) {
+            PcoClientManager.instance = new PcoClientManager();
+        }
+        return PcoClientManager.instance;
+    }
+    /**
+     * Get a client instance with the given configuration
+     */
+    static getClient(config) {
+        return PcoClientManager.getInstance().getClient(config);
+    }
+    /**
+     * Get a client instance for a specific church with config resolution
+     */
+    static async getClientForChurch(churchId, configResolver) {
+        return PcoClientManager.getInstance().getClientForChurch(churchId, configResolver);
+    }
+    /**
+     * Clear the client cache
+     */
+    static clearCache() {
+        PcoClientManager.getInstance().clearCache();
+    }
+    /**
+     * Get a client instance with caching
+     */
+    getClient(config) {
+        const configKey = this.generateConfigKey(config);
+        // Check if we have a cached client
+        let client = this.clientCache.get(configKey);
+        if (!client) {
+            // Create new client
+            client = new client_1.PcoClient(config);
+            this.clientCache.set(configKey, client);
+            this.configCache.set(configKey, { ...config });
+        }
+        else {
+            // Check if config has changed
+            const cachedConfig = this.configCache.get(configKey);
+            if (cachedConfig && this.hasConfigChanged(cachedConfig, config)) {
+                // Update client with new config
+                client.updateConfig(config);
+                this.configCache.set(configKey, { ...config });
+            }
+        }
+        return client;
+    }
+    /**
+     * Get a client instance for a specific church
+     */
+    async getClientForChurch(churchId, configResolver) {
+        const configKey = `church:${churchId}`;
+        // Check if we have a cached client
+        let client = this.clientCache.get(configKey);
+        if (!client) {
+            // Resolve configuration
+            const config = await configResolver(churchId);
+            // Create new client
+            client = new client_1.PcoClient(config);
+            this.clientCache.set(configKey, client);
+            this.configCache.set(configKey, { ...config });
+        }
+        return client;
+    }
+    /**
+     * Clear the client cache
+     */
+    clearCache() {
+        this.clientCache.clear();
+        this.configCache.clear();
+    }
+    /**
+     * Remove a specific client from cache
+     */
+    removeClient(config) {
+        const configKey = this.generateConfigKey(config);
+        this.clientCache.delete(configKey);
+        this.configCache.delete(configKey);
+    }
+    /**
+     * Remove a church client from cache
+     */
+    removeChurchClient(churchId) {
+        const configKey = `church:${churchId}`;
+        this.clientCache.delete(configKey);
+        this.configCache.delete(configKey);
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        const churchClients = Array.from(this.clientCache.keys()).filter(key => key.startsWith('church:')).length;
+        return {
+            clientCount: this.clientCache.size,
+            configCount: this.configCache.size,
+            churchClients,
+        };
+    }
+    /**
+     * Generate a cache key for a configuration
+     */
+    generateConfigKey(config) {
+        // 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,
+            baseURL: config.baseURL,
+            timeout: config.timeout,
+        });
+        // Simple hash function
+        let hash = 0;
+        for (let i = 0; i < configStr.length; i++) {
+            const char = configStr.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32-bit integer
+        }
+        return `config:${Math.abs(hash)}`;
+    }
+    /**
+     * Check if configuration has changed
+     */
+    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 ||
+            oldConfig.timeout !== newConfig.timeout);
+    }
+}
+exports.PcoClientManager = PcoClientManager;

package/dist/client.d.ts

@@ -0,0 +1,71 @@
+/**
+ * v2.0.0 Main PcoClient Class
+ */
+import type { PcoClientConfig } from './types/client';
+import type { EventEmitter } from './types/events';
+import { PeopleModule } from './modules/people';
+import { FieldsModule } from './modules/fields';
+import { WorkflowsModule } from './modules/workflows';
+import { ContactsModule } from './modules/contacts';
+import { HouseholdsModule } from './modules/households';
+import { NotesModule } from './modules/notes';
+import { ListsModule } from './modules/lists';
+import { BatchExecutor } from './batch';
+export declare class PcoClient implements EventEmitter {
+    people: PeopleModule;
+    fields: FieldsModule;
+    workflows: WorkflowsModule;
+    contacts: ContactsModule;
+    households: HouseholdsModule;
+    notes: NotesModule;
+    lists: ListsModule;
+    batch: BatchExecutor;
+    private httpClient;
+    private paginationHelper;
+    private eventEmitter;
+    private config;
+    constructor(config: PcoClientConfig);
+    on<T extends import('./types/events').PcoEvent>(eventType: T['type'], handler: import('./types/events').EventHandler<T>): void;
+    off<T extends import('./types/events').PcoEvent>(eventType: T['type'], handler: import('./types/events').EventHandler<T>): void;
+    emit<T extends import('./types/events').PcoEvent>(event: T): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): PcoClientConfig;
+    /**
+     * Update the configuration
+     */
+    updateConfig(updates: Partial<PcoClientConfig>): void;
+    /**
+     * Get performance metrics
+     */
+    getPerformanceMetrics(): Record<string, {
+        count: number;
+        averageTime: number;
+        minTime: number;
+        maxTime: number;
+        errorRate: number;
+    }>;
+    /**
+     * Get rate limit information
+     */
+    getRateLimitInfo(): Record<string, {
+        limit: number;
+        remaining: number;
+        resetTime: number;
+    }>;
+    /**
+     * Clear all event listeners
+     */
+    removeAllListeners(eventType?: import('./types/events').EventType): void;
+    /**
+     * Get the number of listeners for an event type
+     */
+    listenerCount(eventType: import('./types/events').EventType): number;
+    /**
+     * Get all registered event types
+     */
+    eventTypes(): import('./types/events').EventType[];
+    private setupEventHandlers;
+    private updateModules;
+}

package/dist/client.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * v2.0.0 Main PcoClient Class
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PcoClient = void 0;
+const monitoring_1 = require("./monitoring");
+const http_1 = require("./core/http");
+const pagination_1 = require("./core/pagination");
+const people_1 = require("./modules/people");
+const fields_1 = require("./modules/fields");
+const workflows_1 = require("./modules/workflows");
+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 batch_1 = require("./batch");
+class PcoClient {
+    constructor(config) {
+        this.config = config;
+        this.eventEmitter = new monitoring_1.PcoEventEmitter();
+        this.httpClient = new http_1.PcoHttpClient(config, this.eventEmitter);
+        this.paginationHelper = new pagination_1.PaginationHelper(this.httpClient);
+        // Initialize modules
+        this.people = new people_1.PeopleModule(this.httpClient, this.paginationHelper, this.eventEmitter);
+        this.fields = new fields_1.FieldsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
+        this.workflows = new workflows_1.WorkflowsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
+        this.contacts = new contacts_1.ContactsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
+        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.batch = new batch_1.BatchExecutor(this, this.eventEmitter);
+        // Set up event handlers from config
+        this.setupEventHandlers();
+    }
+    // EventEmitter implementation
+    on(eventType, handler) {
+        this.eventEmitter.on(eventType, handler);
+    }
+    off(eventType, handler) {
+        this.eventEmitter.off(eventType, handler);
+    }
+    emit(event) {
+        this.eventEmitter.emit(event);
+    }
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update the configuration
+     */
+    updateConfig(updates) {
+        this.config = { ...this.config, ...updates };
+        // Recreate HTTP client with new config
+        this.httpClient = new http_1.PcoHttpClient(this.config, this.eventEmitter);
+        this.paginationHelper = new pagination_1.PaginationHelper(this.httpClient);
+        // Update modules with new HTTP client
+        this.updateModules();
+    }
+    /**
+     * Get performance metrics
+     */
+    getPerformanceMetrics() {
+        return this.httpClient.getPerformanceMetrics();
+    }
+    /**
+     * Get rate limit information
+     */
+    getRateLimitInfo() {
+        return this.httpClient.getRateLimitInfo();
+    }
+    /**
+     * Clear all event listeners
+     */
+    removeAllListeners(eventType) {
+        this.eventEmitter.removeAllListeners(eventType);
+    }
+    /**
+     * Get the number of listeners for an event type
+     */
+    listenerCount(eventType) {
+        return this.eventEmitter.listenerCount(eventType);
+    }
+    /**
+     * Get all registered event types
+     */
+    eventTypes() {
+        return this.eventEmitter.eventTypes();
+    }
+    setupEventHandlers() {
+        // Set up config event handlers
+        if (this.config.events?.onError) {
+            this.on('error', this.config.events.onError);
+        }
+        if (this.config.events?.onAuthFailure) {
+            this.on('auth:failure', this.config.events.onAuthFailure);
+        }
+        if (this.config.events?.onRequestStart) {
+            this.on('request:start', this.config.events.onRequestStart);
+        }
+        if (this.config.events?.onRequestComplete) {
+            this.on('request:complete', this.config.events.onRequestComplete);
+        }
+        if (this.config.events?.onRateLimit) {
+            this.on('rate:limit', this.config.events.onRateLimit);
+        }
+    }
+    updateModules() {
+        // Recreate modules with new HTTP client
+        this.people = new people_1.PeopleModule(this.httpClient, this.paginationHelper, this.eventEmitter);
+        this.fields = new fields_1.FieldsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
+        this.workflows = new workflows_1.WorkflowsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
+        this.contacts = new contacts_1.ContactsModule(this.httpClient, this.paginationHelper, this.eventEmitter);
+        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.batch = new batch_1.BatchExecutor(this, this.eventEmitter);
+    }
+}
+exports.PcoClient = PcoClient;

package/dist/core/http.d.ts

@@ -0,0 +1,47 @@
+/**
+ * v2.0.0 HTTP Client
+ */
+import type { PcoClientConfig } from '../types/client';
+import { PcoEventEmitter } from '../monitoring';
+export interface HttpRequestOptions {
+    method: string;
+    endpoint: string;
+    data?: any;
+    params?: Record<string, any>;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+export interface HttpResponse<T = any> {
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+    requestId: string;
+    duration: number;
+}
+export declare class PcoHttpClient {
+    private config;
+    private eventEmitter;
+    private requestIdGenerator;
+    private performanceMetrics;
+    private rateLimitTracker;
+    private rateLimiter;
+    constructor(config: PcoClientConfig, eventEmitter: PcoEventEmitter);
+    request<T = any>(options: HttpRequestOptions): Promise<HttpResponse<T>>;
+    private makeRequest;
+    private addAuthentication;
+    private getResourceTypeFromEndpoint;
+    private extractHeaders;
+    private updateRateLimitTracking;
+    getPerformanceMetrics(): Record<string, {
+        count: number;
+        averageTime: number;
+        minTime: number;
+        maxTime: number;
+        errorRate: number;
+    }>;
+    getRateLimitInfo(): Record<string, {
+        limit: number;
+        remaining: number;
+        resetTime: number;
+    }>;
+}

package/dist/core/http.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * v2.0.0 HTTP Client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+        this.eventEmitter = eventEmitter;
+        this.requestIdGenerator = new monitoring_1.RequestIdGenerator();
+        this.performanceMetrics = new monitoring_1.PerformanceMetrics();
+        this.rateLimitTracker = new monitoring_1.RateLimitTracker();
+        // Initialize rate limiter
+        this.rateLimiter = new rate_limiter_1.PcoRateLimiter(100, 60000); // 100 requests per minute
+    }
+    async request(options) {
+        const requestId = this.requestIdGenerator.generate();
+        const startTime = Date.now();
+        // Emit request start event
+        this.eventEmitter.emit({
+            type: 'request:start',
+            endpoint: options.endpoint,
+            method: options.method,
+            requestId,
+            timestamp: new Date().toISOString(),
+        });
+        try {
+            // Wait for rate limiter
+            await this.rateLimiter.waitForAvailability();
+            const response = await this.makeRequest(options, requestId);
+            const duration = Date.now() - startTime;
+            // Record performance metrics
+            this.performanceMetrics.record(`${options.method} ${options.endpoint}`, duration, true);
+            // Update rate limit tracking
+            this.updateRateLimitTracking(options.endpoint, response.headers);
+            // Emit request complete event
+            this.eventEmitter.emit({
+                type: 'request:complete',
+                endpoint: options.endpoint,
+                method: options.method,
+                status: response.status,
+                duration,
+                requestId,
+                timestamp: new Date().toISOString(),
+            });
+            return response;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            // Record performance metrics
+            this.performanceMetrics.record(`${options.method} ${options.endpoint}`, duration, false);
+            // Emit request error event
+            this.eventEmitter.emit({
+                type: 'request:error',
+                endpoint: options.endpoint,
+                method: options.method,
+                error: error,
+                requestId,
+                timestamp: new Date().toISOString(),
+            });
+            throw error;
+        }
+    }
+    async makeRequest(options, requestId) {
+        const baseURL = this.config.baseURL || 'https://api.planningcenteronline.com/people/v2';
+        let url = options.endpoint.startsWith('http') ? options.endpoint : `${baseURL}${options.endpoint}`;
+        // Add query parameters
+        if (options.params) {
+            const searchParams = new URLSearchParams();
+            Object.entries(options.params).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    searchParams.append(key, String(value));
+                }
+            });
+            const queryString = searchParams.toString();
+            if (queryString) {
+                url += url.includes('?') ? `&${queryString}` : `?${queryString}`;
+            }
+        }
+        // Prepare headers
+        const headers = {
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+            ...this.config.headers,
+            ...options.headers,
+        };
+        // Add authentication
+        this.addAuthentication(headers);
+        // Prepare request options
+        const requestOptions = {
+            headers,
+            method: options.method,
+        };
+        // Add body for POST/PATCH requests
+        if ((options.method === 'POST' || options.method === 'PATCH') && options.data) {
+            // Determine resource type from endpoint
+            const resourceType = this.getResourceTypeFromEndpoint(options.endpoint);
+            // Separate attributes and relationships
+            const { relationships, ...attributes } = options.data;
+            const jsonApiData = {
+                data: {
+                    type: resourceType,
+                    attributes
+                }
+            };
+            // Add relationships if present
+            if (relationships) {
+                jsonApiData.data.relationships = relationships;
+            }
+            requestOptions.body = JSON.stringify(jsonApiData);
+        }
+        // Add timeout
+        const timeout = options.timeout || this.config.timeout || 30000;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        requestOptions.signal = controller.signal;
+        try {
+            const response = await fetch(url, requestOptions);
+            clearTimeout(timeoutId);
+            // Update rate limiter from headers
+            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,
+            };
+            this.rateLimiter.updateFromHeaders(rateLimitHeaders);
+            this.rateLimiter.recordRequest();
+            // Handle 429 responses
+            if (response.status === 429) {
+                await this.rateLimiter.waitForAvailability();
+                return this.makeRequest(options, requestId);
+            }
+            // 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)) {
+                    try {
+                        await (0, auth_1.attemptTokenRefresh)(clientState, () => this.makeRequest(options, requestId));
+                        return this.makeRequest(options, requestId);
+                    }
+                    catch (refreshError) {
+                        console.warn('Token refresh failed:', refreshError);
+                    }
+                }
+                let errorData;
+                try {
+                    errorData = await response.json();
+                }
+                catch {
+                    errorData = {};
+                }
+                throw api_error_1.PcoApiError.fromFetchError(response, errorData);
+            }
+            // Parse response
+            if (options.method === 'DELETE') {
+                return {
+                    data: undefined,
+                    status: response.status,
+                    headers: this.extractHeaders(response),
+                    requestId,
+                    duration: 0, // Will be set by caller
+                };
+            }
+            const data = await response.json();
+            return {
+                data,
+                status: response.status,
+                headers: this.extractHeaders(response),
+                requestId,
+                duration: 0, // Will be set by caller
+            };
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            throw error;
+        }
+    }
+    addAuthentication(headers) {
+        if (this.config.auth.personalAccessToken) {
+            // 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) {
+            headers.Authorization = `Bearer ${this.config.auth.accessToken}`;
+        }
+    }
+    getResourceTypeFromEndpoint(endpoint) {
+        // Extract resource type from endpoint
+        // /households -> Household
+        // /people -> Person
+        // /emails -> Email
+        // etc.
+        const pathParts = endpoint.split('/').filter(part => part.length > 0);
+        const resourcePath = pathParts[pathParts.length - 1];
+        // Convert kebab-case to PascalCase and make singular
+        const pascalCase = resourcePath
+            .split('-')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join('');
+        // Make singular (remove trailing 's' if it exists and the word is longer than 3 characters)
+        if (pascalCase.endsWith('s') && pascalCase.length > 3) {
+            return pascalCase.slice(0, -1);
+        }
+        return pascalCase;
+    }
+    extractHeaders(response) {
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        return headers;
+    }
+    updateRateLimitTracking(endpoint, headers) {
+        const limit = headers['x-pco-api-request-rate-limit'];
+        const remaining = headers['x-pco-api-request-rate-count'];
+        const resetTime = headers['retry-after'];
+        if (limit && remaining && resetTime) {
+            this.rateLimitTracker.update(endpoint, parseInt(limit), parseInt(remaining), Date.now() + parseInt(resetTime) * 1000);
+        }
+    }
+    getPerformanceMetrics() {
+        return this.performanceMetrics.getMetrics();
+    }
+    getRateLimitInfo() {
+        return this.rateLimitTracker.getAllLimits();
+    }
+}
+exports.PcoHttpClient = PcoHttpClient;

package/dist/core/pagination.d.ts

@@ -0,0 +1,34 @@
+/**
+ * v2.0.0 Pagination Utilities
+ */
+import type { ResourceObject, Paginated } from '../types';
+import type { PcoHttpClient } from './http';
+export interface PaginationOptions {
+    /** Maximum number of pages to fetch */
+    maxPages?: number;
+    /** Items per page */
+    perPage?: number;
+    /** Progress callback */
+    onProgress?: (current: number, total: number) => void;
+    /** Delay between requests in milliseconds */
+    delay?: number;
+}
+export interface PaginationResult<T> {
+    data: T[];
+    totalCount: number;
+    pagesFetched: number;
+    duration: number;
+}
+export declare class PaginationHelper {
+    private httpClient;
+    constructor(httpClient: PcoHttpClient);
+    getAllPages<T extends ResourceObject<string, any, any>>(endpoint: string, params?: Record<string, any>, options?: PaginationOptions): Promise<PaginationResult<T>>;
+    getPage<T extends ResourceObject<string, any, any>>(endpoint: string, page?: number, perPage?: number, params?: Record<string, any>): Promise<Paginated<T>>;
+    streamPages<T extends ResourceObject<string, any, any>>(endpoint: string, params?: Record<string, any>, options?: PaginationOptions): AsyncGenerator<T[], void, unknown>;
+    /**
+     * Get all pages with parallel processing for better performance
+     */
+    getAllPagesParallel<T extends ResourceObject<string, any, any>>(endpoint: string, params?: Record<string, any>, options?: PaginationOptions & {
+        maxConcurrency?: number;
+    }): Promise<PaginationResult<T>>;
+}