@echoxyz/sonar-react

This library provides higher level React hooks to abstract some of the state management for you. You will still need to use the @echoxyz/sonar-core library for some parts of the integration, and to import types.

Hooks

`useSonarAuth`

A hook to handle the OAuth flow for the user. Returns

Field	Type	Description
`authenticated`	`boolean`	Whether the user is authenticated.
`login`	`() => void`	Redirect the user to Sonar to login and authorize your application.
`token`	`string` \| `undefined`	The OAuth token for the user.
`completeOAuth`	`(args: { code: string; state: string }) => Promise<void>`	Call this in your OAuth callback handler to complete the OAuth flow and exchange the code for an access token.
`logout`	`() => void`	Call this to logout the user.

`useSonarClient`

A hook to get a reference to the underlying SonarClient from the @echoxyz/sonar-core library. Returns

Field	Type	Description
`client`	`SonarClient`	The underlying `SonarClient`.

`useSonarEntity`

A hook to fetch the state of a user’s Sonar entity based on their connected wallet address. The hook will only start loading once the entityID or walletAddress is defined. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to get entity details for.
`entityID`	`string` \| `undefined`	The entity ID of the entity to get details for.
`walletAddress`	`string` \| `undefined`	The wallet address of the entity to get details for. Only used for a wallet linking feature, enabled for niche use-cases on request.

Returns

Field	Type	Description
`authenticated`	`boolean`	Whether the user is authenticated.
`loading`	`boolean`	Whether the hook is loading.
`entity`	`EntityDetails` \| `undefined`	The state of the user’s Sonar entity. This can be `undefined` even if the user is not authenticated - see note about 404 errors in `readentity` docs.
`error`	`Error` \| `undefined`	Populated if the entity failed to load.

`useSonarEntities`

A hook to list all available entities for the authenticated user. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to list entities for.

Returns

Field	Type	Description
`authenticated`	`boolean`	Whether the user is authenticated.
`loading`	`boolean`	Whether the hook is loading.
`entities`	`EntityDetails[]` \| `undefined`	The state of the user’s Sonar entities.
`error`	`Error` \| `undefined`	Populated if the entity failed to load.

`useSonarPurchase`

A hook to run pre-purchase checks and return functions required to complete the purchase flow. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to run pre-purchase checks against the entity for.
`entityID`	`string`	The UUID of the entity to run pre-purchase checks for.
`walletAddress`	`string`	The wallet address of the entity to run pre-purchase checks for.

Returns

Name	Type	Description
`loading`	boolean	Whether the pre-purchase checks are loading.
`readyToPurchase`	boolean	Whether the entity is ready to purchase.
`error`	`Error` \| `undefined`	Populated if the pre-purchase checks failed to run.
`failureReason`	`PrePurchaseFailureReason` \| `undefined`	Populated if the entity is not ready to purchase.
`livenessCheckURL`	`string` \| `undefined`	URL to link the user to so that they can complete a liveness check on the Sonar site. Populated if the `failureReason` is `requires-liveness`.
`generatePurchasePermit`	`() => Promise<GeneratePurchasePermitResponse>` \| `undefined`	Function to generate a purchase permit to pass to the sale contract when purchasing tokens. Populated if the `readyToPurchase` is true.

`useSonarProfile`

A hook to fetch the authenticated user’s profile information. Returns

Field	Type	Description
`authenticated`	`boolean`	Whether the user is authenticated.
`loading`	`boolean`	Whether the profile is loading.
`profile`	`MyProfileResponse` \| `undefined`	The authenticated user’s profile containing their entity ID and email address.
`error`	`Error` \| `undefined`	Populated if the profile failed to load.

`useEntityInvestmentHistory`

A hook to fetch the authenticated user’s investment history, showing all Echo private group investments they have participated in. This automatically fetches when the user is authenticated and resets when they log out. Returns

Field	Type	Description
`authenticated`	`boolean`	Whether the user is authenticated.
`loading`	`boolean`	Whether the investment history is loading.
`investmentHistory`	`EntityInvestmentHistoryResponse` \| `undefined`	The user’s investment history containing an array of investments.
`error`	`Error` \| `undefined`	Populated if the investment history failed to load.

Example

import { useEntityInvestmentHistory } from '@echoxyz/sonar-react';

function InvestmentHistoryList() {
  const { loading, investmentHistory, error } = useEntityInvestmentHistory();

  if (loading) {
    return <div>Loading your investment history...</div>;
  }

  if (error) {
    return <div>Error loading investments: {error.message}</div>;
  }

  if (!investmentHistory?.Investments.length) {
    return <div>No investments yet</div>;
  }

  return (
    <div>
      <h2>Your Investment History</h2>
      <ul>
        {investmentHistory.Investments.map((investment, index) => (
          <li key={index}>
            <strong>{investment.CompanyName}</strong> - {investment.Round}
            <br />
            <small>
              Invested on: {new Date(investment.InvestedOn).toLocaleDateString()}
            </small>
          </li>
        ))}
      </ul>
    </div>
  );
}

`useCommitmentData`

A hook to fetch commitment data for a sale, with optional polling for live updates. This calls a public API endpoint, so the client does not need to be authenticated. Arguments

Name	Type	Description
`saleUUID`	`string`	The UUID of the sale to fetch commitment data for.
`pollingIntervalMs`	`number` \| `undefined`	Optional polling interval in milliseconds. Must be at least 1000ms. If not provided, the data is fetched once on mount.

Returns

Field	Type	Description
`loading`	`boolean`	Whether the commitment data is loading.
`commitmentData`	`ReadCommitmentDataResponse` \| `undefined`	The commitment data for the sale.
`error`	`Error` \| `undefined`	Populated if the commitment data failed to load.

Planning Your Sale

Integration Guides

Technical Features

Contract Reference

JS Reference

HTTP Reference

Hooks

`useSonarAuth`

`useSonarClient`

`useSonarEntity`

`useSonarEntities`

`useSonarPurchase`

`useSonarProfile`

`useEntityInvestmentHistory`

`useCommitmentData`

​Hooks

​useSonarAuth

​useSonarClient

​useSonarEntity

​useSonarEntities

​useSonarPurchase

​useSonarProfile

​useEntityInvestmentHistory

​useCommitmentData

Hooks

`useSonarAuth`

`useSonarClient`

`useSonarEntity`

`useSonarEntities`

`useSonarPurchase`

`useSonarProfile`

`useEntityInvestmentHistory`

`useCommitmentData`