@nospt/backstage-plugin-apigee-backend 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @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 `other`) |
+| 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.

package/config.d.ts

@@ -0,0 +1,75 @@
+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;
+    /**
+     * 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":";;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,431 @@
+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 revision number */
+    apiRevision?: string;
+    /** Deployment state: READY | PROGRESSING | ERROR */
+    deploymentStatus?: 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>;
+}
+
+/**
+ * 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;
+    /** API Hub lifecycle state: DRAFT | ACTIVE | DEPRECATED | ARCHIVED */
+    businessUnit?: string;
+    /** 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;
+    }>;
+    /** 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().
+ */
+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;
+    /** Names of environments this proxy is deployed to in this org */
+    environments: string[];
+    /** 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;
+}
+
+/** 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?;
+    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. Warn and skip any org that fails (error isolation per org).
+     *   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. Per-spec failures are isolated: any
+     * error is logged and `undefined` is returned so one bad spec never aborts
+     * the whole sync.
+     */
+    private resolveSpecForApi;
+    /**
+     * 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 };