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

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

package/dist/core/pagination.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * v2.0.0 Pagination Utilities
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginationHelper = void 0;
+class PaginationHelper {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async getAllPages(endpoint, params = {}, options = {}) {
+        // Ensure endpoint is a string
+        if (typeof endpoint !== 'string') {
+            throw new Error(`Expected endpoint to be a string, got ${typeof endpoint}`);
+        }
+        const { maxPages = 1000, perPage = 100, onProgress, delay = 50, } = options;
+        const startTime = Date.now();
+        const allData = [];
+        let page = 1;
+        let hasMore = true;
+        let totalCount = 0;
+        while (hasMore && page <= maxPages) {
+            const response = await this.httpClient.request({
+                method: 'GET',
+                endpoint,
+                params: {
+                    ...params,
+                    page,
+                    per_page: perPage,
+                },
+            });
+            if (response.data.data && Array.isArray(response.data.data)) {
+                allData.push(...response.data.data);
+            }
+            if (response.data.meta?.total_count) {
+                totalCount = Number(response.data.meta.total_count) || 0;
+            }
+            hasMore = !!response.data.links?.next;
+            page++;
+            if (onProgress) {
+                onProgress(allData.length, totalCount || allData.length);
+            }
+            // Add delay between requests to respect rate limits
+            if (hasMore && delay > 0) {
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+        return {
+            data: allData,
+            totalCount,
+            pagesFetched: page - 1,
+            duration: Date.now() - startTime,
+        };
+    }
+    async getPage(endpoint, page = 1, perPage = 100, params = {}) {
+        const response = await this.httpClient.request({
+            method: 'GET',
+            endpoint,
+            params: {
+                ...params,
+                page,
+                per_page: perPage,
+            },
+        });
+        return response.data;
+    }
+    async *streamPages(endpoint, params = {}, options = {}) {
+        const { maxPages = 1000, perPage = 100, delay = 50, } = options;
+        let page = 1;
+        let hasMore = true;
+        while (hasMore && page <= maxPages) {
+            const response = await this.httpClient.request({
+                method: 'GET',
+                endpoint,
+                params: {
+                    ...params,
+                    page,
+                    per_page: perPage,
+                },
+            });
+            if (response.data.data && Array.isArray(response.data.data)) {
+                yield response.data.data;
+            }
+            hasMore = !!response.data.links?.next;
+            page++;
+            if (hasMore && delay > 0) {
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+    }
+    /**
+     * Get all pages with parallel processing for better performance
+     */
+    async getAllPagesParallel(endpoint, params = {}, options = {}) {
+        const { maxPages = 1000, perPage = 100, maxConcurrency = 3, onProgress, } = options;
+        const startTime = Date.now();
+        // First, get the first page to determine total count
+        const firstPage = await this.getPage(endpoint, 1, perPage, params);
+        const totalCount = Number(firstPage.meta?.total_count) || 0;
+        const totalPages = Math.min(Math.ceil(totalCount / perPage), maxPages);
+        const allData = [...(firstPage.data || [])];
+        if (totalPages <= 1) {
+            return {
+                data: allData,
+                totalCount,
+                pagesFetched: 1,
+                duration: Date.now() - startTime,
+            };
+        }
+        // Process remaining pages in parallel batches
+        const remainingPages = Array.from({ length: totalPages - 1 }, (_, i) => i + 2);
+        const semaphore = new Semaphore(maxConcurrency);
+        const pagePromises = remainingPages.map(async (pageNum) => {
+            await semaphore.acquire();
+            try {
+                const page = await this.getPage(endpoint, pageNum, perPage, params);
+                return page.data || [];
+            }
+            finally {
+                semaphore.release();
+            }
+        });
+        const pageResults = await Promise.all(pagePromises);
+        for (const pageData of pageResults) {
+            allData.push(...pageData);
+            if (onProgress) {
+                onProgress(allData.length, totalCount);
+            }
+        }
+        return {
+            data: allData,
+            totalCount,
+            pagesFetched: totalPages,
+            duration: Date.now() - startTime,
+        };
+    }
+}
+exports.PaginationHelper = PaginationHelper;
+/**
+ * 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/core.d.ts

@@ -1,6 +1,7 @@
 import { type ErrorContext, PcoError } from './error-handling';
 import { PcoRateLimiter } from './rate-limiter';
 import { Paginated, ResourceObject, Response as JsonApiResponse } from './types';
+import { type TokenRefreshCallback, type TokenRefreshFailureCallback } from './auth';
 export interface PcoClientConfig {
     /** Personal Access Token (for single-user apps) */
     personalAccessToken?: string;
@@ -8,6 +9,10 @@ export interface PcoClientConfig {
     accessToken?: string;
     /** OAuth 2.0 Refresh Token (for multi-user apps) */
     refreshToken?: string;
+    /** Callback to handle token refresh */
+    onTokenRefresh?: TokenRefreshCallback;
+    /** Callback to handle token refresh failures */
+    onTokenRefreshFailure?: TokenRefreshFailureCallback;
     /** App ID (for Personal Access Token auth) */
     appId?: string;
     /** App Secret (for Personal Access Token auth) */

package/dist/core.js

@@ -11,6 +11,7 @@ exports.getAllPages = getAllPages;
 exports.getRateLimitInfo = getRateLimitInfo;
 const error_handling_1 = require("./error-handling");
 const rate_limiter_1 = require("./rate-limiter");
+const auth_1 = require("./auth");
 // Re-export PcoApiError for convenience
 var api_error_1 = require("./api-error");
 Object.defineProperty(exports, "PcoApiError", { enumerable: true, get: function () { return api_error_1.PcoApiError; } });
@@ -211,6 +212,17 @@ async function makeFetchRequest(client, method, endpoint, data, params, context)
         }
         // Handle other errors
         if (!response.ok) {
+            // Handle 401 errors with token refresh if available
+            if (response.status === 401 && (0, auth_1.hasRefreshTokenCapability)(client)) {
+                try {
+                    // Attempt to refresh the token and retry the request
+                    return await (0, auth_1.attemptTokenRefresh)(client, () => makeFetchRequest(client, method, endpoint, data, params, context));
+                }
+                catch (refreshError) {
+                    // If token refresh fails, fall through to normal error handling
+                    console.warn('Token refresh failed:', refreshError);
+                }
+            }
             let errorData;
             try {
                 errorData = await response.json();