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

package/dist/helpers.d.ts

@@ -1,144 +1,169 @@
+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';
 /**
- * Helper Functions for Common PCO People API Operations
- *
- * This module provides convenient helper functions for common operations
- * that combine multiple API calls or provide higher-level abstractions.
+ * Transform complex params object into flat query params for API calls
  */
-import type { PcoClientState } from './core';
-import type { AddressResource, EmailResource, FieldDatumResource, ListResource, NoteResource, OrganizationResource, PersonResource, PhoneNumberResource, SocialProfileResource, WorkflowCardNoteResource, WorkflowCardResource } from './types';
-/**
- * Get a complete person profile with all related data
- */
-export declare function getCompletePersonProfile(client: PcoClientState, personId: string): Promise<{
-    person: PersonResource;
-    emails: EmailResource[];
-    phoneNumbers: PhoneNumberResource[];
-    addresses: AddressResource[];
-    socialProfiles: SocialProfileResource[];
-    fieldData: FieldDatumResource[];
-    workflowCards: WorkflowCardResource[];
-    notes: NoteResource[];
-}>;
+export declare function buildQueryParams(params?: {
+    where?: Record<string, any>;
+    include?: string[];
+    per_page?: number;
+    page?: number;
+    filter?: string;
+}): Record<string, any>;
+/**
+ * Calculate age from birthdate string
+ */
+export declare function calculateAge(birthdate: string): number;
+/**
+ * Validate email format
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * Validate phone number format (basic validation)
+ */
+export declare function isValidPhone(phone: string): boolean;
+/**
+ * Format person name from attributes
+ */
+export declare function formatPersonName(person: {
+    first_name?: string;
+    last_name?: string;
+    nickname?: string;
+}): string;
 /**
- * Create a person with initial contact information
+ * Format date string in various formats
  */
-export declare function createPersonWithContact(client: PcoClientState, personData: {
-    first_name: string;
-    last_name: string;
+export declare function formatDate(dateString: string, format?: 'short' | 'long' | 'iso'): string;
+/**
+ * Validate person data
+ */
+export declare function validatePersonData(data: Partial<PersonAttributes>): {
+    isValid: boolean;
+    errors: string[];
+};
+/**
+ * Get primary contact information for a person
+ */
+export declare function getPrimaryContact(client: PcoClientState, personId: string, context?: Partial<ErrorContext>): Promise<{
     email?: string;
     phone?: string;
-    address?: {
-        address1: string;
-        city: string;
-        state: string;
-        zip: string;
-    };
-}): Promise<{
-    person: PersonResource;
-    email?: EmailResource;
-    phone?: PhoneNumberResource;
-    address?: AddressResource;
+    address?: string;
 }>;
 /**
- * Search for people by multiple criteria
+ * Create a person with contact information
+ */
+export declare function createPersonWithContact(client: PcoClientState, 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;
+}>;
+/**
+ * Search people by multiple criteria
  */
 export declare function searchPeople(client: PcoClientState, criteria: {
+    status?: string;
     name?: string;
     email?: string;
-    phone?: string;
-    status?: string;
-    household?: string;
-}): Promise<PersonResource[]>;
+    per_page?: number;
+}, context?: Partial<ErrorContext>): Promise<PeopleList>;
 /**
  * Get people by household
  */
-export declare function getPeopleByHousehold(client: PcoClientState, householdId: string): Promise<PersonResource[]>;
-/**
- * Get all workflow cards for a person with their notes
- */
-export declare function getPersonWorkflowCardsWithNotes(client: PcoClientState, personId: string): Promise<(WorkflowCardResource & {
-    notes: WorkflowCardNoteResource[];
-})[]>;
+export declare function getPeopleByHousehold(client: PcoClientState, householdId: string, context?: Partial<ErrorContext>): Promise<PeopleList>;
 /**
- * Create a workflow card with an initial note
+ * Get complete person profile with all related data
  */
-export declare function createWorkflowCardWithNote(client: PcoClientState, personId: string, workflowId: string, cardData: {
-    title: string;
-    description?: string;
-    initialNote?: string;
-}): Promise<{
-    card: WorkflowCardResource;
-    note?: WorkflowCardNoteResource;
+export declare function getCompletePersonProfile(client: PcoClientState, personId: string, context?: Partial<ErrorContext>): Promise<{
+    person: PersonSingle;
+    emails: any;
+    phones: any;
+    addresses: any;
+    fieldData: any;
+    workflowCards: any;
 }>;
 /**
- * Get all lists with their categories
+ * Get organization info with statistics
  */
-export declare function getListsWithCategories(client: PcoClientState): Promise<(ListResource & {
-    category?: any;
-})[]>;
-/**
- * Get organization information with statistics
- */
-export declare function getOrganizationInfo(client: PcoClientState): Promise<{
-    organization: OrganizationResource;
+export declare function getOrganizationInfo(client: PcoClientState, context?: Partial<ErrorContext>): Promise<{
+    organization: OrganizationSingle;
     stats: {
         totalPeople: number;
         totalHouseholds: number;
         totalLists: number;
-        totalWorkflows: number;
     };
 }>;
 /**
- * Export all people data to a structured format
+ * Get lists with their categories
+ */
+export declare function getListsWithCategories(client: PcoClientState, context?: Partial<ErrorContext>): 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;
+    notes: {
+        [cardId: string]: any;
+    };
+}>;
+/**
+ * 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 all people data in a structured format
  */
 export declare function exportAllPeopleData(client: PcoClientState, options?: {
     includeInactive?: boolean;
     includeFieldData?: boolean;
     includeWorkflowCards?: boolean;
-    batchSize?: number;
-}): Promise<{
-    person: PersonResource;
-    emails: EmailResource[];
-    phoneNumbers: PhoneNumberResource[];
-    addresses: AddressResource[];
-    socialProfiles: SocialProfileResource[];
-    fieldData?: FieldDatumResource[];
-    workflowCards?: WorkflowCardResource[];
-}[]>;
-/**
- * Validate person data before creation/update
- */
-export declare function validatePersonData(data: any): {
-    isValid: boolean;
-    errors: string[];
-};
+    perPage?: number;
+}, context?: Partial<ErrorContext>): Promise<{
+    people: any[];
+    households: any[];
+    lists: any[];
+    organization: any;
+    exportDate: string;
+    totalCount: number;
+}>;
 /**
- * Validate email format
+ * 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>
  */
-export declare function isValidEmail(email: string): boolean;
+export declare function extractFileUrl(value: string): string;
 /**
- * Validate phone format (basic validation)
+ * Determines if a value contains a file URL
  */
-export declare function isValidPhone(phone: string): boolean;
+export declare function isFileUrl(value: string): boolean;
 /**
- * Format person name for display
+ * Gets file extension from URL
  */
-export declare function formatPersonName(person: PersonResource): string;
+export declare function getFileExtension(url: string): string;
 /**
- * Get primary contact information for a person
+ * Gets filename from URL
  */
-export declare function getPrimaryContact(person: PersonResource, relatedData: {
-    emails?: EmailResource[];
-    phoneNumbers?: PhoneNumberResource[];
-}): {
-    email?: string;
-    phone?: string;
-};
+export declare function getFilename(url: string): string;
 /**
- * Calculate age from birthdate
+ * Determines if a field value represents a file upload
  */
-export declare function calculateAge(birthdate: string): number | null;
+export declare function isFileUpload(value: string): boolean;
 /**
- * Format date for display
+ * Processes file upload value for PCO field
+ * Returns clean URL for text fields, or file data for file fields
  */
-export declare function formatDate(dateString: string, format?: 'short' | 'long' | 'iso'): string;
+export declare function processFileValue(value: string, fieldType?: 'text' | 'file'): string | {
+    url: string;
+    filename: string;
+    contentType: string;
+};