@objectstack/connector-rest 7.4.0

package/.turbo/turbo-build.log

@@ -0,0 +1,22 @@
+
+> @objectstack/connector-rest@7.4.0 build /home/runner/work/framework/framework/packages/connectors/connector-rest
+> tsup --config ../../../tsup.config.ts
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /home/runner/work/framework/framework/tsup.config.ts
+CLI Target: es2020
+CLI Cleaning output folder
+ESM Build start
+CJS Build start
+ESM dist/index.mjs     4.58 KB
+ESM dist/index.mjs.map 12.89 KB
+ESM ⚡️ Build success in 69ms
+CJS dist/index.js     5.65 KB
+CJS dist/index.js.map 13.84 KB
+CJS ⚡️ Build success in 94ms
+DTS Build start
+DTS ⚡️ Build success in 13989ms
+DTS dist/index.d.mts 3.62 KB
+DTS dist/index.d.ts  3.62 KB

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @objectstack/connector-rest
+
+## 7.4.0
+
+### Patch Changes
+
+- Updated dependencies [23c7107]
+- Updated dependencies [c72daad]
+- Updated dependencies [f115182]
+- Updated dependencies [2faf9f2]
+- Updated dependencies [2faf9f2]
+- Updated dependencies [2faf9f2]
+- Updated dependencies [58b450b]
+- Updated dependencies [82eb6cf]
+- Updated dependencies [13d8653]
+- Updated dependencies [ff3d006]
+- Updated dependencies [5e831de]
+  - @objectstack/spec@7.4.0
+  - @objectstack/core@7.4.0

package/LICENSE

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

package/dist/index.d.mts

@@ -0,0 +1,83 @@
+import { Connector } from '@objectstack/spec/integration';
+import { Plugin, PluginContext } from '@objectstack/core';
+
+/**
+ * Generic REST connector — the reference *concrete* connector (ADR-0018
+ * §Addendum). It produces a {@link Connector} definition plus the handler for
+ * its one action, `request`, which the baseline `connector_action` node
+ * dispatches to.
+ *
+ * Open-source scope: **static** auth only (`none` / `api-key` / `basic` /
+ * `bearer`), with credentials supplied by the caller. OAuth2 token acquisition
+ * and refresh, credential vaulting, and multi-tenant connection lifecycle are
+ * the enterprise tier (see `../cloud/docs/design/connector-tiering.md`) and are
+ * deliberately out of scope here.
+ */
+/** Auth config understood by the REST connector (the static subset). */
+type RestAuth = Extract<Connector['authentication'], {
+    type: 'none' | 'api-key' | 'basic' | 'bearer';
+}>;
+interface RestConnectorOptions {
+    /** Connector machine name (snake_case). Defaults to `rest`. */
+    name?: string;
+    /** Human-readable label. Defaults to a title derived from `name`. */
+    label?: string;
+    /** Base URL prepended to each request's `path` (e.g. `https://api.example.com`). */
+    baseUrl: string;
+    /** Static authentication. Defaults to `{ type: 'none' }`. */
+    auth?: RestAuth;
+    /** Headers merged into every request (request-level headers win). */
+    defaultHeaders?: Record<string, string>;
+    /** Injected for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Input accepted by the `request` action. */
+interface RestRequestInput {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+}
+/** A connector definition paired with its action handlers, ready for registerConnector(). */
+interface RestConnectorBundle {
+    def: Connector;
+    handlers: Record<string, (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>>;
+}
+declare function createRestConnector(opts: RestConnectorOptions): RestConnectorBundle;
+
+/**
+ * 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`.
+ */
+interface ConnectorRegistrySurface {
+    registerConnector(def: Connector, handlers: Record<string, (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>>): void;
+    unregisterConnector(name: string): void;
+}
+interface ConnectorRestPluginOptions extends 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.
+ *
+ * If no automation engine is present the plugin logs and skips — the connector
+ * has nowhere to register, which is not an error.
+ */
+declare class ConnectorRestPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    private readonly options;
+    private connectorName?;
+    private automation?;
+    constructor(options: ConnectorRestPluginOptions);
+    init(_ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    stop(_ctx: PluginContext): Promise<void>;
+}
+
+export { type ConnectorRegistrySurface, ConnectorRestPlugin, type ConnectorRestPluginOptions, type RestAuth, type RestConnectorBundle, type RestConnectorOptions, type RestRequestInput, createRestConnector };

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+import { Connector } from '@objectstack/spec/integration';
+import { Plugin, PluginContext } from '@objectstack/core';
+
+/**
+ * Generic REST connector — the reference *concrete* connector (ADR-0018
+ * §Addendum). It produces a {@link Connector} definition plus the handler for
+ * its one action, `request`, which the baseline `connector_action` node
+ * dispatches to.
+ *
+ * Open-source scope: **static** auth only (`none` / `api-key` / `basic` /
+ * `bearer`), with credentials supplied by the caller. OAuth2 token acquisition
+ * and refresh, credential vaulting, and multi-tenant connection lifecycle are
+ * the enterprise tier (see `../cloud/docs/design/connector-tiering.md`) and are
+ * deliberately out of scope here.
+ */
+/** Auth config understood by the REST connector (the static subset). */
+type RestAuth = Extract<Connector['authentication'], {
+    type: 'none' | 'api-key' | 'basic' | 'bearer';
+}>;
+interface RestConnectorOptions {
+    /** Connector machine name (snake_case). Defaults to `rest`. */
+    name?: string;
+    /** Human-readable label. Defaults to a title derived from `name`. */
+    label?: string;
+    /** Base URL prepended to each request's `path` (e.g. `https://api.example.com`). */
+    baseUrl: string;
+    /** Static authentication. Defaults to `{ type: 'none' }`. */
+    auth?: RestAuth;
+    /** Headers merged into every request (request-level headers win). */
+    defaultHeaders?: Record<string, string>;
+    /** Injected for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Input accepted by the `request` action. */
+interface RestRequestInput {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+}
+/** A connector definition paired with its action handlers, ready for registerConnector(). */
+interface RestConnectorBundle {
+    def: Connector;
+    handlers: Record<string, (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>>;
+}
+declare function createRestConnector(opts: RestConnectorOptions): RestConnectorBundle;
+
+/**
+ * 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`.
+ */
+interface ConnectorRegistrySurface {
+    registerConnector(def: Connector, handlers: Record<string, (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>>): void;
+    unregisterConnector(name: string): void;
+}
+interface ConnectorRestPluginOptions extends 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.
+ *
+ * If no automation engine is present the plugin logs and skips — the connector
+ * has nowhere to register, which is not an error.
+ */
+declare class ConnectorRestPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    private readonly options;
+    private connectorName?;
+    private automation?;
+    constructor(options: ConnectorRestPluginOptions);
+    init(_ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    stop(_ctx: PluginContext): Promise<void>;
+}
+
+export { type ConnectorRegistrySurface, ConnectorRestPlugin, type ConnectorRestPluginOptions, type RestAuth, type RestConnectorBundle, type RestConnectorOptions, type RestRequestInput, createRestConnector };

package/dist/index.js

@@ -0,0 +1,167 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConnectorRestPlugin: () => ConnectorRestPlugin,
+  createRestConnector: () => createRestConnector
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/rest-connector.ts
+function buildUrl(baseUrl, path, query) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const suffix = path ? path.startsWith("/") ? path : `/${path}` : "";
+  const url = new URL(base + suffix);
+  if (query) {
+    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 createRestConnector(opts) {
+  const name = opts.name ?? "rest";
+  const auth = opts.auth ?? { type: "none" };
+  const doFetch = opts.fetchImpl ?? fetch;
+  const def = {
+    name,
+    label: opts.label ?? "REST Connector",
+    type: "api",
+    description: "Generic REST/HTTP connector with static authentication.",
+    icon: "globe",
+    authentication: auth,
+    // Defaulted by ConnectorSchema; set explicitly so the literal satisfies
+    // the (post-parse) Connector output type.
+    status: "active",
+    enabled: true,
+    connectionTimeoutMs: 3e4,
+    requestTimeoutMs: 3e4,
+    actions: [
+      {
+        key: "request",
+        label: "HTTP Request",
+        description: "Send an HTTP request to the connector's base URL with static auth applied.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            method: { type: "string", description: "HTTP method (default GET)" },
+            path: { type: "string", description: "Path appended to the base URL" },
+            headers: { type: "object", description: "Per-request headers" },
+            query: { type: "object", description: "Query parameters" },
+            body: { description: "Request body (JSON-encoded for non-GET)" }
+          }
+        },
+        outputSchema: {
+          type: "object",
+          properties: {
+            status: { type: "number" },
+            ok: { type: "boolean" },
+            body: {}
+          }
+        }
+      }
+    ]
+  };
+  async function request(input) {
+    const req = input;
+    const method = (req.method ?? "GET").toUpperCase();
+    const headers = { ...opts.defaultHeaders, ...req.headers };
+    const query = { ...req.query };
+    applyAuth(auth, headers, query);
+    const url = buildUrl(opts.baseUrl, req.path ?? "", query);
+    const hasBody = req.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(req.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 };
+  }
+  return { def, handlers: { request } };
+}
+
+// src/connector-rest-plugin.ts
+var ConnectorRestPlugin = class {
+  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.
+    this.dependencies = ["com.objectstack.service-automation"];
+    this.options = options;
+  }
+  async init(_ctx) {
+  }
+  async start(ctx) {
+    let automation;
+    try {
+      automation = ctx.getService("automation");
+    } catch {
+      automation = void 0;
+    }
+    if (!automation || typeof automation.registerConnector !== "function") {
+      ctx.logger.info("ConnectorRestPlugin: no automation engine \u2014 REST connector not registered");
+      return;
+    }
+    const { def, handlers } = createRestConnector(this.options);
+    automation.registerConnector(def, handlers);
+    this.automation = automation;
+    this.connectorName = def.name;
+    ctx.logger.info(`ConnectorRestPlugin: REST connector '${def.name}' registered`);
+  }
+  async stop(_ctx) {
+    if (this.automation && this.connectorName) {
+      try {
+        this.automation.unregisterConnector(this.connectorName);
+      } catch {
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConnectorRestPlugin,
+  createRestConnector
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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';\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    const doFetch = opts.fetchImpl ?? fetch;\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 doFetch(url, {\n            method,\n            headers,\n            body: hasBody ? JSON.stringify(req.body) : undefined,\n        });\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":[]}

package/dist/index.mjs

@@ -0,0 +1,139 @@
+// src/rest-connector.ts
+function buildUrl(baseUrl, path, query) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const suffix = path ? path.startsWith("/") ? path : `/${path}` : "";
+  const url = new URL(base + suffix);
+  if (query) {
+    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 createRestConnector(opts) {
+  const name = opts.name ?? "rest";
+  const auth = opts.auth ?? { type: "none" };
+  const doFetch = opts.fetchImpl ?? fetch;
+  const def = {
+    name,
+    label: opts.label ?? "REST Connector",
+    type: "api",
+    description: "Generic REST/HTTP connector with static authentication.",
+    icon: "globe",
+    authentication: auth,
+    // Defaulted by ConnectorSchema; set explicitly so the literal satisfies
+    // the (post-parse) Connector output type.
+    status: "active",
+    enabled: true,
+    connectionTimeoutMs: 3e4,
+    requestTimeoutMs: 3e4,
+    actions: [
+      {
+        key: "request",
+        label: "HTTP Request",
+        description: "Send an HTTP request to the connector's base URL with static auth applied.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            method: { type: "string", description: "HTTP method (default GET)" },
+            path: { type: "string", description: "Path appended to the base URL" },
+            headers: { type: "object", description: "Per-request headers" },
+            query: { type: "object", description: "Query parameters" },
+            body: { description: "Request body (JSON-encoded for non-GET)" }
+          }
+        },
+        outputSchema: {
+          type: "object",
+          properties: {
+            status: { type: "number" },
+            ok: { type: "boolean" },
+            body: {}
+          }
+        }
+      }
+    ]
+  };
+  async function request(input) {
+    const req = input;
+    const method = (req.method ?? "GET").toUpperCase();
+    const headers = { ...opts.defaultHeaders, ...req.headers };
+    const query = { ...req.query };
+    applyAuth(auth, headers, query);
+    const url = buildUrl(opts.baseUrl, req.path ?? "", query);
+    const hasBody = req.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(req.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 };
+  }
+  return { def, handlers: { request } };
+}
+
+// src/connector-rest-plugin.ts
+var ConnectorRestPlugin = class {
+  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.
+    this.dependencies = ["com.objectstack.service-automation"];
+    this.options = options;
+  }
+  async init(_ctx) {
+  }
+  async start(ctx) {
+    let automation;
+    try {
+      automation = ctx.getService("automation");
+    } catch {
+      automation = void 0;
+    }
+    if (!automation || typeof automation.registerConnector !== "function") {
+      ctx.logger.info("ConnectorRestPlugin: no automation engine \u2014 REST connector not registered");
+      return;
+    }
+    const { def, handlers } = createRestConnector(this.options);
+    automation.registerConnector(def, handlers);
+    this.automation = automation;
+    this.connectorName = def.name;
+    ctx.logger.info(`ConnectorRestPlugin: REST connector '${def.name}' registered`);
+  }
+  async stop(_ctx) {
+    if (this.automation && this.connectorName) {
+      try {
+        this.automation.unregisterConnector(this.connectorName);
+      } catch {
+      }
+    }
+  }
+};
+export {
+  ConnectorRestPlugin,
+  createRestConnector
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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';\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    const doFetch = opts.fetchImpl ?? fetch;\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 doFetch(url, {\n            method,\n            headers,\n            body: hasBody ? JSON.stringify(req.body) : undefined,\n        });\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":[]}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@objectstack/connector-rest",
+  "version": "7.4.0",
+  "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",
+  "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",
+    "rest",
+    "integration",
+    "http"
+  ],
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run --passWithNoTests"
+  }
+}

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

@@ -0,0 +1,83 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { LiteKernel } from '@objectstack/core';
+import { AutomationServicePlugin, type AutomationEngine } from '@objectstack/service-automation';
+import { ConnectorRestPlugin } from './connector-rest-plugin.js';
+
+/** A fetch stub recording calls, returning a fixed JSON response. */
+function stubFetch() {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const impl = (async (url: string, init: RequestInit) => {
+        calls.push({ url, init });
+        return {
+            status: 201,
+            ok: true,
+            headers: { get: (h: string) => (h.toLowerCase() === 'content-type' ? 'application/json' : null) },
+            json: async () => ({ id: 'created-1' }),
+            text: async () => '{"id":"created-1"}',
+        };
+    }) as unknown as typeof fetch;
+    return { impl, calls };
+}
+
+describe('ConnectorRestPlugin — end to end with the automation engine', () => {
+    it('registers the REST connector so a connector_action flow dispatches to it', async () => {
+        const { impl, calls } = stubFetch();
+
+        const kernel = new LiteKernel();
+        kernel.use(new AutomationServicePlugin());
+        kernel.use(
+            new ConnectorRestPlugin({
+                baseUrl: 'https://api.example.com',
+                auth: { type: 'bearer', token: 'secret-token' },
+                fetchImpl: impl,
+            }),
+        );
+        await kernel.bootstrap();
+
+        const engine = kernel.getService<AutomationEngine>('automation');
+
+        // The baseline node and the plugin-contributed connector are both present.
+        expect(engine.getRegisteredNodeTypes()).toContain('connector_action');
+        expect(engine.getRegisteredConnectors()).toContain('rest');
+
+        engine.registerFlow('create_via_rest', {
+            name: 'create_via_rest',
+            label: 'Create via REST',
+            type: 'autolaunched',
+            variables: [{ name: 'call.body', type: 'json', isOutput: true }],
+            nodes: [
+                { id: 'start', type: 'start', label: 'Start' },
+                {
+                    id: 'call',
+                    type: 'connector_action',
+                    label: 'POST /items',
+                    connectorConfig: {
+                        connectorId: 'rest',
+                        actionId: 'request',
+                        input: { method: 'POST', path: '/items', body: { name: 'Widget' } },
+                    },
+                },
+                { id: 'end', type: 'end', label: 'End' },
+            ],
+            edges: [
+                { id: 'e1', source: 'start', target: 'call' },
+                { id: 'e2', source: 'call', target: 'end' },
+            ],
+        });
+
+        const result = await engine.execute('create_via_rest');
+
+        expect(result.success).toBe(true);
+        // The REST connector handled the dispatch: one fetch with auth + body.
+        expect(calls).toHaveLength(1);
+        expect(calls[0].url).toBe('https://api.example.com/items');
+        expect(calls[0].init.method).toBe('POST');
+        expect((calls[0].init.headers as Record<string, string>)['Authorization']).toBe('Bearer secret-token');
+        // The action output propagated back into the flow.
+        expect(result.output).toEqual({ 'call.body': { id: 'created-1' } });
+
+        await kernel.shutdown();
+    });
+});

package/src/connector-rest-plugin.ts

@@ -0,0 +1,79 @@
+// 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 { createRestConnector, type RestConnectorOptions } from './rest-connector.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`.
+ */
+export interface ConnectorRegistrySurface {
+    registerConnector(
+        def: Connector,
+        handlers: Record<
+            string,
+            (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>
+        >,
+    ): void;
+    unregisterConnector(name: string): void;
+}
+
+export interface ConnectorRestPluginOptions extends 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.
+ *
+ * If no automation engine is present the plugin logs and skips — the connector
+ * has nowhere to register, which is not an error.
+ */
+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.
+    dependencies = ['com.objectstack.service-automation'];
+
+    private readonly options: ConnectorRestPluginOptions;
+    private connectorName?: string;
+    private automation?: ConnectorRegistrySurface;
+
+    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 start(ctx: PluginContext): Promise<void> {
+        let automation: ConnectorRegistrySurface | undefined;
+        try {
+            automation = ctx.getService<ConnectorRegistrySurface>('automation');
+        } catch {
+            automation = undefined;
+        }
+
+        if (!automation || typeof automation.registerConnector !== 'function') {
+            ctx.logger.info('ConnectorRestPlugin: no automation engine — REST connector not registered');
+            return;
+        }
+
+        const { def, handlers } = createRestConnector(this.options);
+        automation.registerConnector(def, handlers);
+        this.automation = automation;
+        this.connectorName = def.name;
+        ctx.logger.info(`ConnectorRestPlugin: REST connector '${def.name}' registered`);
+    }
+
+    async stop(_ctx: PluginContext): Promise<void> {
+        if (this.automation && this.connectorName) {
+            try { this.automation.unregisterConnector(this.connectorName); } catch { /* ignore */ }
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/connector-rest
+ *
+ * Generic REST connector — the reference *concrete* connector (ADR-0018
+ * §Addendum). The baseline automation engine ships the `connector_action`
+ * dispatch node + an empty connector registry; this plugin populates the
+ * registry with a `rest` connector exposing a `request` action.
+ *
+ * Static auth only (`none` / `api-key` / `basic` / `bearer`); OAuth2 refresh,
+ * credential vaulting, and multi-tenant lifecycle are the enterprise tier.
+ */
+
+export {
+    createRestConnector,
+    type RestConnectorOptions,
+    type RestConnectorBundle,
+    type RestRequestInput,
+    type RestAuth,
+} from './rest-connector.js';
+export {
+    ConnectorRestPlugin,
+    type ConnectorRestPluginOptions,
+    type ConnectorRegistrySurface,
+} from './connector-rest-plugin.js';

package/src/rest-connector.test.ts

@@ -0,0 +1,139 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import { createRestConnector } from './rest-connector.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+interface CapturedCall {
+    url: string;
+    init: RequestInit;
+}
+
+/** A fetch stub that records calls and returns a fixed JSON response. */
+function stubFetch(responseBody: unknown = { ok: true }, status = 200) {
+    const calls: CapturedCall[] = [];
+    const impl = (async (url: string, init: RequestInit) => {
+        calls.push({ url, init });
+        return {
+            status,
+            ok: status >= 200 && status < 300,
+            headers: { get: (h: string) => (h.toLowerCase() === 'content-type' ? 'application/json' : null) },
+            json: async () => responseBody,
+            text: async () => JSON.stringify(responseBody),
+        };
+    }) as unknown as typeof fetch;
+    return { impl, calls };
+}
+
+function headersOf(call: CapturedCall): Record<string, string> {
+    return (call.init.headers ?? {}) as Record<string, string>;
+}
+
+// ─── request action ──────────────────────────────────────────────────
+
+describe('createRestConnector — request action', () => {
+    it('builds the URL from base + path + query and returns the parsed body', async () => {
+        const { impl, calls } = stubFetch({ id: 1, name: 'Ada' });
+        const { def, handlers } = createRestConnector({ baseUrl: 'https://api.example.com/', fetchImpl: impl });
+
+        expect(def.name).toBe('rest');
+        expect(def.actions?.[0].key).toBe('request');
+
+        const out = await handlers.request({ path: '/users', query: { page: 2, active: true } }, {});
+
+        expect(calls).toHaveLength(1);
+        expect(calls[0].url).toBe('https://api.example.com/users?page=2&active=true');
+        expect(calls[0].init.method).toBe('GET');
+        expect(out).toEqual({ status: 200, ok: true, body: { id: 1, name: 'Ada' } });
+    });
+
+    it('JSON-encodes the body and sets Content-Type for non-GET', async () => {
+        const { impl, calls } = stubFetch();
+        const { handlers } = createRestConnector({ baseUrl: 'https://api.example.com', fetchImpl: impl });
+
+        await handlers.request({ method: 'post', path: 'items', body: { name: 'x' } }, {});
+
+        expect(calls[0].init.method).toBe('POST');
+        expect(calls[0].init.body).toBe('{"name":"x"}');
+        expect(headersOf(calls[0])['Content-Type']).toBe('application/json');
+    });
+
+    it('does not send a body on GET', async () => {
+        const { impl, calls } = stubFetch();
+        const { handlers } = createRestConnector({ baseUrl: 'https://api.example.com', fetchImpl: impl });
+
+        await handlers.request({ method: 'GET', path: '/ping', body: { ignored: true } }, {});
+        expect(calls[0].init.body).toBeUndefined();
+    });
+});
+
+// ─── auth injection ──────────────────────────────────────────────────
+
+describe('createRestConnector — static auth', () => {
+    it('injects a bearer token', async () => {
+        const { impl, calls } = stubFetch();
+        const { handlers } = createRestConnector({
+            baseUrl: 'https://api.example.com',
+            auth: { type: 'bearer', token: 'tok-123' },
+            fetchImpl: impl,
+        });
+        await handlers.request({ path: '/me' }, {});
+        expect(headersOf(calls[0])['Authorization']).toBe('Bearer tok-123');
+    });
+
+    it('injects a basic auth header', async () => {
+        const { impl, calls } = stubFetch();
+        const { handlers } = createRestConnector({
+            baseUrl: 'https://api.example.com',
+            auth: { type: 'basic', username: 'user', password: 'pass' },
+            fetchImpl: impl,
+        });
+        await handlers.request({ path: '/me' }, {});
+        const expected = `Basic ${Buffer.from('user:pass').toString('base64')}`;
+        expect(headersOf(calls[0])['Authorization']).toBe(expected);
+    });
+
+    it('injects an api-key header by default', async () => {
+        const { impl, calls } = stubFetch();
+        const { handlers } = createRestConnector({
+            baseUrl: 'https://api.example.com',
+            auth: { type: 'api-key', key: 'k-1', headerName: 'X-Api-Key' },
+            fetchImpl: impl,
+        });
+        await handlers.request({ path: '/me' }, {});
+        expect(headersOf(calls[0])['X-Api-Key']).toBe('k-1');
+    });
+
+    it('injects an api-key as a query param when paramName is set', async () => {
+        const { impl, calls } = stubFetch();
+        const { handlers } = createRestConnector({
+            baseUrl: 'https://api.example.com',
+            auth: { type: 'api-key', key: 'k-1', headerName: 'X-API-Key', paramName: 'api_key' },
+            fetchImpl: impl,
+        });
+        await handlers.request({ path: '/me' }, {});
+        expect(calls[0].url).toBe('https://api.example.com/me?api_key=k-1');
+        expect(headersOf(calls[0])['X-API-Key']).toBeUndefined();
+    });
+
+    it('adds no auth for type none', async () => {
+        const { impl, calls } = stubFetch();
+        const { handlers } = createRestConnector({ baseUrl: 'https://api.example.com', fetchImpl: impl });
+        await handlers.request({ path: '/public' }, {});
+        expect(headersOf(calls[0])['Authorization']).toBeUndefined();
+    });
+
+    it('merges defaultHeaders, with per-request headers winning', async () => {
+        const { impl, calls } = stubFetch();
+        const { handlers } = createRestConnector({
+            baseUrl: 'https://api.example.com',
+            defaultHeaders: { 'X-Trace': 'on', 'X-Env': 'prod' },
+            fetchImpl: impl,
+        });
+        await handlers.request({ path: '/x', headers: { 'X-Env': 'dev' } }, {});
+        const h = headersOf(calls[0]);
+        expect(h['X-Trace']).toBe('on');
+        expect(h['X-Env']).toBe('dev');
+    });
+});

package/src/rest-connector.ts

@@ -0,0 +1,174 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Connector } from '@objectstack/spec/integration';
+
+/**
+ * Generic REST connector — the reference *concrete* connector (ADR-0018
+ * §Addendum). It produces a {@link Connector} definition plus the handler for
+ * its one action, `request`, which the baseline `connector_action` node
+ * dispatches to.
+ *
+ * Open-source scope: **static** auth only (`none` / `api-key` / `basic` /
+ * `bearer`), with credentials supplied by the caller. OAuth2 token acquisition
+ * and refresh, credential vaulting, and multi-tenant connection lifecycle are
+ * the enterprise tier (see `../cloud/docs/design/connector-tiering.md`) and are
+ * deliberately out of scope here.
+ */
+
+/** Auth config understood by the REST connector (the static subset). */
+export type RestAuth = Extract<
+    Connector['authentication'],
+    { type: 'none' | 'api-key' | 'basic' | 'bearer' }
+>;
+
+export interface RestConnectorOptions {
+    /** Connector machine name (snake_case). Defaults to `rest`. */
+    name?: string;
+    /** Human-readable label. Defaults to a title derived from `name`. */
+    label?: string;
+    /** Base URL prepended to each request's `path` (e.g. `https://api.example.com`). */
+    baseUrl: string;
+    /** Static authentication. Defaults to `{ type: 'none' }`. */
+    auth?: RestAuth;
+    /** Headers merged into every request (request-level headers win). */
+    defaultHeaders?: Record<string, string>;
+    /** Injected for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+
+/** Input accepted by the `request` action. */
+export interface RestRequestInput {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+}
+
+/** A connector definition paired with its action handlers, ready for registerConnector(). */
+export interface RestConnectorBundle {
+    def: Connector;
+    handlers: Record<
+        string,
+        (input: Record<string, unknown>, ctx: unknown) => Promise<Record<string, unknown>>
+    >;
+}
+
+/** Build the request URL from base + path + query, encoding query params. */
+function buildUrl(baseUrl: string, path: string, query?: RestRequestInput['query']): string {
+    const base = baseUrl.replace(/\/+$/, '');
+    const suffix = path ? (path.startsWith('/') ? path : `/${path}`) : '';
+    const url = new URL(base + suffix);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+        }
+    }
+    return url.toString();
+}
+
+/**
+ * Apply static auth to the outgoing headers / query. Returns possibly-extended
+ * query so an `api-key` configured with `paramName` can ride the query string.
+ */
+function applyAuth(
+    auth: RestAuth,
+    headers: Record<string, string>,
+    query: Record<string, string | number | boolean | null | undefined>,
+): void {
+    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;
+    }
+}
+
+export function createRestConnector(opts: RestConnectorOptions): RestConnectorBundle {
+    const name = opts.name ?? 'rest';
+    const auth: RestAuth = opts.auth ?? { type: 'none' };
+    const doFetch = opts.fetchImpl ?? fetch;
+
+    const def: Connector = {
+        name,
+        label: opts.label ?? 'REST Connector',
+        type: 'api',
+        description: 'Generic REST/HTTP connector with static authentication.',
+        icon: 'globe',
+        authentication: auth,
+        // Defaulted by ConnectorSchema; set explicitly so the literal satisfies
+        // the (post-parse) Connector output type.
+        status: 'active',
+        enabled: true,
+        connectionTimeoutMs: 30000,
+        requestTimeoutMs: 30000,
+        actions: [
+            {
+                key: 'request',
+                label: 'HTTP Request',
+                description: 'Send an HTTP request to the connector\'s base URL with static auth applied.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        method: { type: 'string', description: 'HTTP method (default GET)' },
+                        path: { type: 'string', description: 'Path appended to the base URL' },
+                        headers: { type: 'object', description: 'Per-request headers' },
+                        query: { type: 'object', description: 'Query parameters' },
+                        body: { description: 'Request body (JSON-encoded for non-GET)' },
+                    },
+                },
+                outputSchema: {
+                    type: 'object',
+                    properties: {
+                        status: { type: 'number' },
+                        ok: { type: 'boolean' },
+                        body: {},
+                    },
+                },
+            },
+        ],
+    };
+
+    async function request(input: Record<string, unknown>): Promise<Record<string, unknown>> {
+        const req = input as RestRequestInput;
+        const method = (req.method ?? 'GET').toUpperCase();
+        const headers: Record<string, string> = { ...opts.defaultHeaders, ...req.headers };
+        const query: Record<string, string | number | boolean | null | undefined> = { ...req.query };
+
+        applyAuth(auth, headers, query);
+
+        const url = buildUrl(opts.baseUrl, req.path ?? '', query);
+
+        const hasBody = req.body !== undefined && method !== 'GET' && method !== 'HEAD';
+        if (hasBody && headers['Content-Type'] === undefined && headers['content-type'] === undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+
+        const response = await doFetch(url, {
+            method,
+            headers,
+            body: hasBody ? JSON.stringify(req.body) : undefined,
+        });
+
+        // Parse JSON when advertised; fall back to text so non-JSON endpoints
+        // don't throw.
+        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 };
+    }
+
+    return { def, handlers: { request } };
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}