// utils/requester.js
//
// Single source of truth for "who initiated this bot action?" — used for
// audit log lines, attribution in confirmation messages, and the requester
// snapshot stored alongside pending adaptive cards.
//
// IMPORTANT — why this file exists:
//   webex-node-bot-framework does NOT expose `trigger.personEmail` or
//   `trigger.personDisplayName` as top-level fields, despite a couple of
//   stale references in its own JSDoc examples. The framework always
//   populates `trigger.person` (the full Webex Person object, fetched via
//   `webex.people.get(triggerObject.personId)` — see framework.js around
//   line 697) for both `message` and `attachmentAction` triggers. The raw
//   Webex `attachmentAction` payload only carries `personId`, not the
//   email. So the only reliable way to attribute the requester is via
//   `trigger.person.emails[0]` and `trigger.person.displayName`.
//
// HTTP-originated triggers (built in index.js's `app.get('/:command', ...)`
// adapter) carry `source: 'http'` and no `person` field — that case yields
// `email/displayName = null` and `describeRequester` renders it as
// "via HTTP API" for the audit log.

/**
 * Build a structured requester record from a trigger.
 *
 * @param {object} trigger - webex-node-bot-framework trigger or HTTP fake
 *                           trigger (from index.js).
 * @returns {{email: string|null, displayName: string|null, source: 'webex'|'http'}}
 */
export function extractRequester(trigger) {
  const isHttp = trigger?.source === 'http';
  const rawEmail = trigger?.person?.emails?.[0];
  return {
    email: rawEmail ? String(rawEmail).toLowerCase() : null,
    displayName: trigger?.person?.displayName || null,
    source: isHttp ? 'http' : 'webex',
  };
}

/**
 * Render a requester as a human-readable string for audit log lines.
 *
 * Examples:
 *   "chat user benhumeag@ae.com"
 *   "via HTTP API"
 *   "unknown requester"
 *
 * @param {ReturnType<typeof extractRequester> | null | undefined} requester
 * @returns {string}
 */
export function describeRequester(requester) {
  if (!requester) return 'unknown requester';
  if (requester.source === 'http') return 'via HTTP API';
  const who = requester.email || requester.displayName || 'unknown chat user';
  return `chat user ${who}`;
}