@tumbaland/frontend-core 1.1.0

package/dist/apiClient.d.ts

@@ -0,0 +1,33 @@
+export interface ApiClientOptions {
+    /** Read fresh at call time (config may not be resolved yet at module load). */
+    baseUrl: () => string;
+    /** Called on a 401 response, e.g. to redirect to the login page. */
+    onUnauthorized?: () => void;
+}
+export interface ApiRequestOptions extends RequestInit {
+    /** Skip the onUnauthorized callback for this call (e.g. an auth-check that expects 401 as a normal "not logged in" result, not a hard redirect). */
+    skipAuthRedirect?: boolean;
+}
+export declare class ApiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+}
+/**
+ * Generic authenticated JSON fetch wrapper — base URL handling, credentials,
+ * correlation/session headers, structured errors, and an opt-in 401 →
+ * redirect-to-auth hook, per TECHNICAL_REVIEW.md P1.3. `authService` and
+ * `groupService` don't route through this: they use different auth
+ * transports (cookie vs. Bearer token) that predate this client. New
+ * call sites (the many per-front album/finance/etc. service files that
+ * still hand-roll fetch) can adopt this incrementally.
+ */
+export declare function createApiClient(options: ApiClientOptions): {
+    request: <T = unknown>(path: string, init?: ApiRequestOptions) => Promise<T>;
+    get: <T = unknown>(path: string, init?: ApiRequestOptions) => Promise<T>;
+    post: <T = unknown>(path: string, body?: unknown, init?: ApiRequestOptions) => Promise<T>;
+    put: <T = unknown>(path: string, body?: unknown, init?: ApiRequestOptions) => Promise<T>;
+    patch: <T = unknown>(path: string, body?: unknown, init?: ApiRequestOptions) => Promise<T>;
+    delete: <T = unknown>(path: string, init?: ApiRequestOptions) => Promise<T>;
+};
+export type ApiClient = ReturnType<typeof createApiClient>;

package/dist/apiClient.js

@@ -0,0 +1,59 @@
+import { getCorrelationId, getSessionId } from '@tumbaland/components';
+export class ApiError extends Error {
+    constructor(status, message, body) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * Generic authenticated JSON fetch wrapper — base URL handling, credentials,
+ * correlation/session headers, structured errors, and an opt-in 401 →
+ * redirect-to-auth hook, per TECHNICAL_REVIEW.md P1.3. `authService` and
+ * `groupService` don't route through this: they use different auth
+ * transports (cookie vs. Bearer token) that predate this client. New
+ * call sites (the many per-front album/finance/etc. service files that
+ * still hand-roll fetch) can adopt this incrementally.
+ */
+export function createApiClient(options) {
+    async function request(path, init = {}) {
+        const { skipAuthRedirect, headers, ...rest } = init;
+        const response = await fetch(`${options.baseUrl()}${path}`, {
+            credentials: 'include',
+            ...rest,
+            headers: {
+                'Content-Type': 'application/json',
+                'x-correlation-id': getCorrelationId(),
+                'x-session-id': getSessionId(),
+                ...headers
+            }
+        });
+        if (response.status === 401 && !skipAuthRedirect) {
+            options.onUnauthorized?.();
+        }
+        if (!response.ok) {
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch {
+                // response wasn't JSON — leave body undefined
+            }
+            const message = body?.message ?? `HTTP error! status: ${response.status}`;
+            throw new ApiError(response.status, message, body);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        return response.json();
+    }
+    return {
+        request,
+        get: (path, init) => request(path, { ...init, method: 'GET' }),
+        post: (path, body, init) => request(path, { ...init, method: 'POST', body: body !== undefined ? JSON.stringify(body) : undefined }),
+        put: (path, body, init) => request(path, { ...init, method: 'PUT', body: body !== undefined ? JSON.stringify(body) : undefined }),
+        patch: (path, body, init) => request(path, { ...init, method: 'PATCH', body: body !== undefined ? JSON.stringify(body) : undefined }),
+        delete: (path, init) => request(path, { ...init, method: 'DELETE' })
+    };
+}

package/dist/authService.d.ts

@@ -0,0 +1,35 @@
+import { AuthResponse, User } from './types';
+export interface AuthServiceConfig {
+    /** Read fresh at call time (config may not be resolved yet at module load). */
+    getAuthServiceUrl: () => string;
+    getAuthFrontUrl: () => string;
+}
+/**
+ * Builds a per-front auth service instance. Each of the 7 frontends that
+ * previously hand-rolled their own (six divergent copies, per
+ * TECHNICAL_REVIEW.md P1.3) now just wire this up with their own config
+ * accessor:
+ *
+ *   export const authService = createAuthService({
+ *     getAuthServiceUrl: () => getGlobalConfig().AUTH_SERVICE_URL!,
+ *     getAuthFrontUrl: () => getGlobalConfig().AUTH_FRONT_URL!
+ *   });
+ */
+export declare function createAuthService(config: AuthServiceConfig): {
+    /** Sync the JWT from cookie to localStorage. Call once on app start. */
+    init(): void;
+    getToken(): string | null;
+    syncToken(): void;
+    clearAuthCache(): void;
+    /** Verifies the session against auth-service. Cached for 5 minutes. */
+    checkAuth(): Promise<AuthResponse>;
+    redirectToLogin(returnUrl?: string): void;
+    logout(): Promise<boolean>;
+    getCurrentUser(): Promise<User | null>;
+    /** Full profile (e.g. firstName/lastName) — only auth-service's /auth/profile has this. */
+    getProfile(): Promise<User | null>;
+    /** Decodes the local JWT directly — no network call, but can be stale. */
+    getCurrentUserFromToken(): User | null;
+    isAuthenticated(): Promise<boolean>;
+};
+export type AuthService = ReturnType<typeof createAuthService>;

package/dist/authService.js

@@ -0,0 +1,162 @@
+import { getCorrelationId, getSessionId } from '@tumbaland/components';
+const AUTH_CACHE_TTL = 5 * 60 * 1000;
+function authHeaders() {
+    return {
+        'Content-Type': 'application/json',
+        'x-correlation-id': getCorrelationId(),
+        'x-session-id': getSessionId()
+    };
+}
+function getJwtTokenFromCookie(cookieName = 'access_token') {
+    const match = document.cookie.match(new RegExp('(^| )' + cookieName + '=([^;]+)'));
+    return match ? match[2] : null;
+}
+/**
+ * Builds a per-front auth service instance. Each of the 7 frontends that
+ * previously hand-rolled their own (six divergent copies, per
+ * TECHNICAL_REVIEW.md P1.3) now just wire this up with their own config
+ * accessor:
+ *
+ *   export const authService = createAuthService({
+ *     getAuthServiceUrl: () => getGlobalConfig().AUTH_SERVICE_URL!,
+ *     getAuthFrontUrl: () => getGlobalConfig().AUTH_FRONT_URL!
+ *   });
+ */
+export function createAuthService(config) {
+    let authCache = null;
+    let authCacheTime = 0;
+    function syncJwtToken() {
+        const token = getJwtTokenFromCookie();
+        if (token && localStorage.getItem('authToken') !== token) {
+            localStorage.setItem('authToken', token);
+        }
+    }
+    return {
+        /** Sync the JWT from cookie to localStorage. Call once on app start. */
+        init() {
+            syncJwtToken();
+        },
+        getToken() {
+            return localStorage.getItem('authToken');
+        },
+        syncToken() {
+            syncJwtToken();
+        },
+        clearAuthCache() {
+            authCache = null;
+            authCacheTime = 0;
+        },
+        /** Verifies the session against auth-service. Cached for 5 minutes. */
+        async checkAuth() {
+            const now = Date.now();
+            if (authCache && now - authCacheTime < AUTH_CACHE_TTL) {
+                return authCache;
+            }
+            try {
+                const response = await fetch(`${config.getAuthServiceUrl()}/auth/verify`, {
+                    credentials: 'include',
+                    headers: authHeaders()
+                });
+                if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+                const data = await response.json();
+                const result = {
+                    authenticated: data.success && data.authenticated,
+                    user: data.user || null
+                };
+                authCache = result;
+                authCacheTime = now;
+                return result;
+            }
+            catch (error) {
+                console.error('Auth check failed:', error);
+                const result = { authenticated: false, user: null };
+                authCache = result;
+                authCacheTime = now;
+                return result;
+            }
+        },
+        redirectToLogin(returnUrl) {
+            const currentUrl = returnUrl || window.location.href;
+            window.location.href = `${config.getAuthFrontUrl()}?redirect_uri=${encodeURIComponent(currentUrl)}`;
+        },
+        async logout() {
+            try {
+                const response = await fetch(`${config.getAuthServiceUrl()}/auth/logout`, {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: authHeaders()
+                });
+                if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+                const data = await response.json();
+                if (data.success) {
+                    localStorage.removeItem('authToken');
+                    authCache = null;
+                    authCacheTime = 0;
+                    window.location.reload();
+                }
+                return data.success;
+            }
+            catch (error) {
+                console.error('Logout failed:', error);
+                return false;
+            }
+        },
+        async getCurrentUser() {
+            const result = await this.checkAuth();
+            return result.user;
+        },
+        /** Full profile (e.g. firstName/lastName) — only auth-service's /auth/profile has this. */
+        async getProfile() {
+            try {
+                const response = await fetch(`${config.getAuthServiceUrl()}/auth/profile`, {
+                    credentials: 'include',
+                    headers: authHeaders()
+                });
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    console.error('Profile fetch error:', response.status, errorText);
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+                const data = await response.json();
+                return data.success ? data.user : null;
+            }
+            catch (error) {
+                console.error('Get profile failed:', error);
+                return null;
+            }
+        },
+        /** Decodes the local JWT directly — no network call, but can be stale. */
+        getCurrentUserFromToken() {
+            try {
+                const token = this.getToken();
+                if (!token)
+                    return null;
+                const payload = token.split('.')[1];
+                if (!payload)
+                    return null;
+                const decoded = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')));
+                if (decoded.exp && Date.now() >= decoded.exp * 1000) {
+                    return null;
+                }
+                return {
+                    id: decoded.sub || decoded.id,
+                    email: decoded.email,
+                    name: decoded.name || decoded.preferred_username,
+                    picture: decoded.picture
+                };
+            }
+            catch (error) {
+                console.error('Failed to decode JWT token:', error);
+                return null;
+            }
+        },
+        async isAuthenticated() {
+            const result = await this.checkAuth();
+            return result.authenticated;
+        }
+    };
+}

package/dist/groupService.d.ts

@@ -0,0 +1,19 @@
+import { Group } from './types';
+export interface GroupServiceConfig {
+    /** Read fresh at call time (config may not be resolved yet at module load). */
+    getGroupApiUrl: () => string;
+}
+/**
+ * Builds a per-front group service instance, consolidating the
+ * getUserGroups/getUserGroupIds pair that was duplicated across
+ * album/finance/relationship-front (TECHNICAL_REVIEW.md P1.3).
+ *
+ *   export const { getUserGroups, getUserGroupIds } = createGroupService({
+ *     getGroupApiUrl: () => getGlobalConfig().GROUP_API_URL!
+ *   });
+ */
+export declare function createGroupService(config: GroupServiceConfig): {
+    getUserGroups(): Promise<Group[]>;
+    getUserGroupIds(): Promise<string[]>;
+};
+export type GroupService = ReturnType<typeof createGroupService>;

package/dist/groupService.js

@@ -0,0 +1,63 @@
+import { getCorrelationId, getSessionId } from '@tumbaland/components';
+function getAuthToken() {
+    return localStorage.getItem('authToken') || '';
+}
+function groupHeaders() {
+    return {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${getAuthToken()}`,
+        'x-correlation-id': getCorrelationId(),
+        'x-session-id': getSessionId()
+    };
+}
+/**
+ * Builds a per-front group service instance, consolidating the
+ * getUserGroups/getUserGroupIds pair that was duplicated across
+ * album/finance/relationship-front (TECHNICAL_REVIEW.md P1.3).
+ *
+ *   export const { getUserGroups, getUserGroupIds } = createGroupService({
+ *     getGroupApiUrl: () => getGlobalConfig().GROUP_API_URL!
+ *   });
+ */
+export function createGroupService(config) {
+    return {
+        async getUserGroups() {
+            try {
+                const response = await fetch(`${config.getGroupApiUrl()}/api/groups/mine`, {
+                    headers: groupHeaders()
+                });
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch groups: ${response.statusText}`);
+                }
+                const result = await response.json();
+                if (!result.success) {
+                    throw new Error(result.message || 'Failed to fetch groups');
+                }
+                return result.data;
+            }
+            catch (error) {
+                console.error('Error fetching user groups:', error);
+                throw error;
+            }
+        },
+        async getUserGroupIds() {
+            try {
+                const response = await fetch(`${config.getGroupApiUrl()}/api/groups/mine/ids`, {
+                    headers: groupHeaders()
+                });
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch group IDs: ${response.statusText}`);
+                }
+                const result = await response.json();
+                if (!result.success) {
+                    throw new Error(result.message || 'Failed to fetch group IDs');
+                }
+                return result.data;
+            }
+            catch (error) {
+                console.error('Error fetching user group IDs:', error);
+                throw error;
+            }
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createApiClient, ApiError } from './apiClient';
+export type { ApiClientOptions, ApiRequestOptions } from './apiClient';
+export { createAuthService } from './authService';
+export type { AuthServiceConfig, AuthService } from './authService';
+export { createGroupService } from './groupService';
+export type { GroupServiceConfig, GroupService } from './groupService';
+export type { User, AuthResponse, Group, ApiResponse } from './types';

package/dist/index.js

@@ -0,0 +1,4 @@
+// @tumbaland/frontend-core - Shared frontend auth/group/API-client logic
+export { createApiClient, ApiError } from './apiClient';
+export { createAuthService } from './authService';
+export { createGroupService } from './groupService';

package/dist/test/setup.d.ts

@@ -0,0 +1,9 @@
+declare class MemoryStorage implements Storage {
+    private store;
+    get length(): number;
+    clear(): void;
+    getItem(key: string): string | null;
+    key(index: number): string;
+    removeItem(key: string): void;
+    setItem(key: string, value: string): void;
+}

package/dist/test/setup.js

@@ -0,0 +1,28 @@
+"use strict";
+// This jsdom environment doesn't provide a working localStorage (window.localStorage
+// is undefined here) — polyfill it with a simple in-memory Storage.
+class MemoryStorage {
+    constructor() {
+        this.store = new Map();
+    }
+    get length() {
+        return this.store.size;
+    }
+    clear() {
+        this.store.clear();
+    }
+    getItem(key) {
+        return this.store.has(key) ? this.store.get(key) : null;
+    }
+    key(index) {
+        return Array.from(this.store.keys())[index] ?? null;
+    }
+    removeItem(key) {
+        this.store.delete(key);
+    }
+    setItem(key, value) {
+        this.store.set(key, String(value));
+    }
+}
+Object.defineProperty(globalThis, 'localStorage', { value: new MemoryStorage(), configurable: true });
+Object.defineProperty(window, 'localStorage', { value: globalThis.localStorage, configurable: true });

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+export interface User {
+    id: string;
+    email: string;
+    name: string;
+    firstName?: string;
+    lastName?: string;
+    picture?: string;
+    roles?: string[];
+    isApproved?: boolean;
+}
+export interface AuthResponse {
+    authenticated: boolean;
+    user: User | null;
+}
+export interface Group {
+    _id: string;
+    name: string;
+    description?: string;
+    memberCount?: number;
+    isOwner?: boolean;
+    createdAt?: string;
+}
+export interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+    message?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@tumbaland/frontend-core",
+  "version": "1.1.0",
+  "description": "Shared frontend auth/group/API-client logic for Tumbaland frontends",
+  "author": "Tumbaland",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "release": "standard-version && npm run build && npm publish --access public",
+    "release:beta": "standard-version --prerelease beta && npm run build && npm publish --access public --tag beta",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tumbaland/components": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "standard-version": "^9.5.0",
+    "typescript": "^6.0.3"
+  }
+}