React

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

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

const sonarConfig = {
  // can be found in the sale integration settings on the Echo founder
  // dashboard
  clientUUID: "<YOUR_OAUTH_CLIENT_UUID>",
  // must match a redirect URI that you have configured against your
  // OAuth client in the sale settings
  redirectURI: "<YOUR_REDIRECT_URI>",
};

function Provider() {
  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 { useAccount } from "wagmi";
import { useSonarEntity } from "@echoxyz/sonar-react";

const SonarEntityPanel = () => {
  const { address, isConnected } = useAccount();
  const { authenticated, loading, entity, error } = useSonarEntity({
    // from the sale integration settings on the Echo founder dashboard
    saleUUID: "YOUR_SALE_UUID",
    walletAddress: address,
  });

  if (!address || !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>;
  }

  // in this case the user has authenticated with Sonar,
  // but has not yet linked the currently connected wallet
  // to any of their entities on the Sonar site
  if (!entity) {
    return (
      <p>No entity found for this wallet. Please link your wallet{" "}
      on <a href="https://app.echo.xyz/sonar"> Sonar</a> to continue.</p>
    );
  }

  return (
    <div>
      <span>{entity.Label}</span>
      <span>{entity.EntitySetupState}</span>
      <span>{entity.EntitySaleEligibility}</span>
    </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>
      <span>{readinessCfg.description}</span>

      {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 = (walletAddress: `0x${string}`) => {
  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;

      const { request } = await simulateContract(config, {
        address: "YOUR_SALE_CONTRACT_ADDRESS",
        abi: YourSaleContractABI,
        functionName: "YOUR_PURCHASE_FUNCTION_NAME",
        args: [
          amount,
          {
              entityID: permit.EntityID,
              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),
              payload: permit.Payload,
          },
          purchasePermitResp.Signature,
        ] as const,
      });

      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 PurchasePanel({
  walletAddress,
  amount,
  generatePurchasePermit, // From the useSonarPurchase hook
}: {
  walletAddress: `0x${string}`;
  amount: bigint;
  generatePurchasePermit: () => Promise<GeneratePurchasePermitResponse>;
}) {
  const {
    commitWithPermit,
    awaitingTxReceipt,
    txReceipt,
    awaitingTxReceiptError,
  } = useSaleContract(walletAddress);

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

  const purchase = 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={purchase}
      >
        {loading || awaitingTxReceipt ? "Loading..." : "Purchase"}
      </button>

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