feat(tool-next): support App Bridge (#85)

* feat(tool-next): support App Bridge

* rename Test -> Example

* Update tool-plugins/nextjs-starter/src/utils/const.ts

Co-authored-by: Demetrius Feijóo <demetrius.feijoo.91@gmail.com>

* Update tool-plugins/nextjs-starter/src/hooks/useAppBridge.ts

Co-authored-by: Demetrius Feijóo <demetrius.feijoo.91@gmail.com>

* error handling for validation failure

* Update tool-plugins/nextjs-starter/README.md

Co-authored-by: Demetrius Feijóo <demetrius.feijoo.91@gmail.com>

* rename component

* Update tool-plugins/nextjs-starter/README.md

Co-authored-by: Demetrius Feijóo <demetrius.feijoo.91@gmail.com>

---------

Co-authored-by: Demetrius Feijóo <demetrius.feijoo.91@gmail.com>

space-plugins/nextjs-starter/src/hooks/useAppBridge.ts

@@ -111,6 +111,8 @@ const useAppBridgeAuth = ({
 			sessionStorage.setItem(KEY_SLUG, slug || '');
 		} catch (err) {
 			sessionStorage.removeItem(KEY_PARENT_HOST);
+			sessionStorage.removeItem(KEY_SLUG);
+			setError('Failed to request validation.');
 		}
 	};
 

space-plugins/nuxt-base/composables/useAppBridge.ts

@@ -94,6 +94,8 @@ const useAppBridgeAuth = ({
 			sessionStorage.setItem(KEY_SLUG, slug || '');
 		} catch (err) {
 			sessionStorage.removeItem(KEY_PARENT_HOST);
+			sessionStorage.removeItem(KEY_SLUG);
+			error.value = 'Failed to request validation.';
 		}
 	};
 

tool-plugins/nextjs-starter/README.md

@@ -46,7 +46,7 @@ There are two ways on how you can create a tool inside Storyblok. Depending on y
 4. Select `tool` as extension type
 5. Click on **Save**
 
-### Tool Configuration
+### Configuration
 
 Once the tool has been created, a new entry will appear inside the extension list. Open it and navigate to the `OAuth 2.0 and Pages` tab.
 
@@ -70,6 +70,43 @@ Start the application by running:
 yarn dev # pnpm dev or npm run dev
 ```
 
+### App Bridge
+
+App Bridge is an extra authentication layer recently introduced for Space Plugins and Tool Plugins. This starter assumes you've enabled App Bridge on the Settings page. Documentation on App Bridge will come in the near future, but you don't need to know about its inner process. This starter addresses a large portion of this aspect out of the box.
+
+<img src="./docs/app-bridge.png" alt="App Bridge" width="600" />
+
+If you don't want to use App Bridge, you can use [the legacy template](https://github.com/storyblok/custom-app-examples/tree/main/app-nextjs-starter).
+
+### App Bridge in Depth
+
+App Bridge authentication starts on the frontend by sending a postMessage to `app.storyblok.com`. In the `src/pages/index.tsx` file, you can find the following code:
+
+```jsx
+const { completed } = useAppBridge({ type: 'space-plugin', oauth: true });
+
+return (
+	<div>
+		{completed && (
+			<div>
+				<UserInfo />
+				<Test />
+			</div>
+		)}
+	</div>
+);
+```
+
+The code above handles both App Bridge authentication and OAuth.
+
+1. If you need to use Storyblok's Management API:
+
+After completing both authentications, the `<UserInfo />` component is rendered. This component sends a request to `/api/user_info`. The OAuth token is automatically included in the request as a cookie, and the endpoint retrieves the session using `await getAppSession(req, res)`. It then fetches user information from Storyblok's Management API using the OAuth token.
+
+2. If you don't need the Management API but still want to validate the request on the backend:
+
+When the `<Example />` component is rendered, it makes a request to `/api/example`. We attach the App Bridge token as a header. The endpoint verifies the token using `await verifyAppBridgeHeader(req)`. Only if the token is verified can you perform any desired action.
+
 ### Tool Installation
 
 Finally, install the application to your space:

tool-plugins/nextjs-starter/package.json

@@ -9,13 +9,15 @@
 		"lint": "next lint"
 	},
 	"dependencies": {
-		"@storyblok/app-extension-auth": "1.0.3",
+		"@storyblok/app-extension-auth": "2.0.0",
+		"jsonwebtoken": "^9.0.2",
 		"next": "13.4.19",
 		"react": "18.2.0",
 		"react-dom": "18.2.0",
 		"typescript": "5.2.2"
 	},
 	"devDependencies": {
+		"@types/jsonwebtoken": "^9.0.7",
 		"@types/node": "20.5.9",
 		"@types/react": "18.2.21",
 		"@types/react-dom": "18.2.7"