@superdurable/connectors-sdk 0.0.0-stage → 0.1.0

package/dist/connectormock/index.js

@@ -0,0 +1,350 @@
+import {
+  validateMutationDefinition,
+  validateQueryDefinition
+} from "../chunk-2NBM7P4T.js";
+import {
+  DefectBranchID,
+  FailureSchema,
+  UncertainBranchID,
+  newMutationBranch,
+  newMutationRetry,
+  newMutationUncertain,
+  newQueryBranch,
+  newQueryRetry,
+  zeroReceipt
+} from "../chunk-SOXYPIMO.js";
+
+// src/connectormock/index.ts
+import { readFile } from "fs/promises";
+import { isDeepStrictEqual } from "util";
+import { z } from "zod";
+
+// src/connectormock/scripted.ts
+var Script = class {
+  rules = [];
+  queue = [];
+  defaults = [];
+  defaultCount = 0;
+  nextScripted(input) {
+    for (const rule of this.rules) if (rule.matches(input)) return rule.response;
+    return this.queue.shift();
+  }
+  nextDefault() {
+    if (!this.defaults.length) return void 0;
+    return this.defaults[Math.min(this.defaultCount++, this.defaults.length - 1)];
+  }
+};
+var FlowScript = class {
+  #owner;
+  #script;
+  /** Capture one Flow prefix and its owning operation. */
+  constructor(owner, script) {
+    this.#owner = owner;
+    this.#script = script;
+  }
+  /** Queue one case per matching call. */
+  respond(...cases) {
+    this.#owner.addResponses(this.#script, cases);
+    return this;
+  }
+  /** Use a persistent input predicate before queued cases. */
+  when(matches, response) {
+    this.#owner.addRule(this.#script, matches, response);
+    return this;
+  }
+  /** Replace fallback cases; the last case repeats. */
+  default(...cases) {
+    this.#owner.setDefaults(this.#script, cases);
+    return this;
+  }
+};
+var ScriptedOperation = class {
+  #definition;
+  #isMutation;
+  #options;
+  #unscoped = new Script();
+  #flowScripts = /* @__PURE__ */ new Map();
+  #terminalByKey = /* @__PURE__ */ new Map();
+  #calls = [];
+  #failures = [];
+  #isStrict = false;
+  /** Validate the real operation definition and capture test checks. */
+  constructor(definition, isMutation, options = {}) {
+    if (isMutation) validateMutationDefinition(definition);
+    else validateQueryDefinition(definition);
+    if (options.answerCheck && !definition.branches.some((branch) => branch.id === options.answerCheck?.branch)) throw new TypeError("mock answer check branch is not declared");
+    this.#definition = definition;
+    this.#isMutation = isMutation;
+    this.#options = options;
+  }
+  /** Queue cases on the unscoped script. */
+  respond(...cases) {
+    this.addResponses(this.#unscoped, cases);
+    return this;
+  }
+  /** Add a persistent input predicate on the unscoped script. */
+  when(matches, response) {
+    this.addRule(this.#unscoped, matches, response);
+    return this;
+  }
+  /** Replace unscoped fallback cases; the last repeats. */
+  default(...cases) {
+    this.setDefaults(this.#unscoped, cases);
+    return this;
+  }
+  /** Require a Respond or When case for every call, ignoring all defaults. */
+  strict() {
+    this.#isStrict = true;
+    return this;
+  }
+  /** Select a script by exact Flow ID or prefix; longest prefixes win. */
+  forFlow(flowIdOrPrefix) {
+    if (!flowIdOrPrefix.trim()) throw new TypeError("mock ForFlow requires a Flow ID or prefix");
+    const existing = this.#flowScripts.get(flowIdOrPrefix);
+    if (existing) return existing.publicScript;
+    const script = new Script();
+    const publicScript = new FlowScript(this, script);
+    this.#flowScripts.set(flowIdOrPrefix, { script, publicScript });
+    return publicScript;
+  }
+  /** Copy answered calls in answer order, including retries and replays. */
+  calls() {
+    return [...this.#calls];
+  }
+  /** Copy scripting errors; callers can assert after a real Flow completes. */
+  failures() {
+    return [...this.#failures];
+  }
+  /** Throw after integration verification if a script was invalid or unscripted. */
+  assertNoFailures() {
+    if (this.#failures.length) throw new Error(this.#failures.join("\n"));
+  }
+  /** Add validated ordered responses to a script. */
+  addResponses(script, cases) {
+    for (const response of cases) this.#reportCaseProblem(response);
+    script.queue.push(...cases);
+  }
+  /** Add a validated persistent predicate to a script. */
+  addRule(script, matches, response) {
+    if (!matches) throw new TypeError("mock When requires an input predicate");
+    this.#reportCaseProblem(response);
+    script.rules.push({ matches, response });
+  }
+  /** Replace a script's fallback cases. */
+  setDefaults(script, cases) {
+    for (const response of cases) this.#reportCaseProblem(response);
+    script.defaults = [...cases];
+    script.defaultCount = 0;
+  }
+  /** Answer one real SDK invocation and record its safe outcome. */
+  answer(call, input, idempotencyKey) {
+    const flowId = call.context.flowId;
+    let resolved;
+    const requestFailure = this.#options.requestCheck?.(input);
+    if (requestFailure) {
+      resolved = { response: { kind: "branch", branch: DefectBranchID, value: void 0, failure: this.#completeFailure(requestFailure) }, branch: DefectBranchID };
+    } else {
+      const remembered = idempotencyKey ? this.#terminalByKey.get(idempotencyKey) : void 0;
+      if (remembered) resolved = { ...remembered, isReplay: true };
+      else {
+        resolved = this.#selectCase(flowId, input);
+        const answerCheck = this.#options.answerCheck;
+        if (answerCheck && resolved.response.kind === "branch" && resolved.branch === answerCheck.branch) {
+          try {
+            answerCheck.check(input, resolved.response.value);
+          } catch {
+            this.#reportFailure("connector mock answer does not match request");
+            resolved = this.#defectCase("connector mock answer does not match request");
+          }
+        }
+        if (idempotencyKey && resolved.response.kind !== "retry") this.#terminalByKey.set(idempotencyKey, resolved);
+      }
+    }
+    const response = resolved.response;
+    const record = {
+      connectorId: this.#definition.operation.connectorId,
+      operationId: this.#definition.operation.operationId,
+      connectionName: call.connection.name,
+      flowId,
+      callId: call.id,
+      input,
+      ...call.idempotencyKey ? { idempotencyKey: call.idempotencyKey } : {},
+      ...resolved.branch ? { branch: resolved.branch } : {},
+      ...response.kind === "retry" ? { retry: true } : {},
+      ...resolved.isReplay ? { replay: true } : {},
+      ...resolved.isUnscripted ? { unscripted: true } : {}
+    };
+    this.#calls.push(record);
+    return resolved;
+  }
+  #selectCase(flowId, input) {
+    const scripts = [...this.#flowScripts.entries()].filter(([prefix]) => flowId.startsWith(prefix)).sort(([left], [right]) => right.length - left.length).map(([, entry]) => entry.script);
+    scripts.push(this.#unscoped);
+    for (const script of scripts) {
+      const response = script.nextScripted(input);
+      if (response) return this.#resolveCase(response);
+    }
+    if (!this.#isStrict) for (const script of scripts) {
+      const response = script.nextDefault();
+      if (response) return this.#resolveCase(response);
+    }
+    this.#reportFailure(`unscripted call for Flow ${flowId}`);
+    return { ...this.#defectCase("unscripted connector mock call"), isUnscripted: true };
+  }
+  #resolveCase(response) {
+    const problem = this.#caseProblem(response);
+    if (problem) return this.#defectCase(problem);
+    if (response.kind === "retry") return { response: { ...response, failure: this.#completeFailure(response.failure) } };
+    if (response.kind === "uncertain") return { response: { ...response, failure: this.#completeFailure(response.failure) }, branch: UncertainBranchID };
+    return { response: response.failure ? { ...response, failure: this.#completeFailure(response.failure) } : response, branch: response.branch };
+  }
+  #defectCase(message) {
+    return { response: { kind: "branch", branch: DefectBranchID, value: void 0, failure: { kind: "LOCAL_DEFECT", provider: this.#definition.operation.connectorId, operation: this.#definition.operation.operationId, message } }, branch: DefectBranchID };
+  }
+  #reportCaseProblem(response) {
+    const problem = this.#caseProblem(response);
+    if (problem) this.#reportFailure(problem);
+  }
+  #caseProblem(response) {
+    if (response.kind === "branch" && !this.#definition.branches.some((branch) => branch.id === response.branch)) return `branch ${response.branch} is not declared by the operation`;
+    if (response.kind === "uncertain" && (!this.#isMutation || !this.#definition.branches.some((branch) => branch.id === UncertainBranchID))) return "an uncertain case requires a mutation uncertain branch";
+    if (response.kind === "retry" && (!Number.isSafeInteger(response.retryAfterMs) || response.retryAfterMs < 0)) return "the retry delay is invalid";
+    if ("failure" in response && response.failure && !FailureSchema.safeParse(this.#completeFailure(response.failure)).success) return "the case failure is invalid";
+    return void 0;
+  }
+  #completeFailure(failure) {
+    return { ...failure, provider: failure.provider || this.#definition.operation.connectorId, operation: failure.operation || this.#definition.operation.operationId };
+  }
+  #reportFailure(message) {
+    const safeMessage = `connector mock ${this.#definition.operation.connectorId}.${this.#definition.operation.operationId}: ${message}`;
+    this.#failures.push(safeMessage);
+    this.#options.onFailure?.(safeMessage);
+  }
+};
+var MockQuery = class extends ScriptedOperation {
+  #definition;
+  /** Construct from the real query definition. */
+  constructor(definition, options) {
+    super(definition, false, options);
+    this.#definition = definition;
+  }
+  /** Return the real query definition. */
+  definition() {
+    return this.#definition;
+  }
+  /** Answer one query call from the script. */
+  invoke(call, input) {
+    const response = this.answer(call, input, "").response;
+    if (response.kind === "retry") return newQueryRetry(response.failure, response.retryAfterMs);
+    if (response.kind === "uncertain") return newQueryBranch(DefectBranchID, void 0, zeroReceipt(), { kind: "LOCAL_DEFECT", provider: call.operation.connectorId, operation: call.operation.operationId, message: "query mock cannot return uncertainty" });
+    return newQueryBranch(response.branch, response.value, zeroReceipt(), response.failure);
+  }
+};
+var MockMutation = class extends ScriptedOperation {
+  #definition;
+  /** Construct from the real mutation definition. */
+  constructor(definition, options) {
+    super(definition, true, options);
+    this.#definition = definition;
+  }
+  /** Return the real mutation definition. */
+  definition() {
+    return this.#definition;
+  }
+  /** Use the stable SDK call ID as the provider deduplication key. */
+  idempotencyKey(callId) {
+    return callId;
+  }
+  /** Answer one mutation call and remember terminal outcomes by key. */
+  invoke(call, input) {
+    const response = this.answer(call, input, call.idempotencyKey ?? "").response;
+    if (response.kind === "retry") return newMutationRetry(response.failure, response.retryAfterMs);
+    if (response.kind === "uncertain") return newMutationUncertain(response.value, response.failure, zeroReceipt());
+    return newMutationBranch(response.branch, response.value, zeroReceipt(), response.failure);
+  }
+};
+function newQuery(definition, options) {
+  return new MockQuery(definition, options);
+}
+function newMutation(definition, options) {
+  return new MockMutation(definition, options);
+}
+
+// src/connectormock/index.ts
+var ReportDirectoryEnvironment = "DEX_CONNECTOR_MOCK_REPORT_DIR";
+var ReportFileName = "connector-calls.json";
+function branchCase(branch, value, failure) {
+  if (!branch) throw new TypeError("mock branch is required");
+  return failure ? { kind: "branch", branch, value, failure: FailureSchema.parse(failure) } : { kind: "branch", branch, value };
+}
+function retryCase(failure, retryAfterMs = 0) {
+  if (!Number.isSafeInteger(retryAfterMs) || retryAfterMs < 0) throw new RangeError("mock retry delay is invalid");
+  return { kind: "retry", failure: FailureSchema.parse(failure), retryAfterMs };
+}
+function uncertainCase(value, failure) {
+  return { kind: "uncertain", branch: UncertainBranchID, value, failure: FailureSchema.parse(failure) };
+}
+var RecordedCallSchema = z.strictObject({
+  connectorId: z.string().min(1),
+  operationId: z.string().min(1),
+  connectionName: z.string().min(1),
+  flowId: z.string(),
+  callId: z.uuid(),
+  branch: z.string().optional(),
+  retry: z.boolean().optional(),
+  replay: z.boolean().optional(),
+  unscripted: z.boolean().optional()
+});
+var ReportRowSchema = z.strictObject({
+  connection: z.string(),
+  operation: z.string(),
+  branch: z.string().optional(),
+  connectorId: z.string(),
+  flowId: z.string().optional(),
+  callId: z.string().optional(),
+  retry: z.boolean().optional(),
+  replay: z.boolean().optional(),
+  unscripted: z.boolean().optional()
+});
+var CallReportSchema = z.strictObject({ calls: z.array(ReportRowSchema) });
+function decodeOutput(encoded, outputSchema) {
+  let document;
+  try {
+    document = JSON.parse(encoded);
+  } catch {
+    throw new TypeError("mock output fixture is not valid JSON");
+  }
+  const parsed = outputSchema.safeParse(document);
+  if (!parsed.success || !isDeepStrictEqual(parsed.data, document)) throw new TypeError("mock output fixture violates the output schema");
+  return parsed.data;
+}
+async function loadOutputFixture(path, outputSchema) {
+  return decodeOutput(await readFile(path, "utf8"), outputSchema);
+}
+function decodeCallReport(encoded) {
+  let document;
+  try {
+    document = JSON.parse(encoded);
+  } catch {
+    throw new TypeError("connector call report is not valid JSON");
+  }
+  return CallReportSchema.parse(document);
+}
+export {
+  CallReportSchema,
+  FlowScript,
+  MockMutation,
+  MockQuery,
+  RecordedCallSchema,
+  ReportDirectoryEnvironment,
+  ReportFileName,
+  ReportRowSchema,
+  branchCase,
+  decodeCallReport,
+  decodeOutput,
+  loadOutputFixture,
+  newMutation,
+  newQuery,
+  retryCase,
+  uncertainCase
+};