// 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 domain — appears in the subject and the opening line.
   *
   * 🔴 Its presence says nothing about whether we SERVE it. On a not-yet-cut-over
   * record this is where the site is going; today it still resolves to whatever the
   * owner had there before. That is what `live` is for.
   */
  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;
  /**
   * Are we actually serving `domain`? Same question `list_sites` answers with `stage`.
   *
   * 🩸 Defaults to FALSE on purpose. The letter used to say "Your site is live at
   * <domain>" unconditionally, and on 2026-08-14 that would have pointed a customer
   * at their own Wix site. An unknown answer must make no claim; a caller that means
   * "yes" already knows it and can say so.
   */
  live?: boolean;
  /** Where the site can be seen while the domain still points somewhere else. */
  previewUrl?: 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[];