Apps and instances
getChildApps, getParent, getChildAppById, listSmartAppInstances, runSmartApp, pauseSmartApp, resumeSmartApp
Global functions available to smart-app code. Call them by bare name; there is no object to import.
| Function | Summary |
|---|---|
getChildApps | Child instances of this app (declared via childApps in the manifest). |
getParent | The parent instance of this child app. |
getChildAppById | Look up one child instance by its app id. |
listSmartAppInstances | Lists every running smart-app instance on the hub EXCEPT the caller's own instance. |
runSmartApp | Fire-and-forget invocation of another smart-app instance's run() lifecycle — equivalent to the SPA's Run button or a press of the target's companion input_button. |
pauseSmartApp | Pause / resume a smart-app instance. |
resumeSmartApp | Resume a paused smart-app instance so its triggers fire again. |
getChildApps
Not available to AI-generated user automations.
Child instances of this app (declared via childApps in the manifest).
Signature
function getChildApps(): SmartAppInstanceHandle[]Parameters
None.
Returns
SmartAppInstanceHandle[] — [] for childless instances.
See also
getParent
Not available to AI-generated user automations.
The parent instance of this child app.
Signature
function getParent(): SmartAppInstanceHandle | nullParameters
None.
Returns
SmartAppInstanceHandle \| null — null when this app has no parent.
See also
getChildAppById
Not available to AI-generated user automations.
Look up one child instance by its app id.
Signature
function getChildAppById(appId: string): SmartAppInstanceHandle | nullParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
appId | string | yes | — | The child instance id (as returned in a SmartAppInstanceHandle). |
Returns
SmartAppInstanceHandle \| null
listSmartAppInstances
Not available to AI-generated user automations.
Lists every running smart-app instance on the hub EXCEPT the caller's own instance. Used to populate "pick a smart app to run" pickers in wizard preferences. The label field carries the operator-supplied friendly label (null when unset) so callers can render label ?? appName.
Signature
function listSmartAppInstances(): Array<{ appId: string; appDefinitionId: string; appName: string; label: string | null; parentAppId: string | null; }>Parameters
None.
Returns
Array<{ appId, appDefinitionId, appName, label, parentAppId }> — Every other running instance on the hub (the caller is excluded). label is the operator’s friendly name or null.
Examples
options: listSmartAppInstances().map((a) => ({ value: a.appId, label: a.label ?? a.appName }))See also
runSmartApp
Not available to AI-generated user automations.
Fire-and-forget invocation of another smart-app instance's run() lifecycle — equivalent to the SPA's Run button or a press of the target's companion input_button. The host refuses self-runs (reason: 'self-run-refused') and unknown targets (reason: 'target-not-found'); on success returns { ok: true }. Whether the target actually fires depends on its own paused-state gate — paused apps silently no-op.
Signature
function runSmartApp(appId: string): { ok: boolean; reason?: string }Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
appId | string | yes | — | Target instance id. |
Returns
{ ok: boolean; reason?: string } — reason is self-run-refused or target-not-found. A paused target silently no-ops.
Notes
- Not available to AI-generated user automations.
pauseSmartApp
Not available to AI-generated user automations.
Pause / resume a smart-app instance. Pass an empty string (or the caller's own appId) for self. Paused apps don't fire on their configured triggers until resumed. The host emits running-state change events on every transition so the SPA reflects the new state immediately. Returns { ok: false, reason } on missing target.
durationSeconds (optional, pause only) schedules a host-side auto-resume that fires regardless of the target's paused state — the auto-resume timer runs off the host's setTimeout, not the runner's own scheduler. Non-durable across hub restart: a reboot mid-snooze leaves the target paused until manually resumed.
Signature
function pauseSmartApp(appId: string, durationSeconds?: number): { ok: boolean; reason?: string }Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
appId | string | yes | — | Target instance id, or "" for this instance. |
durationSeconds | number | no | — | Auto-resume after this many seconds. The timer is host-side and not durable across a reboot. |
Returns
{ ok: boolean; reason?: string }
Notes
- Not available to AI-generated user automations.
See also
resumeSmartApp
Not available to AI-generated user automations.
Resume a paused smart-app instance so its triggers fire again.
Signature
function resumeSmartApp(appId: string): { ok: boolean; reason?: string }Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
appId | string | yes | — | Target instance id, or "" for this instance. |
Returns
{ ok: boolean; reason?: string }
Notes
- Not available to AI-generated user automations.