# `Hephaestus.Connectors.Connector`
[🔗](https://github.com/hephaestus-org/hephaestus_core/blob/v0.3.1/lib/hephaestus/connectors/connector.ex#L1)

Contract for external service connectors.

# `action`

```elixir
@type action() :: atom()
```

An atom identifying the operation to perform on the external service.

Each connector defines its own set of supported actions (e.g., `:get_task`, `:create_task`).

# `config`

```elixir
@type config() :: map()
```

A map of configuration values required by the connector.

Typically holds credentials and connection settings (e.g., `%{api_key: "secret"}`).

# `error_reason`

```elixir
@type error_reason() :: term()
```

The reason for a failed action execution.

Can be any term, though atoms like `:unsupported_action` or descriptive strings are recommended.

# `params`

```elixir
@type params() :: map()
```

A map of input parameters for the action being executed.

The expected keys depend on the specific action (e.g., `%{task_id: "123"}` for a `:get_task` action).

# `result`

```elixir
@type result() :: map()
```

A map containing the data returned by a successful action execution.

# `execute`

```elixir
@callback execute(action(), params(), config()) ::
  {:ok, result()} | {:error, error_reason()}
```

Executes the given `action` against the external service.

Receives the action to perform, a map of `params` specific to that action,
and a `config` map with credentials or connection settings.

Returns `{:ok, result}` on success or `{:error, reason}` on failure.

# `supported_actions`

```elixir
@callback supported_actions() :: [action()]
```

Returns the list of actions supported by this connector.

---

*Consult [api-reference.md](api-reference.md) for complete listing*