Apply the auto-fixable lint rules and the formatter, and drop the Vite build artifacts.
This commit is contained in:
@@ -3,10 +3,12 @@
|
||||
## Plugin Structure
|
||||
|
||||
Each plugin must be a directory containing at least:
|
||||
|
||||
- `index.js` - Main entry point
|
||||
- `plugin-metadata.json` - Plugin metadata
|
||||
|
||||
### Example Directory Structure
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── index.js
|
||||
@@ -38,22 +40,22 @@ Your `index.js` must export a default plugin object with an `onLoad` function:
|
||||
```javascript
|
||||
// index.js
|
||||
module.exports = {
|
||||
name: "My Plugin",
|
||||
version: "1.0.0",
|
||||
name: 'My Plugin',
|
||||
version: '1.0.0',
|
||||
dependencies: {
|
||||
"paarrot.utils": "^1.0.0" // Optional: depend on other plugins
|
||||
'paarrot.utils': '^1.0.0', // Optional: depend on other plugins
|
||||
},
|
||||
|
||||
|
||||
/**
|
||||
* Called when the plugin is loaded
|
||||
* @param {PluginContext} ctx - The plugin context
|
||||
*/
|
||||
onLoad: async (ctx) => {
|
||||
ctx.log('Plugin loaded!');
|
||||
|
||||
|
||||
// Your plugin code here
|
||||
},
|
||||
|
||||
|
||||
/**
|
||||
* Called when the plugin is unloaded (optional)
|
||||
*/
|
||||
@@ -61,13 +63,15 @@ module.exports = {
|
||||
ctx.log('Plugin unloaded!');
|
||||
// Cleanup resources here
|
||||
},
|
||||
|
||||
|
||||
/**
|
||||
* Exports for other plugins to use (optional)
|
||||
*/
|
||||
exports: {
|
||||
myFunction: () => { /* ... */ }
|
||||
}
|
||||
myFunction: () => {
|
||||
/* ... */
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
@@ -82,32 +86,32 @@ Register slash commands with argument parsing:
|
||||
```javascript
|
||||
// Simple command
|
||||
ctx.commands.register({
|
||||
name: "shrug",
|
||||
run: () => "¯\\_(ツ)_/¯"
|
||||
name: 'shrug',
|
||||
run: () => '¯\\_(ツ)_/¯',
|
||||
});
|
||||
|
||||
// Command with args
|
||||
ctx.commands.register({
|
||||
name: "echo",
|
||||
args: ["text"],
|
||||
run: ({ text }) => text
|
||||
name: 'echo',
|
||||
args: ['text'],
|
||||
run: ({ text }) => text,
|
||||
});
|
||||
|
||||
// Advanced command
|
||||
ctx.commands.register({
|
||||
name: "greet",
|
||||
description: "Greet someone",
|
||||
args: ["name", "greeting"],
|
||||
name: 'greet',
|
||||
description: 'Greet someone',
|
||||
args: ['name', 'greeting'],
|
||||
run: ({ name, greeting }) => {
|
||||
return `${greeting || 'Hello'}, ${name || 'stranger'}!`;
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
// Execute commands programmatically
|
||||
ctx.commands.execute("shrug", {});
|
||||
ctx.commands.execute('shrug', {});
|
||||
|
||||
// Unregister a command
|
||||
ctx.commands.unregister("mycommand");
|
||||
ctx.commands.unregister('mycommand');
|
||||
```
|
||||
|
||||
### 💬 Messages API
|
||||
@@ -117,26 +121,27 @@ Intercept and modify messages:
|
||||
```javascript
|
||||
// Before send interceptor
|
||||
ctx.messages.onBeforeSend((msg) => {
|
||||
if (msg.content === "brb") {
|
||||
msg.content = "be right back!";
|
||||
if (msg.content === 'brb') {
|
||||
msg.content = 'be right back!';
|
||||
}
|
||||
|
||||
|
||||
// Add prefix
|
||||
msg.content = `[Bot] ${msg.content}`;
|
||||
|
||||
|
||||
// Access metadata
|
||||
msg.metadata = { processed: true };
|
||||
});
|
||||
|
||||
// Receive interceptor
|
||||
ctx.messages.onReceive((msg) => {
|
||||
if (msg.content.includes("@bot")) {
|
||||
if (msg.content.includes('@bot')) {
|
||||
ctx.log('Bot was mentioned!');
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
MessageContext interface:
|
||||
|
||||
```typescript
|
||||
interface MessageContext {
|
||||
content: string;
|
||||
@@ -162,8 +167,8 @@ ctx.ui.registerRenderer('message', (msg, defaultRenderer) => {
|
||||
Register custom renderers:
|
||||
|
||||
```javascript
|
||||
ctx.ui.registerRenderer("message", (msg, defaultRenderer) => {
|
||||
if (msg.type === "image") {
|
||||
ctx.ui.registerRenderer('message', (msg, defaultRenderer) => {
|
||||
if (msg.type === 'image') {
|
||||
return `<img src="${msg.url}" style="border-radius:12px"/>`;
|
||||
}
|
||||
// Fall back to default
|
||||
@@ -171,7 +176,7 @@ ctx.ui.registerRenderer("message", (msg, defaultRenderer) => {
|
||||
});
|
||||
|
||||
// Unregister renderer
|
||||
ctx.ui.unregisterRenderer("message");
|
||||
ctx.ui.unregisterRenderer('message');
|
||||
```
|
||||
|
||||
### ⚙️ Settings API
|
||||
@@ -181,36 +186,36 @@ Define plugin settings with UI:
|
||||
```javascript
|
||||
ctx.settings.define({
|
||||
theme: {
|
||||
type: "select",
|
||||
label: "Theme",
|
||||
description: "Choose your theme",
|
||||
type: 'select',
|
||||
label: 'Theme',
|
||||
description: 'Choose your theme',
|
||||
options: [
|
||||
{ value: "dark", label: "Dark" },
|
||||
{ value: "light", label: "Light" }
|
||||
{ value: 'dark', label: 'Dark' },
|
||||
{ value: 'light', label: 'Light' },
|
||||
],
|
||||
default: "dark"
|
||||
default: 'dark',
|
||||
},
|
||||
spamFilter: {
|
||||
type: "boolean",
|
||||
label: "Spam Filter",
|
||||
description: "Enable spam filtering",
|
||||
default: true
|
||||
type: 'boolean',
|
||||
label: 'Spam Filter',
|
||||
description: 'Enable spam filtering',
|
||||
default: true,
|
||||
},
|
||||
prefix: {
|
||||
type: "string",
|
||||
label: "Command Prefix",
|
||||
default: "!"
|
||||
type: 'string',
|
||||
label: 'Command Prefix',
|
||||
default: '!',
|
||||
},
|
||||
maxMessages: {
|
||||
type: "number",
|
||||
label: "Max Messages",
|
||||
default: 100
|
||||
type: 'number',
|
||||
label: 'Max Messages',
|
||||
default: 100,
|
||||
},
|
||||
accentColor: {
|
||||
type: "color",
|
||||
label: "Accent Color",
|
||||
default: "#6366f1"
|
||||
}
|
||||
type: 'color',
|
||||
label: 'Accent Color',
|
||||
default: '#6366f1',
|
||||
},
|
||||
});
|
||||
|
||||
// Get/set settings
|
||||
@@ -223,22 +228,23 @@ ctx.settings.set('theme', 'light');
|
||||
Listen to raw Matrix events:
|
||||
|
||||
```javascript
|
||||
ctx.matrix.on("m.room.message", (event) => {
|
||||
ctx.matrix.on('m.room.message', (event) => {
|
||||
const content = event.getContent();
|
||||
ctx.log('Message received:', content.body);
|
||||
});
|
||||
|
||||
ctx.matrix.on("Room.timeline", (event) => {
|
||||
ctx.matrix.on('Room.timeline', (event) => {
|
||||
if (event.getType() === 'm.room.member') {
|
||||
ctx.log('Member event:', event.getSender());
|
||||
}
|
||||
});
|
||||
|
||||
// Remove listener
|
||||
ctx.matrix.off("m.room.message", handler);
|
||||
ctx.matrix.off('m.room.message', handler);
|
||||
```
|
||||
|
||||
Common events:
|
||||
|
||||
- `"m.room.message"` - Room messages
|
||||
- `"m.room.member"` - Membership changes
|
||||
- `"Room.timeline"` - Timeline events
|
||||
@@ -274,22 +280,22 @@ Show notifications to users:
|
||||
|
||||
```javascript
|
||||
// Simple notification
|
||||
ctx.notify("Plugin loaded!");
|
||||
ctx.notify('Plugin loaded!');
|
||||
|
||||
// Advanced notification
|
||||
ctx.notify({
|
||||
title: "New Message",
|
||||
body: "You have a new message from Steve",
|
||||
type: "info", // info, success, error, warning
|
||||
title: 'New Message',
|
||||
body: 'You have a new message from Steve',
|
||||
type: 'info', // info, success, error, warning
|
||||
duration: 5000,
|
||||
actions: [
|
||||
{
|
||||
label: "View",
|
||||
label: 'View',
|
||||
action: () => {
|
||||
// Handle action
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
@@ -312,12 +318,12 @@ Use other plugins:
|
||||
|
||||
```javascript
|
||||
// Require another plugin's exports
|
||||
const utils = ctx.require("paarrot.utils");
|
||||
const utils = ctx.require('paarrot.utils');
|
||||
utils.formatDate(new Date());
|
||||
|
||||
// Check if plugin exists
|
||||
try {
|
||||
const plugin = ctx.require("optional.plugin");
|
||||
const plugin = ctx.require('optional.plugin');
|
||||
} catch (err) {
|
||||
ctx.warn('Optional plugin not available');
|
||||
}
|
||||
@@ -339,7 +345,7 @@ const rooms = mx.getRooms();
|
||||
const room = mx.getRoom(roomId);
|
||||
|
||||
// Send messages
|
||||
await mx.sendTextMessage(roomId, "Hello!");
|
||||
await mx.sendTextMessage(roomId, 'Hello!');
|
||||
|
||||
// Full Matrix.js SDK available
|
||||
```
|
||||
@@ -354,9 +360,13 @@ const { useState, useEffect } = ctx.React;
|
||||
// Create custom UI components
|
||||
const MyComponent = () => {
|
||||
const [count, setCount] = useState(0);
|
||||
return ctx.React.createElement('button', {
|
||||
onClick: () => setCount(count + 1)
|
||||
}, `Count: ${count}`);
|
||||
return ctx.React.createElement(
|
||||
'button',
|
||||
{
|
||||
onClick: () => setCount(count + 1),
|
||||
},
|
||||
`Count: ${count}`,
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
@@ -366,54 +376,55 @@ See [`example-plugin/index.js`](../../../../example-plugin/index.js) for a full-
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
name: "Awesome Plugin",
|
||||
version: "1.0.0",
|
||||
|
||||
name: 'Awesome Plugin',
|
||||
version: '1.0.0',
|
||||
|
||||
onLoad: async (ctx) => {
|
||||
// Register commands
|
||||
ctx.commands.register({
|
||||
name: "shrug",
|
||||
run: () => "¯\\_(ツ)_/¯"
|
||||
name: 'shrug',
|
||||
run: () => '¯\\_(ツ)_/¯',
|
||||
});
|
||||
|
||||
|
||||
// Message interceptors
|
||||
ctx.messages.onBeforeSend((msg) => {
|
||||
if (msg.content === "brb") {
|
||||
msg.content = "be right back!";
|
||||
if (msg.content === 'brb') {
|
||||
msg.content = 'be right back!';
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
// Settings
|
||||
ctx.settings.define({
|
||||
enabled: { type: "boolean", default: true }
|
||||
enabled: { type: 'boolean', default: true },
|
||||
});
|
||||
|
||||
|
||||
// Matrix events
|
||||
ctx.matrix.on("m.room.message", (event) => {
|
||||
ctx.matrix.on('m.room.message', (event) => {
|
||||
ctx.log('Message:', event.getContent().body);
|
||||
});
|
||||
|
||||
|
||||
// Background task
|
||||
ctx.timers.setInterval(() => {
|
||||
ctx.log('Checking for updates...');
|
||||
}, 60000);
|
||||
|
||||
ctx.notify("Plugin loaded!");
|
||||
|
||||
ctx.notify('Plugin loaded!');
|
||||
},
|
||||
|
||||
|
||||
onUnload: async () => {
|
||||
// Cleanup happens automatically
|
||||
},
|
||||
|
||||
|
||||
exports: {
|
||||
version: "1.0.0"
|
||||
}
|
||||
version: '1.0.0',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Error Handling
|
||||
|
||||
Always wrap your code in try-catch blocks:
|
||||
|
||||
```javascript
|
||||
@@ -423,24 +434,28 @@ onLoad: async (ctx) => {
|
||||
} catch (error) {
|
||||
ctx.error('Failed to load:', error);
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Cleanup Resources
|
||||
|
||||
Timers and Matrix handlers are auto-cleaned, but clean up other resources:
|
||||
|
||||
```javascript
|
||||
onUnload: async () => {
|
||||
// Close connections, save state, etc.
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 3. Performance
|
||||
|
||||
Don't block the main thread:
|
||||
|
||||
```javascript
|
||||
// Bad
|
||||
for (let i = 0; i < 1000000; i++) { /* ... */ }
|
||||
for (let i = 0; i < 1000000; i++) {
|
||||
/* ... */
|
||||
}
|
||||
|
||||
// Good
|
||||
ctx.timers.setTimeout(() => {
|
||||
@@ -449,26 +464,28 @@ ctx.timers.setTimeout(() => {
|
||||
```
|
||||
|
||||
### 4. Settings Best Practices
|
||||
|
||||
Provide defaults and descriptions:
|
||||
|
||||
```javascript
|
||||
ctx.settings.define({
|
||||
maxRetries: {
|
||||
type: "number",
|
||||
label: "Max Retries",
|
||||
description: "Number of retry attempts",
|
||||
default: 3
|
||||
}
|
||||
type: 'number',
|
||||
label: 'Max Retries',
|
||||
description: 'Number of retry attempts',
|
||||
default: 3,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### 5. Logging
|
||||
|
||||
Use ctx.log() instead of console.log():
|
||||
|
||||
```javascript
|
||||
ctx.log('Info'); // Shows in plugin logs panel
|
||||
ctx.log('Info'); // Shows in plugin logs panel
|
||||
ctx.warn('Warning'); // Highlighted as warning
|
||||
ctx.error('Error'); // Highlighted as error
|
||||
ctx.error('Error'); // Highlighted as error
|
||||
```
|
||||
|
||||
## Advanced Patterns
|
||||
@@ -480,13 +497,13 @@ Require and use other plugins:
|
||||
```javascript
|
||||
onLoad: async (ctx) => {
|
||||
try {
|
||||
const utils = ctx.require("paarrot.utils");
|
||||
const utils = ctx.require('paarrot.utils');
|
||||
const formatted = utils.formatDate(new Date());
|
||||
ctx.log('Using utils:', formatted);
|
||||
} catch (err) {
|
||||
ctx.warn('Utils plugin not available, using fallback');
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Conditional Features
|
||||
@@ -496,7 +513,7 @@ Enable features based on settings:
|
||||
```javascript
|
||||
const autoReply = ctx.settings.get('autoReply');
|
||||
if (autoReply) {
|
||||
ctx.matrix.on("m.room.message", (event) => {
|
||||
ctx.matrix.on('m.room.message', (event) => {
|
||||
// Auto-reply logic
|
||||
});
|
||||
}
|
||||
@@ -520,10 +537,10 @@ const lastRun = ctx.settings.get('lastRun');
|
||||
Create multiple commands for the same function:
|
||||
|
||||
```javascript
|
||||
const shrugFn = () => "¯\\_(ツ)_/¯";
|
||||
const shrugFn = () => '¯\\_(ツ)_/¯';
|
||||
|
||||
ctx.commands.register({ name: "shrug", run: shrugFn });
|
||||
ctx.commands.register({ name: "dunno", run: shrugFn });
|
||||
ctx.commands.register({ name: 'shrug', run: shrugFn });
|
||||
ctx.commands.register({ name: 'dunno', run: shrugFn });
|
||||
```
|
||||
|
||||
### Hot Reload Support
|
||||
@@ -581,26 +598,32 @@ To list your plugin in the marketplace:
|
||||
## Debugging
|
||||
|
||||
### Browser Console
|
||||
|
||||
Check the browser console (F12) for plugin logs:
|
||||
|
||||
- `[PluginLoader]` - Plugin loading messages
|
||||
- `[Plugin yourplugin]` - Your plugin's logs
|
||||
|
||||
### Plugin Logs Panel
|
||||
|
||||
View per-plugin logs in Settings → Plugins → Logs (coming soon)
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Plugin won't load:**
|
||||
|
||||
- Check `index.js` exists
|
||||
- Verify `module.exports` is correct
|
||||
- Look for JavaScript syntax errors
|
||||
|
||||
**Command not working:**
|
||||
|
||||
- Ensure command is registered in onLoad
|
||||
- Check command name doesn't conflict
|
||||
- Verify run function returns a value
|
||||
|
||||
**Settings not saving:**
|
||||
|
||||
- Use ctx.settings.set() not localStorage
|
||||
- Check setting key matches defined schema
|
||||
|
||||
|
||||
Reference in New Issue
Block a user