// Types for handover-message.js — written rather than `@ts-expect-error`'d, for the same reason
// github-app.d.ts is: this is OUR module and its shape is part of a customer-facing contract.
// SPEC-coam §8.6 says what a handover letter must contain and what it must never contain; a caller
// that can pass the wrong `role`, or forget `expires`, produces a letter that is wrong in a way
// nobody sees until it has already been sent.

/** owner = the site changes hands. admin/manager = a seat on someone else's site. */
export type HandoverRole = 'owner' | 'admin' | 'manager';

export interface HandoverParams {
  /** The site's live domain — appears in the subject and the opening line. */
  domain: string;
  /** The one-time invite/transfer URL. Goes in the BODY only; never the subject. */
  link: string;
  /** ISO timestamp; rendered as a date. */
  expires: string;
  /** Recipient's name. Absent → a plain greeting rather than "Hi ,". */
  name?: string;
  /** What WE keep after an owner handover. `null` = nothing. Ignored for admin/manager. */
  keep?: string | null;
}

export interface HandoverMessage {
  /** Never contains the link: subjects survive in mail logs and notification previews. */
  subject: string;
  body: string;
  /** `mailto:?subject=…&body=…` — no recipient baked in; the sender chooses. */
  mailto: string;
}

export function handoverMessage(role: HandoverRole, p: HandoverParams): HandoverMessage;
export function mailtoFor(subject: string, body: string): string;
/** Which of the five required parts (SPEC-coam §8.6) a letter is missing. Empty = complete. */
export function missingParts(
  role: HandoverRole,
  msg: HandoverMessage,
  p: Pick<HandoverParams, 'link' | 'expires'>,
): string[];
export const REQUIRED_PARTS: readonly string[];