From de5c358e4414b5177d7c52fbb988b3580c208804 Mon Sep 17 00:00:00 2001 From: tarai-dl Date: Fri, 17 Apr 2026 02:28:14 -0400 Subject: [PATCH] feat: Add .cursor/rules/echo_rules.mdc to all templates Add Cursor IDE rules for Echo SDK usage guidelines to all template directories. Each template has tailored rules based on its framework (Next.js, React, CLI, etc.). Closes #636 --- .../assistant-ui/.cursor/rules/echo_rules.mdc | 169 +++++++++++++++++ templates/authjs/.cursor/rules/echo_rules.mdc | 177 ++++++++++++++++++ .../echo-cli/.cursor/rules/echo_rules.mdc | 168 +++++++++++++++++ .../next-chat/.cursor/rules/echo_rules.mdc | 176 +++++++++++++++++ .../next-image/.cursor/rules/echo_rules.mdc | 176 +++++++++++++++++ .../.cursor/rules/echo_rules.mdc | 176 +++++++++++++++++ templates/next/.cursor/rules/echo_rules.mdc | 176 +++++++++++++++++ .../.cursor/rules/echo_rules.mdc | 176 +++++++++++++++++ .../react-chat/.cursor/rules/echo_rules.mdc | 170 +++++++++++++++++ .../react-image/.cursor/rules/echo_rules.mdc | 170 +++++++++++++++++ templates/react/.cursor/rules/echo_rules.mdc | 170 +++++++++++++++++ 11 files changed, 1904 insertions(+) create mode 100644 templates/assistant-ui/.cursor/rules/echo_rules.mdc create mode 100644 templates/authjs/.cursor/rules/echo_rules.mdc create mode 100644 templates/echo-cli/.cursor/rules/echo_rules.mdc create mode 100644 templates/next-chat/.cursor/rules/echo_rules.mdc create mode 100644 templates/next-image/.cursor/rules/echo_rules.mdc create mode 100644 templates/next-video-template/.cursor/rules/echo_rules.mdc create mode 100644 templates/next/.cursor/rules/echo_rules.mdc create mode 100644 templates/nextjs-api-key-template/.cursor/rules/echo_rules.mdc create mode 100644 templates/react-chat/.cursor/rules/echo_rules.mdc create mode 100644 templates/react-image/.cursor/rules/echo_rules.mdc create mode 100644 templates/react/.cursor/rules/echo_rules.mdc diff --git a/templates/assistant-ui/.cursor/rules/echo_rules.mdc b/templates/assistant-ui/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..5c8b080de --- /dev/null +++ b/templates/assistant-ui/.cursor/rules/echo_rules.mdc @@ -0,0 +1,169 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## Assistant UI Specific Guidelines + +### Chat Interface Integration +- Use Echo providers with Assistant UI components +- Implement streaming for real-time responses +- Handle conversation history properly + +### Message Handling +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { useAssistant } from '@assistant-ui/react'; + +function Chat() { + const { openai } = useEchoModelProviders(); + const { messages, append } = useAssistant({ + api: '/api/chat', + body: { + model: openai('gpt-5'), + }, + }); + + // Render messages +} +``` + +### Customization +- Style Assistant UI components to match your app +- Add custom message types if needed +- Implement file upload and processing + +### Performance +- Use virtualization for long conversations +- Implement pagination for message history +- Cache model responses when appropriate diff --git a/templates/authjs/.cursor/rules/echo_rules.mdc b/templates/authjs/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..75db245bc --- /dev/null +++ b/templates/authjs/.cursor/rules/echo_rules.mdc @@ -0,0 +1,177 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## Auth.js (NextAuth) Specific Guidelines + +### Provider Configuration +- Configure Echo as an Auth.js provider +- Handle OAuth callbacks properly +- Manage session and JWT tokens + +### Setup Example +```typescript +import { EchoProvider } from '@merit-systems/echo-auth-js-provider'; + +export const authOptions = { + providers: [ + EchoProvider({ + clientId: process.env.ECHO_CLIENT_ID, + clientSecret: process.env.ECHO_CLIENT_SECRET, + }), + ], + callbacks: { + async jwt({ token, account }) { + if (account) { + token.accessToken = account.access_token; + } + return token; + }, + async session({ session, token }) { + session.accessToken = token.accessToken; + return session; + }, + }, +}; +``` + +### Session Management +- Use JWT for session management +- Refresh tokens automatically +- Handle logout properly + +### Security +- Validate tokens on each request +- Implement CSRF protection +- Use secure cookies for production diff --git a/templates/echo-cli/.cursor/rules/echo_rules.mdc b/templates/echo-cli/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..270a17557 --- /dev/null +++ b/templates/echo-cli/.cursor/rules/echo_rules.mdc @@ -0,0 +1,168 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## CLI Specific Guidelines + +### Command Structure +- Use Commander.js for CLI argument parsing +- Implement interactive prompts for user input +- Handle authentication tokens securely + +### API Key Management +```typescript +import { EchoCLI } from '@merit-systems/echo-cli-sdk'; + +const cli = new EchoCLI({ + appId: process.env.ECHO_APP_ID, + // Store tokens securely in user config +}); + +// Authenticate user +await cli.authenticate(); + +// Make AI calls +const response = await cli.chat('Hello, how are you?'); +console.log(response); +``` + +### Configuration Files +- Store user preferences in `~/.echo/config.json` +- Cache authentication tokens securely +- Log usage for debugging + +### Error Handling +- Provide clear error messages for CLI users +- Implement retry logic for network errors +- Handle authentication expiration gracefully diff --git a/templates/next-chat/.cursor/rules/echo_rules.mdc b/templates/next-chat/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..dae460732 --- /dev/null +++ b/templates/next-chat/.cursor/rules/echo_rules.mdc @@ -0,0 +1,176 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## Next.js Specific Guidelines + +### App Router Integration +- Use `createEchoServerClient` for server components +- Implement API routes with Echo authentication +- Use middleware for route protection + +### Server Components +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +export default async function Page() { + const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID!, + appSecret: process.env.ECHO_APP_SECRET!, + }); + + const models = await echoClient.getAvailableModels(); + return
Available models: {models.length}
; +} +``` + +### API Routes +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function POST(request: Request) { + const session = await echoAuth(request); + if (!session) { + return Response.json({ error: 'Unauthorized' }, { status: 401 }); + } + + const { prompt } = await request.json(); + // Use session.accessToken with Echo model providers +} +``` + +### Environment Variables +- `ECHO_APP_ID`: Your Echo application ID +- `ECHO_APP_SECRET`: Your Echo application secret +- `NEXT_PUBLIC_ECHO_APP_ID`: Public app ID for client-side diff --git a/templates/next-image/.cursor/rules/echo_rules.mdc b/templates/next-image/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..dae460732 --- /dev/null +++ b/templates/next-image/.cursor/rules/echo_rules.mdc @@ -0,0 +1,176 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## Next.js Specific Guidelines + +### App Router Integration +- Use `createEchoServerClient` for server components +- Implement API routes with Echo authentication +- Use middleware for route protection + +### Server Components +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +export default async function Page() { + const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID!, + appSecret: process.env.ECHO_APP_SECRET!, + }); + + const models = await echoClient.getAvailableModels(); + return
Available models: {models.length}
; +} +``` + +### API Routes +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function POST(request: Request) { + const session = await echoAuth(request); + if (!session) { + return Response.json({ error: 'Unauthorized' }, { status: 401 }); + } + + const { prompt } = await request.json(); + // Use session.accessToken with Echo model providers +} +``` + +### Environment Variables +- `ECHO_APP_ID`: Your Echo application ID +- `ECHO_APP_SECRET`: Your Echo application secret +- `NEXT_PUBLIC_ECHO_APP_ID`: Public app ID for client-side diff --git a/templates/next-video-template/.cursor/rules/echo_rules.mdc b/templates/next-video-template/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..dae460732 --- /dev/null +++ b/templates/next-video-template/.cursor/rules/echo_rules.mdc @@ -0,0 +1,176 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## Next.js Specific Guidelines + +### App Router Integration +- Use `createEchoServerClient` for server components +- Implement API routes with Echo authentication +- Use middleware for route protection + +### Server Components +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +export default async function Page() { + const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID!, + appSecret: process.env.ECHO_APP_SECRET!, + }); + + const models = await echoClient.getAvailableModels(); + return
Available models: {models.length}
; +} +``` + +### API Routes +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function POST(request: Request) { + const session = await echoAuth(request); + if (!session) { + return Response.json({ error: 'Unauthorized' }, { status: 401 }); + } + + const { prompt } = await request.json(); + // Use session.accessToken with Echo model providers +} +``` + +### Environment Variables +- `ECHO_APP_ID`: Your Echo application ID +- `ECHO_APP_SECRET`: Your Echo application secret +- `NEXT_PUBLIC_ECHO_APP_ID`: Public app ID for client-side diff --git a/templates/next/.cursor/rules/echo_rules.mdc b/templates/next/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..dae460732 --- /dev/null +++ b/templates/next/.cursor/rules/echo_rules.mdc @@ -0,0 +1,176 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## Next.js Specific Guidelines + +### App Router Integration +- Use `createEchoServerClient` for server components +- Implement API routes with Echo authentication +- Use middleware for route protection + +### Server Components +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +export default async function Page() { + const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID!, + appSecret: process.env.ECHO_APP_SECRET!, + }); + + const models = await echoClient.getAvailableModels(); + return
Available models: {models.length}
; +} +``` + +### API Routes +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function POST(request: Request) { + const session = await echoAuth(request); + if (!session) { + return Response.json({ error: 'Unauthorized' }, { status: 401 }); + } + + const { prompt } = await request.json(); + // Use session.accessToken with Echo model providers +} +``` + +### Environment Variables +- `ECHO_APP_ID`: Your Echo application ID +- `ECHO_APP_SECRET`: Your Echo application secret +- `NEXT_PUBLIC_ECHO_APP_ID`: Public app ID for client-side diff --git a/templates/nextjs-api-key-template/.cursor/rules/echo_rules.mdc b/templates/nextjs-api-key-template/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..dae460732 --- /dev/null +++ b/templates/nextjs-api-key-template/.cursor/rules/echo_rules.mdc @@ -0,0 +1,176 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## Next.js Specific Guidelines + +### App Router Integration +- Use `createEchoServerClient` for server components +- Implement API routes with Echo authentication +- Use middleware for route protection + +### Server Components +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +export default async function Page() { + const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID!, + appSecret: process.env.ECHO_APP_SECRET!, + }); + + const models = await echoClient.getAvailableModels(); + return
Available models: {models.length}
; +} +``` + +### API Routes +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function POST(request: Request) { + const session = await echoAuth(request); + if (!session) { + return Response.json({ error: 'Unauthorized' }, { status: 401 }); + } + + const { prompt } = await request.json(); + // Use session.accessToken with Echo model providers +} +``` + +### Environment Variables +- `ECHO_APP_ID`: Your Echo application ID +- `ECHO_APP_SECRET`: Your Echo application secret +- `NEXT_PUBLIC_ECHO_APP_ID`: Public app ID for client-side diff --git a/templates/react-chat/.cursor/rules/echo_rules.mdc b/templates/react-chat/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..3e4503e52 --- /dev/null +++ b/templates/react-chat/.cursor/rules/echo_rules.mdc @@ -0,0 +1,170 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## React (Vite) Specific Guidelines + +### Provider Setup +- Wrap your app with `EchoProvider` at the root +- Use `useEchoModelProviders` hook for AI operations +- Handle loading and error states properly + +### Component Structure +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; +import { useState } from 'react'; + +function App() { + const [isAuthenticated, setIsAuthenticated] = useState(false); + + return ( + + {isAuthenticated ? : } + + ); +} +``` + +### State Management +- Use React context for Echo state +- Handle authentication state changes +- Manage loading states during API calls + +### Vite Configuration +- Ensure environment variables are prefixed with `VITE_` +- Configure CORS for development +- Set up proxy for API calls if needed diff --git a/templates/react-image/.cursor/rules/echo_rules.mdc b/templates/react-image/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..3e4503e52 --- /dev/null +++ b/templates/react-image/.cursor/rules/echo_rules.mdc @@ -0,0 +1,170 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## React (Vite) Specific Guidelines + +### Provider Setup +- Wrap your app with `EchoProvider` at the root +- Use `useEchoModelProviders` hook for AI operations +- Handle loading and error states properly + +### Component Structure +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; +import { useState } from 'react'; + +function App() { + const [isAuthenticated, setIsAuthenticated] = useState(false); + + return ( + + {isAuthenticated ? : } + + ); +} +``` + +### State Management +- Use React context for Echo state +- Handle authentication state changes +- Manage loading states during API calls + +### Vite Configuration +- Ensure environment variables are prefixed with `VITE_` +- Configure CORS for development +- Set up proxy for API calls if needed diff --git a/templates/react/.cursor/rules/echo_rules.mdc b/templates/react/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..3e4503e52 --- /dev/null +++ b/templates/react/.cursor/rules/echo_rules.mdc @@ -0,0 +1,170 @@ +--- +description: Guidelines and best practices for building applications with Echo, the user-pays AI infrastructure +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Guidelines + +## Overview +Echo is a user-pays AI infrastructure that allows developers to integrate AI without fronting API costs. Users authenticate once, get a balance, and pay for their own usage. Developers set a markup and earn revenue automatically. + +## Core Concepts + +### How Echo Works +1. **User Authentication**: Users authenticate via OAuth to get a universal balance across all Echo apps +2. **Model Providers**: Replace AI SDK imports with Echo's model providers +3. **Automatic Billing**: Users pay providers directly through Echo, developers never proxy requests or front bills +4. **Revenue Generation**: Set a markup percentage, every token generates profit automatically + +### Key Benefits +- **No hosting costs**: Users pay providers directly +- **Better UX**: One OAuth login replaces complex BYOK flows +- **Instant revenue**: Set markup percentage for automatic profit +- **Zero infrastructure**: No payment processing, usage tracking, or key validation needed + +## SDK Usage + +### React SDK +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { generateText } from 'ai'; + +const { openai } = useEchoModelProviders(); +const response = await generateText({ + model: openai('gpt-5'), + prompt: '...', +}); +``` + +### Next.js SDK +```typescript +import { createEchoServerClient } from '@merit-systems/echo-next-sdk'; + +const echoClient = createEchoServerClient({ + appId: process.env.ECHO_APP_ID, + appSecret: process.env.ECHO_APP_SECRET, +}); +``` + +## Best Practices + +### Authentication +- Always use Echo's OAuth flow for user authentication +- Never store user API keys - Echo handles this automatically +- Use the universal balance system for cross-app compatibility + +### Model Provider Usage +- Import model providers from Echo SDK, not directly from AI providers +- Use the same AI SDK functions (generateText, streamText, etc.) with Echo providers +- Let Echo handle rate limiting and usage tracking + +### Revenue Configuration +- Set appropriate markup percentages in the Echo dashboard +- Monitor usage and adjust pricing as needed +- Use Echo's analytics to understand user behavior + +### Error Handling +- Handle authentication errors gracefully +- Provide clear error messages for insufficient balance +- Implement retry logic for transient failures + +## Common Patterns + +### Setting Up Echo Provider (React) +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; + +function App() { + return ( + + {/* Your app components */} + + ); +} +``` + +### Server-Side Integration (Next.js) +```typescript +import { echoAuth } from '@merit-systems/echo-next-sdk'; + +export async function GET(request: Request) { + const session = await echoAuth(request); + if (!session) { + return new Response('Unauthorized', { status: 401 }); + } + // Use session.user and session.accessToken +} +``` + +### Streaming Responses +```typescript +import { useEchoModelProviders } from '@merit-systems/echo-react-sdk'; +import { streamText } from 'ai'; + +const { openai } = useEchoModelProviders(); + +const { textStream } = streamText({ + model: openai('gpt-5'), + prompt: 'Write a story about...', +}); + +for await (const textPart of textStream) { + process.stdout.write(textPart); +} +``` + +## Troubleshooting + +### Common Issues +1. **Authentication Failed**: Check app ID and secret configuration +2. **Insufficient Balance**: User needs to top up their Echo balance +3. **Rate Limiting**: Echo handles this automatically, but check for 429 errors +4. **Model Not Available**: Verify model is supported in your Echo plan + +### Debugging Tips +- Check browser console for authentication errors +- Verify environment variables are set correctly +- Use Echo's dashboard to monitor usage and errors +- Test with a small balance first before production deployment + +## Resources +- [Echo Documentation](https://echo.merit.systems/docs) +- [Echo Dashboard](https://echo.merit.systems/dashboard) +- [GitHub Repository](https://github.com/Merit-Systems/echo) +- [Discord Community](https://discord.gg/merit) + +## React (Vite) Specific Guidelines + +### Provider Setup +- Wrap your app with `EchoProvider` at the root +- Use `useEchoModelProviders` hook for AI operations +- Handle loading and error states properly + +### Component Structure +```typescript +import { EchoProvider } from '@merit-systems/echo-react-sdk'; +import { useState } from 'react'; + +function App() { + const [isAuthenticated, setIsAuthenticated] = useState(false); + + return ( + + {isAuthenticated ? : } + + ); +} +``` + +### State Management +- Use React context for Echo state +- Handle authentication state changes +- Manage loading states during API calls + +### Vite Configuration +- Ensure environment variables are prefixed with `VITE_` +- Configure CORS for development +- Set up proxy for API calls if needed