@marble-sh/backstage-plugin-grafana-common 0.2.0

package/README.md

@@ -0,0 +1,46 @@
+# @marble-sh/backstage-plugin-grafana-common
+
+Common functionality shared by the Grafana Backstage plugins. This package is
+isomorphic (usable from both frontend and backend) and has no heavy
+dependencies, so it can be safely imported anywhere.
+
+It provides:
+
+- **Entity annotations** and helpers for selecting Grafana content per entity.
+- **Data-transfer types** describing the shapes returned by the Grafana backend
+  REST API.
+
+## Entity annotations
+
+| Annotation                     | Helper                   | Meaning                                                            |
+| ------------------------------ | ------------------------ | ------------------------------------------------------------------ |
+| `grafana/instance`             | `getGrafanaInstanceName` | Which configured Grafana instance the entity belongs to.           |
+| `grafana/dashboard-selector`   | `getDashboardSelector`   | Comma-separated title substrings; any match selects the dashboard. |
+| `grafana/tag-selector`         | `getTagSelector`         | A comma-separated list of dashboard tags.                          |
+| `grafana/alert-label-selector` | `getAlertLabelSelector`  | A `key=value,...` list of alert label matchers.                    |
+
+`isGrafanaAvailable(entity)` returns `true` when an entity carries any of the
+above annotations, and is used to gate the Grafana entity tabs and cards.
+
+```ts
+import {
+  isGrafanaAvailable,
+  getGrafanaInstanceName,
+} from '@marble-sh/backstage-plugin-grafana-common';
+
+if (isGrafanaAvailable(entity)) {
+  const instance = getGrafanaInstanceName(entity); // e.g. "production"
+}
+```
+
+## Types
+
+The package exports the response and entity types used by the plugins, including
+`GrafanaInstanceInfo`, `GrafanaDashboard`, `GrafanaAlert`, and the
+`List*Response` bodies returned by the backend.
+
+## Testing
+
+```sh
+yarn workspace @marble-sh/backstage-plugin-grafana-common test
+```

package/dist/annotations.cjs.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const GRAFANA_ANNOTATION_INSTANCE = "grafana/instance";
+const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = "grafana/dashboard-selector";
+const GRAFANA_ANNOTATION_TAG_SELECTOR = "grafana/tag-selector";
+const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR = "grafana/alert-label-selector";
+const read = (entity, key) => {
+  const value = entity.metadata.annotations?.[key];
+  return value ? value : void 0;
+};
+const getGrafanaInstanceName = (entity) => read(entity, GRAFANA_ANNOTATION_INSTANCE);
+const getDashboardSelector = (entity) => read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);
+const getTagSelector = (entity) => read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);
+const getAlertLabelSelector = (entity) => read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);
+const isDashboardsAvailable = (entity) => Boolean(
+  getGrafanaInstanceName(entity) || getDashboardSelector(entity) || getTagSelector(entity)
+);
+const isAlertsAvailable = (entity) => Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));
+const isGrafanaAvailable = (entity) => isDashboardsAvailable(entity) || isAlertsAvailable(entity);
+
+exports.GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR = GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR;
+exports.GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = GRAFANA_ANNOTATION_DASHBOARD_SELECTOR;
+exports.GRAFANA_ANNOTATION_INSTANCE = GRAFANA_ANNOTATION_INSTANCE;
+exports.GRAFANA_ANNOTATION_TAG_SELECTOR = GRAFANA_ANNOTATION_TAG_SELECTOR;
+exports.getAlertLabelSelector = getAlertLabelSelector;
+exports.getDashboardSelector = getDashboardSelector;
+exports.getGrafanaInstanceName = getGrafanaInstanceName;
+exports.getTagSelector = getTagSelector;
+exports.isAlertsAvailable = isAlertsAvailable;
+exports.isDashboardsAvailable = isDashboardsAvailable;
+exports.isGrafanaAvailable = isGrafanaAvailable;
+//# sourceMappingURL=annotations.cjs.js.map

package/dist/annotations.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.cjs.js","sources":["../src/annotations.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\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 } from '@backstage/catalog-model';\n\n/**\n * Selects which configured Grafana instance an entity belongs to. The value\n * must match an instance `name` in the backend configuration.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_INSTANCE = 'grafana/instance';\n\n/**\n * Selects the dashboards shown for an entity: a comma-separated list of\n * case-insensitive title substrings, matching any dashboard whose title\n * contains at least one of the values.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR =\n  'grafana/dashboard-selector';\n\n/**\n * A comma-separated list of dashboard tags used to select the dashboards shown\n * for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_TAG_SELECTOR = 'grafana/tag-selector';\n\n/**\n * A comma-separated list of `key=value` label matchers used to select the\n * alerts shown for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR =\n  'grafana/alert-label-selector';\n\nconst read = (entity: Entity, key: string): string | undefined => {\n  const value = entity.metadata.annotations?.[key];\n  return value ? value : undefined;\n};\n\n/**\n * Returns the configured Grafana instance name for an entity, if any.\n *\n * @public\n */\nexport const getGrafanaInstanceName = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_INSTANCE);\n\n/**\n * Returns the dashboard selector expression for an entity, if any.\n *\n * @public\n */\nexport const getDashboardSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);\n\n/**\n * Returns the dashboard tag selector for an entity, if any.\n *\n * @public\n */\nexport const getTagSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);\n\n/**\n * Returns the alert label selector for an entity, if any.\n *\n * @public\n */\nexport const getAlertLabelSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * dashboards, and therefore has dashboard content to display.\n *\n * @public\n */\nexport const isDashboardsAvailable = (entity: Entity): boolean =>\n  Boolean(\n    getGrafanaInstanceName(entity) ||\n      getDashboardSelector(entity) ||\n      getTagSelector(entity),\n  );\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * alerts, and therefore has alert content to display.\n *\n * @public\n */\nexport const isAlertsAvailable = (entity: Entity): boolean =>\n  Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));\n\n/**\n * Returns `true` when an entity carries any Grafana annotation, and therefore\n * has Grafana content to display.\n *\n * @public\n */\nexport const isGrafanaAvailable = (entity: Entity): boolean =>\n  isDashboardsAvailable(entity) || isAlertsAvailable(entity);\n"],"names":[],"mappings":";;AAwBO,MAAM,2BAAA,GAA8B;AASpC,MAAM,qCAAA,GACX;AAQK,MAAM,+BAAA,GAAkC;AAQxC,MAAM,uCAAA,GACX;AAEF,MAAM,IAAA,GAAO,CAAC,MAAA,EAAgB,GAAA,KAAoC;AAChE,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,QAAA,CAAS,WAAA,GAAc,GAAG,CAAA;AAC/C,EAAA,OAAO,QAAQ,KAAA,GAAQ,MAAA;AACzB,CAAA;AAOO,MAAM,sBAAA,GAAyB,CAAC,MAAA,KACrC,IAAA,CAAK,QAAQ,2BAA2B;AAOnC,MAAM,oBAAA,GAAuB,CAAC,MAAA,KACnC,IAAA,CAAK,QAAQ,qCAAqC;AAO7C,MAAM,cAAA,GAAiB,CAAC,MAAA,KAC7B,IAAA,CAAK,QAAQ,+BAA+B;AAOvC,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,IAAA,CAAK,QAAQ,uCAAuC;AAQ/C,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,OAAA;AAAA,EACE,uBAAuB,MAAM,CAAA,IAC3B,qBAAqB,MAAM,CAAA,IAC3B,eAAe,MAAM;AACzB;AAQK,MAAM,iBAAA,GAAoB,CAAC,MAAA,KAChC,OAAA,CAAQ,uBAAuB,MAAM,CAAA,IAAK,qBAAA,CAAsB,MAAM,CAAC;AAQlE,MAAM,qBAAqB,CAAC,MAAA,KACjC,sBAAsB,MAAM,CAAA,IAAK,kBAAkB,MAAM;;;;;;;;;;;;"}

package/dist/annotations.esm.js

@@ -0,0 +1,20 @@
+const GRAFANA_ANNOTATION_INSTANCE = "grafana/instance";
+const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = "grafana/dashboard-selector";
+const GRAFANA_ANNOTATION_TAG_SELECTOR = "grafana/tag-selector";
+const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR = "grafana/alert-label-selector";
+const read = (entity, key) => {
+  const value = entity.metadata.annotations?.[key];
+  return value ? value : void 0;
+};
+const getGrafanaInstanceName = (entity) => read(entity, GRAFANA_ANNOTATION_INSTANCE);
+const getDashboardSelector = (entity) => read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);
+const getTagSelector = (entity) => read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);
+const getAlertLabelSelector = (entity) => read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);
+const isDashboardsAvailable = (entity) => Boolean(
+  getGrafanaInstanceName(entity) || getDashboardSelector(entity) || getTagSelector(entity)
+);
+const isAlertsAvailable = (entity) => Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));
+const isGrafanaAvailable = (entity) => isDashboardsAvailable(entity) || isAlertsAvailable(entity);
+
+export { GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR, GRAFANA_ANNOTATION_INSTANCE, GRAFANA_ANNOTATION_TAG_SELECTOR, getAlertLabelSelector, getDashboardSelector, getGrafanaInstanceName, getTagSelector, isAlertsAvailable, isDashboardsAvailable, isGrafanaAvailable };
+//# sourceMappingURL=annotations.esm.js.map

package/dist/annotations.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.esm.js","sources":["../src/annotations.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\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 } from '@backstage/catalog-model';\n\n/**\n * Selects which configured Grafana instance an entity belongs to. The value\n * must match an instance `name` in the backend configuration.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_INSTANCE = 'grafana/instance';\n\n/**\n * Selects the dashboards shown for an entity: a comma-separated list of\n * case-insensitive title substrings, matching any dashboard whose title\n * contains at least one of the values.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR =\n  'grafana/dashboard-selector';\n\n/**\n * A comma-separated list of dashboard tags used to select the dashboards shown\n * for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_TAG_SELECTOR = 'grafana/tag-selector';\n\n/**\n * A comma-separated list of `key=value` label matchers used to select the\n * alerts shown for an entity.\n *\n * @public\n */\nexport const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR =\n  'grafana/alert-label-selector';\n\nconst read = (entity: Entity, key: string): string | undefined => {\n  const value = entity.metadata.annotations?.[key];\n  return value ? value : undefined;\n};\n\n/**\n * Returns the configured Grafana instance name for an entity, if any.\n *\n * @public\n */\nexport const getGrafanaInstanceName = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_INSTANCE);\n\n/**\n * Returns the dashboard selector expression for an entity, if any.\n *\n * @public\n */\nexport const getDashboardSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR);\n\n/**\n * Returns the dashboard tag selector for an entity, if any.\n *\n * @public\n */\nexport const getTagSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_TAG_SELECTOR);\n\n/**\n * Returns the alert label selector for an entity, if any.\n *\n * @public\n */\nexport const getAlertLabelSelector = (entity: Entity): string | undefined =>\n  read(entity, GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR);\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * dashboards, and therefore has dashboard content to display.\n *\n * @public\n */\nexport const isDashboardsAvailable = (entity: Entity): boolean =>\n  Boolean(\n    getGrafanaInstanceName(entity) ||\n      getDashboardSelector(entity) ||\n      getTagSelector(entity),\n  );\n\n/**\n * Returns `true` when an entity carries an annotation that selects Grafana\n * alerts, and therefore has alert content to display.\n *\n * @public\n */\nexport const isAlertsAvailable = (entity: Entity): boolean =>\n  Boolean(getGrafanaInstanceName(entity) || getAlertLabelSelector(entity));\n\n/**\n * Returns `true` when an entity carries any Grafana annotation, and therefore\n * has Grafana content to display.\n *\n * @public\n */\nexport const isGrafanaAvailable = (entity: Entity): boolean =>\n  isDashboardsAvailable(entity) || isAlertsAvailable(entity);\n"],"names":[],"mappings":"AAwBO,MAAM,2BAAA,GAA8B;AASpC,MAAM,qCAAA,GACX;AAQK,MAAM,+BAAA,GAAkC;AAQxC,MAAM,uCAAA,GACX;AAEF,MAAM,IAAA,GAAO,CAAC,MAAA,EAAgB,GAAA,KAAoC;AAChE,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,QAAA,CAAS,WAAA,GAAc,GAAG,CAAA;AAC/C,EAAA,OAAO,QAAQ,KAAA,GAAQ,MAAA;AACzB,CAAA;AAOO,MAAM,sBAAA,GAAyB,CAAC,MAAA,KACrC,IAAA,CAAK,QAAQ,2BAA2B;AAOnC,MAAM,oBAAA,GAAuB,CAAC,MAAA,KACnC,IAAA,CAAK,QAAQ,qCAAqC;AAO7C,MAAM,cAAA,GAAiB,CAAC,MAAA,KAC7B,IAAA,CAAK,QAAQ,+BAA+B;AAOvC,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,IAAA,CAAK,QAAQ,uCAAuC;AAQ/C,MAAM,qBAAA,GAAwB,CAAC,MAAA,KACpC,OAAA;AAAA,EACE,uBAAuB,MAAM,CAAA,IAC3B,qBAAqB,MAAM,CAAA,IAC3B,eAAe,MAAM;AACzB;AAQK,MAAM,iBAAA,GAAoB,CAAC,MAAA,KAChC,OAAA,CAAQ,uBAAuB,MAAM,CAAA,IAAK,qBAAA,CAAsB,MAAM,CAAC;AAQlE,MAAM,qBAAqB,CAAC,MAAA,KACjC,sBAAsB,MAAM,CAAA,IAAK,kBAAkB,MAAM;;"}

package/dist/index.cjs.js

@@ -0,0 +1,21 @@
+'use strict';
+
+var annotations = require('./annotations.cjs.js');
+var selectors = require('./selectors.cjs.js');
+
+
+
+exports.GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR = annotations.GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR;
+exports.GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = annotations.GRAFANA_ANNOTATION_DASHBOARD_SELECTOR;
+exports.GRAFANA_ANNOTATION_INSTANCE = annotations.GRAFANA_ANNOTATION_INSTANCE;
+exports.GRAFANA_ANNOTATION_TAG_SELECTOR = annotations.GRAFANA_ANNOTATION_TAG_SELECTOR;
+exports.getAlertLabelSelector = annotations.getAlertLabelSelector;
+exports.getDashboardSelector = annotations.getDashboardSelector;
+exports.getGrafanaInstanceName = annotations.getGrafanaInstanceName;
+exports.getTagSelector = annotations.getTagSelector;
+exports.isAlertsAvailable = annotations.isAlertsAvailable;
+exports.isDashboardsAvailable = annotations.isDashboardsAvailable;
+exports.isGrafanaAvailable = annotations.isGrafanaAvailable;
+exports.parseLabelSelector = selectors.parseLabelSelector;
+exports.parseTagSelector = selectors.parseTagSelector;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+import { Entity } from '@backstage/catalog-model';
+
+/**
+ * Selects which configured Grafana instance an entity belongs to. The value
+ * must match an instance `name` in the backend configuration.
+ *
+ * @public
+ */
+declare const GRAFANA_ANNOTATION_INSTANCE = "grafana/instance";
+/**
+ * Selects the dashboards shown for an entity: a comma-separated list of
+ * case-insensitive title substrings, matching any dashboard whose title
+ * contains at least one of the values.
+ *
+ * @public
+ */
+declare const GRAFANA_ANNOTATION_DASHBOARD_SELECTOR = "grafana/dashboard-selector";
+/**
+ * A comma-separated list of dashboard tags used to select the dashboards shown
+ * for an entity.
+ *
+ * @public
+ */
+declare const GRAFANA_ANNOTATION_TAG_SELECTOR = "grafana/tag-selector";
+/**
+ * A comma-separated list of `key=value` label matchers used to select the
+ * alerts shown for an entity.
+ *
+ * @public
+ */
+declare const GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR = "grafana/alert-label-selector";
+/**
+ * Returns the configured Grafana instance name for an entity, if any.
+ *
+ * @public
+ */
+declare const getGrafanaInstanceName: (entity: Entity) => string | undefined;
+/**
+ * Returns the dashboard selector expression for an entity, if any.
+ *
+ * @public
+ */
+declare const getDashboardSelector: (entity: Entity) => string | undefined;
+/**
+ * Returns the dashboard tag selector for an entity, if any.
+ *
+ * @public
+ */
+declare const getTagSelector: (entity: Entity) => string | undefined;
+/**
+ * Returns the alert label selector for an entity, if any.
+ *
+ * @public
+ */
+declare const getAlertLabelSelector: (entity: Entity) => string | undefined;
+/**
+ * Returns `true` when an entity carries an annotation that selects Grafana
+ * dashboards, and therefore has dashboard content to display.
+ *
+ * @public
+ */
+declare const isDashboardsAvailable: (entity: Entity) => boolean;
+/**
+ * Returns `true` when an entity carries an annotation that selects Grafana
+ * alerts, and therefore has alert content to display.
+ *
+ * @public
+ */
+declare const isAlertsAvailable: (entity: Entity) => boolean;
+/**
+ * Returns `true` when an entity carries any Grafana annotation, and therefore
+ * has Grafana content to display.
+ *
+ * @public
+ */
+declare const isGrafanaAvailable: (entity: Entity) => boolean;
+
+/**
+ * Parses a `key=value,key2=value2` label selector string (as used by the
+ * `grafana/alert-label-selector` annotation) into a record. Whitespace around
+ * keys and values is trimmed, and empty or malformed segments are ignored.
+ *
+ * @public
+ */
+declare function parseLabelSelector(selector: string | undefined): Record<string, string>;
+/**
+ * Parses a comma-separated tag list (as used by the `grafana/tag-selector`
+ * annotation) into an array of trimmed, non-empty tags.
+ *
+ * @public
+ */
+declare function parseTagSelector(selector: string | undefined): string[];
+
+/**
+ * A configured Grafana instance, as exposed to clients of the backend.
+ *
+ * @public
+ */
+type GrafanaInstanceInfo = {
+    /** The unique, stable instance name (matches the `grafana/instance` annotation). */
+    name: string;
+    /** A human-readable title for display. */
+    title: string;
+    /** The base URL of the Grafana instance, without a trailing slash. */
+    url: string;
+};
+/**
+ * A Grafana dashboard, normalized across the App Platform and legacy search
+ * APIs.
+ *
+ * @public
+ */
+type GrafanaDashboard = {
+    /** The dashboard uid, as used in the dashboard URL. */
+    uid: string;
+    /** The dashboard title. */
+    title: string;
+    /** A fully-qualified URL to the dashboard in Grafana. */
+    url: string;
+    /** The title of the folder containing the dashboard, if any. */
+    folderTitle?: string;
+    /** A fully-qualified URL to the folder containing the dashboard, if any. */
+    folderUrl?: string;
+    /** The dashboard tags. */
+    tags: string[];
+    /** The name of the instance this dashboard was read from. */
+    instanceName: string;
+};
+/**
+ * The evaluation state of a Grafana alert rule.
+ *
+ * @public
+ */
+type GrafanaAlertState = 'firing' | 'pending' | 'inactive' | 'normal' | 'no_data' | 'error' | 'unknown';
+/**
+ * A Grafana alert rule together with its current state.
+ *
+ * @public
+ */
+type GrafanaAlert = {
+    /** The alert rule name. */
+    name: string;
+    /** The current evaluation state of the rule. */
+    state: GrafanaAlertState;
+    /** A fully-qualified URL to the alert (or its dashboard/panel) in Grafana. */
+    url: string;
+    /** The labels attached to the rule. */
+    labels: Record<string, string>;
+    /** The title of the folder (namespace) containing the rule, if any. */
+    folderTitle?: string;
+    /** The name of the instance this alert was read from. */
+    instanceName: string;
+};
+/**
+ * Response body for `GET /instances`.
+ *
+ * @public
+ */
+type ListInstancesResponse = {
+    items: GrafanaInstanceInfo[];
+};
+/**
+ * Response body for the dashboard listing endpoints.
+ *
+ * @public
+ */
+type ListDashboardsResponse = {
+    items: GrafanaDashboard[];
+};
+/**
+ * Response body for the alert listing endpoints.
+ *
+ * @public
+ */
+type ListAlertsResponse = {
+    items: GrafanaAlert[];
+};
+
+export { GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR, GRAFANA_ANNOTATION_INSTANCE, GRAFANA_ANNOTATION_TAG_SELECTOR, getAlertLabelSelector, getDashboardSelector, getGrafanaInstanceName, getTagSelector, isAlertsAvailable, isDashboardsAvailable, isGrafanaAvailable, parseLabelSelector, parseTagSelector };
+export type { GrafanaAlert, GrafanaAlertState, GrafanaDashboard, GrafanaInstanceInfo, ListAlertsResponse, ListDashboardsResponse, ListInstancesResponse };

package/dist/index.esm.js

@@ -0,0 +1,3 @@
+export { GRAFANA_ANNOTATION_ALERT_LABEL_SELECTOR, GRAFANA_ANNOTATION_DASHBOARD_SELECTOR, GRAFANA_ANNOTATION_INSTANCE, GRAFANA_ANNOTATION_TAG_SELECTOR, getAlertLabelSelector, getDashboardSelector, getGrafanaInstanceName, getTagSelector, isAlertsAvailable, isDashboardsAvailable, isGrafanaAvailable } from './annotations.esm.js';
+export { parseLabelSelector, parseTagSelector } from './selectors.esm.js';
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/selectors.cjs.js

@@ -0,0 +1,30 @@
+'use strict';
+
+function parseLabelSelector(selector) {
+  if (!selector) {
+    return {};
+  }
+  const result = {};
+  for (const segment of selector.split(",")) {
+    const index = segment.indexOf("=");
+    if (index <= 0) {
+      continue;
+    }
+    const key = segment.slice(0, index).trim();
+    const value = segment.slice(index + 1).trim();
+    if (key) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function parseTagSelector(selector) {
+  if (!selector) {
+    return [];
+  }
+  return selector.split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+
+exports.parseLabelSelector = parseLabelSelector;
+exports.parseTagSelector = parseTagSelector;
+//# sourceMappingURL=selectors.cjs.js.map

package/dist/selectors.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.cjs.js","sources":["../src/selectors.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\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 * Parses a `key=value,key2=value2` label selector string (as used by the\n * `grafana/alert-label-selector` annotation) into a record. Whitespace around\n * keys and values is trimmed, and empty or malformed segments are ignored.\n *\n * @public\n */\nexport function parseLabelSelector(\n  selector: string | undefined,\n): Record<string, string> {\n  if (!selector) {\n    return {};\n  }\n  const result: Record<string, string> = {};\n  for (const segment of selector.split(',')) {\n    const index = segment.indexOf('=');\n    if (index <= 0) {\n      continue;\n    }\n    const key = segment.slice(0, index).trim();\n    const value = segment.slice(index + 1).trim();\n    if (key) {\n      result[key] = value;\n    }\n  }\n  return result;\n}\n\n/**\n * Parses a comma-separated tag list (as used by the `grafana/tag-selector`\n * annotation) into an array of trimmed, non-empty tags.\n *\n * @public\n */\nexport function parseTagSelector(selector: string | undefined): string[] {\n  if (!selector) {\n    return [];\n  }\n  return selector\n    .split(',')\n    .map(tag => tag.trim())\n    .filter(Boolean);\n}\n"],"names":[],"mappings":";;AAuBO,SAAS,mBACd,QAAA,EACwB;AACxB,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,OAAO,EAAC;AAAA,EACV;AACA,EAAA,MAAM,SAAiC,EAAC;AACxC,EAAA,KAAA,MAAW,OAAA,IAAW,QAAA,CAAS,KAAA,CAAM,GAAG,CAAA,EAAG;AACzC,IAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,OAAA,CAAQ,GAAG,CAAA;AACjC,IAAA,IAAI,SAAS,CAAA,EAAG;AACd,MAAA;AAAA,IACF;AACA,IAAA,MAAM,MAAM,OAAA,CAAQ,KAAA,CAAM,CAAA,EAAG,KAAK,EAAE,IAAA,EAAK;AACzC,IAAA,MAAM,QAAQ,OAAA,CAAQ,KAAA,CAAM,KAAA,GAAQ,CAAC,EAAE,IAAA,EAAK;AAC5C,IAAA,IAAI,GAAA,EAAK;AACP,MAAA,MAAA,CAAO,GAAG,CAAA,GAAI,KAAA;AAAA,IAChB;AAAA,EACF;AACA,EAAA,OAAO,MAAA;AACT;AAQO,SAAS,iBAAiB,QAAA,EAAwC;AACvE,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,OAAO,EAAC;AAAA,EACV;AACA,EAAA,OAAO,QAAA,CACJ,KAAA,CAAM,GAAG,CAAA,CACT,GAAA,CAAI,CAAA,GAAA,KAAO,GAAA,CAAI,IAAA,EAAM,CAAA,CACrB,MAAA,CAAO,OAAO,CAAA;AACnB;;;"}

package/dist/selectors.esm.js

@@ -0,0 +1,27 @@
+function parseLabelSelector(selector) {
+  if (!selector) {
+    return {};
+  }
+  const result = {};
+  for (const segment of selector.split(",")) {
+    const index = segment.indexOf("=");
+    if (index <= 0) {
+      continue;
+    }
+    const key = segment.slice(0, index).trim();
+    const value = segment.slice(index + 1).trim();
+    if (key) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function parseTagSelector(selector) {
+  if (!selector) {
+    return [];
+  }
+  return selector.split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+
+export { parseLabelSelector, parseTagSelector };
+//# sourceMappingURL=selectors.esm.js.map

package/dist/selectors.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.esm.js","sources":["../src/selectors.ts"],"sourcesContent":["/*\n * Copyright 2026 Cassidy Marble\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 * Parses a `key=value,key2=value2` label selector string (as used by the\n * `grafana/alert-label-selector` annotation) into a record. Whitespace around\n * keys and values is trimmed, and empty or malformed segments are ignored.\n *\n * @public\n */\nexport function parseLabelSelector(\n  selector: string | undefined,\n): Record<string, string> {\n  if (!selector) {\n    return {};\n  }\n  const result: Record<string, string> = {};\n  for (const segment of selector.split(',')) {\n    const index = segment.indexOf('=');\n    if (index <= 0) {\n      continue;\n    }\n    const key = segment.slice(0, index).trim();\n    const value = segment.slice(index + 1).trim();\n    if (key) {\n      result[key] = value;\n    }\n  }\n  return result;\n}\n\n/**\n * Parses a comma-separated tag list (as used by the `grafana/tag-selector`\n * annotation) into an array of trimmed, non-empty tags.\n *\n * @public\n */\nexport function parseTagSelector(selector: string | undefined): string[] {\n  if (!selector) {\n    return [];\n  }\n  return selector\n    .split(',')\n    .map(tag => tag.trim())\n    .filter(Boolean);\n}\n"],"names":[],"mappings":"AAuBO,SAAS,mBACd,QAAA,EACwB;AACxB,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,OAAO,EAAC;AAAA,EACV;AACA,EAAA,MAAM,SAAiC,EAAC;AACxC,EAAA,KAAA,MAAW,OAAA,IAAW,QAAA,CAAS,KAAA,CAAM,GAAG,CAAA,EAAG;AACzC,IAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,OAAA,CAAQ,GAAG,CAAA;AACjC,IAAA,IAAI,SAAS,CAAA,EAAG;AACd,MAAA;AAAA,IACF;AACA,IAAA,MAAM,MAAM,OAAA,CAAQ,KAAA,CAAM,CAAA,EAAG,KAAK,EAAE,IAAA,EAAK;AACzC,IAAA,MAAM,QAAQ,OAAA,CAAQ,KAAA,CAAM,KAAA,GAAQ,CAAC,EAAE,IAAA,EAAK;AAC5C,IAAA,IAAI,GAAA,EAAK;AACP,MAAA,MAAA,CAAO,GAAG,CAAA,GAAI,KAAA;AAAA,IAChB;AAAA,EACF;AACA,EAAA,OAAO,MAAA;AACT;AAQO,SAAS,iBAAiB,QAAA,EAAwC;AACvE,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,OAAO,EAAC;AAAA,EACV;AACA,EAAA,OAAO,QAAA,CACJ,KAAA,CAAM,GAAG,CAAA,CACT,GAAA,CAAI,CAAA,GAAA,KAAO,GAAA,CAAI,IAAA,EAAM,CAAA,CACrB,MAAA,CAAO,OAAO,CAAA;AACnB;;"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@marble-sh/backstage-plugin-grafana-common",
+  "version": "0.2.0",
+  "description": "Common functionality for the Grafana Backstage plugins (types, annotations, and API contracts)",
+  "main": "./dist/index.cjs.js",
+  "types": "./dist/index.d.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "backstage": {
+    "role": "common-library",
+    "pluginId": "grafana",
+    "pluginPackages": [
+      "@marble-sh/backstage-plugin-grafana",
+      "@marble-sh/backstage-plugin-grafana-backend",
+      "@marble-sh/backstage-plugin-grafana-common",
+      "@marble-sh/backstage-plugin-grafana-node"
+    ]
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "backstage-cli package build",
+    "clean": "backstage-cli package clean",
+    "lint": "backstage-cli package lint",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack",
+    "test": "backstage-cli package test"
+  },
+  "dependencies": {
+    "@backstage/catalog-model": "backstage:^"
+  },
+  "devDependencies": {
+    "@backstage/cli": "backstage:^"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marble-sh/backstage-plugins-grafana",
+    "directory": "plugins/grafana-common"
+  },
+  "keywords": [
+    "backstage",
+    "plugin",
+    "grafana"
+  ],
+  "author": "Cassidy Marble",
+  "homepage": "https://github.com/marble-sh/backstage-plugins-grafana/tree/main/plugins/grafana-common",
+  "bugs": "https://github.com/marble-sh/backstage-plugins-grafana/issues",
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "package.json": [
+        "package.json"
+      ]
+    }
+  },
+  "module": "./dist/index.esm.js"
+}