/**
 * Known consent categories. The `(string & {})` escape hatch keeps the union
 * open for custom categories while still providing autocomplete for the
 * standard values.
 */
export type ConsentCategory =
  | "necessary"
  | "functional"
  | "analytics"
  | "marketing"
  | (string & {});

/** Whether a subject has granted or denied consent for a category. */
export type ConsentState = "granted" | "denied" | "pending";

/** Per-category consent record for a single subject. */
export type UserConsentState = {
  readonly category: ConsentCategory;
  readonly state: ConsentState;
  readonly grantedAt?: Date;
  readonly withdrawnAt?: Date;
  /** Banner version the user saw when granting/withdrawing. */
  readonly bannerVersion?: string;
  /** Privacy policy version in effect at grant/withdrawal time. */
  readonly policyVersion?: string;
  /** How consent was recorded: "banner-accept", "signup-migration", etc. */
  readonly method?: string;
};

/** Optional metadata carried with a consent grant. */
export type ConsentGrantMeta = {
  bannerVersion?: string;
  policyVersion?: string;
  method?: string;
};
