@rachelallyson/planning-center-people-ts 2.14.0 → 3.0.0

package/dist/error-scenarios.js

@@ -56,8 +56,12 @@ function isRetryableError(error, retryableStatuses) {
         return retryableStatuses.includes(error.status);
     }
     // Network errors are generally retryable
-    if (error.name === 'TypeError' && error.message.includes('fetch')) {
-        return true;
+    if (error && typeof error === 'object' && 'name' in error && 'message' in error) {
+        const errorName = error.name;
+        const errorMessage = error.message;
+        if (errorName === 'TypeError' && typeof errorMessage === 'string' && errorMessage.includes('fetch')) {
+            return true;
+        }
     }
     return false;
 }
@@ -198,7 +202,11 @@ function classifyError(error) {
     if (error instanceof planning_center_base_ts_1.PcoApiError) {
         return classifyPcoError(error);
     }
-    if (error.name === 'TypeError' && error.message.includes('fetch')) {
+    // Type guard for Error-like objects
+    const isErrorLike = (e) => {
+        return typeof e === 'object' && e !== null;
+    };
+    if (isErrorLike(error) && error.name === 'TypeError' && error.message?.includes('fetch')) {
         return {
             category: 'network',
             retryable: true,
@@ -206,7 +214,7 @@ function classifyError(error) {
             userMessage: 'Network connection error. Please check your internet connection.',
         };
     }
-    if (error.message.includes('timeout')) {
+    if (isErrorLike(error) && error.message?.includes('timeout')) {
         return {
             category: 'network',
             retryable: true,
@@ -282,11 +290,14 @@ function classifyPcoError(error) {
             userMessage: 'The requested resource was not found.',
         };
     }
+    const isErrorLike = (e) => {
+        return typeof e === 'object' && e !== null;
+    };
     return {
         category: 'unknown',
         retryable: false,
         severity: 'medium',
-        userMessage: error.message || 'An error occurred while processing your request.',
+        userMessage: (isErrorLike(error) && error.message) || 'An error occurred while processing your request.',
     };
 }
 // ===== Error Recovery =====
@@ -329,6 +340,11 @@ async function attemptRecovery(operation, error, context) {
  */
 function createErrorReport(error, context) {
     const classification = classifyError(error);
+    // Type guard for error-like objects
+    const isErrorLike = (e) => {
+        return typeof e === 'object' && e !== null;
+    };
+    const errorObj = isErrorLike(error) ? error : {};
     return {
         classification,
         context: {
@@ -340,11 +356,11 @@ function createErrorReport(error, context) {
             requestInfo: context.requestInfo,
         },
         error: {
-            errors: error.errors,
-            message: error.message || 'Unknown error',
-            name: error.name || 'UnknownError',
-            stack: error.stack,
-            status: error.status,
+            errors: errorObj.errors,
+            message: errorObj.message || 'Unknown error',
+            name: errorObj.name || 'UnknownError',
+            stack: errorObj.stack,
+            status: errorObj.status,
         },
         operation: context.operation,
         timestamp: new Date().toISOString(),

package/dist/helpers.d.ts

@@ -1,16 +1,7 @@
-import type { PcoClientState } from './core';
-import type { ErrorContext } from './error-handling';
-import type { PersonAttributes, EmailAttributes, PhoneNumberAttributes, AddressAttributes, WorkflowCardNoteAttributes, PeopleList, PersonSingle, EmailSingle, PhoneNumberSingle, AddressSingle, WorkflowCardSingle, WorkflowCardNoteSingle, ListsList, ListCategoriesList, OrganizationSingle } from './types';
-/**
- * Transform complex params object into flat query params for API calls
- */
-export declare function buildQueryParams(params?: {
-    where?: Record<string, any>;
-    include?: string[];
-    per_page?: number;
-    page?: number;
-    filter?: string;
-}): Record<string, any>;
+import type { PcoClient } from './client';
+import type { ResourceObject, ResourceIdentifier } from './types/json-api';
+import { mapIncludedToRelationships as baseMapIncludedToRelationships } from '@rachelallyson/planning-center-base-ts';
+import type { PersonAttributes, PersonResource, EmailAttributes, PhoneNumberAttributes, AddressAttributes, WorkflowCardNoteAttributes, PeopleList, ListsList, ListCategoriesList, EmailResource, PhoneNumberResource, AddressResource, FieldDatumResource, WorkflowCardResource, EmailsList, PhoneNumbersList, AddressesList, OrganizationResource, WorkflowCardNoteResource, Meta, TopLevelLinks, ListResource, HouseholdResource } from './types';
 /**
  * Calculate age from birthdate string
  */
@@ -131,7 +122,7 @@ export interface TrustResult {
  * @param trustWindow - Trust window in milliseconds (default: 1 hour)
  * @returns Object with trust decision, age, and reason
  *
- * @example
+ * @gmail.com
  * ```typescript
  * const trust = calculateTrust(pcoInfo.personIdCreatedAt);
  * if (trust.shouldTrust) {
@@ -166,7 +157,7 @@ export declare function validatePersonData(data: Partial<PersonAttributes>): {
 /**
  * Get primary contact information for a person
  */
-export declare function getPrimaryContact(client: PcoClientState, personId: string, context?: Partial<ErrorContext>): Promise<{
+export declare function getPrimaryContact(client: PcoClient, personId: string): Promise<{
     email?: string;
     phone?: string;
     address?: string;
@@ -174,45 +165,61 @@ export declare function getPrimaryContact(client: PcoClientState, personId: stri
 /**
  * Create a person with contact information
  */
-export declare function createPersonWithContact(client: PcoClientState, personData: Partial<PersonAttributes>, contactData?: {
+export declare function createPersonWithContact(client: PcoClient, personData: Partial<PersonAttributes>, contactData?: {
     email?: Partial<EmailAttributes>;
     phone?: Partial<PhoneNumberAttributes>;
     address?: Partial<AddressAttributes>;
-}, context?: Partial<ErrorContext>): Promise<{
-    person: PersonSingle;
-    email?: EmailSingle;
-    phone?: PhoneNumberSingle;
-    address?: AddressSingle;
+}): Promise<{
+    person: PersonResource;
+    email?: EmailResource;
+    phone?: PhoneNumberResource;
+    address?: AddressResource;
 }>;
 /**
  * Search people by multiple criteria
  */
-export declare function searchPeople(client: PcoClientState, criteria: {
+export declare function searchPeople(client: PcoClient, criteria: {
     status?: string;
     name?: string;
     email?: string;
-    per_page?: number;
-}, context?: Partial<ErrorContext>): Promise<PeopleList>;
+    perPage?: number;
+    page?: number;
+}): Promise<PeopleList>;
 /**
  * Get people by household
  */
-export declare function getPeopleByHousehold(client: PcoClientState, householdId: string, context?: Partial<ErrorContext>): Promise<PeopleList>;
+export declare function getPeopleByHousehold(client: PcoClient, householdId: string): Promise<{
+    data: import("@rachelallyson/planning-center-base-ts").FlattenedResource<"Person", PersonAttributes, import("./types").PersonRelationships, import("./types").PersonRelationshipMap>[];
+    totalCount: number;
+    pagesFetched: number;
+    duration: number;
+    meta?: Meta;
+    links?: TopLevelLinks;
+}>;
 /**
  * Get complete person profile with all related data
  */
-export declare function getCompletePersonProfile(client: PcoClientState, personId: string, context?: Partial<ErrorContext>): Promise<{
-    person: PersonSingle;
-    emails: any;
-    phones: any;
-    addresses: any;
-    fieldData: any;
-    workflowCards: any;
+export declare function getCompletePersonProfile(client: PcoClient, personId: string): Promise<{
+    person: PersonResource;
+    emails: EmailsList;
+    phones: PhoneNumbersList;
+    addresses: AddressesList;
+    fieldData: {
+        data: FieldDatumResource[];
+        meta?: Meta;
+        links?: TopLevelLinks;
+    };
+    workflowCards: {
+        data: WorkflowCardResource[];
+        meta?: Meta;
+        links?: TopLevelLinks;
+    };
 }>;
 /**
  * Get organization info with statistics
  */
-export declare function getOrganizationInfo(client: PcoClientState, context?: Partial<ErrorContext>): Promise<{
-    organization: OrganizationSingle;
+export declare function getOrganizationInfo(client: PcoClient): Promise<{
+    organization: OrganizationResource | null;
     stats: {
         totalPeople: number;
         totalHouseholds: number;
@@ -222,42 +229,111 @@ export declare function getOrganizationInfo(client: PcoClientState, context?: Pa
 /**
  * Get lists with their categories
  */
-export declare function getListsWithCategories(client: PcoClientState, context?: Partial<ErrorContext>): Promise<{
+export declare function getListsWithCategories(client: PcoClient): Promise<{
     lists: ListsList;
     categories: ListCategoriesList;
 }>;
 /**
  * Get workflow cards with notes for a person
  */
-export declare function getPersonWorkflowCardsWithNotes(client: PcoClientState, personId: string, context?: Partial<ErrorContext>): Promise<{
-    workflowCards: any;
+export declare function getPersonWorkflowCardsWithNotes(client: PcoClient, personId: string): Promise<{
+    workflowCards: {
+        data: WorkflowCardResource[];
+        meta?: Meta;
+        links?: TopLevelLinks;
+    };
     notes: {
-        [cardId: string]: any;
+        [cardId: string]: {
+            data: WorkflowCardNoteResource[];
+            meta?: Meta;
+            links?: TopLevelLinks;
+        };
     };
 }>;
 /**
  * Create a workflow card with a note
  */
-export declare function createWorkflowCardWithNote(client: PcoClientState, workflowId: string, personId: string, noteData: Partial<WorkflowCardNoteAttributes>, context?: Partial<ErrorContext>): Promise<{
-    workflowCard: WorkflowCardSingle;
-    note: WorkflowCardNoteSingle;
+export declare function createWorkflowCardWithNote(client: PcoClient, workflowId: string, personId: string, noteData: Partial<WorkflowCardNoteAttributes>): Promise<{
+    workflowCard: WorkflowCardResource;
+    note: WorkflowCardNoteResource;
 }>;
 /**
  * Export all people data in a structured format
  */
-export declare function exportAllPeopleData(client: PcoClientState, options?: {
+export declare function exportAllPeopleData(client: PcoClient, options?: {
     includeInactive?: boolean;
     includeFieldData?: boolean;
     includeWorkflowCards?: boolean;
-    perPage?: number;
-}, context?: Partial<ErrorContext>): Promise<{
-    people: any[];
-    households: any[];
-    lists: any[];
-    organization: any;
+}): Promise<{
+    people: PersonResource[];
+    households: HouseholdResource[];
+    lists: ListResource[];
+    organization: OrganizationResource | null;
     exportDate: string;
     totalCount: number;
 }>;
+/**
+ * Find an included resource by type and id
+ *
+ * In JSON:API, relationships contain resource identifiers like { type: 'Email', id: '456' }
+ * This helper finds the full resource object from the included array.
+ *
+ * @param included - Array of included resources from JSON:API response
+ * @param type - Resource type to find
+ * @param id - Resource id to find
+ * @returns The matching resource object, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const person = await client.people.getPage({ include: ['emails'] });
+ * // Data is flattened: person.data[0].emails is the resolved array
+ * const email = person.data[0].emails?.[0];
+ * console.log(email?.address); // 'john@gmail.com'
+ * ```
+ */
+export declare function findIncluded<T extends ResourceObject<string, any, any> = ResourceObject<string, any, any>>(included: ResourceObject<string, any, any>[] | undefined, type: string, id: string): T | undefined;
+/**
+ * Resolve all resources from a relationship to their full included objects
+ *
+ * Takes a relationship's data array (which contains resource identifiers)
+ * and resolves them to full resource objects from the included array.
+ *
+ * @param included - Array of included resources from JSON:API response
+ * @param relationshipData - Relationship data array (from relationships.xxx.data)
+ * @returns Array of full resource objects, or empty array if none found
+ *
+ * @example
+ * ```typescript
+ * const person = await client.people.getPage({ include: ['emails', 'phone_numbers'] });
+ * // Data is flattened: person.data[0].emails is the resolved array
+ * const emails = person.data[0].emails ?? [];
+ * emails.forEach(email => console.log(email.address));
+ * ```
+ */
+export declare function resolveIncluded<T extends ResourceObject<string, any, any> = ResourceObject<string, any, any>>(included: ResourceObject<string, any, any>[] | undefined, relationshipData: ResourceIdentifier | ResourceIdentifier[] | null | undefined): T[];
+/**
+ * Create a lookup map for included resources by type and id
+ *
+ * This is more efficient than calling findIncluded() multiple times.
+ *
+ * @param included - Array of included resources from JSON:API response
+ * @returns Map with key format "type:id" -> resource object
+ *
+ * @gmail.com
+ * ```typescript
+ * const person = await client.people.getPage({ include: ['emails', 'phone_numbers'] });
+ * const lookup = createIncludedLookup(person.included);
+ * const email = lookup.get('Email:456'); // Fast lookup
+ * ```
+ */
+export declare function createIncludedLookup(included: ResourceObject<string, any, any>[] | undefined): Map<string, ResourceObject<string, any, any>>;
+/**
+ * Automatically map included resources to their relationships
+ *
+ * Re-exported from @rachelallyson/planning-center-base-ts for convenience.
+ * The mapping is now automatically applied in getList()/getPage() methods.
+ */
+export declare const mapIncludedToRelationships: typeof baseMapIncludedToRelationships;
 /**
  * Extracts clean URL from HTML markup that contains file links
  * Handles cases like: <a href="https://onark.s3.us-east-1.amazonaws.com/file.pdf" download>View File: https://onark.s3.us-east-1.amazonaws.com/file.pdf</a>