Build a member data quality desk

// Paste into the Widget group's server index.ts. No SDK or API key is needed.
const MANDATE_ID = 'YOUR_MANDATE_ID';
const ALLOW_WRITES = false; // Enable only after reviewing the Admin scope and permissions.
const TEST_CONTACT_IDS: string[] = []; // Set fixture IDs here to limit your first scan and edits.
const PAGE_SIZE = 100;
const MAX_MEMBERS = 5000;

type Address = { country: string; state?: string; zip: string; city: string; addressLine: string; details1?: string; details2?: string };
type ReviewMember = { id: string; name: string; email: string; address: Address | null; issues: string[]; revision: string };

function id(value: unknown): string {
    const text = typeof value === 'string' ? value : value && typeof value === 'object' && '$oid' in value ? String(value.$oid) : String(value);
    if (!/^[a-f0-9]{24}$/i.test(text)) throw new Error('Configure a valid mandate/contact ID.');
    return text;
}

function scope() {
    return { mandateId: id(MANDATE_ID) };
}

function project(contact: any): ReviewMember {
    if (!contact || !Array.isArray(contact.types) || !contact.types.includes('member')) throw new Error('This record is not a member.');
    if (typeof contact.communication?.email !== 'string' || !Object.prototype.hasOwnProperty.call(contact, 'address')) {
        throw new Error('Email or address fields are unavailable. Review the app field permissions.');
    }
    const email = contact.communication.email;
    const address = contact.address;
    const issues: string[] = [];
    if (!email.trim()) issues.push('email');
    if (!address || !address.addressLine?.trim() || !address.city?.trim() || !address.country?.trim()) issues.push('address');
    // Compare the displayed fields before saving. This is not a database transaction lock.
    const revision = JSON.stringify({ email, address });
    return { id: id(contact._id), name: String(contact.name || 'Unnamed member'), email, address, issues, revision };
}

export async function scanMembers() {
    const members: ReviewMember[] = [];
    const seen = new Set<string>();
    const allowed = new Set(TEST_CONTACT_IDS.map(id));
    if (allowed.size) {
        for (const contactId of allowed) {
            const contact = await api.crm.contacts.getContact({ ...scope(), contactId });
            members.push(project(contact));
        }
    } else {
        let complete = false;
        for (let offset = 0; offset <= MAX_MEMBERS; offset += PAGE_SIZE) {
            const result = await api.crm.contacts.listContacts({ ...scope(), types: ['member'], sort: { _id: 'asc' }, limit: PAGE_SIZE, offset });
            if (!Array.isArray(result.contacts) || result.contacts.length > PAGE_SIZE) throw new Error('Unexpected member-list response.');
            for (const contact of result.contacts) {
                const member = project(contact);
                if (seen.has(member.id)) throw new Error('The member list moved during scanning. Refresh before reviewing.');
                seen.add(member.id);
                members.push(member);
                if (members.length > MAX_MEMBERS) throw new Error('This example supports up to 5,000 members. Split the scan before continuing.');
            }
            if (result.contacts.length < PAGE_SIZE) { complete = true; break; }
        }
        if (!complete) throw new Error('The scan did not finish. No partial review was returned.');
    }
    return {
        scanned: members.length,
        missingEmail: members.filter(member => member.issues.includes('email')).length,
        missingAddress: members.filter(member => member.issues.includes('address')).length,
        rows: members.filter(member => member.issues.length),
        checkedAt: new Date().toISOString(),
        canWrite: ALLOW_WRITES,
        fixtureOnly: Boolean(allowed.size),
    };
}

function checkedAddress(value: unknown): Address {
    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Enter a complete postal address.');
    const input = value as Record<string, unknown>;
    const result: Record<string, string> = {};
    for (const field of ['country', 'state', 'zip', 'city', 'addressLine', 'details1', 'details2']) {
        if (typeof input[field] !== 'string') {
            if (['state', 'details1', 'details2'].includes(field) && input[field] === undefined) continue;
            throw new Error('An address field is missing.');
        }
        const text = (input[field] as string).trim();
        if (text.length > (field === 'zip' ? 10 : 45)) throw new Error('An address field is too long.');
        result[field] = text;
    }
    result.country = result.country.toUpperCase();
    if (!/^[A-Z]{2}$/.test(result.country) || !result.addressLine || !result.city) throw new Error('Enter the street, city, and two-letter country code.');
    // campai performs country-specific postal-code and state validation.
    return result as Address;
}

export async function saveCorrection(input: unknown) {
    if (!ALLOW_WRITES) throw new Error('This app is in read-only mode. Enable writes in the server source first.');
    if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Invalid correction.');
    const value = input as Record<string, unknown>;
    const contactId = id(value.id);
    if (TEST_CONTACT_IDS.length && !TEST_CONTACT_IDS.includes(contactId)) throw new Error('This member is outside the test fixture selection.');
    if (typeof value.revision !== 'string' || value.revision.length > 3000) throw new Error('Refresh the member before saving.');
    if (value.changeEmail !== true && value.changeAddress !== true) throw new Error('Select at least one correction.');

    const current = await api.crm.contacts.getContact({ ...scope(), contactId });
    const before = project(current);
    if (before.revision !== value.revision) throw new Error('This member changed after your scan. Refresh and review the current details.');

    let communication: typeof current.communication | undefined;
    let address: Address | undefined;
    if (value.changeEmail === true) {
        if (typeof value.email !== 'string' || value.email.length > 254 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.email.trim())) throw new Error('Enter a valid email address.');
        // Preserve phone numbers, mailing preferences, and unsubscribe history.
        communication = { ...current.communication, email: value.email.trim() };
    }
    if (value.changeAddress === true) address = checkedAddress(value.address);
    try {
        await api.crm.contacts.updateContact({
            ...scope(), contactId,
            ...(communication ? { communication } : {}),
            ...(address ? { address } : {}),
            dataPropagationTargets: [],
        });
    } catch {
        throw new Error('Save was not confirmed. Refresh this member and inspect the current values before trying again.');
    }
    let saved: ReviewMember;
    try { saved = project(await api.crm.contacts.getContact({ ...scope(), contactId })); }
    catch { throw new Error('The save returned, but read-back failed. Refresh before making another change.'); }
    if ((communication && saved.email !== communication.email) || (address && Object.entries(address).some(([key, value]) => saved.address?.[key as keyof Address] !== value))) {
        throw new Error('Read-back differs from your correction. Refresh and check the record in campai.');
    }
    return saved;
}