@insforge/nextjs 0.10.2 → 0.10.4

package/dist/middleware/InsforgeMiddleware.d.ts

@@ -1,15 +1,133 @@
 import { NextRequest, NextResponse } from 'next/server';
 
 interface InsforgeMiddlewareConfig {
+    /**
+     * Base URL of your Insforge backend
+     * @example 'https://your-backend.com' or 'http://localhost:3001'
+     */
     baseUrl: string;
+    /**
+     * Routes that are public and don't require authentication
+     * @default ['/']
+     * @example ['/sign-in', '/sign-up', '/', '/about']
+     */
     publicRoutes?: string[];
+    /**
+     * Local route path for sign-in (can be customized to any path like '/login')
+     * When using built-in auth, this will redirect to backend's `/auth/sign-in`
+     * @default '/sign-in'
+     */
     signInUrl?: string;
+    /**
+     * Local route path for sign-up (can be customized to any path like '/register')
+     * When using built-in auth, this will redirect to backend's `/auth/sign-up`
+     * @default '/sign-up'
+     */
     signUpUrl?: string;
+    /**
+     * Local route path for forgot password
+     * When using built-in auth, this will redirect to backend's `/auth/forgot-password`
+     * @default '/forgot-password'
+     */
     forgotPasswordUrl?: string;
+    /**
+     * URL to redirect to after successful authentication
+     * When user completes sign-in/sign-up, they will be redirected to this URL with token in URL
+     * @default '/'
+     */
     afterSignInUrl?: string;
+    /**
+     * Cookie name for the auth token
+     * @default 'insforge_token'
+     */
     cookieName?: string;
+    /**
+     * Whether to use built-in authentication pages hosted on the backend
+     * - When true: redirects to backend's `/auth/sign-in` and `/auth/sign-up` pages
+     * - When false: redirects to local sign-in/sign-up pages (you provide your own components)
+     * @default true
+     */
     useBuiltInAuth?: boolean;
 }
-declare function InsforgeMiddleware(config: InsforgeMiddlewareConfig): (request: NextRequest) => Promise<NextResponse<unknown>>;
+/**
+ * Creates Next.js middleware for protecting routes with Insforge authentication.
+ *
+ * This middleware provides lightweight route protection by:
+ * - Detecting and storing auth tokens from URL parameters (after backend redirect)
+ * - Checking for auth token presence in cookies
+ * - Redirecting unauthenticated users to sign-in page
+ * - Allowing public routes to be accessed without authentication
+ * - Mapping local auth routes to backend's fixed paths when using built-in auth
+ *
+ * **How Authentication Flow Works:**
+ * 1. User visits protected route → Middleware checks for token
+ * 2. No token → Redirects to sign-in (backend or local)
+ * 3. User accesses auth page (e.g., /sign-in) → Redirects to backend with afterSignInUrl as redirect target
+ * 4. After sign-in → Backend redirects to `yourapp.com/afterSignInUrl?access_token=xxx&user_id=xxx...`
+ * 5. Middleware detects `access_token` in URL → Stores in HTTP-only cookie → Cleans URL → Allows access
+ * 6. SDK also detects token from URL → Stores in localStorage → Updates auth state
+ *
+ * **Important Notes:**
+ * - This middleware only checks if a token exists, it doesn't validate it
+ * - Tokens from URL are automatically extracted and stored in cookies
+ * - When `useBuiltInAuth: true`, local routes map to backend's fixed auth paths
+ * - You can customize local route paths (e.g., `/login`) while backend paths remain fixed
+ * - After successful auth, users are redirected to `afterSignInUrl` (default: `/`), not back to the auth page
+ *
+ * @param config - Middleware configuration
+ * @returns Next.js middleware function
+ *
+ * @example
+ * ```ts
+ * // middleware.ts - Using built-in auth
+ * import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
+ *
+ * export default InsforgeMiddleware({
+ *   baseUrl: process.env.INSFORGE_BASE_URL!,
+ *   publicRoutes: ['/', '/about'],
+ *   afterSignInUrl: '/', // Redirect here after successful auth
+ *   useBuiltInAuth: true,
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/((?!_next|api|.*\\..*).*)'],
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // middleware.ts - Custom local auth pages with custom paths
+ * import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
+ *
+ * export default InsforgeMiddleware({
+ *   baseUrl: process.env.INSFORGE_BASE_URL!,
+ *   publicRoutes: ['/login', '/register', '/', '/about'],
+ *   signInUrl: '/login',
+ *   signUpUrl: '/register',
+ *   afterSignInUrl: '/dashboard',
+ *   useBuiltInAuth: false,
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/((?!_next|api|.*\\..*).*)'],
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * // middleware.ts - Built-in auth with custom auth route paths
+ * import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
+ *
+ * export default InsforgeMiddleware({
+ *   baseUrl: 'https://your-backend.com',
+ *   signInUrl: '/login',
+ *   signUpUrl: '/register',
+ *   forgotPasswordUrl: '/forgot',
+ *   afterSignInUrl: '/dashboard',
+ *   useBuiltInAuth: true,
+ * });
+ * ```
+ */
+declare function InsforgeMiddleware(config: InsforgeMiddlewareConfig): (request: NextRequest) => NextResponse<unknown>;
 
 export { InsforgeMiddleware, type InsforgeMiddlewareConfig };

package/dist/navigation/NextNavigationAdapter.d.ts

@@ -1,5 +1,10 @@
 import { NavigationAdapter } from '@insforge/react/navigation';
 
+/**
+ * Next.js navigation adapter
+ * Uses Next.js's useSearchParams hook and Link component
+ * Provides optimized navigation with prefetching and client-side routing
+ */
 declare const NextNavigationAdapter: NavigationAdapter;
 
 export { NextNavigationAdapter };

package/package.json

@@ -1,60 +1,58 @@
-{
-  "name": "@insforge/nextjs",
-  "version": "0.10.2",
-  "description": "Pre-built authentication UI components for Next.js with Insforge backend - zero configuration required",
-  "type": "module",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/esm/index.js"
-    },
-    "./middleware": {
-      "types": "./dist/middleware/index.d.ts",
-      "import": "./dist/esm/middleware/index.js"
-    },
-    "./api": {
-      "types": "./dist/api/index.d.ts",
-      "import": "./dist/esm/api/index.js"
-    },
-    "./styles.css": "./src/styles.css"
-  },
-  "files": [
-    "dist",
-    "src/styles.css",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "type-check": "tsc --noEmit"
-  },
-  "keywords": [
-    "insforge",
-    "nextjs",
-    "authentication",
-    "auth",
-    "ui",
-    "components",
-    "react"
-  ],
-  "author": "Insforge",
-  "license": "MIT",
-  "dependencies": {
-    "@insforge/react": "^0.6.0",
-    "@insforge/sdk": "^0.0.58",
-    "@insforge/shared-schemas": "^1.1.19"
-  },
-  "devDependencies": {
-    "@types/node": "^24.9.2",
-    "@types/react": "^19.2.2",
-    "@types/react-dom": "^19.2.2",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3"
-  },
-  "peerDependencies": {
-    "next": "^15.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
-  }
-}
+{
+  "name": "@insforge/nextjs",
+  "version": "0.10.4",
+  "description": "Pre-built authentication UI components for Next.js with Insforge backend - zero configuration required",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/esm/middleware/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/esm/api/index.js"
+    },
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "dist",
+    "src/styles.css",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "insforge",
+    "nextjs",
+    "authentication",
+    "auth",
+    "ui",
+    "components",
+    "react"
+  ],
+  "author": "Insforge",
+  "license": "MIT",
+  "dependencies": {
+    "@insforge/react": "^0.6.1",
+    "@insforge/sdk": "^0.0.58",
+    "@insforge/shared": "^0.1.0",
+    "@insforge/shared-schemas": "^1.1.19"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2"
+  },
+  "peerDependencies": {
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}

package/src/styles.css

@@ -6,4 +6,4 @@
  */
 
 /* Import base React package styles - contains all component styles */
-@import '@insforge/react/styles.css';
+@import '@insforge/react/styles.css';