@rachelallyson/planning-center-people-ts 2.6.3 → 2.7.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.7.0] - 2025-01-11
+
+### 🚀 **RATE LIMITING IMPROVEMENTS**
+
+This release updates the rate limiting implementation to match Planning Center's actual API specifications and adds enhanced error handling capabilities.
+
+### Added
+
+- **📊 Enhanced Rate Limiting**: Updated default rate limits to match PCO's actual API (100 requests per 20 seconds)
+- **🔄 Dynamic Period Adjustment**: Automatically adapts to server-provided time periods via `X-PCO-API-Request-Rate-Period` header
+- **🔍 Error Parsing**: New `parseRateLimitError()` method extracts detailed information from 429 error responses
+- **📝 Error Message Parsing**: Handles error messages like `"Rate limit exceeded: 118 of 100 requests per 20 seconds"`
+- **🧪 Comprehensive Testing**: Added 22 rate limiter tests with new 20-second window and error parsing tests
+
+### Changed
+
+- **⚡ Rate Limit Defaults**: Changed from 100 requests per 60 seconds to 100 requests per 20 seconds
+- **📚 Documentation**: Updated all documentation to reflect correct rate limiting specifications
+- **🔧 Header Synchronization**: Enhanced parsing of `X-PCO-API-Request-Rate-Period` header for dynamic window adjustment
+- **📖 Configuration Examples**: Updated client configuration examples with proper rate limiting settings
+
+### Fixed
+
+- **🎯 API Compliance**: Now correctly follows Planning Center's actual API rate limits
+- **🔄 Server Synchronization**: Better rate limit tracking that stays in sync with PCO's servers
+- **📊 Debug Information**: Enhanced visibility into rate limit status and remaining requests
+
+### Technical Details
+
+- **Backward Compatible**: No breaking changes - existing code continues to work
+- **Future-Proof**: Automatically adapts to PCO rate limit changes via header synchronization
+- **Performance**: More accurate rate limiting reduces 429 errors and improves API efficiency
+
 ## [2.6.3] - 2025-01-10
 
 ### 🏢 **CAMPUS ATTRIBUTES ENHANCEMENT**

package/README.md

@@ -9,7 +9,7 @@ A modern, type-safe TypeScript library for interacting with the Planning Center
 - ✅ **Strict TypeScript**: Full type safety with no `any` types
 - ✅ **JSON:API 1.0 Compliant**: Follows the JSON:API specification exactly
 - ✅ **Functional Approach**: Clean, composable functions instead of classes
-- ✅ **Rate Limiting**: Built-in rate limiting with PCO's 100 req/min policy
+- ✅ **Rate Limiting**: Built-in rate limiting with PCO's 100 req/20s policy
 - ✅ **Modern HTTP**: Uses native fetch API (no external dependencies)
 - ✅ **Authentication**: Supports both Personal Access Tokens and OAuth 2.0
 - ✅ **Enhanced Error Handling**: Comprehensive error handling with categories, severity, and retry logic
@@ -505,7 +505,7 @@ See [TYPE_VALIDATION_SUMMARY.md](./TYPE_VALIDATION_SUMMARY.md) for detailed docu
 
 - All test data is automatically cleaned up
 - Uses descriptive test names (e.g., "TEST_INTEGRATION_2025")
-- Respects PCO rate limits (90 requests per 20 seconds)
+- Respects PCO rate limits (100 requests per 20 seconds)
 - 30-second timeout per test
 - Comprehensive error handling
 

package/dist/core/http.js

@@ -15,7 +15,7 @@ class PcoHttpClient {
         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
+        this.rateLimiter = new rate_limiter_1.PcoRateLimiter(100, 20000); // 100 requests per 20 seconds
     }
     async request(options) {
         const requestId = this.requestIdGenerator.generate();

package/dist/core.js

@@ -23,7 +23,7 @@ function createPcoClient(config) {
     // Initialize rate limiter
     const rateLimitConfig = config.rateLimit ?? {
         maxRequests: 100,
-        perMilliseconds: 60000,
+        perMilliseconds: 20000, // 20 seconds
     };
     const rateLimiter = new rate_limiter_1.PcoRateLimiter(rateLimitConfig.maxRequests, rateLimitConfig.perMilliseconds);
     return {

package/dist/rate-limiter.d.ts

@@ -2,9 +2,10 @@
  * PCO Rate Limiter
  *
  * Planning Center Online has the following rate limits:
- * - 100 requests per minute (60 seconds)
+ * - 100 requests per 20 seconds (subject to change)
  * - Rate limit headers are returned on every response
  * - 429 responses include Retry-After header
+ * - Limits and time periods can change dynamically
  *
  * This rate limiter tracks requests and enforces these limits.
  */
@@ -56,6 +57,14 @@ export declare class PcoRateLimiter {
      * Update the sliding window
      */
     private updateWindow;
+    /**
+     * Parse rate limit error details from 429 response
+     */
+    static parseRateLimitError(errorDetail: string): {
+        current: number;
+        limit: number;
+        period: number;
+    } | null;
     /**
      * Get debug information
      */

package/dist/rate-limiter.js

@@ -3,9 +3,10 @@
  * PCO Rate Limiter
  *
  * Planning Center Online has the following rate limits:
- * - 100 requests per minute (60 seconds)
+ * - 100 requests per 20 seconds (subject to change)
  * - Rate limit headers are returned on every response
  * - 429 responses include Retry-After header
+ * - Limits and time periods can change dynamically
  *
  * This rate limiter tracks requests and enforces these limits.
  */
@@ -15,8 +16,8 @@ class PcoRateLimiter {
     constructor(limit, windowMs) {
         this.requestCount = 0;
         this.windowStart = Date.now();
-        this.defaultLimit = 100; // requests per minute
-        this.defaultWindow = 60000; // 60 seconds in milliseconds
+        this.defaultLimit = 100; // requests per 20 seconds
+        this.defaultWindow = 20000; // 20 seconds in milliseconds
         this.limit = limit || this.defaultLimit;
         this.windowMs = windowMs || this.defaultWindow;
     }
@@ -60,6 +61,13 @@ class PcoRateLimiter {
         if (headers['X-PCO-API-Request-Rate-Limit']) {
             this.limit = parseInt(headers['X-PCO-API-Request-Rate-Limit'], 10);
         }
+        if (headers['X-PCO-API-Request-Rate-Period']) {
+            // Update window period from server (in seconds, convert to milliseconds)
+            const periodSeconds = parseInt(headers['X-PCO-API-Request-Rate-Period'], 10);
+            if (!isNaN(periodSeconds)) {
+                this.windowMs = periodSeconds * 1000;
+            }
+        }
         if (headers['X-PCO-API-Request-Rate-Count']) {
             this.requestCount = parseInt(headers['X-PCO-API-Request-Rate-Count'], 10);
         }
@@ -97,6 +105,21 @@ class PcoRateLimiter {
             this.requestCount = 0;
         }
     }
+    /**
+     * Parse rate limit error details from 429 response
+     */
+    static parseRateLimitError(errorDetail) {
+        // Parse error like "Rate limit exceeded: 118 of 100 requests per 20 seconds"
+        const match = errorDetail.match(/Rate limit exceeded: (\d+) of (\d+) requests per (\d+) seconds/);
+        if (match) {
+            return {
+                current: parseInt(match[1], 10),
+                limit: parseInt(match[2], 10),
+                period: parseInt(match[3], 10)
+            };
+        }
+        return null;
+    }
     /**
      * Get debug information
      */

package/dist/types/people.d.ts

@@ -384,6 +384,7 @@ export interface OrganizationStatisticResource extends ResourceObject<'Organizat
 export type OrganizationStatisticsList = Paginated<OrganizationStatisticResource>;
 export type OrganizationStatisticSingle = Response<OrganizationStatisticResource>;
 export interface CampusAttributes extends Attributes {
+    name: string;
     latitude?: number;
     longitude?: number;
     description?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rachelallyson/planning-center-people-ts",
-    "version": "2.6.3",
+    "version": "2.7.0",
     "description": "A strictly typed TypeScript client for Planning Center Online People API with smart matching, batch operations, and enhanced developer experience",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",