From 4c0ba1cfc77df577e4fff9fc0de4773f7462a27f Mon Sep 17 00:00:00 2001
From: Vincenzo Scamporlino <vincenzos@spotify.com>
Date: Mon, 27 Feb 2023 15:20:08 +0100
Subject: [PATCH] permission-node: improve createPermissionIntegrationRouter
 docs

Signed-off-by: Vincenzo Scamporlino <vincenzos@spotify.com>
---
 plugins/permission-node/api-report.md         | 20 +++----
 .../createPermissionIntegrationRouter.test.ts | 18 +++---
 .../createPermissionIntegrationRouter.ts      | 60 +++++++++++++------
 3 files changed, 58 insertions(+), 40 deletions(-)

diff --git a/plugins/permission-node/api-report.md b/plugins/permission-node/api-report.md
index 5d2966ec73..52e666996a 100644
--- a/plugins/permission-node/api-report.md
+++ b/plugins/permission-node/api-report.md
@@ -112,22 +112,20 @@ export const createConditionTransformer: <
 ) => ConditionTransformer<TQuery>;
 
 // @public
-export const createPermissionIntegrationRouter: <
+export function createPermissionIntegrationRouter<
   TResourceType extends string,
   TResource,
 >(
-  options: CreatePermissionIntegrationRouterOptions<TResourceType, TResource>,
-) => express.Router;
+  options: CreatePermissionIntegrationRouterResourceOptions<
+    TResourceType,
+    TResource
+  >,
+): express.Router;
 
 // @public
-export type CreatePermissionIntegrationRouterOptions<
-  TResourceType extends string,
-  TResource,
-> =
-  | {
-      permissions: Array<Permission>;
-    }
-  | CreatePermissionIntegrationRouterResourceOptions<TResourceType, TResource>;
+export function createPermissionIntegrationRouter(options: {
+  permissions: Array<Permission>;
+}): express.Router;
 
 // @public
 export type CreatePermissionIntegrationRouterResourceOptions<
diff --git a/plugins/permission-node/src/integration/createPermissionIntegrationRouter.test.ts b/plugins/permission-node/src/integration/createPermissionIntegrationRouter.test.ts
index 8b918cabb2..1a7462665e 100644
--- a/plugins/permission-node/src/integration/createPermissionIntegrationRouter.test.ts
+++ b/plugins/permission-node/src/integration/createPermissionIntegrationRouter.test.ts
@@ -65,16 +65,14 @@ const createApp = (
     | typeof defaultMockedGetResources
     | null = defaultMockedGetResources,
 ) => {
-  const router = createPermissionIntegrationRouter(
-    mockedGetResources
-      ? {
-          resourceType: 'test-resource',
-          permissions: [testPermission],
-          getResources: mockedGetResources,
-          rules: [testRule1, testRule2],
-        }
-      : { permissions: [testPermission] },
-  );
+  const router = mockedGetResources
+    ? createPermissionIntegrationRouter({
+        resourceType: 'test-resource',
+        permissions: [testPermission],
+        getResources: mockedGetResources,
+        rules: [testRule1, testRule2],
+      })
+    : createPermissionIntegrationRouter({ permissions: [testPermission] });
 
   return express().use(router);
 };
diff --git a/plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts b/plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts
index 715b1ec574..087de23198 100644
--- a/plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts
+++ b/plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts
@@ -182,20 +182,6 @@ export type CreatePermissionIntegrationRouterResourceOptions<
   ) => Promise<Array<TResource | undefined>>;
 };
 
-/**
- * Options for creating a permission integration router.
- *
- * @public
- */
-export type CreatePermissionIntegrationRouterOptions<
-  TResourceType extends string,
-  TResource,
-> =
-  | {
-      permissions: Array<Permission>;
-    }
-  | CreatePermissionIntegrationRouterResourceOptions<TResourceType, TResource>;
-
 /**
  * Create an express Router which provides an authorization route to allow
  * integration between the permission backend and other Backstage backend
@@ -203,6 +189,9 @@ export type CreatePermissionIntegrationRouterOptions<
  * their resources should add the router created by this function to their
  * express app inside their `createRouter` implementation.
  *
+ * In case the `permissions` option is provided, the router also
+ * provides a route that exposes permissions and routes of a plugin.
+ *
  * @remarks
  *
  * To make this concrete, we can use the Backstage software catalog as an
@@ -231,12 +220,40 @@ export type CreatePermissionIntegrationRouterOptions<
  *
  * @public
  */
-export const createPermissionIntegrationRouter = <
+export function createPermissionIntegrationRouter<
   TResourceType extends string,
   TResource,
 >(
-  options: CreatePermissionIntegrationRouterOptions<TResourceType, TResource>,
-): express.Router => {
+  options: CreatePermissionIntegrationRouterResourceOptions<
+    TResourceType,
+    TResource
+  >,
+): express.Router;
+
+/**
+ *
+ * Create an express Router which provides a route that exposes
+ * permissions and routes of a plugin.
+ * @public
+ */
+export function createPermissionIntegrationRouter(options: {
+  permissions: Array<Permission>;
+}): express.Router;
+
+/**
+ * @public
+ */
+export function createPermissionIntegrationRouter<
+  TResourceType extends string,
+  TResource,
+>(
+  options:
+    | { permissions: Array<Permission> }
+    | CreatePermissionIntegrationRouterResourceOptions<
+        TResourceType,
+        TResource
+      >,
+): express.Router {
   const router = Router();
   router.use(express.json());
 
@@ -326,13 +343,18 @@ export const createPermissionIntegrationRouter = <
   router.use(errorHandler());
 
   return router;
-};
+}
 
 function isCreatePermissionIntegrationRouterResourceOptions<
   TResourceType extends string,
   TResource,
 >(
-  options: CreatePermissionIntegrationRouterOptions<TResourceType, TResource>,
+  options:
+    | { permissions: Array<Permission> }
+    | CreatePermissionIntegrationRouterResourceOptions<
+        TResourceType,
+        TResource
+      >,
 ): options is CreatePermissionIntegrationRouterResourceOptions<
   TResourceType,
   TResource