Session Behaviors

Session behaviors define how your application handles different user types and what features are enabled. Configure them when creating a TokenManager.

import { SessionBehavior } from '@woographql/session-utils';

Enables support for authenticated WordPress users alongside guest sessions.

What it does:

• Manages authToken and refreshToken lifecycle
• Automatically refreshes auth tokens before expiration (every 10 minutes by default)
• Falls back to guest session when not authenticated
• Requires refreshAuthToken callback to be provided

Use when:

• Your store supports both guest checkout and user accounts
• You want to offer a seamless experience where users can browse as guests and optionally sign in

const tokenManager = new TokenManagerWithBrowserStorage({
  ID: 'my-store',
  behavior: [SessionBehavior.withAuth],
  startSession: async (tokens) => { /* ... */ },
  refreshAuthToken: async (refreshToken) => { /* Required for withAuth */ },
});

Requires authentication for all sessions. Guest sessions are not supported.

What it does:

• Session initialization fails if no valid refresh token exists
• All tokens (session, auth, refresh) must be present for isReady() to return true
• hasTokens() requires all three tokens

Use when:

• Your store is members-only
• All features require user authentication
• You're building a B2B store with registered accounts only

const tokenManager = new TokenManagerWithBrowserStorage({
  ID: 'my-store',
  behavior: [SessionBehavior.authOnly],
  startSession: async (tokens) => { /* ... */ },
  refreshAuthToken: async (refreshToken) => { /* Required */ },
});

Enables client session ID generation for device tracking and session handoff URLs.

What it does:

• Creates and maintains a clientSessionId that identifies the device
• Generates the ID using device fingerprinting (user agent, IP address, timestamp)
• Automatically renews the client session ID every 45 minutes
• Stores the ID in session storage (cleared when browser closes)
• Requires updateSession callback to sync with server

Use when:

• You need to generate session dropoff URLs for WordPress
• You want to track sessions across devices
• You need secure session handoff between headless frontend and WordPress backend

const tokenManager = new TokenManagerWithBrowserStorage({
  ID: 'my-store',
  behavior: [SessionBehavior.withClientSession],
  startSession: async (tokens) => { /* ... */ },
  updateSession: async (tokens, input) => { /* Required for withClientSession */ },
});

Behaviors are combined using an array. Common configurations:

No authentication support. Simplest configuration.

behavior: []

Token requirements:

• sessionToken only

Support both guest and authenticated sessions.

behavior: [SessionBehavior.withAuth]

Token requirements:

• sessionToken always
• authToken and refreshToken when authenticated

Auth support plus client session for session dropoff URLs.

behavior: [SessionBehavior.withAuth, SessionBehavior.withClientSession]

Token requirements:

• sessionToken always
• authToken and refreshToken when authenticated
• clientSessionId always

Members-only store with session dropoff.

behavior: [SessionBehavior.authOnly, SessionBehavior.withClientSession]

Token requirements:

• All tokens required