From 538ca90790c75f62b713dfb03b73da72b673f564 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Fri, 11 Feb 2022 15:51:18 +0100 Subject: [PATCH] catalog-client: clean up api exports MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/clever-pears-turn.md | 11 + .changeset/tasty-eagles-retire.md | 11 + packages/catalog-client/api-report.md | 97 +++--- .../catalog-client/src/CatalogClient.test.ts | 4 +- packages/catalog-client/src/CatalogClient.ts | 105 ++---- packages/catalog-client/src/types/api.ts | 303 +++++++++--------- .../catalog-client/src/types/deprecated.ts | 43 +++ .../catalog-client/src/types/discovery.ts | 2 - packages/catalog-client/src/types/fetch.ts | 2 - packages/catalog-client/src/types/index.ts | 11 +- plugins/catalog-backend/api-report.md | 8 +- .../src/search/DefaultCatalogCollator.ts | 8 +- plugins/catalog-graph/dev/index.tsx | 4 +- plugins/catalog-react/api-report.md | 4 +- .../src/hooks/useOwnedEntities.ts | 7 +- plugins/catalog/api-report.md | 16 +- plugins/catalog/src/CatalogClientWrapper.ts | 16 +- .../OwnershipCard/OwnershipCard.test.tsx | 10 +- .../EntityTagsPicker/EntityTagsPicker.tsx | 4 +- .../entityMetadataFactRetriever.test.ts | 6 +- .../entityOwnershipFactRetriever.test.ts | 6 +- .../techdocsFactRetriever.test.ts | 6 +- 22 files changed, 349 insertions(+), 335 deletions(-) create mode 100644 .changeset/clever-pears-turn.md create mode 100644 .changeset/tasty-eagles-retire.md create mode 100644 packages/catalog-client/src/types/deprecated.ts diff --git a/.changeset/clever-pears-turn.md b/.changeset/clever-pears-turn.md new file mode 100644 index 0000000000..33e08c231b --- /dev/null +++ b/.changeset/clever-pears-turn.md @@ -0,0 +1,11 @@ +--- +'@backstage/plugin-catalog': patch +'@backstage/plugin-catalog-backend': patch +'@backstage/plugin-catalog-graph': patch +'@backstage/plugin-catalog-react': patch +'@backstage/plugin-org': patch +'@backstage/plugin-scaffolder': patch +'@backstage/plugin-tech-insights-backend': patch +--- + +Use updated type names from `@backstage/catalog-client` diff --git a/.changeset/tasty-eagles-retire.md b/.changeset/tasty-eagles-retire.md new file mode 100644 index 0000000000..f93ae3b97e --- /dev/null +++ b/.changeset/tasty-eagles-retire.md @@ -0,0 +1,11 @@ +--- +'@backstage/catalog-client': minor +--- + +Deprecated the following types used by the catalog client, and created new +corresponding types to make them more consistent: + +- `CatalogEntitiesRequest` -> `GetEntitiesRequest` +- `CatalogListResponse` was removed and generally replaced with `GetEntitiesResponse` (which does not use a type parameter argument) +- `CatalogEntityAncestorsRequest`-> `GetEntityAncestorsRequest` +- `CatalogEntityAncestorsResponse` -> `GetEntityAncestorsResponse` diff --git a/packages/catalog-client/api-report.md b/packages/catalog-client/api-report.md index a489b32179..829acc221b 100644 --- a/packages/catalog-client/api-report.md +++ b/packages/catalog-client/api-report.md @@ -32,13 +32,13 @@ export interface CatalogApi { options?: CatalogRequestOptions, ): Promise; getEntities( - request?: CatalogEntitiesRequest, + request?: GetEntitiesRequest, options?: CatalogRequestOptions, - ): Promise>; + ): Promise; getEntityAncestors( - request: CatalogEntityAncestorsRequest, + request: GetEntityAncestorsRequest, options?: CatalogRequestOptions, - ): Promise; + ): Promise; getEntityByName( name: EntityName, options?: CatalogRequestOptions, @@ -84,13 +84,13 @@ export class CatalogClient implements CatalogApi { options?: CatalogRequestOptions, ): Promise; getEntities( - request?: CatalogEntitiesRequest, + request?: GetEntitiesRequest, options?: CatalogRequestOptions, - ): Promise>; + ): Promise; getEntityAncestors( - request: CatalogEntityAncestorsRequest, + request: GetEntityAncestorsRequest, options?: CatalogRequestOptions, - ): Promise; + ): Promise; getEntityByName( compoundName: EntityName, options?: CatalogRequestOptions, @@ -121,43 +121,60 @@ export class CatalogClient implements CatalogApi { ): Promise; } -// @public -export type CatalogEntitiesRequest = { - filter?: - | Record[] - | Record - | undefined; - fields?: string[] | undefined; - offset?: number; - limit?: number; - after?: string; -}; +// @public @deprecated (undocumented) +export type CatalogEntitiesRequest = GetEntitiesRequest; + +// @public @deprecated (undocumented) +export type CatalogEntityAncestorsRequest = GetEntityAncestorsRequest; + +// @public @deprecated (undocumented) +export type CatalogEntityAncestorsResponse = GetEntityAncestorsResponse; + +// @public @deprecated (undocumented) +export type CatalogListResponse<_Entity> = GetEntitiesResponse; // @public -export type CatalogEntityAncestorsRequest = { - entityRef: string; -}; - -// @public -export type CatalogEntityAncestorsResponse = { - rootEntityRef: string; - items: { - entity: Entity; - parentEntityRefs: string[]; - }[]; -}; - -// @public -export type CatalogListResponse = { - items: T[]; -}; - -// @public -export type CatalogRequestOptions = { +export interface CatalogRequestOptions { + // (undocumented) token?: string; -}; +} // @public export const ENTITY_STATUS_CATALOG_PROCESSING_TYPE = 'backstage.io/catalog-processing'; + +// @public +export interface GetEntitiesRequest { + after?: string; + fields?: string[] | undefined; + filter?: + | Record[] + | Record + | undefined; + limit?: number; + offset?: number; +} + +// @public +export interface GetEntitiesResponse { + // (undocumented) + items: Entity[]; +} + +// @public +export interface GetEntityAncestorsRequest { + // (undocumented) + entityRef: string; +} + +// @public +export interface GetEntityAncestorsResponse { + // (undocumented) + items: Array<{ + entity: Entity; + parentEntityRefs: string[]; + }>; + // (undocumented) + rootEntityRef: string; +} ``` diff --git a/packages/catalog-client/src/CatalogClient.test.ts b/packages/catalog-client/src/CatalogClient.test.ts index 1331f8e874..0035691f2c 100644 --- a/packages/catalog-client/src/CatalogClient.test.ts +++ b/packages/catalog-client/src/CatalogClient.test.ts @@ -18,7 +18,7 @@ import { Entity } from '@backstage/catalog-model'; import { rest } from 'msw'; import { setupServer } from 'msw/node'; import { CatalogClient } from './CatalogClient'; -import { CATALOG_FILTER_EXISTS, CatalogListResponse } from './types/api'; +import { CATALOG_FILTER_EXISTS, GetEntitiesResponse } from './types/api'; import { DiscoveryApi } from './types/discovery'; const server = setupServer(); @@ -60,7 +60,7 @@ describe('CatalogClient', () => { }, }, ]; - const defaultResponse: CatalogListResponse = { + const defaultResponse: GetEntitiesResponse = { items: defaultServiceResponse.reverse(), }; diff --git a/packages/catalog-client/src/CatalogClient.ts b/packages/catalog-client/src/CatalogClient.ts index 009bc9a6cb..3f2a3b39b6 100644 --- a/packages/catalog-client/src/CatalogClient.ts +++ b/packages/catalog-client/src/CatalogClient.ts @@ -31,20 +31,21 @@ import { AddLocationRequest, AddLocationResponse, CatalogApi, - CatalogEntitiesRequest, - CatalogListResponse, + GetEntitiesRequest, + GetEntitiesResponse, CatalogRequestOptions, - CatalogEntityAncestorsRequest, - CatalogEntityAncestorsResponse, + GetEntityAncestorsRequest, + GetEntityAncestorsResponse, } from './types/api'; import { DiscoveryApi } from './types/discovery'; import { FetchApi } from './types/fetch'; /** - * A frontend and backend compatible client for communicating with the Backstage Catalog. + * A frontend and backend compatible client for communicating with the Backstage + * software catalog. * * @public - * */ + */ export class CatalogClient implements CatalogApi { private readonly discoveryApi: DiscoveryApi; private readonly fetchApi: FetchApi; @@ -58,19 +59,12 @@ export class CatalogClient implements CatalogApi { } /** - * Gets the Ancestors of an Entity. - * - * @param request - A request type for retrieving Entity ancestors. - * @param options - An object with your preferred options. - * - * @returns A CatalogEntityAncestorsResponse. - * - * @public + * {@inheritdoc CatalogApi.getEntityAncestors} */ async getEntityAncestors( - request: CatalogEntityAncestorsRequest, + request: GetEntityAncestorsRequest, options?: CatalogRequestOptions, - ): Promise { + ): Promise { const { kind, namespace, name } = parseEntityRef(request.entityRef); return await this.requestRequired( 'GET', @@ -82,14 +76,7 @@ export class CatalogClient implements CatalogApi { } /** - * Gets a Location by Id. - * - * @param id - A string containing the Id. - * @param options - An object with your preferred options. - * - * @returns A {@link catalog-model#Location_2}. - * - * @public + * {@inheritdoc CatalogApi.getLocationById} */ async getLocationById( id: string, @@ -103,19 +90,12 @@ export class CatalogClient implements CatalogApi { } /** - * Gets a set of Entities. - * - * @param request - A request type for retrieving an Entity. - * @param options - An object with your preferred options. - * - * @returns A CatalogListResponse. - * - * @public + * {@inheritdoc CatalogApi.getEntities} */ async getEntities( - request?: CatalogEntitiesRequest, + request?: GetEntitiesRequest, options?: CatalogRequestOptions, - ): Promise> { + ): Promise { const { filter = [], fields = [], offset, limit, after } = request ?? {}; const filterItems = [filter].flat(); const params: string[] = []; @@ -190,14 +170,7 @@ export class CatalogClient implements CatalogApi { } /** - * Gets a given Entity based on a provided name. - * - * @param compoundName - A string containing the name. - * @param options - An object with your preferred options. - * - * @returns An {@link catalog-model#Entity}. - * - * @public + * {@inheritdoc CatalogApi.getEntityByName} */ async getEntityByName( compoundName: EntityName, @@ -214,12 +187,7 @@ export class CatalogClient implements CatalogApi { } /** - * Refreshes an Entity. - * - * @param entityRef - A string containing the entityREf - * @param options - An object with your preferred options. - * - * @public + * {@inheritdoc CatalogApi.refreshEntity} */ async refreshEntity(entityRef: string, options?: CatalogRequestOptions) { const response = await this.fetchApi.fetch( @@ -240,14 +208,7 @@ export class CatalogClient implements CatalogApi { } /** - * Adds a location. - * - * @param options - An object with your preferred options. - * @param AddLocationRequest - A request object for adding locations. - * - * @returns An AddLocationResponse - * - * @public + * {@inheritdoc CatalogApi.addLocation} */ async addLocation( { type = 'url', target, dryRun, presence }: AddLocationRequest, @@ -285,14 +246,7 @@ export class CatalogClient implements CatalogApi { } /** - * Gets an origin Location By Entity. - * - * @param entity - An Entity - * @param options - An object with your preferred options. - * - * @returns A {@link catalog-model#Location_2}. - * - * @public + * {@inheritdoc CatalogApi.getOriginLocationByEntity} */ async getOriginLocationByEntity( entity: Entity, @@ -314,14 +268,7 @@ export class CatalogClient implements CatalogApi { } /** - * Gets a Location by Entity. - * - * @param entity - An Entity - * @param options - An object with your preferred options. - * - * @returns A {@link catalog-model#Location_2}. - * - * @public + * {@inheritdoc CatalogApi.getLocationByEntity} */ async getLocationByEntity( entity: Entity, @@ -342,12 +289,7 @@ export class CatalogClient implements CatalogApi { } /** - * Removes a location as identified by Id. - * - * @param id - A string containing the Id - * @param options - An object with your preferred options. - * - * @public + * {@inheritdoc CatalogApi.removeLocationById} */ async removeLocationById( id: string, @@ -361,12 +303,7 @@ export class CatalogClient implements CatalogApi { } /** - * Removes an Entity as identified by Uid. - * - * @param uid - A string containing the Uid - * @param options - An object with your preferred options. - * - * @public + * {@inheritdoc CatalogApi.removeEntityByUid} */ async removeEntityByUid( uid: string, diff --git a/packages/catalog-client/src/types/api.ts b/packages/catalog-client/src/types/api.ts index 2177c41aa2..10e2e14a81 100644 --- a/packages/catalog-client/src/types/api.ts +++ b/packages/catalog-client/src/types/api.ts @@ -17,7 +17,9 @@ import { Entity, EntityName, Location } from '@backstage/catalog-model'; /** - * A Symbol to define if a catalog filter exists or not. + * This symbol can be used in place of a value when passed to filters in e.g. + * {@link CatalogClient.getEntities}, to signify that you want to filter on the + * presence of that key no matter what its value is. * * @public */ @@ -27,11 +29,11 @@ export const CATALOG_FILTER_EXISTS = Symbol.for( ); /** - * A request type for retrieving catalog Entities. + * The request type for {@link CatalogClient.getEntities}. * * @public */ -export type CatalogEntitiesRequest = { +export interface GetEntitiesRequest { /** * If given, return only entities that match the given patterns. * @@ -107,175 +109,50 @@ export type CatalogEntitiesRequest = { * request. */ after?: string; -}; +} /** - * A request type for Catalog Entity Ancestor information. + * The response type for {@link CatalogClient.getEntities}. * * @public */ -export type CatalogEntityAncestorsRequest = { +export interface GetEntitiesResponse { + items: Entity[]; +} + +/** + * The request type for {@link CatalogClient.getEntityAncestors}. + * + * @public + */ +export interface GetEntityAncestorsRequest { entityRef: string; -}; +} /** - * A response type for Catalog Entity Ancestor information. + * The response type for {@link CatalogClient.getEntityAncestors}. * * @public */ -export type CatalogEntityAncestorsResponse = { +export interface GetEntityAncestorsResponse { rootEntityRef: string; - items: { entity: Entity; parentEntityRefs: string[] }[]; -}; - -/** - * A response type for the result of a catalog operation in list form. - * - * @public - */ -export type CatalogListResponse = { - items: T[]; -}; + items: Array<{ + entity: Entity; + parentEntityRefs: string[]; + }>; +} /** * Options you can pass into a catalog request for additional information. * * @public */ -export type CatalogRequestOptions = { +export interface CatalogRequestOptions { token?: string; -}; - -/** - * Public functions for interacting with the Catalog API. - * - * @public - */ -export interface CatalogApi { - /** - * Gets the Entities from the catalog based on your request and options. - * - * @param request - An object with your filters and fields. - * @param options - An object with your preferred options. - * - * @returns A CatalogListResponse with items typed Catalog Model Entity. - * - */ - getEntities( - request?: CatalogEntitiesRequest, - options?: CatalogRequestOptions, - ): Promise>; - /** - * Gets the Entity ancestor information from the catalog based on your request and options. - * - * @param request - An object with your filters and fields. - * @param options - An object with your preferred options. - * - * @returns A CatalogEntityAncestorsResponse. - */ - getEntityAncestors( - request: CatalogEntityAncestorsRequest, - options?: CatalogRequestOptions, - ): Promise; - /** - * Gets a single Entity from the catalog by Entity name. - * - * @param name - A complete Entity name, with the full kind-namespace-name triplet. - * @param options - An object with your preferred options. - * - * @returns A {@link catalog-model#Entity}. - */ - getEntityByName( - name: EntityName, - options?: CatalogRequestOptions, - ): Promise; - /** - * Removes a single Entity from the catalog by Entity UID. - * - * @param uid - A string of the Entity UID. - * @param options - An object with your preferred options. - * - */ - removeEntityByUid( - uid: string, - options?: CatalogRequestOptions, - ): Promise; - /** - * Refreshes an Entity in the catalog. - * - * @param entityRef - A string in the form of 'Kind/default:foo'. - * @param options - An object with your preferred options. - * - */ - refreshEntity( - entityRef: string, - options?: CatalogRequestOptions, - ): Promise; - - // Locations - /** - * Gets a Location object by ID from the catalog. - * - * @param id - A string in of the Location Id. - * @param options - An object with your preferred options. - * - * @returns A {@link catalog-model#Location_2}. - */ - getLocationById( - id: string, - options?: CatalogRequestOptions, - ): Promise; - /** - * Gets origin location by Entity. - * - * @param entity - An {@link catalog-model#Entity}. - * @param options - An object with your preferred options. - * - * @returns A {@link catalog-model#Location_2}. - */ - getOriginLocationByEntity( - entity: Entity, - options?: CatalogRequestOptions, - ): Promise; - /** - * Gets Location by Entity. - * - * @param entity - An {@link catalog-model#Entity}. - * @param options - An object with your preferred options. - * - * @returns A {@link catalog-model#Location_2}. - */ - getLocationByEntity( - entity: Entity, - options?: CatalogRequestOptions, - ): Promise; - /** - * Adds a Location. - * - * @param location - A request type for adding a Location to the catalog. - * @param options - An object with your preferred options. - * - * @returns A AddLocationResponse. - */ - addLocation( - location: AddLocationRequest, - options?: CatalogRequestOptions, - ): Promise; - /** - * Removes a Location by Id. - * - * @param id - A string in of the Location Id. - * @param options - An object with your preferred options. - * - */ - removeLocationById( - id: string, - options?: CatalogRequestOptions, - ): Promise; } /** - * A request type for adding a Location to the catalog. + * The request type for {@link CatalogClient.addLocation}. * * @public */ @@ -287,13 +164,135 @@ export type AddLocationRequest = { }; /** - * A response type for adding a Location to the catalog. + * The response type for {@link CatalogClient.addLocation}. * * @public */ export type AddLocationResponse = { location: Location; entities: Entity[]; - // Exists is only set in DryRun mode. + // Only set in dryRun mode. exists?: boolean; }; + +/** + * A client for interacting with the Backstage software catalog through its API. + * + * @public + */ +export interface CatalogApi { + /** + * Lists catalog entities. + * + * @param request - Request parameters + * @param options - Additional options + */ + getEntities( + request?: GetEntitiesRequest, + options?: CatalogRequestOptions, + ): Promise; + + /** + * Gets entity ancestor information, i.e. the hierarchy of parent entities + * whose processing resulted in a given entity appearing in the catalog. + * + * @param request - Request parameters + * @param options - Additional options + */ + getEntityAncestors( + request: GetEntityAncestorsRequest, + options?: CatalogRequestOptions, + ): Promise; + + /** + * Gets a single entity from the catalog by its ref (kind, namespace, name) + * triplet. + * + * @param name - A complete entity ref + * @param options - Additional options + */ + getEntityByName( + name: EntityName, + options?: CatalogRequestOptions, + ): Promise; + + /** + * Removes a single entity from the catalog by entity UID. + * + * @param uid - An entity UID + * @param options - Additional options + */ + removeEntityByUid( + uid: string, + options?: CatalogRequestOptions, + ): Promise; + + /** + * Refreshes (marks for reprocessing) an entity in the catalog. + * + * @param entityRef - An entity ref on string form (e.g. + * 'component/default:my-component') + * @param options - Additional options + */ + refreshEntity( + entityRef: string, + options?: CatalogRequestOptions, + ): Promise; + + // Locations + + /** + * Gets a registered location by its ID. + * + * @param id - A location ID + * @param options - Additional options + */ + getLocationById( + id: string, + options?: CatalogRequestOptions, + ): Promise; + + /** + * Gets origin location by Entity. + * + * @param entity - An {@link catalog-model#Entity}. + * @param options - Additional options + */ + getOriginLocationByEntity( + entity: Entity, + options?: CatalogRequestOptions, + ): Promise; + + /** + * Gets Location by Entity. + * + * @param entity - An {@link catalog-model#Entity}. + * @param options - Additional options + */ + getLocationByEntity( + entity: Entity, + options?: CatalogRequestOptions, + ): Promise; + + /** + * Registers a new location. + * + * @param location - Request parameters + * @param options - Additional options + */ + addLocation( + location: AddLocationRequest, + options?: CatalogRequestOptions, + ): Promise; + + /** + * Removes a registered Location by its ID. + * + * @param id - A location ID + * @param options - Additional options + */ + removeLocationById( + id: string, + options?: CatalogRequestOptions, + ): Promise; +} diff --git a/packages/catalog-client/src/types/deprecated.ts b/packages/catalog-client/src/types/deprecated.ts new file mode 100644 index 0000000000..0b145f3024 --- /dev/null +++ b/packages/catalog-client/src/types/deprecated.ts @@ -0,0 +1,43 @@ +/* + * Copyright 2022 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { + GetEntitiesRequest, + GetEntitiesResponse, + GetEntityAncestorsRequest, + GetEntityAncestorsResponse, +} from './api'; + +/** + * @public + * @deprecated use GetEntitiesRequest instead + */ +export type CatalogEntitiesRequest = GetEntitiesRequest; +/** + * @public + * @deprecated use GetEntitiesResponse instead + */ +export type CatalogListResponse<_Entity> = GetEntitiesResponse; +/** + * @public + * @deprecated use GetEntityAncestorsRequest instead + */ +export type CatalogEntityAncestorsRequest = GetEntityAncestorsRequest; +/** + * @public + * @deprecated use GetEntityAncestorsResponse instead + */ +export type CatalogEntityAncestorsResponse = GetEntityAncestorsResponse; diff --git a/packages/catalog-client/src/types/discovery.ts b/packages/catalog-client/src/types/discovery.ts index 5fa14372e3..19f304b1fd 100644 --- a/packages/catalog-client/src/types/discovery.ts +++ b/packages/catalog-client/src/types/discovery.ts @@ -16,8 +16,6 @@ /** * This is a copy of the DiscoveryApi, to avoid importing core-plugin-api. - * - * @public */ export type DiscoveryApi = { getBaseUrl(pluginId: string): Promise; diff --git a/packages/catalog-client/src/types/fetch.ts b/packages/catalog-client/src/types/fetch.ts index 59de6a68f1..047a9f3558 100644 --- a/packages/catalog-client/src/types/fetch.ts +++ b/packages/catalog-client/src/types/fetch.ts @@ -16,8 +16,6 @@ /** * This is a copy of FetchApi, to avoid importing core-plugin-api. - * - * @public */ export type FetchApi = { fetch: typeof fetch; diff --git a/packages/catalog-client/src/types/index.ts b/packages/catalog-client/src/types/index.ts index cb6166c6d5..95a9a10416 100644 --- a/packages/catalog-client/src/types/index.ts +++ b/packages/catalog-client/src/types/index.ts @@ -14,15 +14,16 @@ * limitations under the License. */ +export { CATALOG_FILTER_EXISTS } from './api'; export type { AddLocationRequest, AddLocationResponse, CatalogApi, - CatalogEntitiesRequest, - CatalogListResponse, CatalogRequestOptions, - CatalogEntityAncestorsRequest, - CatalogEntityAncestorsResponse, + GetEntitiesRequest, + GetEntitiesResponse, + GetEntityAncestorsRequest, + GetEntityAncestorsResponse, } from './api'; -export { CATALOG_FILTER_EXISTS } from './api'; export { ENTITY_STATUS_CATALOG_PROCESSING_TYPE } from './status'; +export * from './deprecated'; diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index deed3e2d8b..2cc8f397c1 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -8,7 +8,6 @@ import { Account } from 'aws-sdk/clients/organizations'; import { BitbucketIntegration } from '@backstage/integration'; import { CatalogApi } from '@backstage/catalog-client'; -import { CatalogEntitiesRequest } from '@backstage/catalog-client'; import { ConditionalPolicyDecision } from '@backstage/plugin-permission-node'; import { Conditions } from '@backstage/plugin-permission-node'; import { Config } from '@backstage/config'; @@ -17,6 +16,7 @@ import { Entity } from '@backstage/catalog-model'; import { EntityPolicy } from '@backstage/catalog-model'; import { EntityRelationSpec } from '@backstage/catalog-model'; import express from 'express'; +import { GetEntitiesRequest } from '@backstage/catalog-client'; import { GithubCredentialsProvider } from '@backstage/integration'; import { GitHubIntegrationConfig } from '@backstage/integration'; import { IndexableDocument } from '@backstage/search-common'; @@ -509,7 +509,7 @@ export class DefaultCatalogCollator implements DocumentCollator { discovery: PluginEndpointDiscovery; tokenManager: TokenManager; locationTemplate?: string; - filter?: CatalogEntitiesRequest['filter']; + filter?: GetEntitiesRequest['filter']; catalogClient?: CatalogApi; }); // (undocumented) @@ -524,14 +524,14 @@ export class DefaultCatalogCollator implements DocumentCollator { // (undocumented) execute(): Promise; // (undocumented) - protected filter?: CatalogEntitiesRequest['filter']; + protected filter?: GetEntitiesRequest['filter']; // (undocumented) static fromConfig( _config: Config, options: { discovery: PluginEndpointDiscovery; tokenManager: TokenManager; - filter?: CatalogEntitiesRequest['filter']; + filter?: GetEntitiesRequest['filter']; }, ): DefaultCatalogCollator; // (undocumented) diff --git a/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts b/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts index 93ef6968d1..8e72a265af 100644 --- a/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts +++ b/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts @@ -28,7 +28,7 @@ import { Config } from '@backstage/config'; import { CatalogApi, CatalogClient, - CatalogEntitiesRequest, + GetEntitiesRequest, } from '@backstage/catalog-client'; import { catalogEntityReadPermission } from '@backstage/plugin-catalog-common'; @@ -43,7 +43,7 @@ export interface CatalogEntityDocument extends IndexableDocument { export class DefaultCatalogCollator implements DocumentCollator { protected discovery: PluginEndpointDiscovery; protected locationTemplate: string; - protected filter?: CatalogEntitiesRequest['filter']; + protected filter?: GetEntitiesRequest['filter']; protected readonly catalogClient: CatalogApi; public readonly type: string = 'software-catalog'; public readonly visibilityPermission = catalogEntityReadPermission; @@ -54,7 +54,7 @@ export class DefaultCatalogCollator implements DocumentCollator { options: { discovery: PluginEndpointDiscovery; tokenManager: TokenManager; - filter?: CatalogEntitiesRequest['filter']; + filter?: GetEntitiesRequest['filter']; }, ) { return new DefaultCatalogCollator({ @@ -66,7 +66,7 @@ export class DefaultCatalogCollator implements DocumentCollator { discovery: PluginEndpointDiscovery; tokenManager: TokenManager; locationTemplate?: string; - filter?: CatalogEntitiesRequest['filter']; + filter?: GetEntitiesRequest['filter']; catalogClient?: CatalogApi; }) { const { discovery, locationTemplate, filter, catalogClient, tokenManager } = diff --git a/plugins/catalog-graph/dev/index.tsx b/plugins/catalog-graph/dev/index.tsx index ed14e5fce9..b9da70c812 100644 --- a/plugins/catalog-graph/dev/index.tsx +++ b/plugins/catalog-graph/dev/index.tsx @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { CatalogListResponse } from '@backstage/catalog-client'; +import { GetEntitiesResponse } from '@backstage/catalog-client'; import { Entity, EntityName, @@ -136,7 +136,7 @@ createDevApp() async getEntityByName(name: EntityName): Promise { return entities[stringifyEntityRef(name)]; }, - async getEntities(): Promise> { + async getEntities(): Promise { return { items: Object.values(entities) }; }, } as Partial as unknown as CatalogApi; diff --git a/plugins/catalog-react/api-report.md b/plugins/catalog-react/api-report.md index 056f10f135..5ab3f20d76 100644 --- a/plugins/catalog-react/api-report.md +++ b/plugins/catalog-react/api-report.md @@ -9,12 +9,12 @@ import { ApiRef } from '@backstage/core-plugin-api'; import { AsyncState } from 'react-use/lib/useAsync'; import { CATALOG_FILTER_EXISTS } from '@backstage/catalog-client'; import { CatalogApi } from '@backstage/catalog-client'; -import { CatalogListResponse } from '@backstage/catalog-client'; import { ComponentEntity } from '@backstage/catalog-model'; import { ComponentProps } from 'react'; import { Context } from 'react'; import { Entity } from '@backstage/catalog-model'; import { EntityName } from '@backstage/catalog-model'; +import { GetEntitiesResponse } from '@backstage/catalog-client'; import { IconButton } from '@material-ui/core'; import { IdentityApi } from '@backstage/core-plugin-api'; import { LinkProps } from '@backstage/core-components'; @@ -612,7 +612,7 @@ export function useEntityTypeFilter(): EntityTypeReturn; // @public export function useOwnedEntities(allowedKinds?: string[]): { loading: boolean; - ownedEntities: CatalogListResponse | undefined; + ownedEntities: GetEntitiesResponse | undefined; }; // Warning: (ae-missing-release-tag) "useOwnUser" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) diff --git a/plugins/catalog-react/src/hooks/useOwnedEntities.ts b/plugins/catalog-react/src/hooks/useOwnedEntities.ts index ffe64830f4..dad73740c1 100644 --- a/plugins/catalog-react/src/hooks/useOwnedEntities.ts +++ b/plugins/catalog-react/src/hooks/useOwnedEntities.ts @@ -19,8 +19,8 @@ import { loadIdentityOwnerRefs, } from './useEntityOwnership'; import { identityApiRef, useApi } from '@backstage/core-plugin-api'; -import { Entity, RELATION_OWNED_BY } from '@backstage/catalog-model'; -import { CatalogListResponse } from '@backstage/catalog-client'; +import { RELATION_OWNED_BY } from '@backstage/catalog-model'; +import { GetEntitiesResponse } from '@backstage/catalog-client'; import useAsync from 'react-use/lib/useAsync'; import { useMemo } from 'react'; @@ -32,11 +32,10 @@ import { useMemo } from 'react'; * @public * * @param allowedKinds - Array of allowed kinds to filter the entities - * @returns CatalogListResponse */ export function useOwnedEntities(allowedKinds?: string[]): { loading: boolean; - ownedEntities: CatalogListResponse | undefined; + ownedEntities: GetEntitiesResponse | undefined; } { const identityApi = useApi(identityApiRef); const catalogApi = useApi(catalogApiRef); diff --git a/plugins/catalog/api-report.md b/plugins/catalog/api-report.md index fe20c1548b..22a9dffaba 100644 --- a/plugins/catalog/api-report.md +++ b/plugins/catalog/api-report.md @@ -11,14 +11,14 @@ import { ApiHolder } from '@backstage/core-plugin-api'; import { BackstagePlugin } from '@backstage/core-plugin-api'; import { CatalogApi } from '@backstage/catalog-client'; import { CatalogClient } from '@backstage/catalog-client'; -import { CatalogEntitiesRequest } from '@backstage/catalog-client'; -import { CatalogEntityAncestorsRequest } from '@backstage/catalog-client'; -import { CatalogEntityAncestorsResponse } from '@backstage/catalog-client'; -import { CatalogListResponse } from '@backstage/catalog-client'; import { CatalogRequestOptions } from '@backstage/catalog-client'; import { Entity } from '@backstage/catalog-model'; import { EntityName } from '@backstage/catalog-model'; import { ExternalRouteRef } from '@backstage/core-plugin-api'; +import { GetEntitiesRequest } from '@backstage/catalog-client'; +import { GetEntitiesResponse } from '@backstage/catalog-client'; +import { GetEntityAncestorsRequest } from '@backstage/catalog-client'; +import { GetEntityAncestorsResponse } from '@backstage/catalog-client'; import { IconComponent } from '@backstage/core-plugin-api'; import { IdentityApi } from '@backstage/core-plugin-api'; import { InfoCardVariants } from '@backstage/core-components'; @@ -76,14 +76,14 @@ export class CatalogClientWrapper implements CatalogApi { ): Promise; // (undocumented) getEntities( - request?: CatalogEntitiesRequest, + request?: GetEntitiesRequest, options?: CatalogRequestOptions, - ): Promise>; + ): Promise; // (undocumented) getEntityAncestors( - request: CatalogEntityAncestorsRequest, + request: GetEntityAncestorsRequest, options?: CatalogRequestOptions, - ): Promise; + ): Promise; // (undocumented) getEntityByName( compoundName: EntityName, diff --git a/plugins/catalog/src/CatalogClientWrapper.ts b/plugins/catalog/src/CatalogClientWrapper.ts index 939c4f095b..e34273c19f 100644 --- a/plugins/catalog/src/CatalogClientWrapper.ts +++ b/plugins/catalog/src/CatalogClientWrapper.ts @@ -20,11 +20,11 @@ import { AddLocationResponse, CatalogApi, CatalogClient, - CatalogEntitiesRequest, - CatalogListResponse, + GetEntitiesRequest, + GetEntitiesResponse, CatalogRequestOptions, - CatalogEntityAncestorsRequest, - CatalogEntityAncestorsResponse, + GetEntityAncestorsRequest, + GetEntityAncestorsResponse, } from '@backstage/catalog-client'; import { IdentityApi } from '@backstage/core-plugin-api'; @@ -58,9 +58,9 @@ export class CatalogClientWrapper implements CatalogApi { } async getEntities( - request?: CatalogEntitiesRequest, + request?: GetEntitiesRequest, options?: CatalogRequestOptions, - ): Promise> { + ): Promise { return await this.client.getEntities( request, await this.getCredentials(options), @@ -138,9 +138,9 @@ export class CatalogClientWrapper implements CatalogApi { } async getEntityAncestors( - request: CatalogEntityAncestorsRequest, + request: GetEntityAncestorsRequest, options?: CatalogRequestOptions, - ): Promise { + ): Promise { return await this.client.getEntityAncestors( request, await this.getCredentials(options), diff --git a/plugins/org/src/components/Cards/OwnershipCard/OwnershipCard.test.tsx b/plugins/org/src/components/Cards/OwnershipCard/OwnershipCard.test.tsx index 26a79dfaee..2030f4c100 100644 --- a/plugins/org/src/components/Cards/OwnershipCard/OwnershipCard.test.tsx +++ b/plugins/org/src/components/Cards/OwnershipCard/OwnershipCard.test.tsx @@ -15,8 +15,8 @@ */ import { - CatalogEntitiesRequest, - CatalogListResponse, + GetEntitiesRequest, + GetEntitiesResponse, } from '@backstage/catalog-client'; import { Entity, GroupEntity, UserEntity } from '@backstage/catalog-model'; import { @@ -110,15 +110,15 @@ const items = [ ] as Entity[]; const getEntitiesMock = ( - request?: CatalogEntitiesRequest, -): Promise> => { + request?: GetEntitiesRequest, +): Promise => { const filterKinds = !Array.isArray(request?.filter) && Array.isArray(request?.filter?.kind) ? request?.filter?.kind ?? [] : []; // we expect the request to be like { filter: { kind: ['API','System'], .... }. If changed in OwnerShipCard, let's change in also here return Promise.resolve({ items: items.filter(item => filterKinds.find(k => k === item.kind)), - } as CatalogListResponse); + } as GetEntitiesResponse); }; describe('OwnershipCard', () => { diff --git a/plugins/scaffolder/src/components/fields/EntityTagsPicker/EntityTagsPicker.tsx b/plugins/scaffolder/src/components/fields/EntityTagsPicker/EntityTagsPicker.tsx index b0577acfeb..bf566bd616 100644 --- a/plugins/scaffolder/src/components/fields/EntityTagsPicker/EntityTagsPicker.tsx +++ b/plugins/scaffolder/src/components/fields/EntityTagsPicker/EntityTagsPicker.tsx @@ -16,7 +16,7 @@ import React, { useState } from 'react'; import useAsync from 'react-use/lib/useAsync'; import useEffectOnce from 'react-use/lib/useEffectOnce'; -import { CatalogEntitiesRequest } from '@backstage/catalog-client'; +import { GetEntitiesRequest } from '@backstage/catalog-client'; import { Entity, makeValidator } from '@backstage/catalog-model'; import { useApi } from '@backstage/core-plugin-api'; import { catalogApiRef } from '@backstage/plugin-catalog-react'; @@ -40,7 +40,7 @@ export const EntityTagsPicker = ({ const kinds = uiSchema['ui:options']?.kinds as string[]; const { loading, value: existingTags } = useAsync(async () => { - const tagsRequest: CatalogEntitiesRequest = { fields: ['metadata.tags'] }; + const tagsRequest: GetEntitiesRequest = { fields: ['metadata.tags'] }; if (kinds) { tagsRequest.filter = { kind: kinds }; } diff --git a/plugins/tech-insights-backend/src/service/fact/factRetrievers/entityMetadataFactRetriever.test.ts b/plugins/tech-insights-backend/src/service/fact/factRetrievers/entityMetadataFactRetriever.test.ts index b99f6a1c02..a51ce0ab83 100644 --- a/plugins/tech-insights-backend/src/service/fact/factRetrievers/entityMetadataFactRetriever.test.ts +++ b/plugins/tech-insights-backend/src/service/fact/factRetrievers/entityMetadataFactRetriever.test.ts @@ -14,13 +14,13 @@ * limitations under the License. */ -import { Entity, RELATION_OWNED_BY } from '@backstage/catalog-model'; +import { RELATION_OWNED_BY } from '@backstage/catalog-model'; import { PluginEndpointDiscovery, getVoidLogger, } from '@backstage/backend-common'; import { ConfigReader } from '@backstage/config'; -import { CatalogListResponse } from '@backstage/catalog-client'; +import { GetEntitiesResponse } from '@backstage/catalog-client'; import { entityMetadataFactRetriever } from './entityMetadataFactRetriever'; const getEntitiesMock = jest.fn(); @@ -36,7 +36,7 @@ const discovery: jest.Mocked = { getExternalBaseUrl: jest.fn(), }; -const defaultEntityListResponse: CatalogListResponse = { +const defaultEntityListResponse: GetEntitiesResponse = { items: [ { apiVersion: 'backstage.io/v1beta1', diff --git a/plugins/tech-insights-backend/src/service/fact/factRetrievers/entityOwnershipFactRetriever.test.ts b/plugins/tech-insights-backend/src/service/fact/factRetrievers/entityOwnershipFactRetriever.test.ts index ea0801f17c..2108379f06 100644 --- a/plugins/tech-insights-backend/src/service/fact/factRetrievers/entityOwnershipFactRetriever.test.ts +++ b/plugins/tech-insights-backend/src/service/fact/factRetrievers/entityOwnershipFactRetriever.test.ts @@ -15,13 +15,13 @@ */ import { entityOwnershipFactRetriever } from './entityOwnershipFactRetriever'; -import { Entity, RELATION_OWNED_BY } from '@backstage/catalog-model'; +import { RELATION_OWNED_BY } from '@backstage/catalog-model'; import { PluginEndpointDiscovery, getVoidLogger, } from '@backstage/backend-common'; import { ConfigReader } from '@backstage/config'; -import { CatalogListResponse } from '@backstage/catalog-client'; +import { GetEntitiesResponse } from '@backstage/catalog-client'; const getEntitiesMock = jest.fn(); jest.mock('@backstage/catalog-client', () => { @@ -36,7 +36,7 @@ const discovery: jest.Mocked = { getExternalBaseUrl: jest.fn(), }; -const defaultEntityListResponse: CatalogListResponse = { +const defaultEntityListResponse: GetEntitiesResponse = { items: [ { apiVersion: 'backstage.io/v1beta1', diff --git a/plugins/tech-insights-backend/src/service/fact/factRetrievers/techdocsFactRetriever.test.ts b/plugins/tech-insights-backend/src/service/fact/factRetrievers/techdocsFactRetriever.test.ts index 6ed9b12523..a3604129b7 100644 --- a/plugins/tech-insights-backend/src/service/fact/factRetrievers/techdocsFactRetriever.test.ts +++ b/plugins/tech-insights-backend/src/service/fact/factRetrievers/techdocsFactRetriever.test.ts @@ -15,13 +15,13 @@ */ import { techdocsFactRetriever } from './techdocsFactRetriever'; -import { Entity, RELATION_OWNED_BY } from '@backstage/catalog-model'; +import { RELATION_OWNED_BY } from '@backstage/catalog-model'; import { PluginEndpointDiscovery, getVoidLogger, } from '@backstage/backend-common'; import { ConfigReader } from '@backstage/config'; -import { CatalogListResponse } from '@backstage/catalog-client'; +import { GetEntitiesResponse } from '@backstage/catalog-client'; const getEntitiesMock = jest.fn(); jest.mock('@backstage/catalog-client', () => { @@ -36,7 +36,7 @@ const discovery: jest.Mocked = { getExternalBaseUrl: jest.fn(), }; -const defaultEntityListResponse: CatalogListResponse = { +const defaultEntityListResponse: GetEntitiesResponse = { items: [ { apiVersion: 'backstage.io/v1beta1',