npm install @echoxyz/sonar-core @echoxyz/sonar-react

import { SonarProvider } from "@echoxyz/sonar-react";

const sonarConfig = {
  clientUUID: "YOUR_OAUTH_CLIENT_UUID",
  redirectURI: "YOUR_REDIRECT_URI",
};

function App() {
  return (
    <SonarProvider config={sonarConfig}>
      {/* Your application */}
    </SonarProvider>
  );
}

import { useSonarAuth } from "@echoxyz/sonar-react";

function AuthButton() {
  const { login, authenticated, logout } = useSonarAuth();

  const onClick = () => {
    if (authenticated) {
      logout();
      return;
    }
    login();
  };

  return (
    <button onClick={onClick}>
      {authenticated ? "Disconnect from Sonar" : "Sign in with Sonar"}
    </button>
  );
}

import { useEffect, useRef, useState } from "react";
import { useSonarAuth } from "@echoxyz/sonar-react";

export default function OAuthCallback() {
  const { authenticated, completeOAuth, ready } = useSonarAuth();
  const oauthCompletionTriggered = useRef(false);
  const [oauthError, setOAuthError] = useState<string | null>(null);

  const params = new URLSearchParams(window.location.search);
  const code = params.get("code");
  const state = params.get("state");

  // complete the oauth flow and exchange the code for an access token
  useEffect(() => {
    const processOAuthCallback = async () => {
      // the user is already authenticated, nothing to do
      if (!ready || authenticated || !code || !state) {
        return;
      }

      // ensuring the oauth completion isn't called multiple times
      // since subsequent ones are expected to fail
      if (oauthCompletionTriggered.current) {
        return;
      }
      oauthCompletionTriggered.current = true;

      try {
        await completeOAuth({ code, state });
      } catch (err) {
        setOAuthError(err instanceof Error ? err.message : null);
      }
    };

    processOAuthCallback();
  }, [authenticated, completeOAuth, code, ready, state]);

  // redirect away from this page once the OAuth flow is complete
  useEffect(() => {
    if (!ready || !authenticated) {
      return;
    }
    window.location.href = "/";
  }, [authenticated, ready]);

  // note you should also add a timeout to handle the case
  // where it takes too long for `authenticated` to be true
  if (oauthError) {
    return (
      <p>{oauthError}</p>
    );
  }

  return (
    <p>Connecting to Echo...</p>
  );
}

import { useSonarEntities } from "@echoxyz/sonar-react";

const SonarEntityPanel = () => {
  const { authenticated, loading, entities, error } = useSonarEntities({
    // from the sale integration settings on the Echo founder dashboard
    saleUUID: "YOUR_SALE_UUID",
  });

  if (!authenticated) {
    return <p>Connect your Sonar account to continue</p>;
  }

  if (loading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }

  if (!entities || entities.length === 0) {
    return (
      <p>No entity found. Continue your setup{" "}
      on <a href="https://app.echo.xyz/sonar"> Sonar</a> to continue.</p>
    );
  }

  return (
    <div>
      {entities.map((entity) => (
        <div key={entity.EntityID}>
          <span>{entity.Label}</span>
          <span>{entity.EntitySetupState}</span>
          <span>{entity.EntitySaleEligibility}</span>
        </div>
      ))}
    </div>
  );
};

import { PrePurchaseFailureReason } from "@echoxyz/sonar-core";
import {
  useSonarPurchase,
} from "@echoxyz/sonar-react";

function PrePurchaseStatusPanel({
  entityID,
  walletAddress,
}: {
  entityID: string;
  walletAddress: `0x${string}`;
}) {
  const sonarPurchaser = useSonarPurchase({
    saleUUID: "YOUR_SALE_UUID",
    entityID,
    walletAddress,
  });

  if (sonarPurchaser.loading) {
    return <p>Loading...</p>;
  }

  if (sonarPurchaser.error) {
    return <p>Error: {sonarPurchaser.error.message}</p>;
  }

  return (
    <div>
      {sonarPurchaser.readyToPurchase && (
        <span>Ready to purchase!</span>
      )}

      {!sonarPurchaser.readyToPurchase &&
          sonarPurchaser.failureReason ===
            PrePurchaseFailureReason.REQUIRES_LIVENESS && (
            <a href={sonarPurchaser.livenessCheckURL} target="_blank">
              Complete liveness check to purchase
            </a>
          )}
    </div>
  );
}

import { GeneratePurchasePermitResponse } from "@echoxyz/sonar-core";
import { useCallback, useState } from "react";
import { useWriteContract, useWaitForTransactionReceipt } from "wagmi";
import { useConfig } from "wagmi";
import { simulateContract } from "wagmi/actions";
import { YourSaleContractABI } from "./YourSaleContractABI";

export const useSaleContract = () => {
  const { writeContractAsync } = useWriteContract();
  const config = useConfig();

  const [txHash, setTxHash] = useState<`0x${string}` | undefined>(undefined);

  // Track the state of the transaction receipt
  const {
    data: txReceipt,
    isFetching: awaitingTxReceipt,
    error: awaitingTxReceiptError,
  } = useWaitForTransactionReceipt({
    hash: txHash,
  });

  // This function is used to construct the transaction,
  // simulate it, and then submit it after the user has signed it
  const commitWithPermit = useCallback(
    async ({
      purchasePermitResp,
      amount,
    }: {
      purchasePermitResp: GeneratePurchasePermitResponse;
      amount: bigint;
    }) => {
      if (!("MinPrice" in purchasePermitResp.PermitJSON)) {
          throw new Error("Invalid purchase permit response");
      }
      const permit = purchasePermitResp.PermitJSON;

      // Your args might be different if you are not using the generic SettlementSale contract.
      // But the format of the purchase permit should be the same.
      const commitmentArgs = [
        "PAYMENT_TOKEN_ADDRESS",
        { amount: amount, price: 0n, lockup: false },
        {
          saleSpecificEntityID: permit.SaleSpecificEntityID,
          saleUUID: permit.SaleUUID,
          wallet: permit.Wallet,
          expiresAt: BigInt(permit.ExpiresAt),
          minAmount: BigInt(permit.MinAmount),
          maxAmount: BigInt(permit.MaxAmount),
          minPrice: BigInt(permit.MinPrice),
          maxPrice: BigInt(permit.MaxPrice),
          opensAt: BigInt(permit.OpensAt),
          closesAt: BigInt(permit.ClosesAt),
          payload: permit.Payload,
        },
        purchasePermitResp.Signature,
      ] as const;

      // Assumes that the sender has already approved the sale contract to spend the token.
      // Note that the SettlementSale contract also provides the option of committing with an ERC20 permit (replaceBidWithPermit)
      const { request } = await simulateContract(config, {
        address: "YOUR_SALE_CONTRACT_ADDRESS",
        abi: YourSaleContractABI,
        functionName: "YOUR_PURCHASE_FUNCTION_NAME", // e.g. replaceBidWithApproval for the SettlementSale contract
        args: commitmentArgs,
      });

      setTxHash(
        await writeContractAsync(request, {
          onError: (error: Error) => {
            throw error;
          },
        })
      );
    },
    [writeContractAsync, config]
  );

  return {
    commitWithPermit,
    awaitingTxReceipt,
    txReceipt,
    awaitingTxReceiptError,
  };
};

import { GeneratePurchasePermitResponse } from "@echoxyz/sonar-core";
import { useState } from "react";
import { useSaleContract } from "./useSaleContract";

function CommitPanel({
  amount,
  generatePurchasePermit, // From the useSonarPurchase hook
}: {
  amount: bigint;
  generatePurchasePermit: () => Promise<GeneratePurchasePermitResponse>;
}) {
  const {
    commitWithPermit,
    awaitingTxReceipt,
    txReceipt,
    awaitingTxReceiptError,
  } = useSaleContract();

  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | undefined>(undefined);

  const commit = async () => {
    setLoading(true);
    setError(undefined);
    try {
      const purchasePermitResp = await generatePurchasePermit();
      await commitWithPermit({
        purchasePermitResp: purchasePermitResp,
        amount: amount,
      });
    } catch (error) {
      setError(error as Error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button
        disabled={loading || awaitingTxReceipt}
        onClick={commit}
      >
        {loading || awaitingTxReceipt ? "Loading..." : "Commit"}
      </button>

      {awaitingTxReceipt && !txReceipt && (
        <p>Waiting for transaction receipt...</p>
      )}
      {txReceipt?.status === "success" && (
        <p>Commitment successful</p>
      )}
      {txReceipt?.status === "reverted" && (
        <p>Commitment reverted</p>
      )}
      {error && <p>{error.message}</p>}
      {awaitingTxReceiptError && (
        <p>{awaitingTxReceiptError.message}</p>
      )}
    </div>
  );
}