@logickernel/bridge 0.8.1 → 0.8.3

package/README.md

@@ -1,83 +1,171 @@
-# Bridge
+# @logickernel/bridge
 
-Framework-agnostic micro-frontend authentication library for AuthJS/NextAuth JWT tokens.
+Framework-agnostic micro-frontend authentication library for AuthJS/NextAuth JWT tokens with built-in Next.js components.
 
 ## Installation
 
 ```bash
 npm install @logickernel/bridge
-# or
-pnpm add @logickernel/bridge
-# or
-yarn add @logickernel/bridge
 ```
 
-## Features
-
-- **Framework-agnostic core** - JWT decoding and validation works anywhere
-- **Next.js adapter** - First-class support for Next.js App Router
-- **Role-based access control** - Check user roles against organization permissions
-- **TypeScript-first** - Full type safety with detailed type exports
-- **Dual ESM/CJS** - Works in any JavaScript environment
+## Quick Start (Next.js)
 
-## Quick Start
+### 1. Environment Variables
 
-### Environment Variables
+Add these to the `.env` file of your application:
 
 ```bash
 AUTH_SECRET=your-nextauth-secret  # Required: Same secret used by your kernel/auth server
-AUTH_URL=http://localhost:3000    # Required: Used internally for API calls to the kernel
-BASE_URL=http://localhost:7001    # Optional: Facade URL for user-facing redirects (used by getBaseUrl())
-AUTH_COOKIE=authjs.session-token  # Optional: Cookie name for session token (defaults to authjs.session-token)
+AUTH_URL=http://localhost:3000    # Required: Base URL of your kernel/auth server
+BASE_URL=http://localhost:7001    # Optional: Your facade URL for user-facing redirects
 ```
 
-### Core Usage (Framework-Agnostic)
+### 2. Configure Next.js
+
+In your `next.config.ts`, add the bridge package to `transpilePackages`:
 
 ```typescript
-import {
-  decodeSessionToken,
-  extractSessionCookie,
-  fetchUserRoles,
-  hasAnyRole,
-} from "@logickernel/bridge"
+import type { NextConfig } from "next"
 
-// Decode a JWT session token
-const result = await decodeSessionToken(token, secret, isSecure)
-if (result.success) {
-  console.log(result.session.user.email)
-  console.log(result.session.user.id)
-} else {
-  console.error(result.error) // "missing_token" | "missing_secret" | "decode_error" | "expired"
+const nextConfig: NextConfig = {
+  transpilePackages: ["@logickernel/bridge"],
+  // ... other config
 }
 
-// Check user roles (uses AUTH_URL environment variable internally)
-// User ID is determined from the session token
-const roles = await fetchUserRoles({
-  organizationId: "org-456",
-  sessionToken: token,
-})
+export default nextConfig
+```
+
+**Why `transpilePackages`?** This tells Next.js to transpile the bridge library's TypeScript/ES modules during the build process. This is necessary because the library uses modern JavaScript features and needs to be processed by Next.js's bundler (Turbopack or webpack) to work correctly with your application.
+
+### 3. Use the Layout Component
+
+The library provides a ready-to-use layout component with sidebar navigation. You need a thin wrapper component in your app to establish the client/server boundary.
+
+**Step 1: Create a wrapper component**
+
+Create `src/components/app-layout-wrapper.tsx`:
 
-if (roles.success && hasAnyRole(roles.roles, ["organization.owner"])) {
-  // User is an owner
+```typescript
+"use client"
+
+/**
+ * Client boundary wrapper for AppLayout.
+ * 
+ * This wrapper is required because "use client" directives are not preserved
+ * in bundled library code. Next.js needs this directive in your source code
+ * to properly handle the client/server boundary.
+ */
+import { AppLayout } from "@logickernel/bridge/next-components"
+
+export function AppLayoutWrapper({
+  children,
+  organizationId,
+  apiBaseUrl,
+}: {
+  children: React.ReactNode
+  organizationId?: string
+  apiBaseUrl?: string
+}) {
+  return (
+    <AppLayout
+      organizationId={organizationId}
+      apiBaseUrl={apiBaseUrl}
+    >
+      {children}
+    </AppLayout>
+  )
 }
 ```
 
-### Next.js Usage
+**Step 2: Use in your layout**
+
+In your `app/app/layout.tsx` (or wherever your app layout is):
 
 ```typescript
-import {
-  getSession,
-  getUserRoles,
-  withAuth,
-  checkPageAuth,
-  createProxyHandler,
-} from "@logickernel/bridge/next"
+import { redirect } from "next/navigation"
+import { auth } from "@/lib/next-auth" // or your auth setup
+import { AppLayoutWrapper } from "@/components/app-layout-wrapper"
+
+export default async function Layout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const session = await auth()
+
+  if (!session?.user) {
+    redirect("/auth/signin?callbackUrl=/app")
+  }
+
+  return (
+    <AppLayoutWrapper>
+      {children}
+    </AppLayoutWrapper>
+  )
+}
+```
+
+The `user` prop is **not needed** - the layout automatically fetches user information from the navigation API endpoint.
+
+### 4. Navigation API Endpoint
+
+The layout component automatically loads navigation items from your API. The **Kernel Core application** provides this endpoint at `/api/navigation/[organization_id]`.
+
+**Required Endpoint:** `GET /api/navigation/[organization_id]`
+
+**Response Payload:**
+
+```typescript
+{
+  items: NavigationItem[]
+  organizationId: string
+  organizations: NavigationOrganization[]
+  user: {
+    id: string
+    name: string | null
+    email: string
+    image: string | null
+  }
+}
+
+interface NavigationItem {
+  title: string
+  url?: string        // If missing, item is treated as a section label
+  icon?: string       // Lucide icon name (e.g., "LayoutDashboard", "Users")
+  isActive?: boolean  // Whether the item should be highlighted
+  items?: {           // Sub-items for collapsible navigation
+    title: string
+    url: string
+  }[]
+}
+
+interface NavigationOrganization {
+  id: string
+  name: string
+  logo?: string       // Lucide icon name for the organization logo
+  plan?: string       // Optional plan/badge text
+}
 ```
 
-#### Server Components / Pages
+**Note:** The endpoint should be protected and only return data the authenticated user has access to. The `{organizationId}` placeholder in item URLs will be automatically replaced with the current organization ID.
+
+## Features
+
+The `AppLayout` component provides:
+
+- ✅ **Built-in sidebar navigation** with collapsible sections
+- ✅ **Organization switcher** - Switch between organizations the user belongs to
+- ✅ **User menu** with profile information and sign-out
+- ✅ **Responsive design** - Works on mobile and desktop
+- ✅ **Automatic navigation loading** - Fetches from your API endpoint
+- ✅ **Consistent UI** - Same look and feel across all microfrontends using the library
+- ✅ **No extra components required** - All UI components are included in the library
+
+## Next.js Utilities
+
+### Server Components / Pages
 
 ```typescript
-// app/dashboard/page.tsx
 import { getSession } from "@logickernel/bridge/next"
 import { redirect } from "next/navigation"
 
@@ -92,42 +180,39 @@ export default async function DashboardPage() {
 }
 ```
 
-#### Role-Based Page Protection
+### Role-Based Page Protection
 
 ```typescript
-// app/[org_id]/admin/page.tsx
 import { checkPageAuth } from "@logickernel/bridge/next"
 import { redirect, notFound } from "next/navigation"
 
 export default async function AdminPage({
   params,
 }: {
-  params: Promise<{ org_id: string }>
+  params: Promise<{ organization_id: string }>
 }) {
-  const { org_id } = await params
+  const { organization_id } = await params
 
   const auth = await checkPageAuth({
     requiredRoles: ["organization.owner", "organization.editor"],
-    organizationId: org_id,
+    organizationId: organization_id,
   })
 
   if (!auth.authenticated) {
     redirect(auth.redirectUrl)
   }
 
-  // User is authenticated but may not have required roles
-  if (!auth.roles.some(r => ["organization.owner", "organization.editor"].includes(r))) {
+  if (!auth.hasRequiredRole) {
     notFound()
   }
 
-  return <div>Admin Panel for {session.user.email}</div>
+  return <div>Admin Panel for {auth.session.user.email}</div>
 }
 ```
 
-#### API Routes
+### API Routes
 
 ```typescript
-// app/api/data/route.ts
 import { withAuth } from "@logickernel/bridge/next"
 import { NextResponse } from "next/server"
 
@@ -152,10 +237,10 @@ export const DELETE = withAuth(
 )
 ```
 
-#### Middleware / Proxy
+### Middleware / Proxy
 
 ```typescript
-// src/proxy.ts (or middleware.ts)
+// middleware.ts or proxy.ts
 import { createProxyHandler, type ProxyOptions } from "@logickernel/bridge/next"
 
 const config: ProxyOptions = {
@@ -166,7 +251,7 @@ const config: ProxyOptions = {
   },
   dynamicRoutes: [
     {
-      pattern: "/[organization_id]/admin",
+      pattern: "/app/[organization_id]/admin",
       requiredRoles: ["organization.owner"],
     },
   ],
@@ -174,174 +259,27 @@ const config: ProxyOptions = {
 
 export const proxy = createProxyHandler(config)
 
-// Static config for Next.js (must be in the same file)
-export const middlewareConfig = {
+// Static config for Next.js middleware
+export const config = {
   matcher: ["/((?!_next/static|_next/image|favicon.ico|public).*)"],
 }
 ```
 
-#### Layout Components
-
-The bridge library provides ready-to-use layout components with built-in navigation connected to the Core of the Kernel.
-
-```typescript
-// app/app/layout.tsx (or your app layout)
-"use client"
-
-import { AppLayout, type User } from "@logickernel/bridge/next/components"
-import { useSession } from "next-auth/react"
-
-export default function Layout({ children }: { children: React.ReactNode }) {
-  const { data: session } = useSession()
-  
-  if (!session?.user) {
-    return <>{children}</>
-  }
-
-  const user: User = {
-    name: session.user.name || null,
-    email: session.user.email || "",
-    image: session.user.image || null,
-  }
-
-  return (
-    <AppLayout
-      user={user}
-      organizationId={organizationId} // Optional: Current organization ID
-      apiBaseUrl={apiBaseUrl}         // Optional: API base URL for navigation
-    >
-      {children}
-    </AppLayout>
-  )
-}
-```
-
-**For Server Components:**
+## Import Paths
 
-```typescript
-// app/app/layout.tsx
-import { AppLayout, type User } from "@logickernel/bridge/next/components"
-import { redirect } from "next/navigation"
-import { auth } from "@/lib/next-auth" // or your NextAuth setup
+The library uses top-level exports (no subpath exports) for better bundler compatibility:
 
-export default async function Layout({
-  children,
-  params,
-}: {
-  children: React.ReactNode
-  params: Promise<{ organization_id?: string }>
-}) {
-  const session = await auth()
-  
-  if (!session?.user) {
-    redirect("/auth/signin")
-  }
-
-  const { organization_id } = await params
-
-  const user: User = {
-    name: session.user.name || null,
-    email: session.user.email || "",
-    image: session.user.image || null,
-  }
-
-  return (
-    <AppLayout
-      user={user}
-      organizationId={organization_id}
-      apiBaseUrl={process.env.AUTH_URL}
-    >
-      {children}
-    </AppLayout>
-  )
-}
-```
-
-**Note:** You can also use `getSession()` from `@logickernel/bridge/next` instead of NextAuth's `auth()` function. Both will work, but NextAuth's `auth()` is recommended if you're using NextAuth v5.
-
-**Features:**
-- ✅ Built-in sidebar navigation with organization switcher
-- ✅ User menu with sign-out
-- ✅ Responsive design (mobile/desktop)
-- ✅ Automatic navigation loading from your API
-- ✅ No component passing required - UI components are included in the library
-- ✅ Consistent UI across all microfrontends using the bridge
-
-The `AppLayout` component automatically:
-- Loads navigation items from `/api/navigation/[organization_id]` endpoint
-- Displays organizations the user belongs to
-- Handles organization switching
-- Provides user profile menu with sign-out
-
-**Required API Endpoint:**
-
-The navigation requires an endpoint at `/api/navigation/[organization_id]` that returns:
-```typescript
-{
-  items: NavigationItem[],
-  organizations: NavigationOrganization[]
-}
-```
-
-**Type Definitions:**
 ```typescript
-interface NavigationItem {
-  title: string
-  url?: string        // If missing, item is treated as a section label
-  icon?: string       // Icon name (mapped using getIconComponent)
-  isActive?: boolean  // Whether the item should be highlighted
-  items?: {           // Sub-items for collapsible navigation
-    title: string
-    url: string
-  }[]
-}
+// Core utilities (framework-agnostic)
+import { decodeSessionToken, fetchUserRoles } from "@logickernel/bridge"
 
-interface NavigationOrganization {
-  id: string
-  name: string
-  logo?: string       // Icon name for the organization logo
-  plan?: string       // Optional plan/badge text
-}
-```
+// Next.js utilities (server components, API routes, middleware)
+import { getSession, withAuth, checkPageAuth } from "@logickernel/bridge/next"
 
-**Example Response:**
-```json
-{
-  "items": [
-    {
-      "title": "Dashboard",
-      "url": "/app/{organizationId}/home",
-      "icon": "LayoutDashboard"
-    },
-    {
-      "title": "Team",
-      "icon": "Users"  // Section label (no URL)
-    },
-    {
-      "title": "Members",
-      "url": "/app/{organizationId}/members",
-      "icon": "User",
-      "items": [
-        {
-          "title": "All Members",
-          "url": "/app/{organizationId}/members"
-        }
-      ]
-    }
-  ],
-  "organizations": [
-    {
-      "id": "org-123",
-      "name": "Acme Corp",
-      "logo": "Building",
-      "plan": "Pro"
-    }
-  ]
-}
+// Layout components (client components)
+import { AppLayout, type User } from "@logickernel/bridge/next-components"
 ```
 
-**Note:** The `{organizationId}` placeholder in URLs will be automatically replaced with the current organization ID. The endpoint should be protected and only return data the current user has access to.
-
 ## API Reference
 
 ### Core Exports (`@logickernel/bridge`)
@@ -350,13 +288,10 @@ interface NavigationOrganization {
 |--------|-------------|
 | `decodeSessionToken(token, secret, isSecure)` | Decode and validate a JWT session token |
 | `extractSessionCookie(cookies)` | Extract session cookie from a cookies object |
-| `fetchUserRoles(options)` | Fetch user roles from the kernel API (uses AUTH_URL internally) |
+| `fetchUserRoles(options)` | Fetch user roles from the kernel API |
 | `hasAnyRole(userRoles, requiredRoles)` | Check if user has at least one required role |
 | `hasAllRoles(userRoles, requiredRoles)` | Check if user has all required roles |
 | `hasRole(userRoles, role)` | Check if user has a specific role |
-| `matchRoute(pathname, config)` | Match a pathname against route configuration |
-| `buildSignInUrl(callbackUrl?)` | Build a sign-in redirect URL (uses AUTH_URL internally) |
-| `buildSignOutUrl(callbackUrl?)` | Build a sign-out redirect URL (uses AUTH_URL internally) |
 
 ### Next.js Exports (`@logickernel/bridge/next`)
 
@@ -364,63 +299,57 @@ interface NavigationOrganization {
 |--------|-------------|
 | `getSession()` | Get the current session from cookies |
 | `getSessionToken()` | Get the raw session token value |
-| `getUserRoles(orgId)` | Get user roles in an organization (user ID determined from session token) |
+| `getUserRoles(orgId)` | Get user roles in an organization |
 | `withAuth(handler, options?)` | Wrap an API route with authentication |
-| `getSessionFromRequest(request)` | Get session from a NextRequest |
 | `checkPageAuth(options?)` | Check authentication for a page |
 | `requireAuth()` | Require authentication (throws if not authenticated) |
-| `hasRequiredRole(orgId, roles)` | Check if user has required roles (user ID determined from session token) |
+| `hasRequiredRole(orgId, roles)` | Check if user has required roles |
 | `createProxyHandler(options)` | Create a middleware/proxy handler |
 
-### Layout Components (`@logickernel/bridge/next/components`)
+### Layout Components (`@logickernel/bridge/next-components`)
 
 | Export | Description |
 |--------|-------------|
-| `AppLayout` | Main layout component with sidebar navigation |
-| `AppSidebar` | Sidebar component (used internally by AppLayout) |
-| `NavMain` | Main navigation component (used internally) |
-| `NavUser` | User menu component (used internally) |
-| `TeamSwitcher` | Organization switcher component (used internally) |
+| `AppLayout` | Main layout component with sidebar navigation (wrap in a local component with `"use client"` for server components) |
 | `useNavigation` | Hook to fetch navigation items from API |
 | `getIconComponent` | Utility to get icon component from icon name |
 
 **AppLayout Props:**
+
 ```typescript
 interface AppLayoutProps {
-  user: User                    // User information (name, email, image)
-  organizationId?: string       // Optional: Current organization ID
-  apiBaseUrl?: string           // Optional: API base URL for navigation
-  children: React.ReactNode     // Page content
+  user?: User                    // Optional: User information (auto-fetched if not provided)
+  organizationId?: string        // Optional: Current organization ID
+  apiBaseUrl?: string            // Optional: API base URL (defaults to "/api")
+  children: React.ReactNode      // Page content
 }
 ```
 
-### Types
+## TypeScript Types
 
 ```typescript
+// Core types
 import type {
   Session,
   SessionUser,
   DecodeResult,
-  RouteConfig,
-  RouteMatch,
-  MicroFrontendConfig,
 } from "@logickernel/bridge"
 
+// Next.js types
 import type {
   ProxyOptions,
-  DynamicRoutePattern,
   AuthContext,
   AuthenticatedHandler,
-  WithAuthOptions,
   PageAuthOptions,
   PageAuthResult,
 } from "@logickernel/bridge/next"
 
+// Component types
 import type {
   User,
   NavigationItem,
   NavigationOrganization,
-} from "@logickernel/bridge/next/components"
+} from "@logickernel/bridge/next-components"
 ```
 
 ## Architecture
@@ -428,26 +357,23 @@ import type {
 ```
 bridge/
 ├── src/
-│   ├── index.ts      # Core exports
-│   ├── types.ts      # Core type definitions
-│   ├── jwt.ts        # JWT decoding utilities
-│   ├── roles.ts      # Role checking utilities
-│   ├── routes.ts     # Route matching utilities
+│   ├── index.ts              # Core exports (framework-agnostic)
+│   ├── jwt.ts                # JWT decoding utilities
+│   ├── roles.ts              # Role checking utilities
 │   └── next/
-│       ├── index.ts  # Next.js adapter exports
-│       ├── types.ts  # Next.js-specific types
-│       ├── session.ts # Session utilities
-│       ├── api.ts    # API route utilities
-│       ├── page.ts   # Page utilities
-│       ├── proxy.ts  # Middleware/proxy utilities
+│       ├── index.ts          # Next.js adapter exports
+│       ├── session.ts        # Session utilities
+│       ├── api.ts            # API route utilities
+│       ├── page.ts           # Page utilities
+│       ├── proxy.ts          # Middleware/proxy utilities
 │       └── components/
-│           ├── app-layout.tsx    # Main layout component
-│           ├── app-sidebar.tsx   # Sidebar component
-│           ├── nav-main.tsx      # Navigation component
-│           ├── nav-user.tsx      # User menu component
-│           ├── team-switcher.tsx # Organization switcher
-│           ├── use-navigation.ts # Navigation hook
-│           └── ui/               # Internal UI components (shadcn)
+│           ├── app-layout.tsx     # Main layout component
+│           ├── app-sidebar.tsx    # Sidebar component
+│           ├── nav-main.tsx       # Navigation component
+│           ├── nav-user.tsx       # User menu component
+│           ├── team-switcher.tsx  # Organization switcher
+│           ├── use-navigation.ts  # Navigation hook
+│           └── ui/                # Internal UI components (shadcn)
 ```
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logickernel/bridge",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Framework-agnostic micro-frontend authentication library for AuthJS/NextAuth JWT tokens",
   "author": "Victor",
   "license": "MIT",
@@ -101,4 +101,3 @@
     "node": ">=18"
   }
 }
-