web3bio-profile-kit 0.1.0

package/README.md

@@ -0,0 +1,256 @@
+# Web3.bio Profile Kit
+
+A lightweight React hooks library for easily integrating Web3.bio profile data into your applications.
+
+## Installation
+
+```bash
+npm install web3bio-profile-kit
+# or
+yarn add web3bio-profile-kit
+# or
+pnpm add web3bio-profile-kit
+```
+
+## Overview
+
+Web3.bio Profile Kit provides React hooks for querying the [Web3.bio Profile API](https://api.web3.bio/), which offers unified profile data across multiple Web3 platforms. This library makes it easy to fetch user profiles, name service information, and domain data.
+
+More information about the Web3.bio Profile API can be found in the [document](https://api.web3.bio/).
+
+## API Key
+
+The Profile API is free, but usage without API keys includes rate limiting mechanisms to ensure fair usage and prevent abuse. If you need an API Key, you can obtain one by contacting Web3.bio via [Twitter (X)](https://x.com/web3bio) or [Telegram group](https://t.me/web3dotbio).
+
+You can set your API key using environment variables:
+
+```
+WEB3BIO_API_KEY=your_api_key
+# or
+REACT_APP_WEB3BIO_API_KEY=your_api_key
+# or
+NEXT_PUBLIC_WEB3BIO_API_KEY=your_api_key
+# or
+VITE_WEB3BIO_API_KEY=your_api_key
+```
+
+## Usage
+
+### Query Profile Data
+
+#### Platform-Specific Profile Queries
+
+```jsx
+import { useProfile } from 'web3bio-profile-kit';
+
+function ProfileComponent() {
+  // Query with explicit platform format
+  const { data, isLoading, error } = useProfile("ens,vitalik.eth");
+
+  // Or simplified format without the platform prefix
+  // const { data, isLoading, error } = useProfile("vitalik.eth");
+  // Or with Ethereum address
+  // const { data, isLoading, error } = useProfile("ethereum,0x123...");
+  // Or Farcaster, Lens, Basenames, Linea names and more
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h1>{data?.displayName || data?.identity}</h1>
+      {data?.avatar && <img src={data.avatar} alt="Profile" />}
+      <p>{data?.description}</p>
+    </div>
+  );
+}
+```
+
+#### Universal Profile Queries
+
+```jsx
+import { useUniversalProfile } from 'web3bio-profile-kit';
+
+function UniversalProfileComponent() {
+  // Query by any identity format - ENS domain, Farcaster handle, etc.
+  const { data, isLoading, error } = useUniversalProfile("vitalik.eth");
+
+  // Or with any other identity
+  // const { data, isLoading, error } = useUniversalProfile("dwr.eth.farcaster");
+  // const { data, isLoading, error } = useUniversalProfile("0x123...");
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h1>{data?.displayName || data?.identity}</h1>
+      {data?.avatar && <img src={data.avatar} alt="Profile" />}
+      <p>{data?.description}</p>
+    </div>
+  );
+}
+```
+
+### Query Name Service Data
+
+#### Platform-Specific Name Service Queries
+
+```jsx
+import { useNS } from 'web3bio-profile-kit';
+
+function NameServiceComponent() {
+  const { data, isLoading } = useNS("ens,vitalik.eth");
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h2>{data?.displayName}</h2>
+      <p>Address: {data?.address}</p>
+    </div>
+  );
+}
+```
+
+#### Universal Name Service Queries
+
+```jsx
+import { useUniversalNS } from 'web3bio-profile-kit';
+
+function UniversalNameServiceComponent() {
+  // Works with any identity format
+  const { data, isLoading } = useUniversalNS("vitalik.eth");
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h2>{data?.displayName}</h2>
+      <p>Address: {data?.address}</p>
+    </div>
+  );
+}
+```
+
+### Query Domain Data
+
+```jsx
+import { useDomain } from 'web3bio-profile-kit';
+
+function DomainComponent() {
+  const { data, isLoading } = useDomain("vitalik.eth");
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h2>{data?.identity}</h2>
+      <p>Resolved address: {data?.resolvedAddress}</p>
+      <p>Owner address: {data?.ownerAddress}</p>
+    </div>
+  );
+}
+```
+
+### Batch Profile Query
+
+```jsx
+import { useProfile } from 'web3bio-profile-kit';
+
+function BatchProfileComponent() {
+  const { data, isLoading } = useProfile([
+    "vitalik.eth",
+    "lens,stani"
+  ]);
+
+  // You can also use useNS for batch queries
+  // const { data, isLoading } = useNS([
+  //   "vitalik.eth",
+  //   "lens,stani"
+  // ]);
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {Array.isArray(data) && data.map(profile => (
+        <div key={profile.identity}>
+          <h3>{profile.displayName}</h3>
+          <p>{profile.description}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Advanced Usage: Controlling Query Execution
+
+You can control when the query executes using the `enabled` option:
+
+```jsx
+const [searchTerm, setSearchTerm] = useState("");
+const { data, isLoading } = useProfile(searchTerm, {
+  enabled: searchTerm.length > 0
+});
+```
+
+## Supported Identity Formats
+
+- ENS domains: `name.eth`
+- Ethereum addresses: `0x123...`
+- Farcaster: `username.farcaster`
+- Lens profiles: `username.lens`
+- And many more!
+
+You can also use the explicit format `platform,identity` for clarity:
+- `ens,vitalik.eth`
+- `ethereum,0x123...`
+- `farcaster,dwr.eth`
+- `lens,stani.lens`
+
+## API Reference
+
+### Hooks
+
+#### `useProfile(identity, options?)`
+
+Fetches comprehensive profile data including social links and avatar.
+
+#### `useUniversalProfile(identity, options?)`
+
+Fetches comprehensive universal profile data including social links and avatar across multiple platforms.
+
+#### `useNS(identity, options?)`
+
+Fetches basic name service data (similar to ENS lookups).
+
+#### `useUniversalNS(identity, options?)`
+
+Fetches basic universal name service data across multiple platforms.
+
+#### `useDomain(identity, options?)`
+
+Fetches detailed domain information including resolution data.
+
+### Arguments
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `identity` | `string` or `string[]` | Identity to query or array of identities for batch queries |
+| `options` | `object` | Optional configuration with `apiKey` and `enabled` |
+
+### Return Values
+
+All hooks return an object with:
+
+| Property | Type | Description |
+|-----------|------|-------------|
+| `data` | `object` or `null` | The profile data when successful |
+| `isLoading` | `boolean` | `true` during the fetch operation |
+| `error` | `Error` or `null` | Error object if the request failed |
+
+## License
+
+MIT

package/dist/hooks/index.d.ts

@@ -0,0 +1,6 @@
+export { useProfile } from "./useProfile";
+export { useNS } from "./useNS";
+export { useDomain } from "./useDomain";
+export { useUniversalProfile } from "./useUniversalProfile";
+export { useUniversalNS } from "./useUniversalNS";
+export { useBaseQuery } from "./useBaseQuery";

package/dist/hooks/useBaseQuery.d.ts

@@ -0,0 +1,6 @@
+import { QueryEndpoint } from "../utils/constants";
+import { Identity, QueryOptions, QueryResult } from "../utils/types";
+/**
+ * Core hook for querying Web3.bio Profile API
+ */
+export declare function useBaseQuery<T>(identity: Identity, endpoint: QueryEndpoint, universal?: boolean, options?: QueryOptions): QueryResult<T>;

package/dist/hooks/useDomain.d.ts

@@ -0,0 +1,16 @@
+import { DomainQueryResult, Identity, QueryOptions } from "../utils/types";
+/**
+ * Hook to query Web3.bio domain data by identity
+ *
+ * @param identity - Identity string or array of identities to query
+ * @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");
+ */
+export declare function useDomain(identity: Identity, options?: QueryOptions): DomainQueryResult;

package/dist/hooks/useNS.d.ts

@@ -0,0 +1,16 @@
+import { Identity, NSQueryResult, QueryOptions } from "../utils/types";
+/**
+ * Hook to query Web3.bio name service (NS) data by identity
+ *
+ * @param identity - Identity string or array of identities to query
+ * @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...");
+ */
+export declare function useNS(identity: Identity, options?: QueryOptions): NSQueryResult;

package/dist/hooks/useProfile.d.ts

@@ -0,0 +1,16 @@
+import { Identity, ProfileQueryResult, QueryOptions } from "../utils/types";
+/**
+ * Hook to query Web3.bio profile data by identity
+ *
+ * @param identity - Identity string or array of identities to query
+ * @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");
+ */
+export declare function useProfile(identity: Identity, options?: QueryOptions): ProfileQueryResult;

package/dist/hooks/useUniversalNS.d.ts

@@ -0,0 +1,16 @@
+import { Identity, NSQueryResult, QueryOptions } from "../utils/types";
+/**
+ * Hook to query Web3.bio name service (NS) data using universal identity lookup
+ *
+ * @param identity - Identity string or array of identities to query
+ * @param options - Optional configuration options
+ * @returns Object containing NS data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name with universal lookup
+ * const { data, isLoading, error } = useUniversalNS("vitalik.eth");
+ *
+ * // Query by any identity type with universal lookup
+ * const { data } = useUniversalNS("dwr.farcaster");
+ */
+export declare function useUniversalNS(identity: Identity, options?: QueryOptions): NSQueryResult;

package/dist/hooks/useUniversalProfile.d.ts

@@ -0,0 +1,16 @@
+import { Identity, ProfileQueryResult, QueryOptions } from "../utils/types";
+/**
+ * Hook to query Web3.bio profile data using universal identity lookup
+ *
+ * @param identity - Identity string or array of identities to query
+ * @param options - Optional configuration options
+ * @returns Object containing profile data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name with universal lookup
+ * const { data, isLoading, error } = useUniversalProfile("vitalik.eth");
+ *
+ * // Query by any identity type with universal lookup
+ * const { data } = useUniversalProfile("dwr.farcaster");
+ */
+export declare function useUniversalProfile(identity: Identity, options?: QueryOptions): ProfileQueryResult;

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+declare enum PlatformType {
+    ens = "ens",
+    farcaster = "farcaster",
+    lens = "lens",
+    ethereum = "ethereum",
+    twitter = "twitter",
+    github = "github",
+    bitcoin = "bitcoin",
+    unstoppableDomains = "unstoppabledomains",
+    basenames = "basenames",
+    linea = "linea",
+    space_id = "space_id",
+    solana = "solana",
+    sns = "sns",
+    nextid = "nextid",
+    dotbit = "dotbit"
+}
+declare enum SourceType {
+    ethereum = "ethereum",
+    ens = "ens",
+    twitter = "twitter",
+    nextid = "nextid",
+    dotbit = "dotbit",
+    unstoppabledomains = "unstoppabledomains",
+    lens = "lens",
+    farcaster = "farcaster",
+    space_id = "space_id",
+    solana = "solana",
+    sns = "sns"
+}
+type SocialLinksItem = {
+    link: string | null;
+    handle: string | null;
+    sources: SourceType[];
+};
+type SocialLinks = Record<string, SocialLinksItem>;
+interface ProfileResponse {
+    identity: string;
+    address: string | null;
+    avatar: string | null;
+    description: string | null;
+    platform: string;
+    displayName: string | null;
+    email: string | null;
+    contenthash: string | null;
+    header: string | null;
+    location: string | null;
+    createdAt: string | null;
+    status: string | null;
+    error?: string;
+    links: SocialLinks;
+    social: {
+        uid: number | null;
+        follower: number;
+        following: number;
+    } | {};
+}
+interface NSResponse {
+    identity: string;
+    address: string | null;
+    avatar: string | null;
+    description: string | null;
+    platform: string;
+    displayName: string | null;
+}
+interface DomainResponse {
+    identity: string;
+    platform: PlatformType;
+    resolvedAddress: string | null;
+    ownerAddress: string | null;
+    managerAddress: string | null;
+    displayName: string | null;
+    isPrimary: boolean;
+    status: string;
+    createdAt: string | null;
+    updatedAt: string | null;
+    expiredAt: string | null;
+    contenthash: string | null;
+    texts: Record<string, string>;
+    addresses: Record<string, string>;
+}
+type QueryOptions = {
+    /** API Key for authentication */
+    apiKey?: string;
+    /** Whether the query should execute */
+    enabled?: boolean;
+};
+type IdentityString = string | `${PlatformType},${string}`;
+type Identity = IdentityString | IdentityString[];
+type QueryResult<T> = {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+type ProfileQueryResult = QueryResult<ProfileResponse>;
+type NSQueryResult = QueryResult<NSResponse>;
+type DomainQueryResult = QueryResult<DomainResponse>;
+
+/**
+ * Hook to query Web3.bio profile data by identity
+ *
+ * @param identity - Identity string or array of identities to query
+ * @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");
+ */
+declare function useProfile(identity: Identity, options?: QueryOptions): ProfileQueryResult;
+
+/**
+ * Hook to query Web3.bio name service (NS) data by identity
+ *
+ * @param identity - Identity string or array of identities to query
+ * @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...");
+ */
+declare function useNS(identity: Identity, options?: QueryOptions): NSQueryResult;
+
+/**
+ * Hook to query Web3.bio domain data by identity
+ *
+ * @param identity - Identity string or array of identities to query
+ * @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");
+ */
+declare function useDomain(identity: Identity, options?: QueryOptions): DomainQueryResult;
+
+/**
+ * Hook to query Web3.bio profile data using universal identity lookup
+ *
+ * @param identity - Identity string or array of identities to query
+ * @param options - Optional configuration options
+ * @returns Object containing profile data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name with universal lookup
+ * const { data, isLoading, error } = useUniversalProfile("vitalik.eth");
+ *
+ * // Query by any identity type with universal lookup
+ * const { data } = useUniversalProfile("dwr.farcaster");
+ */
+declare function useUniversalProfile(identity: Identity, options?: QueryOptions): ProfileQueryResult;
+
+/**
+ * Hook to query Web3.bio name service (NS) data using universal identity lookup
+ *
+ * @param identity - Identity string or array of identities to query
+ * @param options - Optional configuration options
+ * @returns Object containing NS data, loading state, and any errors
+ *
+ * @example
+ * // Query by ENS name with universal lookup
+ * const { data, isLoading, error } = useUniversalNS("vitalik.eth");
+ *
+ * // Query by any identity type with universal lookup
+ * const { data } = useUniversalNS("dwr.farcaster");
+ */
+declare function useUniversalNS(identity: Identity, options?: QueryOptions): NSQueryResult;
+
+declare const API_ENDPOINT = "https://api.web3.bio";
+declare enum ErrorMessages {
+    NOT_FOUND = "Not Found",
+    INVALID_RESOLVER = "Invalid Resolver Address",
+    INVALID_RESOLVED = "Invalid Resolved Address",
+    NOT_EXIST = "Does Not Exist",
+    INVALID_IDENTITY = "Invalid Identity or Domain",
+    INVALID_ADDRESS = "Invalid Address",
+    UNKNOWN_ERROR = "Unknown Error Occurred",
+    NETWORK_ERROR = "Network Error"
+}
+declare enum QueryEndpoint {
+    NS = "ns",
+    PROFILE = "profile",
+    DOMAIN = "domain"
+}
+declare const REGEX: {
+    ENS: RegExp;
+    BASENAMES: RegExp;
+    LINEA: RegExp;
+    FARCASTER: RegExp;
+    LENS: RegExp;
+    CLUSTER: RegExp;
+    SPACE_ID: RegExp;
+    GENOME: RegExp;
+    UNSTOPPABLE_DOMAINS: RegExp;
+    CROSSBELL: RegExp;
+    DOTBIT: RegExp;
+    SNS: RegExp;
+    ETH_ADDRESS: RegExp;
+    BTC_ADDRESS: RegExp;
+    SOLANA_ADDRESS: RegExp;
+    LOWERCASE_EXEMPT: RegExp;
+    TWITTER: RegExp;
+    NEXT_ID: RegExp;
+};
+
+export { API_ENDPOINT, DomainQueryResult, DomainResponse, ErrorMessages, Identity, IdentityString, NSQueryResult, NSResponse, PlatformType, ProfileQueryResult, ProfileResponse, QueryEndpoint, QueryOptions, QueryResult, REGEX, SocialLinks, SocialLinksItem, SourceType, useDomain, useNS, useProfile, useUniversalNS, useUniversalProfile };