# From packages/privacy-boost-react directory
npm run docs

# Documentation will be generated in docs/api/

<PrivacyBoostProvider
  config={PrivacyBoostConfig}
  loadingComponent?: ReactNode
  errorComponent?: (error: Error) => ReactNode
>
  {children}
</PrivacyBoostProvider>

// Or with pre-initialized SDK
<PrivacyBoostProvider sdk={PrivacyBoost}>
  {children}
</PrivacyBoostProvider>

function usePrivacyBoost(): PrivacyBoost | null

function usePrivacyBoostState(): {
  loading: boolean;
  error: Error | null;
  initialized: boolean;
}

function useAuth(): UseAuthResult

interface UseAuthResult {
  // State
  isConnected: boolean;
  isAuthenticated: boolean;
  isWalletAvailable: boolean;
  address: string | null;
  privacyAddress: string | null;
  mpk: string | null;

  // Methods
  authenticate(adapter: WalletAdapter, options?: AuthenticateOptions): Promise<AuthResult>;
  authenticateWithWalletAdapter(options?: AuthenticateOptions): Promise<AuthResult>;
  logout(): Promise<void>;
  clearSession(): Promise<void>;
}

function useVault(): UseVaultResult

interface UseVaultResult {
  shield(params: SimpleShieldParams): Promise<ShieldResult>;
  unshield(params: SimpleUnshieldParams): Promise<UnshieldResult>;
  send(params: SimpleSendParams): Promise<TransactionResult>;
  getBalance(tokenAddress: string): Promise<TokenBalance>;
  getAllBalances(): Promise<TokenBalance[]>;
  getTokens(): Promise<TokenMetadata[]>;
  /** Force a server refresh of one token's balance. */
  refreshBalance(tokenAddress: Hex): Promise<void>;
  /** Force a server refresh of all tracked balances. */
  refreshBalances(): Promise<void>;
}

interface SimpleShieldParams {
  tokenAddress: Hex;
  /** Either a human-readable string (e.g. "1.5") or a wei `bigint`. Strings are parsed using the token's `decimals`. */
  amount: string | bigint;
  onProgress?: OnProgress;
}

interface SimpleUnshieldParams {
  tokenAddress: Hex;
  amount: string | bigint;
  /** Recipient Ethereum address. Defaults to the connected wallet address. */
  recipient?: Hex;
  /** @deprecated Use `recipient`. */
  recipientAddress?: Hex;
  onProgress?: OnProgress;
}

interface SimpleSendParams {
  tokenAddress: Hex;
  amount: string | bigint;
  /** Recipient privacy address. */
  recipient?: Hex;
  /** @deprecated Use `recipient`. */
  to?: Hex;
}

function useBalances(): UseBalancesResult

interface UseBalancesResult {
  balances: FormattedBalance[];
  loading: boolean;
  lastSynced: number | null;
  getBalance(tokenAddress: string): FormattedBalance | undefined;
  getShieldedBalance(tokenAddress: string): bigint;
  getWalletBalance(tokenAddress: string): bigint;
  totalShielded: bigint;
  tokenCount: number;
}

interface FormattedBalance extends TokenBalance {
  formattedShielded: string;
  formattedWallet: string;
}

function useTransactions(): UseTransactionsResult

interface UseTransactionsResult {
  transactions: Transaction[];
  recentTransactions: Transaction[];
  pending: Transaction[];
  isLoading: boolean;
  hasPending: boolean;
  pendingCount: number;
  deposits: Transaction[];
  withdrawals: Transaction[];
  transfers: Transaction[];
  fetchHistory(params?: TransactionHistoryParams): Promise<Transaction[]>;
  refreshPending(): Promise<number>;
  getByHash(txHash: string): Transaction | undefined;
  getByType(type: TransactionType): Transaction[];
  getByStatus(status: TransactionStatus): Transaction[];
}

interface TransactionHistoryParams {
  type?: 'shield' | 'unshield' | 'transfer';
  tokenAddress?: string;
  limit?: number;
}

function useChain(config: ChainClientConfig): ChainClient | null

interface ChainClientConfig {
  /** Server URL for the chain. Required. */
  serverUrl: string;
  /** EVM chain ID. Auto-discovered from the server when omitted. */
  chainId?: number;
  /** Shield contract address on this chain. Auto-discovered when omitted. */
  shieldContractAddress?: string;
  /** WETH address on this chain. Required for native-ETH flows. */
  wethContractAddress?: string;
  rpcUrl?: string;
  tokenRegistryAddress?: string;
  pinnedTransportKeys?: TransportServerKeyInfo[];
  allowPlaintext?: boolean;
}

function useCampaignProgress(): UseCampaignProgressReturn

interface UseCampaignProgressReturn {
  /** Mission progress, or null before the first fetch settles or after one failed. */
  data: StartaleCampaignProgress | null;
  /** Alias for `data`. */
  progress: StartaleCampaignProgress | null;
  isLoading: boolean;
  /** Alias for `isLoading`. */
  loading: boolean;
  error: PrivacyBoostError | null;
  refetch: () => Promise<void>;
}

interface StartaleCampaignProgress {
  hasDepositedAtLeast10Usd: boolean;
  hasMadeTransfer: boolean;
  /** Registry token ID the deposit mission is scoped to, if the server scopes it. */
  campaignTokenId?: number;
}

function MissionList() {
  const { progress, isLoading, error } = useCampaignProgress();

  if (isLoading) return <div>Loading progress...</div>;
  if (error) return <div>Progress unavailable. Try again shortly.</div>;
  // Idle: the session is not authenticated yet, so there is nothing to report.
  if (!progress) return null;

  // Scoped to one token when campaignTokenId is present, otherwise any token
  // the user shields counts toward the $10.
  const depositLabel =
    progress.campaignTokenId === undefined
      ? 'Deposit $10'
      : `Deposit $10 of token #${progress.campaignTokenId}`;

  return (
    <ul>
      <li>{progress.hasDepositedAtLeast10Usd ? '✓' : '○'} {depositLabel}</li>
      <li>{progress.hasMadeTransfer ? '✓' : '○'} Make a private transfer</li>
    </ul>
  );
}

function createWalletAdapter(): WalletAdapter

interface PrivacyBoostConfig {
  appId: string;
  serverUrl: string;
  chainId?: number;                 // Auto-discovered from server if omitted
  shieldContractAddress?: string;   // Auto-discovered from server if omitted
  wethContractAddress?: string;
  rpcUrl?: string;
  tokenRegistryAddress?: string;
  persistence?: {
    storage: 'localStorage' | 'indexedDB' | 'osKeychain';
    unlock?: 'none' | 'pin' | 'password';
  };
}

interface ReceiverTransfer {
  pubKey: Hex;
  amount: bigint;
}

interface Transaction {
  txHash: Hex;
  type: 'shield' | 'unshield' | 'transfer';
  direction: 'incoming' | 'outgoing';
  status: 'pending' | 'preconfirmed' | 'completed' | 'failed' | 'blocked';
  tokenAddress?: Hex;
  amount?: bigint;
  receivers: ReceiverTransfer[];
  createdAt: number;
  updatedAt: number;
  to?: Hex;
  from?: Hex;
  error?: string;
  tokenSymbol?: string;
  commitment?: Hex;
  complianceStatus?: ComplianceStatus;  // 'PENDING' | 'LEGIT' | 'ILLICIT'
}

interface TokenBalance {
  tokenAddress: Hex;
  /** Private balance held in the shielded pool, in token wei. */
  shieldedBalance: bigint;
  /** Public balance in the connected wallet, in token wei. */
  walletBalance: bigint;
  symbol?: string;
  decimals?: number;
  /** Number of unspent notes contributing to `shieldedBalance`. */
  noteCount?: number;
}

type OnProgress = (progress: {
  step: ShieldStep | UnshieldStep;
  message: string;
  txHash?: Hex;
}) => void;