Apply the auto-fixable lint rules and the formatter, and drop the Vite build artifacts.
Checks / checks (push) Successful in 2m11s
Trigger cinny-mobile / dispatch (push) Successful in 1s

This commit is contained in:
2026-11-01 04:23:53 +11:00
parent 3cd159a63e
commit a6ad8651b3
605 changed files with 11480 additions and 9125 deletions
@@ -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