Build a membership dashboard for your board

// Hosted Widget server. Read-only member reporting for one fixed mandate.
const MANDATE_ID = 'YOUR_MANDATE_ID';
const TEST_CONTACT_IDS: string[] = []; // Optional synthetic fixture IDs for the first test.
const PAGE_SIZE = 100;
const MAX_MEMBERS = 5000;
type Dates = { entry: string | null; exit: string | null };

function id(value: unknown) {
    const result =
        typeof value === 'string'
            ? value
            : value && typeof value === 'object' && '$oid' in value
              ? String(value.$oid)
              : String(value);
    if (!/^[a-f0-9]{24}$/i.test(result)) throw new Error('Configure valid full mandate and contact IDs.');
    return result;
}
function day(value: unknown, label: string) {
    if (
        typeof value !== 'string' ||
        !/^\d{4}-\d{2}-\d{2}$/.test(value) ||
        !Number.isFinite(Date.parse(`${value}T00:00:00Z`)) ||
        new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) !== value
    )
        throw new Error(`${label} must be a real YYYY-MM-DD date.`);
    return value;
}
function storedDay(value: unknown): string | null {
    if (value === null) return null;
    const iso = value instanceof Date ? value.toISOString() : value;
    if (typeof iso !== 'string' || !/^\d{4}-\d{2}-\d{2}T00:00:00\.000Z$/.test(iso))
        throw new Error('Unexpected membership date representation. No partial report was returned.');
    return day(iso.slice(0, 10), 'Membership date');
}
function project(contact: any) {
    if (!contact || !Array.isArray(contact.types) || !contact.types.includes('member'))
        throw new Error('A returned record is not a member.');
    if (
        !contact.member ||
        !Object.prototype.hasOwnProperty.call(contact.member, 'entryAt') ||
        !Object.prototype.hasOwnProperty.call(contact.member, 'exitAt')
    )
        throw new Error('Membership date fields are unavailable. Review the app field permissions.');
    return {
        id: id(contact._id),
        entry: storedDay(contact.member.entryAt),
        exit: storedDay(contact.member.exitAt),
    };
}
export async function buildReport(input: unknown) {
    if (!input || typeof input !== 'object') throw new Error('Choose a report date.');
    const asOf = day((input as Record<string, unknown>).asOf, 'Report date');
    const year = Number(asOf.slice(0, 4));
    if (year < 1900 || year > 2100) throw new Error('Choose a report year from 1900 to 2100.');
    const mandateId = id(MANDATE_ID);
    const fixtureIds = [...new Set(TEST_CONTACT_IDS.map(id))];
    if (fixtureIds.length > 1000) throw new Error('Use at most 1,000 test contact IDs.');
    const members: Dates[] = [];
    const seen = new Set<string>();
    const add = (contact: any) => {
        const row = project(contact);
        if (fixtureIds.length && !fixtureIds.includes(row.id))
            throw new Error('A returned member is outside the test selection. No report was returned.');
        if (seen.has(row.id)) throw new Error('The member list moved during scanning. Run a fresh report.');
        seen.add(row.id);
        members.push({ entry: row.entry, exit: row.exit });
        if (members.length > MAX_MEMBERS)
            throw new Error(
                'This example supports up to 5,000 member records. Split the report before continuing.',
            );
    };
    let complete = false;
    for (let offset = 0; offset <= MAX_MEMBERS; offset += PAGE_SIZE) {
        const page = await api.crm.contacts.listContacts({
            mandateId,
            types: ['member'],
            sort: { _id: 'asc' },
            limit: PAGE_SIZE,
            offset,
            ...(fixtureIds.length ? { selection: { ids: fixtureIds } } : {}),
        });
        if (!Array.isArray(page.contacts) || page.contacts.length > PAGE_SIZE)
            throw new Error('Unexpected member-list response.');
        for (const contact of page.contacts) add(contact);
        if (page.contacts.length < PAGE_SIZE) {
            complete = true;
            break;
        }
    }
    if (!complete) throw new Error('The report did not finish. No partial totals were returned.');
    if (fixtureIds.length && seen.size !== fixtureIds.length)
        throw new Error('Some test contacts were not returned. Check the IDs, mandate, and member type.');
    // A null entry date cannot establish membership on the chosen day.
    const unknownStart = members.filter((member) => member.entry === null).length;
    const inconsistent = members.filter(
        (member) => member.entry && member.exit && member.exit < member.entry,
    ).length;
    const usable = members.filter(
        (member): member is { entry: string; exit: string | null } =>
            member.entry !== null && (member.exit === null || member.exit >= member.entry),
    );
    // The exit day is included. The member is outside the interval the following day.
    const active = usable.filter(
        (member) => member.entry <= asOf && (member.exit === null || member.exit >= asOf),
    ).length;
    const futureStarts = usable.filter((member) => member.entry > asOf).length;
    const ended = usable.filter((member) => member.exit !== null && member.exit < asOf).length;
    const yearStart = `${year}-01-01`;
    const months = Array.from({ length: Number(asOf.slice(5, 7)) }, (_, index) => {
        const prefix = `${year}-${String(index + 1).padStart(2, '0')}`;
        return {
            month: prefix,
            joined: usable.filter((member) => member.entry.startsWith(prefix) && member.entry <= asOf).length,
            exits: usable.filter((member) => member.exit?.startsWith(prefix) && member.exit <= asOf).length,
        };
    });
    // Return aggregates only. Names, IDs and contact details never reach the widget.
    return {
        asOf,
        year,
        scanned: members.length,
        active,
        ended,
        futureStarts,
        unknownStart,
        inconsistent,
        joinedThisYear: usable.filter((member) => member.entry >= yearStart && member.entry <= asOf).length,
        exitsThisYear: usable.filter(
            (member) => member.exit !== null && member.exit >= yearStart && member.exit <= asOf,
        ).length,
        months,
        checkedAt: new Date().toISOString(),
        fixtureOnly: TEST_CONTACT_IDS.length > 0,
    };
}