@escalated-dev/escalated 0.7.0 → 0.8.0

package/src/composables/usePluginExtensions.js

@@ -1,159 +1,159 @@
-import { computed } from 'vue';
-import { usePage } from '@inertiajs/vue3';
-
-/**
- * Composable for reading plugin extensions from Inertia shared props.
- *
- * The Laravel backend (escalated-laravel) shares plugin UI extensions via
- * `$page.props.escalated.plugins`, which contains:
- * - menuItems: Array of navigation items injected by plugins
- * - dashboardWidgets: Array of widget definitions for the agent dashboard
- * - pageComponents: Object mapping slot names to arrays of component definitions
- *
- * @returns {Object} Plugin extension data and helper functions
- */
-export function usePluginExtensions() {
-    const page = usePage();
-
-    const pluginData = computed(() => page.props?.escalated?.plugins || {});
-
-    /**
-     * Menu items injected by plugins, sorted by position.
-     * Each item: { label, route, icon, position, permission, badge, submenu }
-     */
-    const menuItems = computed(() => {
-        const items = pluginData.value.menuItems || [];
-        return [...items].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Dashboard widgets injected by plugins, sorted by position.
-     * Each widget: { id, title, component, plugin, data, position, width }
-     */
-    const dashboardWidgets = computed(() => {
-        const widgets = pluginData.value.dashboardWidgets || [];
-        return [...widgets].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Ticket actions injected by plugins (e.g., "Escalate to Jira", "Send Approval").
-     * Each action: { id, label, icon, handler, position, permission, context }
-     * context: 'agent' | 'admin' | 'both'
-     */
-    const ticketActions = computed(() => {
-        const actions = pluginData.value.ticketActions || [];
-        return [...actions].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Sidebar panels injected by plugins for the ticket detail context panel.
-     * Each panel: { id, title, component, plugin, position, collapsed, icon }
-     */
-    const sidebarPanels = computed(() => {
-        const panels = pluginData.value.sidebarPanels || [];
-        return [...panels].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Custom ticket fields injected by plugins for ticket creation/edit forms.
-     * Each field: { id, label, type, name, options, required, position, plugin }
-     * type: 'text' | 'textarea' | 'select' | 'checkbox' | 'date' | 'number'
-     */
-    const ticketFields = computed(() => {
-        const fields = pluginData.value.ticketFields || [];
-        return [...fields].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Reply composer actions injected by plugins (e.g., "AI Suggest", "Insert KB Article").
-     * Each action: { id, label, icon, handler, component, plugin, position }
-     */
-    const composerActions = computed(() => {
-        const actions = pluginData.value.composerActions || [];
-        return [...actions].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Report widgets injected by plugins for the admin reports page.
-     * Each widget: { id, title, component, plugin, data, position, width }
-     */
-    const reportWidgets = computed(() => {
-        const widgets = pluginData.value.reportWidgets || [];
-        return [...widgets].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Settings panels injected by plugins for the admin settings page.
-     * Each panel: { id, title, component, plugin, position, icon }
-     */
-    const settingsPanels = computed(() => {
-        const panels = pluginData.value.settingsPanels || [];
-        return [...panels].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Notification channels registered by plugins (e.g., Slack, SMS, WhatsApp).
-     * Each channel: { id, label, icon, plugin, configComponent }
-     */
-    const notificationChannels = computed(() => {
-        const channels = pluginData.value.notificationChannels || [];
-        return [...channels].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Custom ticket list columns injected by plugins.
-     * Each column: { id, label, key, component, plugin, position, width }
-     */
-    const ticketListColumns = computed(() => {
-        const columns = pluginData.value.ticketListColumns || [];
-        return [...columns].sort((a, b) => (a.position || 100) - (b.position || 100));
-    });
-
-    /**
-     * Get plugin components for a specific page slot, sorted by position.
-     *
-     * @param {string} pageName - The page name (e.g. 'dashboard', 'ticket.show')
-     * @param {string} slotName - The slot name (e.g. 'header', 'sidebar', 'footer')
-     * @returns {Array} Sorted array of component definitions for the given slot
-     */
-    function getPageComponents(pageName, slotName) {
-        const key = `${pageName}.${slotName}`;
-        const components = pluginData.value.pageComponents || {};
-        return [...(components[key] || [])].sort((a, b) => (a.position || 100) - (b.position || 100));
-    }
-
-    /**
-     * Check whether any plugins have registered extensions.
-     */
-    const hasPlugins = computed(() => {
-        return (
-            menuItems.value.length > 0 ||
-            dashboardWidgets.value.length > 0 ||
-            Object.keys(pluginData.value.pageComponents || {}).length > 0 ||
-            ticketActions.value.length > 0 ||
-            sidebarPanels.value.length > 0 ||
-            ticketFields.value.length > 0 ||
-            composerActions.value.length > 0 ||
-            reportWidgets.value.length > 0 ||
-            settingsPanels.value.length > 0 ||
-            notificationChannels.value.length > 0 ||
-            ticketListColumns.value.length > 0
-        );
-    });
-
-    return {
-        pluginData,
-        menuItems,
-        dashboardWidgets,
-        ticketActions,
-        sidebarPanels,
-        ticketFields,
-        composerActions,
-        reportWidgets,
-        settingsPanels,
-        notificationChannels,
-        ticketListColumns,
-        getPageComponents,
-        hasPlugins,
-    };
-}
+import { computed } from 'vue';
+import { usePage } from '@inertiajs/vue3';
+
+/**
+ * Composable for reading plugin extensions from Inertia shared props.
+ *
+ * The Laravel backend (escalated-laravel) shares plugin UI extensions via
+ * `$page.props.escalated.plugins`, which contains:
+ * - menuItems: Array of navigation items injected by plugins
+ * - dashboardWidgets: Array of widget definitions for the agent dashboard
+ * - pageComponents: Object mapping slot names to arrays of component definitions
+ *
+ * @returns {Object} Plugin extension data and helper functions
+ */
+export function usePluginExtensions() {
+    const page = usePage();
+
+    const pluginData = computed(() => page.props?.escalated?.plugins || {});
+
+    /**
+     * Menu items injected by plugins, sorted by position.
+     * Each item: { label, route, icon, position, permission, badge, submenu }
+     */
+    const menuItems = computed(() => {
+        const items = pluginData.value.menuItems || [];
+        return [...items].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Dashboard widgets injected by plugins, sorted by position.
+     * Each widget: { id, title, component, plugin, data, position, width }
+     */
+    const dashboardWidgets = computed(() => {
+        const widgets = pluginData.value.dashboardWidgets || [];
+        return [...widgets].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Ticket actions injected by plugins (e.g., "Escalate to Jira", "Send Approval").
+     * Each action: { id, label, icon, handler, position, permission, context }
+     * context: 'agent' | 'admin' | 'both'
+     */
+    const ticketActions = computed(() => {
+        const actions = pluginData.value.ticketActions || [];
+        return [...actions].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Sidebar panels injected by plugins for the ticket detail context panel.
+     * Each panel: { id, title, component, plugin, position, collapsed, icon }
+     */
+    const sidebarPanels = computed(() => {
+        const panels = pluginData.value.sidebarPanels || [];
+        return [...panels].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Custom ticket fields injected by plugins for ticket creation/edit forms.
+     * Each field: { id, label, type, name, options, required, position, plugin }
+     * type: 'text' | 'textarea' | 'select' | 'checkbox' | 'date' | 'number'
+     */
+    const ticketFields = computed(() => {
+        const fields = pluginData.value.ticketFields || [];
+        return [...fields].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Reply composer actions injected by plugins (e.g., "AI Suggest", "Insert KB Article").
+     * Each action: { id, label, icon, handler, component, plugin, position }
+     */
+    const composerActions = computed(() => {
+        const actions = pluginData.value.composerActions || [];
+        return [...actions].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Report widgets injected by plugins for the admin reports page.
+     * Each widget: { id, title, component, plugin, data, position, width }
+     */
+    const reportWidgets = computed(() => {
+        const widgets = pluginData.value.reportWidgets || [];
+        return [...widgets].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Settings panels injected by plugins for the admin settings page.
+     * Each panel: { id, title, component, plugin, position, icon }
+     */
+    const settingsPanels = computed(() => {
+        const panels = pluginData.value.settingsPanels || [];
+        return [...panels].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Notification channels registered by plugins (e.g., Slack, SMS, WhatsApp).
+     * Each channel: { id, label, icon, plugin, configComponent }
+     */
+    const notificationChannels = computed(() => {
+        const channels = pluginData.value.notificationChannels || [];
+        return [...channels].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Custom ticket list columns injected by plugins.
+     * Each column: { id, label, key, component, plugin, position, width }
+     */
+    const ticketListColumns = computed(() => {
+        const columns = pluginData.value.ticketListColumns || [];
+        return [...columns].sort((a, b) => (a.position || 100) - (b.position || 100));
+    });
+
+    /**
+     * Get plugin components for a specific page slot, sorted by position.
+     *
+     * @param {string} pageName - The page name (e.g. 'dashboard', 'ticket.show')
+     * @param {string} slotName - The slot name (e.g. 'header', 'sidebar', 'footer')
+     * @returns {Array} Sorted array of component definitions for the given slot
+     */
+    function getPageComponents(pageName, slotName) {
+        const key = `${pageName}.${slotName}`;
+        const components = pluginData.value.pageComponents || {};
+        return [...(components[key] || [])].sort((a, b) => (a.position || 100) - (b.position || 100));
+    }
+
+    /**
+     * Check whether any plugins have registered extensions.
+     */
+    const hasPlugins = computed(() => {
+        return (
+            menuItems.value.length > 0 ||
+            dashboardWidgets.value.length > 0 ||
+            Object.keys(pluginData.value.pageComponents || {}).length > 0 ||
+            ticketActions.value.length > 0 ||
+            sidebarPanels.value.length > 0 ||
+            ticketFields.value.length > 0 ||
+            composerActions.value.length > 0 ||
+            reportWidgets.value.length > 0 ||
+            settingsPanels.value.length > 0 ||
+            notificationChannels.value.length > 0 ||
+            ticketListColumns.value.length > 0
+        );
+    });
+
+    return {
+        pluginData,
+        menuItems,
+        dashboardWidgets,
+        ticketActions,
+        sidebarPanels,
+        ticketFields,
+        composerActions,
+        reportWidgets,
+        settingsPanels,
+        notificationChannels,
+        ticketListColumns,
+        getPageComponents,
+        hasPlugins,
+    };
+}

package/src/composables/usePluginHooks.js

@@ -1,65 +1,65 @@
-import { getCurrentInstance } from 'vue';
-
-/**
- * Composable for dispatching and consuming plugin hooks.
- *
- * Hooks allow plugins to react to events (e.g., ticket.created, ticket.replied)
- * and to filter/modify data before it's processed (e.g., reply.beforeSubmit).
- *
- * Action hooks: fire-and-forget, all handlers run
- * Filter hooks: chain handlers, each can modify the value
- *
- * @returns {Object} Hook dispatch functions
- */
-export function usePluginHooks() {
-    const instance = getCurrentInstance();
-    const hookRegistry = instance?.appContext?.config?.globalProperties?.$escalatedHooks || {};
-
-    /**
-     * Dispatch an action hook. All registered handlers are called.
-     * @param {string} event - Hook name (e.g., 'ticket.created')
-     * @param  {...any} args - Arguments passed to handlers
-     */
-    async function dispatch(event, ...args) {
-        const handlers = hookRegistry[event] || [];
-        for (const { handler } of handlers) {
-            try {
-                await handler(...args);
-            } catch (err) {
-                console.warn(`[Escalated] Plugin hook "${event}" error:`, err);
-            }
-        }
-    }
-
-    /**
-     * Dispatch a filter hook. Each handler receives the value and can return a modified version.
-     * @param {string} event - Hook name (e.g., 'reply.beforeSubmit')
-     * @param {*} value - The value to filter
-     * @param  {...any} args - Additional arguments passed to handlers
-     * @returns {*} The filtered value
-     */
-    async function filter(event, value, ...args) {
-        const handlers = hookRegistry[event] || [];
-        let result = value;
-        for (const { handler } of handlers) {
-            try {
-                const modified = await handler(result, ...args);
-                if (modified !== undefined) result = modified;
-            } catch (err) {
-                console.warn(`[Escalated] Plugin filter "${event}" error:`, err);
-            }
-        }
-        return result;
-    }
-
-    /**
-     * Check if any handlers are registered for a given hook.
-     * @param {string} event - Hook name
-     * @returns {boolean}
-     */
-    function hasHook(event) {
-        return (hookRegistry[event] || []).length > 0;
-    }
-
-    return { dispatch, filter, hasHook };
-}
+import { getCurrentInstance } from 'vue';
+
+/**
+ * Composable for dispatching and consuming plugin hooks.
+ *
+ * Hooks allow plugins to react to events (e.g., ticket.created, ticket.replied)
+ * and to filter/modify data before it's processed (e.g., reply.beforeSubmit).
+ *
+ * Action hooks: fire-and-forget, all handlers run
+ * Filter hooks: chain handlers, each can modify the value
+ *
+ * @returns {Object} Hook dispatch functions
+ */
+export function usePluginHooks() {
+    const instance = getCurrentInstance();
+    const hookRegistry = instance?.appContext?.config?.globalProperties?.$escalatedHooks || {};
+
+    /**
+     * Dispatch an action hook. All registered handlers are called.
+     * @param {string} event - Hook name (e.g., 'ticket.created')
+     * @param  {...any} args - Arguments passed to handlers
+     */
+    async function dispatch(event, ...args) {
+        const handlers = hookRegistry[event] || [];
+        for (const { handler } of handlers) {
+            try {
+                await handler(...args);
+            } catch (err) {
+                console.warn(`[Escalated] Plugin hook "${event}" error:`, err);
+            }
+        }
+    }
+
+    /**
+     * Dispatch a filter hook. Each handler receives the value and can return a modified version.
+     * @param {string} event - Hook name (e.g., 'reply.beforeSubmit')
+     * @param {*} value - The value to filter
+     * @param  {...any} args - Additional arguments passed to handlers
+     * @returns {*} The filtered value
+     */
+    async function filter(event, value, ...args) {
+        const handlers = hookRegistry[event] || [];
+        let result = value;
+        for (const { handler } of handlers) {
+            try {
+                const modified = await handler(result, ...args);
+                if (modified !== undefined) result = modified;
+            } catch (err) {
+                console.warn(`[Escalated] Plugin filter "${event}" error:`, err);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Check if any handlers are registered for a given hook.
+     * @param {string} event - Hook name
+     * @returns {boolean}
+     */
+    function hasHook(event) {
+        return (hookRegistry[event] || []).length > 0;
+    }
+
+    return { dispatch, filter, hasHook };
+}

package/src/composables/useRealtime.js

@@ -0,0 +1,182 @@
+import { ref, onUnmounted, readonly } from 'vue';
+
+/**
+ * Composable for real-time WebSocket event listening via Laravel Echo.
+ *
+ * If `window.Echo` is available (provided by the host app), this composable
+ * subscribes to private channels and listens for broadcast events. When Echo
+ * is not present, it silently falls back - the caller can check `echoAvailable`
+ * and implement polling as needed.
+ *
+ * Usage:
+ *   const { echoAvailable, subscribeToTicket, subscribeToTickets, subscribeToAgent } = useRealtime();
+ *
+ * All subscriptions are automatically cleaned up on component unmount.
+ */
+export function useRealtime() {
+    const echoAvailable = ref(typeof window !== 'undefined' && !!window.Echo);
+    const subscriptions = [];
+
+    /**
+     * Subscribe to a private channel and listen for an event.
+     * Returns an unsubscribe function.
+     */
+    function listen(channelName, eventName, callback) {
+        if (!echoAvailable.value) return () => {};
+
+        const channel = window.Echo.private(channelName);
+        channel.listen(eventName, callback);
+
+        const unsub = () => {
+            channel.stopListening(eventName, callback);
+            window.Echo.leave(channelName);
+        };
+        subscriptions.push(unsub);
+        return unsub;
+    }
+
+    /**
+     * Subscribe to a specific ticket's channel for real-time updates.
+     *
+     * @param {number|string} ticketId - The ticket ID
+     * @param {Object} handlers - Event handler callbacks
+     * @param {Function} [handlers.onReplyCreated] - Called when a new reply is added
+     * @param {Function} [handlers.onTicketUpdated] - Called when ticket fields are updated
+     * @param {Function} [handlers.onStatusChanged] - Called when ticket status changes
+     * @param {Function} [handlers.onTicketAssigned] - Called when ticket is assigned
+     * @param {Function} [handlers.onTicketEscalated] - Called when ticket is escalated
+     * @returns {Function} Unsubscribe function
+     */
+    function subscribeToTicket(ticketId, handlers = {}) {
+        if (!echoAvailable.value) return () => {};
+
+        const channelName = `escalated.tickets.${ticketId}`;
+        const channel = window.Echo.private(channelName);
+        const listeners = [];
+
+        if (handlers.onReplyCreated) {
+            channel.listen('.reply.created', handlers.onReplyCreated);
+            listeners.push(['.reply.created', handlers.onReplyCreated]);
+        }
+        if (handlers.onTicketUpdated) {
+            channel.listen('.ticket.updated', handlers.onTicketUpdated);
+            listeners.push(['.ticket.updated', handlers.onTicketUpdated]);
+        }
+        if (handlers.onStatusChanged) {
+            channel.listen('.ticket.status_changed', handlers.onStatusChanged);
+            listeners.push(['.ticket.status_changed', handlers.onStatusChanged]);
+        }
+        if (handlers.onTicketAssigned) {
+            channel.listen('.ticket.assigned', handlers.onTicketAssigned);
+            listeners.push(['.ticket.assigned', handlers.onTicketAssigned]);
+        }
+        if (handlers.onTicketEscalated) {
+            channel.listen('.ticket.escalated', handlers.onTicketEscalated);
+            listeners.push(['.ticket.escalated', handlers.onTicketEscalated]);
+        }
+
+        const unsub = () => {
+            listeners.forEach(([event, cb]) => channel.stopListening(event, cb));
+            window.Echo.leave(channelName);
+        };
+        subscriptions.push(unsub);
+        return unsub;
+    }
+
+    /**
+     * Subscribe to the global tickets channel for new ticket notifications.
+     *
+     * @param {Object} handlers - Event handler callbacks
+     * @param {Function} [handlers.onTicketCreated] - Called when a new ticket is created
+     * @returns {Function} Unsubscribe function
+     */
+    function subscribeToTickets(handlers = {}) {
+        if (!echoAvailable.value) return () => {};
+
+        const channelName = 'escalated.tickets';
+        const channel = window.Echo.private(channelName);
+        const listeners = [];
+
+        if (handlers.onTicketCreated) {
+            channel.listen('.ticket.created', handlers.onTicketCreated);
+            listeners.push(['.ticket.created', handlers.onTicketCreated]);
+        }
+
+        const unsub = () => {
+            listeners.forEach(([event, cb]) => channel.stopListening(event, cb));
+            window.Echo.leave(channelName);
+        };
+        subscriptions.push(unsub);
+        return unsub;
+    }
+
+    /**
+     * Subscribe to an agent's personal channel for assignment notifications.
+     *
+     * @param {number|string} agentId - The agent's user ID
+     * @param {Object} handlers - Event handler callbacks
+     * @param {Function} [handlers.onTicketAssigned] - Called when a ticket is assigned to this agent
+     * @returns {Function} Unsubscribe function
+     */
+    function subscribeToAgent(agentId, handlers = {}) {
+        if (!echoAvailable.value) return () => {};
+
+        const channelName = `escalated.agents.${agentId}`;
+        const channel = window.Echo.private(channelName);
+        const listeners = [];
+
+        if (handlers.onTicketAssigned) {
+            channel.listen('.ticket.assigned', handlers.onTicketAssigned);
+            listeners.push(['.ticket.assigned', handlers.onTicketAssigned]);
+        }
+
+        const unsub = () => {
+            listeners.forEach(([event, cb]) => channel.stopListening(event, cb));
+            window.Echo.leave(channelName);
+        };
+        subscriptions.push(unsub);
+        return unsub;
+    }
+
+    /**
+     * Get a presence channel for a ticket (if Echo supports it).
+     * Returns the channel instance or null.
+     */
+    function joinTicketPresence(ticketId, callbacks = {}) {
+        if (!echoAvailable.value) return null;
+
+        const channelName = `escalated.tickets.${ticketId}`;
+        const channel = window.Echo.join(channelName);
+
+        if (callbacks.here) channel.here(callbacks.here);
+        if (callbacks.joining) channel.joining(callbacks.joining);
+        if (callbacks.leaving) channel.leaving(callbacks.leaving);
+
+        const unsub = () => {
+            window.Echo.leave(`presence-${channelName}`);
+        };
+        subscriptions.push(unsub);
+        return { channel, unsubscribe: unsub };
+    }
+
+    // Cleanup all subscriptions on component unmount
+    onUnmounted(() => {
+        subscriptions.forEach((unsub) => {
+            try {
+                unsub();
+            } catch {
+                /* ignore */
+            }
+        });
+        subscriptions.length = 0;
+    });
+
+    return {
+        echoAvailable: readonly(echoAvailable),
+        listen,
+        subscribeToTicket,
+        subscribeToTickets,
+        subscribeToAgent,
+        joinTicketPresence,
+    };
+}