@objectstack/connector-openapi 7.4.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/openapi-connector.ts","../src/connector-openapi-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * @objectstack/connector-openapi\n *\n * Generate an ObjectStack {@link Connector} from a declarative OpenAPI 3.x\n * document (ADR-0023). One operation becomes one connector action; a single\n * generic handler drives a self-contained static-auth HTTP transport (mirroring\n * `@objectstack/connector-rest`). The generated connector is an ordinary\n * `type: 'api'` connector — registered via `engine.registerConnector` with no\n * new engine surface.\n *\n * Open-source scope: static auth only (`none` / `api-key` / `basic` / `bearer`),\n * credentials supplied by the caller. Managed OAuth2, credential vaulting, and\n * per-tenant lifecycle are the enterprise tier (ADR-0015 / 0022).\n */\n\nexport {\n    createOpenApiConnector,\n    type OpenApiConnectorBundle,\n    type OpenApiConnectorConfig,\n    type OpenApiDocument,\n    type OpenApiPathItem,\n    type OpenApiOperation,\n    type OpenApiParameter,\n    type OpenApiRequestBody,\n    type OpenApiResponse,\n    type OpenApiSecurityScheme,\n    type OperationInfo,\n    type RestAuth,\n    type JsonSchema,\n} from './openapi-connector.js';\nexport {\n    registerOpenApiConnector,\n    type ConnectorRegistrySurface,\n} from './connector-openapi-plugin.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Connector } from '@objectstack/spec/integration';\n\n/**\n * OpenAPI connector generator — turns a declarative OpenAPI 3.x document into a\n * {@link Connector} definition + handler map (ADR-0023).\n *\n * Each OpenAPI operation maps to one connector action; a single generic handler\n * (closing over the operation's method + path template) drives one shared HTTP\n * request implementation. That transport mirrors `@objectstack/connector-rest`\n * (build URL from base+path+query, apply static auth, JSON-encode the body,\n * normalise the response to `{ status, ok, body }`) — kept inline so this package\n * stays self-contained, depending only on `@objectstack/core` + `@objectstack/spec`\n * like its sibling connectors. The output is an ordinary `type: 'api'` connector,\n * registered via `engine.registerConnector(def, handlers)` exactly like a\n * hand-written one — the registry, the `connector_action` node, the discovery\n * route, and the Studio palette never know it came from OpenAPI.\n *\n * Open-source scope: **static** auth only (`none` / `api-key` / `basic` /\n * `bearer`), with credentials supplied by the caller. Managed OAuth2, credential\n * vaulting, and per-tenant lifecycle are the enterprise tier (ADR-0015 / 0022).\n */\n\n/** Static auth understood by the generated connector (the open-source subset). */\nexport type RestAuth = Extract<Connector['authentication'], { type: 'none' | 'api-key' | 'basic' | 'bearer' }>;\n\n/** An action on a Connector definition (derived to avoid guessing export names). */\ntype ConnectorAction = NonNullable<Connector['actions']>[number];\n\n/** Handler signature accepted by the connector registry (ADR-0018 §Addendum). */\ntype ConnectorHandler = (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>;\n\n/** A connector definition paired with its action handlers, ready for registerConnector(). */\nexport interface OpenApiConnectorBundle {\n    def: Connector;\n    handlers: Record<string, ConnectorHandler>;\n}\n\n/** A free-form JSON Schema fragment (matches ConnectorAction input/outputSchema). */\nexport type JsonSchema = Record<string, unknown>;\n\n/** Minimal subset of an OpenAPI 3.x document consumed by the generator.\n *  The caller is responsible for loading and de-referencing ($ref) the doc. */\nexport interface OpenApiDocument {\n    openapi?: string;\n    info?: { title?: string; description?: string; version?: string };\n    servers?: { url: string }[];\n    paths?: Record<string, OpenApiPathItem>;\n    components?: { securitySchemes?: Record<string, OpenApiSecurityScheme> };\n}\n\nexport interface OpenApiPathItem {\n    [method: string]: OpenApiOperation | unknown;\n}\n\nexport interface OpenApiOperation {\n    operationId?: string;\n    summary?: string;\n    description?: string;\n    tags?: string[];\n    parameters?: OpenApiParameter[];\n    requestBody?: OpenApiRequestBody;\n    responses?: Record<string, OpenApiResponse>;\n}\n\nexport interface OpenApiParameter {\n    name: string;\n    in: 'path' | 'query' | 'header' | 'cookie';\n    required?: boolean;\n    description?: string;\n    schema?: JsonSchema;\n}\n\nexport interface OpenApiRequestBody {\n    required?: boolean;\n    description?: string;\n    content?: Record<string, { schema?: JsonSchema }>;\n}\n\nexport interface OpenApiResponse {\n    description?: string;\n    content?: Record<string, { schema?: JsonSchema }>;\n}\n\nexport interface OpenApiSecurityScheme {\n    type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';\n    name?: string;\n    in?: 'header' | 'query' | 'cookie';\n    scheme?: string;\n}\n\n/** Flattened view of a single operation, passed to the `include` predicate. */\nexport interface OperationInfo {\n    operationId?: string;\n    method: string;\n    path: string;\n    tags?: string[];\n    summary?: string;\n    description?: string;\n}\n\n/** Configuration for {@link createOpenApiConnector}. */\nexport interface OpenApiConnectorConfig {\n    /** Connector machine name (snake_case). Defaults to a slug of info.title. */\n    name?: string;\n    /** Human-friendly label. Defaults to info.title (then name). */\n    label?: string;\n    /** Description. Defaults to info.description. */\n    description?: string;\n    /** Icon identifier for the Studio palette. Defaults to `globe`. */\n    icon?: string;\n    /** The parsed OpenAPI 3.x document (caller loads/derefs it). */\n    document: OpenApiDocument;\n    /** Override the base URL (else servers[0].url). */\n    baseUrl?: string;\n    /** Static auth with credentials. Defaults to `{ type: 'none' }`. */\n    auth?: RestAuth;\n    /** Headers merged into every request (request-level headers win). */\n    defaultHeaders?: Record<string, string>;\n    /** Only include operations for which this predicate returns true (allowlist). */\n    include?: (op: OperationInfo) => boolean;\n    /** Injected fetch implementation (defaults to global `fetch`). */\n    fetchImpl?: typeof fetch;\n}\n\n/** OpenAPI HTTP method keys, in a deterministic order. */\nconst HTTP_METHODS = ['get', 'put', 'post', 'delete', 'patch', 'options', 'head', 'trace'] as const;\n\n/** Input passed to the shared request transport. */\ninterface RequestInput {\n    method: string;\n    path: string;\n    headers?: Record<string, string>;\n    query?: Record<string, string>;\n    body?: unknown;\n}\n\n/**\n * Build an OpenAPI connector definition and its handler map.\n *\n * @returns the `Connector` definition (`def`) and a `handlers` record keyed by\n * action key, suitable for `engine.registerConnector(def, handlers)`.\n */\nexport function createOpenApiConnector(config: OpenApiConnectorConfig): OpenApiConnectorBundle {\n    const { document, include } = config;\n    const auth: RestAuth = config.auth ?? { type: 'none' };\n    const doFetch = config.fetchImpl ?? fetch;\n    const name = config.name ?? slug(document.info?.title ?? 'openapi_connector');\n    const label = config.label ?? document.info?.title ?? titleize(name);\n    const description = config.description ?? document.info?.description;\n    const baseUrl = config.baseUrl ?? document.servers?.[0]?.url;\n    if (!baseUrl) {\n        throw new Error('createOpenApiConnector: no base URL — provide config.baseUrl or document.servers[0].url');\n    }\n\n    // One shared transport (mirrors connector-rest) reused by every action handler.\n    async function request(input: RequestInput): Promise<Record<string, unknown>> {\n        const method = input.method.toUpperCase();\n        const headers: Record<string, string> = { ...config.defaultHeaders, ...input.headers };\n        const query: Record<string, string> = { ...input.query };\n        applyAuth(auth, headers, query);\n\n        const url = buildUrl(baseUrl as string, input.path, query);\n        const hasBody = input.body !== undefined && method !== 'GET' && method !== 'HEAD';\n        if (hasBody && headers['Content-Type'] === undefined && headers['content-type'] === undefined) {\n            headers['Content-Type'] = 'application/json';\n        }\n\n        const response = await doFetch(url, {\n            method,\n            headers,\n            body: hasBody ? JSON.stringify(input.body) : undefined,\n        });\n\n        const contentType = response.headers.get('content-type') ?? '';\n        const parsed = contentType.includes('application/json') ? await response.json() : await response.text();\n        return { status: response.status, ok: response.ok, body: parsed };\n    }\n\n    const actions: ConnectorAction[] = [];\n    const handlers: Record<string, ConnectorHandler> = {};\n    const seenKeys = new Set<string>();\n\n    for (const op of collectOperations(document)) {\n        if (include && !include(toInfo(op))) continue;\n        const key = uniqueKey(op.operationId ?? slug(`${op.method}_${op.path}`), seenKeys);\n\n        actions.push({\n            key,\n            label: op.summary ?? titleize(key),\n            description: op.description,\n            inputSchema: buildInputSchema(op),\n            outputSchema: buildOutputSchema(op),\n        });\n\n        handlers[key] = async (input: Record<string, unknown>) => {\n            const req = input as { path?: unknown; query?: unknown; header?: unknown; body?: unknown };\n            return request({\n                method: op.method,\n                path: interpolatePath(op.path, asRecord(req.path)),\n                query: stringifyValues(asRecord(req.query)),\n                headers: stringifyValues(asRecord(req.header)),\n                body: req.body,\n            });\n        };\n    }\n\n    const def: Connector = {\n        name,\n        label,\n        type: 'api',\n        description,\n        icon: config.icon ?? 'globe',\n        authentication: auth,\n        // Defaulted by ConnectorSchema; set explicitly so the literal satisfies\n        // the (post-parse) Connector output type (mirrors connector-rest/mcp).\n        status: 'active',\n        enabled: true,\n        connectionTimeoutMs: 30000,\n        requestTimeoutMs: 30000,\n        actions,\n    };\n\n    return { def, handlers };\n}\n\ninterface Op extends OpenApiOperation {\n    method: string;\n    path: string;\n}\n\n/** Flatten paths × methods into a deterministic list of operations. */\nfunction collectOperations(doc: OpenApiDocument): Op[] {\n    const ops: Op[] = [];\n    for (const [path, item] of Object.entries(doc.paths ?? {})) {\n        if (!item || typeof item !== 'object') continue;\n        const record = item as Record<string, unknown>;\n        for (const method of HTTP_METHODS) {\n            const operation = record[method] as OpenApiOperation | undefined;\n            if (!operation || typeof operation !== 'object') continue;\n            ops.push({ ...operation, method, path });\n        }\n    }\n    return ops;\n}\n\nfunction toInfo(op: Op): OperationInfo {\n    return {\n        operationId: op.operationId,\n        method: op.method,\n        path: op.path,\n        tags: op.tags,\n        summary: op.summary,\n        description: op.description,\n    };\n}\n\n/**\n * Assemble the action inputSchema from an operation's parameters + requestBody.\n * Produces { type: 'object', properties: { path, query, header, body }, required }\n * where only non-empty sections are emitted.\n */\nfunction buildInputSchema(op: OpenApiOperation): JsonSchema | undefined {\n    const sections: Record<'path' | 'query' | 'header', { props: Record<string, JsonSchema>; required: string[] }> = {\n        path: { props: {}, required: [] },\n        query: { props: {}, required: [] },\n        header: { props: {}, required: [] },\n    };\n\n    for (const p of op.parameters ?? []) {\n        if (!p || typeof p !== 'object' || '$ref' in p) continue;\n        if (p.in !== 'path' && p.in !== 'query' && p.in !== 'header') continue;\n        const sec = sections[p.in];\n        sec.props[p.name] = p.schema ?? (p.description ? { type: 'string', description: p.description } : { type: 'string' });\n        if (p.required) sec.required.push(p.name);\n    }\n\n    const properties: Record<string, JsonSchema> = {};\n    const required: string[] = [];\n    for (const where of ['path', 'query', 'header'] as const) {\n        const sec = sections[where];\n        if (Object.keys(sec.props).length === 0) continue;\n        const schema: JsonSchema = { type: 'object', properties: sec.props };\n        if (sec.required.length) schema.required = sec.required;\n        properties[where] = schema;\n        // Path params are always required when present; others only if any are.\n        if (where === 'path' || sec.required.length) required.push(where);\n    }\n\n    const bodySchema = extractRequestBodySchema(op.requestBody);\n    if (bodySchema) {\n        properties.body = bodySchema;\n        if (op.requestBody && !('$ref' in op.requestBody) && op.requestBody.required) required.push('body');\n    }\n\n    if (Object.keys(properties).length === 0) return undefined;\n    const schema: JsonSchema = { type: 'object', properties };\n    if (required.length) schema.required = required;\n    return schema;\n}\n\n/** Pick the success response's JSON schema (200 → first 2xx → default). */\nfunction buildOutputSchema(op: OpenApiOperation): JsonSchema | undefined {\n    const responses = op.responses;\n    if (!responses) return undefined;\n    let code: string | undefined;\n    if (responses['200']) code = '200';\n    else code = Object.keys(responses).find((c) => /^2\\d\\d$/.test(c));\n    if (!code && responses['default']) code = 'default';\n    if (!code) return undefined;\n    const resp = responses[code];\n    if (!resp || typeof resp !== 'object' || '$ref' in resp) return undefined;\n    return pickJsonSchema(resp.content);\n}\n\n/** Extract the requestBody JSON schema (prefers application/json). */\nfunction extractRequestBodySchema(rb: OpenApiRequestBody | undefined): JsonSchema | undefined {\n    if (!rb || typeof rb !== 'object' || '$ref' in rb) return undefined;\n    return pickJsonSchema(rb.content);\n}\n\n/** Choose the application/json schema, falling back to the first content type. */\nfunction pickJsonSchema(content: Record<string, { schema?: JsonSchema }> | undefined): JsonSchema | undefined {\n    if (!content) return undefined;\n    const chosen = content['application/json'] ?? Object.values(content)[0];\n    return chosen?.schema;\n}\n\n/** Build the request URL from base + path + query, encoding query params. */\nfunction buildUrl(baseUrl: string, path: string, query: Record<string, string>): string {\n    const base = baseUrl.replace(/\\/+$/, '');\n    const suffix = path ? (path.startsWith('/') ? path : `/${path}`) : '';\n    const url = new URL(base + suffix);\n    for (const [key, value] of Object.entries(query)) {\n        if (value !== undefined && value !== null) url.searchParams.set(key, String(value));\n    }\n    return url.toString();\n}\n\n/** Apply static auth to the outgoing headers / query (mirrors connector-rest). */\nfunction applyAuth(auth: RestAuth, headers: Record<string, string>, query: Record<string, string>): void {\n    switch (auth.type) {\n        case 'none':\n            return;\n        case 'bearer':\n            headers['Authorization'] = `Bearer ${auth.token}`;\n            return;\n        case 'basic': {\n            const encoded = Buffer.from(`${auth.username}:${auth.password}`).toString('base64');\n            headers['Authorization'] = `Basic ${encoded}`;\n            return;\n        }\n        case 'api-key':\n            if (auth.paramName) query[auth.paramName] = auth.key;\n            else headers[auth.headerName ?? 'X-API-Key'] = auth.key;\n            return;\n    }\n}\n\n/** Interpolate {name} path templates with encoded values from the input. */\nfunction interpolatePath(template: string, pathParams: Record<string, unknown>): string {\n    return template.replace(/\\{([^}]+)\\}/g, (_match, key: string) => {\n        const value = pathParams[key];\n        return value === undefined || value === null ? `{${key}}` : encodeURIComponent(String(value));\n    });\n}\n\n/** Coerce a record of mixed values into string values, dropping null/undefined. */\nfunction stringifyValues(rec: Record<string, unknown>): Record<string, string> {\n    const out: Record<string, string> = {};\n    for (const [k, v] of Object.entries(rec)) {\n        if (v === undefined || v === null) continue;\n        out[k] = String(v);\n    }\n    return out;\n}\n\n/** Return v if it is a plain object, else an empty record. */\nfunction asRecord(v: unknown): Record<string, unknown> {\n    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};\n}\n\n/** Ensure a deterministically unique action key within the connector. */\nfunction uniqueKey(base: string, seen: Set<string>): string {\n    let candidate = base;\n    if (seen.has(candidate)) {\n        let i = 2;\n        while (seen.has(`${base}_${i}`)) i++;\n        candidate = `${base}_${i}`;\n    }\n    seen.add(candidate);\n    return candidate;\n}\n\n/** Slugify a string into a snake_case machine name (`/^[a-z_][a-z0-9_]*$/`). */\nfunction slug(s: string): string {\n    const out = s\n        .normalize('NFKD')\n        .replace(/[^a-zA-Z0-9]+/g, '_')\n        .replace(/^_+|_+$/g, '')\n        .toLowerCase();\n    if (!out) return 'connector';\n    return /^[a-z_]/.test(out) ? out : `op_${out}`;\n}\n\n/** Title-case a snake_case key for a default label (`get_pets` → `Get Pets`). */\nfunction titleize(name: string): string {\n    return name\n        .split('_')\n        .filter(Boolean)\n        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))\n        .join(' ');\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Connector } from '@objectstack/spec/integration';\nimport { createOpenApiConnector, type OpenApiConnectorConfig } from './openapi-connector.js';\n\n/**\n * Minimal surface of the automation engine this helper depends on — the\n * connector registry from ADR-0018 §Addendum. Kept structural so callers need\n * no runtime dependency on `@objectstack/service-automation` (mirrors\n * connector-rest / connector-mcp).\n */\nexport interface ConnectorRegistrySurface {\n    registerConnector(\n        def: Connector,\n        handlers: Record<\n            string,\n            (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>\n        >,\n    ): void;\n    unregisterConnector(name: string): void;\n}\n\n/**\n * Generate an OpenAPI-backed connector and register it on the engine's connector\n * registry so the baseline `connector_action` node can dispatch to the generated\n * actions (ADR-0023). Returns the registered connector name.\n */\nexport function registerOpenApiConnector(registry: ConnectorRegistrySurface, config: OpenApiConnectorConfig): string {\n    const { def, handlers } = createOpenApiConnector(config);\n    registry.registerConnector(def, handlers);\n    return def.name;\n}\n"],"mappings":"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","names":["schema"]}

package/dist/index.mjs

@@ -0,0 +1,224 @@
+// src/openapi-connector.ts
+var HTTP_METHODS = ["get", "put", "post", "delete", "patch", "options", "head", "trace"];
+function createOpenApiConnector(config) {
+  const { document, include } = config;
+  const auth = config.auth ?? { type: "none" };
+  const doFetch = config.fetchImpl ?? fetch;
+  const name = config.name ?? slug(document.info?.title ?? "openapi_connector");
+  const label = config.label ?? document.info?.title ?? titleize(name);
+  const description = config.description ?? document.info?.description;
+  const baseUrl = config.baseUrl ?? document.servers?.[0]?.url;
+  if (!baseUrl) {
+    throw new Error("createOpenApiConnector: no base URL \u2014 provide config.baseUrl or document.servers[0].url");
+  }
+  async function request(input) {
+    const method = input.method.toUpperCase();
+    const headers = { ...config.defaultHeaders, ...input.headers };
+    const query = { ...input.query };
+    applyAuth(auth, headers, query);
+    const url = buildUrl(baseUrl, input.path, query);
+    const hasBody = input.body !== void 0 && method !== "GET" && method !== "HEAD";
+    if (hasBody && headers["Content-Type"] === void 0 && headers["content-type"] === void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const response = await doFetch(url, {
+      method,
+      headers,
+      body: hasBody ? JSON.stringify(input.body) : void 0
+    });
+    const contentType = response.headers.get("content-type") ?? "";
+    const parsed = contentType.includes("application/json") ? await response.json() : await response.text();
+    return { status: response.status, ok: response.ok, body: parsed };
+  }
+  const actions = [];
+  const handlers = {};
+  const seenKeys = /* @__PURE__ */ new Set();
+  for (const op of collectOperations(document)) {
+    if (include && !include(toInfo(op))) continue;
+    const key = uniqueKey(op.operationId ?? slug(`${op.method}_${op.path}`), seenKeys);
+    actions.push({
+      key,
+      label: op.summary ?? titleize(key),
+      description: op.description,
+      inputSchema: buildInputSchema(op),
+      outputSchema: buildOutputSchema(op)
+    });
+    handlers[key] = async (input) => {
+      const req = input;
+      return request({
+        method: op.method,
+        path: interpolatePath(op.path, asRecord(req.path)),
+        query: stringifyValues(asRecord(req.query)),
+        headers: stringifyValues(asRecord(req.header)),
+        body: req.body
+      });
+    };
+  }
+  const def = {
+    name,
+    label,
+    type: "api",
+    description,
+    icon: config.icon ?? "globe",
+    authentication: auth,
+    // Defaulted by ConnectorSchema; set explicitly so the literal satisfies
+    // the (post-parse) Connector output type (mirrors connector-rest/mcp).
+    status: "active",
+    enabled: true,
+    connectionTimeoutMs: 3e4,
+    requestTimeoutMs: 3e4,
+    actions
+  };
+  return { def, handlers };
+}
+function collectOperations(doc) {
+  const ops = [];
+  for (const [path, item] of Object.entries(doc.paths ?? {})) {
+    if (!item || typeof item !== "object") continue;
+    const record = item;
+    for (const method of HTTP_METHODS) {
+      const operation = record[method];
+      if (!operation || typeof operation !== "object") continue;
+      ops.push({ ...operation, method, path });
+    }
+  }
+  return ops;
+}
+function toInfo(op) {
+  return {
+    operationId: op.operationId,
+    method: op.method,
+    path: op.path,
+    tags: op.tags,
+    summary: op.summary,
+    description: op.description
+  };
+}
+function buildInputSchema(op) {
+  const sections = {
+    path: { props: {}, required: [] },
+    query: { props: {}, required: [] },
+    header: { props: {}, required: [] }
+  };
+  for (const p of op.parameters ?? []) {
+    if (!p || typeof p !== "object" || "$ref" in p) continue;
+    if (p.in !== "path" && p.in !== "query" && p.in !== "header") continue;
+    const sec = sections[p.in];
+    sec.props[p.name] = p.schema ?? (p.description ? { type: "string", description: p.description } : { type: "string" });
+    if (p.required) sec.required.push(p.name);
+  }
+  const properties = {};
+  const required = [];
+  for (const where of ["path", "query", "header"]) {
+    const sec = sections[where];
+    if (Object.keys(sec.props).length === 0) continue;
+    const schema2 = { type: "object", properties: sec.props };
+    if (sec.required.length) schema2.required = sec.required;
+    properties[where] = schema2;
+    if (where === "path" || sec.required.length) required.push(where);
+  }
+  const bodySchema = extractRequestBodySchema(op.requestBody);
+  if (bodySchema) {
+    properties.body = bodySchema;
+    if (op.requestBody && !("$ref" in op.requestBody) && op.requestBody.required) required.push("body");
+  }
+  if (Object.keys(properties).length === 0) return void 0;
+  const schema = { type: "object", properties };
+  if (required.length) schema.required = required;
+  return schema;
+}
+function buildOutputSchema(op) {
+  const responses = op.responses;
+  if (!responses) return void 0;
+  let code;
+  if (responses["200"]) code = "200";
+  else code = Object.keys(responses).find((c) => /^2\d\d$/.test(c));
+  if (!code && responses["default"]) code = "default";
+  if (!code) return void 0;
+  const resp = responses[code];
+  if (!resp || typeof resp !== "object" || "$ref" in resp) return void 0;
+  return pickJsonSchema(resp.content);
+}
+function extractRequestBodySchema(rb) {
+  if (!rb || typeof rb !== "object" || "$ref" in rb) return void 0;
+  return pickJsonSchema(rb.content);
+}
+function pickJsonSchema(content) {
+  if (!content) return void 0;
+  const chosen = content["application/json"] ?? Object.values(content)[0];
+  return chosen?.schema;
+}
+function buildUrl(baseUrl, path, query) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const suffix = path ? path.startsWith("/") ? path : `/${path}` : "";
+  const url = new URL(base + suffix);
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0 && value !== null) url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+function applyAuth(auth, headers, query) {
+  switch (auth.type) {
+    case "none":
+      return;
+    case "bearer":
+      headers["Authorization"] = `Bearer ${auth.token}`;
+      return;
+    case "basic": {
+      const encoded = Buffer.from(`${auth.username}:${auth.password}`).toString("base64");
+      headers["Authorization"] = `Basic ${encoded}`;
+      return;
+    }
+    case "api-key":
+      if (auth.paramName) query[auth.paramName] = auth.key;
+      else headers[auth.headerName ?? "X-API-Key"] = auth.key;
+      return;
+  }
+}
+function interpolatePath(template, pathParams) {
+  return template.replace(/\{([^}]+)\}/g, (_match, key) => {
+    const value = pathParams[key];
+    return value === void 0 || value === null ? `{${key}}` : encodeURIComponent(String(value));
+  });
+}
+function stringifyValues(rec) {
+  const out = {};
+  for (const [k, v] of Object.entries(rec)) {
+    if (v === void 0 || v === null) continue;
+    out[k] = String(v);
+  }
+  return out;
+}
+function asRecord(v) {
+  return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+function uniqueKey(base, seen) {
+  let candidate = base;
+  if (seen.has(candidate)) {
+    let i = 2;
+    while (seen.has(`${base}_${i}`)) i++;
+    candidate = `${base}_${i}`;
+  }
+  seen.add(candidate);
+  return candidate;
+}
+function slug(s) {
+  const out = s.normalize("NFKD").replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+  if (!out) return "connector";
+  return /^[a-z_]/.test(out) ? out : `op_${out}`;
+}
+function titleize(name) {
+  return name.split("_").filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+
+// src/connector-openapi-plugin.ts
+function registerOpenApiConnector(registry, config) {
+  const { def, handlers } = createOpenApiConnector(config);
+  registry.registerConnector(def, handlers);
+  return def.name;
+}
+export {
+  createOpenApiConnector,
+  registerOpenApiConnector
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/openapi-connector.ts","../src/connector-openapi-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Connector } from '@objectstack/spec/integration';\n\n/**\n * OpenAPI connector generator — turns a declarative OpenAPI 3.x document into a\n * {@link Connector} definition + handler map (ADR-0023).\n *\n * Each OpenAPI operation maps to one connector action; a single generic handler\n * (closing over the operation's method + path template) drives one shared HTTP\n * request implementation. That transport mirrors `@objectstack/connector-rest`\n * (build URL from base+path+query, apply static auth, JSON-encode the body,\n * normalise the response to `{ status, ok, body }`) — kept inline so this package\n * stays self-contained, depending only on `@objectstack/core` + `@objectstack/spec`\n * like its sibling connectors. The output is an ordinary `type: 'api'` connector,\n * registered via `engine.registerConnector(def, handlers)` exactly like a\n * hand-written one — the registry, the `connector_action` node, the discovery\n * route, and the Studio palette never know it came from OpenAPI.\n *\n * Open-source scope: **static** auth only (`none` / `api-key` / `basic` /\n * `bearer`), with credentials supplied by the caller. Managed OAuth2, credential\n * vaulting, and per-tenant lifecycle are the enterprise tier (ADR-0015 / 0022).\n */\n\n/** Static auth understood by the generated connector (the open-source subset). */\nexport type RestAuth = Extract<Connector['authentication'], { type: 'none' | 'api-key' | 'basic' | 'bearer' }>;\n\n/** An action on a Connector definition (derived to avoid guessing export names). */\ntype ConnectorAction = NonNullable<Connector['actions']>[number];\n\n/** Handler signature accepted by the connector registry (ADR-0018 §Addendum). */\ntype ConnectorHandler = (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>;\n\n/** A connector definition paired with its action handlers, ready for registerConnector(). */\nexport interface OpenApiConnectorBundle {\n    def: Connector;\n    handlers: Record<string, ConnectorHandler>;\n}\n\n/** A free-form JSON Schema fragment (matches ConnectorAction input/outputSchema). */\nexport type JsonSchema = Record<string, unknown>;\n\n/** Minimal subset of an OpenAPI 3.x document consumed by the generator.\n *  The caller is responsible for loading and de-referencing ($ref) the doc. */\nexport interface OpenApiDocument {\n    openapi?: string;\n    info?: { title?: string; description?: string; version?: string };\n    servers?: { url: string }[];\n    paths?: Record<string, OpenApiPathItem>;\n    components?: { securitySchemes?: Record<string, OpenApiSecurityScheme> };\n}\n\nexport interface OpenApiPathItem {\n    [method: string]: OpenApiOperation | unknown;\n}\n\nexport interface OpenApiOperation {\n    operationId?: string;\n    summary?: string;\n    description?: string;\n    tags?: string[];\n    parameters?: OpenApiParameter[];\n    requestBody?: OpenApiRequestBody;\n    responses?: Record<string, OpenApiResponse>;\n}\n\nexport interface OpenApiParameter {\n    name: string;\n    in: 'path' | 'query' | 'header' | 'cookie';\n    required?: boolean;\n    description?: string;\n    schema?: JsonSchema;\n}\n\nexport interface OpenApiRequestBody {\n    required?: boolean;\n    description?: string;\n    content?: Record<string, { schema?: JsonSchema }>;\n}\n\nexport interface OpenApiResponse {\n    description?: string;\n    content?: Record<string, { schema?: JsonSchema }>;\n}\n\nexport interface OpenApiSecurityScheme {\n    type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';\n    name?: string;\n    in?: 'header' | 'query' | 'cookie';\n    scheme?: string;\n}\n\n/** Flattened view of a single operation, passed to the `include` predicate. */\nexport interface OperationInfo {\n    operationId?: string;\n    method: string;\n    path: string;\n    tags?: string[];\n    summary?: string;\n    description?: string;\n}\n\n/** Configuration for {@link createOpenApiConnector}. */\nexport interface OpenApiConnectorConfig {\n    /** Connector machine name (snake_case). Defaults to a slug of info.title. */\n    name?: string;\n    /** Human-friendly label. Defaults to info.title (then name). */\n    label?: string;\n    /** Description. Defaults to info.description. */\n    description?: string;\n    /** Icon identifier for the Studio palette. Defaults to `globe`. */\n    icon?: string;\n    /** The parsed OpenAPI 3.x document (caller loads/derefs it). */\n    document: OpenApiDocument;\n    /** Override the base URL (else servers[0].url). */\n    baseUrl?: string;\n    /** Static auth with credentials. Defaults to `{ type: 'none' }`. */\n    auth?: RestAuth;\n    /** Headers merged into every request (request-level headers win). */\n    defaultHeaders?: Record<string, string>;\n    /** Only include operations for which this predicate returns true (allowlist). */\n    include?: (op: OperationInfo) => boolean;\n    /** Injected fetch implementation (defaults to global `fetch`). */\n    fetchImpl?: typeof fetch;\n}\n\n/** OpenAPI HTTP method keys, in a deterministic order. */\nconst HTTP_METHODS = ['get', 'put', 'post', 'delete', 'patch', 'options', 'head', 'trace'] as const;\n\n/** Input passed to the shared request transport. */\ninterface RequestInput {\n    method: string;\n    path: string;\n    headers?: Record<string, string>;\n    query?: Record<string, string>;\n    body?: unknown;\n}\n\n/**\n * Build an OpenAPI connector definition and its handler map.\n *\n * @returns the `Connector` definition (`def`) and a `handlers` record keyed by\n * action key, suitable for `engine.registerConnector(def, handlers)`.\n */\nexport function createOpenApiConnector(config: OpenApiConnectorConfig): OpenApiConnectorBundle {\n    const { document, include } = config;\n    const auth: RestAuth = config.auth ?? { type: 'none' };\n    const doFetch = config.fetchImpl ?? fetch;\n    const name = config.name ?? slug(document.info?.title ?? 'openapi_connector');\n    const label = config.label ?? document.info?.title ?? titleize(name);\n    const description = config.description ?? document.info?.description;\n    const baseUrl = config.baseUrl ?? document.servers?.[0]?.url;\n    if (!baseUrl) {\n        throw new Error('createOpenApiConnector: no base URL — provide config.baseUrl or document.servers[0].url');\n    }\n\n    // One shared transport (mirrors connector-rest) reused by every action handler.\n    async function request(input: RequestInput): Promise<Record<string, unknown>> {\n        const method = input.method.toUpperCase();\n        const headers: Record<string, string> = { ...config.defaultHeaders, ...input.headers };\n        const query: Record<string, string> = { ...input.query };\n        applyAuth(auth, headers, query);\n\n        const url = buildUrl(baseUrl as string, input.path, query);\n        const hasBody = input.body !== undefined && method !== 'GET' && method !== 'HEAD';\n        if (hasBody && headers['Content-Type'] === undefined && headers['content-type'] === undefined) {\n            headers['Content-Type'] = 'application/json';\n        }\n\n        const response = await doFetch(url, {\n            method,\n            headers,\n            body: hasBody ? JSON.stringify(input.body) : undefined,\n        });\n\n        const contentType = response.headers.get('content-type') ?? '';\n        const parsed = contentType.includes('application/json') ? await response.json() : await response.text();\n        return { status: response.status, ok: response.ok, body: parsed };\n    }\n\n    const actions: ConnectorAction[] = [];\n    const handlers: Record<string, ConnectorHandler> = {};\n    const seenKeys = new Set<string>();\n\n    for (const op of collectOperations(document)) {\n        if (include && !include(toInfo(op))) continue;\n        const key = uniqueKey(op.operationId ?? slug(`${op.method}_${op.path}`), seenKeys);\n\n        actions.push({\n            key,\n            label: op.summary ?? titleize(key),\n            description: op.description,\n            inputSchema: buildInputSchema(op),\n            outputSchema: buildOutputSchema(op),\n        });\n\n        handlers[key] = async (input: Record<string, unknown>) => {\n            const req = input as { path?: unknown; query?: unknown; header?: unknown; body?: unknown };\n            return request({\n                method: op.method,\n                path: interpolatePath(op.path, asRecord(req.path)),\n                query: stringifyValues(asRecord(req.query)),\n                headers: stringifyValues(asRecord(req.header)),\n                body: req.body,\n            });\n        };\n    }\n\n    const def: Connector = {\n        name,\n        label,\n        type: 'api',\n        description,\n        icon: config.icon ?? 'globe',\n        authentication: auth,\n        // Defaulted by ConnectorSchema; set explicitly so the literal satisfies\n        // the (post-parse) Connector output type (mirrors connector-rest/mcp).\n        status: 'active',\n        enabled: true,\n        connectionTimeoutMs: 30000,\n        requestTimeoutMs: 30000,\n        actions,\n    };\n\n    return { def, handlers };\n}\n\ninterface Op extends OpenApiOperation {\n    method: string;\n    path: string;\n}\n\n/** Flatten paths × methods into a deterministic list of operations. */\nfunction collectOperations(doc: OpenApiDocument): Op[] {\n    const ops: Op[] = [];\n    for (const [path, item] of Object.entries(doc.paths ?? {})) {\n        if (!item || typeof item !== 'object') continue;\n        const record = item as Record<string, unknown>;\n        for (const method of HTTP_METHODS) {\n            const operation = record[method] as OpenApiOperation | undefined;\n            if (!operation || typeof operation !== 'object') continue;\n            ops.push({ ...operation, method, path });\n        }\n    }\n    return ops;\n}\n\nfunction toInfo(op: Op): OperationInfo {\n    return {\n        operationId: op.operationId,\n        method: op.method,\n        path: op.path,\n        tags: op.tags,\n        summary: op.summary,\n        description: op.description,\n    };\n}\n\n/**\n * Assemble the action inputSchema from an operation's parameters + requestBody.\n * Produces { type: 'object', properties: { path, query, header, body }, required }\n * where only non-empty sections are emitted.\n */\nfunction buildInputSchema(op: OpenApiOperation): JsonSchema | undefined {\n    const sections: Record<'path' | 'query' | 'header', { props: Record<string, JsonSchema>; required: string[] }> = {\n        path: { props: {}, required: [] },\n        query: { props: {}, required: [] },\n        header: { props: {}, required: [] },\n    };\n\n    for (const p of op.parameters ?? []) {\n        if (!p || typeof p !== 'object' || '$ref' in p) continue;\n        if (p.in !== 'path' && p.in !== 'query' && p.in !== 'header') continue;\n        const sec = sections[p.in];\n        sec.props[p.name] = p.schema ?? (p.description ? { type: 'string', description: p.description } : { type: 'string' });\n        if (p.required) sec.required.push(p.name);\n    }\n\n    const properties: Record<string, JsonSchema> = {};\n    const required: string[] = [];\n    for (const where of ['path', 'query', 'header'] as const) {\n        const sec = sections[where];\n        if (Object.keys(sec.props).length === 0) continue;\n        const schema: JsonSchema = { type: 'object', properties: sec.props };\n        if (sec.required.length) schema.required = sec.required;\n        properties[where] = schema;\n        // Path params are always required when present; others only if any are.\n        if (where === 'path' || sec.required.length) required.push(where);\n    }\n\n    const bodySchema = extractRequestBodySchema(op.requestBody);\n    if (bodySchema) {\n        properties.body = bodySchema;\n        if (op.requestBody && !('$ref' in op.requestBody) && op.requestBody.required) required.push('body');\n    }\n\n    if (Object.keys(properties).length === 0) return undefined;\n    const schema: JsonSchema = { type: 'object', properties };\n    if (required.length) schema.required = required;\n    return schema;\n}\n\n/** Pick the success response's JSON schema (200 → first 2xx → default). */\nfunction buildOutputSchema(op: OpenApiOperation): JsonSchema | undefined {\n    const responses = op.responses;\n    if (!responses) return undefined;\n    let code: string | undefined;\n    if (responses['200']) code = '200';\n    else code = Object.keys(responses).find((c) => /^2\\d\\d$/.test(c));\n    if (!code && responses['default']) code = 'default';\n    if (!code) return undefined;\n    const resp = responses[code];\n    if (!resp || typeof resp !== 'object' || '$ref' in resp) return undefined;\n    return pickJsonSchema(resp.content);\n}\n\n/** Extract the requestBody JSON schema (prefers application/json). */\nfunction extractRequestBodySchema(rb: OpenApiRequestBody | undefined): JsonSchema | undefined {\n    if (!rb || typeof rb !== 'object' || '$ref' in rb) return undefined;\n    return pickJsonSchema(rb.content);\n}\n\n/** Choose the application/json schema, falling back to the first content type. */\nfunction pickJsonSchema(content: Record<string, { schema?: JsonSchema }> | undefined): JsonSchema | undefined {\n    if (!content) return undefined;\n    const chosen = content['application/json'] ?? Object.values(content)[0];\n    return chosen?.schema;\n}\n\n/** Build the request URL from base + path + query, encoding query params. */\nfunction buildUrl(baseUrl: string, path: string, query: Record<string, string>): string {\n    const base = baseUrl.replace(/\\/+$/, '');\n    const suffix = path ? (path.startsWith('/') ? path : `/${path}`) : '';\n    const url = new URL(base + suffix);\n    for (const [key, value] of Object.entries(query)) {\n        if (value !== undefined && value !== null) url.searchParams.set(key, String(value));\n    }\n    return url.toString();\n}\n\n/** Apply static auth to the outgoing headers / query (mirrors connector-rest). */\nfunction applyAuth(auth: RestAuth, headers: Record<string, string>, query: Record<string, string>): void {\n    switch (auth.type) {\n        case 'none':\n            return;\n        case 'bearer':\n            headers['Authorization'] = `Bearer ${auth.token}`;\n            return;\n        case 'basic': {\n            const encoded = Buffer.from(`${auth.username}:${auth.password}`).toString('base64');\n            headers['Authorization'] = `Basic ${encoded}`;\n            return;\n        }\n        case 'api-key':\n            if (auth.paramName) query[auth.paramName] = auth.key;\n            else headers[auth.headerName ?? 'X-API-Key'] = auth.key;\n            return;\n    }\n}\n\n/** Interpolate {name} path templates with encoded values from the input. */\nfunction interpolatePath(template: string, pathParams: Record<string, unknown>): string {\n    return template.replace(/\\{([^}]+)\\}/g, (_match, key: string) => {\n        const value = pathParams[key];\n        return value === undefined || value === null ? `{${key}}` : encodeURIComponent(String(value));\n    });\n}\n\n/** Coerce a record of mixed values into string values, dropping null/undefined. */\nfunction stringifyValues(rec: Record<string, unknown>): Record<string, string> {\n    const out: Record<string, string> = {};\n    for (const [k, v] of Object.entries(rec)) {\n        if (v === undefined || v === null) continue;\n        out[k] = String(v);\n    }\n    return out;\n}\n\n/** Return v if it is a plain object, else an empty record. */\nfunction asRecord(v: unknown): Record<string, unknown> {\n    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};\n}\n\n/** Ensure a deterministically unique action key within the connector. */\nfunction uniqueKey(base: string, seen: Set<string>): string {\n    let candidate = base;\n    if (seen.has(candidate)) {\n        let i = 2;\n        while (seen.has(`${base}_${i}`)) i++;\n        candidate = `${base}_${i}`;\n    }\n    seen.add(candidate);\n    return candidate;\n}\n\n/** Slugify a string into a snake_case machine name (`/^[a-z_][a-z0-9_]*$/`). */\nfunction slug(s: string): string {\n    const out = s\n        .normalize('NFKD')\n        .replace(/[^a-zA-Z0-9]+/g, '_')\n        .replace(/^_+|_+$/g, '')\n        .toLowerCase();\n    if (!out) return 'connector';\n    return /^[a-z_]/.test(out) ? out : `op_${out}`;\n}\n\n/** Title-case a snake_case key for a default label (`get_pets` → `Get Pets`). */\nfunction titleize(name: string): string {\n    return name\n        .split('_')\n        .filter(Boolean)\n        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))\n        .join(' ');\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Connector } from '@objectstack/spec/integration';\nimport { createOpenApiConnector, type OpenApiConnectorConfig } from './openapi-connector.js';\n\n/**\n * Minimal surface of the automation engine this helper depends on — the\n * connector registry from ADR-0018 §Addendum. Kept structural so callers need\n * no runtime dependency on `@objectstack/service-automation` (mirrors\n * connector-rest / connector-mcp).\n */\nexport interface ConnectorRegistrySurface {\n    registerConnector(\n        def: Connector,\n        handlers: Record<\n            string,\n            (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>\n        >,\n    ): void;\n    unregisterConnector(name: string): void;\n}\n\n/**\n * Generate an OpenAPI-backed connector and register it on the engine's connector\n * registry so the baseline `connector_action` node can dispatch to the generated\n * actions (ADR-0023). Returns the registered connector name.\n */\nexport function registerOpenApiConnector(registry: ConnectorRegistrySurface, config: OpenApiConnectorConfig): string {\n    const { def, handlers } = createOpenApiConnector(config);\n    registry.registerConnector(def, handlers);\n    return def.name;\n}\n"],"mappings":"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","names":["schema"]}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@objectstack/connector-openapi",
+  "version": "7.4.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"
+    }
+  },
+  "dependencies": {
+    "@objectstack/core": "7.4.0",
+    "@objectstack/spec": "7.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7",
+    "@objectstack/service-automation": "7.4.0"
+  },
+  "keywords": [
+    "objectstack",
+    "connector",
+    "openapi",
+    "swagger",
+    "integration",
+    "api"
+  ],
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/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');
+    });
+});

package/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;
+}

package/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';

package/src/openapi-connector.test.ts

@@ -0,0 +1,141 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { createOpenApiConnector, type OpenApiDocument } from './openapi-connector.js';
+
+const doc: OpenApiDocument = {
+    openapi: '3.0.0',
+    info: { title: 'Pet Store', description: 'A sample pet API' },
+    servers: [{ url: 'https://api.pets.example.com/v1' }],
+    components: {
+        securitySchemes: { apiKey: { type: 'apiKey', name: 'X-API-Key', in: 'header' } },
+    },
+    paths: {
+        '/pets/{petId}': {
+            get: {
+                operationId: 'getPetById',
+                summary: 'Get a pet by id',
+                tags: ['pets'],
+                parameters: [
+                    { name: 'petId', in: 'path', required: true, schema: { type: 'integer' } },
+                    { name: 'detail', in: 'query', schema: { type: 'string' } },
+                ],
+                responses: {
+                    '200': { content: { 'application/json': { schema: { type: 'object', properties: { id: { type: 'integer' } } } } } },
+                },
+            },
+        },
+        '/pets': {
+            post: {
+                operationId: 'createPet',
+                summary: 'Create a pet',
+                tags: ['pets'],
+                requestBody: {
+                    required: true,
+                    content: { 'application/json': { schema: { type: 'object', properties: { name: { type: 'string' } } } } },
+                },
+                responses: { '201': { description: 'created' } },
+            },
+            get: {
+                // no operationId — exercises the slug fallback
+                summary: 'List pets',
+                tags: ['admin'],
+                responses: { '200': { description: 'ok' } },
+            },
+        },
+    },
+};
+
+/** A fake fetch that records calls and returns a JSON response (mirrors connector-rest tests). */
+function fakeFetch(payload: unknown) {
+    const calls: Array<{ url: string; init: { method?: string; body?: unknown; headers?: Record<string, string> } }> = [];
+    const fetchImpl = (async (url: string, init: { method?: string; body?: unknown; headers?: Record<string, string> }) => {
+        calls.push({ url, init });
+        return {
+            status: 200,
+            ok: true,
+            headers: { get: () => 'application/json' },
+            json: async () => payload,
+            text: async () => JSON.stringify(payload),
+        };
+    }) as unknown as typeof fetch;
+    return { calls, fetchImpl };
+}
+
+describe('createOpenApiConnector', () => {
+    it('derives connector metadata from info + servers', () => {
+        const { def } = createOpenApiConnector({ document: doc });
+        expect(def.name).toBe('pet_store');
+        expect(def.label).toBe('Pet Store');
+        expect(def.description).toBe('A sample pet API');
+        expect(def.type).toBe('api');
+    });
+
+    it('maps each operation to an action and falls back to a slug key', () => {
+        const { def } = createOpenApiConnector({ document: doc });
+        const keys = (def.actions ?? []).map((a) => a.key);
+        expect(keys).toContain('getPetById');
+        expect(keys).toContain('createPet');
+        expect(keys).toContain('get_pets'); // GET /pets has no operationId
+    });
+
+    it('assembles input schema sections from parameters and requestBody', () => {
+        const { def } = createOpenApiConnector({ document: doc });
+        const get = def.actions?.find((a) => a.key === 'getPetById');
+        expect(get?.inputSchema).toMatchObject({
+            type: 'object',
+            properties: {
+                path: { type: 'object', properties: { petId: { type: 'integer' } }, required: ['petId'] },
+                query: { type: 'object', properties: { detail: { type: 'string' } } },
+            },
+            required: ['path'],
+        });
+
+        const post = def.actions?.find((a) => a.key === 'createPet');
+        expect(post?.inputSchema).toMatchObject({
+            properties: { body: { type: 'object', properties: { name: { type: 'string' } } } },
+            required: ['body'],
+        });
+    });
+
+    it('picks the success response schema as the output schema', () => {
+        const { def } = createOpenApiConnector({ document: doc });
+        const get = def.actions?.find((a) => a.key === 'getPetById');
+        expect(get?.outputSchema).toMatchObject({ type: 'object', properties: { id: { type: 'integer' } } });
+    });
+
+    it('defaults authentication to none and reflects supplied credentials', () => {
+        expect(createOpenApiConnector({ document: doc }).def.authentication).toEqual({ type: 'none' });
+        const withAuth = createOpenApiConnector({ document: doc, auth: { type: 'bearer', token: 'secret' } });
+        expect(withAuth.def.authentication).toEqual({ type: 'bearer', token: 'secret' });
+    });
+
+    it('honors an include allowlist', () => {
+        const { def } = createOpenApiConnector({ document: doc, include: (op) => (op.tags ?? []).includes('pets') });
+        expect((def.actions ?? []).map((a) => a.key)).toEqual(['getPetById', 'createPet']);
+    });
+
+    it('handler interpolates path params and forwards query via the REST request', async () => {
+        const { calls, fetchImpl } = fakeFetch({ id: 42 });
+        const { handlers } = createOpenApiConnector({ document: doc, fetchImpl });
+        const result = await handlers.getPetById({ path: { petId: 42 }, query: { detail: 'full' } }, {});
+
+        expect(calls).toHaveLength(1);
+        expect(calls[0].url).toBe('https://api.pets.example.com/v1/pets/42?detail=full');
+        expect(calls[0].init.method).toBe('GET');
+        expect(result).toEqual({ status: 200, ok: true, body: { id: 42 } });
+    });
+
+    it('handler sends a JSON body for write operations', async () => {
+        const { calls, fetchImpl } = fakeFetch({});
+        const { handlers } = createOpenApiConnector({ document: doc, fetchImpl });
+        await handlers.createPet({ body: { name: 'Rex' } }, {});
+
+        expect(calls[0].init.method).toBe('POST');
+        expect(calls[0].init.body).toBe(JSON.stringify({ name: 'Rex' }));
+    });
+
+    it('throws when no base URL can be determined', () => {
+        expect(() => createOpenApiConnector({ document: { info: { title: 'x' }, paths: {} } })).toThrow(/base URL/);
+    });
+});