@ph-cms/client-sdk 0.1.6 → 0.1.7

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

@@ -0,0 +1,151 @@
+import { AuthProvider } from './interfaces';
+/**
+ * Abstract base class that implements the common token-management logic
+ * shared by all {@link AuthProvider} implementations (e.g. `LocalAuthProvider`,
+ * `FirebaseAuthProvider`).
+ *
+ * Subclasses **must** implement:
+ * - `type` — the discriminator literal (`'LOCAL'` | `'FIREBASE'`).
+ * - `getToken()` — provider-specific logic for returning a valid access token
+ *   (including any fallback strategies such as Firebase ID tokens).
+ *
+ * Subclasses **may** override:
+ * - `logout()` — to perform additional cleanup (e.g. signing out of Firebase).
+ *   Always call `super.logout()` to ensure in-memory and localStorage tokens
+ *   are cleared.
+ */
+export declare abstract class BaseAuthProvider implements AuthProvider {
+    /** Discriminator that identifies the provider type. */
+    abstract readonly type: 'FIREBASE' | 'LOCAL';
+    /**
+     * Returns the current valid access token.
+     *
+     * Implementations should check token expiration and attempt a refresh
+     * automatically before returning the token. If the token is expired
+     * and cannot be refreshed, return `null`.
+     */
+    abstract getToken(): Promise<string | null>;
+    /** The current PH-CMS access token (JWT), or `null` if not authenticated. */
+    protected accessToken: string | null;
+    /** The current refresh token, or `null` if not authenticated. */
+    protected refreshToken: string | null;
+    /**
+     * Callback invoked when the token is known to be expired and automatic
+     * refresh has failed. Typically used to redirect the user to a login page.
+     */
+    protected onExpiredCallback: (() => Promise<void>) | null;
+    /**
+     * Function that performs the actual token refresh against the PH-CMS
+     * server. Registered by `PHCMSClient` after construction via
+     * {@link setRefreshFn}.
+     */
+    protected refreshFn: ((refreshToken: string) => Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>) | null;
+    /**
+     * In-flight refresh promise used to de-duplicate concurrent refresh
+     * requests triggered by parallel `getToken()` calls.
+     */
+    protected refreshPromise: Promise<string | null> | null;
+    /**
+     * How many milliseconds before actual JWT expiration the token is
+     * considered "expired" so the caller can refresh proactively.
+     */
+    protected expiryBufferMs: number;
+    /**
+     * Prefix applied to all `localStorage` keys managed by this provider
+     * (e.g. `'ph_cms_'` → keys `ph_cms_access_token`, `ph_cms_refresh_token`).
+     */
+    protected readonly storageKeyPrefix: string;
+    /**
+     * @param storageKeyPrefix  Prefix for `localStorage` keys (e.g. `'ph_cms_'`).
+     * @param expiryBufferMs    How many ms before actual expiration the token is
+     *                          considered expired. Defaults to {@link DEFAULT_EXPIRY_BUFFER_MS}
+     *                          (60 000 ms / 1 minute).
+     */
+    constructor(storageKeyPrefix: string, expiryBufferMs?: number);
+    /**
+     * Returns `true` if the provider currently holds any token (access **or**
+     * refresh). This is a synchronous check used to decide whether to attempt
+     * API calls that require authentication (e.g. `/auth/me`).
+     */
+    hasToken(): boolean;
+    /**
+     * Returns the current refresh token, or `null` if none is stored.
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Registers the function that performs the actual token refresh against
+     * the server. Called by `PHCMSClient` after construction so that the
+     * provider can refresh tokens autonomously inside {@link getToken} without
+     * a circular dependency on the client/module layer.
+     *
+     * @param fn  A function that receives the current refresh token and returns
+     *            a fresh access/refresh token pair.
+     */
+    setRefreshFn(fn: (refreshToken: string) => Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>): void;
+    /**
+     * Stores a new pair of access/refresh tokens in memory **and**
+     * `localStorage` (when running in a browser).
+     *
+     * @param accessToken   The new JWT access token.
+     * @param refreshToken  The new refresh token.
+     */
+    setTokens(accessToken: string, refreshToken: string): void;
+    /**
+     * Sets a callback to be invoked when the token is known to be expired
+     * and automatic refresh has failed.
+     *
+     * @param callback  An async function executed on unrecoverable expiry
+     *                  (e.g. redirect the user to a login page).
+     */
+    onTokenExpired(callback: () => Promise<void>): void;
+    /**
+     * Clears the current session by removing tokens from memory and
+     * `localStorage`.
+     *
+     * Subclasses may override this method to perform additional cleanup
+     * (e.g. signing out of Firebase) but **must** call `super.logout()`.
+     */
+    logout(): Promise<void>;
+    /**
+     * Attempt to refresh the token pair using the registered {@link refreshFn}.
+     *
+     * If a refresh is already in progress (e.g. from a concurrent
+     * `getToken()` call) the existing promise is returned so we don't fire
+     * multiple refresh requests simultaneously.
+     *
+     * @returns The new access token on success, or `null` on failure.
+     */
+    protected tryRefresh(): Promise<string | null>;
+    /**
+     * Executes the actual refresh call via {@link refreshFn}.
+     *
+     * On success the new tokens are persisted via {@link setTokens}.
+     * On failure all tokens are cleared and the {@link onExpiredCallback}
+     * is invoked.
+     *
+     * @returns The new access token on success, or `null` on failure.
+     */
+    protected executeRefresh(): Promise<string | null>;
+    /**
+     * Removes the access and refresh tokens from both in-memory state and
+     * `localStorage`.
+     */
+    protected clearTokens(): void;
+    /**
+     * Checks whether the current access token is expired (or will expire
+     * within {@link expiryBufferMs}).
+     *
+     * @returns
+     *   - `true`  — the token is expired or will expire within the buffer.
+     *   - `false` — the token is still valid beyond the buffer window.
+     *   - `null`  — the token could not be parsed (caller should treat this
+     *               as potentially valid and let the server decide).
+     */
+    protected isCurrentTokenExpired(): boolean | null;
+}

package/dist/auth/base-provider.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAuthProvider = void 0;
+const jwt_utils_1 = require("./jwt-utils");
+/**
+ * Buffer time (ms) before actual expiration at which we consider the token
+ * "expired" and proactively refresh.  Default: 60 seconds.
+ */
+const DEFAULT_EXPIRY_BUFFER_MS = 60000;
+/**
+ * Abstract base class that implements the common token-management logic
+ * shared by all {@link AuthProvider} implementations (e.g. `LocalAuthProvider`,
+ * `FirebaseAuthProvider`).
+ *
+ * Subclasses **must** implement:
+ * - `type` — the discriminator literal (`'LOCAL'` | `'FIREBASE'`).
+ * - `getToken()` — provider-specific logic for returning a valid access token
+ *   (including any fallback strategies such as Firebase ID tokens).
+ *
+ * Subclasses **may** override:
+ * - `logout()` — to perform additional cleanup (e.g. signing out of Firebase).
+ *   Always call `super.logout()` to ensure in-memory and localStorage tokens
+ *   are cleared.
+ */
+class BaseAuthProvider {
+    // -----------------------------------------------------------------------
+    // Constructor
+    // -----------------------------------------------------------------------
+    /**
+     * @param storageKeyPrefix  Prefix for `localStorage` keys (e.g. `'ph_cms_'`).
+     * @param expiryBufferMs    How many ms before actual expiration the token is
+     *                          considered expired. Defaults to {@link DEFAULT_EXPIRY_BUFFER_MS}
+     *                          (60 000 ms / 1 minute).
+     */
+    constructor(storageKeyPrefix, expiryBufferMs) {
+        // -----------------------------------------------------------------------
+        // Protected state — accessible to subclasses
+        // -----------------------------------------------------------------------
+        /** The current PH-CMS access token (JWT), or `null` if not authenticated. */
+        this.accessToken = null;
+        /** The current refresh token, or `null` if not authenticated. */
+        this.refreshToken = null;
+        /**
+         * Callback invoked when the token is known to be expired and automatic
+         * refresh has failed. Typically used to redirect the user to a login page.
+         */
+        this.onExpiredCallback = null;
+        /**
+         * Function that performs the actual token refresh against the PH-CMS
+         * server. Registered by `PHCMSClient` after construction via
+         * {@link setRefreshFn}.
+         */
+        this.refreshFn = null;
+        /**
+         * In-flight refresh promise used to de-duplicate concurrent refresh
+         * requests triggered by parallel `getToken()` calls.
+         */
+        this.refreshPromise = null;
+        this.storageKeyPrefix = storageKeyPrefix;
+        this.expiryBufferMs = expiryBufferMs ?? DEFAULT_EXPIRY_BUFFER_MS;
+        // Hydrate tokens from localStorage when running in a browser context.
+        if (typeof window !== 'undefined') {
+            this.accessToken = localStorage.getItem(`${this.storageKeyPrefix}access_token`);
+            this.refreshToken = localStorage.getItem(`${this.storageKeyPrefix}refresh_token`);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Concrete AuthProvider methods
+    // -----------------------------------------------------------------------
+    /**
+     * Returns `true` if the provider currently holds any token (access **or**
+     * refresh). This is a synchronous check used to decide whether to attempt
+     * API calls that require authentication (e.g. `/auth/me`).
+     */
+    hasToken() {
+        return this.accessToken !== null || this.refreshToken !== null;
+    }
+    /**
+     * Returns the current refresh token, or `null` if none is stored.
+     */
+    getRefreshToken() {
+        return this.refreshToken;
+    }
+    /**
+     * Registers the function that performs the actual token refresh against
+     * the server. Called by `PHCMSClient` after construction so that the
+     * provider can refresh tokens autonomously inside {@link getToken} without
+     * a circular dependency on the client/module layer.
+     *
+     * @param fn  A function that receives the current refresh token and returns
+     *            a fresh access/refresh token pair.
+     */
+    setRefreshFn(fn) {
+        this.refreshFn = fn;
+    }
+    /**
+     * Stores a new pair of access/refresh tokens in memory **and**
+     * `localStorage` (when running in a browser).
+     *
+     * @param accessToken   The new JWT access token.
+     * @param refreshToken  The new 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);
+        }
+    }
+    /**
+     * Sets a callback to be invoked when the token is known to be expired
+     * and automatic refresh has failed.
+     *
+     * @param callback  An async function executed on unrecoverable expiry
+     *                  (e.g. redirect the user to a login page).
+     */
+    onTokenExpired(callback) {
+        this.onExpiredCallback = callback;
+    }
+    /**
+     * Clears the current session by removing tokens from memory and
+     * `localStorage`.
+     *
+     * Subclasses may override this method to perform additional cleanup
+     * (e.g. signing out of Firebase) but **must** call `super.logout()`.
+     */
+    async logout() {
+        this.clearTokens();
+    }
+    // -----------------------------------------------------------------------
+    // Protected helpers — available to subclasses
+    // -----------------------------------------------------------------------
+    /**
+     * Attempt to refresh the token pair using the registered {@link refreshFn}.
+     *
+     * If a refresh is already in progress (e.g. from a concurrent
+     * `getToken()` call) the existing promise is returned so we don't fire
+     * multiple refresh requests simultaneously.
+     *
+     * @returns The new access token on success, or `null` on failure.
+     */
+    async tryRefresh() {
+        if (!this.refreshFn || !this.refreshToken) {
+            // Cannot refresh — notify the expired callback if set.
+            await this.onExpiredCallback?.();
+            return null;
+        }
+        // De-duplicate concurrent refreshes.
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.executeRefresh();
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    /**
+     * Executes the actual refresh call via {@link refreshFn}.
+     *
+     * On success the new tokens are persisted via {@link setTokens}.
+     * On failure all tokens are cleared and the {@link onExpiredCallback}
+     * is invoked.
+     *
+     * @returns The new access token on success, or `null` on failure.
+     */
+    async executeRefresh() {
+        try {
+            const result = await this.refreshFn(this.refreshToken);
+            this.setTokens(result.accessToken, result.refreshToken);
+            return result.accessToken;
+        }
+        catch {
+            // Refresh failed (e.g. refresh token also expired).
+            // Clear tokens and notify.
+            this.clearTokens();
+            await this.onExpiredCallback?.();
+            return null;
+        }
+    }
+    /**
+     * Removes the access and refresh tokens from both in-memory state and
+     * `localStorage`.
+     */
+    clearTokens() {
+        this.accessToken = null;
+        this.refreshToken = null;
+        if (typeof window !== 'undefined') {
+            localStorage.removeItem(`${this.storageKeyPrefix}access_token`);
+            localStorage.removeItem(`${this.storageKeyPrefix}refresh_token`);
+        }
+    }
+    /**
+     * Checks whether the current access token is expired (or will expire
+     * within {@link expiryBufferMs}).
+     *
+     * @returns
+     *   - `true`  — the token is expired or will expire within the buffer.
+     *   - `false` — the token is still valid beyond the buffer window.
+     *   - `null`  — the token could not be parsed (caller should treat this
+     *               as potentially valid and let the server decide).
+     */
+    isCurrentTokenExpired() {
+        return (0, jwt_utils_1.isTokenExpired)(this.accessToken, this.expiryBufferMs);
+    }
+}
+exports.BaseAuthProvider = BaseAuthProvider;

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

@@ -1,18 +1,52 @@
 import type { Auth } from "firebase/auth";
-import { AuthProvider } from "./interfaces";
-export declare class FirebaseAuthProvider implements AuthProvider {
+import { BaseAuthProvider } from "./base-provider";
+/**
+ * Authentication provider that integrates Firebase Authentication with PH-CMS.
+ *
+ * Uses Firebase as the identity provider while managing PH-CMS-specific
+ * access/refresh tokens. When no valid PH-CMS token is available, falls back
+ * to the Firebase ID token (useful for the initial token exchange call).
+ *
+ * Extends {@link BaseAuthProvider} which handles all common token management
+ * logic (storage, refresh de-duplication, expiry checks, etc.).
+ */
+export declare class FirebaseAuthProvider extends BaseAuthProvider {
     private readonly auth;
-    private readonly storageKeyPrefix;
-    readonly type = "FIREBASE";
-    private accessToken;
-    private refreshToken;
-    private onExpiredCallback;
-    constructor(auth: Auth, storageKeyPrefix?: string);
-    hasToken(): boolean;
-    setTokens(accessToken: string, refreshToken: string): void;
+    readonly type: "FIREBASE";
+    /**
+     * @param auth              The Firebase `Auth` instance.
+     * @param storageKeyPrefix  Prefix for `localStorage` keys.
+     *                          Defaults to `'ph_cms_fb_'`.
+     * @param options           Optional configuration.
+     * @param options.expiryBufferMs  How many ms before actual expiration the
+     *                                token is considered expired. Defaults to
+     *                                60 000 ms (1 minute).
+     */
+    constructor(auth: Auth, 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 for PH-CMS API calls.
+     *
+     * 1. If a PH-CMS access token exists and is still valid, return it.
+     * 2. If the PH-CMS access token is expired (or will expire within
+     *    `expiryBufferMs`), attempt an automatic refresh using the stored
+     *    refresh token.
+     * 3. If no PH-CMS token exists at all (or refresh failed), fall back to
+     *    the Firebase ID token (useful for the initial exchange call or if the
+     *    server supports Firebase tokens directly).
+     */
     getToken(): Promise<string | null>;
-    onTokenExpired(callback: () => Promise<void>): void;
+    /**
+     * Clears PH-CMS tokens **and** signs the user out of Firebase.
+     */
     logout(): Promise<void>;
-    getRefreshToken(): string | null;
+    /**
+     * Returns the current Firebase ID token, or `null` if no user is signed in.
+     */
     getIdToken(): Promise<string | null>;
 }

package/dist/auth/firebase-provider.js

@@ -1,58 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FirebaseAuthProvider = void 0;
-class FirebaseAuthProvider {
-    constructor(auth, storageKeyPrefix = 'ph_cms_fb_') {
+const base_provider_1 = require("./base-provider");
+/**
+ * Authentication provider that integrates Firebase Authentication with PH-CMS.
+ *
+ * Uses Firebase as the identity provider while managing PH-CMS-specific
+ * access/refresh tokens. When no valid PH-CMS token is available, falls back
+ * to the Firebase ID token (useful for the initial token exchange call).
+ *
+ * Extends {@link BaseAuthProvider} which handles all common token management
+ * logic (storage, refresh de-duplication, expiry checks, etc.).
+ */
+class FirebaseAuthProvider extends base_provider_1.BaseAuthProvider {
+    /**
+     * @param auth              The Firebase `Auth` instance.
+     * @param storageKeyPrefix  Prefix for `localStorage` keys.
+     *                          Defaults to `'ph_cms_fb_'`.
+     * @param options           Optional configuration.
+     * @param options.expiryBufferMs  How many ms before actual expiration the
+     *                                token is considered expired. Defaults to
+     *                                60 000 ms (1 minute).
+     */
+    constructor(auth, storageKeyPrefix = 'ph_cms_fb_', options) {
+        super(storageKeyPrefix, options?.expiryBufferMs);
         this.auth = auth;
-        this.storageKeyPrefix = storageKeyPrefix;
         this.type = 'FIREBASE';
-        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`);
-        }
-    }
-    hasToken() {
-        return this.accessToken !== null || this.refreshToken !== null;
-    }
-    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);
-        }
     }
+    /**
+     * Returns a valid access token for PH-CMS API calls.
+     *
+     * 1. If a PH-CMS access token exists and is still valid, return it.
+     * 2. If the PH-CMS access token is expired (or will expire within
+     *    `expiryBufferMs`), attempt an automatic refresh using the stored
+     *    refresh token.
+     * 3. If no PH-CMS token exists at all (or refresh failed), fall back to
+     *    the Firebase ID token (useful for the initial exchange call or if the
+     *    server supports Firebase tokens directly).
+     */
     async getToken() {
-        // If we have a local access token, use it for PH-CMS API calls.
         if (this.accessToken) {
-            return this.accessToken;
+            const expired = this.isCurrentTokenExpired();
+            if (expired === true) {
+                const refreshed = await this.tryRefresh();
+                if (refreshed)
+                    return refreshed;
+                // Refresh failed — fall through to Firebase ID token fallback.
+            }
+            else {
+                // Token is valid (or unparseable — let server decide).
+                return this.accessToken;
+            }
         }
-        // Fallback to Firebase ID token if no local token is set yet.
-        // This might be useful if the server starts supporting Firebase tokens directly
-        // or for the initial exchange call if we want to automate it (though currently it's manual).
-        const user = this.auth.currentUser;
-        if (!user)
-            return null;
-        return user.getIdToken();
-    }
-    onTokenExpired(callback) {
-        this.onExpiredCallback = callback;
+        // Fallback to Firebase ID token if no valid PH-CMS token is available.
+        return this.getIdToken();
     }
+    /**
+     * Clears PH-CMS tokens **and** signs the user out of Firebase.
+     */
     async logout() {
-        this.accessToken = null;
-        this.refreshToken = null;
-        if (typeof window !== 'undefined') {
-            localStorage.removeItem(`${this.storageKeyPrefix}access_token`);
-            localStorage.removeItem(`${this.storageKeyPrefix}refresh_token`);
-        }
+        await super.logout();
         await this.auth.signOut();
     }
-    getRefreshToken() {
-        return this.refreshToken;
-    }
+    /**
+     * Returns the current Firebase ID token, or `null` if no user is signed in.
+     */
     async getIdToken() {
         const user = this.auth.currentUser;
         if (!user)

package/dist/auth/interfaces.d.ts

@@ -2,7 +2,9 @@ export interface AuthProvider {
     type: 'FIREBASE' | 'LOCAL';
     /**
      * Returns the current valid access token.
-     * Should handle refreshing if necessary (or return null/throw if expired and can't refresh).
+     * Implementations should check token expiration and attempt a refresh
+     * automatically before returning the token. If the token is expired
+     * and cannot be refreshed, return `null`.
      */
     getToken(): Promise<string | null>;
     /**
@@ -12,7 +14,28 @@ export interface AuthProvider {
      */
     hasToken(): boolean;
     /**
-     * Sets a callback to be called when the token is known to be expired by the external world (e.g. 401 response).
+     * Returns the current refresh token, or `null` if none is stored.
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Registers the function that performs the actual token refresh against the server.
+     * This is called by `PHCMSClient` after construction so that the provider can
+     * refresh tokens autonomously inside `getToken()` without a circular dependency
+     * on the client/module layer.
+     *
+     * The function receives the current refresh token and returns a fresh pair.
+     */
+    setRefreshFn(fn: (refreshToken: string) => Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>): void;
+    /**
+     * Stores a new pair of access/refresh tokens.
+     */
+    setTokens(accessToken: string, refreshToken: string): void;
+    /**
+     * Sets a callback to be called when the token is known to be expired by the
+     * external world (e.g. 401 response) and automatic refresh has failed.
      */
     onTokenExpired(callback: () => Promise<void>): void;
     /**

package/dist/auth/jwt-utils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+export interface JwtPayload {
+    /** Subject (user id / uid) */
+    sub?: string;
+    /** Internal user id (PH-CMS specific) */
+    id?: number;
+    /** Issued-at timestamp (seconds since epoch) */
+    iat?: number;
+    /** Expiration timestamp (seconds since epoch) */
+    exp?: number;
+    /** Any other claims */
+    [key: string]: unknown;
+}
+/**
+ * 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.
+ */
+export declare function decodeJwtPayload(token: string): JwtPayload | 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.
+ */
+export declare function getTokenExpirationMs(token: string): number | null;
+/**
+ * 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)
+ */
+export declare function isTokenExpired(token: string, bufferMs?: number): boolean | null;
+/**
+ * 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.
+ */
+export declare function getTokenTTL(token: string): number | null;