feat(connector-openapi): OpenAPI 3.x → Connector generator (ADR-0023) (#1425)

* feat(connector-openapi): OpenAPI 3.x → Connector generator (ADR-0023)

Add @objectstack/connector-openapi, mirroring connector-rest / connector-mcp:

- createOpenApiConnector turns an OpenAPI 3.x document into a Connector
  definition + handler map (one operation -> one action). It reuses
  @objectstack/connector-rest's request handler for the HTTP/auth transport
  (one shared implementation, per ADR-0022) and returns the same
  { definition, handlers } shape consumed by engine.registerConnector — no new
  engine surface.
- Input schemas assembled as { path, query, header, body } from parameters +
  requestBody; output schema from the 200/2xx/default JSON response; action
  names from operationId with a deterministic slug fallback and de-duping.
- Auth inferred from components.securitySchemes when no credentials are
  supplied; supplied RestAuth is reflected in the definition metadata.
- include allowlist for trimming large specs.
- registerOpenApiConnector plugin mirroring registerRestConnector /
  registerMcpConnector.
- 12 unit tests (metadata, name/slug fallback, schema assembly, output schema,
  auth inference, allowlist, handler path/query/body dispatch, missing-base-URL
  error, engine registration).

Updates ADR-0023 status to mark the generator package implemented; the CLI and
worked example remain noted follow-ups.

* fix(connector-openapi): self-contained transport; merge main; changeset

Make @objectstack/connector-openapi self-contained and correct against the
real connector/spec APIs (fixes the initial scaffold):

- Drop the @objectstack/connector-rest dependency; inline the static-auth HTTP
  transport (build URL, apply auth, JSON-encode body, normalise to
  { status, ok, body }) mirroring connector-rest, so the package depends only
  on @objectstack/core + @objectstack/spec like every sibling connector.
- Use the real ConnectorAction `key` field, the `{ type }` auth discriminator,
  import Connector from @objectstack/spec/integration, and return { def,
  handlers } — matching the registry contract used by connector-rest/mcp.
- Fix tsconfig (rootDir/outDir/types) so dts builds.

Resolves the "Validate Package Dependencies" failure: add
@objectstack/connector-openapi to the changesets `fixed` group, add a changeset
entry, and refresh pnpm-lock.yaml. Update ADR-0023 to describe the
self-contained transport. Merge latest main.

Verified locally: turbo build (esm+cjs+dts), 10/10 vitest tests, eslint,
check-changeset-fixed.mjs, and pnpm install --frozen-lockfile all pass.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/config.json

@@ -1,6 +1,11 @@
 {
   "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
-  "changelog": ["@changesets/cli/changelog", { "repo": "objectstack-ai/spec" }],
+  "changelog": [
+    "@changesets/cli/changelog",
+    {
+      "repo": "objectstack-ai/spec"
+    }
+  ],
   "commit": false,
   "fixed": [
     [
@@ -71,7 +76,8 @@
       "@objectstack/embedder-openai",
       "@objectstack/account",
       "create-objectstack",
-      "objectstack-vscode"
+      "objectstack-vscode",
+      "@objectstack/connector-openapi"
     ]
   ],
   "linked": [],

.changeset/openapi-to-connector.md

@@ -0,0 +1,5 @@
+---
+"@objectstack/connector-openapi": minor
+---
+
+Add `@objectstack/connector-openapi` — generate an ObjectStack connector from a declarative OpenAPI 3.x document (ADR-0023). One operation becomes one connector action; a single generic handler drives a self-contained static-auth HTTP transport (mirroring `@objectstack/connector-rest`). The generated `type: 'api'` connector registers via `engine.registerConnector(def, handlers)` with no new engine surface, and supports an `include` allowlist for trimming large specs.

docs/adr/0023-openapi-to-connector-generator.md

@@ -141,8 +141,8 @@ A spec that declares OAuth2 is still importable open-source — we generate the
 
 ## Status & follow-ups
 
-- **This ADR changes no shipped code.** It records the decision to add a generator package on top of the existing connector baseline.
-- Follow-up: scaffold `packages/connectors/connector-openapi` mirroring `connector-rest`, with `createOpenApiConnector` + `ConnectorOpenApiPlugin`.
-- Follow-up: a small `openapi-to-connector` CLI that emits a reviewable `*.connector.json`.
+- ✅ **Implemented:** `packages/connectors/connector-openapi` mirrors `connector-rest` / `connector-mcp`, exporting `createOpenApiConnector` (one operation → one action) + `registerOpenApiConnector`. Each generated action drives one shared static-auth HTTP transport that mirrors `connector-rest` (build URL from base+path+query, apply static auth, JSON-encode the body, normalise the response to `{ status, ok, body }`) — kept inline so the package stays self-contained (depends only on `@objectstack/core` + `@objectstack/spec`, like its sibling connectors), and returns the `{ def, handlers }` shape consumed by `engine.registerConnector`. Input schemas are assembled as `{ path, query, header, body }` from `parameters` + `requestBody`; output schemas from the `200`/`2xx`/`default` JSON response; static auth (`none`/`api-key`/`basic`/`bearer`) is supplied by the caller. Includes an `include` allowlist for trimming large specs.
+- Follow-up: a small `openapi-to-connector` CLI that emits a reviewable `*.connector.json` (deferred — needs a multi-entry build, whereas every connector package currently uses the shared single-entry `tsup` config).
 - Follow-up: a worked example (e.g. GitHub or Stripe public OpenAPI → a handful of allowlisted actions) under `examples/`, paralleling the worked `connector_action` example from ADR-0022.
+- Follow-up: YAML spec input and a `$ref` deref pass for specs the caller has not pre-dereferenced.
 - Cross-reference: see [ADR-0024](./0024-mcp-connectors.md) for the complementary path — wrapping live **MCP servers** as connectors when no OpenAPI spec exists but an MCP server does.

packages/connectors/connector-openapi/LICENSE

@@ -0,0 +1,93 @@
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             ObjectStack AI LLC
+Licensed Work:        ObjectStack Runtime: the BSL-licensed packages
+                      of the ObjectStack monorepo as listed in LICENSING.md.
+                      Copyright (c) 2026 ObjectStack AI LLC.
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      Your use does not include offering the Licensed Work to third
+                      parties on a hosted or embedded basis in order to compete with 
+                      ObjectStack AI LLC's paid version(s) of the Licensed Work. For purposes 
+                      of this license:
+
+                      A "competitive offering" is a Product that is offered to third
+                      parties on a paid basis, including through paid support 
+                      arrangements, that significantly overlaps with the capabilities 
+                      of ObjectStack AI LLC's paid version(s) of the Licensed Work. If Your 
+                      Product is not a competitive offering when You first make it 
+                      generally available, it will not become a competitive offering
+                      later due to ObjectStack AI LLC releasing a new version of the Licensed 
+                      Work with additional capabilities. In addition, Products that 
+                      are not provided on a paid basis are not competitive.
+
+                      "Product" means software that is offered to end users to manage 
+                      in their own environments or offered as a service on a hosted 
+                      basis.
+
+                      "Embedded" means including the source code or executable code 
+                      from the Licensed Work in a competitive offering. "Embedded" 
+                      also means packaging the competitive offering in such a way 
+                      that the Licensed Work must be accessed or downloaded for the 
+                      competitive offering to operate.
+
+                      Hosting or using the Licensed Work(s) for internal purposes 
+                      within an organization is not considered a competitive 
+                      offering. ObjectStack AI LLC considers your organization to include all 
+                      of your affiliates under common control.
+
+                      For binding interpretive guidance on using ObjectStack AI LLC products 
+                      under the Business Source License, please visit our FAQ. 
+                      (see LICENSING.md in this repository)
+Change Date:          Four years from the date the Licensed Work is published.
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact licensing@objectstack.dev.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

packages/connectors/connector-openapi/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@objectstack/connector-openapi",
+    "version": "7.3.0",
+    "license": "Apache-2.0",
+    "description": "OpenAPI 3.x connector generator for ObjectStack — turns a declarative OpenAPI document into connector actions on the automation engine's registry, with a self-contained static-auth HTTP transport (ADR-0023).",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsup --config ../../../tsup.config.ts",
+        "test": "vitest run --passWithNoTests"
+    },
+    "dependencies": {
+        "@objectstack/core": "workspace:*",
+        "@objectstack/spec": "workspace:*"
+    },
+    "devDependencies": {
+        "@objectstack/service-automation": "workspace:*",
+        "@types/node": "^25.9.1",
+        "typescript": "^6.0.3",
+        "vitest": "^4.1.7"
+    },
+    "keywords": [
+        "objectstack",
+        "connector",
+        "openapi",
+        "swagger",
+        "integration",
+        "api"
+    ]
+}

packages/connectors/connector-openapi/src/connector-openapi-plugin.test.ts

@@ -0,0 +1,28 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import { registerOpenApiConnector, type ConnectorRegistrySurface } from './connector-openapi-plugin.js';
+import type { OpenApiDocument } from './openapi-connector.js';
+
+const doc: OpenApiDocument = {
+    info: { title: 'Mini' },
+    servers: [{ url: 'https://api.mini.example.com' }],
+    paths: {
+        '/ping': { get: { operationId: 'ping', responses: { '200': { description: 'ok' } } } },
+    },
+};
+
+describe('registerOpenApiConnector', () => {
+    it('registers the generated definition + handlers on the registry', () => {
+        const registerConnector = vi.fn();
+        const registry = { registerConnector, unregisterConnector: vi.fn() } as unknown as ConnectorRegistrySurface;
+
+        const name = registerOpenApiConnector(registry, { document: doc });
+
+        expect(name).toBe('mini');
+        expect(registerConnector).toHaveBeenCalledTimes(1);
+        const [def, handlers] = registerConnector.mock.calls[0];
+        expect(def.name).toBe('mini');
+        expect(typeof handlers.ping).toBe('function');
+    });
+});

packages/connectors/connector-openapi/src/connector-openapi-plugin.ts

@@ -0,0 +1,32 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Connector } from '@objectstack/spec/integration';
+import { createOpenApiConnector, type OpenApiConnectorConfig } from './openapi-connector.js';
+
+/**
+ * Minimal surface of the automation engine this helper depends on — the
+ * connector registry from ADR-0018 §Addendum. Kept structural so callers need
+ * no runtime dependency on `@objectstack/service-automation` (mirrors
+ * connector-rest / connector-mcp).
+ */
+export interface ConnectorRegistrySurface {
+    registerConnector(
+        def: Connector,
+        handlers: Record<
+            string,
+            (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>
+        >,
+    ): void;
+    unregisterConnector(name: string): void;
+}
+
+/**
+ * Generate an OpenAPI-backed connector and register it on the engine's connector
+ * registry so the baseline `connector_action` node can dispatch to the generated
+ * actions (ADR-0023). Returns the registered connector name.
+ */
+export function registerOpenApiConnector(registry: ConnectorRegistrySurface, config: OpenApiConnectorConfig): string {
+    const { def, handlers } = createOpenApiConnector(config);
+    registry.registerConnector(def, handlers);
+    return def.name;
+}

packages/connectors/connector-openapi/src/index.ts

@@ -0,0 +1,36 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/connector-openapi
+ *
+ * Generate an ObjectStack {@link Connector} from a declarative OpenAPI 3.x
+ * document (ADR-0023). One operation becomes one connector action; a single
+ * generic handler drives a self-contained static-auth HTTP transport (mirroring
+ * `@objectstack/connector-rest`). The generated connector is an ordinary
+ * `type: 'api'` connector — registered via `engine.registerConnector` with no
+ * new engine surface.
+ *
+ * Open-source scope: static auth only (`none` / `api-key` / `basic` / `bearer`),
+ * credentials supplied by the caller. Managed OAuth2, credential vaulting, and
+ * per-tenant lifecycle are the enterprise tier (ADR-0015 / 0022).
+ */
+
+export {
+    createOpenApiConnector,
+    type OpenApiConnectorBundle,
+    type OpenApiConnectorConfig,
+    type OpenApiDocument,
+    type OpenApiPathItem,
+    type OpenApiOperation,
+    type OpenApiParameter,
+    type OpenApiRequestBody,
+    type OpenApiResponse,
+    type OpenApiSecurityScheme,
+    type OperationInfo,
+    type RestAuth,
+    type JsonSchema,
+} from './openapi-connector.js';
+export {
+    registerOpenApiConnector,
+    type ConnectorRegistrySurface,
+} from './connector-openapi-plugin.js';