elysium/apps/api/src/services/discord.ts

/**
 * @file Discord OAuth helpers for token exchange, user fetching, and URL building.
 * @copyright nhcarrigan
 * @license Naomi's Public License
 * @author Naomi Carrigan
 */
/* eslint-disable @typescript-eslint/naming-convention -- Discord API requires snake_case fields and HTTP headers require Pascal-Case */
import { logger } from "./logger.js";

interface DiscordTokenResponse {
  access_token:  string;
  token_type:    string;
  expires_in:    number;
  refresh_token: string;
  scope:         string;
}

interface DiscordUser {
  id:            string;
  username:      string;
  discriminator: string;
  avatar:        string | null;
}

/**
 * Exchanges a Discord OAuth authorisation code for an access token.
 * @param code - The authorisation code received from Discord's OAuth callback.
 * @returns The Discord token response containing the access token.
 * @throws {Error} If OAuth environment variables are missing or the exchange fails.
 */
const exchangeCode = async(
  code: string,
): Promise<DiscordTokenResponse> => {
  const clientId = process.env.DISCORD_CLIENT_ID;
  const clientSecret = process.env.DISCORD_CLIENT_SECRET;
  const redirectUri = process.env.DISCORD_REDIRECT_URI;

  if (
    clientId === undefined || clientId === ""
    || clientSecret === undefined || clientSecret === ""
    || redirectUri === undefined || redirectUri === ""
  ) {
    throw new Error("Discord OAuth environment variables are required");
  }

  const parameters = new URLSearchParams({
    client_id:     clientId,
    client_secret: clientSecret,
    code:          code,
    grant_type:    "authorization_code",
    redirect_uri:  redirectUri,
  });

  try {
    const response = await fetch("https://discord.com/api/v10/oauth2/token", {
      body:    parameters.toString(),
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      method:  "POST",
    });

    if (!response.ok) {
      throw new Error(`Discord token exchange failed: ${response.statusText}`);
    }

    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Response JSON matches DiscordTokenResponse shape */
    return await (response.json() as Promise<DiscordTokenResponse>);
  } catch (error) {
    void logger.error(
      "discord_exchange_code",
      error instanceof Error
        ? error
        : new Error(String(error)),
    );
    throw error;
  }
};

/**
 * Fetches the Discord user profile for the given access token.
 * @param accessToken - A valid Discord OAuth access token.
 * @returns The Discord user object.
 * @throws {Error} If the user fetch fails.
 */
const fetchDiscordUser = async(
  accessToken: string,
): Promise<DiscordUser> => {
  try {
    const response = await fetch("https://discord.com/api/v10/users/@me", {
      headers: { Authorization: `Bearer ${accessToken}` },
    });

    if (!response.ok) {
      throw new Error(`Discord user fetch failed: ${response.statusText}`);
    }

    /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Response JSON matches DiscordUser shape */
    return await (response.json() as Promise<DiscordUser>);
  } catch (error) {
    void logger.error(
      "discord_fetch_user",
      error instanceof Error
        ? error
        : new Error(String(error)),
    );
    throw error;
  }
};

/**
 * Builds the Discord OAuth authorisation URL.
 * @returns The full OAuth URL to redirect the user to.
 * @throws {Error} If OAuth environment variables are missing.
 */
const buildOAuthUrl = (): string => {
  const clientId = process.env.DISCORD_CLIENT_ID;
  const redirectUri = process.env.DISCORD_REDIRECT_URI;

  if (
    clientId === undefined || clientId === ""
    || redirectUri === undefined || redirectUri === ""
  ) {
    throw new Error("Discord OAuth environment variables are required");
  }

  const parameters = new URLSearchParams({
    client_id:     clientId,
    redirect_uri:  redirectUri,
    response_type: "code",
    scope:         "identify",
  });

  return `https://discord.com/api/oauth2/authorize?${parameters.toString()}`;
};

export type { DiscordTokenResponse, DiscordUser };
export { buildOAuthUrl, exchangeCode, fetchDiscordUser };