HealthLog/src/lib/queries/use-managed-profiles.ts

"use client";

/**
 * v1.37.0 — the reads and writes behind the managed-profile surface.
 *
 * A managed profile is a record with no login of its own. It is created by the
 * person who will look after it, and from that moment it exists only through
 * its Guardians — which is why every call here refreshes the ACCOUNT payload
 * and not merely the panel it was fired from.
 *
 * That is the one property worth stating up front. The list of profiles a
 * Guardian looks after is not a read of its own: it is `accountAccess.accounts`
 * on `GET /api/auth/me`, filtered to the managed entries, because the Guardian's
 * relationship to the profile IS a MANAGE grant. So a creation that refreshed
 * the sharing panel and not the payload would leave the new profile invisible —
 * in the switcher, in the banner, and in this card — until the next boot. Every
 * mutation below therefore goes through `invalidateGrantReads`, the one entry
 * `use-account-grants.ts` already publishes for exactly this fan-out; the
 * managed-profile family rides it as a key prefix rather than as a second
 * invalidation path (`grantDependentKeys`).
 */

import type { HandoverMethod } from "@/lib/validations/claim-sso";
import {
  useMutation,
  useQuery,
  useQueryClient,
  type QueryClient,
} from "@tanstack/react-query";

import { apiDelete, apiGet, apiPatch, apiPost } from "@/lib/api/api-fetch";
import { queryKeys } from "@/lib/query-keys";
import { invalidateGrantReads } from "@/lib/queries/use-account-grants";
import type { GrantParty } from "@/lib/queries/use-account-grants";
import type { Locale } from "@/lib/i18n/config";
import type { HandoverAccess } from "@/lib/managed-profiles/handover-access";

/**
 * Exactly the body `POST /api/managed-profiles` accepts.
 *
 * The route's schema is `.strict()`, so an extra key is a 422 with nothing
 * useful in it — a form that helpfully posted an empty `heightCm` would be
 * refused for a field the person never saw. Naming the four fields as a type
 * rather than passing the form state through is what stops that: a fifth field
 * added to the form cannot reach the wire without somebody deciding it should.
 */
export interface CreateManagedProfileInput {
  displayName: string;
  /** ISO `yyyy-MM-dd`, or null. Never synthesised from a year. */
  dateOfBirth: string | null;
  locale: Locale;
  /** IANA zone name. */
  timezone: string;
  /** `User.gender`. Null is a real answer — "not recorded" — not an omission. */
  gender: ManagedProfileGender;
}

/** The three values `User.gender` takes, plus the honest absence. */
export type ManagedProfileGender = "MALE" | "FEMALE" | "OTHER" | null;

/** What the create, read and update routes all answer with. */
export interface ManagedProfileView {
  id: string;
  displayName: string | null;
  dateOfBirth: string | null;
  gender: ManagedProfileGender;
  /** Nullable, as the column is. A record created here always carries one. */
  locale: string | null;
  timezone: string;
  recordKind: "managed";
}

/**
 * The body `PATCH /api/managed-profiles/{id}` accepts, plus the record it is
 * addressed to.
 *
 * Every field optional, at least one required, and `.strict()` on the server —
 * so the mutation names the fields one by one rather than spreading form state,
 * exactly as the creation does. An absent key means "leave it"; an explicit
 * null on the two nullable fields clears it. `profileId` addresses the request
 * and is deliberately not in the body: the schema would refuse it.
 */
export interface UpdateManagedProfileInput {
  profileId: string;
  displayName?: string;
  dateOfBirth?: string | null;
  locale?: Locale;
  timezone?: string;
  gender?: ManagedProfileGender;
}

/**
 * Everything a managed-profile lifecycle change makes stale.
 *
 * Exported as a plain function over a `QueryClient` for the same reason
 * `invalidateGrantReads` is: a test can hand it a real client, seed the reads
 * and check they came back invalidated. "The mutation calls invalidate" is a
 * claim about the source; "the account payload comes back invalidated" is the
 * claim that decides whether the new profile appears in the switcher.
 */
export function invalidateManagedProfileReads(queryClient: QueryClient): void {
  invalidateGrantReads(queryClient);
}

/** The same refresh, bound to the mounted client. */
function useInvalidateManagedProfiles() {
  const queryClient = useQueryClient();
  return () => invalidateManagedProfileReads(queryClient);
}

/**
 * Runs a request that the server may hold back for a fresh proof — in a
 * component, `useRecentProof().run`.
 *
 * Every write in this family resolves `requireFreshMfa`, whose 401
 * `auth.stepup.required` names the proofs that clear it in `meta.methods`.
 * The guard opens the re-proof dialog on that answer, posts the proof and
 * sends the request once more, so the mutation settles with the real outcome
 * instead of a sentence telling somebody to confirm a factor with nowhere to
 * do it. The argument is required rather than defaulted: a caller that forgot
 * it would compile, render the refusal as text, and be the defect again.
 */
export type ProofGuard = <T>(action: () => Promise<T>) => Promise<T>;

/**
 * Create a record somebody looks after.
 *
 * `requireFreshMfa` guards the route, so a 401 carrying
 * `meta.errorCode: auth.stepup.required` is the EXPECTED first answer for
 * anybody who has a second factor and has not proved it recently. `guard`
 * turns it into the re-proof dialog and a second attempt.
 */
export function useCreateManagedProfile(guard: ProofGuard) {
  const invalidate = useInvalidateManagedProfiles();
  return useMutation({
    mutationKey: queryKeys.managedProfileCreate(),
    mutationFn: (input: CreateManagedProfileInput) =>
      guard(() => apiPost<ManagedProfileView>("/api/managed-profiles", input)),
    onSuccess: invalidate,
  });
}

/**
 * The record as it stands, for the form that is about to change it.
 *
 * The account payload names a managed record and nothing more, so a form
 * opened from the Guardian's own panel cannot show the timezone, the language,
 * the date of birth or the sex it is about to overwrite. This is that read.
 * `enabled` is what keeps it off the wire until somebody opens the form: a
 * Guardian with four records should not fetch four identities to paint a list
 * that shows none of them.
 */
export function useManagedProfile(profileId: string, enabled = true) {
  return useQuery({
    queryKey: queryKeys.managedProfile(profileId),
    queryFn: () =>
      apiGet<ManagedProfileView>(`/api/managed-profiles/${profileId}`),
    enabled,
  });
}

/**
 * Change a record somebody looks after.
 *
 * Guarded by `requireFreshMfa` like every other act in this family, so a 401
 * carrying `meta.errorCode: auth.stepup.required` is the expected first answer
 * rather than a failure — `guard` routes it into the re-proof dialog.
 *
 * The whole family is invalidated on success because the display name is what
 * the switcher, the record banner and this card all identify the record by, and
 * the record's own identity read is dropped alongside so a second edit opens
 * from the server's version rather than from the one that was just replaced.
 */
export function useUpdateManagedProfile(guard: ProofGuard) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationKey: queryKeys.managedProfileUpdate(),
    mutationFn: (input: UpdateManagedProfileInput) =>
      guard(() =>
        apiPatch<ManagedProfileView>(
          `/api/managed-profiles/${input.profileId}`,
          managedProfileEditBody(input),
        ),
      ),
    onSuccess: (_result, input) => {
      invalidateManagedProfileReads(queryClient);
      void queryClient.invalidateQueries({
        queryKey: queryKeys.managedProfile(input.profileId),
      });
    },
  });
}

/**
 * The wire body, composed once and exported.
 *
 * Pure and separate from the mutation for the same reason `guardianInviteBody`
 * is: the integration suite posts the REAL body through the REAL route rather
 * than a hand-written copy, which is the assembly a two-sided test misses.
 *
 * Each key is present only when the caller named it, because the route reads
 * absence as "leave it" and an explicit `undefined` would serialise to nothing
 * anyway — stating it is what stops a later spread from sending five keys for a
 * one-field edit.
 */
export function managedProfileEditBody(
  input: UpdateManagedProfileInput,
): Record<string, unknown> {
  return {
    ...(input.displayName !== undefined
      ? { displayName: input.displayName }
      : {}),
    ...(input.dateOfBirth !== undefined
      ? { dateOfBirth: input.dateOfBirth }
      : {}),
    ...(input.locale !== undefined ? { locale: input.locale } : {}),
    ...(input.timezone !== undefined ? { timezone: input.timezone } : {}),
    ...(input.gender !== undefined ? { gender: input.gender } : {}),
  };
}

/** One person who looks after a profile, as the roster publishes them. */
export interface ManagedProfileGuardian {
  /** The grant row — what `DELETE .../guardians/{grantId}` takes. */
  grantId: string;
  account: GrantParty;
  /**
   * PENDING or ACTIVE. Only ACTIVE counts toward the last-Guardian floor, and
   * the server counts the same way — a pending invitation does not let the
   * last Guardian leave.
   */
  state: "PENDING" | "ACTIVE";
  invitedAt: string;
  acceptedAt: string | null;
}

/**
 * Who else looks after this profile.
 *
 * The read the removal control needs to exist at all: a Guardian grant has the
 * PROFILE as grantor, so it never appears in the caller's own given-list and
 * `GET /api/account/grants` cannot supply the `grantId`. It is also where the
 * last-Guardian floor is counted from BEFORE the act rather than discovered as
 * a 409 after it.
 */
export function useManagedProfileGuardians(profileId: string, enabled = true) {
  return useQuery({
    queryKey: queryKeys.managedProfileGuardians(profileId),
    queryFn: () =>
      apiGet<ManagedProfileGuardian[]>(
        `/api/managed-profiles/${profileId}/guardians`,
      ),
    enabled,
  });
}

/**
 * Delete a managed profile, and everything recorded in it.
 *
 * The variable is the profile id, which is what lets a refusal be rendered on
 * the row it was refused for rather than somewhere near it.
 *
 * This route emits no last-Guardian refusal, and that is deliberate rather
 * than an omission: deleting the profile is the documented way OUT of the
 * floor. A Guardian may not strand a record with nobody looking after it, but
 * they may end the record.
 */
export function useDeleteManagedProfile(guard: ProofGuard) {
  const invalidate = useInvalidateManagedProfiles();
  return useMutation({
    mutationKey: queryKeys.managedProfileDelete(),
    mutationFn: (profileId: string) =>
      guard(() =>
        apiDelete<{ deleted: true }>(`/api/managed-profiles/${profileId}`),
      ),
    onSuccess: invalidate,
  });
}

/**
 * Exactly the body `POST /api/managed-profiles/{id}/guardians` accepts, plus
 * the profile the request is addressed to.
 *
 * The route's schema is `.strict()` and names two fields. `identifier` is the
 * invitee's username OR e-mail, matched case-insensitively — the same
 * identifier the ordinary grant invitation takes. `expiresAt` is an ISO
 * datetime WITH an offset: a bare `YYYY-MM-DD` is a 422, which is why the
 * caller runs it through the shared end-of-day helper rather than sending the
 * date field's raw value.
 */
export interface InviteManagedProfileGuardianInput {
  profileId: string;
  identifier: string;
  expiresAt: string | null;
}

/**
 * Offer somebody else a share in looking after this profile.
 *
 * The grant is created PENDING and reaches the invitee's ordinary "invitations
 * to you" card, where they accept it exactly as they would any other. Nothing
 * here accepts on their behalf, and until they accept they do not count toward
 * the last-Guardian floor.
 */
export function useInviteManagedProfileGuardian(guard: ProofGuard) {
  const invalidate = useInvalidateManagedProfiles();
  return useMutation({
    mutationKey: queryKeys.managedProfileGuardianInvite(),
    mutationFn: (input: InviteManagedProfileGuardianInput) =>
      guard(() =>
        apiPost(
          `/api/managed-profiles/${input.profileId}/guardians`,
          guardianInviteBody(input),
        ),
      ),
    onSuccess: invalidate,
  });
}

/**
 * The wire body, composed once and exported.
 *
 * Pure and separate from the mutation so the integration suite can post the
 * REAL body through the REAL route rather than a hand-written copy of it. A
 * hand-written copy is the shape of test that stays green while the client
 * renames a field: both ends prove themselves and the assembly between them is
 * what dropped it.
 *
 * `profileId` addresses the request and is deliberately not in the body: the
 * route's schema is `.strict()` and would refuse it.
 */
export function guardianInviteBody(input: InviteManagedProfileGuardianInput): {
  identifier: string;
  expiresAt: string | null;
} {
  return { identifier: input.identifier, expiresAt: input.expiresAt };
}

/**
 * End another Guardian's access.
 *
 * Another Guardian's, never one's own: the service refuses a target grant whose
 * grantee is the caller and the route turns that into the same 404 an unknown
 * profile gets. A Guardian steps away through the renounce control on the
 * shared-access panel instead.
 *
 * `variables` carries both ids so a refusal can be rendered on the guardian row
 * it belongs to rather than on the panel.
 */
export function useRemoveManagedProfileGuardian(guard: ProofGuard) {
  const invalidate = useInvalidateManagedProfiles();
  return useMutation({
    mutationKey: queryKeys.managedProfileGuardianRemove(),
    mutationFn: ({
      profileId,
      grantId,
    }: {
      profileId: string;
      grantId: string;
    }) =>
      guard(() =>
        apiDelete(`/api/managed-profiles/${profileId}/guardians/${grantId}`),
      ),
    onSuccess: invalidate,
  });
}

// ── Handover (v1.42, #959) ──────────────────────────────────────────────────

/** What `GET /api/managed-profiles/{id}/handover` answers. */
export interface ManagedProfileHandoverStatus {
  /** False only when no way to redeem a link exists on this instance. */
  available: boolean;
  /**
   * v1.43 — how the person can redeem the link here. Absent from an older
   * server, which only offered the password.
   */
  methods?: HandoverMethod[];
  open: {
    id: string;
    createdAt: string;
    expiresAt: string;
    createdByYou: boolean;
  } | null;
}

/** The minted link. `token` and `url` exist in this response only. */
export interface ManagedProfileHandoverLink {
  id: string;
  token: string;
  url: string;
  expiresAt: string;
}

/**
 * Exactly the body `POST /api/managed-profiles/{id}/handover` accepts, plus
 * the profile it is addressed to. The route is `.strict()`, so the wire body
 * is composed by {@link handoverCreateBody} rather than by spreading this.
 */
export interface CreateManagedProfileHandoverInput {
  profileId: string;
  expiresInDays: 1 | 7 | 14;
  proposals: { grantId: string; proposal: HandoverAccess }[];
}

/** The wire body, composed once and exported for the integration suite. */
export function handoverCreateBody(input: CreateManagedProfileHandoverInput): {
  expiresInDays: 1 | 7 | 14;
  proposals: { grantId: string; proposal: HandoverAccess }[];
} {
  return {
    expiresInDays: input.expiresInDays,
    proposals: input.proposals.map((p) => ({
      grantId: p.grantId,
      proposal: p.proposal,
    })),
  };
}

/** Whether this profile has an open handover link. Never the link itself. */
export function useManagedProfileHandover(profileId: string, enabled = true) {
  return useQuery({
    queryKey: queryKeys.managedProfileHandover(profileId),
    queryFn: () =>
      apiGet<ManagedProfileHandoverStatus>(
        `/api/managed-profiles/${profileId}/handover`,
      ),
    enabled,
  });
}

/**
 * Mint the handover link. Step-up gated like every act in this family, so a
 * 401 carrying `auth.stepup.required` is the expected first answer, and
 * `guard` turns it into the re-proof dialog and a second attempt.
 *
 * The link lives in the mutation's `data` and nowhere else: it is shown once
 * and never cached under a query key.
 */
export function useCreateManagedProfileHandover(guard: ProofGuard) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationKey: queryKeys.managedProfileHandoverCreate(),
    mutationFn: async (input: CreateManagedProfileHandoverInput) => {
      const link = await guard(() =>
        apiPost<ManagedProfileHandoverLink>(
          `/api/managed-profiles/${input.profileId}/handover`,
          handoverCreateBody(input),
        ),
      );
      // Lazy chunk, as the admin invite and the share link do: the QR encoder
      // is needed here, at mint time, and nowhere else.
      const QRCode = (await import("qrcode")).default;
      const qrDataUrl = await QRCode.toDataURL(link.url, {
        width: 240,
        margin: 1,
      });
      return { ...link, qrDataUrl };
    },
    onSuccess: (_link, input) => {
      void queryClient.invalidateQueries({
        queryKey: queryKeys.managedProfileHandover(input.profileId),
      });
    },
  });
}

/** Withdraw the open link. No step-up: taking it back is never harder. */
export function useRevokeManagedProfileHandover() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationKey: queryKeys.managedProfileHandoverRevoke(),
    mutationFn: (profileId: string) =>
      apiDelete<{ revoked: boolean }>(
        `/api/managed-profiles/${profileId}/handover`,
      ),
    onSuccess: (_result, profileId) => {
      void queryClient.invalidateQueries({
        queryKey: queryKeys.managedProfileHandover(profileId),
      });
    },
  });
}