@thetechfossil/auth2 1.2.1 → 1.2.2

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.
package/README.NEW.md ADDED
@@ -0,0 +1,365 @@
1
+ # Auth SDK - Complete Authentication Solution
2
+
3
+ A production-ready authentication SDK with a Clerk.js-like developer experience. Works with React, Next.js (App Router & Pages Router), and Node.js.
4
+
5
+ ## ✨ Features
6
+
7
+ - 🎨 **Pre-built UI Components** - Drop-in auth components (SignIn, SignUp, UserButton, etc.)
8
+ - 🔐 **Automatic Auth Handling** - No need to write auth logic, API calls, or state management
9
+ - 🚀 **Zero Config** - Configure via environment variables, no code changes needed
10
+ - 🎯 **Type-Safe** - Full TypeScript support with comprehensive type definitions
11
+ - 🔄 **Auto Redirects** - Automatic redirects after login, logout, registration, etc.
12
+ - 🛡️ **Route Protection** - Built-in components for protecting routes
13
+ - 🌐 **Universal** - Works with React, Next.js (client & server), and Node.js
14
+ - 📱 **Responsive** - Mobile-first design for all components
15
+ - ♿ **Accessible** - WCAG 2.1 AA compliant components
16
+ - 🎨 **Customizable** - Style components to match your brand
17
+
18
+ ## 📦 Installation
19
+
20
+ ```bash
21
+ npm install @thetechfossil/auth2
22
+ # or
23
+ pnpm add @thetechfossil/auth2
24
+ # or
25
+ yarn add @thetechfossil/auth2
26
+ ```
27
+
28
+ ## 🚀 Quick Start
29
+
30
+ ### 1. Configure Environment
31
+
32
+ Create `.env.local` (Next.js) or `.env` (React):
33
+
34
+ ```env
35
+ # Required
36
+ NEXT_PUBLIC_AUTH_API_URL=http://localhost:7000
37
+ NEXT_PUBLIC_FRONTEND_BASE_URL=http://localhost:3000
38
+
39
+ # Optional - Customize redirects
40
+ NEXT_PUBLIC_AUTH_REDIRECT_AFTER_LOGIN=/dashboard
41
+ NEXT_PUBLIC_AUTH_REDIRECT_AFTER_LOGOUT=/auth/login
42
+ ```
43
+
44
+ ### 2. Add AuthProvider
45
+
46
+ #### Next.js App Router
47
+
48
+ ```tsx
49
+ // app/layout.tsx
50
+ import { AuthProvider } from '@thetechfossil/auth2';
51
+
52
+ export default function RootLayout({ children }) {
53
+ return (
54
+ <html>
55
+ <body>
56
+ <AuthProvider>{children}</AuthProvider>
57
+ </body>
58
+ </html>
59
+ );
60
+ }
61
+ ```
62
+
63
+ #### React
64
+
65
+ ```tsx
66
+ // src/App.tsx
67
+ import { AuthProvider } from '@thetechfossil/auth2';
68
+
69
+ function App() {
70
+ return (
71
+ <AuthProvider>
72
+ {/* Your app */}
73
+ </AuthProvider>
74
+ );
75
+ }
76
+ ```
77
+
78
+ ### 3. Use Components
79
+
80
+ ```tsx
81
+ // Login page
82
+ import { SignIn } from '@thetechfossil/auth2';
83
+ export default function LoginPage() {
84
+ return <SignIn />;
85
+ }
86
+
87
+ // Protected dashboard
88
+ import { ProtectedRoute, UserButton } from '@thetechfossil/auth2';
89
+ export default function Dashboard() {
90
+ return (
91
+ <ProtectedRoute>
92
+ <UserButton showName />
93
+ <h1>Dashboard</h1>
94
+ </ProtectedRoute>
95
+ );
96
+ }
97
+ ```
98
+
99
+ **That's it!** Your authentication is fully functional.
100
+
101
+ ## 📚 Documentation
102
+
103
+ - **[Quick Start Guide](./QUICKSTART.md)** - Get started in 3 steps
104
+ - **[Complete Documentation](./README-CLERK-LIKE.md)** - Full API reference and examples
105
+ - **[Migration Guide](./MIGRATION-GUIDE.md)** - Migrate from old API to new API
106
+ - **[Implementation Summary](./IMPLEMENTATION-SUMMARY.md)** - Architecture and design decisions
107
+
108
+ ## 🎯 Components
109
+
110
+ ### Client Components
111
+
112
+ | Component | Description |
113
+ |-----------|-------------|
114
+ | `<SignIn />` | Pre-built login form with email/password and OTP |
115
+ | `<SignUp />` | Pre-built registration form with validation |
116
+ | `<SignOut />` | Sign out component (auto-redirects) |
117
+ | `<UserButton />` | User avatar dropdown with profile and sign-out |
118
+ | `<ProtectedRoute>` | Wrap protected content (auto-redirects if not authenticated) |
119
+ | `<PublicRoute>` | Wrap public pages (auto-redirects if authenticated) |
120
+ | `<VerifyEmail />` | Email verification handler |
121
+ | `<ForgotPassword />` | Password reset request form |
122
+ | `<ResetPassword />` | Password reset form |
123
+
124
+ ### Hooks
125
+
126
+ ```tsx
127
+ import { useAuth } from '@thetechfossil/auth2';
128
+
129
+ const {
130
+ user, // Current user object
131
+ isSignedIn, // Boolean: is user authenticated?
132
+ isLoaded, // Boolean: is auth state loaded?
133
+ loading, // Boolean: is an auth operation in progress?
134
+ signIn, // Function: sign in user
135
+ signUp, // Function: register new user
136
+ signOut, // Function: sign out user
137
+ verify, // Function: verify OTP
138
+ updateProfile, // Function: update user profile
139
+ forgotPassword, // Function: request password reset
140
+ resetPassword, // Function: reset password
141
+ } = useAuth();
142
+ ```
143
+
144
+ ### Server-Side (Next.js)
145
+
146
+ ```tsx
147
+ // Server Components
148
+ import { currentUser, auth, requireAuth } from '@thetechfossil/auth2/next/server';
149
+
150
+ // Get current user (returns null if not authenticated)
151
+ const user = await currentUser();
152
+
153
+ // Get auth state
154
+ const { user, isAuthenticated } = await auth();
155
+
156
+ // Require authentication (auto-redirects if not authenticated)
157
+ const user = await requireAuth();
158
+ ```
159
+
160
+ ### Middleware (Next.js)
161
+
162
+ ```ts
163
+ // middleware.ts
164
+ import { authMiddleware } from '@thetechfossil/auth2/next/server';
165
+
166
+ export default authMiddleware({
167
+ publicRoutes: ['/auth/*', '/'],
168
+ protectedRoutes: ['/dashboard/*'],
169
+ });
170
+
171
+ export const config = {
172
+ matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
173
+ };
174
+ ```
175
+
176
+ ## 🎨 Customization
177
+
178
+ ### Custom Styling
179
+
180
+ ```tsx
181
+ <SignIn
182
+ appearance={{
183
+ elements: {
184
+ card: { backgroundColor: '#f5f5f5' },
185
+ formButtonPrimary: { backgroundColor: '#10b981' },
186
+ headerTitle: { color: '#1f2937' },
187
+ },
188
+ }}
189
+ />
190
+ ```
191
+
192
+ ### Custom Redirects
193
+
194
+ ```tsx
195
+ <SignIn redirectUrl="/custom-dashboard" />
196
+ <ProtectedRoute redirectTo="/custom-login">
197
+ <Content />
198
+ </ProtectedRoute>
199
+ ```
200
+
201
+ ## 🌍 Environment Variables
202
+
203
+ | Variable | Description | Default |
204
+ |----------|-------------|---------|
205
+ | `NEXT_PUBLIC_AUTH_API_URL` | Auth backend URL | `http://localhost:7000` |
206
+ | `NEXT_PUBLIC_FRONTEND_BASE_URL` | Frontend base URL | `window.location.origin` |
207
+ | `NEXT_PUBLIC_AUTH_REDIRECT_AFTER_LOGIN` | Redirect after login | `/dashboard` |
208
+ | `NEXT_PUBLIC_AUTH_REDIRECT_AFTER_LOGOUT` | Redirect after logout | `/` |
209
+ | `NEXT_PUBLIC_AUTH_REDIRECT_AFTER_REGISTER` | Redirect after registration | `/dashboard` |
210
+ | `NEXT_PUBLIC_AUTH_REDIRECT_AFTER_VERIFY` | Redirect after email verification | `/dashboard` |
211
+ | `NEXT_PUBLIC_AUTH_REDIRECT_TO_LOGIN` | Login page path | `/auth/login` |
212
+
213
+ For React (non-Next.js), use `REACT_APP_` prefix instead of `NEXT_PUBLIC_`.
214
+
215
+ ## 📖 Examples
216
+
217
+ ### Complete Next.js App
218
+
219
+ See [`example/clerk-like-nextjs-example.tsx`](./example/clerk-like-nextjs-example.tsx) for a complete Next.js implementation with:
220
+ - All auth pages (login, register, verify, forgot password, reset password)
221
+ - Protected dashboard with UserButton
222
+ - Server Components examples
223
+ - API route examples
224
+ - Middleware configuration
225
+
226
+ ### Complete React App
227
+
228
+ See [`example/clerk-like-react-example.tsx`](./example/clerk-like-react-example.tsx) for a complete React implementation with:
229
+ - React Router setup
230
+ - All auth pages
231
+ - Protected routes
232
+ - Custom components with useAuth
233
+
234
+ ## 🔄 Migration from Old API
235
+
236
+ If you're using the old API, see the [Migration Guide](./MIGRATION-GUIDE.md).
237
+
238
+ **Good news:** The old API still works! No breaking changes.
239
+
240
+ ```tsx
241
+ // Old API (still works)
242
+ import { useAuthLegacy, LoginForm, RegisterForm } from '@thetechfossil/auth2';
243
+
244
+ // New API (recommended)
245
+ import { useAuth, SignIn, SignUp } from '@thetechfossil/auth2';
246
+ ```
247
+
248
+ ## 🏗️ Architecture
249
+
250
+ ```
251
+ Frontend App
252
+
253
+ <AuthProvider> ← Manages global auth state
254
+
255
+ Components & Hooks ← Pre-built UI & useAuth()
256
+
257
+ AuthService ← Core auth logic
258
+
259
+ HttpClient ← API communication
260
+
261
+ Auth Backend API ← Your auth server
262
+ ```
263
+
264
+ ## 🎯 Use Cases
265
+
266
+ ### Simple Login Page
267
+
268
+ ```tsx
269
+ import { SignIn } from '@thetechfossil/auth2';
270
+
271
+ export default function LoginPage() {
272
+ return <SignIn />;
273
+ }
274
+ ```
275
+
276
+ ### Protected Dashboard
277
+
278
+ ```tsx
279
+ import { ProtectedRoute, UserButton, useAuth } from '@thetechfossil/auth2';
280
+
281
+ export default function Dashboard() {
282
+ const { user } = useAuth();
283
+
284
+ return (
285
+ <ProtectedRoute>
286
+ <nav>
287
+ <h1>My App</h1>
288
+ <UserButton showName />
289
+ </nav>
290
+ <main>
291
+ <h2>Welcome, {user?.name}!</h2>
292
+ </main>
293
+ </ProtectedRoute>
294
+ );
295
+ }
296
+ ```
297
+
298
+ ### Custom Auth Component
299
+
300
+ ```tsx
301
+ import { useAuth } from '@thetechfossil/auth2';
302
+
303
+ function CustomAuth() {
304
+ const { isSignedIn, user, signOut } = useAuth();
305
+
306
+ if (!isSignedIn) {
307
+ return <a href="/auth/login">Sign In</a>;
308
+ }
309
+
310
+ return (
311
+ <div>
312
+ <span>Hello, {user.name}</span>
313
+ <button onClick={signOut}>Sign Out</button>
314
+ </div>
315
+ );
316
+ }
317
+ ```
318
+
319
+ ### Server Component (Next.js)
320
+
321
+ ```tsx
322
+ import { currentUser } from '@thetechfossil/auth2/next/server';
323
+
324
+ export default async function ProfilePage() {
325
+ const user = await currentUser();
326
+
327
+ if (!user) {
328
+ return <div>Please log in</div>;
329
+ }
330
+
331
+ return <div>Welcome, {user.name}!</div>;
332
+ }
333
+ ```
334
+
335
+ ## 🤝 Contributing
336
+
337
+ Contributions are welcome! Please read our contributing guidelines.
338
+
339
+ ## 📄 License
340
+
341
+ MIT
342
+
343
+ ## 🆘 Support
344
+
345
+ - 📖 [Documentation](./README-CLERK-LIKE.md)
346
+ - 🚀 [Quick Start](./QUICKSTART.md)
347
+ - 🔄 [Migration Guide](./MIGRATION-GUIDE.md)
348
+ - 💡 [Examples](./example/)
349
+
350
+ ## 🎉 What Makes This Different?
351
+
352
+ Unlike traditional auth libraries, this SDK:
353
+
354
+ - ✅ **No boilerplate** - Just install and use
355
+ - ✅ **No API calls to write** - All handled automatically
356
+ - ✅ **No state management** - Built-in context provider
357
+ - ✅ **No redirect logic** - Automatic based on env vars
358
+ - ✅ **No form validation** - Built into components
359
+ - ✅ **No token management** - Automatic storage and refresh
360
+
361
+ Just focus on building your app, not authentication!
362
+
363
+ ---
364
+
365
+ Made with ❤️ for developers who want authentication to "just work"
@@ -1,4 +1,4 @@
1
- import React from 'react';
1
+ import React, { ReactNode } from 'react';
2
2
 
3
3
  interface LoginFormProps {
4
4
  onSuccess?: (response: {
@@ -59,4 +59,114 @@ interface EmailVerificationPageProps {
59
59
  }
60
60
  declare const EmailVerificationPage: React.FC<EmailVerificationPageProps>;
61
61
 
62
- export { AuthFlow, EmailVerificationPage, LoginForm, OtpForm, RegisterForm };
62
+ interface SignInProps {
63
+ redirectUrl?: string;
64
+ appearance?: {
65
+ elements?: {
66
+ formButtonPrimary?: React.CSSProperties;
67
+ card?: React.CSSProperties;
68
+ headerTitle?: React.CSSProperties;
69
+ formFieldInput?: React.CSSProperties;
70
+ };
71
+ };
72
+ routing?: 'path' | 'virtual';
73
+ path?: string;
74
+ }
75
+ declare const SignIn: React.FC<SignInProps>;
76
+
77
+ interface SignUpProps {
78
+ redirectUrl?: string;
79
+ appearance?: {
80
+ elements?: {
81
+ formButtonPrimary?: React.CSSProperties;
82
+ card?: React.CSSProperties;
83
+ headerTitle?: React.CSSProperties;
84
+ formFieldInput?: React.CSSProperties;
85
+ };
86
+ };
87
+ }
88
+ declare const SignUp: React.FC<SignUpProps>;
89
+
90
+ interface SignOutProps {
91
+ redirectUrl?: string;
92
+ }
93
+ declare const SignOut: React.FC<SignOutProps>;
94
+
95
+ interface UserButtonProps {
96
+ showName?: boolean;
97
+ appearance?: {
98
+ elements?: {
99
+ userButtonBox?: React.CSSProperties;
100
+ userButtonTrigger?: React.CSSProperties;
101
+ userButtonPopoverCard?: React.CSSProperties;
102
+ };
103
+ };
104
+ }
105
+ declare const UserButton: React.FC<UserButtonProps>;
106
+
107
+ interface ProtectedRouteProps {
108
+ children: ReactNode;
109
+ fallback?: ReactNode;
110
+ redirectTo?: string;
111
+ }
112
+ declare const ProtectedRoute: React.FC<ProtectedRouteProps>;
113
+
114
+ interface PublicRouteProps {
115
+ children: ReactNode;
116
+ redirectTo?: string;
117
+ }
118
+ declare const PublicRoute: React.FC<PublicRouteProps>;
119
+
120
+ interface VerifyEmailProps {
121
+ token?: string;
122
+ onSuccess?: () => void;
123
+ onError?: (error: string) => void;
124
+ }
125
+ declare const VerifyEmail: React.FC<VerifyEmailProps>;
126
+
127
+ interface ForgotPasswordProps {
128
+ appearance?: {
129
+ elements?: {
130
+ formButtonPrimary?: React.CSSProperties;
131
+ card?: React.CSSProperties;
132
+ headerTitle?: React.CSSProperties;
133
+ formFieldInput?: React.CSSProperties;
134
+ };
135
+ };
136
+ }
137
+ declare const ForgotPassword: React.FC<ForgotPasswordProps>;
138
+
139
+ interface ResetPasswordProps {
140
+ token?: string;
141
+ appearance?: {
142
+ elements?: {
143
+ formButtonPrimary?: React.CSSProperties;
144
+ card?: React.CSSProperties;
145
+ headerTitle?: React.CSSProperties;
146
+ formFieldInput?: React.CSSProperties;
147
+ };
148
+ };
149
+ }
150
+ declare const ResetPassword: React.FC<ResetPasswordProps>;
151
+
152
+ interface ChangePasswordProps {
153
+ onSuccess?: () => void;
154
+ appearance?: {
155
+ elements?: {
156
+ formButtonPrimary?: React.CSSProperties;
157
+ card?: React.CSSProperties;
158
+ headerTitle?: React.CSSProperties;
159
+ formFieldInput?: React.CSSProperties;
160
+ };
161
+ };
162
+ }
163
+ declare const ChangePassword: React.FC<ChangePasswordProps>;
164
+
165
+ interface UserProfileProps {
166
+ showAvatar?: boolean;
167
+ showEmailChange?: boolean;
168
+ showPasswordChange?: boolean;
169
+ }
170
+ declare const UserProfile: React.FC<UserProfileProps>;
171
+
172
+ export { AuthFlow, ChangePassword, EmailVerificationPage, ForgotPassword, LoginForm, OtpForm, ProtectedRoute, PublicRoute, RegisterForm, ResetPassword, SignIn, SignOut, SignUp, UserButton, UserProfile, VerifyEmail };