@echoxyz/sonar-react 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @echoxyz/sonar-react
 
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies [affa026]
+    - @echoxyz/sonar-core@0.2.1
+
+## 0.3.0
+
+### Minor Changes
+
+- b6393ef: Add useSonarEntity hook
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -78,26 +78,69 @@ export default function OAuthCallback() {
 }
 ```
 
-4. Call APIs using the low-level client:
+4. Load the Sonar entity associated with the user's wallet
+
+```tsx
+import { useSonarEntity } from "./hooks/useSonarEntity";
+import { useAccount } from "wagmi";
+
+const ExampleEntityPanel = () => {
+    const { address, isConnected } = useAccount();
+    const { authenticated, loading, entity, error } = useSonarEntity({
+        saleUUID: "<your-sale-uuid>",
+        wallet: { address, isConnected },
+    });
+
+    if (!isConnected || !authenticated) {
+        return <p>Connect your wallet and Sonar account to continue</p>;
+    }
+
+    if (loading) {
+        return <p>Loading...</p>;
+    }
+
+    if (error) {
+        return <p>Error: {error.message}</p>;
+    }
+
+    if (!entity) {
+        return <p>No entity found for this wallet. Please link your wallet on Sonar to continue.</p>;
+    }
+
+    return (
+        <div>
+            <span>entity.Label</span>
+            <span>entity.EntitySetupState</span>
+            <span>entity.EntitySaleEligibility</span>
+        </div>
+    );
+};
+
+```
+
+5. Optional: call APIs with the low level client to implement the purchase flow:
 
 ```tsx
 import { useEffect } from "react";
-import { useSonarAuth, useSonarClient } from "@echoxyz/sonar-react";
+import { useSonarEntity } from "./hooks/useSonarEntity";
+import { useAccount } from "wagmi";
 import { EntityType } from "@echoxyz/sonar-core";
 
 export function Example() {
-    const { authenticated, ready } = useSonarAuth();
+    const { address, isConnected } = useAccount();
+    // Would normally need to handle loading and error states like above
+    const { entity } = useSonarEntity({
+        saleUUID: "<your-sale-uuid>",
+        wallet: { address, isConnected },
+    });
     const client = useSonarClient();
-    const { walletAddress } = useWallet();
 
     useEffect(() => {
-        if (!ready || !authenticated) {
+        if (!entity) {
             return;
         }
 
         (async () => {
-            const { Entity: entity } = await client.readEntity({ saleUUID: "<your-sale-uuid>", walletAddress });
-
             const pre = await client.prePurchaseCheck({
                 saleUUID: "<your-sale-uuid>",
                 entityUUID: entity.EntityUUID,
@@ -121,7 +164,7 @@ export function Example() {
             });
             console.log(alloc);
         })();
-    }, [authenticated, client, ready]);
+    }, [entity]);
 
     return null;
 }
@@ -140,6 +183,8 @@ export function Example() {
 - `useSonarAuth()` → `{ authenticated, ready, token?, login(), completeOAuth({ code, state }), logout() }`
 
 - `useSonarClient()` → low-level `SonarClient` instance.
+  
+- `useSonarEntity()` → `{ authenticated, loading, entity?, error? }` high-level convenience hook for fetching a Sonar entity by wallet address.
 
 ## Notes
 

package/dist/index.cjs

@@ -22,11 +22,12 @@ var index_exports = {};
 __export(index_exports, {
   SonarProvider: () => SonarProvider,
   useSonarAuth: () => useSonarAuth,
-  useSonarClient: () => useSonarClient
+  useSonarClient: () => useSonarClient,
+  useSonarEntity: () => useSonarEntity
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/react.tsx
+// src/provider.tsx
 var import_sonar_core = require("@echoxyz/sonar-core");
 var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -102,23 +103,99 @@ function SonarProvider({ children, config }) {
   const clientValue = (0, import_react.useMemo)(() => ({ client }), [client]);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AuthContext.Provider, { value: authValue, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ClientContext.Provider, { value: clientValue, children }) });
 }
+
+// src/hooks.ts
+var import_sonar_core2 = require("@echoxyz/sonar-core");
+var import_react2 = require("react");
 function useSonarAuth() {
-  const ctx = (0, import_react.useContext)(AuthContext);
+  const ctx = (0, import_react2.useContext)(AuthContext);
   if (!ctx) {
     throw new Error("useSonarAuth must be used within a SonarProvider");
   }
   return ctx;
 }
 function useSonarClient() {
-  const ctx = (0, import_react.useContext)(ClientContext);
+  const ctx = (0, import_react2.useContext)(ClientContext);
   if (!ctx) {
     throw new Error("useSonarClient must be used within a SonarProvider");
   }
   return ctx.client;
 }
+function useSonarEntity(args) {
+  const { authenticated, ready } = useSonarAuth();
+  const client = useSonarClient();
+  if (!args.saleUUID) {
+    throw new Error("saleUUID is required");
+  }
+  const saleUUID = args.saleUUID;
+  const activeWallet = args.wallet.address;
+  const walletConnected = args.wallet.isConnected;
+  const [state, setState] = (0, import_react2.useState)({
+    loading: false,
+    hasFetched: false
+  });
+  const fullyConnected = ready && authenticated && Boolean(activeWallet) && walletConnected;
+  const refetch = (0, import_react2.useCallback)(async () => {
+    if (!saleUUID || !activeWallet || !fullyConnected) {
+      return;
+    }
+    setState((s) => ({ ...s, loading: true }));
+    try {
+      const resp = await client.readEntity({
+        saleUUID,
+        walletAddress: activeWallet
+      });
+      setState({
+        loading: false,
+        entity: resp.Entity,
+        error: void 0,
+        hasFetched: true
+      });
+    } catch (err) {
+      if (err instanceof import_sonar_core2.APIError && err.status === 404) {
+        setState({
+          loading: false,
+          entity: void 0,
+          error: void 0,
+          hasFetched: true
+        });
+        return;
+      }
+      const error = err instanceof Error ? err : new Error(String(err));
+      setState({ loading: false, entity: void 0, error, hasFetched: true });
+    }
+  }, [client, saleUUID, activeWallet, fullyConnected]);
+  const reset = (0, import_react2.useCallback)(() => {
+    setState({
+      loading: false,
+      hasFetched: false,
+      entity: void 0,
+      error: void 0
+    });
+  }, []);
+  (0, import_react2.useEffect)(() => {
+    if (fullyConnected) {
+      if (!state.hasFetched && !state.loading) {
+        refetch();
+      }
+    }
+  }, [fullyConnected, state.hasFetched, state.loading, refetch]);
+  (0, import_react2.useEffect)(() => {
+    if (ready && (!authenticated || !walletConnected || !activeWallet)) {
+      reset();
+    }
+  }, [ready, authenticated, walletConnected, activeWallet, reset]);
+  return {
+    authenticated,
+    loading: state.loading,
+    entity: state.entity,
+    error: state.error
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SonarProvider,
   useSonarAuth,
-  useSonarClient
+  useSonarClient,
+  useSonarEntity
 });

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { SonarClient } from '@echoxyz/sonar-core';
 import React from 'react';
+import { SonarClient, EntityDetails } from '@echoxyz/sonar-core';
 
 type SonarProviderProps = {
     children: React.ReactNode;
@@ -26,7 +26,22 @@ type AuthContextValue = {
     logout: () => void;
 };
 declare function SonarProvider({ children, config }: SonarProviderProps): react_jsx_runtime.JSX.Element;
+
 declare function useSonarAuth(): AuthContextValue;
 declare function useSonarClient(): SonarClient;
+type WalletConnection = {
+    address?: string;
+    isConnected: boolean;
+};
+type UseSonarEntityResult = {
+    authenticated: boolean;
+    loading: boolean;
+    entity?: EntityDetails;
+    error?: Error;
+};
+declare function useSonarEntity(args: {
+    saleUUID: string;
+    wallet: WalletConnection;
+}): UseSonarEntityResult;
 
-export { SonarProvider, type SonarProviderConfig, useSonarAuth, useSonarClient };
+export { SonarProvider, type SonarProviderConfig, type UseSonarEntityResult, type WalletConnection, useSonarAuth, useSonarClient, useSonarEntity };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { SonarClient } from '@echoxyz/sonar-core';
 import React from 'react';
+import { SonarClient, EntityDetails } from '@echoxyz/sonar-core';
 
 type SonarProviderProps = {
     children: React.ReactNode;
@@ -26,7 +26,22 @@ type AuthContextValue = {
     logout: () => void;
 };
 declare function SonarProvider({ children, config }: SonarProviderProps): react_jsx_runtime.JSX.Element;
+
 declare function useSonarAuth(): AuthContextValue;
 declare function useSonarClient(): SonarClient;
+type WalletConnection = {
+    address?: string;
+    isConnected: boolean;
+};
+type UseSonarEntityResult = {
+    authenticated: boolean;
+    loading: boolean;
+    entity?: EntityDetails;
+    error?: Error;
+};
+declare function useSonarEntity(args: {
+    saleUUID: string;
+    wallet: WalletConnection;
+}): UseSonarEntityResult;
 
-export { SonarProvider, type SonarProviderConfig, useSonarAuth, useSonarClient };
+export { SonarProvider, type SonarProviderConfig, type UseSonarEntityResult, type WalletConnection, useSonarAuth, useSonarClient, useSonarEntity };

package/dist/index.js

@@ -1,6 +1,6 @@
-// src/react.tsx
+// src/provider.tsx
 import { buildAuthorizationUrl, createClient, generatePKCEParams } from "@echoxyz/sonar-core";
-import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { createContext, useCallback, useEffect, useMemo, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 var AuthContext = createContext(void 0);
 var ClientContext = createContext(void 0);
@@ -74,22 +74,98 @@ function SonarProvider({ children, config }) {
   const clientValue = useMemo(() => ({ client }), [client]);
   return /* @__PURE__ */ jsx(AuthContext.Provider, { value: authValue, children: /* @__PURE__ */ jsx(ClientContext.Provider, { value: clientValue, children }) });
 }
+
+// src/hooks.ts
+import { APIError } from "@echoxyz/sonar-core";
+import { useCallback as useCallback2, useContext as useContext2, useEffect as useEffect2, useState as useState2 } from "react";
 function useSonarAuth() {
-  const ctx = useContext(AuthContext);
+  const ctx = useContext2(AuthContext);
   if (!ctx) {
     throw new Error("useSonarAuth must be used within a SonarProvider");
   }
   return ctx;
 }
 function useSonarClient() {
-  const ctx = useContext(ClientContext);
+  const ctx = useContext2(ClientContext);
   if (!ctx) {
     throw new Error("useSonarClient must be used within a SonarProvider");
   }
   return ctx.client;
 }
+function useSonarEntity(args) {
+  const { authenticated, ready } = useSonarAuth();
+  const client = useSonarClient();
+  if (!args.saleUUID) {
+    throw new Error("saleUUID is required");
+  }
+  const saleUUID = args.saleUUID;
+  const activeWallet = args.wallet.address;
+  const walletConnected = args.wallet.isConnected;
+  const [state, setState] = useState2({
+    loading: false,
+    hasFetched: false
+  });
+  const fullyConnected = ready && authenticated && Boolean(activeWallet) && walletConnected;
+  const refetch = useCallback2(async () => {
+    if (!saleUUID || !activeWallet || !fullyConnected) {
+      return;
+    }
+    setState((s) => ({ ...s, loading: true }));
+    try {
+      const resp = await client.readEntity({
+        saleUUID,
+        walletAddress: activeWallet
+      });
+      setState({
+        loading: false,
+        entity: resp.Entity,
+        error: void 0,
+        hasFetched: true
+      });
+    } catch (err) {
+      if (err instanceof APIError && err.status === 404) {
+        setState({
+          loading: false,
+          entity: void 0,
+          error: void 0,
+          hasFetched: true
+        });
+        return;
+      }
+      const error = err instanceof Error ? err : new Error(String(err));
+      setState({ loading: false, entity: void 0, error, hasFetched: true });
+    }
+  }, [client, saleUUID, activeWallet, fullyConnected]);
+  const reset = useCallback2(() => {
+    setState({
+      loading: false,
+      hasFetched: false,
+      entity: void 0,
+      error: void 0
+    });
+  }, []);
+  useEffect2(() => {
+    if (fullyConnected) {
+      if (!state.hasFetched && !state.loading) {
+        refetch();
+      }
+    }
+  }, [fullyConnected, state.hasFetched, state.loading, refetch]);
+  useEffect2(() => {
+    if (ready && (!authenticated || !walletConnected || !activeWallet)) {
+      reset();
+    }
+  }, [ready, authenticated, walletConnected, activeWallet, reset]);
+  return {
+    authenticated,
+    loading: state.loading,
+    entity: state.entity,
+    error: state.error
+  };
+}
 export {
   SonarProvider,
   useSonarAuth,
-  useSonarClient
+  useSonarClient,
+  useSonarEntity
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echoxyz/sonar-react",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -16,7 +16,7 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@echoxyz/sonar-core": "0.2.0"
+    "@echoxyz/sonar-core": "0.2.1"
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",