@mereb/web-runtime 0.0.1

package/dist/config.d.ts

@@ -0,0 +1,26 @@
+type ShellRuntimeEnv = {
+    REMOTE_MANIFEST_URL?: string;
+    GRAPHQL_URL?: string;
+    FLAGS_URL?: string;
+    KEYCLOAK_URL?: string;
+    KC_REALM?: string;
+    KC_CLIENT_ID?: string;
+};
+declare global {
+    interface Window {
+        __MEREB_ENV__?: Partial<ShellRuntimeEnv>;
+    }
+}
+export declare const appConfig: {
+    remoteManifestUrl: string;
+    graphqlUrl: string;
+    flagsUrl: string;
+    keycloak: {
+        url: string;
+        realm: string;
+        clientId: string;
+    };
+};
+export type AppConfig = typeof appConfig;
+export declare function resolveKeycloakMissingKeys(): readonly (keyof typeof appConfig.keycloak)[];
+export {};

package/dist/config.js

@@ -0,0 +1,34 @@
+const defaultRuntime = {
+    REMOTE_MANIFEST_URL: '',
+    GRAPHQL_URL: 'http://localhost:8000/graphql',
+    FLAGS_URL: 'http://localhost:8000/flags',
+    KEYCLOAK_URL: 'http://localhost:8081',
+    KC_REALM: 'social',
+    KC_CLIENT_ID: 'web-shell'
+};
+const runtimeEnv = globalThis.window === undefined ? {} : globalThis.window.__MEREB_ENV__ ?? {};
+function resolveEnv(metaValue, key) {
+    const trimmedMeta = metaValue?.trim();
+    if (trimmedMeta) {
+        return trimmedMeta;
+    }
+    const runtimeValue = runtimeEnv[key]?.trim();
+    if (runtimeValue) {
+        return runtimeValue;
+    }
+    return defaultRuntime[key] ?? '';
+}
+export const appConfig = {
+    remoteManifestUrl: resolveEnv(import.meta.env.VITE_REMOTE_MANIFEST_URL, 'REMOTE_MANIFEST_URL'),
+    graphqlUrl: resolveEnv(import.meta.env.VITE_GRAPHQL_URL, 'GRAPHQL_URL'),
+    flagsUrl: resolveEnv(import.meta.env.VITE_FLAGS_URL, 'FLAGS_URL'),
+    keycloak: {
+        url: resolveEnv(import.meta.env.VITE_KEYCLOAK_URL, 'KEYCLOAK_URL'),
+        realm: resolveEnv(import.meta.env.VITE_KC_REALM, 'KC_REALM'),
+        clientId: resolveEnv(import.meta.env.VITE_KC_CLIENT_ID, 'KC_CLIENT_ID')
+    }
+};
+export function resolveKeycloakMissingKeys() {
+    const keys = ['url', 'realm', 'clientId'];
+    return keys.filter((key) => !appConfig.keycloak[key]);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './config.js';
+export * from './providers/AppProviders.js';
+export * from './providers/auth.js';
+export * from './providers/flags.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './config.js';
+export * from './providers/AppProviders.js';
+export * from './providers/auth.js';
+export * from './providers/flags.js';

package/dist/providers/AppProviders.d.ts

@@ -0,0 +1,2 @@
+import type { PropsWithChildren } from 'react';
+export declare function AppProviders({ children }: Readonly<PropsWithChildren>): import("react/jsx-runtime").JSX.Element;

package/dist/providers/AppProviders.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { ApolloClient, HttpLink, InMemoryCache } from '@apollo/client';
+import { ApolloProvider } from '@apollo/client/react';
+import { AuthProvider, useAuthToken } from './auth.js';
+import { FlagsProvider } from './flags.js';
+import { appConfig } from '../config.js';
+function GraphProvider({ children }) {
+    const token = useAuthToken();
+    const client = useMemo(() => new ApolloClient({
+        link: new HttpLink({
+            uri: appConfig.graphqlUrl,
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                ...(token ? { Authorization: `Bearer ${token}` } : {})
+            }
+        }),
+        cache: new InMemoryCache()
+    }), [token]);
+    return _jsx(ApolloProvider, { client: client, children: children });
+}
+export function AppProviders({ children }) {
+    return (_jsx(AuthProvider, { children: _jsx(FlagsProvider, { children: _jsx(GraphProvider, { children: children }) }) }));
+}

package/dist/providers/auth.d.ts

@@ -0,0 +1,30 @@
+import type { KeycloakLoginOptions, KeycloakRegisterOptions } from 'keycloak-js';
+import type { ReactNode } from 'react';
+type AdminAccessLevel = 'full' | 'limited' | 'none';
+export type AuthProfile = {
+    id: string;
+    username?: string;
+    name?: string;
+    email?: string;
+    roles: string[];
+    adminAccess: AdminAccessLevel;
+};
+type AuthContextValue = {
+    isReady: boolean;
+    isAuthConfigured: boolean;
+    isAuthenticated: boolean;
+    token?: string;
+    profile?: AuthProfile;
+    login: (options?: KeycloakLoginOptions) => void;
+    register: (options?: KeycloakRegisterOptions) => void;
+    logout: () => void;
+    hasRole: (role: string) => boolean;
+    hasAnyRole: (roles: string[]) => boolean;
+    missingConfigKeys: readonly string[];
+};
+export declare function AuthProvider({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react/jsx-runtime").JSX.Element;
+export declare const useAuth: () => AuthContextValue;
+export declare const useAuthToken: () => string | undefined;
+export {};

package/dist/providers/auth.js

@@ -0,0 +1,271 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import Keycloak from 'keycloak-js';
+import { appConfig, resolveKeycloakMissingKeys } from '../config.js';
+const AuthCtx = createContext({
+    isReady: false,
+    isAuthConfigured: false,
+    isAuthenticated: false,
+    token: undefined,
+    profile: undefined,
+    login: () => { },
+    register: () => { },
+    logout: () => { },
+    hasRole: () => false,
+    hasAnyRole: () => false,
+    missingConfigKeys: []
+});
+const keycloakConfig = {
+    url: appConfig.keycloak.url,
+    realm: appConfig.keycloak.realm,
+    clientId: appConfig.keycloak.clientId
+};
+const missingConfigKeys = resolveKeycloakMissingKeys();
+const isKeycloakConfigured = missingConfigKeys.length === 0;
+let keycloakInstance = null;
+let keycloakInitPromise = null;
+const FULL_ADMIN_ROLES = new Set(['admin', 'mereb.admin', 'realm-admin']);
+const LIMITED_ADMIN_ROLES = new Set(['moderator', 'support', 'admin.viewer', 'mereb.staff']);
+function extractRoles(token) {
+    if (!token)
+        return [];
+    const realmRoles = token.realm_access?.roles ?? [];
+    const resourceRoles = Object.values(token.resource_access ?? {}).flatMap((access) => access.roles ?? []);
+    return Array.from(new Set([...realmRoles, ...resourceRoles]));
+}
+function determineAdminAccess(roles) {
+    if (roles.some((role) => FULL_ADMIN_ROLES.has(role)))
+        return 'full';
+    if (roles.some((role) => LIMITED_ADMIN_ROLES.has(role)))
+        return 'limited';
+    return 'none';
+}
+function buildProfile(instance) {
+    if (!instance.authenticated || !instance.tokenParsed)
+        return undefined;
+    const parsed = instance.tokenParsed;
+    const roles = extractRoles(parsed);
+    return {
+        id: parsed?.sub ?? '',
+        username: parsed?.preferred_username,
+        name: parsed?.name,
+        email: parsed?.email,
+        roles,
+        adminAccess: determineAdminAccess(roles)
+    };
+}
+function getKeycloak() {
+    if (!isKeycloakConfigured) {
+        throw new Error(`Keycloak configuration is incomplete (missing: ${missingConfigKeys.join(', ')})`);
+    }
+    keycloakInstance ??= new Keycloak(keycloakConfig);
+    return keycloakInstance;
+}
+function extractErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message ?? '';
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object') {
+        const errObj = error;
+        let maybeMessage;
+        if ('error_description' in errObj) {
+            maybeMessage = errObj.error_description;
+        }
+        else if ('error' in errObj) {
+            maybeMessage = errObj.error;
+        }
+        if (typeof maybeMessage === 'string') {
+            return maybeMessage;
+        }
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return '';
+        }
+    }
+    return '';
+}
+function shouldRetryWithoutPkce(error) {
+    const message = extractErrorMessage(error).toLowerCase();
+    if (!message)
+        return false;
+    return message.includes('pkce') || message.includes('code_challenge');
+}
+function shouldDisableSilentSso(error) {
+    const message = extractErrorMessage(error).toLowerCase();
+    if (!message)
+        return false;
+    return message.includes('3rd party check iframe');
+}
+function resetPkceState(instance) {
+    ;
+    instance.pkceMethod = undefined;
+}
+function disableSilentSso(instance) {
+    const mutableInstance = instance;
+    mutableInstance.silentCheckSsoRedirectUri = false;
+    mutableInstance.silentCheckSsoFallback = false;
+}
+async function attemptKeycloakInit(instance, options) {
+    try {
+        return await instance.init(options);
+    }
+    catch (error) {
+        if (options.pkceMethod && shouldRetryWithoutPkce(error)) {
+            console.warn('[auth] Keycloak PKCE handshake failed. Retrying without PKCE. Enable PKCE (S256) on the client to avoid this fallback.', error);
+            const fallbackOptions = { ...options };
+            delete fallbackOptions.pkceMethod;
+            resetPkceState(instance);
+            return attemptKeycloakInit(instance, fallbackOptions);
+        }
+        if (options.silentCheckSsoRedirectUri && shouldDisableSilentSso(error)) {
+            console.warn('[auth] Silent SSO cookie probe failed (likely blocked /protocol/openid-connect/3p-cookies). Retrying without silent SSO so the shell can still load.', error);
+            const fallbackOptions = { ...options };
+            delete fallbackOptions.silentCheckSsoRedirectUri;
+            fallbackOptions.silentCheckSsoFallback = false;
+            disableSilentSso(instance);
+            return attemptKeycloakInit(instance, fallbackOptions);
+        }
+        throw error;
+    }
+}
+function initKeycloak() {
+    if (!isKeycloakConfigured)
+        return Promise.resolve(false);
+    if (!keycloakInitPromise) {
+        const instance = getKeycloak();
+        const options = {
+            onLoad: 'check-sso',
+            pkceMethod: 'S256',
+            silentCheckSsoRedirectUri: `${globalThis.location.origin}/silent-check-sso.html`,
+            checkLoginIframe: false,
+            useNonce: false
+        };
+        keycloakInitPromise = attemptKeycloakInit(instance, options).catch((error) => {
+            keycloakInitPromise = null;
+            throw error ?? new Error('Keycloak init failed');
+        });
+    }
+    return keycloakInitPromise;
+}
+export function AuthProvider({ children }) {
+    const [isReady, setIsReady] = useState(!isKeycloakConfigured);
+    const [isAuthenticated, setIsAuthenticated] = useState(false);
+    const [token, setToken] = useState();
+    const [profile, setProfile] = useState();
+    useEffect(() => {
+        if (!isKeycloakConfigured) {
+            console.warn('[auth] Keycloak is disabled because the following env vars are missing:', missingConfigKeys.join(', '));
+            setIsReady(true);
+            return;
+        }
+        let isCancelled = false;
+        const instance = getKeycloak();
+        const syncFromInstance = () => {
+            if (isCancelled)
+                return;
+            setIsAuthenticated(Boolean(instance.authenticated));
+            setToken(instance.token ?? undefined);
+            setProfile(buildProfile(instance));
+        };
+        initKeycloak()
+            .then((authenticated) => {
+            if (isCancelled)
+                return;
+            if (authenticated) {
+                syncFromInstance();
+            }
+            else {
+                setIsAuthenticated(false);
+                setToken(undefined);
+                setProfile(undefined);
+            }
+            setIsReady(true);
+        })
+            .catch((err) => {
+            console.error('Keycloak failed to initialise', err ?? new Error('Unknown Keycloak init failure'));
+            if (!isCancelled) {
+                setIsReady(true);
+            }
+        });
+        instance.onTokenExpired = () => {
+            void instance.updateToken(0)
+                .then(() => syncFromInstance())
+                .catch((err) => {
+                console.error('Failed to refresh Keycloak token', err);
+            });
+        };
+        instance.onAuthSuccess = syncFromInstance;
+        instance.onAuthRefreshSuccess = syncFromInstance;
+        instance.onAuthLogout = () => {
+            if (isCancelled)
+                return;
+            setIsAuthenticated(false);
+            setToken(undefined);
+            setProfile(undefined);
+        };
+        const refreshId = globalThis.setInterval(async () => {
+            if (!instance.authenticated)
+                return;
+            const refreshed = await instance.updateToken(30).catch(() => false);
+            if (refreshed)
+                syncFromInstance();
+        }, 20_000);
+        return () => {
+            isCancelled = true;
+            globalThis.clearInterval(refreshId);
+            instance.onTokenExpired = () => { };
+            instance.onAuthSuccess = () => { };
+            instance.onAuthRefreshSuccess = () => { };
+            instance.onAuthLogout = () => { };
+        };
+    }, []);
+    const login = useCallback((options) => {
+        if (!isKeycloakConfigured) {
+            console.warn('[auth] Keycloak login skipped: configuration is missing.', missingConfigKeys);
+            return;
+        }
+        getKeycloak().login(options).catch((err) => {
+            console.error('Keycloak login failed', err);
+        });
+    }, []);
+    const register = useCallback((options) => {
+        if (!isKeycloakConfigured) {
+            console.warn('[auth] Keycloak register skipped: configuration is missing.', missingConfigKeys);
+            return;
+        }
+        getKeycloak().register(options).catch((err) => {
+            console.error('Keycloak registration failed', err);
+        });
+    }, []);
+    const logout = useCallback(() => {
+        if (!isKeycloakConfigured) {
+            console.warn('[auth] Keycloak logout skipped: configuration is missing.', missingConfigKeys);
+            return;
+        }
+        getKeycloak().logout().catch((err) => {
+            console.error('Keycloak logout failed', err);
+        });
+    }, []);
+    const roleSet = useMemo(() => new Set(profile?.roles ?? []), [profile]);
+    const value = useMemo(() => ({
+        isReady,
+        isAuthConfigured: isKeycloakConfigured,
+        isAuthenticated,
+        token,
+        profile,
+        login,
+        register,
+        logout,
+        hasRole: (role) => roleSet.has(role),
+        hasAnyRole: (roles) => roles.some((role) => roleSet.has(role)),
+        missingConfigKeys
+    }), [isReady, isAuthenticated, token, profile, login, register, logout, roleSet]);
+    return _jsx(AuthCtx.Provider, { value: value, children: children });
+}
+export const useAuth = () => useContext(AuthCtx);
+export const useAuthToken = () => useAuth().token;

package/dist/providers/flags.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+export type Flags = Record<string, boolean>;
+type FlagsContextValue = {
+    flags: Flags;
+    loading: boolean;
+    error?: string;
+};
+export declare function FlagsProvider({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react/jsx-runtime").JSX.Element;
+export declare function useFlags(): FlagsContextValue;
+export declare function useFlag(name: string): boolean;
+export {};

package/dist/providers/flags.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { appConfig } from '../config.js';
+const FlagsCtx = createContext({
+    flags: {},
+    loading: false,
+    error: undefined
+});
+export function FlagsProvider({ children }) {
+    const [flags, setFlags] = useState({});
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState();
+    useEffect(() => {
+        if (!appConfig.flagsUrl) {
+            setFlags({});
+            setLoading(false);
+            setError(undefined);
+            return;
+        }
+        const controller = new AbortController();
+        setLoading(true);
+        setError(undefined);
+        fetch(appConfig.flagsUrl, { credentials: 'include', signal: controller.signal })
+            .then(async (response) => {
+            if (!response.ok) {
+                throw new Error(`Flags request failed (${response.status})`);
+            }
+            return response.json();
+        })
+            .then((nextFlags) => {
+            setFlags(nextFlags);
+        })
+            .catch((err) => {
+            if (controller.signal.aborted)
+                return;
+            setFlags({});
+            setError(err instanceof Error ? err.message : 'Unknown error');
+        })
+            .finally(() => {
+            if (!controller.signal.aborted) {
+                setLoading(false);
+            }
+        });
+        return () => controller.abort();
+    }, []);
+    const value = useMemo(() => ({
+        flags,
+        loading,
+        error
+    }), [flags, loading, error]);
+    return _jsx(FlagsCtx.Provider, { value: value, children: children });
+}
+export function useFlags() {
+    return useContext(FlagsCtx);
+}
+export function useFlag(name) {
+    return useFlags().flags[name];
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@mereb/web-runtime",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "default": "./dist/config.js"
+    },
+    "./auth": {
+      "types": "./dist/providers/auth.d.ts",
+      "import": "./dist/providers/auth.js",
+      "default": "./dist/providers/auth.js"
+    },
+    "./flags": {
+      "types": "./dist/providers/flags.d.ts",
+      "import": "./dist/providers/flags.js",
+      "default": "./dist/providers/flags.js"
+    },
+    "./AppProviders": {
+      "types": "./dist/providers/AppProviders.d.ts",
+      "import": "./dist/providers/AppProviders.js",
+      "default": "./dist/providers/AppProviders.js"
+    }
+  },
+  "dependencies": {
+    "@apollo/client": "^4.0.7",
+    "keycloak-js": "^23.0.7"
+  },
+  "peerDependencies": {
+    "graphql": "^16.0.0",
+    "react": ">=18.2.0 <19",
+    "react-dom": ">=18.2.0 <19"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^18.2.79",
+    "husky": "^9.1.7",
+    "jsdom": "^26.1.0",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "typescript": "~5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "clean": "node -e \"const fs=require('node:fs'); fs.rmSync('dist',{recursive:true,force:true}); fs.rmSync('tsconfig.tsbuildinfo',{force:true});\"",
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "test": "pnpm exec vitest run --config vitest.config.ts",
+    "test:watch": "pnpm exec vitest --config vitest.config.ts",
+    "build": "pnpm run clean && tsc --project tsconfig.json",
+    "version:bump": "node ./scripts/bump-version.mjs"
+  }
+}