@objectstack/connector-rest 15.0.0 → 15.1.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/connector-rest@15.0.0 build /home/runner/work/framework/framework/packages/connectors/connector-rest
+> @objectstack/connector-rest@15.1.1 build /home/runner/work/framework/framework/packages/connectors/connector-rest
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     4.64 KB
-ESM dist/index.mjs.map 12.96 KB
-ESM ⚡️ Build success in 87ms
-CJS dist/index.js     5.72 KB
-CJS dist/index.js.map 13.91 KB
-CJS ⚡️ Build success in 93ms
+ESM dist/index.mjs     6.23 KB
+ESM dist/index.mjs.map 18.35 KB
+ESM ⚡️ Build success in 75ms
+CJS dist/index.js     7.42 KB
+CJS dist/index.js.map 19.43 KB
+CJS ⚡️ Build success in 77ms
 DTS Build start
-DTS ⚡️ Build success in 15133ms
-DTS dist/index.d.mts 3.62 KB
-DTS dist/index.d.ts  3.62 KB
+DTS ⚡️ Build success in 13889ms
+DTS dist/index.d.mts 5.43 KB
+DTS dist/index.d.ts  5.43 KB

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @objectstack/connector-rest
 
+## 15.1.1
+
+### Patch Changes
+
+- @objectstack/spec@15.1.1
+- @objectstack/core@15.1.1
+
+## 15.1.0
+
+### Minor Changes
+
+- f531a26: feat(connectors): ADR-0096 — provider-bound declarative connector instances materialized at boot (#2977)
+
+  Declarative `connectors:` stack entries used to be **descriptor-only** (#2612):
+  registered as metadata but never dispatchable, the platform's one dead metadata
+  surface. An entry may now name a **`provider`** — an installed generic executor
+  (`openapi` / `mcp` / `rest`) — and the automation service **materializes** it
+  into a live, dispatchable connector at boot. AI can now wire an integration as
+  pure metadata and a flow `connector_action` calls it end-to-end.
+
+  - **Schema (`@objectstack/spec`).** `ConnectorSchema` gains `provider`,
+    `providerConfig`, and `auth` (a `credentialRef`-based instance-auth shape —
+    `ConnectorInstanceAuthSchema` — that references credentials, never inlines
+    them); `authentication` now defaults to `{ type: 'none' }` so a provider-bound
+    instance need not author it (loosening — existing connectors are unaffected).
+    `DeclarativeConnectorEntrySchema` (used by `stack.zod.ts`) rejects inline
+    secrets, orphan `providerConfig`/`auth`, and authored `actions`/`triggers` on a
+    provider-bound entry. A new `integration/connector-provider.ts` defines the
+    provider-factory contract as pure types.
+
+  - **Engine + boot (`@objectstack/service-automation`).** The engine adds a
+    connector-provider registry (`registerConnectorProvider`/`getConnectorProvider`)
+    and origin-tags registered connectors. At boot the service resolves each
+    provider-bound entry — looking up the factory, resolving `auth.credentialRef`
+    via a pluggable `CredentialResolver` (open-tier default: environment
+    variables), and registering the materialized connector. Boot **fails loudly**
+    for an unknown provider, invalid `providerConfig`, an unresolvable
+    `credentialRef`, or a name conflict with a plugin-registered connector (no
+    silent precedence).
+
+  - **Providers (`connector-rest` / `connector-openapi` / `connector-mcp`).** Each
+    plugin registers a provider factory in `init()` reusing its existing
+    generator/adapter API. Plugin options are now **optional**: with none the
+    plugin contributes only its provider factory; with instance options it also
+    registers a hand-wired connector (back-compat). `connector-openapi` adds a
+    `ConnectorOpenApiPlugin`.
+
+  Open tier: static auth (`none`/`api-key`/`basic`/`bearer`) with `credentialRef`
+  resolved from env vars. Managed vaulting, OAuth2 refresh, and per-tenant
+  connection lifecycle remain the enterprise tier (ADR-0015) — an enterprise host
+  injects a vault-backed `CredentialResolver` with no change to the materialization
+  path.
+
+### Patch Changes
+
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [3fe9df1]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [4109153]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [627f225]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+- Updated dependencies [f531a26]
+  - @objectstack/spec@15.1.0
+  - @objectstack/core@15.1.0
+
 ## 15.0.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Connector } from '@objectstack/spec/integration';
+import { Connector, ConnectorProviderFactory } from '@objectstack/spec/integration';
 import { Plugin, PluginContext } from '@objectstack/core';
 
 /**
@@ -48,20 +48,33 @@ declare function createRestConnector(opts: RestConnectorOptions): RestConnectorB
 
 /**
  * Minimal surface of the automation engine this plugin depends on — the
- * connector registry from ADR-0018 §Addendum. Kept structural so the plugin
- * needs no runtime dependency on `@objectstack/service-automation`.
+ * connector registry (ADR-0018 §Addendum) plus the provider registry (ADR-0097).
+ * Kept structural so the plugin needs no runtime dependency on
+ * `@objectstack/service-automation`.
  */
 interface ConnectorRegistrySurface {
     registerConnector(def: Connector, handlers: Record<string, (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>>): void;
     unregisterConnector(name: string): void;
+    registerConnectorProvider(providerKey: string, factory: ConnectorProviderFactory): void;
 }
-interface ConnectorRestPluginOptions extends RestConnectorOptions {
+/**
+ * Options for {@link ConnectorRestPlugin}. All optional (ADR-0097): with no
+ * `baseUrl` the plugin contributes only the `rest` provider factory — so a stack
+ * can declare `provider: 'rest'` instances as pure metadata. Supply `baseUrl`
+ * (etc.) to ALSO register a single hand-wired `rest` connector, the pre-ADR-0097
+ * usage.
+ */
+interface ConnectorRestPluginOptions extends Partial<RestConnectorOptions> {
 }
 /**
- * ConnectorRestPlugin — registers a generic REST connector on the automation
- * engine. This is the **reference concrete connector** (ADR-0018 §Addendum):
- * the dispatch node + registry are baseline; a connector like this one is a
- * plugin that populates the registry.
+ * ConnectorRestPlugin — contributes the generic REST connector (ADR-0018
+ * §Addendum) in two forms:
+ *
+ *  1. **Provider factory** (`rest`, ADR-0097): registered at `init()` so the
+ *     automation service can materialize declarative `provider: 'rest'`
+ *     `connectors:` entries into live connectors at boot.
+ *  2. **Hand-wired instance** (optional, back-compat): when constructed with a
+ *     `baseUrl`, it also registers one concrete `rest` connector at `start()`.
  *
  * If no automation engine is present the plugin logs and skips — the connector
  * has nowhere to register, which is not an error.
@@ -74,10 +87,33 @@ declare class ConnectorRestPlugin implements Plugin {
     private readonly options;
     private connectorName?;
     private automation?;
-    constructor(options: ConnectorRestPluginOptions);
-    init(_ctx: PluginContext): Promise<void>;
+    constructor(options?: ConnectorRestPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
     stop(_ctx: PluginContext): Promise<void>;
+    private tryGetAutomation;
 }
 
-export { type ConnectorRegistrySurface, ConnectorRestPlugin, type ConnectorRestPluginOptions, type RestAuth, type RestConnectorBundle, type RestConnectorOptions, type RestRequestInput, createRestConnector };
+/**
+ * The provider key this package contributes (ADR-0097). A declarative
+ * `connectors:` entry with `provider: 'rest'` is materialized by this factory.
+ */
+declare const REST_PROVIDER_KEY = "rest";
+/** Injectable dependencies for {@link createRestProviderFactory} (tests). */
+interface RestProviderDeps {
+    /** Injected fetch implementation; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Build the `rest` {@link ConnectorProviderFactory} (ADR-0097). At boot the
+ * automation service invokes it for each `provider: 'rest'` declarative instance,
+ * turning `providerConfig.baseUrl` (+ the resolved `auth`) into the same
+ * `{ def, handlers }` bundle {@link createRestConnector} produces for a
+ * hand-wired REST connector — one `request` action over static-auth HTTP.
+ *
+ * Hard-fails on invalid config (missing `baseUrl`), so a misconfigured instance
+ * fails boot loudly rather than materializing a dead connector.
+ */
+declare function createRestProviderFactory(deps?: RestProviderDeps): ConnectorProviderFactory;
+
+export { type ConnectorRegistrySurface, ConnectorRestPlugin, type ConnectorRestPluginOptions, REST_PROVIDER_KEY, type RestAuth, type RestConnectorBundle, type RestConnectorOptions, type RestProviderDeps, type RestRequestInput, createRestConnector, createRestProviderFactory };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Connector } from '@objectstack/spec/integration';
+import { Connector, ConnectorProviderFactory } from '@objectstack/spec/integration';
 import { Plugin, PluginContext } from '@objectstack/core';
 
 /**
@@ -48,20 +48,33 @@ declare function createRestConnector(opts: RestConnectorOptions): RestConnectorB
 
 /**
  * Minimal surface of the automation engine this plugin depends on — the
- * connector registry from ADR-0018 §Addendum. Kept structural so the plugin
- * needs no runtime dependency on `@objectstack/service-automation`.
+ * connector registry (ADR-0018 §Addendum) plus the provider registry (ADR-0097).
+ * Kept structural so the plugin needs no runtime dependency on
+ * `@objectstack/service-automation`.
  */
 interface ConnectorRegistrySurface {
     registerConnector(def: Connector, handlers: Record<string, (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>>): void;
     unregisterConnector(name: string): void;
+    registerConnectorProvider(providerKey: string, factory: ConnectorProviderFactory): void;
 }
-interface ConnectorRestPluginOptions extends RestConnectorOptions {
+/**
+ * Options for {@link ConnectorRestPlugin}. All optional (ADR-0097): with no
+ * `baseUrl` the plugin contributes only the `rest` provider factory — so a stack
+ * can declare `provider: 'rest'` instances as pure metadata. Supply `baseUrl`
+ * (etc.) to ALSO register a single hand-wired `rest` connector, the pre-ADR-0097
+ * usage.
+ */
+interface ConnectorRestPluginOptions extends Partial<RestConnectorOptions> {
 }
 /**
- * ConnectorRestPlugin — registers a generic REST connector on the automation
- * engine. This is the **reference concrete connector** (ADR-0018 §Addendum):
- * the dispatch node + registry are baseline; a connector like this one is a
- * plugin that populates the registry.
+ * ConnectorRestPlugin — contributes the generic REST connector (ADR-0018
+ * §Addendum) in two forms:
+ *
+ *  1. **Provider factory** (`rest`, ADR-0097): registered at `init()` so the
+ *     automation service can materialize declarative `provider: 'rest'`
+ *     `connectors:` entries into live connectors at boot.
+ *  2. **Hand-wired instance** (optional, back-compat): when constructed with a
+ *     `baseUrl`, it also registers one concrete `rest` connector at `start()`.
  *
  * If no automation engine is present the plugin logs and skips — the connector
  * has nowhere to register, which is not an error.
@@ -74,10 +87,33 @@ declare class ConnectorRestPlugin implements Plugin {
     private readonly options;
     private connectorName?;
     private automation?;
-    constructor(options: ConnectorRestPluginOptions);
-    init(_ctx: PluginContext): Promise<void>;
+    constructor(options?: ConnectorRestPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
     stop(_ctx: PluginContext): Promise<void>;
+    private tryGetAutomation;
 }
 
-export { type ConnectorRegistrySurface, ConnectorRestPlugin, type ConnectorRestPluginOptions, type RestAuth, type RestConnectorBundle, type RestConnectorOptions, type RestRequestInput, createRestConnector };
+/**
+ * The provider key this package contributes (ADR-0097). A declarative
+ * `connectors:` entry with `provider: 'rest'` is materialized by this factory.
+ */
+declare const REST_PROVIDER_KEY = "rest";
+/** Injectable dependencies for {@link createRestProviderFactory} (tests). */
+interface RestProviderDeps {
+    /** Injected fetch implementation; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Build the `rest` {@link ConnectorProviderFactory} (ADR-0097). At boot the
+ * automation service invokes it for each `provider: 'rest'` declarative instance,
+ * turning `providerConfig.baseUrl` (+ the resolved `auth`) into the same
+ * `{ def, handlers }` bundle {@link createRestConnector} produces for a
+ * hand-wired REST connector — one `request` action over static-auth HTTP.
+ *
+ * Hard-fails on invalid config (missing `baseUrl`), so a misconfigured instance
+ * fails boot loudly rather than materializing a dead connector.
+ */
+declare function createRestProviderFactory(deps?: RestProviderDeps): ConnectorProviderFactory;
+
+export { type ConnectorRegistrySurface, ConnectorRestPlugin, type ConnectorRestPluginOptions, REST_PROVIDER_KEY, type RestAuth, type RestConnectorBundle, type RestConnectorOptions, type RestProviderDeps, type RestRequestInput, createRestConnector, createRestProviderFactory };

package/dist/index.js

@@ -21,7 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ConnectorRestPlugin: () => ConnectorRestPlugin,
-  createRestConnector: () => createRestConnector
+  REST_PROVIDER_KEY: () => REST_PROVIDER_KEY,
+  createRestConnector: () => createRestConnector,
+  createRestProviderFactory: () => createRestProviderFactory
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -121,25 +123,60 @@ function createRestConnector(opts) {
   return { def, handlers: { request } };
 }
 
+// src/rest-provider.ts
+var REST_PROVIDER_KEY = "rest";
+function isStringRecord(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  return Object.values(v).every((x) => typeof x === "string");
+}
+function createRestProviderFactory(deps = {}) {
+  return (ctx) => {
+    const cfg = ctx.providerConfig ?? {};
+    if (typeof cfg.baseUrl !== "string" || cfg.baseUrl.length === 0) {
+      throw new Error(
+        `connector-rest provider: connector '${ctx.name}' requires providerConfig.baseUrl (a non-empty string, e.g. https://api.example.com).`
+      );
+    }
+    if (cfg.defaultHeaders !== void 0 && !isStringRecord(cfg.defaultHeaders)) {
+      throw new Error(
+        `connector-rest provider: connector '${ctx.name}' providerConfig.defaultHeaders must be a string\u2192string map.`
+      );
+    }
+    const auth = ctx.auth;
+    return createRestConnector({
+      name: ctx.name,
+      label: ctx.label,
+      baseUrl: cfg.baseUrl,
+      auth,
+      defaultHeaders: isStringRecord(cfg.defaultHeaders) ? cfg.defaultHeaders : void 0,
+      fetchImpl: deps.fetchImpl
+    });
+  };
+}
+
 // src/connector-rest-plugin.ts
 var ConnectorRestPlugin = class {
-  constructor(options) {
+  constructor(options = {}) {
     this.name = "com.objectstack.connector.rest";
     this.version = "1.0.0";
     this.type = "standard";
-    // Ensure the automation engine (and its connector registry) is started first.
+    // Ensure the automation engine (and its connector/provider registries) exist first.
     this.dependencies = ["com.objectstack.service-automation"];
     this.options = options;
   }
-  async init(_ctx) {
+  async init(ctx) {
+    const automation = this.tryGetAutomation(ctx);
+    if (automation && typeof automation.registerConnectorProvider === "function") {
+      automation.registerConnectorProvider(
+        REST_PROVIDER_KEY,
+        createRestProviderFactory({ fetchImpl: this.options.fetchImpl })
+      );
+      ctx.logger.info("ConnectorRestPlugin: registered 'rest' connector provider");
+    }
   }
   async start(ctx) {
-    let automation;
-    try {
-      automation = ctx.getService("automation");
-    } catch {
-      automation = void 0;
-    }
+    if (!this.options.baseUrl) return;
+    const automation = this.tryGetAutomation(ctx);
     if (!automation || typeof automation.registerConnector !== "function") {
       ctx.logger.info("ConnectorRestPlugin: no automation engine \u2014 REST connector not registered");
       return;
@@ -158,10 +195,19 @@ var ConnectorRestPlugin = class {
       }
     }
   }
+  tryGetAutomation(ctx) {
+    try {
+      return ctx.getService("automation");
+    } catch {
+      return void 0;
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConnectorRestPlugin,
-  createRestConnector
+  REST_PROVIDER_KEY,
+  createRestConnector,
+  createRestProviderFactory
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/rest-connector.ts","../src/connector-rest-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * @objectstack/connector-rest\n *\n * Generic REST connector — the reference *concrete* connector (ADR-0018\n * §Addendum). The baseline automation engine ships the `connector_action`\n * dispatch node + an empty connector registry; this plugin populates the\n * registry with a `rest` connector exposing a `request` action.\n *\n * Static auth only (`none` / `api-key` / `basic` / `bearer`); OAuth2 refresh,\n * credential vaulting, and multi-tenant lifecycle are the enterprise tier.\n */\n\nexport {\n    createRestConnector,\n    type RestConnectorOptions,\n    type RestConnectorBundle,\n    type RestRequestInput,\n    type RestAuth,\n} from './rest-connector.js';\nexport {\n    ConnectorRestPlugin,\n    type ConnectorRestPluginOptions,\n    type ConnectorRegistrySurface,\n} from './connector-rest-plugin.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Connector } from '@objectstack/spec/integration';\nimport { resilientFetch } from '@objectstack/spec/shared';\n\n/**\n * Generic REST connector — the reference *concrete* connector (ADR-0018\n * §Addendum). It produces a {@link Connector} definition plus the handler for\n * its one action, `request`, which the baseline `connector_action` node\n * dispatches to.\n *\n * Open-source scope: **static** auth only (`none` / `api-key` / `basic` /\n * `bearer`), with credentials supplied by the caller. OAuth2 token acquisition\n * and refresh, credential vaulting, and multi-tenant connection lifecycle are\n * the enterprise tier (see `../cloud/docs/design/connector-tiering.md`) and are\n * deliberately out of scope here.\n */\n\n/** Auth config understood by the REST connector (the static subset). */\nexport type RestAuth = Extract<\n    Connector['authentication'],\n    { type: 'none' | 'api-key' | 'basic' | 'bearer' }\n>;\n\nexport interface RestConnectorOptions {\n    /** Connector machine name (snake_case). Defaults to `rest`. */\n    name?: string;\n    /** Human-readable label. Defaults to a title derived from `name`. */\n    label?: string;\n    /** Base URL prepended to each request's `path` (e.g. `https://api.example.com`). */\n    baseUrl: string;\n    /** Static authentication. Defaults to `{ type: 'none' }`. */\n    auth?: RestAuth;\n    /** Headers merged into every request (request-level headers win). */\n    defaultHeaders?: Record<string, string>;\n    /** Injected for tests; defaults to the global `fetch`. */\n    fetchImpl?: typeof fetch;\n}\n\n/** Input accepted by the `request` action. */\nexport interface RestRequestInput {\n    method?: string;\n    path?: string;\n    headers?: Record<string, string>;\n    query?: Record<string, string | number | boolean | null | undefined>;\n    body?: unknown;\n}\n\n/** A connector definition paired with its action handlers, ready for registerConnector(). */\nexport interface RestConnectorBundle {\n    def: Connector;\n    handlers: Record<\n        string,\n        (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>\n    >;\n}\n\n/** Build the request URL from base + path + query, encoding query params. */\nfunction buildUrl(baseUrl: string, path: string, query?: RestRequestInput['query']): string {\n    const base = baseUrl.replace(/\\/+$/, '');\n    const suffix = path ? (path.startsWith('/') ? path : `/${path}`) : '';\n    const url = new URL(base + suffix);\n    if (query) {\n        for (const [key, value] of Object.entries(query)) {\n            if (value !== undefined && value !== null) url.searchParams.set(key, String(value));\n        }\n    }\n    return url.toString();\n}\n\n/**\n * Apply static auth to the outgoing headers / query. Returns possibly-extended\n * query so an `api-key` configured with `paramName` can ride the query string.\n */\nfunction applyAuth(\n    auth: RestAuth,\n    headers: Record<string, string>,\n    query: Record<string, string | number | boolean | null | undefined>,\n): 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\nexport function createRestConnector(opts: RestConnectorOptions): RestConnectorBundle {\n    const name = opts.name ?? 'rest';\n    const auth: RestAuth = opts.auth ?? { type: 'none' };\n\n    const def: Connector = {\n        name,\n        label: opts.label ?? 'REST Connector',\n        type: 'api',\n        description: 'Generic REST/HTTP connector with static authentication.',\n        icon: 'globe',\n        authentication: auth,\n        // Defaulted by ConnectorSchema; set explicitly so the literal satisfies\n        // the (post-parse) Connector output type.\n        status: 'active',\n        enabled: true,\n        connectionTimeoutMs: 30000,\n        requestTimeoutMs: 30000,\n        actions: [\n            {\n                key: 'request',\n                label: 'HTTP Request',\n                description: 'Send an HTTP request to the connector\\'s base URL with static auth applied.',\n                inputSchema: {\n                    type: 'object',\n                    properties: {\n                        method: { type: 'string', description: 'HTTP method (default GET)' },\n                        path: { type: 'string', description: 'Path appended to the base URL' },\n                        headers: { type: 'object', description: 'Per-request headers' },\n                        query: { type: 'object', description: 'Query parameters' },\n                        body: { description: 'Request body (JSON-encoded for non-GET)' },\n                    },\n                },\n                outputSchema: {\n                    type: 'object',\n                    properties: {\n                        status: { type: 'number' },\n                        ok: { type: 'boolean' },\n                        body: {},\n                    },\n                },\n            },\n        ],\n    };\n\n    async function request(input: Record<string, unknown>): Promise<Record<string, unknown>> {\n        const req = input as RestRequestInput;\n        const method = (req.method ?? 'GET').toUpperCase();\n        const headers: Record<string, string> = { ...opts.defaultHeaders, ...req.headers };\n        const query: Record<string, string | number | boolean | null | undefined> = { ...req.query };\n\n        applyAuth(auth, headers, query);\n\n        const url = buildUrl(opts.baseUrl, req.path ?? '', query);\n\n        const hasBody = req.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 resilientFetch(url, {\n            method,\n            headers,\n            body: hasBody ? JSON.stringify(req.body) : undefined,\n        }, { fetchImpl: opts.fetchImpl });\n\n        // Parse JSON when advertised; fall back to text so non-JSON endpoints\n        // don't throw.\n        const contentType = response.headers.get('content-type') ?? '';\n        const parsed = contentType.includes('application/json')\n            ? await response.json()\n            : await response.text();\n\n        return { status: response.status, ok: response.ok, body: parsed };\n    }\n\n    return { def, handlers: { request } };\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { Connector } from '@objectstack/spec/integration';\nimport { createRestConnector, type RestConnectorOptions } from './rest-connector.js';\n\n/**\n * Minimal surface of the automation engine this plugin depends on — the\n * connector registry from ADR-0018 §Addendum. Kept structural so the plugin\n * needs no runtime dependency on `@objectstack/service-automation`.\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\nexport interface ConnectorRestPluginOptions extends RestConnectorOptions {}\n\n/**\n * ConnectorRestPlugin — registers a generic REST connector on the automation\n * engine. This is the **reference concrete connector** (ADR-0018 §Addendum):\n * the dispatch node + registry are baseline; a connector like this one is a\n * plugin that populates the registry.\n *\n * If no automation engine is present the plugin logs and skips — the connector\n * has nowhere to register, which is not an error.\n */\nexport class ConnectorRestPlugin implements Plugin {\n    name = 'com.objectstack.connector.rest';\n    version = '1.0.0';\n    type = 'standard' as const;\n    // Ensure the automation engine (and its connector registry) is started first.\n    dependencies = ['com.objectstack.service-automation'];\n\n    private readonly options: ConnectorRestPluginOptions;\n    private connectorName?: string;\n    private automation?: ConnectorRegistrySurface;\n\n    constructor(options: ConnectorRestPluginOptions) {\n        this.options = options;\n    }\n\n    async init(_ctx: PluginContext): Promise<void> {\n        // No services to register; the connector is registered in start() once\n        // the automation engine is available.\n    }\n\n    async start(ctx: PluginContext): Promise<void> {\n        let automation: ConnectorRegistrySurface | undefined;\n        try {\n            automation = ctx.getService<ConnectorRegistrySurface>('automation');\n        } catch {\n            automation = undefined;\n        }\n\n        if (!automation || typeof automation.registerConnector !== 'function') {\n            ctx.logger.info('ConnectorRestPlugin: no automation engine — REST connector not registered');\n            return;\n        }\n\n        const { def, handlers } = createRestConnector(this.options);\n        automation.registerConnector(def, handlers);\n        this.automation = automation;\n        this.connectorName = def.name;\n        ctx.logger.info(`ConnectorRestPlugin: REST connector '${def.name}' registered`);\n    }\n\n    async stop(_ctx: PluginContext): Promise<void> {\n        if (this.automation && this.connectorName) {\n            try { this.automation.unregisterConnector(this.connectorName); } catch { /* ignore */ }\n        }\n    }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/rest-connector.ts","../src/rest-provider.ts","../src/connector-rest-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * @objectstack/connector-rest\n *\n * Generic REST connector — the reference *concrete* connector (ADR-0018\n * §Addendum). The baseline automation engine ships the `connector_action`\n * dispatch node + an empty connector registry; this plugin populates the\n * registry with a `rest` connector exposing a `request` action.\n *\n * Static auth only (`none` / `api-key` / `basic` / `bearer`); OAuth2 refresh,\n * credential vaulting, and multi-tenant lifecycle are the enterprise tier.\n */\n\nexport {\n    createRestConnector,\n    type RestConnectorOptions,\n    type RestConnectorBundle,\n    type RestRequestInput,\n    type RestAuth,\n} from './rest-connector.js';\nexport {\n    ConnectorRestPlugin,\n    type ConnectorRestPluginOptions,\n    type ConnectorRegistrySurface,\n} from './connector-rest-plugin.js';\nexport {\n    createRestProviderFactory,\n    REST_PROVIDER_KEY,\n    type RestProviderDeps,\n} from './rest-provider.js';\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Connector } from '@objectstack/spec/integration';\nimport { resilientFetch } from '@objectstack/spec/shared';\n\n/**\n * Generic REST connector — the reference *concrete* connector (ADR-0018\n * §Addendum). It produces a {@link Connector} definition plus the handler for\n * its one action, `request`, which the baseline `connector_action` node\n * dispatches to.\n *\n * Open-source scope: **static** auth only (`none` / `api-key` / `basic` /\n * `bearer`), with credentials supplied by the caller. OAuth2 token acquisition\n * and refresh, credential vaulting, and multi-tenant connection lifecycle are\n * the enterprise tier (see `../cloud/docs/design/connector-tiering.md`) and are\n * deliberately out of scope here.\n */\n\n/** Auth config understood by the REST connector (the static subset). */\nexport type RestAuth = Extract<\n    Connector['authentication'],\n    { type: 'none' | 'api-key' | 'basic' | 'bearer' }\n>;\n\nexport interface RestConnectorOptions {\n    /** Connector machine name (snake_case). Defaults to `rest`. */\n    name?: string;\n    /** Human-readable label. Defaults to a title derived from `name`. */\n    label?: string;\n    /** Base URL prepended to each request's `path` (e.g. `https://api.example.com`). */\n    baseUrl: string;\n    /** Static authentication. Defaults to `{ type: 'none' }`. */\n    auth?: RestAuth;\n    /** Headers merged into every request (request-level headers win). */\n    defaultHeaders?: Record<string, string>;\n    /** Injected for tests; defaults to the global `fetch`. */\n    fetchImpl?: typeof fetch;\n}\n\n/** Input accepted by the `request` action. */\nexport interface RestRequestInput {\n    method?: string;\n    path?: string;\n    headers?: Record<string, string>;\n    query?: Record<string, string | number | boolean | null | undefined>;\n    body?: unknown;\n}\n\n/** A connector definition paired with its action handlers, ready for registerConnector(). */\nexport interface RestConnectorBundle {\n    def: Connector;\n    handlers: Record<\n        string,\n        (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>\n    >;\n}\n\n/** Build the request URL from base + path + query, encoding query params. */\nfunction buildUrl(baseUrl: string, path: string, query?: RestRequestInput['query']): string {\n    const base = baseUrl.replace(/\\/+$/, '');\n    const suffix = path ? (path.startsWith('/') ? path : `/${path}`) : '';\n    const url = new URL(base + suffix);\n    if (query) {\n        for (const [key, value] of Object.entries(query)) {\n            if (value !== undefined && value !== null) url.searchParams.set(key, String(value));\n        }\n    }\n    return url.toString();\n}\n\n/**\n * Apply static auth to the outgoing headers / query. Returns possibly-extended\n * query so an `api-key` configured with `paramName` can ride the query string.\n */\nfunction applyAuth(\n    auth: RestAuth,\n    headers: Record<string, string>,\n    query: Record<string, string | number | boolean | null | undefined>,\n): 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\nexport function createRestConnector(opts: RestConnectorOptions): RestConnectorBundle {\n    const name = opts.name ?? 'rest';\n    const auth: RestAuth = opts.auth ?? { type: 'none' };\n\n    const def: Connector = {\n        name,\n        label: opts.label ?? 'REST Connector',\n        type: 'api',\n        description: 'Generic REST/HTTP connector with static authentication.',\n        icon: 'globe',\n        authentication: auth,\n        // Defaulted by ConnectorSchema; set explicitly so the literal satisfies\n        // the (post-parse) Connector output type.\n        status: 'active',\n        enabled: true,\n        connectionTimeoutMs: 30000,\n        requestTimeoutMs: 30000,\n        actions: [\n            {\n                key: 'request',\n                label: 'HTTP Request',\n                description: 'Send an HTTP request to the connector\\'s base URL with static auth applied.',\n                inputSchema: {\n                    type: 'object',\n                    properties: {\n                        method: { type: 'string', description: 'HTTP method (default GET)' },\n                        path: { type: 'string', description: 'Path appended to the base URL' },\n                        headers: { type: 'object', description: 'Per-request headers' },\n                        query: { type: 'object', description: 'Query parameters' },\n                        body: { description: 'Request body (JSON-encoded for non-GET)' },\n                    },\n                },\n                outputSchema: {\n                    type: 'object',\n                    properties: {\n                        status: { type: 'number' },\n                        ok: { type: 'boolean' },\n                        body: {},\n                    },\n                },\n            },\n        ],\n    };\n\n    async function request(input: Record<string, unknown>): Promise<Record<string, unknown>> {\n        const req = input as RestRequestInput;\n        const method = (req.method ?? 'GET').toUpperCase();\n        const headers: Record<string, string> = { ...opts.defaultHeaders, ...req.headers };\n        const query: Record<string, string | number | boolean | null | undefined> = { ...req.query };\n\n        applyAuth(auth, headers, query);\n\n        const url = buildUrl(opts.baseUrl, req.path ?? '', query);\n\n        const hasBody = req.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 resilientFetch(url, {\n            method,\n            headers,\n            body: hasBody ? JSON.stringify(req.body) : undefined,\n        }, { fetchImpl: opts.fetchImpl });\n\n        // Parse JSON when advertised; fall back to text so non-JSON endpoints\n        // don't throw.\n        const contentType = response.headers.get('content-type') ?? '';\n        const parsed = contentType.includes('application/json')\n            ? await response.json()\n            : await response.text();\n\n        return { status: response.status, ok: response.ok, body: parsed };\n    }\n\n    return { def, handlers: { request } };\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { ConnectorProviderFactory, ResolvedConnectorAuth } from '@objectstack/spec/integration';\nimport { createRestConnector, type RestAuth } from './rest-connector.js';\n\n/**\n * The provider key this package contributes (ADR-0097). A declarative\n * `connectors:` entry with `provider: 'rest'` is materialized by this factory.\n */\nexport const REST_PROVIDER_KEY = 'rest';\n\n/** Injectable dependencies for {@link createRestProviderFactory} (tests). */\nexport interface RestProviderDeps {\n  /** Injected fetch implementation; defaults to the global `fetch`. */\n  fetchImpl?: typeof fetch;\n}\n\n/** Shape of `providerConfig` for a `provider: 'rest'` declarative instance. */\ninterface RestProviderConfig {\n  baseUrl?: unknown;\n  defaultHeaders?: unknown;\n}\n\nfunction isStringRecord(v: unknown): v is Record<string, string> {\n  if (!v || typeof v !== 'object' || Array.isArray(v)) return false;\n  return Object.values(v as Record<string, unknown>).every((x) => typeof x === 'string');\n}\n\n/**\n * Build the `rest` {@link ConnectorProviderFactory} (ADR-0097). At boot the\n * automation service invokes it for each `provider: 'rest'` declarative instance,\n * turning `providerConfig.baseUrl` (+ the resolved `auth`) into the same\n * `{ def, handlers }` bundle {@link createRestConnector} produces for a\n * hand-wired REST connector — one `request` action over static-auth HTTP.\n *\n * Hard-fails on invalid config (missing `baseUrl`), so a misconfigured instance\n * fails boot loudly rather than materializing a dead connector.\n */\nexport function createRestProviderFactory(deps: RestProviderDeps = {}): ConnectorProviderFactory {\n  return (ctx) => {\n    const cfg = (ctx.providerConfig ?? {}) as RestProviderConfig;\n    if (typeof cfg.baseUrl !== 'string' || cfg.baseUrl.length === 0) {\n      throw new Error(\n        `connector-rest provider: connector '${ctx.name}' requires providerConfig.baseUrl (a non-empty string, e.g. https://api.example.com).`,\n      );\n    }\n    if (cfg.defaultHeaders !== undefined && !isStringRecord(cfg.defaultHeaders)) {\n      throw new Error(\n        `connector-rest provider: connector '${ctx.name}' providerConfig.defaultHeaders must be a string→string map.`,\n      );\n    }\n    // `ResolvedConnectorAuth` is exactly the static-auth subset RestAuth expects\n    // (the credentialRef has already been resolved to a secret upstream).\n    const auth = ctx.auth as ResolvedConnectorAuth | undefined as RestAuth | undefined;\n    return createRestConnector({\n      name: ctx.name,\n      label: ctx.label,\n      baseUrl: cfg.baseUrl,\n      auth,\n      defaultHeaders: isStringRecord(cfg.defaultHeaders) ? cfg.defaultHeaders : undefined,\n      fetchImpl: deps.fetchImpl,\n    });\n  };\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { Connector, ConnectorProviderFactory } from '@objectstack/spec/integration';\nimport { createRestConnector, type RestConnectorOptions } from './rest-connector.js';\nimport { createRestProviderFactory, REST_PROVIDER_KEY } from './rest-provider.js';\n\n/**\n * Minimal surface of the automation engine this plugin depends on — the\n * connector registry (ADR-0018 §Addendum) plus the provider registry (ADR-0097).\n * Kept structural so the plugin needs no runtime dependency on\n * `@objectstack/service-automation`.\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    registerConnectorProvider(providerKey: string, factory: ConnectorProviderFactory): void;\n}\n\n/**\n * Options for {@link ConnectorRestPlugin}. All optional (ADR-0097): with no\n * `baseUrl` the plugin contributes only the `rest` provider factory — so a stack\n * can declare `provider: 'rest'` instances as pure metadata. Supply `baseUrl`\n * (etc.) to ALSO register a single hand-wired `rest` connector, the pre-ADR-0097\n * usage.\n */\nexport interface ConnectorRestPluginOptions extends Partial<RestConnectorOptions> {}\n\n/**\n * ConnectorRestPlugin — contributes the generic REST connector (ADR-0018\n * §Addendum) in two forms:\n *\n *  1. **Provider factory** (`rest`, ADR-0097): registered at `init()` so the\n *     automation service can materialize declarative `provider: 'rest'`\n *     `connectors:` entries into live connectors at boot.\n *  2. **Hand-wired instance** (optional, back-compat): when constructed with a\n *     `baseUrl`, it also registers one concrete `rest` connector at `start()`.\n *\n * If no automation engine is present the plugin logs and skips — the connector\n * has nowhere to register, which is not an error.\n */\nexport class ConnectorRestPlugin implements Plugin {\n    name = 'com.objectstack.connector.rest';\n    version = '1.0.0';\n    type = 'standard' as const;\n    // Ensure the automation engine (and its connector/provider registries) exist first.\n    dependencies = ['com.objectstack.service-automation'];\n\n    private readonly options: ConnectorRestPluginOptions;\n    private connectorName?: string;\n    private automation?: ConnectorRegistrySurface;\n\n    constructor(options: ConnectorRestPluginOptions = {}) {\n        this.options = options;\n    }\n\n    async init(ctx: PluginContext): Promise<void> {\n        // Contribute the `rest` provider factory (ADR-0097). Done in init() — not\n        // start() — so it is registered before the automation service materializes\n        // declarative instances during its own start().\n        const automation = this.tryGetAutomation(ctx);\n        if (automation && typeof automation.registerConnectorProvider === 'function') {\n            automation.registerConnectorProvider(\n                REST_PROVIDER_KEY,\n                createRestProviderFactory({ fetchImpl: this.options.fetchImpl }),\n            );\n            ctx.logger.info(\"ConnectorRestPlugin: registered 'rest' connector provider\");\n        }\n    }\n\n    async start(ctx: PluginContext): Promise<void> {\n        // Only register a concrete connector when a baseUrl was supplied — the\n        // provider-only usage (no options) contributes just the factory in init().\n        if (!this.options.baseUrl) return;\n\n        const automation = this.tryGetAutomation(ctx);\n        if (!automation || typeof automation.registerConnector !== 'function') {\n            ctx.logger.info('ConnectorRestPlugin: no automation engine — REST connector not registered');\n            return;\n        }\n\n        const { def, handlers } = createRestConnector(this.options as RestConnectorOptions);\n        automation.registerConnector(def, handlers);\n        this.automation = automation;\n        this.connectorName = def.name;\n        ctx.logger.info(`ConnectorRestPlugin: REST connector '${def.name}' registered`);\n    }\n\n    async stop(_ctx: PluginContext): Promise<void> {\n        if (this.automation && this.connectorName) {\n            try { this.automation.unregisterConnector(this.connectorName); } catch { /* ignore */ }\n        }\n    }\n\n    private tryGetAutomation(ctx: PluginContext): ConnectorRegistrySurface | undefined {\n        try {\n            return ctx.getService<ConnectorRegistrySurface>('automation');\n        } catch {\n            return undefined;\n        }\n    }\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -94,25 +94,60 @@ function createRestConnector(opts) {
   return { def, handlers: { request } };
 }
 
+// src/rest-provider.ts
+var REST_PROVIDER_KEY = "rest";
+function isStringRecord(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  return Object.values(v).every((x) => typeof x === "string");
+}
+function createRestProviderFactory(deps = {}) {
+  return (ctx) => {
+    const cfg = ctx.providerConfig ?? {};
+    if (typeof cfg.baseUrl !== "string" || cfg.baseUrl.length === 0) {
+      throw new Error(
+        `connector-rest provider: connector '${ctx.name}' requires providerConfig.baseUrl (a non-empty string, e.g. https://api.example.com).`
+      );
+    }
+    if (cfg.defaultHeaders !== void 0 && !isStringRecord(cfg.defaultHeaders)) {
+      throw new Error(
+        `connector-rest provider: connector '${ctx.name}' providerConfig.defaultHeaders must be a string\u2192string map.`
+      );
+    }
+    const auth = ctx.auth;
+    return createRestConnector({
+      name: ctx.name,
+      label: ctx.label,
+      baseUrl: cfg.baseUrl,
+      auth,
+      defaultHeaders: isStringRecord(cfg.defaultHeaders) ? cfg.defaultHeaders : void 0,
+      fetchImpl: deps.fetchImpl
+    });
+  };
+}
+
 // src/connector-rest-plugin.ts
 var ConnectorRestPlugin = class {
-  constructor(options) {
+  constructor(options = {}) {
     this.name = "com.objectstack.connector.rest";
     this.version = "1.0.0";
     this.type = "standard";
-    // Ensure the automation engine (and its connector registry) is started first.
+    // Ensure the automation engine (and its connector/provider registries) exist first.
     this.dependencies = ["com.objectstack.service-automation"];
     this.options = options;
   }
-  async init(_ctx) {
+  async init(ctx) {
+    const automation = this.tryGetAutomation(ctx);
+    if (automation && typeof automation.registerConnectorProvider === "function") {
+      automation.registerConnectorProvider(
+        REST_PROVIDER_KEY,
+        createRestProviderFactory({ fetchImpl: this.options.fetchImpl })
+      );
+      ctx.logger.info("ConnectorRestPlugin: registered 'rest' connector provider");
+    }
   }
   async start(ctx) {
-    let automation;
-    try {
-      automation = ctx.getService("automation");
-    } catch {
-      automation = void 0;
-    }
+    if (!this.options.baseUrl) return;
+    const automation = this.tryGetAutomation(ctx);
     if (!automation || typeof automation.registerConnector !== "function") {
       ctx.logger.info("ConnectorRestPlugin: no automation engine \u2014 REST connector not registered");
       return;
@@ -131,9 +166,18 @@ var ConnectorRestPlugin = class {
       }
     }
   }
+  tryGetAutomation(ctx) {
+    try {
+      return ctx.getService("automation");
+    } catch {
+      return void 0;
+    }
+  }
 };
 export {
   ConnectorRestPlugin,
-  createRestConnector
+  REST_PROVIDER_KEY,
+  createRestConnector,
+  createRestProviderFactory
 };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/rest-connector.ts","../src/connector-rest-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Connector } from '@objectstack/spec/integration';\nimport { resilientFetch } from '@objectstack/spec/shared';\n\n/**\n * Generic REST connector — the reference *concrete* connector (ADR-0018\n * §Addendum). It produces a {@link Connector} definition plus the handler for\n * its one action, `request`, which the baseline `connector_action` node\n * dispatches to.\n *\n * Open-source scope: **static** auth only (`none` / `api-key` / `basic` /\n * `bearer`), with credentials supplied by the caller. OAuth2 token acquisition\n * and refresh, credential vaulting, and multi-tenant connection lifecycle are\n * the enterprise tier (see `../cloud/docs/design/connector-tiering.md`) and are\n * deliberately out of scope here.\n */\n\n/** Auth config understood by the REST connector (the static subset). */\nexport type RestAuth = Extract<\n    Connector['authentication'],\n    { type: 'none' | 'api-key' | 'basic' | 'bearer' }\n>;\n\nexport interface RestConnectorOptions {\n    /** Connector machine name (snake_case). Defaults to `rest`. */\n    name?: string;\n    /** Human-readable label. Defaults to a title derived from `name`. */\n    label?: string;\n    /** Base URL prepended to each request's `path` (e.g. `https://api.example.com`). */\n    baseUrl: string;\n    /** Static authentication. Defaults to `{ type: 'none' }`. */\n    auth?: RestAuth;\n    /** Headers merged into every request (request-level headers win). */\n    defaultHeaders?: Record<string, string>;\n    /** Injected for tests; defaults to the global `fetch`. */\n    fetchImpl?: typeof fetch;\n}\n\n/** Input accepted by the `request` action. */\nexport interface RestRequestInput {\n    method?: string;\n    path?: string;\n    headers?: Record<string, string>;\n    query?: Record<string, string | number | boolean | null | undefined>;\n    body?: unknown;\n}\n\n/** A connector definition paired with its action handlers, ready for registerConnector(). */\nexport interface RestConnectorBundle {\n    def: Connector;\n    handlers: Record<\n        string,\n        (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>\n    >;\n}\n\n/** Build the request URL from base + path + query, encoding query params. */\nfunction buildUrl(baseUrl: string, path: string, query?: RestRequestInput['query']): string {\n    const base = baseUrl.replace(/\\/+$/, '');\n    const suffix = path ? (path.startsWith('/') ? path : `/${path}`) : '';\n    const url = new URL(base + suffix);\n    if (query) {\n        for (const [key, value] of Object.entries(query)) {\n            if (value !== undefined && value !== null) url.searchParams.set(key, String(value));\n        }\n    }\n    return url.toString();\n}\n\n/**\n * Apply static auth to the outgoing headers / query. Returns possibly-extended\n * query so an `api-key` configured with `paramName` can ride the query string.\n */\nfunction applyAuth(\n    auth: RestAuth,\n    headers: Record<string, string>,\n    query: Record<string, string | number | boolean | null | undefined>,\n): 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\nexport function createRestConnector(opts: RestConnectorOptions): RestConnectorBundle {\n    const name = opts.name ?? 'rest';\n    const auth: RestAuth = opts.auth ?? { type: 'none' };\n\n    const def: Connector = {\n        name,\n        label: opts.label ?? 'REST Connector',\n        type: 'api',\n        description: 'Generic REST/HTTP connector with static authentication.',\n        icon: 'globe',\n        authentication: auth,\n        // Defaulted by ConnectorSchema; set explicitly so the literal satisfies\n        // the (post-parse) Connector output type.\n        status: 'active',\n        enabled: true,\n        connectionTimeoutMs: 30000,\n        requestTimeoutMs: 30000,\n        actions: [\n            {\n                key: 'request',\n                label: 'HTTP Request',\n                description: 'Send an HTTP request to the connector\\'s base URL with static auth applied.',\n                inputSchema: {\n                    type: 'object',\n                    properties: {\n                        method: { type: 'string', description: 'HTTP method (default GET)' },\n                        path: { type: 'string', description: 'Path appended to the base URL' },\n                        headers: { type: 'object', description: 'Per-request headers' },\n                        query: { type: 'object', description: 'Query parameters' },\n                        body: { description: 'Request body (JSON-encoded for non-GET)' },\n                    },\n                },\n                outputSchema: {\n                    type: 'object',\n                    properties: {\n                        status: { type: 'number' },\n                        ok: { type: 'boolean' },\n                        body: {},\n                    },\n                },\n            },\n        ],\n    };\n\n    async function request(input: Record<string, unknown>): Promise<Record<string, unknown>> {\n        const req = input as RestRequestInput;\n        const method = (req.method ?? 'GET').toUpperCase();\n        const headers: Record<string, string> = { ...opts.defaultHeaders, ...req.headers };\n        const query: Record<string, string | number | boolean | null | undefined> = { ...req.query };\n\n        applyAuth(auth, headers, query);\n\n        const url = buildUrl(opts.baseUrl, req.path ?? '', query);\n\n        const hasBody = req.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 resilientFetch(url, {\n            method,\n            headers,\n            body: hasBody ? JSON.stringify(req.body) : undefined,\n        }, { fetchImpl: opts.fetchImpl });\n\n        // Parse JSON when advertised; fall back to text so non-JSON endpoints\n        // don't throw.\n        const contentType = response.headers.get('content-type') ?? '';\n        const parsed = contentType.includes('application/json')\n            ? await response.json()\n            : await response.text();\n\n        return { status: response.status, ok: response.ok, body: parsed };\n    }\n\n    return { def, handlers: { request } };\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { Connector } from '@objectstack/spec/integration';\nimport { createRestConnector, type RestConnectorOptions } from './rest-connector.js';\n\n/**\n * Minimal surface of the automation engine this plugin depends on — the\n * connector registry from ADR-0018 §Addendum. Kept structural so the plugin\n * needs no runtime dependency on `@objectstack/service-automation`.\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\nexport interface ConnectorRestPluginOptions extends RestConnectorOptions {}\n\n/**\n * ConnectorRestPlugin — registers a generic REST connector on the automation\n * engine. This is the **reference concrete connector** (ADR-0018 §Addendum):\n * the dispatch node + registry are baseline; a connector like this one is a\n * plugin that populates the registry.\n *\n * If no automation engine is present the plugin logs and skips — the connector\n * has nowhere to register, which is not an error.\n */\nexport class ConnectorRestPlugin implements Plugin {\n    name = 'com.objectstack.connector.rest';\n    version = '1.0.0';\n    type = 'standard' as const;\n    // Ensure the automation engine (and its connector registry) is started first.\n    dependencies = ['com.objectstack.service-automation'];\n\n    private readonly options: ConnectorRestPluginOptions;\n    private connectorName?: string;\n    private automation?: ConnectorRegistrySurface;\n\n    constructor(options: ConnectorRestPluginOptions) {\n        this.options = options;\n    }\n\n    async init(_ctx: PluginContext): Promise<void> {\n        // No services to register; the connector is registered in start() once\n        // the automation engine is available.\n    }\n\n    async start(ctx: PluginContext): Promise<void> {\n        let automation: ConnectorRegistrySurface | undefined;\n        try {\n            automation = ctx.getService<ConnectorRegistrySurface>('automation');\n        } catch {\n            automation = undefined;\n        }\n\n        if (!automation || typeof automation.registerConnector !== 'function') {\n            ctx.logger.info('ConnectorRestPlugin: no automation engine — REST connector not registered');\n            return;\n        }\n\n        const { def, handlers } = createRestConnector(this.options);\n        automation.registerConnector(def, handlers);\n        this.automation = automation;\n        this.connectorName = def.name;\n        ctx.logger.info(`ConnectorRestPlugin: REST connector '${def.name}' registered`);\n    }\n\n    async stop(_ctx: PluginContext): Promise<void> {\n        if (this.automation && this.connectorName) {\n            try { this.automation.unregisterConnector(this.connectorName); } catch { /* ignore */ }\n        }\n    }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/rest-connector.ts","../src/rest-provider.ts","../src/connector-rest-plugin.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Connector } from '@objectstack/spec/integration';\nimport { resilientFetch } from '@objectstack/spec/shared';\n\n/**\n * Generic REST connector — the reference *concrete* connector (ADR-0018\n * §Addendum). It produces a {@link Connector} definition plus the handler for\n * its one action, `request`, which the baseline `connector_action` node\n * dispatches to.\n *\n * Open-source scope: **static** auth only (`none` / `api-key` / `basic` /\n * `bearer`), with credentials supplied by the caller. OAuth2 token acquisition\n * and refresh, credential vaulting, and multi-tenant connection lifecycle are\n * the enterprise tier (see `../cloud/docs/design/connector-tiering.md`) and are\n * deliberately out of scope here.\n */\n\n/** Auth config understood by the REST connector (the static subset). */\nexport type RestAuth = Extract<\n    Connector['authentication'],\n    { type: 'none' | 'api-key' | 'basic' | 'bearer' }\n>;\n\nexport interface RestConnectorOptions {\n    /** Connector machine name (snake_case). Defaults to `rest`. */\n    name?: string;\n    /** Human-readable label. Defaults to a title derived from `name`. */\n    label?: string;\n    /** Base URL prepended to each request's `path` (e.g. `https://api.example.com`). */\n    baseUrl: string;\n    /** Static authentication. Defaults to `{ type: 'none' }`. */\n    auth?: RestAuth;\n    /** Headers merged into every request (request-level headers win). */\n    defaultHeaders?: Record<string, string>;\n    /** Injected for tests; defaults to the global `fetch`. */\n    fetchImpl?: typeof fetch;\n}\n\n/** Input accepted by the `request` action. */\nexport interface RestRequestInput {\n    method?: string;\n    path?: string;\n    headers?: Record<string, string>;\n    query?: Record<string, string | number | boolean | null | undefined>;\n    body?: unknown;\n}\n\n/** A connector definition paired with its action handlers, ready for registerConnector(). */\nexport interface RestConnectorBundle {\n    def: Connector;\n    handlers: Record<\n        string,\n        (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>\n    >;\n}\n\n/** Build the request URL from base + path + query, encoding query params. */\nfunction buildUrl(baseUrl: string, path: string, query?: RestRequestInput['query']): string {\n    const base = baseUrl.replace(/\\/+$/, '');\n    const suffix = path ? (path.startsWith('/') ? path : `/${path}`) : '';\n    const url = new URL(base + suffix);\n    if (query) {\n        for (const [key, value] of Object.entries(query)) {\n            if (value !== undefined && value !== null) url.searchParams.set(key, String(value));\n        }\n    }\n    return url.toString();\n}\n\n/**\n * Apply static auth to the outgoing headers / query. Returns possibly-extended\n * query so an `api-key` configured with `paramName` can ride the query string.\n */\nfunction applyAuth(\n    auth: RestAuth,\n    headers: Record<string, string>,\n    query: Record<string, string | number | boolean | null | undefined>,\n): 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\nexport function createRestConnector(opts: RestConnectorOptions): RestConnectorBundle {\n    const name = opts.name ?? 'rest';\n    const auth: RestAuth = opts.auth ?? { type: 'none' };\n\n    const def: Connector = {\n        name,\n        label: opts.label ?? 'REST Connector',\n        type: 'api',\n        description: 'Generic REST/HTTP connector with static authentication.',\n        icon: 'globe',\n        authentication: auth,\n        // Defaulted by ConnectorSchema; set explicitly so the literal satisfies\n        // the (post-parse) Connector output type.\n        status: 'active',\n        enabled: true,\n        connectionTimeoutMs: 30000,\n        requestTimeoutMs: 30000,\n        actions: [\n            {\n                key: 'request',\n                label: 'HTTP Request',\n                description: 'Send an HTTP request to the connector\\'s base URL with static auth applied.',\n                inputSchema: {\n                    type: 'object',\n                    properties: {\n                        method: { type: 'string', description: 'HTTP method (default GET)' },\n                        path: { type: 'string', description: 'Path appended to the base URL' },\n                        headers: { type: 'object', description: 'Per-request headers' },\n                        query: { type: 'object', description: 'Query parameters' },\n                        body: { description: 'Request body (JSON-encoded for non-GET)' },\n                    },\n                },\n                outputSchema: {\n                    type: 'object',\n                    properties: {\n                        status: { type: 'number' },\n                        ok: { type: 'boolean' },\n                        body: {},\n                    },\n                },\n            },\n        ],\n    };\n\n    async function request(input: Record<string, unknown>): Promise<Record<string, unknown>> {\n        const req = input as RestRequestInput;\n        const method = (req.method ?? 'GET').toUpperCase();\n        const headers: Record<string, string> = { ...opts.defaultHeaders, ...req.headers };\n        const query: Record<string, string | number | boolean | null | undefined> = { ...req.query };\n\n        applyAuth(auth, headers, query);\n\n        const url = buildUrl(opts.baseUrl, req.path ?? '', query);\n\n        const hasBody = req.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 resilientFetch(url, {\n            method,\n            headers,\n            body: hasBody ? JSON.stringify(req.body) : undefined,\n        }, { fetchImpl: opts.fetchImpl });\n\n        // Parse JSON when advertised; fall back to text so non-JSON endpoints\n        // don't throw.\n        const contentType = response.headers.get('content-type') ?? '';\n        const parsed = contentType.includes('application/json')\n            ? await response.json()\n            : await response.text();\n\n        return { status: response.status, ok: response.ok, body: parsed };\n    }\n\n    return { def, handlers: { request } };\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { ConnectorProviderFactory, ResolvedConnectorAuth } from '@objectstack/spec/integration';\nimport { createRestConnector, type RestAuth } from './rest-connector.js';\n\n/**\n * The provider key this package contributes (ADR-0097). A declarative\n * `connectors:` entry with `provider: 'rest'` is materialized by this factory.\n */\nexport const REST_PROVIDER_KEY = 'rest';\n\n/** Injectable dependencies for {@link createRestProviderFactory} (tests). */\nexport interface RestProviderDeps {\n  /** Injected fetch implementation; defaults to the global `fetch`. */\n  fetchImpl?: typeof fetch;\n}\n\n/** Shape of `providerConfig` for a `provider: 'rest'` declarative instance. */\ninterface RestProviderConfig {\n  baseUrl?: unknown;\n  defaultHeaders?: unknown;\n}\n\nfunction isStringRecord(v: unknown): v is Record<string, string> {\n  if (!v || typeof v !== 'object' || Array.isArray(v)) return false;\n  return Object.values(v as Record<string, unknown>).every((x) => typeof x === 'string');\n}\n\n/**\n * Build the `rest` {@link ConnectorProviderFactory} (ADR-0097). At boot the\n * automation service invokes it for each `provider: 'rest'` declarative instance,\n * turning `providerConfig.baseUrl` (+ the resolved `auth`) into the same\n * `{ def, handlers }` bundle {@link createRestConnector} produces for a\n * hand-wired REST connector — one `request` action over static-auth HTTP.\n *\n * Hard-fails on invalid config (missing `baseUrl`), so a misconfigured instance\n * fails boot loudly rather than materializing a dead connector.\n */\nexport function createRestProviderFactory(deps: RestProviderDeps = {}): ConnectorProviderFactory {\n  return (ctx) => {\n    const cfg = (ctx.providerConfig ?? {}) as RestProviderConfig;\n    if (typeof cfg.baseUrl !== 'string' || cfg.baseUrl.length === 0) {\n      throw new Error(\n        `connector-rest provider: connector '${ctx.name}' requires providerConfig.baseUrl (a non-empty string, e.g. https://api.example.com).`,\n      );\n    }\n    if (cfg.defaultHeaders !== undefined && !isStringRecord(cfg.defaultHeaders)) {\n      throw new Error(\n        `connector-rest provider: connector '${ctx.name}' providerConfig.defaultHeaders must be a string→string map.`,\n      );\n    }\n    // `ResolvedConnectorAuth` is exactly the static-auth subset RestAuth expects\n    // (the credentialRef has already been resolved to a secret upstream).\n    const auth = ctx.auth as ResolvedConnectorAuth | undefined as RestAuth | undefined;\n    return createRestConnector({\n      name: ctx.name,\n      label: ctx.label,\n      baseUrl: cfg.baseUrl,\n      auth,\n      defaultHeaders: isStringRecord(cfg.defaultHeaders) ? cfg.defaultHeaders : undefined,\n      fetchImpl: deps.fetchImpl,\n    });\n  };\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { Connector, ConnectorProviderFactory } from '@objectstack/spec/integration';\nimport { createRestConnector, type RestConnectorOptions } from './rest-connector.js';\nimport { createRestProviderFactory, REST_PROVIDER_KEY } from './rest-provider.js';\n\n/**\n * Minimal surface of the automation engine this plugin depends on — the\n * connector registry (ADR-0018 §Addendum) plus the provider registry (ADR-0097).\n * Kept structural so the plugin needs no runtime dependency on\n * `@objectstack/service-automation`.\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    registerConnectorProvider(providerKey: string, factory: ConnectorProviderFactory): void;\n}\n\n/**\n * Options for {@link ConnectorRestPlugin}. All optional (ADR-0097): with no\n * `baseUrl` the plugin contributes only the `rest` provider factory — so a stack\n * can declare `provider: 'rest'` instances as pure metadata. Supply `baseUrl`\n * (etc.) to ALSO register a single hand-wired `rest` connector, the pre-ADR-0097\n * usage.\n */\nexport interface ConnectorRestPluginOptions extends Partial<RestConnectorOptions> {}\n\n/**\n * ConnectorRestPlugin — contributes the generic REST connector (ADR-0018\n * §Addendum) in two forms:\n *\n *  1. **Provider factory** (`rest`, ADR-0097): registered at `init()` so the\n *     automation service can materialize declarative `provider: 'rest'`\n *     `connectors:` entries into live connectors at boot.\n *  2. **Hand-wired instance** (optional, back-compat): when constructed with a\n *     `baseUrl`, it also registers one concrete `rest` connector at `start()`.\n *\n * If no automation engine is present the plugin logs and skips — the connector\n * has nowhere to register, which is not an error.\n */\nexport class ConnectorRestPlugin implements Plugin {\n    name = 'com.objectstack.connector.rest';\n    version = '1.0.0';\n    type = 'standard' as const;\n    // Ensure the automation engine (and its connector/provider registries) exist first.\n    dependencies = ['com.objectstack.service-automation'];\n\n    private readonly options: ConnectorRestPluginOptions;\n    private connectorName?: string;\n    private automation?: ConnectorRegistrySurface;\n\n    constructor(options: ConnectorRestPluginOptions = {}) {\n        this.options = options;\n    }\n\n    async init(ctx: PluginContext): Promise<void> {\n        // Contribute the `rest` provider factory (ADR-0097). Done in init() — not\n        // start() — so it is registered before the automation service materializes\n        // declarative instances during its own start().\n        const automation = this.tryGetAutomation(ctx);\n        if (automation && typeof automation.registerConnectorProvider === 'function') {\n            automation.registerConnectorProvider(\n                REST_PROVIDER_KEY,\n                createRestProviderFactory({ fetchImpl: this.options.fetchImpl }),\n            );\n            ctx.logger.info(\"ConnectorRestPlugin: registered 'rest' connector provider\");\n        }\n    }\n\n    async start(ctx: PluginContext): Promise<void> {\n        // Only register a concrete connector when a baseUrl was supplied — the\n        // provider-only usage (no options) contributes just the factory in init().\n        if (!this.options.baseUrl) return;\n\n        const automation = this.tryGetAutomation(ctx);\n        if (!automation || typeof automation.registerConnector !== 'function') {\n            ctx.logger.info('ConnectorRestPlugin: no automation engine — REST connector not registered');\n            return;\n        }\n\n        const { def, handlers } = createRestConnector(this.options as RestConnectorOptions);\n        automation.registerConnector(def, handlers);\n        this.automation = automation;\n        this.connectorName = def.name;\n        ctx.logger.info(`ConnectorRestPlugin: REST connector '${def.name}' registered`);\n    }\n\n    async stop(_ctx: PluginContext): Promise<void> {\n        if (this.automation && this.connectorName) {\n            try { this.automation.unregisterConnector(this.connectorName); } catch { /* ignore */ }\n        }\n    }\n\n    private tryGetAutomation(ctx: PluginContext): ConnectorRegistrySurface | undefined {\n        try {\n            return ctx.getService<ConnectorRegistrySurface>('automation');\n        } catch {\n            return undefined;\n        }\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/connector-rest",
-  "version": "15.0.0",
+  "version": "15.1.1",
   "license": "Apache-2.0",
   "description": "Generic REST connector for ObjectStack — the reference concrete connector that registers a `request` action on the automation engine's connector registry (ADR-0018 §Addendum).",
   "main": "dist/index.js",
@@ -13,14 +13,14 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "15.0.0",
-    "@objectstack/spec": "15.0.0"
+    "@objectstack/core": "15.1.1",
+    "@objectstack/spec": "15.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@objectstack/service-automation": "15.0.0"
+    "@objectstack/service-automation": "15.1.1"
   },
   "keywords": [
     "objectstack",

package/src/connector-rest-plugin.test.ts

@@ -80,4 +80,75 @@ describe('ConnectorRestPlugin — end to end with the automation engine', () =>
 
         await kernel.shutdown();
     });
+
+    it('materializes a declarative `provider: rest` instance from stack metadata (ADR-0097)', async () => {
+        const { impl, calls } = stubFetch();
+
+        // A provider-bound `connectors:` entry as it sits in the ObjectQL registry.
+        const declared = [
+            {
+                name: 'billing',
+                label: 'Billing API',
+                type: 'api',
+                provider: 'rest',
+                providerConfig: { baseUrl: 'https://billing.example.com' },
+                auth: { type: 'bearer', credentialRef: 'BILLING_TOKEN' },
+            },
+        ];
+
+        const kernel = new LiteKernel();
+        // The plugin, with no baseUrl, contributes ONLY the `rest` provider factory.
+        kernel.use(new AutomationServicePlugin({ credentialResolver: (r) => (r === 'BILLING_TOKEN' ? 'sk-live' : undefined) }));
+        kernel.use(new ConnectorRestPlugin({ fetchImpl: impl }));
+        // A tiny harness that serves the declared connector metadata to the automation service.
+        kernel.use({
+            name: 'test.metadata',
+            type: 'standard',
+            version: '1.0.0',
+            dependencies: [],
+            async init(ctx: any) {
+                ctx.registerService('objectql', {
+                    registry: { listItems: (t: string) => (t === 'connector' ? declared : []) },
+                });
+            },
+            async start() {},
+        } as never);
+
+        await kernel.bootstrap();
+        const engine = kernel.getService<AutomationEngine>('automation');
+
+        // Materialized under the declared name, tagged declarative, and listed.
+        expect(engine.getRegisteredConnectors()).toContain('billing');
+        expect(engine.getConnectorOrigin('billing')).toBe('declarative');
+        expect(engine.getConnectorDescriptors().find((d) => d.name === 'billing')?.actions.map((a) => a.key)).toEqual(['request']);
+
+        engine.registerFlow('call_billing', {
+            name: 'call_billing',
+            label: 'Call Billing',
+            type: 'autolaunched',
+            variables: [{ name: 'call.status', type: 'number', isOutput: true }],
+            nodes: [
+                { id: 'start', type: 'start', label: 'Start' },
+                {
+                    id: 'call',
+                    type: 'connector_action',
+                    label: 'GET /invoices',
+                    connectorConfig: { connectorId: 'billing', actionId: 'request', input: { path: '/invoices' } },
+                },
+                { id: 'end', type: 'end', label: 'End' },
+            ],
+            edges: [
+                { id: 'e1', source: 'start', target: 'call' },
+                { id: 'e2', source: 'call', target: 'end' },
+            ],
+        });
+
+        const result = await engine.execute('call_billing');
+        expect(result.success).toBe(true);
+        // Dispatched to the resolved base URL, with the credentialRef-resolved bearer token.
+        expect(calls[0].url).toBe('https://billing.example.com/invoices');
+        expect((calls[0].init.headers as Record<string, string>)['Authorization']).toBe('Bearer sk-live');
+
+        await kernel.shutdown();
+    });
 });

package/src/connector-rest-plugin.ts

@@ -1,13 +1,15 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { Plugin, PluginContext } from '@objectstack/core';
-import type { Connector } from '@objectstack/spec/integration';
+import type { Connector, ConnectorProviderFactory } from '@objectstack/spec/integration';
 import { createRestConnector, type RestConnectorOptions } from './rest-connector.js';
+import { createRestProviderFactory, REST_PROVIDER_KEY } from './rest-provider.js';
 
 /**
  * Minimal surface of the automation engine this plugin depends on — the
- * connector registry from ADR-0018 §Addendum. Kept structural so the plugin
- * needs no runtime dependency on `@objectstack/service-automation`.
+ * connector registry (ADR-0018 §Addendum) plus the provider registry (ADR-0097).
+ * Kept structural so the plugin needs no runtime dependency on
+ * `@objectstack/service-automation`.
  */
 export interface ConnectorRegistrySurface {
     registerConnector(
@@ -18,15 +20,27 @@ export interface ConnectorRegistrySurface {
         >,
     ): void;
     unregisterConnector(name: string): void;
+    registerConnectorProvider(providerKey: string, factory: ConnectorProviderFactory): void;
 }
 
-export interface ConnectorRestPluginOptions extends RestConnectorOptions {}
+/**
+ * Options for {@link ConnectorRestPlugin}. All optional (ADR-0097): with no
+ * `baseUrl` the plugin contributes only the `rest` provider factory — so a stack
+ * can declare `provider: 'rest'` instances as pure metadata. Supply `baseUrl`
+ * (etc.) to ALSO register a single hand-wired `rest` connector, the pre-ADR-0097
+ * usage.
+ */
+export interface ConnectorRestPluginOptions extends Partial<RestConnectorOptions> {}
 
 /**
- * ConnectorRestPlugin — registers a generic REST connector on the automation
- * engine. This is the **reference concrete connector** (ADR-0018 §Addendum):
- * the dispatch node + registry are baseline; a connector like this one is a
- * plugin that populates the registry.
+ * ConnectorRestPlugin — contributes the generic REST connector (ADR-0018
+ * §Addendum) in two forms:
+ *
+ *  1. **Provider factory** (`rest`, ADR-0097): registered at `init()` so the
+ *     automation service can materialize declarative `provider: 'rest'`
+ *     `connectors:` entries into live connectors at boot.
+ *  2. **Hand-wired instance** (optional, back-compat): when constructed with a
+ *     `baseUrl`, it also registers one concrete `rest` connector at `start()`.
  *
  * If no automation engine is present the plugin logs and skips — the connector
  * has nowhere to register, which is not an error.
@@ -35,36 +49,43 @@ export class ConnectorRestPlugin implements Plugin {
     name = 'com.objectstack.connector.rest';
     version = '1.0.0';
     type = 'standard' as const;
-    // Ensure the automation engine (and its connector registry) is started first.
+    // Ensure the automation engine (and its connector/provider registries) exist first.
     dependencies = ['com.objectstack.service-automation'];
 
     private readonly options: ConnectorRestPluginOptions;
     private connectorName?: string;
     private automation?: ConnectorRegistrySurface;
 
-    constructor(options: ConnectorRestPluginOptions) {
+    constructor(options: ConnectorRestPluginOptions = {}) {
         this.options = options;
     }
 
-    async init(_ctx: PluginContext): Promise<void> {
-        // No services to register; the connector is registered in start() once
-        // the automation engine is available.
+    async init(ctx: PluginContext): Promise<void> {
+        // Contribute the `rest` provider factory (ADR-0097). Done in init() — not
+        // start() — so it is registered before the automation service materializes
+        // declarative instances during its own start().
+        const automation = this.tryGetAutomation(ctx);
+        if (automation && typeof automation.registerConnectorProvider === 'function') {
+            automation.registerConnectorProvider(
+                REST_PROVIDER_KEY,
+                createRestProviderFactory({ fetchImpl: this.options.fetchImpl }),
+            );
+            ctx.logger.info("ConnectorRestPlugin: registered 'rest' connector provider");
+        }
     }
 
     async start(ctx: PluginContext): Promise<void> {
-        let automation: ConnectorRegistrySurface | undefined;
-        try {
-            automation = ctx.getService<ConnectorRegistrySurface>('automation');
-        } catch {
-            automation = undefined;
-        }
+        // Only register a concrete connector when a baseUrl was supplied — the
+        // provider-only usage (no options) contributes just the factory in init().
+        if (!this.options.baseUrl) return;
 
+        const automation = this.tryGetAutomation(ctx);
         if (!automation || typeof automation.registerConnector !== 'function') {
             ctx.logger.info('ConnectorRestPlugin: no automation engine — REST connector not registered');
             return;
         }
 
-        const { def, handlers } = createRestConnector(this.options);
+        const { def, handlers } = createRestConnector(this.options as RestConnectorOptions);
         automation.registerConnector(def, handlers);
         this.automation = automation;
         this.connectorName = def.name;
@@ -76,4 +97,12 @@ export class ConnectorRestPlugin implements Plugin {
             try { this.automation.unregisterConnector(this.connectorName); } catch { /* ignore */ }
         }
     }
+
+    private tryGetAutomation(ctx: PluginContext): ConnectorRegistrySurface | undefined {
+        try {
+            return ctx.getService<ConnectorRegistrySurface>('automation');
+        } catch {
+            return undefined;
+        }
+    }
 }

package/src/index.ts

@@ -24,3 +24,8 @@ export {
     type ConnectorRestPluginOptions,
     type ConnectorRegistrySurface,
 } from './connector-rest-plugin.js';
+export {
+    createRestProviderFactory,
+    REST_PROVIDER_KEY,
+    type RestProviderDeps,
+} from './rest-provider.js';

package/src/rest-provider.test.ts

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// ADR-0097 — the `rest` provider factory: materialize a declarative
+// `provider: 'rest'` connector instance from providerConfig + resolved auth.
+
+import { describe, it, expect } from 'vitest';
+import type { ConnectorProviderContext } from '@objectstack/spec/integration';
+import { createRestProviderFactory, REST_PROVIDER_KEY } from './rest-provider.js';
+
+function stubFetch() {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const impl = (async (url: string, init: RequestInit) => {
+        calls.push({ url, init });
+        return {
+            status: 200,
+            ok: true,
+            headers: { get: (h: string) => (h.toLowerCase() === 'content-type' ? 'application/json' : null) },
+            json: async () => ({ ok: true }),
+            text: async () => '{}',
+        };
+    }) as unknown as typeof fetch;
+    return { impl, calls };
+}
+
+function ctx(partial: Partial<ConnectorProviderContext> & Pick<ConnectorProviderContext, 'providerConfig'>): ConnectorProviderContext {
+    return { name: 'svc', label: 'Svc', type: 'api', ...partial };
+}
+
+describe('rest provider factory (ADR-0097)', () => {
+    it('advertises the rest provider key', () => {
+        expect(REST_PROVIDER_KEY).toBe('rest');
+    });
+
+    it('builds a def + request handler from providerConfig.baseUrl and applies resolved auth', async () => {
+        const { impl, calls } = stubFetch();
+        const factory = createRestProviderFactory({ fetchImpl: impl });
+        const { def, handlers } = await factory(
+            ctx({ name: 'billing', label: 'Billing', providerConfig: { baseUrl: 'https://api.example.com' }, auth: { type: 'bearer', token: 'tok' } }),
+        );
+
+        expect(def.name).toBe('billing');
+        expect(Object.keys(handlers)).toEqual(['request']);
+
+        const out = await handlers.request({ path: '/ping' }, {});
+        expect(out).toMatchObject({ status: 200, ok: true });
+        expect(calls[0].url).toBe('https://api.example.com/ping');
+        expect((calls[0].init.headers as Record<string, string>).Authorization).toBe('Bearer tok');
+    });
+
+    it('throws when providerConfig.baseUrl is missing', () => {
+        const factory = createRestProviderFactory();
+        expect(() => factory(ctx({ providerConfig: {} }))).toThrow(/baseUrl/);
+    });
+
+    it('throws when providerConfig.defaultHeaders is not a string map', () => {
+        const factory = createRestProviderFactory();
+        expect(() =>
+            factory(ctx({ providerConfig: { baseUrl: 'https://x', defaultHeaders: { n: 1 } } })),
+        ).toThrow(/defaultHeaders/);
+    });
+});

package/src/rest-provider.ts

@@ -0,0 +1,64 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ConnectorProviderFactory, ResolvedConnectorAuth } from '@objectstack/spec/integration';
+import { createRestConnector, type RestAuth } from './rest-connector.js';
+
+/**
+ * The provider key this package contributes (ADR-0097). A declarative
+ * `connectors:` entry with `provider: 'rest'` is materialized by this factory.
+ */
+export const REST_PROVIDER_KEY = 'rest';
+
+/** Injectable dependencies for {@link createRestProviderFactory} (tests). */
+export interface RestProviderDeps {
+  /** Injected fetch implementation; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+/** Shape of `providerConfig` for a `provider: 'rest'` declarative instance. */
+interface RestProviderConfig {
+  baseUrl?: unknown;
+  defaultHeaders?: unknown;
+}
+
+function isStringRecord(v: unknown): v is Record<string, string> {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return false;
+  return Object.values(v as Record<string, unknown>).every((x) => typeof x === 'string');
+}
+
+/**
+ * Build the `rest` {@link ConnectorProviderFactory} (ADR-0097). At boot the
+ * automation service invokes it for each `provider: 'rest'` declarative instance,
+ * turning `providerConfig.baseUrl` (+ the resolved `auth`) into the same
+ * `{ def, handlers }` bundle {@link createRestConnector} produces for a
+ * hand-wired REST connector — one `request` action over static-auth HTTP.
+ *
+ * Hard-fails on invalid config (missing `baseUrl`), so a misconfigured instance
+ * fails boot loudly rather than materializing a dead connector.
+ */
+export function createRestProviderFactory(deps: RestProviderDeps = {}): ConnectorProviderFactory {
+  return (ctx) => {
+    const cfg = (ctx.providerConfig ?? {}) as RestProviderConfig;
+    if (typeof cfg.baseUrl !== 'string' || cfg.baseUrl.length === 0) {
+      throw new Error(
+        `connector-rest provider: connector '${ctx.name}' requires providerConfig.baseUrl (a non-empty string, e.g. https://api.example.com).`,
+      );
+    }
+    if (cfg.defaultHeaders !== undefined && !isStringRecord(cfg.defaultHeaders)) {
+      throw new Error(
+        `connector-rest provider: connector '${ctx.name}' providerConfig.defaultHeaders must be a string→string map.`,
+      );
+    }
+    // `ResolvedConnectorAuth` is exactly the static-auth subset RestAuth expects
+    // (the credentialRef has already been resolved to a secret upstream).
+    const auth = ctx.auth as ResolvedConnectorAuth | undefined as RestAuth | undefined;
+    return createRestConnector({
+      name: ctx.name,
+      label: ctx.label,
+      baseUrl: cfg.baseUrl,
+      auth,
+      defaultHeaders: isStringRecord(cfg.defaultHeaders) ? cfg.defaultHeaders : undefined,
+      fetchImpl: deps.fetchImpl,
+    });
+  };
+}