# Block Implementation Template

Use this template when adding a new AWS Connect block type to CxBlueprint.

## Before You Start

1. Find the block in the AWS API reference: https://docs.aws.amazon.com/connect/latest/APIReference/API-reference-contact-flow-actions.html
2. Read the block's **Parameters**, **Results**, **Conditions**, and **Errors** sections
3. Decide which category directory it belongs in:
   - `participant_actions/` — actions on the caller (prompts, input, disconnect, bots)
   - `contact_actions/` — actions on the contact record (attributes, queues, recording)
   - `flow_control_actions/` — flow logic (branching, wait, transfer, end)
   - `interactions/` — external integrations (Lambda, callbacks)

## File Template (blocks with typed parameters)

```python
"""
BlockTypeName - Short description from AWS docs.
https://docs.aws.amazon.com/connect/latest/APIReference/<category>-<blockname>.html
"""

from dataclasses import dataclass
from typing import Optional
import uuid
from ..base import FlowBlock


@dataclass
class BlockTypeName(FlowBlock):
    """
    Description from AWS docs.

    Results:
        - List each result type from the AWS docs

    Errors:
        - List each error type from the AWS docs

    Restrictions:
        - Channel restrictions, flow type restrictions, etc.
    """

    # Typed fields for each AWS Parameter (use Python types, not strings)
    some_param: Optional[str] = None
    timeout_seconds: int = 60

    def __post_init__(self):
        self.type = "BlockTypeName"  # Must match AWS Type string exactly
        self._build_parameters()

    def _build_parameters(self):
        """Build parameters dict from typed attributes."""
        params = {}
        if self.some_param is not None:
            params["SomeParam"] = self.some_param
        params["TimeoutSeconds"] = str(self.timeout_seconds)  # AWS wants strings
        self.parameters = params

    def __repr__(self) -> str:
        return f"BlockTypeName(some_param='{self.some_param}')"

    def to_dict(self) -> dict:
        self._build_parameters()
        return super().to_dict()

    @classmethod
    def from_dict(cls, data: dict) -> "BlockTypeName":
        params = data.get("Parameters", {})
        return cls(
            identifier=data.get("Identifier", str(uuid.uuid4())),
            some_param=params.get("SomeParam"),
            timeout_seconds=int(params.get("TimeoutSeconds", "60")),
            parameters=params,
            transitions=data.get("Transitions", {}),
        )
```

## File Template (shell blocks — no typed parameters)

Use this for blocks where parameters are passed through as raw dicts via `flow.add()`:

```python
"""
BlockTypeName - Short description from AWS docs.
https://docs.aws.amazon.com/connect/latest/APIReference/<category>-<blockname>.html
"""

from dataclasses import dataclass
import uuid
from ..base import FlowBlock


@dataclass
class BlockTypeName(FlowBlock):
    """Short description from AWS docs."""

    def __post_init__(self):
        self.type = "BlockTypeName"  # Must match AWS Type string exactly

    def __repr__(self) -> str:
        return "BlockTypeName()"

    @classmethod
    def from_dict(cls, data: dict) -> "BlockTypeName":
        params = data.get("Parameters", {})
        return cls(
            identifier=data.get("Identifier", str(uuid.uuid4())),
            parameters=params,
            transitions=data.get("Transitions", {}),
        )
```

## Registration Checklist

After creating the block file, register it in these 4 locations:

### 1. Category `__init__.py`

Add the import and `__all__` entry in `src/cxblueprint/blocks/<category>/__init__.py`:

```python
from .block_type_name import BlockTypeName

__all__ = [
    # ... existing entries ...
    "BlockTypeName",
]
```

### 2. `BLOCK_TYPE_MAP` in `src/cxblueprint/flow_builder.py`

Add the AWS type string to class mapping:

```python
BLOCK_TYPE_MAP: Dict[str, Type[FlowBlock]] = {
    # ... existing entries ...
    "BlockTypeName": BlockTypeName,
}
```

### 3. `BLOCK_FIXTURES` in `tests/test_block_roundtrip.py`

Add minimal constructor kwargs. **CI will fail without this** — the `test_all_block_types_have_fixtures` guard test enforces it:

```python
BLOCK_FIXTURES = {
    # ... existing entries ...
    "BlockTypeName": {"some_param": "test_value", "timeout_seconds": 30},
    # Use {} for shell blocks with no typed parameters
}
```

### 4. Top-level `__init__.py` (optional)

If the block will be commonly used with `flow.add()`, export it from `src/cxblueprint/__init__.py`:

```python
from .blocks.contact_actions import BlockTypeName
```

## Optional: Convenience Method

If the block is commonly used, add a convenience method on the `Flow` class in `src/cxblueprint/flow_builder.py`:

```python
def block_type_name(self, some_param: str, timeout: int = 60) -> BlockTypeName:
    """Short description."""
    block = BlockTypeName(
        identifier=str(uuid.uuid4()),
        some_param=some_param,
        timeout_seconds=timeout,
    )
    return self._register_block(block)
```

## Key Rules

- The `self.type` string in `__post_init__` **must exactly match** the AWS Type value
- All AWS parameters are strings — convert ints/bools with `str()`, `to_aws_bool()`, `to_aws_int()`
- `from_dict` must always accept `Identifier`, `Parameters`, and `Transitions` from AWS JSON
- The module docstring **must include the AWS documentation URL** for the specific block
- The class docstring should list Results, Errors, and Restrictions from the AWS docs
