@aloma.io/integration-sdk 3.8.67 → 3.8.69

package/build/testing/network-guard.mjs

@@ -0,0 +1,49 @@
+import net from 'node:net';
+/**
+ * Test-only network guard.
+ *
+ * While installed, any TCP connection to a host that is not loopback throws
+ * immediately. fetch (undici), http, https, ws and axios all end up in
+ * net.Socket.prototype.connect, so this is the safety net behind the vendor mock:
+ * even code that bypasses global fetch cannot reach the network from a test.
+ */
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+let original;
+let installs = 0;
+export const blocked = [];
+const targetOf = (args) => {
+    // net.connect hands over a normalized [options, callback] array
+    const first = Array.isArray(args[0]) ? args[0][0] : args[0];
+    if (first && typeof first === 'object' && !Array.isArray(first)) {
+        if (first.path)
+            return { host: String(first.path), local: true };
+        return { host: String(first.host ?? 'localhost'), local: false };
+    }
+    if (typeof first === 'number' || (typeof first === 'string' && !Number.isNaN(Number(first)))) {
+        return { host: typeof args[1] === 'string' ? args[1] : 'localhost', local: false };
+    }
+    // unix socket path
+    return { host: String(first), local: true };
+};
+export const installNetworkGuard = () => {
+    if (installs++ > 0)
+        return;
+    original = net.Socket.prototype.connect;
+    net.Socket.prototype.connect = function (...args) {
+        const { host, local } = targetOf(args);
+        if (!local && !LOOPBACK.has(host)) {
+            const message = `NETWORK BLOCKED by connector test harness: connection to ${host} is not allowed in tests`;
+            blocked.push(host);
+            throw new Error(message);
+        }
+        return original.apply(this, args);
+    };
+};
+export const uninstallNetworkGuard = () => {
+    if (installs === 0)
+        return;
+    if (--installs > 0)
+        return;
+    net.Socket.prototype.connect = original;
+    original = undefined;
+};

package/build/testing/runtime-connector.d.mts

@@ -0,0 +1,11 @@
+import type RuntimeContext from '../builder/runtime-context.mjs';
+import { Connector } from '../internal/connector/index.mjs';
+/**
+ * Turn what a connector repo builds (`await new Builder()...build()` gives a RuntimeContext) into a configured
+ * `Connector` that the ConnectorHarness can run, without calling `connector.run()` (which starts a metrics
+ * server on a fixed port and installs process signal handlers).
+ *
+ * This repeats the wiring of RuntimeContext.start(): methods become resolvers, config/oauth/endpoint are applied,
+ * main() starts the controller and sends a health check. If RuntimeContext.start() changes, change this too.
+ */
+export declare const connectorFromRuntimeContext: (context: RuntimeContext) => Connector;

package/build/testing/runtime-connector.mjs

@@ -0,0 +1,38 @@
+import { AbstractController } from '../controller/index.mjs';
+import { buildResolvers } from '../builder/runtime-context.mjs';
+import { Connector } from '../internal/connector/index.mjs';
+/**
+ * Turn what a connector repo builds (`await new Builder()...build()` gives a RuntimeContext) into a configured
+ * `Connector` that the ConnectorHarness can run, without calling `connector.run()` (which starts a metrics
+ * server on a fixed port and installs process signal handlers).
+ *
+ * This repeats the wiring of RuntimeContext.start(): methods become resolvers, config/oauth/endpoint are applied,
+ * main() starts the controller and sends a health check. If RuntimeContext.start() changes, change this too.
+ */
+export const connectorFromRuntimeContext = (context) => {
+    const { controller, data } = context;
+    if (!(controller instanceof AbstractController)) {
+        throw new Error('the controller needs to extend AbstractController');
+    }
+    const connector = new Connector({
+        id: data.id,
+        version: data.version,
+        name: `${data.id}/${data.version}`,
+        icon: undefined,
+    });
+    const configuration = connector.configure().config(data.config || {});
+    const methods = [...data.methods, '__autocomplete', '__endpoint', '__default'];
+    configuration.types(data.types).resolvers(buildResolvers(methods, controller));
+    if (data.options?.endpoint?.enabled) {
+        configuration.endpoint((arg) => controller.__endpoint(arg), data.options?.endpoint?.required);
+    }
+    if (data.auth?.oauth) {
+        configuration.oauth(data.auth?.oauth);
+    }
+    configuration.main(async ({ newTask, updateTask, config, oauth, getClient, getBlob, getBlobContent, createBlob, healthCheck }) => {
+        await controller._doStop();
+        await controller._doStart(config, oauth, newTask, updateTask, getClient, getBlob, getBlobContent, createBlob);
+        await healthCheck(controller);
+    });
+    return connector;
+};

package/build/testing/vendor-mock.d.mts

@@ -0,0 +1,59 @@
+/// <reference types="node" resolution-mode="require"/>
+export type VendorRequest = {
+    method: string;
+    url: string;
+    /** the url exactly as the connector passed it to fetch */
+    rawUrl: string;
+    headers: Record<string, string>;
+    body?: string;
+};
+export type VendorResponse = {
+    status?: number;
+    headers?: Record<string, string>;
+    /** sent as JSON with a json content-type */
+    json?: unknown;
+    /** sent as is */
+    text?: string;
+};
+export type VendorResponder = VendorResponse | ((request: VendorRequest) => VendorResponse | Promise<VendorResponse>);
+export type UrlMatcher = string | RegExp | ((url: string) => boolean);
+/**
+ * Mock for the HTTP calls a connector makes to its vendor API.
+ *
+ * - intercepts global fetch (what the SDK Fetcher and OAuth code use)
+ * - answers from routes you register with on()/get()/post()...
+ * - any request without a route is recorded in `unmocked` and rejected,
+ *   verify() then fails the test even if the connector swallowed the error
+ * - also installs the network guard, so nothing can reach a non-loopback host
+ */
+export declare class VendorMock {
+    readonly requests: VendorRequest[];
+    readonly unmocked: VendorRequest[];
+    private routes;
+    private originalFetch?;
+    private passthrough;
+    /** urls for which the real fetch is used (the fake ALOMA endpoint); everything else is mocked */
+    allowPassthrough(fn: (url: URL) => boolean): this;
+    on(method: string, matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    get(matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    post(matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    put(matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    delete(matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    install(): this;
+    uninstall(): void;
+    /** throws if the connector made a request that had no mock, even if it caught the error */
+    verify(): void;
+    /** throws if a registered route was never used */
+    verifyAllRoutesUsed(): void;
+    private handle;
+}

package/build/testing/vendor-mock.mjs

@@ -0,0 +1,121 @@
+import { installNetworkGuard, uninstallNetworkGuard } from './network-guard.mjs';
+// "https:/host/x" (one slash, which the SDK Fetcher produces) and "https://host/x" are the same URL to fetch
+const canonical = (url) => {
+    try {
+        return new URL(url).href;
+    }
+    catch (e) {
+        return url;
+    }
+};
+const matches = (matcher, url) => {
+    if (typeof matcher === 'string')
+        return canonical(matcher) === url;
+    if (matcher instanceof RegExp)
+        return matcher.test(url);
+    return matcher(url);
+};
+/**
+ * Mock for the HTTP calls a connector makes to its vendor API.
+ *
+ * - intercepts global fetch (what the SDK Fetcher and OAuth code use)
+ * - answers from routes you register with on()/get()/post()...
+ * - any request without a route is recorded in `unmocked` and rejected,
+ *   verify() then fails the test even if the connector swallowed the error
+ * - also installs the network guard, so nothing can reach a non-loopback host
+ */
+export class VendorMock {
+    requests = [];
+    unmocked = [];
+    routes = [];
+    originalFetch;
+    passthrough = () => false;
+    /** urls for which the real fetch is used (the fake ALOMA endpoint); everything else is mocked */
+    allowPassthrough(fn) {
+        this.passthrough = fn;
+        return this;
+    }
+    on(method, matcher, respond, options = {}) {
+        this.routes.push({ method: method.toUpperCase(), matcher, respond, times: options.times ?? Infinity, used: 0 });
+        return this;
+    }
+    get(matcher, respond, options) {
+        return this.on('GET', matcher, respond, options);
+    }
+    post(matcher, respond, options) {
+        return this.on('POST', matcher, respond, options);
+    }
+    put(matcher, respond, options) {
+        return this.on('PUT', matcher, respond, options);
+    }
+    delete(matcher, respond, options) {
+        return this.on('DELETE', matcher, respond, options);
+    }
+    install() {
+        if (this.originalFetch)
+            return this;
+        installNetworkGuard();
+        this.originalFetch = globalThis.fetch;
+        globalThis.fetch = ((input, init) => this.handle(input, init));
+        return this;
+    }
+    uninstall() {
+        if (!this.originalFetch)
+            return;
+        globalThis.fetch = this.originalFetch;
+        this.originalFetch = undefined;
+        uninstallNetworkGuard();
+    }
+    /** throws if the connector made a request that had no mock, even if it caught the error */
+    verify() {
+        if (this.unmocked.length) {
+            const list = this.unmocked.map((r) => `${r.method} ${r.url}`).join('\n  ');
+            throw new Error(`UNMOCKED vendor requests were made (no network is allowed in tests):\n  ${list}`);
+        }
+    }
+    /** throws if a registered route was never used */
+    verifyAllRoutesUsed() {
+        const unused = this.routes.filter((r) => r.used === 0);
+        if (unused.length) {
+            throw new Error(`mocked routes never called: ${unused.map((r) => `${r.method} ${String(r.matcher)}`).join(', ')}`);
+        }
+    }
+    async handle(input, init = {}) {
+        const rawUrl = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const url = canonical(rawUrl);
+        const method = String(init.method || (typeof input === 'object' && input.method) || 'GET').toUpperCase();
+        const headers = {};
+        new Headers(init.headers || (typeof input === 'object' && input.headers) || {}).forEach((value, key) => {
+            headers[key] = value;
+        });
+        const request = { method, url, rawUrl, headers };
+        if (init.body != null)
+            request.body = typeof init.body === 'string' ? init.body : String(init.body);
+        const route = this.routes.find((r) => r.method === method && r.used < r.times && matches(r.matcher, url));
+        if (route) {
+            route.used++;
+            this.requests.push(request);
+            const spec = typeof route.respond === 'function' ? await route.respond(request) : route.respond;
+            const responseHeaders = { ...spec.headers };
+            let body = null;
+            if (spec.json !== undefined) {
+                body = JSON.stringify(spec.json);
+                responseHeaders['content-type'] ||= 'application/json';
+            }
+            else if (spec.text !== undefined) {
+                body = spec.text;
+            }
+            const status = spec.status ?? 200;
+            return new Response([204, 205, 304].includes(status) ? null : body, { status, headers: responseHeaders });
+        }
+        if (this.originalFetch && this.passthrough(new URL(url))) {
+            return this.originalFetch(input, init);
+        }
+        this.unmocked.push(request);
+        // status 400 makes the SDK Fetcher give up at once instead of retrying for seconds
+        const error = new Error(`UNMOCKED vendor request: ${method} ${url} (add a route with vendor.on(...))`);
+        error.status = 400;
+        error.alomaHarnessUnmocked = true;
+        throw error;
+    }
+}

package/build/transform/index.d.mts

@@ -1,5 +1,5 @@
-declare const _default: (path: string) => Promise<{
-    text: any;
+declare const _default: (file: string) => Promise<{
+    text: string;
     methods: string[];
 }>;
 export default _default;