@rachelallyson/planning-center-people-ts 2.14.1 → 3.1.0

package/dist/testing/types.d.ts

@@ -141,6 +141,10 @@ export interface RecordingConfig {
     filter?: (endpoint: string, method: string) => boolean;
     /** Transform recorded responses */
     transform?: (response: any) => any;
+    /** Optional getConfig for debug logging (e.g. when recording client has debug) */
+    getConfig?: () => {
+        debug?: boolean | import('@rachelallyson/planning-center-base-ts').PcoDebugOptions;
+    };
 }
 export interface RecordedRequest {
     endpoint: string;

package/dist/types/api-options.d.ts

@@ -0,0 +1,380 @@
+/**
+ * Strictly typed API options for Planning Center People API endpoints
+ * Based on official API documentation: https://developer.planning.center/docs
+ */
+/**
+ * Valid include values for Person endpoint
+ */
+export type PersonInclude = 'addresses' | 'emails' | 'field_data' | 'households' | 'inactive_reason' | 'marital_status' | 'name_prefix' | 'name_suffix' | 'organization' | 'person_apps' | 'phone_numbers' | 'platform_notifications' | 'primary_campus' | 'school' | 'social_profiles';
+/**
+ * Valid order fields for Person endpoint (prefix with '-' for descending)
+ */
+export type PersonOrderField = 'accounting_administrator' | 'anniversary' | 'birthdate' | 'child' | 'created_at' | 'first_name' | 'gender' | 'given_name' | 'grade' | 'graduation_year' | 'inactivated_at' | 'last_name' | 'membership' | 'middle_name' | 'nickname' | 'people_permissions' | 'remote_id' | 'site_administrator' | 'status' | 'updated_at';
+/**
+ * Strictly typed where clause for Person endpoint
+ */
+export interface PersonWhereClause {
+    accounting_administrator?: boolean;
+    anniversary?: string;
+    birthdate?: string;
+    child?: boolean;
+    created_at?: string;
+    first_name?: string;
+    gender?: string;
+    given_name?: string;
+    grade?: number;
+    graduation_year?: number;
+    id?: string;
+    inactivated_at?: string | null;
+    last_name?: string;
+    medical_notes?: string;
+    membership?: string;
+    mfa_configured?: boolean;
+    middle_name?: string;
+    nickname?: string;
+    people_permissions?: string;
+    primary_campus_id?: number;
+    remote_id?: number;
+    search_name?: string;
+    search_name_or_email?: string;
+    search_name_or_email_or_phone_number?: string;
+    search_phone_number?: string;
+    search_phone_number_e164?: string;
+    site_administrator?: boolean;
+    status?: string;
+    updated_at?: string;
+}
+/**
+ * Strictly typed options for Person getAll() - no pagination options
+ */
+export interface PersonListOptions {
+    /** Filter by specific fields */
+    where?: PersonWhereClause;
+    /** Include related resources */
+    include?: PersonInclude[];
+    /** Order by field (prefix with '-' for descending) */
+    order?: PersonOrderField | `-${PersonOrderField}`;
+}
+/**
+ * Strictly typed options for Person getPage() - includes pagination
+ */
+export interface PersonPageOptions extends PersonListOptions {
+    /** Items per page (1-100, default: 25) */
+    perPage?: number;
+    /** Page number */
+    page?: number;
+}
+/**
+ * Valid include values for FieldDefinition endpoint
+ */
+export type FieldDefinitionInclude = 'tab' | 'field_options';
+/**
+ * Valid order fields for FieldDefinition endpoint
+ */
+export type FieldDefinitionOrderField = 'config' | 'data_type' | 'deleted_at' | 'name' | 'sequence' | 'slug' | 'tab_id';
+/**
+ * Strictly typed where clause for FieldDefinition endpoint
+ */
+export interface FieldDefinitionWhereClause {
+    config?: string;
+    data_type?: string;
+    deleted_at?: string;
+    name?: string;
+    sequence?: number;
+    slug?: string;
+    tab_id?: string;
+}
+/**
+ * Strictly typed options for FieldDefinition list endpoints
+ */
+export interface FieldDefinitionListOptions {
+    /** Include related resources */
+    include?: FieldDefinitionInclude[];
+    /** Filter by specific fields */
+    where?: FieldDefinitionWhereClause;
+    /** Order by field (prefix with '-' for descending) */
+    order?: FieldDefinitionOrderField | `-${FieldDefinitionOrderField}`;
+    /** Include deleted field definitions */
+    includeDeleted?: boolean;
+}
+export type FieldDataOrderField = 'file' | 'file_content_type' | 'file_name' | 'file_size' | 'value';
+export interface FieldDataWhereClause {
+    field_definition_id?: number;
+    file?: string;
+    file_content_type?: string;
+    file_name?: string;
+    file_size?: number;
+    value?: string;
+}
+export interface FieldDataOptions {
+    /** Include related resources */
+    include?: ('field_definition' | 'field_option' | 'tab')[];
+    /** Filter by specific fields */
+    where?: FieldDataWhereClause;
+    /** Order by field (prefix with '-' for descending) */
+    order?: FieldDataOrderField | `-${FieldDataOrderField}`;
+}
+/**
+ * Valid include values for Workflow endpoint
+ */
+export type WorkflowInclude = 'category' | 'shares' | 'steps';
+/**
+ * Valid order fields for Workflow endpoint
+ */
+export type WorkflowOrderField = 'archived_at' | 'campus_id' | 'created_at' | 'deleted_at' | 'name' | 'updated_at' | 'workflow_category_id';
+/**
+ * Strictly typed where clause for Workflow endpoint
+ */
+export interface WorkflowWhereClause {
+    archived_at?: string;
+    campus_id?: string;
+    created_at?: string;
+    deleted_at?: string;
+    id?: string;
+    name?: string;
+    updated_at?: string;
+    workflow_category_id?: string;
+}
+/**
+ * Strictly typed options for Workflow getAll() - no pagination options
+ */
+export interface WorkflowListOptions {
+    /** Filter by specific fields */
+    where?: WorkflowWhereClause;
+    /** Include related resources */
+    include?: WorkflowInclude[];
+    /** Order by field (prefix with '-' for descending) */
+    order?: WorkflowOrderField | `-${WorkflowOrderField}`;
+}
+/**
+ * Strictly typed options for Workflow getPage() - includes pagination
+ */
+export interface WorkflowPageOptions extends WorkflowListOptions {
+    /** Items per page (1-100, default: 25) */
+    perPage?: number;
+    /** Page number */
+    page?: number;
+}
+/**
+ * Valid include values for Note endpoint
+ */
+export type NoteInclude = 'note_category' | 'created_by' | 'person' | 'organization';
+/**
+ * Valid order fields for Note endpoint
+ */
+export type NoteOrderField = 'created_at' | 'display_date' | 'id' | 'note' | 'note_category_id' | 'updated_at';
+/**
+ * Strictly typed where clause for Note endpoint
+ */
+export interface NoteWhereClause {
+    note?: string;
+    note_category_id?: string;
+}
+/**
+ * Strictly typed options for Note getAll() - no pagination options
+ */
+export interface NoteListOptions {
+    /** Filter by specific fields */
+    where?: NoteWhereClause;
+    /** Include related resources */
+    include?: NoteInclude[];
+    /** Order by field (prefix with '-' for descending) */
+    order?: NoteOrderField | `-${NoteOrderField}`;
+}
+/**
+ * Strictly typed options for Note getPage() - includes pagination
+ */
+export interface NotePageOptions extends NoteListOptions {
+    /** Items per page (1-100, default: 25) */
+    perPage?: number;
+    /** Page number */
+    page?: number;
+}
+/**
+ * Valid include values for List endpoint
+ */
+export type ListInclude = 'campus' | 'category' | 'created_by' | 'mailchimp_sync_status' | 'people' | 'rules' | 'shares' | 'updated_by';
+/**
+ * Valid order fields for List endpoint
+ */
+export type ListOrderField = 'batch_completed_at' | 'campus_id' | 'created_at' | 'list_categories.name' | 'list_category_id' | 'name' | 'name_or_description' | 'updated_at';
+/**
+ * Strictly typed where clause for List endpoint
+ */
+export interface ListWhereClause {
+    batch_completed_at?: string;
+    created_at?: string;
+    id?: string;
+    list_category_id?: string;
+    name?: string;
+    updated_at?: string;
+}
+/**
+ * Strictly typed options for List getAll() - no pagination options
+ */
+export interface ListListOptions {
+    /** Filter by specific fields */
+    where?: ListWhereClause;
+    /** Include related resources */
+    include?: ListInclude[];
+    /** Order by field (prefix with '-' for descending) */
+    order?: ListOrderField | `-${ListOrderField}`;
+}
+/**
+ * Strictly typed options for List getPage() - includes pagination
+ */
+export interface ListPageOptions extends ListListOptions {
+    /** Items per page (1-100, default: 25) */
+    perPage?: number;
+    /** Page number */
+    page?: number;
+}
+/**
+ * Valid include values for Household endpoint
+ */
+export type HouseholdInclude = 'people' | 'primary_contact';
+/**
+ * Valid order fields for Household endpoint
+ */
+export type HouseholdOrderField = 'created_at' | 'member_count' | 'name' | 'primary_contact_name' | 'updated_at';
+/**
+ * Strictly typed where clause for Household endpoint
+ */
+export interface HouseholdWhereClause {
+    created_at?: string;
+    member_count?: number;
+    name?: string;
+    updated_at?: string;
+}
+/**
+ * Strictly typed options for Household getAll() - no pagination options
+ */
+export interface HouseholdListOptions {
+    /** Filter by specific fields */
+    where?: HouseholdWhereClause;
+    /** Include related resources */
+    include?: HouseholdInclude[];
+    /** Order by field (prefix with '-' for descending) */
+    order?: HouseholdOrderField | `-${HouseholdOrderField}`;
+}
+/**
+ * Strictly typed options for Household getPage() - includes pagination
+ */
+export interface HouseholdPageOptions extends HouseholdListOptions {
+    /** Items per page (1-100, default: 25) */
+    perPage?: number;
+    /** Page number */
+    page?: number;
+}
+/**
+ * Valid include values for Campus endpoint
+ */
+export type CampusInclude = 'organization' | 'lists' | 'service_times';
+/**
+ * Valid order fields for Campus endpoint
+ */
+export type CampusOrderField = 'created_at' | 'name' | 'updated_at';
+/**
+ * Strictly typed where clause for Campus endpoint
+ */
+export interface CampusWhereClause {
+    created_at?: string;
+    id?: string;
+    updated_at?: string;
+}
+/**
+ * Strictly typed options for Campus getAll() - no pagination options
+ */
+export interface CampusListOptions {
+    /** Filter by specific fields */
+    where?: CampusWhereClause;
+    /** Include related resources */
+    include?: CampusInclude[];
+    /** Order by field (prefix with '-' for descending) */
+    order?: CampusOrderField | `-${CampusOrderField}`;
+}
+/**
+ * Strictly typed options for Campus getPage() - includes pagination
+ */
+export interface CampusPageOptions extends CampusListOptions {
+    /** Items per page (1-100, default: 25) */
+    perPage?: number;
+    /** Page number */
+    page?: number;
+}
+/**
+ * Strictly typed where clause for Form endpoint
+ */
+export interface FormWhereClause {
+    active?: boolean;
+    id?: string;
+}
+/**
+ * Strictly typed options for Form getAll() - no pagination options
+ */
+export interface FormListOptions {
+    /** Filter by specific fields */
+    where?: FormWhereClause;
+    /** Include related resources */
+    include?: string[];
+    /** Order by field (prefix with '-' for descending) */
+    order?: string;
+}
+/**
+ * Strictly typed options for Form getPage() - includes pagination
+ */
+export interface FormPageOptions extends FormListOptions {
+    /** Items per page (1-100, default: 25) */
+    perPage?: number;
+    /** Page number */
+    page?: number;
+}
+/**
+ * Strictly typed where clause for Report endpoint
+ */
+export interface ReportWhereClause {
+    body?: string;
+    created_at?: string;
+    name?: string;
+    updated_at?: string;
+}
+/**
+ * Strictly typed options for Report getAll() - no pagination options
+ */
+export interface ReportListOptions {
+    /** Filter by specific fields */
+    where?: ReportWhereClause;
+    /** Include related resources */
+    include?: string[];
+    /** Order by field (prefix with '-' for descending) */
+    order?: string;
+}
+/**
+ * Strictly typed options for Report getPage() - includes pagination
+ */
+export interface ReportPageOptions extends ReportListOptions {
+    /** Items per page (1-100, default: 25) */
+    perPage?: number;
+    /** Page number */
+    page?: number;
+}
+/**
+ * Strictly typed options for ServiceTime getAll() - no pagination options
+ */
+export interface ServiceTimeListOptions {
+    /** Filter by specific fields - Note: ServiceTime endpoint does not support where[] filtering */
+    where?: never;
+    /** Include related resources */
+    include?: string[];
+    /** Order by field (prefix with '-' for descending) */
+    order?: string;
+}
+/**
+ * Strictly typed options for ServiceTime getPage() - includes pagination
+ */
+export interface ServiceTimePageOptions extends ServiceTimeListOptions {
+    /** Items per page (1-100, default: 25) */
+    perPage?: number;
+    /** Page number */
+    page?: number;
+}

package/dist/types/api-options.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Strictly typed API options for Planning Center People API endpoints
+ * Based on official API documentation: https://developer.planning.center/docs
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/client.d.ts

@@ -1,6 +1,8 @@
 /**
  * v2.0.0 Client Configuration Types
  *
- * Re-exports from base package for convenience
+ * Re-exports from base package for consistency. Debug options live in base so all PCO packages share the same behavior.
  */
-export type { PcoClientConfig, PcoAuthConfig, PersonalAccessTokenAuth, OAuthAuth, BasicAuth, ErrorEvent, AuthFailureEvent, RequestStartEvent, RequestCompleteEvent, RateLimitEvent, CacheEvent, } from '@rachelallyson/planning-center-base-ts';
+export type { PcoClientConfig, PcoAuthConfig, PcoDebugOptions, PersonalAccessTokenAuth, OAuthAuth, BasicAuth, ErrorEvent, AuthFailureEvent, RequestStartEvent, RequestCompleteEvent, RateLimitEvent, CacheEvent, } from '@rachelallyson/planning-center-base-ts';
+/** Alias for PcoClientConfig (base now includes debug). Use for clarity in People package. */
+export type PeopleClientConfig = import('@rachelallyson/planning-center-base-ts').PcoClientConfig;

package/dist/types/client.js

@@ -2,6 +2,6 @@
 /**
  * v2.0.0 Client Configuration Types
  *
- * Re-exports from base package for convenience
+ * Re-exports from base package for consistency. Debug options live in base so all PCO packages share the same behavior.
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

@@ -1,3 +1,3 @@
 export type { JsonValue, Meta, LinkObject, Link, Links, PaginationLinks, TopLevelLinks, TopLevelJsonApi, ResourceIdentifier, Relationship, ToOne, ToMany, Attributes, ResourceObject, JsonApiBase, ErrorObject, ErrorDocument, DataDocumentSingle, DataDocumentMany, JsonApiDocument, Paginated, Response, } from '@rachelallyson/planning-center-base-ts';
 export * from './people';
-export type { AddressAttributes, AddressesList, AddressResource, AddressSingle, EmailAttributes, EmailResource, EmailSingle, EmailsList, FieldDefinitionAttributes, FieldDefinitionResource, FieldDefinitionSingle, FieldDefinitionsList, FieldOptionAttributes, FieldOptionResource, FieldOptionSingle, FieldOptionsList, HouseholdAttributes, HouseholdResource, HouseholdSingle, HouseholdsList, PeopleList, PersonAttributes, PersonRelationships, PersonResource, PersonSingle, PhoneNumberAttributes, PhoneNumberResource, PhoneNumberSingle, PhoneNumbersList, SocialProfileAttributes, SocialProfileResource, SocialProfileSingle, SocialProfilesList, } from './people';
+export type { AddressAttributes, AddressesList, AddressResource, AddressSingle, EmailAttributes, EmailResource, EmailSingle, EmailsList, FieldDefinitionAttributes, FieldDefinitionResource, FieldDefinitionSingle, FieldDefinitionsList, FieldOptionAttributes, FieldOptionResource, FieldOptionSingle, FieldOptionsList, HouseholdAttributes, HouseholdResource, HouseholdSingle, HouseholdsList, PeopleList, PersonAttributes, PersonRelationships, PersonRelationshipMap, FlattenedPersonResource, PersonResource, PersonSingle, PhoneNumberAttributes, PhoneNumberResource, PhoneNumberSingle, PhoneNumbersList, SocialProfileAttributes, SocialProfileResource, SocialProfileSingle, SocialProfilesList, } from './people';

package/dist/types/people.d.ts

@@ -3,6 +3,7 @@
  * Based on JSON:API 1.0 specification
  */
 import { Attributes, Paginated, Relationship, ResourceObject, Response } from './json-api';
+import type { FlattenedResource } from '@rachelallyson/planning-center-base-ts';
 export interface PersonAttributes extends Attributes {
     first_name?: string;
     last_name?: string;
@@ -50,11 +51,32 @@ export interface PersonRelationships {
 }
 export interface PersonResource extends ResourceObject<'Person', PersonAttributes, PersonRelationships> {
 }
+/**
+ * Mapping of Person relationship keys to their resource types
+ * Used for proper typing of flattened relationships
+ */
+export type PersonRelationshipMap = {
+    emails: EmailResource[];
+    phone_numbers: PhoneNumberResource[];
+    addresses: AddressResource[];
+    household: HouseholdResource;
+    primary_campus: CampusResource;
+    gender: ResourceObject<string, any, any>;
+    workflow_cards: WorkflowCardResource[];
+    notes: NoteResource[];
+    field_data: FieldDatumResource[];
+    social_profiles: SocialProfileResource[];
+};
+/**
+ * Flattened Person resource type with properly typed relationships
+ * Relationships are typed as their actual resource types, not Relationship wrappers
+ */
+export type FlattenedPersonResource = FlattenedResource<PersonResource['type'], PersonAttributes, PersonRelationships, PersonRelationshipMap>;
 export type PeopleList = Paginated<PersonResource, PeopleIncluded>;
 export type PersonSingle = Response<PersonResource>;
 export interface EmailAttributes extends Attributes {
-    address?: string;
-    location?: string;
+    address: string;
+    location: 'Home' | 'Work' | 'Other';
     primary?: boolean;
     created_at?: string;
     updated_at?: string;
@@ -68,8 +90,8 @@ export interface EmailResource extends ResourceObject<'Email', EmailAttributes,
 export type EmailsList = Paginated<EmailResource>;
 export type EmailSingle = Response<EmailResource>;
 export interface PhoneNumberAttributes extends Attributes {
-    number?: string;
-    location?: string;
+    number: string;
+    location: 'Home' | 'Work' | 'Other';
     primary?: boolean;
     created_at?: string;
     updated_at?: string;
@@ -169,12 +191,13 @@ export interface FieldOptionResource extends ResourceObject<'FieldOption', Field
 }
 export type FieldOptionsList = Paginated<FieldOptionResource>;
 export type FieldOptionSingle = Response<FieldOptionResource>;
+export interface FieldDatumFileMetadata {
+    url?: string | null;
+    [key: string]: string | number | boolean | null | undefined;
+}
 export interface FieldDatumAttributes extends Attributes {
     value?: string | null;
-    file?: {
-        url?: string | null;
-        [key: string]: any;
-    } | null;
+    file?: FieldDatumFileMetadata | null;
     file_content_type?: string | null;
     file_name?: string | null;
     file_size?: string | number | null;
@@ -186,6 +209,20 @@ export interface FieldDatumRelationships {
 }
 export interface FieldDatumResource extends ResourceObject<'FieldDatum', FieldDatumAttributes, FieldDatumRelationships> {
 }
+/**
+ * Mapping of FieldDatum relationship keys to their resource types
+ * Used for proper typing of flattened relationships
+ */
+export type FieldDatumRelationshipMap = {
+    field_definition: FieldDefinitionResource;
+    field_option: FieldOptionResource;
+    customizable: PersonResource;
+};
+/**
+ * Flattened FieldDatum resource type with properly typed relationships
+ * Relationships are typed as their actual resource types, not Relationship wrappers
+ */
+export type FlattenedFieldDatumResource = FlattenedResource<FieldDatumResource['type'], FieldDatumAttributes, FieldDatumRelationships, FieldDatumRelationshipMap>;
 export type FieldDataList = Paginated<FieldDatumResource>;
 export type FieldDataSingle = Response<FieldDatumResource>;
 export interface ListAttributes extends Attributes {
@@ -236,8 +273,23 @@ export interface ListStarResource extends ResourceObject<'ListStar', ListStarAtt
 }
 export type ListStarsList = Paginated<ListStarResource>;
 export type ListStarSingle = Response<ListStarResource>;
+export interface ListRuleAttributes extends Attributes {
+    group?: string;
+    operator?: string;
+    value?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface ListRuleRelationships {
+    list?: Relationship;
+}
+export interface ListRuleResource extends ResourceObject<'Rule', ListRuleAttributes, ListRuleRelationships> {
+}
+export type ListRulesList = Paginated<ListRuleResource>;
+export type ListRuleSingle = Response<ListRuleResource>;
 export interface NoteAttributes extends Attributes {
-    content?: string;
+    note?: string;
+    note_category_id?: string;
     created_at?: string;
     updated_at?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rachelallyson/planning-center-people-ts",
-    "version": "2.14.1",
+    "version": "3.1.0",
     "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",
@@ -39,12 +39,12 @@
     "license": "MIT",
     "devDependencies": {
         "@types/jest": "^30.0.0",
-        "@types/node": "^20.0.0",
-        "dotenv": "^16.6.1",
+        "@types/node": "^25.0.10",
+        "dotenv": "^17.2.3",
         "jest": "^30.2.0",
-        "ts-jest": "^29.4.4",
+        "ts-jest": "^29.4.6",
         "tslib": "^2.8.1",
-        "typedoc": "^0.28.14",
+        "typedoc": "^0.28.16",
         "typedoc-plugin-markdown": "^4.9.0",
         "typescript": "^5.9.3"
     },
@@ -69,7 +69,7 @@
         "access": "public"
     },
     "dependencies": {
-        "@rachelallyson/planning-center-base-ts": "^1.0.0",
-        "form-data": "^4.0.4"
+        "@rachelallyson/planning-center-base-ts": "^1.1.0",
+        "form-data": "^4.0.5"
     }
 }

package/dist/core/http.d.ts

@@ -1,56 +0,0 @@
-/**
- * v2.0.0 HTTP Client
- */
-import type { PcoClientConfig } from '../types/client';
-import { PcoEventEmitter } from '@rachelallyson/planning-center-base-ts';
-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 attemptTokenRefresh;
-    private updateRateLimitTracking;
-    getPerformanceMetrics(): Record<string, {
-        count: number;
-        averageTime: number;
-        minTime: number;
-        maxTime: number;
-        errorRate: number;
-    }>;
-    getRateLimitInfo(): Record<string, {
-        limit: number;
-        remaining: number;
-        resetTime: number;
-    }>;
-    /**
-     * Get authentication header for external services (like file uploads)
-     */
-    getAuthHeader(): string;
-    /**
-     * Make HTTPS request using Node.js HTTPS module (fallback when fetch is unavailable)
-     */
-    private makeHttpsRequest;
-}