Improve api reports

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

packages/catalog-client/api-report.md

@@ -58,6 +58,11 @@ export interface CatalogApi {
     locationRef: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
+  // @alpha
+  getPaginatedEntities?(
+    request?: GetPaginatedEntitiesRequest,
+    options?: CatalogRequestOptions,
+  ): Promise<GetPaginatedEntitiesResponse>;
   refreshEntity(
     entityRef: string,
     options?: CatalogRequestOptions,
@@ -124,6 +129,11 @@ export class CatalogClient implements CatalogApi {
     locationRef: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
+  // @alpha
+  getPaginatedEntities?(
+    request?: GetPaginatedEntitiesRequest,
+    options?: CatalogRequestOptions,
+  ): Promise<GetPaginatedEntitiesResponse>;
   refreshEntity(
     entityRef: string,
     options?: CatalogRequestOptions,
@@ -149,6 +159,12 @@ export interface CatalogRequestOptions {
   token?: string;
 }
 
+// @public
+export type EntitiesFilter =
+  | Record<string, string | symbol | (string | symbol)[]>[]
+  | Record<string, string | symbol | (string | symbol)[]>
+  | undefined;
+
 // @public
 export const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =
   'backstage.io/catalog-processing';
@@ -219,10 +235,7 @@ export interface GetEntityAncestorsResponse {
 // @public
 export interface GetEntityFacetsRequest {
   facets: string[];
-  filter?:
-    | Record<string, string | symbol | (string | symbol)[]>[]
-    | Record<string, string | symbol | (string | symbol)[]>
-    | undefined;
+  filter?: EntitiesFilter;
 }
 
 // @public
@@ -236,6 +249,42 @@ export interface GetEntityFacetsResponse {
   >;
 }
 
+// @alpha
+export type GetPaginatedEntitiesCursorRequest = {
+  fields?: string[];
+  limit?: number;
+  cursor: string;
+};
+
+// @alpha
+export type GetPaginatedEntitiesInitialRequest =
+  | {
+      fields?: string[];
+      limit?: number;
+      filter?: EntitiesFilter;
+      sortField?: string;
+      query?: string;
+      sortFieldOrder?: 'asc' | 'desc';
+    }
+  | undefined;
+
+// @alpha
+export type GetPaginatedEntitiesRequest =
+  | GetPaginatedEntitiesInitialRequest
+  | GetPaginatedEntitiesCursorRequest;
+
+// @alpha
+export type GetPaginatedEntitiesResponse = {
+  entities: Entity[];
+  totalItems: number;
+  next?(
+    request?: Omit<GetPaginatedEntitiesCursorRequest, 'cursor'>,
+  ): Promise<GetPaginatedEntitiesResponse>;
+  prev?(
+    request?: Omit<GetPaginatedEntitiesCursorRequest, 'cursor'>,
+  ): Promise<GetPaginatedEntitiesResponse>;
+};
+
 // @public
 type Location_2 = {
   id: string;

packages/catalog-client/src/CatalogClient.ts

@@ -207,6 +207,8 @@ export class CatalogClient implements CatalogApi {
 
   /**
    * {@inheritdoc CatalogApi.getPaginatedEntities}
+   *
+   * @alpha
    */
   async getPaginatedEntities?(
     request?: GetPaginatedEntitiesRequest,

packages/catalog-client/src/index.ts

@@ -22,4 +22,3 @@
 
 export { CatalogClient } from './CatalogClient';
 export * from './types';
-export * from './utils';

packages/catalog-client/src/types/api.ts

@@ -356,6 +356,11 @@ export type AddLocationRequest = {
   dryRun?: boolean;
 };
 
+/**
+ * Used for filtering entities that match the given patterns.
+ *
+ * @public
+ */
 export type EntitiesFilter =
   | Record<string, string | symbol | (string | symbol)[]>[]
   | Record<string, string | symbol | (string | symbol)[]>
@@ -481,12 +486,12 @@ export interface CatalogApi {
 
   /**
    * Gets paginated entities from the catalog.
-   * The method takes
-   * @alpha
+   *
    * @remarks
    *
    * Example:
    *
+   * ```
    * const response = await catalogClient.getPaginatedEntities({
    *   filter: [{ kind: 'group' }],
    *   limit: 20,
@@ -494,6 +499,7 @@ export interface CatalogApi {
    *   sortField: 'metadata.name',
    *   sortFieldOrder: 'asc'
    * });
+   * ```
    *
    * this will match all entities of type group having a name starting
    * with 'A', ordered by name ascending.
@@ -502,12 +508,16 @@ export interface CatalogApi {
    * more than 20 entities exist, the response will contain a next function, invocable
    * using:
    *
+   * ```
    * const secondBatchResponse = await response.next({ limit: 20 });
+   * ```
    *
    * secondBatchResponse will contain the next batch of maximum 20 entities, together
    * with a prev function useful for navigating backwards and a next function
    * in case more entities matching the filters of the first request are present in the catalog.
    *
+   * @alpha
+   *
    * @param request - Request parameters
    * @param options - Additional options
    */

packages/catalog-client/src/types/index.ts

@@ -25,6 +25,7 @@ export type {
   EntityOrderQuery,
   GetEntitiesByRefsRequest,
   GetEntitiesByRefsResponse,
+  EntitiesFilter,
   GetEntitiesRequest,
   GetEntitiesResponse,
   GetEntityAncestorsRequest,
@@ -35,6 +36,7 @@ export type {
   ValidateEntityResponse,
   GetPaginatedEntitiesCursorRequest,
   GetPaginatedEntitiesInitialRequest,
+  GetPaginatedEntitiesRequest,
   GetPaginatedEntitiesResponse,
 } from './api';
 export { ENTITY_STATUS_CATALOG_PROCESSING_TYPE } from './status';

plugins/catalog-backend/src/service/DefaultEntitiesCatalog.test.ts

@@ -717,7 +717,7 @@ describe('DefaultEntitiesCatalog', () => {
             .map(e => addEntityToSearch(knex, e)),
         );
 
-        const catalog = new DefaultEntitiesCatalog(knex);
+        const catalog = new DefaultEntitiesCatalog(knex, stitcher);
 
         const filter = {
           key: 'spec.should_include_this',
@@ -869,7 +869,7 @@ describe('DefaultEntitiesCatalog', () => {
             .map(e => addEntityToSearch(knex, e)),
         );
 
-        const catalog = new DefaultEntitiesCatalog(knex);
+        const catalog = new DefaultEntitiesCatalog(knex, stitcher);
 
         const filter = {
           key: 'spec.should_include_this',
@@ -1023,7 +1023,7 @@ describe('DefaultEntitiesCatalog', () => {
             .map(e => addEntityToSearch(knex, e)),
         );
 
-        const catalog = new DefaultEntitiesCatalog(knex);
+        const catalog = new DefaultEntitiesCatalog(knex, stitcher);
 
         const filter = {
           key: 'spec.should_include_this',
@@ -1064,7 +1064,7 @@ describe('DefaultEntitiesCatalog', () => {
             ),
         );
 
-        const catalog = new DefaultEntitiesCatalog(knex);
+        const catalog = new DefaultEntitiesCatalog(knex, stitcher);
 
         const request: PaginatedEntitiesInitialRequest = {
           limit: 0,
@@ -1346,7 +1346,7 @@ describe('DefaultEntitiesCatalog', () => {
           ],
         });
 
-        const catalog = new DefaultEntitiesCatalog(knex);
+        const catalog = new DefaultEntitiesCatalog(knex, stitcher);
 
         await expect(
           catalog.facets({