@nsxbet/admin-sdk 0.6.0 → 0.7.1

package/CHECKLIST.md

@@ -256,6 +256,18 @@ If your module was scaffolded by Lovable, the following differences apply:
 - [ ] Lovable's existing `server`, `resolve.alias`, and plugin settings are preserved — `adminModule()` only affects `vite build`
 - [ ] Build script can be `"vite build"` (Lovable default) or `"tsc && vite build"` — both work
 
+### Environment Configuration (automatic)
+
+`adminModule()` automatically injects `VITE_ADMIN_GATEWAY_URL` with the staging gateway URL (`https://admin-bff-stg.nsx.dev`). No `.env.staging` file or `--mode staging` script is needed for Lovable projects.
+
+- [ ] Do NOT create `.env.staging` — the Vite plugin handles it
+- [ ] Do NOT add `--mode staging` to the dev script
+
+To override the gateway URL, either:
+- Set `VITE_ADMIN_GATEWAY_URL` in a `.env` or `.env.local` file
+- Pass `gatewayUrl` option: `...adminModule({ gatewayUrl: "http://localhost:8080" })`
+- Disable injection: `...adminModule({ gatewayUrl: null })`
+
 Expected `vite.config.ts` for Lovable:
 
 ```typescript

package/README.md

@@ -676,6 +676,38 @@ export default defineConfig(({ mode }) => ({
 | `entry` | string | `"./src/spa.tsx"` | Entry file path |
 | `outDir` | string | `"dist"` | Output directory |
 | `additionalExternals` | string[] | `[]` | Extra externals |
+| `gatewayUrl` | `string \| null` | `undefined` | Admin gateway URL for env injection. `undefined` = auto-inject staging URL, `string` = inject custom URL, `null` = disable injection. Explicit env vars always take precedence. |
+
+### Automatic Environment Injection
+
+`adminModule()` includes an env injection plugin that automatically sets `VITE_ADMIN_GATEWAY_URL` at build time. This ensures Lovable projects get real JWT tokens from the staging gateway without any manual `.env` configuration.
+
+**Precedence order** (highest to lowest):
+
+1. Explicit env var (`.env`, `.env.local`, shell environment)
+2. `gatewayUrl` option passed to `adminModule()` or `defineModuleConfig()`
+3. Default: `https://admin-bff-stg.nsx.dev` (staging)
+
+**Known gateway URLs:**
+
+| Environment | URL |
+|---|---|
+| Staging | `https://admin-bff-stg.nsx.dev` |
+| Homol | `https://admin-bff-homol.nsx.dev` |
+| Local | `http://localhost:8080` |
+
+**Examples:**
+
+```ts
+// Default: staging URL auto-injected
+...adminModule()
+
+// Custom URL
+...adminModule({ gatewayUrl: "http://localhost:8080" })
+
+// Disable injection entirely
+...adminModule({ gatewayUrl: null })
+```
 
 ### Shared Externals
 
@@ -1103,6 +1135,8 @@ When `VITE_ADMIN_GATEWAY_URL` is set (or `gatewayUrl` is passed explicitly), the
 2. `import.meta.env.VITE_ADMIN_GATEWAY_URL` environment variable
 3. If neither is set, BFF integration is disabled (mock tokens, current behavior)
 
+> **Vite plugin auto-injection:** When using `adminModule()` or `defineModuleConfig()` from `@nsxbet/admin-sdk/vite`, the `VITE_ADMIN_GATEWAY_URL` environment variable is automatically set to the staging gateway URL. No `.env.staging` file or `--mode staging` script is needed. See the [Vite Configuration](#vite-configuration) section for override options.
+
 **Error handling:**
 
 The UserSelector shows loading, error, and timeout states during the token fetch. If the gateway is unreachable, the developer can:

package/dist/auth/client/private-network-guidance.d.ts

@@ -0,0 +1,2 @@
+export declare function isLovableContext(): boolean;
+export declare function logPrivateNetworkGuidance(previewUrl: string): void;

package/dist/auth/client/private-network-guidance.js

@@ -0,0 +1,38 @@
+const LOVABLE_DOMAINS = [".lovableproject.com", ".lovable.app"];
+export function isLovableContext() {
+    try {
+        const { hostname } = window.location;
+        return LOVABLE_DOMAINS.some((domain) => hostname.endsWith(domain));
+    }
+    catch {
+        return false;
+    }
+}
+export function logPrivateNetworkGuidance(previewUrl) {
+    try {
+        const flagsUrl = "chrome://flags/#block-insecure-private-network-requests";
+        console.groupCollapsed("%c⚠️ Private Network Access — Lovable Preview", "color: #f59e0b; font-weight: bold; font-size: 14px");
+        console.warn([
+            "Chrome is blocking requests from this Lovable iframe to your local/private network API.",
+            "The gateway token fetch failed because the browser's Private Network Access policy",
+            "prevents public origins from reaching private IPs without explicit permission.",
+            "",
+            "━━━ Option 1 (Recommended) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+            `Open this preview URL directly in a new tab:`,
+            `  👉 ${previewUrl}`,
+            "",
+            "This takes the page out of the iframe so Chrome can show the local network",
+            "access permission prompt.",
+            "",
+            "━━━ Option 2 (Alternative) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+            "Disable the Chrome flag (less secure, but works globally):",
+            `  🔧 ${flagsUrl}`,
+            "",
+            'Set "Block insecure private network requests" to Disabled, then relaunch Chrome.',
+        ].join("\n"));
+        console.groupEnd();
+    }
+    catch {
+        // best-effort — never throw from guidance logging
+    }
+}

package/dist/auth/components/UserSelector.d.ts

@@ -11,6 +11,35 @@ interface UserSelectorProps {
     /** Callback when user is selected */
     onUserSelected?: () => void;
 }
+/**
+ * Loading screen shown while fetching a BFF token.
+ */
+export declare function LoginLoadingScreen({ userName }: {
+    userName: string;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Error screen shown when the gateway returns an error or is unreachable.
+ */
+export declare function LoginErrorScreen({ errorMessage, gatewayUrl, isLovable, onRetry, onFallback, onBack, retrying, }: {
+    errorMessage: string;
+    gatewayUrl: string | null;
+    isLovable: boolean;
+    onRetry: () => void;
+    onFallback: () => void;
+    onBack: () => void;
+    retrying: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Timeout screen shown when the gateway doesn't respond in time.
+ */
+export declare function LoginTimeoutScreen({ gatewayUrl, isLovable, onRetry, onFallback, onBack, retrying, }: {
+    gatewayUrl: string | null;
+    isLovable: boolean;
+    onRetry: () => void;
+    onFallback: () => void;
+    onBack: () => void;
+    retrying: boolean;
+}): import("react/jsx-runtime").JSX.Element;
 /**
  * Main User Selector Component
  */

package/dist/auth/components/UserSelector.js

@@ -6,8 +6,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Uses Brasa Design System tokens for consistent styling.
  */
 import { useState } from 'react';
-import { Crown, Ban, Eye, User, Users, Sparkles, Wrench, Trash2, Plus, ChevronRight, Loader2, AlertCircle, Clock, ArrowLeft, RefreshCw, ShieldAlert, } from '@nsxbet/admin-ui';
+import { Crown, Ban, Eye, User, Users, Sparkles, Wrench, Trash2, Plus, ChevronRight, Loader2, AlertCircle, Clock, ArrowLeft, RefreshCw, ShieldAlert, Info, Copy, Check, ChevronDown, } from '@nsxbet/admin-ui';
+import { ExternalLink } from 'lucide-react';
 import { GatewayTimeoutError } from '../client/in-memory';
+import { isLovableContext, logPrivateNetworkGuidance } from '../client/private-network-guidance';
 /**
  * Get user icon based on roles
  */
@@ -88,9 +90,31 @@ function CustomUserForm({ onSubmit, onCancel, }) {
 /**
  * Loading screen shown while fetching a BFF token.
  */
-function LoginLoadingScreen({ userName }) {
+export function LoginLoadingScreen({ userName }) {
     return (_jsx("div", { className: "min-h-screen bg-background flex items-center justify-center p-4", children: _jsxs("div", { className: "w-full max-w-md text-center", children: [_jsx("div", { className: "inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-primary/10 mb-6", children: _jsx(Loader2, { className: "h-8 w-8 text-primary animate-spin" }) }), _jsx("h2", { className: "text-xl font-semibold text-foreground mb-2", children: "Authenticating\u2026" }), _jsxs("p", { className: "text-muted-foreground", children: ["Fetching token for ", _jsx("span", { className: "font-medium text-foreground", children: userName })] })] }) }));
 }
+/**
+ * Guidance shown on error/timeout screens when running inside a Lovable preview iframe.
+ * Explains why Chrome's Private Network Access policy blocks the gateway request
+ * and offers two resolution paths.
+ */
+function LovableNetworkGuidance() {
+    const [showAlternative, setShowAlternative] = useState(false);
+    const [copied, setCopied] = useState(false);
+    const previewUrl = typeof window !== "undefined" ? window.location.href : "";
+    const flagsUrl = "chrome://flags/#block-insecure-private-network-requests";
+    const handleCopy = async () => {
+        try {
+            await navigator.clipboard.writeText(flagsUrl);
+            setCopied(true);
+            setTimeout(() => setCopied(false), 2000);
+        }
+        catch {
+            // clipboard API may not be available in all contexts
+        }
+    };
+    return (_jsx("div", { "data-testid": "lovable-network-guidance", className: "w-full mt-4 rounded-xl border border-info/30 bg-info/5 p-4 text-left", children: _jsxs("div", { className: "flex items-start gap-3", children: [_jsx(Info, { className: "h-5 w-5 text-info flex-shrink-0 mt-0.5" }), _jsxs("div", { className: "flex-1 space-y-3", children: [_jsxs("div", { children: [_jsx("h3", { className: "text-sm font-semibold text-foreground", children: "Lovable Preview \u2014 Private Network Access" }), _jsx("p", { className: "text-sm text-muted-foreground mt-1", children: "Chrome blocks requests from Lovable's iframe to local/private network APIs. Open this preview directly in a new tab to grant permission." })] }), _jsxs("a", { href: previewUrl, target: "_blank", rel: "noopener noreferrer", className: "inline-flex items-center gap-2 px-4 py-2 rounded-lg bg-info text-info-foreground font-medium text-sm hover:bg-info/90 transition-colors", children: [_jsx(ExternalLink, { className: "h-4 w-4" }), "Open preview directly"] }), _jsxs("div", { children: [_jsxs("button", { onClick: () => setShowAlternative(!showAlternative), className: "flex items-center gap-1 text-xs text-muted-foreground hover:text-foreground transition-colors", children: [_jsx(ChevronDown, { className: `h-3.5 w-3.5 transition-transform ${showAlternative ? "rotate-180" : ""}` }), "Alternative: disable Chrome flag"] }), showAlternative && (_jsxs("div", { className: "mt-2 space-y-2", children: [_jsx("p", { className: "text-xs text-muted-foreground", children: "Disable the Private Network Access check in Chrome flags (less secure, but works globally):" }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("code", { className: "flex-1 text-xs px-3 py-1.5 rounded-md bg-muted text-foreground font-mono break-all", children: flagsUrl }), _jsx("button", { onClick: handleCopy, className: "flex-shrink-0 p-1.5 rounded-md hover:bg-muted transition-colors", title: "Copy to clipboard", children: copied ? (_jsx(Check, { className: "h-3.5 w-3.5 text-success" })) : (_jsx(Copy, { className: "h-3.5 w-3.5 text-muted-foreground" })) })] }), _jsxs("p", { className: "text-xs text-muted-foreground/70", children: ["Set \u201CBlock insecure private network requests\u201D to ", _jsx("strong", { children: "Disabled" }), ", then relaunch Chrome."] })] }))] })] })] }) }));
+}
 /**
  * Shared action bar for error / timeout screens.
  */
@@ -100,14 +124,14 @@ function LoginRecoveryActions({ onRetry, onFallback, onBack, retrying, }) {
 /**
  * Error screen shown when the gateway returns an error or is unreachable.
  */
-function LoginErrorScreen({ errorMessage, gatewayUrl, onRetry, onFallback, onBack, retrying, }) {
-    return (_jsx("div", { className: "min-h-screen bg-background flex items-center justify-center p-4", children: _jsxs("div", { className: "w-full max-w-md flex flex-col items-center text-center", children: [_jsx("div", { className: "inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-destructive/10 mb-6", children: _jsx(AlertCircle, { className: "h-8 w-8 text-destructive" }) }), _jsx("h2", { className: "text-xl font-semibold text-foreground mb-2", children: "Authentication Failed" }), _jsx("p", { className: "text-muted-foreground mb-1", children: errorMessage }), gatewayUrl && (_jsx("p", { className: "text-xs text-muted-foreground/70 font-mono break-all", children: gatewayUrl })), _jsx(LoginRecoveryActions, { onRetry: onRetry, onFallback: onFallback, onBack: onBack, retrying: retrying })] }) }));
+export function LoginErrorScreen({ errorMessage, gatewayUrl, isLovable, onRetry, onFallback, onBack, retrying, }) {
+    return (_jsx("div", { className: "min-h-screen bg-background flex items-center justify-center p-4", children: _jsxs("div", { className: "w-full max-w-md flex flex-col items-center text-center", children: [_jsx("div", { className: "inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-destructive/10 mb-6", children: _jsx(AlertCircle, { className: "h-8 w-8 text-destructive" }) }), _jsx("h2", { className: "text-xl font-semibold text-foreground mb-2", children: "Authentication Failed" }), _jsx("p", { className: "text-muted-foreground mb-1", children: errorMessage }), gatewayUrl && (_jsx("p", { className: "text-xs text-muted-foreground/70 font-mono break-all", children: gatewayUrl })), isLovable && _jsx(LovableNetworkGuidance, {}), _jsx(LoginRecoveryActions, { onRetry: onRetry, onFallback: onFallback, onBack: onBack, retrying: retrying })] }) }));
 }
 /**
  * Timeout screen shown when the gateway doesn't respond in time.
  */
-function LoginTimeoutScreen({ gatewayUrl, onRetry, onFallback, onBack, retrying, }) {
-    return (_jsx("div", { className: "min-h-screen bg-background flex items-center justify-center p-4", children: _jsxs("div", { className: "w-full max-w-md flex flex-col items-center text-center", children: [_jsx("div", { className: "inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-amber-500/10 mb-6", children: _jsx(Clock, { className: "h-8 w-8 text-amber-500" }) }), _jsx("h2", { className: "text-xl font-semibold text-foreground mb-2", children: "Gateway Timeout" }), _jsx("p", { className: "text-muted-foreground mb-1", children: "The gateway did not respond in time." }), gatewayUrl && (_jsx("p", { className: "text-xs text-muted-foreground/70 font-mono break-all", children: gatewayUrl })), _jsx(LoginRecoveryActions, { onRetry: onRetry, onFallback: onFallback, onBack: onBack, retrying: retrying })] }) }));
+export function LoginTimeoutScreen({ gatewayUrl, isLovable, onRetry, onFallback, onBack, retrying, }) {
+    return (_jsx("div", { className: "min-h-screen bg-background flex items-center justify-center p-4", children: _jsxs("div", { className: "w-full max-w-md flex flex-col items-center text-center", children: [_jsx("div", { className: "inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-amber-500/10 mb-6", children: _jsx(Clock, { className: "h-8 w-8 text-amber-500" }) }), _jsx("h2", { className: "text-xl font-semibold text-foreground mb-2", children: "Gateway Timeout" }), _jsx("p", { className: "text-muted-foreground mb-1", children: "The gateway did not respond in time." }), gatewayUrl && (_jsx("p", { className: "text-xs text-muted-foreground/70 font-mono break-all", children: gatewayUrl })), isLovable && _jsx(LovableNetworkGuidance, {}), _jsx(LoginRecoveryActions, { onRetry: onRetry, onFallback: onFallback, onBack: onBack, retrying: retrying })] }) }));
 }
 /**
  * Main User Selector Component
@@ -117,6 +141,7 @@ export function UserSelector({ authClient, onUserSelected }) {
     const [loginState, setLoginState] = useState({ status: 'idle' });
     const [, forceUpdate] = useState(0);
     const users = authClient.getAvailableUsers();
+    const isLovable = isLovableContext();
     const findUserName = (userId) => users.find((u) => u.id === userId)?.displayName ?? userId;
     const handleSelectUser = async (userId) => {
         if (!authClient.gatewayUrl) {
@@ -130,6 +155,9 @@ export function UserSelector({ authClient, onUserSelected }) {
             onUserSelected?.();
         }
         catch (error) {
+            if (isLovable) {
+                logPrivateNetworkGuidance(window.location.href);
+            }
             if (error instanceof GatewayTimeoutError) {
                 setLoginState({ status: 'timeout', userId });
             }
@@ -181,10 +209,10 @@ export function UserSelector({ authClient, onUserSelected }) {
         return _jsx(LoginLoadingScreen, { userName: findUserName(loginState.userId) });
     }
     if (loginState.status === 'error') {
-        return (_jsx(LoginErrorScreen, { errorMessage: loginState.error, gatewayUrl: authClient.gatewayUrl, onRetry: handleRetry, onFallback: handleFallbackToMock, onBack: handleBack, retrying: false }));
+        return (_jsx(LoginErrorScreen, { errorMessage: loginState.error, gatewayUrl: authClient.gatewayUrl, isLovable: isLovable, onRetry: handleRetry, onFallback: handleFallbackToMock, onBack: handleBack, retrying: false }));
     }
     if (loginState.status === 'timeout') {
-        return (_jsx(LoginTimeoutScreen, { gatewayUrl: authClient.gatewayUrl, onRetry: handleRetry, onFallback: handleFallbackToMock, onBack: handleBack, retrying: false }));
+        return (_jsx(LoginTimeoutScreen, { gatewayUrl: authClient.gatewayUrl, isLovable: isLovable, onRetry: handleRetry, onFallback: handleFallbackToMock, onBack: handleBack, retrying: false }));
     }
     return (_jsx("div", { className: "min-h-screen bg-background flex items-center justify-center p-4", children: _jsxs("div", { className: "w-full max-w-md", children: [_jsxs("div", { className: "text-center mb-8", children: [_jsx("div", { className: "inline-flex items-center justify-center w-16 h-16 rounded-2xl bg-primary mb-4 shadow-lg shadow-primary/25", children: _jsx(Users, { className: "h-8 w-8 text-primary-foreground" }) }), _jsx("h1", { className: "text-2xl font-bold text-foreground mb-2", children: "Select User" }), _jsx("p", { className: "text-muted-foreground", children: "Choose a mock user to continue in development mode" })] }), _jsx("div", { className: "space-y-3 mb-6", children: users.map((user) => {
                         const isCustom = authClient.isCustomUser(user.id);

package/dist/auth/components/UserSelector.stories.d.ts

@@ -0,0 +1,9 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+declare const meta: Meta;
+export default meta;
+export declare const LoginErrorDefault: StoryObj;
+export declare const LoginErrorLovable: StoryObj;
+export declare const LoginTimeoutDefault: StoryObj;
+export declare const LoginTimeoutLovable: StoryObj;
+export declare const Loading: StoryObj;
+export declare const Idle: StoryObj;

package/dist/auth/components/UserSelector.stories.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { LoginErrorScreen, LoginTimeoutScreen, LoginLoadingScreen, UserSelector } from "./UserSelector";
+const noop = () => { };
+const meta = {
+    title: "Auth/UserSelector",
+    parameters: {
+        layout: "fullscreen",
+    },
+};
+export default meta;
+// ---------------------------------------------------------------------------
+// LoginErrorScreen
+// ---------------------------------------------------------------------------
+export const LoginErrorDefault = {
+    name: "LoginError — Default",
+    render: () => (_jsx(LoginErrorScreen, { errorMessage: "Failed to fetch: NetworkError when attempting to fetch resource.", gatewayUrl: "https://admin-bff-stg.nsx.dev", isLovable: false, onRetry: noop, onFallback: noop, onBack: noop, retrying: false })),
+};
+export const LoginErrorLovable = {
+    name: "LoginError — Lovable Context",
+    render: () => (_jsx(LoginErrorScreen, { errorMessage: "Failed to fetch: NetworkError when attempting to fetch resource.", gatewayUrl: "https://admin-bff-stg.nsx.dev", isLovable: true, onRetry: noop, onFallback: noop, onBack: noop, retrying: false })),
+};
+// ---------------------------------------------------------------------------
+// LoginTimeoutScreen
+// ---------------------------------------------------------------------------
+export const LoginTimeoutDefault = {
+    name: "LoginTimeout — Default",
+    render: () => (_jsx(LoginTimeoutScreen, { gatewayUrl: "https://admin-bff-stg.nsx.dev", isLovable: false, onRetry: noop, onFallback: noop, onBack: noop, retrying: false })),
+};
+export const LoginTimeoutLovable = {
+    name: "LoginTimeout — Lovable Context",
+    render: () => (_jsx(LoginTimeoutScreen, { gatewayUrl: "https://admin-bff-stg.nsx.dev", isLovable: true, onRetry: noop, onFallback: noop, onBack: noop, retrying: false })),
+};
+// ---------------------------------------------------------------------------
+// LoginLoadingScreen
+// ---------------------------------------------------------------------------
+export const Loading = {
+    name: "UserSelector — Loading",
+    render: () => _jsx(LoginLoadingScreen, { userName: "Admin User" }),
+};
+// ---------------------------------------------------------------------------
+// UserSelector — Idle (full component)
+// ---------------------------------------------------------------------------
+const mockUsers = [
+    { id: "admin", displayName: "Admin User", email: "admin@nsx.bet", roles: ["admin"] },
+    { id: "editor", displayName: "Editor User", email: "editor@nsx.bet", roles: ["admin.tasks.edit", "admin.users.view"] },
+    { id: "viewer", displayName: "Viewer User", email: "viewer@nsx.bet", roles: ["admin.tasks.view", "admin.users.view"] },
+    { id: "no-access", displayName: "No Access", email: "noaccess@nsx.bet", roles: [] },
+];
+function createStoryClient() {
+    return {
+        type: "in-memory",
+        gatewayUrl: null,
+        getAvailableUsers: () => mockUsers,
+        isCustomUser: () => false,
+        login: async () => { },
+        logout: async () => { },
+        initialize: async () => false,
+        isAuthenticated: () => false,
+        hasPermission: () => false,
+        getUser: () => null,
+        getAccessToken: async () => "mock-token",
+        subscribe: () => () => { },
+        createCustomUser: async (user) => ({ id: "custom", ...user }),
+        deleteCustomUser: () => false,
+    };
+}
+export const Idle = {
+    name: "UserSelector — Idle",
+    render: () => _jsx(UserSelector, { authClient: createStoryClient() }),
+};

package/dist/components/AuthProvider.js

@@ -5,7 +5,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Works with both in-memory (mock) and Keycloak auth clients.
  * Shows user selection screen when in-memory client has no selected user.
  */
-import { createContext, useContext, useEffect, useState, useCallback } from 'react';
+import { createContext, useContext, useEffect, useState, useCallback, useMemo } from 'react';
+import { useCallbackRef } from '../hooks/useCallbackRef';
 import { UserSelector } from '../auth/components/UserSelector';
 const AuthContext = createContext(null);
 /**
@@ -80,15 +81,17 @@ export function AuthProvider({ children, authClient }) {
         });
         setNeedsUserSelection(false);
     }, [authClient]);
-    // Context value
-    const contextValue = {
+    const getAccessToken = useCallbackRef(() => authClient.getAccessToken());
+    const hasPermission = useCallbackRef((permission) => authClient.hasPermission(permission));
+    const logout = useCallbackRef(() => authClient.logout());
+    const contextValue = useMemo(() => ({
         isAuthenticated: authState.isAuthenticated,
         user: authState.user,
-        getAccessToken: () => authClient.getAccessToken(),
-        hasPermission: (permission) => authClient.hasPermission(permission),
-        logout: () => authClient.logout(),
+        getAccessToken,
+        hasPermission,
+        logout,
         authClient,
-    };
+    }), [authState.isAuthenticated, authState.user, authClient, getAccessToken, hasPermission, logout]);
     // Show loading during initialization
     if (isInitializing) {
         return _jsx(LoadingScreen, {});

package/dist/hooks/useAuth.js

@@ -1,7 +1,9 @@
 /**
  * Unified authentication hook that works in shell, standalone, and mock modes
  */
+import { useMemo } from 'react';
 import { usePlatformAPI } from './usePlatformAPI';
+import { useCallbackRef } from './useCallbackRef';
 import { useOptionalAuthContext } from '../components/AuthProvider';
 /**
  * useAuth provides authentication methods that work seamlessly across:
@@ -11,24 +13,27 @@ import { useOptionalAuthContext } from '../components/AuthProvider';
 export function useAuth() {
     const { isShellMode, api } = usePlatformAPI();
     const authContext = useOptionalAuthContext();
-    // In shell mode, use the platform API
-    if (isShellMode && api) {
-        return {
-            getAccessToken: api.auth.getAccessToken,
-            hasPermission: api.auth.hasPermission,
-            getUser: api.auth.getUser,
-            logout: api.auth.logout,
-        };
-    }
-    // Use AuthProvider context (new AuthClient-based system)
-    if (authContext) {
-        return {
-            getAccessToken: authContext.getAccessToken,
-            hasPermission: authContext.hasPermission,
-            getUser: () => authContext.user || { id: '', email: '', displayName: '', roles: [] },
-            logout: authContext.logout,
-        };
-    }
-    throw new Error('useAuth must be used within AuthProvider. ' +
-        'Wrap your app with <AuthProvider authClient={...}> from @nsxbet/admin-sdk');
+    const standaloneGetUser = useCallbackRef(authContext
+        ? () => authContext.user || { id: '', email: '', displayName: '', roles: [] }
+        : undefined);
+    return useMemo(() => {
+        if (isShellMode && api) {
+            return {
+                getAccessToken: api.auth.getAccessToken,
+                hasPermission: api.auth.hasPermission,
+                getUser: api.auth.getUser,
+                logout: api.auth.logout,
+            };
+        }
+        if (authContext) {
+            return {
+                getAccessToken: authContext.getAccessToken,
+                hasPermission: authContext.hasPermission,
+                getUser: standaloneGetUser,
+                logout: authContext.logout,
+            };
+        }
+        throw new Error('useAuth must be used within AuthProvider. ' +
+            'Wrap your app with <AuthProvider authClient={...}> from @nsxbet/admin-sdk');
+    }, [isShellMode, api, authContext, standaloneGetUser]);
 }

package/dist/hooks/useCallbackRef.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a stable function reference that always invokes the latest callback.
+ *
+ * Follows the Radix UI / "Latest Ref" pattern: the returned function identity
+ * never changes, but calling it always executes the most recent `callback`.
+ */
+export declare function useCallbackRef<T extends (...args: any[]) => any>(callback: T | undefined): T;

package/dist/hooks/useCallbackRef.js

@@ -0,0 +1,14 @@
+import { useRef, useEffect, useMemo } from 'react';
+/**
+ * Returns a stable function reference that always invokes the latest callback.
+ *
+ * Follows the Radix UI / "Latest Ref" pattern: the returned function identity
+ * never changes, but calling it always executes the most recent `callback`.
+ */
+export function useCallbackRef(callback) {
+    const callbackRef = useRef(callback);
+    useEffect(() => {
+        callbackRef.current = callback;
+    });
+    return useMemo(() => ((...args) => callbackRef.current?.(...args)), []);
+}

package/dist/hooks/usePlatformAPI.d.ts

@@ -1,6 +1,3 @@
-/**
- * Hook to access the platform API
- */
 import type { PlatformAPI } from '../types/platform';
 /**
  * Returns the platform API and whether the module is running in shell mode

package/dist/hooks/usePlatformAPI.js

@@ -1,10 +1,12 @@
+/**
+ * Hook to access the platform API
+ */
+import { useMemo } from 'react';
 /**
  * Returns the platform API and whether the module is running in shell mode
  */
 export function usePlatformAPI() {
     const isShellMode = typeof window !== 'undefined' && window.__ADMIN_PLATFORM_API__ !== undefined;
-    return {
-        isShellMode,
-        api: isShellMode ? window.__ADMIN_PLATFORM_API__ : undefined,
-    };
+    const api = isShellMode ? window.__ADMIN_PLATFORM_API__ : undefined;
+    return useMemo(() => ({ isShellMode, api }), [isShellMode, api]);
 }

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { useFetch } from './hooks/useFetch';
 export { useTelemetry } from './hooks/useTelemetry';
 export { useI18n } from './hooks/useI18n';
 export { useTimestamp } from './hooks/useTimestamp';
+export { useCallbackRef } from './hooks/useCallbackRef';
 export { createInMemoryAuthClient, clearInMemoryAuth, createMockUsersFromRoles, createKeycloakAuthClient, UserSelector, } from './auth';
 export type { AuthClient, InMemoryAuthClient, MockUser, MockUserRoles, AuthState, AuthStateCallback, InMemoryAuthClientOptions, KeycloakAuthClientOptions, } from './auth';
 export type { PlatformAPI, Breadcrumb, User, TimezoneMode, TimestampFormat } from './types/platform';

package/dist/index.js

@@ -14,6 +14,7 @@ export { useFetch } from './hooks/useFetch';
 export { useTelemetry } from './hooks/useTelemetry';
 export { useI18n } from './hooks/useI18n';
 export { useTimestamp } from './hooks/useTimestamp';
+export { useCallbackRef } from './hooks/useCallbackRef';
 // Auth Client
 export { createInMemoryAuthClient, clearInMemoryAuth, createMockUsersFromRoles, createKeycloakAuthClient, UserSelector, } from './auth';
 // i18n

package/dist/registry/AdminShellRegistry.js

@@ -26,6 +26,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * ```
  */
 import { createContext, useContext, useState, useEffect, useCallback, useMemo, } from 'react';
+import { useCallbackRef } from '../hooks/useCallbackRef';
 const RegistryContext = createContext(null);
 /**
  * Registry provider component
@@ -51,14 +52,14 @@ export function AdminShellRegistry({ store, children, onModulesChange, }) {
     const [modules, setModules] = useState([]);
     const [isLoading, setIsLoading] = useState(true);
     const [error, setError] = useState(null);
-    // Load modules from registry
+    const stableOnModulesChange = useCallbackRef(onModulesChange);
     const reload = useCallback(async () => {
         setIsLoading(true);
         setError(null);
         try {
             const result = await store.modules.findAll();
             setModules(result);
-            onModulesChange?.(result);
+            stableOnModulesChange(result);
         }
         catch (err) {
             setError(err instanceof Error ? err : new Error('Failed to load modules'));
@@ -67,7 +68,7 @@ export function AdminShellRegistry({ store, children, onModulesChange, }) {
         finally {
             setIsLoading(false);
         }
-    }, [store, onModulesChange]);
+    }, [store, stableOnModulesChange]);
     // Initial load
     useEffect(() => {
         reload();

package/dist/shell/components/theme-provider.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useState } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 const initialState = {
     theme: "system",
     setTheme: () => null,
@@ -24,13 +24,11 @@ storageKey = "admin-ui-theme", ...props }) {
         }
         root.classList.add(theme);
     }, [theme]);
-    const value = {
-        theme,
-        setTheme: (theme) => {
-            localStorage.setItem(storageKey, theme);
-            setTheme(theme);
-        },
-    };
+    const setThemeStable = useCallback((newTheme) => {
+        localStorage.setItem(storageKey, newTheme);
+        setTheme(newTheme);
+    }, [storageKey]);
+    const value = useMemo(() => ({ theme, setTheme: setThemeStable }), [theme, setThemeStable]);
     return (_jsx(ThemeProviderContext.Provider, { ...props, value: value, children: children }));
 }
 // eslint-disable-next-line react-refresh/only-export-components

package/dist/vite/config.d.ts

@@ -1,4 +1,9 @@
-import type { Plugin } from "vite";
+import { type Plugin } from "vite";
+/**
+ * Default admin gateway URL (staging environment).
+ * Used by the env injection plugin when no explicit value is configured.
+ */
+export declare const ADMIN_GATEWAY_STAGING_URL = "https://admin-bff-stg.nsx.dev";
 /**
  * Shared dependencies that are externalized in module builds.
  * These are provided by the shell via import maps.
@@ -28,6 +33,15 @@ export interface AdminModuleOptions {
      * - "always": Always apply during `vite build`. Used by defineModuleConfig().
      */
     buildMode?: "auto" | "always";
+    /**
+     * Admin gateway URL for BFF token integration (InMemory auth).
+     * - `undefined` (default): auto-inject staging URL (`https://admin-bff-stg.nsx.dev`)
+     * - `string`: inject the provided URL
+     * - `null`: disable automatic injection entirely
+     *
+     * Explicit env vars (`.env` files, shell env) always take precedence over this option.
+     */
+    gatewayUrl?: string | null;
 }
 export interface ModuleConfigOptions extends AdminModuleOptions {
     /**

package/dist/vite/config.js

@@ -1,6 +1,13 @@
+import { loadEnv } from "vite";
 import { generateModuleManifestPlugin, serveDistPlugin } from "./plugins.js";
 import { adminModuleI18nPlugin } from "./i18n-plugin.js";
 import { getSharedExternals } from "./AdminShellSharedDeps.js";
+const ENV_KEY = "VITE_ADMIN_GATEWAY_URL";
+/**
+ * Default admin gateway URL (staging environment).
+ * Used by the env injection plugin when no explicit value is configured.
+ */
+export const ADMIN_GATEWAY_STAGING_URL = "https://admin-bff-stg.nsx.dev";
 /**
  * Shared dependencies that are externalized in module builds.
  * These are provided by the shell via import maps.
@@ -40,13 +47,33 @@ export const SHARED_EXTERNALS = getSharedExternals();
  * ```
  */
 export function adminModule(options = {}) {
-    const { entry = "./src/spa.tsx", outDir = "dist", additionalExternals = [], buildMode = "auto", } = options;
+    const { entry = "./src/spa.tsx", outDir = "dist", additionalExternals = [], buildMode = "auto", gatewayUrl, } = options;
     const externals = [...SHARED_EXTERNALS, ...additionalExternals];
     function isModuleBuild() {
         if (buildMode === "always")
             return true;
         return process.env.ADMIN_MODULE === "true";
     }
+    const envPlugin = {
+        name: "admin-module-env",
+        config(_config, { mode }) {
+            if (gatewayUrl === null)
+                return;
+            const env = loadEnv(mode, process.cwd(), "VITE_");
+            const fromEnv = process.env[ENV_KEY] || env[ENV_KEY];
+            if (fromEnv) {
+                console.log(`[admin-module-env] ${ENV_KEY} → ${fromEnv} (from env)`);
+                return;
+            }
+            const url = gatewayUrl ?? ADMIN_GATEWAY_STAGING_URL;
+            console.log(`[admin-module-env] ${ENV_KEY} → ${url} (auto-injected)`);
+            return {
+                define: {
+                    [`import.meta.env.${ENV_KEY}`]: JSON.stringify(url),
+                },
+            };
+        },
+    };
     const buildConfigPlugin = {
         name: "admin-module-build-config",
         config(_config, { command }) {
@@ -73,6 +100,7 @@ export function adminModule(options = {}) {
         },
     };
     return [
+        envPlugin,
         adminModuleI18nPlugin(),
         serveDistPlugin({ distDir: outDir }),
         generateModuleManifestPlugin(),

package/dist/vite/index.d.ts

@@ -15,5 +15,5 @@
  */
 export { generateModuleManifestPlugin, serveDistPlugin, type GenerateModuleManifestPluginOptions, type ServeDistPluginOptions, } from "./plugins.js";
 export { adminModuleI18nPlugin, type AdminModuleI18nPluginOptions, } from "./i18n-plugin.js";
-export { adminModule, defineModuleConfig, SHARED_EXTERNALS, type AdminModuleOptions, type ModuleConfigOptions, } from "./config.js";
+export { adminModule, defineModuleConfig, SHARED_EXTERNALS, ADMIN_GATEWAY_STAGING_URL, type AdminModuleOptions, type ModuleConfigOptions, } from "./config.js";
 export { AdminShellSharedDeps, SHARED_DEPS_CONFIG, getSharedExternals, type SharedDepConfig, } from "./AdminShellSharedDeps.js";

package/dist/vite/index.js

@@ -15,5 +15,5 @@
  */
 export { generateModuleManifestPlugin, serveDistPlugin, } from "./plugins.js";
 export { adminModuleI18nPlugin, } from "./i18n-plugin.js";
-export { adminModule, defineModuleConfig, SHARED_EXTERNALS, } from "./config.js";
+export { adminModule, defineModuleConfig, SHARED_EXTERNALS, ADMIN_GATEWAY_STAGING_URL, } from "./config.js";
 export { AdminShellSharedDeps, SHARED_DEPS_CONFIG, getSharedExternals, } from "./AdminShellSharedDeps.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nsxbet/admin-sdk",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "SDK for building NSX Admin modules with integrated shell",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,7 +37,9 @@
     "build": "tsc",
     "dev": "tsc --watch --preserveWatchOutput",
     "type-check": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests"
+    "test": "vitest run --passWithNoTests",
+    "storybook": "storybook dev -p 6007 --host 0.0.0.0",
+    "build-storybook": "storybook build -o storybook-static"
   },
   "peerDependencies": {
     "@vitejs/plugin-react": "^4.0.0",
@@ -66,14 +68,20 @@
   },
   "devDependencies": {
     "@nsxbet/admin-ui": "workspace:*",
+    "@storybook/react-vite": "^10.3.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
     "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.27",
     "i18next": "^25.7.4",
+    "postcss": "^8.5.8",
     "react-i18next": "^16.5.3",
     "react-router-dom": "^6.20.1",
+    "storybook": "^10.3.0",
+    "tailwindcss": "^3.4.0",
+    "tailwindcss-animate": "^1.0.7",
     "typescript": "^5.7.0",
     "vite": "^6.0.0",
     "vitest": "^1.0.0"