web3bio-profile-kit 0.1.2 → 0.1.4

package/README.md

@@ -41,7 +41,7 @@ VITE_WEB3BIO_API_KEY=your_api_key
 #### Platform-Specific Profile Queries
 
 ```jsx
-import { useProfile } from 'web3bio-profile-kit';
+import { useProfile } from "web3bio-profile-kit";
 
 function ProfileComponent() {
   // Query with explicit platform format
@@ -69,7 +69,7 @@ function ProfileComponent() {
 #### Universal Profile Queries
 
 ```jsx
-import { useUniversalProfile } from 'web3bio-profile-kit';
+import { useUniversalProfile } from "web3bio-profile-kit";
 
 function UniversalProfileComponent() {
   // Query by any identity format - ENS domain, Farcaster handle, etc.
@@ -97,7 +97,7 @@ function UniversalProfileComponent() {
 #### Platform-Specific Name Service Queries
 
 ```jsx
-import { useNS } from 'web3bio-profile-kit';
+import { useNS } from "web3bio-profile-kit";
 
 function NameServiceComponent() {
   const { data, isLoading } = useNS("ens,vitalik.eth");
@@ -116,7 +116,7 @@ function NameServiceComponent() {
 #### Universal Name Service Queries
 
 ```jsx
-import { useUniversalNS } from 'web3bio-profile-kit';
+import { useUniversalNS } from "web3bio-profile-kit";
 
 function UniversalNameServiceComponent() {
   // Works with any identity format
@@ -136,7 +136,7 @@ function UniversalNameServiceComponent() {
 ### Query Domain Data
 
 ```jsx
-import { useDomain } from 'web3bio-profile-kit';
+import { useDomain } from "web3bio-profile-kit";
 
 function DomainComponent() {
   const { data, isLoading } = useDomain("vitalik.eth");
@@ -156,7 +156,7 @@ function DomainComponent() {
 ### Batch Profile Query
 
 ```jsx
-import { useBatchProfile } from 'web3bio-profile-kit';
+import { useBatchProfile } from "web3bio-profile-kit";
 
 function BatchProfileComponent() {
   const { data, isLoading } = useBatchProfile([
@@ -234,6 +234,14 @@ Fetches basic universal name service data across multiple platforms.
 
 Fetches detailed domain information including resolution data.
 
+#### `useBatchProfile(identity, options?)`
+
+Fetches comprehensive profile data for multiple identities in a single request.
+
+#### `useBatchNS(identity, options?)`
+
+Fetches basic name service data for multiple identities in a single request.
+
 ### Arguments
 
 | Parameter | Type | Description |

package/dist/hooks/index.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+var useProfile = require('./useProfile.cjs');
+var useNS = require('./useNS.cjs');
+var useUniversalProfile = require('./useUniversalProfile.cjs');
+var useUniversalNS = require('./useUniversalNS.cjs');
+var useBatchProfile = require('./useBatchProfile.cjs');
+var useBatchNS = require('./useBatchNS.cjs');
+var useDomain = require('./useDomain.cjs');
+var useBaseQuery = require('./useBaseQuery.cjs');
+
+
+
+exports.useProfile = useProfile.useProfile;
+exports.useNS = useNS.useNS;
+exports.useUniversalProfile = useUniversalProfile.useUniversalProfile;
+exports.useUniversalNS = useUniversalNS.useUniversalNS;
+exports.useBatchProfile = useBatchProfile.useBatchProfile;
+exports.useBatchNS = useBatchNS.useBatchNS;
+exports.useDomain = useDomain.useDomain;
+exports.useBaseQuery = useBaseQuery.useBaseQuery;

package/dist/hooks/index.js

@@ -0,0 +1,8 @@
+export { useProfile } from './useProfile.js';
+export { useNS } from './useNS.js';
+export { useUniversalProfile } from './useUniversalProfile.js';
+export { useUniversalNS } from './useUniversalNS.js';
+export { useBatchProfile } from './useBatchProfile.js';
+export { useBatchNS } from './useBatchNS.js';
+export { useDomain } from './useDomain.js';
+export { useBaseQuery } from './useBaseQuery.js';

package/dist/hooks/useBaseQuery.cjs

@@ -0,0 +1,129 @@
+'use strict';
+
+require('../types/platform.cjs');
+require('../types/network.cjs');
+var hook = require('../types/hook.cjs');
+require('../types/source.cjs');
+require('../types/cointype.cjs');
+var react = require('react');
+var helpers = require('../utils/helpers.cjs');
+require('../utils/network.cjs');
+require('../utils/platform.cjs');
+require('../utils/source.cjs');
+
+/**
+ * Constructs the API URL based on query parameters
+ */
+const buildApiUrl = (identity, endpoint, universal) => {
+    // Handle batch requests
+    if (Array.isArray(identity)) {
+        return `${helpers.API_ENDPOINT}/${endpoint}/batch/${encodeURIComponent(JSON.stringify(identity))}`;
+    }
+    // Handle universal queries
+    if (universal) {
+        return `${helpers.API_ENDPOINT}/${endpoint}/${identity}`;
+    }
+    // Handle platform-specific queries
+    const resolvedId = helpers.resolveIdentity(identity);
+    if (!resolvedId)
+        return null;
+    // Domain endpoint uses resolved ID directly
+    if (endpoint === hook.QueryEndpoint.DOMAIN) {
+        return `${helpers.API_ENDPOINT}/${endpoint}/${resolvedId}`;
+    }
+    // Other endpoints need platform/handle split
+    const [platform, handle] = resolvedId.split(",");
+    return `${helpers.API_ENDPOINT}/${endpoint}/${platform}/${handle}`;
+};
+// Generate a stable cache key for this request
+const getCacheKey = (identity, endpoint, universal) => {
+    return JSON.stringify({
+        identity,
+        endpoint,
+        universal,
+    });
+};
+// Create a cache to store results across component instances and re-renders
+const globalRequestCache = new Map();
+/**
+ * Core hook for querying Web3.bio Profile API
+ */
+function useBaseQuery(identity, endpoint, universal = false, options = {}) {
+    const { apiKey: userApiKey, enabled = true } = options;
+    const apiKey = helpers.getApiKey(userApiKey);
+    const [data, setData] = react.useState(() => {
+        // Initialize state from cache if available
+        const cacheKey = getCacheKey(identity, endpoint, universal);
+        return globalRequestCache.get(cacheKey) || null;
+    });
+    const [isLoading, setIsLoading] = react.useState(false);
+    const [error, setError] = react.useState(null);
+    // Use ref to track in-flight requests and prevent race conditions
+    const requestIdRef = react.useRef(0);
+    const prevParamsRef = react.useRef("");
+    // Current request parameters as a string for comparison
+    const currentParams = JSON.stringify({
+        identity,
+        endpoint,
+        universal,
+    });
+    react.useEffect(() => {
+        // Don't run the query if disabled or no identity
+        if (!enabled || !identity)
+            return;
+        // Skip if parameters haven't changed
+        if (currentParams === prevParamsRef.current && data !== null) {
+            return;
+        }
+        // Update previous parameters
+        prevParamsRef.current = currentParams;
+        // Generate cache key
+        const cacheKey = getCacheKey(identity, endpoint, universal);
+        // Check if we already have cached data
+        const cachedData = globalRequestCache.get(cacheKey);
+        if (cachedData) {
+            setData(cachedData);
+            return;
+        }
+        // Increment request ID to track the latest request
+        const requestId = ++requestIdRef.current;
+        setIsLoading(true);
+        setError(null);
+        const fetchData = async () => {
+            try {
+                const url = buildApiUrl(identity, endpoint, universal);
+                if (!url) {
+                    throw new Error(hook.ErrorMessages.INVALID_IDENTITY);
+                }
+                const headers = apiKey ? { "x-api-key": apiKey } : {};
+                const fetchOptions = {
+                    method: "GET",
+                    headers,
+                };
+                const response = await fetch(url, fetchOptions);
+                if (!response.ok) {
+                    throw new Error(`API error: ${response.status}`);
+                }
+                const responseData = await response.json();
+                if (responseData === null || responseData === void 0 ? void 0 : responseData.error) {
+                    throw new Error(responseData.error);
+                }
+                if (requestId === requestIdRef.current) {
+                    globalRequestCache.set(cacheKey, responseData);
+                    setData(responseData);
+                    setIsLoading(false);
+                }
+            }
+            catch (err) {
+                if (requestId === requestIdRef.current) {
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                    setIsLoading(false);
+                }
+            }
+        };
+        fetchData();
+    }, [currentParams, enabled]);
+    return { data, isLoading, error };
+}
+
+exports.useBaseQuery = useBaseQuery;

package/dist/{types/hooks → hooks}/useBaseQuery.d.ts

@@ -1,5 +1,4 @@
-import type { IdentityString, QueryOptions, QueryResult } from "../utils/types";
-import { QueryEndpoint } from "../utils/constants";
+import { type IdentityString, type QueryOptions, type QueryResult, QueryEndpoint } from "../types";
 /**
  * Core hook for querying Web3.bio Profile API
  */

package/dist/hooks/useBaseQuery.js

@@ -0,0 +1,127 @@
+import '../types/platform.js';
+import '../types/network.js';
+import { ErrorMessages, QueryEndpoint } from '../types/hook.js';
+import '../types/source.js';
+import '../types/cointype.js';
+import { useState, useRef, useEffect } from 'react';
+import { getApiKey, API_ENDPOINT, resolveIdentity } from '../utils/helpers.js';
+import '../utils/network.js';
+import '../utils/platform.js';
+import '../utils/source.js';
+
+/**
+ * Constructs the API URL based on query parameters
+ */
+const buildApiUrl = (identity, endpoint, universal) => {
+    // Handle batch requests
+    if (Array.isArray(identity)) {
+        return `${API_ENDPOINT}/${endpoint}/batch/${encodeURIComponent(JSON.stringify(identity))}`;
+    }
+    // Handle universal queries
+    if (universal) {
+        return `${API_ENDPOINT}/${endpoint}/${identity}`;
+    }
+    // Handle platform-specific queries
+    const resolvedId = resolveIdentity(identity);
+    if (!resolvedId)
+        return null;
+    // Domain endpoint uses resolved ID directly
+    if (endpoint === QueryEndpoint.DOMAIN) {
+        return `${API_ENDPOINT}/${endpoint}/${resolvedId}`;
+    }
+    // Other endpoints need platform/handle split
+    const [platform, handle] = resolvedId.split(",");
+    return `${API_ENDPOINT}/${endpoint}/${platform}/${handle}`;
+};
+// Generate a stable cache key for this request
+const getCacheKey = (identity, endpoint, universal) => {
+    return JSON.stringify({
+        identity,
+        endpoint,
+        universal,
+    });
+};
+// Create a cache to store results across component instances and re-renders
+const globalRequestCache = new Map();
+/**
+ * Core hook for querying Web3.bio Profile API
+ */
+function useBaseQuery(identity, endpoint, universal = false, options = {}) {
+    const { apiKey: userApiKey, enabled = true } = options;
+    const apiKey = getApiKey(userApiKey);
+    const [data, setData] = useState(() => {
+        // Initialize state from cache if available
+        const cacheKey = getCacheKey(identity, endpoint, universal);
+        return globalRequestCache.get(cacheKey) || null;
+    });
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // Use ref to track in-flight requests and prevent race conditions
+    const requestIdRef = useRef(0);
+    const prevParamsRef = useRef("");
+    // Current request parameters as a string for comparison
+    const currentParams = JSON.stringify({
+        identity,
+        endpoint,
+        universal,
+    });
+    useEffect(() => {
+        // Don't run the query if disabled or no identity
+        if (!enabled || !identity)
+            return;
+        // Skip if parameters haven't changed
+        if (currentParams === prevParamsRef.current && data !== null) {
+            return;
+        }
+        // Update previous parameters
+        prevParamsRef.current = currentParams;
+        // Generate cache key
+        const cacheKey = getCacheKey(identity, endpoint, universal);
+        // Check if we already have cached data
+        const cachedData = globalRequestCache.get(cacheKey);
+        if (cachedData) {
+            setData(cachedData);
+            return;
+        }
+        // Increment request ID to track the latest request
+        const requestId = ++requestIdRef.current;
+        setIsLoading(true);
+        setError(null);
+        const fetchData = async () => {
+            try {
+                const url = buildApiUrl(identity, endpoint, universal);
+                if (!url) {
+                    throw new Error(ErrorMessages.INVALID_IDENTITY);
+                }
+                const headers = apiKey ? { "x-api-key": apiKey } : {};
+                const fetchOptions = {
+                    method: "GET",
+                    headers,
+                };
+                const response = await fetch(url, fetchOptions);
+                if (!response.ok) {
+                    throw new Error(`API error: ${response.status}`);
+                }
+                const responseData = await response.json();
+                if (responseData === null || responseData === void 0 ? void 0 : responseData.error) {
+                    throw new Error(responseData.error);
+                }
+                if (requestId === requestIdRef.current) {
+                    globalRequestCache.set(cacheKey, responseData);
+                    setData(responseData);
+                    setIsLoading(false);
+                }
+            }
+            catch (err) {
+                if (requestId === requestIdRef.current) {
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                    setIsLoading(false);
+                }
+            }
+        };
+        fetchData();
+    }, [currentParams, enabled]);
+    return { data, isLoading, error };
+}
+
+export { useBaseQuery };

package/dist/hooks/useBatchNS.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+require('../types/platform.cjs');
+require('../types/network.cjs');
+var hook = require('../types/hook.cjs');
+require('../types/source.cjs');
+require('../types/cointype.cjs');
+var useBaseQuery = require('./useBaseQuery.cjs');
+
+/**
+ * Hook to query Web3.bio profile data using batch(NS) identity lookup
+ *
+ * @param identity - array of Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing profile data, loading state, and any errors
+ *
+ * @example
+ * // Query by any identity type with batch lookup
+ * const { data } = useBatchNS(["dwr.farcaster","ens,vitalik.eth","sujiyan.eth","stani.lens"]);
+ */
+function useBatchNS(identity, options = {}) {
+    return useBaseQuery.useBaseQuery(identity, hook.QueryEndpoint.NS, false, options);
+}
+
+exports.useBatchNS = useBatchNS;

package/dist/{types/hooks → hooks}/useBatchNS.d.ts

@@ -1,4 +1,4 @@
-import type { IdentityString, NSBatchResult, QueryOptions } from "../utils/types";
+import { type IdentityString, type NSBatchResult, type QueryOptions } from "../types";
 /**
  * Hook to query Web3.bio profile data using batch(NS) identity lookup
  *

package/dist/hooks/useBatchNS.js

@@ -0,0 +1,23 @@
+import '../types/platform.js';
+import '../types/network.js';
+import { QueryEndpoint } from '../types/hook.js';
+import '../types/source.js';
+import '../types/cointype.js';
+import { useBaseQuery } from './useBaseQuery.js';
+
+/**
+ * Hook to query Web3.bio profile data using batch(NS) identity lookup
+ *
+ * @param identity - array of Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing profile data, loading state, and any errors
+ *
+ * @example
+ * // Query by any identity type with batch lookup
+ * const { data } = useBatchNS(["dwr.farcaster","ens,vitalik.eth","sujiyan.eth","stani.lens"]);
+ */
+function useBatchNS(identity, options = {}) {
+    return useBaseQuery(identity, QueryEndpoint.NS, false, options);
+}
+
+export { useBatchNS };

package/dist/hooks/useBatchProfile.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+require('../types/platform.cjs');
+require('../types/network.cjs');
+var hook = require('../types/hook.cjs');
+require('../types/source.cjs');
+require('../types/cointype.cjs');
+var useBaseQuery = require('./useBaseQuery.cjs');
+
+/**
+ * Hook to query Web3.bio profile data using batch identity lookup
+ *
+ * @param identity - array of Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing profile data, loading state, and any errors
+ *
+ * @example
+ * // Query by any identity type with batch lookup
+ * const { data } = useBatchProfile(["dwr.farcaster","ens,vitalik.eth","sujiyan.eth","stani.lens"]);
+ */
+function useBatchProfile(identity, options = {}) {
+    return useBaseQuery.useBaseQuery(identity, hook.QueryEndpoint.PROFILE, false, options);
+}
+
+exports.useBatchProfile = useBatchProfile;

package/dist/{types/hooks → hooks}/useBatchProfile.d.ts

@@ -1,4 +1,4 @@
-import type { IdentityString, ProfileBatchResult, QueryOptions } from "../utils/types";
+import { type IdentityString, type ProfileBatchResult, type QueryOptions } from "../types";
 /**
  * Hook to query Web3.bio profile data using batch identity lookup
  *

package/dist/hooks/useBatchProfile.js

@@ -0,0 +1,23 @@
+import '../types/platform.js';
+import '../types/network.js';
+import { QueryEndpoint } from '../types/hook.js';
+import '../types/source.js';
+import '../types/cointype.js';
+import { useBaseQuery } from './useBaseQuery.js';
+
+/**
+ * Hook to query Web3.bio profile data using batch identity lookup
+ *
+ * @param identity - array of Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing profile data, loading state, and any errors
+ *
+ * @example
+ * // Query by any identity type with batch lookup
+ * const { data } = useBatchProfile(["dwr.farcaster","ens,vitalik.eth","sujiyan.eth","stani.lens"]);
+ */
+function useBatchProfile(identity, options = {}) {
+    return useBaseQuery(identity, QueryEndpoint.PROFILE, false, options);
+}
+
+export { useBatchProfile };

package/dist/hooks/useDomain.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+require('../types/platform.cjs');
+require('../types/network.cjs');
+var hook = require('../types/hook.cjs');
+require('../types/source.cjs');
+require('../types/cointype.cjs');
+var useBaseQuery = require('./useBaseQuery.cjs');
+
+/**
+ * Hook to query Web3.bio domain data by identity
+ *
+ * @param identity - Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing domain data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name
+ * const { data, isLoading, error } = useDomain("vitalik.eth");
+ *
+ * // Query by domain name with platform
+ * const { data } = useDomain("ens,vitalik.eth");
+ */
+function useDomain(identity, options = {}) {
+    return useBaseQuery.useBaseQuery(identity, hook.QueryEndpoint.DOMAIN, false, options);
+}
+
+exports.useDomain = useDomain;

package/dist/{types/hooks → hooks}/useDomain.d.ts

@@ -1,4 +1,4 @@
-import type { DomainResult, IdentityString, QueryOptions } from "../utils/types";
+import { type DomainResult, type IdentityString, type QueryOptions } from "../types";
 /**
  * Hook to query Web3.bio domain data by identity
  *

package/dist/hooks/useDomain.js

@@ -0,0 +1,26 @@
+import '../types/platform.js';
+import '../types/network.js';
+import { QueryEndpoint } from '../types/hook.js';
+import '../types/source.js';
+import '../types/cointype.js';
+import { useBaseQuery } from './useBaseQuery.js';
+
+/**
+ * Hook to query Web3.bio domain data by identity
+ *
+ * @param identity - Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing domain data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name
+ * const { data, isLoading, error } = useDomain("vitalik.eth");
+ *
+ * // Query by domain name with platform
+ * const { data } = useDomain("ens,vitalik.eth");
+ */
+function useDomain(identity, options = {}) {
+    return useBaseQuery(identity, QueryEndpoint.DOMAIN, false, options);
+}
+
+export { useDomain };

package/dist/hooks/useNS.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+require('../types/platform.cjs');
+require('../types/network.cjs');
+var hook = require('../types/hook.cjs');
+require('../types/source.cjs');
+require('../types/cointype.cjs');
+var useBaseQuery = require('./useBaseQuery.cjs');
+
+/**
+ * Hook to query Web3.bio name service (NS) data by identity
+ *
+ * @param identity - Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing NS data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name
+ * const { data, isLoading, error } = useNS("vitalik.eth");
+ *
+ * // Query by Ethereum address
+ * const { data } = useNS("0x123...");
+ */
+function useNS(identity, options = {}) {
+    return useBaseQuery.useBaseQuery(identity, hook.QueryEndpoint.NS, false, options);
+}
+
+exports.useNS = useNS;

package/dist/{types/hooks → hooks}/useNS.d.ts

@@ -1,4 +1,4 @@
-import type { QueryOptions, IdentityString, NSResult } from "../utils/types";
+import { type QueryOptions, type IdentityString, type NSResult } from "../types";
 /**
  * Hook to query Web3.bio name service (NS) data by identity
  *

package/dist/hooks/useNS.js

@@ -0,0 +1,26 @@
+import '../types/platform.js';
+import '../types/network.js';
+import { QueryEndpoint } from '../types/hook.js';
+import '../types/source.js';
+import '../types/cointype.js';
+import { useBaseQuery } from './useBaseQuery.js';
+
+/**
+ * Hook to query Web3.bio name service (NS) data by identity
+ *
+ * @param identity - Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing NS data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name
+ * const { data, isLoading, error } = useNS("vitalik.eth");
+ *
+ * // Query by Ethereum address
+ * const { data } = useNS("0x123...");
+ */
+function useNS(identity, options = {}) {
+    return useBaseQuery(identity, QueryEndpoint.NS, false, options);
+}
+
+export { useNS };

package/dist/hooks/useProfile.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+require('../types/platform.cjs');
+require('../types/network.cjs');
+var hook = require('../types/hook.cjs');
+require('../types/source.cjs');
+require('../types/cointype.cjs');
+var useBaseQuery = require('./useBaseQuery.cjs');
+
+/**
+ * Hook to query Web3.bio profile data by identity
+ *
+ * @param identity - Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing profile data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name
+ * const { data, isLoading, error } = useProfile("vitalik.eth");
+ *
+ * // Query with platform specification
+ * const { data } = useProfile("farcaster,dwr");
+ */
+function useProfile(identity, options = {}) {
+    return useBaseQuery.useBaseQuery(identity, hook.QueryEndpoint.PROFILE, false, options);
+}
+
+exports.useProfile = useProfile;

package/dist/{types/hooks → hooks}/useProfile.d.ts

@@ -1,4 +1,4 @@
-import type { IdentityString, ProfileResult, QueryOptions } from "../utils/types";
+import { type IdentityString, type ProfileResult, type QueryOptions } from "../types";
 /**
  * Hook to query Web3.bio profile data by identity
  *

package/dist/hooks/useProfile.js

@@ -0,0 +1,26 @@
+import '../types/platform.js';
+import '../types/network.js';
+import { QueryEndpoint } from '../types/hook.js';
+import '../types/source.js';
+import '../types/cointype.js';
+import { useBaseQuery } from './useBaseQuery.js';
+
+/**
+ * Hook to query Web3.bio profile data by identity
+ *
+ * @param identity - Identity string
+ * @param options - Optional configuration options
+ * @returns Object containing profile data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name
+ * const { data, isLoading, error } = useProfile("vitalik.eth");
+ *
+ * // Query with platform specification
+ * const { data } = useProfile("farcaster,dwr");
+ */
+function useProfile(identity, options = {}) {
+    return useBaseQuery(identity, QueryEndpoint.PROFILE, false, options);
+}
+
+export { useProfile };