Getting Started with @woographql/session-utils

This guide walks you through installing and configuring @woographql/session-utils for your WooGraphQL application.

This package requires a WooGraphQL Pro license. Configure your .npmrc:

@woographql:registry=https://yeetsquad.net/
//yeetsquad.net/:_authToken="YOUR_LICENSE_KEY"

npm install @woographql/session-utils

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

const tokenManager = new TokenManager({
  // Unique identifier for storage keys
  ID: 'my-store',

  // Session behaviors to enable
  behavior: [SessionBehavior.withAuth],

  // Callback to start/resume a session
  startSession: async () => {
    const response = await fetch('/api/session');
    const { sessionToken } = await response.json();
    return sessionToken;
  },

  // Callback to update the session
  updateSession: async (sessionToken) => {
    const response = await fetch('/api/session', {
      method: 'PUT',
      body: JSON.stringify({ sessionToken }),
    });
    const { newSessionToken } = await response.json();
    return newSessionToken;
  },

  // Callback to refresh auth token
  refreshAuthToken: async (refreshToken) => {
    const response = await fetch('/api/auth/refresh', {
      method: 'POST',
      body: JSON.stringify({ refreshToken }),
    });
    const { authToken } = await response.json();
    return authToken;
  },
});

// Start the session (lazy - only runs once)
await tokenManager.initializeSession();

// Check if ready
if (tokenManager.isReady()) {
  // Get tokens for GraphQL requests
  const { sessionToken, authToken } = tokenManager.getTokens();
}

Import and combine behaviors as needed:

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

// Guest shopping only
const guestBehavior = [SessionBehavior.guestOnly];

// Authenticated users only
const authBehavior = [SessionBehavior.authOnly];

// Both guest and authenticated, with device tracking
const fullBehavior = [
  SessionBehavior.withAuth,
  SessionBehavior.withClientSession,
];

By default, tokens are stored in:

For React applications, use @woographql/react-hooks which provides hooks that wrap the TokenManager:

import { useSessionManager } from '@woographql/react-hooks';

function MyApp() {
  const session = useSessionManager(tokenManager);

  if (!session.isReady) {
    return <Loading />;
  }

  return <Store cart={session.cart} />;
}

If the default TokenManager doesn't fit your needs, implement TokenManagerInterface:

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

const customManager: TokenManagerInterface = {
  ID: 'custom',
  getTokens: () => ({ sessionToken: '...', authToken: '...' }),
  saveTokens: (tokens) => { /* custom storage */ },
  hasTokens: () => true,
  isReady: () => true,
  initializeSession: () => Promise.resolve({}),
  endSession: () => {},
  startSession: () => Promise.resolve('token'),
  updateSession: () => Promise.resolve('token'),
  refreshAuthToken: () => Promise.resolve('token'),
  createClientSessionId: () => Promise.resolve({ clientSessionId: '...', timeout: '...' }),
  getClientSessionId: () => '...',
};

• Learn about Token Management in depth
• See how @woographql/react-hooks uses session-utils
• Check out @woographql/next for Next.js integration