@mapnests/gateway-web-sdk 1.0.5 → 1.0.7

package/README.md

@@ -4,59 +4,86 @@ A lightweight, production-ready session token management SDK for React and Next.
 
 ## Features
 
-- 🔄 **Automatic Token Refresh**: Configurable background refresh (default: 25 minutes)
-- 🔒 **HttpOnly Cookie Support**: Secure token storage via server-set cookies
-- ⚛️ **React Integration**: Simple React hook for seamless integration
-- 🎯 **Singleton Pattern**: Single session instance across your entire app
-- 📦 **Zero Dependencies**: Lightweight with only React as a peer dependency
-- 🚀 **Next.js Compatible**: Works with both React and Next.js applications (SSR-safe)
-- ⏱️ **Configurable Intervals**: Customize refresh and expiry times
-- 🔔 **State Subscriptions**: React to session state changes
-- 📘 **TypeScript Support**: Full TypeScript definitions included
+- Automatic token refresh with configurable background intervals
+- HttpOnly cookie support for secure token storage
+- React hook (`useSession`) for seamless integration
+- Singleton pattern ensuring a single session instance across your app
+- Zero runtime dependencies (`react` and `react-dom` as peer dependencies)
+- Next.js compatible (SSR-safe)
+- Built-in Fetch and Axios interceptors for automatic 401 handling
+- Full TypeScript definitions included
 
-## Security Notice
+## Installation
+
+```bash
+npm install @mapnests/gateway-web-sdk
+```
 
-⚠️ **Important**: This SDK prioritizes **server-set HttpOnly cookies** for maximum security. The SDK includes a fallback mechanism to set cookies client-side, but this is **less secure** as these cookies cannot be HttpOnly and are accessible to JavaScript.
+---
 
-**Recommended Setup:**
-- Always set cookies from your server using the `Set-Cookie` header with `HttpOnly` flag
-- The SDK will automatically detect and skip client-side cookie setting when server cookies are present
-- Client-side cookies should only be used for development or specific use cases where server-side setting is not possible
+## Implementation Guide
 
-## Installation
+Choose one of the three approaches below based on your preferred HTTP client. All three approaches share the same **Step 1** (environment setup) and **Step 2** (session initialization).
 
-```bash
-npm install gateway-web-sdk
+> **Next.js users:** Skip the Common Setup below and go directly to the [Next.js Integration](#nextjs-integration) section, which provides its own Steps 1–2. Then return here for Approach A, B, or C.
+
+---
+
+### Common Setup (Vite / CRA / React Apps)
+
+#### Step 1 — Environment Variables
+
+Create a `.env` file in your project root with the following variables:
+
+```env
+VITE_API_BASE_URL=https://your-gateway.example.com
+VITE_BOOTSTRAP_PATH=/api/session/bootstrap
+VITE_TOKEN_COOKIE_NAME=token
 ```
 
-## Quick Start
+| Variable | Description |
+|----------|-------------|
+| `VITE_API_BASE_URL` | Base URL of your API gateway |
+| `VITE_BOOTSTRAP_PATH` | Path to the session bootstrap endpoint |
+| `VITE_TOKEN_COOKIE_NAME` | Name of the token cookie set by your server |
 
-### Simple Implementation (Copy-Paste)
+Then create a config helper to read these values:
 
-This setup covers bootstrap on app start and three API patterns:
-- Users → Fetch interceptor
-- Products → Axios interceptor
-- Orders → Manual implementation
+```js
+// src/config.js
+const API_BASE_URL = import.meta.env.VITE_API_BASE_URL;
+const BOOTSTRAP_PATH = import.meta.env.VITE_BOOTSTRAP_PATH;
+const TOKEN_COOKIE_NAME = import.meta.env.VITE_TOKEN_COOKIE_NAME;
+
+if (!API_BASE_URL) throw new Error('VITE_API_BASE_URL is not defined');
+if (!BOOTSTRAP_PATH) throw new Error('VITE_BOOTSTRAP_PATH is not defined');
+if (!TOKEN_COOKIE_NAME) throw new Error('VITE_TOKEN_COOKIE_NAME is not defined');
+
+export { API_BASE_URL, BOOTSTRAP_PATH, TOKEN_COOKIE_NAME };
+```
+
+#### Step 2 — Initialize the Session Manager
+
+Configure and initialize the SDK once at your app's entry point:
 
-1) Configure and initialize once on app start
 ```jsx
+// src/main.jsx
 import React from 'react';
 import ReactDOM from 'react-dom/client';
-import { SessionManager } from 'gateway-web-sdk';
+import { SessionManager } from '@mapnests/gateway-web-sdk';
 import { API_BASE_URL, BOOTSTRAP_PATH, TOKEN_COOKIE_NAME } from './config.js';
 import App from './App';
 
 const sessionManager = SessionManager.getInstance();
-try {
-  sessionManager.configure({
-    bootstrapUrl: `${API_BASE_URL}${BOOTSTRAP_PATH}`,
-    tokenCookieName: TOKEN_COOKIE_NAME,
-  });
-} catch (error) {
-  console.error('Failed to configure session manager:', error);
-}
 
-sessionManager.initialize().catch(err => console.error('Failed to initialize session:', err));
+sessionManager.configure({
+  bootstrapUrl: `${API_BASE_URL}${BOOTSTRAP_PATH}`,
+  tokenCookieName: TOKEN_COOKIE_NAME,
+});
+
+sessionManager.initialize().catch(err =>
+  console.error('Failed to initialize session:', err)
+);
 
 ReactDOM.createRoot(document.getElementById('root')).render(
   <React.StrictMode>
@@ -65,39 +92,148 @@ ReactDOM.createRoot(document.getElementById('root')).render(
 );
 ```
 
-2) API layer with three patterns
+Now proceed with one of the three approaches below.
+
+---
+
+### Approach A — Fetch Interceptor
+
+The simplest option. Drop-in replacement for `fetch` that automatically handles session headers and 401 retry.
+
+#### Step 3 — Create the API layer
+
 ```js
-// src/api/index.js
-import axios from 'axios';
-import { fetchInterceptor, setupAxiosInterceptor, SessionManager } from 'gateway-web-sdk';
+// src/api.js
+import { fetchInterceptor } from '@mapnests/gateway-web-sdk';
+import { API_BASE_URL } from './config.js';
 
-const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'https://your-gateway.example.com';
+export const getUser = () =>
+  fetchInterceptor(`${API_BASE_URL}/api/user`);
+```
+
+#### Step 4 — Use in a component
+
+```jsx
+// src/Dashboard.jsx
+import { useEffect, useState } from 'react';
+import { useSession } from '@mapnests/gateway-web-sdk';
+import { getUser } from './api.js';
+
+export default function Dashboard() {
+  const { isInitialized, isLoading, error } = useSession();
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    if (!isInitialized) return;
+
+    getUser()
+      .then(res => res.json())
+      .then(setUser)
+      .catch(err => console.error('Failed to fetch user:', err));
+  }, [isInitialized]);
+
+  if (isLoading) return <p>Loading session...</p>;
+  if (error) return <p>Session error: {error}</p>;
+  if (!user) return <p>Loading data...</p>;
 
-// Users via Fetch interceptor
-export const getUser = () => fetchInterceptor(`${API_BASE_URL}/api/user`);
+  return <pre>{JSON.stringify(user, null, 2)}</pre>;
+}
+```
+
+---
+
+### Approach B — Axios Interceptor
+
+Best if you already use Axios. Wraps an Axios instance with automatic session headers and 401 retry.
+
+> Requires `axios` as a dependency: `npm install axios`
+
+#### Step 3 — Create the Axios instance and API layer
 
-// Products via Axios interceptor
-export const axiosInstance = setupAxiosInterceptor(
-  axios.create({ baseURL: API_BASE_URL, withCredentials: true })
+```js
+// src/api.js
+import axios from 'axios';
+import { setupAxiosInterceptor } from '@mapnests/gateway-web-sdk';
+import { API_BASE_URL } from './config.js';
+
+const api = setupAxiosInterceptor(
+  axios.create({
+    baseURL: API_BASE_URL,
+    withCredentials: true,
+  })
 );
-export const getProducts = () => axiosInstance.get('/api/products');
 
-// Orders via Manual implementation
+export const getUser = () => api.get('/api/user');
+```
+
+#### Step 4 — Use in a component
+
+```jsx
+// src/Dashboard.jsx
+import { useEffect, useState } from 'react';
+import { useSession } from '@mapnests/gateway-web-sdk';
+import { getUser } from './api.js';
+
+export default function Dashboard() {
+  const { isInitialized, isLoading, error } = useSession();
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    if (!isInitialized) return;
+
+    getUser()
+      .then(res => setUser(res.data))
+      .catch(err => console.error('Failed to fetch user:', err));
+  }, [isInitialized]);
+
+  if (isLoading) return <p>Loading session...</p>;
+  if (error) return <p>Session error: {error}</p>;
+  if (!user) return <p>Loading data...</p>;
+
+  return <pre>{JSON.stringify(user, null, 2)}</pre>;
+}
+```
+
+---
+
+### Approach C — Manual Implementation
+
+Full control over request construction and 401 handling. Use this when you need custom logic or don't want to use the built-in interceptors.
+
+#### Step 3 — Create a manual fetch wrapper
+
+```js
+// src/api.js
+import { SessionManager } from '@mapnests/gateway-web-sdk';
+import { API_BASE_URL } from './config.js';
+
 const sm = SessionManager.getInstance();
-async function manual(url, init = {}) {
-  const opts = { ...init, headers: { ...(init.headers || {}) }, credentials: 'include' };
+
+async function request(url, init = {}) {
+  const opts = {
+    ...init,
+    credentials: 'include',
+    headers: { ...(init.headers || {}) },
+  };
+
+  // Attach session headers
   opts.headers['cf-session-id'] = sm.getSessionId();
   opts.headers['x-client-platform'] = 'web';
+
   if (sm.shouldUseTokenHeader()) {
-    const t = sm.getToken(sm.config.tokenCookieName);
-    if (t) opts.headers[sm.config.tokenCookieName] = t;
+    const token = sm.getToken(sm.config.tokenCookieName);
+    if (token) opts.headers[sm.config.tokenCookieName] = token;
   }
+
   let res = await fetch(url, opts);
+
+  // Handle 401 INVALID_SESSION
   if (res.status === 401) {
     const cloned = res.clone();
     try {
-      const data = await cloned.json();
-      if (data.error_msg === 'INVALID_SESSION') {
+      const body = await cloned.json();
+      if (body.error_msg === 'INVALID_SESSION') {
+        // Wait for any in-progress refresh, or trigger a new one
         if (sm.isRefreshing()) {
           await sm.waitForRefresh();
         } else {
@@ -106,175 +242,203 @@ async function manual(url, init = {}) {
             await sm.refreshToken();
           }
         }
+
+        // Update headers with refreshed session
         opts.headers['cf-session-id'] = sm.getSessionId();
-        opts.headers['x-client-platform'] = 'web';
         if (sm.shouldUseTokenHeader()) {
-          const nt = sm.getToken(sm.config.tokenCookieName);
-          if (nt) opts.headers[sm.config.tokenCookieName] = nt;
+          const newToken = sm.getToken(sm.config.tokenCookieName);
+          if (newToken) opts.headers[sm.config.tokenCookieName] = newToken;
         }
+
+        // Retry the request
         res = await fetch(url, opts);
       }
     } catch {
-      // Not JSON or parsing failed
+      // Response was not JSON — return the original response
     }
   }
+
   return res;
 }
-export const getOrders = () => manual(`${API_BASE_URL}/api/orders`);
+
+export const getUser = () => request(`${API_BASE_URL}/api/user`);
 ```
 
-3) Usage in a component
+#### Step 4 — Use in a component
+
 ```jsx
+// src/Dashboard.jsx
 import { useEffect, useState } from 'react';
-import { useSession } from 'gateway-web-sdk';
-import { getUser, getProducts, getOrders } from './api/index.js';
+import { useSession } from '@mapnests/gateway-web-sdk';
+import { getUser } from './api.js';
 
 export default function Dashboard() {
   const { isInitialized, isLoading, error } = useSession();
-  const [data, setData] = useState(null);
+  const [user, setUser] = useState(null);
 
   useEffect(() => {
     if (!isInitialized) return;
-    (async () => {
-      try {
-        const [u, p, o] = await Promise.all([getUser(), getProducts(), getOrders()]);
-        if (!u.ok) throw new Error('User failed');
-        if (!o.ok) throw new Error('Orders failed');
-        setData({ user: await u.json(), products: p.data, orders: await o.json() });
-      } catch (e) {
-        console.error(e);
-        setData(null);
-      }
-    })();
+
+    getUser()
+      .then(res => res.json())
+      .then(setUser)
+      .catch(err => console.error('Failed to fetch user:', err));
   }, [isInitialized]);
 
-  if (isLoading) return <p>Loading session…</p>;
-  if (error) return <p>Session error, limited mode.</p>;
-  if (!data) return <p>Loading data…</p>;
+  if (isLoading) return <p>Loading session...</p>;
+  if (error) return <p>Session error: {error}</p>;
+  if (!user) return <p>Loading data...</p>;
 
-  return (
-    <div>
-      <h3>User</h3>
-      <pre>{JSON.stringify(data.user, null, 2)}</pre>
-      <h3>Products</h3>
-      <pre>{JSON.stringify(data.products, null, 2)}</pre>
-      <h3>Orders</h3>
-      <pre>{JSON.stringify(data.orders, null, 2)}</pre>
-    </div>
-  );
+  return <pre>{JSON.stringify(user, null, 2)}</pre>;
 }
 ```
 
-Notes
-- Install axios if you use the Axios pattern: `npm i axios`
-- Ensure your gateway exposes:
-  - GET /api/session/bootstrap
-  - GET /api/user
-  - GET /api/products
-  - GET /api/orders
-- The SDK automatically sends cookies; token header fallback is added only when necessary.
-
-### React Application
-
-```jsx
-import React from 'react';
-import { useSession } from 'gateway-web-sdk';
+---
 
-function App() {
-  const { isInitialized, isLoading, error, timeUntilRefresh, refresh } = useSession();
-
-  if (isLoading) {
-    return <div>Loading session...</div>;
-  }
+## Next.js Integration
 
-  if (error) {
-    return <div>Error: {error}</div>;
-  }
-
-  if (!isInitialized) {
-    return <div>Session not initialized</div>;
-  }
+> **Note:** For Next.js, use `NEXT_PUBLIC_` prefixed environment variables instead of `VITE_`, and replace the common **Step 1** config helper and **Step 2** initialization with the Next.js-specific setup below.
 
-  return (
-    <div>
-      <h1>Session Active</h1>
-      <p>Next refresh in: {Math.floor(timeUntilRefresh / 1000)} seconds</p>
-      <button onClick={refresh}>Refresh Now</button>
-    </div>
-  );
-}
+### Step 1 — Environment Variables
 
-export default App;
+```env
+NEXT_PUBLIC_API_BASE_URL=https://your-gateway.example.com
+NEXT_PUBLIC_BOOTSTRAP_PATH=/api/session/bootstrap
+NEXT_PUBLIC_TOKEN_COOKIE_NAME=token
 ```
 
-### Configuration
-
-Configure the session manager before your app renders:
+### Step 2 — Config Helper
 
-```jsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { SessionManager } from 'gateway-web-sdk';
-import App from './App';
+```js
+// src/config.js
+const API_BASE_URL = process.env.NEXT_PUBLIC_API_BASE_URL;
+const BOOTSTRAP_PATH = process.env.NEXT_PUBLIC_BOOTSTRAP_PATH;
+const TOKEN_COOKIE_NAME = process.env.NEXT_PUBLIC_TOKEN_COOKIE_NAME;
 
-// Configure session manager
-const sessionManager = SessionManager.getInstance();
-sessionManager.configure({
-  bootstrapUrl: 'https://your-api.com/session/bootstrap',
-  headers: {
-    'X-Custom-Header': 'value',
-  },
-});
+if (!API_BASE_URL) throw new Error('NEXT_PUBLIC_API_BASE_URL is not defined');
+if (!BOOTSTRAP_PATH) throw new Error('NEXT_PUBLIC_BOOTSTRAP_PATH is not defined');
+if (!TOKEN_COOKIE_NAME) throw new Error('NEXT_PUBLIC_TOKEN_COOKIE_NAME is not defined');
 
-ReactDOM.createRoot(document.getElementById('root')).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
+export { API_BASE_URL, BOOTSTRAP_PATH, TOKEN_COOKIE_NAME };
 ```
 
-### Next.js Application
+### App Router
+
+#### Step 3 — Create a Session Provider
 
-#### Using App Router (`app/layout.js`)
+Create a client component that initializes the session. This keeps the root layout as a Server Component, preserving the benefits of React Server Components.
 
 ```jsx
+// app/providers/SessionProvider.jsx
 'use client';
 
 import { useEffect } from 'react';
-import { SessionManager } from 'gateway-web-sdk';
+import { SessionManager } from '@mapnests/gateway-web-sdk';
+import { API_BASE_URL, BOOTSTRAP_PATH, TOKEN_COOKIE_NAME } from '@/src/config';
 
-export default function RootLayout({ children }) {
+const sessionManager = SessionManager.getInstance();
+
+export default function SessionProvider({ children }) {
   useEffect(() => {
-    const sessionManager = SessionManager.getInstance();
     sessionManager.configure({
-      bootstrapUrl: '/api/session/bootstrap',
+      bootstrapUrl: `${API_BASE_URL}${BOOTSTRAP_PATH}`,
+      tokenCookieName: TOKEN_COOKIE_NAME,
     });
-    
-    sessionManager.initialize();
+    sessionManager.initialize().catch(err =>
+      console.error('Failed to initialize session:', err)
+    );
   }, []);
 
+  return children;
+}
+```
+
+#### Step 4 — Add the Provider to the Root Layout
+
+The root layout stays as a Server Component — do **not** add `'use client'` here.
+
+```jsx
+// app/layout.js
+import SessionProvider from './providers/SessionProvider';
+
+export default function RootLayout({ children }) {
   return (
     <html lang="en">
-      <body>{children}</body>
+      <body>
+        <SessionProvider>{children}</SessionProvider>
+      </body>
     </html>
   );
 }
 ```
 
-#### Using Pages Router (`pages/_app.js`)
+#### Step 5 — Create an API Layer and Use in a Page
+
+After your router setup is complete, create an API layer using any of **Approach A / B / C** from the [Implementation Guide](#implementation-guide) above. The only change needed is to replace `import.meta.env.VITE_*` references with imports from your `src/config.js`.
+
+For example, using Approach A (Fetch Interceptor):
+
+```js
+// src/api.js
+import { fetchInterceptor } from '@mapnests/gateway-web-sdk';
+import { API_BASE_URL } from './config';
+
+export const getUser = () =>
+  fetchInterceptor(`${API_BASE_URL}/api/user`);
+```
+
+Then use it in a page component. Page components that use hooks must be client components.
 
 ```jsx
+// app/dashboard/page.jsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useSession } from '@mapnests/gateway-web-sdk';
+import { getUser } from '@/src/api';
+
+export default function DashboardPage() {
+  const { isInitialized, isLoading, error } = useSession();
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    if (!isInitialized) return;
+
+    getUser()
+      .then(res => res.json())
+      .then(setUser)
+      .catch(err => console.error('Failed to fetch user:', err));
+  }, [isInitialized]);
+
+  if (isLoading) return <p>Loading session...</p>;
+  if (error) return <p>Session error: {error}</p>;
+  if (!user) return <p>Loading data...</p>;
+
+  return <pre>{JSON.stringify(user, null, 2)}</pre>;
+}
+```
+
+### Pages Router
+
+#### Step 3 — Initialize in `_app.js`
+
+```jsx
+// pages/_app.js
 import { useEffect } from 'react';
-import { SessionManager } from 'gateway-web-sdk';
+import { SessionManager } from '@mapnests/gateway-web-sdk';
+import { API_BASE_URL, BOOTSTRAP_PATH, TOKEN_COOKIE_NAME } from '../src/config';
+
+const sessionManager = SessionManager.getInstance();
 
 function MyApp({ Component, pageProps }) {
   useEffect(() => {
-    const sessionManager = SessionManager.getInstance();
     sessionManager.configure({
-      bootstrapUrl: '/api/session/bootstrap',
+      bootstrapUrl: `${API_BASE_URL}${BOOTSTRAP_PATH}`,
+      tokenCookieName: TOKEN_COOKIE_NAME,
     });
-    
-    sessionManager.initialize();
+    sessionManager.initialize().catch(err =>
+      console.error('Failed to initialize session:', err)
+    );
   }, []);
 
   return <Component {...pageProps} />;
@@ -283,30 +447,64 @@ function MyApp({ Component, pageProps }) {
 export default MyApp;
 ```
 
+#### Step 4 — Create an API Layer and Use in a Page
+
+Same as the App Router — create an `src/api.js` using any of **Approach A / B / C**, then use it in your page:
+
+```jsx
+// pages/dashboard.jsx
+import { useEffect, useState } from 'react';
+import { useSession } from '@mapnests/gateway-web-sdk';
+import { getUser } from '../src/api';
+
+export default function Dashboard() {
+  const { isInitialized, isLoading, error } = useSession();
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    if (!isInitialized) return;
+
+    getUser()
+      .then(res => res.json())
+      .then(setUser)
+      .catch(err => console.error('Failed to fetch user:', err));
+  }, [isInitialized]);
+
+  if (isLoading) return <p>Loading session...</p>;
+  if (error) return <p>Session error: {error}</p>;
+  if (!user) return <p>Loading data...</p>;
+
+  return <pre>{JSON.stringify(user, null, 2)}</pre>;
+}
+```
+
+---
+
 ## API Reference
 
-### `useSession(options)`
+### `useSession(options?)`
 
 React hook for session management.
 
-#### Parameters
+**Parameters:**
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `options.autoInitialize` | boolean | `true` | Automatically initialize session on mount |
 
-#### Return Value
+**Returns:**
 
 ```typescript
 {
-  isInitialized: boolean;      // Whether session is initialized
-  isLoading: boolean;          // Whether bootstrap is in progress
-  error: string | null;        // Error message if any
-  lastRefreshTime: number;     // Timestamp of last refresh
-  nextRefreshTime: number;     // Timestamp of next scheduled refresh
-  timeUntilRefresh: number;    // Milliseconds until next refresh
-  refresh: () => Promise<void>; // Manual refresh function
-  initialize: () => Promise<void>; // Manual initialize function
+  isInitialized: boolean;
+  isLoading: boolean;
+  error: string | null;
+  lastRefreshTime: number | null;
+  nextRefreshTime: number | null;
+  timeUntilRefresh: number | null;
+  initializationFailed: boolean;
+  refresh: () => Promise<void>;
+  initialize: () => Promise<void>;
 }
 ```
 
@@ -314,175 +512,187 @@ React hook for session management.
 
 Core session management class (Singleton).
 
-#### Methods
+#### `SessionManager.getInstance()`
 
-##### `configure(config)`
+Returns the singleton instance.
 
-Configure the session manager.
+#### `configure(config)`
 
 ```javascript
 sessionManager.configure({
-  bootstrapUrl: '/session/bootstrap',  // Required: Bootstrap API endpoint
-  tokenCookieName: 'stoken',     // Optional: Custom token cookie name
-  maxRetries: 3,                         // Optional: Max retry attempts
-  headers: {},                           // Optional: Additional headers
+  bootstrapUrl: '/session/bootstrap',    // Required: Bootstrap API endpoint
+  tokenCookieName: 'token',             // Optional: Token cookie name (default: 'token')
+  maxRetries: 3,                         // Optional: Max retry attempts (default: 3)
+  headers: {},                           // Optional: Additional headers for bootstrap calls
   credentials: true,                     // Optional: Include credentials (default: true)
+  logLevel: 'WARN',                      // Optional: 'NONE' | 'ERROR' | 'WARN' | 'INFO' | 'DEBUG'
 });
 ```
 
-Note: `refreshInterval` and `tokenExpiry` are automatically set by the server's bootstrap response (`refresh_time` and `expire` fields). You don't need to configure them manually.
+> `refreshInterval` and `tokenExpiry` are automatically set by the server's bootstrap response (`refresh_time` and `expire_time` fields). You don't need to configure them manually.
 
-##### `initialize()`
+#### `initialize()`
 
-Initialize session by calling bootstrap API.
+Initialize session by calling the bootstrap endpoint.
 
 ```javascript
 await sessionManager.initialize();
 ```
 
-##### `refreshToken()`
+#### `refreshToken()`
 
-Manually refresh the session token.
+Manually trigger a session token refresh.
 
 ```javascript
 await sessionManager.refreshToken();
 ```
 
-##### `getSessionStatus()`
+#### `getSessionId()`
 
-Get current session status.
+Returns the current `cf-session-id`.
 
-```javascript
-const status = sessionManager.getSessionStatus();
+#### `getToken(name?)`
+
+Returns the token value from the named cookie, or `null`.
+
+#### `shouldUseTokenHeader()`
+
+Returns `true` if the token should be sent as a request header (i.e. when the app is served over HTTP, not HTTPS).
+
+#### `isRefreshing()`
+
+Returns `true` if a refresh/initialize is currently in progress.
+
+#### `waitForRefresh()`
+
+Returns a promise that resolves when the in-progress refresh completes.
+
+#### `getSessionStatus()`
+
+Returns the current session state object.
+
+```typescript
+{
+  isInitialized: boolean;
+  isLoading: boolean;
+  lastRefreshTime: number | null;
+  nextRefreshTime: number | null;
+  tokenExpiry: number | null;
+  error: string | null;
+  errorCode: string | null;
+  initializationFailed: boolean;
+  timeUntilRefresh: number | null;
+}
 ```
 
-##### `subscribe(listener)`
+> **Note:** `getSessionStatus()` returns `tokenExpiry` and `errorCode` which are not exposed by the `useSession` hook. Use this method directly if you need those fields.
+
+#### `subscribe(listener)`
 
-Subscribe to session state changes.
+Subscribe to session state changes. Returns an unsubscribe function.
 
 ```javascript
 const unsubscribe = sessionManager.subscribe((state) => {
   console.log('Session state:', state);
 });
-
-// Later: unsubscribe()
 ```
 
-##### `destroy()`
+#### `destroy()`
+
+Clean up timers, listeners, and cookies. Resets the session manager.
+
+### `fetchInterceptor(url, options?)`
 
-Clean up and reset the session manager.
+Drop-in `fetch` wrapper. Automatically attaches session headers and retries on 401 `INVALID_SESSION`.
 
 ```javascript
-sessionManager.destroy();
+import { fetchInterceptor } from '@mapnests/gateway-web-sdk';
+const response = await fetchInterceptor('/api/data');
 ```
 
-### Interceptors (Optional)
+### `setupAxiosInterceptor(axiosInstance)`
 
-#### `fetchInterceptor(url, options)`
-
-Fetch wrapper with automatic token refresh on 401/403.
+Attaches request/response interceptors to an Axios instance. Returns the same instance.
 
 ```javascript
-import { fetchInterceptor } from 'gateway-web-sdk';
+import axios from 'axios';
+import { setupAxiosInterceptor } from '@mapnests/gateway-web-sdk';
+const api = setupAxiosInterceptor(axios.create({ baseURL: '/api' }));
+```
 
-const response = await fetchInterceptor('/api/data', {
-  method: 'GET',
-  headers: { 'Content-Type': 'application/json' }
-});
+### Error Classes
+
+The SDK exports custom error classes for typed error handling:
+
+```javascript
+import {
+  SessionError,       // Base error class (code, details)
+  ConfigurationError, // Invalid configuration (code: 'CONFIGURATION_ERROR')
+  BootstrapError,     // Bootstrap API failure (code: 'BOOTSTRAP_ERROR')
+  NetworkError,       // Network-level failure (code: 'NETWORK_ERROR')
+  SSRError,           // Called in non-browser environment (code: 'SSR_ERROR')
+} from '@mapnests/gateway-web-sdk';
 ```
 
-#### `setupAxiosInterceptor(axiosInstance)`
+All errors extend `SessionError`, which provides `code` (string) and `details` (object) properties.
 
-Configure Axios instance with automatic token refresh.
+### `logger` and `LOG_LEVELS`
+
+The SDK's internal logger is exported for advanced use (e.g. setting log level independently of `configure()`):
 
 ```javascript
-import axios from 'axios';
-import { setupAxiosInterceptor } from 'gateway-web-sdk';
+import { logger, LOG_LEVELS } from '@mapnests/gateway-web-sdk';
 
-const api = setupAxiosInterceptor(axios.create({
-  baseURL: 'https://api.example.com'
-}));
+logger.setLevel('DEBUG');     // or logger.setLevel(LOG_LEVELS.DEBUG)
+logger.info('Custom log');    // [SessionManager] Custom log
 ```
 
-## Client-Side Best Practices
+Available levels: `NONE` (0), `ERROR` (1), `WARN` (2, default), `INFO` (3), `DEBUG` (4).
+
+---
+
+## Security Notice
+
+This SDK prioritizes **server-set HttpOnly cookies** for maximum security. The SDK includes a fallback to set cookies client-side, but these cannot be HttpOnly and are accessible to JavaScript.
+
+**Recommended:** Always set cookies from your server using the `Set-Cookie` header with `HttpOnly` flag. The SDK will detect server cookies and skip client-side cookie setting automatically.
 
-1. Single Instance: Call configure() once at app startup and reuse the singleton.
-2. Token Timing: The server controls refresh and expiry timing via bootstrap response.
-3. Error Handling: Handle errors and provide user feedback for limited mode.
-4. HTTPS: Use secure, production-grade origins (https) in production environments.
-5. CORS/Credentials: If cross-origin, ensure credentials are enabled in server CORS (SDK defaults to credentials: true).
-6. Initialization: Initialize after configure() and before issuing business API calls.
+---
+
+## Best Practices
+
+1. **Single Instance** — Call `configure()` once at app startup and reuse the singleton.
+2. **Token Timing** — The server controls refresh and expiry timing via the bootstrap response.
+3. **Error Handling** — Handle errors gracefully and provide user feedback for limited mode.
+4. **HTTPS** — Always use HTTPS in production environments.
+5. **CORS/Credentials** — If cross-origin, ensure your server CORS allows credentials.
+6. **Initialization Order** — Always call `configure()` then `initialize()` before making API calls.
+
+---
 
 ## Troubleshooting
 
 ### Cookies not being set
-
 - Verify your API returns `Set-Cookie` header with `HttpOnly` flag
 - Check CORS configuration allows credentials
 - Ensure `credentials: true` in configuration
 
 ### Automatic refresh not working
-
 - Check browser console for errors
 - Verify server is sending `refresh_time` in bootstrap response
 - Ensure timer isn't being cleared prematurely
 
 ### Multiple initializations
-
 - The SDK uses singleton pattern, but ensure you're not calling `initialize()` multiple times
 - Use `autoInitialize: false` in `useSession()` if you want manual control
 
 ### Next.js SSR errors
-
-- The SDK automatically detects SSR environments and prevents initialization
+- The SDK detects SSR environments and prevents initialization
 - Always wrap initialization in `useEffect` or client components (`'use client'`)
 - Do not call `initialize()` during server-side rendering
 
-## TypeScript Support
-
-Full TypeScript definitions are included:
-
-```typescript
-import { SessionManager, useSession } from 'gateway-web-sdk';
-import type { SessionConfig, SessionState, UseSessionOptions } from 'gateway-web-sdk';
-
-const config: SessionConfig = {
-  bootstrapUrl: '/api/session',
-};
-
-const manager = SessionManager.getInstance();
-manager.configure(config);
-```
-
-## Changelog
-
-### [1.0.0] - 2024-01-12
-
-#### Added
-- Initial production release
-- TypeScript definitions for full type safety
-- Build process with Rollup (CJS + ESM outputs)
-- SSR detection for Next.js compatibility
-- Configuration validation
-- Secure session ID generation using crypto.randomUUID()
-- URL encoding for cookie values
-
-#### Security
-- Added warnings for client-side cookie limitations
-- Improved session ID generation with Web Crypto API
-- Added SSR environment checks to prevent runtime errors
-- URL-encoded cookie values to prevent injection
+---
 
 ## License
 
-MIT
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.
-
-## Support
-
-For issues and questions:
-- GitHub Issues: [Report a bug](https://github.com/yourusername/gateway-web-sdk/issues)
-- Documentation: [Full API Reference](#api-reference)
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapnests/gateway-web-sdk",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Session token management SDK with automatic refresh for React/Next.js applications",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -43,7 +43,8 @@
   },
   "peerDependencies": {
     "react": ">=16.8.0",
-    "react-dom": ">=16.8.0"
+    "react-dom": ">=16.8.0",
+    "axios": ">=0.21.0"
   },
   "peerDependenciesMeta": {
     "axios": {