@ulthon/ul-opencode-event 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ulthon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# @ulthon/ul-opencode-event
+
+OpenCode notification plugin that sends email notifications when session events occur.
+
+## Installation
+
+```bash
+npm install @ulthon/ul-opencode-event
+```
+
+Then add to your OpenCode configuration:
+
+```json
+{
+  "plugin": ["@ulthon/ul-opencode-event"]
+}
+```
+
+## Configuration
+
+### Configuration File Locations
+
+The plugin looks for configuration in these locations (in order of priority):
+
+1. **Project-level**: `.opencode/ul-opencode-event.json` or `./ul-opencode-event.json`
+2. **Global**: `~/.config/opencode/ul-opencode-event.json`
+
+Project-level configuration overrides global configuration (channels are merged by name).
+
+### Configuration Format
+
+```json
+{
+  "channels": [
+    {
+      "type": "smtp",
+      "enabled": true,
+      "name": "My Email",
+      "config": {
+        "host": "smtp.example.com",
+        "port": 465,
+        "secure": true,
+        "auth": {
+          "user": "your-email@example.com",
+          "pass": "your-app-password"
+        }
+      },
+      "recipients": ["receiver@example.com"],
+      "events": {
+        "created": true,
+        "idle": true,
+        "error": true
+      },
+      "templates": {
+        "created": {
+          "subject": "[OpenCode] Task Started - {{projectName}}",
+          "body": "Task started at {{timestamp}}"
+        }
+      }
+    }
+  ]
+}
+```
+
+See `examples/ul-opencode-event.json` for a complete example.
+
+### Channel Configuration
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Channel type: `smtp` (more coming soon) |
+| `enabled` | boolean | No | Whether this channel is active (default: true) |
+| `name` | string | No | Channel name for identification |
+| `config` | object | Yes | Channel-specific configuration |
+| `recipients` | string[] | Yes* | Email recipients (*required for smtp*) |
+| `events` | object | No | Which events to notify |
+| `templates` | object | No | Custom templates for each event |
+
+### SMTP Configuration
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `host` | string | Yes | SMTP server hostname |
+| `port` | number | Yes | SMTP port (465 for SSL, 587 for STARTTLS) |
+| `secure` | boolean | No | Use SSL (default: true for port 465) |
+| `auth.user` | string | Yes | SMTP username |
+| `auth.pass` | string | Yes | SMTP password or app password |
+
+## Template Variables
+
+Use these variables in your subject and body templates:
+
+| Variable | Description | Available Events |
+|----------|-------------|------------------|
+| `{{eventType}}` | Event type (created, idle, error) | All |
+| `{{timestamp}}` | ISO 8601 timestamp | All |
+| `{{projectName}}` | Project name | All |
+| `{{sessionId}}` | Session ID | All |
+| `{{message}}` | Completion message | idle |
+| `{{duration}}` | Task duration | idle |
+| `{{error}}` | Error message | error |
+
+## Events
+
+| Event | When it triggers |
+|-------|------------------|
+| `created` | When a new session starts |
+| `idle` | When a session completes (AI finishes responding) |
+| `error` | When a session encounters an error |
+
+## Multiple Channels
+
+You can configure multiple channels, and all enabled channels will receive notifications:
+
+```json
+{
+  "channels": [
+    {
+      "type": "smtp",
+      "enabled": true,
+      "name": "Primary Email",
+      "config": { "host": "smtp.primary.com", ... },
+      "recipients": ["primary@example.com"],
+      "events": { "created": true, "idle": true, "error": true }
+    },
+    {
+      "type": "smtp",
+      "enabled": true,
+      "name": "Secondary Email",
+      "config": { "host": "smtp.secondary.com", ... },
+      "recipients": ["secondary@example.com"],
+      "events": { "idle": true, "error": true }
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+### No notifications sent
+
+1. Check if `enabled: true` is set
+2. Check if the event type is enabled in `events`
+3. Check SMTP credentials are correct
+
+### SMTP authentication failed
+
+- For Gmail, use an App Password instead of your regular password
+- For QQ Mail, use the authorization code
+- Ensure `secure` matches your port (465 = true, 587 = false)
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+import type { NotificationConfig } from './types';
+/**
+ * Load and merge notification configuration
+ *
+ * Config locations (in order of priority):
+ * 1. Project-level: .opencode/ul-opencode-event.json or ./ul-opencode-event.json
+ * 2. Global: ~/.config/opencode/ul-opencode-event.json
+ *
+ * Merge strategy:
+ * - Channels are merged by `name` field
+ * - If names match, project channel overrides global channel
+ * - If no name match, project channels are appended to global channels
+ *
+ * Filtering:
+ * - Only returns channels where enabled is true (or undefined, which defaults to true)
+ * - Channels with enabled: false are excluded
+ *
+ * Validation:
+ * - Channel type must be 'smtp' (only supported type in phase 1)
+ * - Throws clear error for unsupported channel types
+ *
+ * @returns Merged and filtered configuration, or default config if no files exist
+ * @throws Error if any channel has an unsupported type
+ */
+export declare function loadConfig(): NotificationConfig;

package/dist/email.d.ts

@@ -0,0 +1,10 @@
+import type { Channel } from './types';
+export interface EmailSender {
+    send: (subject: string, body: string) => Promise<void>;
+}
+/**
+ * Creates an email sender for the given SMTP channel
+ * @param channel - The channel configuration (must be SMTP type)
+ * @returns EmailSender instance or null if channel is invalid/disabled
+ */
+export declare function createEmailSender(channel: Channel): EmailSender | null;

package/dist/handler.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Multi-channel event handler for notifications
+ */
+import type { NotificationConfig, EventPayload, EventType } from './types';
+export interface EventHandler {
+    handle: (eventType: EventType, payload: EventPayload) => Promise<void>;
+}
+/**
+ * Creates an event handler that dispatches notifications to all enabled channels
+ */
+export declare function createEventHandler(config: NotificationConfig): EventHandler;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Notification Plugin Entry Point
+ * Sends email notifications when session events occur
+ */
+import type { Plugin } from '@opencode-ai/plugin';
+/**
+ * Notification Plugin for OpenCode
+ * Listens for session events and sends notifications via configured channels
+ */
+export declare const NotificationPlugin: Plugin;
+export default NotificationPlugin;