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

package/dist/index.d.ts

@@ -0,0 +1,511 @@
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+import { SchedulerServiceTaskRunner, LoggerService } from '@backstage/backend-plugin-api';
+import { GoogleAuth } from 'google-auth-library';
+import { EntityProvider, EntityProviderConnection, CatalogProcessor, LocationSpec, CatalogProcessorEmit } from '@backstage/plugin-catalog-node';
+import { Entity } from '@backstage/catalog-model';
+
+declare const apigeePlugin: _backstage_backend_plugin_api.BackendFeature;
+
+/**
+ * Backstage catalog backend module for Apigee API discovery.
+ * Plugs into the catalog backend and registers Apigee proxies + API Hub
+ * definitions as Backstage API entities.
+ */
+declare const catalogModuleApigee: _backstage_backend_plugin_api.BackendFeature;
+
+/** Represents a single Apigee API proxy entry from GET /organizations/{org}/apis */
+interface ApigeeProxy {
+    /** Proxy name as registered in Apigee (may contain dots/underscores — slugify before use as metadata.name) */
+    name: string;
+    /** Array of revision numbers (strings), most recent last */
+    revision?: string[];
+    /** ISO 8601 creation timestamp */
+    createdAt?: string;
+    /** ISO 8601 last-modified timestamp */
+    lastModifiedAt?: string;
+}
+/** Represents one environment deployment from GET /organizations/{org}/apis/{proxy}/deployments */
+interface ApigeeDeployment {
+    /** Environment name (e.g. "prod", "staging") */
+    environment: string;
+    /** Deployed API proxy revision (string, e.g. "1") — field name matches the Apigee API. */
+    revision?: string;
+    /** Deployment state: READY | PROGRESSING | ERROR (omitted by the list endpoint). */
+    state?: string;
+}
+/**
+ * Represents a single proxy revision detail from
+ * GET /organizations/{org}/apis/{proxy}/revisions/{rev}
+ */
+interface ApigeeProxyRevision {
+    name: string;
+    revision?: string;
+    /** Base paths declared in the proxy bundle (used for apigee.com/base-path annotation) */
+    basepaths?: string[];
+    description?: string;
+    /** Resource files attached to this revision */
+    resourceFiles?: {
+        resourceFile?: Array<{
+            name: string;
+            type: string;
+        }>;
+    };
+}
+/**
+ * Read-only HTTP client for the Apigee Management API v1.
+ *
+ * Auth: uses GCP Application Default Credentials via the injected GoogleAuth
+ * instance. All calls are GET-only (AUTH-02: read-only IAM roles).
+ *
+ * Usage:
+ * ```typescript
+ * const auth = new GoogleAuth({ scopes: ['https://www.googleapis.com/auth/cloud-platform'] });
+ * const client = new ApigeeClient(auth);
+ * const proxies = await client.listProxies('my-apigee-org');
+ * ```
+ */
+declare class ApigeeClient {
+    private readonly auth;
+    constructor(auth: GoogleAuth);
+    /**
+     * Lists all API proxies in the given Apigee organisation.
+     * Calls: GET /organizations/{org}/apis
+     */
+    listProxies(org: string): Promise<ApigeeProxy[]>;
+    /**
+     * Lists all environment deployments for a given proxy.
+     * Calls: GET /organizations/{org}/apis/{proxy}/deployments
+     */
+    listDeployments(org: string, proxy: string): Promise<ApigeeDeployment[]>;
+    /**
+     * Fetches full detail for a specific proxy revision.
+     * Calls: GET /organizations/{org}/apis/{proxy}/revisions/{rev}
+     */
+    getProxyRevision(org: string, proxy: string, rev: string): Promise<ApigeeProxyRevision>;
+}
+
+/** One allowed value of a Cloud API Hub enum attribute (AllowedValue). */
+interface ApiHubAllowedValue {
+    id?: string;
+    displayName?: string;
+    description?: string;
+    immutable?: boolean;
+}
+/**
+ * The value(s) assigned to a single attribute on an API resource
+ * (Cloud API Hub AttributeValues). Exactly one of the *Values fields is set,
+ * depending on the attribute's data type.
+ */
+interface ApiHubAttributeValues {
+    /** Attribute resource name these values belong to (output-only). */
+    attribute?: string;
+    enumValues?: {
+        values?: ApiHubAllowedValue[];
+    };
+    stringValues?: {
+        values?: string[];
+    };
+    jsonValues?: {
+        values?: string[];
+    };
+}
+/**
+ * Represents a single API definition from Cloud API Hub.
+ * GET /projects/{p}/locations/{l}/apis
+ */
+interface ApiHubApi {
+    /** Full resource name: projects/{p}/locations/{l}/apis/{id} */
+    name: string;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Description from API Hub */
+    description?: string;
+    /**
+     * System-defined "Business unit" attribute. In Cloud API Hub this is a
+     * TOP-LEVEL field on the Api resource (an AttributeValues object), NOT an
+     * entry inside `attributes`. Feeds the entity `department` label (see
+     * departmentLabel in entity-builder).
+     */
+    businessUnit?: ApiHubAttributeValues;
+    /**
+     * User-defined attributes keyed by attribute resource name. System-defined
+     * attributes (business unit, team, …) are top-level fields, not entries here;
+     * scanned only as a fallback for a user-modelled business unit.
+     */
+    attributes?: Record<string, ApiHubAttributeValues>;
+    /** Owner team name (maps to spec.owner in Backstage) */
+    owner?: {
+        displayName?: string;
+        email?: string;
+    };
+    /**
+     * GitHub / source repo URI from API Hub metadata.
+     * Maps to metadata.links in Backstage (FR17 / META-10).
+     */
+    sourceMetadata?: Array<{
+        sourceType?: string;
+        value?: string;
+    }>;
+    /**
+     * Externally hosted documentation URI — the API Hub "Documentation" field.
+     * NOS records the proxy's GitHub repository URL here, so it is the
+     * authoritative source for the entity's "Source repository" link (META-10).
+     */
+    documentation?: {
+        externalUri?: string;
+    };
+    /** Array of category/tag IDs applied to this API in API Hub (META-09) */
+    categories?: string[];
+    /** API Hub catalog type (e.g. "openapi", "mcp") — maps to spec.type in Backstage */
+    apiType?: string;
+    /** ISO 8601 create/update timestamps */
+    createTime?: string;
+    updateTime?: string;
+}
+/**
+ * Represents one version of an API Hub API.
+ * GET /projects/{p}/locations/{l}/apis/{apiId}/versions
+ */
+interface ApiHubVersion {
+    /** Full resource name: .../apis/{id}/versions/{vid} */
+    name: string;
+    displayName?: string;
+    description?: string;
+    /** Version state: DRAFT | ACTIVE | DEPRECATED | ARCHIVED */
+    lifecycle?: {
+        stage?: string;
+    };
+    /** Spec IDs attached to this version */
+    specIds?: string[];
+    createTime?: string;
+    updateTime?: string;
+}
+/**
+ * Represents a spec (OpenAPI document) attached to a version.
+ * GET /projects/{p}/locations/{l}/apis/{apiId}/versions/{versionId}/specs/{specId}
+ */
+interface ApiHubSpec {
+    /** Full resource name */
+    name: string;
+    /** MIME type (e.g. "application/json", "application/yaml") */
+    mimeType?: string;
+    /** File name (e.g. "openapi.yaml") */
+    filename?: string;
+    /** Hash of spec contents for deduplication */
+    hash?: string;
+    /** Size in bytes — used by spec size guard in Phase 3 */
+    sizeBytes?: number;
+    createTime?: string;
+    updateTime?: string;
+}
+/**
+ * Raw spec contents response from the :contents sub-resource.
+ * `contents` is base64-encoded (Cloud API Hub ApiSpecContents resource).
+ */
+interface ApiHubSpecContents {
+    mimeType?: string;
+    /** Base64-encoded spec file content */
+    contents?: string;
+}
+/**
+ * Read-only HTTP client for the Cloud API Hub REST v1 API.
+ *
+ * Mirrors ApigeeClient exactly (D-04): same constructor pattern, same
+ * fetchWithRetry delegation, same encodeURIComponent usage.
+ *
+ * Auth: uses the same GCP Application Default Credentials GoogleAuth instance
+ * that is shared with ApigeeClient (D-03).
+ *
+ * Usage:
+ * ```typescript
+ * const auth = new GoogleAuth({ scopes: ['https://www.googleapis.com/auth/cloud-platform'] });
+ * const client = new ApiHubClient(auth, 'my-gcp-project');
+ * const apis = await client.listApis();
+ * ```
+ */
+declare class ApiHubClient {
+    private readonly auth;
+    private readonly projectId;
+    private readonly location;
+    /**
+     * @param auth - Shared GoogleAuth instance (D-03: injected by module.ts, not created here)
+     * @param projectId - GCP project that hosts the API Hub instance
+     * @param location - API Hub location (default: "global" — override if regional instance)
+     */
+    constructor(auth: GoogleAuth, projectId?: string, location?: string);
+    /** Base path prefix shared by all API Hub resource URLs for this instance. */
+    private resourcePrefix;
+    /**
+     * Fetches every page of a paginated API Hub list endpoint, following
+     * `nextPageToken` until the collection is exhausted, and returns the
+     * concatenated items. API Hub caps list responses (commonly at 50 entries per
+     * page), so callers MUST page or risk silently truncating the catalogue.
+     */
+    private fetchAllPages;
+    /**
+     * Lists all API definitions in this API Hub instance.
+     * Calls: GET /projects/{p}/locations/{l}/apis
+     *
+     * @param projectId - Optional override for the GCP project ID. When provided,
+     *   overrides the instance-level projectId from the constructor. Allows a single
+     *   ApiHubClient instance to serve multiple GCP projects (multi-org setups).
+     *
+     * Pages through all results, following nextPageToken until exhausted (API Hub
+     * caps list responses, commonly at 50 entries per page).
+     */
+    listApis(projectId?: string): Promise<ApiHubApi[]>;
+    /**
+     * Lists all versions for a given API.
+     * Calls: GET /projects/{p}/locations/{l}/apis/{apiId}/versions
+     *
+     * @param apiId - Short API ID (last segment of the full resource name)
+     * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.
+     */
+    listVersions(apiId: string, projectId?: string): Promise<ApiHubVersion[]>;
+    /**
+     * Lists all specs attached to a given API version.
+     * Calls: GET /projects/{p}/locations/{l}/apis/{apiId}/versions/{versionId}/specs
+     *
+     * This is the authoritative source of spec IDs for a version. The versions
+     * list endpoint frequently returns version.specIds: null even when specs
+     * exist, so callers must enumerate specs here rather than trusting specIds.
+     *
+     * @param apiId - Short API ID (last segment of the full resource name)
+     * @param versionId - Short version ID (last segment of the version resource name)
+     * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.
+     */
+    listSpecs(apiId: string, versionId: string, projectId?: string): Promise<ApiHubSpec[]>;
+    /**
+     * Fetches the spec metadata for a given API version and spec ID.
+     * Calls: GET /projects/{p}/locations/{l}/apis/{apiId}/versions/{versionId}/specs/{specId}
+     *
+     * To retrieve the actual spec file content (base64), call getSpecContents() instead.
+     *
+     * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.
+     */
+    getSpec(apiId: string, versionId: string, specId: string, projectId?: string): Promise<ApiHubSpec>;
+    /**
+     * Fetches the raw spec file content for a given spec resource.
+     * Calls: GET .../specs/{specId}:contents
+     * Returns base64-encoded content in the `contents` field — caller must decode
+     * with Buffer.from(contents, 'base64').toString('utf-8').
+     *
+     * Used in Phase 3 for spec.definition population (with 500 KB size guard).
+     *
+     * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.
+     */
+    getSpecContents(apiId: string, versionId: string, specId: string, projectId?: string): Promise<ApiHubSpecContents>;
+}
+
+/**
+ * Minimal representation of an Apigee sharedflow as returned by
+ * GET /v1/organizations/{org}/sharedflows
+ */
+interface ApigeeSharedflow {
+    name: string;
+    latestRevisionId?: string;
+    metaData?: {
+        createdAt?: string;
+        lastModifiedAt?: string;
+    };
+}
+/**
+ * Client for the Apigee Management API's sharedflow endpoints.
+ */
+declare class SharedflowClient {
+    private readonly auth;
+    constructor(auth: GoogleAuth);
+    /**
+     * Lists all sharedflows in the given Apigee organisation.
+     */
+    listSharedflows(org: string): Promise<ApigeeSharedflow[]>;
+}
+
+/**
+ * Per-organisation data gathered during a sync run.
+ * Populated by ApigeeEntityProvider.run() before calling proxyToEntities().
+ */
+/** One environment this proxy is deployed to, with the revision deployed there. */
+interface EnvDeployment {
+    /** Environment name (e.g. "dev-1") */
+    name: string;
+    /** Deployed API proxy revision in this environment (e.g. "1") */
+    revision: string;
+}
+interface OrgSyncData {
+    /** Slugified org identifier (used as annotation key segment) */
+    slug: string;
+    /** Raw org name from config (e.g. "my-apigee-org") */
+    name: string;
+    /** GCP project ID owning this Apigee organisation */
+    projectId: string;
+    /** Environments this proxy is deployed to in this org, each with its revision */
+    environments: EnvDeployment[];
+    /** Resolved Backstage lifecycle for this org: production | experimental | deprecated */
+    lifecycle: string;
+}
+/**
+ * A proxy that has been deduplicated across organisations (D-03).
+ * Multiple orgs may share the same proxy name — they are merged into one entity.
+ */
+interface MergedProxy {
+    /** Proxy data from the first org that declared this proxy */
+    proxy: ApigeeProxy;
+    /** Union of all base paths declared across all org revisions */
+    basePaths: string[];
+    /** All orgs that contain this proxy */
+    orgs: OrgSyncData[];
+}
+/** Options forwarded from plugin configuration. */
+interface EntityBuildOptions {
+    /** Default spec.owner when not provided by API Hub. Must be a Backstage entity ref. */
+    defaultOwner?: string;
+    /** Inline spec size limit in bytes; default 512000 applied by the provider (D-03). */
+    specMaxBytes?: number;
+    /**
+     * Optional map of Apigee environment name → Backstage lifecycle
+     * (production | experimental | deprecated). When set, a proxy's lifecycle is
+     * derived from the environments it is deployed to (highest-ranked wins).
+     */
+    environmentLifecycle?: Record<string, string>;
+}
+
+/** Org configuration shape (matches config.d.ts apigee.orgs[n]) */
+interface OrgConfig {
+    name: string;
+    projectId: string;
+    environments?: string[];
+    githubOrgSlug?: string;
+    /** proxyName → API Hub apiId override (D-01); set by module.ts from config. */
+    apiHubMappings?: Record<string, string>;
+}
+/**
+ * Entity provider that discovers Apigee API proxies and sharedflows across
+ * one or more organisations and registers them as Backstage entities.
+ *
+ * Registered with the catalog via `catalogProcessingExtensionPoint.addEntityProvider`.
+ * Scheduled via the `SchedulerServiceTaskRunner` injected at construction time.
+ */
+declare class ApigeeEntityProvider implements EntityProvider {
+    private readonly taskRunner;
+    private readonly logger;
+    private readonly orgsConfig;
+    private readonly apigeeClient;
+    private readonly apiHubClient;
+    private readonly sharedflowClient;
+    private readonly options;
+    private connection?;
+    /**
+     * Last successfully-fetched data per org name. Reused when a later sync of
+     * that org fails, so a `type: 'full'` mutation never deletes a transiently
+     * unavailable org's entities (they survive until that org syncs again).
+     */
+    private readonly lastGoodOrgData;
+    /**
+     * Last successfully-resolved spec per `${projectId}::${apiId}`. Reused when a
+     * later live spec resolution throws (e.g. API Hub is down while an org is
+     * served from {@link lastGoodOrgData}), so the entity keeps its embedded spec
+     * instead of blinking to `has-spec: false`. Bounded by an LRU policy
+     * (MAX_SPEC_CACHE_ENTRIES / MAX_SPEC_CACHE_BYTES).
+     */
+    private readonly lastGoodSpecs;
+    /** Running total of bytes retained in {@link lastGoodSpecs} (for LRU eviction). */
+    private specCacheBytes;
+    constructor(taskRunner: SchedulerServiceTaskRunner, logger: LoggerService, orgsConfig: OrgConfig[], apigeeClient: ApigeeClient, apiHubClient: ApiHubClient, sharedflowClient: SharedflowClient, options: EntityBuildOptions);
+    /** Stable provider name — MUST NOT change; it links entities to this provider. */
+    getProviderName(): string;
+    /**
+     * Called once by the catalog on startup. Stores the connection and registers
+     * the recurring sync task with the scheduler.
+     */
+    connect(connection: EntityProviderConnection): Promise<void>;
+    /**
+     * Executes one full catalog sync:
+     *   1. Fetch proxy / sharedflow / API-Hub data for all orgs in parallel.
+     *   2. Reuse each failed org's last-known-good data so a `full` mutation
+     *      never deletes its entities; skip the run entirely if no org succeeds.
+     *   3. Deduplicate proxies shared across multiple orgs (D-03).
+     *   4. Build entities and call applyMutation exactly once.
+     */
+    run(): Promise<void>;
+    /**
+     * Maps `items` through `fn` with at most `limit` invocations in flight at
+     * once, preserving input order in the returned array. Used to parallelise
+     * per-API spec resolution without overwhelming the API Hub backend (WR-03).
+     */
+    private mapWithConcurrency;
+    /**
+     * Fetches a spec's contents subject to the size guard (D-03).
+     *
+     * Two-stage guard:
+     *  1. Pre-fetch: if the spec metadata reports `sizeBytes > specMaxBytes`, skip
+     *     the download entirely and return a `specUrl` link. NOTE: the API Hub spec
+     *     metadata endpoint frequently reports `sizeBytes: 0`/undefined, so this
+     *     stage often cannot fire and the contents are downloaded anyway.
+     *  2. Post-decode: enforce `specMaxBytes` against the actual decoded byte
+     *     length — this is the guard that reliably bounds the *embedded* size.
+     *
+     * Because stage 1 is unreliable, `specMaxBytes` bounds the size of the spec
+     * that gets embedded, not necessarily the size downloaded into memory.
+     */
+    private fetchSpecEmbed;
+    /**
+     * Resolves the spec for an API: lists versions, deterministically selects one
+     * (D-02), enumerates that version's specs (the versions endpoint does not
+     * reliably populate specIds), picks the lexicographically smallest spec ID,
+     * then fetches it with the size guard.
+     *
+     * Every successful resolution is cached in {@link lastGoodSpecs}. If a live
+     * resolution throws (e.g. API Hub is down while the owning org is served from
+     * cache), the last-known-good spec is returned so the entity keeps its
+     * embedded spec; with no prior spec, `undefined` is returned. Either way one
+     * bad spec never aborts the whole sync.
+     */
+    private resolveSpecForApi;
+    /** Records a successfully-resolved spec (bounded LRU) and returns it unchanged. */
+    private rememberSpec;
+    /**
+     * Fetches all data for one org: proxies, their deployments + revisions,
+     * API Hub type map, and sharedflows.
+     */
+    private fetchOrgData;
+}
+
+/**
+ * A Backstage {@link CatalogProcessor} that links a backend `Component` to its
+ * proxy `API` entity by emitting the native `providesApi` / `apiProvidedBy`
+ * relation pair, surfacing the standard "Provided APIs" / "Providers" cards
+ * with zero custom UI (STITCH-01).
+ *
+ * Resolution dispatches through a strategy seam: a TargetServer-first path
+ * (deferred — STITCH-02, see 04-CONTEXT D-01) followed by the active
+ * direct-mapping path. The first strategy to return a target ref wins.
+ */
+declare class ApigeeStitchingProcessor implements CatalogProcessor {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    getProcessorName(): string;
+    postProcessEntity(entity: Entity, _location: LocationSpec, emit: CatalogProcessorEmit): Promise<Entity>;
+    /**
+     * Strategy seam. Tries the TargetServer-preferred path first (deferred this
+     * phase), then falls back to the active direct-mapping path. First strategy
+     * to return a ref wins.
+     */
+    private resolveTarget;
+    /**
+     * Deferred: TargetServer-preferred path (STITCH-02). See 04-CONTEXT D-01.
+     * No TargetServer data exists in the codebase yet, so this is the clean
+     * insertion point for the future branch and intentionally returns undefined.
+     */
+    private resolveViaTargetServer;
+    /**
+     * Direct-mapping path. Requires BOTH the api-name and project-id annotations.
+     * The proxy API entity ref is deterministic — `api:default/<slugify(api-name)>` —
+     * so no live catalog lookup is needed (D-01). projectId is validated for
+     * presence to confirm intent but is not part of the deterministic ref.
+     */
+    private resolveViaDirect;
+}
+
+export { ApiHubClient, ApigeeClient, ApigeeEntityProvider, ApigeeStitchingProcessor, SharedflowClient, catalogModuleApigee, apigeePlugin as default };
+export type { ApiHubApi, ApiHubSpec, ApiHubSpecContents, ApiHubVersion, ApigeeDeployment, ApigeeProxy, ApigeeProxyRevision, ApigeeSharedflow, EntityBuildOptions, MergedProxy, OrgSyncData };

package/dist/lib/api-hub-client.cjs.js

@@ -0,0 +1,118 @@
+'use strict';
+
+var fetchUtils = require('./fetch-utils.cjs.js');
+
+const APIHUB_BASE_URL = "https://apihub.googleapis.com/v1";
+class ApiHubClient {
+  /**
+   * @param auth - Shared GoogleAuth instance (D-03: injected by module.ts, not created here)
+   * @param projectId - GCP project that hosts the API Hub instance
+   * @param location - API Hub location (default: "global" — override if regional instance)
+   */
+  constructor(auth, projectId = "", location = "global") {
+    this.auth = auth;
+    this.projectId = projectId;
+    this.location = location;
+  }
+  auth;
+  projectId;
+  location;
+  /** Base path prefix shared by all API Hub resource URLs for this instance. */
+  resourcePrefix(projectId) {
+    const proj = projectId ?? this.projectId;
+    return `${APIHUB_BASE_URL}/projects/${encodeURIComponent(proj)}/locations/${encodeURIComponent(this.location)}`;
+  }
+  /**
+   * Fetches every page of a paginated API Hub list endpoint, following
+   * `nextPageToken` until the collection is exhausted, and returns the
+   * concatenated items. API Hub caps list responses (commonly at 50 entries per
+   * page), so callers MUST page or risk silently truncating the catalogue.
+   */
+  async fetchAllPages(baseUrl, collection) {
+    const items = [];
+    let pageToken;
+    do {
+      const sep = baseUrl.includes("?") ? "&" : "?";
+      const url = pageToken ? `${baseUrl}${sep}pageToken=${encodeURIComponent(pageToken)}` : baseUrl;
+      const body = await fetchUtils.fetchWithRetry(
+        url,
+        () => this.auth.getAccessToken()
+      );
+      const page = body[collection] ?? [];
+      items.push(...page);
+      pageToken = typeof body.nextPageToken === "string" && body.nextPageToken.length > 0 ? body.nextPageToken : void 0;
+    } while (pageToken);
+    return items;
+  }
+  /**
+   * Lists all API definitions in this API Hub instance.
+   * Calls: GET /projects/{p}/locations/{l}/apis
+   *
+   * @param projectId - Optional override for the GCP project ID. When provided,
+   *   overrides the instance-level projectId from the constructor. Allows a single
+   *   ApiHubClient instance to serve multiple GCP projects (multi-org setups).
+   *
+   * Pages through all results, following nextPageToken until exhausted (API Hub
+   * caps list responses, commonly at 50 entries per page).
+   */
+  async listApis(projectId) {
+    const url = `${this.resourcePrefix(projectId)}/apis`;
+    return this.fetchAllPages(url, "apis");
+  }
+  /**
+   * Lists all versions for a given API.
+   * Calls: GET /projects/{p}/locations/{l}/apis/{apiId}/versions
+   *
+   * @param apiId - Short API ID (last segment of the full resource name)
+   * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.
+   */
+  async listVersions(apiId, projectId) {
+    const url = `${this.resourcePrefix(projectId)}/apis/${encodeURIComponent(apiId)}/versions`;
+    return this.fetchAllPages(url, "versions");
+  }
+  /**
+   * Lists all specs attached to a given API version.
+   * Calls: GET /projects/{p}/locations/{l}/apis/{apiId}/versions/{versionId}/specs
+   *
+   * This is the authoritative source of spec IDs for a version. The versions
+   * list endpoint frequently returns version.specIds: null even when specs
+   * exist, so callers must enumerate specs here rather than trusting specIds.
+   *
+   * @param apiId - Short API ID (last segment of the full resource name)
+   * @param versionId - Short version ID (last segment of the version resource name)
+   * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.
+   */
+  async listSpecs(apiId, versionId, projectId) {
+    const url = `${this.resourcePrefix(projectId)}/apis/${encodeURIComponent(apiId)}/versions/${encodeURIComponent(versionId)}/specs`;
+    return this.fetchAllPages(url, "specs");
+  }
+  /**
+   * Fetches the spec metadata for a given API version and spec ID.
+   * Calls: GET /projects/{p}/locations/{l}/apis/{apiId}/versions/{versionId}/specs/{specId}
+   *
+   * To retrieve the actual spec file content (base64), call getSpecContents() instead.
+   *
+   * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.
+   */
+  async getSpec(apiId, versionId, specId, projectId) {
+    const url = `${this.resourcePrefix(projectId)}/apis/${encodeURIComponent(apiId)}/versions/${encodeURIComponent(versionId)}/specs/${encodeURIComponent(specId)}`;
+    return await fetchUtils.fetchWithRetry(url, () => this.auth.getAccessToken());
+  }
+  /**
+   * Fetches the raw spec file content for a given spec resource.
+   * Calls: GET .../specs/{specId}:contents
+   * Returns base64-encoded content in the `contents` field — caller must decode
+   * with Buffer.from(contents, 'base64').toString('utf-8').
+   *
+   * Used in Phase 3 for spec.definition population (with 500 KB size guard).
+   *
+   * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.
+   */
+  async getSpecContents(apiId, versionId, specId, projectId) {
+    const url = `${this.resourcePrefix(projectId)}/apis/${encodeURIComponent(apiId)}/versions/${encodeURIComponent(versionId)}/specs/${encodeURIComponent(specId)}:contents`;
+    return await fetchUtils.fetchWithRetry(url, () => this.auth.getAccessToken());
+  }
+}
+
+exports.ApiHubClient = ApiHubClient;
+//# sourceMappingURL=api-hub-client.cjs.js.map

package/dist/lib/api-hub-client.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-hub-client.cjs.js","sources":["../../src/lib/api-hub-client.ts"],"sourcesContent":["// SPDX-License-Identifier: Apache-2.0\r\nimport { GoogleAuth } from 'google-auth-library';\r\nimport { fetchWithRetry } from './fetch-utils';\r\n\r\n// ---------------------------------------------------------------------------\r\n// Minimal response types — only the fields consumed in Phases 1-3.\r\n// Full Cloud API Hub REST v1 reference:\r\n//   https://cloud.google.com/apigee/docs/apihub/reference/rest/v1/projects.locations.apis\r\n// ---------------------------------------------------------------------------\r\n\r\n/** One allowed value of a Cloud API Hub enum attribute (AllowedValue). */\r\nexport interface ApiHubAllowedValue {\r\n  id?: string;\r\n  displayName?: string;\r\n  description?: string;\r\n  immutable?: boolean;\r\n}\r\n\r\n/**\r\n * The value(s) assigned to a single attribute on an API resource\r\n * (Cloud API Hub AttributeValues). Exactly one of the *Values fields is set,\r\n * depending on the attribute's data type.\r\n */\r\nexport interface ApiHubAttributeValues {\r\n  /** Attribute resource name these values belong to (output-only). */\r\n  attribute?: string;\r\n  enumValues?: { values?: ApiHubAllowedValue[] };\r\n  stringValues?: { values?: string[] };\r\n  jsonValues?: { values?: string[] };\r\n}\r\n\r\n/**\r\n * Represents a single API definition from Cloud API Hub.\r\n * GET /projects/{p}/locations/{l}/apis\r\n */\r\nexport interface ApiHubApi {\r\n  /** Full resource name: projects/{p}/locations/{l}/apis/{id} */\r\n  name: string;\r\n  /** Human-readable display name */\r\n  displayName?: string;\r\n  /** Description from API Hub */\r\n  description?: string;\r\n  /**\r\n   * System-defined \"Business unit\" attribute. In Cloud API Hub this is a\r\n   * TOP-LEVEL field on the Api resource (an AttributeValues object), NOT an\r\n   * entry inside `attributes`. Feeds the entity `department` label (see\r\n   * departmentLabel in entity-builder).\r\n   */\r\n  businessUnit?: ApiHubAttributeValues;\r\n  /**\r\n   * User-defined attributes keyed by attribute resource name. System-defined\r\n   * attributes (business unit, team, …) are top-level fields, not entries here;\r\n   * scanned only as a fallback for a user-modelled business unit.\r\n   */\r\n  attributes?: Record<string, ApiHubAttributeValues>;\r\n  /** Owner team name (maps to spec.owner in Backstage) */\r\n  owner?: { displayName?: string; email?: string };\r\n  /**\r\n   * GitHub / source repo URI from API Hub metadata.\r\n   * Maps to metadata.links in Backstage (FR17 / META-10).\r\n   */\r\n  sourceMetadata?: Array<{ sourceType?: string; value?: string }>;\r\n  /**\r\n   * Externally hosted documentation URI — the API Hub \"Documentation\" field.\r\n   * NOS records the proxy's GitHub repository URL here, so it is the\r\n   * authoritative source for the entity's \"Source repository\" link (META-10).\r\n   */\r\n  documentation?: { externalUri?: string };\r\n  /** Array of category/tag IDs applied to this API in API Hub (META-09) */\r\n  categories?: string[];\r\n  /** API Hub catalog type (e.g. \"openapi\", \"mcp\") — maps to spec.type in Backstage */\r\n  apiType?: string;\r\n  /** ISO 8601 create/update timestamps */\r\n  createTime?: string;\r\n  updateTime?: string;\r\n}\r\n\r\n/**\r\n * Represents one version of an API Hub API.\r\n * GET /projects/{p}/locations/{l}/apis/{apiId}/versions\r\n */\r\nexport interface ApiHubVersion {\r\n  /** Full resource name: .../apis/{id}/versions/{vid} */\r\n  name: string;\r\n  displayName?: string;\r\n  description?: string;\r\n  /** Version state: DRAFT | ACTIVE | DEPRECATED | ARCHIVED */\r\n  lifecycle?: { stage?: string };\r\n  /** Spec IDs attached to this version */\r\n  specIds?: string[];\r\n  createTime?: string;\r\n  updateTime?: string;\r\n}\r\n\r\n/**\r\n * Represents a spec (OpenAPI document) attached to a version.\r\n * GET /projects/{p}/locations/{l}/apis/{apiId}/versions/{versionId}/specs/{specId}\r\n */\r\nexport interface ApiHubSpec {\r\n  /** Full resource name */\r\n  name: string;\r\n  /** MIME type (e.g. \"application/json\", \"application/yaml\") */\r\n  mimeType?: string;\r\n  /** File name (e.g. \"openapi.yaml\") */\r\n  filename?: string;\r\n  /** Hash of spec contents for deduplication */\r\n  hash?: string;\r\n  /** Size in bytes — used by spec size guard in Phase 3 */\r\n  sizeBytes?: number;\r\n  createTime?: string;\r\n  updateTime?: string;\r\n}\r\n\r\n/**\r\n * Raw spec contents response from the :contents sub-resource.\r\n * `contents` is base64-encoded (Cloud API Hub ApiSpecContents resource).\r\n */\r\nexport interface ApiHubSpecContents {\r\n  mimeType?: string;\r\n  /** Base64-encoded spec file content */\r\n  contents?: string;\r\n}\r\n\r\n// ---------------------------------------------------------------------------\r\n// Client\r\n// ---------------------------------------------------------------------------\r\n\r\nconst APIHUB_BASE_URL = 'https://apihub.googleapis.com/v1';\r\n\r\n/**\r\n * Read-only HTTP client for the Cloud API Hub REST v1 API.\r\n *\r\n * Mirrors ApigeeClient exactly (D-04): same constructor pattern, same\r\n * fetchWithRetry delegation, same encodeURIComponent usage.\r\n *\r\n * Auth: uses the same GCP Application Default Credentials GoogleAuth instance\r\n * that is shared with ApigeeClient (D-03).\r\n *\r\n * Usage:\r\n * ```typescript\r\n * const auth = new GoogleAuth({ scopes: ['https://www.googleapis.com/auth/cloud-platform'] });\r\n * const client = new ApiHubClient(auth, 'my-gcp-project');\r\n * const apis = await client.listApis();\r\n * ```\r\n */\r\nexport class ApiHubClient {\r\n  /**\r\n   * @param auth - Shared GoogleAuth instance (D-03: injected by module.ts, not created here)\r\n   * @param projectId - GCP project that hosts the API Hub instance\r\n   * @param location - API Hub location (default: \"global\" — override if regional instance)\r\n   */\r\n  constructor(\r\n    private readonly auth: GoogleAuth,\r\n    private readonly projectId: string = '',\r\n    private readonly location: string = 'global',\r\n  ) {}\r\n\r\n  /** Base path prefix shared by all API Hub resource URLs for this instance. */\r\n  private resourcePrefix(projectId?: string): string {\r\n    const proj = projectId ?? this.projectId;\r\n    return (\r\n      `${APIHUB_BASE_URL}/projects/${encodeURIComponent(proj)}` +\r\n      `/locations/${encodeURIComponent(this.location)}`\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Fetches every page of a paginated API Hub list endpoint, following\r\n   * `nextPageToken` until the collection is exhausted, and returns the\r\n   * concatenated items. API Hub caps list responses (commonly at 50 entries per\r\n   * page), so callers MUST page or risk silently truncating the catalogue.\r\n   */\r\n  private async fetchAllPages<T>(\r\n    baseUrl: string,\r\n    collection: 'apis' | 'versions' | 'specs',\r\n  ): Promise<T[]> {\r\n    const items: T[] = [];\r\n    let pageToken: string | undefined;\r\n    do {\r\n      const sep = baseUrl.includes('?') ? '&' : '?';\r\n      const url = pageToken\r\n        ? `${baseUrl}${sep}pageToken=${encodeURIComponent(pageToken)}`\r\n        : baseUrl;\r\n      const body = (await fetchWithRetry(url, () =>\r\n        this.auth.getAccessToken(),\r\n      )) as Record<string, unknown>;\r\n      const page = (body[collection] as T[] | undefined) ?? [];\r\n      items.push(...page);\r\n      pageToken =\r\n        typeof body.nextPageToken === 'string' && body.nextPageToken.length > 0\r\n          ? body.nextPageToken\r\n          : undefined;\r\n    } while (pageToken);\r\n    return items;\r\n  }\r\n\r\n  /**\r\n   * Lists all API definitions in this API Hub instance.\r\n   * Calls: GET /projects/{p}/locations/{l}/apis\r\n   *\r\n   * @param projectId - Optional override for the GCP project ID. When provided,\r\n   *   overrides the instance-level projectId from the constructor. Allows a single\r\n   *   ApiHubClient instance to serve multiple GCP projects (multi-org setups).\r\n   *\r\n   * Pages through all results, following nextPageToken until exhausted (API Hub\r\n   * caps list responses, commonly at 50 entries per page).\r\n   */\r\n  async listApis(projectId?: string): Promise<ApiHubApi[]> {\r\n    const url = `${this.resourcePrefix(projectId)}/apis`;\r\n    return this.fetchAllPages<ApiHubApi>(url, 'apis');\r\n  }\r\n\r\n  /**\r\n   * Lists all versions for a given API.\r\n   * Calls: GET /projects/{p}/locations/{l}/apis/{apiId}/versions\r\n   *\r\n   * @param apiId - Short API ID (last segment of the full resource name)\r\n   * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.\r\n   */\r\n  async listVersions(apiId: string, projectId?: string): Promise<ApiHubVersion[]> {\r\n    const url = `${this.resourcePrefix(projectId)}/apis/${encodeURIComponent(apiId)}/versions`;\r\n    return this.fetchAllPages<ApiHubVersion>(url, 'versions');\r\n  }\r\n\r\n  /**\r\n   * Lists all specs attached to a given API version.\r\n   * Calls: GET /projects/{p}/locations/{l}/apis/{apiId}/versions/{versionId}/specs\r\n   *\r\n   * This is the authoritative source of spec IDs for a version. The versions\r\n   * list endpoint frequently returns version.specIds: null even when specs\r\n   * exist, so callers must enumerate specs here rather than trusting specIds.\r\n   *\r\n   * @param apiId - Short API ID (last segment of the full resource name)\r\n   * @param versionId - Short version ID (last segment of the version resource name)\r\n   * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.\r\n   */\r\n  async listSpecs(\r\n    apiId: string,\r\n    versionId: string,\r\n    projectId?: string,\r\n  ): Promise<ApiHubSpec[]> {\r\n    const url =\r\n      `${this.resourcePrefix(projectId)}/apis/${encodeURIComponent(apiId)}` +\r\n      `/versions/${encodeURIComponent(versionId)}/specs`;\r\n    return this.fetchAllPages<ApiHubSpec>(url, 'specs');\r\n  }\r\n\r\n  /**\r\n   * Fetches the spec metadata for a given API version and spec ID.\r\n   * Calls: GET /projects/{p}/locations/{l}/apis/{apiId}/versions/{versionId}/specs/{specId}\r\n   *\r\n   * To retrieve the actual spec file content (base64), call getSpecContents() instead.\r\n   *\r\n   * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.\r\n   */\r\n  async getSpec(\r\n    apiId: string,\r\n    versionId: string,\r\n    specId: string,\r\n    projectId?: string,\r\n  ): Promise<ApiHubSpec> {\r\n    const url =\r\n      `${this.resourcePrefix(projectId)}/apis/${encodeURIComponent(apiId)}` +\r\n      `/versions/${encodeURIComponent(versionId)}` +\r\n      `/specs/${encodeURIComponent(specId)}`;\r\n    return (await fetchWithRetry(url, () => this.auth.getAccessToken())) as ApiHubSpec;\r\n  }\r\n\r\n  /**\r\n   * Fetches the raw spec file content for a given spec resource.\r\n   * Calls: GET .../specs/{specId}:contents\r\n   * Returns base64-encoded content in the `contents` field — caller must decode\r\n   * with Buffer.from(contents, 'base64').toString('utf-8').\r\n   *\r\n   * Used in Phase 3 for spec.definition population (with 500 KB size guard).\r\n   *\r\n   * @param projectId - Optional GCP project override for multi-org setups; defaults to the instance projectId.\r\n   */\r\n  async getSpecContents(\r\n    apiId: string,\r\n    versionId: string,\r\n    specId: string,\r\n    projectId?: string,\r\n  ): Promise<ApiHubSpecContents> {\r\n    const url =\r\n      `${this.resourcePrefix(projectId)}/apis/${encodeURIComponent(apiId)}` +\r\n      `/versions/${encodeURIComponent(versionId)}` +\r\n      `/specs/${encodeURIComponent(specId)}:contents`;\r\n    return (await fetchWithRetry(url, () => this.auth.getAccessToken())) as ApiHubSpecContents;\r\n  }\r\n}\r\n"],"names":["fetchWithRetry"],"mappings":"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"}