@ensnode/ensnode-react 0.36.0 → 1.0.1

package/dist/index.d.ts

@@ -1,15 +1,15 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { QueryObserverOptions, QueryClient } from '@tanstack/react-query';
+import { QueryObserverOptions, DefaultError, QueryKey, DefinedInitialDataOptions, QueryClient, DefinedUseQueryResult, UndefinedInitialDataOptions, UseQueryResult, UseQueryOptions } from '@tanstack/react-query';
 export { QueryClient } from '@tanstack/react-query';
 import * as _ensnode_ensnode_sdk from '@ensnode/ensnode-sdk';
-import { ClientOptions, ResolverRecordsSelection, ResolveRecordsRequest, ResolveRecordsResponse, ResolvePrimaryNameRequest, ResolvePrimaryNameResponse, ResolvePrimaryNamesRequest, ResolvePrimaryNamesResponse, ConfigResponse, IndexingStatusRequest, IndexingStatusResponse, UnresolvedIdentity, ENSNamespaceId, Identity } from '@ensnode/ensnode-sdk';
+import { ClientOptions, ResolvePrimaryNameRequest, ResolvePrimaryNameResponse, ResolvePrimaryNamesRequest, ResolvePrimaryNamesResponse, ResolverRecordsSelection, ResolveRecordsRequest, ResolveRecordsResponse, ConfigResponse, IndexingStatusRequest, IndexingStatusResponse, RegistrarActionsRequest, RegistrarActionsResponse, UnresolvedIdentity, ENSNamespaceId, Identity } from '@ensnode/ensnode-sdk';
 export { ResolverRecordsSelection } from '@ensnode/ensnode-sdk';
 import * as react from 'react';
 
 /**
  * Configuration options for the ENSNode provider
  */
-interface ENSNodeConfig {
+interface ENSNodeSDKConfig {
     /** The ENSNode API client configuration */
     client: ClientOptions;
 }
@@ -22,7 +22,7 @@ interface QueryParameter<TData = unknown, TError = Error> {
 /**
  * Configuration parameter for hooks that need access to config
  */
-interface ConfigParameter<TConfig extends ENSNodeConfig = ENSNodeConfig> {
+interface WithSDKConfigParameter<TConfig extends ENSNodeSDKConfig = ENSNodeSDKConfig> {
     config?: TConfig | undefined;
 }
 /**
@@ -50,88 +50,26 @@ interface UsePrimaryNamesParameters extends Omit<ResolvePrimaryNamesRequest, "ad
     address: ResolvePrimaryNamesRequest["address"] | null;
 }
 
-interface ENSNodeProviderProps {
-    /** ENSNode configuration */
-    config: ENSNodeConfig;
-    /**
-     * Optional QueryClient instance. If provided, you must wrap your app with QueryClientProvider yourself.
-     * If not provided, ENSNodeProvider will create and manage its own QueryClient internally.
-     */
-    queryClient?: QueryClient;
-    /**
-     * Custom query client options when auto-creating a QueryClient.
-     * Only used when queryClient is not provided.
-     */
-    queryClientOptions?: ConstructorParameters<typeof QueryClient>[0];
-}
-declare function ENSNodeProvider(parameters: React.PropsWithChildren<ENSNodeProviderProps>): react.FunctionComponentElement<{
-    children: React.ReactNode;
-    config: ENSNodeConfig;
-}> | react.FunctionComponentElement<_tanstack_react_query.QueryClientProviderProps>;
-/**
- * Helper function to create ENSNode configuration
- */
-declare function createConfig(options?: {
-    url?: string | URL;
-}): ENSNodeConfig;
-
 /**
  * React context for ENSNode configuration
  */
-declare const ENSNodeContext: react.Context<ENSNodeConfig | undefined>;
+declare const ENSNodeContext: react.Context<ENSNodeSDKConfig | undefined>;
+
+type UseENSNodeConfigParameters = QueryParameter<ConfigResponse>;
+declare function useENSNodeConfig(parameters?: WithSDKConfigParameter & UseENSNodeConfigParameters): _tanstack_react_query.UseQueryResult<_ensnode_ensnode_sdk.ENSApiPublicConfig, Error>;
 
 /**
- * Hook to access the ENSNode configuration from context or parameters
+ * Hook to access the ENSNodeSDKConfig from context or parameters.
  *
  * @param parameters - Optional config parameter that overrides context
  * @returns The ENSNode configuration
  * @throws Error if no config is available in context or parameters
  */
-declare function useENSNodeConfig<TConfig extends ENSNodeConfig = ENSNodeConfig>(config: TConfig | undefined): TConfig;
+declare function useENSNodeSDKConfig<TConfig extends ENSNodeSDKConfig = ENSNodeSDKConfig>(config: TConfig | undefined): TConfig;
 
-/**
- * Resolves records for an ENS name (Forward Resolution).
- *
- * The returned `name` field, if set, is guaranteed to be a normalized name.
- * If the name record returned by the resolver is not normalized, `null` is returned as if no name record was set.
- *
- * @param parameters - Configuration for the ENS name resolution
- * @returns Query result with resolved records
- *
- * @example
- * ```typescript
- * import { useRecords } from "@ensnode/ensnode-react";
- *
- * function DisplayNameRecords() {
- *   const { data, isLoading, error } = useRecords({
- *     name: "jesse.base.eth",
- *     selection: {
- *       addresses: [60], // ETH CoinType
- *       texts: ["avatar", "com.twitter"]
- *     }
- *   });
- *
- *   if (isLoading) return <div>Loading...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *
- *   return (
- *     <div>
- *       <h3>Resolved Records for vitalik.eth</h3>
- *       {data.records.addresses && (
- *         <p>ETH Address: {data.records.addresses[60]}</p>
- *       )}
- *       {data.records.texts && (
- *         <div>
- *           <p>Avatar: {data.records.texts.avatar}</p>
- *           <p>Twitter: {data.records.texts["com.twitter"]}</p>
- *         </div>
- *       )}
- *     </div>
- *   );
- * }
- * ```
- */
-declare function useRecords<SELECTION extends ResolverRecordsSelection>(parameters: UseRecordsParameters<SELECTION> & ConfigParameter): _tanstack_react_query.UseQueryResult<_ensnode_ensnode_sdk.ResolveRecordsResponse<SELECTION>, Error>;
+interface UseIndexingStatusParameters extends IndexingStatusRequest, QueryParameter<IndexingStatusResponse> {
+}
+declare function useIndexingStatus(parameters?: WithSDKConfigParameter & UseIndexingStatusParameters): _tanstack_react_query.UseQueryResult<IndexingStatusResponse, Error>;
 
 /**
  * Resolves the primary name of a specified address (Reverse Resolution).
@@ -150,6 +88,7 @@ declare function useRecords<SELECTION extends ResolverRecordsSelection>(paramete
  *   const { data, isLoading, error } = usePrimaryName({
  *     address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  *     chainId: 1, // Ethereum Mainnet
+ *     accelerate: true, // Attempt Protocol Acceleration
  *   });
  *
  *   if (isLoading) return <div>Loading...</div>;
@@ -164,7 +103,7 @@ declare function useRecords<SELECTION extends ResolverRecordsSelection>(paramete
  * }
  * ```
  */
-declare function usePrimaryName(parameters: UsePrimaryNameParameters & ConfigParameter): _tanstack_react_query.UseQueryResult<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse, Error>;
+declare function usePrimaryName(parameters: UsePrimaryNameParameters & WithSDKConfigParameter): _tanstack_react_query.UseQueryResult<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse, Error>;
 
 /**
  * Resolves the primary names of a specified address across multiple chains.
@@ -200,14 +139,60 @@ declare function usePrimaryName(parameters: UsePrimaryNameParameters & ConfigPar
  * }
  * ```
  */
-declare function usePrimaryNames(parameters: UsePrimaryNamesParameters & ConfigParameter): _tanstack_react_query.UseQueryResult<_ensnode_ensnode_sdk.ResolvePrimaryNamesResponse, Error>;
+declare function usePrimaryNames(parameters: UsePrimaryNamesParameters & WithSDKConfigParameter): _tanstack_react_query.UseQueryResult<_ensnode_ensnode_sdk.ResolvePrimaryNamesResponse, Error>;
 
-type UseENSIndexerConfigParameters = QueryParameter<ConfigResponse>;
-declare function useENSIndexerConfig(parameters?: ConfigParameter & UseENSIndexerConfigParameters): _tanstack_react_query.UseQueryResult<_ensnode_ensnode_sdk.ENSIndexerPublicConfig, Error>;
+/**
+ * Resolves records for an ENS name (Forward Resolution).
+ *
+ * The returned `name` field, if set, is guaranteed to be a normalized name.
+ * If the name record returned by the resolver is not normalized, `null` is returned as if no name record was set.
+ *
+ * @param parameters - Configuration for the ENS name resolution
+ * @returns Query result with resolved records
+ *
+ * @example
+ * ```typescript
+ * import { useRecords } from "@ensnode/ensnode-react";
+ *
+ * function DisplayNameRecords() {
+ *   const { data, isLoading, error } = useRecords({
+ *     name: "jesse.base.eth",
+ *     selection: {
+ *       addresses: [60], // ETH CoinType
+ *       texts: ["avatar", "com.twitter"]
+ *     }
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h3>Resolved Records for vitalik.eth</h3>
+ *       {data.records.addresses && (
+ *         <p>ETH Address: {data.records.addresses[60]}</p>
+ *       )}
+ *       {data.records.texts && (
+ *         <div>
+ *           <p>Avatar: {data.records.texts.avatar}</p>
+ *           <p>Twitter: {data.records.texts["com.twitter"]}</p>
+ *         </div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useRecords<SELECTION extends ResolverRecordsSelection>(parameters: UseRecordsParameters<SELECTION> & WithSDKConfigParameter): _tanstack_react_query.UseQueryResult<_ensnode_ensnode_sdk.ResolveRecordsResponse<SELECTION>, Error>;
 
-interface UseIndexingStatusParameters extends IndexingStatusRequest, QueryParameter<IndexingStatusResponse> {
+interface UseRegistrarActionsParameters extends RegistrarActionsRequest, QueryParameter<RegistrarActionsResponse> {
 }
-declare function useIndexingStatus(parameters?: ConfigParameter & UseIndexingStatusParameters): _tanstack_react_query.UseQueryResult<IndexingStatusResponse, Error>;
+/**
+ * Use Registrar Actions hook
+ *
+ * Query ENSNode Registrar Actions API.
+ */
+declare function useRegistrarActions(parameters?: WithSDKConfigParameter & UseRegistrarActionsParameters): _tanstack_react_query.UseQueryResult<RegistrarActionsResponse, Error>;
 
 /**
  * Parameters for the useResolvedIdentity hook.
@@ -215,6 +200,7 @@ declare function useIndexingStatus(parameters?: ConfigParameter & UseIndexingSta
 interface UseResolvedIdentityParameters {
     identity: UnresolvedIdentity;
     namespaceId: ENSNamespaceId;
+    accelerate?: boolean;
 }
 /**
  * Hook to perform ENSIP-19 primary name resolution to resolve an
@@ -226,6 +212,8 @@ interface UseResolvedIdentityParameters {
  * @param parameters.namespaceId - The {@link ENSNamespaceId} that `identity.chainId` should be interpreted
  *                                 through (via {@link getResolvePrimaryNameChainIdParam}) to determine the literal
  *                                 chainId that should be used for ENSIP-19 primary name resolution.
+ * @param parameters.accelerate - Whether to attempt Protocol Acceleration (default: false)
+ *                                when resolving the primary name.
  *
  * @returns An object containing:
  * - `identity`: An {@link Identity} with one of four possible {@link ResolutionStatusIds}:
@@ -257,6 +245,7 @@ declare function useResolvedIdentity(parameters: UseResolvedIdentityParameters):
     isPaused: boolean;
     isRefetching: boolean;
     isStale: boolean;
+    isEnabled: boolean;
     refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
     promise: Promise<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse>;
@@ -282,6 +271,7 @@ declare function useResolvedIdentity(parameters: UseResolvedIdentityParameters):
     isPaused: boolean;
     isRefetching: boolean;
     isStale: boolean;
+    isEnabled: boolean;
     refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
     promise: Promise<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse>;
@@ -307,6 +297,7 @@ declare function useResolvedIdentity(parameters: UseResolvedIdentityParameters):
     isPaused: boolean;
     isRefetching: boolean;
     isStale: boolean;
+    isEnabled: boolean;
     refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
     promise: Promise<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse>;
@@ -332,6 +323,7 @@ declare function useResolvedIdentity(parameters: UseResolvedIdentityParameters):
     isPaused: boolean;
     isRefetching: boolean;
     isStale: boolean;
+    isEnabled: boolean;
     refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
     promise: Promise<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse>;
@@ -357,6 +349,7 @@ declare function useResolvedIdentity(parameters: UseResolvedIdentityParameters):
     isPaused: boolean;
     isRefetching: boolean;
     isStale: boolean;
+    isEnabled: boolean;
     refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
     promise: Promise<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse>;
@@ -382,11 +375,82 @@ declare function useResolvedIdentity(parameters: UseResolvedIdentityParameters):
     isPaused: boolean;
     isRefetching: boolean;
     isStale: boolean;
+    isEnabled: boolean;
     refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
     promise: Promise<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse>;
 };
 
+/**
+ * Use Stale-While-Revalidate Query
+ *
+ * This hooks is a proxy for {@link useQuery} with addition of the following
+ * semantics:
+ * - if the query has been resolved successfully just once,
+ *   the query result will always be success with data being the previously
+ *   cached result,
+ * - the cached result can never go stale, or be garbage collected
+ * - the cached result can be only overridden by the current result when
+ *   the query is successfully re-fetched (in other words,
+ *   the `options.queryFn` returns a resolved promise).
+ *
+ * Please note how there can be any number of failed queries before one
+ * succeeds. In such case, no successful result has ever been cached and
+ * the query fails (`isError: true`, `error` is available) until
+ * the first successful resolution (`isSuccess: true`, `data` is available).
+ *
+ * @example
+ * ```tsx
+ * const swrQuery = useSwrQuery({
+ *   queryKey: ['data'],
+ *   queryFn: fetchData,
+ * });
+ *
+ * if (swrQuery.isPending) {
+ *   // Show loading state while there's no cached successful result and
+ *   // no query attempt was finished yet.
+ *   return <>Loading...</>;
+ * }
+ *
+ * if (swrQuery.isError) {
+ *   // Show error state when query attempt fails and
+ *   // no cached successful result is available.
+ *   return <>Error: {swrQuery.error.message}</>;
+ * }
+ *
+ * // Otherwise, show data when the cached successful result is available.
+ * return <>Data: {JSON.stringify(swrQuery.data)}</>;
+ * ```
+ */
+declare function useSwrQuery<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): DefinedUseQueryResult<NoInfer<TData>, TError>;
+declare function useSwrQuery<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryResult<NoInfer<TData>, TError>;
+declare function useSwrQuery<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseQueryResult<NoInfer<TData>, TError>;
+
+interface ENSNodeProviderProps {
+    /** ENSNode configuration */
+    config: ENSNodeSDKConfig;
+    /**
+     * Optional QueryClient instance. If provided, you must wrap your app with QueryClientProvider yourself.
+     * If not provided, ENSNodeProvider will create and manage its own QueryClient internally.
+     */
+    queryClient?: QueryClient;
+    /**
+     * Custom query client options when auto-creating a QueryClient.
+     * Only used when queryClient is not provided.
+     */
+    queryClientOptions?: ConstructorParameters<typeof QueryClient>[0];
+}
+declare function ENSNodeProvider(parameters: React.PropsWithChildren<ENSNodeProviderProps>): react.FunctionComponentElement<{
+    children?: React.ReactNode;
+    config: ENSNodeSDKConfig;
+}> | react.FunctionComponentElement<_tanstack_react_query.QueryClientProviderProps>;
+/**
+ * Helper function to create ENSNode configuration
+ */
+declare function createConfig(options?: {
+    url?: string | URL;
+}): ENSNodeSDKConfig;
+
 /**
  * Immutable query options for data that is assumed to be immutable and should only be fetched once per full page refresh per unique key.
  * Similar to SWR's immutable: true API.
@@ -409,5 +473,66 @@ declare const ASSUME_IMMUTABLE_QUERY: {
     readonly refetchOnReconnect: false;
     readonly refetchOnMount: false;
 };
+/**
+ * Query keys for hooks. Simply keys by path and arguments.
+ */
+declare const queryKeys: {
+    base: (url: string) => readonly ["ensnode", string];
+    resolve: (url: string) => readonly ["ensnode", string, "resolve"];
+    records: (url: string, args: ResolveRecordsRequest<any>) => readonly ["ensnode", string, "resolve", "records", ResolveRecordsRequest<any>];
+    primaryName: (url: string, args: ResolvePrimaryNameRequest) => readonly ["ensnode", string, "resolve", "primary-name", ResolvePrimaryNameRequest];
+    primaryNames: (url: string, args: ResolvePrimaryNamesRequest) => readonly ["ensnode", string, "resolve", "primary-names", ResolvePrimaryNamesRequest];
+    config: (url: string) => readonly ["ensnode", string, "config"];
+    indexingStatus: (url: string) => readonly ["ensnode", string, "indexing-status"];
+    registrarActions: (url: string, args: RegistrarActionsRequest) => readonly ["ensnode", string, "registrar-actions", RegistrarActionsRequest];
+};
+/**
+ * Creates query options for Records Resolution
+ */
+declare function createRecordsQueryOptions<SELECTION extends ResolverRecordsSelection>(config: ENSNodeSDKConfig, args: ResolveRecordsRequest<SELECTION>): {
+    enabled: boolean;
+    queryKey: readonly ["ensnode", string, "resolve", "records", ResolveRecordsRequest<any>];
+    queryFn: () => Promise<_ensnode_ensnode_sdk.ResolveRecordsResponse<SELECTION>>;
+};
+/**
+ * Creates query options for Primary Name Resolution
+ */
+declare function createPrimaryNameQueryOptions(config: ENSNodeSDKConfig, args: ResolvePrimaryNameRequest): {
+    enabled: boolean;
+    queryKey: readonly ["ensnode", string, "resolve", "primary-name", ResolvePrimaryNameRequest];
+    queryFn: () => Promise<_ensnode_ensnode_sdk.ResolvePrimaryNameResponse>;
+};
+/**
+ * Creates query options for Primary Name Resolution
+ */
+declare function createPrimaryNamesQueryOptions(config: ENSNodeSDKConfig, args: ResolvePrimaryNamesRequest): {
+    enabled: boolean;
+    queryKey: readonly ["ensnode", string, "resolve", "primary-names", ResolvePrimaryNamesRequest];
+    queryFn: () => Promise<_ensnode_ensnode_sdk.ResolvePrimaryNamesResponse>;
+};
+/**
+ * Creates query options for ENSNode Config API
+ */
+declare function createConfigQueryOptions(config: ENSNodeSDKConfig): {
+    enabled: boolean;
+    queryKey: readonly ["ensnode", string, "config"];
+    queryFn: () => Promise<_ensnode_ensnode_sdk.ENSApiPublicConfig>;
+};
+/**
+ * Creates query options for ENSNode Indexing Status API
+ */
+declare function createIndexingStatusQueryOptions(config: ENSNodeSDKConfig): {
+    enabled: boolean;
+    queryKey: readonly ["ensnode", string, "indexing-status"];
+    queryFn: () => Promise<_ensnode_ensnode_sdk.IndexingStatusResponse>;
+};
+/**
+ * Creates query options for ENSNode Registrar Actions API
+ */
+declare function createRegistrarActionsQueryOptions(config: ENSNodeSDKConfig, args: RegistrarActionsRequest): {
+    enabled: boolean;
+    queryKey: readonly ["ensnode", string, "registrar-actions", RegistrarActionsRequest];
+    queryFn: () => Promise<_ensnode_ensnode_sdk.RegistrarActionsResponse>;
+};
 
-export { ASSUME_IMMUTABLE_QUERY, type ConfigParameter, type ENSNodeConfig, ENSNodeContext, ENSNodeProvider, type ENSNodeProviderProps, type QueryParameter, type UsePrimaryNameParameters, type UsePrimaryNamesParameters, type UseRecordsParameters, type UseResolvedIdentityParameters, createConfig, useENSIndexerConfig, useENSNodeConfig, useIndexingStatus, usePrimaryName, usePrimaryNames, useRecords, useResolvedIdentity };
+export { ASSUME_IMMUTABLE_QUERY, ENSNodeContext, ENSNodeProvider, type ENSNodeProviderProps, type ENSNodeSDKConfig, type QueryParameter, type UsePrimaryNameParameters, type UsePrimaryNamesParameters, type UseRecordsParameters, type UseResolvedIdentityParameters, type WithSDKConfigParameter, createConfig, createConfigQueryOptions, createIndexingStatusQueryOptions, createPrimaryNameQueryOptions, createPrimaryNamesQueryOptions, createRecordsQueryOptions, createRegistrarActionsQueryOptions, queryKeys, useENSNodeConfig, useENSNodeSDKConfig, useIndexingStatus, usePrimaryName, usePrimaryNames, useRecords, useRegistrarActions, useResolvedIdentity, useSwrQuery };