Your First API Call

const user = await getUserDetail(userId);
console.log(`${user.fullName} has ${user.participations.length} participations`);

curl https://api.vomo.org/v1/users/12345 \
  -H "Authorization: Bearer $VOMO_API_TOKEN" \
  -H "Accept: application/json"

async function getUserDetail(userId) {
  const response = await fetch(
    `https://api.vomo.org/v1/users/${userId}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.VOMO_API_TOKEN}`,
        Accept: 'application/json',
      },
    }
  );

  if (response.status === 404) {
    return null; // User doesn't exist
  }

  if (!response.ok) {
    throw new Error(`Failed to fetch user ${userId}: ${response.status}`);
  }

  const result = await response.json();
  const raw = result.data;

  // Parse into a clean, integration-friendly shape
  return {
    id: raw.id,
    firstName: raw.first_name,
    lastName: raw.last_name,
    fullName: raw.full_name,
    email: raw.email,
    phone: raw.phone ?? null,
    address: raw.address ?? null,
    birthday: raw.birthday ? new Date(raw.birthday) : null,
    gender: raw.gender ?? null,
    createdAt: new Date(raw.created_at),
    updatedAt: new Date(raw.updated_at),
    userStatus: raw.user_status,
    membershipStatus: raw.membership_status,
    membershipRole: raw.membership_role,
    participations: (raw.participations ?? []).map(parseParticipation),
    profileFieldValues: (raw.profile_field_values ?? []).map(parseProfileFieldValue),
  };
}

function parseParticipation(raw) {
  return {
    guests: raw.guests ?? 0,
    checkedInAt: raw.checked_in_at ? new Date(raw.checked_in_at) : null,
    checkedOutAt: raw.checked_out_at ? new Date(raw.checked_out_at) : null,
    signedUpAt: raw.signed_up_at ? new Date(raw.signed_up_at) : null,
    // hours: typed integer in spec but live returns fractional values
    hours: typeof raw.hours === 'string' ? parseFloat(raw.hours) : raw.hours,
    verified: raw.verified ?? false,
    role: raw.role ?? null,
    // project_id and project_date_id: typed string in spec; parse to integer for joins
    projectId: raw.project_id ? parseInt(raw.project_id, 10) : null,
    projectDateId: raw.project_date_id ? parseInt(raw.project_date_id, 10) : null,
  };
}

function parseProfileFieldValue(raw) {
  return {
    fieldId: raw.field_id,
    fieldLabel: raw.field_label,
    value: raw.value,
  };
}

async function getUserDetailRobust(userId) {
  try {
    const response = await fetch(
      `https://api.vomo.org/v1/users/${userId}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );

    switch (true) {
      case response.ok:
        return parseUser(await response.json());

      case response.status === 404:
        return null;

      case response.status === 401:
        await alertCredentialIssue(userId);
        throw new AuthError('VOMO token is invalid');

      case response.status === 403:
        throw new ForbiddenError(`No permission for user ${userId}`);

      case response.status >= 500:
        // Transient — caller should retry with backoff
        throw new TransientError(`Server error: ${response.status}`);

      default:
        throw new Error(`Unexpected status: ${response.status}`);
    }
  } catch (err) {
    if (err instanceof AuthError || err instanceof ForbiddenError) {
      throw err;
    }
    if (err.code === 'ECONNRESET' || err.code === 'ETIMEDOUT') {
      throw new TransientError(`Network error: ${err.message}`);
    }
    throw err;
  }
}

const user = await getUserDetail(12345);

const totalHours = user.participations.reduce((sum, p) => sum + (p.hours ?? 0), 0);
console.log(`${user.fullName} has volunteered ${totalHours} hours total`);

const user = await getUserDetail(12345);

const sortedParticipations = user.participations
  .filter((p) => p.checkedOutAt)
  .sort((a, b) => b.checkedOutAt - a.checkedOutAt);

const mostRecent = sortedParticipations[0];
if (mostRecent) {
  console.log(`Last volunteered: ${mostRecent.checkedOutAt.toISOString()}`);
}

function getProfileFieldValue(user, label) {
  return user.profileFieldValues.find((v) => v.fieldLabel === label)?.value ?? null;
}

const tshirtSize = getProfileFieldValue(user, 'T-shirt size');
const dietaryRestrictions = getProfileFieldValue(user, 'Dietary restrictions');

async function upsertUser(userData) {
  const response = await fetch('https://api.vomo.org/v1/users', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({
      first_name: userData.firstName,
      last_name: userData.lastName,
      email: userData.email,
      phone: userData.phone,
      birthday: userData.birthday,
      gender: userData.gender,
      role: userData.role,
      // Note: snake_case property names in the request body
    }),
  });

  // 200 = updated existing user; 201 = created new user
  if (!response.ok) throw new Error(`Upsert failed: ${response.status}`);

  return parseUser(await response.json());
}