companion-action-file-pattern

Create a new src/actions/action-{category}.ts file exporting an action ID enum and a GetActions{Category} factory, then import it in actions.ts, call the factory, add the enum to the union type, and spread the result into the combined actions object.

Import the enum and factory with a .js extension, call the factory inside GetActions() storing the typed result, add the enum to the [id in ...] union type, and spread the local variable into the combined actions object returned to setActionDefinitions.

Create a new file only when adding a logically distinct category with no existing action-{category}.ts file. If a file for your category already exists, add the enum member and action definition directly to that file without touching the aggregator.

Common causes are forgetting the .js extension on ESM imports, adding the spread but not the enum to the union type, duplicating an existing action ID, or using await in a callback not marked async. Run yarn build to surface the exact TypeScript error.

Cast action.options values explicitly since TypeScript types them as any, for example action.options.level as number. For text options, use await instance.parseVariablesInString() to resolve Companion variables before use.