Hooks

useEcho

Primary hook for accessing authentication state, user information, and core functionality.

import { useEcho } from '@merit-systems/echo-react-sdk';

function AuthComponent() {
  const { 
    user, 
    isAuthenticated, 
    isLoading,
    error,
    signIn, 
    signOut,
    token,
    getToken
  } = useEcho();
  
  if (isLoading) {
    return <div>Loading...</div>;
  }
  
  if (error) {
    return <div>Error: {error}</div>;
  }
  
  if (!isAuthenticated) {
    return <button onClick={signIn}>Sign In</button>;
  }
  
  return (
    <div>
      <p>Welcome {user?.name || user?.email}!</p>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

EchoContextValue

The context value provided by EchoProvider, accessible via useEcho().

import type { EchoContextValue } from '@merit-systems/echo-react-sdk';

EchoContextValue

Prop	Type	Default
`rawUser`	`User \| null \| undefined`	-
`user`	`EchoUser \| null`	-
`balance`	`Balance \| null`	-
`freeTierBalance`	`FreeBalance \| null`	-
`isAuthenticated`	`boolean`	-
`isLoading`	`boolean`	-
`error`	`string \| null`	-
`token`	`string \| null`	-
`echoClient`	`EchoClient \| null`	-
`signIn`	`() => Promise<void>`	-
`signOut`	`() => Promise<void>`	-
`refreshBalance`	`() => Promise<void>`	-
`createPaymentLink`	`(amount: number, description?: string \| undefined, successUrl?: string \| undefined) => Promise<string>`	-
`getToken`	`() => Promise<string \| null>`	-
`clearAuth`	`() => Promise<void>`	-
`config`	`EchoConfig`	-
`isInsufficientFunds`	`boolean`	-
`setIsInsufficientFunds`	`(value: boolean) => void`	-

EchoUser

User information from OAuth2 authentication.

import type { EchoUser } from '@merit-systems/echo-react-sdk';

const { user } = useEcho();

EchoUser

Prop	Type	Default
`id`	`string`	-
`email`	`string`	-
`name?`	`string`	-
`picture?`	`string`	-
`totalPaid?`	`number`	-
`totalSpent?`	`number`	-
`createdAt`	`string`	-
`updatedAt`	`string`	-

useEchoClient

Provides access to the Echo TypeScript SDK client for platform operations.

import { useEchoClient } from '@merit-systems/echo-react-sdk';

const echoClient = useEchoClient({ 
  apiUrl: 'https://echo.merit.systems' 
});

// Access all TypeScript SDK functionality
const apps = await echoClient.apps.listEchoApps();
const balance = await echoClient.balance.getBalance();

useEchoClient provides a full Echo TypeScript SDK client instance, automatically authenticated using the current user's token.

Common operations:

echoClient.apps.* - App management
echoClient.balance.* - Balance operations
echoClient.payments.* - Payment links
echoClient.models.* - Model information
echoClient.users.* - User operations

useEchoModelProviders

Access LLM model providers for direct AI integration.

import { useEchoModelProviders } from '@merit-systems/echo-react-sdk';
import { generateText } from 'ai';

function AIComponent() {
  const { openai, anthropic } = useEchoModelProviders();
  
  const handleGenerate = async () => {
    const { text } = await generateText({
      model: openai('gpt-4'),
      prompt: 'Hello world'
    });
    
    return text;
  };
  
  return <button onClick={handleGenerate}>Generate</button>;
}

Balance Management

The useEcho hook provides balance management functionality:

const { balance, freeTierBalance, refreshBalance, createPaymentLink } = useEcho();

balance - Current account balance

<p>Balance: ${balance?.balance || 0}</p>
<p>Total Spent: ${balance?.totalSpent || 0}</p>

freeTierBalance - Free tier usage information

<p>Free Credits Remaining: ${freeTierBalance?.userSpendInfo.amountLeft || 0}</p>

refreshBalance() - Manually refresh balance data

<button onClick={refreshBalance}>Refresh Balance</button>

createPaymentLink() - Create Stripe payment links

const paymentUrl = await createPaymentLink(25, 'Credits', '/success');
window.location.href = paymentUrl;

Hooks

On this page