Export more types and functions for customization

Signed-off-by: ivgo <ivgo@spreadgroup.com>

.changeset/green-otters-wait.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-catalog-unprocessed-entities': patch
+---
+
+Export some types and API items. This allows people to call the API from different places with the ApiRef, as well
+as completely customize the client if required. Check the [README.md](../plugins/catalog-unprocessed-entities/README.md) to
+note what needs to be added in order to use the new `catalogUnprocessedEntitiesApiRef` exported function.

plugins/catalog-unprocessed-entities/README.md

@@ -40,6 +40,30 @@ import { CatalogUnprocessedEntitiesPage } from '@backstage/plugin-catalog-unproc
 />;
 ```
 
+## Customization
+
+If you want to use the provided endpoints in a different way, you can use the ApiRef doing the following:
+
+```typescript
+import { catalogUnprocessedEntitiesApiRef } from '@backstage/plugin-catalog-unprocessed-entities';
+import { useApi } from '@backstage/core-plugin-api';
+
+const catalogUnprocessedEntitiesApi = useApi(catalogUnprocessedEntitiesApiRef);
+```
+
+Note that you will need to add the API implementation to avoid your instance to crash due to "missing implementation for apiRef". To do so, add the following lines:
+
+```typescript
+// In packages/app/src/apis.ts
+import { catalogUnprocessedEntitiesPlugin } from '@backstage/plugin-catalog-unprocessed-entities';
+
+export const apis: AnyApiFactory[] = [
+  // ...other API implementations
+
+  ...catalogUnprocessedEntitiesPlugin.getApis(),
+];
+```
+
 ## Getting started
 
 Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/catalog-unprocessed-entities](http://localhost:3000/catalog-unprocessed-entities).

plugins/catalog-unprocessed-entities/src/api/index.ts

@@ -32,20 +32,43 @@ export const catalogUnprocessedEntitiesApiRef =
   });
 
 /**
- * API client for the Catalog Unprocessed Entities plugin
+ * Response expected by the {@link CatalogUnprocessedEntitiesApi}
  *
  * @public
  */
-export class CatalogUnprocessedEntitiesApi {
-  url: string = '';
+export type CatalogUnprocessedEntitiesApiResponse = {
+  entities: UnprocessedEntity[];
+};
 
+/**
+ * Interface for the CatalogUnprocessedEntitiesApi.
+ *
+ * @public
+ */
+export interface CatalogUnprocessedEntitiesApi {
+  /**
+   * Returns a list of entities with state 'pending'
+   */
+  pending(): Promise<CatalogUnprocessedEntitiesApiResponse>;
+  /**
+   * Returns a list of entities with state 'failed'
+   */
+  failed(): Promise<CatalogUnprocessedEntitiesApiResponse>;
+}
+
+/**
+ * Default API implementation for the Catalog Unprocessed Entities plugin
+ *
+ * @public
+ */
+export class CatalogUnprocessedEntitiesClient
+  implements CatalogUnprocessedEntitiesApi
+{
   constructor(public discovery: DiscoveryApi, public fetchApi: FetchApi) {}
 
   private async fetch<T>(path: string, init?: RequestInit): Promise<T> {
-    if (!this.url) {
-      this.url = await this.discovery.getBaseUrl('catalog');
-    }
-    const resp = await this.fetchApi.fetch(`${this.url}/${path}`, init);
+    const url = await this.discovery.getBaseUrl('catalog');
+    const resp = await this.fetchApi.fetch(`${url}/${path}`, init);
     if (!resp.ok) {
       throw await ResponseError.fromResponse(resp);
     }
@@ -53,11 +76,11 @@ export class CatalogUnprocessedEntitiesApi {
     return await resp.json();
   }
 
-  async pending(): Promise<{ entities: UnprocessedEntity[] }> {
+  async pending(): Promise<CatalogUnprocessedEntitiesApiResponse> {
     return await this.fetch('entities/unprocessed/pending');
   }
 
-  async failed(): Promise<{ entities: UnprocessedEntity[] }> {
+  async failed(): Promise<CatalogUnprocessedEntitiesApiResponse> {
     return await this.fetch('entities/unprocessed/failed');
   }
 }

plugins/catalog-unprocessed-entities/src/index.ts

@@ -18,3 +18,13 @@ export {
   CatalogUnprocessedEntitiesPage,
 } from './plugin';
 export { UnprocessedEntitiesContent } from './components/UnprocessedEntities';
+export {
+  type CatalogUnprocessedEntitiesApiResponse,
+  type CatalogUnprocessedEntitiesApi,
+  catalogUnprocessedEntitiesApiRef,
+} from './api';
+export type {
+  UnprocessedEntity,
+  UnprocessedEntityCache,
+  UnprocessedEntityError,
+} from './types';

plugins/catalog-unprocessed-entities/src/plugin.ts

@@ -23,7 +23,7 @@ import {
 
 import { rootRouteRef } from './routes';
 import {
-  CatalogUnprocessedEntitiesApi,
+  CatalogUnprocessedEntitiesClient,
   catalogUnprocessedEntitiesApiRef,
 } from './api';
 
@@ -42,7 +42,7 @@ export const catalogUnprocessedEntitiesPlugin = createPlugin({
       api: catalogUnprocessedEntitiesApiRef,
       deps: { discoveryApi: discoveryApiRef, fetchApi: fetchApiRef },
       factory: ({ discoveryApi, fetchApi }) =>
-        new CatalogUnprocessedEntitiesApi(discoveryApi, fetchApi),
+        new CatalogUnprocessedEntitiesClient(discoveryApi, fetchApi),
     }),
   ],
 });

plugins/catalog-unprocessed-entities/src/types.ts

@@ -15,6 +15,10 @@
  */
 import { Entity } from '@backstage/catalog-model';
 
+/**
+ * Unprocessed entity data stored in the database.
+ * @public
+ */
 export type UnprocessedEntity = {
   entity_id: string;
   entity_ref: string;
@@ -29,11 +33,19 @@ export type UnprocessedEntity = {
   location_key?: string;
 };
 
+/**
+ * Unprocessed entity cache stored in the database.
+ * @public
+ */
 export type UnprocessedEntityCache = {
   ttl: number;
   cache: object;
 };
 
+/**
+ * Unprocessed entity error information stored in the database.
+ * @public
+ */
 export type UnprocessedEntityError = {
   name: string;
   message: string;