insforge 1.2.10 → 1.4.8

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

@@ -1,414 +1,710 @@
----
-title: Authentication SDK Reference
-description: User authentication and profile management with the InsForge SDK
----
-
-import Installation from '/snippets/sdk-installation.mdx';
-
-<Installation />
-
-## signUp()
-
-Create a new user account with email and password.
-
-### Parameters
-
-- `email` (string, required) - User's email address
-- `password` (string, required) - User's password
-- `name` (string, optional) - User's display name
-
-### Returns
-
-```typescript
-{
-  data: {
-    user: { id, email, name, emailVerified, createdAt, updatedAt },
-    accessToken: string
-  } | null,
-  error: Error | null
-}
-```
-
-### Example
-
-```javascript
-const { data, error } = await insforge.auth.signUp({
-  email: 'user@example.com',
-  password: 'secure_password123',
-  name: 'John Doe'
-})
-```
-
-### Output
-
-```json
-{
-  "data": {
-    "user": {
-      "id": "usr_abc123",
-      "email": "user@example.com",
-      "name": "John Doe",
-      "emailVerified": false,
-      "createdAt": "2024-01-15T10:00:00Z",
-      "updatedAt": "2024-01-15T10:00:00Z"
-    },
-    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-  },
-  "error": null
-}
-```
-
----
-
-## signInWithPassword()
-
-Sign in an existing user with email and password.
-
-### Parameters
-
-- `email` (string, required) - User's email address
-- `password` (string, required) - User's password
-
-### Returns
-
-```typescript
-{
-  data: {
-    user: { id, email, name, emailVerified, createdAt, updatedAt },
-    accessToken: string
-  } | null,
-  error: Error | null
-}
-```
-
-### Example
-
-```javascript
-const { data, error } = await insforge.auth.signInWithPassword({
-  email: 'user@example.com',
-  password: 'secure_password123'
-})
-```
-
-### Output
-
-```json
-{
-  "data": {
-    "user": {
-      "id": "usr_abc123",
-      "email": "user@example.com",
-      "name": "John Doe",
-      "emailVerified": true,
-      "createdAt": "2024-01-15T10:00:00Z",
-      "updatedAt": "2024-01-15T10:00:00Z"
-    },
-    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-  },
-  "error": null
-}
-```
-
----
-
-## signInWithOAuth()
-
-Start OAuth authentication flow with supported providers (Google, GitHub, Microsoft, Discord, and more).
-
-### Parameters
-
-- `provider` (string, required) - OAuth provider name (e.g., 'google', 'github', 'microsoft', 'discord')
-- `redirectTo` (string, optional) - URL to redirect after authentication
-- `skipBrowserRedirect` (boolean, optional) - If true, returns OAuth URL without auto-redirecting (for mobile apps)
-
-### Returns
-
-```typescript
-{
-  data: { url?: string, provider?: string },
-  error: Error | null
-}
-```
-
-<Note>
-After OAuth redirect, SDK automatically detects callback parameters and saves session. No manual handling needed.
-</Note>
-
-### Example
-
-```javascript
-// Default: auto-redirect
-await insforge.auth.signInWithOAuth({
-  provider: 'google',
-  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
-})
-
-window.location.href = data.url // Redirect when ready
-```
-
-### Output
-
-```json
-{
-  "data": {
-    "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...",
-    "provider": "google"
-  },
-  "error": null
-}
-```
-
----
-
-## signOut()
-
-Sign out the current user and clear session.
-
-### Parameters
-
-None
-
-### Returns
-
-```typescript
-{
-  error: Error | null
-}
-```
-
-### Example
-
-```javascript
-const { error } = await insforge.auth.signOut()
-```
-
-### Output
-
-```json
-{
-  "error": null
-}
-```
-
----
-
-## getCurrentUser()
-
-Get authenticated user with profile data from users table.
-
-### Parameters
-
-None
-
-### Returns
-
-```typescript
-{
-  data: {
-    user: { id, email, role },
-    profile: { id, nickname, avatar_url, bio, birthday, ... }
-  } | null,
-  error: Error | null
-}
-```
-
-### Example
-
-```javascript
-const { data, error } = await insforge.auth.getCurrentUser()
-
-if (data) {
-  console.log(data.user.email)        // Auth info
-  console.log(data.profile.nickname)  // Profile from users table
-}
-```
-
-### Output
-
-```json
-{
-  "data": {
-    "user": {
-      "id": "usr_abc123",
-      "email": "user@example.com",
-      "role": "authenticated"
-    },
-    "profile": {
-      "id": "usr_abc123",
-      "nickname": "JohnDoe",
-      "avatar_url": "https://example.com/avatar.jpg",
-      "bio": "Full-stack developer",
-      "birthday": "1990-01-01"
-    }
-  },
-  "error": null
-}
-```
-
----
-
-## getCurrentSession()
-
-Get current session from local storage (no API call).
-
-### Parameters
-
-None
-
-### Returns
-
-```typescript
-{
-  data: {
-    session: {
-      accessToken: string,
-      user: { id, email, name, ... }
-    } | null
-  },
-  error: Error | null
-}
-```
-
-### Example
-
-```javascript
-const { data, error } = await insforge.auth.getCurrentSession()
-
-if (data.session) {
-  console.log('Token:', data.session.accessToken)
-}
-```
-
-### Output
-
-```json
-{
-  "data": {
-    "session": {
-      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-      "user": {
-        "id": "usr_abc123",
-        "email": "user@example.com",
-        "name": "John Doe"
-      }
-    }
-  },
-  "error": null
-}
-```
-
----
-
-## getProfile()
-
-Get any user's public profile by ID.
-
-### Parameters
-
-- `userId` (string, required) - User ID to fetch profile for
-
-### Returns
-
-```typescript
-{
-  data: { id, nickname, avatar_url, bio, birthday, ... } | null,
-  error: Error | null
-}
-```
-
-### Example
-
-```javascript
-const { data: profile, error } = await insforge.auth.getProfile('usr_xyz789')
-
-console.log(profile.nickname)
-```
-
-### Output
-
-```json
-{
-  "data": {
-    "id": "usr_xyz789",
-    "nickname": "JaneDoe",
-    "avatar_url": "https://example.com/jane.jpg",
-    "bio": "Designer and developer",
-    "birthday": "1992-05-15"
-  },
-  "error": null
-}
-```
-
----
-
-## setProfile()
-
-Update current user's profile in users table.
-
-### 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)
-
-### Returns
-
-```typescript
-{
-  data: { id, nickname, avatar_url, bio, birthday, ... } | null,
-  error: Error | null
-}
-```
-
-### Example
-
-```javascript
-const { data: profile, error } = await insforge.auth.setProfile({
-  nickname: 'JohnDev',
-  bio: 'Full-stack developer',
-  avatar_url: 'https://example.com/avatar.jpg'
-})
-```
-
-### Output
-
-```json
-{
-  "data": {
-    "id": "usr_abc123",
-    "nickname": "JohnDev",
-    "avatar_url": "https://example.com/avatar.jpg",
-    "bio": "Full-stack developer",
-    "birthday": null
-  },
-  "error": null
-}
-```
-
----
-
-## Error Handling
-
-All auth methods return structured errors:
-
-```javascript
-const { data, error } = await insforge.auth.signInWithPassword({
-  email: 'user@example.com',
-  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'
-}
-```
+---
+title: Authentication SDK Reference
+description: User authentication and profile management with the InsForge SDK
+---
+
+import Installation from '/snippets/sdk-installation.mdx';
+
+<Installation />
+
+## signUp()
+
+Create a new user account with email and password.
+
+### Parameters
+
+- `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, 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',
+});
+
+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
+
+```json
+{
+  "data": {
+    "user": {
+      "id": "usr_abc123",
+      "email": "user@example.com",
+      "emailVerified": false,
+      "providers": ["email"],
+      "createdAt": "2024-01-15T10:00:00Z",
+      "updatedAt": "2024-01-15T10:00:00Z",
+      "profile": {
+        "name": "John Doe",
+        "avatar_url": null
+      },
+      "metadata": {}
+    },
+    "requireEmailVerification": true,
+    "accessToken": null,
+    "redirectTo": "https://app.example.com/verify-email",
+    "csrfToken": null
+  },
+  "error": null
+}
+```
+
+---
+
+## signInWithPassword()
+
+Sign in an existing user with email and password.
+
+### Parameters
+
+- `email` (string, required) - User's email address
+- `password` (string, required) - User's password
+
+### Returns
+
+```typescript
+{
+  data: {
+    user: { id, email, emailVerified, providers, createdAt, updatedAt, profile, metadata },
+    accessToken: string,
+    redirectTo?: string,
+    csrfToken?: string | null
+  } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.signInWithPassword({
+  email: 'user@example.com',
+  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
+
+```json
+{
+  "data": {
+    "user": {
+      "id": "usr_abc123",
+      "email": "user@example.com",
+      "emailVerified": true,
+      "providers": ["email"],
+      "createdAt": "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...",
+    "redirectTo": "https://app.example.com/dashboard",
+    "csrfToken": "5758d38259fb..."
+  },
+  "error": null
+}
+```
+
+---
+
+## signInWithOAuth()
+
+Start OAuth authentication flow with supported providers (Google, GitHub, Microsoft, Discord, and more).
+
+### Parameters
+
+- `provider` (string, required) - OAuth provider name (e.g., 'google', 'github', 'microsoft', 'discord')
+- `redirectTo` (string, optional) - URL to redirect after authentication
+- `skipBrowserRedirect` (boolean, optional) - If true, returns OAuth URL without auto-redirecting (for mobile apps)
+
+### Returns
+
+```typescript
+{
+  data: { url?: string, provider?: string },
+  error: Error | null
+}
+```
+
+<Note>
+  After OAuth redirect, SDK automatically detects callback parameters and saves session. No manual
+  handling needed.
+</Note>
+
+### Example
+
+```javascript
+// Default: auto-redirect
+await insforge.auth.signInWithOAuth({
+  provider: 'google',
+  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,
+});
+
+window.location.href = data.url; // Redirect when ready
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...",
+    "provider": "google"
+  },
+  "error": null
+}
+```
+
+---
+
+## signOut()
+
+Sign out the current user and clear session.
+
+### Parameters
+
+None
+
+### Returns
+
+```typescript
+{
+  error: Error | null;
+}
+```
+
+### Example
+
+```javascript
+const { error } = await insforge.auth.signOut();
+```
+
+### Output
+
+```json
+{
+  "error": null
+}
+```
+
+---
+
+## getCurrentSession()
+
+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
+
+None
+
+### Returns
+
+```typescript
+{
+  data: {
+    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
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.getProfile('usr_xyz789');
+
+if (data) {
+  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",
+      "emailVerified": true
+    },
+    "redirectTo": "https://app.example.com/dashboard"
+  },
+  "error": null
+}
+```
+
+---
+
+## sendResetPasswordEmail()
+
+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
+
+- `email` (string, required) - User's email address
+
+### Returns
+
+```typescript
+{
+  data: { success: boolean, message: string } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.sendResetPasswordEmail({
+  email: 'user@example.com',
+});
+
+if (data?.success) {
+  console.log('Password reset email sent!');
+}
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "success": true,
+    "message": "Password reset email sent"
+  },
+  "error": null
+}
+```
+
+---
+
+## 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`).
+
+<Note>
+  This endpoint is not used when `resetPasswordMethod` is `link` (magic link flow is direct).
+</Note>
+
+### Parameters
+
+- `email` (string, required) - User's email address
+- `code` (string, required) - 6-digit code from the email
+
+### Returns
+
+```typescript
+{
+  data: { token: string, expiresAt: string } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+const { data, error } = await insforge.auth.exchangeResetPasswordToken({
+  email: 'user@example.com',
+  code: '123456',
+});
+
+if (data) {
+  // Use token to reset password
+  await insforge.auth.resetPassword({
+    newPassword: 'newSecurePassword123',
+    otp: data.token,
+  });
+}
+```
+
+### Output
+
+```json
+{
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "expiresAt": "2024-01-15T11:00:00Z"
+  },
+  "error": null
+}
+```
+
+---
+
+## resetPassword()
+
+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
+
+- `newPassword` (string, required) - New password for the user
+- `otp` (string, required) - Reset token or magic link token
+
+### Returns
+
+```typescript
+{
+  data: { message: string, redirectTo?: string } | null,
+  error: Error | null
+}
+```
+
+### Example
+
+```javascript
+// 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
+
+```json
+{
+  "data": {
+    "message": "Password reset successfully",
+    "redirectTo": "https://app.example.com/login"
+  },
+  "error": null
+}
+```
+
+---
+
+## Error Handling
+
+All auth methods return structured errors:
+
+```javascript
+const { data, error } = await insforge.auth.signInWithPassword({
+  email: 'user@example.com',
+  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'
+}
+```