lumia-plugin 0.1.15 → 0.1.17

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "lumia-plugin",
-	"version": "0.1.15",
+	"version": "0.1.17",
 	"description": "Command-line tools for creating, building, and validating Lumia Stream plugins.",
 	"bin": {
 		"lumia-plugin": "scripts/cli.js"
 	},
 	"files": [
 		"scripts",
-		"examples/base-plugin",
+		"examples/base_plugin",
 		"README.md",
 		"LICENSE"
 	],
@@ -20,7 +20,7 @@
 	"author": "Lumia Stream",
 	"license": "MIT",
 	"dependencies": {
-		"@lumiastream/plugin": "^0.1.15",
+		"@lumiastream/plugin": "^0.1.17",
 		"jszip": "3.10.1"
 	}
 }

package/scripts/create-plugin.js

@@ -2,7 +2,7 @@
 const path = require("path");
 const fs = require("fs");
 
-const TEMPLATE_DIR = path.resolve(__dirname, "..", "examples", "base-plugin");
+const TEMPLATE_DIR = path.resolve(__dirname, "..", "examples", "base_plugin");
 
 function toSafeId(value) {
 	const cleaned = value

package/examples/base-plugin/GETTING_STARTED.md

@@ -1,243 +0,0 @@
-# Getting Started with Showcase Plugin Template
-
-Welcome to your new Lumia Stream plugin! This guide will help you understand the plugin structure and start building your custom functionality.
-
-## Project Structure
-
-```
-your-plugin/
-├── manifest.json    # Plugin metadata and configuration
-├── main.js          # Your plugin's main code
-├── package.json     # npm dependencies (optional)
-└── README.md        # Plugin documentation
-```
-
-## Understanding the Files
-
-### 📋 manifest.json
-
-This file defines your plugin's metadata and capabilities:
-
-- **id**: Unique identifier using letters, numbers, or underscores (e.g., "my_awesome_plugin")
-- **name**: Display name shown to users
-- **description**: Short description for the plugin marketplace
-- **main**: Entry point file (usually "main.js")
-- **config**: Defines settings, actions, and variables
-
-**Key sections:**
-- `settings`: User-configurable options for your plugin
-- `actions`: Functions users can trigger (e.g., send a message, change color)
-- `variables`: Data your plugin exposes to Lumia Stream
-
-### 🔧 main.js
-
-Your plugin's logic lives here. The main class extends the `Plugin` base class:
-
-```javascript
-class YourPlugin extends Plugin {
-  constructor(props) {
-    super(props);
-    // Initialize your plugin
-  }
-
-  async onload() {
-    // Called when plugin is loaded
-  }
-
-  async onsettingsupdate() {
-    // Called when settings change
-  }
-
-  async onunload() {
-    // Called when plugin is unloaded
-  }
-}
-```
-
-## Common Tasks
-
-### Adding a New Setting
-
-1. Edit `manifest.json` in the `config.settings` array:
-
-```json
-{
-  "key": "myNewSetting",
-  "label": "My New Setting",
-  "type": "text",
-  "defaultValue": "default value",
-  "required": false
-}
-```
-
-2. Access in `main.js`:
-
-```javascript
-const value = this.getSetting('myNewSetting');
-```
-
-### Adding a New Action
-
-1. Define in `manifest.json` under `config.actions`:
-
-```json
-{
-  "type": "my_custom_action",
-  "label": "Do Something Cool",
-  "fields": [
-    {
-      "key": "message",
-      "label": "Message",
-      "type": "text",
-      "required": true
-    }
-  ]
-}
-```
-
-2. Handle in `main.js`:
-
-```javascript
-async onAction(action) {
-  if (action.type === 'my_custom_action') {
-    const message = action.fields.message;
-    // Your logic here
-  }
-}
-```
-
-### Creating Variables
-
-Variables let other Lumia features access your plugin's data:
-
-1. Define in `manifest.json` under `config.variables`:
-
-```json
-{
-  "name": "my_variable",
-  "key": "myVariable",
-  "origin": "your_plugin_id",
-  "type": "string",
-  "example": "Sample value"
-}
-```
-
-2. Update in `main.js`:
-
-```javascript
-this.setVariable('myVariable', 'new value');
-```
-
-## Testing Your Plugin
-
-1. **Install dependencies** (if using package.json):
-   ```bash
-   npm install
-   ```
-
-2. **Load in Lumia Stream**:
-   - Open Lumia Stream
-   - Go to Plugins section
-   - Load your plugin directory
-   - Enable your plugin
-
-3. **Check logs**:
-   ```javascript
-   this.log('Debug message');
-   this.error('Error message');
-   ```
-
-## Next Steps
-
-- [ ] Customize `manifest.json` with your plugin details
-- [ ] Update the plugin name and description
-- [ ] Add your custom settings
-- [ ] Implement your actions
-- [ ] Test your plugin in Lumia Stream
-- [ ] Write tests (optional)
-- [ ] Update README.md with usage instructions
-
-## API Reference
-
-### Plugin Methods
-
-- `this.getSetting(key)` - Get a setting value
-- `this.setVariable(key, value)` - Update a variable
-- `this.log(message)` - Log info message
-- `this.error(message)` - Log error message
-- `this.sendAlert(type, data)` - Trigger an alert
-
-### Lifecycle Hooks
-
-- `onload()` - Plugin initialization
-- `onunload()` - Cleanup when plugin is disabled
-- `onsettingsupdate()` - Respond to setting changes
-- `onAction(action)` - Handle triggered actions
-
-## Common Patterns
-
-### Making HTTP Requests
-
-```javascript
-const response = await fetch('https://api.example.com/data');
-const data = await response.json();
-```
-
-### Using Timers
-
-```javascript
-async onload() {
-  this.interval = setInterval(() => {
-    // Do something periodically
-  }, 5000);
-}
-
-async onunload() {
-  if (this.interval) {
-    clearInterval(this.interval);
-  }
-}
-```
-
-### Error Handling
-
-```javascript
-try {
-  // Your code
-} catch (error) {
-  this.error(`Something went wrong: ${error.message}`);
-}
-```
-
-## Troubleshooting
-
-**Plugin not loading?**
-- Check manifest.json syntax (use a JSON validator)
-- Ensure the `main` field points to the correct file
-- Check Lumia Stream logs for errors
-
-**Settings not showing?**
-- Verify the `settings` array in manifest.json
-- Ensure required fields are filled
-
-**Actions not working?**
-- Check the action type matches your handler
-- Verify field keys match what you're accessing
-
-## Resources
-
-- [Lumia Stream Documentation](https://docs.lumiastream.com)
-- [Plugin API Reference](https://docs.lumiastream.com/plugins/api)
-- [Example Plugins](https://github.com/lumiastream/plugins)
-- [Community Discord](https://discord.gg/lumiastream)
-
-## Need Help?
-
-- Join the Lumia Stream Discord community
-- Check the documentation
-- Review example plugins
-- Ask questions in the developer channel
-
----
-
-Happy coding! 🚀

package/examples/base-plugin/README.md

@@ -1,17 +0,0 @@
-# Showcase Plugin Template
-
-This template demonstrates a handful of common Lumia Stream plugin capabilities:
-
-- Logs lifecycle events and recent actions
-- Stores and updates variables that other Lumia features can consume
-- Responds to custom actions for logging, variable updates, and alert triggering
-- Triggers a sample alert effect using configurable colors and duration
-- Shows how to react to setting changes inside `onsettingsupdate`
-
-Use the CLI to copy and customise the template:
-
-```
-npx lumia-plugin create my_plugin
-```
-
-After scaffolding you can tailor the manifest, code, and README to match your idea.

package/examples/base-plugin/main.js

@@ -1,150 +0,0 @@
-const { Plugin } = require("@lumiastream/plugin");
-
-const VARIABLE_NAMES = {
-	lastMessage: "last_message",
-	lastAlertColor: "last_alert_color",
-};
-
-const DEFAULTS = {
-	welcomeMessage: "Hello from Showcase Plugin!",
-	color: "#00c2ff",
-	alertDuration: 5,
-};
-
-class ShowcasePluginTemplate extends Plugin {
-	async onload() {
-		const message = this._currentMessage();
-		await this._log("Plugin loaded");
-		await this._rememberMessage(message);
-
-		if (this.settings.autoAlert === "load") {
-			await this._triggerSampleAlert({
-				color: this.settings.favoriteColor,
-				duration: DEFAULTS.alertDuration,
-			});
-		}
-	}
-
-	async onunload() {
-		await this._log("Plugin unloaded");
-	}
-
-	async onsettingsupdate(settings, previous = {}) {
-		await this._log("Settings updated");
-
-		if (
-			settings?.welcomeMessage &&
-			settings.welcomeMessage !== previous?.welcomeMessage
-		) {
-			await this._rememberMessage(settings.welcomeMessage);
-		}
-
-		if (settings?.autoAlert === "load" && previous?.autoAlert !== "load") {
-			await this._log("Auto alert configured to fire on load");
-		}
-	}
-
-	async actions(config = {}) {
-		const actions = Array.isArray(config.actions) ? config.actions : [];
-		for (const action of actions) {
-			switch (action?.type) {
-				case "log_message":
-					await this._handleLogMessage(action.data);
-					break;
-				case "update_variable":
-					await this._handleUpdateVariable(action.data);
-					break;
-				case "trigger_alert":
-					await this._triggerSampleAlert(action.data);
-					break;
-				default:
-					await this._log(
-						`Unknown action type: ${action?.type ?? "undefined"}`
-					);
-			}
-		}
-	}
-
-	_tag() {
-		return `[${this.manifest?.id ?? "showcase_plugin"}]`;
-	}
-
-	_currentMessage() {
-		return (
-			this.settings?.welcomeMessage ||
-			`Hello from ${this.manifest?.name ?? "Showcase Plugin"}!`
-		);
-	}
-
-	async _log(message, severity = "info") {
-		const prefix = this._tag();
-		const decorated =
-			severity === "warn"
-				? `${prefix} ⚠️ ${message}`
-				: severity === "error"
-				? `${prefix} ❌ ${message}`
-				: `${prefix} ${message}`;
-
-		await this.lumia.addLog(decorated);
-	}
-
-	async _rememberMessage(value) {
-		await this.lumia.setVariable(VARIABLE_NAMES.lastMessage, value);
-	}
-
-	async _handleLogMessage(data = {}) {
-		const message = data?.message || this._currentMessage();
-		const severity = data?.severity || "info";
-
-		await this._log(message, severity);
-
-		if (typeof this.lumia.showToast === "function") {
-			await this.lumia.showToast({
-				message: `${this.manifest?.name ?? "Plugin"}: ${message}`,
-				time: 4,
-			});
-		}
-
-		if (this.settings.autoAlert === "after-log") {
-			await this._triggerSampleAlert({
-				color: this.settings.favoriteColor,
-				duration: DEFAULTS.alertDuration,
-			});
-		}
-	}
-
-	async _handleUpdateVariable(data = {}) {
-		const value = data?.value ?? new Date().toISOString();
-		await this._rememberMessage(value);
-		await this._log(`Stored variable value: ${value}`);
-	}
-
-	async _triggerSampleAlert(data = {}) {
-		const color = data?.color || this.settings?.favoriteColor || DEFAULTS.color;
-		const duration = Number(data?.duration) || DEFAULTS.alertDuration;
-
-		try {
-			const success = await this.lumia.triggerAlert({
-				alert: "sample_light",
-				extraSettings: { color, duration },
-			});
-
-			if (!success) {
-				await this._log("Sample alert reported failure", "warn");
-				return;
-			}
-
-			await this.lumia.setVariable(VARIABLE_NAMES.lastAlertColor, color);
-			await this._log(
-				`Triggered sample alert with color ${color} for ${duration}s`
-			);
-		} catch (error) {
-			await this._log(
-				`Failed to trigger sample alert: ${error.message ?? error}`,
-				"error"
-			);
-		}
-	}
-}
-
-module.exports = ShowcasePluginTemplate;

package/examples/base-plugin/manifest.json

@@ -1,149 +0,0 @@
-{
-	"id": "showcase_plugin",
-	"name": "Showcase Plugin",
-	"version": "1.0.0",
-	"author": "LumiaStream",
-	"email": "",
-	"website": "",
-	"repository": "",
-	"description": "Sample plugin that demonstrates Lumia Stream logging, variables, alerts, and settings.",
-	"license": "MIT",
-	"lumiaVersion": "^9.0.0",
-	"keywords": "sample, demo, lumia",
-	"category": "examples",
-	"icon": "",
-	"changelog": "",
-	"config": {
-		"settings": [
-			{
-				"key": "welcomeMessage",
-				"label": "Welcome Message",
-				"type": "text",
-				"defaultValue": "Hello from Showcase Plugin!",
-				"helperText": "Shown when the plugin loads and stored in the sample variable."
-			},
-			{
-				"key": "favoriteColor",
-				"label": "Favorite Color",
-				"type": "color",
-				"defaultValue": "#00c2ff",
-				"helperText": "Used when triggering the sample light alert."
-			},
-			{
-				"key": "autoAlert",
-				"label": "Trigger Sample Alert",
-				"type": "select",
-				"defaultValue": "never",
-				"options": [
-					{ "label": "Never", "value": "never" },
-					{ "label": "On Load", "value": "load" },
-					{ "label": "After Log Action", "value": "after-log" }
-				],
-				"helperText": "Automatically fire the sample alert at different times."
-			}
-		],
-		"actions": [
-			{
-				"type": "log_message",
-				"label": "Log Message",
-				"description": "Write a formatted message to the Lumia log panel and optionally trigger the sample alert.",
-				"fields": [
-					{
-						"key": "message",
-						"label": "Message",
-						"type": "text",
-						"defaultValue": "Hello from Showcase Plugin!"
-					},
-					{
-						"key": "severity",
-						"label": "Severity",
-						"type": "select",
-						"defaultValue": "info",
-						"options": [
-							{ "label": "Info", "value": "info" },
-							{ "label": "Warning", "value": "warn" },
-							{ "label": "Error", "value": "error" }
-						]
-					}
-				]
-			},
-			{
-				"type": "update_variable",
-				"label": "Update Variable",
-				"description": "Persist a value into the sample Lumia variable.",
-				"fields": [
-					{
-						"key": "value",
-						"label": "Value",
-						"type": "text",
-						"defaultValue": "Triggered from an action"
-					}
-				]
-			},
-			{
-				"type": "trigger_alert",
-				"label": "Trigger Sample Alert",
-				"description": "Fire the sample alert with optional overrides.",
-				"fields": [
-					{
-						"key": "color",
-						"label": "Color",
-						"type": "color",
-						"defaultValue": "#ff5f5f"
-					},
-					{
-						"key": "duration",
-						"label": "Duration (seconds)",
-						"type": "number",
-						"defaultValue": 5,
-						"min": 1,
-						"max": 60
-					}
-				]
-			}
-		],
-		"variables": [
-			{
-				"name": "last_message",
-				"system": false,
-				"origin": "showcase_plugin",
-				"allowedPlaces": ["automations", "overlays"],
-				"description": "Stores the most recent message handled by the plugin.",
-				"value": "",
-				"example": "Hello from Showcase Plugin!"
-			},
-			{
-				"name": "last_alert_color",
-				"system": false,
-				"origin": "showcase_plugin",
-				"allowedPlaces": ["automations", "overlays"],
-				"description": "Tracks the color used by the latest sample alert.",
-				"value": "",
-				"example": "#00c2ff"
-			}
-		],
-		"alerts": [
-			{
-				"id": "sample_light",
-				"label": "Sample Light Alert",
-				"description": "Change lights to the selected color for a few seconds.",
-				"fields": [
-					{
-						"key": "color",
-						"label": "Color",
-						"type": "color",
-						"defaultValue": "#00c2ff"
-					},
-					{
-						"key": "duration",
-						"label": "Duration (seconds)",
-						"type": "number",
-						"defaultValue": 5,
-						"min": 1,
-						"max": 60
-					}
-				]
-			}
-		]
-	}
-}

package/examples/base-plugin/package.json

@@ -1,10 +0,0 @@
-{
-	"name": "lumia-showcase-plugin-template",
-	"version": "1.0.0",
-	"private": true,
-	"description": "Internal template illustrating logging, variables, actions, and alerts for Lumia Stream plugins.",
-	"main": "main.js",
-	"dependencies": {
-		"@lumiastream/plugin": "^0.1.15"
-	}
-}