@escalated-dev/escalated 0.6.0 → 0.7.1

package/src/composables/useMentions.js

@@ -0,0 +1,134 @@
+import { ref, onUnmounted } from 'vue';
+
+/**
+ * Composable that detects `@` typed in a text input/textarea,
+ * fetches agent suggestions from the API (debounced), and provides
+ * an insert function to replace the mention token.
+ *
+ * @param {Object} options
+ * @param {string} [options.searchEndpoint] - API endpoint for agent search (default: route-based)
+ * @param {number} [options.debounce=250] - Debounce delay in ms
+ * @returns {Object}
+ */
+export function useMentions(options = {}) {
+    const { debounce = 250 } = options;
+
+    const suggestions = ref([]);
+    const isActive = ref(false);
+    const query = ref('');
+    const mentionStart = ref(null); // cursor position where `@` was typed
+    const loading = ref(false);
+
+    let timer = null;
+
+    function clearTimer() {
+        if (timer !== null) {
+            window.clearTimeout(timer);
+            timer = null;
+        }
+    }
+
+    /**
+     * Call this on every input/keyup event with the textarea element
+     * and the current text value.
+     */
+    function onTextChange(textareaEl, text) {
+        if (!textareaEl) return;
+
+        const cursorPos = textareaEl.selectionStart;
+        const textBeforeCursor = text.slice(0, cursorPos);
+
+        // Find the last `@` that starts a mention (preceded by whitespace or start of string)
+        const mentionMatch = textBeforeCursor.match(/(?:^|[\s(])@([a-zA-Z0-9_ ]*)$/);
+
+        if (mentionMatch) {
+            const searchQuery = mentionMatch[1];
+            // The @ is at cursorPos minus the matched group minus 1 for the @
+            mentionStart.value = cursorPos - searchQuery.length - 1;
+            query.value = searchQuery;
+            isActive.value = true;
+            debouncedFetch(searchQuery);
+        } else {
+            close();
+        }
+    }
+
+    function debouncedFetch(searchQuery) {
+        clearTimer();
+
+        if (searchQuery.length < 1) {
+            fetchSuggestions('');
+            return;
+        }
+
+        timer = window.setTimeout(() => {
+            fetchSuggestions(searchQuery);
+        }, debounce);
+    }
+
+    async function fetchSuggestions(searchQuery) {
+        loading.value = true;
+        try {
+            const endpoint = options.searchEndpoint || '/support/admin/agents/search';
+            const url = `${endpoint}?q=${encodeURIComponent(searchQuery)}`;
+            const response = await fetch(url, {
+                headers: {
+                    Accept: 'application/json',
+                    'X-Requested-With': 'XMLHttpRequest',
+                    'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content || '',
+                },
+            });
+            if (response.ok) {
+                suggestions.value = await response.json();
+            } else {
+                suggestions.value = [];
+            }
+        } catch {
+            suggestions.value = [];
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    /**
+     * Insert the selected agent mention into the text.
+     * Returns the new text value with the mention inserted.
+     *
+     * @param {string} currentText - Current textarea value
+     * @param {Object} agent - Agent object with `name` property
+     * @returns {string} Updated text
+     */
+    function insertMention(currentText, agent) {
+        if (mentionStart.value === null) return currentText;
+
+        const before = currentText.slice(0, mentionStart.value);
+        const cursorPos = mentionStart.value + 1 + query.value.length;
+        const after = currentText.slice(cursorPos);
+
+        const mentionText = `@{${agent.name}} `;
+        const newText = before + mentionText + after;
+
+        close();
+        return newText;
+    }
+
+    function close() {
+        isActive.value = false;
+        suggestions.value = [];
+        query.value = '';
+        mentionStart.value = null;
+        clearTimer();
+    }
+
+    onUnmounted(clearTimer);
+
+    return {
+        suggestions,
+        isActive,
+        query,
+        loading,
+        onTextChange,
+        insertMention,
+        close,
+    };
+}

package/src/composables/usePluginExtensions.js

@@ -1,67 +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));
-    });
-
-    /**
-     * 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;
-    });
-
-    return {
-        pluginData,
-        menuItems,
-        dashboardWidgets,
-        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

@@ -0,0 +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 };
+}

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,
+    };
+}