catalog-node: promote catalogServiceRef to main entry point

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.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.

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';
 

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<CatalogProcessingExtensionPoint>;
 
-// 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<CatalogApi, 'plugin', 'singleton'>;
 
 // (No @packageDocumentation comment for this package)
 ```

plugins/catalog-node/report.api.md

@@ -5,15 +5,32 @@
 ```ts
 /// <reference types="node" />
 
+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<AddLocationResponse>;
+  // (undocumented)
+  getEntities(
+    request?: GetEntitiesRequest,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<GetEntitiesResponse>;
+  // (undocumented)
+  getEntitiesByRefs(
+    request: GetEntitiesByRefsRequest,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<GetEntitiesByRefsResponse>;
+  // (undocumented)
+  getEntityAncestors(
+    request: GetEntityAncestorsRequest,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<GetEntityAncestorsResponse>;
+  // (undocumented)
+  getEntityByRef(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<Entity | undefined>;
+  // (undocumented)
+  getEntityFacets(
+    request: GetEntityFacetsRequest,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<GetEntityFacetsResponse>;
+  // (undocumented)
+  getLocationByEntity(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<Location_2 | undefined>;
+  // (undocumented)
+  getLocationById(
+    id: string,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<Location_2 | undefined>;
+  // (undocumented)
+  getLocationByRef(
+    locationRef: string,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<Location_2 | undefined>;
+  // (undocumented)
+  queryEntities(
+    request?: QueryEntitiesRequest,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<QueryEntitiesResponse>;
+  // (undocumented)
+  refreshEntity(
+    entityRef: string,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<void>;
+  // (undocumented)
+  removeEntityByUid(
+    uid: string,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<void>;
+  // (undocumented)
+  removeLocationById(
+    id: string,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<void>;
+  // (undocumented)
+  validateEntity(
+    entity: Entity,
+    locationRef: string,
+    options?: CatalogServiceRequestOptions,
+  ): Promise<ValidateEntityResponse>;
+}
+
+// @public
+export const catalogServiceRef: ServiceRef<
+  CatalogService,
+  'plugin',
+  'singleton'
+>;
+
+// @public (undocumented)
+export interface CatalogServiceRequestOptions extends CatalogRequestOptions {
+  // (undocumented)
+  credentials?: BackstageCredentials;
+}
+
 // @public
 export type DeferredEntity = {
   entity: Entity;

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';

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

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';