init: port to typescript and bun

engage-api/get-activity.ts

@@ -0,0 +1,346 @@
+// ./engage-api/get-activity.ts
+import axios from 'axios';
+import { readFile, writeFile, unlink } from 'fs/promises';
+import { resolve } from 'path';
+import { logger } from '../utils/logger';
+
+// Define interfaces for our data structures
+interface ActivityResponse {
+  d: string;
+  isError?: boolean;
+  [key: string]: any;
+}
+
+// --- Custom Error for Authentication ---
+class AuthenticationError extends Error {
+  status: number;
+  
+  constructor(message: string = "Authentication failed, cookie may be invalid.", status?: number) {
+    super(message);
+    this.name = "AuthenticationError";
+    this.status = status || 0;
+  }
+}
+
+// In Bun, we can use import.meta.dir instead of the Node.js __dirname approach
+const COOKIE_FILE_PATH = resolve(import.meta.dir, 'nkcs-engage.cookie.txt');
+let _inMemoryCookie: string | null = null;
+
+// --- Cookie Cache Helper Functions ---
+async function loadCachedCookie(): Promise<string | null> {
+  if (_inMemoryCookie) {
+    logger.debug("Using in-memory cached cookie.");
+    return _inMemoryCookie;
+  }
+  try {
+    const cookieFromFile = await readFile(COOKIE_FILE_PATH, 'utf8');
+    if (cookieFromFile) {
+      _inMemoryCookie = cookieFromFile;
+      logger.debug("Loaded cookie from file cache.");
+      return _inMemoryCookie;
+    }
+  } catch (err: any) {
+    if (err.code === 'ENOENT') {
+      logger.debug("Cookie cache file not found. No cached cookie loaded.");
+    } else {
+      logger.warn("Error loading cookie from file:", err.message);
+    }
+  }
+  return null;
+}
+
+async function saveCookieToCache(cookieString: string): Promise<void> {
+  if (!cookieString) {
+    logger.warn("Attempted to save an empty or null cookie. Aborting save.");
+    return;
+  }
+  _inMemoryCookie = cookieString;
+  try {
+    await writeFile(COOKIE_FILE_PATH, cookieString, 'utf8');
+    logger.debug("Cookie saved to file cache.");
+  } catch (err: any) {
+    logger.error("Error saving cookie to file:", err.message);
+  }
+}
+
+async function clearCookieCache(): Promise<void> {
+  _inMemoryCookie = null;
+  try {
+    await unlink(COOKIE_FILE_PATH);
+    logger.debug("Cookie cache file deleted.");
+  } catch (err: any) {
+    if (err.code !== 'ENOENT') {
+      logger.error("Error deleting cookie file:", err.message);
+    } else {
+      logger.debug("Cookie cache file did not exist, no need to delete.");
+    }
+  }
+}
+
+async function testCookieValidity(cookieString: string): Promise<boolean> {
+  if (!cookieString) return false;
+  logger.debug("Testing cookie validity...");
+  
+  const MAX_RETRIES = 3;
+  let attempt = 0;
+  
+  while (attempt < MAX_RETRIES) {
+    try {
+      attempt++;
+      const url = 'https://engage.nkcswx.cn/Services/ActivitiesService.asmx/GetActivityDetails';
+      const headers = {
+        'Content-Type': 'application/json; charset=UTF-8',
+        'Cookie': cookieString,
+        'User-Agent': 'Mozilla/5.0 (Bun DSAS-CCA get-activity Module)',
+      };
+      const payload = { "activityID": "3350" };
+      
+      logger.debug(`Attempt ${attempt}/${MAX_RETRIES}`);
+      await axios.post(url, payload, { headers, timeout: 20000 });
+      
+      logger.debug("Cookie test successful (API responded 2xx). Cookie is valid.");
+      return true;
+    } catch (error: any) {
+      logger.warn(`Cookie validity test failed (attempt ${attempt}/${MAX_RETRIES}).`);
+      if (error.response) {
+        logger.warn(`Cookie test API response status: ${error.response.status}.`);
+      } else {
+        logger.warn(`Network/other error: ${error.message}`);
+      }
+      
+      if (attempt >= MAX_RETRIES) {
+        logger.warn("Max retries reached. Cookie is likely invalid or expired.");
+        return false;
+      }
+    }
+  }
+  return false;
+}
+
+// --- Core API Interaction Functions ---
+async function getSessionId(): Promise<string | null> {
+  const url = 'https://engage.nkcswx.cn/Login.aspx';
+  try {
+    const response = await axios.get(url, {
+      headers: { 'User-Agent': 'Mozilla/5.0 (Bun DSAS-CCA get-activity Module)' }
+    });
+    const setCookieHeader = response.headers['set-cookie'];
+    if (setCookieHeader && setCookieHeader.length > 0) {
+      const sessionIdCookie = setCookieHeader.find(cookie => cookie.trim().startsWith('ASP.NET_SessionId='));
+      if (sessionIdCookie) {
+        logger.debug('ASP.NET_SessionId created');
+        return sessionIdCookie.split(';')[0] || null; // Ensure a fallback to `null` if splitting fails
+      }
+      return null; // Explicitly return `null` if no cookie is found
+    }
+    logger.error("No ASP.NET_SessionId cookie found in Set-Cookie header.");
+    return null;
+  } catch (error: any) {
+    logger.error(`Error in getSessionId: ${error.response ? `${error.response.status} - ${error.response.statusText}` : error.message}`);
+    throw error;
+  }
+}
+
+async function getMSAUTH(sessionId: string, userName: string, userPwd: string, templateFilePath: string): Promise<string | null> {
+  const url = 'https://engage.nkcswx.cn/Login.aspx';
+  try {
+    let templateData = await readFile(templateFilePath, 'utf8');
+    const postData = templateData
+      .replace('{{USERNAME}}', userName)
+      .replace('{{PASSWORD}}', userPwd);
+    const headers = {
+      'Content-Type': 'application/x-www-form-urlencoded', 
+      'Cookie': sessionId,
+      'User-Agent': 'Mozilla/5.0 (Bun DSAS-CCA get-activity Module)',
+      'Referer': 'https://engage.nkcswx.cn/Login.aspx'
+    };
+    logger.debug('Getting .ASPXFORMSAUTH');
+    const response = await axios.post(url, postData, {
+      headers, 
+      maxRedirects: 0,
+      validateStatus: (status) => status >= 200 && status < 400
+    });
+    const setCookieHeader = response.headers['set-cookie'];
+    let formsAuthCookieValue = null;
+    if (setCookieHeader && setCookieHeader.length > 0) {
+      const aspxAuthCookies = setCookieHeader.filter(cookie => cookie.trim().startsWith('.ASPXFORMSAUTH='));
+      if (aspxAuthCookies.length > 0) {
+        for (let i = aspxAuthCookies.length - 1; i >= 0; i--) {
+          const cookieCandidateParts = aspxAuthCookies[i].split(';');
+          if (cookieCandidateParts.length > 0 && cookieCandidateParts[0] !== undefined) {  // Explicit check
+            const firstPart = cookieCandidateParts[0].trim();
+            if (firstPart.length > '.ASPXFORMSAUTH='.length && firstPart.substring('.ASPXFORMSAUTH='.length).length > 0) {
+              formsAuthCookieValue = firstPart; 
+              break;
+            }
+          }
+        }
+      }
+    }
+    if (formsAuthCookieValue) {
+      logger.debug('.ASPXFORMSAUTH cookie obtained.');
+      return formsAuthCookieValue;
+    } else {
+      logger.error("No valid .ASPXFORMSAUTH cookie found. Headers:", setCookieHeader || "none");
+      return null;
+    }
+  } catch (error: any) {
+    if (error.code === 'ENOENT') logger.error(`Error: Template file '${templateFilePath}' not found.`);
+    else logger.error(`Error in getMSAUTH: ${error.message}`);
+    throw error;
+  }
+}
+
+async function getCompleteCookies(userName: string, userPwd: string, templateFilePath: string): Promise<string> {
+  logger.debug('Attempting to get complete cookie string (login process).');
+  const sessionId = await getSessionId();
+  if (!sessionId) throw new Error("Login failed: Could not obtain ASP.NET_SessionId.");
+  
+  const msAuth = await getMSAUTH(sessionId, userName, userPwd, templateFilePath);
+  if (!msAuth) throw new Error("Login failed: Could not obtain .ASPXFORMSAUTH cookie.");
+  
+  return `${sessionId}; ${msAuth}`;
+}
+
+async function getActivityDetailsRaw(
+  activityId: string, 
+  cookies: string, 
+  maxRetries: number = 3, 
+  timeoutMilliseconds: number = 20000
+): Promise<string | null> {
+  const url = 'https://engage.nkcswx.cn/Services/ActivitiesService.asmx/GetActivityDetails';
+  const headers = {
+    'Content-Type': 'application/json; charset=UTF-8', 
+    'Cookie': cookies,
+    'User-Agent': 'Mozilla/5.0 (Bun DSAS-CCA get-activity Module)',
+    'X-Requested-With': 'XMLHttpRequest'
+  };
+  const payload = { "activityID": String(activityId) };
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      const response = await axios.post(url, payload, {
+        headers, 
+        timeout: timeoutMilliseconds, 
+        responseType: 'text'
+      });
+      const outerData = JSON.parse(response.data);
+      if (outerData && typeof outerData.d === 'string') {
+        const innerData = JSON.parse(outerData.d);
+        if (innerData.isError) {
+          logger.warn(`API reported isError:true for activity ${activityId}.`);
+          return null;
+        }
+        return response.data;
+      } else {
+        logger.error(`Unexpected API response structure for activity ${activityId}.`);
+      }
+    } catch (error: any) {
+      // Check if response status is in 4xx range (400-499) to trigger auth error
+      if (error.response && error.response.status >= 400 && error.response.status < 500) {
+        logger.warn(`Authentication error (${error.response.status}) while fetching activity ${activityId}. Cookie may be invalid.`);
+        throw new AuthenticationError(`Received ${error.response.status} for activity ${activityId}`, error.response.status);
+      }
+      logger.error(`Attempt ${attempt + 1}/${maxRetries} for activity ${activityId} failed: ${error.message}`);
+      if (error.response) {
+         logger.error(`Status: ${error.response.status}, Data (getActivityDetailsRaw): ${ String(error.response.data).slice(0,100)}...`);
+      }
+      if (attempt === maxRetries - 1) {
+         logger.error(`All ${maxRetries} retries failed for activity ${activityId}.`);
+         throw error;
+      }
+      await new Promise(resolve => setTimeout(resolve, 1000 * (attempt + 1)));
+    }
+  }
+  return null;
+}
+
+/**
+ * Main exported function. Handles cookie caching, validation, re-authentication, and fetches activity details.
+ * @param activityId - The ID of the activity to fetch.
+ * @param userName - URL-encoded username.
+ * @param userPwd - URL-encoded password.
+ * @param templateFileName - Name of the login template file.
+ * @param forceLogin - If true, bypasses cached cookie and forces a new login.
+ * @returns The parsed JSON object of activity details, or null on failure.
+ */
+export async function fetchActivityData(
+  activityId: string, 
+  userName: string, 
+  userPwd: string, 
+  templateFileName: string = "login_template.txt", 
+  forceLogin: boolean = false
+): Promise<any | null> {
+  let currentCookie = forceLogin ? null : await loadCachedCookie();
+  
+  if (forceLogin && currentCookie) {
+    await clearCookieCache();
+    currentCookie = null;
+  }
+
+  if (currentCookie) {
+    const isValid = await testCookieValidity(currentCookie);
+    if (!isValid) {
+      logger.info("Cached cookie test failed or cookie expired. Clearing cache.");
+      await clearCookieCache();
+      currentCookie = null;
+    } else {
+      logger.info("Using valid cached cookie.");
+    }
+  }
+
+  if (!currentCookie) {
+    logger.info(forceLogin ? "Forcing new login." : "No valid cached cookie found or cache bypassed. Attempting login...");
+    try {
+      currentCookie = await getCompleteCookies(userName, userPwd, resolve(import.meta.dir, templateFileName));
+      await saveCookieToCache(currentCookie);
+    } catch (loginError) {
+      logger.error(`Login process failed: ${(loginError as Error).message}`);
+      return null;
+    }
+  }
+
+  if (!currentCookie) {
+    logger.error("Critical: No cookie available after login attempt. Cannot fetch activity data.");
+    return null;
+  }
+  
+  try {
+    const rawActivityDetailsString = await getActivityDetailsRaw(activityId, currentCookie);
+    if (rawActivityDetailsString) {
+      const parsedOuter = JSON.parse(rawActivityDetailsString);
+      return JSON.parse(parsedOuter.d);
+    }
+    logger.warn(`No data returned from getActivityDetailsRaw for activity ${activityId}, but no authentication error was thrown.`);
+    return null;
+  } catch (error) {
+    if (error instanceof AuthenticationError) {
+      logger.warn(`Initial fetch failed with AuthenticationError (Status: ${error.status}). Cookie was likely invalid. Attempting re-login and one retry.`);
+      await clearCookieCache(); 
+
+      try {
+        logger.info("Attempting re-login due to authentication failure...");
+        currentCookie = await getCompleteCookies(userName, userPwd, resolve(import.meta.dir, templateFileName));
+        await saveCookieToCache(currentCookie);
+        
+        logger.info("Re-login successful. Retrying request for activity details once...");
+        const rawActivityDetailsStringRetry = await getActivityDetailsRaw(activityId, currentCookie);
+        if (rawActivityDetailsStringRetry) {
+          const parsedOuterRetry = JSON.parse(rawActivityDetailsStringRetry);
+          return JSON.parse(parsedOuterRetry.d);
+        }
+        logger.warn(`Still no details for activity ${activityId} after re-login and retry.`);
+        return null;
+      } catch (retryLoginOrFetchError) {
+        logger.error(`Error during re-login or retry fetch for activity ${activityId}: ${(retryLoginOrFetchError as Error).message}`);
+        return null;
+      }
+    } else {
+      logger.error(`Failed to fetch activity data for ${activityId} due to non-authentication error: ${(error as Error).message}`);
+      return null;
+    }
+  }
+}
+
+// Optionally
+export { clearCookieCache, testCookieValidity };

engage-api/struct-activity.ts

@@ -0,0 +1,242 @@
+// engage-api/struct-activity.ts
+import pangu from 'pangu';
+import { logger } from '../utils/logger';
+import type { ActivityData } from '../models/activity';
+
+// Define interfaces
+interface ActivityField {
+  fID: string;
+  fData: string;
+  fType?: string;
+  lParms?: any[];
+}
+
+interface ActivityRow {
+  rID: string;
+  fields: ActivityField[];
+}
+
+interface RawActivityData {
+  newRows: ActivityRow[];
+  isError?: boolean;
+}
+
+interface Location {
+  block: string | null;
+  room: string | null;
+  site: string | null;
+}
+
+interface Duration {
+  endDate: string | null;
+  isRecurringWeekly: boolean | null;
+  startDate: string | null;
+}
+
+interface Grades {
+  max: string | null;
+  min: string | null;
+}
+
+interface Meeting {
+  day: string | null;
+  endTime: string | null;
+  location: Location;
+  startTime: string | null;
+}
+
+const clubSchema: ActivityData = {
+  academicYear: null,
+  category: null,
+  description: null,
+  duration: {
+    endDate: null,
+    isRecurringWeekly: null,
+    startDate: null
+  },
+  grades: {
+    max: null,
+    min: null
+  },
+  id: null,
+  isPreSignup: null,
+  isStudentLed: null,
+  materials: [],
+  meeting: {
+    day: null,
+    endTime: null,
+    location: {
+      block: null,
+      room: null,
+      site: null
+    },
+    startTime: null
+  },
+  name: null,
+  photo: null,
+  poorWeatherPlan: null,
+  requirements: [],
+  schedule: null,
+  semesterCost: null,
+  staff: [],
+  staffForReports: [],
+  studentLeaders: []
+};
+
+async function applyFields(field: ActivityField, structuredActivityData: ActivityData): Promise<void> {
+  switch (true) {
+    case field.fID === "academicyear":
+      structuredActivityData.academicYear = field.fData;
+      break;
+    case field.fID === "schedule":
+      structuredActivityData.schedule = field.fData;
+      break;
+    case field.fID === "category":
+      structuredActivityData.category = field.fData;
+      break;
+    case field.fID === "activityname":
+      if (!structuredActivityData.name) structuredActivityData.name = "";
+      structuredActivityData.name = field.fData.replaceAll("  "," ");
+      structuredActivityData.name = structuredActivityData.name.replaceAll("）", ")");
+      structuredActivityData.name = structuredActivityData.name.replaceAll("（", "(");
+      structuredActivityData.name = structuredActivityData.name.replaceAll("'", "'");
+      structuredActivityData.name = structuredActivityData.name.replaceAll(".", "");
+      structuredActivityData.name = structuredActivityData.name.replaceAll("IssuesT台上的社会问题", "Issues T 台上的社会问题");
+      structuredActivityData.name =
+        structuredActivityData.name.replaceAll("校管弦乐团(新老成员都适用", "校管弦乐团(新老成员都适用)").replaceAll("))",")");
+      structuredActivityData.name = pangu.spacing(structuredActivityData.name);
+      break;
+    case field.fID === "day":
+      structuredActivityData.meeting.day = field.fData;
+      break;
+    case field.fID === "start":
+      structuredActivityData.meeting.startTime = field.fData;
+      break;
+    case field.fID === "end":
+      structuredActivityData.meeting.endTime = field.fData;
+      break;
+    case field.fID === "site":
+      structuredActivityData.meeting.location.site = field.fData;
+      break;
+    case field.fID === "block":
+      structuredActivityData.meeting.location.block = field.fData;
+      break;
+    case field.fID === "room":
+      structuredActivityData.meeting.location.room = field.fData;
+      break;
+    case field.fID === "staff":
+      let staff = field.fData.split(", ");
+      structuredActivityData.staff = staff;
+      break;
+    case field.fID === "runsfrom":
+      structuredActivityData.duration.startDate = field.fData;
+      break;
+    case field.fID === "runsto":
+      structuredActivityData.duration.endDate = field.fData;
+      break;
+    case field.fData === "Recurring Weekly":
+      structuredActivityData.duration.isRecurringWeekly = true;
+      break;
+    default:
+      logger.debug(`No matching case for field: fID=${field.fID}, fType=${field.fType}`);
+      break;
+  }
+}
+
+async function postProcess(structuredActivityData: ActivityData): Promise<void> {
+  // Format description
+  structuredActivityData.description = structuredActivityData.description?.replaceAll("<br/>", "\n") ?? "";
+  structuredActivityData.description = structuredActivityData.description?.replaceAll("\u000B", "\v") ?? "";
+  structuredActivityData.description = pangu.spacing(structuredActivityData.description ?? "");
+  structuredActivityData.description = structuredActivityData.description?.replaceAll("\n ", "\n") ?? "";
+  
+  // Determine if student-led
+  if (structuredActivityData.name) {
+    if (structuredActivityData.name.search("Student-led") !== -1 ||
+        structuredActivityData.name.search("学生社团") !== -1 ||
+        structuredActivityData.name.search("(SL)") !== -1) {
+      structuredActivityData.isStudentLed = true;
+    } else {
+      structuredActivityData.isStudentLed = false;
+    }
+  }
+  
+  // Parse grades from schedule
+  try {
+    if (structuredActivityData.schedule) {
+      let grades = structuredActivityData.schedule.match(/G(\d+)-(\d+)/) || 
+                  structuredActivityData.schedule.match(/KG(\d+)-KG(\d+)/);
+      
+      if (!grades || grades.length < 3) {
+        throw new Error('Invalid grade format in schedule');
+      }
+      const minGrade = grades[1];
+      const maxGrade = grades[2];
+      if (minGrade === undefined || maxGrade === undefined) {
+          throw new Error('Invalid grade format in schedule');
+      }
+      structuredActivityData.grades.min = parseInt(minGrade).toString(10);
+      structuredActivityData.grades.max = parseInt(maxGrade).toString(10);
+    }
+  } catch (error) {
+    logger.error(`Failed to parse grades: ${(error as Error).message}`);
+    structuredActivityData.grades.min = null;
+    structuredActivityData.grades.max = null;
+  }
+}
+
+export async function structActivityData(rawActivityData: RawActivityData): Promise<ActivityData> {
+  let structuredActivityData: ActivityData = JSON.parse(JSON.stringify(clubSchema));
+  let rows = rawActivityData.newRows;
+  
+  // Load club id - "rID": "3350:1:0:0"
+  structuredActivityData.id = rows[0]?.rID?.split(":")[0] ?? null;
+  
+  for (const rowObject of rows) {
+    for (let i = 0; i < rowObject.fields.length; i++) {
+      const field = rowObject.fields[i];
+      // Skip if no fData
+      if (!field || !field.fData) { continue; }
+      // Process hard cases first
+      if (field.fData === "Description") {
+        if (i + 1 < rowObject.fields.length && rowObject.fields[i + 1]) {
+          structuredActivityData.description = rowObject.fields[i + 1].fData;
+        }
+        continue;
+      } else if (field.fData === "Name To Appear On Reports") {
+        if (i + 1 < rowObject.fields.length && rowObject.fields[i + 1]) {
+          let staffForReports = rowObject.fields[i + 1].fData.split(", ");
+          structuredActivityData.staffForReports = staffForReports;
+        }
+      } else if (field.fData === "Upload Photo") {
+        if (i + 1 < rowObject.fields.length && rowObject.fields[i + 1]) {
+          structuredActivityData.photo = rowObject.fields[i + 1].fData;
+        }
+      } else if (field.fData === "Poor Weather Plan") {
+        if (i + 1 < rowObject.fields.length && rowObject.fields[i + 1]) {
+          structuredActivityData.poorWeatherPlan = rowObject.fields[i + 1].fData;
+        }
+      } else if (field.fData === "Activity Runs From") {
+        if (i + 4 < rowObject.fields.length && rowObject.fields[i + 4]) {
+          structuredActivityData.duration.isRecurringWeekly = 
+            rowObject.fields[i + 4].fData === "Recurring Weekly";
+        }
+      } else if (field.fData === "Is Pre Sign-up") {
+        if (i + 1 < rowObject.fields.length && rowObject.fields[i + 1]) {
+          structuredActivityData.isPreSignup = rowObject.fields[i + 1].fData !== "";
+        }
+      } else if (field.fData === "Semester Cost") {
+        if (i + 1 < rowObject.fields.length && rowObject.fields[i + 1]) {
+          structuredActivityData.semesterCost = 
+            rowObject.fields[i + 1].fData === "" ? null : rowObject.fields[i + 1].fData;
+        }
+      } else {
+        // Pass any other easy cases to helper function
+        await applyFields(field, structuredActivityData);
+      }
+    }
+  }
+  
+  await postProcess(structuredActivityData);
+  return structuredActivityData;
+}

engage-api/struct-staff.ts

@@ -0,0 +1,114 @@
+// ./engage-api/struct-staff.ts
+import { logger } from '../utils/logger';
+
+// Define interfaces
+interface Staff {
+  key: string;
+  val: string;
+}
+
+interface ActivityField {
+  fID: string;
+  fData?: string;
+  lParms?: Staff[];
+}
+
+interface ActivityRow {
+  fields: ActivityField[];
+}
+
+interface RawActivityData {
+  newRows: ActivityRow[];
+}
+
+// Using a Map for staff data
+const staffs: Map<string, string> = new Map();
+
+/**
+ * Filters out blacklisted staff keys and corrects odd name formats
+ * @param staffsMap - Map of staff IDs to names
+ * @returns Cleaned staff map
+ */
+async function dropOddName(staffsMap: Map<string, string>): Promise<Map<string, string>> {
+  const blackList: string[] = [
+    "CL1-827", "CL1-831", "ID: CL1-832", "CL1-834",
+    "CL1-835", "CL1-836", "CL1-838", "CL1-842", "CL1-843",
+    "CL1-844", "CL1-845", "CL1-846"
+  ];
+  
+  const oddNames: Record<string, string> = {
+    "Mr TT15 Pri KinLiu TT15 Pri KinLiu": "Mr Kin Liu",
+    "Mr TT13 Yanni Shen TT13 Yanni Shen": "Mr Yanni Shen",
+    "Mr TT19 Pri Saima Salem TT19 Pri Saima Salem": "Mr Saima Salem",
+    "Ms TT Ca(CCA) TT Ma": "Ms Ca Ma", 
+    "Mr JackyT JackyT": "Mr JackyT",
+    "Ms TT Ma TT M": "Ms Ma M", 
+    "TT01 Fang TT01 Dong": "Mr Fang Dong",
+    "Mr TT18 Shane Rose TT18 Shane Rose": "Mr Shane Rose",
+    "Ms Caroline Malone(id)": "Ms Caroline Malone",
+    "Ms Marina Mao(id)": "Ms Marina Mao",
+    "Mrs Amy Yuan (Lower Secondary Secretary初中部学部助理)": "Mrs Amy Yuan",
+    "Ms Lily Liu (Primary)": "Ms Lily Liu", 
+    "Ms Cindy 薛": "Ms Cindy Xue",
+    "Ms SiSi Li": "Ms Sisi Li"
+  };
+  
+  // Filter out blacklisted keys
+  for (const key of blackList) {
+    staffsMap.delete(key);
+  }
+  
+  // Update odd names
+  for (const [originalName, correctedName] of Object.entries(oddNames)) {
+    for (const [id, name] of staffsMap.entries()) {
+      if (name === originalName) {
+        staffsMap.set(id, correctedName);
+      }
+    }
+  }
+  
+  return staffsMap;
+}
+
+/**
+ * Updates the staff map with new staff data
+ * @param staffsMap - Existing map of staff IDs to names
+ * @param lParms - Array of staff objects with key/value pairs
+ * @returns Updated staff map
+ */
+async function updateStaffMap(
+  staffsMap: Map<string, string>, 
+  lParms?: Staff[]
+): Promise<Map<string, string>> {
+  if (!lParms) {
+    return staffsMap;
+  }
+  
+  for (const staff of lParms) {
+    if (staff && staff.key) {
+      staffsMap.set(staff.key, staff.val || "");
+    }
+  }
+  
+  return await dropOddName(staffsMap);
+}
+
+/**
+ * Structures staff data from raw activity data
+ * @param rawActivityData - Raw activity data from API
+ * @returns Map of staff IDs to names
+ */
+export async function structStaffData(rawActivityData: RawActivityData): Promise<Map<string, string>> {
+  const rows = rawActivityData.newRows;
+  
+  for (const rowObject of rows) {
+    for (const field of rowObject.fields) {
+      if (field.fID === "staff") {
+        return await updateStaffMap(staffs, field.lParms);
+      }
+    }
+  }
+  
+  // Return the staff map even if no updates were made
+  return staffs;
+}