@aloma.io/integration-sdk 3.8.68 → 3.8.69

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

@@ -0,0 +1,30 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  /**
+   * greet somebody
+   * @param name - who to greet, e.g. Ann
+   * @param times - how often
+   * @param opts - extra \@options
+   * @namespace demo
+   *
+   * @example
+   * ```javascript
+   * greet({name: 'Ann'})
+   * ```
+   */
+  async greet({name, times = 2, loud = false, label = 'x', neg = -1, nothing = null}, other = 1) {
+    return {ok: true, greeting: name + times};
+  }
+
+  /** no params */
+  async ping() {
+    return {ok: true};
+  }
+
+  async list(): Promise<string[]> {
+    return [];
+  }
+
+  async nothing(): Promise<void> {}
+}

package/test/fixtures/transform/basic/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/interface-param/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/interface-param/src/controller/index.mts

@@ -0,0 +1,12 @@
+import {AbstractController} from './abstract.mjs';
+
+interface Opts {
+  id: string;
+  n?: number;
+}
+
+export default class Controller extends AbstractController {
+  async viaInterface({id, n}: Opts): Promise<{id: string; n: number | undefined}> {
+    return {id, n};
+  }
+}

package/test/fixtures/transform/interface-param/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/overloads/expected.json

@@ -0,0 +1,6 @@
+{
+ "text": "\n/**\n * first form\n *\n * \n * \n **/    \ndeclare function over({a}: {\n/**\n\n */\n a: string}): string;\n      \n\n/**\n * second form\n *\n * \n * \n **/    \ndeclare function over({b}: {\n/**\n\n */\n b: number}): number;\n      ",
+ "methods": [
+  "over"
+ ]
+}

package/test/fixtures/transform/overloads/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/overloads/src/controller/index.mts

@@ -0,0 +1,11 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  /** first form */
+  async over({a}: {a: string}): Promise<string>;
+  /** second form */
+  async over({b}: {b: number}): Promise<number>;
+  async over(args: any): Promise<any> {
+    return args;
+  }
+}

package/test/fixtures/transform/overloads/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/tdd-stub/expected.json

@@ -0,0 +1,8 @@
+{
+ "text": "\n/**\n * Returns recorded calls scoped to the current task.\n *\n * \n * @example usage\n```javascript\nconst log = await connectors.testing.getCallLog({})\n// log.calls = [{method, args, timestamp}, ...] for THIS task only\n```\n **/    \ndeclare function getCallLog(): { calls: CallRecord[]; count: number; };\n      \n/**\n * Resets the call log for the current task only.\n *\n * \n * @example usage\n```javascript\nawait connectors.testing.clearCallLog({})\n```\n **/    \ndeclare function clearCallLog(): { cleared: boolean; };\n      \n/**\n * Updates the response map for the current task at runtime.\n *\n * \n * @example usage\n```javascript\nawait connectors.testing.setResponses({\n  responses: { \"someConnector.create\": { id: \"456\" } }\n})\n```\n **/    \ndeclare function setResponses(): { updated: boolean; responseCount: number; };\n      ",
+ "methods": [
+  "getCallLog",
+  "clearCallLog",
+  "setResponses"
+ ]
+}

package/test/fixtures/transform/tdd-stub/src/controller/abstract.mts

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

package/test/fixtures/transform/tdd-stub/src/controller/index.mts

@@ -0,0 +1,204 @@
+import { AbstractController } from "./abstract.mjs";
+
+interface CallRecord {
+  method: string;
+  args: any;
+  timestamp: string;
+}
+
+/**
+ * Per-task scoped mock connector for ALOMA test workflows.
+ *
+ * State (responseMap, callLog) is keyed by ctx.taskId so concurrent
+ * test tasks against the same Testing pod do not contaminate each
+ * other's stubbed responses or recorded calls.
+ *
+ * Requires @aloma.io/integration-sdk ^3.8.67, which forwards
+ * { taskId, namespace, sticky } as the second arg to controller
+ * method handlers and to the __default fallback.
+ *
+ * Backward compatibility: when ctx is missing (legacy invocation or
+ * non-task call from admin UI), state falls into the "__no_ctx__"
+ * bucket so the connector does not crash. Isolation is NOT guaranteed
+ * in that mode — it is degraded compatibility only.
+ */
+export default class Controller extends AbstractController {
+  // Per-task scoped state — Maps keyed by taskId (insertion order = LRU order)
+  private responseMapByTask: Map<string, Record<string, any>> = new Map();
+  private callLogByTask: Map<string, CallRecord[]> = new Map();
+  private recording: boolean = true;
+  private defaultResponses: Record<string, any> = {};
+  // Memory cap (LRU). Configurable via config.maxTasks; default 1000.
+  private maxTasks: number = 1000;
+
+  protected async start() {
+    this.loadConfig();
+  }
+
+  private loadConfig() {
+    const config = this.config;
+
+    // Parse default responses from connector config — these seed each
+    // task's bucket when first touched.
+    if (config.responses) {
+      try {
+        this.defaultResponses =
+          typeof config.responses === "string"
+            ? JSON.parse(config.responses)
+            : config.responses;
+      } catch (e) {
+        this.defaultResponses = {};
+      }
+    } else {
+      this.defaultResponses = {};
+    }
+
+    this.recording = config.recordCalls !== "false";
+
+    // Allow config-driven override of LRU cap. Default 1000 if not set
+    // or not a positive number.
+    const configured = Number(config.maxTasks);
+    if (Number.isFinite(configured) && configured > 0) {
+      this.maxTasks = Math.floor(configured);
+    }
+  }
+
+  /**
+   * Resolve the bucket key for the current invocation. When ctx is
+   * absent or lacks taskId, falls back to a single shared bucket so
+   * legacy / hand-rolled callers do not crash. Isolation is not
+   * guaranteed in that mode.
+   */
+  private bucketKey(ctx?: { taskId?: string }): string {
+    return ctx && ctx.taskId ? ctx.taskId : "__no_ctx__";
+  }
+
+  /**
+   * LRU touch — ensures the bucket exists for the given key, evicting
+   * the least-recently-used entry if the cap would be exceeded. Map
+   * iteration order is insertion order; reinserting promotes a key to
+   * "most recently used" position.
+   */
+  private touchTask(key: string) {
+    // If not present and at cap, evict the oldest (insertion order)
+    if (!this.responseMapByTask.has(key)) {
+      if (this.responseMapByTask.size >= this.maxTasks) {
+        const firstKey = this.responseMapByTask.keys().next().value as
+          | string
+          | undefined;
+        if (firstKey !== undefined) {
+          this.responseMapByTask.delete(firstKey);
+          this.callLogByTask.delete(firstKey);
+        }
+      }
+      this.responseMapByTask.set(key, { ...this.defaultResponses });
+      this.callLogByTask.set(key, []);
+    }
+  }
+
+  /**
+   * Catch-all handler — registered as __default by the SDK via the
+   * fallback override below. Looks up the response in the task-scoped
+   * map, records the call in the task-scoped log, and returns the
+   * configured response or a default stub acknowledgement.
+   */
+  private async handleStubCall(
+    arg: any,
+    ctx?: { taskId?: string },
+  ): Promise<any> {
+    const key = this.bucketKey(ctx);
+    this.touchTask(key);
+
+    const method = Array.isArray(arg?.__method)
+      ? arg.__method.join(".")
+      : arg?.__method || "unknown";
+
+    if (this.recording) {
+      const log = this.callLogByTask.get(key)!;
+      log.push({
+        method,
+        args: { ...arg, __method: undefined },
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    const responseMap = this.responseMapByTask.get(key)!;
+    if (responseMap[method] !== undefined) {
+      return responseMap[method];
+    }
+    if (responseMap["default"] !== undefined) {
+      return responseMap["default"];
+    }
+
+    return { stubbed: true, method };
+  }
+
+  /**
+   * SDK override hook — invoked by AbstractController.__default with
+   * the per-invocation ctx (taskId, namespace, sticky) as second arg.
+   */
+  protected fallback(arg: any, ctx?: { taskId?: string }): Promise<any> {
+    return this.handleStubCall(arg, ctx);
+  }
+
+  /**
+   * Returns recorded calls scoped to the current task.
+   * @example
+   * ```javascript
+   * const log = await connectors.testing.getCallLog({})
+   * // log.calls = [{method, args, timestamp}, ...] for THIS task only
+   * ```
+   */
+  async getCallLog(_args: any, ctx?: { taskId?: string }) {
+    const key = this.bucketKey(ctx);
+    const calls = this.callLogByTask.get(key) || [];
+    return { calls: [...calls], count: calls.length };
+  }
+
+  /**
+   * Resets the call log for the current task only.
+   * @example
+   * ```javascript
+   * await connectors.testing.clearCallLog({})
+   * ```
+   */
+  async clearCallLog(_args: any, ctx?: { taskId?: string }) {
+    const key = this.bucketKey(ctx);
+    if (this.callLogByTask.has(key)) {
+      this.callLogByTask.set(key, []);
+    }
+    return { cleared: true };
+  }
+
+  /**
+   * Updates the response map for the current task at runtime.
+   * @example
+   * ```javascript
+   * await connectors.testing.setResponses({
+   *   responses: { "someConnector.create": { id: "456" } }
+   * })
+   * ```
+   */
+  async setResponses(args: any, ctx?: { taskId?: string }) {
+    const key = this.bucketKey(ctx);
+    this.touchTask(key);
+
+    if (args?.responses) {
+      try {
+        const newResponses =
+          typeof args.responses === "string"
+            ? JSON.parse(args.responses)
+            : args.responses;
+        const existing = this.responseMapByTask.get(key)!;
+        this.responseMapByTask.set(key, { ...existing, ...newResponses });
+      } catch (e) {
+        // ignore parse errors — leave existing map untouched
+      }
+    }
+
+    return {
+      updated: true,
+      responseCount: Object.keys(this.responseMapByTask.get(key)!).length,
+    };
+  }
+}

package/test/fixtures/transform/tdd-stub/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/two-exports/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/two-exports/src/controller/index.mts

@@ -0,0 +1,9 @@
+import {AbstractController} from './abstract.mjs';
+
+export interface Extra {
+  a: string;
+}
+
+export default class Controller extends AbstractController {
+  async one() {}
+}

package/test/fixtures/transform/two-exports/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/type-error/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/type-error/src/controller/index.mts

@@ -0,0 +1,7 @@
+import {AbstractController} from './abstract.mjs';
+
+export default class Controller extends AbstractController {
+  async one(): Promise<number> {
+    return 'not a number';
+  }
+}

package/test/fixtures/transform/type-error/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/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/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;
+    });
+  });
+});