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

package/dist/helpers.js

@@ -1,359 +1,399 @@
 "use strict";
-/**
- * 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.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCompletePersonProfile = getCompletePersonProfile;
+exports.buildQueryParams = buildQueryParams;
+exports.calculateAge = calculateAge;
+exports.isValidEmail = isValidEmail;
+exports.isValidPhone = isValidPhone;
+exports.formatPersonName = formatPersonName;
+exports.formatDate = formatDate;
+exports.validatePersonData = validatePersonData;
+exports.getPrimaryContact = getPrimaryContact;
 exports.createPersonWithContact = createPersonWithContact;
 exports.searchPeople = searchPeople;
 exports.getPeopleByHousehold = getPeopleByHousehold;
+exports.getCompletePersonProfile = getCompletePersonProfile;
+exports.getOrganizationInfo = getOrganizationInfo;
+exports.getListsWithCategories = getListsWithCategories;
 exports.getPersonWorkflowCardsWithNotes = getPersonWorkflowCardsWithNotes;
 exports.createWorkflowCardWithNote = createWorkflowCardWithNote;
-exports.getListsWithCategories = getListsWithCategories;
-exports.getOrganizationInfo = getOrganizationInfo;
 exports.exportAllPeopleData = exportAllPeopleData;
-exports.validatePersonData = validatePersonData;
-exports.isValidEmail = isValidEmail;
-exports.isValidPhone = isValidPhone;
-exports.formatPersonName = formatPersonName;
-exports.getPrimaryContact = getPrimaryContact;
-exports.calculateAge = calculateAge;
-exports.formatDate = formatDate;
+exports.extractFileUrl = extractFileUrl;
+exports.isFileUrl = isFileUrl;
+exports.getFileExtension = getFileExtension;
+exports.getFilename = getFilename;
+exports.isFileUpload = isFileUpload;
+exports.processFileValue = processFileValue;
 const people_1 = require("./people");
-// ===== Person Management Helpers =====
 /**
- * Get a complete person profile with all related data
+ * Transform complex params object into flat query params for API calls
  */
-async function getCompletePersonProfile(client, personId) {
-    const [personResponse, emailsResponse, phoneNumbersResponse, addressesResponse, socialProfilesResponse, fieldDataResponse, workflowCardsResponse, notesResponse,] = await Promise.all([
-        (0, people_1.getPerson)(client, personId),
-        (0, people_1.getPersonEmails)(client, personId),
-        (0, people_1.getPersonPhoneNumbers)(client, personId),
-        (0, people_1.getPersonAddresses)(client, personId),
-        (0, people_1.getPersonSocialProfiles)(client, personId),
-        (0, people_1.getPersonFieldData)(client, personId),
-        (0, people_1.getWorkflowCards)(client, personId),
-        (0, people_1.getNotes)(client, { where: { person_id: personId } }),
-    ]);
-    if (!personResponse.data) {
-        throw new Error(`Person with ID ${personId} not found`);
+function buildQueryParams(params) {
+    const queryParams = {};
+    if (params?.where) {
+        Object.entries(params.where).forEach(([key, value]) => {
+            queryParams[`where[${key}]`] = value;
+        });
     }
-    return {
-        addresses: addressesResponse.data,
-        emails: emailsResponse.data,
-        fieldData: fieldDataResponse.data,
-        notes: notesResponse.data,
-        person: personResponse.data,
-        phoneNumbers: phoneNumbersResponse.data,
-        socialProfiles: socialProfilesResponse.data,
-        workflowCards: workflowCardsResponse.data,
-    };
+    if (params?.include) {
+        queryParams.include = params.include.join(',');
+    }
+    if (params?.per_page) {
+        queryParams.per_page = params.per_page;
+    }
+    if (params?.page) {
+        queryParams.page = params.page;
+    }
+    if (params?.filter) {
+        queryParams.filter = params.filter;
+    }
+    return queryParams;
 }
 /**
- * Create a person with initial contact information
+ * Calculate age from birthdate string
  */
-async function createPersonWithContact(client, personData) {
-    // Create the person first
-    const personResponse = await (0, people_1.createPerson)(client, {
-        first_name: personData.first_name,
-        last_name: personData.last_name,
-    });
-    if (!personResponse.data) {
-        throw new Error('Failed to create person');
+function calculateAge(birthdate) {
+    const birth = new Date(birthdate);
+    const today = new Date();
+    let age = today.getFullYear() - birth.getFullYear();
+    const monthDiff = today.getMonth() - birth.getMonth();
+    if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birth.getDate())) {
+        age--;
     }
-    const personId = personResponse.data.id;
-    const results = { person: personResponse.data };
-    // Add email if provided
-    if (personData.email) {
-        const emailResponse = await (0, people_1.createPersonEmail)(client, personId, {
-            address: personData.email,
-            location: 'Home',
-            primary: true,
-        });
-        results.email = emailResponse.data;
+    return age;
+}
+/**
+ * Validate email format
+ */
+function isValidEmail(email) {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+}
+/**
+ * Validate phone number format (basic validation)
+ */
+function isValidPhone(phone) {
+    const phoneRegex = /^[\+]?[1-9][\d]{6,14}$/;
+    return phoneRegex.test(phone.replace(/[\s\-\(\)]/g, ''));
+}
+/**
+ * Format person name from attributes
+ */
+function formatPersonName(person) {
+    const firstName = person.nickname || person.first_name || '';
+    const lastName = person.last_name || '';
+    if (firstName && lastName) {
+        return `${firstName} ${lastName}`;
     }
-    // Add phone if provided
-    if (personData.phone) {
-        const phoneResponse = await (0, people_1.createPersonPhoneNumber)(client, personId, {
-            location: 'Mobile',
-            number: personData.phone,
-            primary: true,
-        });
-        results.phone = phoneResponse.data;
+    else if (firstName) {
+        return firstName;
     }
-    // Add address if provided
-    if (personData.address) {
-        const addressResponse = await (0, people_1.createPersonAddress)(client, personId, {
-            ...personData.address,
-            location: 'Home',
-            primary: true,
-        });
-        results.address = addressResponse.data;
+    else if (lastName) {
+        return lastName;
     }
-    return results;
+    return 'Unknown';
 }
 /**
- * Search for people by multiple criteria
+ * Format date string in various formats
  */
-async function searchPeople(client, criteria) {
-    const whereConditions = {};
-    if (criteria.name) {
-        whereConditions.name = criteria.name;
+function formatDate(dateString, format = 'short') {
+    const date = new Date(dateString);
+    if (isNaN(date.getTime())) {
+        return 'Invalid Date';
     }
-    if (criteria.email) {
-        whereConditions.email = criteria.email;
+    switch (format) {
+        case 'short':
+            return date.toLocaleDateString();
+        case 'long':
+            return date.toLocaleDateString('en-US', {
+                year: 'numeric',
+                month: 'long',
+                day: 'numeric'
+            });
+        case 'iso':
+            return date.toISOString().split('T')[0];
+        default:
+            return date.toLocaleDateString();
     }
-    if (criteria.phone) {
-        whereConditions.phone = criteria.phone;
+}
+/**
+ * Validate person data
+ */
+function validatePersonData(data) {
+    const errors = [];
+    if (data.email && typeof data.email === 'string' && !isValidEmail(data.email)) {
+        errors.push('Invalid email format');
     }
-    if (criteria.status) {
-        whereConditions.status = criteria.status;
+    if (data.phone && typeof data.phone === 'string' && !isValidPhone(data.phone)) {
+        errors.push('Invalid phone format');
     }
-    if (criteria.household) {
-        whereConditions.household = criteria.household;
+    if (data.birthdate) {
+        const birthDate = new Date(data.birthdate);
+        if (isNaN(birthDate.getTime())) {
+            errors.push('Invalid birthdate format');
+        }
     }
-    const response = await (0, people_1.getPeople)(client, {
-        include: ['emails', 'phone_numbers', 'household'],
-        where: whereConditions,
-    });
-    return response.data;
+    return {
+        isValid: errors.length === 0,
+        errors
+    };
 }
 /**
- * Get people by household
+ * Get primary contact information for a person
  */
-async function getPeopleByHousehold(client, householdId) {
-    const response = await (0, people_1.getPeople)(client, {
-        include: ['emails', 'phone_numbers', 'addresses'],
-        where: { household_id: householdId },
-    });
-    return response.data;
+async function getPrimaryContact(client, personId, context) {
+    const [emails, phones, addresses] = await Promise.all([
+        (0, people_1.getPersonEmails)(client, personId, context),
+        (0, people_1.getPersonPhoneNumbers)(client, personId, context),
+        (0, people_1.getPersonAddresses)(client, personId, context)
+    ]);
+    const primaryEmail = emails.data.find((e) => e.attributes.primary);
+    const primaryPhone = phones.data.find((p) => p.attributes.primary);
+    const primaryAddress = addresses.data.find((a) => a.attributes.primary);
+    return {
+        email: primaryEmail?.attributes?.address || emails.data[0]?.attributes?.address,
+        phone: primaryPhone?.attributes?.number || phones.data[0]?.attributes?.number,
+        address: (primaryAddress?.attributes?.street || addresses.data[0]?.attributes?.street)
+    };
 }
-// ===== Workflow Management Helpers =====
 /**
- * Get all workflow cards for a person with their notes
+ * Create a person with contact information
  */
-async function getPersonWorkflowCardsWithNotes(client, personId) {
-    const workflowCardsResponse = await (0, people_1.getWorkflowCards)(client, personId);
-    const cardsWithNotes = await Promise.all(workflowCardsResponse.data.map(async (card) => {
-        const notesResponse = await (0, people_1.getWorkflowCardNotes)(client, personId, card.id);
-        return {
-            ...card,
-            notes: notesResponse.data,
-        };
-    }));
-    return cardsWithNotes;
+async function createPersonWithContact(client, personData, contactData, context) {
+    const person = await (0, people_1.createPerson)(client, personData, context);
+    const results = { person };
+    if (contactData?.email) {
+        results.email = await (0, people_1.createPersonEmail)(client, person.data.id, contactData.email, context);
+    }
+    if (contactData?.phone) {
+        results.phone = await (0, people_1.createPersonPhoneNumber)(client, person.data.id, contactData.phone, context);
+    }
+    if (contactData?.address) {
+        results.address = await (0, people_1.createPersonAddress)(client, person.data.id, contactData.address, context);
+    }
+    return results;
 }
 /**
- * Create a workflow card with an initial note
+ * Search people by multiple criteria
  */
-async function createWorkflowCardWithNote(client, personId, workflowId, cardData) {
-    const cardResponse = await (0, people_1.createWorkflowCard)(client, workflowId, personId);
-    if (!cardResponse.data) {
-        throw new Error('Failed to create workflow card');
+async function searchPeople(client, criteria, context) {
+    const where = {};
+    if (criteria.status) {
+        where.status = criteria.status;
+    }
+    if (criteria.name) {
+        where.name = criteria.name;
     }
-    const results = { card: cardResponse.data };
-    if (cardData.initialNote) {
-        const noteResponse = await (0, people_1.createWorkflowCardNote)(client, personId, cardResponse.data.id, { note: cardData.initialNote });
-        results.note = noteResponse.data;
+    if (criteria.email) {
+        where.email = criteria.email;
     }
-    return results;
+    return (0, people_1.getPeople)(client, {
+        where,
+        per_page: criteria.per_page || 25
+    }, context);
 }
-// ===== List Management Helpers =====
 /**
- * Get all lists with their categories
+ * Get people by household
  */
-async function getListsWithCategories(client) {
-    const [listsResponse, categoriesResponse] = await Promise.all([
-        (0, people_1.getLists)(client, { include: ['category'] }),
-        (0, people_1.getLists)(client), // This should be getListCategories when available
+async function getPeopleByHousehold(client, householdId, context) {
+    return (0, people_1.getPeople)(client, {
+        where: { household_id: householdId },
+        include: ['household']
+    }, context);
+}
+/**
+ * Get complete person profile with all related data
+ */
+async function getCompletePersonProfile(client, personId, context) {
+    const [person, emails, phones, addresses, fieldData, workflowCards] = await Promise.all([
+        (0, people_1.getPerson)(client, personId, ['household'], context),
+        (0, people_1.getPersonEmails)(client, personId, context),
+        (0, people_1.getPersonPhoneNumbers)(client, personId, context),
+        (0, people_1.getPersonAddresses)(client, personId, context),
+        (0, people_1.getPersonFieldData)(client, personId, context),
+        (0, people_1.getWorkflowCards)(client, personId, context)
     ]);
-    // For now, return lists with basic category info
-    return listsResponse.data.map(list => ({
-        ...list,
-        category: list.relationships?.category?.data,
-    }));
+    return {
+        person,
+        emails,
+        phones,
+        addresses,
+        fieldData,
+        workflowCards
+    };
 }
-// ===== Organization Helpers =====
 /**
- * Get organization information with statistics
+ * Get organization info with statistics
  */
-async function getOrganizationInfo(client) {
-    const [organizationResponse, peopleResponse, householdsResponse, listsResponse, workflowsResponse,] = await Promise.all([
-        (0, people_1.getOrganization)(client),
-        (0, people_1.getPeople)(client, { per_page: 1 }),
-        (0, people_1.getHouseholds)(client, { per_page: 1 }),
-        (0, people_1.getLists)(client, { per_page: 1 }),
-        (0, people_1.getWorkflows)(client, { per_page: 1 }),
+async function getOrganizationInfo(client, context) {
+    const [organization, people, households, lists] = await Promise.all([
+        (0, people_1.getOrganization)(client, undefined, context),
+        (0, people_1.getPeople)(client, { per_page: 1 }, context),
+        (0, people_1.getHouseholds)(client, { per_page: 1 }, context),
+        (0, people_1.getLists)(client, { per_page: 1 }, context)
     ]);
-    if (!organizationResponse.data) {
-        throw new Error('Failed to get organization data');
-    }
     return {
-        organization: organizationResponse.data,
+        organization,
         stats: {
-            totalHouseholds: Number(householdsResponse.meta?.total_count) || 0,
-            totalLists: Number(listsResponse.meta?.total_count) || 0,
-            totalPeople: Number(peopleResponse.meta?.total_count) || 0,
-            totalWorkflows: Number(workflowsResponse.meta?.total_count) || 0,
-        },
+            totalPeople: Number(people.meta?.total_count) || 0,
+            totalHouseholds: Number(households.meta?.total_count) || 0,
+            totalLists: Number(lists.meta?.total_count) || 0
+        }
     };
 }
-// ===== Data Export Helpers =====
 /**
- * Export all people data to a structured format
+ * Get lists with their categories
+ */
+async function getListsWithCategories(client, context) {
+    const [lists, categories] = await Promise.all([
+        (0, people_1.getLists)(client, { include: ['list_category'] }, context),
+        (0, people_1.getListCategories)(client, undefined, context)
+    ]);
+    return { lists, categories };
+}
+/**
+ * Get workflow cards with notes for a person
  */
-async function exportAllPeopleData(client, options = {}) {
-    const { batchSize = 50, includeFieldData = false, includeInactive = false, includeWorkflowCards = false, } = options;
-    const whereConditions = {};
+async function getPersonWorkflowCardsWithNotes(client, personId, context) {
+    const workflowCards = await (0, people_1.getWorkflowCards)(client, personId, context);
+    const notes = {};
+    for (const card of workflowCards.data) {
+        try {
+            notes[card.id] = await (0, people_1.getWorkflowCardNotes)(client, personId, card.id, context);
+        }
+        catch (error) {
+            notes[card.id] = { data: [], meta: { total_count: 0 } };
+        }
+    }
+    return { workflowCards, notes };
+}
+/**
+ * Create a workflow card with a note
+ */
+async function createWorkflowCardWithNote(client, workflowId, personId, noteData, context) {
+    const workflowCard = await (0, people_1.createWorkflowCard)(client, workflowId, personId, context);
+    const note = await (0, people_1.createWorkflowCardNote)(client, personId, workflowCard.data.id, noteData, context);
+    return { workflowCard, note };
+}
+/**
+ * Export all people data in a structured format
+ */
+async function exportAllPeopleData(client, options = {}, context) {
+    const { includeInactive = false, includeFieldData = false, includeWorkflowCards = false, perPage = 100 } = options;
+    const where = {};
     if (!includeInactive) {
-        whereConditions.status = 'active';
+        where.status = 'active';
     }
-    const includeArray = [
-        'emails',
-        'phone_numbers',
-        'addresses',
-        'social_profiles',
-    ];
+    const include = ['household'];
     if (includeFieldData) {
-        includeArray.push('field_data');
+        include.push('field_data');
     }
     if (includeWorkflowCards) {
-        includeArray.push('workflow_cards');
-    }
-    let allPeople = [];
-    let page = 1;
-    let hasMore = true;
-    while (hasMore) {
-        const response = await (0, people_1.getPeople)(client, {
-            include: includeArray,
-            page,
-            per_page: batchSize,
-            where: whereConditions,
-        });
-        allPeople = allPeople.concat(response.data);
-        hasMore = response.links?.next ? true : false;
-        page++;
+        include.push('workflow_cards');
     }
-    return allPeople.map(person => ({
-        addresses: person.relationships?.addresses?.data || [],
-        emails: person.relationships?.emails?.data || [],
-        person,
-        phoneNumbers: person.relationships?.phone_numbers?.data || [],
-        socialProfiles: person.relationships?.social_profiles?.data || [],
-        ...(includeFieldData && {
-            fieldData: person.relationships?.field_data?.data || [],
-        }),
-        ...(includeWorkflowCards && {
-            workflowCards: person.relationships?.workflow_cards?.data || [],
-        }),
-    }));
+    const [people, households, lists, organization] = await Promise.all([
+        (0, people_1.getPeople)(client, { where, include, per_page: perPage }, context),
+        (0, people_1.getHouseholds)(client, { per_page: perPage }, context),
+        (0, people_1.getLists)(client, { per_page: perPage }, context),
+        (0, people_1.getOrganization)(client, undefined, context)
+    ]);
+    return {
+        people: people.data,
+        households: households.data,
+        lists: lists.data,
+        organization: organization.data,
+        exportDate: new Date().toISOString(),
+        totalCount: Number(people.meta?.total_count) || 0
+    };
 }
-// ===== Validation Helpers =====
+// ===== File Handling Utilities =====
 /**
- * Validate person data before creation/update
+ * 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>
  */
-function validatePersonData(data) {
-    const errors = [];
-    if (!data.first_name && !data.last_name) {
-        errors.push('Either first_name or last_name is required');
+function extractFileUrl(value) {
+    // If it's already a clean URL, return it
+    if (value.startsWith('http') && !value.includes('<')) {
+        return value;
     }
-    if (data.email && !isValidEmail(data.email)) {
-        errors.push('Invalid email format');
+    // Extract URL from HTML anchor tag
+    const hrefMatch = /href=["']([^"']+)["']/.exec(value);
+    if (hrefMatch) {
+        return hrefMatch[1];
     }
-    if (data.phone && !isValidPhone(data.phone)) {
-        errors.push('Invalid phone format');
+    // Extract URL from text content (fallback)
+    const urlMatch = /(https?:\/\/[^\s<>"']+)/.exec(value);
+    if (urlMatch) {
+        return urlMatch[1];
     }
-    return {
-        errors,
-        isValid: errors.length === 0,
-    };
+    // If no URL found, return original value
+    return value;
 }
 /**
- * Validate email format
+ * Determines if a value contains a file URL
  */
-function isValidEmail(email) {
-    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-    return emailRegex.test(email);
+function isFileUrl(value) {
+    const cleanUrl = extractFileUrl(value);
+    return (cleanUrl.includes('s3.') ||
+        cleanUrl.includes('amazonaws.com') ||
+        cleanUrl.includes('onark.s3.'));
 }
 /**
- * Validate phone format (basic validation)
+ * Gets file extension from URL
  */
-function isValidPhone(phone) {
-    const phoneRegex = /^[\+]?[1-9][\d]{0,15}$/;
-    return phoneRegex.test(phone.replace(/[\s\-\(\)]/g, ''));
+function getFileExtension(url) {
+    const cleanUrl = extractFileUrl(url);
+    const match = /\.([a-zA-Z0-9]+)(?:[?#]|$)/.exec(cleanUrl);
+    return match ? match[1].toLowerCase() : '';
 }
-// ===== Utility Helpers =====
 /**
- * Format person name for display
+ * Gets filename from URL
  */
-function formatPersonName(person) {
-    const attrs = person.attributes;
-    if (attrs?.first_name && attrs?.last_name) {
-        return `${attrs.first_name} ${attrs.last_name}`;
-    }
-    if (attrs?.first_name) {
-        return attrs.first_name;
-    }
-    if (attrs?.last_name) {
-        return attrs.last_name;
-    }
-    if (attrs?.name) {
-        return attrs.name;
-    }
-    return 'Unknown';
+function getFilename(url) {
+    const cleanUrl = extractFileUrl(url);
+    const urlParts = cleanUrl.split('/');
+    return urlParts[urlParts.length - 1] || 'file';
 }
 /**
- * Get primary contact information for a person
+ * Determines if a field value represents a file upload
  */
-function getPrimaryContact(person, relatedData) {
-    const primaryEmail = relatedData.emails?.find(email => email.attributes?.primary);
-    const primaryPhone = relatedData.phoneNumbers?.find(phone => phone.attributes?.primary);
-    return {
-        email: primaryEmail?.attributes?.address,
-        phone: primaryPhone?.attributes?.number,
-    };
+function isFileUpload(value) {
+    return isFileUrl(value) || value.includes('<a href=');
 }
 /**
- * Calculate age from birthdate
+ * Gets MIME type from file extension
  */
-function calculateAge(birthdate) {
-    if (!birthdate)
-        return null;
-    const birth = new Date(birthdate);
-    const today = new Date();
-    if (isNaN(birth.getTime()))
-        return null;
-    let age = today.getFullYear() - birth.getFullYear();
-    const monthDiff = today.getMonth() - birth.getMonth();
-    if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birth.getDate())) {
-        age--;
-    }
-    return age;
+function getMimeType(extension) {
+    const mimeTypes = {
+        csv: 'text/csv',
+        doc: 'application/msword',
+        docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        gif: 'image/gif',
+        jpeg: 'image/jpeg',
+        jpg: 'image/jpeg',
+        pdf: 'application/pdf',
+        png: 'image/png',
+        txt: 'text/plain',
+        xls: 'application/vnd.ms-excel',
+        xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    };
+    return mimeTypes[extension] || 'application/octet-stream';
 }
 /**
- * Format date for display
+ * Processes file upload value for PCO field
+ * Returns clean URL for text fields, or file data for file fields
  */
-function formatDate(dateString, format = 'short') {
-    if (!dateString)
-        return '';
-    const date = new Date(dateString);
-    if (isNaN(date.getTime()))
-        return dateString;
-    switch (format) {
-        case 'short':
-            return date.toLocaleDateString();
-        case 'long':
-            return date.toLocaleDateString('en-US', {
-                day: 'numeric',
-                month: 'long',
-                year: 'numeric',
-            });
-        case 'iso':
-            return date.toISOString();
-        default:
-            return dateString;
+function processFileValue(value, fieldType = 'text') {
+    const cleanUrl = extractFileUrl(value);
+    if (fieldType === 'text') {
+        return cleanUrl;
     }
+    // For file fields, return metadata object
+    const extension = getFileExtension(cleanUrl);
+    const filename = getFilename(cleanUrl);
+    const contentType = getMimeType(extension);
+    return {
+        contentType,
+        filename,
+        url: cleanUrl,
+    };
 }