# Data Types & DTOs

!!! info "Stable API"
    Classes on this page are marked `@api` and are guaranteed backward compatible in the 1.x release line.
    See the [BC Policy](bc-policy.md) for details.

Data transfer objects used throughout the FlowDrop system. These classes carry data between node processors, the runtime, and the orchestration layer.

## Overview

| Class | Type | Description |
|-------|------|-------------|
| [`ParameterBagInterface`](#parameterbaginterface) | interface | Interface for parameter bags. |
| [`ParameterBag`](#parameterbag) | final class | Parameter bag containing resolved parameters for node execution. |
| [`DataInterface`](#datainterface) | interface | Interface for data transfer objects. |
| [`Data`](#data) | class | Data DTO for the flowdrop module. |
| [`OutputInterface`](#outputinterface) | interface | Interface for output data transfer objects. |
| [`Output`](#output) | class | Output DTO for the flowdrop module. |
| [`ValidationResult`](#validationresult) | final class | Represents the result of parameter validation. |
| [`ValidationError`](#validationerror) | final class | Represents a single validation error. |
| [`ValidationWarning`](#validationwarning) | final class | Represents a single validation warning. |
| [`ExecutionContextDTO`](#executioncontextdto) | final class | Data Transfer Object for workflow execution context. |
| [`NodeMetadata`](#nodemetadata) | final class | Value object representing complete node type metadata. |
| [`NodeMetadataBuilder`](#nodemetadatabuilder) | final class | Fluent builder for constructing NodeMetadata instances. |
| [`NodePort`](#nodeport) | final class | Value object representing a node port (input or output). |
| [`ConfigEdit`](#configedit) | final class | Value object for node configuration edit options. |
| [`DynamicSchemaEndpoint`](#dynamicschemaendpoint) | final class | Value object for dynamic schema endpoint configuration. |
| [`ExternalEditLink`](#externaleditlink) | final class | Value object for external edit link configuration. |
| [`ConfigEditApiEndpoints`](#configeditapiendpoints) | final class | Value object for config edit API endpoints. |

## ParameterBagInterface

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** interface  
**Source:** `src/DTO/ParameterBagInterface.php`  

Interface for parameter bags.

A ParameterBag contains resolved parameter values for node execution.
All parameters are pre-resolved and validated before being passed to
the plugin's process() method.

This is the Unified Parameter System that provides a single, unified
approach to handling both runtime inputs and configuration values.

### Methods

#### `get(string $name, mixed $default = NULL): mixed`

Get a parameter value.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$name` | `string` | The parameter name. |
| `$default` | `mixed` | Default value if parameter doesn't exist. |

#### `has(string $name): bool`

Check if a parameter exists.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$name` | `string` | The parameter name. |

#### `all(): array`

Get all parameters as an associative array.

#### `keys(): array`

Get all parameter names.

#### `isEmpty(): bool`

Check if the bag is empty.

#### `getTyped(string $name, string $type, mixed $default = NULL): mixed`

Get a typed parameter value.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$name` | `string` | The parameter name. |
| `$type` | `string` | Expected type ('string', 'int', 'float', 'bool', 'array'). |
| `$default` | `mixed` | Default value. |

**Throws:** `InvalidArgumentException`

#### `getString(string $name, string $default = ""): string`

Get a string parameter.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$name` | `string` | The parameter name. |
| `$default` | `string` | Default value. |

#### `getInt(string $name, int $default = 0): int`

Get an integer parameter.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$name` | `string` | The parameter name. |
| `$default` | `int` | Default value. |

#### `getFloat(string $name, float $default = 0): float`

Get a float parameter.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$name` | `string` | The parameter name. |
| `$default` | `float` | Default value. |

#### `getBool(string $name, bool $default = FALSE): bool`

Get a boolean parameter.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$name` | `string` | The parameter name. |
| `$default` | `bool` | Default value. |

#### `getArray(string $name, array $default = []): array`

Get an array parameter.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$name` | `string` | The parameter name. |
| `$default` | `array` | Default value. |

---

## ParameterBag

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** final class  
**Implements:** `ParameterBagInterface`, `JsonSerializable`  
**Source:** `src/DTO/ParameterBag.php`  

Parameter bag containing resolved parameters for node execution.

This class provides a clean, type-safe interface for accessing
parameter values within a plugin's process() method.

Part of the Unified Parameter System - all parameters (whether they
came from config, workflow values, or runtime inputs) are resolved
and validated before being passed to the plugin.

Note: This class intentionally does NOT extend Symfony's
HttpFoundation\ParameterBag for the following reasons:
- Immutability: Symfony's ParameterBag is mutable
  (E.g. set(), remove(), replace())
  which would break our functional, side-effect-free design. Workflow nodes
  should not be able to mutate parameters passed to them.
- Sealed design: We use 'final' to prevent extension and ensure consistent
  behavior across all usages.
- Type-safe getters: We provide additional typed accessors (getTyped(),
  getString(), getFloat(), getArray()) not available in Symfony.
- JsonSerializable: Native JSON serialization for logging and debugging.

### Methods

#### `get(string $name, mixed $default = NULL): mixed`

#### `has(string $name): bool`

#### `all(): array`

#### `keys(): array`

#### `isEmpty(): bool`

#### `getTyped(string $name, string $type, mixed $default = NULL): mixed`

#### `getString(string $name, string $default = ""): string`

#### `getInt(string $name, int $default = 0): int`

#### `getFloat(string $name, float $default = 0): float`

#### `getBool(string $name, bool $default = FALSE): bool`

#### `getArray(string $name, array $default = []): array`

#### `static fromArray(array $data): self`

Create a ParameterBag from an array.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The parameter data. |

#### `static empty(): self`

Create an empty ParameterBag.

#### `with(array $parameters): self`

Create a new ParameterBag with additional parameters.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$parameters` | `array` | Additional parameters to merge. |

#### `without(array $names): self`

Create a new ParameterBag without specified parameters.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$names` | `array` | Parameter names to remove. |

#### `jsonSerialize(): array`

Serialize the ParameterBag to JSON.

---

## DataInterface

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** interface  
**Source:** `src/DTO/DataInterface.php`  

Interface for data transfer objects.

This interface provides a standardized way to handle data
in the FlowDrop system, ensuring proper serialization and
type safety.

### Methods

#### `get(string $key, mixed $default = NULL): mixed`

Get a value from the data object.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The key to retrieve. |
| `$default` | `mixed` | The default value if key doesn't exist. |

#### `set(string $key, mixed $value): static`

Set a value in the data object.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The key to set. |
| `$value` | `mixed` | The value to set. |

#### `has(string $key): bool`

Check if a key exists in the data object.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The key to check. |

#### `remove(string $key): static`

Remove a key from the data object.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The key to remove. |

#### `toArray(): array`

Get all data as an array.

#### `fromArray(array $data): static`

Set data from an array.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The data array. |

#### `keys(): array`

Get all keys in the data object.

#### `isEmpty(): bool`

Check if the data object is empty.

#### `clear(): static`

Clear all data from the object.

#### `merge(DataInterface $other): static`

Merge data from another DataInterface object.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$other` | `DataInterface` | The other data object to merge from. |

---

## Data

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** class  
**Implements:** `DataInterface`  
**Source:** `src/DTO/Data.php`  

Data DTO for the flowdrop module.

This class provides a flexible data container that implements
the DataInterface for consistent data handling across the FlowDrop system.

### Methods

#### `get(string $key, mixed $default = NULL): mixed`

#### `set(string $key, mixed $value): static`

#### `has(string $key): bool`

#### `remove(string $key): static`

#### `toArray(): array`

#### `fromArray(array $data): static`

#### `keys(): array`

#### `isEmpty(): bool`

#### `clear(): static`

#### `merge(DataInterface $other): static`

---

## OutputInterface

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** interface  
**Extends:** `DataInterface`  
**Source:** `src/DTO/OutputInterface.php`  

Interface for output data transfer objects.

This interface provides specialized methods for handling output data
in the FlowDrop system, including status management and metadata handling.

### Methods

#### `setOutput(string $key, mixed $value, ?callable $validator = NULL): static`

Set output data with validation.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The output key. |
| `$value` | `mixed` | The output value. |
| `$validator` | `?callable` | Optional validation function. |

**Throws:** `InvalidArgumentException`

#### `addMetadata(string $key, mixed $value): static`

Add metadata to the output.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The metadata key. |
| `$value` | `mixed` | The metadata value. |

#### `getMetadata(string $key, mixed $default = NULL): mixed`

Get metadata from the output.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The metadata key. |
| `$default` | `mixed` | The default value. |

#### `setStatus(string $status, ?string $message = NULL): static`

Set execution status.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$status` | `string` | The execution status (success, error, warning, etc.). |
| `$message` | `?string` | Optional status message. |

#### `getStatus(): string`

Get execution status.

#### `isSuccess(): bool`

Check if the output indicates success.

#### `isError(): bool`

Check if the output indicates an error.

#### `setError(string $message, ?string $code = NULL): static`

Set error information.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$message` | `string` | The error message. |
| `$code` | `?string` | Optional error code. |

#### `getErrorMessage(): ?string`

Get error message.

#### `getErrorCode(): ?string`

Get error code.

#### `setSuccess(?string $message = NULL): static`

Set success information.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$message` | `?string` | Optional success message. |

#### `getSuccessMessage(): ?string`

Get success message.

#### `addExecutionTime(float $execution_time): static`

Add execution timing information.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$execution_time` | `float` | The execution time in seconds. |

#### `getExecutionTime(): ?float`

Get execution time.

#### `getAllOutput(): array`

Get all output data as an associative array.

#### `hasOutputData(): bool`

Check if output has any data.

#### `getOutputCount(): int`

Get output count.

#### `mergeOutput(OutputInterface $other): static`

Merge output with another output object.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$other` | `OutputInterface` | The other output object. |

---

## Output

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** class  
**Extends:** `Data`  
**Implements:** `OutputInterface`  
**Source:** `src/DTO/Output.php`  

Output DTO for the flowdrop module.

This class represents output data from node processors,
providing specialized methods for output handling.

### Methods

#### `setOutput(string $key, mixed $value, ?callable $validator = NULL): static`

#### `addMetadata(string $key, mixed $value): static`

#### `getMetadata(string $key, mixed $default = NULL): mixed`

#### `setStatus(string $status, ?string $message = NULL): static`

#### `getStatus(): string`

#### `isSuccess(): bool`

#### `isError(): bool`

#### `setError(string $message, ?string $code = NULL): static`

#### `getErrorMessage(): ?string`

#### `getErrorCode(): ?string`

#### `setSuccess(?string $message = NULL): static`

#### `getSuccessMessage(): ?string`

#### `addExecutionTime(float $execution_time): static`

#### `getExecutionTime(): ?float`

#### `getAllOutput(): array`

#### `hasOutputData(): bool`

#### `getOutputCount(): int`

#### `mergeOutput(OutputInterface $other): static`

---

## ValidationResult

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** final class  
**Source:** `src/DTO/ValidationResult.php`  

Represents the result of parameter validation.

Provides a structured way to return validation results from node processors,
replacing the simple boolean return type. This allows:
- Detailed error messages for each validation failure
- Warnings for non-critical issues
- Centralized logging by the orchestration layer.

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$valid` | `bool` | — | Whether validation passed. |
| `$errors` | `array` | [] | Validation errors that caused failure. |
| `$warnings` | `array` | [] | Validation warnings (non-blocking issues). |

### Methods

#### `static success(array $warnings = []): self`

Create a successful validation result.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$warnings` | `array` | Optional warnings to include despite success. |

#### `static failure(array $errors, array $warnings = []): self`

Create a failed validation result.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$errors` | `array` | The validation errors. |
| `$warnings` | `array` | Optional warnings to include. |

#### `static error(string $parameter, string $message, ?string $code = NULL): self`

Create a failed result from a single error message.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$parameter` | `string` | The parameter name that failed validation. |
| `$message` | `string` | The error message. |
| `$code` | `?string` | Optional error code. |

#### `isValid(): bool`

Check if validation passed.

#### `getErrors(): array`

Get validation errors.

#### `getWarnings(): array`

Get validation warnings.

#### `hasErrors(): bool`

Check if there are any errors.

#### `hasWarnings(): bool`

Check if there are any warnings.

#### `getErrorCount(): int`

Get error count.

#### `getWarningCount(): int`

Get warning count.

#### `getErrorMessages(): array`

Get all error messages as a flat array.

#### `getWarningMessages(): array`

Get all warning messages as a flat array.

#### `toArray(): array`

Convert to array representation.

#### `merge(ValidationResult $other): self`

Merge with another validation result.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$other` | `ValidationResult` | The other validation result to merge. |

---

## ValidationError

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** final class  
**Source:** `src/DTO/ValidationError.php`  

Represents a single validation error.

Used within ValidationResult to provide detailed information
about validation failures.

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$parameter` | `string` | — | The parameter name that failed validation. |
| `$message` | `string` | — | Human-readable error message. |
| `$code` | `?string` | NULL | Optional machine-readable error code. |

### Methods

#### `getParameter(): string`

Get the parameter name.

#### `getMessage(): string`

Get the error message.

#### `getCode(): ?string`

Get the error code.

#### `toArray(): array`

Convert to array representation.

#### `static fromArray(array $data): self`

Create from array representation.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The array data. |

---

## ValidationWarning

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** final class  
**Source:** `src/DTO/ValidationWarning.php`  

Represents a single validation warning.

Used within ValidationResult to provide information about
non-critical validation issues that don't block execution.

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$parameter` | `string` | — | The parameter name associated with the warning. |
| `$message` | `string` | — | Human-readable warning message. |

### Methods

#### `getParameter(): string`

Get the parameter name.

#### `getMessage(): string`

Get the warning message.

#### `toArray(): array`

Convert to array representation.

#### `static fromArray(array $data): self`

Create from array representation.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The array data. |

---

## ExecutionContextDTO

**Namespace:** `Drupal\flowdrop\DTO`  
**Type:** final class  
**Source:** `src/DTO/ExecutionContextDTO.php`  

Data Transfer Object for workflow execution context.

This DTO provides type-safe access to workflow execution context data.
Processors that implement ExecutionContextAwareInterface receive an
instance of this class before execution.

The context includes:
- Initial data passed when workflow execution started
- Workflow, pipeline, and execution identifiers
- Additional metadata about the current execution

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$initialData` | `array` | — | The initial data passed when workflow execution started. |
| `$workflowId` | `string` | — | The workflow ID being executed. |
| `$pipelineId` | `string` | — | The pipeline ID being executed. |
| `$executionId` | `string` | — | The unique execution identifier. |
| `$nodeId` | `string` | — | The id of the node being executed. |
| `$metadata` | `array` | [] | Additional execution metadata. |

### Methods

#### `getNodeId(): string`

Gets the node id.

#### `getInitialData(): array`

Gets the initial data passed when workflow execution started.

#### `getInitialDataValue(string $key, mixed $default = NULL): mixed`

Gets a specific value from the initial data.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The key to retrieve. |
| `$default` | `mixed` | Default value if key doesn't exist. |

#### `hasInitialDataKey(string $key): bool`

Checks if initial data has a specific key.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The key to check. |

#### `getWorkflowId(): string`

Gets the workflow ID being executed.

#### `getPipelineId(): string`

Gets the pipeline ID being executed.

#### `getExecutionId(): string`

Gets the unique execution identifier.

#### `getMetadata(): array`

Gets additional execution metadata.

#### `getMetadataValue(string $key, mixed $default = NULL): mixed`

Gets a specific metadata value.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$key` | `string` | The metadata key. |
| `$default` | `mixed` | Default value if key doesn't exist. |

#### `static fromArray(array $data): self`

Creates an ExecutionContextDTO from an array.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The context data array with keys: - initial_data: array - workflow_id: string - pipeline_id: string - execution_id: string - metadata: array (optional) |

#### `toArray(): array`

Converts the DTO to an array.

---

## NodeMetadata

**Namespace:** `Drupal\flowdrop\DTO\NodeMetadata`  
**Type:** final class  
**Source:** `src/DTO/NodeMetadata/NodeMetadata.php`  

Value object representing complete node type metadata.

Encapsulates all metadata returned by the nodes API, providing
type-safe access to node configuration for the workflow editor.
This is the primary data structure returned by the NodesController
for node type listings and individual node type queries.

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$id` | `string` | — | The node type ID (e.g., "trigger", "text_processor"). |
| `$name` | `string` | — | The human-readable node name. |
| `$type` | `string` | — | The visual type (e.g., "basic", "terminal"). |
| `$supportedTypes` | `array` | — | List of supported visual types for this node. |
| `$description` | `string` | — | The node description. |
| `$category` | `string` | — | The category in plural form (e.g., "triggers", "processing"). |
| `$icon` | `string` | — | The icon identifier (e.g., "mdi:play", "mdi:cog"). |
| `$pluginVersion` | `string` | — | The plugin version string. |
| `$enabled` | `bool` | — | Whether the node type is enabled. |
| `$tags` | `array` | — | Associated tags for categorization/filtering. |
| `$executorPlugin` | `string` | — | The executor plugin ID that processes this node. |
| `$inputs` | `array` | — | The input ports for this node. |
| `$outputs` | `array` | — | The output ports for this node. |
| `$config` | `array` | — | Default configuration values. |
| `$configSchema` | `array` | — | The JSON Schema for configuration. |
| `$configEdit` | `?ConfigEdit` | NULL | Optional configuration edit options. |

### Methods

#### `static fromArray(array $data): self`

Creates an instance from an array.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The array data containing node metadata properties. |

#### `toArray(): array`

Converts the object to an array suitable for JSON serialization.

#### `hasConfigEdit(): bool`

Checks if this node has configEdit options.

#### `getInputById(string $id): ?NodePort`

Gets an input port by ID.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$id` | `string` | The port ID to find. |

#### `getOutputById(string $id): ?NodePort`

Gets an output port by ID.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$id` | `string` | The port ID to find. |

#### `getInputCount(): int`

Gets the count of input ports.

#### `getOutputCount(): int`

Gets the count of output ports.

#### `hasRequiredInputs(): bool`

Checks if this node has any required inputs.

#### `getRequiredInputs(): array`

Gets all required input ports.

---

## NodeMetadataBuilder

**Namespace:** `Drupal\flowdrop\DTO\NodeMetadata`  
**Type:** final class  
**Source:** `src/DTO/NodeMetadata/NodeMetadataBuilder.php`  

Fluent builder for constructing NodeMetadata instances.

This builder simplifies the creation of NodeMetadata objects,
especially in contexts where properties are set incrementally
(like in NodesController::buildNodeData()).

Example usage:

### Methods

#### `static create(): self`

Creates a new builder instance.

#### `setId(string $id): self`

Sets the node type ID.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$id` | `string` | The node type ID. |

#### `setName(string $name): self`

Sets the human-readable name.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$name` | `string` | The node name. |

#### `setType(string $type): self`

Sets the visual type.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$type` | `string` | The visual type (e.g., "basic", "terminal"). |

#### `setSupportedTypes(array $supportedTypes): self`

Sets the supported visual types.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$supportedTypes` | `array` | List of supported visual types. |

#### `setDescription(string $description): self`

Sets the node description.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$description` | `string` | The description. |

#### `setCategory(string $category): self`

Sets the category.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$category` | `string` | The category in plural form (e.g., "triggers", "processing"). |

#### `setIcon(string $icon): self`

Sets the icon identifier.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$icon` | `string` | The icon (e.g., "mdi:play"). |

#### `setPluginVersion(string $pluginVersion): self`

Sets the plugin version.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$pluginVersion` | `string` | The version string. |

#### `setEnabled(bool $enabled): self`

Sets whether the node is enabled.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$enabled` | `bool` | TRUE if enabled. |

#### `setTags(array $tags): self`

Sets the associated tags.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$tags` | `array` | The tags array. |

#### `setExecutorPlugin(string $executorPlugin): self`

Sets the executor plugin ID.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$executorPlugin` | `string` | The plugin ID. |

#### `setInputs(array $inputs): self`

Sets the input ports.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$inputs` | `array` | Array of input ports. |

#### `addInput(NodePort $input): self`

Adds a single input port.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$input` | `NodePort` | The input port to add. |

#### `setOutputs(array $outputs): self`

Sets the output ports.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$outputs` | `array` | Array of output ports. |

#### `addOutput(NodePort $output): self`

Adds a single output port.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$output` | `NodePort` | The output port to add. |

#### `setConfig(array $config): self`

Sets the default configuration values.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$config` | `array` | The config defaults. |

#### `setConfigSchema(array $configSchema): self`

Sets the configuration JSON Schema.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$configSchema` | `array` | The config schema. |

#### `setConfigEdit(?ConfigEdit $configEdit): self`

Sets the configuration edit options.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$configEdit` | `?ConfigEdit` | The config edit options or NULL. |

#### `build(): NodeMetadata`

Builds the NodeMetadata instance.

---

## NodePort

**Namespace:** `Drupal\flowdrop\DTO\NodeMetadata`  
**Type:** final class  
**Source:** `src/DTO/NodeMetadata/NodePort.php`  

Value object representing a node port (input or output).

Ports are connection points on nodes in the workflow editor.
Each port has a type (input/output), data type, and metadata
describing how it can be connected to other nodes.

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$id` | `string` | — | The port identifier (e.g., "input_value", "output", "trigger"). |
| `$name` | `string` | — | The human-readable port name. |
| `$type` | `string` | — | The port type: "input" or "output". |
| `$dataType` | `string` | — | The data type: "string", "number", "boolean", "json", "trigger", etc. |
| `$required` | `bool` | FALSE | Whether the port connection is required. |
| `$description` | `string` | "" | The port description. |
| `$defaultValue` | `mixed` | NULL | The default value for this port (optional). |

### Constants

| Constant | Value | Description |
|----------|-------|-------------|
| `TYPE_INPUT` | "input" | Port type constant for input ports. |
| `TYPE_OUTPUT` | "output" | Port type constant for output ports. |

### Methods

#### `static input(string $id, string $name, string $dataType, bool $required = FALSE, string $description = "", mixed $defaultValue = NULL): self`

Creates an input port instance.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$id` | `string` | The port identifier. |
| `$name` | `string` | The human-readable port name. |
| `$dataType` | `string` | The data type. |
| `$required` | `bool` | Whether the port connection is required. |
| `$description` | `string` | The port description. |
| `$defaultValue` | `mixed` | The default value for this port. |

#### `static output(string $id, string $name, string $dataType, string $description = ""): self`

Creates an output port instance.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$id` | `string` | The port identifier. |
| `$name` | `string` | The human-readable port name. |
| `$dataType` | `string` | The data type. |
| `$description` | `string` | The port description. |

#### `static fromArray(array $data): self`

Creates an instance from an array.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The array data containing port properties. Expected keys: id, name, type, dataType, required, description, defaultValue. |

#### `toArray(): array`

Converts the port to an array suitable for JSON serialization.

#### `isInput(): bool`

Checks if this is an input port.

#### `isOutput(): bool`

Checks if this is an output port.

#### `hasDefaultValue(): bool`

Checks if this port has a default value.

---

## ConfigEdit

**Namespace:** `Drupal\flowdrop\DTO\ConfigEdit`  
**Type:** final class  
**Source:** `src/DTO/ConfigEdit/ConfigEdit.php`  

Value object for node configuration edit options.

Encapsulates all options for how a node's configuration can be edited -
either dynamically via schema fetching, through an external form, or both.
It provides the frontend with all necessary information to render the
appropriate configuration UI.

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$dynamicSchema` | `?DynamicSchemaEndpoint` | NULL | Configuration for fetching schema dynamically from a REST endpoint. |
| `$externalEditLink` | `?ExternalEditLink` | NULL | Configuration for opening an external edit form. |
| `$api` | `?ConfigEditApiEndpoints` | NULL | API endpoints for CRUD operations on the configuration entity. |
| `$preferDynamicSchema` | `bool` | TRUE | When both dynamicSchema and externalEditLink are present, prefer dynamic schema. Default TRUE. |
| `$showRefreshButton` | `bool` | TRUE | Show button to manually refresh the schema. Default TRUE. |
| `$loadingMessage` | `string` | "Loading configuration..." | Message to display while loading configuration. |
| `$errorMessage` | `string` | "Failed to load configuration" | Message to display when configuration loading fails. |

### Methods

#### `static fromArray(array $data): self`

Creates an instance from an array.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The array data to create the instance from. |

#### `toArray(): array`

Converts the object to an array suitable for JSON serialization.

#### `hasDynamicSchema(): bool`

Check if dynamic schema is available.

#### `hasExternalEditLink(): bool`

Check if external edit link is available.

#### `hasApi(): bool`

Check if API endpoints are available.

---

## DynamicSchemaEndpoint

**Namespace:** `Drupal\flowdrop\DTO\ConfigEdit`  
**Type:** final class  
**Source:** `src/DTO/ConfigEdit/DynamicSchemaEndpoint.php`  

Value object for dynamic schema endpoint configuration.

Represents the configuration for fetching a node's config schema
dynamically from a REST endpoint at runtime. This is useful when:
- Config options depend on external data (e.g., available models, API keys)
- Options change based on user authentication or permissions
- Schema needs to be refreshed periodically.

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$url` | `string` | — | The URL endpoint to fetch the schema from. Supports template variables like {nodeTypeId}, {instanceId}. |
| `$method` | `string` | "GET" | HTTP method to use (GET, POST). Defaults to GET. |
| `$parameterMapping` | `array` | [] | Maps URL template variables to node data paths. Example: ["nodeTypeId" => "metadata.id", "instanceId" => "id"]. |
| `$headers` | `array` | [] | Additional HTTP headers to include in the request. |
| `$cacheSchema` | `bool` | TRUE | Whether to cache the fetched schema. Default TRUE. Set to FALSE if schema varies by dynamic parameters. |
| `$timeout` | `int` | 10000 | Request timeout in milliseconds. Default 10000 (10 seconds). |

### Methods

#### `static fromArray(array $data): self`

Creates an instance from an array.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The array data to create the instance from. |

#### `toArray(): array`

Converts the object to an array suitable for JSON serialization.

---

## ExternalEditLink

**Namespace:** `Drupal\flowdrop\DTO\ConfigEdit`  
**Type:** final class  
**Source:** `src/DTO/ConfigEdit/ExternalEditLink.php`  

Value object for external edit link configuration.

Represents the configuration for opening an external configuration form
(e.g., admin UI) for a node. This is useful when:
- Configuration is managed by a 3rd party system
- You need a specialized UI not supported by FlowDrop forms
- Config includes complex nested structures or file uploads.

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$url` | `string` | — | The URL template for the external edit form. Supports template variables like {nodeTypeId}, {instanceId}. |
| `$label` | `string` | "Configure" | Human-readable label for the link (e.g., "Configure in Admin Portal"). |
| `$icon` | `string` | "mdi:cog" | Icon identifier (e.g., "mdi:cog", "mdi:open-in-new"). |
| `$description` | `string` | "" | Description text explaining what the link does. |
| `$parameterMapping` | `array` | [] | Maps URL template variables to node data paths. Example: ["trigger_config_id" => "config.trigger_config_id"]. |
| `$openInNewTab` | `bool` | TRUE | Whether to open the link in a new browser tab. Default TRUE. |

### Methods

#### `static fromArray(array $data): self`

Creates an instance from an array.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The array data to create the instance from. |

#### `toArray(): array`

Converts the object to an array suitable for JSON serialization.

---

## ConfigEditApiEndpoints

**Namespace:** `Drupal\flowdrop\DTO\ConfigEdit`  
**Type:** final class  
**Source:** `src/DTO/ConfigEdit/ConfigEditApiEndpoints.php`  

Value object for config edit API endpoints.

Represents the API endpoints for CRUD operations on dynamically managed
configuration entities. This allows the frontend to programmatically
create, read, update, and delete configuration entities associated
with a node.

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$create` | `?string` | NULL | URL for creating new configuration (POST). |
| `$read` | `?string` | NULL | URL template for reading configuration (GET). Supports template variables like {id}. |
| `$update` | `?string` | NULL | URL template for updating configuration (PATCH/PUT). Supports template variables like {id}. |
| `$delete` | `?string` | NULL | URL template for deleting configuration (DELETE). Supports template variables like {id}. |
| `$custom` | `array` | [] | Additional custom endpoints (e.g., "eventTypes" => "/api/event-types"). |

### Methods

#### `static fromArray(array $data): self`

Creates an instance from an array.

| Parameter | Type | Description |
|-----------|------|-------------|
| `$data` | `array` | The array data to create the instance from. |

#### `toArray(): array`

Converts the object to an array suitable for JSON serialization.

---

## See Also

- [Node Processor Plugin API](node-processor.md) — plugin interfaces that use these DTOs
- [BC Policy](bc-policy.md) — backward compatibility guarantees

---

*This page was auto-generated from source code PHPDoc annotations. Run `php scripts/generate-api-docs.php` to regenerate.*
