Apply the auto-fixable lint rules and the formatter, and drop the Vite build artifacts.
This commit is contained in:
+231
-210
@@ -27,6 +27,7 @@ Complete reference for developing plugins for Paarrot/Cinny Desktop.
|
||||
### Plugin Location
|
||||
|
||||
Plugins are installed in:
|
||||
|
||||
- **Windows**: `%APPDATA%\paarrot\plugins\<plugin-name>\`
|
||||
- **Linux**: `~/.config/Paarrot/plugins/<plugin-name>/`
|
||||
- **macOS**: `~/Library/Application Support/Paarrot/plugins/<plugin-name>/`
|
||||
@@ -59,38 +60,38 @@ Plugins are installed in:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
name: "My Plugin",
|
||||
version: "1.0.0",
|
||||
name: 'My Plugin',
|
||||
version: '1.0.0',
|
||||
dependencies: {
|
||||
// "other-plugin": "^1.0.0"
|
||||
},
|
||||
|
||||
|
||||
/**
|
||||
* Called when plugin loads
|
||||
* @param {PluginContext} ctx - Plugin context
|
||||
*/
|
||||
onLoad: async (ctx) => {
|
||||
ctx.log('Plugin loaded!');
|
||||
|
||||
|
||||
// Initialize your plugin here
|
||||
ctx.commands.register({
|
||||
name: "hello",
|
||||
description: "Say hello",
|
||||
run: () => "Hello, world!"
|
||||
name: 'hello',
|
||||
description: 'Say hello',
|
||||
run: () => 'Hello, world!',
|
||||
});
|
||||
},
|
||||
|
||||
|
||||
/**
|
||||
* Called when plugin unloads
|
||||
*/
|
||||
onUnload: async () => {
|
||||
console.log('Plugin unloaded');
|
||||
},
|
||||
|
||||
|
||||
/**
|
||||
* API for other plugins
|
||||
*/
|
||||
exports: null
|
||||
exports: null,
|
||||
};
|
||||
```
|
||||
|
||||
@@ -106,7 +107,7 @@ interface PluginContext {
|
||||
matrixClient: MatrixClient;
|
||||
React: typeof import('react');
|
||||
lucide: typeof import('lucide-react');
|
||||
|
||||
|
||||
commands: CommandsAPI;
|
||||
messages: MessagesAPI;
|
||||
ui: UIAPI;
|
||||
@@ -129,54 +130,57 @@ Register slash commands that users can type in chat.
|
||||
|
||||
```javascript
|
||||
ctx.commands.register({
|
||||
name: "mycommand",
|
||||
description: "Does something cool",
|
||||
args: ["arg1", "arg2"], // Optional
|
||||
name: 'mycommand',
|
||||
description: 'Does something cool',
|
||||
args: ['arg1', 'arg2'], // Optional
|
||||
run: (args) => {
|
||||
// Return string to send as message
|
||||
return `Got args: ${args.arg1}, ${args.arg2}`;
|
||||
}
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
#### Examples
|
||||
|
||||
**Simple command:**
|
||||
|
||||
```javascript
|
||||
ctx.commands.register({
|
||||
name: "shrug",
|
||||
description: "Send a shrug emoji",
|
||||
run: () => "¯\\_(ツ)_/¯"
|
||||
name: 'shrug',
|
||||
description: 'Send a shrug emoji',
|
||||
run: () => '¯\\_(ツ)_/¯',
|
||||
});
|
||||
// Usage: /shrug
|
||||
```
|
||||
|
||||
**Command with arguments:**
|
||||
|
||||
```javascript
|
||||
ctx.commands.register({
|
||||
name: "greet",
|
||||
description: "Greet someone",
|
||||
args: ["name"],
|
||||
run: ({ name }) => `Hello, ${name || 'stranger'}!`
|
||||
name: 'greet',
|
||||
description: 'Greet someone',
|
||||
args: ['name'],
|
||||
run: ({ name }) => `Hello, ${name || 'stranger'}!`,
|
||||
});
|
||||
// Usage: /greet Alice
|
||||
```
|
||||
|
||||
**Advanced command:**
|
||||
|
||||
```javascript
|
||||
ctx.commands.register({
|
||||
name: "calc",
|
||||
description: "Simple calculator",
|
||||
args: ["expression"],
|
||||
name: 'calc',
|
||||
description: 'Simple calculator',
|
||||
args: ['expression'],
|
||||
run: ({ expression }) => {
|
||||
try {
|
||||
const sanitized = expression.replace(/[^0-9+\-*/().\s]/g, '');
|
||||
const result = Function(`'use strict'; return (${sanitized})`)();
|
||||
return `${expression} = ${result}`;
|
||||
} catch (err) {
|
||||
return "Invalid expression";
|
||||
return 'Invalid expression';
|
||||
}
|
||||
}
|
||||
},
|
||||
});
|
||||
// Usage: /calc 2 + 2 * 3
|
||||
```
|
||||
@@ -214,7 +218,7 @@ ctx.messages.onBeforeSend((msg) => {
|
||||
if (msg.content.includes('secret')) {
|
||||
msg.content = msg.content.replace(/secret/g, '█████');
|
||||
}
|
||||
|
||||
|
||||
// Add prefix
|
||||
msg.content = `[Bot] ${msg.content}`;
|
||||
});
|
||||
@@ -231,7 +235,7 @@ ctx.messages.onReceive((msg) => {
|
||||
ctx.notify({
|
||||
title: 'Important Message',
|
||||
body: msg.content,
|
||||
type: 'info'
|
||||
type: 'info',
|
||||
});
|
||||
}
|
||||
});
|
||||
@@ -240,15 +244,16 @@ ctx.messages.onReceive((msg) => {
|
||||
#### Real-World Examples
|
||||
|
||||
**Auto-expand abbreviations:**
|
||||
|
||||
```javascript
|
||||
ctx.messages.onBeforeSend((msg) => {
|
||||
const expansions = {
|
||||
'brb': 'be right back',
|
||||
'omw': 'on my way',
|
||||
'gtg': 'got to go',
|
||||
'afk': 'away from keyboard'
|
||||
brb: 'be right back',
|
||||
omw: 'on my way',
|
||||
gtg: 'got to go',
|
||||
afk: 'away from keyboard',
|
||||
};
|
||||
|
||||
|
||||
Object.entries(expansions).forEach(([abbr, full]) => {
|
||||
const regex = new RegExp(`\\b${abbr}\\b`, 'gi');
|
||||
msg.content = msg.content.replace(regex, full);
|
||||
@@ -257,6 +262,7 @@ ctx.messages.onBeforeSend((msg) => {
|
||||
```
|
||||
|
||||
**Add auto-shrug to questions:**
|
||||
|
||||
```javascript
|
||||
ctx.messages.onBeforeSend((msg) => {
|
||||
if (msg.content.trim().endsWith('?')) {
|
||||
@@ -266,6 +272,7 @@ ctx.messages.onBeforeSend((msg) => {
|
||||
```
|
||||
|
||||
**Track mentions:**
|
||||
|
||||
```javascript
|
||||
ctx.messages.onReceive((msg) => {
|
||||
const userId = ctx.matrixClient.getUserId();
|
||||
@@ -300,21 +307,25 @@ Register custom UI renderers for messages, images, and other content types.
|
||||
|
||||
```javascript
|
||||
// Custom message renderer
|
||||
ctx.ui.registerRenderer("message", (msg, defaultRenderer) => {
|
||||
ctx.ui.registerRenderer('message', (msg, defaultRenderer) => {
|
||||
// Custom logic
|
||||
if (msg.sender?.includes('bot')) {
|
||||
// Return custom React component
|
||||
return ctx.React.createElement('div', {
|
||||
style: { background: 'yellow' }
|
||||
}, msg.content);
|
||||
return ctx.React.createElement(
|
||||
'div',
|
||||
{
|
||||
style: { background: 'yellow' },
|
||||
},
|
||||
msg.content,
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
// Fall back to default
|
||||
return defaultRenderer?.();
|
||||
});
|
||||
|
||||
// Custom image renderer
|
||||
ctx.ui.registerRenderer("image", (data, defaultRenderer) => {
|
||||
ctx.ui.registerRenderer('image', (data, defaultRenderer) => {
|
||||
// Add custom effects, borders, etc.
|
||||
return defaultRenderer?.();
|
||||
});
|
||||
@@ -328,14 +339,11 @@ interface UIAPI {
|
||||
unregisterButton(id: string): void;
|
||||
registerRenderer(
|
||||
type: string,
|
||||
renderer: (data: any, defaultRenderer?: () => ReactNode) => ReactNode
|
||||
renderer: (data: any, defaultRenderer?: () => ReactNode) => ReactNode,
|
||||
): void;
|
||||
}
|
||||
|
||||
type CustomRenderer = (
|
||||
data: any,
|
||||
defaultRenderer?: () => ReactNode
|
||||
) => ReactNode;
|
||||
type CustomRenderer = (data: any, defaultRenderer?: () => ReactNode) => ReactNode;
|
||||
```
|
||||
|
||||
---
|
||||
@@ -354,30 +362,30 @@ ctx.ui.registerButton({
|
||||
location: 'text-composer-toolbar',
|
||||
label: 'My Tool',
|
||||
icon: '🔧',
|
||||
onClick: () => ctx.log('clicked!')
|
||||
onClick: () => ctx.log('clicked!'),
|
||||
});
|
||||
```
|
||||
|
||||
#### UI Locations — Nav List Rows
|
||||
|
||||
| Location | Where it appears |
|
||||
|---|---|
|
||||
| `channel-list` | Space channel list, below Lobby and Message Search |
|
||||
| `home-section` | Home panel, inside the Rooms category above the room list |
|
||||
| Location | Where it appears |
|
||||
| ----------------- | ----------------------------------------------------------- |
|
||||
| `channel-list` | Space channel list, below Lobby and Message Search |
|
||||
| `home-section` | Home panel, inside the Rooms category above the room list |
|
||||
| `direct-messages` | DMs panel, below "Create Chat" and above the CHATS dropdown |
|
||||
|
||||
#### UI Locations — Icon Buttons
|
||||
|
||||
| Location | Where it appears |
|
||||
|---|---|
|
||||
| `text-composer-toolbar` | Message composer toolbar (alongside emoji, sticker buttons) |
|
||||
| `composer-actions` | Left side of the composer, beside the `+` attach button |
|
||||
| `room-header` | Top room header bar, before the ⋮ menu |
|
||||
| `room-menu` | Room ⋮ dropdown menu |
|
||||
| `message-actions` | Message hover action bar |
|
||||
| `user-menu` | Right-click popup on the user avatar |
|
||||
| `search-notification-section` | Notifications page header (right side) |
|
||||
| `sidebar-actions` | Left sidebar — above Explore Servers icon, and above Search icon in the sticky bottom section |
|
||||
| Location | Where it appears |
|
||||
| ----------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `text-composer-toolbar` | Message composer toolbar (alongside emoji, sticker buttons) |
|
||||
| `composer-actions` | Left side of the composer, beside the `+` attach button |
|
||||
| `room-header` | Top room header bar, before the ⋮ menu |
|
||||
| `room-menu` | Room ⋮ dropdown menu |
|
||||
| `message-actions` | Message hover action bar |
|
||||
| `user-menu` | Right-click popup on the user avatar |
|
||||
| `search-notification-section` | Notifications page header (right side) |
|
||||
| `sidebar-actions` | Left sidebar — above Explore Servers icon, and above Search icon in the sticky bottom section |
|
||||
|
||||
#### Positioning
|
||||
|
||||
@@ -390,9 +398,9 @@ ctx.ui.registerButton({
|
||||
position: {
|
||||
after: 'emoji-picker-button',
|
||||
group: 'my-tools',
|
||||
order: 1
|
||||
order: 1,
|
||||
},
|
||||
onClick: () => ctx.log('clicked!')
|
||||
onClick: () => ctx.log('clicked!'),
|
||||
});
|
||||
```
|
||||
|
||||
@@ -407,10 +415,17 @@ ctx.ui.unregisterButton('my-button');
|
||||
|
||||
```typescript
|
||||
type UILocation =
|
||||
| 'channel-list' | 'direct-messages' | 'home-section'
|
||||
| 'text-composer-toolbar' | 'composer-actions'
|
||||
| 'room-header' | 'room-menu' | 'message-actions'
|
||||
| 'user-menu' | 'search-notification-section' | 'sidebar-actions';
|
||||
| 'channel-list'
|
||||
| 'direct-messages'
|
||||
| 'home-section'
|
||||
| 'text-composer-toolbar'
|
||||
| 'composer-actions'
|
||||
| 'room-header'
|
||||
| 'room-menu'
|
||||
| 'message-actions'
|
||||
| 'user-menu'
|
||||
| 'search-notification-section'
|
||||
| 'sidebar-actions';
|
||||
|
||||
interface UIButtonDefinition {
|
||||
id: string;
|
||||
@@ -443,47 +458,47 @@ Define settings that users can configure in the UI.
|
||||
ctx.settings.define({
|
||||
// Boolean toggle
|
||||
enableFeature: {
|
||||
type: "boolean",
|
||||
label: "Enable Feature",
|
||||
description: "Toggle this feature on/off",
|
||||
default: true
|
||||
type: 'boolean',
|
||||
label: 'Enable Feature',
|
||||
description: 'Toggle this feature on/off',
|
||||
default: true,
|
||||
},
|
||||
|
||||
|
||||
// String input
|
||||
apiKey: {
|
||||
type: "string",
|
||||
label: "API Key",
|
||||
description: "Your API key",
|
||||
default: ""
|
||||
type: 'string',
|
||||
label: 'API Key',
|
||||
description: 'Your API key',
|
||||
default: '',
|
||||
},
|
||||
|
||||
|
||||
// Number input
|
||||
maxRetries: {
|
||||
type: "number",
|
||||
label: "Max Retries",
|
||||
description: "Maximum retry attempts",
|
||||
default: 3
|
||||
type: 'number',
|
||||
label: 'Max Retries',
|
||||
description: 'Maximum retry attempts',
|
||||
default: 3,
|
||||
},
|
||||
|
||||
|
||||
// Select dropdown
|
||||
theme: {
|
||||
type: "select",
|
||||
label: "Theme",
|
||||
description: "Choose a theme",
|
||||
type: 'select',
|
||||
label: 'Theme',
|
||||
description: 'Choose a theme',
|
||||
options: [
|
||||
{ value: "dark", label: "Dark Mode" },
|
||||
{ value: "light", label: "Light Mode" }
|
||||
{ value: 'dark', label: 'Dark Mode' },
|
||||
{ value: 'light', label: 'Light Mode' },
|
||||
],
|
||||
default: "dark"
|
||||
default: 'dark',
|
||||
},
|
||||
|
||||
|
||||
// Color picker
|
||||
accentColor: {
|
||||
type: "color",
|
||||
label: "Accent Color",
|
||||
description: "Choose your accent color",
|
||||
default: "#6366f1"
|
||||
}
|
||||
type: 'color',
|
||||
label: 'Accent Color',
|
||||
description: 'Choose your accent color',
|
||||
default: '#6366f1',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
@@ -528,9 +543,9 @@ Register custom themes that appear in the theme selector dropdown. Themes use CS
|
||||
|
||||
```javascript
|
||||
ctx.themes.register({
|
||||
id: "my-theme",
|
||||
name: "My Custom Theme",
|
||||
kind: "dark", // "light" or "dark"
|
||||
id: 'my-theme',
|
||||
name: 'My Custom Theme',
|
||||
kind: 'dark', // "light" or "dark"
|
||||
css: `
|
||||
body.plugin-my-plugin-my-theme {
|
||||
background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
|
||||
@@ -543,7 +558,7 @@ ctx.themes.register({
|
||||
.plugin-my-plugin-my-theme {
|
||||
--tc-link: hsl(213, 100%, 80%);
|
||||
}
|
||||
`
|
||||
`,
|
||||
});
|
||||
```
|
||||
|
||||
@@ -563,6 +578,7 @@ Example: plugin ID `my-plugin` + theme ID `dark-blue` = `.plugin-my-plugin-dark-
|
||||
#### CSS Custom Properties
|
||||
|
||||
Available CSS variables you can override:
|
||||
|
||||
- `--tc-link` - Link color
|
||||
- `--mx-uc-1` through `--mx-uc-8` - Matrix user ID colors (for different users)
|
||||
- `--font-emoji` - Emoji font family
|
||||
@@ -571,6 +587,7 @@ Available CSS variables you can override:
|
||||
#### Styling Elements
|
||||
|
||||
Common selectors to style:
|
||||
|
||||
- `body.plugin-{pluginId}-{themeId}` - Body background
|
||||
- `.plugin-{pluginId}-{themeId} #root` - Main app container
|
||||
- `.plugin-{pluginId}-{themeId} [role="navigation"]` - Navigation sidebar
|
||||
@@ -582,11 +599,12 @@ Common selectors to style:
|
||||
#### Examples
|
||||
|
||||
**Dark Theme with Gradients:**
|
||||
|
||||
```javascript
|
||||
ctx.themes.register({
|
||||
id: "midnight",
|
||||
name: "Midnight Blue 🌙",
|
||||
kind: "dark",
|
||||
id: 'midnight',
|
||||
name: 'Midnight Blue 🌙',
|
||||
kind: 'dark',
|
||||
css: `
|
||||
body.plugin-my-plugin-midnight {
|
||||
background: linear-gradient(135deg, #0a192f 0%, #112240 50%, #1a365d 100%);
|
||||
@@ -613,16 +631,17 @@ ctx.themes.register({
|
||||
.plugin-my-plugin-midnight {
|
||||
--tc-link: hsl(213, 100%, 80%);
|
||||
}
|
||||
`
|
||||
`,
|
||||
});
|
||||
```
|
||||
|
||||
**Light Theme:**
|
||||
|
||||
```javascript
|
||||
ctx.themes.register({
|
||||
id: "sunrise",
|
||||
name: "Sunrise ☀️",
|
||||
kind: "light",
|
||||
id: 'sunrise',
|
||||
name: 'Sunrise ☀️',
|
||||
kind: 'light',
|
||||
css: `
|
||||
body.plugin-my-plugin-sunrise {
|
||||
background: linear-gradient(135deg, #fff4e6 0%, #ffe0b2 50%, #ffcc80 100%);
|
||||
@@ -645,16 +664,17 @@ ctx.themes.register({
|
||||
.plugin-my-plugin-sunrise {
|
||||
--tc-link: hsl(30, 100%, 40%);
|
||||
}
|
||||
`
|
||||
`,
|
||||
});
|
||||
```
|
||||
|
||||
**Minimal Theme:**
|
||||
|
||||
```javascript
|
||||
ctx.themes.register({
|
||||
id: "forest",
|
||||
name: "Forest Green 🌲",
|
||||
kind: "dark",
|
||||
id: 'forest',
|
||||
name: 'Forest Green 🌲',
|
||||
kind: 'dark',
|
||||
css: `
|
||||
body.plugin-my-plugin-forest {
|
||||
background: #1a2f23;
|
||||
@@ -671,14 +691,14 @@ ctx.themes.register({
|
||||
--mx-uc-7: hsl(135, 60%, 70%);
|
||||
--mx-uc-8: hsl(155, 60%, 70%);
|
||||
}
|
||||
`
|
||||
`,
|
||||
});
|
||||
```
|
||||
|
||||
#### Unregister Theme
|
||||
|
||||
```javascript
|
||||
ctx.themes.unregister("my-theme");
|
||||
ctx.themes.unregister('my-theme');
|
||||
```
|
||||
|
||||
#### API Reference
|
||||
@@ -699,6 +719,7 @@ interface PluginTheme {
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- CSS is injected once when the plugin loads (not per theme change)
|
||||
- Theme IDs are automatically prefixed with `plugin-{pluginId}-` to avoid conflicts
|
||||
- Theme class names follow the pattern: `.plugin-{pluginId}-{themeId}`
|
||||
@@ -717,19 +738,19 @@ Hook into raw Matrix events for advanced functionality.
|
||||
|
||||
```javascript
|
||||
// Room messages
|
||||
ctx.matrix.on("m.room.message", (event) => {
|
||||
ctx.matrix.on('m.room.message', (event) => {
|
||||
const content = event.getContent();
|
||||
ctx.log('Message:', content.body);
|
||||
});
|
||||
|
||||
// Membership changes
|
||||
ctx.matrix.on("m.room.member", (event) => {
|
||||
ctx.matrix.on('m.room.member', (event) => {
|
||||
const content = event.getContent();
|
||||
ctx.log('Membership:', content.membership);
|
||||
});
|
||||
|
||||
// Timeline events
|
||||
ctx.matrix.on("Room.timeline", (event) => {
|
||||
ctx.matrix.on('Room.timeline', (event) => {
|
||||
if (event.getType() === 'm.room.message') {
|
||||
const sender = event.getSender();
|
||||
ctx.log('Timeline event from:', sender);
|
||||
@@ -737,7 +758,7 @@ ctx.matrix.on("Room.timeline", (event) => {
|
||||
});
|
||||
|
||||
// Sync state
|
||||
ctx.matrix.on("sync", (state, prevState) => {
|
||||
ctx.matrix.on('sync', (state, prevState) => {
|
||||
ctx.log('Sync state:', state);
|
||||
});
|
||||
```
|
||||
@@ -749,10 +770,10 @@ const handler = (event) => {
|
||||
ctx.log('Event received');
|
||||
};
|
||||
|
||||
ctx.matrix.on("m.room.message", handler);
|
||||
ctx.matrix.on('m.room.message', handler);
|
||||
|
||||
// Later...
|
||||
ctx.matrix.off("m.room.message", handler);
|
||||
ctx.matrix.off('m.room.message', handler);
|
||||
```
|
||||
|
||||
#### API Reference
|
||||
@@ -765,6 +786,7 @@ interface MatrixEventsAPI {
|
||||
```
|
||||
|
||||
**Common Event Types:**
|
||||
|
||||
- `m.room.message` - Room messages
|
||||
- `m.room.member` - Membership changes
|
||||
- `m.room.name` - Room name changes
|
||||
@@ -784,11 +806,11 @@ Run periodic tasks or delayed actions.
|
||||
// Run every 30 seconds
|
||||
const intervalId = ctx.timers.setInterval(() => {
|
||||
ctx.log('Periodic task running');
|
||||
|
||||
|
||||
// Do something periodically
|
||||
const stats = {
|
||||
timestamp: Date.now(),
|
||||
setting: ctx.settings.get('theme')
|
||||
setting: ctx.settings.get('theme'),
|
||||
};
|
||||
ctx.log('Stats:', stats);
|
||||
}, 30000);
|
||||
@@ -805,9 +827,9 @@ const timeoutId = ctx.timers.setTimeout(() => {
|
||||
ctx.notify({
|
||||
title: 'Reminder',
|
||||
body: 'This is a delayed notification',
|
||||
type: 'info'
|
||||
type: 'info',
|
||||
});
|
||||
}, 10000); // 10 seconds
|
||||
}, 10000); // 10 seconds
|
||||
|
||||
// Clear timeout
|
||||
ctx.timers.clearTimeout(timeoutId);
|
||||
@@ -844,8 +866,8 @@ ctx.notify('Hello, world!');
|
||||
ctx.notify({
|
||||
title: 'Plugin Alert',
|
||||
body: 'Something important happened!',
|
||||
type: 'info', // 'info' | 'success' | 'error' | 'warning'
|
||||
duration: 5000 // milliseconds (optional)
|
||||
type: 'info', // 'info' | 'success' | 'error' | 'warning'
|
||||
duration: 5000, // milliseconds (optional)
|
||||
});
|
||||
```
|
||||
|
||||
@@ -856,30 +878,28 @@ ctx.notify({
|
||||
ctx.notify({
|
||||
title: 'Success',
|
||||
body: 'Operation completed successfully!',
|
||||
type: 'success'
|
||||
type: 'success',
|
||||
});
|
||||
|
||||
// Error notification
|
||||
ctx.notify({
|
||||
title: 'Error',
|
||||
body: 'Something went wrong',
|
||||
type: 'error'
|
||||
type: 'error',
|
||||
});
|
||||
|
||||
// Warning
|
||||
ctx.notify({
|
||||
title: 'Warning',
|
||||
body: 'This action cannot be undone',
|
||||
type: 'warning'
|
||||
type: 'warning',
|
||||
});
|
||||
```
|
||||
|
||||
#### API Reference
|
||||
|
||||
```typescript
|
||||
type NotificationFunction = (
|
||||
options: NotificationOptions | string
|
||||
) => void;
|
||||
type NotificationFunction = (options: NotificationOptions | string) => void;
|
||||
|
||||
interface NotificationOptions {
|
||||
title: string;
|
||||
@@ -916,13 +936,14 @@ ctx.error('Error details:', errorObject);
|
||||
type LogFunction = (...args: any[]) => void;
|
||||
|
||||
interface PluginContext {
|
||||
log: LogFunction; // Info level
|
||||
warn: LogFunction; // Warning level
|
||||
error: LogFunction; // Error level
|
||||
log: LogFunction; // Info level
|
||||
warn: LogFunction; // Warning level
|
||||
error: LogFunction; // Error level
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** All logs are visible in:
|
||||
|
||||
- Browser console (F12)
|
||||
- Plugin logs panel (Settings → Plugins → Logs) - coming soon
|
||||
|
||||
@@ -937,21 +958,21 @@ Export functions and data for other plugins to use.
|
||||
```javascript
|
||||
module.exports = {
|
||||
// ... onLoad, onUnload ...
|
||||
|
||||
|
||||
exports: {
|
||||
version: "1.0.0",
|
||||
|
||||
version: '1.0.0',
|
||||
|
||||
utils: {
|
||||
greet: (name) => `Hello, ${name}!`,
|
||||
|
||||
|
||||
processText: (text) => text.toUpperCase(),
|
||||
|
||||
|
||||
getStats: () => ({
|
||||
version: "1.0.0",
|
||||
features: ['commands', 'settings']
|
||||
})
|
||||
}
|
||||
}
|
||||
version: '1.0.0',
|
||||
features: ['commands', 'settings'],
|
||||
}),
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
@@ -963,11 +984,11 @@ const otherPlugin = ctx.require('other-plugin-id');
|
||||
|
||||
if (otherPlugin) {
|
||||
const greeting = otherPlugin.utils.greet('World');
|
||||
ctx.log(greeting); // "Hello, World!"
|
||||
|
||||
ctx.log(greeting); // "Hello, World!"
|
||||
|
||||
const processed = otherPlugin.utils.processText('hello');
|
||||
ctx.log(processed); // "HELLO"
|
||||
|
||||
ctx.log(processed); // "HELLO"
|
||||
|
||||
const stats = otherPlugin.utils.getStats();
|
||||
ctx.log('Stats:', stats);
|
||||
}
|
||||
@@ -1018,7 +1039,7 @@ ctx.log('Sync state:', syncState);
|
||||
// Send custom event
|
||||
await ctx.matrixClient.sendEvent(roomId, 'm.room.message', {
|
||||
msgtype: 'm.text',
|
||||
body: 'Hello from plugin!'
|
||||
body: 'Hello from plugin!',
|
||||
});
|
||||
```
|
||||
|
||||
@@ -1026,7 +1047,7 @@ await ctx.matrixClient.sendEvent(roomId, 'm.room.message', {
|
||||
|
||||
```typescript
|
||||
interface PluginContext {
|
||||
matrixClient: MatrixClient; // Full Matrix.js SDK client
|
||||
matrixClient: MatrixClient; // Full Matrix.js SDK client
|
||||
}
|
||||
```
|
||||
|
||||
@@ -1043,122 +1064,122 @@ Here's a complete plugin that demonstrates all features:
|
||||
* Example Plugin - All Features
|
||||
*/
|
||||
module.exports = {
|
||||
name: "Example Plugin",
|
||||
version: "1.0.0",
|
||||
name: 'Example Plugin',
|
||||
version: '1.0.0',
|
||||
dependencies: {},
|
||||
|
||||
|
||||
onLoad: async (ctx) => {
|
||||
ctx.log('🚀 Plugin loading...');
|
||||
|
||||
|
||||
// === COMMANDS ===
|
||||
ctx.commands.register({
|
||||
name: "hello",
|
||||
description: "Say hello",
|
||||
run: () => "Hello, world!"
|
||||
name: 'hello',
|
||||
description: 'Say hello',
|
||||
run: () => 'Hello, world!',
|
||||
});
|
||||
|
||||
|
||||
ctx.commands.register({
|
||||
name: "greet",
|
||||
description: "Greet someone",
|
||||
args: ["name"],
|
||||
run: ({ name }) => `Hello, ${name}!`
|
||||
name: 'greet',
|
||||
description: 'Greet someone',
|
||||
args: ['name'],
|
||||
run: ({ name }) => `Hello, ${name}!`,
|
||||
});
|
||||
|
||||
|
||||
// === INTERCEPTORS ===
|
||||
ctx.messages.onBeforeSend((msg) => {
|
||||
// Auto-expand abbreviations
|
||||
msg.content = msg.content.replace(/\bbrb\b/gi, 'be right back');
|
||||
|
||||
|
||||
// Add emoji if enabled
|
||||
if (ctx.settings.get('addEmoji')) {
|
||||
msg.content += ' ✨';
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
ctx.messages.onReceive((msg) => {
|
||||
// Track keywords
|
||||
const keywords = ctx.settings.get('keywords') || '';
|
||||
keywords.split(',').forEach(keyword => {
|
||||
keywords.split(',').forEach((keyword) => {
|
||||
if (msg.content.includes(keyword.trim())) {
|
||||
ctx.notify(`Keyword detected: ${keyword}`);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
// === SETTINGS ===
|
||||
ctx.settings.define({
|
||||
addEmoji: {
|
||||
type: "boolean",
|
||||
label: "Add Emoji",
|
||||
description: "Add sparkles to messages",
|
||||
default: false
|
||||
type: 'boolean',
|
||||
label: 'Add Emoji',
|
||||
description: 'Add sparkles to messages',
|
||||
default: false,
|
||||
},
|
||||
keywords: {
|
||||
type: "string",
|
||||
label: "Track Keywords",
|
||||
description: "Comma-separated keywords to track",
|
||||
default: "important,urgent"
|
||||
type: 'string',
|
||||
label: 'Track Keywords',
|
||||
description: 'Comma-separated keywords to track',
|
||||
default: 'important,urgent',
|
||||
},
|
||||
theme: {
|
||||
type: "select",
|
||||
label: "Theme",
|
||||
type: 'select',
|
||||
label: 'Theme',
|
||||
options: [
|
||||
{ value: "light", label: "Light" },
|
||||
{ value: "dark", label: "Dark" }
|
||||
{ value: 'light', label: 'Light' },
|
||||
{ value: 'dark', label: 'Dark' },
|
||||
],
|
||||
default: "dark"
|
||||
}
|
||||
default: 'dark',
|
||||
},
|
||||
});
|
||||
|
||||
|
||||
// === THEMES ===
|
||||
ctx.themes.register({
|
||||
id: "example-theme",
|
||||
name: "Example Theme",
|
||||
kind: "dark",
|
||||
id: 'example-theme',
|
||||
name: 'Example Theme',
|
||||
kind: 'dark',
|
||||
colors: {
|
||||
background: "#1a1a2e",
|
||||
surface: "#16213e",
|
||||
primary: "#0f3460",
|
||||
secondary: "#533483",
|
||||
onBackground: "#ffffff",
|
||||
onSurface: "#e0e0e0"
|
||||
}
|
||||
background: '#1a1a2e',
|
||||
surface: '#16213e',
|
||||
primary: '#0f3460',
|
||||
secondary: '#533483',
|
||||
onBackground: '#ffffff',
|
||||
onSurface: '#e0e0e0',
|
||||
},
|
||||
});
|
||||
|
||||
|
||||
// === MATRIX EVENTS ===
|
||||
ctx.matrix.on("m.room.message", (event) => {
|
||||
ctx.matrix.on('m.room.message', (event) => {
|
||||
const content = event.getContent();
|
||||
if (content.body?.includes('example')) {
|
||||
ctx.log('Keyword found in message');
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
// === BACKGROUND TASKS ===
|
||||
ctx.timers.setInterval(() => {
|
||||
ctx.log('Periodic check');
|
||||
}, 60000); // Every minute
|
||||
|
||||
}, 60000); // Every minute
|
||||
|
||||
// === NOTIFICATIONS ===
|
||||
ctx.notify({
|
||||
title: 'Example Plugin',
|
||||
body: 'Plugin loaded successfully!',
|
||||
type: 'success'
|
||||
type: 'success',
|
||||
});
|
||||
|
||||
|
||||
// === EXPORTS ===
|
||||
this.exports = {
|
||||
version: "1.0.0",
|
||||
greet: (name) => `Hello, ${name}!`
|
||||
version: '1.0.0',
|
||||
greet: (name) => `Hello, ${name}!`,
|
||||
};
|
||||
|
||||
|
||||
ctx.log('✅ Plugin loaded');
|
||||
},
|
||||
|
||||
|
||||
onUnload: async () => {
|
||||
console.log('Plugin unloaded');
|
||||
},
|
||||
|
||||
exports: null
|
||||
|
||||
exports: null,
|
||||
};
|
||||
```
|
||||
|
||||
@@ -1179,10 +1200,10 @@ onLoad: async (ctx) => {
|
||||
ctx.notify({
|
||||
title: 'Plugin Error',
|
||||
body: error.message,
|
||||
type: 'error'
|
||||
type: 'error',
|
||||
});
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
@@ -1194,9 +1215,9 @@ onUnload: async () => {
|
||||
// Timers are auto-cleared
|
||||
// Event handlers are auto-removed
|
||||
// Settings are persisted automatically
|
||||
|
||||
|
||||
console.log('Plugin unloaded');
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Settings Validation
|
||||
@@ -1205,7 +1226,7 @@ Validate settings before use:
|
||||
|
||||
```javascript
|
||||
const maxRetries = ctx.settings.get('maxRetries') || 3;
|
||||
const keywords = (ctx.settings.get('keywords') || '').split(',').filter(k => k.trim());
|
||||
const keywords = (ctx.settings.get('keywords') || '').split(',').filter((k) => k.trim());
|
||||
```
|
||||
|
||||
### Logging
|
||||
@@ -1213,9 +1234,9 @@ const keywords = (ctx.settings.get('keywords') || '').split(',').filter(k => k.t
|
||||
Use appropriate log levels:
|
||||
|
||||
```javascript
|
||||
ctx.log('Info message'); // Normal operation
|
||||
ctx.warn('Warning message'); // Potential issues
|
||||
ctx.error('Error message'); // Actual errors
|
||||
ctx.log('Info message'); // Normal operation
|
||||
ctx.warn('Warning message'); // Potential issues
|
||||
ctx.error('Error message'); // Actual errors
|
||||
```
|
||||
|
||||
### Performance
|
||||
|
||||
Reference in New Issue
Block a user