insforge 1.3.0 → 1.4.8

package/docs/core-concepts/authentication/sdk.mdx

@@ -16,27 +16,45 @@ Create a new user account with email and password.
 - `email` (string, required) - User's email address
 - `password` (string, required) - User's password
 - `name` (string, optional) - User's display name
+- `options` (object, optional) - Additional options
+  - `emailRedirectTo` (string, optional) - Custom URL to redirect to after email verification. It's a fallback if you didn't set default redirect URL configured in your dashboard.
 
 ### Returns
 
 ```typescript
 {
   data: {
-    user: { id, email, name, emailVerified, createdAt, updatedAt },
-    accessToken: string
+    user?: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata },
+    accessToken: string | null,
+    requireEmailVerification?: boolean,
+    redirectTo?: string,
+    csrfToken?: string | null
   } | null,
   error: Error | null
 }
 ```
 
+<Note>
+  When `requireEmailVerification` is true, `accessToken` will be null until the user verifies their email. InsForge sends a verification email with either a link or a 6-digit code, based on your dashboard configuration (`verifyEmailMethod`). For code verification, implement a page that prompts the user to enter the code (see [verifyEmail()](#verifyemail)). For link verification, redirect users to the sign-in page—the insforge backend handles verification automatically when the link is clicked.
+</Note>
+
 ### Example
 
 ```javascript
 const { data, error } = await insforge.auth.signUp({
   email: 'user@example.com',
   password: 'secure_password123',
-  name: 'John Doe'
-})
+  name: 'John Doe',
+});
+
+if (data?.requireEmailVerification) {
+  // For code verification: redirect to page where user enters the 6-digit code
+  // For link verification: redirect to sign-in page to await email link click
+  console.log('Please verify your email');
+} else if (data?.accessToken) {
+  // User is signed in (email verification disabled)
+  console.log('Welcome!', data.user.email);
+}
 ```
 
 ### Output
@@ -47,12 +65,20 @@ const { data, error } = await insforge.auth.signUp({
     "user": {
       "id": "usr_abc123",
       "email": "user@example.com",
-      "name": "John Doe",
       "emailVerified": false,
+      "providers": ["email"],
       "createdAt": "2024-01-15T10:00:00Z",
-      "updatedAt": "2024-01-15T10:00:00Z"
+      "updatedAt": "2024-01-15T10:00:00Z",
+      "profile": {
+        "name": "John Doe",
+        "avatar_url": null
+      },
+      "metadata": {}
     },
-    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+    "requireEmailVerification": true,
+    "accessToken": null,
+    "redirectTo": "https://app.example.com/verify-email",
+    "csrfToken": null
   },
   "error": null
 }
@@ -74,8 +100,10 @@ Sign in an existing user with email and password.
 ```typescript
 {
   data: {
-    user: { id, email, name, emailVerified, createdAt, updatedAt },
-    accessToken: string
+    user: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata },
+    accessToken: string,
+    redirectTo?: string,
+    csrfToken?: string | null
   } | null,
   error: Error | null
 }
@@ -86,8 +114,16 @@ Sign in an existing user with email and password.
 ```javascript
 const { data, error } = await insforge.auth.signInWithPassword({
   email: 'user@example.com',
-  password: 'secure_password123'
-})
+  password: 'secure_password123',
+});
+
+if (data) {
+  console.log('Signed in as:', data.user.email);
+  // Optional: redirect to configured URL
+  if (data.redirectTo) {
+    window.location.href = data.redirectTo;
+  }
+}
 ```
 
 ### Output
@@ -98,12 +134,19 @@ const { data, error } = await insforge.auth.signInWithPassword({
     "user": {
       "id": "usr_abc123",
       "email": "user@example.com",
-      "name": "John Doe",
       "emailVerified": true,
+      "providers": ["email"],
       "createdAt": "2024-01-15T10:00:00Z",
-      "updatedAt": "2024-01-15T10:00:00Z"
+      "updatedAt": "2024-01-15T10:00:00Z",
+      "profile": {
+        "name": "John Doe",
+        "avatar_url": "https://example.com/avatar.jpg"
+      },
+      "metadata": {}
     },
-    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "redirectTo": "https://app.example.com/dashboard",
+    "csrfToken": "5758d38259fb..."
   },
   "error": null
 }
@@ -131,7 +174,8 @@ Start OAuth authentication flow with supported providers (Google, GitHub, Micros
 ```
 
 <Note>
-After OAuth redirect, SDK automatically detects callback parameters and saves session. No manual handling needed.
+  After OAuth redirect, SDK automatically detects callback parameters and saves session. No manual
+  handling needed.
 </Note>
 
 ### Example
@@ -140,17 +184,17 @@ After OAuth redirect, SDK automatically detects callback parameters and saves se
 // Default: auto-redirect
 await insforge.auth.signInWithOAuth({
   provider: 'google',
-  redirectTo: 'http://localhost:3000/dashboard'
-})
+  redirectTo: 'http://localhost:3000/dashboard',
+});
 // Browser immediately redirects to Google
 
 // skipBrowserRedirect: get URL for manual handling
 const { data } = await insforge.auth.signInWithOAuth({
   provider: 'google',
-  skipBrowserRedirect: true
-})
+  skipBrowserRedirect: true,
+});
 
-window.location.href = data.url // Redirect when ready
+window.location.href = data.url; // Redirect when ready
 ```
 
 ### Output
@@ -179,14 +223,14 @@ None
 
 ```typescript
 {
-  error: Error | null
+  error: Error | null;
 }
 ```
 
 ### Example
 
 ```javascript
-const { error } = await insforge.auth.signOut()
+const { error } = await insforge.auth.signOut();
 ```
 
 ### Output
@@ -199,9 +243,9 @@ const { error } = await insforge.auth.signOut()
 
 ---
 
-## getCurrentUser()
+## getCurrentSession()
 
-Get authenticated user with profile data from users table.
+Get the current session. If no active session exists, attempts to refresh using the httpOnly cookie. Call this on app initialization to restore user sessions automatically.
 
 ### Parameters
 
@@ -212,8 +256,80 @@ None
 ```typescript
 {
   data: {
-    user: { id, email, role },
-    profile: { id, nickname, avatar_url, bio, birthday, ... }
+    session: {
+      accessToken: string,
+      user: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata },
+      expiresAt?: Date
+    } | null
+  },
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.getCurrentSession();
+
+if (data.session) {
+  console.log('Token:', data.session.accessToken);
+  console.log('User:', data.session.user.email);
+
+  // Check if session is expired
+  if (data.session.expiresAt && new Date() > data.session.expiresAt) {
+    console.log('Session expired');
+  }
+}
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "session": {
+      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+      "expiresAt": "2024-01-22T10:00:00.000Z",
+      "user": {
+        "id": "usr_abc123",
+        "email": "user@example.com",
+        "emailVerified": true,
+        "createdAt": "2024-01-15T10:00:00Z",
+        "updatedAt": "2024-01-15T10:00:00Z",
+        "providers": ["email"],
+        "profile": {
+          "name": "John Doe",
+          "avatar_url": "https://example.com/avatar.jpg"
+        },
+        "metadata": {}
+      }
+    }
+  },
+  "error": null
+}
+```
+
+---
+
+## getProfile()
+
+Get any user's public profile by ID. Returns a flat profile object with all fields at the top level.
+
+### Parameters
+
+- `userId` (string, required) - User ID to fetch profile for
+
+### Returns
+
+```typescript
+{
+  data: {
+    id: string,
+    name?: string,
+    avatar_url?: string,
+    createdAt?: string,
+    updatedAt?: string,
+    ...customFields
   } | null,
   error: Error | null
 }
@@ -222,31 +338,198 @@ None
 ### Example
 
 ```javascript
-const { data, error } = await insforge.auth.getCurrentUser()
+const { data, error } = await insforge.auth.getProfile('usr_xyz789');
 
 if (data) {
-  console.log(data.user.email)        // Auth info
-  console.log(data.profile.nickname)  // Profile from users table
+  console.log(data.name);
+  console.log(data.avatar_url);
+}
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "id": "usr_xyz789",
+    "name": "John Doe",
+    "avatar_url": "https://example.com/avatar.jpg",
+    "bio": "Full-stack developer",
+    "createdAt": "2024-01-15T10:00:00Z",
+    "updatedAt": "2024-01-15T10:00:00Z"
+  },
+  "error": null
+}
+```
+
+---
+
+## setProfile()
+
+Update current user's profile in users table. Supports any dynamic fields and returns the updated profile as a flat object.
+
+### Parameters
+
+- `profile` (object) - A key-value map of profile fields to update. Any fields are accepted.
+
+**Common fields:**
+
+- `name` (predefined, string) - User's display name
+- `avatar_url` (predefined, string) - Profile picture URL
+
+### Returns
+
+```typescript
+{
+  data: {
+    id: string,
+    name?: string,
+    avatar_url?: string,
+    createdAt?: string,
+    updatedAt?: string,
+    ...customFields
+  } | null,
+  error: Error | null
 }
 ```
 
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.setProfile({
+  name: 'JohnDev',
+  bio: 'Full-stack developer',
+  avatar_url: 'https://example.com/avatar.jpg',
+  custom_field: 'any value', // Any custom fields are supported
+});
+```
+
 ### Output
 
 ```json
 {
   "data": {
+    "id": "usr_abc123",
+    "name": "JohnDev",
+    "avatar_url": "https://example.com/avatar.jpg",
+    "bio": "Full-stack developer",
+    "custom_field": "any value",
+    "createdAt": "2024-01-15T10:00:00Z",
+    "updatedAt": "2024-01-15T12:30:00Z"
+  },
+  "error": null
+}
+```
+
+---
+
+## resendVerificationEmail()
+
+Resend email verification when the previous OTP has expired or was not received. Uses the method configured in auth settings (`verifyEmailMethod`). When method is `code`, sends a 6-digit numeric code. When method is `link`, sends a magic link.
+
+<Note>
+  This endpoint prevents user enumeration by returning success even if the email doesn't exist.
+</Note>
+
+### Parameters
+
+- `email` (string, required) - User's email address
+- `options` (object, optional) - Additional options
+  - `emailRedirectTo` (string, optional) - Custom URL to redirect to after email verification. It's a fallback if you didn't set default redirect URL configured in your dashboard.
+
+### Returns
+
+```typescript
+{
+  data: { success: boolean, message: string } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.resendVerificationEmail({
+  email: 'user@example.com',
+});
+
+if (data?.success) {
+  console.log('Verification email sent!');
+}
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "success": true,
+    "message": "Verification email sent"
+  },
+  "error": null
+}
+```
+
+---
+
+## verifyEmail()
+
+Verify email address using the method configured in auth settings (`verifyEmailMethod`):
+- **Code verification**: Provide both `email` and `otp` (6-digit numeric code)
+- **Link verification**: Provide only `otp` (64-character hex token from magic link)
+
+Successfully verified users will receive a session token.
+
+### Parameters
+
+- `email` (string, optional) - User's email address (required for code verification)
+- `otp` (string, required) - 6-digit code or 64-character token from magic link
+
+### Returns
+
+```typescript
+{
+  data: {
+    accessToken: string,
+    user: { id, email, emailVerified, ... },
+    redirectTo?: string
+  } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+// Code verification (when verifyEmailMethod is 'code')
+const { data, error } = await insforge.auth.verifyEmail({
+  email: 'user@example.com',
+  otp: '123456',
+});
+
+// Link verification (when verifyEmailMethod is 'link')
+// Token is extracted from the magic link URL
+const { data, error } = await insforge.auth.verifyEmail({
+  otp: 'a1b2c3d4e5f6...', // 64-character token from URL
+});
+
+if (data) {
+  console.log('Email verified!', data.accessToken);
+}
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "user": {
       "id": "usr_abc123",
       "email": "user@example.com",
-      "role": "authenticated"
+      "emailVerified": true
     },
-    "profile": {
-      "id": "usr_abc123",
-      "nickname": "JohnDoe",
-      "avatar_url": "https://example.com/avatar.jpg",
-      "bio": "Full-stack developer",
-      "birthday": "1990-01-01"
-    }
+    "redirectTo": "https://app.example.com/dashboard"
   },
   "error": null
 }
@@ -254,24 +537,23 @@ if (data) {
 
 ---
 
-## getCurrentSession()
+## sendResetPasswordEmail()
 
-Get current session from local storage (no API call).
+Send password reset email using the method configured in auth settings (`resetPasswordMethod`). When method is `code`, sends a 6-digit numeric code for two-step flow. When method is `link`, sends a magic link.
+
+<Note>
+  This endpoint prevents user enumeration by returning success even if the email doesn't exist.
+</Note>
 
 ### Parameters
 
-None
+- `email` (string, required) - User's email address
 
 ### Returns
 
 ```typescript
 {
-  data: {
-    session: {
-      accessToken: string,
-      user: { id, email, name, ... }
-    } | null
-  },
+  data: { success: boolean, message: string } | null,
   error: Error | null
 }
 ```
@@ -279,10 +561,12 @@ None
 ### Example
 
 ```javascript
-const { data, error } = await insforge.auth.getCurrentSession()
+const { data, error } = await insforge.auth.sendResetPasswordEmail({
+  email: 'user@example.com',
+});
 
-if (data.session) {
-  console.log('Token:', data.session.accessToken)
+if (data?.success) {
+  console.log('Password reset email sent!');
 }
 ```
 
@@ -291,14 +575,8 @@ if (data.session) {
 ```json
 {
   "data": {
-    "session": {
-      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-      "user": {
-        "id": "usr_abc123",
-        "email": "user@example.com",
-        "name": "John Doe"
-      }
-    }
+    "success": true,
+    "message": "Password reset email sent"
   },
   "error": null
 }
@@ -306,19 +584,24 @@ if (data.session) {
 
 ---
 
-## getProfile()
+## exchangeResetPasswordToken()
+
+Exchange a 6-digit reset password code for a reset token. This is step 1 of the two-step password reset flow (only used when `resetPasswordMethod` is `code`).
 
-Get any user's public profile by ID.
+<Note>
+  This endpoint is not used when `resetPasswordMethod` is `link` (magic link flow is direct).
+</Note>
 
 ### Parameters
 
-- `userId` (string, required) - User ID to fetch profile for
+- `email` (string, required) - User's email address
+- `code` (string, required) - 6-digit code from the email
 
 ### Returns
 
 ```typescript
 {
-  data: { id, nickname, avatar_url, bio, birthday, ... } | null,
+  data: { token: string, expiresAt: string } | null,
   error: Error | null
 }
 ```
@@ -326,9 +609,18 @@ Get any user's public profile by ID.
 ### Example
 
 ```javascript
-const { data: profile, error } = await insforge.auth.getProfile('usr_xyz789')
+const { data, error } = await insforge.auth.exchangeResetPasswordToken({
+  email: 'user@example.com',
+  code: '123456',
+});
 
-console.log(profile.nickname)
+if (data) {
+  // Use token to reset password
+  await insforge.auth.resetPassword({
+    newPassword: 'newSecurePassword123',
+    otp: data.token,
+  });
+}
 ```
 
 ### Output
@@ -336,11 +628,8 @@ console.log(profile.nickname)
 ```json
 {
   "data": {
-    "id": "usr_xyz789",
-    "nickname": "JaneDoe",
-    "avatar_url": "https://example.com/jane.jpg",
-    "bio": "Designer and developer",
-    "birthday": "1992-05-15"
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "expiresAt": "2024-01-15T11:00:00Z"
   },
   "error": null
 }
@@ -348,22 +637,22 @@ console.log(profile.nickname)
 
 ---
 
-## setProfile()
+## resetPassword()
 
-Update current user's profile in users table.
+Reset user password with a token. The token can be:
+- **Magic link token**: 64-character hex token from `sendResetPasswordEmail` when method is `link`
+- **Reset token**: From `exchangeResetPasswordToken` after code verification when method is `code`
 
 ### Parameters
 
-- `nickname` (string, optional) - User's display name
-- `avatar_url` (string, optional) - Profile picture URL
-- `bio` (string, optional) - User biography
-- `birthday` (string, optional) - Birth date (YYYY-MM-DD format)
+- `newPassword` (string, required) - New password for the user
+- `otp` (string, required) - Reset token or magic link token
 
 ### Returns
 
 ```typescript
 {
-  data: { id, nickname, avatar_url, bio, birthday, ... } | null,
+  data: { message: string, redirectTo?: string } | null,
   error: Error | null
 }
 ```
@@ -371,11 +660,21 @@ Update current user's profile in users table.
 ### Example
 
 ```javascript
-const { data: profile, error } = await insforge.auth.setProfile({
-  nickname: 'JohnDev',
-  bio: 'Full-stack developer',
-  avatar_url: 'https://example.com/avatar.jpg'
-})
+// Code method flow: after exchangeResetPasswordToken
+const { data, error } = await insforge.auth.resetPassword({
+  newPassword: 'newSecurePassword123',
+  otp: resetToken, // Token from exchangeResetPasswordToken
+});
+
+// Link method flow: token from URL params
+const { data, error } = await insforge.auth.resetPassword({
+  newPassword: 'newSecurePassword123',
+  otp: 'a1b2c3d4e5f6...', // 64-character token from magic link URL
+});
+
+if (data) {
+  console.log('Password reset successful!');
+}
 ```
 
 ### Output
@@ -383,11 +682,8 @@ const { data: profile, error } = await insforge.auth.setProfile({
 ```json
 {
   "data": {
-    "id": "usr_abc123",
-    "nickname": "JohnDev",
-    "avatar_url": "https://example.com/avatar.jpg",
-    "bio": "Full-stack developer",
-    "birthday": null
+    "message": "Password reset successfully",
+    "redirectTo": "https://app.example.com/login"
   },
   "error": null
 }
@@ -402,13 +698,13 @@ All auth methods return structured errors:
 ```javascript
 const { data, error } = await insforge.auth.signInWithPassword({
   email: 'user@example.com',
-  password: 'wrong_password'
-})
+  password: 'wrong_password',
+});
 
 if (error) {
-  console.error(error.statusCode)    // 401
-  console.error(error.error)         // 'INVALID_CREDENTIALS'
-  console.error(error.message)       // 'Invalid login credentials'
-  console.error(error.nextActions)   // 'Check email and password'
+  console.error(error.statusCode); // 401
+  console.error(error.error); // 'INVALID_CREDENTIALS'
+  console.error(error.message); // 'Invalid login credentials'
+  console.error(error.nextActions); // 'Check email and password'
 }
 ```