@backstage/catalog-client 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @backstage/catalog-client
 
+## 0.7.2
+
+### Patch Changes
+
+- ed09ad8093: Updated usage of the `LocationSpec` type from `@backstage/catalog-model`, which is deprecated.
+- 46dee04eba: Deprecated `AddLocationRequest.presence`, as it is already being ignored.
+- 6e1cbc12a6: Added `CatalogApi.getEntityFacets`. Marking this as a breaking change since it
+  is a non-optional addition to the API and depends on the backend being in place.
+  If you are mocking this interface in your tests, you will need to add an extra
+  `getEntityFacets: jest.fn()` or similar to that interface.
+- Updated dependencies
+  - @backstage/catalog-model@0.11.0
+
 ## 0.7.1
 
 ### Patch Changes

package/dist/index.cjs.js

@@ -26,9 +26,8 @@ class CatalogClient {
   }
   async getEntities(request, options) {
     const { filter = [], fields = [], offset, limit, after } = request != null ? request : {};
-    const filterItems = [filter].flat();
     const params = [];
-    for (const filterItem of filterItems) {
+    for (const filterItem of [filter].flat()) {
       const filterParts = [];
       for (const [key, value] of Object.entries(filterItem)) {
         for (const v of [value].flat()) {
@@ -91,6 +90,30 @@ class CatalogClient {
       throw new Error(await response.text());
     }
   }
+  async getEntityFacets(request, options) {
+    const { filter = [], facets } = request;
+    const params = [];
+    for (const filterItem of [filter].flat()) {
+      const filterParts = [];
+      for (const [key, value] of Object.entries(filterItem)) {
+        for (const v of [value].flat()) {
+          if (v === CATALOG_FILTER_EXISTS) {
+            filterParts.push(encodeURIComponent(key));
+          } else if (typeof v === "string") {
+            filterParts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
+          }
+        }
+      }
+      if (filterParts.length) {
+        params.push(`filter=${filterParts.join(",")}`);
+      }
+    }
+    for (const facet of facets) {
+      params.push(`facet=${encodeURIComponent(facet)}`);
+    }
+    const query = params.length ? `?${params.join("&")}` : "";
+    return await this.requestOptional("GET", `/entity-facets${query}`, options);
+  }
   async addLocation({ type = "url", target, dryRun, presence }, options) {
     const response = await this.fetchApi.fetch(`${await this.discoveryApi.getBaseUrl("catalog")}/locations${dryRun ? "?dryRun=true" : ""}`, {
       headers: {

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":["../src/types/api.ts","../src/CatalogClient.ts","../src/types/status.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity, EntityName, LocationSpec } from '@backstage/catalog-model';\n\n/**\n * This symbol can be used in place of a value when passed to filters in e.g.\n * {@link CatalogClient.getEntities}, to signify that you want to filter on the\n * presence of that key no matter what its value is.\n *\n * @public\n */\nexport const CATALOG_FILTER_EXISTS = Symbol.for(\n  // Random UUID to ensure no collisions\n  'CATALOG_FILTER_EXISTS_0e15b590c0b343a2bae3e787e84c2111',\n);\n\n/**\n * The request type for {@link CatalogClient.getEntities}.\n *\n * @public\n */\nexport interface GetEntitiesRequest {\n  /**\n   * If given, return only entities that match the given patterns.\n   *\n   * @remarks\n   *\n   * If multiple filter sets are given as an array, then there is effectively an\n   * OR between each filter set.\n   *\n   * Within one filter set, there is effectively an AND between the various\n   * keys.\n   *\n   * Within one key, if there are more than one value, then there is effectively\n   * an OR between them.\n   *\n   * Example: For an input of\n   *\n   * ```\n   * [\n   *   { kind: ['API', 'Component'] },\n   *   { 'metadata.name': 'a', 'metadata.namespace': 'b' }\n   * ]\n   * ```\n   *\n   * This effectively means\n   *\n   * ```\n   * (kind = EITHER 'API' OR 'Component')\n   * OR\n   * (metadata.name = 'a' AND metadata.namespace = 'b' )\n   * ```\n   *\n   * Each key is a dot separated path in each object.\n   *\n   * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`\n   * (exported from this package), which means that you assert on the existence\n   * of that key, no matter what its value is.\n   */\n  filter?:\n    | Record<string, string | symbol | (string | symbol)[]>[]\n    | Record<string, string | symbol | (string | symbol)[]>\n    | undefined;\n  /**\n   * If given, return only the parts of each entity that match those dot\n   * separated paths in each object.\n   *\n   * @remarks\n   *\n   * Example: For an input of `['kind', 'metadata.annotations']`, then response\n   * objects will be shaped like\n   *\n   * ```\n   * {\n   *   \"kind\": \"Component\",\n   *   \"metadata\": {\n   *     \"annotations\": {\n   *       \"foo\": \"bar\"\n   *     }\n   *   }\n   * }\n   * ```\n   */\n  fields?: string[] | undefined;\n  /**\n   * If given, skips over the first N items in the result set.\n   */\n  offset?: number;\n  /**\n   * If given, returns at most N items from the result set.\n   */\n  limit?: number;\n  /**\n   * If given, skips over all items before that cursor as returned by a previous\n   * request.\n   */\n  after?: string;\n}\n\n/**\n * The response type for {@link CatalogClient.getEntities}.\n *\n * @public\n */\nexport interface GetEntitiesResponse {\n  items: Entity[];\n}\n\n/**\n * The request type for {@link CatalogClient.getEntityAncestors}.\n *\n * @public\n */\nexport interface GetEntityAncestorsRequest {\n  entityRef: string;\n}\n\n/**\n * The response type for {@link CatalogClient.getEntityAncestors}.\n *\n * @public\n */\nexport interface GetEntityAncestorsResponse {\n  rootEntityRef: string;\n  items: Array<{\n    entity: Entity;\n    parentEntityRefs: string[];\n  }>;\n}\n\n/**\n * Options you can pass into a catalog request for additional information.\n *\n * @public\n */\nexport interface CatalogRequestOptions {\n  token?: string;\n}\n\n/**\n * Entity location for a specific entity.\n *\n * @public\n */\nexport type Location = {\n  id: string;\n} & LocationSpec;\n\n/**\n * The request type for {@link CatalogClient.addLocation}.\n *\n * @public\n */\nexport type AddLocationRequest = {\n  type?: string;\n  target: string;\n  dryRun?: boolean;\n  presence?: 'optional' | 'required';\n};\n\n/**\n * The response type for {@link CatalogClient.addLocation}.\n *\n * @public\n */\nexport type AddLocationResponse = {\n  location: Location;\n  entities: Entity[];\n  // Only set in dryRun mode.\n  exists?: boolean;\n};\n\n/**\n * A client for interacting with the Backstage software catalog through its API.\n *\n * @public\n */\nexport interface CatalogApi {\n  /**\n   * Lists catalog entities.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntities(\n    request?: GetEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntitiesResponse>;\n\n  /**\n   * Gets entity ancestor information, i.e. the hierarchy of parent entities\n   * whose processing resulted in a given entity appearing in the catalog.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntityAncestors(\n    request: GetEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityAncestorsResponse>;\n\n  /**\n   * Gets a single entity from the catalog by its ref (kind, namespace, name)\n   * triplet.\n   *\n   * @param name - A complete entity ref\n   * @param options - Additional options\n   */\n  getEntityByName(\n    name: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined>;\n\n  /**\n   * Removes a single entity from the catalog by entity UID.\n   *\n   * @param uid - An entity UID\n   * @param options - Additional options\n   */\n  removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  /**\n   * Refreshes (marks for reprocessing) an entity in the catalog.\n   *\n   * @param entityRef - An entity ref on string form (e.g.\n   *        'component/default:my-component')\n   * @param options - Additional options\n   */\n  refreshEntity(\n    entityRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  // Locations\n\n  /**\n   * Gets a registered location by its ID.\n   *\n   * @param id - A location ID\n   * @param options - Additional options\n   */\n  getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n\n  /**\n   * Gets a registered location by its ref.\n   *\n   * @param locationRef - A location ref, e.g. \"url:https://github.com/...\"\n   * @param options - Additional options\n   */\n  getLocationByRef(\n    locationRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n\n  /**\n   * Registers a new location.\n   *\n   * @param location - Request parameters\n   * @param options - Additional options\n   */\n  addLocation(\n    location: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse>;\n\n  /**\n   * Removes a registered Location by its ID.\n   *\n   * @param id - A location ID\n   * @param options - Additional options\n   */\n  removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n}\n","/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  ANNOTATION_LOCATION,\n  ANNOTATION_ORIGIN_LOCATION,\n  Entity,\n  EntityName,\n  parseEntityRef,\n  stringifyEntityRef,\n  stringifyLocationRef,\n} from '@backstage/catalog-model';\nimport { ResponseError } from '@backstage/errors';\nimport crossFetch from 'cross-fetch';\nimport {\n  CATALOG_FILTER_EXISTS,\n  AddLocationRequest,\n  AddLocationResponse,\n  CatalogApi,\n  GetEntitiesRequest,\n  GetEntitiesResponse,\n  CatalogRequestOptions,\n  GetEntityAncestorsRequest,\n  GetEntityAncestorsResponse,\n  Location,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\nimport { FetchApi } from './types/fetch';\n\n/**\n * A frontend and backend compatible client for communicating with the Backstage\n * software catalog.\n *\n * @public\n */\nexport class CatalogClient implements CatalogApi {\n  private readonly discoveryApi: DiscoveryApi;\n  private readonly fetchApi: FetchApi;\n\n  constructor(options: {\n    discoveryApi: { getBaseUrl(pluginId: string): Promise<string> };\n    fetchApi?: { fetch: typeof fetch };\n  }) {\n    this.discoveryApi = options.discoveryApi;\n    this.fetchApi = options.fetchApi || { fetch: crossFetch };\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityAncestors}\n   */\n  async getEntityAncestors(\n    request: GetEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityAncestorsResponse> {\n    const { kind, namespace, name } = parseEntityRef(request.entityRef);\n    return await this.requestRequired(\n      'GET',\n      `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n        namespace,\n      )}/${encodeURIComponent(name)}/ancestry`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getLocationById}\n   */\n  async getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    return await this.requestOptional(\n      'GET',\n      `/locations/${encodeURIComponent(id)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntities}\n   */\n  async getEntities(\n    request?: GetEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntitiesResponse> {\n    const { filter = [], fields = [], offset, limit, after } = request ?? {};\n    const filterItems = [filter].flat();\n    const params: string[] = [];\n\n    // filter param can occur multiple times, for example\n    // /api/catalog/entities?filter=metadata.name=wayback-search,kind=component&filter=metadata.name=www-artist,kind=component'\n    // the \"outer array\" defined by `filter` occurrences corresponds to \"anyOf\" filters\n    // the \"inner array\" defined within a `filter` param corresponds to \"allOf\" filters\n    for (const filterItem of filterItems) {\n      const filterParts: string[] = [];\n      for (const [key, value] of Object.entries(filterItem)) {\n        for (const v of [value].flat()) {\n          if (v === CATALOG_FILTER_EXISTS) {\n            filterParts.push(encodeURIComponent(key));\n          } else if (typeof v === 'string') {\n            filterParts.push(\n              `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,\n            );\n          }\n        }\n      }\n\n      if (filterParts.length) {\n        params.push(`filter=${filterParts.join(',')}`);\n      }\n    }\n\n    if (fields.length) {\n      params.push(`fields=${fields.map(encodeURIComponent).join(',')}`);\n    }\n\n    if (offset !== undefined) {\n      params.push(`offset=${offset}`);\n    }\n    if (limit !== undefined) {\n      params.push(`limit=${limit}`);\n    }\n    if (after !== undefined) {\n      params.push(`after=${encodeURIComponent(after)}`);\n    }\n\n    const query = params.length ? `?${params.join('&')}` : '';\n    const entities: Entity[] = await this.requestRequired(\n      'GET',\n      `/entities${query}`,\n      options,\n    );\n\n    const refCompare = (a: Entity, b: Entity) => {\n      // in case field filtering is used, these fields might not be part of the response\n      if (\n        a.metadata?.name === undefined ||\n        a.kind === undefined ||\n        b.metadata?.name === undefined ||\n        b.kind === undefined\n      ) {\n        return 0;\n      }\n\n      const aRef = stringifyEntityRef(a);\n      const bRef = stringifyEntityRef(b);\n      if (aRef < bRef) {\n        return -1;\n      }\n      if (aRef > bRef) {\n        return 1;\n      }\n      return 0;\n    };\n\n    return { items: entities.sort(refCompare) };\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityByName}\n   */\n  async getEntityByName(\n    compoundName: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined> {\n    const { kind, namespace = 'default', name } = compoundName;\n    return this.requestOptional(\n      'GET',\n      `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n        namespace,\n      )}/${encodeURIComponent(name)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.refreshEntity}\n   */\n  async refreshEntity(entityRef: string, options?: CatalogRequestOptions) {\n    const response = await this.fetchApi.fetch(\n      `${await this.discoveryApi.getBaseUrl('catalog')}/refresh`,\n      {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n        },\n        method: 'POST',\n        body: JSON.stringify({ entityRef }),\n      },\n    );\n\n    if (response.status !== 200) {\n      throw new Error(await response.text());\n    }\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.addLocation}\n   */\n  async addLocation(\n    { type = 'url', target, dryRun, presence }: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse> {\n    const response = await this.fetchApi.fetch(\n      `${await this.discoveryApi.getBaseUrl('catalog')}/locations${\n        dryRun ? '?dryRun=true' : ''\n      }`,\n      {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n        },\n        method: 'POST',\n        body: JSON.stringify({ type, target, presence }),\n      },\n    );\n\n    if (response.status !== 201) {\n      throw new Error(await response.text());\n    }\n\n    const { location, entities, exists } = await response.json();\n\n    if (!location) {\n      throw new Error(`Location wasn't added: ${target}`);\n    }\n\n    return {\n      location,\n      entities,\n      exists,\n    };\n  }\n\n  /**\n   * @deprecated please use getLocationByRef instead\n   */\n  async getOriginLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound =\n      entity.metadata.annotations?.[ANNOTATION_ORIGIN_LOCATION];\n    if (!locationCompound) {\n      return undefined;\n    }\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationCompound === stringifyLocationRef(l));\n  }\n\n  /**\n   * @deprecated please use getLocationByRef instead\n   */\n  async getLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound = entity.metadata.annotations?.[ANNOTATION_LOCATION];\n    if (!locationCompound) {\n      return undefined;\n    }\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationCompound === stringifyLocationRef(l));\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getLocationByRef}\n   */\n  async getLocationByRef(\n    locationRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationRef === stringifyLocationRef(l));\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.removeLocationById}\n   */\n  async removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    await this.requestIgnored(\n      'DELETE',\n      `/locations/${encodeURIComponent(id)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.removeEntityByUid}\n   */\n  async removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    await this.requestIgnored(\n      'DELETE',\n      `/entities/by-uid/${encodeURIComponent(uid)}`,\n      options,\n    );\n  }\n\n  //\n  // Private methods\n  //\n\n  private async requestIgnored(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n  }\n\n  private async requestRequired(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<any> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n\n    return await response.json();\n  }\n\n  private async requestOptional(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<any | undefined> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      if (response.status === 404) {\n        return undefined;\n      }\n      throw await ResponseError.fromResponse(response);\n    }\n\n    return await response.json();\n  }\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The entity `status.items[].type` for the status of the processing engine in\n * regards to an entity.\n *\n * @public\n */\nexport const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =\n  'backstage.io/catalog-processing';\n"],"names":["crossFetch","parseEntityRef","stringifyEntityRef","ANNOTATION_ORIGIN_LOCATION","stringifyLocationRef","ANNOTATION_LOCATION","ResponseError"],"mappings":"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"}
+{"version":3,"file":"index.cjs.js","sources":["../src/types/api.ts","../src/CatalogClient.ts","../src/types/status.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity, EntityName } from '@backstage/catalog-model';\n\n/**\n * This symbol can be used in place of a value when passed to filters in e.g.\n * {@link CatalogClient.getEntities}, to signify that you want to filter on the\n * presence of that key no matter what its value is.\n *\n * @public\n */\nexport const CATALOG_FILTER_EXISTS = Symbol.for(\n  // Random UUID to ensure no collisions\n  'CATALOG_FILTER_EXISTS_0e15b590c0b343a2bae3e787e84c2111',\n);\n\n/**\n * The request type for {@link CatalogClient.getEntities}.\n *\n * @public\n */\nexport interface GetEntitiesRequest {\n  /**\n   * If given, return only entities that match the given patterns.\n   *\n   * @remarks\n   *\n   * If multiple filter sets are given as an array, then there is effectively an\n   * OR between each filter set.\n   *\n   * Within one filter set, there is effectively an AND between the various\n   * keys.\n   *\n   * Within one key, if there are more than one value, then there is effectively\n   * an OR between them.\n   *\n   * Example: For an input of\n   *\n   * ```\n   * [\n   *   { kind: ['API', 'Component'] },\n   *   { 'metadata.name': 'a', 'metadata.namespace': 'b' }\n   * ]\n   * ```\n   *\n   * This effectively means\n   *\n   * ```\n   * (kind = EITHER 'API' OR 'Component')\n   * OR\n   * (metadata.name = 'a' AND metadata.namespace = 'b' )\n   * ```\n   *\n   * Each key is a dot separated path in each object.\n   *\n   * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`\n   * (exported from this package), which means that you assert on the existence\n   * of that key, no matter what its value is.\n   */\n  filter?:\n    | Record<string, string | symbol | (string | symbol)[]>[]\n    | Record<string, string | symbol | (string | symbol)[]>\n    | undefined;\n  /**\n   * If given, return only the parts of each entity that match those dot\n   * separated paths in each object.\n   *\n   * @remarks\n   *\n   * Example: For an input of `['kind', 'metadata.annotations']`, then response\n   * objects will be shaped like\n   *\n   * ```\n   * {\n   *   \"kind\": \"Component\",\n   *   \"metadata\": {\n   *     \"annotations\": {\n   *       \"foo\": \"bar\"\n   *     }\n   *   }\n   * }\n   * ```\n   */\n  fields?: string[] | undefined;\n  /**\n   * If given, skips over the first N items in the result set.\n   */\n  offset?: number;\n  /**\n   * If given, returns at most N items from the result set.\n   */\n  limit?: number;\n  /**\n   * If given, skips over all items before that cursor as returned by a previous\n   * request.\n   */\n  after?: string;\n}\n\n/**\n * The response type for {@link CatalogClient.getEntities}.\n *\n * @public\n */\nexport interface GetEntitiesResponse {\n  items: Entity[];\n}\n\n/**\n * The request type for {@link CatalogClient.getEntityAncestors}.\n *\n * @public\n */\nexport interface GetEntityAncestorsRequest {\n  entityRef: string;\n}\n\n/**\n * The response type for {@link CatalogClient.getEntityAncestors}.\n *\n * @public\n */\nexport interface GetEntityAncestorsResponse {\n  rootEntityRef: string;\n  items: Array<{\n    entity: Entity;\n    parentEntityRefs: string[];\n  }>;\n}\n\n/**\n * The request type for {@link CatalogClient.getEntityFacets}.\n *\n * @public\n */\nexport interface GetEntityFacetsRequest {\n  /**\n   * If given, return only entities that match the given patterns.\n   *\n   * @remarks\n   *\n   * If multiple filter sets are given as an array, then there is effectively an\n   * OR between each filter set.\n   *\n   * Within one filter set, there is effectively an AND between the various\n   * keys.\n   *\n   * Within one key, if there are more than one value, then there is effectively\n   * an OR between them.\n   *\n   * Example: For an input of\n   *\n   * ```\n   * [\n   *   { kind: ['API', 'Component'] },\n   *   { 'metadata.name': 'a', 'metadata.namespace': 'b' }\n   * ]\n   * ```\n   *\n   * This effectively means\n   *\n   * ```\n   * (kind = EITHER 'API' OR 'Component')\n   * OR\n   * (metadata.name = 'a' AND metadata.namespace = 'b' )\n   * ```\n   *\n   * Each key is a dot separated path in each object.\n   *\n   * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`\n   * (exported from this package), which means that you assert on the existence\n   * of that key, no matter what its value is.\n   */\n  filter?:\n    | Record<string, string | symbol | (string | symbol)[]>[]\n    | Record<string, string | symbol | (string | symbol)[]>\n    | undefined;\n  /**\n   * Dot separated paths for the facets to extract from each entity.\n   *\n   * @remarks\n   *\n   * Example: For an input of `['kind', 'metadata.annotations.backstage.io/orphan']`, then the\n   * response will be shaped like\n   *\n   * ```\n   * {\n   *   \"facets\": {\n   *     \"kind\": [\n   *       { \"key\": \"Component\", \"count\": 22 },\n   *       { \"key\": \"API\", \"count\": 13 }\n   *     ],\n   *     \"metadata.annotations.backstage.io/orphan\": [\n   *       { \"key\": \"true\", \"count\": 2 }\n   *     ]\n   *   }\n   * }\n   * ```\n   */\n  facets: string[];\n}\n\n/**\n * The response type for {@link CatalogClient.getEntityFacets}.\n *\n * @public\n */\nexport interface GetEntityFacetsResponse {\n  /**\n   * The computed facets, one entry per facet in the request.\n   */\n  facets: Record<string, Array<{ value: string; count: number }>>;\n}\n\n/**\n * Options you can pass into a catalog request for additional information.\n *\n * @public\n */\nexport interface CatalogRequestOptions {\n  token?: string;\n}\n\n/**\n * Entity location for a specific entity.\n *\n * @public\n */\nexport type Location = {\n  id: string;\n  type: string;\n  target: string;\n  /** @deprecated This field is is ignored */\n  presence?: 'optional' | 'required';\n};\n\n/**\n * The request type for {@link CatalogClient.addLocation}.\n *\n * @public\n */\nexport type AddLocationRequest = {\n  type?: string;\n  target: string;\n  dryRun?: boolean;\n  /** @deprecated This field is is ignored */\n  presence?: 'optional' | 'required';\n};\n\n/**\n * The response type for {@link CatalogClient.addLocation}.\n *\n * @public\n */\nexport type AddLocationResponse = {\n  location: Location;\n  entities: Entity[];\n  // Only set in dryRun mode.\n  exists?: boolean;\n};\n\n/**\n * A client for interacting with the Backstage software catalog through its API.\n *\n * @public\n */\nexport interface CatalogApi {\n  /**\n   * Lists catalog entities.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntities(\n    request?: GetEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntitiesResponse>;\n\n  /**\n   * Gets entity ancestor information, i.e. the hierarchy of parent entities\n   * whose processing resulted in a given entity appearing in the catalog.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntityAncestors(\n    request: GetEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityAncestorsResponse>;\n\n  /**\n   * Gets a single entity from the catalog by its ref (kind, namespace, name)\n   * triplet.\n   *\n   * @param name - A complete entity ref\n   * @param options - Additional options\n   */\n  getEntityByName(\n    name: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined>;\n\n  /**\n   * Removes a single entity from the catalog by entity UID.\n   *\n   * @param uid - An entity UID\n   * @param options - Additional options\n   */\n  removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  /**\n   * Refreshes (marks for reprocessing) an entity in the catalog.\n   *\n   * @param entityRef - An entity ref on string form (e.g.\n   *        'component/default:my-component')\n   * @param options - Additional options\n   */\n  refreshEntity(\n    entityRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  /**\n   * Gets a summary of field facets of entities in the catalog.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntityFacets(\n    request: GetEntityFacetsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityFacetsResponse>;\n\n  // Locations\n\n  /**\n   * Gets a registered location by its ID.\n   *\n   * @param id - A location ID\n   * @param options - Additional options\n   */\n  getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n\n  /**\n   * Gets a registered location by its ref.\n   *\n   * @param locationRef - A location ref, e.g. \"url:https://github.com/...\"\n   * @param options - Additional options\n   */\n  getLocationByRef(\n    locationRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n\n  /**\n   * Registers a new location.\n   *\n   * @param location - Request parameters\n   * @param options - Additional options\n   */\n  addLocation(\n    location: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse>;\n\n  /**\n   * Removes a registered Location by its ID.\n   *\n   * @param id - A location ID\n   * @param options - Additional options\n   */\n  removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n}\n","/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  ANNOTATION_LOCATION,\n  ANNOTATION_ORIGIN_LOCATION,\n  Entity,\n  EntityName,\n  parseEntityRef,\n  stringifyEntityRef,\n  stringifyLocationRef,\n} from '@backstage/catalog-model';\nimport { ResponseError } from '@backstage/errors';\nimport crossFetch from 'cross-fetch';\nimport {\n  CATALOG_FILTER_EXISTS,\n  AddLocationRequest,\n  AddLocationResponse,\n  CatalogApi,\n  GetEntitiesRequest,\n  GetEntitiesResponse,\n  CatalogRequestOptions,\n  GetEntityAncestorsRequest,\n  GetEntityAncestorsResponse,\n  Location,\n  GetEntityFacetsRequest,\n  GetEntityFacetsResponse,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\nimport { FetchApi } from './types/fetch';\n\n/**\n * A frontend and backend compatible client for communicating with the Backstage\n * software catalog.\n *\n * @public\n */\nexport class CatalogClient implements CatalogApi {\n  private readonly discoveryApi: DiscoveryApi;\n  private readonly fetchApi: FetchApi;\n\n  constructor(options: {\n    discoveryApi: { getBaseUrl(pluginId: string): Promise<string> };\n    fetchApi?: { fetch: typeof fetch };\n  }) {\n    this.discoveryApi = options.discoveryApi;\n    this.fetchApi = options.fetchApi || { fetch: crossFetch };\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityAncestors}\n   */\n  async getEntityAncestors(\n    request: GetEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityAncestorsResponse> {\n    const { kind, namespace, name } = parseEntityRef(request.entityRef);\n    return await this.requestRequired(\n      'GET',\n      `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n        namespace,\n      )}/${encodeURIComponent(name)}/ancestry`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getLocationById}\n   */\n  async getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    return await this.requestOptional(\n      'GET',\n      `/locations/${encodeURIComponent(id)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntities}\n   */\n  async getEntities(\n    request?: GetEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntitiesResponse> {\n    const { filter = [], fields = [], offset, limit, after } = request ?? {};\n    const params: string[] = [];\n\n    // filter param can occur multiple times, for example\n    // /api/catalog/entities?filter=metadata.name=wayback-search,kind=component&filter=metadata.name=www-artist,kind=component'\n    // the \"outer array\" defined by `filter` occurrences corresponds to \"anyOf\" filters\n    // the \"inner array\" defined within a `filter` param corresponds to \"allOf\" filters\n    for (const filterItem of [filter].flat()) {\n      const filterParts: string[] = [];\n      for (const [key, value] of Object.entries(filterItem)) {\n        for (const v of [value].flat()) {\n          if (v === CATALOG_FILTER_EXISTS) {\n            filterParts.push(encodeURIComponent(key));\n          } else if (typeof v === 'string') {\n            filterParts.push(\n              `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,\n            );\n          }\n        }\n      }\n\n      if (filterParts.length) {\n        params.push(`filter=${filterParts.join(',')}`);\n      }\n    }\n\n    if (fields.length) {\n      params.push(`fields=${fields.map(encodeURIComponent).join(',')}`);\n    }\n\n    if (offset !== undefined) {\n      params.push(`offset=${offset}`);\n    }\n    if (limit !== undefined) {\n      params.push(`limit=${limit}`);\n    }\n    if (after !== undefined) {\n      params.push(`after=${encodeURIComponent(after)}`);\n    }\n\n    const query = params.length ? `?${params.join('&')}` : '';\n    const entities: Entity[] = await this.requestRequired(\n      'GET',\n      `/entities${query}`,\n      options,\n    );\n\n    const refCompare = (a: Entity, b: Entity) => {\n      // in case field filtering is used, these fields might not be part of the response\n      if (\n        a.metadata?.name === undefined ||\n        a.kind === undefined ||\n        b.metadata?.name === undefined ||\n        b.kind === undefined\n      ) {\n        return 0;\n      }\n\n      const aRef = stringifyEntityRef(a);\n      const bRef = stringifyEntityRef(b);\n      if (aRef < bRef) {\n        return -1;\n      }\n      if (aRef > bRef) {\n        return 1;\n      }\n      return 0;\n    };\n\n    return { items: entities.sort(refCompare) };\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityByName}\n   */\n  async getEntityByName(\n    compoundName: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined> {\n    const { kind, namespace = 'default', name } = compoundName;\n    return this.requestOptional(\n      'GET',\n      `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n        namespace,\n      )}/${encodeURIComponent(name)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.refreshEntity}\n   */\n  async refreshEntity(entityRef: string, options?: CatalogRequestOptions) {\n    const response = await this.fetchApi.fetch(\n      `${await this.discoveryApi.getBaseUrl('catalog')}/refresh`,\n      {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n        },\n        method: 'POST',\n        body: JSON.stringify({ entityRef }),\n      },\n    );\n\n    if (response.status !== 200) {\n      throw new Error(await response.text());\n    }\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityFacets}\n   */\n  async getEntityFacets(\n    request: GetEntityFacetsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityFacetsResponse> {\n    const { filter = [], facets } = request;\n    const params: string[] = [];\n\n    // filter param can occur multiple times, for example\n    // /api/catalog/entities?filter=metadata.name=wayback-search,kind=component&filter=metadata.name=www-artist,kind=component'\n    // the \"outer array\" defined by `filter` occurrences corresponds to \"anyOf\" filters\n    // the \"inner array\" defined within a `filter` param corresponds to \"allOf\" filters\n    for (const filterItem of [filter].flat()) {\n      const filterParts: string[] = [];\n      for (const [key, value] of Object.entries(filterItem)) {\n        for (const v of [value].flat()) {\n          if (v === CATALOG_FILTER_EXISTS) {\n            filterParts.push(encodeURIComponent(key));\n          } else if (typeof v === 'string') {\n            filterParts.push(\n              `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,\n            );\n          }\n        }\n      }\n\n      if (filterParts.length) {\n        params.push(`filter=${filterParts.join(',')}`);\n      }\n    }\n\n    for (const facet of facets) {\n      params.push(`facet=${encodeURIComponent(facet)}`);\n    }\n\n    const query = params.length ? `?${params.join('&')}` : '';\n    return await this.requestOptional('GET', `/entity-facets${query}`, options);\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.addLocation}\n   */\n  async addLocation(\n    { type = 'url', target, dryRun, presence }: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse> {\n    const response = await this.fetchApi.fetch(\n      `${await this.discoveryApi.getBaseUrl('catalog')}/locations${\n        dryRun ? '?dryRun=true' : ''\n      }`,\n      {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n        },\n        method: 'POST',\n        body: JSON.stringify({ type, target, presence }),\n      },\n    );\n\n    if (response.status !== 201) {\n      throw new Error(await response.text());\n    }\n\n    const { location, entities, exists } = await response.json();\n\n    if (!location) {\n      throw new Error(`Location wasn't added: ${target}`);\n    }\n\n    return {\n      location,\n      entities,\n      exists,\n    };\n  }\n\n  /**\n   * @deprecated please use getLocationByRef instead\n   */\n  async getOriginLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound =\n      entity.metadata.annotations?.[ANNOTATION_ORIGIN_LOCATION];\n    if (!locationCompound) {\n      return undefined;\n    }\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationCompound === stringifyLocationRef(l));\n  }\n\n  /**\n   * @deprecated please use getLocationByRef instead\n   */\n  async getLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound = entity.metadata.annotations?.[ANNOTATION_LOCATION];\n    if (!locationCompound) {\n      return undefined;\n    }\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationCompound === stringifyLocationRef(l));\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getLocationByRef}\n   */\n  async getLocationByRef(\n    locationRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationRef === stringifyLocationRef(l));\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.removeLocationById}\n   */\n  async removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    await this.requestIgnored(\n      'DELETE',\n      `/locations/${encodeURIComponent(id)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.removeEntityByUid}\n   */\n  async removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    await this.requestIgnored(\n      'DELETE',\n      `/entities/by-uid/${encodeURIComponent(uid)}`,\n      options,\n    );\n  }\n\n  //\n  // Private methods\n  //\n\n  private async requestIgnored(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n  }\n\n  private async requestRequired(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<any> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n\n    return await response.json();\n  }\n\n  private async requestOptional(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<any | undefined> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      if (response.status === 404) {\n        return undefined;\n      }\n      throw await ResponseError.fromResponse(response);\n    }\n\n    return await response.json();\n  }\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The entity `status.items[].type` for the status of the processing engine in\n * regards to an entity.\n *\n * @public\n */\nexport const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =\n  'backstage.io/catalog-processing';\n"],"names":["crossFetch","parseEntityRef","stringifyEntityRef","ANNOTATION_ORIGIN_LOCATION","stringifyLocationRef","ANNOTATION_LOCATION","ResponseError"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Entity, LocationSpec, EntityName } from '@backstage/catalog-model';
+import { Entity, EntityName } from '@backstage/catalog-model';
 
 /**
  * This symbol can be used in place of a value when passed to filters in e.g.
@@ -115,6 +115,88 @@ interface GetEntityAncestorsResponse {
         parentEntityRefs: string[];
     }>;
 }
+/**
+ * The request type for {@link CatalogClient.getEntityFacets}.
+ *
+ * @public
+ */
+interface GetEntityFacetsRequest {
+    /**
+     * If given, return only entities that match the given patterns.
+     *
+     * @remarks
+     *
+     * If multiple filter sets are given as an array, then there is effectively an
+     * OR between each filter set.
+     *
+     * Within one filter set, there is effectively an AND between the various
+     * keys.
+     *
+     * Within one key, if there are more than one value, then there is effectively
+     * an OR between them.
+     *
+     * Example: For an input of
+     *
+     * ```
+     * [
+     *   { kind: ['API', 'Component'] },
+     *   { 'metadata.name': 'a', 'metadata.namespace': 'b' }
+     * ]
+     * ```
+     *
+     * This effectively means
+     *
+     * ```
+     * (kind = EITHER 'API' OR 'Component')
+     * OR
+     * (metadata.name = 'a' AND metadata.namespace = 'b' )
+     * ```
+     *
+     * Each key is a dot separated path in each object.
+     *
+     * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`
+     * (exported from this package), which means that you assert on the existence
+     * of that key, no matter what its value is.
+     */
+    filter?: Record<string, string | symbol | (string | symbol)[]>[] | Record<string, string | symbol | (string | symbol)[]> | undefined;
+    /**
+     * Dot separated paths for the facets to extract from each entity.
+     *
+     * @remarks
+     *
+     * Example: For an input of `['kind', 'metadata.annotations.backstage.io/orphan']`, then the
+     * response will be shaped like
+     *
+     * ```
+     * {
+     *   "facets": {
+     *     "kind": [
+     *       { "key": "Component", "count": 22 },
+     *       { "key": "API", "count": 13 }
+     *     ],
+     *     "metadata.annotations.backstage.io/orphan": [
+     *       { "key": "true", "count": 2 }
+     *     ]
+     *   }
+     * }
+     * ```
+     */
+    facets: string[];
+}
+/**
+ * The response type for {@link CatalogClient.getEntityFacets}.
+ *
+ * @public
+ */
+interface GetEntityFacetsResponse {
+    /**
+     * The computed facets, one entry per facet in the request.
+     */
+    facets: Record<string, Array<{
+        value: string;
+        count: number;
+    }>>;
+}
 /**
  * Options you can pass into a catalog request for additional information.
  *
@@ -130,7 +212,11 @@ interface CatalogRequestOptions {
  */
 declare type Location = {
     id: string;
-} & LocationSpec;
+    type: string;
+    target: string;
+    /** @deprecated This field is is ignored */
+    presence?: 'optional' | 'required';
+};
 /**
  * The request type for {@link CatalogClient.addLocation}.
  *
@@ -140,6 +226,7 @@ declare type AddLocationRequest = {
     type?: string;
     target: string;
     dryRun?: boolean;
+    /** @deprecated This field is is ignored */
     presence?: 'optional' | 'required';
 };
 /**
@@ -196,6 +283,13 @@ interface CatalogApi {
      * @param options - Additional options
      */
     refreshEntity(entityRef: string, options?: CatalogRequestOptions): Promise<void>;
+    /**
+     * Gets a summary of field facets of entities in the catalog.
+     *
+     * @param request - Request parameters
+     * @param options - Additional options
+     */
+    getEntityFacets(request: GetEntityFacetsRequest, options?: CatalogRequestOptions): Promise<GetEntityFacetsResponse>;
     /**
      * Gets a registered location by its ID.
      *
@@ -263,6 +357,10 @@ declare class CatalogClient implements CatalogApi {
      * {@inheritdoc CatalogApi.refreshEntity}
      */
     refreshEntity(entityRef: string, options?: CatalogRequestOptions): Promise<void>;
+    /**
+     * {@inheritdoc CatalogApi.getEntityFacets}
+     */
+    getEntityFacets(request: GetEntityFacetsRequest, options?: CatalogRequestOptions): Promise<GetEntityFacetsResponse>;
     /**
      * {@inheritdoc CatalogApi.addLocation}
      */
@@ -292,14 +390,6 @@ declare class CatalogClient implements CatalogApi {
     private requestOptional;
 }
 
-/**
- * The entity `status.items[].type` for the status of the processing engine in
- * regards to an entity.
- *
- * @public
- */
-declare const ENTITY_STATUS_CATALOG_PROCESSING_TYPE = "backstage.io/catalog-processing";
-
 /**
  * @public
  * @deprecated use GetEntitiesRequest instead
@@ -321,4 +411,12 @@ declare type CatalogEntityAncestorsRequest = GetEntityAncestorsRequest;
  */
 declare type CatalogEntityAncestorsResponse = GetEntityAncestorsResponse;
 
-export { AddLocationRequest, AddLocationResponse, CATALOG_FILTER_EXISTS, CatalogApi, CatalogClient, CatalogEntitiesRequest, CatalogEntityAncestorsRequest, CatalogEntityAncestorsResponse, CatalogListResponse, CatalogRequestOptions, ENTITY_STATUS_CATALOG_PROCESSING_TYPE, GetEntitiesRequest, GetEntitiesResponse, GetEntityAncestorsRequest, GetEntityAncestorsResponse, Location };
+/**
+ * The entity `status.items[].type` for the status of the processing engine in
+ * regards to an entity.
+ *
+ * @public
+ */
+declare const ENTITY_STATUS_CATALOG_PROCESSING_TYPE = "backstage.io/catalog-processing";
+
+export { AddLocationRequest, AddLocationResponse, CATALOG_FILTER_EXISTS, CatalogApi, CatalogClient, CatalogEntitiesRequest, CatalogEntityAncestorsRequest, CatalogEntityAncestorsResponse, CatalogListResponse, CatalogRequestOptions, ENTITY_STATUS_CATALOG_PROCESSING_TYPE, GetEntitiesRequest, GetEntitiesResponse, GetEntityAncestorsRequest, GetEntityAncestorsResponse, GetEntityFacetsRequest, GetEntityFacetsResponse, Location };

package/dist/index.esm.js

@@ -18,9 +18,8 @@ class CatalogClient {
   }
   async getEntities(request, options) {
     const { filter = [], fields = [], offset, limit, after } = request != null ? request : {};
-    const filterItems = [filter].flat();
     const params = [];
-    for (const filterItem of filterItems) {
+    for (const filterItem of [filter].flat()) {
       const filterParts = [];
       for (const [key, value] of Object.entries(filterItem)) {
         for (const v of [value].flat()) {
@@ -83,6 +82,30 @@ class CatalogClient {
       throw new Error(await response.text());
     }
   }
+  async getEntityFacets(request, options) {
+    const { filter = [], facets } = request;
+    const params = [];
+    for (const filterItem of [filter].flat()) {
+      const filterParts = [];
+      for (const [key, value] of Object.entries(filterItem)) {
+        for (const v of [value].flat()) {
+          if (v === CATALOG_FILTER_EXISTS) {
+            filterParts.push(encodeURIComponent(key));
+          } else if (typeof v === "string") {
+            filterParts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
+          }
+        }
+      }
+      if (filterParts.length) {
+        params.push(`filter=${filterParts.join(",")}`);
+      }
+    }
+    for (const facet of facets) {
+      params.push(`facet=${encodeURIComponent(facet)}`);
+    }
+    const query = params.length ? `?${params.join("&")}` : "";
+    return await this.requestOptional("GET", `/entity-facets${query}`, options);
+  }
   async addLocation({ type = "url", target, dryRun, presence }, options) {
     const response = await this.fetchApi.fetch(`${await this.discoveryApi.getBaseUrl("catalog")}/locations${dryRun ? "?dryRun=true" : ""}`, {
       headers: {

package/dist/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":["../src/types/api.ts","../src/CatalogClient.ts","../src/types/status.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity, EntityName, LocationSpec } from '@backstage/catalog-model';\n\n/**\n * This symbol can be used in place of a value when passed to filters in e.g.\n * {@link CatalogClient.getEntities}, to signify that you want to filter on the\n * presence of that key no matter what its value is.\n *\n * @public\n */\nexport const CATALOG_FILTER_EXISTS = Symbol.for(\n  // Random UUID to ensure no collisions\n  'CATALOG_FILTER_EXISTS_0e15b590c0b343a2bae3e787e84c2111',\n);\n\n/**\n * The request type for {@link CatalogClient.getEntities}.\n *\n * @public\n */\nexport interface GetEntitiesRequest {\n  /**\n   * If given, return only entities that match the given patterns.\n   *\n   * @remarks\n   *\n   * If multiple filter sets are given as an array, then there is effectively an\n   * OR between each filter set.\n   *\n   * Within one filter set, there is effectively an AND between the various\n   * keys.\n   *\n   * Within one key, if there are more than one value, then there is effectively\n   * an OR between them.\n   *\n   * Example: For an input of\n   *\n   * ```\n   * [\n   *   { kind: ['API', 'Component'] },\n   *   { 'metadata.name': 'a', 'metadata.namespace': 'b' }\n   * ]\n   * ```\n   *\n   * This effectively means\n   *\n   * ```\n   * (kind = EITHER 'API' OR 'Component')\n   * OR\n   * (metadata.name = 'a' AND metadata.namespace = 'b' )\n   * ```\n   *\n   * Each key is a dot separated path in each object.\n   *\n   * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`\n   * (exported from this package), which means that you assert on the existence\n   * of that key, no matter what its value is.\n   */\n  filter?:\n    | Record<string, string | symbol | (string | symbol)[]>[]\n    | Record<string, string | symbol | (string | symbol)[]>\n    | undefined;\n  /**\n   * If given, return only the parts of each entity that match those dot\n   * separated paths in each object.\n   *\n   * @remarks\n   *\n   * Example: For an input of `['kind', 'metadata.annotations']`, then response\n   * objects will be shaped like\n   *\n   * ```\n   * {\n   *   \"kind\": \"Component\",\n   *   \"metadata\": {\n   *     \"annotations\": {\n   *       \"foo\": \"bar\"\n   *     }\n   *   }\n   * }\n   * ```\n   */\n  fields?: string[] | undefined;\n  /**\n   * If given, skips over the first N items in the result set.\n   */\n  offset?: number;\n  /**\n   * If given, returns at most N items from the result set.\n   */\n  limit?: number;\n  /**\n   * If given, skips over all items before that cursor as returned by a previous\n   * request.\n   */\n  after?: string;\n}\n\n/**\n * The response type for {@link CatalogClient.getEntities}.\n *\n * @public\n */\nexport interface GetEntitiesResponse {\n  items: Entity[];\n}\n\n/**\n * The request type for {@link CatalogClient.getEntityAncestors}.\n *\n * @public\n */\nexport interface GetEntityAncestorsRequest {\n  entityRef: string;\n}\n\n/**\n * The response type for {@link CatalogClient.getEntityAncestors}.\n *\n * @public\n */\nexport interface GetEntityAncestorsResponse {\n  rootEntityRef: string;\n  items: Array<{\n    entity: Entity;\n    parentEntityRefs: string[];\n  }>;\n}\n\n/**\n * Options you can pass into a catalog request for additional information.\n *\n * @public\n */\nexport interface CatalogRequestOptions {\n  token?: string;\n}\n\n/**\n * Entity location for a specific entity.\n *\n * @public\n */\nexport type Location = {\n  id: string;\n} & LocationSpec;\n\n/**\n * The request type for {@link CatalogClient.addLocation}.\n *\n * @public\n */\nexport type AddLocationRequest = {\n  type?: string;\n  target: string;\n  dryRun?: boolean;\n  presence?: 'optional' | 'required';\n};\n\n/**\n * The response type for {@link CatalogClient.addLocation}.\n *\n * @public\n */\nexport type AddLocationResponse = {\n  location: Location;\n  entities: Entity[];\n  // Only set in dryRun mode.\n  exists?: boolean;\n};\n\n/**\n * A client for interacting with the Backstage software catalog through its API.\n *\n * @public\n */\nexport interface CatalogApi {\n  /**\n   * Lists catalog entities.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntities(\n    request?: GetEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntitiesResponse>;\n\n  /**\n   * Gets entity ancestor information, i.e. the hierarchy of parent entities\n   * whose processing resulted in a given entity appearing in the catalog.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntityAncestors(\n    request: GetEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityAncestorsResponse>;\n\n  /**\n   * Gets a single entity from the catalog by its ref (kind, namespace, name)\n   * triplet.\n   *\n   * @param name - A complete entity ref\n   * @param options - Additional options\n   */\n  getEntityByName(\n    name: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined>;\n\n  /**\n   * Removes a single entity from the catalog by entity UID.\n   *\n   * @param uid - An entity UID\n   * @param options - Additional options\n   */\n  removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  /**\n   * Refreshes (marks for reprocessing) an entity in the catalog.\n   *\n   * @param entityRef - An entity ref on string form (e.g.\n   *        'component/default:my-component')\n   * @param options - Additional options\n   */\n  refreshEntity(\n    entityRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  // Locations\n\n  /**\n   * Gets a registered location by its ID.\n   *\n   * @param id - A location ID\n   * @param options - Additional options\n   */\n  getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n\n  /**\n   * Gets a registered location by its ref.\n   *\n   * @param locationRef - A location ref, e.g. \"url:https://github.com/...\"\n   * @param options - Additional options\n   */\n  getLocationByRef(\n    locationRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n\n  /**\n   * Registers a new location.\n   *\n   * @param location - Request parameters\n   * @param options - Additional options\n   */\n  addLocation(\n    location: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse>;\n\n  /**\n   * Removes a registered Location by its ID.\n   *\n   * @param id - A location ID\n   * @param options - Additional options\n   */\n  removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n}\n","/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  ANNOTATION_LOCATION,\n  ANNOTATION_ORIGIN_LOCATION,\n  Entity,\n  EntityName,\n  parseEntityRef,\n  stringifyEntityRef,\n  stringifyLocationRef,\n} from '@backstage/catalog-model';\nimport { ResponseError } from '@backstage/errors';\nimport crossFetch from 'cross-fetch';\nimport {\n  CATALOG_FILTER_EXISTS,\n  AddLocationRequest,\n  AddLocationResponse,\n  CatalogApi,\n  GetEntitiesRequest,\n  GetEntitiesResponse,\n  CatalogRequestOptions,\n  GetEntityAncestorsRequest,\n  GetEntityAncestorsResponse,\n  Location,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\nimport { FetchApi } from './types/fetch';\n\n/**\n * A frontend and backend compatible client for communicating with the Backstage\n * software catalog.\n *\n * @public\n */\nexport class CatalogClient implements CatalogApi {\n  private readonly discoveryApi: DiscoveryApi;\n  private readonly fetchApi: FetchApi;\n\n  constructor(options: {\n    discoveryApi: { getBaseUrl(pluginId: string): Promise<string> };\n    fetchApi?: { fetch: typeof fetch };\n  }) {\n    this.discoveryApi = options.discoveryApi;\n    this.fetchApi = options.fetchApi || { fetch: crossFetch };\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityAncestors}\n   */\n  async getEntityAncestors(\n    request: GetEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityAncestorsResponse> {\n    const { kind, namespace, name } = parseEntityRef(request.entityRef);\n    return await this.requestRequired(\n      'GET',\n      `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n        namespace,\n      )}/${encodeURIComponent(name)}/ancestry`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getLocationById}\n   */\n  async getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    return await this.requestOptional(\n      'GET',\n      `/locations/${encodeURIComponent(id)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntities}\n   */\n  async getEntities(\n    request?: GetEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntitiesResponse> {\n    const { filter = [], fields = [], offset, limit, after } = request ?? {};\n    const filterItems = [filter].flat();\n    const params: string[] = [];\n\n    // filter param can occur multiple times, for example\n    // /api/catalog/entities?filter=metadata.name=wayback-search,kind=component&filter=metadata.name=www-artist,kind=component'\n    // the \"outer array\" defined by `filter` occurrences corresponds to \"anyOf\" filters\n    // the \"inner array\" defined within a `filter` param corresponds to \"allOf\" filters\n    for (const filterItem of filterItems) {\n      const filterParts: string[] = [];\n      for (const [key, value] of Object.entries(filterItem)) {\n        for (const v of [value].flat()) {\n          if (v === CATALOG_FILTER_EXISTS) {\n            filterParts.push(encodeURIComponent(key));\n          } else if (typeof v === 'string') {\n            filterParts.push(\n              `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,\n            );\n          }\n        }\n      }\n\n      if (filterParts.length) {\n        params.push(`filter=${filterParts.join(',')}`);\n      }\n    }\n\n    if (fields.length) {\n      params.push(`fields=${fields.map(encodeURIComponent).join(',')}`);\n    }\n\n    if (offset !== undefined) {\n      params.push(`offset=${offset}`);\n    }\n    if (limit !== undefined) {\n      params.push(`limit=${limit}`);\n    }\n    if (after !== undefined) {\n      params.push(`after=${encodeURIComponent(after)}`);\n    }\n\n    const query = params.length ? `?${params.join('&')}` : '';\n    const entities: Entity[] = await this.requestRequired(\n      'GET',\n      `/entities${query}`,\n      options,\n    );\n\n    const refCompare = (a: Entity, b: Entity) => {\n      // in case field filtering is used, these fields might not be part of the response\n      if (\n        a.metadata?.name === undefined ||\n        a.kind === undefined ||\n        b.metadata?.name === undefined ||\n        b.kind === undefined\n      ) {\n        return 0;\n      }\n\n      const aRef = stringifyEntityRef(a);\n      const bRef = stringifyEntityRef(b);\n      if (aRef < bRef) {\n        return -1;\n      }\n      if (aRef > bRef) {\n        return 1;\n      }\n      return 0;\n    };\n\n    return { items: entities.sort(refCompare) };\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityByName}\n   */\n  async getEntityByName(\n    compoundName: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined> {\n    const { kind, namespace = 'default', name } = compoundName;\n    return this.requestOptional(\n      'GET',\n      `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n        namespace,\n      )}/${encodeURIComponent(name)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.refreshEntity}\n   */\n  async refreshEntity(entityRef: string, options?: CatalogRequestOptions) {\n    const response = await this.fetchApi.fetch(\n      `${await this.discoveryApi.getBaseUrl('catalog')}/refresh`,\n      {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n        },\n        method: 'POST',\n        body: JSON.stringify({ entityRef }),\n      },\n    );\n\n    if (response.status !== 200) {\n      throw new Error(await response.text());\n    }\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.addLocation}\n   */\n  async addLocation(\n    { type = 'url', target, dryRun, presence }: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse> {\n    const response = await this.fetchApi.fetch(\n      `${await this.discoveryApi.getBaseUrl('catalog')}/locations${\n        dryRun ? '?dryRun=true' : ''\n      }`,\n      {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n        },\n        method: 'POST',\n        body: JSON.stringify({ type, target, presence }),\n      },\n    );\n\n    if (response.status !== 201) {\n      throw new Error(await response.text());\n    }\n\n    const { location, entities, exists } = await response.json();\n\n    if (!location) {\n      throw new Error(`Location wasn't added: ${target}`);\n    }\n\n    return {\n      location,\n      entities,\n      exists,\n    };\n  }\n\n  /**\n   * @deprecated please use getLocationByRef instead\n   */\n  async getOriginLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound =\n      entity.metadata.annotations?.[ANNOTATION_ORIGIN_LOCATION];\n    if (!locationCompound) {\n      return undefined;\n    }\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationCompound === stringifyLocationRef(l));\n  }\n\n  /**\n   * @deprecated please use getLocationByRef instead\n   */\n  async getLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound = entity.metadata.annotations?.[ANNOTATION_LOCATION];\n    if (!locationCompound) {\n      return undefined;\n    }\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationCompound === stringifyLocationRef(l));\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getLocationByRef}\n   */\n  async getLocationByRef(\n    locationRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationRef === stringifyLocationRef(l));\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.removeLocationById}\n   */\n  async removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    await this.requestIgnored(\n      'DELETE',\n      `/locations/${encodeURIComponent(id)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.removeEntityByUid}\n   */\n  async removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    await this.requestIgnored(\n      'DELETE',\n      `/entities/by-uid/${encodeURIComponent(uid)}`,\n      options,\n    );\n  }\n\n  //\n  // Private methods\n  //\n\n  private async requestIgnored(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n  }\n\n  private async requestRequired(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<any> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n\n    return await response.json();\n  }\n\n  private async requestOptional(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<any | undefined> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      if (response.status === 404) {\n        return undefined;\n      }\n      throw await ResponseError.fromResponse(response);\n    }\n\n    return await response.json();\n  }\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The entity `status.items[].type` for the status of the processing engine in\n * regards to an entity.\n *\n * @public\n */\nexport const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =\n  'backstage.io/catalog-processing';\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.esm.js","sources":["../src/types/api.ts","../src/CatalogClient.ts","../src/types/status.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Entity, EntityName } from '@backstage/catalog-model';\n\n/**\n * This symbol can be used in place of a value when passed to filters in e.g.\n * {@link CatalogClient.getEntities}, to signify that you want to filter on the\n * presence of that key no matter what its value is.\n *\n * @public\n */\nexport const CATALOG_FILTER_EXISTS = Symbol.for(\n  // Random UUID to ensure no collisions\n  'CATALOG_FILTER_EXISTS_0e15b590c0b343a2bae3e787e84c2111',\n);\n\n/**\n * The request type for {@link CatalogClient.getEntities}.\n *\n * @public\n */\nexport interface GetEntitiesRequest {\n  /**\n   * If given, return only entities that match the given patterns.\n   *\n   * @remarks\n   *\n   * If multiple filter sets are given as an array, then there is effectively an\n   * OR between each filter set.\n   *\n   * Within one filter set, there is effectively an AND between the various\n   * keys.\n   *\n   * Within one key, if there are more than one value, then there is effectively\n   * an OR between them.\n   *\n   * Example: For an input of\n   *\n   * ```\n   * [\n   *   { kind: ['API', 'Component'] },\n   *   { 'metadata.name': 'a', 'metadata.namespace': 'b' }\n   * ]\n   * ```\n   *\n   * This effectively means\n   *\n   * ```\n   * (kind = EITHER 'API' OR 'Component')\n   * OR\n   * (metadata.name = 'a' AND metadata.namespace = 'b' )\n   * ```\n   *\n   * Each key is a dot separated path in each object.\n   *\n   * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`\n   * (exported from this package), which means that you assert on the existence\n   * of that key, no matter what its value is.\n   */\n  filter?:\n    | Record<string, string | symbol | (string | symbol)[]>[]\n    | Record<string, string | symbol | (string | symbol)[]>\n    | undefined;\n  /**\n   * If given, return only the parts of each entity that match those dot\n   * separated paths in each object.\n   *\n   * @remarks\n   *\n   * Example: For an input of `['kind', 'metadata.annotations']`, then response\n   * objects will be shaped like\n   *\n   * ```\n   * {\n   *   \"kind\": \"Component\",\n   *   \"metadata\": {\n   *     \"annotations\": {\n   *       \"foo\": \"bar\"\n   *     }\n   *   }\n   * }\n   * ```\n   */\n  fields?: string[] | undefined;\n  /**\n   * If given, skips over the first N items in the result set.\n   */\n  offset?: number;\n  /**\n   * If given, returns at most N items from the result set.\n   */\n  limit?: number;\n  /**\n   * If given, skips over all items before that cursor as returned by a previous\n   * request.\n   */\n  after?: string;\n}\n\n/**\n * The response type for {@link CatalogClient.getEntities}.\n *\n * @public\n */\nexport interface GetEntitiesResponse {\n  items: Entity[];\n}\n\n/**\n * The request type for {@link CatalogClient.getEntityAncestors}.\n *\n * @public\n */\nexport interface GetEntityAncestorsRequest {\n  entityRef: string;\n}\n\n/**\n * The response type for {@link CatalogClient.getEntityAncestors}.\n *\n * @public\n */\nexport interface GetEntityAncestorsResponse {\n  rootEntityRef: string;\n  items: Array<{\n    entity: Entity;\n    parentEntityRefs: string[];\n  }>;\n}\n\n/**\n * The request type for {@link CatalogClient.getEntityFacets}.\n *\n * @public\n */\nexport interface GetEntityFacetsRequest {\n  /**\n   * If given, return only entities that match the given patterns.\n   *\n   * @remarks\n   *\n   * If multiple filter sets are given as an array, then there is effectively an\n   * OR between each filter set.\n   *\n   * Within one filter set, there is effectively an AND between the various\n   * keys.\n   *\n   * Within one key, if there are more than one value, then there is effectively\n   * an OR between them.\n   *\n   * Example: For an input of\n   *\n   * ```\n   * [\n   *   { kind: ['API', 'Component'] },\n   *   { 'metadata.name': 'a', 'metadata.namespace': 'b' }\n   * ]\n   * ```\n   *\n   * This effectively means\n   *\n   * ```\n   * (kind = EITHER 'API' OR 'Component')\n   * OR\n   * (metadata.name = 'a' AND metadata.namespace = 'b' )\n   * ```\n   *\n   * Each key is a dot separated path in each object.\n   *\n   * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`\n   * (exported from this package), which means that you assert on the existence\n   * of that key, no matter what its value is.\n   */\n  filter?:\n    | Record<string, string | symbol | (string | symbol)[]>[]\n    | Record<string, string | symbol | (string | symbol)[]>\n    | undefined;\n  /**\n   * Dot separated paths for the facets to extract from each entity.\n   *\n   * @remarks\n   *\n   * Example: For an input of `['kind', 'metadata.annotations.backstage.io/orphan']`, then the\n   * response will be shaped like\n   *\n   * ```\n   * {\n   *   \"facets\": {\n   *     \"kind\": [\n   *       { \"key\": \"Component\", \"count\": 22 },\n   *       { \"key\": \"API\", \"count\": 13 }\n   *     ],\n   *     \"metadata.annotations.backstage.io/orphan\": [\n   *       { \"key\": \"true\", \"count\": 2 }\n   *     ]\n   *   }\n   * }\n   * ```\n   */\n  facets: string[];\n}\n\n/**\n * The response type for {@link CatalogClient.getEntityFacets}.\n *\n * @public\n */\nexport interface GetEntityFacetsResponse {\n  /**\n   * The computed facets, one entry per facet in the request.\n   */\n  facets: Record<string, Array<{ value: string; count: number }>>;\n}\n\n/**\n * Options you can pass into a catalog request for additional information.\n *\n * @public\n */\nexport interface CatalogRequestOptions {\n  token?: string;\n}\n\n/**\n * Entity location for a specific entity.\n *\n * @public\n */\nexport type Location = {\n  id: string;\n  type: string;\n  target: string;\n  /** @deprecated This field is is ignored */\n  presence?: 'optional' | 'required';\n};\n\n/**\n * The request type for {@link CatalogClient.addLocation}.\n *\n * @public\n */\nexport type AddLocationRequest = {\n  type?: string;\n  target: string;\n  dryRun?: boolean;\n  /** @deprecated This field is is ignored */\n  presence?: 'optional' | 'required';\n};\n\n/**\n * The response type for {@link CatalogClient.addLocation}.\n *\n * @public\n */\nexport type AddLocationResponse = {\n  location: Location;\n  entities: Entity[];\n  // Only set in dryRun mode.\n  exists?: boolean;\n};\n\n/**\n * A client for interacting with the Backstage software catalog through its API.\n *\n * @public\n */\nexport interface CatalogApi {\n  /**\n   * Lists catalog entities.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntities(\n    request?: GetEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntitiesResponse>;\n\n  /**\n   * Gets entity ancestor information, i.e. the hierarchy of parent entities\n   * whose processing resulted in a given entity appearing in the catalog.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntityAncestors(\n    request: GetEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityAncestorsResponse>;\n\n  /**\n   * Gets a single entity from the catalog by its ref (kind, namespace, name)\n   * triplet.\n   *\n   * @param name - A complete entity ref\n   * @param options - Additional options\n   */\n  getEntityByName(\n    name: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined>;\n\n  /**\n   * Removes a single entity from the catalog by entity UID.\n   *\n   * @param uid - An entity UID\n   * @param options - Additional options\n   */\n  removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  /**\n   * Refreshes (marks for reprocessing) an entity in the catalog.\n   *\n   * @param entityRef - An entity ref on string form (e.g.\n   *        'component/default:my-component')\n   * @param options - Additional options\n   */\n  refreshEntity(\n    entityRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  /**\n   * Gets a summary of field facets of entities in the catalog.\n   *\n   * @param request - Request parameters\n   * @param options - Additional options\n   */\n  getEntityFacets(\n    request: GetEntityFacetsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityFacetsResponse>;\n\n  // Locations\n\n  /**\n   * Gets a registered location by its ID.\n   *\n   * @param id - A location ID\n   * @param options - Additional options\n   */\n  getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n\n  /**\n   * Gets a registered location by its ref.\n   *\n   * @param locationRef - A location ref, e.g. \"url:https://github.com/...\"\n   * @param options - Additional options\n   */\n  getLocationByRef(\n    locationRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n\n  /**\n   * Registers a new location.\n   *\n   * @param location - Request parameters\n   * @param options - Additional options\n   */\n  addLocation(\n    location: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse>;\n\n  /**\n   * Removes a registered Location by its ID.\n   *\n   * @param id - A location ID\n   * @param options - Additional options\n   */\n  removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n}\n","/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  ANNOTATION_LOCATION,\n  ANNOTATION_ORIGIN_LOCATION,\n  Entity,\n  EntityName,\n  parseEntityRef,\n  stringifyEntityRef,\n  stringifyLocationRef,\n} from '@backstage/catalog-model';\nimport { ResponseError } from '@backstage/errors';\nimport crossFetch from 'cross-fetch';\nimport {\n  CATALOG_FILTER_EXISTS,\n  AddLocationRequest,\n  AddLocationResponse,\n  CatalogApi,\n  GetEntitiesRequest,\n  GetEntitiesResponse,\n  CatalogRequestOptions,\n  GetEntityAncestorsRequest,\n  GetEntityAncestorsResponse,\n  Location,\n  GetEntityFacetsRequest,\n  GetEntityFacetsResponse,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\nimport { FetchApi } from './types/fetch';\n\n/**\n * A frontend and backend compatible client for communicating with the Backstage\n * software catalog.\n *\n * @public\n */\nexport class CatalogClient implements CatalogApi {\n  private readonly discoveryApi: DiscoveryApi;\n  private readonly fetchApi: FetchApi;\n\n  constructor(options: {\n    discoveryApi: { getBaseUrl(pluginId: string): Promise<string> };\n    fetchApi?: { fetch: typeof fetch };\n  }) {\n    this.discoveryApi = options.discoveryApi;\n    this.fetchApi = options.fetchApi || { fetch: crossFetch };\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityAncestors}\n   */\n  async getEntityAncestors(\n    request: GetEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityAncestorsResponse> {\n    const { kind, namespace, name } = parseEntityRef(request.entityRef);\n    return await this.requestRequired(\n      'GET',\n      `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n        namespace,\n      )}/${encodeURIComponent(name)}/ancestry`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getLocationById}\n   */\n  async getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    return await this.requestOptional(\n      'GET',\n      `/locations/${encodeURIComponent(id)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntities}\n   */\n  async getEntities(\n    request?: GetEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntitiesResponse> {\n    const { filter = [], fields = [], offset, limit, after } = request ?? {};\n    const params: string[] = [];\n\n    // filter param can occur multiple times, for example\n    // /api/catalog/entities?filter=metadata.name=wayback-search,kind=component&filter=metadata.name=www-artist,kind=component'\n    // the \"outer array\" defined by `filter` occurrences corresponds to \"anyOf\" filters\n    // the \"inner array\" defined within a `filter` param corresponds to \"allOf\" filters\n    for (const filterItem of [filter].flat()) {\n      const filterParts: string[] = [];\n      for (const [key, value] of Object.entries(filterItem)) {\n        for (const v of [value].flat()) {\n          if (v === CATALOG_FILTER_EXISTS) {\n            filterParts.push(encodeURIComponent(key));\n          } else if (typeof v === 'string') {\n            filterParts.push(\n              `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,\n            );\n          }\n        }\n      }\n\n      if (filterParts.length) {\n        params.push(`filter=${filterParts.join(',')}`);\n      }\n    }\n\n    if (fields.length) {\n      params.push(`fields=${fields.map(encodeURIComponent).join(',')}`);\n    }\n\n    if (offset !== undefined) {\n      params.push(`offset=${offset}`);\n    }\n    if (limit !== undefined) {\n      params.push(`limit=${limit}`);\n    }\n    if (after !== undefined) {\n      params.push(`after=${encodeURIComponent(after)}`);\n    }\n\n    const query = params.length ? `?${params.join('&')}` : '';\n    const entities: Entity[] = await this.requestRequired(\n      'GET',\n      `/entities${query}`,\n      options,\n    );\n\n    const refCompare = (a: Entity, b: Entity) => {\n      // in case field filtering is used, these fields might not be part of the response\n      if (\n        a.metadata?.name === undefined ||\n        a.kind === undefined ||\n        b.metadata?.name === undefined ||\n        b.kind === undefined\n      ) {\n        return 0;\n      }\n\n      const aRef = stringifyEntityRef(a);\n      const bRef = stringifyEntityRef(b);\n      if (aRef < bRef) {\n        return -1;\n      }\n      if (aRef > bRef) {\n        return 1;\n      }\n      return 0;\n    };\n\n    return { items: entities.sort(refCompare) };\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityByName}\n   */\n  async getEntityByName(\n    compoundName: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined> {\n    const { kind, namespace = 'default', name } = compoundName;\n    return this.requestOptional(\n      'GET',\n      `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n        namespace,\n      )}/${encodeURIComponent(name)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.refreshEntity}\n   */\n  async refreshEntity(entityRef: string, options?: CatalogRequestOptions) {\n    const response = await this.fetchApi.fetch(\n      `${await this.discoveryApi.getBaseUrl('catalog')}/refresh`,\n      {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n        },\n        method: 'POST',\n        body: JSON.stringify({ entityRef }),\n      },\n    );\n\n    if (response.status !== 200) {\n      throw new Error(await response.text());\n    }\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getEntityFacets}\n   */\n  async getEntityFacets(\n    request: GetEntityFacetsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<GetEntityFacetsResponse> {\n    const { filter = [], facets } = request;\n    const params: string[] = [];\n\n    // filter param can occur multiple times, for example\n    // /api/catalog/entities?filter=metadata.name=wayback-search,kind=component&filter=metadata.name=www-artist,kind=component'\n    // the \"outer array\" defined by `filter` occurrences corresponds to \"anyOf\" filters\n    // the \"inner array\" defined within a `filter` param corresponds to \"allOf\" filters\n    for (const filterItem of [filter].flat()) {\n      const filterParts: string[] = [];\n      for (const [key, value] of Object.entries(filterItem)) {\n        for (const v of [value].flat()) {\n          if (v === CATALOG_FILTER_EXISTS) {\n            filterParts.push(encodeURIComponent(key));\n          } else if (typeof v === 'string') {\n            filterParts.push(\n              `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,\n            );\n          }\n        }\n      }\n\n      if (filterParts.length) {\n        params.push(`filter=${filterParts.join(',')}`);\n      }\n    }\n\n    for (const facet of facets) {\n      params.push(`facet=${encodeURIComponent(facet)}`);\n    }\n\n    const query = params.length ? `?${params.join('&')}` : '';\n    return await this.requestOptional('GET', `/entity-facets${query}`, options);\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.addLocation}\n   */\n  async addLocation(\n    { type = 'url', target, dryRun, presence }: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse> {\n    const response = await this.fetchApi.fetch(\n      `${await this.discoveryApi.getBaseUrl('catalog')}/locations${\n        dryRun ? '?dryRun=true' : ''\n      }`,\n      {\n        headers: {\n          'Content-Type': 'application/json',\n          ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n        },\n        method: 'POST',\n        body: JSON.stringify({ type, target, presence }),\n      },\n    );\n\n    if (response.status !== 201) {\n      throw new Error(await response.text());\n    }\n\n    const { location, entities, exists } = await response.json();\n\n    if (!location) {\n      throw new Error(`Location wasn't added: ${target}`);\n    }\n\n    return {\n      location,\n      entities,\n      exists,\n    };\n  }\n\n  /**\n   * @deprecated please use getLocationByRef instead\n   */\n  async getOriginLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound =\n      entity.metadata.annotations?.[ANNOTATION_ORIGIN_LOCATION];\n    if (!locationCompound) {\n      return undefined;\n    }\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationCompound === stringifyLocationRef(l));\n  }\n\n  /**\n   * @deprecated please use getLocationByRef instead\n   */\n  async getLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound = entity.metadata.annotations?.[ANNOTATION_LOCATION];\n    if (!locationCompound) {\n      return undefined;\n    }\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationCompound === stringifyLocationRef(l));\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.getLocationByRef}\n   */\n  async getLocationByRef(\n    locationRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const all: { data: Location }[] = await this.requestRequired(\n      'GET',\n      '/locations',\n      options,\n    );\n    return all\n      .map(r => r.data)\n      .find(l => locationRef === stringifyLocationRef(l));\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.removeLocationById}\n   */\n  async removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    await this.requestIgnored(\n      'DELETE',\n      `/locations/${encodeURIComponent(id)}`,\n      options,\n    );\n  }\n\n  /**\n   * {@inheritdoc CatalogApi.removeEntityByUid}\n   */\n  async removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    await this.requestIgnored(\n      'DELETE',\n      `/entities/by-uid/${encodeURIComponent(uid)}`,\n      options,\n    );\n  }\n\n  //\n  // Private methods\n  //\n\n  private async requestIgnored(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n  }\n\n  private async requestRequired(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<any> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n\n    return await response.json();\n  }\n\n  private async requestOptional(\n    method: string,\n    path: string,\n    options?: CatalogRequestOptions,\n  ): Promise<any | undefined> {\n    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n    const headers: Record<string, string> = options?.token\n      ? { Authorization: `Bearer ${options.token}` }\n      : {};\n    const response = await this.fetchApi.fetch(url, { method, headers });\n\n    if (!response.ok) {\n      if (response.status === 404) {\n        return undefined;\n      }\n      throw await ResponseError.fromResponse(response);\n    }\n\n    return await response.json();\n  }\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The entity `status.items[].type` for the status of the processing engine in\n * regards to an entity.\n *\n * @public\n */\nexport const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =\n  'backstage.io/catalog-processing';\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/catalog-client",
   "description": "An isomorphic client for the catalog backend",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -33,18 +33,18 @@
     "clean": "backstage-cli package clean"
   },
   "dependencies": {
-    "@backstage/catalog-model": "^0.10.1",
+    "@backstage/catalog-model": "^0.11.0",
     "@backstage/errors": "^0.2.2",
     "cross-fetch": "^3.1.5"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.14.0",
+    "@backstage/cli": "^0.14.1",
     "@types/jest": "^26.0.7",
     "msw": "^0.35.0"
   },
   "files": [
     "dist"
   ],
-  "gitHead": "e244b348c473700e7d5e5fbcef38bd9f9fd1d0ba",
+  "gitHead": "a15da6ea1e3e8adc37be98be064071c8b5279b4a",
   "module": "dist/index.esm.js"
 }