Library API

Besides the CLI and the components it scaffolds, @woographql/next ships a small runtime library that the generated app imports. It powers session bootstrapping and WooCommerce session-token management. There are two entry points:

The generated @auth/SessionProvider re-exports the right pieces for your chosen credentialStorageType, so application code usually imports from @auth/SessionProvider rather than reaching for these directly. This page summarizes the underlying API; each export has its own reference page:

Two flavors are provided; the install picks one based on credentialStorageType.

Server-bootstrapped session, hydrated from an HTTP-only cookie. Used when credentialStorageType: "cookies".

• AsyncSessionProvider — Client provider component. Receives the server-fetched initial session and exposes it through context.
• createSessionContext() — Factory that builds the typed session context (Provider + useSession-style hook) the app consumes.
• useSessionReadyGate() — Hook that defers rendering of session-dependent UI until the async session has hydrated, preventing SSR stream hangs.

localStorage-backed session that initializes synchronously on the client. Used when credentialStorageType: "browser".

• SessionProvider — Client provider component for the sync flavor.
• createSyncSessionContext() — Factory for the synchronous session context.

• TokenManager (abstract class) — Base class managing the WooCommerce session-token lifecycle (issue, refresh, persist). Concrete storage strategies extend it.
• useTokenManager() — Hook returning the active token-manager instance bound to the current session.
• useSessionFlag() — Hook reading the session-readiness flag (used by the browser flavor to know when a session exists).
• getTokenManagerInstance() — Imperative accessor for the singleton token-manager instance outside React.
• Cookies (type) — Shape of the cookie bag the token manager reads/writes.

Imported from @woographql/next/server (never bundled into the client):

• withTokenManager(handler) — Wraps a route handler so it runs with a request-scoped TokenManager read from the request cookies.
• withTokenManagerAndParams(handler) — Same, for handlers that also receive route params.
• withMiddlewareTokenManager(handler) — Wraps a Next.js proxy/middleware handler so session tokens are read, refreshed, and re-attached on the response.

A lightweight readiness flag coordinates the browser flavor with the server.

• SESSION_FLAG — The flag's cookie/header name.
• stampSessionFlag(response) — Stamp the flag onto a Response.
• stampSessionFlagForRequest(request) — Stamp readiness when bootstrapping a session (e.g. in the /api/session POST route).
• stampSessionFlagForAction() — Stamp the flag from within a Server Action.

// A route handler with a request-scoped token manager
import { withTokenManager } from '@woographql/next/server';
import { ServerTokenManager } from '@auth/ServerTokenManager';

export const GET = withTokenManager(ServerTokenManager, async (request, tokenManager) => {
  const { authToken } = await tokenManager.getTokens();
  return Response.json({ ok: true });
});

// Re-syncing the client session after a mutation in an API route
import { NextResponse } from 'next/server';
import { stampSessionFlagForRequest } from '@woographql/next/server';

export async function POST(request: Request) {
  const response = NextResponse.json({ ok: true });
  // stamps the flag onto the response (no-op for safe methods / non-cookie responses)
  stampSessionFlagForRequest(request, response);
  return response;
}

• Components — Generated UI that consumes the session context
• API Routes — Where the server helpers are wired
• Configuration — credentialStorageType selects the session flavor