@nospt/backstage-plugin-apigee-backend 1.1.0-rc2

package/README.md

@@ -0,0 +1,118 @@
+# @nospt/backstage-plugin-apigee-backend
+
+Backend package for the bootstrap stage of the Backstage Apigee plugin.
+
+## Included
+
+- New Backend System plugin registration
+- Minimal router mounted at `/api/apigee`
+- Placeholder health endpoint at `/api/apigee/health`
+
+## Development
+
+```bash
+cd plugins/apigee-backend
+yarn start
+yarn test
+yarn lint
+yarn build
+```
+
+## Repository Stitching
+
+A Backstage `CatalogProcessor` (`ApigeeStitchingProcessor`) links a backend
+`Component` to its proxy `API` entity by emitting the native `providesApi` /
+`apiProvidedBy` relations. This surfaces the standard **"Provided APIs"** card on
+the component page and the **"Providers"** card on the API page — with zero custom
+UI. A repository opts in by adding `nos.pt/apigee-*` annotations to its
+`catalog-info.yaml`.
+
+### Annotation styles
+
+**Direct mapping (active in this release):**
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: orders-service
+  annotations:
+    nos.pt/apigee-api-name: my-proxy
+    nos.pt/apigee-project-id: apigee-x-public-p-123
+spec:
+  type: service
+  owner: team-orders
+  lifecycle: production
+```
+
+**TargetServer-based mapping (documented; resolution planned, not yet active):**
+
+```yaml
+metadata:
+  annotations:
+    nos.pt/apigee-targetserver-hostname: backend.nos.pt
+    nos.pt/apigee-targetserver-port: "443"
+```
+
+### Precedence rule
+
+When both styles are present, the **TargetServer-based mapping is the preferred**
+resolution path (STITCH-02). The direct API-name mapping is the **fallback**, used
+when no TargetServer annotation is present or when TargetServer resolution is
+ambiguous (for example, a generic load balancer shared by many proxies).
+
+> **In this release only the direct-mapping path is implemented.** TargetServer
+> resolution is planned but not yet active — no TargetServer data is captured by the
+> entity provider yet (see `04-CONTEXT` D-01). The processor is structured around a
+> resolution-strategy seam so the TargetServer branch slots in without rework.
+
+### Apigee → Backstage mapping
+
+| Apigee concept | Backstage entity |
+|----------------|------------------|
+| API proxy (implementation) | `kind: Component`, `spec.type: api-proxy` |
+| API proxy (contract) | `kind: API`, `spec.type` from API Hub (default `openapi`) |
+| Sharedflow | `kind: Component`, `spec.type: library` |
+| Backend repo component ↔ proxy API | `providesApi` / `apiProvidedBy` relation |
+
+### Resolution detail
+
+The target API entity ref is deterministic:
+`api:default/<slugify(nos.pt/apigee-api-name)>`. The processor reads the annotations,
+synthesizes the ref, and emits the relation pair — no live catalog lookup is needed.
+A partial annotation set (e.g. `nos.pt/apigee-api-name` without
+`nos.pt/apigee-project-id`) or an empty/unresolvable value is skipped with a warning
+(warn-and-skip), so no malformed relations are emitted.
+
+### Example fixture
+
+See [`examples/components.yaml`](./examples/components.yaml) for ready-to-register
+sample `Component` entities exercising both annotation styles — useful for local
+smoke testing of the stitching processor.
+
+## API Hub enrichment
+
+`kind: API` entities discovered from Apigee are enriched with API Hub metadata
+(owner, description, categories, department, spec). The **"Source repository"** link
+on the API entity page (`metadata.links`) is resolved in this order:
+
+1. API Hub **Documentation** field (`Api.documentation.externalUri`) — NOS records
+   the proxy's GitHub repository URL here (e.g.
+   `https://github.com/nosportugal/apigee-x-proxy-<proxy-name>`).
+2. The first `sourceMetadata[]` entry whose value is an `http(s)` URL
+   (`repo`/`git`/`source` types preferred when several qualify).
+3. The `apigee.orgs[].githubOrgSlug` convention:
+   `https://github.com/<slug>/<entity-name>`.
+
+Only `http(s)` URLs are ever emitted; `javascript:`/`data:` values are rejected to
+prevent link injection into rendered entity pages.
+
+### Department label
+
+Both the proxy `kind: Component` and its `kind: API` entity carry a `department`
+label (`metadata.labels.department`) sourced from the Cloud API Hub **Business
+unit** attribute. Business unit is a top-level API Hub `AttributeValues` field; a
+user-modelled `business-unit` attribute is scanned only as a fallback. The raw
+value is slugified and capped at 63 characters so it is always a valid Backstage
+label value. The frontend catalog page exposes it as a **Department** filter
+facet.

package/config.d.ts

@@ -0,0 +1,85 @@
+export interface Config {
+  /** Apigee catalog module configuration */
+  apigee?: {
+    /**
+     * List of Apigee X organisations to sync.
+     * At least one entry is required; the module fails fast at startup if missing.
+     * @visibility backend
+     */
+    orgs: Array<{
+      /** Human-readable label for this org */
+      name: string;
+      /** GCP project ID that owns this Apigee X organisation */
+      projectId: string;
+      /**
+       * Optional list of environments to include (e.g. ["prod", "staging"]).
+       * If omitted, all environments are synced.
+       * @visibility backend
+       */
+      environments?: string[];
+      /**
+       * Optional GitHub organisation slug used to derive GitHub repo links
+       * when API Hub does not supply a repositoryUri (FR17).
+       * @visibility backend
+       */
+      githubOrgSlug?: string;
+      /**
+       * Explicit proxy-name -> API Hub apiId overrides for proxies whose slug
+       * does not match their API Hub apiId (D-01).
+       * @visibility backend
+       */
+      apiHubMappings?: { [proxyName: string]: string };
+    }>;
+    /**
+     * Catalog sync interval in minutes. Default: 60.
+     * @visibility backend
+     */
+    syncIntervalMinutes?: number;
+    /**
+     * Default spec.owner for API entities whose API Hub ownerTeam is absent.
+     * Must be a Backstage entity reference, e.g. "group:default/platform-team".
+     * @visibility backend
+     */
+    defaultOwner?: string;
+    /**
+     * Maximum inline spec size in bytes; specs larger than this are linked via
+     * apigee.com/spec-url instead of embedded. Default 512000 (500 KB).
+     * @visibility backend
+     */
+    specMaxBytes?: number;
+    /**
+     * Optional map of Apigee environment name to Backstage lifecycle
+     * ("production" | "experimental" | "deprecated"). When set, a proxy's
+     * lifecycle is derived from the environments it is deployed to, with the
+     * highest-ranked lifecycle winning (production > experimental > deprecated).
+     * Environments not listed default to "experimental". When omitted, any
+     * ready deployment marks the proxy as "production".
+     * @visibility backend
+     */
+    environmentLifecycle?: { [environment: string]: string };
+    /**
+     * API Hub location (GCP region) to query. Defaults to "global".
+     * Use this when your API Hub instance is regional, e.g. "europe-west1".
+     * @visibility backend
+     */
+    apiHubLocation?: string;
+    /**
+     * Optional custom schedule for the catalog sync task.
+     * When provided, overrides syncIntervalMinutes.
+     * @visibility backend
+     */
+    schedule?: {
+      /** How often to run the sync. */
+      frequency?: {
+        cron?: string;
+        minutes?: number;
+        hours?: number;
+        seconds?: number;
+      };
+      /** Maximum time allowed for a single sync run. */
+      timeout?: { minutes?: number; seconds?: number };
+      /** Delay before the first run after startup. */
+      initialDelay?: { minutes?: number; seconds?: number };
+    };
+  };
+}

package/dist/index.cjs.js

@@ -0,0 +1,22 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var plugin = require('./plugin.cjs.js');
+var module$1 = require('./module.cjs.js');
+var apigeeClient = require('./lib/apigee-client.cjs.js');
+var apiHubClient = require('./lib/api-hub-client.cjs.js');
+var entityProvider = require('./lib/entity-provider.cjs.js');
+var sharedflowClient = require('./lib/sharedflow-client.cjs.js');
+var apigeeStitchingProcessor = require('./lib/apigee-stitching-processor.cjs.js');
+
+
+
+exports.default = plugin.apigeePlugin;
+exports.catalogModuleApigee = module$1.catalogModuleApigee;
+exports.ApigeeClient = apigeeClient.ApigeeClient;
+exports.ApiHubClient = apiHubClient.ApiHubClient;
+exports.ApigeeEntityProvider = entityProvider.ApigeeEntityProvider;
+exports.SharedflowClient = sharedflowClient.SharedflowClient;
+exports.ApigeeStitchingProcessor = apigeeStitchingProcessor.ApigeeStitchingProcessor;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

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