Skip to main content

Hooks

Midnight Auth provides React hooks for programmatic access to wallet state and operations. All hooks are fully typed with TypeScript.

useMidnightAuth​

Core authentication hook providing connection state and wallet operations.

Returns​

interface MidnightAuthContextValue {
  // Connection state
  isConnected: boolean
  isConnecting: boolean
  walletState: WalletState | null
  error: string | null
  
  // Session state
  session: Session | null
  
  // Core methods
  connect: () => Promise<void>
  disconnect: () => void
  clearError: () => void
  
  // Session methods
  refreshSession: () => Promise<void>
  updateSessionMetadata: (metadata: Record<string, any>) => void
  
  // Wallet API access
  getWalletAPI: () => any | null
  
  // Transaction methods
  signData?: (address: string, payload: string) => Promise<SignDataResult>
  submitTransaction?: (tx: any) => Promise<TransactionResult>
}

Usage​

import { useMidnightAuth } from '@uppzen/midnight-auth'

export default function MyComponent() {
  const {
    isConnected,
    isConnecting,
    walletState,
    error,
    session,
    connect,
    disconnect,
    clearError,
    refreshSession,
    updateSessionMetadata,
    getWalletAPI,
    signData,
    submitTransaction
  } = useMidnightAuth()

  if (isConnecting) {
    return <div>Connecting...</div>
  }

  if (error) {
    return (
      <div>
        <p>Error: {error}</p>
        <button onClick={clearError}>Clear Error</button>
      </div>
    )
  }

  if (!isConnected) {
    return <button onClick={connect}>Connect Wallet</button>
  }

  return (
    <div>
      <p>Connected: {walletState?.address}</p>
      <button onClick={disconnect}>Disconnect</button>
      <button onClick={refreshSession}>Refresh Session</button>
    </div>
  )
}

Connection Management​

const { connect, disconnect, isConnecting } = useMidnightAuth()

// Connect to wallet
await connect()

// Disconnect from wallet
disconnect()

// Check connection status
if (isConnecting) {
  console.log('Connection in progress...')
}

Error Handling​

const { error, clearError } = useMidnightAuth()

if (error) {
  console.error('Authentication error:', error)
  // Clear the error
  clearError()
}

useMidnightWallet​

Simplified hook for wallet data and helper functions.

Returns​

interface MidnightWalletHook {
  // Wallet data
  address: string | undefined
  legacyAddress: string | undefined
  balance: string | undefined
  balances: BalanceBreakdown | undefined
  provider: string | undefined
  walletState: WalletState | null
  
  // Connection state
  isConnected: boolean
  isConnecting: boolean
  
  // Methods
  refreshBalance: () => Promise<void>
  signData?: (address: string, payload: string) => Promise<SignDataResult>
  submitTransaction?: (tx: any) => Promise<TransactionResult>
}

Usage​

import { useMidnightWallet } from '@uppzen/midnight-auth'

export default function WalletDisplay() {
  const {
    address,
    legacyAddress,
    balance,
    balances,
    provider,
    isConnected,
    refreshBalance,
    signData,
    submitTransaction
  } = useMidnightWallet()

  if (!isConnected) {
    return <p>Wallet not connected</p>
  }

  return (
    <div>
      <h2>Wallet Information</h2>
      <p>Address: {address}</p>
      <p>Legacy Address: {legacyAddress}</p>
      <p>Provider: {provider}</p>
      
      {balances && (
        <div>
          <p>Total Balance: {balances.total}</p>
          <p>Shielded: {balances.shielded}</p>
          <p>Unshielded: {balances.unshielded}</p>
        </div>
      )}
      
      <button onClick={refreshBalance}>Refresh Balance</button>
    </div>
  )
}

Signing Data​

const { address, signData } = useMidnightWallet()

const handleSign = async () => {
  if (!address || !signData) return
  
  try {
    const result = await signData(address, 'Message to sign')
    console.log('Signature:', result.signature)
    console.log('Key:', result.key)
  } catch (error) {
    console.error('Signing failed:', error)
  }
}

Submitting Transactions​

const { submitTransaction } = useMidnightWallet()

const handleTransaction = async () => {
  if (!submitTransaction) return
  
  try {
    const tx = {
      // Your transaction object
      to: '0x...',
      value: '1000000000000000000'
    }
    
    const result = await submitTransaction(tx)
    
    if (result.success) {
      console.log('Transaction hash:', result.txHash)
    }
  } catch (error) {
    console.error('Transaction failed:', error)
  }
}

useMidnightSession​

Session management and expiration tracking.

Returns​

interface MidnightSessionHook {
  session: Session | null
  isExpired: boolean
  timeRemaining: number
  refreshSession: () => Promise<void>
}

Usage​

import { useMidnightSession } from '@uppzen/midnight-auth'

export default function SessionStatus() {
  const { 
    session, 
    isExpired, 
    timeRemaining, 
    refreshSession 
  } = useMidnightSession()

  if (!session) {
    return <p>No active session</p>
  }

  const formatTime = (ms: number) => {
    const hours = Math.floor(ms / (1000 * 60 * 60))
    const minutes = Math.floor((ms % (1000 * 60 * 60)) / (1000 * 60))
    return `${hours}h ${minutes}m`
  }

  return (
    <div>
      <p>Connected: {new Date(session.connectedAt).toLocaleString()}</p>
      
      {isExpired ? (
        <p className="text-red-500">Session expired</p>
      ) : (
        <p>Time remaining: {formatTime(timeRemaining)}</p>
      )}
      
      <button onClick={refreshSession}>
        Refresh Session
      </button>
    </div>
  )
}

Auto-refresh on Expiration​

import { useMidnightSession } from '@uppzen/midnight-auth'
import { useEffect } from 'react'

export default function AutoRefreshSession() {
  const { isExpired, refreshSession } = useMidnightSession()

  useEffect(() => {
    if (isExpired) {
      refreshSession()
    }
  }, [isExpired, refreshSession])

  return <div>Session auto-refresh enabled</div>
}

Session Metadata​

import { useMidnightAuth } from '@uppzen/midnight-auth'

export default function SessionMetadata() {
  const { session, updateSessionMetadata } = useMidnightAuth()

  const addMetadata = () => {
    updateSessionMetadata({
      lastActivity: Date.now(),
      userPreferences: { theme: 'dark' }
    })
  }

  return (
    <div>
      {session?.metadata && (
        <pre>{JSON.stringify(session.metadata, null, 2)}</pre>
      )}
      <button onClick={addMetadata}>Add Metadata</button>
    </div>
  )
}

Hook Composition​

Combine hooks for complex functionality:

import { 
  useMidnightAuth, 
  useMidnightWallet, 
  useMidnightSession 
} from '@uppzen/midnight-auth'

export default function CompleteWalletInfo() {
  const { isConnected, error } = useMidnightAuth()
  const { address, balances } = useMidnightWallet()
  const { timeRemaining, refreshSession } = useMidnightSession()

  if (error) return <div>Error: {error}</div>
  if (!isConnected) return <div>Not connected</div>

  return (
    <div>
      <p>Address: {address}</p>
      <p>Balance: {balances?.total}</p>
      <p>Session: {Math.floor(timeRemaining / 60000)} minutes</p>
      <button onClick={refreshSession}>Refresh</button>
    </div>
  )
}

Best Practices​

1. Check Connection State​

Always check isConnected before accessing wallet data:

const { isConnected, address } = useMidnightWallet()

if (isConnected && address) {
  // Safe to use address
}

2. Handle Loading States​

Show loading indicators during connection:

const { isConnecting } = useMidnightAuth()

if (isConnecting) {
  return <LoadingSpinner />
}

3. Error Boundaries​

Wrap components using hooks in error boundaries:

<ErrorBoundary>
  <ComponentUsingHooks />
</ErrorBoundary>

4. Cleanup​

Hooks automatically clean up on unmount, but you can manually disconnect:

useEffect(() => {
  return () => {
    // Optional: disconnect on unmount
    disconnect()
  }
}, [])

Next Steps​