Suggest gender from names in Next.js server actions

// app/onboarding/actions.ts
"use server";

import { finowl, FinowlError } from "@/lib/finowl";

type Prediction = {
  result_status: "identified" | "unknown";
  gender: string | null;
  confidence: number | null;
  source: string | null;
  reason: "not_found" | "no_name_candidate" | "ambiguous" | "insufficient_evidence" | null;
};

export type Suggestion =
  | { kind: "suggested"; gender: string; confidence: number | null }
  | { kind: "ask"; reason: string | null } // show an empty, optional field
  | { kind: "retry"; afterSeconds: number | null };

// Prefills an optional, editable field. The user's own choice always wins.
export async function suggestGender(firstName: string, country?: string): Promise<Suggestion> {
  const name = firstName.trim().slice(0, 254);
  if (!name) return { kind: "ask", reason: "no_name_candidate" };

  try {
    const { data } = await finowl<{ data: Prediction }>(
      "/v1/gender/name",
      country ? { name, country } : { name },
    );
    if (data.result_status === "unknown" || !data.gender) {
      return { kind: "ask", reason: data.reason }; // normal, billed result: don't retry
    }
    return { kind: "suggested", gender: data.gender, confidence: data.confidence };
  } catch (err) {
    if (!(err instanceof FinowlError)) throw err;
    if (err.status === 429) return { kind: "retry", afterSeconds: err.retryAfter };
    if (err.status === 400) return { kind: "ask", reason: "invalid_input" }; // e.g. bad country code
    if (err.status === 401) console.error("Finowl rejected FINOWL_API_KEY");
    return { kind: "ask", reason: null };
  }
}