@merit-systems/echo-next-sdk 0.0.24-test.f38adbbe.0 → 0.0.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +242 -19
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,34 +1,257 @@
1
- # Echo TypeScript SDK
1
+ # Echo Next.js SDK
2
2
 
3
- The official TypeScript SDK for the Echo platform, providing easy access to Echo APIs and a command-line interface for managing your Echo applications.
3
+ The official Next.js SDK for the Echo platform, providing seamless authentication, AI provider integration, and easy access to Echo APIs in Next.js applications.
4
4
 
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
- pnpm install @merit-systems/echo-typescript-sdk
8
+ pnpm install @merit-systems/echo-next-sdk
9
9
  ```
10
10
 
11
- ## Programmatic Usage
11
+ ## Features
12
+
13
+ - **OAuth Authentication** - Complete authentication flow with automatic token management
14
+ - **AI Provider Integration** - Pre-configured OpenAI, Anthropic, and Google AI providers
15
+ - **Server & Client Components** - Support for both server-side and client-side usage
16
+ - **Automatic Token Refresh** - Handles token refresh automatically
17
+ - **TypeScript Support** - Full TypeScript support with type definitions
18
+ - **Cookie-based Sessions** - Secure HTTP-only cookie authentication
19
+
20
+ ## Quick Start
21
+
22
+ ### 1. Server Setup
23
+
24
+ Create an Echo instance in your server code:
12
25
 
13
26
  ```typescript
14
- import { EchoClient } from '@merit-systems/echo-typescript-sdk';
27
+ // src/echo/index.ts
28
+ import Echo from '@merit-systems/echo-next-sdk';
29
+
30
+ export const {
31
+ // Echo Auth Routes
32
+ handlers,
33
+
34
+ // Server-side utilities
35
+ getUser,
36
+ isSignedIn,
37
+ getEchoToken,
15
38
 
16
- // Initialize with API key
17
- const client = new EchoClient({
18
- apiKey: 'echo_your_api_key_here',
39
+ // AI Providers
40
+ openai,
41
+ anthropic,
42
+ google,
43
+ } = Echo({
44
+ appId: process.env.NEXT_PUBLIC_ECHO_APP_ID!,
19
45
  });
46
+ ```
20
47
 
21
- // Or use stored credentials from CLI
22
- const client = new EchoClient();
48
+ ### 2. API Route Setup
23
49
 
24
- // Get account balance
25
- const balance = await client.getBalance();
26
- console.log(`Balance: $${balance.balance}`);
50
+ Export the handlers in your API route:
27
51
 
28
- // Create a payment link
29
- const paymentResponse = await client.createPaymentLink({
30
- amount: 10.0, // $10.00
31
- description: 'Credits for my account',
32
- });
33
- console.log('Payment URL:', paymentResponse.paymentLink.url);
52
+ ```typescript
53
+ // app/api/echo/[...echo]/route.ts
54
+ import { handlers } from '@/echo';
55
+
56
+ export const { GET, POST } = handlers;
57
+ ```
58
+
59
+ This automatically sets up these authentication endpoints:
60
+
61
+ - `/api/echo/signin` - Initiates OAuth flow
62
+ - `/api/echo/callback` - OAuth callback handler
63
+ - `/api/echo/refresh` - Token refresh endpoint
64
+ - `/api/echo/session` - Session status endpoint
65
+ - `/api/echo/signout` - Sign out endpoint
66
+
67
+ ### 3. Client Provider Setup
68
+
69
+ Wrap your app with the Echo provider:
70
+
71
+ ```typescript
72
+ // providers.tsx
73
+ 'use client';
74
+
75
+ import { EchoProvider } from '@merit-systems/echo-next-sdk/client';
76
+
77
+ export function Providers({ children }: { children: React.ReactNode }) {
78
+ return (
79
+ <EchoProvider config={{ appId: process.env.NEXT_PUBLIC_ECHO_APP_ID! }}>
80
+ {children}
81
+ </EchoProvider>
82
+ );
83
+ }
84
+ ```
85
+
86
+ ```typescript
87
+ // app/layout.tsx
88
+ import { Providers } from './providers';
89
+
90
+ export default function RootLayout({
91
+ children,
92
+ }: {
93
+ children: React.ReactNode;
94
+ }) {
95
+ return (
96
+ <html lang="en">
97
+ <body>
98
+ <Providers>{children}</Providers>
99
+ </body>
100
+ </html>
101
+ );
102
+ }
103
+ ```
104
+
105
+ ## Usage
106
+
107
+ ### Server-Side Authentication
108
+
109
+ ```typescript
110
+ import { getUser, isSignedIn } from '@/echo';
111
+
112
+ export default async function Page() {
113
+ const signedIn = await isSignedIn();
114
+
115
+ if (!signedIn) {
116
+ return <SignInButton />;
117
+ }
118
+
119
+ const user = await getUser();
120
+ return <Dashboard user={user} />;
121
+ }
122
+ ```
123
+
124
+ ### Client-Side Hook
125
+
126
+ ```typescript
127
+ 'use client';
128
+
129
+ import { useEcho } from '@merit-systems/echo-next-sdk/client';
130
+
131
+ export default function MyComponent() {
132
+ const {
133
+ user,
134
+ balance,
135
+ freeTierBalance,
136
+ signIn,
137
+ signOut,
138
+ echoClient,
139
+ isLoading
140
+ } = useEcho();
141
+
142
+ if (isLoading) {
143
+ return <div>Loading...</div>;
144
+ }
145
+
146
+ if (!user) {
147
+ return <button onClick={signIn}>Sign In with Echo</button>;
148
+ }
149
+
150
+ return (
151
+ <div>
152
+ <p>Welcome {user.name}!</p>
153
+ <p>Balance: ${balance?.balance || 0}</p>
154
+ <button onClick={signOut}>Sign Out</button>
155
+ </div>
156
+ );
157
+ }
158
+ ```
159
+
160
+ ### AI Provider Integration
161
+
162
+ Use Echo-wrapped AI providers with automatic billing:
163
+
164
+ ```typescript
165
+ // app/api/chat/route.ts
166
+ import { openai } from '@/echo';
167
+ import { streamText, convertToModelMessages } from 'ai';
168
+
169
+ export async function POST(req: Request) {
170
+ const { messages } = await req.json();
171
+
172
+ const result = streamText({
173
+ model: openai('gpt-4o'),
174
+ messages: convertToModelMessages(messages),
175
+ });
176
+
177
+ return result.toUIMessageStreamResponse();
178
+ }
34
179
  ```
180
+
181
+ ### Direct API Access
182
+
183
+ Access the full Echo API through the client:
184
+
185
+ ```typescript
186
+ 'use client';
187
+
188
+ import { useEcho } from '@merit-systems/echo-next-sdk/client';
189
+
190
+ export default function PaymentComponent() {
191
+ const { echoClient } = useEcho();
192
+
193
+ const createPaymentLink = async () => {
194
+ if (!echoClient) return;
195
+
196
+ const paymentLink = await echoClient.payments.createPaymentLink({
197
+ amount: 10,
198
+ description: 'Credits for my account',
199
+ });
200
+
201
+ window.open(paymentLink.url, '_blank');
202
+ };
203
+
204
+ return <button onClick={createPaymentLink}>Add Credits</button>;
205
+ }
206
+ ```
207
+
208
+ ## Configuration
209
+
210
+ The Echo constructor accepts the following configuration:
211
+
212
+ | Option | Type | Required | Default | Description |
213
+ | ---------- | -------- | -------- | ----------- | ------------------------ |
214
+ | `appId` | `string` | ✅ | - | Your Echo App ID |
215
+ | `basePath` | `string` | ❌ | `/api/echo` | Base path for API routes |
216
+
217
+ ## Environment Variables
218
+
219
+ Set these environment variables in your `.env.local`:
220
+
221
+ ```bash
222
+ NEXT_PUBLIC_ECHO_APP_ID=your_echo_app_id_here
223
+ ```
224
+
225
+ ## Components
226
+
227
+ The SDK re-exports helpful components from the React SDK:
228
+
229
+ ```typescript
230
+ import {
231
+ EchoSignIn,
232
+ EchoSignOut,
233
+ EchoTokens,
234
+ InsufficientFundsModal,
235
+ } from '@merit-systems/echo-next-sdk/client';
236
+ ```
237
+
238
+ ## TypeScript Support
239
+
240
+ The SDK is built with TypeScript and provides full type definitions for all methods and responses. Import types as needed:
241
+
242
+ ```typescript
243
+ import type { EchoConfig, EchoResult } from '@merit-systems/echo-next-sdk';
244
+ ```
245
+
246
+ ## Documentation
247
+
248
+ For complete documentation and examples, visit:
249
+
250
+ - [Echo Next.js Documentation](https://echo.merit.systems/docs/next-sdk)
251
+ - [Getting Started Guide](https://echo.merit.systems/docs/getting-started/next-js)
252
+
253
+ ## Requirements
254
+
255
+ - Next.js 15.0.0 or higher
256
+ - React 18.0.0 or 19.0.0
257
+ - Node.js 18 or higher
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@merit-systems/echo-next-sdk",
3
- "version": "0.0.24-test.f38adbbe.0",
3
+ "version": "0.0.24",
4
4
  "description": "Next.js SDK for Echo",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -27,8 +27,8 @@
27
27
  "ai": "^5.0.17",
28
28
  "jwt-decode": "^4.0.0",
29
29
  "swr": "^2.3.1",
30
- "@merit-systems/echo-typescript-sdk": "1.0.17-test.f38adbbe.0",
31
- "@merit-systems/echo-react-sdk": "1.0.33-test.f38adbbe.0"
30
+ "@merit-systems/echo-typescript-sdk": "1.0.17",
31
+ "@merit-systems/echo-react-sdk": "1.0.33"
32
32
  },
33
33
  "peerDependencies": {
34
34
  "next": ">=15.0.0",