@escalated-dev/escalated 0.7.0 → 0.7.1

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

package/src/defineEscalatedPlugin.js

@@ -1,76 +1,76 @@
-/**
- * Helper for plugin authors to define an Escalated plugin.
- *
- * Returns a Vue plugin object that registers components globally when installed.
- *
- * Usage:
- *
- *   import { defineEscalatedPlugin } from '@escalated-dev/escalated'
- *   import SalesWidget from './Components/SalesWidget.vue'
- *
- *   export default defineEscalatedPlugin({
- *       name: 'my-plugin',
- *       components: {
- *           SalesWidget,
- *       },
- *       hooks: {
- *           'ticket.created': (ticket) => { ... },
- *           'ticket.replied': (ticket, reply) => { ... },
- *           'ticket.statusChanged': (ticket, oldStatus, newStatus) => { ... },
- *           'reply.beforeSubmit': (content) => { return modifiedContent; },
- *       },
- *       setup(app, ctx) {
- *           // ctx contains: { provide }
- *       },
- *   })
- *
- * @param {Object} options
- * @param {string} options.name - Plugin identifier
- * @param {Object} [options.components] - Map of component name to component definition
- * @param {Object} [options.hooks] - Map of hook event name to handler function
- * @param {Function} [options.setup] - Optional setup callback receiving the Vue app instance and context
- * @returns {Object} A Vue plugin object with an install() method
- */
-export function defineEscalatedPlugin(options = {}) {
-    return {
-        // Metadata for plugin introspection
-        __escalated: true,
-        name: options.name || 'unknown',
-        hooks: options.hooks || {},
-
-        install(app) {
-            // Register all provided components globally
-            if (options.components) {
-                Object.entries(options.components).forEach(([name, component]) => {
-                    app.component(name, component);
-                });
-            }
-
-            // Register plugin hooks on a global event bus
-            if (options.hooks) {
-                const hookRegistry =
-                    app.config.globalProperties.$escalatedHooks || (app.config.globalProperties.$escalatedHooks = {});
-
-                Object.entries(options.hooks).forEach(([event, handler]) => {
-                    if (!hookRegistry[event]) hookRegistry[event] = [];
-                    hookRegistry[event].push({
-                        plugin: options.name,
-                        handler,
-                    });
-                });
-            }
-
-            // Run optional setup callback with context
-            if (typeof options.setup === 'function') {
-                options.setup(app, {
-                    provide: app.provide.bind(app),
-                });
-            }
-
-            // Provide the plugin name for debugging
-            if (options.name) {
-                app.provide(`escalated-plugin:${options.name}`, true);
-            }
-        },
-    };
-}
+/**
+ * Helper for plugin authors to define an Escalated plugin.
+ *
+ * Returns a Vue plugin object that registers components globally when installed.
+ *
+ * Usage:
+ *
+ *   import { defineEscalatedPlugin } from '@escalated-dev/escalated'
+ *   import SalesWidget from './Components/SalesWidget.vue'
+ *
+ *   export default defineEscalatedPlugin({
+ *       name: 'my-plugin',
+ *       components: {
+ *           SalesWidget,
+ *       },
+ *       hooks: {
+ *           'ticket.created': (ticket) => { ... },
+ *           'ticket.replied': (ticket, reply) => { ... },
+ *           'ticket.statusChanged': (ticket, oldStatus, newStatus) => { ... },
+ *           'reply.beforeSubmit': (content) => { return modifiedContent; },
+ *       },
+ *       setup(app, ctx) {
+ *           // ctx contains: { provide }
+ *       },
+ *   })
+ *
+ * @param {Object} options
+ * @param {string} options.name - Plugin identifier
+ * @param {Object} [options.components] - Map of component name to component definition
+ * @param {Object} [options.hooks] - Map of hook event name to handler function
+ * @param {Function} [options.setup] - Optional setup callback receiving the Vue app instance and context
+ * @returns {Object} A Vue plugin object with an install() method
+ */
+export function defineEscalatedPlugin(options = {}) {
+    return {
+        // Metadata for plugin introspection
+        __escalated: true,
+        name: options.name || 'unknown',
+        hooks: options.hooks || {},
+
+        install(app) {
+            // Register all provided components globally
+            if (options.components) {
+                Object.entries(options.components).forEach(([name, component]) => {
+                    app.component(name, component);
+                });
+            }
+
+            // Register plugin hooks on a global event bus
+            if (options.hooks) {
+                const hookRegistry =
+                    app.config.globalProperties.$escalatedHooks || (app.config.globalProperties.$escalatedHooks = {});
+
+                Object.entries(options.hooks).forEach(([event, handler]) => {
+                    if (!hookRegistry[event]) hookRegistry[event] = [];
+                    hookRegistry[event].push({
+                        plugin: options.name,
+                        handler,
+                    });
+                });
+            }
+
+            // Run optional setup callback with context
+            if (typeof options.setup === 'function') {
+                options.setup(app, {
+                    provide: app.provide.bind(app),
+                });
+            }
+
+            // Provide the plugin name for debugging
+            if (options.name) {
+                app.provide(`escalated-plugin:${options.name}`, true);
+            }
+        },
+    };
+}

package/src/index.js

@@ -1,72 +1,84 @@
-// Plugin
-export { EscalatedPlugin } from './plugin';
-
-// Components
-export { default as ActivityTimeline } from './components/ActivityTimeline.vue';
-export { default as AgentLoadIndicator } from './components/AgentLoadIndicator.vue';
-export { default as AgentPerformanceCard } from './components/AgentPerformanceCard.vue';
-export { default as ArticleEditor } from './components/ArticleEditor.vue';
-export { default as AssigneeSelect } from './components/AssigneeSelect.vue';
-export { default as AttachmentList } from './components/AttachmentList.vue';
-export { default as AuditLogEntry } from './components/AuditLogEntry.vue';
-export { default as BulkActionBar } from './components/BulkActionBar.vue';
-export { default as CategoryTree } from './components/CategoryTree.vue';
-export { default as ChartWidget } from './components/ChartWidget.vue';
-export { default as CollisionWarning } from './components/CollisionWarning.vue';
-export { default as ConditionalFieldRules } from './components/ConditionalFieldRules.vue';
-export { default as ContextPanel } from './components/ContextPanel.vue';
-export { default as ContextPanelSection } from './components/ContextPanelSection.vue';
-export { default as CustomFieldRenderer } from './components/CustomFieldRenderer.vue';
-export { default as EscalatedLayout } from './components/EscalatedLayout.vue';
-export { default as FileDropzone } from './components/FileDropzone.vue';
-export { default as FollowButton } from './components/FollowButton.vue';
-export { default as KeyboardShortcutHelp } from './components/KeyboardShortcutHelp.vue';
-export { default as KnowledgePanel } from './components/KnowledgePanel.vue';
-export { default as KpiCard } from './components/KpiCard.vue';
-export { default as MacroDropdown } from './components/MacroDropdown.vue';
-export { default as PermissionMatrix } from './components/PermissionMatrix.vue';
-export { default as PinnedNotes } from './components/PinnedNotes.vue';
-export { default as PluginSlot } from './components/PluginSlot.vue';
-export { default as PresenceIndicator } from './components/PresenceIndicator.vue';
-export { default as PriorityBadge } from './components/PriorityBadge.vue';
-export { default as QuickFilters } from './components/QuickFilters.vue';
-export { default as ReplyComposer } from './components/ReplyComposer.vue';
-export { default as ReplyThread } from './components/ReplyThread.vue';
-export { default as SatisfactionRating } from './components/SatisfactionRating.vue';
-export { default as ScheduleEditor } from './components/ScheduleEditor.vue';
-export { default as SideConversation } from './components/SideConversation.vue';
-export { default as SideConversationList } from './components/SideConversationList.vue';
-export { default as SkillTagManager } from './components/SkillTagManager.vue';
-export { default as SlaComplianceChart } from './components/SlaComplianceChart.vue';
-export { default as SlaTimer } from './components/SlaTimer.vue';
-export { default as StatsCard } from './components/StatsCard.vue';
-export { default as StatusBadge } from './components/StatusBadge.vue';
-export { default as TagSelect } from './components/TagSelect.vue';
-export { default as TicketFilters } from './components/TicketFilters.vue';
-export { default as TicketLinkPanel } from './components/TicketLinkPanel.vue';
-export { default as TicketList } from './components/TicketList.vue';
-export { default as TicketMergeDialog } from './components/TicketMergeDialog.vue';
-export { default as TicketSidebar } from './components/TicketSidebar.vue';
-export { default as TicketTypeSelector } from './components/TicketTypeSelector.vue';
-export { default as TotpInput } from './components/TotpInput.vue';
-export { default as TwoFactorSetup } from './components/TwoFactorSetup.vue';
-
-// Composables
-export { useDebouncedSearch } from './composables/useDebouncedSearch';
-export { useKeyboardShortcuts } from './composables/useKeyboardShortcuts';
-export { usePluginExtensions } from './composables/usePluginExtensions';
-export { usePluginHooks } from './composables/usePluginHooks';
-
-// Utilities
-export { TICKET_STATUSES, TICKET_PRIORITIES, TICKET_TYPES, TICKET_TYPE_COLORS } from './utils/constants';
-export { timeAgo, slaClass } from './utils/formatting';
-
-// Plugin authoring helper
-export { defineEscalatedPlugin } from './defineEscalatedPlugin';
-
-// Import pages
-export { default as AdminImportIndex } from './pages/Admin/Import/Index.vue';
-export { default as AdminImportConnect } from './pages/Admin/Import/Connect.vue';
-export { default as AdminImportMapping } from './pages/Admin/Import/Mapping.vue';
-export { default as AdminImportReview } from './pages/Admin/Import/Review.vue';
-export { default as AdminImportProgress } from './pages/Admin/Import/Progress.vue';
+// Plugin
+export { EscalatedPlugin } from './plugin';
+
+// Components
+export { default as ActiveChatsPanel } from './components/ActiveChatsPanel.vue';
+export { default as ActivityTimeline } from './components/ActivityTimeline.vue';
+export { default as AgentLoadIndicator } from './components/AgentLoadIndicator.vue';
+export { default as AgentPerformanceCard } from './components/AgentPerformanceCard.vue';
+export { default as ArticleEditor } from './components/ArticleEditor.vue';
+export { default as AssigneeSelect } from './components/AssigneeSelect.vue';
+export { default as AttachmentList } from './components/AttachmentList.vue';
+export { default as AuditLogEntry } from './components/AuditLogEntry.vue';
+export { default as BulkActionBar } from './components/BulkActionBar.vue';
+export { default as CategoryTree } from './components/CategoryTree.vue';
+export { default as ChatActionBar } from './components/ChatActionBar.vue';
+export { default as ChatBubble } from './components/ChatBubble.vue';
+export { default as ChatComposer } from './components/ChatComposer.vue';
+export { default as ChatQueue } from './components/ChatQueue.vue';
+export { default as ChatThread } from './components/ChatThread.vue';
+export { default as ChartWidget } from './components/ChartWidget.vue';
+export { default as CollisionWarning } from './components/CollisionWarning.vue';
+export { default as ConditionalFieldRules } from './components/ConditionalFieldRules.vue';
+export { default as ContextPanel } from './components/ContextPanel.vue';
+export { default as ContextPanelSection } from './components/ContextPanelSection.vue';
+export { default as CustomFieldRenderer } from './components/CustomFieldRenderer.vue';
+export { default as EscalatedLayout } from './components/EscalatedLayout.vue';
+export { default as FileDropzone } from './components/FileDropzone.vue';
+export { default as FollowButton } from './components/FollowButton.vue';
+export { default as KeyboardShortcutHelp } from './components/KeyboardShortcutHelp.vue';
+export { default as KnowledgePanel } from './components/KnowledgePanel.vue';
+export { default as KpiCard } from './components/KpiCard.vue';
+export { default as MacroDropdown } from './components/MacroDropdown.vue';
+export { default as MentionDropdown } from './components/MentionDropdown.vue';
+export { default as PermissionMatrix } from './components/PermissionMatrix.vue';
+export { default as PinnedNotes } from './components/PinnedNotes.vue';
+export { default as PluginSlot } from './components/PluginSlot.vue';
+export { default as PresenceIndicator } from './components/PresenceIndicator.vue';
+export { default as PriorityBadge } from './components/PriorityBadge.vue';
+export { default as QuickFilters } from './components/QuickFilters.vue';
+export { default as ReplyComposer } from './components/ReplyComposer.vue';
+export { default as ReplyThread } from './components/ReplyThread.vue';
+export { default as SavedViewSidebar } from './components/SavedViewSidebar.vue';
+export { default as SaveViewDialog } from './components/SaveViewDialog.vue';
+export { default as SatisfactionRating } from './components/SatisfactionRating.vue';
+export { default as ScheduleEditor } from './components/ScheduleEditor.vue';
+export { default as SideConversation } from './components/SideConversation.vue';
+export { default as SideConversationList } from './components/SideConversationList.vue';
+export { default as SkillTagManager } from './components/SkillTagManager.vue';
+export { default as SlaComplianceChart } from './components/SlaComplianceChart.vue';
+export { default as SlaTimer } from './components/SlaTimer.vue';
+export { default as StatsCard } from './components/StatsCard.vue';
+export { default as StatusBadge } from './components/StatusBadge.vue';
+export { default as TagSelect } from './components/TagSelect.vue';
+export { default as TicketFilters } from './components/TicketFilters.vue';
+export { default as TicketLinkPanel } from './components/TicketLinkPanel.vue';
+export { default as TicketList } from './components/TicketList.vue';
+export { default as TicketMergeDialog } from './components/TicketMergeDialog.vue';
+export { default as TicketSidebar } from './components/TicketSidebar.vue';
+export { default as TicketTypeSelector } from './components/TicketTypeSelector.vue';
+export { default as TotpInput } from './components/TotpInput.vue';
+export { default as TwoFactorSetup } from './components/TwoFactorSetup.vue';
+
+// Composables
+export { useDebouncedSearch } from './composables/useDebouncedSearch';
+export { useKeyboardShortcuts } from './composables/useKeyboardShortcuts';
+export { useMentions } from './composables/useMentions';
+export { usePluginExtensions } from './composables/usePluginExtensions';
+export { usePluginHooks } from './composables/usePluginHooks';
+export { useChat } from './composables/useChat';
+export { useRealtime } from './composables/useRealtime';
+
+// Utilities
+export { TICKET_STATUSES, TICKET_PRIORITIES, TICKET_TYPES, TICKET_TYPE_COLORS } from './utils/constants';
+export { timeAgo, slaClass } from './utils/formatting';
+
+// Plugin authoring helper
+export { defineEscalatedPlugin } from './defineEscalatedPlugin';
+
+// Import pages
+export { default as AdminImportIndex } from './pages/Admin/Import/Index.vue';
+export { default as AdminImportConnect } from './pages/Admin/Import/Connect.vue';
+export { default as AdminImportMapping } from './pages/Admin/Import/Mapping.vue';
+export { default as AdminImportReview } from './pages/Admin/Import/Review.vue';
+export { default as AdminImportProgress } from './pages/Admin/Import/Progress.vue';