Add more info about the proposal

Author: bcbogdan

lib/ts/recipe/session/nextjs/README.md

@@ -38,7 +38,9 @@ SuperTokensConfig.init();
 
 ```
 
-### 3. Add the SuperTokensProvider Component
+### 3. Add the authentication UI
+
+#### 3.1 Wrap the app with SuperTokensProvider
 
 ```tsx
 // This should abstract away more of the custom boilerplate
@@ -49,15 +51,26 @@ function Root({ children }) {
 }
 ```
 
-### 4. Add the SuperTokens Middleware
+#### 3.2 Add the UI components
+
+This will differ based on custom vs pre-built UI.
 
-We set the middleware as the default way of handling validation.
+### 4. Add the SuperTokens API function
 
-### Additional Examples
+```ts
+import { getNextJSApiHandler } from "supertokens-node/nextjs";
 
-#### How to protect a page?
+// Include the cache control logic and other custom options in this function
+// Allow users to config the behavior through a factory function
+const handler = getNextJSApiHandler();
+export default handler;
+```
 
-#### Using the `SessionAuth` component
+### 4. Protect pages and API routes
+
+#### Frontend
+
+##### Using the `SessionAuth` component
 
 ```tsx
 import { SessionAuth } from "supertokens-auth-react/recipe/session";
@@ -71,7 +84,7 @@ export default function Home() {
 }
 ```
 
-#### Using the `useSessionContext` hook
+##### Using the `useSessionContext` hook
 
 ```tsx
 import { useSessionContext } from "supertokens-auth-react/recipe/session";
@@ -87,21 +100,57 @@ export default function Home() {
 }
 ```
 
-:::info
-This applies to both SSR and CSR components.
-:::
+##### During SSR
+
+```tsx
+import { getSession } from "supertokens-auth-react/nextjs";
+import { SessionAuth } from "supertokens-auth-react/recipe/session";
+
+export default function Home() {
+    const session = getSession();
+
+    return (
+        <SessionAuth>
+            <div>{session.userId}</div>
+        </SessionAuth>
+    );
+}
+```
+
+#### Backend
+
+##### With session guards
+
+```ts
+import { withSession } from "supertokens-node/nextjs";
 
-#### How to protect an API route?
+function handler(req: NextApiRequest, res: NextApiResponse, session: STSession) {
+    // Do something with the session
+}
 
-#### Get the user id in an API route
+export default withSession(handler, {
+    onUnauthorisedResponse: (req, res) => {},
+    onError: (err, req, res) => {},
+    roles: [],
+    permissions: [],
+});
+```
 
-- with session
-- middleware matching
-- Decorators?
+##### With a middleware
 
-## SSR Session Validation
+```ts
+import { getMiddleware } from "supertokens-node/nextjs";
+
+export const middleware = getMiddleware({
+    onUnauthorisedResponse: (req, res) => {},
+    onError: (err, req, res) => {},
+});
+
+export const config = {
+    matcher: "/api/:path*",
+};
+```
 
 ## Open Questions
 
-- Can we move everything to the `react` library?
 - Figure out how to deal with differences between app router and page router

lib/ts/recipe/session/nextjs/getSessionOrRedirect.tsx

@@ -7,14 +7,14 @@ import SuperTokens from "../../../superTokens";
 import type { AccessTokenPayload, LoadedSessionContext } from "../types";
 
 // const ACCESS_TOKEN_NAME = "st-access-token";
-const ACCESS_TOKEN_NAME = "sAccessToken";
+const COOKIE_ACCESS_TOKEN_NAME = "sAccessToken";
+const HEADER_ACCESS_TOKEN_NAME = "st-access-token";
 const FRONT_TOKEN_NAME = "sFrontToken";
 
 // TODO:
 // - Add error handling
-// - Figure out the correct token name. Is it sAccessToken or st-access-token?
 export async function getSessionOrRedirect(): Promise<LoadedSessionContext> {
-    const headersList = await headers();
+    // const headersList = await headers();
     const cookieStore = await cookies();
     const frontToken = cookieStore.get(FRONT_TOKEN_NAME)?.value;
     const authPagePage = getWebsiteBasePath();
@@ -28,7 +28,9 @@ export async function getSessionOrRedirect(): Promise<LoadedSessionContext> {
         redirect(refreshTokenPath);
     }
 
-    const accessToken = cookieStore.get(ACCESS_TOKEN_NAME)?.value || headersList.get(ACCESS_TOKEN_NAME);
+    // Apparently both end up in cookies.
+    const accessToken =
+        cookieStore.get(COOKIE_ACCESS_TOKEN_NAME)?.value || cookieStore.get(HEADER_ACCESS_TOKEN_NAME)?.value;
     if (!accessToken) {
         // TODO: Should redirect to auth page?
         redirect(refreshTokenPath);