Add the apps and widgets API

[joostlek]

Proposed Changes

(Describe the changes and rationale behind them)

Only next and prev were covered, which left the whole app control surface unreachable. This adds the remaining four endpoints:

Method	Endpoint
apps()	GET /device/apps
app()	GET /device/apps/:package
activate_widget()	PUT /device/apps/:pkg/widgets/:id/activate
app_action()	POST /device/apps/:pkg/widgets/:id/actions

apps = await lametric.apps()
clock = apps["com.lametric.clock"]

await lametric.activate_widget(
    package=clock.package,
    widget_id="1_com.lametric.clock",
)
await lametric.app_action(
    package=clock.package,
    widget_id="1_com.lametric.clock",
    action="clock.alarm",
    params={"enabled": True, "time": "07:00:00"},
)

Apps and widgets come back keyed by package name and widget ID, the way the device reports them, rather than converted to lists — the keys are meaningful and are what the other endpoints take as path segments.

Actions are addressed by name with a free form params mapping. Each app declares its own actions and their parameter specs, and both are reported by apps() and app(), so callers can discover what is available rather than having it hardcoded here.

Model notes

App, Widget and AppParameter follow what the device actually sends. Three fields are optional, each for a specific reason worth recording:

• App.actions — apps with no actions omit the key entirely, as com.lametric.custommessage does.
• AppParameter.required — present on action parameters, absent on trigger parameters.
• Widget.visible — only reported by GET /device/apps, not by GET /device/apps/:package. The app() docstring points at apps() for visibility, and both cases are covered by tests.

Widget.settings is dict[str, Any], since its contents are specific to each app.

The fixtures are real responses from a LaMetric TIME (model sa8, OS 3.2.7). All six of its apps parse, including the empty-actions and empty-parameter cases. All four methods were verified against that device: listing, fetching one app, activating a widget, and running stopwatch.start, stopwatch.pause and stopwatch.reset.

app_action() carries a pylint: disable=too-many-arguments, matching how display() already handles the same limit.

Related Issues

(Github link to related issues or pull requests)

None.

🤖 Generated with Claude Code