@codemation/core-nodes 0.12.0 → 0.14.0

package/src/nodes/httpRequest.ts

@@ -18,7 +18,6 @@ import { HttpRequestNode } from "./HttpRequestNodeFactory";
 
 export type HttpRequestDownloadMode = "auto" | "always" | "never";
 
-/** JSON emitted by {@link HttpRequest} — response metadata only (input item fields are not passed through). */
 export type HttpRequestOutputJson = Readonly<{
   url: string;
   method: string;
@@ -30,20 +29,12 @@ export type HttpRequestOutputJson = Readonly<{
   json?: unknown;
   text?: string;
   bodyBinaryName?: string;
-  /** Set when `responseFormat === "binary"`. Name of the binary slot the response was stored in. */
   binarySlot?: string;
-  /** Set when `responseFormat === "binary"`. MIME type of the stored response. */
   contentType?: string;
-  /** Set when `responseFormat === "binary"`. Size in bytes of the stored response. */
   size?: number;
-  /** Set when `responseFormat === "binary"`. Filename inferred from URL or Content-Disposition. */
   filename?: string;
 }>;
 
-/**
- * The built-in HTTP request credential type IDs accepted by the `HttpRequest` node.
- * These match the four generic credential types shipped with `@codemation/core-nodes`.
- */
 export const HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES: ReadonlyArray<string> = [
   bearerTokenCredentialType.definition.typeId,
   apiKeyCredentialType.definition.typeId,
@@ -51,7 +42,6 @@ export const HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES: ReadonlyArray<string> = [
   oauth2ClientCredentialsType.definition.typeId,
 ] as const;
 
-/** Default maximum response size for binary mode: 100 MiB. */
 const DEFAULT_RESPONSE_SIZE_CAP_BYTES = 100 * 1024 * 1024;
 
 export class HttpRequest<
@@ -67,77 +57,20 @@ export class HttpRequest<
   constructor(
     public readonly name: string,
     public readonly args: Readonly<{
-      /** HTTP method (default: GET). */
       method?: string;
-      /**
-       * Legacy: field name on item.json to read the URL from.
-       * Use `url` for a literal/templated URL instead.
-       */
       urlField?: string;
-      /** Literal or templated URL. When present, takes precedence over `urlField`. */
       url?: string;
-      /** Extra headers to add to every request. */
       headers?: Readonly<Record<string, string>>;
-      /** Query parameters to append to the URL. */
       query?: Readonly<Record<string, string>>;
-      /** Request body specification. For `kind:"json"`, pass the object directly in `body.data` — it is JSON-encoded exactly once, so never a pre-stringified string. */
       body?: HttpBodySpec;
-      /**
-       * Credential slot.
-       *
-       * **String shorthand** (existing): `credentialSlot: "auth"` — the slot accepts all four
-       * default HTTP credential types (bearer, API-key, basic, OAuth2).
-       *
-       * **Object form** (new): narrows the accepted types to the caller-supplied list, useful
-       * when only a subset of credential types makes sense for a specific endpoint.
-       * ```ts
-       * credentialSlot: { name: "auth", acceptedTypes: [bearerTokenCredentialType] }
-       * ```
-       * The slot must be declared in `getCredentialRequirements()`, which is wired automatically.
-       */
       credentialSlot?: string | Readonly<{ name: string; acceptedTypes?: ReadonlyArray<AnyCredentialType> }>;
       binaryName?: string;
       downloadMode?: HttpRequestDownloadMode;
-      /**
-       * Controls how the response body is handled.
-       * - `"json"` / `"text"`: existing behaviour (parse + emit on `item.json`).
-       * - `"binary"`: read the response as raw bytes and store via `ctx.binary.attach`.
-       *   The output JSON contains `{ status, headers, binarySlot, contentType, size, filename }`
-       *   but NOT the raw bytes. Use `responseBinarySlot` to name the slot (default `"response"`).
-       *
-       * When omitted, the existing `downloadMode` logic applies (backward-compatible).
-       */
       responseFormat?: "json" | "text" | "binary";
-      /**
-       * Name of the binary slot to write the response body into when `responseFormat === "binary"`.
-       * Defaults to `"response"`.
-       */
       responseBinarySlot?: string;
-      /**
-       * Maximum response size in bytes for binary mode. Checked against the `Content-Length`
-       * response header before allocating memory. Defaults to 100 MiB (104857600).
-       * Requests whose `Content-Length` exceeds this cap are rejected before the body is read.
-       */
       responseSizeCapBytes?: number;
-      /**
-       * Operator-configurable outbound host allowlist.
-       *
-       * When set, every HTTP request target must match an entry in this list before the
-       * request is made — requests to any other host are rejected with {@link SSRFBlockedError}.
-       * Supports exact hostnames (`api.example.com`) and wildcard subdomain patterns
-       * (`*.example.com` matches `sub.example.com` but not `example.com` itself).
-       *
-       * When unset (default), the existing SSRF private-network guard applies:
-       * public hosts are allowed and private/loopback ranges are blocked.
-       *
-       * **Production warning**: when `NODE_ENV === "production"` and this is unset, a one-time
-       * warning is logged at workflow startup.
-       *
-       * Setting this to an empty array `[]` is equivalent to "block everything".
-       */
       allowedOutboundHosts?: ReadonlyArray<string>;
       id?: string;
-      /** Plain-language explanation surfaced in the node sidebar. */
       description?: string;
     }> = {},
     public readonly retryPolicy: RetryPolicySpec = RetryPolicy.defaultForHttp,
@@ -197,7 +130,6 @@ export class HttpRequest<
         },
       ];
     }
-    // Object form: use caller-supplied acceptedTypes (mapped to typeIds), falling back to all defaults.
     const acceptedTypes =
       slot.acceptedTypes && slot.acceptedTypes.length > 0
         ? slot.acceptedTypes.map((ct) => ct.definition.typeId)

package/src/nodes/isTestRun.ts

@@ -3,10 +3,6 @@ import type { RunnableNodeConfig, TypeToken } from "@codemation/core";
 import { IsTestRunNode } from "./IsTestRunNode";
 import type { NodeBaseOptions } from "./nodeOptions.types";
 
-/**
- * Branches per-item on whether the current run is a test run. Output ports: `true`, `false`.
- * The wire payload is unchanged — this is a router, not a transform.
- */
 export class IsTestRun<TInputJson = unknown> implements RunnableNodeConfig<TInputJson, TInputJson> {
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = IsTestRunNode;

package/src/nodes/mapData.ts

@@ -19,7 +19,6 @@ export class MapData<TInputJson = unknown, TOutputJson = unknown> implements Run
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = MapDataNode;
   readonly execution = { hint: "local" } as const;
-  /** Zero mapped items should still allow downstream nodes to run. */
   readonly continueWhenEmptyOutput = true as const;
   readonly icon = "lucide:square-pen" as const;
   readonly keepBinaries: boolean;

package/src/nodes/merge.ts

@@ -18,10 +18,6 @@ export class Merge<TInputJson = unknown, TOutputJson = TInputJson> implements Ru
     public readonly name: string,
     public readonly cfg: Readonly<{
       mode: MergeMode;
-      /**
-       * Deterministic input precedence order (only used for passThrough/append).
-       * Any inputs not listed are appended in lexicographic order.
-       */
       prefer?: ReadonlyArray<InputPortKey>;
     }> = { mode: "passThrough" },
     idOrOptions?: string | NodeBaseOptions,

package/src/nodes/mergeExecutionUtils.types.ts

@@ -5,9 +5,6 @@ export function getOriginIndex(item: Item): number | undefined {
   return getOriginIndexFromItem(item);
 }
 
-/**
- * Tags items routed to fan-in merge-by-origin (same contract as {@link IfNode} / {@link SwitchNode}).
- */
 export function tagItemForRouterFanIn<TJson>(
   args: Readonly<{
     item: Item<TJson>;

package/src/nodes/nodeOptions.types.ts

@@ -1,11 +1,3 @@
-/**
- * Options shared by every authorable built-in node: a stable `id` and a plain-language
- * `description` (the non-technical "what does this node do" line surfaced in the node sidebar).
- *
- * `description` is a first-class config option — passed inline in the node's options, exactly like
- * `id` — and is threaded onto the config instance so it flows into the persisted workflow snapshot
- * the host / canvas mappers read. Node-specific option types extend this.
- */
 export interface NodeBaseOptions {
   readonly id?: string;
   readonly description?: string;

package/src/nodes/schedulePollingTrigger.ts

@@ -0,0 +1,37 @@
+import { definePollingTrigger } from "@codemation/core";
+
+type ScheduleItem = {
+  firedAt: string;
+  tick: number;
+};
+
+type ScheduleState = {
+  tick: number;
+};
+
+export const schedulePollingTrigger = definePollingTrigger({
+  key: "schedule.interval",
+  packageName: "@codemation/core-nodes",
+  title: "Run on schedule",
+  description: "Emit one tick item on every poll cycle.",
+  icon: "lucide:clock",
+  pollIntervalMs: 60_000,
+  initialState(): ScheduleState {
+    return { tick: 0 };
+  },
+  poll({ state }) {
+    const currentState = (state ?? { tick: 0 }) as ScheduleState;
+    const tick = currentState.tick + 1;
+    const item: { json: ScheduleItem } = { json: { firedAt: new Date().toISOString(), tick } };
+    return {
+      items: [item],
+      nextState: { tick },
+    };
+  },
+  execute(items) {
+    return { main: items };
+  },
+  testItems() {
+    return [{ json: { firedAt: new Date().toISOString(), tick: 0 } }];
+  },
+});

package/src/nodes/split.ts

@@ -13,10 +13,6 @@ export class Split<TIn = unknown, TElem = unknown> implements RunnableNodeConfig
   readonly type: TypeToken<unknown> = SplitNode;
   readonly execution = { hint: "local" } as const;
   readonly keepBinaries = true as const;
-  /**
-   * When splitting yields zero items for a batch, downstream single-input nodes still run once with an empty batch.
-   * Mirrors {@link MapData}'s empty-output behavior.
-   */
   readonly continueWhenEmptyOutput = true as const;
   readonly icon = "builtin:split-rows" as const;
   readonly id?: string;

package/src/nodes/testTrigger.ts

@@ -13,34 +13,13 @@ export interface TestTriggerOptions<TOutputJson> {
   readonly name?: string;
   readonly id?: string;
   readonly icon?: string;
-  /** Cap on simultaneous in-flight test cases for one suite run. Default: 4 (orchestrator). */
   readonly concurrency?: number;
   readonly credentialRequirements?: ReadonlyArray<CredentialRequirement>;
-  /**
-   * Free-form description of where the test cases come from. Shown in the node properties
-   * panel and the Tests-tab suite-detail header so authors revisiting the workflow six months
-   * later remember which mailbox / folder / fixture file the cases originate from.
-   */
   readonly description?: string;
-  /**
-   * Author callback that yields one item per test case. Items are dispatched as separate
-   * workflow runs by the TestSuiteOrchestrator, with `executionOptions.testContext` set.
-   * The provided context exposes credential resolution and an AbortSignal for cancellation.
-   */
   generateItems(ctx: TestTriggerSetupContext<TestTrigger<TOutputJson>>): AsyncIterable<Item<TOutputJson>>;
-  /**
-   * Optional resolver: extract a human-readable label from a yielded item. The orchestrator
-   * persists this on the run, so the Tests-tab tree-table shows e.g. "RFQ for batch 14"
-   * instead of an opaque runId. Typical use: `(item) => item.json.subject` for mailbox tests.
-   */
   caseLabel?(item: Item<TOutputJson>): string | undefined;
 }
 
-/**
- * Trigger config for a test fixture source. Drop one (or more) of these on the canvas alongside
- * a workflow's live triggers; clicking "Run tests" on the Tests tab invokes
- * {@link TestTriggerOptions.generateItems} via the TestSuiteOrchestrator.
- */
 export class TestTrigger<TOutputJson = unknown> implements TestTriggerNodeConfig<TOutputJson> {
   readonly kind = "trigger" as const;
   readonly triggerKind = "test" as const;

package/src/nodes/wait.ts

@@ -7,7 +7,6 @@ export class Wait<TItemJson = unknown> implements RunnableNodeConfig<TItemJson,
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = WaitNode;
   readonly execution = { hint: "local" } as const;
-  /** Pass-through empty batches should still advance to downstream nodes. */
   readonly continueWhenEmptyOutput = true as const;
   readonly icon = "lucide:hourglass" as const;
   readonly id?: string;

package/src/nodes/webhookTriggerNode.ts

@@ -8,11 +8,6 @@ import type {
 import { node } from "@codemation/core";
 import { WebhookTrigger } from "./WebhookTriggerFactory";
 
-/**
- * HTTP webhooks are not registered in trigger setup. The host exposes a single catch-all route
- * (e.g. `/api/webhooks/:endpointPath`); the engine's catalog-backed webhook matcher resolves the
- * user-defined endpoint path to this workflow + node, then runs the workflow from this trigger.
- */
 @node({ packageName: "@codemation/core-nodes" })
 export class WebhookTriggerNode implements ExecutableTriggerNode<WebhookTrigger<any>> {
   readonly kind = "trigger" as const;

package/src/register.types.ts

@@ -14,19 +14,9 @@ import { FilterNode } from "./nodes/filter";
 import { SplitNode } from "./nodes/split";
 import { SwitchNode } from "./nodes/switch";
 
-/**
- * Registrar for built-in nodes. In a real project, this would use tsyringe's
- * container.registerSingleton(...). For the skeleton we keep it token-based:
- * the engine resolves node implementations by class token.
- */
 export function registerCoreNodes(container: Container): void {
-  // With class tokens, resolving registers happen via the DI container setup.
-  // This function exists as the standardized extension point.
   void container;
 
-  // Example: if using tsyringe, you'd do:
-  // tsyringeContainer.registerSingleton(IfNode, IfNode);
-  // ...
   void IfNode;
   void HttpRequestNode;
   void CallbackNode;

package/src/workflows/AIAgentConnectionWorkflowExpander.ts

@@ -5,9 +5,6 @@ import { AIAgentNode } from "../nodes/AIAgentNode";
 import { ConnectionCredentialNode } from "../nodes/ConnectionCredentialNode";
 import { ConnectionCredentialNodeConfigFactory } from "../nodes/ConnectionCredentialNodeConfigFactory";
 
-/**
- * Materializes connection-owned child nodes and {@link WorkflowDefinition.connections} for AI agent nodes.
- */
 export class AIAgentConnectionWorkflowExpander {
   constructor(
     private readonly connectionCredentialNodeConfigFactory: ConnectionCredentialNodeConfigFactory,