@backstage/catalog-client 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @backstage/catalog-client
 
+## 0.7.1
+
+### Patch Changes
+
+- Fix for the previous release with missing type declarations.
+- Updated dependencies
+  - @backstage/catalog-model@0.10.1
+  - @backstage/errors@0.2.2
+
 ## 0.7.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -0,0 +1,324 @@
+import { Entity, LocationSpec, EntityName } 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[];
+    }>;
+}
+/**
+ * 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;
+} & LocationSpec;
+/**
+ * The request type for {@link CatalogClient.addLocation}.
+ *
+ * @public
+ */
+declare type AddLocationRequest = {
+    type?: string;
+    target: string;
+    dryRun?: boolean;
+    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 name - A complete entity ref
+     * @param options - Additional options
+     */
+    getEntityByName(name: EntityName, options?: CatalogRequestOptions): Promise<Entity | undefined>;
+    /**
+     * Removes a single entity from the catalog by entity UID.
+     *
+     * @param uid - 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 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.getEntityByName}
+     */
+    getEntityByName(compoundName: EntityName, options?: CatalogRequestOptions): Promise<Entity | undefined>;
+    /**
+     * {@inheritdoc CatalogApi.refreshEntity}
+     */
+    refreshEntity(entityRef: string, options?: CatalogRequestOptions): Promise<void>;
+    /**
+     * {@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";
+
+/**
+ * @public
+ * @deprecated use GetEntitiesRequest instead
+ */
+declare type CatalogEntitiesRequest = GetEntitiesRequest;
+/**
+ * @public
+ * @deprecated use GetEntitiesResponse instead
+ */
+declare type CatalogListResponse<_Entity> = GetEntitiesResponse;
+/**
+ * @public
+ * @deprecated use GetEntityAncestorsRequest instead
+ */
+declare type CatalogEntityAncestorsRequest = GetEntityAncestorsRequest;
+/**
+ * @public
+ * @deprecated use GetEntityAncestorsResponse instead
+ */
+declare type CatalogEntityAncestorsResponse = GetEntityAncestorsResponse;
+
+export { AddLocationRequest, AddLocationResponse, CATALOG_FILTER_EXISTS, CatalogApi, CatalogClient, CatalogEntitiesRequest, CatalogEntityAncestorsRequest, CatalogEntityAncestorsResponse, CatalogListResponse, CatalogRequestOptions, ENTITY_STATUS_CATALOG_PROCESSING_TYPE, GetEntitiesRequest, GetEntitiesResponse, GetEntityAncestorsRequest, GetEntityAncestorsResponse, Location };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/catalog-client",
   "description": "An isomorphic client for the catalog backend",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -33,8 +33,8 @@
     "clean": "backstage-cli package clean"
   },
   "dependencies": {
-    "@backstage/catalog-model": "^0.10.0",
-    "@backstage/errors": "^0.2.1",
+    "@backstage/catalog-model": "^0.10.1",
+    "@backstage/errors": "^0.2.2",
     "cross-fetch": "^3.1.5"
   },
   "devDependencies": {
@@ -45,6 +45,6 @@
   "files": [
     "dist"
   ],
-  "gitHead": "4805c3d13ce9bfc369e53c271b1b95e722b3b4dc",
+  "gitHead": "e244b348c473700e7d5e5fbcef38bd9f9fd1d0ba",
   "module": "dist/index.esm.js"
 }