@codemation/core-nodes 0.4.2 → 0.6.0

package/src/credentials/OAuth2TokenExchangeFactory.ts

@@ -0,0 +1,52 @@
+/**
+ * Performs an OAuth2 `client_credentials` token exchange against a token endpoint
+ * and returns the resulting access token.
+ *
+ * Lives in a Factory file so the body URLSearchParams construction is allowed at
+ * the composition root.
+ */
+export type OAuth2ClientCredentialsArgs = Readonly<{
+  tokenUrl: string;
+  clientId: string;
+  clientSecret: string;
+  scopes: string;
+  audience: string;
+}>;
+
+export class OAuth2TokenExchangeFactory {
+  async create(args: OAuth2ClientCredentialsArgs): Promise<string> {
+    const body = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: args.clientId,
+    });
+    if (args.scopes) {
+      body.set("scope", args.scopes);
+    }
+    if (args.audience) {
+      body.set("audience", args.audience);
+    }
+
+    const encoded = Buffer.from(`${args.clientId}:${args.clientSecret}`).toString("base64");
+
+    const response = await globalThis.fetch(args.tokenUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/x-www-form-urlencoded",
+        authorization: `Basic ${encoded}`,
+      },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(`Token exchange failed (${response.status} ${response.statusText}): ${text}`);
+    }
+
+    const json = (await response.json()) as Record<string, unknown>;
+    const token = String(json["access_token"] ?? "");
+    if (!token) {
+      throw new Error("Token exchange response did not include an access_token.");
+    }
+    return token;
+  }
+}

package/src/credentials/index.ts

@@ -0,0 +1,4 @@
+export { apiKeyCredentialType } from "./ApiKeyCredentialType";
+export { basicAuthCredentialType } from "./BasicAuthCredentialType";
+export { bearerTokenCredentialType } from "./BearerTokenCredentialType";
+export { oauth2ClientCredentialsType } from "./OAuth2ClientCredentialsTypeFactory";

package/src/http/HttpBodyBuilder.ts

@@ -0,0 +1,90 @@
+import type { Item, NodeExecutionContext } from "@codemation/core";
+import type { RunnableNodeConfig } from "@codemation/core";
+import type { HttpBodySpec } from "./httpRequest.types";
+
+export type EncodedBody = Readonly<{
+  body: NonNullable<RequestInit["body"]>;
+  /**
+   * Desired Content-Type header. Empty string means `fetch` should set it automatically
+   * (used for multipart/form-data so the boundary is set correctly by the browser/Node runtime).
+   */
+  contentType: string;
+}>;
+
+/**
+ * Builds a fetch-compatible `BodyInit` + Content-Type pair from an {@link HttpBodySpec}.
+ * Multipart binaries are read from `item.binary` via `ctx.binary.openReadStream`.
+ */
+export class HttpBodyBuilder {
+  async build(
+    spec: HttpBodySpec | undefined,
+    item: Item,
+    ctx: NodeExecutionContext<RunnableNodeConfig<unknown, unknown>>,
+  ): Promise<EncodedBody | undefined> {
+    if (!spec || spec.kind === "none") {
+      return undefined;
+    }
+
+    if (spec.kind === "json") {
+      return {
+        body: JSON.stringify(spec.data),
+        contentType: "application/json",
+      };
+    }
+
+    if (spec.kind === "form") {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(spec.data)) {
+        params.append(key, value);
+      }
+      return {
+        body: params.toString(),
+        contentType: "application/x-www-form-urlencoded",
+      };
+    }
+
+    if (spec.kind === "multipart") {
+      const formData = new FormData();
+      for (const [key, value] of Object.entries(spec.fields)) {
+        formData.append(key, value);
+      }
+      if (spec.binaries) {
+        for (const [fieldName, binaryRef] of Object.entries(spec.binaries)) {
+          const attachment = item.binary?.[binaryRef];
+          if (attachment) {
+            const readResult = await ctx.binary.openReadStream(attachment);
+            if (readResult) {
+              const reader = readResult.body.getReader();
+              const chunks: Uint8Array[] = [];
+              let done = false;
+              while (!done) {
+                const result = await reader.read();
+                done = result.done;
+                if (result.value) {
+                  chunks.push(result.value);
+                }
+              }
+              const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+              const merged = new Uint8Array(totalLength);
+              let offset = 0;
+              for (const chunk of chunks) {
+                merged.set(chunk, offset);
+                offset += chunk.length;
+              }
+              const blob = new Blob([merged], { type: attachment.mimeType });
+              formData.append(fieldName, blob, attachment.filename ?? binaryRef);
+            }
+          }
+        }
+      }
+      // FormData sets its own Content-Type with boundary; empty string signals that
+      // fetch should set it automatically.
+      return {
+        body: formData,
+        contentType: "",
+      };
+    }
+
+    return undefined;
+  }
+}

package/src/http/HttpRequestExecutor.ts

@@ -0,0 +1,150 @@
+import type { Item } from "@codemation/core";
+import type { HttpRequestResult, HttpRequestSpec } from "./httpRequest.types";
+import type { HttpBodyBuilder } from "./HttpBodyBuilder";
+import type { HttpUrlBuilder } from "./HttpUrlBuilder";
+
+/**
+ * Executes a single HTTP request described by {@link HttpRequestSpec}.
+ *
+ * - Credential sessions provide header/query deltas via `applyToRequest`.
+ * - Body encoding is delegated to {@link HttpBodyBuilder}.
+ * - URL query merging is delegated to {@link HttpUrlBuilder}.
+ * - Binary response bodies: when `download.mode` triggers binary attach, the
+ *   `bodyBinaryName` field is set in the result but the body is NOT read here.
+ *   Callers that need binary attachment should use `buildRequest` to get the
+ *   resolved URL + init and make the fetch + binary attach themselves.
+ *
+ * Collaborators (`fetch`, body builder, url builder) are injected so callers
+ * own construction at composition roots and tests can supply deterministic stubs.
+ */
+export class HttpRequestExecutor {
+  constructor(
+    private readonly fetchFn: typeof globalThis.fetch,
+    private readonly bodyBuilder: HttpBodyBuilder,
+    private readonly urlBuilder: HttpUrlBuilder,
+  ) {}
+
+  /**
+   * Builds the fetch init (headers, query, body) from the spec + credential delta,
+   * returning both the resolved URL and the RequestInit so callers can make the
+   * actual fetch call themselves (useful for streaming / binary attach).
+   */
+  async buildRequest(spec: HttpRequestSpec, item: Item): Promise<Readonly<{ url: string; init: RequestInit }>> {
+    const credentialDelta = spec.credential?.applyToRequest(spec) ?? {};
+
+    const mergedHeaders: Record<string, string> = {
+      ...(spec.headers ?? {}),
+      ...(credentialDelta.headers ?? {}),
+    };
+
+    const mergedQuery: Record<string, string | string[]> = {
+      ...(spec.query ?? {}),
+      ...(credentialDelta.query ?? {}),
+    };
+
+    const encodedBody = await this.bodyBuilder.build(spec.body, item, spec.ctx);
+
+    // Only set Content-Type from the encoded body when it is non-empty
+    // (empty string = FormData will set it automatically).
+    if (encodedBody && encodedBody.contentType) {
+      mergedHeaders["content-type"] = encodedBody.contentType;
+    }
+
+    const resolvedUrl = this.urlBuilder.build(spec.url, mergedQuery);
+
+    const init: RequestInit = {
+      method: spec.method,
+      headers: mergedHeaders,
+      ...(encodedBody ? { body: encodedBody.body } : {}),
+    };
+
+    return { url: resolvedUrl, init };
+  }
+
+  /**
+   * Executes an HTTP request and returns parsed result.
+   * For binary downloads (when `shouldAttachBody` is true), the body is NOT consumed
+   * and callers must call `ctx.binary.attach` directly using the resolved URL + init
+   * (available via `buildRequest`).
+   */
+  async execute(spec: HttpRequestSpec, item: Item): Promise<HttpRequestResult> {
+    const { url: resolvedUrl, init } = await this.buildRequest(spec, item);
+
+    const response = await this.fetchFn(resolvedUrl, init);
+
+    const responseHeaders = this.readHeaders(response.headers);
+    const mimeType = this.resolveMimeType(responseHeaders);
+
+    const downloadMode = spec.download?.mode ?? "auto";
+    const binaryName = spec.download?.binaryName ?? "body";
+    const shouldDownload = this.shouldAttachBody(downloadMode, mimeType);
+
+    const isJson = this.isJsonMimeType(mimeType);
+
+    let json: unknown | undefined;
+    let text: string | undefined;
+    let bodyBinaryName: string | undefined;
+
+    if (shouldDownload) {
+      // Signal to caller that binary attachment is needed.
+      bodyBinaryName = binaryName;
+      // Do NOT read the body here — the caller must handle binary attach separately.
+    } else if (isJson) {
+      try {
+        json = await response.json();
+      } catch {
+        text = await response.text();
+      }
+    } else {
+      text = await response.text();
+    }
+
+    return {
+      url: resolvedUrl,
+      method: spec.method.toUpperCase(),
+      status: response.status,
+      ok: response.ok,
+      statusText: response.statusText,
+      mimeType,
+      headers: responseHeaders,
+      ...(json !== undefined ? { json } : {}),
+      ...(text !== undefined ? { text } : {}),
+      ...(bodyBinaryName !== undefined ? { bodyBinaryName } : {}),
+    };
+  }
+
+  private readHeaders(headers: Headers): Readonly<Record<string, string>> {
+    const values: Record<string, string> = {};
+    headers.forEach((value, key) => {
+      values[key] = value;
+    });
+    return values;
+  }
+
+  private resolveMimeType(headers: Readonly<Record<string, string>>): string {
+    const contentType = headers["content-type"];
+    if (!contentType) {
+      return "application/octet-stream";
+    }
+    return contentType.split(";")[0]?.trim() || "application/octet-stream";
+  }
+
+  private isJsonMimeType(mimeType: string): boolean {
+    return mimeType === "application/json" || mimeType.endsWith("+json");
+  }
+
+  private shouldAttachBody(mode: "auto" | "always" | "never", mimeType: string): boolean {
+    if (mode === "always") {
+      return true;
+    }
+    if (mode === "never") {
+      return false;
+    }
+    return (
+      mimeType.startsWith("image/") ||
+      mimeType.startsWith("audio/") ||
+      mimeType.startsWith("video/") ||
+      mimeType === "application/pdf"
+    );
+  }
+}

package/src/http/HttpUrlBuilder.ts

@@ -0,0 +1,22 @@
+/**
+ * Merges query parameters into a base URL.
+ * Handles both scalar and array values, and preserves any existing params.
+ */
+export class HttpUrlBuilder {
+  build(baseUrl: string, query?: Readonly<Record<string, string | string[]>>): string {
+    if (!query || Object.keys(query).length === 0) {
+      return baseUrl;
+    }
+    const parsed = new URL(baseUrl);
+    for (const [key, value] of Object.entries(query)) {
+      if (Array.isArray(value)) {
+        for (const entry of value) {
+          parsed.searchParams.append(key, entry);
+        }
+      } else {
+        parsed.searchParams.append(key, value);
+      }
+    }
+    return parsed.toString();
+  }
+}

package/src/http/httpRequest.types.ts

@@ -0,0 +1,69 @@
+import type { NodeExecutionContext } from "@codemation/core";
+import type { RunnableNodeConfig } from "@codemation/core";
+
+/**
+ * Binary reference key into `item.binary`.
+ */
+export type BinaryRef = string;
+
+/**
+ * Discriminated union for the HTTP request body.
+ */
+export type HttpBodySpec =
+  | Readonly<{ kind: "none" }>
+  | Readonly<{ kind: "json"; data: unknown }>
+  | Readonly<{ kind: "form"; data: Readonly<Record<string, string>> }>
+  | Readonly<{
+      kind: "multipart";
+      fields: Readonly<Record<string, string>>;
+      binaries?: Readonly<Record<string, BinaryRef>>;
+    }>;
+
+/**
+ * Session interface that credential types implement.
+ * Returns header/query deltas so the executor can merge them without
+ * mutating the immutable HttpRequestSpec.
+ */
+export interface CredentialSession {
+  applyToRequest(spec: HttpRequestSpec): HttpCredentialDelta;
+}
+
+/**
+ * Mutations the credential session wants to apply to the outgoing request.
+ */
+export type HttpCredentialDelta = Readonly<{
+  headers?: Readonly<Record<string, string>>;
+  query?: Readonly<Record<string, string>>;
+}>;
+
+/**
+ * Full specification of one HTTP request. All URLs are fully resolved before
+ * being passed here (template substitution already applied by the caller).
+ */
+export type HttpRequestSpec = Readonly<{
+  url: string;
+  method: string;
+  headers?: Readonly<Record<string, string>>;
+  query?: Readonly<Record<string, string | string[]>>;
+  body?: HttpBodySpec;
+  credential?: CredentialSession;
+  download?: Readonly<{ mode: "auto" | "always" | "never"; binaryName: string }>;
+  /** Execution context — needed for binary attach. */
+  ctx: NodeExecutionContext<RunnableNodeConfig<unknown, unknown>>;
+}>;
+
+/**
+ * Result of executing an HTTP request.
+ */
+export type HttpRequestResult = Readonly<{
+  url: string;
+  method: string;
+  status: number;
+  ok: boolean;
+  statusText: string;
+  mimeType: string;
+  headers: Readonly<Record<string, string>>;
+  json?: unknown;
+  text?: string;
+  bodyBinaryName?: string;
+}>;

package/src/index.ts

@@ -1,22 +1,30 @@
 export * from "./canvasIconName";
+export * from "./credentials/index";
+export * from "./http/httpRequest.types";
+export * from "./authoring/defineRestNode.types";
 export * from "./chatModels/OpenAIChatModelFactory";
-export * from "./chatModels/OpenAIStructuredOutputMethodFactory";
+export * from "./chatModels/OpenAiStrictJsonSchemaFactory";
 export * from "./chatModels/OpenAiCredentialSession";
 export * from "./chatModels/openAiChatModelConfig";
 export * from "./chatModels/OpenAiChatModelPresetsFactory";
 export * from "./nodes/aiAgent";
+export * from "./nodes/assertion";
 export * from "./nodes/CallbackNodeFactory";
 export * from "./nodes/httpRequest";
 export * from "./nodes/aggregate";
 export * from "./nodes/filter";
 export * from "./nodes/if";
+export * from "./nodes/isTestRun";
 export * from "./nodes/switch";
 export * from "./nodes/split";
+export * from "./nodes/CronTriggerFactory";
+export * from "./nodes/CronTriggerNode";
 export * from "./nodes/ManualTriggerFactory";
 export * from "./nodes/mapData";
 export * from "./nodes/merge";
 export * from "./nodes/noOp";
 export * from "./nodes/subWorkflow";
+export * from "./nodes/testTrigger";
 export * from "./nodes/wait";
 export * from "./nodes/webhookRespondNowAndContinueError";
 export * from "./nodes/webhookRespondNowError";
@@ -30,3 +38,4 @@ export * from "./nodes/ConnectionCredentialNode";
 export * from "./nodes/ConnectionCredentialNodeConfig";
 export * from "./nodes/ConnectionCredentialNodeConfigFactory";
 export * from "./nodes/ConnectionCredentialExecutionContextFactory";
+export * from "./nodes/collections";

package/src/nodes/AIAgentExecutionHelpersFactory.ts

@@ -1,17 +1,30 @@
-import type { CredentialSessionService, Item, Items, NodeExecutionContext, ZodSchemaAny } from "@codemation/core";
+import type { CredentialSessionService, ZodSchemaAny } from "@codemation/core";
 import { injectable } from "@codemation/core";
 
-import { isInteropZodSchema } from "@langchain/core/utils/types";
-import { toJsonSchema } from "@langchain/core/utils/json_schema";
-import { DynamicStructuredTool } from "@langchain/core/tools";
-import { toJSONSchema } from "zod/v4/core";
+import { toJSONSchema as frameworkToJSONSchema } from "zod/v4/core";
 
 import { ConnectionCredentialExecutionContextFactory } from "./ConnectionCredentialExecutionContextFactory";
-import type { ResolvedTool } from "./aiAgentSupport.types";
 
 /**
- * LangChain adapters and credential context wiring for {@link AIAgentNode}.
- * Lives in a `*Factory.ts` composition-root module so construction stays explicit and testable.
+ * Shape of the instance-level `toJSONSchema` method that Zod v4 schemas expose. Conversions must go
+ * through this instance method (see {@link AIAgentExecutionHelpersFactory#createJsonSchemaRecord})
+ * rather than the module-level `toJSONSchema` import because the consumer's workflow-loader (see
+ * `CodemationConsumerConfigLoader.toNamespace`) can load Zod under a separate tsx namespace. That
+ * produces two runtime copies of Zod whose internal class / symbol identities don't overlap, so the
+ * framework-side module-level `toJSONSchema` throws "Cannot read properties of undefined (reading
+ * 'def')" on consumer-created schemas. The instance method is bound inside the schema's own module
+ * and therefore uses the matching Zod internals.
+ */
+type ZodInstanceToJsonSchema = (params?: Readonly<{ target: "draft-07" | "draft-7" | "draft-2020-12" }>) => unknown;
+
+/**
+ * Helper utilities shared by {@link AIAgentNode} and supporting runners.
+ *
+ * Responsibilities:
+ * - {@link #createConnectionCredentialExecutionContextFactory} centralizes credential-context wiring.
+ * - {@link #createJsonSchemaRecord} is a pure Zod → draft-07 converter used by both
+ *   `OpenAiStrictJsonSchemaFactory` (to feed OpenAI-strict structured output) and the
+ *   `AgentStructuredOutputRepairPromptFactory` (to show a required-schema reminder).
  */
 @injectable()
 export class AIAgentExecutionHelpersFactory {
@@ -21,47 +34,14 @@ export class AIAgentExecutionHelpersFactory {
     return new ConnectionCredentialExecutionContextFactory(credentialSessions);
   }
 
-  createDynamicStructuredTool(
-    entry: ResolvedTool,
-    toolCredentialContext: NodeExecutionContext<any>,
-    item: Item,
-    itemIndex: number,
-    items: Items,
-  ): DynamicStructuredTool {
-    if (entry.runtime.inputSchema == null) {
-      throw new Error(
-        `Cannot create LangChain tool "${entry.config.name}": missing inputSchema (broken tool runtime resolution).`,
-      );
-    }
-    const schemaForOpenAi = this.createJsonSchemaRecord(entry.runtime.inputSchema, {
-      schemaName: entry.config.name,
-      requireObjectRoot: true,
-    });
-    return new DynamicStructuredTool({
-      name: entry.config.name,
-      description: entry.config.description ?? entry.runtime.defaultDescription,
-      schema: schemaForOpenAi as unknown as ZodSchemaAny,
-      func: async (input) => {
-        const result = await entry.runtime.execute({
-          config: entry.config,
-          input,
-          ctx: toolCredentialContext,
-          item,
-          itemIndex,
-          items,
-        });
-        return JSON.stringify(result);
-      },
-    });
-  }
-
   /**
-   * Produces a plain JSON Schema object for OpenAI tool parameters and LangChain tool invocation:
-   * - **Zod** → `toJSONSchema(..., { target: "draft-07" })` so shapes match what `@cfworker/json-schema`
-   *   expects (`required` must be an array; draft 2020-12 output can break validation).
-   * - Otherwise LangChain `toJsonSchema` (Standard Schema + JSON passthrough); if the result is still Zod
-   *   (duplicate `zod` copies), fall back to Zod `toJSONSchema` with draft-07.
-   * - Strip root `$schema` for OpenAI; normalize invalid `required` keywords for cfworker; ensure `properties`.
+   * Produces a plain JSON Schema object (`draft-07`) from a Zod schema, as needed by
+   * OpenAI tool-parameter schemas and the structured-output repair prompt.
+   * - Prefers the schema's **instance** `toJSONSchema(...)` method so we stay inside the Zod
+   *   instance that created the schema (works across consumer/framework tsx namespaces — see
+   *   {@link ZodInstanceToJsonSchema}). Falls back to the framework-imported module function.
+   * - Strips root `$schema` (OpenAI ignores it).
+   * - Sanitizes `required` for cfworker json-schema compatibility (must be a string array or absent).
    */
   createJsonSchemaRecord(
     inputSchema: ZodSchemaAny,
@@ -71,20 +51,12 @@ export class AIAgentExecutionHelpersFactory {
     }>,
   ): Record<string, unknown> {
     const draft07Params = { target: "draft-07" as const };
-    let converted: unknown;
-    if (isInteropZodSchema(inputSchema)) {
-      converted = toJSONSchema(inputSchema as unknown as Parameters<typeof toJSONSchema>[0], draft07Params);
-    } else {
-      converted = toJsonSchema(inputSchema);
-      if (isInteropZodSchema(converted)) {
-        converted = toJSONSchema(inputSchema as unknown as Parameters<typeof toJSONSchema>[0], draft07Params);
-      }
-    }
+    const converted = this.convertZodSchemaToJsonSchema(inputSchema, draft07Params);
     const record = converted as Record<string, unknown>;
     const { $schema: _draftSchemaOmitted, ...rest } = record;
     if (options.requireObjectRoot && rest.type !== "object") {
       throw new Error(
-        `Cannot create LangChain tool "${options.schemaName}": tool input schema must be a JSON Schema object type (got type=${String(rest.type)}).`,
+        `Cannot create tool "${options.schemaName}": tool input schema must be a JSON Schema object type (got type=${String(rest.type)}).`,
       );
     }
     if (
@@ -93,7 +65,7 @@ export class AIAgentExecutionHelpersFactory {
       (typeof rest.properties !== "object" || Array.isArray(rest.properties))
     ) {
       throw new Error(
-        `Cannot create LangChain tool "${options.schemaName}": tool input schema "properties" must be an object (got ${JSON.stringify(rest.properties)}).`,
+        `Cannot create tool "${options.schemaName}": tool input schema "properties" must be an object (got ${JSON.stringify(rest.properties)}).`,
       );
     }
     if (options.requireObjectRoot && rest.properties === undefined) {
@@ -103,6 +75,20 @@ export class AIAgentExecutionHelpersFactory {
     return rest;
   }
 
+  /**
+   * Runs Zod's `toJSONSchema` via the schema's own instance method when available, so consumer
+   * schemas loaded under a different tsx namespace still convert correctly. If the caller handed us
+   * a payload that lacks that method (e.g. a plain JSON Schema record or a Zod instance whose
+   * prototype was stripped), we fall back to the framework-bundled module function.
+   */
+  private convertZodSchemaToJsonSchema(inputSchema: ZodSchemaAny, params: Readonly<{ target: "draft-07" }>): unknown {
+    const candidate = (inputSchema as unknown as { toJSONSchema?: ZodInstanceToJsonSchema }).toJSONSchema;
+    if (typeof candidate === "function") {
+      return candidate.call(inputSchema, params);
+    }
+    return frameworkToJSONSchema(inputSchema as unknown as Parameters<typeof frameworkToJSONSchema>[0], params);
+  }
+
   /**
    * `@cfworker/json-schema` iterates `schema.required` with `for...of`; it must be a string array or absent.
    */