diff --git a/.changeset/rotten-needles-relax.md b/.changeset/rotten-needles-relax.md index 403e06146a..a34d0a7cb4 100644 --- a/.changeset/rotten-needles-relax.md +++ b/.changeset/rotten-needles-relax.md @@ -2,4 +2,4 @@ '@backstage/plugin-catalog-node': minor --- -The `catalogServiceRef` now have its own accompanying `CatalogService` interface, which also supports passing Backstage `credentials` objects in addition to tokens. +The `catalogServiceRef` now have its own accompanying `CatalogService` interface, which also supports passing Backstage `credentials` objects in addition to tokens. In addition, it has been promoted from the `/alpha` export and is now available from the main `@backstage/plugin-catalog-node` entry point. diff --git a/docs/backend-system/building-plugins-and-modules/08-migrating.md b/docs/backend-system/building-plugins-and-modules/08-migrating.md index 8b2ea17de8..ea86854b18 100644 --- a/docs/backend-system/building-plugins-and-modules/08-migrating.md +++ b/docs/backend-system/building-plugins-and-modules/08-migrating.md @@ -39,7 +39,7 @@ import { coreServices, createBackendPlugin, } from '@backstage/backend-plugin-api'; -import { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha'; +import { catalogServiceRef } from '@backstage/plugin-catalog-node'; import { Router } from 'express'; import { KubernetesBuilder } from './KubernetesBuilder'; diff --git a/plugins/catalog-node/report-alpha.api.md b/plugins/catalog-node/report-alpha.api.md index de5bea0811..044bc14de3 100644 --- a/plugins/catalog-node/report-alpha.api.md +++ b/plugins/catalog-node/report-alpha.api.md @@ -3,37 +3,20 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts -import { AddLocationRequest } from '@backstage/catalog-client'; -import { AddLocationResponse } from '@backstage/catalog-client'; -import { BackstageCredentials } from '@backstage/backend-plugin-api'; import { CatalogApi } from '@backstage/catalog-client'; import { CatalogProcessor } from '@backstage/plugin-catalog-node'; import { CatalogProcessorParser } from '@backstage/plugin-catalog-node'; -import { CatalogRequestOptions } from '@backstage/catalog-client'; -import { CompoundEntityRef } from '@backstage/catalog-model'; import { EntitiesSearchFilter } from '@backstage/plugin-catalog-node'; import { Entity } from '@backstage/catalog-model'; import { EntityProvider } from '@backstage/plugin-catalog-node'; import { ExtensionPoint } from '@backstage/backend-plugin-api'; -import { GetEntitiesByRefsRequest } from '@backstage/catalog-client'; -import { GetEntitiesByRefsResponse } from '@backstage/catalog-client'; -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 { GetEntityFacetsRequest } from '@backstage/catalog-client'; -import { GetEntityFacetsResponse } from '@backstage/catalog-client'; -import { Location as Location_2 } from '@backstage/catalog-client'; import { LocationAnalyzer } from '@backstage/plugin-catalog-node'; import { Permission } from '@backstage/plugin-permission-common'; import { PermissionRule } from '@backstage/plugin-permission-node'; import { PermissionRuleParams } from '@backstage/plugin-permission-common'; import { PlaceholderResolver } from '@backstage/plugin-catalog-node'; -import { QueryEntitiesRequest } from '@backstage/catalog-client'; -import { QueryEntitiesResponse } from '@backstage/catalog-client'; import { ScmLocationAnalyzer } from '@backstage/plugin-catalog-node'; import { ServiceRef } from '@backstage/backend-plugin-api'; -import { ValidateEntityResponse } from '@backstage/catalog-client'; import { Validators } from '@backstage/catalog-model'; // @alpha (undocumented) @@ -112,14 +95,8 @@ export interface CatalogProcessingExtensionPoint { // @alpha (undocumented) export const catalogProcessingExtensionPoint: ExtensionPoint; -// Warning: (ae-forgotten-export) The symbol "CatalogService" needs to be exported by the entry point alpha.d.ts -// -// @alpha -export const catalogServiceRef: ServiceRef< - CatalogService, - 'plugin', - 'singleton' ->; +// @alpha @deprecated (undocumented) +export const catalogServiceRef: ServiceRef; // (No @packageDocumentation comment for this package) ``` diff --git a/plugins/catalog-node/report.api.md b/plugins/catalog-node/report.api.md index 43209aa862..f063e7944b 100644 --- a/plugins/catalog-node/report.api.md +++ b/plugins/catalog-node/report.api.md @@ -5,15 +5,32 @@ ```ts /// +import { AddLocationRequest } from '@backstage/catalog-client'; +import { AddLocationResponse } from '@backstage/catalog-client'; import { AnalyzeLocationExistingEntity } from '@backstage/plugin-catalog-common'; import { AnalyzeLocationRequest } from '@backstage/plugin-catalog-common'; import { AnalyzeLocationResponse } from '@backstage/plugin-catalog-common'; import { BackstageCredentials } from '@backstage/backend-plugin-api'; +import { CatalogApi } from '@backstage/catalog-client'; +import { CatalogRequestOptions } from '@backstage/catalog-client'; import { CompoundEntityRef } from '@backstage/catalog-model'; import { Entity } from '@backstage/catalog-model'; +import { GetEntitiesByRefsRequest } from '@backstage/catalog-client'; +import { GetEntitiesByRefsResponse } from '@backstage/catalog-client'; +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 { GetEntityFacetsRequest } from '@backstage/catalog-client'; +import { GetEntityFacetsResponse } from '@backstage/catalog-client'; import { JsonValue } from '@backstage/types'; +import { Location as Location_2 } from '@backstage/catalog-client'; import { LocationEntityV1alpha1 } from '@backstage/catalog-model'; import { LocationSpec as LocationSpec_2 } from '@backstage/plugin-catalog-common'; +import { QueryEntitiesRequest } from '@backstage/catalog-client'; +import { QueryEntitiesResponse } from '@backstage/catalog-client'; +import { ServiceRef } from '@backstage/backend-plugin-api'; +import { ValidateEntityResponse } from '@backstage/catalog-client'; // @public (undocumented) export type AnalyzeOptions = { @@ -102,6 +119,94 @@ export type CatalogProcessorResult = | CatalogProcessorErrorResult | CatalogProcessorRefreshKeysResult; +// @public +export interface CatalogService extends CatalogApi { + // (undocumented) + addLocation( + location: AddLocationRequest, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + getEntities( + request?: GetEntitiesRequest, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + getEntitiesByRefs( + request: GetEntitiesByRefsRequest, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + getEntityAncestors( + request: GetEntityAncestorsRequest, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + getEntityByRef( + entityRef: string | CompoundEntityRef, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + getEntityFacets( + request: GetEntityFacetsRequest, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + getLocationByEntity( + entityRef: string | CompoundEntityRef, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + getLocationById( + id: string, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + getLocationByRef( + locationRef: string, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + queryEntities( + request?: QueryEntitiesRequest, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + refreshEntity( + entityRef: string, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + removeEntityByUid( + uid: string, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + removeLocationById( + id: string, + options?: CatalogServiceRequestOptions, + ): Promise; + // (undocumented) + validateEntity( + entity: Entity, + locationRef: string, + options?: CatalogServiceRequestOptions, + ): Promise; +} + +// @public +export const catalogServiceRef: ServiceRef< + CatalogService, + 'plugin', + 'singleton' +>; + +// @public (undocumented) +export interface CatalogServiceRequestOptions extends CatalogRequestOptions { + // (undocumented) + credentials?: BackstageCredentials; +} + // @public export type DeferredEntity = { entity: Entity; diff --git a/plugins/catalog-node/src/alpha.ts b/plugins/catalog-node/src/alpha.ts index b75ec48a7f..159b642e52 100644 --- a/plugins/catalog-node/src/alpha.ts +++ b/plugins/catalog-node/src/alpha.ts @@ -14,7 +14,20 @@ * limitations under the License. */ -export { catalogServiceRef } from './catalogService'; +import { ServiceRef } from '@backstage/backend-plugin-api'; +import { catalogServiceRef as _catalogServiceRef } from './catalogService'; +import { CatalogApi } from '@backstage/catalog-client'; + +/** + * @alpha + * @deprecated Use {@link @backstage/plugin-catalog-node#catalogServiceRef} instead + */ +export const catalogServiceRef = _catalogServiceRef as ServiceRef< + CatalogApi, + 'plugin', + 'singleton' +>; + export type { CatalogLocationsExtensionPoint } from './extensions'; export { catalogLocationsExtensionPoint } from './extensions'; export type { CatalogProcessingExtensionPoint } from './extensions'; diff --git a/plugins/catalog-node/src/catalogService.ts b/plugins/catalog-node/src/catalogService.ts index a018483ca4..8b81bc68fd 100644 --- a/plugins/catalog-node/src/catalogService.ts +++ b/plugins/catalog-node/src/catalogService.ts @@ -51,7 +51,7 @@ export interface CatalogServiceRequestOptions extends CatalogRequestOptions { } /** - * A version of the {@link CatalogApi | CatalogApi} that + * A version of the {@link @backstage/catalog-client#CatalogApi | CatalogApi} that * accepts backend credentials in addition to a token. * * @public diff --git a/plugins/catalog-node/src/index.ts b/plugins/catalog-node/src/index.ts index 2dd8b5fd5a..9a95b708ba 100644 --- a/plugins/catalog-node/src/index.ts +++ b/plugins/catalog-node/src/index.ts @@ -23,3 +23,8 @@ export * from './api'; export * from './conversion'; export * from './processing'; +export { + catalogServiceRef, + type CatalogService, + type CatalogServiceRequestOptions, +} from './catalogService';