custom_components/
└── <domain>/                # The unique domain name (e.g., "my_cool_device")
    ├── __init__.py          # Setup entry point (async_setup_entry, unload_entry)
    ├── manifest.json        # Metadata
    ├── config_flow.py       # UI Configuration logic
    ├── const.py             # Constants (DOMAIN, CONF_HOST, etc.)
    ├── coordinator.py       # (Recommended) Central data fetching logic
    ├── strings.json         # Translation keys for Config Flow
    ├── translations/
    │   └── en.json          # Generated translation file
    ├── services.yaml        # (Optional) Custom service definitions
    └── [platform].py        # entity files: sensor.py, binary_sensor.py, light.py, etc.

{
  "domain": "your_domain",
  "name": "Your Integration Name",
  "version": "1.0.0",
  "codeowners": ["@your_github_username"],
  "documentation": "https://github.com/username/repo",
  "requirements": ["some-pypi-package==1.2.3"],
  "iot_class": "local_polling",
  "config_flow": true
}

"""Constants for the Example Integration."""
from logging import Logger, getLogger

LOGGER: Logger = getLogger(__package__)

DOMAIN = "example_domain"
CONF_REFRESH_RATE = "refresh_rate"
DEFAULT_REFRESH_RATE = 30

from datetime import timedelta
from homeassistant.core import HomeAssistant
from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
from .const import DOMAIN, LOGGER

class MyCoordinator(DataUpdateCoordinator):
    """Class to manage fetching data from the API."""

    def __init__(self, hass: HomeAssistant, api_client) -> None:
        """Initialize."""
        super().__init__(
            hass,
            LOGGER,
            name=DOMAIN,
            update_interval=timedelta(seconds=30),
        )
        self.api = api_client

    async def _async_update_data(self):
        """Fetch data from API endpoint."""
        try:
            return await self.api.get_data()
        except Exception as err:
            raise UpdateFailed(f"Error communicating with API: {err}")

from homeassistant.config_entries import ConfigEntry
from homeassistant.core import HomeAssistant
from .const import DOMAIN
from .coordinator import MyCoordinator

PLATFORMS = ["sensor", "binary_sensor"]

async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Set up from a config entry."""
    coordinator = MyCoordinator(hass, entry.data["host"])
    await coordinator.async_config_entry_first_refresh()

    hass.data.setdefault(DOMAIN, {})
    hass.data[DOMAIN][entry.entry_id] = coordinator

    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
    return True

async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Unload a config entry."""
    if unload_ok := await hass.config_entries.async_unload_platforms(entry, PLATFORMS):
        hass.data[DOMAIN].pop(entry.entry_id)
    return unload_ok

from homeassistant.helpers.update_coordinator import CoordinatorEntity
from homeassistant.components.sensor import SensorEntity

class MyDeviceSensor(CoordinatorEntity, SensorEntity):
    """Representation of a Sensor."""
    _attr_has_entity_name = True

    def __init__(self, coordinator, device_id):
        super().__init__(coordinator)
        self._device_id = device_id
        self._attr_unique_id = f"{coordinator.config_entry.entry_id}_{device_id}"
        self._attr_name = "Temperature"

    @property
    def native_value(self):
        """Return the state of the sensor."""
        return self.coordinator.data.get(self._device_id, {}).get("temperature")

    @property
    def device_info(self):
        """Return device registry information."""
        return {
            "identifiers": {(DOMAIN, self._device_id)},
            "name": "My Device Name",
            "manufacturer": "Acme Corp",
        }

STEP_USER_DATA_SCHEMA = vol.Schema({
    vol.Required("host"): str,
    vol.Required("username"): str,
    vol.Required("password"): str,
    vol.Optional("port", default=80): int,
})

async def validate_input(hass: HomeAssistant, data: dict[str, Any]) -> dict[str, Any]:
    """Validate the user input allows us to connect."""
    hub = Hub(data["host"], data["username"], data["password"])
    
    try:
        # Test connection/auth
        await hub.authenticate()
    except InvalidAuth:
        raise
    except CannotConnect:
        raise
        
    return {"title": f"My Device ({data['host']})"}

class ConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
    VERSION = 1

    async def async_step_user(self, user_input=None):
        """Handle the initial step."""
        errors = {}
        
        if user_input is not None:
            try:
                info = await validate_input(self.hass, user_input)
                return self.async_create_entry(title=info["title"], data=user_input)
            except CannotConnect:
                errors["base"] = "cannot_connect"
            except InvalidAuth:
                errors["base"] = "invalid_auth"
            except Exception:
                _LOGGER.exception("Unexpected exception")
                errors["base"] = "unknown"

        return self.async_show_form(
            step_id="user",
            data_schema=STEP_USER_DATA_SCHEMA,
            errors=errors,
        )

_LOGGER.debug("Received payload: %s", payload) # BAD if payload has secrets
_LOGGER.debug("Recieved payload: %s", async_redact_data(payload, TO_REDACT)) # GOOD

from homeassistant.exceptions import ConfigEntryNotReady

async def async_setup_entry(hass, entry):
    try:
        await api.connect()
    except CannotConnect as err:
        raise ConfigEntryNotReady(f"Timeout connecting to {host}") from err

async def _async_update_data(self):
    try:
        data = await self.api.get_status()
    except ApiError as err:
        raise UpdateFailed(f"Error fetching data: {err}")

# Setting unique ID (required for discovery)
await self.async_set_unique_id(device_unique_id)
self._abort_if_unique_id_configured()

from homeassistant.config_entries import OptionsFlow, OptionsFlowWithReload
import voluptuous as vol

OPTIONS_SCHEMA = vol.Schema({
    vol.Required("show_things"): bool,
})

class OptionsFlowHandler(OptionsFlow):
    async def async_step_init(self, user_input=None):
        """Manage the options."""
        if user_input is not None:
            return self.async_create_entry(data=user_input)
        return self.async_show_form(
            step_id="init",
            data_schema=self.add_suggested_values_to_schema(
                OPTIONS_SCHEMA, self.config_entry.options
            ),
        )

async def async_step_reauth(self, entry_data):
    await self.async_step_reauth_confirm()

async def async_step_reauth_confirm(self, user_input=None):
    if user_input is None:
        return self.async_show_form(step_id="reauth_confirm")
    return self.async_update_reload_and_abort(
        self._get_reauth_entry(), data_updates=new_data)

{
  "config": {
    "abort": { "already_configured": "Already configured" },
    "step": { "user": { "title": "Login", "description": "Enter password" } },
    "error": { "invalid_auth": "Invalid credentials" }
  }
}

async def async_migrate_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Migrate old entry."""
    _LOGGER.debug("Migrating from version %s", entry.version)

    if entry.version == 1:
        new_data = {**entry.data, "new_key": "default_value"}
        hass.config_entries.async_update_entry(entry, data=new_data, version=2)

    _LOGGER.info("Migration to version %s successful", entry.version)
    return True

async_create_issue(
    hass,
    DOMAIN,
    "deprecated_yaml",
    breaks_in_ha_version="2025.1.0",
    is_fixable=False,
    severity=IssueSeverity.WARNING,
    translation_key="deprecated_yaml",
)

from homeassistant.helpers import entity_registry as er

async def async_setup_entry(hass, entry):
    ent_reg = er.async_get(hass)
    # Remove specific old entity
    if ent_reg.async_get_entity_id("sensor", DOMAIN, "old_unique_id"):
        ent_reg.async_remove("sensor.my_device_old_sensor")

from homeassistant.helpers.redact import async_redact_data

TO_REDACT = [CONF_API_KEY, APPLIANCE_CODE]

async def async_get_config_entry_diagnostics(
    hass: HomeAssistant, entry: MyConfigEntry
) -> dict[str, Any]:
    """Return diagnostics for a config entry."""
    return {
        "entry_data": async_redact_data(entry.data, TO_REDACT),
        "data": entry.runtime_data.data,
    }

from homeassistant.components import system_health
from homeassistant.core import HomeAssistant, callback

@callback
def async_register(hass: HomeAssistant, register: system_health.SystemHealthRegistration) -> None:
    """Register system health callbacks."""
    register.async_register_info(system_health_info)

async def system_health_info(hass: HomeAssistant) -> dict[str, Any]:
    """Get info for the info page."""
    return {
        "can_reach_server": system_health.async_check_can_reach_url(hass, ENDPOINT),
    }

# Fire event
hass.bus.fire("my_domain_event", {"answer": 42})

# Listen to event
def handle_event(event):
    print(f"Answer: {event.data.get('answer')}")
hass.bus.listen("my_domain_event", handle_event)

# Set state
hass.states.set("hello_state.my_state", "Hello World")

# Entity attributes
@property
def extra_state_attributes(self):
    """Return entity specific state attributes."""
    return self._attributes

from homeassistant.components.button import ButtonEntity

class MyButton(ButtonEntity):
    async def async_press(self) -> None:
        """Handle the button press."""
        # Action logic here

from homeassistant.components.binary_sensor import BinarySensorEntity

class MySensor(BinarySensorEntity):
    @property
    def is_on(self) -> bool:
        return self._is_on

    @property
    def device_class(self):
        return BinarySensorDeviceClass.MOTION

from homeassistant.components.number import NumberEntity

class MyNumber(NumberEntity):
    _attr_native_min_value = 0
    _attr_native_max_value = 100
    _attr_native_step = 1
    _attr_mode = "slider"  # or "box", "auto"

    async def async_set_native_value(self, value: float) -> None:
        """Update the current value."""

from homeassistant.components.select import SelectEntity

class MySelect(SelectEntity):
    @property
    def options(self) -> list[str]:
        return ["option1", "option2", "option3"]

    @property
    def current_option(self) -> str | None:
        return self._current

    async def async_select_option(self, option: str) -> None:
        """Change the selected option."""

from homeassistant.components.time import TimeEntity
from datetime import time

class MyTime(TimeEntity):
    @property
    def native_value(self) -> time:
        return self._time

    async def async_set_value(self, value: time) -> None:
        """Update the current value."""

from homeassistant.components.image import ImageEntity

class MyImage(ImageEntity):
    async def async_image(self) -> bytes | None:
        """Return bytes of image."""
        return self._cached_image

from homeassistant.components.media_player import MediaPlayerEntity, MediaPlayerEntityFeature

class MyPlayer(MediaPlayerEntity):
    _attr_supported_features = (
        MediaPlayerEntityFeature.PLAY |
        MediaPlayerEntityFeature.PAUSE |
        MediaPlayerEntityFeature.VOLUME_SET
    )

from homeassistant.components.sensor import SensorStateClass

class MyEnergySensor(SensorEntity):
    _attr_state_class = SensorStateClass.TOTAL_INCREASING # For meters
    _attr_state_class = SensorStateClass.MEASUREMENT      # For current values (temp, power)

from homeassistant.const import EntityCategory

class MyDebugSensor(SensorEntity):
    _attr_entity_category = EntityCategory.DIAGNOSTIC # or EntityCategory.CONFIG

play_media:
  name: Play Media
  fields:
    media_content_id:
      name: Content ID
      example: "media-source://jellyfin/..."
      selector:
        text:
    entity_id:
      name: Target Player
      selector:
        entity:
          domain: media_player

@property
def device_info(self):
    return {
        "identifiers": {(DOMAIN, self._device_id)},
        "via_device": (DOMAIN, self._hub_id), # The tuple identifier of the parent
        "name": "My Bulb",
    }

from homeassistant.components import websocket_api
import voluptuous as vol

@callback
def async_setup_entry(hass, entry):
    hass.components.websocket_api.async_register_command(
        hass, handle_my_command
    )

@websocket_api.websocket_command({
    vol.Required("type"): "jellyha/search",
    vol.Required("query"): str,
})
@websocket_api.async_response
async def handle_my_command(hass, connection, msg):
    """Handle the search command."""
    query = msg["query"]
    try:
        results = await my_search_function(query)
        connection.send_result(msg["id"], results)
    except Exception as err:
        connection.send_error(msg["id"], "search_failed", str(err))

try {
  const results = await this.hass.callWS({
    type: "jellyha/search",
    query: "Rick Astley",
  });
  console.log("Found:", results);
} catch (err) {
  console.error("Search failed:", err);
}

import { LitElement, html, css } from "https://unpkg.com/lit-element@2/lit-element.js?module";

class MyCard extends LitElement {
  static get properties() {
    return { hass: {}, config: {} };
  }

  setConfig(config) {
    if (!config.entity) throw new Error("Please define an entity");
    this.config = config;
  }

  static getStubConfig() {
    return { type: "custom:my-card", entity: "sun.sun" };
  }

  getCardSize() {
    return 1; // 1 = 50px
  }

  render() {
    return html`
      <ha-card header="My Card">
        <div class="card-content">
          ${this.hass.states[this.config.entity]?.state}
        </div>
      </ha-card>
    `;
  }

  static get styles() {
    return css`
      .card-content { padding: 16px; }
    `;
  }
}

customElements.define("my-card", MyCard);

window.customCards = window.customCards || [];
window.customCards.push({
  type: "my-card",
  name: "My Card",
  description: "A custom card"
});

class ExamplePanel extends LitElement {
  static get properties() {
    return {
      hass: { type: Object },
      narrow: { type: Boolean },
      route: { type: Object },
      panel: { type: Object },
    };
  }

  render() {
    return html`
      <p>There are ${Object.keys(this.hass.states).length} entities.</p>
    `;
  }
}
customElements.define("example-panel", ExamplePanel);

panel_custom:
  - name: example
    url_path: example
    sidebar_title: Example Panel
    sidebar_icon: mdi:server
    module_url: /local/example/panel.js

interface MyCardConfig {
  columns?: number;
  min_columns?: number;
  max_columns?: number;
  max_rows?: number;
}

import { styleMap } from 'lit/directives/style-map.js';

render() {
  const minCols = this.config.min_columns || 2;
  const maxCols = this.config.max_columns || 4;

  const styles = {
    '--min-cols': minCols,
    '--max-cols': maxCols,
  };

  return html`
    <ha-card>
      <div class="grid" style=${styleMap(styles)}>
        ${this._items.map(item => html`<div class="item">...</div>`)}
      </div>
    </ha-card>
  `;
}

static get styles() {
  return css`
    .grid {
      display: grid;
      /* Dynamic responsiveness constrained by config */
      grid-template-columns: repeat(auto-fit, minmax(
        max(150px, 100% / var(--max-cols)),
        1fr
      ));
      gap: 8px;
    }
  `;
}

const maxRows = this.config.max_rows || 3;
const cols = this.config.columns || 3;
const limit = maxRows * cols;
const visibleItems = this._items.slice(0, limit);

render() {
  return html`
    <ha-card .header=${this.config.title}>
      <div class="card-content">
        <!-- content -->
      </div>
    </ha-card>
  `;
}

getCardSize() {
  // Example: 1 unit for header + 1 unit per 3 items
  return 1 + Math.ceil(this.items.length / 3);
}

// Helper to fire haptic events
function fireHaptic(node, pattern) {
  const event = new CustomEvent("haptic", {
    detail: pattern, // "success", "warning", "failure", "light", "medium", "heavy", "selection"
    bubbles: true,
    composed: true,
  });
  node.dispatchEvent(event);
}

// Usage in event handler
_handleTap(e) {
  fireHaptic(this, "light");
}

// Simple implementation pattern
_handleAction(ev) {
  const config = this.config;
  const action = ev.detail.action; // 'tap', 'hold', 'double_tap'
  
  if (config && config[`${action}_action`]) {
    // Handle specific action config
    // e.g. navigate, toggle, call-service, fire-dom-event
  }
}

this.dispatchEvent(new CustomEvent('my-custom-event', {
  detail: { item: this.item },
  bubbles: true,
  composed: true,
}));

:host {
  /* Define local variable with fallback to HA theme variable or default */
  --jellyha-movie-color: var(--warning-color, #ff9800);
}

.movie-badge {
  background-color: var(--jellyha-movie-color);
  color: var(--primary-text-color);
}

const isDark = this.hass.themes.darkMode;

public static getConfigElement(): HTMLElement {
  return document.createElement('my-card-editor');
}

class MyCardEditor extends LitElement {
  setConfig(config) {
    this._config = config;
  }

  _valueChanged(ev) {
    if (!this._config || !this.hass) return;
    const target = ev.target;
    // Fire the standard event that HA listens for
    // Use the fireEvent helper defined in your utils
    const event = new CustomEvent("config-changed", {
      detail: { config: {
        ...this._config,
        [target.configValue]: target.checked !== undefined ? target.checked : target.value,
      }},
      bubbles: true,
      composed: true,
    });
    this.dispatchEvent(event);
  }

  render() {
    return html`
      <div class="card-config">
        <ha-textfield
          label="Title"
          .value=${this._config.title || ''}
          .configValue=${"title"}
          @input=${this._valueChanged}
        ></ha-textfield>
        <ha-switch
          .checked=${this._config.show_icon !== false}
          .configValue=${"show_icon"}
          @change=${this._valueChanged}
        >Show Icon</ha-switch>
      </div>
    `;
  }
}

render() {
  return html`
    <ha-selector
      .hass=${this.hass}
      .selector=${{ entity: { domain: "media_player" } }}
      .value=${this._config.entity}
      .configValue=${"entity"}
      @value-changed=${this._valueChanged}
    ></ha-selector>
  `;
}

from homeassistant.helpers.issue_registry import async_create_issue, IssueSeverity

async_create_issue(
    hass,
    DOMAIN,
    "deprecated_auth",
    is_fixable=False,
    severity=IssueSeverity.WARNING,
    translation_key="deprecated_auth",
)

from homeassistant.helpers.typing import ConfigType, DiscoveryInfoType
from homeassistant.core import HomeAssistant

async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
    ...

async def test_form(hass):
    result = await hass.config_entries.flow.async_init(
        DOMAIN, context={"source": config_entries.SOURCE_USER}
    )
    assert result["type"] == "form"
    
    result2 = await hass.config_entries.flow.async_configure(
        result["flow_id"],
        {"host": "1.1.1.1"},
    )
    assert result2["type"] == "create_entry"

async def test_sensor(hass):
    # Mock data, setup entry...
    state = hass.states.get("sensor.my_device")
    assert state.state == "123"

from importlib.metadata import version
__version__ = version("homeassistant.components.jellyha") # or domain

TRIGGER_SCHEMA = vol.Schema({
    vol.Required(CONF_PLATFORM): "device",
    vol.Required(CONF_DOMAIN): DOMAIN,
    vol.Required(CONF_DEVICE_ID): str,
    vol.Required(CONF_TYPE): "button_pressed",
})

async def async_attach_trigger(hass, config, action, automation_info):
    """Listen for the event and call action."""
    return await hass.components.homeassistant.triggers.event.async_attach_trigger(
        hass,
        event_trigger_config, # templated config listening for specific event
        action,
        automation_info,
    )

name: Validate
on: [push, pull_request]
jobs:
  hassfest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: home-assistant/actions/hassfest@master
  
  hacs_validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: hacs/action@main
        with:
          category: integration