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

package/README.md

@@ -0,0 +1,229 @@
+# @marble-sh/backstage-plugin-grafana-backend
+
+A read-only [Grafana](https://grafana.com/) backend plugin for Backstage,
+targeting the **new backend system**.
+
+The backend performs **all** communication with Grafana. It reads dashboards and
+alerts, caches them (in the Backstage cache **or** database), optionally
+refreshes them on a schedule, and exposes a small read-only REST API under
+`/api/grafana`. The frontend plugin
+([`@marble-sh/backstage-plugin-grafana`](../grafana/README.md)) and the catalog
+module talk only to this API — they never contact Grafana directly, so all
+credentials stay in the backend.
+
+## Features
+
+- Reads dashboards from the modern **App Platform** API
+  (`dashboard.grafana.app/v1`, Grafana 12+), or — opt-in per instance via
+  `apis.dashboards: legacy-search` — from the classic `/api/search` endpoint
+  for older Grafana versions. Folder titles and links are resolved for both.
+- Reads alert rules and their live state from the stable Grafana-managed
+  Prometheus rules API (`/api/prometheus/grafana/api/v1/rules`).
+- Works with both **Grafana Cloud** and **self-hosted** Grafana, using a
+  service-account token.
+- Supports **multiple instances**, each addressable by name.
+- Caches data in the Backstage **cache** service (ephemeral, TTL-based) or the
+  **database** service (durable), selectable by configuration.
+- Optional **scheduled refresh** to keep the cache warm.
+- Serves data live on demand (cache miss) or forcibly via `?refresh=true`.
+
+## Installation
+
+Add the dependency to your backend package:
+
+```sh
+yarn --cwd packages/backend add @marble-sh/backstage-plugin-grafana-backend
+```
+
+Then register the plugin in your backend:
+
+```ts
+// packages/backend/src/index.ts
+const backend = createBackend();
+// ...
+backend.add(import('@marble-sh/backstage-plugin-grafana-backend'));
+backend.start();
+```
+
+## Configuration
+
+All configuration lives under the `grafana` key. The store/schedule schema is
+documented in this package's [`config.d.ts`](./config.d.ts); the shared
+`grafana.instances` schema lives in
+[`grafana-node`](../grafana-node/config.d.ts), where every consumer of the
+instance list picks it up.
+
+```yaml
+grafana:
+  # Where fetched data is stored between refreshes:
+  #   cache    (default) – ephemeral, honors cacheTtl
+  #   database          – durable, survives restarts and is shared across replicas
+  store: cache
+  cacheTtl: { minutes: 15 }
+
+  # Behavior flags (both default to true; see "Behavior flags" below).
+  allowOnDemandRefresh: true
+  fetchOnDemand: true
+
+  # Optional background refresh. Omit to fetch lazily on request instead.
+  schedule:
+    frequency: { minutes: 15 }
+    timeout: { minutes: 2 }
+    initialDelay: { seconds: 30 }
+
+  instances:
+    # A self-hosted Grafana (organization 1 → namespace "default").
+    - name: production
+      title: Production Grafana
+      baseUrl: https://grafana.internal.example.com
+      token: ${GRAFANA_PROD_TOKEN} # service-account token, Viewer is enough
+
+    # A Grafana Cloud stack (namespace derived as "stacks-<stackId>").
+    - name: cloud
+      title: Grafana Cloud
+      baseUrl: https://myorg.grafana.net
+      stackId: '123456'
+      token: ${GRAFANA_CLOUD_TOKEN}
+```
+
+### Instance options
+
+| Key              | Required | Description                                                                                             |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `name`           | yes      | Unique, stable id. Referenced by the `grafana/instance` entity annotation and by the REST API.          |
+| `baseUrl`        | yes      | Base URL of the Grafana instance, without a trailing slash.                                             |
+| `token`          | yes      | Service-account token used as a Bearer token. Read-only (Viewer) permissions are enough. Marked secret. |
+| `title`          | no       | Human-readable title. Defaults to `name`.                                                               |
+| `namespace`      | no       | App Platform namespace. Defaults to `default` (self-hosted) or `stacks-<stackId>` (cloud).              |
+| `stackId`        | no       | Grafana Cloud stack id, used to derive the namespace.                                                   |
+| `apis`           | no       | Override or disable the API used per data type (see below).                                             |
+| `resolveFolders` | no       | `false` skips the `/api/folders` folder lookup (see below). Defaults to `true`.                         |
+
+### API selection
+
+```yaml
+apis:
+  dashboards: app-platform # or "legacy-search" for older Grafana, or "none"
+  alerts: prometheus # or "none"
+```
+
+Every state, per data type:
+
+- `dashboards: app-platform` (default) uses `dashboard.grafana.app/v1`
+  (Grafana 12+).
+- `dashboards: legacy-search` uses the classic `/api/search` endpoint.
+- `dashboards: none` — the instance serves no dashboards: dashboard listings
+  return empty for it without contacting Grafana, and catalog discovery emits
+  no dashboard entities for it.
+- `alerts: prometheus` (default) uses the Grafana-managed Prometheus rules API.
+- `alerts: none` — the instance serves no alerts: alert listings return empty
+  for it without contacting Grafana. Set this on instances that do not use
+  Grafana-managed alerting; otherwise their snapshot refreshes fail on the
+  alerting call.
+
+### Folder resolution (`resolveFolders`)
+
+- `true` (default): when dashboards come from the App Platform API, one extra
+  `/api/folders` request per refresh resolves folder uids to titles and links.
+- `false`: that request is skipped and App Platform dashboards carry no folder
+  information. `legacy-search` dashboards are unaffected either way — their
+  search response already includes folder details.
+
+### Behavior flags
+
+Two top-level flags control when the backend talks to Grafana. Both default to
+`true`; each can be set independently.
+
+- **`allowOnDemandRefresh`** — may API callers force live reads?
+
+  - `true` (default): `?refresh=true` (also `?refresh=1` or the bare flag)
+    bypasses the store, and `POST /refresh` / `POST /instances/:name/refresh`
+    trigger immediate refreshes.
+  - `false`: `refresh` query parameters are silently ignored (the request is
+    served exactly as if the parameter were absent) and both `POST …/refresh`
+    routes respond `403 NotAllowedError`. The scheduled refresh is unaffected.
+
+- **`fetchOnDemand`** — does a store miss trigger a live read?
+  - `true` (default): a miss fetches from Grafana on the spot and stores the
+    snapshot.
+  - `false`: a miss returns empty results and stores nothing; data appears
+    once any refresh runs.
+
+All four combinations:
+
+| `allowOnDemandRefresh` | `fetchOnDemand` | Resulting behavior                                                                                                                   |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `true`                 | `true`          | (Default.) Misses fetch lazily; users may force refreshes.                                                                           |
+| `true`                 | `false`         | Misses return empty, but an explicit `?refresh=true` or `POST …/refresh` still reads live and fills the store.                       |
+| `false`                | `true`          | Users cannot force refreshes, but a cold store still fills itself lazily on first read.                                              |
+| `false`                | `false`         | Grafana is contacted **only** by the schedule (configure one, or the API serves empty forever). Fully deterministic Grafana traffic. |
+
+### Deriving the namespace
+
+Grafana's App Platform APIs are namespaced:
+
+- Self-hosted, organization 1 → `default`
+- Self-hosted, other organizations → `org-<id>` (set `namespace` explicitly)
+- Grafana Cloud → `stacks-<stackId>` (set `stackId`, or `namespace` directly)
+
+## REST API
+
+All routes are mounted under `/api/grafana` and (except `/health`) require a
+valid Backstage credential.
+
+| Method | Path                          | Description                                                |
+| ------ | ----------------------------- | ---------------------------------------------------------- |
+| GET    | `/health`                     | Health check (unauthenticated).                            |
+| GET    | `/instances`                  | List configured instances.                                 |
+| GET    | `/instances/:name/dashboards` | Dashboards for one instance.                               |
+| GET    | `/instances/:name/alerts`     | Alerts for one instance.                                   |
+| POST   | `/instances/:name/refresh`    | Force a refresh of one instance.                           |
+| GET    | `/dashboards`                 | Dashboards across all instances (or `?instance=` for one). |
+| GET    | `/alerts`                     | Alerts across all instances (or `?instance=` for one).     |
+| POST   | `/refresh`                    | Force a refresh of all instances.                          |
+
+### Query parameters
+
+- `tag` — repeatable; only dashboards carrying **all** given tags are returned.
+- `query` — comma-separated, case-insensitive title substrings; dashboards
+  matching **any** value are returned.
+- `labelSelector` — `key=value,key2=value2`; only alerts matching **all** pairs.
+- `instance` — (on `/dashboards` and `/alerts`) restrict to a single instance.
+- `refresh` — `true` or `1` (or the bare flag) to bypass the store and read
+  live from Grafana.
+
+Example:
+
+```sh
+curl -H "Authorization: Bearer <backstage-token>" \
+  "http://localhost:7007/api/grafana/instances/production/dashboards?tag=team-a&refresh=true"
+```
+
+## How caching works
+
+Each request resolves to a per-instance snapshot (all dashboards + all alerts):
+
+1. Unless `refresh=true`, the snapshot is read from the configured store.
+2. On a miss (or when `refresh=true`), the backend reads live from Grafana and
+   writes the snapshot back to the store.
+3. Requested tag/query/label filters are then applied to the snapshot.
+
+Because filtering happens after retrieval, a single cached snapshot serves many
+entities with different selectors, keeping Grafana API traffic low.
+
+## Local development
+
+```sh
+yarn start   # from this directory, runs the plugin in a standalone backend
+```
+
+## Testing
+
+```sh
+yarn workspace @marble-sh/backstage-plugin-grafana-backend test
+```
+
+The plugin is developed test-first. Unit tests cover the HTTP client (with an
+injected `fetch`), config parsing, both stores (the database store against an
+in-memory SQLite), the caching service, and the router. An integration test
+boots the plugin with `startTestBackend` and a mocked Grafana.

package/config.schema.json

@@ -0,0 +1,174 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "grafana": {
+      "type": "object",
+      "properties": {
+        "store": {
+          "type": "string",
+          "enum": [
+            "cache",
+            "database"
+          ],
+          "description": "Where fetched dashboard and alert data is stored between live refreshes.\n\n - `cache` (default): the Backstage cache service (ephemeral, honors    `cacheTtl`). Best for stateless deployments.  - `database`: the Backstage database service (durable). Survives    restarts and is shared across replicas."
+        },
+        "cacheTtl": {
+          "type": "object",
+          "properties": {
+            "years": {
+              "type": "number"
+            },
+            "months": {
+              "type": "number"
+            },
+            "weeks": {
+              "type": "number"
+            },
+            "days": {
+              "type": "number"
+            },
+            "hours": {
+              "type": "number"
+            },
+            "minutes": {
+              "type": "number"
+            },
+            "seconds": {
+              "type": "number"
+            },
+            "milliseconds": {
+              "type": "number"
+            }
+          },
+          "description": "Time-to-live for cached data. Only used when `store` is `cache`. Defaults to 15 minutes."
+        },
+        "allowOnDemandRefresh": {
+          "type": "boolean",
+          "description": "Whether API callers may force live reads from Grafana.\n\n - `true` (default): the `refresh=true` query parameter bypasses the    store, and `POST /refresh` / `POST /instances/:name/refresh` trigger    immediate refreshes.  - `false`: `refresh` query parameters are silently ignored (requests    are served from the store as if the parameter were absent) and the    `POST …/refresh` routes respond `403`. The scheduled refresh is not    affected."
+        },
+        "fetchOnDemand": {
+          "type": "boolean",
+          "description": "Whether a store miss triggers a live read from Grafana.\n\n - `true` (default): when no snapshot is stored for an instance, the    backend fetches from Grafana on the spot and stores the result.  - `false`: store misses return empty results without contacting    Grafana. Data appears once a refresh runs — the schedule, the    `POST …/refresh` routes, or a `refresh=true` read (the latter two    only if `allowOnDemandRefresh` permits them). With both flags    `false`, Grafana is contacted exclusively by the schedule."
+        },
+        "schedule": {
+          "type": "object",
+          "properties": {
+            "frequency": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "years": {
+                      "type": "number"
+                    },
+                    "months": {
+                      "type": "number"
+                    },
+                    "weeks": {
+                      "type": "number"
+                    },
+                    "days": {
+                      "type": "number"
+                    },
+                    "hours": {
+                      "type": "number"
+                    },
+                    "minutes": {
+                      "type": "number"
+                    },
+                    "seconds": {
+                      "type": "number"
+                    },
+                    "milliseconds": {
+                      "type": "number"
+                    }
+                  },
+                  "description": "Human friendly durations object."
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "cron": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "cron"
+                  ]
+                }
+              ],
+              "description": "How often the refresh runs. Either a duration or a cron expression."
+            },
+            "timeout": {
+              "type": "object",
+              "properties": {
+                "years": {
+                  "type": "number"
+                },
+                "months": {
+                  "type": "number"
+                },
+                "weeks": {
+                  "type": "number"
+                },
+                "days": {
+                  "type": "number"
+                },
+                "hours": {
+                  "type": "number"
+                },
+                "minutes": {
+                  "type": "number"
+                },
+                "seconds": {
+                  "type": "number"
+                },
+                "milliseconds": {
+                  "type": "number"
+                }
+              },
+              "description": "The maximum time a single refresh run may take before it times out."
+            },
+            "initialDelay": {
+              "type": "object",
+              "properties": {
+                "years": {
+                  "type": "number"
+                },
+                "months": {
+                  "type": "number"
+                },
+                "weeks": {
+                  "type": "number"
+                },
+                "days": {
+                  "type": "number"
+                },
+                "hours": {
+                  "type": "number"
+                },
+                "minutes": {
+                  "type": "number"
+                },
+                "seconds": {
+                  "type": "number"
+                },
+                "milliseconds": {
+                  "type": "number"
+                }
+              },
+              "description": "How long to wait after startup before the first refresh run."
+            }
+          },
+          "required": [
+            "frequency",
+            "timeout"
+          ],
+          "description": "Background refresh schedule. When set, the backend periodically refreshes every instance's dashboards and alerts into the configured store. Omit to disable scheduled refresh (data is then fetched lazily on request)."
+        }
+      },
+      "description": "Configuration for the Grafana backend plugin.\n\nThe backend performs all communication with Grafana. The frontend never talks to Grafana directly, so all credentials live here in the backend.\n\nThe `grafana.instances` list itself is declared by the shared `@marble-sh/backstage-plugin-grafana-node` library's config schema."
+    }
+  }
+}

package/dist/grafana/config.cjs.js

@@ -0,0 +1,29 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+var errors = require('@backstage/errors');
+var backstagePluginGrafanaNode = require('@marble-sh/backstage-plugin-grafana-node');
+
+const DEFAULT_CACHE_TTL = { minutes: 15 };
+function readGrafanaConfig(rootConfig) {
+  const instances = backstagePluginGrafanaNode.readGrafanaInstances(rootConfig);
+  const config = rootConfig.getOptionalConfig("grafana");
+  const store = config?.getOptionalString("store") ?? "cache";
+  if (store !== "cache" && store !== "database") {
+    throw new errors.InputError(
+      `Invalid grafana.store '${store}', expected 'cache' or 'database'`
+    );
+  }
+  const scheduleConfig = config?.getOptionalConfig("schedule");
+  return {
+    instances,
+    store,
+    cacheTtl: config?.getOptional("cacheTtl") ?? DEFAULT_CACHE_TTL,
+    schedule: scheduleConfig ? backendPluginApi.readSchedulerServiceTaskScheduleDefinitionFromConfig(scheduleConfig) : void 0,
+    allowOnDemandRefresh: config?.getOptionalBoolean("allowOnDemandRefresh") ?? true,
+    fetchOnDemand: config?.getOptionalBoolean("fetchOnDemand") ?? true
+  };
+}
+
+exports.readGrafanaConfig = readGrafanaConfig;
+//# sourceMappingURL=config.cjs.js.map

package/dist/grafana/config.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.cjs.js","sources":["../../src/grafana/config.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 { Config } from '@backstage/config';\nimport {\n  readSchedulerServiceTaskScheduleDefinitionFromConfig,\n  SchedulerServiceTaskScheduleDefinition,\n} from '@backstage/backend-plugin-api';\nimport { InputError } from '@backstage/errors';\nimport { HumanDuration } from '@backstage/types';\nimport {\n  GrafanaInstanceConfig,\n  readGrafanaInstances,\n} from '@marble-sh/backstage-plugin-grafana-node';\n\nexport type {\n  GrafanaInstanceConfig,\n  GrafanaInstanceApis,\n} from '@marble-sh/backstage-plugin-grafana-node';\n\n/**\n * Where fetched data is stored between refreshes.\n *\n * @public\n */\nexport type GrafanaStoreKind = 'cache' | 'database';\n\n/**\n * The fully-resolved backend configuration.\n *\n * @public\n */\nexport type GrafanaBackendConfig = {\n  instances: GrafanaInstanceConfig[];\n  store: GrafanaStoreKind;\n  cacheTtl: HumanDuration;\n  schedule?: SchedulerServiceTaskScheduleDefinition;\n  /** Whether callers may force live reads (`?refresh=true`, `POST /refresh`). */\n  allowOnDemandRefresh: boolean;\n  /** Whether a store miss triggers a live Grafana read. */\n  fetchOnDemand: boolean;\n};\n\nconst DEFAULT_CACHE_TTL: HumanDuration = { minutes: 15 };\n\n/**\n * Reads and validates the `grafana` section of the app configuration into a\n * fully-resolved {@link GrafanaBackendConfig}.\n *\n * @public\n */\nexport function readGrafanaConfig(rootConfig: Config): GrafanaBackendConfig {\n  const instances = readGrafanaInstances(rootConfig);\n  const config = rootConfig.getOptionalConfig('grafana');\n\n  const store =\n    (config?.getOptionalString('store') as GrafanaStoreKind | undefined) ??\n    'cache';\n  if (store !== 'cache' && store !== 'database') {\n    throw new InputError(\n      `Invalid grafana.store '${store}', expected 'cache' or 'database'`,\n    );\n  }\n\n  const scheduleConfig = config?.getOptionalConfig('schedule');\n\n  return {\n    instances,\n    store,\n    cacheTtl:\n      (config?.getOptional('cacheTtl') as HumanDuration | undefined) ??\n      DEFAULT_CACHE_TTL,\n    schedule: scheduleConfig\n      ? readSchedulerServiceTaskScheduleDefinitionFromConfig(scheduleConfig)\n      : undefined,\n    allowOnDemandRefresh:\n      config?.getOptionalBoolean('allowOnDemandRefresh') ?? true,\n    fetchOnDemand: config?.getOptionalBoolean('fetchOnDemand') ?? true,\n  };\n}\n"],"names":["readGrafanaInstances","InputError","readSchedulerServiceTaskScheduleDefinitionFromConfig"],"mappings":";;;;;;AAwDA,MAAM,iBAAA,GAAmC,EAAE,OAAA,EAAS,EAAA,EAAG;AAQhD,SAAS,kBAAkB,UAAA,EAA0C;AAC1E,EAAA,MAAM,SAAA,GAAYA,gDAAqB,UAAU,CAAA;AACjD,EAAA,MAAM,MAAA,GAAS,UAAA,CAAW,iBAAA,CAAkB,SAAS,CAAA;AAErD,EAAA,MAAM,KAAA,GACH,MAAA,EAAQ,iBAAA,CAAkB,OAAO,CAAA,IAClC,OAAA;AACF,EAAA,IAAI,KAAA,KAAU,OAAA,IAAW,KAAA,KAAU,UAAA,EAAY;AAC7C,IAAA,MAAM,IAAIC,iBAAA;AAAA,MACR,0BAA0B,KAAK,CAAA,iCAAA;AAAA,KACjC;AAAA,EACF;AAEA,EAAA,MAAM,cAAA,GAAiB,MAAA,EAAQ,iBAAA,CAAkB,UAAU,CAAA;AAE3D,EAAA,OAAO;AAAA,IACL,SAAA;AAAA,IACA,KAAA;AAAA,IACA,QAAA,EACG,MAAA,EAAQ,WAAA,CAAY,UAAU,CAAA,IAC/B,iBAAA;AAAA,IACF,QAAA,EAAU,cAAA,GACNC,qEAAA,CAAqD,cAAc,CAAA,GACnE,MAAA;AAAA,IACJ,oBAAA,EACE,MAAA,EAAQ,kBAAA,CAAmB,sBAAsB,CAAA,IAAK,IAAA;AAAA,IACxD,aAAA,EAAe,MAAA,EAAQ,kBAAA,CAAmB,eAAe,CAAA,IAAK;AAAA,GAChE;AACF;;"}

package/dist/index.cjs.js

@@ -0,0 +1,25 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var plugin = require('./plugin.cjs.js');
+var GrafanaService = require('./service/GrafanaService.cjs.js');
+var backstagePluginGrafanaNode = require('@marble-sh/backstage-plugin-grafana-node');
+var config = require('./grafana/config.cjs.js');
+var CacheGrafanaStore = require('./store/CacheGrafanaStore.cjs.js');
+var DatabaseGrafanaStore = require('./store/DatabaseGrafanaStore.cjs.js');
+var router = require('./service/router.cjs.js');
+
+
+
+exports.default = plugin.grafanaPlugin;
+exports.DefaultGrafanaService = GrafanaService.DefaultGrafanaService;
+Object.defineProperty(exports, "GrafanaHttpClient", {
+  enumerable: true,
+  get: function () { return backstagePluginGrafanaNode.GrafanaHttpClient; }
+});
+exports.readGrafanaConfig = config.readGrafanaConfig;
+exports.CacheGrafanaStore = CacheGrafanaStore.CacheGrafanaStore;
+exports.DatabaseGrafanaStore = DatabaseGrafanaStore.DatabaseGrafanaStore;
+exports.createRouter = router.createRouter;
+//# 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,230 @@
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+import { LoggerService, SchedulerServiceTaskScheduleDefinition, CacheService, DatabaseService } from '@backstage/backend-plugin-api';
+import { GrafanaDashboard, GrafanaAlert, GrafanaInstanceInfo } from '@marble-sh/backstage-plugin-grafana-common';
+import { GrafanaInstanceConfig, GrafanaClient } from '@marble-sh/backstage-plugin-grafana-node';
+export { FetchApi, GrafanaClient, GrafanaHttpClient, GrafanaInstanceApis, GrafanaInstanceConfig, ListAlertsOptions, ListDashboardsOptions } from '@marble-sh/backstage-plugin-grafana-node';
+import { Config } from '@backstage/config';
+import { HumanDuration } from '@backstage/types';
+import { Knex } from 'knex';
+import express from 'express';
+
+/**
+ * The Grafana backend plugin.
+ *
+ * Reads dashboards and alerts from the configured Grafana instances, caches
+ * them (in the cache or the database), optionally refreshes them on a schedule,
+ * and exposes a read-only REST API under `/api/grafana`.
+ *
+ * @public
+ */
+declare const grafanaPlugin: _backstage_backend_plugin_api.BackendFeature;
+
+/**
+ * A point-in-time snapshot of the data read from a single Grafana instance.
+ *
+ * @public
+ */
+type GrafanaSnapshot = {
+    dashboards: GrafanaDashboard[];
+    alerts: GrafanaAlert[];
+    /** ISO-8601 timestamp of when the data was read from Grafana. */
+    fetchedAt: string;
+};
+/**
+ * Persists {@link GrafanaSnapshot}s between live refreshes.
+ *
+ * Implementations may be durable (database-backed) or ephemeral (cache-backed).
+ *
+ * @public
+ */
+interface GrafanaStore {
+    /** Returns the stored snapshot for an instance, or `undefined` if none. */
+    get(instanceName: string): Promise<GrafanaSnapshot | undefined>;
+    /** Replaces the stored snapshot for an instance. */
+    set(instanceName: string, snapshot: GrafanaSnapshot): Promise<void>;
+}
+
+/**
+ * A configured instance together with the client used to read from it.
+ *
+ * @public
+ */
+type GrafanaInstance = {
+    config: GrafanaInstanceConfig;
+    client: GrafanaClient;
+};
+/**
+ * Options for reading dashboards through the service.
+ *
+ * @public
+ */
+type GetDashboardsOptions = {
+    /** Restrict to a single instance. When omitted, all instances are queried. */
+    instanceName?: string;
+    /** Only return dashboards carrying all of these tags. */
+    tags?: string[];
+    /** Comma-separated title substrings; dashboards matching any are returned. */
+    query?: string;
+    /** Force a live fetch, bypassing the store. */
+    refresh?: boolean;
+};
+/**
+ * Options for reading alerts through the service.
+ *
+ * @public
+ */
+type GetAlertsOptions = {
+    /** Restrict to a single instance. When omitted, all instances are queried. */
+    instanceName?: string;
+    /** Only return alerts whose labels match all of these `key=value` pairs. */
+    labelSelector?: Record<string, string>;
+    /** Force a live fetch, bypassing the store. */
+    refresh?: boolean;
+};
+/**
+ * Reads dashboards and alerts from the configured Grafana instances, backed by a
+ * {@link GrafanaStore} for caching and periodic refresh.
+ *
+ * @public
+ */
+interface GrafanaService {
+    /** Returns the configured Grafana instances. */
+    getInstances(): GrafanaInstanceInfo[];
+    /** Returns dashboards for one or all instances, honoring the store and filters. */
+    getDashboards(options: GetDashboardsOptions): Promise<GrafanaDashboard[]>;
+    /** Returns alerts for one or all instances, honoring the store and filters. */
+    getAlerts(options: GetAlertsOptions): Promise<GrafanaAlert[]>;
+    /** Refreshes a single instance, or all instances when no name is given. */
+    refresh(instanceName?: string): Promise<void>;
+}
+/**
+ * The default {@link GrafanaService} implementation.
+ *
+ * @public
+ */
+declare class DefaultGrafanaService implements GrafanaService {
+    private readonly instances;
+    private readonly store;
+    private readonly logger;
+    private readonly fetchOnDemand;
+    constructor(options: {
+        instances: GrafanaInstance[];
+        store: GrafanaStore;
+        logger: LoggerService;
+        /**
+         * Whether a store miss triggers a live Grafana read (default `true`).
+         * When `false`, misses resolve to an empty snapshot and Grafana is only
+         * contacted by explicit {@link DefaultGrafanaService.refresh} calls (the
+         * schedule, the refresh endpoints, or a `refresh: true` read option).
+         */
+        fetchOnDemand?: boolean;
+    });
+    /** {@inheritDoc GrafanaService.getInstances} */
+    getInstances(): GrafanaInstanceInfo[];
+    /** {@inheritDoc GrafanaService.getDashboards} */
+    getDashboards(options: GetDashboardsOptions): Promise<GrafanaDashboard[]>;
+    /** {@inheritDoc GrafanaService.getAlerts} */
+    getAlerts(options: GetAlertsOptions): Promise<GrafanaAlert[]>;
+    /** {@inheritDoc GrafanaService.refresh} */
+    refresh(instanceName?: string): Promise<void>;
+    private resolveNames;
+    private mustGet;
+    private snapshotFor;
+    private refreshInstance;
+}
+
+/**
+ * Where fetched data is stored between refreshes.
+ *
+ * @public
+ */
+type GrafanaStoreKind = 'cache' | 'database';
+/**
+ * The fully-resolved backend configuration.
+ *
+ * @public
+ */
+type GrafanaBackendConfig = {
+    instances: GrafanaInstanceConfig[];
+    store: GrafanaStoreKind;
+    cacheTtl: HumanDuration;
+    schedule?: SchedulerServiceTaskScheduleDefinition;
+    /** Whether callers may force live reads (`?refresh=true`, `POST /refresh`). */
+    allowOnDemandRefresh: boolean;
+    /** Whether a store miss triggers a live Grafana read. */
+    fetchOnDemand: boolean;
+};
+/**
+ * Reads and validates the `grafana` section of the app configuration into a
+ * fully-resolved {@link GrafanaBackendConfig}.
+ *
+ * @public
+ */
+declare function readGrafanaConfig(rootConfig: Config): GrafanaBackendConfig;
+
+/**
+ * A {@link GrafanaStore} backed by the Backstage cache service. Snapshots are
+ * ephemeral and expire after the configured TTL.
+ *
+ * @public
+ */
+declare class CacheGrafanaStore implements GrafanaStore {
+    private readonly cache;
+    private readonly ttlMillis;
+    constructor(options: {
+        cache: CacheService;
+        ttl: HumanDuration;
+    });
+    private key;
+    /** {@inheritDoc GrafanaStore.get} */
+    get(instanceName: string): Promise<GrafanaSnapshot | undefined>;
+    /** {@inheritDoc GrafanaStore.set} */
+    set(instanceName: string, snapshot: GrafanaSnapshot): Promise<void>;
+}
+
+/**
+ * A {@link GrafanaStore} backed by the Backstage database service. Snapshots are
+ * durable and survive restarts.
+ *
+ * @public
+ */
+declare class DatabaseGrafanaStore implements GrafanaStore {
+    private readonly knex;
+    private constructor();
+    /**
+     * Creates the store from the database core service, running migrations
+     * unless the integrator has configured them to be skipped.
+     */
+    static create(options: {
+        database: DatabaseService;
+    }): Promise<DatabaseGrafanaStore>;
+    /**
+     * Creates the store from a raw Knex client, running migrations. Primarily
+     * intended for testing.
+     */
+    static fromKnex(knex: Knex): Promise<DatabaseGrafanaStore>;
+    /** {@inheritDoc GrafanaStore.get} */
+    get(instanceName: string): Promise<GrafanaSnapshot | undefined>;
+    /** {@inheritDoc GrafanaStore.set} */
+    set(instanceName: string, snapshot: GrafanaSnapshot): Promise<void>;
+}
+
+/**
+ * Creates the Express router that exposes the read-only Grafana REST API.
+ *
+ * All routes are relative to the plugin base path (`/api/grafana`).
+ *
+ * @public
+ */
+declare function createRouter(options: {
+    grafanaService: GrafanaService;
+    /**
+     * Whether callers may force live Grafana reads (default `true`). When
+     * `false`, `refresh` query parameters are ignored and the `POST …/refresh`
+     * routes respond 403.
+     */
+    allowOnDemandRefresh?: boolean;
+}): Promise<express.Router>;
+
+export { CacheGrafanaStore, DatabaseGrafanaStore, DefaultGrafanaService, createRouter, grafanaPlugin as default, readGrafanaConfig };
+export type { GetAlertsOptions, GetDashboardsOptions, GrafanaBackendConfig, GrafanaInstance, GrafanaService, GrafanaSnapshot, GrafanaStore, GrafanaStoreKind };

package/dist/plugin.cjs.js

@@ -0,0 +1,66 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+var config = require('./grafana/config.cjs.js');
+var backstagePluginGrafanaNode = require('@marble-sh/backstage-plugin-grafana-node');
+var CacheGrafanaStore = require('./store/CacheGrafanaStore.cjs.js');
+var DatabaseGrafanaStore = require('./store/DatabaseGrafanaStore.cjs.js');
+var GrafanaService = require('./service/GrafanaService.cjs.js');
+var router = require('./service/router.cjs.js');
+
+const grafanaPlugin = backendPluginApi.createBackendPlugin({
+  pluginId: "grafana",
+  register(env) {
+    env.registerInit({
+      deps: {
+        logger: backendPluginApi.coreServices.logger,
+        config: backendPluginApi.coreServices.rootConfig,
+        httpRouter: backendPluginApi.coreServices.httpRouter,
+        cache: backendPluginApi.coreServices.cache,
+        database: backendPluginApi.coreServices.database,
+        scheduler: backendPluginApi.coreServices.scheduler
+      },
+      async init({ logger, config: config$1, httpRouter, cache, database, scheduler }) {
+        const grafanaConfig = config.readGrafanaConfig(config$1);
+        if (grafanaConfig.instances.length === 0) {
+          logger.warn(
+            "No Grafana instances are configured under `grafana.instances`; the grafana plugin will return empty results"
+          );
+        }
+        const store = grafanaConfig.store === "database" ? await DatabaseGrafanaStore.DatabaseGrafanaStore.create({ database }) : new CacheGrafanaStore.CacheGrafanaStore({ cache, ttl: grafanaConfig.cacheTtl });
+        const instances = grafanaConfig.instances.map(
+          (instance) => ({
+            config: instance,
+            client: new backstagePluginGrafanaNode.GrafanaHttpClient({ instance })
+          })
+        );
+        const grafanaService = new GrafanaService.DefaultGrafanaService({
+          instances,
+          store,
+          logger,
+          fetchOnDemand: grafanaConfig.fetchOnDemand
+        });
+        httpRouter.use(
+          await router.createRouter({
+            grafanaService,
+            allowOnDemandRefresh: grafanaConfig.allowOnDemandRefresh
+          })
+        );
+        httpRouter.addAuthPolicy({ path: "/health", allow: "unauthenticated" });
+        if (grafanaConfig.schedule) {
+          await scheduler.scheduleTask({
+            id: "grafana-refresh",
+            ...grafanaConfig.schedule,
+            fn: async () => {
+              await grafanaService.refresh();
+            }
+          });
+          logger.info("Scheduled periodic Grafana refresh");
+        }
+      }
+    });
+  }
+});
+
+exports.grafanaPlugin = grafanaPlugin;
+//# sourceMappingURL=plugin.cjs.js.map

package/dist/plugin.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.cjs.js","sources":["../src/plugin.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 {\n  coreServices,\n  createBackendPlugin,\n} from '@backstage/backend-plugin-api';\nimport { readGrafanaConfig } from './grafana/config';\nimport { GrafanaHttpClient } from '@marble-sh/backstage-plugin-grafana-node';\nimport { CacheGrafanaStore } from './store/CacheGrafanaStore';\nimport { DatabaseGrafanaStore } from './store/DatabaseGrafanaStore';\nimport { GrafanaStore } from './store/GrafanaStore';\nimport {\n  DefaultGrafanaService,\n  GrafanaInstance,\n} from './service/GrafanaService';\nimport { createRouter } from './service/router';\n\n/**\n * The Grafana backend plugin.\n *\n * Reads dashboards and alerts from the configured Grafana instances, caches\n * them (in the cache or the database), optionally refreshes them on a schedule,\n * and exposes a read-only REST API under `/api/grafana`.\n *\n * @public\n */\nexport const grafanaPlugin = createBackendPlugin({\n  pluginId: 'grafana',\n  register(env) {\n    env.registerInit({\n      deps: {\n        logger: coreServices.logger,\n        config: coreServices.rootConfig,\n        httpRouter: coreServices.httpRouter,\n        cache: coreServices.cache,\n        database: coreServices.database,\n        scheduler: coreServices.scheduler,\n      },\n      async init({ logger, config, httpRouter, cache, database, scheduler }) {\n        const grafanaConfig = readGrafanaConfig(config);\n\n        if (grafanaConfig.instances.length === 0) {\n          logger.warn(\n            'No Grafana instances are configured under `grafana.instances`; the grafana plugin will return empty results',\n          );\n        }\n\n        const store: GrafanaStore =\n          grafanaConfig.store === 'database'\n            ? await DatabaseGrafanaStore.create({ database })\n            : new CacheGrafanaStore({ cache, ttl: grafanaConfig.cacheTtl });\n\n        const instances: GrafanaInstance[] = grafanaConfig.instances.map(\n          instance => ({\n            config: instance,\n            client: new GrafanaHttpClient({ instance }),\n          }),\n        );\n\n        const grafanaService = new DefaultGrafanaService({\n          instances,\n          store,\n          logger,\n          fetchOnDemand: grafanaConfig.fetchOnDemand,\n        });\n\n        httpRouter.use(\n          await createRouter({\n            grafanaService,\n            allowOnDemandRefresh: grafanaConfig.allowOnDemandRefresh,\n          }),\n        );\n        httpRouter.addAuthPolicy({ path: '/health', allow: 'unauthenticated' });\n\n        if (grafanaConfig.schedule) {\n          await scheduler.scheduleTask({\n            id: 'grafana-refresh',\n            ...grafanaConfig.schedule,\n            fn: async () => {\n              await grafanaService.refresh();\n            },\n          });\n          logger.info('Scheduled periodic Grafana refresh');\n        }\n      },\n    });\n  },\n});\n"],"names":["createBackendPlugin","coreServices","config","readGrafanaConfig","DatabaseGrafanaStore","CacheGrafanaStore","GrafanaHttpClient","DefaultGrafanaService","createRouter"],"mappings":";;;;;;;;;;AAwCO,MAAM,gBAAgBA,oCAAA,CAAoB;AAAA,EAC/C,QAAA,EAAU,SAAA;AAAA,EACV,SAAS,GAAA,EAAK;AACZ,IAAA,GAAA,CAAI,YAAA,CAAa;AAAA,MACf,IAAA,EAAM;AAAA,QACJ,QAAQC,6BAAA,CAAa,MAAA;AAAA,QACrB,QAAQA,6BAAA,CAAa,UAAA;AAAA,QACrB,YAAYA,6BAAA,CAAa,UAAA;AAAA,QACzB,OAAOA,6BAAA,CAAa,KAAA;AAAA,QACpB,UAAUA,6BAAA,CAAa,QAAA;AAAA,QACvB,WAAWA,6BAAA,CAAa;AAAA,OAC1B;AAAA,MACA,MAAM,KAAK,EAAE,MAAA,UAAQC,UAAQ,UAAA,EAAY,KAAA,EAAO,QAAA,EAAU,SAAA,EAAU,EAAG;AACrE,QAAA,MAAM,aAAA,GAAgBC,yBAAkBD,QAAM,CAAA;AAE9C,QAAA,IAAI,aAAA,CAAc,SAAA,CAAU,MAAA,KAAW,CAAA,EAAG;AACxC,UAAA,MAAA,CAAO,IAAA;AAAA,YACL;AAAA,WACF;AAAA,QACF;AAEA,QAAA,MAAM,QACJ,aAAA,CAAc,KAAA,KAAU,aACpB,MAAME,yCAAA,CAAqB,OAAO,EAAE,QAAA,EAAU,CAAA,GAC9C,IAAIC,mCAAA,CAAkB,EAAE,OAAO,GAAA,EAAK,aAAA,CAAc,UAAU,CAAA;AAElE,QAAA,MAAM,SAAA,GAA+B,cAAc,SAAA,CAAU,GAAA;AAAA,UAC3D,CAAA,QAAA,MAAa;AAAA,YACX,MAAA,EAAQ,QAAA;AAAA,YACR,MAAA,EAAQ,IAAIC,4CAAA,CAAkB,EAAE,UAAU;AAAA,WAC5C;AAAA,SACF;AAEA,QAAA,MAAM,cAAA,GAAiB,IAAIC,oCAAA,CAAsB;AAAA,UAC/C,SAAA;AAAA,UACA,KAAA;AAAA,UACA,MAAA;AAAA,UACA,eAAe,aAAA,CAAc;AAAA,SAC9B,CAAA;AAED,QAAA,UAAA,CAAW,GAAA;AAAA,UACT,MAAMC,mBAAA,CAAa;AAAA,YACjB,cAAA;AAAA,YACA,sBAAsB,aAAA,CAAc;AAAA,WACrC;AAAA,SACH;AACA,QAAA,UAAA,CAAW,cAAc,EAAE,IAAA,EAAM,SAAA,EAAW,KAAA,EAAO,mBAAmB,CAAA;AAEtE,QAAA,IAAI,cAAc,QAAA,EAAU;AAC1B,UAAA,MAAM,UAAU,YAAA,CAAa;AAAA,YAC3B,EAAA,EAAI,iBAAA;AAAA,YACJ,GAAG,aAAA,CAAc,QAAA;AAAA,YACjB,IAAI,YAAY;AACd,cAAA,MAAM,eAAe,OAAA,EAAQ;AAAA,YAC/B;AAAA,WACD,CAAA;AACD,UAAA,MAAA,CAAO,KAAK,oCAAoC,CAAA;AAAA,QAClD;AAAA,MACF;AAAA,KACD,CAAA;AAAA,EACH;AACF,CAAC;;"}

package/dist/service/GrafanaService.cjs.js

@@ -0,0 +1,121 @@
+'use strict';
+
+var errors = require('@backstage/errors');
+var backstagePluginGrafanaNode = require('@marble-sh/backstage-plugin-grafana-node');
+
+class DefaultGrafanaService {
+  instances;
+  store;
+  logger;
+  fetchOnDemand;
+  constructor(options) {
+    this.instances = new Map(
+      options.instances.map((instance) => [instance.config.name, instance])
+    );
+    this.store = options.store;
+    this.logger = options.logger;
+    this.fetchOnDemand = options.fetchOnDemand ?? true;
+  }
+  /** {@inheritDoc GrafanaService.getInstances} */
+  getInstances() {
+    return [...this.instances.values()].map(({ config }) => ({
+      name: config.name,
+      title: config.title,
+      url: config.baseUrl
+    }));
+  }
+  /** {@inheritDoc GrafanaService.getDashboards} */
+  async getDashboards(options) {
+    const names = this.resolveNames(options.instanceName);
+    const result = [];
+    for (const name of names) {
+      const snapshot = await this.snapshotFor(name, options.refresh);
+      result.push(
+        ...backstagePluginGrafanaNode.filterDashboards(snapshot.dashboards, {
+          tags: options.tags,
+          query: options.query
+        })
+      );
+    }
+    return result;
+  }
+  /** {@inheritDoc GrafanaService.getAlerts} */
+  async getAlerts(options) {
+    const names = this.resolveNames(options.instanceName);
+    const result = [];
+    for (const name of names) {
+      const snapshot = await this.snapshotFor(name, options.refresh);
+      result.push(
+        ...backstagePluginGrafanaNode.filterAlerts(snapshot.alerts, {
+          labelSelector: options.labelSelector
+        })
+      );
+    }
+    return result;
+  }
+  /** {@inheritDoc GrafanaService.refresh} */
+  async refresh(instanceName) {
+    if (instanceName) {
+      await this.refreshInstance(instanceName);
+      return;
+    }
+    for (const name of this.instances.keys()) {
+      try {
+        await this.refreshInstance(name);
+      } catch (error) {
+        this.logger.warn(
+          `Failed to refresh Grafana instance '${name}'`,
+          error
+        );
+      }
+    }
+  }
+  resolveNames(instanceName) {
+    if (instanceName) {
+      this.mustGet(instanceName);
+      return [instanceName];
+    }
+    return [...this.instances.keys()];
+  }
+  mustGet(instanceName) {
+    const instance = this.instances.get(instanceName);
+    if (!instance) {
+      throw new errors.NotFoundError(
+        `No Grafana instance configured with name '${instanceName}'`
+      );
+    }
+    return instance;
+  }
+  async snapshotFor(instanceName, refresh) {
+    if (!refresh) {
+      const cached = await this.store.get(instanceName);
+      if (cached) {
+        return cached;
+      }
+      if (!this.fetchOnDemand) {
+        return { dashboards: [], alerts: [] };
+      }
+    }
+    return this.refreshInstance(instanceName);
+  }
+  async refreshInstance(instanceName) {
+    const { client } = this.mustGet(instanceName);
+    const [dashboards, alerts] = await Promise.all([
+      client.listDashboards(),
+      client.listAlerts()
+    ]);
+    const snapshot = {
+      dashboards,
+      alerts,
+      fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await this.store.set(instanceName, snapshot);
+    this.logger.debug(
+      `Refreshed Grafana instance '${instanceName}': ${dashboards.length} dashboards, ${alerts.length} alerts`
+    );
+    return snapshot;
+  }
+}
+
+exports.DefaultGrafanaService = DefaultGrafanaService;
+//# sourceMappingURL=GrafanaService.cjs.js.map

package/dist/service/GrafanaService.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrafanaService.cjs.js","sources":["../../src/service/GrafanaService.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 { LoggerService } from '@backstage/backend-plugin-api';\nimport { NotFoundError } from '@backstage/errors';\nimport {\n  GrafanaAlert,\n  GrafanaDashboard,\n  GrafanaInstanceInfo,\n} from '@marble-sh/backstage-plugin-grafana-common';\nimport {\n  filterAlerts,\n  filterDashboards,\n  GrafanaClient,\n  GrafanaInstanceConfig,\n} from '@marble-sh/backstage-plugin-grafana-node';\nimport { GrafanaSnapshot, GrafanaStore } from '../store/GrafanaStore';\n\n/**\n * A configured instance together with the client used to read from it.\n *\n * @public\n */\nexport type GrafanaInstance = {\n  config: GrafanaInstanceConfig;\n  client: GrafanaClient;\n};\n\n/**\n * Options for reading dashboards through the service.\n *\n * @public\n */\nexport type GetDashboardsOptions = {\n  /** Restrict to a single instance. When omitted, all instances are queried. */\n  instanceName?: string;\n  /** Only return dashboards carrying all of these tags. */\n  tags?: string[];\n  /** Comma-separated title substrings; dashboards matching any are returned. */\n  query?: string;\n  /** Force a live fetch, bypassing the store. */\n  refresh?: boolean;\n};\n\n/**\n * Options for reading alerts through the service.\n *\n * @public\n */\nexport type GetAlertsOptions = {\n  /** Restrict to a single instance. When omitted, all instances are queried. */\n  instanceName?: string;\n  /** Only return alerts whose labels match all of these `key=value` pairs. */\n  labelSelector?: Record<string, string>;\n  /** Force a live fetch, bypassing the store. */\n  refresh?: boolean;\n};\n\n/**\n * Reads dashboards and alerts from the configured Grafana instances, backed by a\n * {@link GrafanaStore} for caching and periodic refresh.\n *\n * @public\n */\nexport interface GrafanaService {\n  /** Returns the configured Grafana instances. */\n  getInstances(): GrafanaInstanceInfo[];\n  /** Returns dashboards for one or all instances, honoring the store and filters. */\n  getDashboards(options: GetDashboardsOptions): Promise<GrafanaDashboard[]>;\n  /** Returns alerts for one or all instances, honoring the store and filters. */\n  getAlerts(options: GetAlertsOptions): Promise<GrafanaAlert[]>;\n  /** Refreshes a single instance, or all instances when no name is given. */\n  refresh(instanceName?: string): Promise<void>;\n}\n\n/**\n * The default {@link GrafanaService} implementation.\n *\n * @public\n */\nexport class DefaultGrafanaService implements GrafanaService {\n  private readonly instances: Map<string, GrafanaInstance>;\n  private readonly store: GrafanaStore;\n  private readonly logger: LoggerService;\n  private readonly fetchOnDemand: boolean;\n\n  constructor(options: {\n    instances: GrafanaInstance[];\n    store: GrafanaStore;\n    logger: LoggerService;\n    /**\n     * Whether a store miss triggers a live Grafana read (default `true`).\n     * When `false`, misses resolve to an empty snapshot and Grafana is only\n     * contacted by explicit {@link DefaultGrafanaService.refresh} calls (the\n     * schedule, the refresh endpoints, or a `refresh: true` read option).\n     */\n    fetchOnDemand?: boolean;\n  }) {\n    this.instances = new Map(\n      options.instances.map(instance => [instance.config.name, instance]),\n    );\n    this.store = options.store;\n    this.logger = options.logger;\n    this.fetchOnDemand = options.fetchOnDemand ?? true;\n  }\n\n  /** {@inheritDoc GrafanaService.getInstances} */\n  getInstances(): GrafanaInstanceInfo[] {\n    return [...this.instances.values()].map(({ config }) => ({\n      name: config.name,\n      title: config.title,\n      url: config.baseUrl,\n    }));\n  }\n\n  /** {@inheritDoc GrafanaService.getDashboards} */\n  async getDashboards(\n    options: GetDashboardsOptions,\n  ): Promise<GrafanaDashboard[]> {\n    const names = this.resolveNames(options.instanceName);\n    const result: GrafanaDashboard[] = [];\n    for (const name of names) {\n      const snapshot = await this.snapshotFor(name, options.refresh);\n      result.push(\n        ...filterDashboards(snapshot.dashboards, {\n          tags: options.tags,\n          query: options.query,\n        }),\n      );\n    }\n    return result;\n  }\n\n  /** {@inheritDoc GrafanaService.getAlerts} */\n  async getAlerts(options: GetAlertsOptions): Promise<GrafanaAlert[]> {\n    const names = this.resolveNames(options.instanceName);\n    const result: GrafanaAlert[] = [];\n    for (const name of names) {\n      const snapshot = await this.snapshotFor(name, options.refresh);\n      result.push(\n        ...filterAlerts(snapshot.alerts, {\n          labelSelector: options.labelSelector,\n        }),\n      );\n    }\n    return result;\n  }\n\n  /** {@inheritDoc GrafanaService.refresh} */\n  async refresh(instanceName?: string): Promise<void> {\n    if (instanceName) {\n      await this.refreshInstance(instanceName);\n      return;\n    }\n    for (const name of this.instances.keys()) {\n      try {\n        await this.refreshInstance(name);\n      } catch (error) {\n        this.logger.warn(\n          `Failed to refresh Grafana instance '${name}'`,\n          error as Error,\n        );\n      }\n    }\n  }\n\n  private resolveNames(instanceName?: string): string[] {\n    if (instanceName) {\n      this.mustGet(instanceName);\n      return [instanceName];\n    }\n    return [...this.instances.keys()];\n  }\n\n  private mustGet(instanceName: string): GrafanaInstance {\n    const instance = this.instances.get(instanceName);\n    if (!instance) {\n      throw new NotFoundError(\n        `No Grafana instance configured with name '${instanceName}'`,\n      );\n    }\n    return instance;\n  }\n\n  private async snapshotFor(\n    instanceName: string,\n    refresh?: boolean,\n  ): Promise<Pick<GrafanaSnapshot, 'dashboards' | 'alerts'>> {\n    if (!refresh) {\n      const cached = await this.store.get(instanceName);\n      if (cached) {\n        return cached;\n      }\n      if (!this.fetchOnDemand) {\n        // Serve the miss as empty rather than reaching for Grafana; nothing\n        // is stored, so results fill in as soon as a refresh runs.\n        return { dashboards: [], alerts: [] };\n      }\n    }\n    return this.refreshInstance(instanceName);\n  }\n\n  private async refreshInstance(\n    instanceName: string,\n  ): Promise<GrafanaSnapshot> {\n    const { client } = this.mustGet(instanceName);\n    const [dashboards, alerts] = await Promise.all([\n      client.listDashboards(),\n      client.listAlerts(),\n    ]);\n    const snapshot: GrafanaSnapshot = {\n      dashboards,\n      alerts,\n      fetchedAt: new Date().toISOString(),\n    };\n    await this.store.set(instanceName, snapshot);\n    this.logger.debug(\n      `Refreshed Grafana instance '${instanceName}': ${dashboards.length} dashboards, ${alerts.length} alerts`,\n    );\n    return snapshot;\n  }\n}\n"],"names":["filterDashboards","filterAlerts","NotFoundError"],"mappings":"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"}

package/dist/service/router.cjs.js

@@ -0,0 +1,88 @@
+'use strict';
+
+var express = require('express');
+var Router = require('express-promise-router');
+var errors = require('@backstage/errors');
+var backstagePluginGrafanaNode = require('@marble-sh/backstage-plugin-grafana-node');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var express__default = /*#__PURE__*/_interopDefaultCompat(express);
+var Router__default = /*#__PURE__*/_interopDefaultCompat(Router);
+
+const toArray = (value) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  return Array.isArray(value) ? value.map(String) : [String(value)];
+};
+const toString = (value) => value === void 0 ? void 0 : String(value);
+const toBoolean = (value) => value !== void 0 && ["true", "1", ""].includes(String(value));
+async function createRouter(options) {
+  const { grafanaService } = options;
+  const allowOnDemandRefresh = options.allowOnDemandRefresh ?? true;
+  const router = Router__default.default();
+  router.use(express__default.default.json());
+  const toRefresh = (value) => allowOnDemandRefresh && toBoolean(value);
+  const assertRefreshAllowed = () => {
+    if (!allowOnDemandRefresh) {
+      throw new errors.NotAllowedError(
+        "On-demand refresh is disabled by configuration (grafana.allowOnDemandRefresh)"
+      );
+    }
+  };
+  router.get("/health", (_req, res) => {
+    res.json({ status: "ok" });
+  });
+  router.get("/instances", (_req, res) => {
+    res.json({ items: grafanaService.getInstances() });
+  });
+  router.get("/instances/:name/dashboards", async (req, res) => {
+    const items = await grafanaService.getDashboards({
+      instanceName: req.params.name,
+      tags: toArray(req.query.tag),
+      query: toString(req.query.query),
+      refresh: toRefresh(req.query.refresh)
+    });
+    res.json({ items });
+  });
+  router.get("/instances/:name/alerts", async (req, res) => {
+    const items = await grafanaService.getAlerts({
+      instanceName: req.params.name,
+      labelSelector: backstagePluginGrafanaNode.parseLabelSelector(toString(req.query.labelSelector)),
+      refresh: toRefresh(req.query.refresh)
+    });
+    res.json({ items });
+  });
+  router.post("/instances/:name/refresh", async (req, res) => {
+    assertRefreshAllowed();
+    await grafanaService.refresh(req.params.name);
+    res.json({ status: "ok" });
+  });
+  router.get("/dashboards", async (req, res) => {
+    const items = await grafanaService.getDashboards({
+      instanceName: toString(req.query.instance),
+      tags: toArray(req.query.tag),
+      query: toString(req.query.query),
+      refresh: toRefresh(req.query.refresh)
+    });
+    res.json({ items });
+  });
+  router.get("/alerts", async (req, res) => {
+    const items = await grafanaService.getAlerts({
+      instanceName: toString(req.query.instance),
+      labelSelector: backstagePluginGrafanaNode.parseLabelSelector(toString(req.query.labelSelector)),
+      refresh: toRefresh(req.query.refresh)
+    });
+    res.json({ items });
+  });
+  router.post("/refresh", async (_req, res) => {
+    assertRefreshAllowed();
+    await grafanaService.refresh();
+    res.json({ status: "ok" });
+  });
+  return router;
+}
+
+exports.createRouter = createRouter;
+//# sourceMappingURL=router.cjs.js.map

package/dist/service/router.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.cjs.js","sources":["../../src/service/router.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 express from 'express';\nimport Router from 'express-promise-router';\nimport { NotAllowedError } from '@backstage/errors';\nimport { parseLabelSelector } from '@marble-sh/backstage-plugin-grafana-node';\nimport { GrafanaService } from './GrafanaService';\n\nconst toArray = (value: unknown): string[] | undefined => {\n  if (value === undefined) {\n    return undefined;\n  }\n  return Array.isArray(value) ? value.map(String) : [String(value)];\n};\n\nconst toString = (value: unknown): string | undefined =>\n  value === undefined ? undefined : String(value);\n\n// Accepts ?refresh=true, ?refresh=1, and the bare ?refresh flag.\nconst toBoolean = (value: unknown): boolean =>\n  value !== undefined && ['true', '1', ''].includes(String(value));\n\n/**\n * Creates the Express router that exposes the read-only Grafana REST API.\n *\n * All routes are relative to the plugin base path (`/api/grafana`).\n *\n * @public\n */\nexport async function createRouter(options: {\n  grafanaService: GrafanaService;\n  /**\n   * Whether callers may force live Grafana reads (default `true`). When\n   * `false`, `refresh` query parameters are ignored and the `POST …/refresh`\n   * routes respond 403.\n   */\n  allowOnDemandRefresh?: boolean;\n}): Promise<express.Router> {\n  const { grafanaService } = options;\n  const allowOnDemandRefresh = options.allowOnDemandRefresh ?? true;\n  const router = Router();\n  router.use(express.json());\n\n  const toRefresh = (value: unknown): boolean =>\n    allowOnDemandRefresh && toBoolean(value);\n\n  const assertRefreshAllowed = () => {\n    if (!allowOnDemandRefresh) {\n      throw new NotAllowedError(\n        'On-demand refresh is disabled by configuration (grafana.allowOnDemandRefresh)',\n      );\n    }\n  };\n\n  router.get('/health', (_req, res) => {\n    res.json({ status: 'ok' });\n  });\n\n  router.get('/instances', (_req, res) => {\n    res.json({ items: grafanaService.getInstances() });\n  });\n\n  router.get('/instances/:name/dashboards', async (req, res) => {\n    const items = await grafanaService.getDashboards({\n      instanceName: req.params.name,\n      tags: toArray(req.query.tag),\n      query: toString(req.query.query),\n      refresh: toRefresh(req.query.refresh),\n    });\n    res.json({ items });\n  });\n\n  router.get('/instances/:name/alerts', async (req, res) => {\n    const items = await grafanaService.getAlerts({\n      instanceName: req.params.name,\n      labelSelector: parseLabelSelector(toString(req.query.labelSelector)),\n      refresh: toRefresh(req.query.refresh),\n    });\n    res.json({ items });\n  });\n\n  router.post('/instances/:name/refresh', async (req, res) => {\n    assertRefreshAllowed();\n    await grafanaService.refresh(req.params.name);\n    res.json({ status: 'ok' });\n  });\n\n  router.get('/dashboards', async (req, res) => {\n    const items = await grafanaService.getDashboards({\n      instanceName: toString(req.query.instance),\n      tags: toArray(req.query.tag),\n      query: toString(req.query.query),\n      refresh: toRefresh(req.query.refresh),\n    });\n    res.json({ items });\n  });\n\n  router.get('/alerts', async (req, res) => {\n    const items = await grafanaService.getAlerts({\n      instanceName: toString(req.query.instance),\n      labelSelector: parseLabelSelector(toString(req.query.labelSelector)),\n      refresh: toRefresh(req.query.refresh),\n    });\n    res.json({ items });\n  });\n\n  router.post('/refresh', async (_req, res) => {\n    assertRefreshAllowed();\n    await grafanaService.refresh();\n    res.json({ status: 'ok' });\n  });\n\n  return router;\n}\n"],"names":["Router","express","NotAllowedError","parseLabelSelector"],"mappings":"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"}

package/dist/store/CacheGrafanaStore.cjs.js

@@ -0,0 +1,29 @@
+'use strict';
+
+var types = require('@backstage/types');
+
+class CacheGrafanaStore {
+  cache;
+  ttlMillis;
+  constructor(options) {
+    this.cache = options.cache;
+    this.ttlMillis = types.durationToMilliseconds(options.ttl);
+  }
+  key(instanceName) {
+    return `grafana-snapshot:${instanceName}`;
+  }
+  /** {@inheritDoc GrafanaStore.get} */
+  async get(instanceName) {
+    const value = await this.cache.get(this.key(instanceName));
+    return value;
+  }
+  /** {@inheritDoc GrafanaStore.set} */
+  async set(instanceName, snapshot) {
+    await this.cache.set(this.key(instanceName), snapshot, {
+      ttl: this.ttlMillis
+    });
+  }
+}
+
+exports.CacheGrafanaStore = CacheGrafanaStore;
+//# sourceMappingURL=CacheGrafanaStore.cjs.js.map

package/dist/store/CacheGrafanaStore.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheGrafanaStore.cjs.js","sources":["../../src/store/CacheGrafanaStore.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 { CacheService } from '@backstage/backend-plugin-api';\nimport { HumanDuration, durationToMilliseconds } from '@backstage/types';\nimport { GrafanaSnapshot, GrafanaStore } from './GrafanaStore';\n\n/**\n * A {@link GrafanaStore} backed by the Backstage cache service. Snapshots are\n * ephemeral and expire after the configured TTL.\n *\n * @public\n */\nexport class CacheGrafanaStore implements GrafanaStore {\n  private readonly cache: CacheService;\n  private readonly ttlMillis: number;\n\n  constructor(options: { cache: CacheService; ttl: HumanDuration }) {\n    this.cache = options.cache;\n    this.ttlMillis = durationToMilliseconds(options.ttl);\n  }\n\n  private key(instanceName: string): string {\n    return `grafana-snapshot:${instanceName}`;\n  }\n\n  /** {@inheritDoc GrafanaStore.get} */\n  async get(instanceName: string): Promise<GrafanaSnapshot | undefined> {\n    const value = await this.cache.get(this.key(instanceName));\n    return value as GrafanaSnapshot | undefined;\n  }\n\n  /** {@inheritDoc GrafanaStore.set} */\n  async set(instanceName: string, snapshot: GrafanaSnapshot): Promise<void> {\n    await this.cache.set(this.key(instanceName), snapshot as any, {\n      ttl: this.ttlMillis,\n    });\n  }\n}\n"],"names":["durationToMilliseconds"],"mappings":";;;;AA0BO,MAAM,iBAAA,CAA0C;AAAA,EACpC,KAAA;AAAA,EACA,SAAA;AAAA,EAEjB,YAAY,OAAA,EAAsD;AAChE,IAAA,IAAA,CAAK,QAAQ,OAAA,CAAQ,KAAA;AACrB,IAAA,IAAA,CAAK,SAAA,GAAYA,4BAAA,CAAuB,OAAA,CAAQ,GAAG,CAAA;AAAA,EACrD;AAAA,EAEQ,IAAI,YAAA,EAA8B;AACxC,IAAA,OAAO,oBAAoB,YAAY,CAAA,CAAA;AAAA,EACzC;AAAA;AAAA,EAGA,MAAM,IAAI,YAAA,EAA4D;AACpE,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,KAAA,CAAM,IAAI,IAAA,CAAK,GAAA,CAAI,YAAY,CAAC,CAAA;AACzD,IAAA,OAAO,KAAA;AAAA,EACT;AAAA;AAAA,EAGA,MAAM,GAAA,CAAI,YAAA,EAAsB,QAAA,EAA0C;AACxE,IAAA,MAAM,KAAK,KAAA,CAAM,GAAA,CAAI,KAAK,GAAA,CAAI,YAAY,GAAG,QAAA,EAAiB;AAAA,MAC5D,KAAK,IAAA,CAAK;AAAA,KACX,CAAA;AAAA,EACH;AACF;;"}

package/dist/store/DatabaseGrafanaStore.cjs.js

@@ -0,0 +1,62 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+
+const migrationsDir = backendPluginApi.resolvePackagePath(
+  "@marble-sh/backstage-plugin-grafana-backend",
+  "migrations"
+);
+const TABLE = "grafana__snapshots";
+class DatabaseGrafanaStore {
+  constructor(knex) {
+    this.knex = knex;
+  }
+  knex;
+  /**
+   * Creates the store from the database core service, running migrations
+   * unless the integrator has configured them to be skipped.
+   */
+  static async create(options) {
+    const knex = await options.database.getClient();
+    if (options.database.migrations?.skip) {
+      return new DatabaseGrafanaStore(knex);
+    }
+    return DatabaseGrafanaStore.fromKnex(knex);
+  }
+  /**
+   * Creates the store from a raw Knex client, running migrations. Primarily
+   * intended for testing.
+   */
+  static async fromKnex(knex) {
+    await knex.migrate.latest({
+      directory: migrationsDir,
+      tableName: "grafana__knex_migrations"
+    });
+    return new DatabaseGrafanaStore(knex);
+  }
+  /** {@inheritDoc GrafanaStore.get} */
+  async get(instanceName) {
+    const row = await this.knex(TABLE).where({ instance: instanceName }).first();
+    if (!row) {
+      return void 0;
+    }
+    return {
+      dashboards: JSON.parse(row.dashboards),
+      alerts: JSON.parse(row.alerts),
+      fetchedAt: row.fetched_at
+    };
+  }
+  /** {@inheritDoc GrafanaStore.set} */
+  async set(instanceName, snapshot) {
+    const row = {
+      instance: instanceName,
+      dashboards: JSON.stringify(snapshot.dashboards),
+      alerts: JSON.stringify(snapshot.alerts),
+      fetched_at: snapshot.fetchedAt
+    };
+    await this.knex(TABLE).insert(row).onConflict("instance").merge();
+  }
+}
+
+exports.DatabaseGrafanaStore = DatabaseGrafanaStore;
+//# sourceMappingURL=DatabaseGrafanaStore.cjs.js.map

package/dist/store/DatabaseGrafanaStore.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseGrafanaStore.cjs.js","sources":["../../src/store/DatabaseGrafanaStore.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 {\n  DatabaseService,\n  resolvePackagePath,\n} from '@backstage/backend-plugin-api';\nimport { Knex } from 'knex';\nimport { GrafanaSnapshot, GrafanaStore } from './GrafanaStore';\n\nconst migrationsDir = resolvePackagePath(\n  '@marble-sh/backstage-plugin-grafana-backend',\n  'migrations',\n);\n\nconst TABLE = 'grafana__snapshots';\n\ntype SnapshotRow = {\n  instance: string;\n  dashboards: string;\n  alerts: string;\n  fetched_at: string;\n};\n\n/**\n * A {@link GrafanaStore} backed by the Backstage database service. Snapshots are\n * durable and survive restarts.\n *\n * @public\n */\nexport class DatabaseGrafanaStore implements GrafanaStore {\n  private constructor(private readonly knex: Knex) {}\n\n  /**\n   * Creates the store from the database core service, running migrations\n   * unless the integrator has configured them to be skipped.\n   */\n  static async create(options: {\n    database: DatabaseService;\n  }): Promise<DatabaseGrafanaStore> {\n    const knex = await options.database.getClient();\n    if (options.database.migrations?.skip) {\n      return new DatabaseGrafanaStore(knex);\n    }\n    return DatabaseGrafanaStore.fromKnex(knex);\n  }\n\n  /**\n   * Creates the store from a raw Knex client, running migrations. Primarily\n   * intended for testing.\n   */\n  static async fromKnex(knex: Knex): Promise<DatabaseGrafanaStore> {\n    await knex.migrate.latest({\n      directory: migrationsDir,\n      tableName: 'grafana__knex_migrations',\n    });\n    return new DatabaseGrafanaStore(knex);\n  }\n\n  /** {@inheritDoc GrafanaStore.get} */\n  async get(instanceName: string): Promise<GrafanaSnapshot | undefined> {\n    const row = await this.knex<SnapshotRow>(TABLE)\n      .where({ instance: instanceName })\n      .first();\n    if (!row) {\n      return undefined;\n    }\n    return {\n      dashboards: JSON.parse(row.dashboards),\n      alerts: JSON.parse(row.alerts),\n      fetchedAt: row.fetched_at,\n    };\n  }\n\n  /** {@inheritDoc GrafanaStore.set} */\n  async set(instanceName: string, snapshot: GrafanaSnapshot): Promise<void> {\n    const row: SnapshotRow = {\n      instance: instanceName,\n      dashboards: JSON.stringify(snapshot.dashboards),\n      alerts: JSON.stringify(snapshot.alerts),\n      fetched_at: snapshot.fetchedAt,\n    };\n    await this.knex<SnapshotRow>(TABLE)\n      .insert(row)\n      .onConflict('instance')\n      .merge();\n  }\n}\n"],"names":["resolvePackagePath"],"mappings":";;;;AAuBA,MAAM,aAAA,GAAgBA,mCAAA;AAAA,EACpB,6CAAA;AAAA,EACA;AACF,CAAA;AAEA,MAAM,KAAA,GAAQ,oBAAA;AAeP,MAAM,oBAAA,CAA6C;AAAA,EAChD,YAA6B,IAAA,EAAY;AAAZ,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAAA,EAAa;AAAA,EAAb,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMrC,aAAa,OAAO,OAAA,EAEc;AAChC,IAAA,MAAM,IAAA,GAAO,MAAM,OAAA,CAAQ,QAAA,CAAS,SAAA,EAAU;AAC9C,IAAA,IAAI,OAAA,CAAQ,QAAA,CAAS,UAAA,EAAY,IAAA,EAAM;AACrC,MAAA,OAAO,IAAI,qBAAqB,IAAI,CAAA;AAAA,IACtC;AACA,IAAA,OAAO,oBAAA,CAAqB,SAAS,IAAI,CAAA;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,aAAa,SAAS,IAAA,EAA2C;AAC/D,IAAA,MAAM,IAAA,CAAK,QAAQ,MAAA,CAAO;AAAA,MACxB,SAAA,EAAW,aAAA;AAAA,MACX,SAAA,EAAW;AAAA,KACZ,CAAA;AACD,IAAA,OAAO,IAAI,qBAAqB,IAAI,CAAA;AAAA,EACtC;AAAA;AAAA,EAGA,MAAM,IAAI,YAAA,EAA4D;AACpE,IAAA,MAAM,GAAA,GAAM,MAAM,IAAA,CAAK,IAAA,CAAkB,KAAK,CAAA,CAC3C,KAAA,CAAM,EAAE,QAAA,EAAU,YAAA,EAAc,CAAA,CAChC,KAAA,EAAM;AACT,IAAA,IAAI,CAAC,GAAA,EAAK;AACR,MAAA,OAAO,MAAA;AAAA,IACT;AACA,IAAA,OAAO;AAAA,MACL,UAAA,EAAY,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,UAAU,CAAA;AAAA,MACrC,MAAA,EAAQ,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,MAAM,CAAA;AAAA,MAC7B,WAAW,GAAA,CAAI;AAAA,KACjB;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,GAAA,CAAI,YAAA,EAAsB,QAAA,EAA0C;AACxE,IAAA,MAAM,GAAA,GAAmB;AAAA,MACvB,QAAA,EAAU,YAAA;AAAA,MACV,UAAA,EAAY,IAAA,CAAK,SAAA,CAAU,QAAA,CAAS,UAAU,CAAA;AAAA,MAC9C,MAAA,EAAQ,IAAA,CAAK,SAAA,CAAU,QAAA,CAAS,MAAM,CAAA;AAAA,MACtC,YAAY,QAAA,CAAS;AAAA,KACvB;AACA,IAAA,MAAM,IAAA,CAAK,IAAA,CAAkB,KAAK,CAAA,CAC/B,MAAA,CAAO,GAAG,CAAA,CACV,UAAA,CAAW,UAAU,CAAA,CACrB,KAAA,EAAM;AAAA,EACX;AACF;;"}

package/migrations/20260826000000_init.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2026 Cassidy Marble
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.up = async function up(knex) {
+  await knex.schema.createTable('grafana__snapshots', table => {
+    table.comment('Latest Grafana data snapshot per configured instance');
+    table
+      .string('instance')
+      .primary()
+      .notNullable()
+      .comment('The configured Grafana instance name');
+    table
+      .text('dashboards')
+      .notNullable()
+      .comment('JSON-encoded array of dashboards');
+    table.text('alerts').notNullable().comment('JSON-encoded array of alerts');
+    table
+      .text('fetched_at')
+      .notNullable()
+      .comment('ISO-8601 timestamp of when the snapshot was read from Grafana');
+  });
+};
+
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.down = async function down(knex) {
+  await knex.schema.dropTable('grafana__snapshots');
+};

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@marble-sh/backstage-plugin-grafana-backend",
+  "version": "0.2.0",
+  "description": "Backend for the Grafana Backstage plugin: reads dashboards and alerts from Grafana, caches them, and exposes a read-only REST API",
+  "main": "./dist/index.cjs.js",
+  "types": "./dist/index.d.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "backstage": {
+    "role": "backend-plugin",
+    "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"
+    ],
+    "features": {
+      ".": "@backstage/BackendFeature"
+    }
+  },
+  "sideEffects": false,
+  "configSchema": "config.schema.json",
+  "scripts": {
+    "start": "backstage-cli package start",
+    "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/backend-plugin-api": "backstage:^",
+    "@backstage/config": "backstage:^",
+    "@backstage/errors": "backstage:^",
+    "@backstage/types": "backstage:^",
+    "@marble-sh/backstage-plugin-grafana-common": "workspace:^",
+    "@marble-sh/backstage-plugin-grafana-node": "workspace:^",
+    "express": "^4.17.1",
+    "express-promise-router": "^4.1.0",
+    "knex": "^3.0.0"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "backstage:^",
+    "@backstage/cli": "backstage:^",
+    "@types/express": "^4.17.6",
+    "@types/supertest": "^2.0.12",
+    "supertest": "^6.2.4"
+  },
+  "files": [
+    "dist",
+    "config.schema.json",
+    "migrations/**/*.{js,d.ts}"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marble-sh/backstage-plugins-grafana",
+    "directory": "plugins/grafana-backend"
+  },
+  "keywords": [
+    "backstage",
+    "plugin",
+    "grafana"
+  ],
+  "author": "Cassidy Marble",
+  "homepage": "https://github.com/marble-sh/backstage-plugins-grafana/tree/main/plugins/grafana-backend",
+  "bugs": "https://github.com/marble-sh/backstage-plugins-grafana/issues",
+  "exports": {
+    ".": {
+      "backstage": "@backstage/BackendFeature",
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "package.json": [
+        "package.json"
+      ]
+    }
+  }
+}