@backstage/catalog-client 0.5.5-next.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @backstage/catalog-client
 
+## 0.7.1
+
+### Patch Changes
+
+- Fix for the previous release with missing type declarations.
+- Updated dependencies
+  - @backstage/catalog-model@0.10.1
+  - @backstage/errors@0.2.2
+
+## 0.7.0
+
+### Minor Changes
+
+- 8eda0e7a9c: **BREAKING**: Removed the explicit `DiscoveryApi` and `FetchApi` export symbols,
+  which were unnecessary duplicates from the well known core ones.
+
+  The `CATALOG_FILTER_EXISTS` symbol's value has changed. However, this should not
+  affect any code in practice.
+
+- deaf6065db: Removed `CatalogApi.geLocationByEntity` and `CatalogApi.getOriginLocationByEntity`, and replaced them with `CatalogApi.getLocationByRef`.
+
+  If you were using one of the two old methods, you can update your code as follows:
+
+  ```diff
+  -const originLocation = catalogApi.getOriginLocationByEntity(entity);
+  +const originLocation = catalogApi.getLocationByRef(entity.metadata.annotations[ANNOTATION_ORIGIN_LOCATION]!);
+  -const location = catalogApi.getLocationByEntity(entity);
+  +const location = catalogApi.getLocationByRef(entity.metadata.annotations[ANNOTATION_LOCATION]!);
+  ```
+
+### Patch Changes
+
+- 1ed305728b: Bump `node-fetch` to version 2.6.7 and `cross-fetch` to version 3.1.5
+- c77c5c7eb6: Added `backstage.role` to `package.json`
+- 216725b434: Updated to use new names for `parseLocationRef` and `stringifyLocationRef`
+- 244d24ebc4: Export the `Location` type that was previously exported by the `@backstage/catalog-model` package.
+- 538ca90790: Deprecated the following types used by the catalog client, and created new
+  corresponding types to make them more consistent:
+
+  - `CatalogEntitiesRequest` -> `GetEntitiesRequest`
+  - `CatalogListResponse` was removed and generally replaced with `GetEntitiesResponse` (which does not use a type parameter argument)
+  - `CatalogEntityAncestorsRequest`-> `GetEntityAncestorsRequest`
+  - `CatalogEntityAncestorsResponse` -> `GetEntityAncestorsResponse`
+
+- 27eccab216: Replaces use of deprecated catalog-model constants.
+- Updated dependencies
+  - @backstage/errors@0.2.1
+  - @backstage/catalog-model@0.10.0
+
+## 0.6.0
+
+### Minor Changes
+
+- f8633307c4: Fixed the return type of the catalog API `getEntityAncestors`, to match the
+  actual server response shape.
+
+  While this technically is a breaking change, the old shape has never worked at
+  all if you tried to use it - so treating this as an immediately-shipped breaking
+  bug fix.
+
+## 0.5.5
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/catalog-model@0.9.10
+
 ## 0.5.5-next.0
 
 ### Patch Changes

package/dist/index.cjs.js

@@ -10,7 +10,7 @@ function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'defau
 
 var crossFetch__default = /*#__PURE__*/_interopDefaultLegacy(crossFetch);
 
-const CATALOG_FILTER_EXISTS = Symbol("CATALOG_FILTER_EXISTS");
+const CATALOG_FILTER_EXISTS = Symbol.for("CATALOG_FILTER_EXISTS_0e15b590c0b343a2bae3e787e84c2111");
 
 class CatalogClient {
   constructor(options) {
@@ -115,21 +115,25 @@ class CatalogClient {
   }
   async getOriginLocationByEntity(entity, options) {
     var _a;
-    const locationCompound = (_a = entity.metadata.annotations) == null ? void 0 : _a[catalogModel.ORIGIN_LOCATION_ANNOTATION];
+    const locationCompound = (_a = entity.metadata.annotations) == null ? void 0 : _a[catalogModel.ANNOTATION_ORIGIN_LOCATION];
     if (!locationCompound) {
       return void 0;
     }
     const all = await this.requestRequired("GET", "/locations", options);
-    return all.map((r) => r.data).find((l) => locationCompound === catalogModel.stringifyLocationReference(l));
+    return all.map((r) => r.data).find((l) => locationCompound === catalogModel.stringifyLocationRef(l));
   }
   async getLocationByEntity(entity, options) {
     var _a;
-    const locationCompound = (_a = entity.metadata.annotations) == null ? void 0 : _a[catalogModel.LOCATION_ANNOTATION];
+    const locationCompound = (_a = entity.metadata.annotations) == null ? void 0 : _a[catalogModel.ANNOTATION_LOCATION];
     if (!locationCompound) {
       return void 0;
     }
     const all = await this.requestRequired("GET", "/locations", options);
-    return all.map((r) => r.data).find((l) => locationCompound === catalogModel.stringifyLocationReference(l));
+    return all.map((r) => r.data).find((l) => locationCompound === catalogModel.stringifyLocationRef(l));
+  }
+  async getLocationByRef(locationRef, options) {
+    const all = await this.requestRequired("GET", "/locations", options);
+    return all.map((r) => r.data).find((l) => locationRef === catalogModel.stringifyLocationRef(l));
   }
   async removeLocationById(id, options) {
     await this.requestIgnored("DELETE", `/locations/${encodeURIComponent(id)}`, options);

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, Location } from '@backstage/catalog-model';\n\n/**\n * A Symbol to define if a catalog filter exists or not.\n *\n * @public\n */\nexport const CATALOG_FILTER_EXISTS = Symbol('CATALOG_FILTER_EXISTS');\n\n/**\n * A request type for retrieving catalog Entities.\n *\n * @public\n */\nexport type CatalogEntitiesRequest = {\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 * A request type for Catalog Entity Ancestor information.\n *\n * @public\n */\nexport type CatalogEntityAncestorsRequest = {\n  entityRef: string;\n};\n\n/**\n * A response type for Catalog Entity Ancestor information.\n *\n * @public\n */\nexport type CatalogEntityAncestorsResponse = {\n  root: EntityName;\n  items: { entity: Entity; parents: EntityName[] }[];\n};\n\n/**\n * A response type for the result of a catalog operation in list form.\n *\n * @public\n */\nexport type CatalogListResponse<T> = {\n  items: T[];\n};\n\n/**\n * Options you can pass into a catalog request for additional information.\n *\n * @public\n */\nexport type CatalogRequestOptions = {\n  token?: string;\n};\n\n/**\n * Public functions for interacting with the Catalog API.\n *\n * @public\n */\nexport interface CatalogApi {\n  /**\n   * Gets the Entities from the catalog based on your request and options.\n   *\n   * @param request - An object with your filters and fields.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A CatalogListResponse with items typed Catalog Model Entity.\n   *\n   */\n  getEntities(\n    request?: CatalogEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<CatalogListResponse<Entity>>;\n  /**\n   * Gets the Entity ancestor information from the catalog based on your request and options.\n   *\n   * @param request - An object with your filters and fields.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A CatalogEntityAncestorsResponse.\n   */\n  getEntityAncestors(\n    request: CatalogEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<CatalogEntityAncestorsResponse>;\n  /**\n   * Gets a single Entity from the catalog by Entity name.\n   *\n   * @param name - A complete Entity name, with the full kind-namespace-name triplet.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Entity}.\n   */\n  getEntityByName(\n    name: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined>;\n  /**\n   * Removes a single Entity from the catalog by Entity UID.\n   *\n   * @param uid - A string of the Entity UID.\n   * @param options - An object with your preferred options.\n   *\n   */\n  removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n  /**\n   * Refreshes an Entity in the catalog.\n   *\n   * @param entityRef - A string in the form of 'Kind/default:foo'.\n   * @param options - An object with your preferred options.\n   *\n   */\n  refreshEntity(\n    entityRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  // Locations\n  /**\n   * Gets a Location object by ID from the catalog.\n   *\n   * @param id - A string in of the Location Id.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   */\n  getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n  /**\n   * Gets origin location by Entity.\n   *\n   * @param entity - An {@link catalog-model#Entity}.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   */\n  getOriginLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n  /**\n   * Gets Location by Entity.\n   *\n   * @param entity - An {@link catalog-model#Entity}.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   */\n  getLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n  /**\n   * Adds a Location.\n   *\n   * @param location - A request type for adding a Location to the catalog.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A AddLocationResponse.\n   */\n  addLocation(\n    location: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse>;\n  /**\n   * Removes a Location by Id.\n   *\n   * @param id - A string in of the Location Id.\n   * @param options - An object with your preferred options.\n   *\n   */\n  removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n}\n\n/**\n * A request type for adding a Location to the catalog.\n *\n * @public\n */\nexport type AddLocationRequest = {\n  type?: string;\n  target: string;\n  dryRun?: boolean;\n  presence?: 'optional' | 'required';\n};\n\n/**\n * A response type for adding a Location to the catalog.\n *\n * @public\n */\nexport type AddLocationResponse = {\n  location: Location;\n  entities: Entity[];\n  // Exists is only set in DryRun mode.\n  exists?: boolean;\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  Entity,\n  EntityName,\n  Location,\n  LOCATION_ANNOTATION,\n  ORIGIN_LOCATION_ANNOTATION,\n  parseEntityRef,\n  stringifyEntityRef,\n  stringifyLocationReference,\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  CatalogEntitiesRequest,\n  CatalogListResponse,\n  CatalogRequestOptions,\n  CatalogEntityAncestorsRequest,\n  CatalogEntityAncestorsResponse,\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 Catalog.\n *\n * @public\n * */\nexport class CatalogClient implements CatalogApi {\n  private readonly discoveryApi: DiscoveryApi;\n  private readonly fetchApi: FetchApi;\n\n  constructor(options: { discoveryApi: DiscoveryApi; fetchApi?: FetchApi }) {\n    this.discoveryApi = options.discoveryApi;\n    this.fetchApi = options.fetchApi || { fetch: crossFetch };\n  }\n\n  /**\n   * Gets the Ancestors of an Entity.\n   *\n   * @param request - A request type for retrieving Entity ancestors.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A CatalogEntityAncestorsResponse.\n   *\n   * @public\n   */\n  async getEntityAncestors(\n    request: CatalogEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<CatalogEntityAncestorsResponse> {\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   * Gets a Location by Id.\n   *\n   * @param id - A string containing the Id.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   *\n   * @public\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   * Gets a set of Entities.\n   *\n   * @param request - A request type for retrieving an Entity.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A CatalogListResponse.\n   *\n   * @public\n   */\n  async getEntities(\n    request?: CatalogEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<CatalogListResponse<Entity>> {\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   * Gets a given Entity based on a provided name.\n   *\n   * @param compoundName - A string containing the name.\n   * @param options - An object with your preferred options.\n   *\n   * @returns An {@link catalog-model#Entity}.\n   *\n   * @public\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   * Refreshes an Entity.\n   *\n   * @param entityRef - A string containing the entityREf\n   * @param options - An object with your preferred options.\n   *\n   * @public\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   * Adds a location.\n   *\n   * @param options - An object with your preferred options.\n   * @param AddLocationRequest - A request object for adding locations.\n   *\n   * @returns An AddLocationResponse\n   *\n   * @public\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   *  Gets an origin Location By Entity.\n   *\n   * @param entity - An Entity\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   *\n   * @public\n   */\n  async getOriginLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound =\n      entity.metadata.annotations?.[ORIGIN_LOCATION_ANNOTATION];\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 === stringifyLocationReference(l));\n  }\n\n  /**\n   * Gets a Location by Entity.\n   *\n   * @param entity - An Entity\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   *\n   * @public\n   */\n  async getLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound = entity.metadata.annotations?.[LOCATION_ANNOTATION];\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 === stringifyLocationReference(l));\n  }\n\n  /**\n   * Removes a location as identified by Id.\n   *\n   * @param id - A string containing the Id\n   * @param options - An object with your preferred options.\n   *\n   * @public\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   * Removes an Entity as identified by Uid.\n   *\n   * @param uid - A string containing the Uid\n   * @param options - An object with your preferred options.\n   *\n   * @public\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","ORIGIN_LOCATION_ANNOTATION","stringifyLocationReference","LOCATION_ANNOTATION","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, 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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"}

package/dist/index.d.ts

@@ -1,17 +1,19 @@
-import { EntityName, Entity, Location } from '@backstage/catalog-model';
+import { Entity, LocationSpec, EntityName } from '@backstage/catalog-model';
 
 /**
- * A Symbol to define if a catalog filter exists or not.
+ * This symbol can be used in place of a value when passed to filters in e.g.
+ * {@link CatalogClient.getEntities}, to signify that you want to filter on the
+ * presence of that key no matter what its value is.
  *
  * @public
  */
 declare const CATALOG_FILTER_EXISTS: unique symbol;
 /**
- * A request type for retrieving catalog Entities.
+ * The request type for {@link CatalogClient.getEntities}.
  *
  * @public
  */
-declare type CatalogEntitiesRequest = {
+interface GetEntitiesRequest {
     /**
      * If given, return only entities that match the given patterns.
      *
@@ -84,292 +86,205 @@ declare type CatalogEntitiesRequest = {
      * request.
      */
     after?: string;
-};
+}
+/**
+ * The response type for {@link CatalogClient.getEntities}.
+ *
+ * @public
+ */
+interface GetEntitiesResponse {
+    items: Entity[];
+}
 /**
- * A request type for Catalog Entity Ancestor information.
+ * The request type for {@link CatalogClient.getEntityAncestors}.
  *
  * @public
  */
-declare type CatalogEntityAncestorsRequest = {
+interface GetEntityAncestorsRequest {
     entityRef: string;
-};
+}
 /**
- * A response type for Catalog Entity Ancestor information.
+ * The response type for {@link CatalogClient.getEntityAncestors}.
  *
  * @public
  */
-declare type CatalogEntityAncestorsResponse = {
-    root: EntityName;
-    items: {
+interface GetEntityAncestorsResponse {
+    rootEntityRef: string;
+    items: Array<{
         entity: Entity;
-        parents: EntityName[];
-    }[];
-};
+        parentEntityRefs: string[];
+    }>;
+}
 /**
- * A response type for the result of a catalog operation in list form.
+ * Options you can pass into a catalog request for additional information.
  *
  * @public
  */
-declare type CatalogListResponse<T> = {
-    items: T[];
+interface CatalogRequestOptions {
+    token?: string;
+}
+/**
+ * Entity location for a specific entity.
+ *
+ * @public
+ */
+declare type Location = {
+    id: string;
+} & LocationSpec;
+/**
+ * The request type for {@link CatalogClient.addLocation}.
+ *
+ * @public
+ */
+declare type AddLocationRequest = {
+    type?: string;
+    target: string;
+    dryRun?: boolean;
+    presence?: 'optional' | 'required';
 };
 /**
- * Options you can pass into a catalog request for additional information.
+ * The response type for {@link CatalogClient.addLocation}.
  *
  * @public
  */
-declare type CatalogRequestOptions = {
-    token?: string;
+declare type AddLocationResponse = {
+    location: Location;
+    entities: Entity[];
+    exists?: boolean;
 };
 /**
- * Public functions for interacting with the Catalog API.
+ * A client for interacting with the Backstage software catalog through its API.
  *
  * @public
  */
 interface CatalogApi {
     /**
-     * Gets the Entities from the catalog based on your request and options.
-     *
-     * @param request - An object with your filters and fields.
-     * @param options - An object with your preferred options.
-     *
-     * @returns A CatalogListResponse with items typed Catalog Model Entity.
+     * Lists catalog entities.
      *
+     * @param request - Request parameters
+     * @param options - Additional options
      */
-    getEntities(request?: CatalogEntitiesRequest, options?: CatalogRequestOptions): Promise<CatalogListResponse<Entity>>;
+    getEntities(request?: GetEntitiesRequest, options?: CatalogRequestOptions): Promise<GetEntitiesResponse>;
     /**
-     * Gets the Entity ancestor information from the catalog based on your request and options.
+     * Gets entity ancestor information, i.e. the hierarchy of parent entities
+     * whose processing resulted in a given entity appearing in the catalog.
      *
-     * @param request - An object with your filters and fields.
-     * @param options - An object with your preferred options.
-     *
-     * @returns A CatalogEntityAncestorsResponse.
+     * @param request - Request parameters
+     * @param options - Additional options
      */
-    getEntityAncestors(request: CatalogEntityAncestorsRequest, options?: CatalogRequestOptions): Promise<CatalogEntityAncestorsResponse>;
+    getEntityAncestors(request: GetEntityAncestorsRequest, options?: CatalogRequestOptions): Promise<GetEntityAncestorsResponse>;
     /**
-     * Gets a single Entity from the catalog by Entity name.
-     *
-     * @param name - A complete Entity name, with the full kind-namespace-name triplet.
-     * @param options - An object with your preferred options.
+     * Gets a single entity from the catalog by its ref (kind, namespace, name)
+     * triplet.
      *
-     * @returns A {@link catalog-model#Entity}.
+     * @param name - A complete entity ref
+     * @param options - Additional options
      */
     getEntityByName(name: EntityName, options?: CatalogRequestOptions): Promise<Entity | undefined>;
     /**
-     * Removes a single Entity from the catalog by Entity UID.
-     *
-     * @param uid - A string of the Entity UID.
-     * @param options - An object with your preferred options.
+     * Removes a single entity from the catalog by entity UID.
      *
+     * @param uid - An entity UID
+     * @param options - Additional options
      */
     removeEntityByUid(uid: string, options?: CatalogRequestOptions): Promise<void>;
     /**
-     * Refreshes an Entity in the catalog.
-     *
-     * @param entityRef - A string in the form of 'Kind/default:foo'.
-     * @param options - An object with your preferred options.
+     * Refreshes (marks for reprocessing) an entity in the catalog.
      *
+     * @param entityRef - An entity ref on string form (e.g.
+     *        'component/default:my-component')
+     * @param options - Additional options
      */
     refreshEntity(entityRef: string, options?: CatalogRequestOptions): Promise<void>;
     /**
-     * Gets a Location object by ID from the catalog.
+     * Gets a registered location by its ID.
      *
-     * @param id - A string in of the Location Id.
-     * @param options - An object with your preferred options.
-     *
-     * @returns A {@link catalog-model#Location_2}.
+     * @param id - A location ID
+     * @param options - Additional options
      */
     getLocationById(id: string, options?: CatalogRequestOptions): Promise<Location | undefined>;
     /**
-     * Gets origin location by Entity.
-     *
-     * @param entity - An {@link catalog-model#Entity}.
-     * @param options - An object with your preferred options.
-     *
-     * @returns A {@link catalog-model#Location_2}.
-     */
-    getOriginLocationByEntity(entity: Entity, options?: CatalogRequestOptions): Promise<Location | undefined>;
-    /**
-     * Gets Location by Entity.
-     *
-     * @param entity - An {@link catalog-model#Entity}.
-     * @param options - An object with your preferred options.
+     * Gets a registered location by its ref.
      *
-     * @returns A {@link catalog-model#Location_2}.
+     * @param locationRef - A location ref, e.g. "url:https://github.com/..."
+     * @param options - Additional options
      */
-    getLocationByEntity(entity: Entity, options?: CatalogRequestOptions): Promise<Location | undefined>;
+    getLocationByRef(locationRef: string, options?: CatalogRequestOptions): Promise<Location | undefined>;
     /**
-     * Adds a Location.
-     *
-     * @param location - A request type for adding a Location to the catalog.
-     * @param options - An object with your preferred options.
+     * Registers a new location.
      *
-     * @returns A AddLocationResponse.
+     * @param location - Request parameters
+     * @param options - Additional options
      */
     addLocation(location: AddLocationRequest, options?: CatalogRequestOptions): Promise<AddLocationResponse>;
     /**
-     * Removes a Location by Id.
-     *
-     * @param id - A string in of the Location Id.
-     * @param options - An object with your preferred options.
+     * Removes a registered Location by its ID.
      *
+     * @param id - A location ID
+     * @param options - Additional options
      */
     removeLocationById(id: string, options?: CatalogRequestOptions): Promise<void>;
 }
-/**
- * A request type for adding a Location to the catalog.
- *
- * @public
- */
-declare type AddLocationRequest = {
-    type?: string;
-    target: string;
-    dryRun?: boolean;
-    presence?: 'optional' | 'required';
-};
-/**
- * A response type for adding a Location to the catalog.
- *
- * @public
- */
-declare type AddLocationResponse = {
-    location: Location;
-    entities: Entity[];
-    exists?: boolean;
-};
 
 /**
- * This is a copy of the DiscoveryApi, to avoid importing core-plugin-api.
+ * A frontend and backend compatible client for communicating with the Backstage
+ * software catalog.
  *
  * @public
  */
-declare type DiscoveryApi = {
-    getBaseUrl(pluginId: string): Promise<string>;
-};
-
-/**
- * This is a copy of FetchApi, to avoid importing core-plugin-api.
- *
- * @public
- */
-declare type FetchApi = {
-    fetch: typeof fetch;
-};
-
-/**
- * A frontend and backend compatible client for communicating with the Backstage Catalog.
- *
- * @public
- * */
 declare class CatalogClient implements CatalogApi {
     private readonly discoveryApi;
     private readonly fetchApi;
     constructor(options: {
-        discoveryApi: DiscoveryApi;
-        fetchApi?: FetchApi;
+        discoveryApi: {
+            getBaseUrl(pluginId: string): Promise<string>;
+        };
+        fetchApi?: {
+            fetch: typeof fetch;
+        };
     });
     /**
-     * Gets the Ancestors of an Entity.
-     *
-     * @param request - A request type for retrieving Entity ancestors.
-     * @param options - An object with your preferred options.
-     *
-     * @returns A CatalogEntityAncestorsResponse.
-     *
-     * @public
+     * {@inheritdoc CatalogApi.getEntityAncestors}
      */
-    getEntityAncestors(request: CatalogEntityAncestorsRequest, options?: CatalogRequestOptions): Promise<CatalogEntityAncestorsResponse>;
+    getEntityAncestors(request: GetEntityAncestorsRequest, options?: CatalogRequestOptions): Promise<GetEntityAncestorsResponse>;
     /**
-     * Gets a Location by Id.
-     *
-     * @param id - A string containing the Id.
-     * @param options - An object with your preferred options.
-     *
-     * @returns A {@link catalog-model#Location_2}.
-     *
-     * @public
+     * {@inheritdoc CatalogApi.getLocationById}
      */
     getLocationById(id: string, options?: CatalogRequestOptions): Promise<Location | undefined>;
     /**
-     * Gets a set of Entities.
-     *
-     * @param request - A request type for retrieving an Entity.
-     * @param options - An object with your preferred options.
-     *
-     * @returns A CatalogListResponse.
-     *
-     * @public
+     * {@inheritdoc CatalogApi.getEntities}
      */
-    getEntities(request?: CatalogEntitiesRequest, options?: CatalogRequestOptions): Promise<CatalogListResponse<Entity>>;
+    getEntities(request?: GetEntitiesRequest, options?: CatalogRequestOptions): Promise<GetEntitiesResponse>;
     /**
-     * Gets a given Entity based on a provided name.
-     *
-     * @param compoundName - A string containing the name.
-     * @param options - An object with your preferred options.
-     *
-     * @returns An {@link catalog-model#Entity}.
-     *
-     * @public
+     * {@inheritdoc CatalogApi.getEntityByName}
      */
     getEntityByName(compoundName: EntityName, options?: CatalogRequestOptions): Promise<Entity | undefined>;
     /**
-     * Refreshes an Entity.
-     *
-     * @param entityRef - A string containing the entityREf
-     * @param options - An object with your preferred options.
-     *
-     * @public
+     * {@inheritdoc CatalogApi.refreshEntity}
      */
     refreshEntity(entityRef: string, options?: CatalogRequestOptions): Promise<void>;
     /**
-     * Adds a location.
-     *
-     * @param options - An object with your preferred options.
-     * @param AddLocationRequest - A request object for adding locations.
-     *
-     * @returns An AddLocationResponse
-     *
-     * @public
+     * {@inheritdoc CatalogApi.addLocation}
      */
     addLocation({ type, target, dryRun, presence }: AddLocationRequest, options?: CatalogRequestOptions): Promise<AddLocationResponse>;
     /**
-     *  Gets an origin Location By Entity.
-     *
-     * @param entity - An Entity
-     * @param options - An object with your preferred options.
-     *
-     * @returns A {@link catalog-model#Location_2}.
-     *
-     * @public
+     * @deprecated please use getLocationByRef instead
      */
     getOriginLocationByEntity(entity: Entity, options?: CatalogRequestOptions): Promise<Location | undefined>;
     /**
-     * Gets a Location by Entity.
-     *
-     * @param entity - An Entity
-     * @param options - An object with your preferred options.
-     *
-     * @returns A {@link catalog-model#Location_2}.
-     *
-     * @public
+     * @deprecated please use getLocationByRef instead
      */
     getLocationByEntity(entity: Entity, options?: CatalogRequestOptions): Promise<Location | undefined>;
     /**
-     * Removes a location as identified by Id.
-     *
-     * @param id - A string containing the Id
-     * @param options - An object with your preferred options.
-     *
-     * @public
+     * {@inheritdoc CatalogApi.getLocationByRef}
+     */
+    getLocationByRef(locationRef: string, options?: CatalogRequestOptions): Promise<Location | undefined>;
+    /**
+     * {@inheritdoc CatalogApi.removeLocationById}
      */
     removeLocationById(id: string, options?: CatalogRequestOptions): Promise<void>;
     /**
-     * Removes an Entity as identified by Uid.
-     *
-     * @param uid - A string containing the Uid
-     * @param options - An object with your preferred options.
-     *
-     * @public
+     * {@inheritdoc CatalogApi.removeEntityByUid}
      */
     removeEntityByUid(uid: string, options?: CatalogRequestOptions): Promise<void>;
     private requestIgnored;
@@ -385,4 +300,25 @@ declare class CatalogClient implements CatalogApi {
  */
 declare const ENTITY_STATUS_CATALOG_PROCESSING_TYPE = "backstage.io/catalog-processing";
 
-export { AddLocationRequest, AddLocationResponse, CATALOG_FILTER_EXISTS, CatalogApi, CatalogClient, CatalogEntitiesRequest, CatalogEntityAncestorsRequest, CatalogEntityAncestorsResponse, CatalogListResponse, CatalogRequestOptions, DiscoveryApi, ENTITY_STATUS_CATALOG_PROCESSING_TYPE, FetchApi };
+/**
+ * @public
+ * @deprecated use GetEntitiesRequest instead
+ */
+declare type CatalogEntitiesRequest = GetEntitiesRequest;
+/**
+ * @public
+ * @deprecated use GetEntitiesResponse instead
+ */
+declare type CatalogListResponse<_Entity> = GetEntitiesResponse;
+/**
+ * @public
+ * @deprecated use GetEntityAncestorsRequest instead
+ */
+declare type CatalogEntityAncestorsRequest = GetEntityAncestorsRequest;
+/**
+ * @public
+ * @deprecated use GetEntityAncestorsResponse instead
+ */
+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 };

package/dist/index.esm.js

@@ -1,8 +1,8 @@
-import { parseEntityRef, ORIGIN_LOCATION_ANNOTATION, stringifyLocationReference, LOCATION_ANNOTATION, stringifyEntityRef } from '@backstage/catalog-model';
+import { parseEntityRef, ANNOTATION_ORIGIN_LOCATION, stringifyLocationRef, ANNOTATION_LOCATION, stringifyEntityRef } from '@backstage/catalog-model';
 import { ResponseError } from '@backstage/errors';
 import crossFetch from 'cross-fetch';
 
-const CATALOG_FILTER_EXISTS = Symbol("CATALOG_FILTER_EXISTS");
+const CATALOG_FILTER_EXISTS = Symbol.for("CATALOG_FILTER_EXISTS_0e15b590c0b343a2bae3e787e84c2111");
 
 class CatalogClient {
   constructor(options) {
@@ -107,21 +107,25 @@ class CatalogClient {
   }
   async getOriginLocationByEntity(entity, options) {
     var _a;
-    const locationCompound = (_a = entity.metadata.annotations) == null ? void 0 : _a[ORIGIN_LOCATION_ANNOTATION];
+    const locationCompound = (_a = entity.metadata.annotations) == null ? void 0 : _a[ANNOTATION_ORIGIN_LOCATION];
     if (!locationCompound) {
       return void 0;
     }
     const all = await this.requestRequired("GET", "/locations", options);
-    return all.map((r) => r.data).find((l) => locationCompound === stringifyLocationReference(l));
+    return all.map((r) => r.data).find((l) => locationCompound === stringifyLocationRef(l));
   }
   async getLocationByEntity(entity, options) {
     var _a;
-    const locationCompound = (_a = entity.metadata.annotations) == null ? void 0 : _a[LOCATION_ANNOTATION];
+    const locationCompound = (_a = entity.metadata.annotations) == null ? void 0 : _a[ANNOTATION_LOCATION];
     if (!locationCompound) {
       return void 0;
     }
     const all = await this.requestRequired("GET", "/locations", options);
-    return all.map((r) => r.data).find((l) => locationCompound === stringifyLocationReference(l));
+    return all.map((r) => r.data).find((l) => locationCompound === stringifyLocationRef(l));
+  }
+  async getLocationByRef(locationRef, options) {
+    const all = await this.requestRequired("GET", "/locations", options);
+    return all.map((r) => r.data).find((l) => locationRef === stringifyLocationRef(l));
   }
   async removeLocationById(id, options) {
     await this.requestIgnored("DELETE", `/locations/${encodeURIComponent(id)}`, options);

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, Location } from '@backstage/catalog-model';\n\n/**\n * A Symbol to define if a catalog filter exists or not.\n *\n * @public\n */\nexport const CATALOG_FILTER_EXISTS = Symbol('CATALOG_FILTER_EXISTS');\n\n/**\n * A request type for retrieving catalog Entities.\n *\n * @public\n */\nexport type CatalogEntitiesRequest = {\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 * A request type for Catalog Entity Ancestor information.\n *\n * @public\n */\nexport type CatalogEntityAncestorsRequest = {\n  entityRef: string;\n};\n\n/**\n * A response type for Catalog Entity Ancestor information.\n *\n * @public\n */\nexport type CatalogEntityAncestorsResponse = {\n  root: EntityName;\n  items: { entity: Entity; parents: EntityName[] }[];\n};\n\n/**\n * A response type for the result of a catalog operation in list form.\n *\n * @public\n */\nexport type CatalogListResponse<T> = {\n  items: T[];\n};\n\n/**\n * Options you can pass into a catalog request for additional information.\n *\n * @public\n */\nexport type CatalogRequestOptions = {\n  token?: string;\n};\n\n/**\n * Public functions for interacting with the Catalog API.\n *\n * @public\n */\nexport interface CatalogApi {\n  /**\n   * Gets the Entities from the catalog based on your request and options.\n   *\n   * @param request - An object with your filters and fields.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A CatalogListResponse with items typed Catalog Model Entity.\n   *\n   */\n  getEntities(\n    request?: CatalogEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<CatalogListResponse<Entity>>;\n  /**\n   * Gets the Entity ancestor information from the catalog based on your request and options.\n   *\n   * @param request - An object with your filters and fields.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A CatalogEntityAncestorsResponse.\n   */\n  getEntityAncestors(\n    request: CatalogEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<CatalogEntityAncestorsResponse>;\n  /**\n   * Gets a single Entity from the catalog by Entity name.\n   *\n   * @param name - A complete Entity name, with the full kind-namespace-name triplet.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Entity}.\n   */\n  getEntityByName(\n    name: EntityName,\n    options?: CatalogRequestOptions,\n  ): Promise<Entity | undefined>;\n  /**\n   * Removes a single Entity from the catalog by Entity UID.\n   *\n   * @param uid - A string of the Entity UID.\n   * @param options - An object with your preferred options.\n   *\n   */\n  removeEntityByUid(\n    uid: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n  /**\n   * Refreshes an Entity in the catalog.\n   *\n   * @param entityRef - A string in the form of 'Kind/default:foo'.\n   * @param options - An object with your preferred options.\n   *\n   */\n  refreshEntity(\n    entityRef: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n\n  // Locations\n  /**\n   * Gets a Location object by ID from the catalog.\n   *\n   * @param id - A string in of the Location Id.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   */\n  getLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n  /**\n   * Gets origin location by Entity.\n   *\n   * @param entity - An {@link catalog-model#Entity}.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   */\n  getOriginLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n  /**\n   * Gets Location by Entity.\n   *\n   * @param entity - An {@link catalog-model#Entity}.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   */\n  getLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined>;\n  /**\n   * Adds a Location.\n   *\n   * @param location - A request type for adding a Location to the catalog.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A AddLocationResponse.\n   */\n  addLocation(\n    location: AddLocationRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<AddLocationResponse>;\n  /**\n   * Removes a Location by Id.\n   *\n   * @param id - A string in of the Location Id.\n   * @param options - An object with your preferred options.\n   *\n   */\n  removeLocationById(\n    id: string,\n    options?: CatalogRequestOptions,\n  ): Promise<void>;\n}\n\n/**\n * A request type for adding a Location to the catalog.\n *\n * @public\n */\nexport type AddLocationRequest = {\n  type?: string;\n  target: string;\n  dryRun?: boolean;\n  presence?: 'optional' | 'required';\n};\n\n/**\n * A response type for adding a Location to the catalog.\n *\n * @public\n */\nexport type AddLocationResponse = {\n  location: Location;\n  entities: Entity[];\n  // Exists is only set in DryRun mode.\n  exists?: boolean;\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  Entity,\n  EntityName,\n  Location,\n  LOCATION_ANNOTATION,\n  ORIGIN_LOCATION_ANNOTATION,\n  parseEntityRef,\n  stringifyEntityRef,\n  stringifyLocationReference,\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  CatalogEntitiesRequest,\n  CatalogListResponse,\n  CatalogRequestOptions,\n  CatalogEntityAncestorsRequest,\n  CatalogEntityAncestorsResponse,\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 Catalog.\n *\n * @public\n * */\nexport class CatalogClient implements CatalogApi {\n  private readonly discoveryApi: DiscoveryApi;\n  private readonly fetchApi: FetchApi;\n\n  constructor(options: { discoveryApi: DiscoveryApi; fetchApi?: FetchApi }) {\n    this.discoveryApi = options.discoveryApi;\n    this.fetchApi = options.fetchApi || { fetch: crossFetch };\n  }\n\n  /**\n   * Gets the Ancestors of an Entity.\n   *\n   * @param request - A request type for retrieving Entity ancestors.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A CatalogEntityAncestorsResponse.\n   *\n   * @public\n   */\n  async getEntityAncestors(\n    request: CatalogEntityAncestorsRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<CatalogEntityAncestorsResponse> {\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   * Gets a Location by Id.\n   *\n   * @param id - A string containing the Id.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   *\n   * @public\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   * Gets a set of Entities.\n   *\n   * @param request - A request type for retrieving an Entity.\n   * @param options - An object with your preferred options.\n   *\n   * @returns A CatalogListResponse.\n   *\n   * @public\n   */\n  async getEntities(\n    request?: CatalogEntitiesRequest,\n    options?: CatalogRequestOptions,\n  ): Promise<CatalogListResponse<Entity>> {\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   * Gets a given Entity based on a provided name.\n   *\n   * @param compoundName - A string containing the name.\n   * @param options - An object with your preferred options.\n   *\n   * @returns An {@link catalog-model#Entity}.\n   *\n   * @public\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   * Refreshes an Entity.\n   *\n   * @param entityRef - A string containing the entityREf\n   * @param options - An object with your preferred options.\n   *\n   * @public\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   * Adds a location.\n   *\n   * @param options - An object with your preferred options.\n   * @param AddLocationRequest - A request object for adding locations.\n   *\n   * @returns An AddLocationResponse\n   *\n   * @public\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   *  Gets an origin Location By Entity.\n   *\n   * @param entity - An Entity\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   *\n   * @public\n   */\n  async getOriginLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound =\n      entity.metadata.annotations?.[ORIGIN_LOCATION_ANNOTATION];\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 === stringifyLocationReference(l));\n  }\n\n  /**\n   * Gets a Location by Entity.\n   *\n   * @param entity - An Entity\n   * @param options - An object with your preferred options.\n   *\n   * @returns A {@link catalog-model#Location_2}.\n   *\n   * @public\n   */\n  async getLocationByEntity(\n    entity: Entity,\n    options?: CatalogRequestOptions,\n  ): Promise<Location | undefined> {\n    const locationCompound = entity.metadata.annotations?.[LOCATION_ANNOTATION];\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 === stringifyLocationReference(l));\n  }\n\n  /**\n   * Removes a location as identified by Id.\n   *\n   * @param id - A string containing the Id\n   * @param options - An object with your preferred options.\n   *\n   * @public\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   * Removes an Entity as identified by Uid.\n   *\n   * @param uid - A string containing the Uid\n   * @param options - An object with your preferred options.\n   *\n   * @public\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, 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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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/catalog-client",
   "description": "An isomorphic client for the catalog backend",
-  "version": "0.5.5-next.0",
+  "version": "0.7.1",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -12,6 +12,9 @@
     "module": "dist/index.esm.js",
     "types": "dist/index.d.ts"
   },
+  "backstage": {
+    "role": "common-library"
+  },
   "homepage": "https://backstage.io",
   "repository": {
     "type": "git",
@@ -22,26 +25,26 @@
     "backstage"
   ],
   "scripts": {
-    "build": "backstage-cli build",
-    "lint": "backstage-cli lint",
-    "test": "backstage-cli test",
-    "prepack": "backstage-cli prepack",
-    "postpack": "backstage-cli postpack",
-    "clean": "backstage-cli clean"
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "clean": "backstage-cli package clean"
   },
   "dependencies": {
-    "@backstage/catalog-model": "^0.9.10-next.0",
-    "@backstage/errors": "^0.2.0",
-    "cross-fetch": "^3.0.6"
+    "@backstage/catalog-model": "^0.10.1",
+    "@backstage/errors": "^0.2.2",
+    "cross-fetch": "^3.1.5"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.12.0-next.0",
+    "@backstage/cli": "^0.14.0",
     "@types/jest": "^26.0.7",
     "msw": "^0.35.0"
   },
   "files": [
     "dist"
   ],
-  "gitHead": "31184691d5a38cb78b091c8f7ad6db80604519a6",
+  "gitHead": "e244b348c473700e7d5e5fbcef38bd9f9fd1d0ba",
   "module": "dist/index.esm.js"
 }