@aloma.io/integration-sdk 3.8.66 → 3.8.68

package/src/testing/vendor-mock.mts

@@ -0,0 +1,166 @@
+import {installNetworkGuard, uninstallNetworkGuard} from './network-guard.mjs';
+
+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);
+
+type Route = {
+  method: string;
+  matcher: UrlMatcher;
+  respond: VendorResponder;
+  times: number;
+  used: number;
+};
+
+// "https:/host/x" (one slash, which the SDK Fetcher produces) and "https://host/x" are the same URL to fetch
+const canonical = (url: string): string => {
+  try {
+    return new URL(url).href;
+  } catch (e) {
+    return url;
+  }
+};
+
+const matches = (matcher: UrlMatcher, url: string): boolean => {
+  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 {
+  readonly requests: VendorRequest[] = [];
+  readonly unmocked: VendorRequest[] = [];
+  private routes: Route[] = [];
+  private originalFetch?: typeof fetch;
+  private passthrough: (url: URL) => boolean = () => false;
+
+  /** urls for which the real fetch is used (the fake ALOMA endpoint); everything else is mocked */
+  allowPassthrough(fn: (url: URL) => boolean) {
+    this.passthrough = fn;
+    return this;
+  }
+
+  on(method: string, matcher: UrlMatcher, respond: VendorResponder, options: {times?: number} = {}) {
+    this.routes.push({method: method.toUpperCase(), matcher, respond, times: options.times ?? Infinity, used: 0});
+    return this;
+  }
+
+  get(matcher: UrlMatcher, respond: VendorResponder, options?: {times?: number}) {
+    return this.on('GET', matcher, respond, options);
+  }
+  post(matcher: UrlMatcher, respond: VendorResponder, options?: {times?: number}) {
+    return this.on('POST', matcher, respond, options);
+  }
+  put(matcher: UrlMatcher, respond: VendorResponder, options?: {times?: number}) {
+    return this.on('PUT', matcher, respond, options);
+  }
+  delete(matcher: UrlMatcher, respond: VendorResponder, options?: {times?: number}) {
+    return this.on('DELETE', matcher, respond, options);
+  }
+
+  install() {
+    if (this.originalFetch) return this;
+
+    installNetworkGuard();
+    this.originalFetch = globalThis.fetch;
+    globalThis.fetch = ((input: any, init?: any) => this.handle(input, init)) as typeof fetch;
+
+    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(', ')}`);
+    }
+  }
+
+  private async handle(input: any, init: any = {}): Promise<Response> {
+    const rawUrl: string = 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: Record<string, string> = {};
+    new Headers(init.headers || (typeof input === 'object' && (input as any).headers) || {}).forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    const request: VendorRequest = {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: string | null = 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: any = new Error(`UNMOCKED vendor request: ${method} ${url} (add a route with vendor.on(...))`);
+    error.status = 400;
+    error.alomaHarnessUnmocked = true;
+    throw error;
+  }
+}

package/test/MUTATION-entry.md

@@ -0,0 +1,21 @@
+# Mutation check for the SDK tests that `yarn test` now runs
+
+Result: **8/8 mutants killed** (24 Oct). Run with `yarn build && node tools/mutation-run-entry.mjs`.
+
+Each row is one deliberate single-point bug in `src/openapi-to-connector.mts` (the OpenAPI to connector generator). The
+script applies it alone, rebuilds, runs the full `yarn test`, expects a failure, and restores the file.
+
+| # | Bug | Result |
+|---|-----|--------|
+| E01 | the HTTP verb is taken in lower case | killed |
+| E02 | path parameter substitution is guarded by the wrong condition | killed |
+| E03 | fallback method name drops the separator | killed |
+| E04 | body properties are documented with the wrong required flag | killed |
+| E05 | headers are dropped from the generated options type | killed |
+| E06 | options is not defaulted in generated methods | killed |
+| E07 | invalid specs are no longer rejected | killed |
+| E08 | a property is required only if both the schema and the body say so | killed |
+
+A first run left two survivors: E02 (nothing asserted the path parameter substitution) and a draft E03 aimed at
+`disambiguateMethodName` (no test reaches it, so a different mutant on the fallback name was used). A test for E02 was
+added to `test/openapi-to-connector.test.mts`; `disambiguateMethodName` remains without direct coverage.

package/test/MUTATION.md

@@ -0,0 +1,43 @@
+# Mutation check for the connector test harness
+
+Result: **32/32 mutants killed**.
+
+Each row is one deliberate single-point bug in the SDK code paths the harness exercises (handshake, transport,
+dispatch, result return, config) or in the harness itself. `tools/mutation-run.mjs` applies it to `src/`, rebuilds,
+runs `test/harness.test.mjs` with `--bail`, expects a failure, and restores the file. Re-run with
+`yarn build && yarn test:mutation` after changing the harness or those SDK paths.
+
+| # | Area | File | Bug | Result |
+|---|------|------|-----|--------|
+| M01 | sdk handshake | `src/internal/websocket/connection/index.mjs` | a 401 from /connect no longer triggers registration | killed |
+| M02 | sdk handshake | `src/internal/websocket/connection/index.mjs` | the token from registration is not stored | killed |
+| M03 | sdk handshake | `src/internal/websocket/connection/registration.mjs` | registration reads the wrong field of the answer | killed |
+| M04 | sdk handshake | `src/internal/websocket/connection/registration.mjs` | registration sends the name as the connector id | killed |
+| M05 | sdk handshake | `src/internal/websocket/connection/registration.mjs` | registration omits the public key | killed |
+| M06 | sdk handshake | `src/internal/websocket/connection/constants.mjs` | authenticated requests drop the version from the User-Agent | killed |
+| M07 | sdk handshake | `src/internal/websocket/connection/constants.mjs` | wrong authorization scheme for the session token | killed |
+| M08 | sdk handshake | `src/internal/websocket/transport/index.mjs` | websocket opened without the "connector" subprotocol | killed |
+| M09 | sdk transport | `src/internal/websocket/transport/index.mjs` | the first packet of every incoming frame is dropped | killed |
+| M10 | sdk transport | `src/internal/websocket/transport/index.mjs` | outgoing frames use the wrong envelope | killed |
+| M11 | sdk transport | `src/internal/websocket/transport/index.mjs` | answers to connector-initiated requests are never routed to their callback | killed |
+| M12 | sdk dispatch | `src/internal/dispatcher/index.mts` | configuration secrets are dropped before onConfig | killed |
+| M13 | sdk dispatch | `src/internal/dispatcher/index.mts` | sticky is not forwarded to the method | killed |
+| M14 | sdk dispatch | `src/internal/dispatcher/index.mts` | unknown methods are no longer reported as "not found" | killed |
+| M15 | sdk result return | `src/internal/dispatcher/index.mts` | scalar results are wrapped under the wrong key | killed |
+| M16 | sdk result return | `src/internal/util/index.mts` | successful results are replied empty | killed |
+| M17 | sdk result return | `src/internal/util/index.mts` | errors lose their message | killed |
+| M18 | sdk result return | `src/internal/connector/server/on-message.mts` | results are never sent back | killed |
+| M19 | sdk config | `src/internal/connector/server/on-connect/decrypt-config.mts` | config is decrypted for the wrong audience | killed |
+| M20 | sdk config | `src/internal/connector/server/on-connect/decrypt-config.mts` | plain fields are decrypted like secrets | killed |
+| M21 | sdk config | `src/internal/connector/server/on-connect/index.mts` | main() receives an empty config | killed |
+| M22 | harness vendor mock | `src/testing/vendor-mock.mts` | an unmocked request is answered instead of rejected | killed |
+| M23 | harness vendor mock | `src/testing/vendor-mock.mts` | verify() never fails | killed |
+| M24 | harness vendor mock | `src/testing/vendor-mock.mts` | mocked status codes are ignored | killed |
+| M25 | harness vendor mock | `src/testing/vendor-mock.mts` | the times limit on a route is ignored | killed |
+| M26 | harness network guard | `src/testing/network-guard.mts` | the network guard lets everything through (the mutant may try one TCP connect to the TEST-NET-3 documentation address 203.0.113.9) | killed |
+| M27 | harness fake ALOMA | `src/testing/fake-aloma.mts` | the fake accepts a connect without registration | killed |
+| M28 | harness fake ALOMA | `src/testing/fake-aloma.mts` | the fake encrypts config for the wrong audience | killed |
+| M29 | harness fake ALOMA | `src/testing/fake-aloma.mts` | the fake drops the connector's answer | killed |
+| M30 | harness fake ALOMA | `src/testing/fake-aloma.mts` | call() drops the ctx fields | killed |
+| M31 | harness | `src/testing/harness.mts` | stop() no longer fails on unmocked requests | killed |
+| M32 | harness | `src/testing/harness.mts` | the harness never sends configuration | killed |

package/test/dispatcher-ctx-forwarding.test.mjs

@@ -0,0 +1,161 @@
+import { Dispatcher } from '../build/internal/dispatcher/index.mjs';
+import { buildResolvers } from '../build/builder/runtime-context.mjs';
+
+// Simple test framework matching project convention
+const colors = {
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  reset: '\x1b[0m',
+  cyan: '\x1b[36m'
+};
+
+let passed = 0;
+let failed = 0;
+
+async function test(name, fn) {
+  try {
+    console.log(`${colors.cyan}Running: ${name}${colors.reset}`);
+    await fn();
+    console.log(`${colors.green}✓ PASS: ${name}${colors.reset}\n`);
+    passed++;
+  } catch (error) {
+    console.log(`${colors.red}✗ FAIL: ${name}${colors.reset}`);
+    console.log(`${colors.red}  Error: ${error.message}${colors.reset}\n`);
+    failed++;
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message || 'Assertion failed');
+}
+
+function assertEqual(actual, expected, message) {
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(message || `Expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+// Helper: build a dispatcher with given resolvers and execute a query+envelope.
+// IMPORTANT: this test passes taskId/namespace/sticky in the envelope to verify the
+// dispatcher destructures them and forwards them as a ctx object to handlers.
+async function buildAndExecute(resolvers, envelope) {
+  const dispatcher = new Dispatcher();
+  dispatcher.types({ fields: {} });
+  dispatcher.resolvers(resolvers);
+  dispatcher.main(async () => {});
+  const built = dispatcher.build();
+  return built.execute(envelope);
+}
+
+// --- RED TESTS for ctx forwarding (SDK v3.8.67 additive change) ---
+
+// Test 1: dispatcher.execute forwards ctx (taskId, namespace, sticky) to a NAMED METHOD handler
+//   as the second argument. Currently the dispatcher only passes `variables` — so the second
+//   arg is undefined and this test must FAIL (red) until the SDK is patched.
+await test('dispatcher forwards ctx as second arg to named-method handler', async () => {
+  let receivedArgs;
+  let receivedCtx;
+
+  // Use buildResolvers so the wrapper is exercised exactly as it is in production.
+  const mockController = {
+    myMethod: async (args, ctx) => {
+      receivedArgs = args;
+      receivedCtx = ctx;
+      return { ok: true };
+    },
+    '__autocomplete': async () => ({}),
+    '__endpoint': async () => ({}),
+    '__default': async () => ({}),
+  };
+  const methods = ['myMethod', '__autocomplete', '__endpoint', '__default'];
+  const resolvers = buildResolvers(methods, mockController);
+
+  await buildAndExecute(resolvers, {
+    query: ['myMethod'],
+    variables: { foo: 'bar' },
+    taskId: 'task-123',
+    namespace: 'testing',
+    sticky: 'sticky-abc',
+  });
+
+  assertEqual(receivedArgs, { foo: 'bar' }, 'args should be forwarded unchanged');
+  assert(receivedCtx !== undefined, 'ctx should be defined as second argument');
+  assertEqual(receivedCtx.taskId, 'task-123', `ctx.taskId should be "task-123", got ${JSON.stringify(receivedCtx)}`);
+  assertEqual(receivedCtx.namespace, 'testing', `ctx.namespace should be "testing", got ${JSON.stringify(receivedCtx)}`);
+  assertEqual(receivedCtx.sticky, 'sticky-abc', `ctx.sticky should be "sticky-abc", got ${JSON.stringify(receivedCtx)}`);
+});
+
+// Test 2: dispatcher.execute forwards ctx to the __default (fallback) handler as second arg
+//   when the named method is not found. Currently the __default invocation only receives the
+//   merged variables — so ctx is undefined and this test must FAIL (red) until patched.
+await test('dispatcher forwards ctx as second arg to __default fallback handler', async () => {
+  let receivedArg;
+  let receivedCtx;
+
+  // Resolvers map with ONLY __default — no named methods, so dispatcher falls back.
+  const resolvers = {
+    __default: async (arg, ctx) => {
+      receivedArg = arg;
+      receivedCtx = ctx;
+      return { fallback: true };
+    },
+  };
+
+  await buildAndExecute(resolvers, {
+    query: ['someUnknownMethod'],
+    variables: { hello: 'world' },
+    taskId: 'task-456',
+    namespace: 'testing',
+    sticky: 'sticky-def',
+  });
+
+  assert(receivedArg !== undefined, '__default should receive arg');
+  assertEqual(receivedArg.hello, 'world', 'variables should be merged into arg');
+  assertEqual(receivedArg.__method, ['someUnknownMethod'], '__method should be in arg');
+  assert(receivedCtx !== undefined, 'ctx should be defined as second argument to __default');
+  assertEqual(receivedCtx.taskId, 'task-456', `ctx.taskId should be "task-456", got ${JSON.stringify(receivedCtx)}`);
+  assertEqual(receivedCtx.namespace, 'testing', `ctx.namespace should be "testing"`);
+  assertEqual(receivedCtx.sticky, 'sticky-def', `ctx.sticky should be "sticky-def"`);
+});
+
+// Test 3: BACKWARD COMPATIBILITY. A controller method with the old 1-arg signature
+//   `async myMethod(args)` continues to work when called via the new dispatcher path.
+//   The second argument exists but is ignored. This test MUST PASS even in the red phase —
+//   if it fails red, the test setup is broken (not the implementation).
+await test('one-arg handler still works (backward compatibility)', async () => {
+  let receivedArgs;
+
+  const mockController = {
+    // Note: only one parameter. Second arg, if any, must be silently ignored.
+    legacyMethod: async (args) => {
+      receivedArgs = args;
+      return { legacy: true, ...args };
+    },
+    '__autocomplete': async () => ({}),
+    '__endpoint': async () => ({}),
+    '__default': async () => ({}),
+  };
+  const methods = ['legacyMethod', '__autocomplete', '__endpoint', '__default'];
+  const resolvers = buildResolvers(methods, mockController);
+
+  const result = await buildAndExecute(resolvers, {
+    query: ['legacyMethod'],
+    variables: { id: 7 },
+    taskId: 'task-789',
+    namespace: 'testing',
+    sticky: 'sticky-ghi',
+  });
+
+  assertEqual(receivedArgs, { id: 7 }, 'legacy handler should receive args unchanged');
+  assertEqual(result, { legacy: true, id: 7 }, 'legacy handler should return correct result');
+});
+
+// --- Results ---
+console.log(`\n${colors.yellow}--- Dispatcher ctx forwarding test results ---${colors.reset}`);
+console.log(`${colors.green}Passed: ${passed}${colors.reset}`);
+console.log(`${colors.red}Failed: ${failed}${colors.reset}`);
+
+if (failed > 0) {
+  process.exit(1);
+}

package/test/harness-connector-smoke.test.mjs

@@ -0,0 +1,72 @@
+// Handshake smoke test: the one file a connector repo adds (see "Testing a connector" in the SDK README).
+//
+// In a connector repo the RuntimeContext comes from the repo's own builder after `yarn build`:
+//     const context = await new Builder().config({...}).build();
+// Here the controller is defined inline so this file also tests the harness path used by connector repos.
+import {describe, it, afterEach} from 'mocha';
+import {expect} from 'chai';
+import {AbstractController} from '../build/index.mjs';
+import RuntimeContext from '../build/builder/runtime-context.mjs';
+import {ConnectorHarness, connectorFromRuntimeContext} from '../build/testing/index.mjs';
+
+const VENDOR = 'https://api.crm.example.test';
+
+class Controller extends AbstractController {
+  async getContact({id}) {
+    return this.getClient({baseUrl: VENDOR, retry: 1, customize: (r) => {
+      r.headers = {...r.headers, Authorization: `Bearer ${this.config.apiKey}`};
+    }}).fetch(`/contacts/${id}`, {method: 'GET'});
+  }
+}
+
+const context = () =>
+  new RuntimeContext(new Controller(), {
+    id: 'crm-connector',
+    version: '0.0.1',
+    methods: ['getContact'],
+    types: 'type Query { getContact(id: String): String }',
+    config: {fields: {apiKey: {name: 'API Key', type: 'line'}}},
+  });
+
+describe('crm-connector handshake smoke test', function () {
+  this.timeout(15000);
+  let harness;
+
+  afterEach(async () => {
+    // stop() also fails the test when the connector made a request that was not mocked
+    if (harness) await harness.stop();
+    harness = undefined;
+  });
+
+  it('registers, connects, starts and reports healthy', async () => {
+    harness = await ConnectorHarness.start({
+      connector: connectorFromRuntimeContext(context()),
+      config: {apiKey: 'fake-api-key-not-real'},
+    });
+
+    expect(harness.aloma.registration.id).to.equal('crm-connector');
+    expect(harness.aloma.registration.schema.configSchema.fields).to.have.property('apiKey');
+
+    const health = await harness.aloma.waitForPacket('connector.health.check');
+    expect(health.a).to.deep.equal({ok: true, error: null});
+  });
+
+  it('answers a method call from a recorded vendor response', async () => {
+    harness = await ConnectorHarness.start({
+      connector: connectorFromRuntimeContext(context()),
+      config: {apiKey: 'fake-api-key-not-real'},
+    });
+    harness.vendor.get(`${VENDOR}/contacts/42`, {json: {id: 42, email: 'jane@example.test'}});
+
+    expect(await harness.callOk('getContact', {id: 42})).to.deep.equal({id: 42, email: 'jane@example.test'});
+    expect(harness.vendor.requests[0].headers.authorization).to.equal('Bearer fake-api-key-not-real');
+  });
+
+  it('reports a missing configuration value as unhealthy', async () => {
+    harness = await ConnectorHarness.start({connector: connectorFromRuntimeContext(context()), config: {}});
+
+    const health = await harness.aloma.waitForPacket('connector.health.check');
+    expect(health.a.ok).to.equal(false);
+    expect(health.a.error).to.match(/API Key is required/);
+  });
+});