@aws-amplify/adapter-nextjs 0.0.2-console-preview.814dea6.0 → 0.0.2-preview-testing.64b45b1.0

package/lib/runWithAmplifyServerContext.d.ts

@@ -1,2 +1,45 @@
 import { NextServer } from './types';
+/**
+ * Runs the {@link operation} with the the context created from the {@link nextServerContext}.
+ *
+ * @param input The input to call the {@link runWithAmplifyServerContext}.
+ * @param input.nextServerContext The Next.js server context. It varies depends
+ *   where the {@link runWithAmplifyServerContext} is being called.
+ *   - In the [middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware):
+ *     the context consists of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Page server component](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#pages):
+ * 	   the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ *   - In a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers):
+ *     the context can be the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function or a combination of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Server Action](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#how-server-actions-work):
+ *     the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ * @param input.operation The function that contains the business logic calling
+ *   Amplify APIs. It expects a `contextSpec` parameter.
+ * @returns The result returned by the {@link operation}.
+ * @example
+ * // Use the `fetchAuthSession` API in the Next.js `middleware`.
+ * import { NextRequest, NextResponse } from "next/server";
+ * import { fetchAuthSession } from "aws-amplify/auth/server";
+ * import { runWithAmplifyServerContext } from "@aws-amplify/adapter-nextjs";
+
+ * export async function middleware(request: NextRequest) {
+ *   const response = NextResponse.next();
+ *   const authenticated = await runWithAmplifyServerContext({
+ *     nextServerContext: { request, response },
+ *     operation: async (contextSpec) => {
+ *       const session = await fetchAuthSession(contextSpec);
+ *       return session.tokens !== undefined;
+ *     }
+ *   });
+ *   if (authenticated) {
+ *     return response;
+ *   }
+ *   return NextResponse.redirect(new URL('/sign-in', request.url));
+ * }
+ */
 export declare const runWithAmplifyServerContext: NextServer.RunOperationWithContext;

package/lib/runWithAmplifyServerContext.js

@@ -42,6 +42,49 @@ exports.runWithAmplifyServerContext = void 0;
 var utils_1 = require("./utils");
 var core_1 = require("@aws-amplify/core");
 var adapter_core_1 = require("aws-amplify/internals/adapter-core");
+/**
+ * Runs the {@link operation} with the the context created from the {@link nextServerContext}.
+ *
+ * @param input The input to call the {@link runWithAmplifyServerContext}.
+ * @param input.nextServerContext The Next.js server context. It varies depends
+ *   where the {@link runWithAmplifyServerContext} is being called.
+ *   - In the [middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware):
+ *     the context consists of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Page server component](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#pages):
+ * 	   the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ *   - In a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers):
+ *     the context can be the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function or a combination of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Server Action](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#how-server-actions-work):
+ *     the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ * @param input.operation The function that contains the business logic calling
+ *   Amplify APIs. It expects a `contextSpec` parameter.
+ * @returns The result returned by the {@link operation}.
+ * @example
+ * // Use the `fetchAuthSession` API in the Next.js `middleware`.
+ * import { NextRequest, NextResponse } from "next/server";
+ * import { fetchAuthSession } from "aws-amplify/auth/server";
+ * import { runWithAmplifyServerContext } from "@aws-amplify/adapter-nextjs";
+
+ * export async function middleware(request: NextRequest) {
+ *   const response = NextResponse.next();
+ *   const authenticated = await runWithAmplifyServerContext({
+ *     nextServerContext: { request, response },
+ *     operation: async (contextSpec) => {
+ *       const session = await fetchAuthSession(contextSpec);
+ *       return session.tokens !== undefined;
+ *     }
+ *   });
+ *   if (authenticated) {
+ *     return response;
+ *   }
+ *   return NextResponse.redirect(new URL('/sign-in', request.url));
+ * }
+ */
 var runWithAmplifyServerContext = function (_a) {
     var nextServerContext = _a.nextServerContext, operation = _a.operation;
     return __awaiter(void 0, void 0, void 0, function () {

package/lib/runWithAmplifyServerContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"runWithAmplifyServerContext.js","sourceRoot":"","sources":["../src/runWithAmplifyServerContext.ts"],"names":[],"mappings":";AAAA,qEAAqE;AACrE,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGtC,iCAGiB;AACjB,0CAA0D;AAC1D,mEAK4C;AAErC,IAAM,2BAA2B,GACvC,UAAO,EAAgC;QAA9B,iBAAiB,uBAAA,EAAE,SAAS,eAAA;;;;YAM9B,aAAa,GAAG,IAAA,wBAAgB,GAAE,CAAC;YAEzC,wEAAwE;YACxE,+CAA+C;YAC/C,IAAI,aAAa,CAAC,IAAI,EAAE;gBACjB,eAAe;gBACpB,oEAAoE;gBACpE,8DAA8D;gBAC9D,iEAAiE;gBACjE,mEAAmE;gBACnE,iBAAiB,KAAK,IAAI;oBACzB,CAAC,CAAC,4BAAqB;oBACvB,CAAC,CAAC,IAAA,4DAA6C,EAC7C,IAAA,uDAA+C,EAAC,iBAAiB,CAAC,CACjE,CAAC;gBACA,mBAAmB,GAAG,IAAA,wDAAyC,EACpE,aAAa,CAAC,IAAI,EAClB,eAAe,CACf,CAAC;gBACI,aAAa,GAAG,IAAA,2CAA4B,EACjD,aAAa,CAAC,IAAI,EAClB,eAAe,CACf,CAAC;gBAEF,sBAAO,IAAA,0CAA+B,EACrC,aAAa,EACb;wBACC,IAAI,EAAE,EAAE,mBAAmB,qBAAA,EAAE,aAAa,eAAA,EAAE;qBAC5C,EACD,SAAS,CACT,EAAC;aACF;YAED,oEAAoE;YACpE,+CAA+C;YAC/C,sBAAO,IAAA,0CAA+B,EAAC,aAAa,EAAE,EAAE,EAAE,SAAS,CAAC,EAAC;;;CACrE,CAAC;AA3CU,QAAA,2BAA2B,+BA2CrC"}
+{"version":3,"file":"runWithAmplifyServerContext.js","sourceRoot":"","sources":["../src/runWithAmplifyServerContext.ts"],"names":[],"mappings":";AAAA,qEAAqE;AACrE,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGtC,iCAGiB;AACjB,0CAA0D;AAC1D,mEAK4C;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACI,IAAM,2BAA2B,GACvC,UAAO,EAAgC;QAA9B,iBAAiB,uBAAA,EAAE,SAAS,eAAA;;;;YAM9B,aAAa,GAAG,IAAA,wBAAgB,GAAE,CAAC;YAEzC,wEAAwE;YACxE,+CAA+C;YAC/C,IAAI,aAAa,CAAC,IAAI,EAAE;gBACjB,eAAe;gBACpB,oEAAoE;gBACpE,8DAA8D;gBAC9D,iEAAiE;gBACjE,mEAAmE;gBACnE,iBAAiB,KAAK,IAAI;oBACzB,CAAC,CAAC,4BAAqB;oBACvB,CAAC,CAAC,IAAA,4DAA6C,EAC7C,IAAA,uDAA+C,EAAC,iBAAiB,CAAC,CACjE,CAAC;gBACA,mBAAmB,GAAG,IAAA,wDAAyC,EACpE,aAAa,CAAC,IAAI,EAClB,eAAe,CACf,CAAC;gBACI,aAAa,GAAG,IAAA,2CAA4B,EACjD,aAAa,CAAC,IAAI,EAClB,eAAe,CACf,CAAC;gBAEF,sBAAO,IAAA,0CAA+B,EACrC,aAAa,EACb;wBACC,IAAI,EAAE,EAAE,mBAAmB,qBAAA,EAAE,aAAa,eAAA,EAAE;qBAC5C,EACD,SAAS,CACT,EAAC;aACF;YAED,oEAAoE;YACpE,+CAA+C;YAC/C,sBAAO,IAAA,0CAA+B,EAAC,aAAa,EAAE,EAAE,EAAE,SAAS,CAAC,EAAC;;;CACrE,CAAC;AA3CU,QAAA,2BAA2B,+BA2CrC"}

package/lib/types/NextServer.d.ts

@@ -42,7 +42,13 @@ export declare namespace NextServer {
         request: NextGetServerSidePropsContext['req'];
         response: NextGetServerSidePropsContext['res'];
     };
+    /**
+     * The union of possible Next.js app server context types.
+     */
     type Context = NextRequestAndNextResponseContext | NextRequestAndResponseContext | ServerComponentContext | GetServerSidePropsContext;
+    /**
+     * The interface of the input of {@link RunOperationWithContext}.
+     */
     interface RunWithContextInput<OperationResult> {
         nextServerContext: Context | null;
         operation: (contextSpec: AmplifyServer.ContextSpec) => OperationResult | Promise<OperationResult>;

package/lib-esm/runWithAmplifyServerContext.d.ts

@@ -1,2 +1,45 @@
 import { NextServer } from './types';
+/**
+ * Runs the {@link operation} with the the context created from the {@link nextServerContext}.
+ *
+ * @param input The input to call the {@link runWithAmplifyServerContext}.
+ * @param input.nextServerContext The Next.js server context. It varies depends
+ *   where the {@link runWithAmplifyServerContext} is being called.
+ *   - In the [middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware):
+ *     the context consists of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Page server component](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#pages):
+ * 	   the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ *   - In a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers):
+ *     the context can be the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function or a combination of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Server Action](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#how-server-actions-work):
+ *     the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ * @param input.operation The function that contains the business logic calling
+ *   Amplify APIs. It expects a `contextSpec` parameter.
+ * @returns The result returned by the {@link operation}.
+ * @example
+ * // Use the `fetchAuthSession` API in the Next.js `middleware`.
+ * import { NextRequest, NextResponse } from "next/server";
+ * import { fetchAuthSession } from "aws-amplify/auth/server";
+ * import { runWithAmplifyServerContext } from "@aws-amplify/adapter-nextjs";
+
+ * export async function middleware(request: NextRequest) {
+ *   const response = NextResponse.next();
+ *   const authenticated = await runWithAmplifyServerContext({
+ *     nextServerContext: { request, response },
+ *     operation: async (contextSpec) => {
+ *       const session = await fetchAuthSession(contextSpec);
+ *       return session.tokens !== undefined;
+ *     }
+ *   });
+ *   if (authenticated) {
+ *     return response;
+ *   }
+ *   return NextResponse.redirect(new URL('/sign-in', request.url));
+ * }
+ */
 export declare const runWithAmplifyServerContext: NextServer.RunOperationWithContext;

package/lib-esm/runWithAmplifyServerContext.js

@@ -39,6 +39,49 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 import { createCookieStorageAdapterFromNextServerContext, getAmplifyConfig, } from './utils';
 import { MemoryKeyValueStorage } from '@aws-amplify/core';
 import { createAWSCredentialsAndIdentityIdProvider, createKeyValueStorageFromCookieStorageAdapter, createUserPoolsTokenProvider, runWithAmplifyServerContext as runWithAmplifyServerContextCore, } from 'aws-amplify/internals/adapter-core';
+/**
+ * Runs the {@link operation} with the the context created from the {@link nextServerContext}.
+ *
+ * @param input The input to call the {@link runWithAmplifyServerContext}.
+ * @param input.nextServerContext The Next.js server context. It varies depends
+ *   where the {@link runWithAmplifyServerContext} is being called.
+ *   - In the [middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware):
+ *     the context consists of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Page server component](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#pages):
+ * 	   the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ *   - In a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers):
+ *     the context can be the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function or a combination of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Server Action](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#how-server-actions-work):
+ *     the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ * @param input.operation The function that contains the business logic calling
+ *   Amplify APIs. It expects a `contextSpec` parameter.
+ * @returns The result returned by the {@link operation}.
+ * @example
+ * // Use the `fetchAuthSession` API in the Next.js `middleware`.
+ * import { NextRequest, NextResponse } from "next/server";
+ * import { fetchAuthSession } from "aws-amplify/auth/server";
+ * import { runWithAmplifyServerContext } from "@aws-amplify/adapter-nextjs";
+
+ * export async function middleware(request: NextRequest) {
+ *   const response = NextResponse.next();
+ *   const authenticated = await runWithAmplifyServerContext({
+ *     nextServerContext: { request, response },
+ *     operation: async (contextSpec) => {
+ *       const session = await fetchAuthSession(contextSpec);
+ *       return session.tokens !== undefined;
+ *     }
+ *   });
+ *   if (authenticated) {
+ *     return response;
+ *   }
+ *   return NextResponse.redirect(new URL('/sign-in', request.url));
+ * }
+ */
 export var runWithAmplifyServerContext = function (_a) {
     var nextServerContext = _a.nextServerContext, operation = _a.operation;
     return __awaiter(void 0, void 0, void 0, function () {

package/lib-esm/runWithAmplifyServerContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"runWithAmplifyServerContext.js","sourceRoot":"","sources":["../src/runWithAmplifyServerContext.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGtC,OAAO,EACN,+CAA+C,EAC/C,gBAAgB,GAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EACN,yCAAyC,EACzC,6CAA6C,EAC7C,4BAA4B,EAC5B,2BAA2B,IAAI,+BAA+B,GAC9D,MAAM,oCAAoC,CAAC;AAE5C,MAAM,CAAC,IAAM,2BAA2B,GACvC,UAAO,EAAgC;QAA9B,iBAAiB,uBAAA,EAAE,SAAS,eAAA;;;;YAM9B,aAAa,GAAG,gBAAgB,EAAE,CAAC;YAEzC,wEAAwE;YACxE,+CAA+C;YAC/C,IAAI,aAAa,CAAC,IAAI,EAAE;gBACjB,eAAe;gBACpB,oEAAoE;gBACpE,8DAA8D;gBAC9D,iEAAiE;gBACjE,mEAAmE;gBACnE,iBAAiB,KAAK,IAAI;oBACzB,CAAC,CAAC,qBAAqB;oBACvB,CAAC,CAAC,6CAA6C,CAC7C,+CAA+C,CAAC,iBAAiB,CAAC,CACjE,CAAC;gBACA,mBAAmB,GAAG,yCAAyC,CACpE,aAAa,CAAC,IAAI,EAClB,eAAe,CACf,CAAC;gBACI,aAAa,GAAG,4BAA4B,CACjD,aAAa,CAAC,IAAI,EAClB,eAAe,CACf,CAAC;gBAEF,sBAAO,+BAA+B,CACrC,aAAa,EACb;wBACC,IAAI,EAAE,EAAE,mBAAmB,qBAAA,EAAE,aAAa,eAAA,EAAE;qBAC5C,EACD,SAAS,CACT,EAAC;aACF;YAED,oEAAoE;YACpE,+CAA+C;YAC/C,sBAAO,+BAA+B,CAAC,aAAa,EAAE,EAAE,EAAE,SAAS,CAAC,EAAC;;;CACrE,CAAC"}
+{"version":3,"file":"runWithAmplifyServerContext.js","sourceRoot":"","sources":["../src/runWithAmplifyServerContext.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,sCAAsC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGtC,OAAO,EACN,+CAA+C,EAC/C,gBAAgB,GAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EACN,yCAAyC,EACzC,6CAA6C,EAC7C,4BAA4B,EAC5B,2BAA2B,IAAI,+BAA+B,GAC9D,MAAM,oCAAoC,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,CAAC,IAAM,2BAA2B,GACvC,UAAO,EAAgC;QAA9B,iBAAiB,uBAAA,EAAE,SAAS,eAAA;;;;YAM9B,aAAa,GAAG,gBAAgB,EAAE,CAAC;YAEzC,wEAAwE;YACxE,+CAA+C;YAC/C,IAAI,aAAa,CAAC,IAAI,EAAE;gBACjB,eAAe;gBACpB,oEAAoE;gBACpE,8DAA8D;gBAC9D,iEAAiE;gBACjE,mEAAmE;gBACnE,iBAAiB,KAAK,IAAI;oBACzB,CAAC,CAAC,qBAAqB;oBACvB,CAAC,CAAC,6CAA6C,CAC7C,+CAA+C,CAAC,iBAAiB,CAAC,CACjE,CAAC;gBACA,mBAAmB,GAAG,yCAAyC,CACpE,aAAa,CAAC,IAAI,EAClB,eAAe,CACf,CAAC;gBACI,aAAa,GAAG,4BAA4B,CACjD,aAAa,CAAC,IAAI,EAClB,eAAe,CACf,CAAC;gBAEF,sBAAO,+BAA+B,CACrC,aAAa,EACb;wBACC,IAAI,EAAE,EAAE,mBAAmB,qBAAA,EAAE,aAAa,eAAA,EAAE;qBAC5C,EACD,SAAS,CACT,EAAC;aACF;YAED,oEAAoE;YACpE,+CAA+C;YAC/C,sBAAO,+BAA+B,CAAC,aAAa,EAAE,EAAE,EAAE,SAAS,CAAC,EAAC;;;CACrE,CAAC"}

package/lib-esm/types/NextServer.d.ts

@@ -42,7 +42,13 @@ export declare namespace NextServer {
         request: NextGetServerSidePropsContext['req'];
         response: NextGetServerSidePropsContext['res'];
     };
+    /**
+     * The union of possible Next.js app server context types.
+     */
     type Context = NextRequestAndNextResponseContext | NextRequestAndResponseContext | ServerComponentContext | GetServerSidePropsContext;
+    /**
+     * The interface of the input of {@link RunOperationWithContext}.
+     */
     interface RunWithContextInput<OperationResult> {
         nextServerContext: Context | null;
         operation: (contextSpec: AmplifyServer.ContextSpec) => OperationResult | Promise<OperationResult>;

package/package.json

@@ -15,7 +15,7 @@
 		"@types/node": "^20.3.1",
 		"@types/react": "^18.2.13",
 		"@types/react-dom": "^18.2.6",
-		"aws-amplify": "6.0.1-console-preview.814dea6.0+814dea6",
+		"aws-amplify": "6.0.1-preview-testing.64b45b1.0+64b45b1",
 		"jest-fetch-mock": "3.0.3",
 		"next": ">= 13.4.0 < 14.0.0",
 		"typescript": "5.1.6"
@@ -107,6 +107,6 @@
 		"ts-coverage": "typescript-coverage-report -p ./tsconfig.build.json -t 90.31"
 	},
 	"typings": "./lib-esm/index.d.ts",
-	"version": "0.0.2-console-preview.814dea6.0+814dea6",
-	"gitHead": "814dea654744bbf30c413151cfae31bbc367b8a3"
+	"version": "0.0.2-preview-testing.64b45b1.0+64b45b1",
+	"gitHead": "64b45b1680d18b8befa569ea69752179bea8c2ac"
 }

package/src/runWithAmplifyServerContext.ts

@@ -14,6 +14,49 @@ import {
 	runWithAmplifyServerContext as runWithAmplifyServerContextCore,
 } from 'aws-amplify/internals/adapter-core';
 
+/**
+ * Runs the {@link operation} with the the context created from the {@link nextServerContext}.
+ *
+ * @param input The input to call the {@link runWithAmplifyServerContext}.
+ * @param input.nextServerContext The Next.js server context. It varies depends
+ *   where the {@link runWithAmplifyServerContext} is being called.
+ *   - In the [middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware):
+ *     the context consists of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Page server component](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#pages):
+ * 	   the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ *   - In a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers):
+ *     the context can be the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function or a combination of an instance of the `NextRequest` and an instance
+ *     of the `NextResponse`.
+ *   - In a [Server Action](https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#how-server-actions-work):
+ *     the context is the [`cookies`](https://nextjs.org/docs/app/api-reference/functions/cookies)
+ *     function provided by Next.js.
+ * @param input.operation The function that contains the business logic calling
+ *   Amplify APIs. It expects a `contextSpec` parameter.
+ * @returns The result returned by the {@link operation}.
+ * @example
+ * // Use the `fetchAuthSession` API in the Next.js `middleware`.
+ * import { NextRequest, NextResponse } from "next/server";
+ * import { fetchAuthSession } from "aws-amplify/auth/server";
+ * import { runWithAmplifyServerContext } from "@aws-amplify/adapter-nextjs";
+
+ * export async function middleware(request: NextRequest) {
+ *   const response = NextResponse.next();
+ *   const authenticated = await runWithAmplifyServerContext({
+ *     nextServerContext: { request, response },
+ *     operation: async (contextSpec) => {
+ *       const session = await fetchAuthSession(contextSpec);
+ *       return session.tokens !== undefined;
+ *     }
+ *   });
+ *   if (authenticated) {
+ *     return response;
+ *   }
+ *   return NextResponse.redirect(new URL('/sign-in', request.url));
+ * }
+ */
 export const runWithAmplifyServerContext: NextServer.RunOperationWithContext =
 	async ({ nextServerContext, operation }) => {
 		// 1. get amplify config from env vars

package/src/types/NextServer.ts

@@ -51,12 +51,18 @@ export namespace NextServer {
 		response: NextGetServerSidePropsContext['res'];
 	};
 
+	/**
+	 * The union of possible Next.js app server context types.
+	 */
 	export type Context =
 		| NextRequestAndNextResponseContext
 		| NextRequestAndResponseContext
 		| ServerComponentContext
 		| GetServerSidePropsContext;
 
+	/**
+	 * The interface of the input of {@link RunOperationWithContext}.
+	 */
 	export interface RunWithContextInput<OperationResult> {
 		nextServerContext: Context | null;
 		operation: (