@logickernel/bridge 0.8.0 → 0.8.2

package/README.md

@@ -1,6 +1,6 @@
-# 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
 
@@ -12,72 +12,135 @@ pnpm add @logickernel/bridge
 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 your `.env` file:
 
 ```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
+```
+
+### 3. Use the Layout Component
+
+The library provides a ready-to-use layout component with sidebar navigation. Import `AppLayoutWrapper` directly from the library:
+
+In your `app/app/layout.tsx` (or wherever your app layout is):
+
+```typescript
+import { redirect } from "next/navigation"
+import { auth } from "@/lib/next-auth" // or your auth setup
+import { AppLayoutWrapper } from "@logickernel/bridge/next-components"
+
+export default async function Layout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const session = await auth()
 
-if (roles.success && hasAnyRole(roles.roles, ["organization.owner"])) {
-  // User is an owner
+  if (!session?.user) {
+    redirect("/auth/signin?callbackUrl=/app")
+  }
+
+  return (
+    <AppLayoutWrapper>
+      {children}
+    </AppLayoutWrapper>
+  )
 }
 ```
 
-### Next.js Usage
+**Optional: Pass organization ID and API base URL**
 
 ```typescript
-import {
-  getSession,
-  getUserRoles,
-  withAuth,
-  checkPageAuth,
-  createProxyHandler,
-} from "@logickernel/bridge/next"
+<AppLayoutWrapper
+  organizationId={organizationId}
+  apiBaseUrl={apiBaseUrl}
+>
+  {children}
+</AppLayoutWrapper>
 ```
 
-#### Server Components / Pages
+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
+}
+```
+
+**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 +155,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 +212,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 +226,7 @@ const config: ProxyOptions = {
   },
   dynamicRoutes: [
     {
-      pattern: "/[organization_id]/admin",
+      pattern: "/app/[organization_id]/admin",
       requiredRoles: ["organization.owner"],
     },
   ],
@@ -174,174 +234,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:**
-
-```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
-
-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
+## Import Paths
 
-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
+The library uses top-level exports (no subpath exports) for better bundler compatibility:
 
-**Required API Endpoint:**
-
-The navigation requires an endpoint at `/api/navigation/[organization_id]` that returns:
 ```typescript
-{
-  items: NavigationItem[],
-  organizations: NavigationOrganization[]
-}
-```
+// Core utilities (framework-agnostic)
+import { decodeSessionToken, fetchUserRoles } from "@logickernel/bridge"
 
-**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
-  }[]
-}
+// Next.js utilities (server components, API routes, middleware)
+import { getSession, withAuth, checkPageAuth } from "@logickernel/bridge/next"
 
-interface NavigationOrganization {
-  id: string
-  name: string
-  logo?: string       // Icon name for the organization logo
-  plan?: string       // Optional plan/badge text
-}
+// Layout components (client components)
+import { AppLayout, type User } from "@logickernel/bridge/next-components"
 ```
 
-**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"
-    }
-  ]
-}
-```
-
-**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 +263,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 +274,68 @@ 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 (use `AppLayoutWrapper` in server components) |
+| `AppLayoutWrapper` | Wrapper component for use in server components (recommended) |
 | `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
+## Why AppLayoutWrapper?
+
+The library provides `AppLayoutWrapper` as a convenience wrapper for `AppLayout` because:
+
+1. **React Context Requirement**: `AppLayout` uses React Context internally (for sidebar state)
+2. **SSR Build Compatibility**: Next.js requires a clean client/server boundary when client components with Context are used in server components
+3. **Simplified Usage**: Using `AppLayoutWrapper` directly avoids React resolution issues during build-time analysis
+
+You can use `AppLayoutWrapper` directly in server components without creating your own wrapper.
+
+## 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 +343,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/dist/{components.cjs → next-components.cjs}

@@ -1335,13 +1335,28 @@ function AppLayout({
     ] })
   ] });
 }
+function AppLayoutWrapper({
+  organizationId,
+  apiBaseUrl,
+  children
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    AppLayout,
+    {
+      organizationId,
+      apiBaseUrl,
+      children
+    }
+  );
+}
 
 exports.AppLayout = AppLayout;
+exports.AppLayoutWrapper = AppLayoutWrapper;
 exports.AppSidebar = AppSidebar;
 exports.NavMain = NavMain;
 exports.NavUser = NavUser;
 exports.TeamSwitcher = TeamSwitcher;
 exports.getIconComponent = getIconComponent;
 exports.useNavigation = useNavigation;
-//# sourceMappingURL=components.cjs.map
-//# sourceMappingURL=components.cjs.map
+//# sourceMappingURL=next-components.cjs.map
+//# sourceMappingURL=next-components.cjs.map