@aloma.io/integration-sdk 3.8.68 → 3.8.70

package/test/fixtures/transform/typed/expected.json

@@ -0,0 +1,8 @@
+{
+ "text": "\n/**\n * \n *\n * \n * \n **/    \ndeclare function typed({email; count; tags; mode; either; nested}: {\n/**\n\n */\n email: string; \n/**\n\n */\n count: any; \n/**\n\n */\n tags: string[]; \n/**\n\n */\n mode: any; \n/**\n\n */\n either: any; \n/**\n\n */\n nested: any}): { ok: boolean; tags: number[]; };\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function tuple(): [string, number];\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function maybe(): string | undefined;\n      ",
+ "methods": [
+  "typed",
+  "tuple",
+  "maybe"
+ ]
+}

package/test/fixtures/transform/typed/src/controller/abstract.mts

@@ -0,0 +1,5 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}

package/test/fixtures/transform/typed/src/controller/index.mts

@@ -0,0 +1,13 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  async typed({email, count, tags, mode, either, nested}: {email: string; count?: number; tags: string[]; mode: 'a' | 'b'; either: string | number; nested: {x: number}}) {
+    return {ok: true, tags: [1, 2]};
+  }
+  async tuple(): Promise<[string, number]> {
+    return ['a', 1];
+  }
+  async maybe(): Promise<string | undefined> {
+    return undefined;
+  }
+}

package/test/fixtures/transform/typed/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/fixtures/transform/visibility/expected.json

@@ -0,0 +1,9 @@
+{
+ "text": "\n/**\n * \n *\n * \n * \n **/    \ndeclare function visible({a}: {\n/**\n\n */\n a: string}): string;\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function quoted-name({a}: {\n/**\n\n */\n a: string}): void;\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function arrow({a}: {\n/**\n\n */\n a: string}): string;\n      \n/**\n * \n *\n * \n * \n **/    \ndeclare function inheritedPublic(): void;\n      ",
+ "methods": [
+  "visible",
+  "quoted-name",
+  "arrow",
+  "inheritedPublic"
+ ]
+}

package/test/fixtures/transform/visibility/src/controller/abstract.mts

@@ -0,0 +1,5 @@
+// stands in for AbstractController from @aloma.io/integration-sdk
+export class AbstractController {
+  protected config: any = {};
+  async inheritedPublic(): Promise<void> {}
+}

package/test/fixtures/transform/visibility/src/controller/index.mts

@@ -0,0 +1,19 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  async visible({a}: {a: string}) {
+    return a;
+  }
+  private async hidden({a}: {a: string}) {}
+  protected async guarded({a}: {a: string}) {}
+  static async stat({a}: {a: string}) {}
+  async _underscore({a}: {a: string}) {}
+  async 'quoted-name'({a}: {a: string}) {}
+  async '_quoted_private'({a}: {a: string}) {}
+  arrow = async ({a}: {a: string}) => a;
+  notAMethod = 5;
+  get getter() {
+    return 1;
+  }
+  override async inheritedPublic() {}
+}

package/test/fixtures/transform/visibility/tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"target":"es2022","module":"node16","moduleResolution":"node16","skipLibCheck":true,"strict":true,"noImplicitAny":false,"experimentalDecorators":true,"esModuleInterop":true},"include":["src/**/*"]}

package/test/openapi-to-connector.test.mts

@@ -138,6 +138,13 @@ paths:
       }).to.throw('Invalid OpenAPI 3.x specification');
     });
 
+    it('names the field that fails validation (zod 4 reports issues, not errors)', () => {
+      const missingTitle = {openapi: '3.0.0', info: {version: '1.0.0'}, paths: {}};
+      expect(() => {
+        OpenAPIToConnector.parseSpec(JSON.stringify(missingTitle));
+      }).to.throw(/Invalid OpenAPI 3\.x specification: info\.title: /);
+    });
+
     it('should reject invalid JSON/YAML', () => {
       expect(() => {
         OpenAPIToConnector.parseSpec('invalid json {');

package/test/transform.test.mjs

@@ -0,0 +1,68 @@
+// The transform reads a connector's controller source and returns the method declarations (`text`) and names
+// (`methods`) that `cli build` writes to build/.controller.json. It replaced @ts-ast-parser/core (engines stop at
+// Node 20), so most cases below are PARITY cases: expected.json was produced by the previous implementation (the
+// ts-ast-parser one, SDK 3.8.68) on the same source, and the new one must print exactly the same. The same check
+// ran on 58 real connector controllers (all of aloma-io/connector-*) with no difference.
+// Needs `yarn build` first. Offline.
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, it} from 'mocha';
+import transform from '../build/transform/index.mjs';
+
+const fixtures = path.join(path.dirname(fileURLToPath(import.meta.url)), 'fixtures', 'transform');
+
+// the transform reads tsconfig.json from the working directory, as `cli build` runs it from the connector folder
+const run = async (name) => {
+  const before = process.cwd();
+  process.chdir(path.join(fixtures, name));
+  try {
+    return await transform('./src/controller/index.mts');
+  } finally {
+    process.chdir(before);
+  }
+};
+
+const expected = (name) => JSON.parse(fs.readFileSync(path.join(fixtures, name, 'expected.json'), 'utf8'));
+
+describe('transform (controller source to declarations)', function () {
+  this.timeout(60000);
+
+  for (const [name, what] of [
+    ['basic', 'JSDoc description, @param, @example, @namespace, defaults, return types'],
+    ['visibility', 'public, private, protected, static, underscore, quoted names, arrow property, getter, inherited'],
+    ['typed', 'typed object parameters, unions, arrays, tuples, optional'],
+    ['overloads', 'one declaration per overload signature'],
+    ['tdd-stub', 'the real connector-tdd-stub controller'],
+  ]) {
+    it(`prints exactly what the previous implementation printed: ${name} (${what})`, async () => {
+      assert.deepEqual(await run(name), expected(name));
+    });
+  }
+
+  it('lists the public methods the class declares or overrides, not inherited, private, static or underscore ones', async () => {
+    const {methods} = await run('visibility');
+    assert.deepEqual(methods, ['visible', 'quoted-name', 'arrow', 'inheritedPublic']);
+  });
+
+  it('lists the properties of a parameter typed with an interface (the previous implementation crashed)', async () => {
+    const {text, methods} = await run('interface-param');
+    assert.deepEqual(methods, ['viaInterface']);
+    assert.match(text, /declare function viaInterface\(\{id; n\}: \{/);
+    assert.match(text, /\n id: string; /);
+    assert.match(text, /\n n: number \| undefined\}\): \{ id: string; n: number \| undefined; \};/);
+  });
+
+  it('fails when the file exports more than the default class', async () => {
+    await assert.rejects(run('two-exports'), /connector file needs to export default class/);
+  });
+
+  it('fails with the TypeScript error text when the source does not compile (the previous one died on a circular JSON error)', async () => {
+    await assert.rejects(run('type-error'), (err) => {
+      assert.match(err.message, /has TypeScript errors/);
+      assert.match(err.message, /index\.mts\(5,5\).*TS2322.*'string' is not assignable to type 'number'/);
+      return true;
+    });
+  });
+});

package/tools/mutation-run.mjs

@@ -2,8 +2,8 @@
 //
 //   yarn build && yarn test:mutation
 //
-// Applies each deliberate single-point bug below to src/, rebuilds, runs the harness tests and expects them
-// to FAIL. The original file is restored after every mutant (and on Ctrl-C). Writes test/MUTATION.md.
+// Applies each deliberate single-point bug below to src/, rebuilds, runs the harness tests (or, for the F mutants,
+// test/fetcher-query-params.test.mjs) and expects them to FAIL. The original file is restored after every mutant (and on Ctrl-C). Writes test/MUTATION.md.
 // Not part of CI: it rebuilds the SDK ~30 times. Run it when the harness or the SDK paths it covers change.
 import {spawnSync} from 'node:child_process';
 import fs from 'node:fs';
@@ -47,6 +47,19 @@ const MUTANTS = [
   ['M30', 'harness fake ALOMA', 'testing/fake-aloma.mts', "{query: method, variables, ...ctx}", "{query: method, variables}", 'call() drops the ctx fields'],
   ['M31', 'harness', 'testing/harness.mts', 'this.vendor.verify();', '', 'stop() no longer fails on unmocked requests'],
   ['M32', 'harness', 'testing/harness.mts', "await aloma.setConfig(options.config || {});", "", 'the harness never sends configuration'],
+  // PLAT-47: Fetcher query parameters, checked by test/fetcher-query-params.test.mjs
+  ['F01', 'sdk fetcher', 'internal/fetcher/fetcher.mts', 'const fullURL = withQuery(theURL, toQuery(options0.params));', 'const fullURL = theURL;', 'params are not sent at all (the PLAT-47 bug)'],
+  ['F02', 'sdk fetcher', 'internal/fetcher/fetcher.mts', 'if (Array.isArray(value)) value.forEach((item) => add(key, item));\n    else add(key, value);', 'add(key, value);', 'array handling dropped (arrays are refused as objects)'],
+  ['F03', 'sdk fetcher', 'internal/fetcher/fetcher.mts', 'if (Array.isArray(value)) value.forEach((item) => add(key, item));', "if (Array.isArray(value)) add(key, value.join(','));", 'arrays are comma-joined instead of repeated keys'],
+  ['F04', 'sdk fetcher', 'internal/fetcher/fetcher.mts', 'if (value == null) return;', 'if (value === null) return;', 'undefined values are not skipped'],
+  ['F05', 'sdk fetcher', 'internal/fetcher/fetcher.mts', 'if (value == null) return;', 'if (value === undefined) return;', 'null values are not skipped'],
+  ['F06', 'sdk fetcher', 'internal/fetcher/fetcher.mts', "    if (typeof value === 'object') {", '    if (false) {', 'nested objects are sent instead of refused'],
+  ['F07', 'sdk fetcher', 'internal/fetcher/fetcher.mts', 'if (e instanceof ParamsError) throw e;', '', 'a refused params object is retried'],
+  ['F08', 'sdk fetcher', 'internal/fetcher/fetcher.mts', "const sep = !base.includes('?') ? '?'", "const sep = true ? '?'", 'a query already in the url gets a second "?"'],
+  ['F09', 'sdk fetcher', 'internal/fetcher/fetcher.mts', '        ...init,\n', '        ...options0,\n', 'params is passed on to native fetch'],
+  ['F10', 'sdk fetcher', 'internal/fetcher/fetcher.mts', 'const {params, ...init} = options0;', 'const {params, ...init} = options0;\n      delete options0.params;', 'params are dropped from options0, so a retry loses the query'],
+  ['F11', 'sdk fetcher', 'internal/fetcher/fetcher.mts', "console.log(theURL.split('?')[0], e);", 'console.log(theURL, e);', 'a failed attempt logs query values'],
+  ['F12', 'sdk fetcher', 'internal/fetcher/fetcher.mts', 'if (params instanceof URLSearchParams) return params.toString();', '', 'a URLSearchParams instance is silently dropped'],
 ];
 
 const run = (cmd, args, timeout) =>
@@ -57,6 +70,8 @@ const build = () => {
   if (r.status !== 0) throw new Error('build failed:\n' + r.stdout + r.stderr);
 };
 const mocha = () => run('node', ['./node_modules/mocha/bin/_mocha', '--bail', '--exit', 'test/harness.test.mjs', 'test/harness-connector-smoke.test.mjs'], 150000);
+const fetcherTests = () => run('node', ['test/fetcher-query-params.test.mjs'], 150000);
+const testsFor = (id) => (id.startsWith('F') ? fetcherTests() : mocha());
 
 let current = null;
 const restore = () => {
@@ -73,6 +88,8 @@ try {
   build();
   const baseline = mocha();
   if (baseline.status !== 0) throw new Error('baseline run must pass before mutating:\n' + baseline.stdout.slice(-2000));
+  const fetcherBaseline = fetcherTests();
+  if (fetcherBaseline.status !== 0) throw new Error('fetcher baseline must pass:\n' + fetcherBaseline.stdout.slice(-2000));
 
   for (const [id, area, rel, find, replace, bug] of MUTANTS) {
     const file = src(rel);
@@ -85,8 +102,8 @@ try {
     try {
       fs.writeFileSync(file, original.replace(find, () => replace));
       build();
-      const r = mocha();
-      const failing = (r.stdout.match(/^\s+\d+\) .+$/gm) || [])[0]?.trim() || '';
+      const r = testsFor(id);
+      const failing = (r.stdout.match(/^\s+\d+\) .+$|FAIL: .+$/gm) || [])[0]?.trim() || '';
       outcome = r.error?.code === 'ETIMEDOUT' ? 'killed (timeout)' : r.status !== 0 ? 'killed' : 'SURVIVED';
       results.push({id, area, rel, bug, outcome, by: failing});
     } finally {
@@ -107,7 +124,8 @@ const md = [
   '',
   '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',
+  'runs `test/harness.test.mjs` with `--bail` (F rows: `test/fetcher-query-params.test.mjs`), 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 |',