Expose user-defined ESPHome services as first-class API functions

[Copilot]

ListEntitiesServicesResponse (msg twocolors#41) and ExecuteServiceRequest (msg twocolors#42) existed in the protobuf layer but were not surfaced through the library, forcing consumers to reach into pb internals to use user-defined services.

Changes

• lib/connection.js

  • listEntitiesService() now collects ListEntitiesServicesResponse entries (exposed as component: 'Services')
  • New executeServiceService({ key, args }) — builds and sends ExecuteServiceRequest, supporting all 8 arg types (bool, int, float, string, and their array variants)

• index.js — exports ServiceArgType with friendly keys (Bool, Int, Float, String, BoolArray, IntArray, FloatArray, StringArray) mapped from the protobuf enum

• index.d.ts — adds ServiceArgType, ListEntitiesServicesArgument, ListEntitiesServicesResponse, ExecuteServiceArgument, ExecuteServiceCommandData; extends Components, Entities, Connection, and adds on/off overloads for message.ListEntitiesServicesResponse

• README.md — new synopsis example + ### User-defined Services section documenting ServiceArgType values, service discovery, execution, and the raw connection event

Usage

const { Connection, ServiceArgType } = require('@2colors/esphome-native-api');

connection.on('authorized', async () => {
    const entities = await connection.listEntitiesService();
    const services = entities.filter(e => e.component === 'Services');
    // services[0] => { name: 'my_service', key: 1234567890, argsList: [...] }

    connection.executeServiceService({
        key: services[0].key,
        args: [
            { type: ServiceArgType.Int,    value: 100     },
            { type: ServiceArgType.String, value: 'hello' },
        ],
    });
});

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Exposes user defined services as function</issue_title>
<issue_description>Inspired by DrozmotiX/ioBroker.esphome#406

Those functions should be exposed and documented in the lib to be easier usable than importing additional {pb} backend module for usage</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Exposes user defined services as function #1

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR exposes ESPHome “user-defined services” through the public library API (service discovery + execution) so consumers no longer need to use pb internals.

Changes:

• Extend listEntitiesService() to include ListEntitiesServicesResponse entries (component "Services").
• Add executeServiceService({ key, args }) to send ExecuteServiceRequest with typed arguments.
• Export ServiceArgType, update TypeScript declarations, and document discovery/execution usage in the README.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 6 comments.

File	Description
lib/connection.js	Adds services discovery to the entity listing + implements service execution request building.
index.js	Exports a friendly ServiceArgType mapping derived from the protobuf enum.
index.d.ts	Adds typings for service discovery/execution data and connection event overloads.
README.md	Documents how to discover and call user-defined services and the related connection event.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.