Create useProfile Hook

[lightwalker-eth]

Background

• In PR 1071 an opportunity was documented in apps/ensadmin/src/app/name/[name]/page.tsx for creating a distinct data model for the subjective ENS Profile data model as used in ENSAdmin.
• A related idea is implemented in the official ENS Manager app in their useProfile hook: https://github.com/ensdomains/ens-app-v3/blob/5cf6e9d5459c4c9159315f371985a7d0138e12c4/src/hooks/useProfile.ts
• Related issue: Dynamic resolution of all texts / addresses discovered via indexing #1083

Goals

Each app (including ENSAdmin) should define their own "wrapper" data model around their useRecords queries that is specific to their use case.

This data model should take the responsibility of hiding the nuances or complexities of a raw useRecords API response from the broader app. The broader app should be given a more simple and tailored data model to work with to make related code in the app as simple as possible.

• Design a nice data model for ENSProfile in ENSAdmin that's completely optimized for ENS Profiles in ENSAdmin and doesn't worry about being useful outside of ENSAdmin contexts.
• Create a useProfile hook that internally calls useRecords and then performs the data transformations that might be required to return the nice, clean, and specialized ENSProfile data model.
• Update the code in ProfileHeader, ProfileInformation, SocialLinks, Addresses, and AdditionalRecords so that their input changes to just taking an ENSProfile as returned by useProfile.
  • Remove logic in these UI components that are too specific to the nuances or complexities of a raw useRecords data model.

[notrab]

@lightwalker-eth I spent some time earlier today working on the useAvatarUrl hook, and reading through the context and comments implemented there, I should be able to create another hook with just as much detail as that. My idea is below, but not yet in a branch as there's quite a bit of changes already in #1143 so I'll wait for that to land.

The code below is for a hook only for ENSAdmin, BUT below that is another hook concept which can indeed be added to ensnode-react:

"use client";

import { useMemo } from "react";
import { useRecords } from "@ensnode/ensnode-react";
import { 
  Name, 
  ResolverRecordsSelection, 
  getCommonCoinTypes 
} from "@ensnode/ensnode-sdk";
import { useActiveNamespace } from "@/hooks/active/use-active-namespace";

/**
 * Strongly-typed social link identifiers supported by ENSAdmin profiles.
 */
export const ENSADMIN_SOCIAL_LINK_KEYS = [
  "com.twitter",
  "com.github",
  "com.farcaster",
  "org.telegram",
  "com.linkedin",
  "com.reddit",
] as const;

/**
 * A social link key recognized by ENSAdmin.
 */
export type ENSAdminSocialLinkKey = (typeof ENSADMIN_SOCIAL_LINK_KEYS)[number];

/**
 * A structured social link with its platform identifier and username/handle value.
 */
export type ENSAdminSocialLink = {
  readonly key: ENSAdminSocialLinkKey;
  readonly value: string;
};

/**
 * A structured address record with its coin type identifier and address value.
 */
export type ENSAdminAddressRecord = {
  readonly coinType: string;
  readonly address: string;
};

/**
 * A structured additional text record with its key and value.
 * Excludes records already displayed in header, profile, or social sections.
 */
export type ENSAdminAdditionalTextRecord = {
  readonly key: string;
  readonly value: string;
};

/**
 * The specialized ENS Profile data model optimized for ENSAdmin.
 * 
 * This model abstracts away the complexities of raw `useRecords` responses
 * and provides a clean, purpose-built structure for ENSAdmin's profile UI.
 * 
 * @example
 * ```typescript
 * const profile: ENSProfile = {
 *   name: "vitalik.eth",
 *   header: {
 *     avatarUrl: "https://...",
 *     headerImageUrl: "https://...",
 *     websiteUrl: "https://vitalik.ca",
 *   },
 *   information: {
 *     description: "Ethereum co-founder",
 *     email: "v@ethereum.org",
 *   },
 *   socialLinks: [
 *     { key: "com.twitter", value: "VitalikButerin" },
 *   ],
 *   addresses: [
 *     { coinType: "60", address: "0x..." },
 *   ],
 *   additionalTextRecords: [
 *     { key: "status", value: "Building" },
 *   ],
 * };
 * ```
 */
export type ENSProfile = {
  /**
   * The ENS name being displayed.
   */
  readonly name: Name;

  /**
   * Header section data including avatar, banner image, and website URL.
   */
  readonly header: {
    readonly avatarUrl: string | null;
    readonly headerImageUrl: string | null;
    readonly websiteUrl: string | null;
  };

  /**
   * Profile information section data.
   */
  readonly information: {
    readonly description: string | null;
    readonly email: string | null;
  };

  /**
   * Structured list of social platform links with non-null values.
   */
  readonly socialLinks: readonly ENSAdminSocialLink[];

  /**
   * Structured list of blockchain addresses with non-null values.
   */
  readonly addresses: readonly ENSAdminAddressRecord[];

  /**
   * Additional text records not displayed elsewhere, with non-null values.
   */
  readonly additionalTextRecords: readonly ENSAdminAdditionalTextRecord[];
};

/**
 * Text record keys that are displayed in specialized UI sections.
 * Used to filter out these keys from the additional records section.
 */
const DISPLAYED_TEXT_RECORD_KEYS = [
  "url",
  "avatar",
  "header",
  "description",
  "email",
  "name",
  ...ENSADMIN_SOCIAL_LINK_KEYS,
] as const;

/**
 * Parameters for the useProfile hook.
 */
export type UseProfileParameters = {
  /**
   * The ENS name to resolve profile data for.
   */
  name: Name;
};

/**
 * Return type for the useProfile hook, mirroring useRecords query result structure.
 */
export type UseProfileResult = {
  /**
   * The resolved ENS profile data, or undefined if loading or errored.
   */
  readonly data: ENSProfile | undefined;
  
  /**
   * The query status: "pending" | "error" | "success".
   */
  readonly status: "pending" | "error" | "success";
  
  /**
   * Whether the query is currently loading.
   */
  readonly isLoading: boolean;
  
  /**
   * Whether the query encountered an error.
   */
  readonly isError: boolean;
  
  /**
   * Whether the query succeeded.
   */
  readonly isSuccess: boolean;
  
  /**
   * The error object if the query failed, null otherwise.
   */
  readonly error: Error | null;
};

/**
 * Hook for fetching and transforming ENS profile data optimized for ENSAdmin.
 * 
 * Internally calls `useRecords` and transforms the raw response into a clean,
 * structured `ENSProfile` data model tailored for ENSAdmin's UI components.
 * 
 * @param parameters - Configuration specifying which name to resolve
 * @returns Query result containing the transformed ENSProfile data model
 * 
 * @example
 * ```typescript
 * import { useProfile } from "@/hooks/use-profile";
 * 
 * function ProfilePage() {
 *   const { data: profile, status } = useProfile({
 *     name: "vitalik.eth"
 *   });
 * 
 *   if (status === "pending") return <ProfileSkeleton />;
 *   if (status === "error") return <ErrorDisplay />;
 * 
 *   return (
 *     <>
 *       <ProfileHeader profile={profile} />
 *       <ProfileInformation profile={profile} />
 *       <SocialLinks profile={profile} />
 *       <Addresses profile={profile} />
 *       <AdditionalRecords profile={profile} />
 *     </>
 *   );
 * }
 * ```
 */
export function useProfile({ name }: UseProfileParameters): UseProfileResult {
  const activeNamespace = useActiveNamespace();

  const recordsSelection = {
    addresses: getCommonCoinTypes(activeNamespace),
    texts: [
      // Header section texts
      "url",
      "avatar",
      "header",
      // Profile information section texts
      "description",
      "email",
      // Social links
      ...ENSADMIN_SOCIAL_LINK_KEYS,
      // Additional known records
      // TODO: Extend to dynamically discover all text records set onchain
      // See: https://github.com/namehash/ensnode/issues/1083
      "status",
      "eth.ens.delegate",
    ],
  } as const satisfies ResolverRecordsSelection;

  const recordsQueryResult = useRecords({
    name,
    selection: recordsSelection,
  });

  const transformedProfile = useMemo<ENSProfile | undefined>(() => {
    if (!recordsQueryResult.data) {
      return undefined;
    }

    const recordsResponse = recordsQueryResult.data;

    // Extract and structure social links with non-null values
    const socialLinksWithValues = ENSADMIN_SOCIAL_LINK_KEYS
      .map((socialLinkKey) => ({
        key: socialLinkKey,
        value: recordsResponse.records.texts[socialLinkKey],
      }))
      .filter(
        (socialLink): socialLink is ENSAdminSocialLink =>
          socialLink.value !== null && socialLink.value !== undefined
      );

    // Extract and structure addresses with non-null values
    const addressesWithValues = Object.entries(recordsResponse.records.addresses)
      .map(([coinTypeString, addressValue]) => ({
        coinType: coinTypeString,
        address: addressValue,
      }))
      .filter(
        (addressRecord): addressRecord is ENSAdminAddressRecord =>
          addressRecord.address !== null && addressRecord.address !== undefined
      );

    // Extract additional text records not displayed elsewhere
    const additionalTextRecordsWithValues = Object.entries(recordsResponse.records.texts)
      .filter(([textKey]) => !DISPLAYED_TEXT_RECORD_KEYS.includes(textKey as any))
      .map(([textKey, textValue]) => ({
        key: textKey,
        value: textValue,
      }))
      .filter(
        (textRecord): textRecord is ENSAdminAdditionalTextRecord =>
          textRecord.value !== null && textRecord.value !== undefined
      );

    return {
      name,
      header: {
        avatarUrl: recordsResponse.records.texts.avatar ?? null,
        headerImageUrl: recordsResponse.records.texts.header ?? null,
        websiteUrl: recordsResponse.records.texts.url ?? null,
      },
      information: {
        description: recordsResponse.records.texts.description ?? null,
        email: recordsResponse.records.texts.email ?? null,
      },
      socialLinks: socialLinksWithValues,
      addresses: addressesWithValues,
      additionalTextRecords: additionalTextRecordsWithValues,
    };
  }, [recordsQueryResult.data, name]);

  return {
    data: transformedProfile,
    status: recordsQueryResult.status,
    isLoading: recordsQueryResult.isLoading,
    isError: recordsQueryResult.isError,
    isSuccess: recordsQueryResult.isSuccess,
    error: recordsQueryResult.error,
  };
}

For ensnode-react without the ENSAdmin context:

"use client";

import { useMemo } from "react";
import { useRecords } from "./useRecords";
import type { ConfigParameter, UseRecordsParameters } from "../types";
import type { 
  Name, 
  ResolverRecordsSelection 
} from "@ensnode/ensnode-sdk";

/**
 * Parameters for the useProfile hook.
 * 
 * @template SELECTION - The resolver records selection type
 */
export type UseProfileParameters<SELECTION extends ResolverRecordsSelection> = {
  /**
   * The ENS name to resolve profile data for.
   */
  name: Name;

  /**
   * The selection of records to fetch.
   */
  selection: SELECTION;

  /**
   * Optional configuration parameter.
   */
  config?: ConfigParameter["config"];

  /**
   * Optional TanStack Query options.
   */
  query?: UseRecordsParameters<SELECTION>["query"];
};

/**
 * Return type for the useProfile hook.
 * 
 * @template DATA - The transformed profile data type
 */
export type UseProfileResult<DATA> = {
  /**
   * The resolved profile data, or undefined if loading or errored.
   */
  readonly data: DATA | undefined;
  
  /**
   * The query status: "pending" | "error" | "success".
   */
  readonly status: "pending" | "error" | "success";
  
  /**
   * Whether the query is currently loading.
   */
  readonly isLoading: boolean;
  
  /**
   * Whether the query encountered an error.
   */
  readonly isError: boolean;
  
  /**
   * Whether the query succeeded.
   */
  readonly isSuccess: boolean;
  
  /**
   * The error object if the query failed, null otherwise.
   */
  readonly error: Error | null;
};

/**
 * Hook for fetching ENS records with custom transformation logic.
 * 
 * This hook wraps `useRecords` and allows applications to define their own
 * data transformation logic to convert raw resolver records into a custom
 * profile data model optimized for their specific use case.
 * 
 * @template SELECTION - The resolver records selection type
 * @template TRANSFORMED - The transformed profile data type
 * 
 * @param parameters - Configuration for fetching and transforming profile data
 * @param transformRecordsToProfile - Pure function to transform records into profile model
 * @returns Query result containing the transformed profile data
 * 
 * @example
 * ```typescript
 * import { useProfile } from "@ensnode/ensnode-react";
 * import type { ResolverRecordsSelection } from "@ensnode/ensnode-sdk";
 * 
 * const selection = {
 *   addresses: [60],
 *   texts: ["avatar", "description"],
 * } as const satisfies ResolverRecordsSelection;
 * 
 * type MyProfile = {
 *   name: string;
 *   avatar: string | null;
 *   description: string | null;
 *   ethAddress: string | null;
 * };
 * 
 * function MyComponent() {
 *   const { data: profile, status } = useProfile(
 *     {
 *       name: "vitalik.eth",
 *       selection,
 *     },
 *     (name, records) => ({
 *       name,
 *       avatar: records.records.texts.avatar,
 *       description: records.records.texts.description,
 *       ethAddress: records.records.addresses["60"],
 *     })
 *   );
 * 
 *   if (status === "pending") return <div>Loading...</div>;
 *   if (status === "error") return <div>Error</div>;
 * 
 *   return <div>{profile.description}</div>;
 * }
 * ```
 */
export function useProfile<
  SELECTION extends ResolverRecordsSelection,
  TRANSFORMED
>(
  parameters: UseProfileParameters<SELECTION>,
  transformRecordsToProfile: (
    name: Name,
    recordsResponse: NonNullable<ReturnType<typeof useRecords<SELECTION>>["data"]>
  ) => TRANSFORMED
): UseProfileResult<TRANSFORMED> {
  const { name, selection, config, query } = parameters;

  const recordsQueryResult = useRecords({
    name,
    selection,
    config,
    query,
  });

  const transformedProfileData = useMemo<TRANSFORMED | undefined>(() => {
    if (!recordsQueryResult.data) {
      return undefined;
    }

    return transformRecordsToProfile(name, recordsQueryResult.data);
  }, [recordsQueryResult.data, name, transformRecordsToProfile]);

  return {
    data: transformedProfileData,
    status: recordsQueryResult.status,
    isLoading: recordsQueryResult.isLoading,
    isError: recordsQueryResult.isError,
    isSuccess: recordsQueryResult.isSuccess,
    error: recordsQueryResult.error,
  };
}

There would be changes needed to ENSAdmin to make the above work. They look something like:

"use client";

import { useMemo } from "react";
import { useProfile } from "@ensnode/ensnode-react";
import type { 
  Name, 
  ResolverRecordsSelection 
} from "@ensnode/ensnode-sdk";
import { getCommonCoinTypes } from "@ensnode/ensnode-sdk";
import { useActiveNamespace } from "@/hooks/active/use-active-namespace";

/**
 * Strongly-typed social link identifiers supported by ENSAdmin profiles.
 */
export const ENSADMIN_SOCIAL_LINK_KEYS = [
  "com.twitter",
  "com.github",
  "com.farcaster",
  "org.telegram",
  "com.linkedin",
  "com.reddit",
] as const;

/**
 * A social link key recognized by ENSAdmin.
 */
export type ENSAdminSocialLinkKey = (typeof ENSADMIN_SOCIAL_LINK_KEYS)[number];

/**
 * A structured social link with its platform identifier and username/handle value.
 */
export type ENSAdminSocialLink = {
  readonly key: ENSAdminSocialLinkKey;
  readonly value: string;
};

/**
 * A structured address record with its coin type identifier and address value.
 */
export type ENSAdminAddressRecord = {
  readonly coinType: string;
  readonly address: string;
};

/**
 * A structured additional text record with its key and value.
 * Excludes records already displayed in header, profile, or social sections.
 */
export type ENSAdminAdditionalTextRecord = {
  readonly key: string;
  readonly value: string;
};

/**
 * The specialized ENS Profile data model optimized for ENSAdmin.
 * 
 * This model abstracts away the complexities of raw `useRecords` responses
 * and provides a clean, purpose-built structure for ENSAdmin's profile UI.
 * 
 * @example
 * ```typescript
 * const profile: ENSAdminProfile = {
 *   name: "vitalik.eth",
 *   header: {
 *     avatarUrl: "https://...",
 *     headerImageUrl: "https://...",
 *     websiteUrl: "https://vitalik.ca",
 *   },
 *   information: {
 *     description: "Ethereum co-founder",
 *     email: "v@ethereum.org",
 *   },
 *   socialLinks: [
 *     { key: "com.twitter", value: "VitalikButerin" },
 *   ],
 *   addresses: [
 *     { coinType: "60", address: "0x..." },
 *   ],
 *   additionalTextRecords: [
 *     { key: "status", value: "Building" },
 *   ],
 * };
 * ```
 */
export type ENSAdminProfile = {
  /**
   * The ENS name being displayed.
   */
  readonly name: Name;

  /**
   * Header section data including avatar, banner image, and website URL.
   */
  readonly header: {
    readonly avatarUrl: string | null;
    readonly headerImageUrl: string | null;
    readonly websiteUrl: string | null;
  };

  /**
   * Profile information section data.
   */
  readonly information: {
    readonly description: string | null;
    readonly email: string | null;
  };

  /**
   * Structured list of social platform links with non-null values.
   */
  readonly socialLinks: readonly ENSAdminSocialLink[];

  /**
   * Structured list of blockchain addresses with non-null values.
   */
  readonly addresses: readonly ENSAdminAddressRecord[];

  /**
   * Additional text records not displayed elsewhere, with non-null values.
   */
  readonly additionalTextRecords: readonly ENSAdminAdditionalTextRecord[];
};

/**
 * Text record keys that are displayed in specialized UI sections.
 * Used to filter out these keys from the additional records section.
 */
const DISPLAYED_TEXT_RECORD_KEYS = [
  "url",
  "avatar",
  "header",
  "description",
  "email",
  "name",
  ...ENSADMIN_SOCIAL_LINK_KEYS,
] as const;

/**
 * Parameters for the useENSAdminProfile hook.
 */
export type UseENSAdminProfileParameters = {
  /**
   * The ENS name to resolve profile data for.
   */
  name: Name;
};

/**
 * Hook for fetching and transforming ENS profile data optimized for ENSAdmin.
 * 
 * Internally calls `useProfile` with ENSAdmin-specific record selection and
 * transformation logic to produce a clean, structured `ENSAdminProfile` data
 * model tailored for ENSAdmin's UI components.
 * 
 * @param parameters - Configuration specifying which name to resolve
 * @returns Query result containing the transformed ENSAdminProfile data model
 * 
 * @example
 * ```typescript
 * import { useENSAdminProfile } from "@/hooks/use-ensadmin-profile";
 * 
 * function ProfilePage() {
 *   const { data: profile, status } = useENSAdminProfile({
 *     name: "vitalik.eth"
 *   });
 * 
 *   if (status === "pending") return <ProfileSkeleton />;
 *   if (status === "error") return <ErrorDisplay />;
 * 
 *   return (
 *     <>
 *       <ProfileHeader profile={profile} />
 *       <ProfileInformation profile={profile} />
 *       <SocialLinks profile={profile} />
 *       <Addresses profile={profile} />
 *       <AdditionalRecords profile={profile} />
 *     </>
 *   );
 * }
 * ```
 */
export function useENSAdminProfile({ name }: UseENSAdminProfileParameters) {
  const activeNamespace = useActiveNamespace();

  const recordsSelection = useMemo(
    () =>
      ({
        addresses: getCommonCoinTypes(activeNamespace),
        texts: [
          // Header section texts
          "url",
          "avatar",
          "header",
          // Profile information section texts
          "description",
          "email",
          // Social links
          ...ENSADMIN_SOCIAL_LINK_KEYS,
          // Additional known records
          // TODO: Extend to dynamically discover all text records set onchain
          // See: https://github.com/namehash/ensnode/issues/1083
          "status",
          "eth.ens.delegate",
        ],
      }) as const satisfies ResolverRecordsSelection,
    [activeNamespace]
  );

  const transformRecordsToENSAdminProfile = useMemo(
    () => (profileName: Name, recordsResponse: any): ENSAdminProfile => {
      // Extract and structure social links with non-null values
      const socialLinksWithValues = ENSADMIN_SOCIAL_LINK_KEYS.map((socialLinkKey) => ({
        key: socialLinkKey,
        value: recordsResponse.records.texts[socialLinkKey],
      })).filter(
        (socialLink): socialLink is ENSAdminSocialLink =>
          socialLink.value !== null && socialLink.value !== undefined
      );

      // Extract and structure addresses with non-null values
      const addressesWithValues = Object.entries(recordsResponse.records.addresses)
        .map(([coinTypeString, addressValue]) => ({
          coinType: coinTypeString,
          address: addressValue as string,
        }))
        .filter(
          (addressRecord): addressRecord is ENSAdminAddressRecord =>
            addressRecord.address !== null && addressRecord.address !== undefined
        );

      // Extract additional text records not displayed elsewhere
      const additionalTextRecordsWithValues = Object.entries(recordsResponse.records.texts)
        .filter(([textKey]) => !DISPLAYED_TEXT_RECORD_KEYS.includes(textKey as any))
        .map(([textKey, textValue]) => ({
          key: textKey,
          value: textValue as string,
        }))
        .filter(
          (textRecord): textRecord is ENSAdminAdditionalTextRecord =>
            textRecord.value !== null && textRecord.value !== undefined
        );

      return {
        name: profileName,
        header: {
          avatarUrl: recordsResponse.records.texts.avatar ?? null,
          headerImageUrl: recordsResponse.records.texts.header ?? null,
          websiteUrl: recordsResponse.records.texts.url ?? null,
        },
        information: {
          description: recordsResponse.records.texts.description ?? null,
          email: recordsResponse.records.texts.email ?? null,
        },
        socialLinks: socialLinksWithValues,
        addresses: addressesWithValues,
        additionalTextRecords: additionalTextRecordsWithValues,
      };
    },
    []
  );

  return useProfile(
    {
      name,
      selection: recordsSelection,
    },
    transformRecordsToENSAdminProfile
  );
}