Remove Helper or Integration

Remove a Home Assistant helper or integration config entry.

Unifies three backend removal mechanisms — simple-helper websocket delete, config-entry delete, and config-subentry delete — behind one entry point with four routing paths driven by helper_type.

WHEN NOT TO USE:

• Removing only an entity (without deleting its underlying helper or config entry) — use ha_remove_entity instead.

• YAML-configured helpers — they have no storage backend. Edit the YAML file and reload the relevant integration.

SUPPORTED HELPER TYPES:

• SIMPLE (12, websocket-delete): input_button, input_boolean, input_select, input_number, input_text, input_datetime, counter, timer, schedule, zone, person, tag.

• FLOW (15, config-entry-delete via entity lookup): template, group, utility_meter, derivative, min_max, threshold, integration, statistics, trend, random, filter, tod, generic_thermostat, switch_as_x, generic_hygrostat.

ROUTING:

• SIMPLE helper_type + bare helper_id or entity_id → websocket delete.

• FLOW helper_type + entity_id → resolve entity_id to config_entry_id via entity_registry, then delete the config entry. All sub-entities (e.g. utility_meter tariffs) are removed together.

• helper_type=None + entry_id → direct config entry delete (any integration).

• helper_type="config_subentry" + parent entry_id + subentry_id → delete one config subentry.

MISSING-TARGET CONTRACT: A target that is confirmed absent raises a structured error rather than returning silent success, so a typo'd or stale identifier surfaces immediately at the caller layer (the success boolean is what agent wrappers branch on). The error code per-path follows the target shape:

• SIMPLE (bare helper_id or entity_id): state-machine empty AND entity registry empty → raises ENTITY_NOT_FOUND.

• FLOW (entity_id): not in entity registry → raises ENTITY_NOT_FOUND. YAML-configured helpers (no config entry backing) raise RESOURCE_NOT_FOUND. A bare helper_id (no .) on a FLOW target raises ENTITY_NOT_FOUND — FLOW resolution needs a full entity_id. TOCTOU 404 on the resolved entry_id raises RESOURCE_NOT_FOUND.

• Direct config entry (helper_type=None): backend returns HTTP 404 → raises RESOURCE_NOT_FOUND.

• Config subentry: backend returns a "not_found" error → raises RESOURCE_NOT_FOUND.

Idempotency at the contract level still holds (call N times = same response). Transient connectivity failures (WebSocket disconnected, network timeouts) raise their own codes (WEBSOCKET_DISCONNECTED, CONNECTION_FAILED) so retry logic can branch separately.

EXAMPLES:

• Remove SIMPLE button: ha_remove_helpers_integrations( target="my_button", helper_type="input_button", confirm=True )

• Remove FLOW utility_meter (any sub-entity works): ha_remove_helpers_integrations( target="sensor.energy_peak", helper_type="utility_meter", confirm=True, )

• Remove any integration by entry_id: ha_remove_helpers_integrations( target="01HXYZ...", confirm=True )

• Remove a config subentry: ha_remove_helpers_integrations( target="01HXYZ...", helper_type="config_subentry", subentry_id="subentry-123", confirm=True )

WARNING: Removing a helper or integration that is referenced by automations, scripts, or other integrations may cause those to fail. Use ha_search() / ha_get_integration() to verify before removal. Cannot be undone.