permission-node: improve createPermissionIntegrationRouter docs

Signed-off-by: Vincenzo Scamporlino <vincenzos@spotify.com>

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<

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);
 };

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