npm - @backstage/catalog-client - Versions diffs - 0.7.0 → 0.8.0 - Mend

@backstage/catalog-client 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,45 @@
 # @backstage/catalog-client
+## 0.8.0
+### Minor Changes
+- bb2ba5f10d: **BREAKING**: Removed the old deprecated request/response types:
+  - `CatalogEntitiesRequest` - please use `GetEntitiesRequest` instead
+  - `CatalogEntityAncestorsRequest` - please use `GetEntityAncestorsRequest` instead
+  - `CatalogEntityAncestorsResponse` - please use `GetEntityAncestorsResponse` instead
+  - `CatalogListResponse` - please use `GetEntitiesResponse` instead
+### Patch Changes
+- a52f69987a: **DEPRECATION**: Deprecated `getEntityByName` from `CatalogApi` and added `getEntityByRef` instead, which accepts both string and compound ref forms.
+- 36aa63022b: Use `CompoundEntityRef` instead of `EntityName`, and `getCompoundEntityRef` instead of `getEntityName`, from `@backstage/catalog-model`.
+- Updated dependencies
+  - @backstage/catalog-model@0.12.0
+## 0.7.2
+### Patch Changes
+- ed09ad8093: Updated usage of the `LocationSpec` type from `@backstage/catalog-model`, which is deprecated.
+- 46dee04eba: Deprecated `AddLocationRequest.presence`, as it is already being ignored.
+- 6e1cbc12a6: Added `CatalogApi.getEntityFacets`. Marking this as a breaking change since it
+  is a non-optional addition to the API and depends on the backend being in place.
+  If you are mocking this interface in your tests, you will need to add an extra
+  `getEntityFacets: jest.fn()` or similar to that interface.
+- Updated dependencies
+  - @backstage/catalog-model@0.11.0
+## 0.7.1
+### Patch Changes
+- 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

package/dist/index.cjs.js CHANGED Viewed

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

package/dist/index.cjs.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.cjs.js","sources":["../src/types/api.ts","../src/CatalogClient.ts","../src/types/status.ts"],"sourcesContent":["/\n Copyright 2021 The Backstage Authors\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n /\n\nimport { Entity, EntityName, LocationSpec } from '@backstage/catalog-model';\n\n/\n This symbol can be used in place of a value when passed to filters in e.g.\n * {@link CatalogClient.getEntities}, to signify that you want to filter on the\n * presence of that key no matter what its value is.\n \n @public\n /\nexport const CATALOG_FILTER_EXISTS = Symbol.for(\n // Random UUID to ensure no collisions\n 'CATALOG_FILTER_EXISTS_0e15b590c0b343a2bae3e787e84c2111',\n);\n\n/\n The request type for {@link CatalogClient.getEntities}.\n \n @public\n /\nexport interface GetEntitiesRequest {\n /\n If given, return only entities that match the given patterns.\n \n @remarks\n \n If multiple filter sets are given as an array, then there is effectively an\n * OR between each filter set.\n \n Within one filter set, there is effectively an AND between the various\n * keys.\n \n Within one key, if there are more than one value, then there is effectively\n * an OR between them.\n \n Example: For an input of\n \n ```\n * [\n * { kind: ['API', 'Component'] },\n * { 'metadata.name': 'a', 'metadata.namespace': 'b' }\n * ]\n * ```\n \n This effectively means\n \n ```\n * (kind = EITHER 'API' OR 'Component')\n * OR\n * (metadata.name = 'a' AND metadata.namespace = 'b' )\n * ```\n \n Each key is a dot separated path in each object.\n \n As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`\n * (exported from this package), which means that you assert on the existence\n * of that key, no matter what its value is.\n /\n filter?:\n \| Record<string, string \| symbol \| (string \| symbol)[]>[]\n \| Record<string, string \| symbol \| (string \| symbol)[]>\n \| undefined;\n /\n If given, return only the parts of each entity that match those dot\n * separated paths in each object.\n \n @remarks\n \n Example: For an input of `['kind', 'metadata.annotations']`, then response\n * objects will be shaped like\n \n ```\n * {\n * \"kind\": \"Component\",\n * \"metadata\": {\n * \"annotations\": {\n * \"foo\": \"bar\"\n * }\n * }\n * }\n * ```\n /\n fields?: string[] \| undefined;\n /\n If given, skips over the first N items in the result set.\n /\n offset?: number;\n /\n If given, returns at most N items from the result set.\n /\n limit?: number;\n /\n If given, skips over all items before that cursor as returned by a previous\n * request.\n /\n after?: string;\n}\n\n/\n The response type for {@link CatalogClient.getEntities}.\n \n @public\n /\nexport interface GetEntitiesResponse {\n items: Entity[];\n}\n\n/\n The request type for {@link CatalogClient.getEntityAncestors}.\n \n @public\n /\nexport interface GetEntityAncestorsRequest {\n entityRef: string;\n}\n\n/\n The response type for {@link CatalogClient.getEntityAncestors}.\n \n @public\n /\nexport interface GetEntityAncestorsResponse {\n rootEntityRef: string;\n items: Array<{\n entity: Entity;\n parentEntityRefs: string[];\n }>;\n}\n\n/\n Options you can pass into a catalog request for additional information.\n \n @public\n /\nexport interface CatalogRequestOptions {\n token?: string;\n}\n\n/\n Entity location for a specific entity.\n \n @public\n /\nexport type Location = {\n id: string;\n} & LocationSpec;\n\n/\n The request type for {@link CatalogClient.addLocation}.\n \n @public\n /\nexport type AddLocationRequest = {\n type?: string;\n target: string;\n dryRun?: boolean;\n presence?: 'optional' \| 'required';\n};\n\n/\n The response type for {@link CatalogClient.addLocation}.\n \n @public\n /\nexport type AddLocationResponse = {\n location: Location;\n entities: Entity[];\n // Only set in dryRun mode.\n exists?: boolean;\n};\n\n/\n A client for interacting with the Backstage software catalog through its API.\n \n @public\n /\nexport interface CatalogApi {\n /\n Lists catalog entities.\n \n @param request - Request parameters\n * @param options - Additional options\n /\n getEntities(\n request?: GetEntitiesRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntitiesResponse>;\n\n /\n Gets entity ancestor information, i.e. the hierarchy of parent entities\n * whose processing resulted in a given entity appearing in the catalog.\n \n @param request - Request parameters\n * @param options - Additional options\n /\n getEntityAncestors(\n request: GetEntityAncestorsRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntityAncestorsResponse>;\n\n /\n Gets a single entity from the catalog by its ref (kind, namespace, name)\n * triplet.\n \n @param name - A complete entity ref\n * @param options - Additional options\n /\n getEntityByName(\n name: EntityName,\n options?: CatalogRequestOptions,\n ): Promise<Entity \| undefined>;\n\n /\n Removes a single entity from the catalog by entity UID.\n \n @param uid - An entity UID\n * @param options - Additional options\n /\n removeEntityByUid(\n uid: string,\n options?: CatalogRequestOptions,\n ): Promise<void>;\n\n /\n Refreshes (marks for reprocessing) an entity in the catalog.\n \n @param entityRef - An entity ref on string form (e.g.\n * 'component/default:my-component')\n * @param options - Additional options\n /\n refreshEntity(\n entityRef: string,\n options?: CatalogRequestOptions,\n ): Promise<void>;\n\n // Locations\n\n /\n Gets a registered location by its ID.\n \n @param id - A location ID\n * @param options - Additional options\n /\n getLocationById(\n id: string,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined>;\n\n /\n Gets a registered location by its ref.\n \n @param locationRef - A location ref, e.g. \"url:https://github.com/...\"\n * @param options - Additional options\n /\n getLocationByRef(\n locationRef: string,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined>;\n\n /\n Registers a new location.\n \n @param location - Request parameters\n * @param options - Additional options\n /\n addLocation(\n location: AddLocationRequest,\n options?: CatalogRequestOptions,\n ): Promise<AddLocationResponse>;\n\n /\n Removes a registered Location by its ID.\n \n @param id - A location ID\n * @param options - Additional options\n /\n removeLocationById(\n id: string,\n options?: CatalogRequestOptions,\n ): Promise<void>;\n}\n","/\n * Copyright 2020 The Backstage Authors\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n /\n\nimport {\n ANNOTATION_LOCATION,\n ANNOTATION_ORIGIN_LOCATION,\n Entity,\n EntityName,\n parseEntityRef,\n stringifyEntityRef,\n stringifyLocationRef,\n} from '@backstage/catalog-model';\nimport { ResponseError } from '@backstage/errors';\nimport crossFetch from 'cross-fetch';\nimport {\n CATALOG_FILTER_EXISTS,\n AddLocationRequest,\n AddLocationResponse,\n CatalogApi,\n GetEntitiesRequest,\n GetEntitiesResponse,\n CatalogRequestOptions,\n GetEntityAncestorsRequest,\n GetEntityAncestorsResponse,\n Location,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\nimport { FetchApi } from './types/fetch';\n\n/\n A frontend and backend compatible client for communicating with the Backstage\n * software catalog.\n \n @public\n /\nexport class CatalogClient implements CatalogApi {\n private readonly discoveryApi: DiscoveryApi;\n private readonly fetchApi: FetchApi;\n\n constructor(options: {\n discoveryApi: { getBaseUrl(pluginId: string): Promise<string> };\n fetchApi?: { fetch: typeof fetch };\n }) {\n this.discoveryApi = options.discoveryApi;\n this.fetchApi = options.fetchApi \|\| { fetch: crossFetch };\n }\n\n /\n {@inheritdoc CatalogApi.getEntityAncestors}\n /\n async getEntityAncestors(\n request: GetEntityAncestorsRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntityAncestorsResponse> {\n const { kind, namespace, name } = parseEntityRef(request.entityRef);\n return await this.requestRequired(\n 'GET',\n `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n namespace,\n )}/${encodeURIComponent(name)}/ancestry`,\n options,\n );\n }\n\n /\n {@inheritdoc CatalogApi.getLocationById}\n /\n async getLocationById(\n id: string,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined> {\n return await this.requestOptional(\n 'GET',\n `/locations/${encodeURIComponent(id)}`,\n options,\n );\n }\n\n /\n {@inheritdoc CatalogApi.getEntities}\n /\n async getEntities(\n request?: GetEntitiesRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntitiesResponse> {\n const { filter = [], fields = [], offset, limit, after } = request ?? {};\n const filterItems = [filter].flat();\n const params: string[] = [];\n\n // filter param can occur multiple times, for example\n // /api/catalog/entities?filter=metadata.name=wayback-search,kind=component&filter=metadata.name=www-artist,kind=component'\n // the \"outer array\" defined by `filter` occurrences corresponds to \"anyOf\" filters\n // the \"inner array\" defined within a `filter` param corresponds to \"allOf\" filters\n for (const filterItem of filterItems) {\n const filterParts: string[] = [];\n for (const [key, value] of Object.entries(filterItem)) {\n for (const v of [value].flat()) {\n if (v === CATALOG_FILTER_EXISTS) {\n filterParts.push(encodeURIComponent(key));\n } else if (typeof v === 'string') {\n filterParts.push(\n `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,\n );\n }\n }\n }\n\n if (filterParts.length) {\n params.push(`filter=${filterParts.join(',')}`);\n }\n }\n\n if (fields.length) {\n params.push(`fields=${fields.map(encodeURIComponent).join(',')}`);\n }\n\n if (offset !== undefined) {\n params.push(`offset=${offset}`);\n }\n if (limit !== undefined) {\n params.push(`limit=${limit}`);\n }\n if (after !== undefined) {\n params.push(`after=${encodeURIComponent(after)}`);\n }\n\n const query = params.length ? `?${params.join('&')}` : '';\n const entities: Entity[] = await this.requestRequired(\n 'GET',\n `/entities${query}`,\n options,\n );\n\n const refCompare = (a: Entity, b: Entity) => {\n // in case field filtering is used, these fields might not be part of the response\n if (\n a.metadata?.name === undefined \|\|\n a.kind === undefined \|\|\n b.metadata?.name === undefined \|\|\n b.kind === undefined\n ) {\n return 0;\n }\n\n const aRef = stringifyEntityRef(a);\n const bRef = stringifyEntityRef(b);\n if (aRef < bRef) {\n return -1;\n }\n if (aRef > bRef) {\n return 1;\n }\n return 0;\n };\n\n return { items: entities.sort(refCompare) };\n }\n\n /\n {@inheritdoc CatalogApi.getEntityByName}\n /\n async getEntityByName(\n compoundName: EntityName,\n options?: CatalogRequestOptions,\n ): Promise<Entity \| undefined> {\n const { kind, namespace = 'default', name } = compoundName;\n return this.requestOptional(\n 'GET',\n `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n namespace,\n )}/${encodeURIComponent(name)}`,\n options,\n );\n }\n\n /\n {@inheritdoc CatalogApi.refreshEntity}\n /\n async refreshEntity(entityRef: string, options?: CatalogRequestOptions) {\n const response = await this.fetchApi.fetch(\n `${await this.discoveryApi.getBaseUrl('catalog')}/refresh`,\n {\n headers: {\n 'Content-Type': 'application/json',\n ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n },\n method: 'POST',\n body: JSON.stringify({ entityRef }),\n },\n );\n\n if (response.status !== 200) {\n throw new Error(await response.text());\n }\n }\n\n /\n {@inheritdoc CatalogApi.addLocation}\n /\n async addLocation(\n { type = 'url', target, dryRun, presence }: AddLocationRequest,\n options?: CatalogRequestOptions,\n ): Promise<AddLocationResponse> {\n const response = await this.fetchApi.fetch(\n `${await this.discoveryApi.getBaseUrl('catalog')}/locations${\n dryRun ? '?dryRun=true' : ''\n }`,\n {\n headers: {\n 'Content-Type': 'application/json',\n ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n },\n method: 'POST',\n body: JSON.stringify({ type, target, presence }),\n },\n );\n\n if (response.status !== 201) {\n throw new Error(await response.text());\n }\n\n const { location, entities, exists } = await response.json();\n\n if (!location) {\n throw new Error(`Location wasn't added: ${target}`);\n }\n\n return {\n location,\n entities,\n exists,\n };\n }\n\n /\n @deprecated please use getLocationByRef instead\n /\n async getOriginLocationByEntity(\n entity: Entity,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined> {\n const locationCompound =\n entity.metadata.annotations?.[ANNOTATION_ORIGIN_LOCATION];\n if (!locationCompound) {\n return undefined;\n }\n const all: { data: Location }[] = await this.requestRequired(\n 'GET',\n '/locations',\n options,\n );\n return all\n .map(r => r.data)\n .find(l => locationCompound === stringifyLocationRef(l));\n }\n\n /\n @deprecated please use getLocationByRef instead\n /\n async getLocationByEntity(\n entity: Entity,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined> {\n const locationCompound = entity.metadata.annotations?.[ANNOTATION_LOCATION];\n if (!locationCompound) {\n return undefined;\n }\n const all: { data: Location }[] = await this.requestRequired(\n 'GET',\n '/locations',\n options,\n );\n return all\n .map(r => r.data)\n .find(l => locationCompound === stringifyLocationRef(l));\n }\n\n /\n {@inheritdoc CatalogApi.getLocationByRef}\n /\n async getLocationByRef(\n locationRef: string,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined> {\n const all: { data: Location }[] = await this.requestRequired(\n 'GET',\n '/locations',\n options,\n );\n return all\n .map(r => r.data)\n .find(l => locationRef === stringifyLocationRef(l));\n }\n\n /\n {@inheritdoc CatalogApi.removeLocationById}\n /\n async removeLocationById(\n id: string,\n options?: CatalogRequestOptions,\n ): Promise<void> {\n await this.requestIgnored(\n 'DELETE',\n `/locations/${encodeURIComponent(id)}`,\n options,\n );\n }\n\n /\n {@inheritdoc CatalogApi.removeEntityByUid}\n /\n async removeEntityByUid(\n uid: string,\n options?: CatalogRequestOptions,\n ): Promise<void> {\n await this.requestIgnored(\n 'DELETE',\n `/entities/by-uid/${encodeURIComponent(uid)}`,\n options,\n );\n }\n\n //\n // Private methods\n //\n\n private async requestIgnored(\n method: string,\n path: string,\n options?: CatalogRequestOptions,\n ): Promise<void> {\n const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n const headers: Record<string, string> = options?.token\n ? { Authorization: `Bearer ${options.token}` }\n : {};\n const response = await this.fetchApi.fetch(url, { method, headers });\n\n if (!response.ok) {\n throw await ResponseError.fromResponse(response);\n }\n }\n\n private async requestRequired(\n method: string,\n path: string,\n options?: CatalogRequestOptions,\n ): Promise<any> {\n const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n const headers: Record<string, string> = options?.token\n ? { Authorization: `Bearer ${options.token}` }\n : {};\n const response = await this.fetchApi.fetch(url, { method, headers });\n\n if (!response.ok) {\n throw await ResponseError.fromResponse(response);\n }\n\n return await response.json();\n }\n\n private async requestOptional(\n method: string,\n path: string,\n options?: CatalogRequestOptions,\n ): Promise<any \| undefined> {\n const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n const headers: Record<string, string> = options?.token\n ? { Authorization: `Bearer ${options.token}` }\n : {};\n const response = await this.fetchApi.fetch(url, { method, headers });\n\n if (!response.ok) {\n if (response.status === 404) {\n return undefined;\n }\n throw await ResponseError.fromResponse(response);\n }\n\n return await response.json();\n }\n}\n","/\n * Copyright 2021 The Backstage Authors\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n /\n\n/\n The entity `status.items[].type` for the status of the processing engine in\n * regards to an entity.\n \n @public\n */\nexport const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =\n 'backstage.io/catalog-processing';\n"],"names":["crossFetch","parseEntityRef","stringifyEntityRef","ANNOTATION_ORIGIN_LOCATION","stringifyLocationRef","ANNOTATION_LOCATION","ResponseError"],"mappings":";;;;;;;;;;;;MAyBa,wBAAwB,OAAO,IAE1C;;oBCqB+C;AAAA,EAI/C,YAAY,SAGT;AACD,SAAK,eAAe,QAAQ;AAC5B,SAAK,WAAW,QAAQ,YAAY,EAAE,OAAOA;AAAA;AAAA,QAMzC,mBACJ,SACA,SACqC;AACrC,UAAM,EAAE,MAAM,WAAW,SAASC,4BAAe,QAAQ;AACzD,WAAO,MAAM,KAAK,gBAChB,OACA,qBAAqB,mBAAmB,SAAS,mBAC/C,cACG,mBAAmB,kBACxB;AAAA;AAAA,QAOE,gBACJ,IACA,SAC+B;AAC/B,WAAO,MAAM,KAAK,gBAChB,OACA,cAAc,mBAAmB,OACjC;AAAA;AAAA,QAOE,YACJ,SACA,SAC8B;AAC9B,UAAM,EAAE,SAAS,IAAI,SAAS,IAAI,QAAQ,OAAO,UAAU,4BAAW;AACtE,UAAM,cAAc,CAAC,QAAQ;AAC7B,UAAM,SAAmB;AAMzB,eAAW,cAAc,aAAa;AACpC,YAAM,cAAwB;AAC9B,iBAAW,CAAC,KAAK,UAAU,OAAO,QAAQ,aAAa;AACrD,mBAAW,KAAK,CAAC,OAAO,QAAQ;AAC9B,cAAI,MAAM,uBAAuB;AAC/B,wBAAY,KAAK,mBAAmB;AAAA,qBAC3B,OAAO,MAAM,UAAU;AAChC,wBAAY,KACV,GAAG,mBAAmB,QAAQ,mBAAmB;AAAA;AAAA;AAAA;AAMzD,UAAI,YAAY,QAAQ;AACtB,eAAO,KAAK,UAAU,YAAY,KAAK;AAAA;AAAA;AAI3C,QAAI,OAAO,QAAQ;AACjB,aAAO,KAAK,UAAU,OAAO,IAAI,oBAAoB,KAAK;AAAA;AAG5D,QAAI,WAAW,QAAW;AACxB,aAAO,KAAK,UAAU;AAAA;AAExB,QAAI,UAAU,QAAW;AACvB,aAAO,KAAK,SAAS;AAAA;AAEvB,QAAI,UAAU,QAAW;AACvB,aAAO,KAAK,SAAS,mBAAmB;AAAA;AAG1C,UAAM,QAAQ,OAAO,SAAS,IAAI,OAAO,KAAK,SAAS;AACvD,UAAM,WAAqB,MAAM,KAAK,gBACpC,OACA,YAAY,SACZ;AAGF,UAAM,aAAa,CAAC,GAAW,MAAc;AAlJjD;AAoJM,UACE,SAAE,aAAF,mBAAY,UAAS,UACrB,EAAE,SAAS,UACX,SAAE,aAAF,mBAAY,UAAS,UACrB,EAAE,SAAS,QACX;AACA,eAAO;AAAA;AAGT,YAAM,OAAOC,gCAAmB;AAChC,YAAM,OAAOA,gCAAmB;AAChC,UAAI,OAAO,MAAM;AACf,eAAO;AAAA;AAET,UAAI,OAAO,MAAM;AACf,eAAO;AAAA;AAET,aAAO;AAAA;AAGT,WAAO,EAAE,OAAO,SAAS,KAAK;AAAA;AAAA,QAM1B,gBACJ,cACA,SAC6B;AAC7B,UAAM,EAAE,MAAM,YAAY,WAAW,SAAS;AAC9C,WAAO,KAAK,gBACV,OACA,qBAAqB,mBAAmB,SAAS,mBAC/C,cACG,mBAAmB,SACxB;AAAA;AAAA,QAOE,cAAc,WAAmB,SAAiC;AACtE,UAAM,WAAW,MAAM,KAAK,SAAS,MACnC,GAAG,MAAM,KAAK,aAAa,WAAW,sBACtC;AAAA,MACE,SAAS;AAAA,QACP,gBAAgB;AAAA,WACZ,oCAAS,UAAS,EAAE,eAAe,UAAU,mCAAS;AAAA;AAAA,MAE5D,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU,EAAE;AAAA;AAI3B,QAAI,SAAS,WAAW,KAAK;AAC3B,YAAM,IAAI,MAAM,MAAM,SAAS;AAAA;AAAA;AAAA,QAO7B,YACJ,EAAE,OAAO,OAAO,QAAQ,QAAQ,YAChC,SAC8B;AAC9B,UAAM,WAAW,MAAM,KAAK,SAAS,MACnC,GAAG,MAAM,KAAK,aAAa,WAAW,uBACpC,SAAS,iBAAiB,MAE5B;AAAA,MACE,SAAS;AAAA,QACP,gBAAgB;AAAA,WACZ,oCAAS,UAAS,EAAE,eAAe,UAAU,mCAAS;AAAA;AAAA,MAE5D,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU,EAAE,MAAM,QAAQ;AAAA;AAIzC,QAAI,SAAS,WAAW,KAAK;AAC3B,YAAM,IAAI,MAAM,MAAM,SAAS;AAAA;AAGjC,UAAM,EAAE,UAAU,UAAU,WAAW,MAAM,SAAS;AAEtD,QAAI,CAAC,UAAU;AACb,YAAM,IAAI,MAAM,0BAA0B;AAAA;AAG5C,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA;AAAA;AAAA,QAOE,0BACJ,QACA,SAC+B;AA7PnC;AA8PI,UAAM,mBACJ,aAAO,SAAS,gBAAhB,mBAA8BC;AAChC,QAAI,CAAC,kBAAkB;AACrB,aAAO;AAAA;AAET,UAAM,MAA4B,MAAM,KAAK,gBAC3C,OACA,cACA;AAEF,WAAO,IACJ,IAAI,OAAK,EAAE,MACX,KAAK,OAAK,qBAAqBC,kCAAqB;AAAA;AAAA,QAMnD,oBACJ,QACA,SAC+B;AAnRnC;AAoRI,UAAM,mBAAmB,aAAO,SAAS,gBAAhB,mBAA8BC;AACvD,QAAI,CAAC,kBAAkB;AACrB,aAAO;AAAA;AAET,UAAM,MAA4B,MAAM,KAAK,gBAC3C,OACA,cACA;AAEF,WAAO,IACJ,IAAI,OAAK,EAAE,MACX,KAAK,OAAK,qBAAqBD,kCAAqB;AAAA;AAAA,QAMnD,iBACJ,aACA,SAC+B;AAC/B,UAAM,MAA4B,MAAM,KAAK,gBAC3C,OACA,cACA;AAEF,WAAO,IACJ,IAAI,OAAK,EAAE,MACX,KAAK,OAAK,gBAAgBA,kCAAqB;AAAA;AAAA,QAM9C,mBACJ,IACA,SACe;AACf,UAAM,KAAK,eACT,UACA,cAAc,mBAAmB,OACjC;AAAA;AAAA,QAOE,kBACJ,KACA,SACe;AACf,UAAM,KAAK,eACT,UACA,oBAAoB,mBAAmB,QACvC;AAAA;AAAA,QAQU,eACZ,QACA,MACA,SACe;AACf,UAAM,MAAM,GAAG,MAAM,KAAK,aAAa,WAAW,aAAa;AAC/D,UAAM,UAAkC,oCAAS,SAC7C,EAAE,eAAe,UAAU,QAAQ,YACnC;AACJ,UAAM,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,EAAE,QAAQ;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,MAAME,qBAAc,aAAa;AAAA;AAAA;AAAA,QAI7B,gBACZ,QACA,MACA,SACc;AACd,UAAM,MAAM,GAAG,MAAM,KAAK,aAAa,WAAW,aAAa;AAC/D,UAAM,UAAkC,oCAAS,SAC7C,EAAE,eAAe,UAAU,QAAQ,YACnC;AACJ,UAAM,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,EAAE,QAAQ;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,MAAMA,qBAAc,aAAa;AAAA;AAGzC,WAAO,MAAM,SAAS;AAAA;AAAA,QAGV,gBACZ,QACA,MACA,SAC0B;AAC1B,UAAM,MAAM,GAAG,MAAM,KAAK,aAAa,WAAW,aAAa;AAC/D,UAAM,UAAkC,oCAAS,SAC7C,EAAE,eAAe,UAAU,QAAQ,YACnC;AACJ,UAAM,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,EAAE,QAAQ;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,UAAI,SAAS,WAAW,KAAK;AAC3B,eAAO;AAAA;AAET,YAAM,MAAMA,qBAAc,aAAa;AAAA;AAGzC,WAAO,MAAM,SAAS;AAAA;AAAA;;MCjXb,wCACX;;;;;;"}
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 { CompoundEntityRef, Entity } from '@backstage/catalog-model';\n\n/\n This symbol can be used in place of a value when passed to filters in e.g.\n * {@link CatalogClient.getEntities}, to signify that you want to filter on the\n * presence of that key no matter what its value is.\n \n @public\n /\nexport const CATALOG_FILTER_EXISTS = Symbol.for(\n // Random UUID to ensure no collisions\n 'CATALOG_FILTER_EXISTS_0e15b590c0b343a2bae3e787e84c2111',\n);\n\n/\n The request type for {@link CatalogClient.getEntities}.\n \n @public\n /\nexport interface GetEntitiesRequest {\n /\n If given, return only entities that match the given patterns.\n \n @remarks\n \n If multiple filter sets are given as an array, then there is effectively an\n * OR between each filter set.\n \n Within one filter set, there is effectively an AND between the various\n * keys.\n \n Within one key, if there are more than one value, then there is effectively\n * an OR between them.\n \n Example: For an input of\n \n ```\n * [\n * { kind: ['API', 'Component'] },\n * { 'metadata.name': 'a', 'metadata.namespace': 'b' }\n * ]\n * ```\n \n This effectively means\n \n ```\n * (kind = EITHER 'API' OR 'Component')\n * OR\n * (metadata.name = 'a' AND metadata.namespace = 'b' )\n * ```\n \n Each key is a dot separated path in each object.\n \n As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`\n * (exported from this package), which means that you assert on the existence\n * of that key, no matter what its value is.\n /\n filter?:\n \| Record<string, string \| symbol \| (string \| symbol)[]>[]\n \| Record<string, string \| symbol \| (string \| symbol)[]>\n \| undefined;\n /\n If given, return only the parts of each entity that match those dot\n * separated paths in each object.\n \n @remarks\n \n Example: For an input of `['kind', 'metadata.annotations']`, then response\n * objects will be shaped like\n \n ```\n * {\n * \"kind\": \"Component\",\n * \"metadata\": {\n * \"annotations\": {\n * \"foo\": \"bar\"\n * }\n * }\n * }\n * ```\n /\n fields?: string[] \| undefined;\n /\n If given, skips over the first N items in the result set.\n /\n offset?: number;\n /\n If given, returns at most N items from the result set.\n /\n limit?: number;\n /\n If given, skips over all items before that cursor as returned by a previous\n * request.\n /\n after?: string;\n}\n\n/\n The response type for {@link CatalogClient.getEntities}.\n \n @public\n /\nexport interface GetEntitiesResponse {\n items: Entity[];\n}\n\n/\n The request type for {@link CatalogClient.getEntityAncestors}.\n \n @public\n /\nexport interface GetEntityAncestorsRequest {\n entityRef: string;\n}\n\n/\n The response type for {@link CatalogClient.getEntityAncestors}.\n \n @public\n /\nexport interface GetEntityAncestorsResponse {\n rootEntityRef: string;\n items: Array<{\n entity: Entity;\n parentEntityRefs: string[];\n }>;\n}\n\n/\n The request type for {@link CatalogClient.getEntityFacets}.\n \n @public\n /\nexport interface GetEntityFacetsRequest {\n /\n If given, return only entities that match the given patterns.\n \n @remarks\n \n If multiple filter sets are given as an array, then there is effectively an\n * OR between each filter set.\n \n Within one filter set, there is effectively an AND between the various\n * keys.\n \n Within one key, if there are more than one value, then there is effectively\n * an OR between them.\n \n Example: For an input of\n \n ```\n * [\n * { kind: ['API', 'Component'] },\n * { 'metadata.name': 'a', 'metadata.namespace': 'b' }\n * ]\n * ```\n \n This effectively means\n \n ```\n * (kind = EITHER 'API' OR 'Component')\n * OR\n * (metadata.name = 'a' AND metadata.namespace = 'b' )\n * ```\n \n Each key is a dot separated path in each object.\n \n As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`\n * (exported from this package), which means that you assert on the existence\n * of that key, no matter what its value is.\n /\n filter?:\n \| Record<string, string \| symbol \| (string \| symbol)[]>[]\n \| Record<string, string \| symbol \| (string \| symbol)[]>\n \| undefined;\n /\n Dot separated paths for the facets to extract from each entity.\n \n @remarks\n \n Example: For an input of `['kind', 'metadata.annotations.backstage.io/orphan']`, then the\n * response will be shaped like\n \n ```\n * {\n * \"facets\": {\n * \"kind\": [\n * { \"key\": \"Component\", \"count\": 22 },\n * { \"key\": \"API\", \"count\": 13 }\n * ],\n * \"metadata.annotations.backstage.io/orphan\": [\n * { \"key\": \"true\", \"count\": 2 }\n * ]\n * }\n * }\n * ```\n /\n facets: string[];\n}\n\n/\n The response type for {@link CatalogClient.getEntityFacets}.\n \n @public\n /\nexport interface GetEntityFacetsResponse {\n /\n The computed facets, one entry per facet in the request.\n /\n facets: Record<string, Array<{ value: string; count: number }>>;\n}\n\n/\n Options you can pass into a catalog request for additional information.\n \n @public\n /\nexport interface CatalogRequestOptions {\n token?: string;\n}\n\n/\n Entity location for a specific entity.\n \n @public\n /\nexport type Location = {\n id: string;\n type: string;\n target: string;\n /* @deprecated This field is is ignored /\n presence?: 'optional' \| 'required';\n};\n\n/\n The request type for {@link CatalogClient.addLocation}.\n \n @public\n /\nexport type AddLocationRequest = {\n type?: string;\n target: string;\n dryRun?: boolean;\n /* @deprecated This field is is ignored /\n presence?: 'optional' \| 'required';\n};\n\n/\n The response type for {@link CatalogClient.addLocation}.\n \n @public\n /\nexport type AddLocationResponse = {\n location: Location;\n entities: Entity[];\n // Only set in dryRun mode.\n exists?: boolean;\n};\n\n/\n A client for interacting with the Backstage software catalog through its API.\n \n @public\n /\nexport interface CatalogApi {\n /\n Lists catalog entities.\n \n @param request - Request parameters\n * @param options - Additional options\n /\n getEntities(\n request?: GetEntitiesRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntitiesResponse>;\n\n /\n Gets entity ancestor information, i.e. the hierarchy of parent entities\n * whose processing resulted in a given entity appearing in the catalog.\n \n @param request - Request parameters\n * @param options - Additional options\n /\n getEntityAncestors(\n request: GetEntityAncestorsRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntityAncestorsResponse>;\n\n /\n Gets a single entity from the catalog by its ref (kind, namespace, name)\n * triplet.\n \n @param entityRef - A complete entity ref, either on string or compound form\n * @param options - Additional options\n * @returns The matching entity, or undefined if there was no entity with that ref\n /\n getEntityByRef(\n entityRef: string \| CompoundEntityRef,\n options?: CatalogRequestOptions,\n ): Promise<Entity \| undefined>;\n\n /\n Gets a single entity from the catalog by its ref (kind, namespace, name)\n * triplet.\n \n @deprecated Use getEntityRef instead\n * @param name - A complete entity ref\n * @param options - Additional options\n /\n getEntityByName(\n name: CompoundEntityRef,\n options?: CatalogRequestOptions,\n ): Promise<Entity \| undefined>;\n\n /\n Removes a single entity from the catalog by entity UID.\n \n @param uid - An entity UID\n * @param options - Additional options\n /\n removeEntityByUid(\n uid: string,\n options?: CatalogRequestOptions,\n ): Promise<void>;\n\n /\n Refreshes (marks for reprocessing) an entity in the catalog.\n \n @param entityRef - An entity ref on string form (e.g.\n * 'component/default:my-component')\n * @param options - Additional options\n /\n refreshEntity(\n entityRef: string,\n options?: CatalogRequestOptions,\n ): Promise<void>;\n\n /\n Gets a summary of field facets of entities in the catalog.\n \n @param request - Request parameters\n * @param options - Additional options\n /\n getEntityFacets(\n request: GetEntityFacetsRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntityFacetsResponse>;\n\n // Locations\n\n /\n Gets a registered location by its ID.\n \n @param id - A location ID\n * @param options - Additional options\n /\n getLocationById(\n id: string,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined>;\n\n /\n Gets a registered location by its ref.\n \n @param locationRef - A location ref, e.g. \"url:https://github.com/...\"\n * @param options - Additional options\n /\n getLocationByRef(\n locationRef: string,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined>;\n\n /\n Registers a new location.\n \n @param location - Request parameters\n * @param options - Additional options\n /\n addLocation(\n location: AddLocationRequest,\n options?: CatalogRequestOptions,\n ): Promise<AddLocationResponse>;\n\n /\n Removes a registered Location by its ID.\n \n @param id - A location ID\n * @param options - Additional options\n /\n removeLocationById(\n id: string,\n options?: CatalogRequestOptions,\n ): Promise<void>;\n}\n","/\n * Copyright 2020 The Backstage Authors\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n /\n\nimport {\n ANNOTATION_LOCATION,\n ANNOTATION_ORIGIN_LOCATION,\n Entity,\n CompoundEntityRef,\n parseEntityRef,\n stringifyEntityRef,\n stringifyLocationRef,\n} from '@backstage/catalog-model';\nimport { ResponseError } from '@backstage/errors';\nimport crossFetch from 'cross-fetch';\nimport {\n CATALOG_FILTER_EXISTS,\n AddLocationRequest,\n AddLocationResponse,\n CatalogApi,\n GetEntitiesRequest,\n GetEntitiesResponse,\n CatalogRequestOptions,\n GetEntityAncestorsRequest,\n GetEntityAncestorsResponse,\n Location,\n GetEntityFacetsRequest,\n GetEntityFacetsResponse,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\nimport { FetchApi } from './types/fetch';\n\n/\n A frontend and backend compatible client for communicating with the Backstage\n * software catalog.\n \n @public\n /\nexport class CatalogClient implements CatalogApi {\n private readonly discoveryApi: DiscoveryApi;\n private readonly fetchApi: FetchApi;\n\n constructor(options: {\n discoveryApi: { getBaseUrl(pluginId: string): Promise<string> };\n fetchApi?: { fetch: typeof fetch };\n }) {\n this.discoveryApi = options.discoveryApi;\n this.fetchApi = options.fetchApi \|\| { fetch: crossFetch };\n }\n\n /\n {@inheritdoc CatalogApi.getEntityAncestors}\n /\n async getEntityAncestors(\n request: GetEntityAncestorsRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntityAncestorsResponse> {\n const { kind, namespace, name } = parseEntityRef(request.entityRef);\n return await this.requestRequired(\n 'GET',\n `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n namespace,\n )}/${encodeURIComponent(name)}/ancestry`,\n options,\n );\n }\n\n /\n {@inheritdoc CatalogApi.getLocationById}\n /\n async getLocationById(\n id: string,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined> {\n return await this.requestOptional(\n 'GET',\n `/locations/${encodeURIComponent(id)}`,\n options,\n );\n }\n\n /\n {@inheritdoc CatalogApi.getEntities}\n /\n async getEntities(\n request?: GetEntitiesRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntitiesResponse> {\n const { filter = [], fields = [], offset, limit, after } = request ?? {};\n const params: string[] = [];\n\n // filter param can occur multiple times, for example\n // /api/catalog/entities?filter=metadata.name=wayback-search,kind=component&filter=metadata.name=www-artist,kind=component'\n // the \"outer array\" defined by `filter` occurrences corresponds to \"anyOf\" filters\n // the \"inner array\" defined within a `filter` param corresponds to \"allOf\" filters\n for (const filterItem of [filter].flat()) {\n const filterParts: string[] = [];\n for (const [key, value] of Object.entries(filterItem)) {\n for (const v of [value].flat()) {\n if (v === CATALOG_FILTER_EXISTS) {\n filterParts.push(encodeURIComponent(key));\n } else if (typeof v === 'string') {\n filterParts.push(\n `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,\n );\n }\n }\n }\n\n if (filterParts.length) {\n params.push(`filter=${filterParts.join(',')}`);\n }\n }\n\n if (fields.length) {\n params.push(`fields=${fields.map(encodeURIComponent).join(',')}`);\n }\n\n if (offset !== undefined) {\n params.push(`offset=${offset}`);\n }\n if (limit !== undefined) {\n params.push(`limit=${limit}`);\n }\n if (after !== undefined) {\n params.push(`after=${encodeURIComponent(after)}`);\n }\n\n const query = params.length ? `?${params.join('&')}` : '';\n const entities: Entity[] = await this.requestRequired(\n 'GET',\n `/entities${query}`,\n options,\n );\n\n const refCompare = (a: Entity, b: Entity) => {\n // in case field filtering is used, these fields might not be part of the response\n if (\n a.metadata?.name === undefined \|\|\n a.kind === undefined \|\|\n b.metadata?.name === undefined \|\|\n b.kind === undefined\n ) {\n return 0;\n }\n\n const aRef = stringifyEntityRef(a);\n const bRef = stringifyEntityRef(b);\n if (aRef < bRef) {\n return -1;\n }\n if (aRef > bRef) {\n return 1;\n }\n return 0;\n };\n\n return { items: entities.sort(refCompare) };\n }\n\n /\n {@inheritdoc CatalogApi.getEntityByRef}\n /\n async getEntityByRef(\n entityRef: string \| CompoundEntityRef,\n options?: CatalogRequestOptions,\n ): Promise<Entity \| undefined> {\n const { kind, namespace, name } = parseEntityRef(entityRef);\n return this.requestOptional(\n 'GET',\n `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n namespace,\n )}/${encodeURIComponent(name)}`,\n options,\n );\n }\n\n // NOTE(freben): When we deprecate getEntityByName from the interface, we may\n // still want to leave this implementation in place for quite some time\n // longer, to minimize the risk for breakages. Suggested date for removal:\n // August 2022\n /\n {@inheritdoc CatalogApi.getEntityByName}\n /\n async getEntityByName(\n compoundName: CompoundEntityRef,\n options?: CatalogRequestOptions,\n ): Promise<Entity \| undefined> {\n const { kind, namespace = 'default', name } = compoundName;\n return this.requestOptional(\n 'GET',\n `/entities/by-name/${encodeURIComponent(kind)}/${encodeURIComponent(\n namespace,\n )}/${encodeURIComponent(name)}`,\n options,\n );\n }\n\n /\n {@inheritdoc CatalogApi.refreshEntity}\n /\n async refreshEntity(entityRef: string, options?: CatalogRequestOptions) {\n const response = await this.fetchApi.fetch(\n `${await this.discoveryApi.getBaseUrl('catalog')}/refresh`,\n {\n headers: {\n 'Content-Type': 'application/json',\n ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n },\n method: 'POST',\n body: JSON.stringify({ entityRef }),\n },\n );\n\n if (response.status !== 200) {\n throw new Error(await response.text());\n }\n }\n\n /\n {@inheritdoc CatalogApi.getEntityFacets}\n /\n async getEntityFacets(\n request: GetEntityFacetsRequest,\n options?: CatalogRequestOptions,\n ): Promise<GetEntityFacetsResponse> {\n const { filter = [], facets } = request;\n const params: string[] = [];\n\n // filter param can occur multiple times, for example\n // /api/catalog/entities?filter=metadata.name=wayback-search,kind=component&filter=metadata.name=www-artist,kind=component'\n // the \"outer array\" defined by `filter` occurrences corresponds to \"anyOf\" filters\n // the \"inner array\" defined within a `filter` param corresponds to \"allOf\" filters\n for (const filterItem of [filter].flat()) {\n const filterParts: string[] = [];\n for (const [key, value] of Object.entries(filterItem)) {\n for (const v of [value].flat()) {\n if (v === CATALOG_FILTER_EXISTS) {\n filterParts.push(encodeURIComponent(key));\n } else if (typeof v === 'string') {\n filterParts.push(\n `${encodeURIComponent(key)}=${encodeURIComponent(v)}`,\n );\n }\n }\n }\n\n if (filterParts.length) {\n params.push(`filter=${filterParts.join(',')}`);\n }\n }\n\n for (const facet of facets) {\n params.push(`facet=${encodeURIComponent(facet)}`);\n }\n\n const query = params.length ? `?${params.join('&')}` : '';\n return await this.requestOptional('GET', `/entity-facets${query}`, options);\n }\n\n /\n {@inheritdoc CatalogApi.addLocation}\n /\n async addLocation(\n { type = 'url', target, dryRun, presence }: AddLocationRequest,\n options?: CatalogRequestOptions,\n ): Promise<AddLocationResponse> {\n const response = await this.fetchApi.fetch(\n `${await this.discoveryApi.getBaseUrl('catalog')}/locations${\n dryRun ? '?dryRun=true' : ''\n }`,\n {\n headers: {\n 'Content-Type': 'application/json',\n ...(options?.token && { Authorization: `Bearer ${options?.token}` }),\n },\n method: 'POST',\n body: JSON.stringify({ type, target, presence }),\n },\n );\n\n if (response.status !== 201) {\n throw new Error(await response.text());\n }\n\n const { location, entities, exists } = await response.json();\n\n if (!location) {\n throw new Error(`Location wasn't added: ${target}`);\n }\n\n return {\n location,\n entities,\n exists,\n };\n }\n\n /\n @deprecated please use getLocationByRef instead\n /\n async getOriginLocationByEntity(\n entity: Entity,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined> {\n const locationCompound =\n entity.metadata.annotations?.[ANNOTATION_ORIGIN_LOCATION];\n if (!locationCompound) {\n return undefined;\n }\n const all: { data: Location }[] = await this.requestRequired(\n 'GET',\n '/locations',\n options,\n );\n return all\n .map(r => r.data)\n .find(l => locationCompound === stringifyLocationRef(l));\n }\n\n /\n @deprecated please use getLocationByRef instead\n /\n async getLocationByEntity(\n entity: Entity,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined> {\n const locationCompound = entity.metadata.annotations?.[ANNOTATION_LOCATION];\n if (!locationCompound) {\n return undefined;\n }\n const all: { data: Location }[] = await this.requestRequired(\n 'GET',\n '/locations',\n options,\n );\n return all\n .map(r => r.data)\n .find(l => locationCompound === stringifyLocationRef(l));\n }\n\n /\n {@inheritdoc CatalogApi.getLocationByRef}\n /\n async getLocationByRef(\n locationRef: string,\n options?: CatalogRequestOptions,\n ): Promise<Location \| undefined> {\n const all: { data: Location }[] = await this.requestRequired(\n 'GET',\n '/locations',\n options,\n );\n return all\n .map(r => r.data)\n .find(l => locationRef === stringifyLocationRef(l));\n }\n\n /\n {@inheritdoc CatalogApi.removeLocationById}\n /\n async removeLocationById(\n id: string,\n options?: CatalogRequestOptions,\n ): Promise<void> {\n await this.requestIgnored(\n 'DELETE',\n `/locations/${encodeURIComponent(id)}`,\n options,\n );\n }\n\n /\n {@inheritdoc CatalogApi.removeEntityByUid}\n /\n async removeEntityByUid(\n uid: string,\n options?: CatalogRequestOptions,\n ): Promise<void> {\n await this.requestIgnored(\n 'DELETE',\n `/entities/by-uid/${encodeURIComponent(uid)}`,\n options,\n );\n }\n\n //\n // Private methods\n //\n\n private async requestIgnored(\n method: string,\n path: string,\n options?: CatalogRequestOptions,\n ): Promise<void> {\n const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n const headers: Record<string, string> = options?.token\n ? { Authorization: `Bearer ${options.token}` }\n : {};\n const response = await this.fetchApi.fetch(url, { method, headers });\n\n if (!response.ok) {\n throw await ResponseError.fromResponse(response);\n }\n }\n\n private async requestRequired(\n method: string,\n path: string,\n options?: CatalogRequestOptions,\n ): Promise<any> {\n const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n const headers: Record<string, string> = options?.token\n ? { Authorization: `Bearer ${options.token}` }\n : {};\n const response = await this.fetchApi.fetch(url, { method, headers });\n\n if (!response.ok) {\n throw await ResponseError.fromResponse(response);\n }\n\n return await response.json();\n }\n\n private async requestOptional(\n method: string,\n path: string,\n options?: CatalogRequestOptions,\n ): Promise<any \| undefined> {\n const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;\n const headers: Record<string, string> = options?.token\n ? { Authorization: `Bearer ${options.token}` }\n : {};\n const response = await this.fetchApi.fetch(url, { method, headers });\n\n if (!response.ok) {\n if (response.status === 404) {\n return undefined;\n }\n throw await ResponseError.fromResponse(response);\n }\n\n return await response.json();\n }\n}\n","/\n * Copyright 2021 The Backstage Authors\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n /\n\n/\n The entity `status.items[].type` for the status of the processing engine in\n * regards to an entity.\n \n @public\n */\nexport const ENTITY_STATUS_CATALOG_PROCESSING_TYPE =\n 'backstage.io/catalog-processing';\n"],"names":["crossFetch","parseEntityRef","stringifyEntityRef","ANNOTATION_ORIGIN_LOCATION","stringifyLocationRef","ANNOTATION_LOCATION","ResponseError"],"mappings":";;;;;;;;;;;;MAyBa,wBAAwB,OAAO,IAE1C;;oBCuB+C;AAAA,EAI/C,YAAY,SAGT;AACD,SAAK,eAAe,QAAQ;AAC5B,SAAK,WAAW,QAAQ,YAAY,EAAE,OAAOA;AAAA;AAAA,QAMzC,mBACJ,SACA,SACqC;AACrC,UAAM,EAAE,MAAM,WAAW,SAASC,4BAAe,QAAQ;AACzD,WAAO,MAAM,KAAK,gBAChB,OACA,qBAAqB,mBAAmB,SAAS,mBAC/C,cACG,mBAAmB,kBACxB;AAAA;AAAA,QAOE,gBACJ,IACA,SAC+B;AAC/B,WAAO,MAAM,KAAK,gBAChB,OACA,cAAc,mBAAmB,OACjC;AAAA;AAAA,QAOE,YACJ,SACA,SAC8B;AAC9B,UAAM,EAAE,SAAS,IAAI,SAAS,IAAI,QAAQ,OAAO,UAAU,4BAAW;AACtE,UAAM,SAAmB;AAMzB,eAAW,cAAc,CAAC,QAAQ,QAAQ;AACxC,YAAM,cAAwB;AAC9B,iBAAW,CAAC,KAAK,UAAU,OAAO,QAAQ,aAAa;AACrD,mBAAW,KAAK,CAAC,OAAO,QAAQ;AAC9B,cAAI,MAAM,uBAAuB;AAC/B,wBAAY,KAAK,mBAAmB;AAAA,qBAC3B,OAAO,MAAM,UAAU;AAChC,wBAAY,KACV,GAAG,mBAAmB,QAAQ,mBAAmB;AAAA;AAAA;AAAA;AAMzD,UAAI,YAAY,QAAQ;AACtB,eAAO,KAAK,UAAU,YAAY,KAAK;AAAA;AAAA;AAI3C,QAAI,OAAO,QAAQ;AACjB,aAAO,KAAK,UAAU,OAAO,IAAI,oBAAoB,KAAK;AAAA;AAG5D,QAAI,WAAW,QAAW;AACxB,aAAO,KAAK,UAAU;AAAA;AAExB,QAAI,UAAU,QAAW;AACvB,aAAO,KAAK,SAAS;AAAA;AAEvB,QAAI,UAAU,QAAW;AACvB,aAAO,KAAK,SAAS,mBAAmB;AAAA;AAG1C,UAAM,QAAQ,OAAO,SAAS,IAAI,OAAO,KAAK,SAAS;AACvD,UAAM,WAAqB,MAAM,KAAK,gBACpC,OACA,YAAY,SACZ;AAGF,UAAM,aAAa,CAAC,GAAW,MAAc;AAnJjD;AAqJM,UACE,SAAE,aAAF,mBAAY,UAAS,UACrB,EAAE,SAAS,UACX,SAAE,aAAF,mBAAY,UAAS,UACrB,EAAE,SAAS,QACX;AACA,eAAO;AAAA;AAGT,YAAM,OAAOC,gCAAmB;AAChC,YAAM,OAAOA,gCAAmB;AAChC,UAAI,OAAO,MAAM;AACf,eAAO;AAAA;AAET,UAAI,OAAO,MAAM;AACf,eAAO;AAAA;AAET,aAAO;AAAA;AAGT,WAAO,EAAE,OAAO,SAAS,KAAK;AAAA;AAAA,QAM1B,eACJ,WACA,SAC6B;AAC7B,UAAM,EAAE,MAAM,WAAW,SAASD,4BAAe;AACjD,WAAO,KAAK,gBACV,OACA,qBAAqB,mBAAmB,SAAS,mBAC/C,cACG,mBAAmB,SACxB;AAAA;AAAA,QAWE,gBACJ,cACA,SAC6B;AAC7B,UAAM,EAAE,MAAM,YAAY,WAAW,SAAS;AAC9C,WAAO,KAAK,gBACV,OACA,qBAAqB,mBAAmB,SAAS,mBAC/C,cACG,mBAAmB,SACxB;AAAA;AAAA,QAOE,cAAc,WAAmB,SAAiC;AACtE,UAAM,WAAW,MAAM,KAAK,SAAS,MACnC,GAAG,MAAM,KAAK,aAAa,WAAW,sBACtC;AAAA,MACE,SAAS;AAAA,QACP,gBAAgB;AAAA,WACZ,oCAAS,UAAS,EAAE,eAAe,UAAU,mCAAS;AAAA;AAAA,MAE5D,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU,EAAE;AAAA;AAI3B,QAAI,SAAS,WAAW,KAAK;AAC3B,YAAM,IAAI,MAAM,MAAM,SAAS;AAAA;AAAA;AAAA,QAO7B,gBACJ,SACA,SACkC;AAClC,UAAM,EAAE,SAAS,IAAI,WAAW;AAChC,UAAM,SAAmB;AAMzB,eAAW,cAAc,CAAC,QAAQ,QAAQ;AACxC,YAAM,cAAwB;AAC9B,iBAAW,CAAC,KAAK,UAAU,OAAO,QAAQ,aAAa;AACrD,mBAAW,KAAK,CAAC,OAAO,QAAQ;AAC9B,cAAI,MAAM,uBAAuB;AAC/B,wBAAY,KAAK,mBAAmB;AAAA,qBAC3B,OAAO,MAAM,UAAU;AAChC,wBAAY,KACV,GAAG,mBAAmB,QAAQ,mBAAmB;AAAA;AAAA;AAAA;AAMzD,UAAI,YAAY,QAAQ;AACtB,eAAO,KAAK,UAAU,YAAY,KAAK;AAAA;AAAA;AAI3C,eAAW,SAAS,QAAQ;AAC1B,aAAO,KAAK,SAAS,mBAAmB;AAAA;AAG1C,UAAM,QAAQ,OAAO,SAAS,IAAI,OAAO,KAAK,SAAS;AACvD,WAAO,MAAM,KAAK,gBAAgB,OAAO,iBAAiB,SAAS;AAAA;AAAA,QAM/D,YACJ,EAAE,OAAO,OAAO,QAAQ,QAAQ,YAChC,SAC8B;AAC9B,UAAM,WAAW,MAAM,KAAK,SAAS,MACnC,GAAG,MAAM,KAAK,aAAa,WAAW,uBACpC,SAAS,iBAAiB,MAE5B;AAAA,MACE,SAAS;AAAA,QACP,gBAAgB;AAAA,WACZ,oCAAS,UAAS,EAAE,eAAe,UAAU,mCAAS;AAAA;AAAA,MAE5D,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU,EAAE,MAAM,QAAQ;AAAA;AAIzC,QAAI,SAAS,WAAW,KAAK;AAC3B,YAAM,IAAI,MAAM,MAAM,SAAS;AAAA;AAGjC,UAAM,EAAE,UAAU,UAAU,WAAW,MAAM,SAAS;AAEtD,QAAI,CAAC,UAAU;AACb,YAAM,IAAI,MAAM,0BAA0B;AAAA;AAG5C,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA;AAAA;AAAA,QAOE,0BACJ,QACA,SAC+B;AA5TnC;AA6TI,UAAM,mBACJ,aAAO,SAAS,gBAAhB,mBAA8BE;AAChC,QAAI,CAAC,kBAAkB;AACrB,aAAO;AAAA;AAET,UAAM,MAA4B,MAAM,KAAK,gBAC3C,OACA,cACA;AAEF,WAAO,IACJ,IAAI,OAAK,EAAE,MACX,KAAK,OAAK,qBAAqBC,kCAAqB;AAAA;AAAA,QAMnD,oBACJ,QACA,SAC+B;AAlVnC;AAmVI,UAAM,mBAAmB,aAAO,SAAS,gBAAhB,mBAA8BC;AACvD,QAAI,CAAC,kBAAkB;AACrB,aAAO;AAAA;AAET,UAAM,MAA4B,MAAM,KAAK,gBAC3C,OACA,cACA;AAEF,WAAO,IACJ,IAAI,OAAK,EAAE,MACX,KAAK,OAAK,qBAAqBD,kCAAqB;AAAA;AAAA,QAMnD,iBACJ,aACA,SAC+B;AAC/B,UAAM,MAA4B,MAAM,KAAK,gBAC3C,OACA,cACA;AAEF,WAAO,IACJ,IAAI,OAAK,EAAE,MACX,KAAK,OAAK,gBAAgBA,kCAAqB;AAAA;AAAA,QAM9C,mBACJ,IACA,SACe;AACf,UAAM,KAAK,eACT,UACA,cAAc,mBAAmB,OACjC;AAAA;AAAA,QAOE,kBACJ,KACA,SACe;AACf,UAAM,KAAK,eACT,UACA,oBAAoB,mBAAmB,QACvC;AAAA;AAAA,QAQU,eACZ,QACA,MACA,SACe;AACf,UAAM,MAAM,GAAG,MAAM,KAAK,aAAa,WAAW,aAAa;AAC/D,UAAM,UAAkC,oCAAS,SAC7C,EAAE,eAAe,UAAU,QAAQ,YACnC;AACJ,UAAM,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,EAAE,QAAQ;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,MAAME,qBAAc,aAAa;AAAA;AAAA;AAAA,QAI7B,gBACZ,QACA,MACA,SACc;AACd,UAAM,MAAM,GAAG,MAAM,KAAK,aAAa,WAAW,aAAa;AAC/D,UAAM,UAAkC,oCAAS,SAC7C,EAAE,eAAe,UAAU,QAAQ,YACnC;AACJ,UAAM,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,EAAE,QAAQ;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,MAAMA,qBAAc,aAAa;AAAA;AAGzC,WAAO,MAAM,SAAS;AAAA;AAAA,QAGV,gBACZ,QACA,MACA,SAC0B;AAC1B,UAAM,MAAM,GAAG,MAAM,KAAK,aAAa,WAAW,aAAa;AAC/D,UAAM,UAAkC,oCAAS,SAC7C,EAAE,eAAe,UAAU,QAAQ,YACnC;AACJ,UAAM,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,EAAE,QAAQ;AAE1D,QAAI,CAAC,SAAS,IAAI;AAChB,UAAI,SAAS,WAAW,KAAK;AAC3B,eAAO;AAAA;AAET,YAAM,MAAMA,qBAAc,aAAa;AAAA;AAGzC,WAAO,MAAM,SAAS;AAAA;AAAA;;MChbb,wCACX;;;;;;"}

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,415 @@
+import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
+/**
+ * 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;
+/**
+ * The request type for {@link CatalogClient.getEntities}.
+ *
+ * @public
+ */
+interface GetEntitiesRequest {
+    /**
+     * If given, return only entities that match the given patterns.
+     *
+     * @remarks
+     *
+     * If multiple filter sets are given as an array, then there is effectively an
+     * OR between each filter set.
+     *
+     * Within one filter set, there is effectively an AND between the various
+     * keys.
+     *
+     * Within one key, if there are more than one value, then there is effectively
+     * an OR between them.
+     *
+     * Example: For an input of
+     *
+     * ```
+     * [
+     *   { kind: ['API', 'Component'] },
+     *   { 'metadata.name': 'a', 'metadata.namespace': 'b' }
+     * ]
+     * ```
+     *
+     * This effectively means
+     *
+     * ```
+     * (kind = EITHER 'API' OR 'Component')
+     * OR
+     * (metadata.name = 'a' AND metadata.namespace = 'b' )
+     * ```
+     *
+     * Each key is a dot separated path in each object.
+     *
+     * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`
+     * (exported from this package), which means that you assert on the existence
+     * of that key, no matter what its value is.
+     */
+    filter?: Record<string, string | symbol | (string | symbol)[]>[] | Record<string, string | symbol | (string | symbol)[]> | undefined;
+    /**
+     * If given, return only the parts of each entity that match those dot
+     * separated paths in each object.
+     *
+     * @remarks
+     *
+     * Example: For an input of `['kind', 'metadata.annotations']`, then response
+     * objects will be shaped like
+     *
+     * ```
+     * {
+     *   "kind": "Component",
+     *   "metadata": {
+     *     "annotations": {
+     *       "foo": "bar"
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    fields?: string[] | undefined;
+    /**
+     * If given, skips over the first N items in the result set.
+     */
+    offset?: number;
+    /**
+     * If given, returns at most N items from the result set.
+     */
+    limit?: number;
+    /**
+     * If given, skips over all items before that cursor as returned by a previous
+     * request.
+     */
+    after?: string;
+}
+/**
+ * The response type for {@link CatalogClient.getEntities}.
+ *
+ * @public
+ */
+interface GetEntitiesResponse {
+    items: Entity[];
+}
+/**
+ * The request type for {@link CatalogClient.getEntityAncestors}.
+ *
+ * @public
+ */
+interface GetEntityAncestorsRequest {
+    entityRef: string;
+}
+/**
+ * The response type for {@link CatalogClient.getEntityAncestors}.
+ *
+ * @public
+ */
+interface GetEntityAncestorsResponse {
+    rootEntityRef: string;
+    items: Array<{
+        entity: Entity;
+        parentEntityRefs: string[];
+    }>;
+}
+/**
+ * The request type for {@link CatalogClient.getEntityFacets}.
+ *
+ * @public
+ */
+interface GetEntityFacetsRequest {
+    /**
+     * If given, return only entities that match the given patterns.
+     *
+     * @remarks
+     *
+     * If multiple filter sets are given as an array, then there is effectively an
+     * OR between each filter set.
+     *
+     * Within one filter set, there is effectively an AND between the various
+     * keys.
+     *
+     * Within one key, if there are more than one value, then there is effectively
+     * an OR between them.
+     *
+     * Example: For an input of
+     *
+     * ```
+     * [
+     *   { kind: ['API', 'Component'] },
+     *   { 'metadata.name': 'a', 'metadata.namespace': 'b' }
+     * ]
+     * ```
+     *
+     * This effectively means
+     *
+     * ```
+     * (kind = EITHER 'API' OR 'Component')
+     * OR
+     * (metadata.name = 'a' AND metadata.namespace = 'b' )
+     * ```
+     *
+     * Each key is a dot separated path in each object.
+     *
+     * As a value you can also pass in the symbol `CATALOG_FILTER_EXISTS`
+     * (exported from this package), which means that you assert on the existence
+     * of that key, no matter what its value is.
+     */
+    filter?: Record<string, string | symbol | (string | symbol)[]>[] | Record<string, string | symbol | (string | symbol)[]> | undefined;
+    /**
+     * Dot separated paths for the facets to extract from each entity.
+     *
+     * @remarks
+     *
+     * Example: For an input of `['kind', 'metadata.annotations.backstage.io/orphan']`, then the
+     * response will be shaped like
+     *
+     * ```
+     * {
+     *   "facets": {
+     *     "kind": [
+     *       { "key": "Component", "count": 22 },
+     *       { "key": "API", "count": 13 }
+     *     ],
+     *     "metadata.annotations.backstage.io/orphan": [
+     *       { "key": "true", "count": 2 }
+     *     ]
+     *   }
+     * }
+     * ```
+     */
+    facets: string[];
+}
+/**
+ * The response type for {@link CatalogClient.getEntityFacets}.
+ *
+ * @public
+ */
+interface GetEntityFacetsResponse {
+    /**
+     * The computed facets, one entry per facet in the request.
+     */
+    facets: Record<string, Array<{
+        value: string;
+        count: number;
+    }>>;
+}
+/**
+ * Options you can pass into a catalog request for additional information.
+ *
+ * @public
+ */
+interface CatalogRequestOptions {
+    token?: string;
+}
+/**
+ * Entity location for a specific entity.
+ *
+ * @public
+ */
+declare type Location = {
+    id: string;
+    type: string;
+    target: string;
+    /** @deprecated This field is is ignored */
+    presence?: 'optional' | 'required';
+};
+/**
+ * The request type for {@link CatalogClient.addLocation}.
+ *
+ * @public
+ */
+declare type AddLocationRequest = {
+    type?: string;
+    target: string;
+    dryRun?: boolean;
+    /** @deprecated This field is is ignored */
+    presence?: 'optional' | 'required';
+};
+/**
+ * The response type for {@link CatalogClient.addLocation}.
+ *
+ * @public
+ */
+declare type AddLocationResponse = {
+    location: Location;
+    entities: Entity[];
+    exists?: boolean;
+};
+/**
+ * A client for interacting with the Backstage software catalog through its API.
+ *
+ * @public
+ */
+interface CatalogApi {
+    /**
+     * Lists catalog entities.
+     *
+     * @param request - Request parameters
+     * @param options - Additional options
+     */
+    getEntities(request?: GetEntitiesRequest, options?: CatalogRequestOptions): Promise<GetEntitiesResponse>;
+    /**
+     * Gets entity ancestor information, i.e. the hierarchy of parent entities
+     * whose processing resulted in a given entity appearing in the catalog.
+     *
+     * @param request - Request parameters
+     * @param options - Additional options
+     */
+    getEntityAncestors(request: GetEntityAncestorsRequest, options?: CatalogRequestOptions): Promise<GetEntityAncestorsResponse>;
+    /**
+     * Gets a single entity from the catalog by its ref (kind, namespace, name)
+     * triplet.
+     *
+     * @param entityRef - A complete entity ref, either on string or compound form
+     * @param options - Additional options
+     * @returns The matching entity, or undefined if there was no entity with that ref
+     */
+    getEntityByRef(entityRef: string | CompoundEntityRef, options?: CatalogRequestOptions): Promise<Entity | undefined>;
+    /**
+     * Gets a single entity from the catalog by its ref (kind, namespace, name)
+     * triplet.
+     *
+     * @deprecated Use getEntityRef instead
+     * @param name - A complete entity ref
+     * @param options - Additional options
+     */
+    getEntityByName(name: CompoundEntityRef, options?: CatalogRequestOptions): Promise<Entity | undefined>;
+    /**
+     * 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 (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 summary of field facets of entities in the catalog.
+     *
+     * @param request - Request parameters
+     * @param options - Additional options
+     */
+    getEntityFacets(request: GetEntityFacetsRequest, options?: CatalogRequestOptions): Promise<GetEntityFacetsResponse>;
+    /**
+     * Gets a registered location by its ID.
+     *
+     * @param id - A location ID
+     * @param options - Additional options
+     */
+    getLocationById(id: string, options?: CatalogRequestOptions): Promise<Location | undefined>;
+    /**
+     * Gets a registered location by its ref.
+     *
+     * @param locationRef - A location ref, e.g. "url:https://github.com/..."
+     * @param options - Additional options
+     */
+    getLocationByRef(locationRef: string, options?: CatalogRequestOptions): Promise<Location | undefined>;
+    /**
+     * Registers a new location.
+     *
+     * @param location - Request parameters
+     * @param options - Additional options
+     */
+    addLocation(location: AddLocationRequest, options?: CatalogRequestOptions): Promise<AddLocationResponse>;
+    /**
+     * Removes a registered Location by its ID.
+     *
+     * @param id - A location ID
+     * @param options - Additional options
+     */
+    removeLocationById(id: string, options?: CatalogRequestOptions): Promise<void>;
+}
+/**
+ * A frontend and backend compatible client for communicating with the Backstage
+ * software catalog.
+ *
+ * @public
+ */
+declare class CatalogClient implements CatalogApi {
+    private readonly discoveryApi;
+    private readonly fetchApi;
+    constructor(options: {
+        discoveryApi: {
+            getBaseUrl(pluginId: string): Promise<string>;
+        };
+        fetchApi?: {
+            fetch: typeof fetch;
+        };
+    });
+    /**
+     * {@inheritdoc CatalogApi.getEntityAncestors}
+     */
+    getEntityAncestors(request: GetEntityAncestorsRequest, options?: CatalogRequestOptions): Promise<GetEntityAncestorsResponse>;
+    /**
+     * {@inheritdoc CatalogApi.getLocationById}
+     */
+    getLocationById(id: string, options?: CatalogRequestOptions): Promise<Location | undefined>;
+    /**
+     * {@inheritdoc CatalogApi.getEntities}
+     */
+    getEntities(request?: GetEntitiesRequest, options?: CatalogRequestOptions): Promise<GetEntitiesResponse>;
+    /**
+     * {@inheritdoc CatalogApi.getEntityByRef}
+     */
+    getEntityByRef(entityRef: string | CompoundEntityRef, options?: CatalogRequestOptions): Promise<Entity | undefined>;
+    /**
+     * {@inheritdoc CatalogApi.getEntityByName}
+     */
+    getEntityByName(compoundName: CompoundEntityRef, options?: CatalogRequestOptions): Promise<Entity | undefined>;
+    /**
+     * {@inheritdoc CatalogApi.refreshEntity}
+     */
+    refreshEntity(entityRef: string, options?: CatalogRequestOptions): Promise<void>;
+    /**
+     * {@inheritdoc CatalogApi.getEntityFacets}
+     */
+    getEntityFacets(request: GetEntityFacetsRequest, options?: CatalogRequestOptions): Promise<GetEntityFacetsResponse>;
+    /**
+     * {@inheritdoc CatalogApi.addLocation}
+     */
+    addLocation({ type, target, dryRun, presence }: AddLocationRequest, options?: CatalogRequestOptions): Promise<AddLocationResponse>;
+    /**
+     * @deprecated please use getLocationByRef instead
+     */
+    getOriginLocationByEntity(entity: Entity, options?: CatalogRequestOptions): Promise<Location | undefined>;
+    /**
+     * @deprecated please use getLocationByRef instead
+     */
+    getLocationByEntity(entity: Entity, options?: CatalogRequestOptions): Promise<Location | undefined>;
+    /**
+     * {@inheritdoc CatalogApi.getLocationByRef}
+     */
+    getLocationByRef(locationRef: string, options?: CatalogRequestOptions): Promise<Location | undefined>;
+    /**
+     * {@inheritdoc CatalogApi.removeLocationById}
+     */
+    removeLocationById(id: string, options?: CatalogRequestOptions): Promise<void>;
+    /**
+     * {@inheritdoc CatalogApi.removeEntityByUid}
+     */
+    removeEntityByUid(uid: string, options?: CatalogRequestOptions): Promise<void>;
+    private requestIgnored;
+    private requestRequired;
+    private requestOptional;
+}
+/**
+ * The entity `status.items[].type` for the status of the processing engine in
+ * regards to an entity.
+ *
+ * @public
+ */
+declare const ENTITY_STATUS_CATALOG_PROCESSING_TYPE = "backstage.io/catalog-processing";
+export { AddLocationRequest, AddLocationResponse, CATALOG_FILTER_EXISTS, CatalogApi, CatalogClient, CatalogRequestOptions, ENTITY_STATUS_CATALOG_PROCESSING_TYPE, GetEntitiesRequest, GetEntitiesResponse, GetEntityAncestorsRequest, GetEntityAncestorsResponse, GetEntityFacetsRequest, GetEntityFacetsResponse, Location };

package/dist/index.esm.js CHANGED Viewed

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

package/dist/index.esm.js.map CHANGED Viewed

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

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/catalog-client",
   "description": "An isomorphic client for the catalog backend",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -33,18 +33,18 @@
     "clean": "backstage-cli package clean"
   },
   "dependencies": {
-    "@backstage/catalog-model": "^0.10.0",
-    "@backstage/errors": "^0.2.1",
+    "@backstage/catalog-model": "^0.12.0",
+    "@backstage/errors": "^0.2.2",
     "cross-fetch": "^3.1.5"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.14.0",
+    "@backstage/cli": "^0.15.0",
     "@types/jest": "^26.0.7",
     "msw": "^0.35.0"
   },
   "files": [
     "dist"
   ],
-  "gitHead": "4805c3d13ce9bfc369e53c271b1b95e722b3b4dc",
+  "gitHead": "04bb0dd824b78f6b57dac62c3015e681f094045c",
   "module": "dist/index.esm.js"
 }