Merge pull request #60 from InsForge/auth-fix

Auth SDK update for OSS v2.0.2

Author: Fermionic-Lyu

README.md

@@ -46,7 +46,8 @@ const insforge = createClient({
 const { data, error } = await insforge.auth.signUp({
   email: 'user@example.com',
   password: 'securePassword123',
-  name: 'John Doe' // optional
+  name: 'John Doe', // optional
+  redirectTo: 'http://localhost:3000/sign-in' // optional, recommended for link-based verification
 });
 
 // Sign in with email/password
@@ -61,8 +62,8 @@ await insforge.auth.signInWithOAuth({
   redirectTo: 'http://localhost:3000/dashboard'
 });
 
-// Get current user
-const { data: user } = await insforge.auth.getCurrentUser();
+// Get current user (call this during browser app startup)
+const { data: currentUser } = await insforge.auth.getCurrentUser();
 
 // Get any user's profile by ID (public endpoint)
 const { data: profile, error } = await insforge.auth.getProfile('user-id-here');
@@ -78,6 +79,51 @@ const { data: updatedProfile, error } = await insforge.auth.setProfile({
 await insforge.auth.signOut();
 ```
 
+### Email Verification And Password Reset
+
+```javascript
+// Resend a verification email
+await insforge.auth.resendVerificationEmail({
+  email: 'user@example.com',
+  redirectTo: 'http://localhost:3000/sign-in' // optional, recommended for link-based verification
+});
+
+// Verify email with a 6-digit code
+await insforge.auth.verifyEmail({
+  email: 'user@example.com',
+  otp: '123456'
+});
+
+// Send password reset email
+await insforge.auth.sendResetPasswordEmail({
+  email: 'user@example.com',
+  redirectTo: 'http://localhost:3000/reset-password' // optional, recommended for link-based reset
+});
+
+// Code-based reset flow: exchange the code, then reset the password
+const { data: resetToken } = await insforge.auth.exchangeResetPasswordToken({
+  email: 'user@example.com',
+  code: '123456'
+});
+
+if (resetToken) {
+  await insforge.auth.resetPassword({
+    newPassword: 'newSecurePassword123',
+    otp: resetToken.token
+  });
+}
+```
+
+For link-based verification and password reset, users click the emailed browser links:
+- `GET /api/auth/email/verify-link`
+- `GET /api/auth/email/reset-password-link`
+
+Those backend endpoints validate the token first, then redirect the browser to your `redirectTo` URL.
+
+- Verification links redirect with `insforge_status=success|error`, `insforge_type=verify_email`, and optional `insforge_error`
+- Recommended: use your sign-in page as the verification `redirectTo`, then show a confirmation message and ask the user to sign in with email and password
+- Reset links redirect with `token` when ready, plus `insforge_status=ready|error`, `insforge_type=reset_password`, and optional `insforge_error`
+
 ### Database Operations
 
 ```javascript
@@ -201,14 +247,14 @@ const insforge = createClient({
 The SDK is written in TypeScript and provides full type definitions:
 
 ```typescript
-import { createClient, InsForgeClient, User, Session } from '@insforge/sdk';
+import { createClient, InsForgeClient } from '@insforge/sdk';
 
 const insforge: InsForgeClient = createClient({
   baseUrl: 'http://localhost:7130'
 });
 
 // Type-safe API calls
-const response: { data: User | null; error: Error | null } =
+const response =
   await insforge.auth.getCurrentUser();
 ```
 

SDK-REFERENCE.md

@@ -40,9 +40,9 @@ The SDK automatically detects and handles OAuth callback parameters when initial
 
 **How it works:**
 1. User calls `signInWithOAuth()` and is redirected to OAuth provider
-2. After authentication, provider redirects back to your app with tokens in URL
-3. SDK automatically detects these parameters on initialization
-4. Session is saved and URL is cleaned - no manual handling needed!
+2. After authentication, InsForge redirects back to your app with an `insforge_code` in the URL
+3. SDK automatically exchanges that code for a session on initialization
+4. Session is saved and the URL is cleaned - no manual handling needed
 
 **Example:**
 ```javascript
@@ -52,11 +52,12 @@ const insforge = createClient({
 });
 
 // If the URL contains OAuth callback parameters like:
-// ?access_token=xxx&user_id=yyy&email=user@example.com&name=John
+// ?insforge_code=...
 // The SDK will:
+// - Exchange the code for a session
 // - Save the session in memory
 // - Set the auth token for API calls
-// - Clean the URL (remove sensitive parameters)
+// - Clean the URL
 
 // You can then immediately use authenticated methods:
 const { data } = await insforge.auth.getCurrentUser();
@@ -69,13 +70,23 @@ const { data } = await insforge.auth.getCurrentUser();
 await insforge.auth.signUp({
   email: 'user@example.com',
   password: 'password123',
-  name: 'John Doe'  // optional
+  name: 'John Doe',  // optional
+  redirectTo: 'http://localhost:3000/sign-in' // optional, recommended for link-based verification
 })
 // Response: { data: { user, accessToken }, error }
 // user: { id, email, name, emailVerified, createdAt, updatedAt }
 // accessToken: JWT token string
 ```
 
+If the backend uses link-based email verification, the emailed link opens:
+
+```text
+GET /api/auth/email/verify-link?token=...
+```
+
+InsForge validates the token first, then redirects the browser to your `redirectTo` URL.
+Recommended: use your sign-in page as `redirectTo`, then show a success message and ask the user to sign in with email and password.
+
 ### `signInWithPassword()`
 ```javascript
 await insforge.auth.signInWithPassword({
@@ -99,9 +110,10 @@ await insforge.auth.signInWithOAuth({
 
 // AUTOMATIC OAuth Callback Detection (v0.0.14+):
 // When users are redirected back from OAuth provider, the SDK automatically:
-// 1. Detects OAuth parameters (access_token, user_id, email, name) in URL
-// 2. Saves the session in memory
-// 3. Cleans the URL of sensitive parameters
+// 1. Detects insforge_code in the URL
+// 2. Exchanges the code for a session
+// 3. Saves the session in memory
+// 4. Cleans the URL
 // No manual handling needed - just initialize the client!
 ```
 
@@ -115,12 +127,15 @@ await insforge.auth.signOut()
 ### `getCurrentUser()`
 ```javascript
 await insforge.auth.getCurrentUser()
-// Response: { data: { user, profile }, error }
-// user: { id, email, role }  // Auth info from API
-// profile: { id, nickname, avatar_url, bio, birthday, ... }  // Profile from users table
+// Response: { data: { user }, error }
+// user: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata }
 // Returns null if not authenticated
 ```
 
+For browser apps, call `getCurrentUser()` during startup. The SDK will use the httpOnly refresh cookie automatically when it can refresh the session.
+
+For `isServerMode: true`, call `refreshSession({ refreshToken })` explicitly when you need to refresh an expired access token.
+
 ### `getProfile()`
 ```javascript
 await insforge.auth.getProfile(userId)
@@ -149,6 +164,64 @@ await insforge.auth.getPublicAuthConfig()
 // This is a public endpoint that doesn't require authentication
 ```
 
+### `resendVerificationEmail()`
+```javascript
+await insforge.auth.resendVerificationEmail({
+  email: 'user@example.com',
+  redirectTo: 'http://localhost:3000/sign-in' // optional, recommended for link-based verification
+})
+// Response: { data: { success, message }, error }
+```
+
+### `verifyEmail()`
+```javascript
+await insforge.auth.verifyEmail({
+  email: 'user@example.com',
+  otp: '123456'
+})
+// Response: { data: { user, accessToken, csrfToken?, refreshToken? }, error }
+// POST /api/auth/email/verify is code-only
+// Browser link verification uses GET /api/auth/email/verify-link
+// Verification redirect params:
+// - insforge_status=success|error
+// - insforge_type=verify_email
+// - insforge_error (only on error)
+```
+
+### `sendResetPasswordEmail()`
+```javascript
+await insforge.auth.sendResetPasswordEmail({
+  email: 'user@example.com',
+  redirectTo: 'http://localhost:3000/reset-password' // optional, recommended for link-based reset
+})
+// Response: { data: { success, message }, error }
+```
+
+### `exchangeResetPasswordToken()`
+```javascript
+await insforge.auth.exchangeResetPasswordToken({
+  email: 'user@example.com',
+  code: '123456'
+})
+// Response: { data: { token, expiresAt }, error }
+```
+
+### `resetPassword()`
+```javascript
+await insforge.auth.resetPassword({
+  newPassword: 'newSecurePassword123',
+  otp: 'reset-token'
+})
+// Response: { data: { message }, error }
+// Browser reset links use GET /api/auth/email/reset-password-link first,
+// then your app submits the new password with POST /api/auth/email/reset-password.
+// Reset redirect params:
+// - token (present only when ready)
+// - insforge_status=ready|error
+// - insforge_type=reset_password
+// - insforge_error (only on error)
+```
+
 ## Error Handling
 
 ### Auth/Storage/AI Errors (InsForgeError)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@insforge/sdk",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Official JavaScript/TypeScript client for InsForge Backend-as-a-Service platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -50,7 +50,7 @@
     "url": "https://github.com/InsForge/insforge-sdk-js/issues"
   },
   "dependencies": {
-    "@insforge/shared-schemas": "^1.1.44",
+    "@insforge/shared-schemas": "^1.1.46",
     "@supabase/postgrest-js": "^1.21.3",
     "socket.io-client": "^4.8.1"
   },