Improve session helper docs (#1376)

README.md

@@ -249,33 +249,33 @@ For other comprehensive examples, see the [EXAMPLES.md](https://github.com/auth0
 
 `import * from @auth0/nextjs-auth0/edge`
 
-- [Configuration Options and Environment variables](https://auth0.github.io/nextjs-auth0/modules/config.html)
-- [initAuth0](https://auth0.github.io/nextjs-auth0/modules/index.html#initauth0)
-- [handleAuth](https://auth0.github.io/nextjs-auth0/modules/handlers_auth.html)
-- [handleLogin](https://auth0.github.io/nextjs-auth0/modules/handlers_login.html#handlelogin)
-- [handleCallback](https://auth0.github.io/nextjs-auth0/modules/handlers_callback.html)
-- [handleLogout](https://auth0.github.io/nextjs-auth0/modules/handlers_logout.html)
-- [handleProfile](https://auth0.github.io/nextjs-auth0/modules/handlers_profile.html)
-- [withApiAuthRequired](https://auth0.github.io/nextjs-auth0/modules/helpers_with_api_auth_required.html)
-- [withPageAuthRequired](https://auth0.github.io/nextjs-auth0/modules/helpers_with_page_auth_required.html#withpageauthrequired)
-- [getSession](https://auth0.github.io/nextjs-auth0/modules/session_get_session.html)
-- [updateSession](https://auth0.github.io/nextjs-auth0/modules/session_update_session.html)
-- [getAccessToken](https://auth0.github.io/nextjs-auth0/modules/session_get_access_token.html)
-- [withMiddlewareAuthRequired](https://auth0.github.io/nextjs-auth0/modules/helpers_with_middleware_auth_required.html) (Edge only)
+- [Configuration Options and Environment variables](https://auth0.github.io/nextjs-auth0/types/config.ConfigParameters.html)
+- [initAuth0](https://auth0.github.io/nextjs-auth0/types/init.InitAuth0.html)
+- [handleAuth](https://auth0.github.io/nextjs-auth0/types/handlers_auth.HandleAuth.html)
+- [handleLogin](https://auth0.github.io/nextjs-auth0/types/handlers_login.HandleLogin.html)
+- [handleCallback](https://auth0.github.io/nextjs-auth0/types/handlers_callback.HandleCallback.html)
+- [handleLogout](https://auth0.github.io/nextjs-auth0/types/handlers_logout.HandleLogout.html)
+- [handleProfile](https://auth0.github.io/nextjs-auth0/types/handlers_profile.HandleProfile.html)
+- [withApiAuthRequired](https://auth0.github.io/nextjs-auth0/types/helpers_with_api_auth_required.WithApiAuthRequired.html)
+- [withPageAuthRequired](https://auth0.github.io/nextjs-auth0/types/helpers_with_page_auth_required.WithPageAuthRequired.html)
+- [getSession](https://auth0.github.io/nextjs-auth0/types/session_get_session.GetSession.html)
+- [updateSession](https://auth0.github.io/nextjs-auth0/types/session_update_session.UpdateSession.html)
+- [getAccessToken](https://auth0.github.io/nextjs-auth0/types/session_get_access_token.GetAccessToken.html)
+- [withMiddlewareAuthRequired](https://auth0.github.io/nextjs-auth0/types/helpers_with_middleware_auth_required.WithMiddlewareAuthRequired.html) (Edge only)
 
 ### Client (for the Browser)
 
 `import * from @auth0/nextjs-auth0/client`
 
-- [UserProvider](https://auth0.github.io/nextjs-auth0/modules/client_use_user.html#userprovider)
-- [useUser](https://auth0.github.io/nextjs-auth0/modules/client_use_user.html)
-- [withPageAuthRequired](https://auth0.github.io/nextjs-auth0/modules/client_with_page_auth_required.html)
+- [UserProvider](https://auth0.github.io/nextjs-auth0/types/client_use_user.UserProvider.html)
+- [useUser](https://auth0.github.io/nextjs-auth0/functions/client_use_user.useUser.html)
+- [withPageAuthRequired](https://auth0.github.io/nextjs-auth0/types/client_with_page_auth_required.WithPageAuthRequired.html)
 
 ### Testing helpers
 
 `import * from @auth0/nextjs-auth0/testing`
 
-- [generateSessionCookie](https://auth0.github.io/nextjs-auth0/modules/helpers_testing.html#generatesessioncookie)
+- [generateSessionCookie](https://auth0.github.io/nextjs-auth0/types/helpers_testing.GenerateSessionCookieConfig.html)
 
 Visit the auto-generated [API Docs](https://auth0.github.io/nextjs-auth0/) for more details
 

docs/types/session_touch_session.TouchSession.html

@@ -26,7 +26,29 @@ <h4>Type declaration</h4>
 <li class="tsd-description">
 <div class="tsd-comment tsd-typography"><p>Touch the session object. If rolling sessions are enabled and autoSave is disabled, you will need
 to call this method to update the session expiry.</p>
-<pre><code class="language-js"><span class="hl-0">// pages/api/graphql.js</span><br/><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">touchSession</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">&#39;@auth0/nextjs-auth0&#39;</span><span class="hl-2">;</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-1">default</span><span class="hl-2"> </span><span class="hl-5">async</span><span class="hl-2"> </span><span class="hl-5">function</span><span class="hl-2"> </span><span class="hl-6">graphql</span><span class="hl-2">(</span><span class="hl-3">req</span><span class="hl-2">, </span><span class="hl-3">res</span><span class="hl-2">) {</span><br/><span class="hl-2">  </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-6">touchSession</span><span class="hl-2">(</span><span class="hl-3">req</span><span class="hl-2">, </span><span class="hl-3">res</span><span class="hl-2">);</span><br/><br/><span class="hl-2"> </span><span class="hl-0">// ...</span><br/><span class="hl-2">};</span>
+<p><strong>In the App Router:</strong></p>
+<p>In a route handler:</p>
+<pre><code class="language-js"><span class="hl-0">// app/my-api/route.js</span><br/><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">touchSession</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">&#39;@auth0/nextjs-auth0&#39;</span><span class="hl-2">;</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-5">async</span><span class="hl-2"> </span><span class="hl-5">function</span><span class="hl-2"> </span><span class="hl-6">GET</span><span class="hl-2">() {</span><br/><span class="hl-2">  </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-6">touchSession</span><span class="hl-2">();</span><br/><span class="hl-2">  </span><span class="hl-1">return</span><span class="hl-2"> </span><span class="hl-3">NextResponse</span><span class="hl-2">.</span><span class="hl-6">json</span><span class="hl-2">({ </span><span class="hl-3">foo:</span><span class="hl-2"> </span><span class="hl-4">&#39;bar&#39;</span><span class="hl-2"> });</span><br/><span class="hl-2">}</span><br/><br/><span class="hl-0">// Or, it&#39;s slightly more efficient to use the `req`, `res` args if you&#39;re</span><br/><span class="hl-0">// using another part of the SDK like `withApiAuthRequired` or `getSession`.</span><br/><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">touchSession</span><span class="hl-2">, </span><span class="hl-3">withApiAuthRequired</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">&#39;@auth0/nextjs-auth0&#39;</span><span class="hl-2">;</span><br/><br/><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-7">GET</span><span class="hl-2"> = </span><span class="hl-6">withApiAuthRequired</span><span class="hl-2">(</span><span class="hl-5">async</span><span class="hl-2"> </span><span class="hl-5">function</span><span class="hl-2"> </span><span class="hl-6">GET</span><span class="hl-2">(</span><span class="hl-3">req</span><span class="hl-2">) {</span><br/><span class="hl-2">  </span><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-7">res</span><span class="hl-2"> = </span><span class="hl-5">new</span><span class="hl-2"> </span><span class="hl-6">NextResponse</span><span class="hl-2">();</span><br/><span class="hl-2">  </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-6">touchSession</span><span class="hl-2">(</span><span class="hl-3">req</span><span class="hl-2">, </span><span class="hl-3">res</span><span class="hl-2">);</span><br/><span class="hl-2">  </span><span class="hl-1">return</span><span class="hl-2"> </span><span class="hl-3">NextResponse</span><span class="hl-2">.</span><span class="hl-6">json</span><span class="hl-2">({ </span><span class="hl-3">foo:</span><span class="hl-2"> </span><span class="hl-4">&#39;bar&#39;</span><span class="hl-2"> }, </span><span class="hl-3">res</span><span class="hl-2">);</span><br/><span class="hl-2">});</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> { </span><span class="hl-3">GET</span><span class="hl-2"> };</span>
+</code><button>Copy</button></pre>
+<p>In a page or React Server Component:</p>
+<pre><code class="language-js"><span class="hl-0">// app/my-page/page.js</span><br/><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">touchSession</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">&#39;@auth0/nextjs-auth0&#39;</span><span class="hl-2">;</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-1">default</span><span class="hl-2"> </span><span class="hl-5">async</span><span class="hl-2"> </span><span class="hl-5">function</span><span class="hl-2"> </span><span class="hl-6">MyPage</span><span class="hl-2">({ </span><span class="hl-3">params</span><span class="hl-2">, </span><span class="hl-3">searchParams</span><span class="hl-2"> }) {</span><br/><span class="hl-2">  </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-6">touchSession</span><span class="hl-2">();</span><br/><span class="hl-2">  </span><span class="hl-1">return</span><span class="hl-2"> </span><span class="hl-8">&lt;</span><span class="hl-11">h1</span><span class="hl-8">&gt;</span><span class="hl-2">My Page</span><span class="hl-8">&lt;/</span><span class="hl-11">h1</span><span class="hl-8">&gt;</span><span class="hl-2">;</span><br/><span class="hl-2">}</span>
+</code><button>Copy</button></pre>
+<p><strong>Note:</strong> You can&#39;t write to the cookie in a React Server Component, so updates
+to the session like setting the expiry of the rolling session won&#39;t be persisted.
+For this, we recommend interacting with the session in the middleware.</p>
+<p>You can also touch the session in a page or route in the Edge Runtime:</p>
+<pre><code class="language-js"><span class="hl-0">// app/my-api/route.js</span><br/><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">getSession</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">&#39;@auth0/nextjs-auth0/edge&#39;</span><span class="hl-2">; </span><span class="hl-0">// Note the /edge import</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-1">default</span><span class="hl-2"> </span><span class="hl-5">async</span><span class="hl-2"> </span><span class="hl-5">function</span><span class="hl-2"> </span><span class="hl-6">MyPage</span><span class="hl-2">({ </span><span class="hl-3">params</span><span class="hl-2">, </span><span class="hl-3">searchParams</span><span class="hl-2"> }) {</span><br/><span class="hl-2">  </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-6">touchSession</span><span class="hl-2">();</span><br/><span class="hl-2">  </span><span class="hl-1">return</span><span class="hl-2"> </span><span class="hl-8">&lt;</span><span class="hl-11">h1</span><span class="hl-8">&gt;</span><span class="hl-2">My Page</span><span class="hl-8">&lt;/</span><span class="hl-11">h1</span><span class="hl-8">&gt;</span><span class="hl-2">;</span><br/><span class="hl-2">}</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-7">runtime</span><span class="hl-2"> = </span><span class="hl-4">&#39;edge&#39;</span><span class="hl-2">;</span>
+</code><button>Copy</button></pre>
+<p><strong>Note:</strong> The Edge runtime features are only supported in the App Router.</p>
+<p><strong>In the Page Router:</strong></p>
+<p>In an API handler:</p>
+<pre><code class="language-js"><span class="hl-0">// pages/api/my-api.js</span><br/><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">touchSession</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">&#39;@auth0/nextjs-auth0&#39;</span><span class="hl-2">;</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-1">default</span><span class="hl-2"> </span><span class="hl-5">async</span><span class="hl-2"> </span><span class="hl-5">function</span><span class="hl-2"> </span><span class="hl-6">MyApi</span><span class="hl-2">(</span><span class="hl-3">req</span><span class="hl-2">, </span><span class="hl-3">res</span><span class="hl-2">) {</span><br/><span class="hl-2">  </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-6">touchSession</span><span class="hl-2">(</span><span class="hl-3">req</span><span class="hl-2">, </span><span class="hl-3">res</span><span class="hl-2">);</span><br/><span class="hl-2">  </span><span class="hl-3">res</span><span class="hl-2">.</span><span class="hl-6">status</span><span class="hl-2">(</span><span class="hl-14">200</span><span class="hl-2">).</span><span class="hl-6">json</span><span class="hl-2">({ </span><span class="hl-3">name:</span><span class="hl-2"> </span><span class="hl-3">user</span><span class="hl-2">.</span><span class="hl-3">name</span><span class="hl-2"> });</span><br/><span class="hl-2">}</span>
+</code><button>Copy</button></pre>
+<p>In a page:</p>
+<pre><code class="language-js"><span class="hl-0">// pages/my-page.js</span><br/><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">touchSession</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">&#39;@auth0/nextjs-auth0&#39;</span><span class="hl-2">;</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-1">default</span><span class="hl-2"> </span><span class="hl-5">function</span><span class="hl-2"> </span><span class="hl-6">About</span><span class="hl-2">() {</span><br/><span class="hl-2">  </span><span class="hl-1">return</span><span class="hl-2"> </span><span class="hl-8">&lt;</span><span class="hl-11">div</span><span class="hl-8">&gt;</span><span class="hl-2">About</span><span class="hl-8">&lt;/</span><span class="hl-11">div</span><span class="hl-8">&gt;</span><span class="hl-2">;</span><br/><span class="hl-2">}</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-5">async</span><span class="hl-2"> </span><span class="hl-5">function</span><span class="hl-2"> </span><span class="hl-6">getServerSideProps</span><span class="hl-2">(</span><span class="hl-3">ctx</span><span class="hl-2">) {</span><br/><span class="hl-2">  </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-6">touchSession</span><span class="hl-2">(</span><span class="hl-3">ctx</span><span class="hl-2">.</span><span class="hl-3">req</span><span class="hl-2">, </span><span class="hl-3">ctx</span><span class="hl-2">.</span><span class="hl-3">res</span><span class="hl-2">);</span><br/><span class="hl-2">  </span><span class="hl-1">return</span><span class="hl-2"> { </span><span class="hl-3">props:</span><span class="hl-2"> { </span><span class="hl-3">foo:</span><span class="hl-2"> </span><span class="hl-4">&#39;bar&#39;</span><span class="hl-2"> } };</span><br/><span class="hl-2">}</span>
+</code><button>Copy</button></pre>
+<p><strong>In middleware:</strong></p>
+<pre><code class="language-js"><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">NextResponse</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">&#39;next/server&#39;</span><span class="hl-2">;</span><br/><span class="hl-1">import</span><span class="hl-2"> { </span><span class="hl-3">touchSession</span><span class="hl-2"> } </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">&#39;@auth0/nextjs-auth0/edge&#39;</span><span class="hl-2">; </span><span class="hl-0">// Note the /edge import</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-5">async</span><span class="hl-2"> </span><span class="hl-5">function</span><span class="hl-2"> </span><span class="hl-6">middleware</span><span class="hl-2">(</span><span class="hl-3">req</span><span class="hl-2">) {</span><br/><span class="hl-2">  </span><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-7">res</span><span class="hl-2"> = </span><span class="hl-5">new</span><span class="hl-2"> </span><span class="hl-6">NextResponse</span><span class="hl-2">();</span><br/><span class="hl-2">  </span><span class="hl-1">await</span><span class="hl-2"> </span><span class="hl-6">touchSession</span><span class="hl-2">(</span><span class="hl-3">req</span><span class="hl-2">, </span><span class="hl-3">res</span><span class="hl-2">);</span><br/><span class="hl-2">  </span><span class="hl-1">return</span><span class="hl-2"> </span><span class="hl-3">NextResponse</span><span class="hl-2">.</span><span class="hl-6">redirect</span><span class="hl-2">(</span><span class="hl-5">new</span><span class="hl-2"> </span><span class="hl-6">URL</span><span class="hl-2">(</span><span class="hl-4">&#39;/bar&#39;</span><span class="hl-2">, </span><span class="hl-3">request</span><span class="hl-2">.</span><span class="hl-3">url</span><span class="hl-2">), </span><span class="hl-3">res</span><span class="hl-2">);</span><br/><span class="hl-2">}</span><br/><br/><span class="hl-1">export</span><span class="hl-2"> </span><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-7">config</span><span class="hl-2"> = {</span><br/><span class="hl-2">  </span><span class="hl-3">matcher:</span><span class="hl-2"> </span><span class="hl-4">&#39;/foo&#39;</span><span class="hl-2">,</span><br/><span class="hl-2">};</span><br/><br/><span class="hl-2">@</span><span class="hl-3">category</span><span class="hl-2"> </span><span class="hl-3">Server</span>
 </code><button>Copy</button></pre>
 </div>
 <div class="tsd-parameters">
@@ -37,7 +59,7 @@ <h5><code class="tsd-tag ts-flagRest">Rest</code> <span class="tsd-signature-sym
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type ">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span></h4>
 <div class="tsd-comment tsd-typography"></div></li></ul></li></ul></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/auth0/nextjs-auth0/blob/b9edb82/src/session/touch-session.ts#L23">session/touch-session.ts:23</a></li></ul></aside></div>
+<li>Defined in <a href="https://github.com/auth0/nextjs-auth0/blob/5d993ac/src/session/touch-session.ts#L116">session/touch-session.ts:116</a></li></ul></aside></div>
 <div class="col-sidebar">
 <div class="page-menu">
 <div class="tsd-navigation settings">