@ph-cms/client-sdk 0.1.6 → 0.1.8

package/dist/auth/jwt-utils.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Lightweight JWT utilities for client-side token inspection.
+ *
+ * These helpers parse the **payload** of a JWT (the middle segment) using
+ * plain base64 decoding. They do NOT verify the signature — that is the
+ * server's responsibility. The client only needs to know *when* a token
+ * expires so it can proactively refresh before sending an API request.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeJwtPayload = decodeJwtPayload;
+exports.getTokenExpirationMs = getTokenExpirationMs;
+exports.isTokenExpired = isTokenExpired;
+exports.getTokenTTL = getTokenTTL;
+/**
+ * Decode the payload (second segment) of a JWT string.
+ *
+ * Returns `null` if the token is malformed or cannot be decoded.
+ * This function works in both browser and Node.js environments.
+ */
+function decodeJwtPayload(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const base64Url = parts[1];
+        // Convert base64url → base64
+        const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
+        let jsonStr;
+        if (typeof atob === 'function') {
+            // Browser (and Node >= 16 with global atob)
+            jsonStr = atob(base64);
+        }
+        else {
+            // Fallback for older Node.js environments
+            jsonStr = Buffer.from(base64, 'base64').toString('utf-8');
+        }
+        return JSON.parse(jsonStr);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns the expiration time of a JWT as a Unix timestamp **in milliseconds**.
+ *
+ * Returns `null` if the token is malformed or does not contain an `exp` claim.
+ */
+function getTokenExpirationMs(token) {
+    const payload = decodeJwtPayload(token);
+    if (!payload || typeof payload.exp !== 'number')
+        return null;
+    // JWT `exp` is in seconds; convert to milliseconds.
+    return payload.exp * 1000;
+}
+/**
+ * Check whether a token has expired (or will expire within `bufferMs`).
+ *
+ * @param token     Raw JWT string
+ * @param bufferMs  Grace period in milliseconds. If the token expires within
+ *                  this window it is considered "expired" so the caller can
+ *                  refresh proactively.  Defaults to **60 000 ms (1 minute)**.
+ * @returns
+ *   - `true`  — the token is expired or will expire within `bufferMs`
+ *   - `false` — the token is still valid beyond the buffer window
+ *   - `null`  — the token could not be parsed (treat as expired for safety)
+ */
+function isTokenExpired(token, bufferMs = 60000) {
+    const expiresAtMs = getTokenExpirationMs(token);
+    if (expiresAtMs === null)
+        return null;
+    return Date.now() >= expiresAtMs - bufferMs;
+}
+/**
+ * Returns the number of milliseconds until the token expires.
+ *
+ * Returns `null` if the token is malformed.
+ * Returns a negative value if the token is already expired.
+ */
+function getTokenTTL(token) {
+    const expiresAtMs = getTokenExpirationMs(token);
+    if (expiresAtMs === null)
+        return null;
+    return expiresAtMs - Date.now();
+}

package/dist/auth/local-provider.d.ts

@@ -1,19 +1,36 @@
-import { AuthProvider } from "./interfaces";
-export declare class LocalAuthProvider implements AuthProvider {
-    private readonly storageKeyPrefix;
-    private readonly refreshFn?;
-    readonly type = "LOCAL";
-    private accessToken;
-    private refreshToken;
-    private onExpiredCallback;
-    constructor(storageKeyPrefix?: string, refreshFn?: ((refreshToken: string) => Promise<{
-        accessToken: string;
-        refreshToken: string;
-    }>) | undefined);
-    setTokens(accessToken: string, refreshToken: string): void;
-    hasToken(): boolean;
+import { BaseAuthProvider } from './base-provider';
+/**
+ * Authentication provider that stores PH-CMS tokens in `localStorage`.
+ *
+ * This is the default provider for applications that use email/password
+ * or any non-Firebase authentication flow.
+ *
+ * Token lifecycle:
+ * 1. On `getToken()`, the stored access token's `exp` claim is checked.
+ * 2. If the token is expired (or will expire within `expiryBufferMs`),
+ *    an automatic refresh is attempted via the registered `refreshFn`.
+ * 3. If refresh fails, tokens are cleared and the `onExpiredCallback` is
+ *    invoked so the UI layer can redirect to a login page.
+ */
+export declare class LocalAuthProvider extends BaseAuthProvider {
+    readonly type: "LOCAL";
+    constructor(storageKeyPrefix?: string, options?: {
+        /**
+         * How many ms before actual expiration the token is considered expired.
+         * @default 60_000 (1 minute)
+         */
+        expiryBufferMs?: number;
+    });
+    /**
+     * Returns a valid access token.
+     *
+     * Before returning the stored access token this method checks its `exp`
+     * claim.  If the token is expired (or will expire within `expiryBufferMs`)
+     * **and** a refresh function has been registered via `setRefreshFn()`,
+     * it automatically refreshes the token pair.
+     *
+     * Concurrent callers share the same in-flight refresh promise so that
+     * multiple parallel requests don't each trigger their own refresh.
+     */
     getToken(): Promise<string | null>;
-    onTokenExpired(callback: () => Promise<void>): void;
-    logout(): Promise<void>;
-    getRefreshToken(): string | null;
 }

package/dist/auth/local-provider.js

@@ -1,49 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalAuthProvider = void 0;
-class LocalAuthProvider {
-    constructor(storageKeyPrefix = 'ph_cms_', refreshFn) {
-        this.storageKeyPrefix = storageKeyPrefix;
-        this.refreshFn = refreshFn;
+const base_provider_1 = require("./base-provider");
+/**
+ * Authentication provider that stores PH-CMS tokens in `localStorage`.
+ *
+ * This is the default provider for applications that use email/password
+ * or any non-Firebase authentication flow.
+ *
+ * Token lifecycle:
+ * 1. On `getToken()`, the stored access token's `exp` claim is checked.
+ * 2. If the token is expired (or will expire within `expiryBufferMs`),
+ *    an automatic refresh is attempted via the registered `refreshFn`.
+ * 3. If refresh fails, tokens are cleared and the `onExpiredCallback` is
+ *    invoked so the UI layer can redirect to a login page.
+ */
+class LocalAuthProvider extends base_provider_1.BaseAuthProvider {
+    constructor(storageKeyPrefix = 'ph_cms_', options) {
+        super(storageKeyPrefix, options?.expiryBufferMs);
         this.type = 'LOCAL';
-        this.accessToken = null;
-        this.refreshToken = null;
-        this.onExpiredCallback = null;
-        if (typeof window !== 'undefined') {
-            this.accessToken = localStorage.getItem(`${this.storageKeyPrefix}access_token`);
-            this.refreshToken = localStorage.getItem(`${this.storageKeyPrefix}refresh_token`);
-        }
-    }
-    setTokens(accessToken, refreshToken) {
-        this.accessToken = accessToken;
-        this.refreshToken = refreshToken;
-        if (typeof window !== 'undefined') {
-            localStorage.setItem(`${this.storageKeyPrefix}access_token`, accessToken);
-            localStorage.setItem(`${this.storageKeyPrefix}refresh_token`, refreshToken);
-        }
-    }
-    hasToken() {
-        return this.accessToken !== null || this.refreshToken !== null;
     }
+    /**
+     * Returns a valid access token.
+     *
+     * Before returning the stored access token this method checks its `exp`
+     * claim.  If the token is expired (or will expire within `expiryBufferMs`)
+     * **and** a refresh function has been registered via `setRefreshFn()`,
+     * it automatically refreshes the token pair.
+     *
+     * Concurrent callers share the same in-flight refresh promise so that
+     * multiple parallel requests don't each trigger their own refresh.
+     */
     async getToken() {
-        // Ideally check expiration here using jwt-decode, but for now return what we have.
-        // If it's expired, the API will return 401, triggering the interceptor which calls onTokenExpired.
-        return this.accessToken;
-    }
-    onTokenExpired(callback) {
-        this.onExpiredCallback = callback;
-    }
-    async logout() {
-        this.accessToken = null;
-        this.refreshToken = null;
-        if (typeof window !== 'undefined') {
-            localStorage.removeItem(`${this.storageKeyPrefix}access_token`);
-            localStorage.removeItem(`${this.storageKeyPrefix}refresh_token`);
+        // Fast path: no access token at all.
+        if (!this.accessToken)
+            return null;
+        // Check expiration.
+        const expired = this.isCurrentTokenExpired();
+        // `expired === null` means the token could not be parsed — treat as
+        // potentially valid and let the server decide (it might still be fine
+        // if the format changed, or the server will 401 and the interceptor
+        // will handle it).
+        if (expired === true) {
+            const refreshed = await this.tryRefresh();
+            if (refreshed)
+                return refreshed;
+            // Refresh failed — return null so the request goes out without a
+            // token (will result in 401 which the interceptor can handle).
+            return null;
         }
-    }
-    // Helper for the client to trigger refresh manually if needed
-    getRefreshToken() {
-        return this.refreshToken;
+        return this.accessToken;
     }
 }
 exports.LocalAuthProvider = LocalAuthProvider;

package/dist/client.d.ts

@@ -19,7 +19,30 @@ export declare class PHCMSClient {
     readonly channel: ChannelModule;
     readonly terms: TermsModule;
     readonly media: MediaModule;
+    /**
+     * Whether a token refresh is currently in flight (used by the 401
+     * interceptor to de-duplicate concurrent refresh attempts).
+     */
+    private isRefreshing;
+    /**
+     * Queue of requests waiting for the current refresh to complete.
+     * Each entry will be resolved/rejected once the single in-flight
+     * refresh call finishes.
+     */
+    private refreshQueue;
     /** Exposes the auth provider so UI layers can check token state synchronously. */
     get authProvider(): AuthProvider | undefined;
     constructor(config: PHCMSClientConfig);
+    /**
+     * If a refresh is already in flight, queue the caller. Otherwise kick
+     * off a fresh refresh request and resolve all queued callers when it
+     * completes.
+     *
+     * This method reuses the **provider's** `tryRefresh()` path (via
+     * `getToken()` → proactive refresh) when possible. However since we
+     * arrive here because the access token already failed server-side
+     * validation (401), we perform an explicit refresh using the raw
+     * axios instance with `_skipAuth` to avoid circular `getToken()` calls.
+     */
+    private coordinatedRefresh;
 }

package/dist/client.js

@@ -18,6 +18,17 @@ class PHCMSClient {
     }
     constructor(config) {
         this.config = config;
+        /**
+         * Whether a token refresh is currently in flight (used by the 401
+         * interceptor to de-duplicate concurrent refresh attempts).
+         */
+        this.isRefreshing = false;
+        /**
+         * Queue of requests waiting for the current refresh to complete.
+         * Each entry will be resolved/rejected once the single in-flight
+         * refresh call finishes.
+         */
+        this.refreshQueue = [];
         const normalizedApiPrefix = `/${(config.apiPrefix || '/api').replace(/^\/+|\/+$/g, '')}`;
         this.axiosInstance = axios_1.default.create({
             baseURL: config.baseURL,
@@ -26,8 +37,33 @@ class PHCMSClient {
                 'Content-Type': 'application/json',
             },
         });
-        // Request Interceptor: Add Auth Token
+        // Initialize Modules (before interceptors so the refresh wiring
+        // can reference `this.auth`).
+        this.auth = new auth_1.AuthModule(this.axiosInstance, config.auth);
+        this.content = new content_1.ContentModule(this.axiosInstance);
+        this.channel = new channel_1.ChannelModule(this.axiosInstance);
+        this.terms = new terms_1.TermsModule(this.axiosInstance);
+        this.media = new media_1.MediaModule(this.axiosInstance);
+        // Wire the refresh function into the auth provider so it can
+        // proactively refresh tokens inside `getToken()` without needing
+        // a direct reference to the AuthModule / axios instance.
+        //
+        // The `_skipAuth` flag ensures the refresh request itself does NOT
+        // pass through the "attach auth token" logic in the request
+        // interceptor, avoiding a recursive `getToken()` call.
+        if (config.auth) {
+            config.auth.setRefreshFn(async (refreshToken) => {
+                const response = await this.axiosInstance.post('/api/auth/refresh', { refreshToken }, { _skipAuth: true });
+                // The response interceptor unwraps `response.data`, so at
+                // this point `response` is already the data payload.
+                return response;
+            });
+        }
+        // ---------------------------------------------------------------
+        // Request Interceptor: Rewrite API prefix & attach auth token
+        // ---------------------------------------------------------------
         this.axiosInstance.interceptors.request.use(async (reqConfig) => {
+            // --- URL rewriting ---
             if (typeof reqConfig.url === 'string') {
                 if (reqConfig.url === '/api') {
                     reqConfig.url = normalizedApiPrefix;
@@ -36,7 +72,9 @@ class PHCMSClient {
                     reqConfig.url = `${normalizedApiPrefix}${reqConfig.url.slice('/api'.length)}`;
                 }
             }
-            if (this.config.auth) {
+            // --- Auth header ---
+            // Skip auth for requests explicitly flagged (e.g. refresh calls)
+            if (!reqConfig._skipAuth && this.config.auth) {
                 const token = await this.config.auth.getToken();
                 if (token) {
                     reqConfig.headers.Authorization = `Bearer ${token}`;
@@ -44,37 +82,89 @@ class PHCMSClient {
             }
             return reqConfig;
         });
-        // Response Interceptor: Unwrap Data & Handle Errors
+        // ---------------------------------------------------------------
+        // Response Interceptor: Unwrap data, handle errors, 401 auto-retry
+        // ---------------------------------------------------------------
         this.axiosInstance.interceptors.response.use((response) => {
-            // Return the data directly, stripping Axios wrapper
+            // Return the data directly, stripping the Axios wrapper.
             return response.data;
         }, async (error) => {
-            if (error.response) {
-                // Server responded with a status code outside 2xx
-                const { status, data } = error.response;
-                const message = data?.message || error.message;
-                // Handle 401 Token Expiry if provider supports it
-                if (status === 401 && this.config.auth) {
-                    // Logic to handle token refresh could be here or triggered by the app.
-                    // For now just throw.
+            if (!error.response) {
+                if (error.request) {
+                    throw new errors_1.PHCMSError('No response received from server');
                 }
-                throw new errors_1.ApiError(message, status, data);
-            }
-            else if (error.request) {
-                // Request made but no response
-                throw new errors_1.PHCMSError('No response received from server');
-            }
-            else {
-                // Something happened in setting up the request
                 throw new errors_1.PHCMSError(error.message);
             }
+            const { status, data } = error.response;
+            const message = data?.message || error.message;
+            const originalRequest = error.config;
+            // ----------------------------------------------------------
+            // 401 handling: attempt one transparent token refresh
+            // ----------------------------------------------------------
+            if (status === 401 &&
+                this.config.auth &&
+                !originalRequest._retry &&
+                !originalRequest._skipAuth // don't retry refresh requests
+            ) {
+                originalRequest._retry = true;
+                const refreshToken = this.config.auth.getRefreshToken();
+                if (refreshToken) {
+                    try {
+                        const newToken = await this.coordinatedRefresh(refreshToken);
+                        if (newToken) {
+                            // Re-issue the original request with the fresh token.
+                            originalRequest.headers.Authorization = `Bearer ${newToken}`;
+                            return this.axiosInstance(originalRequest);
+                        }
+                    }
+                    catch {
+                        // Refresh itself failed — fall through to throw ApiError.
+                    }
+                }
+            }
+            throw new errors_1.ApiError(message, status, data);
         });
-        // Initialize Modules
-        this.auth = new auth_1.AuthModule(this.axiosInstance, config.auth);
-        this.content = new content_1.ContentModule(this.axiosInstance);
-        this.channel = new channel_1.ChannelModule(this.axiosInstance);
-        this.terms = new terms_1.TermsModule(this.axiosInstance);
-        this.media = new media_1.MediaModule(this.axiosInstance);
+    }
+    // -------------------------------------------------------------------
+    // Private: coordinated token refresh (de-duplicates concurrent 401s)
+    // -------------------------------------------------------------------
+    /**
+     * If a refresh is already in flight, queue the caller. Otherwise kick
+     * off a fresh refresh request and resolve all queued callers when it
+     * completes.
+     *
+     * This method reuses the **provider's** `tryRefresh()` path (via
+     * `getToken()` → proactive refresh) when possible. However since we
+     * arrive here because the access token already failed server-side
+     * validation (401), we perform an explicit refresh using the raw
+     * axios instance with `_skipAuth` to avoid circular `getToken()` calls.
+     */
+    async coordinatedRefresh(refreshToken) {
+        if (this.isRefreshing) {
+            // Another request already triggered a refresh — wait for it.
+            return new Promise((resolve, reject) => {
+                this.refreshQueue.push({ resolve, reject });
+            });
+        }
+        this.isRefreshing = true;
+        try {
+            const result = await this.axiosInstance.post('/api/auth/refresh', { refreshToken }, { _skipAuth: true });
+            // Store the new tokens in the provider.
+            this.config.auth.setTokens(result.accessToken, result.refreshToken);
+            // Resolve all queued callers.
+            this.refreshQueue.forEach((q) => q.resolve(result.accessToken));
+            this.refreshQueue = [];
+            return result.accessToken;
+        }
+        catch (err) {
+            // Notify all queued callers of the failure.
+            this.refreshQueue.forEach((q) => q.reject(err));
+            this.refreshQueue = [];
+            return null;
+        }
+        finally {
+            this.isRefreshing = false;
+        }
     }
 }
 exports.PHCMSClient = PHCMSClient;

package/dist/context.d.ts

@@ -2,11 +2,23 @@ import { UserDto } from '@ph-cms/api-contract';
 import { QueryClient } from '@tanstack/react-query';
 import React, { ReactNode } from 'react';
 import { PHCMSClient } from './client';
+export type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
 export interface PHCMSContextType {
     client: PHCMSClient;
     user: UserDto | null;
     isAuthenticated: boolean;
     isLoading: boolean;
+    /** Whether the user profile fetch failed. */
+    isError: boolean;
+    /**
+     * Fine-grained authentication status.
+     * - `'loading'`: Token exists, `/auth/me` is being fetched.
+     * - `'authenticated'`: User profile successfully loaded.
+     * - `'unauthenticated'`: No token, or token validation failed.
+     */
+    authStatus: AuthStatus;
+    /** Whether the auth provider currently holds any token (access or refresh). */
+    hasToken: boolean;
     /** Manually trigger a refetch of the current user profile. */
     refreshUser: () => Promise<void>;
 }

package/dist/context.js

@@ -76,13 +76,25 @@ const PHCMSInternalProvider = ({ client, children }) => {
         }, 2000); // Check every 2s as a fallback
         return () => clearInterval(interval);
     }, [client.authProvider, hasToken]);
-    const value = (0, react_1.useMemo)(() => ({
-        client,
-        user: user || null,
-        isAuthenticated: !!user && !isError && hasToken,
-        isLoading: hasToken ? isLoading : false,
-        refreshUser,
-    }), [client, user, isError, isLoading, hasToken, refreshUser]);
+    const value = (0, react_1.useMemo)(() => {
+        const authStatus = (() => {
+            if (hasToken && isLoading)
+                return 'loading';
+            if (!!user && !isError && hasToken)
+                return 'authenticated';
+            return 'unauthenticated';
+        })();
+        return {
+            client,
+            user: user || null,
+            isAuthenticated: authStatus === 'authenticated',
+            isLoading: authStatus === 'loading',
+            isError,
+            authStatus,
+            hasToken,
+            refreshUser,
+        };
+    }, [client, user, isError, isLoading, hasToken, refreshUser]);
     return react_1.default.createElement(PHCMSContext.Provider, { value: value }, children);
 };
 /**

package/dist/hooks/useAuth.d.ts

@@ -205,34 +205,31 @@ export declare const useUser: () => {
     } | null;
     isLoading: boolean;
     isAuthenticated: boolean;
+    error: boolean;
 };
-export declare const useLogin: () => {
-    mutateAsync: import("@tanstack/react-query").UseMutateAsyncFunction<{
-        refreshToken: string;
-        user: {
-            uid: string;
-            email: string;
-            username: string | null;
-            display_name: string;
-            avatar_url: string | null;
-            phone_number: string | null;
-            email_verified_at: string | null;
-            phone_verified_at: string | null;
-            locale: string;
-            timezone: string;
-            status: string;
-            role: string[];
-            profile_data: Record<string, any>;
-            last_login_at: string | null;
-            created_at: string;
-            updated_at: string;
-        };
-        accessToken: string;
-    }, Error, {
+export declare const useLogin: () => import("@tanstack/react-query").UseMutationResult<{
+    refreshToken: string;
+    user: {
+        uid: string;
         email: string;
-        password: string;
-    }, unknown>;
-};
-export declare const useLogout: () => {
-    mutateAsync: import("@tanstack/react-query").UseMutateAsyncFunction<void, Error, void, unknown>;
-};
+        username: string | null;
+        display_name: string;
+        avatar_url: string | null;
+        phone_number: string | null;
+        email_verified_at: string | null;
+        phone_verified_at: string | null;
+        locale: string;
+        timezone: string;
+        status: string;
+        role: string[];
+        profile_data: Record<string, any>;
+        last_login_at: string | null;
+        created_at: string;
+        updated_at: string;
+    };
+    accessToken: string;
+}, Error, {
+    email: string;
+    password: string;
+}, unknown>;
+export declare const useLogout: () => import("@tanstack/react-query").UseMutationResult<void, Error, void, unknown>;

package/dist/hooks/useAuth.js

@@ -55,17 +55,17 @@ const useAuth = () => {
 exports.useAuth = useAuth;
 // Keep individual hooks for backward compatibility or more specific use cases
 const useUser = () => {
-    const { user, isLoading, isAuthenticated } = (0, context_1.usePHCMSContext)();
-    return { data: user, isLoading, isAuthenticated };
+    const { user, isLoading, isAuthenticated, isError } = (0, context_1.usePHCMSContext)();
+    return { data: user, isLoading, isAuthenticated, error: isError };
 };
 exports.useUser = useUser;
 const useLogin = () => {
-    const { login } = (0, exports.useAuth)();
-    return { mutateAsync: login };
+    const { loginStatus } = (0, exports.useAuth)();
+    return loginStatus;
 };
 exports.useLogin = useLogin;
 const useLogout = () => {
-    const { logout } = (0, exports.useAuth)();
-    return { mutateAsync: logout };
+    const { logoutStatus } = (0, exports.useAuth)();
+    return logoutStatus;
 };
 exports.useLogout = useLogout;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+export * from './auth/base-provider';
 export * from './auth/firebase-provider';
 export * from './auth/interfaces';
+export * from './auth/jwt-utils';
 export * from './auth/local-provider';
 export * from './client';
 export * from './errors';

package/dist/index.js

@@ -14,8 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./auth/base-provider"), exports);
 __exportStar(require("./auth/firebase-provider"), exports);
 __exportStar(require("./auth/interfaces"), exports);
+__exportStar(require("./auth/jwt-utils"), exports);
 __exportStar(require("./auth/local-provider"), exports);
 __exportStar(require("./client"), exports);
 __exportStar(require("./errors"), exports);

package/dist/modules/auth.d.ts

@@ -1,12 +1,12 @@
+import { AuthResponse, FirebaseExchangeRequest, LoginRequest, RegisterRequest, UserDto } from "@ph-cms/api-contract";
 import { AxiosInstance } from "axios";
 import { AuthProvider } from "../auth/interfaces";
-import { LoginRequest, RegisterRequest, AuthResponse, UserDto, FirebaseExchangeRequest } from "@ph-cms/api-contract";
 export declare class AuthModule {
     private client;
     private provider?;
     constructor(client: AxiosInstance, provider?: AuthProvider | undefined);
     /**
-     * Logs in the user and updates the AuthProvider if it's a LocalAuthProvider.
+     * Logs in the user and updates the AuthProvider tokens automatically.
      */
     login(data: LoginRequest): Promise<AuthResponse>;
     /**