# API Reference

This page documents the **stable contracts** exposed by `dxaws-acm`.

The goal of this module is to provide a small, durable surface area that higher-level orchestrators (e.g., `dxaws-website`) can depend on without coupling to AWS SDK details.

```{toctree}
:maxdepth: 2

api/modules
```

---

## Primary Entry Point

### `AcmManager`

```python
from dxaws_acm.manager import AcmManager
```

The manager coordinates planning and execution.

Primary method:

```python
AcmManager.execute(desired: AcmDesired, *, options: ExecuteOptions | None = None) -> AcmManagerResult
```

This method:

1. Reads current state
2. Plans differences
3. Applies changes
4. Optionally waits for convergence

It is safe to call repeatedly (idempotent).

---

## Desired Model

### `AcmDesired`

```python
from dxaws_acm.models import AcmDesired
```

Fields:

- `domain_name: str`
- `subject_alternative_names: list[str]`
- `hosted_zone_id: str`
- `region: str`
- `tags: dict[str, str]`

This describes the **target certificate state**.

---

## Result Model

### `AcmManagerResult`

Returned from `execute()`.

Key fields:

- `desired`
- `current`
- `plan`
- `outputs`
- `outcome` (`"noop" | "applied" | "failed"`)

### `AcmOutputs`

Key fields:

- `certificate_arn: str`
- `status: str`

---

## Execution Options

### `ExecuteOptions`

```python
from dxaws_acm.manager import ExecuteOptions, ApplyOptions
```

Fields:

- `apply_options: ApplyOptions | None`
- `emit_events: bool`

### `ApplyOptions`

Controls polling and wait behavior.

Fields:

- `max_wait_seconds: int`
- `poll_interval_seconds: int`
- `dns_ttl: int`
- `emit_events: bool`

---

## Providers

Providers encapsulate AWS-specific logic.

### `AwsProvider`

```python
from dxaws_acm.providers.aws import AwsProvider
```

Responsibilities:

- `list_certificates()`
- `describe_certificate()`
- `request_dns_validated_certificate()`
- `delete_certificate()`
- `get_dns_validation_records()`

All boto3 interaction lives here.

### `Route53RecordProvider`

```python
from dxaws_acm.providers.route53 import Route53RecordProvider
```

Responsibilities:

- `resolve_zone_id(zone_name: str) -> str`
- `upsert_record(...)`
- `delete_record(...)`

---

## Stability Contract

The following are considered **stable integration points**:

- `AcmManager.execute()`
- `AcmDesired`
- `AcmManagerResult`
- `AcmOutputs`

Internal planner logic and AWS normalization details are intentionally hidden behind these contracts.

Higher-level modules should depend only on these surfaces.