@objectstack/connector-openapi 15.0.0 → 15.1.1

package/src/openapi-provider.ts

@@ -0,0 +1,135 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  ConnectorProviderContext,
+  ConnectorProviderFactory,
+  ResolvedConnectorAuth,
+} from '@objectstack/spec/integration';
+import {
+  createOpenApiConnector,
+  type OpenApiDocument,
+  type RestAuth,
+} from './openapi-connector.js';
+
+/**
+ * The provider key this package contributes (ADR-0097). A declarative
+ * `connectors:` entry with `provider: 'openapi'` is materialized by this factory.
+ */
+export const OPENAPI_PROVIDER_KEY = 'openapi';
+
+/** Injectable dependencies for {@link createOpenApiProviderFactory} (tests). */
+export interface OpenApiProviderDeps {
+  /** Injected fetch implementation (spec fetch + request transport); defaults to global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+/** Shape of `providerConfig` for a `provider: 'openapi'` declarative instance. */
+interface OpenApiProviderConfig {
+  /**
+   * The OpenAPI 3.x document: an inline object, an http(s) URL to fetch at
+   * boot, or a file path resolved relative to the declaring stack/package root
+   * (`'./billing-openapi.json'`, #3016).
+   */
+  spec?: unknown;
+  /** Override the base URL (else the document's `servers[0].url`). */
+  baseUrl?: unknown;
+}
+
+/**
+ * Resolve `providerConfig.spec` into a parsed OpenAPI document (ADR-0097;
+ * union per #3016): an inline document object (the reliable, no-I/O-at-boot
+ * form used by the showcase), an http(s) URL fetched at materialization, or a
+ * **file path** read through the host's `ctx.loadPackageFile` — which resolves
+ * it relative to the declaring stack/package root and confines the read to
+ * that root (absolute / `..`-escaping paths are rejected there). Every failure
+ * throws, so the materializer's reconcile policy applies: fatal at boot, the
+ * entry is skipped on reload.
+ */
+async function loadOpenApiDocument(
+  spec: unknown,
+  fetchImpl: typeof fetch | undefined,
+  ctx: ConnectorProviderContext,
+): Promise<OpenApiDocument> {
+  const connectorName = ctx.name;
+  if (spec && typeof spec === 'object' && !Array.isArray(spec)) {
+    return spec as OpenApiDocument;
+  }
+  if (typeof spec === 'string' && spec.length > 0) {
+    if (/^https?:\/\//i.test(spec)) {
+      const doFetch = fetchImpl ?? fetch;
+      const res = await doFetch(spec);
+      if (!res.ok) {
+        throw new Error(
+          `connector-openapi provider: connector '${connectorName}' failed to fetch spec '${spec}' (HTTP ${res.status}).`,
+        );
+      }
+      return (await res.json()) as OpenApiDocument;
+    }
+    // File path — dereferenced through the host capability so resolution stays
+    // anchored to (and confined within) the declaring stack/package root.
+    if (!ctx.loadPackageFile) {
+      throw new Error(
+        `connector-openapi provider: connector '${connectorName}' providerConfig.spec '${spec}' is a file path, ` +
+          `but this host provides no package file access — inline the OpenAPI document or use an http(s) URL.`,
+      );
+    }
+    let text: string;
+    try {
+      text = await ctx.loadPackageFile(spec);
+    } catch (err) {
+      throw new Error(
+        `connector-openapi provider: connector '${connectorName}' failed to read providerConfig.spec '${spec}': ` +
+          `${(err as Error).message}`,
+      );
+    }
+    try {
+      const parsed: unknown = JSON.parse(text);
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('not a JSON object');
+      }
+      return parsed as OpenApiDocument;
+    } catch (err) {
+      throw new Error(
+        `connector-openapi provider: connector '${connectorName}' providerConfig.spec '${spec}' is not a parseable ` +
+          `OpenAPI JSON document: ${(err as Error).message}`,
+      );
+    }
+  }
+  throw new Error(
+    `connector-openapi provider: connector '${connectorName}' requires providerConfig.spec — an inline OpenAPI 3.x ` +
+      `document object, an http(s) URL, or a package-relative file path.`,
+  );
+}
+
+/**
+ * Build the `openapi` {@link ConnectorProviderFactory} (ADR-0097 / ADR-0023). At
+ * boot the automation service invokes it for each `provider: 'openapi'`
+ * declarative instance: it loads the OpenAPI document from `providerConfig.spec`,
+ * then produces the same `{ def, handlers }` bundle {@link createOpenApiConnector}
+ * generates for a hand-wired OpenAPI connector — one action per operation over a
+ * static-auth HTTP transport, with the resolved `auth` applied.
+ *
+ * Hard-fails on invalid config (missing/unfetchable spec, no base URL), so a
+ * misconfigured instance fails boot loudly.
+ */
+export function createOpenApiProviderFactory(deps: OpenApiProviderDeps = {}): ConnectorProviderFactory {
+  return async (ctx) => {
+    const cfg = (ctx.providerConfig ?? {}) as OpenApiProviderConfig;
+    if (cfg.baseUrl !== undefined && typeof cfg.baseUrl !== 'string') {
+      throw new Error(
+        `connector-openapi provider: connector '${ctx.name}' providerConfig.baseUrl must be a string when set.`,
+      );
+    }
+    const document = await loadOpenApiDocument(cfg.spec, deps.fetchImpl, ctx);
+    const auth = ctx.auth as ResolvedConnectorAuth | undefined as RestAuth | undefined;
+    return createOpenApiConnector({
+      name: ctx.name,
+      label: ctx.label,
+      description: ctx.description,
+      document,
+      baseUrl: typeof cfg.baseUrl === 'string' ? cfg.baseUrl : undefined,
+      auth,
+      fetchImpl: deps.fetchImpl,
+    });
+  };
+}