@mapnests/gateway-web-sdk 1.0.6 → 1.0.7

package/README.md

@@ -8,7 +8,7 @@ A lightweight, production-ready session token management SDK for React and Next.
 - HttpOnly cookie support for secure token storage
 - React hook (`useSession`) for seamless integration
 - Singleton pattern ensuring a single session instance across your app
-- Zero dependencies (only React as a peer dependency)
+- 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
@@ -25,9 +25,11 @@ npm install @mapnests/gateway-web-sdk
 
 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).
 
+> **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 (All Approaches)
+### Common Setup (Vite / CRA / React Apps)
 
 #### Step 1 — Environment Variables
 
@@ -45,8 +47,6 @@ VITE_TOKEN_COOKIE_NAME=token
 | `VITE_BOOTSTRAP_PATH` | Path to the session bootstrap endpoint |
 | `VITE_TOKEN_COOKIE_NAME` | Name of the token cookie set by your server |
 
-> If you are using Next.js, prefix with `NEXT_PUBLIC_` instead of `VITE_`.
-
 Then create a config helper to read these values:
 
 ```js
@@ -297,46 +297,148 @@ export default function Dashboard() {
 
 ## Next.js Integration
 
-### App Router (`app/layout.js`)
+> **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.
+
+### Step 1 — Environment Variables
+
+```env
+NEXT_PUBLIC_API_BASE_URL=https://your-gateway.example.com
+NEXT_PUBLIC_BOOTSTRAP_PATH=/api/session/bootstrap
+NEXT_PUBLIC_TOKEN_COOKIE_NAME=token
+```
+
+### Step 2 — Config Helper
+
+```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;
+
+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');
+
+export { API_BASE_URL, BOOTSTRAP_PATH, TOKEN_COOKIE_NAME };
+```
+
+### App Router
+
+#### Step 3 — Create a Session Provider
+
+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 '@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: `${process.env.NEXT_PUBLIC_API_BASE_URL}${process.env.NEXT_PUBLIC_BOOTSTRAP_PATH}`,
-      tokenCookieName: process.env.NEXT_PUBLIC_TOKEN_COOKIE_NAME,
+      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>
   );
 }
 ```
 
-### 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 '@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: `${process.env.NEXT_PUBLIC_API_BASE_URL}${process.env.NEXT_PUBLIC_BOOTSTRAP_PATH}`,
-      tokenCookieName: process.env.NEXT_PUBLIC_TOKEN_COOKIE_NAME,
+      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} />;
@@ -345,6 +447,37 @@ 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
@@ -366,9 +499,10 @@ React hook for session management.
   isInitialized: boolean;
   isLoading: boolean;
   error: string | null;
-  lastRefreshTime: number;
-  nextRefreshTime: number;
-  timeUntilRefresh: number;
+  lastRefreshTime: number | null;
+  nextRefreshTime: number | null;
+  timeUntilRefresh: number | null;
+  initializationFailed: boolean;
   refresh: () => Promise<void>;
   initialize: () => Promise<void>;
 }
@@ -423,7 +557,7 @@ Returns the token value from the named cookie, or `null`.
 
 #### `shouldUseTokenHeader()`
 
-Returns `true` if the token should be sent as a request header (manual token mode or HTTP protocol).
+Returns `true` if the token should be sent as a request header (i.e. when the app is served over HTTP, not HTTPS).
 
 #### `isRefreshing()`
 
@@ -437,6 +571,22 @@ Returns a promise that resolves when the in-progress refresh completes.
 
 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;
+}
+```
+
+> **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. Returns an unsubscribe function.
@@ -470,6 +620,35 @@ import { setupAxiosInterceptor } from '@mapnests/gateway-web-sdk';
 const api = setupAxiosInterceptor(axios.create({ baseURL: '/api' }));
 ```
 
+### 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';
+```
+
+All errors extend `SessionError`, which provides `code` (string) and `details` (object) properties.
+
+### `logger` and `LOG_LEVELS`
+
+The SDK's internal logger is exported for advanced use (e.g. setting log level independently of `configure()`):
+
+```javascript
+import { logger, LOG_LEVELS } from '@mapnests/gateway-web-sdk';
+
+logger.setLevel('DEBUG');     // or logger.setLevel(LOG_LEVELS.DEBUG)
+logger.info('Custom log');    // [SessionManager] Custom log
+```
+
+Available levels: `NONE` (0), `ERROR` (1), `WARN` (2, default), `INFO` (3), `DEBUG` (4).
+
 ---
 
 ## Security Notice

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapnests/gateway-web-sdk",
-  "version": "1.0.6",
+  "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": {