@escalated-dev/escalated 0.11.9 → 0.12.0

package/README.md

@@ -359,6 +359,42 @@ npm install @escalated-dev/plugin-jira
 
 ## For Package Maintainers
 
+Verified guest access is enabled by backend capabilities. `Escalated/Guest/Create`
+accepts optional `verification_url` and `lookup_url` props. With these URLs, the
+form requests an email code before posting a ticket; a separate form verifies
+email to find existing tickets by tracking/ticket reference and renew private
+links. `Guest/Show` displays `ticket.guest_access_expires_at` when supplied.
+
+The built-in widget enables the same flow only when `/config` returns
+`guest_verification_required: true`. The backend must provide POST `/verification`
+with email and purpose (`ticket`, `chat`, `lookup`), returning `verification_id`;
+creation accepts `verification_id` and the eight-digit `verification_code`.
+POST `/lookup` returns `{ data: [{ reference, subject, guest_access_token,
+expires_at }] }`; subsequent widget status reads send the token as a Bearer
+header. Chat creation returns an opaque `id` and polling uses
+`/chat/{id}/messages`. Proofs and private results are cleared on destination or
+identity changes. Tokens remain in component memory. CSRF headers are sent only
+to the page's own origin.
+
+Backends that omit these capabilities retain their existing form contract. Hosts
+must ship these forms before requiring verification in their backend. This does
+not implement verification in the other backend packages, release the separate
+web-widget plugin, or configure cross-origin CORS/CSRF policy.
+
+Backends with account isolation can share `escalated.broadcasting.channel_prefix`
+through Inertia, for example `escalated.tenants.<opaque-account-namespace>`.
+Ticket, agent, chat and presence subscriptions use this prefix and rejoin when it
+changes. Omitting it preserves the existing `escalated` channels. Standalone
+`PresenceIndicator` consumers can pass its `channelPrefix` prop; `useRealtime`
+and `useChat` accept `channelPrefix` as a string, ref or getter. Raw
+`useRealtime().listen(channel, event, callback)` still treats the channel literally.
+
+The backend must authorize the current account and each private/presence join.
+Channel names alone are not authorization. Ticket presence should expose only
+agent identity/display names, with requester access limited to private ticket
+updates. Deploy a frontend version containing this support before enabling a
+backend's account-scoped channels.
+
 If you're building a new backend integration, this package is available on npm:
 
 ```bash
@@ -378,6 +414,21 @@ import CustomerIndex from '@escalated-dev/escalated/pages/Customer/Index.vue'
 
 Peer dependencies: `vue` ^3.3.0, `@inertiajs/vue3` ^1.0.0 || ^2.0.0
 
+## Backend settings capabilities
+
+The `Escalated/Admin/Settings` page accepts optional `supported_settings` and
+`update_url` props. Pass an array of editable setting names to show and submit only
+those fields, and a URL accepting a flat POST payload. An empty array exposes no
+editable settings. Omitting these props preserves the full settings form and its
+Laravel named route. Backends must validate their own setting allowlist; hiding a
+control is not authorization.
+
+For example, a backend implementing only knowledge-base and branding preferences
+can expose `knowledge_base_enabled`, `knowledge_base_public`,
+`knowledge_base_feedback_enabled`, and `show_powered_by`. Supply typed values in
+the `settings` prop. Changing the settings/account props clears stale form values
+and pending requests, including previously entered credentials.
+
 ## Ecosystem
 
 This is the shared frontend for the Escalated support ticket system. Host framework packages and client SDKs available across the ecosystem:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escalated-dev/escalated",
-    "version": "0.11.9",
+    "version": "0.12.0",
     "description": "Vue 3 + Inertia.js UI components for Escalated — the embeddable support ticket system",
     "author": "Escalated Dev <hello@escalated.dev>",
     "license": "MIT",
@@ -59,6 +59,11 @@
             "prettier --write"
         ]
     },
+    "overrides": {
+        "concurrently": {
+            "shell-quote": "^1.12.0"
+        }
+    },
     "devDependencies": {
         "@eslint/js": "^10.0.1",
         "@inertiajs/vue3": "^3.7.0",

package/pages.json

@@ -1,6 +1,6 @@
 {
     "$comment": "Generated by scripts/generate-page-manifest.js from src/pages. Every name here resolves to a component; a name a backend renders that is not here is a blank screen. `props` is what each component reads -- a backend sending something else renders the screen with no content in it.",
-    "version": "0.11.9",
+    "version": "0.12.0",
     "pages": [
         "Escalated/Admin/ApiTokens/Index",
         "Escalated/Admin/AuditLog/Index",
@@ -564,7 +564,9 @@
         "Escalated/Admin/Settings": {
             "props": [
                 "departments",
-                "settings"
+                "settings",
+                "supported_settings",
+                "update_url"
             ],
             "required": []
         },
@@ -837,7 +839,9 @@
         "Escalated/Guest/Create": {
             "props": [
                 "departments",
-                "priorities"
+                "lookup_url",
+                "priorities",
+                "verification_url"
             ],
             "required": []
         },

package/src/components/ActiveChatsPanel.vue

@@ -95,7 +95,10 @@ function chatInitials(chat) {
 // that use '/escalated/widget' instead of '/support/widget'.
 const page = usePage();
 const routePrefix = page.props.escalated?.prefix || 'support';
-const { subscribeToChatQueue } = useChat({ widgetPath: `/${routePrefix}/widget` });
+const { subscribeToChatQueue } = useChat({
+    channelPrefix: () => page.props.escalated?.broadcasting?.channel_prefix,
+    widgetPath: `/${routePrefix}/widget`,
+});
 
 onMounted(() => {
     subscribeToChatQueue({

package/src/components/ChatQueue.vue

@@ -73,7 +73,10 @@ async function acceptChat(session) {
 // other framework ('/support/widget').
 const page = usePage();
 const routePrefix = page.props.escalated?.prefix || 'support';
-const { subscribeToChatQueue } = useChat({ widgetPath: `/${routePrefix}/widget` });
+const { subscribeToChatQueue } = useChat({
+    channelPrefix: () => page.props.escalated?.broadcasting?.channel_prefix,
+    widgetPath: `/${routePrefix}/widget`,
+});
 
 onMounted(() => {
     subscribeToChatQueue({

package/src/components/GuestEmailCode.vue

@@ -0,0 +1,58 @@
+<script setup>
+defineProps({ verification: { type: Object, required: true } });
+defineEmits(['code']);
+</script>
+
+<template>
+    <div class="guest-email-code space-y-2" aria-live="polite">
+        <p v-if="verification.state.message" class="text-sm">{{ verification.state.message }}</p>
+        <p v-if="verification.state.error" class="text-sm text-red-600" role="alert">{{ verification.state.error }}</p>
+        <label v-if="verification.state.id" class="block text-sm">
+            Email verification code
+            <input
+                :value="verification.state.code"
+                type="text"
+                inputmode="numeric"
+                autocomplete="one-time-code"
+                maxlength="8"
+                class="mt-1 block w-full rounded-lg border border-gray-300 p-2 text-gray-900"
+                @input="$emit('code', $event.target.value)"
+            />
+        </label>
+        <button
+            v-if="verification.state.id"
+            type="button"
+            class="text-sm underline"
+            :disabled="verification.state.pending"
+            @click="verification.send()"
+        >
+            Send a new code
+        </button>
+    </div>
+</template>
+
+<style scoped>
+.guest-email-code {
+    margin: 12px 0;
+    font-size: 14px;
+}
+.guest-email-code label,
+.guest-email-code input {
+    display: block;
+}
+.guest-email-code input {
+    box-sizing: border-box;
+    width: 100%;
+    margin-top: 6px;
+    padding: 8px;
+    border: 1px solid #d1d5db;
+    border-radius: 8px;
+    color: #111827;
+    background: #fff;
+}
+.guest-email-code button {
+    margin-top: 8px;
+    cursor: pointer;
+    text-decoration: underline;
+}
+</style>

package/src/components/PresenceIndicator.vue

@@ -4,6 +4,7 @@ import { ref, computed, inject, onUnmounted, watch } from 'vue';
 const props = defineProps({
     ticketReference: { type: String, required: true },
     ticketId: { type: [Number, String], default: null },
+    channelPrefix: { type: String, default: 'escalated' },
     routePrefix: { type: String, required: true },
     pollInterval: { type: Number, default: 30000 },
     showLabel: { type: Boolean, default: false },
@@ -23,11 +24,18 @@ let presenceChannel = null;
 // Track the exact channel name we joined so we leave the RIGHT channel when the
 // ticket changes — props.ticketId would already hold the new id by then.
 let joinedChannelName = null;
+let generation = 0;
+let pendingRequest = null;
 
 async function fetchPresence() {
+    const currentGeneration = generation;
+    pendingRequest?.abort();
+    const controller = new window.AbortController();
+    pendingRequest = controller;
     try {
         const response = await fetch(route(`${props.routePrefix}.tickets.presence`, props.ticketReference), {
             method: 'POST',
+            signal: controller.signal,
             headers: {
                 Accept: 'application/json',
                 'Content-Type': 'application/json',
@@ -37,7 +45,9 @@ async function fetchPresence() {
         });
         if (response.ok) {
             const data = await response.json();
-            viewers.value = data.viewers || data || [];
+            if (currentGeneration === generation && !controller.signal.aborted) {
+                viewers.value = data.viewers || data || [];
+            }
         }
     } catch {
         // silently ignore network errors
@@ -52,19 +62,23 @@ function initPresenceChannel() {
     if (!echoAvailable || !props.ticketId) return false;
 
     try {
-        joinedChannelName = `escalated.tickets.${props.ticketId}`;
+        const currentGeneration = generation;
+        joinedChannelName = `${props.channelPrefix}.tickets.${props.ticketId}`;
         presenceChannel = window.Echo.join(joinedChannelName);
 
         presenceChannel
             .here((users) => {
+                if (currentGeneration !== generation) return;
                 viewers.value = users;
             })
             .joining((user) => {
+                if (currentGeneration !== generation) return;
                 if (!viewers.value.find((v) => v.id === user.id)) {
                     viewers.value = [...viewers.value, user];
                 }
             })
             .leaving((user) => {
+                if (currentGeneration !== generation) return;
                 viewers.value = viewers.value.filter((v) => v.id !== user.id);
             });
 
@@ -104,13 +118,17 @@ function getColor(index) {
 }
 
 function teardown() {
+    generation++;
+    pendingRequest?.abort();
+    pendingRequest = null;
     if (intervalId) {
         clearInterval(intervalId);
         intervalId = null;
     }
     if (presenceChannel) {
         try {
-            window.Echo.leave(joinedChannelName);
+            if (window.Echo.leaveChannel) window.Echo.leaveChannel(`presence-${joinedChannelName}`);
+            else window.Echo.leave(`presence-${joinedChannelName}`);
         } catch {
             // ignore
         }
@@ -134,7 +152,10 @@ function start() {
 }
 
 // (Re)initialise whenever the ticket identity changes; `immediate` covers mount.
-watch(() => [props.ticketId, props.ticketReference], start, { immediate: true });
+watch(() => [props.ticketId, props.ticketReference, props.routePrefix, props.channelPrefix], start, {
+    immediate: true,
+    flush: 'sync',
+});
 
 onUnmounted(teardown);
 </script>

package/src/components/QuickFilters.vue

@@ -51,17 +51,20 @@ function selectTab(tab) {
                 activeTab === tab.key
                     ? escDark
                         ? 'text-cyan-400 focus-visible:ring-cyan-500/40'
-                        : 'text-blue-600 focus-visible:ring-blue-500/40'
+                        : 'text-[var(--esc-panel-accent)] focus-visible:ring-[var(--esc-panel-accent)]'
                     : escDark
                       ? 'text-neutral-500 hover:text-neutral-300 focus-visible:ring-cyan-500/40'
-                      : 'text-gray-500 hover:text-gray-700 focus-visible:ring-blue-500/40',
+                      : 'text-gray-500 hover:text-gray-700 focus-visible:ring-[var(--esc-panel-accent)]',
             ]"
             @click="selectTab(tab)"
         >
             {{ tab.label }}
             <span
                 v-if="activeTab === tab.key"
-                :class="['absolute bottom-0 left-0 right-0 h-0.5 rounded-t', escDark ? 'bg-cyan-400' : 'bg-blue-600']"
+                :class="[
+                    'absolute bottom-0 left-0 right-0 h-0.5 rounded-t',
+                    escDark ? 'bg-cyan-400' : 'bg-[var(--esc-panel-accent)]',
+                ]"
             ></span>
         </button>
     </div>

package/src/components/TicketList.vue

@@ -439,7 +439,7 @@ const colCount = computed(() => {
                             type="checkbox"
                             :checked="allSelected"
                             aria-label="Select all tickets"
-                            class="h-4 w-4 rounded border-gray-300 text-indigo-600 focus:ring-indigo-500"
+                            class="h-4 w-4 rounded border-gray-300 text-[var(--esc-panel-accent)] focus:ring-[var(--esc-panel-accent)]"
                             @change="toggleAll"
                         />
                     </th>
@@ -490,7 +490,7 @@ const colCount = computed(() => {
                                     <input
                                         type="checkbox"
                                         :checked="isColumnActive(col.key)"
-                                        class="h-3.5 w-3.5 rounded border-gray-300 text-indigo-600 focus:ring-indigo-500"
+                                        class="h-3.5 w-3.5 rounded border-gray-300 text-[var(--esc-panel-accent)] focus:ring-[var(--esc-panel-accent)]"
                                         @change="toggleColumn(col.key)"
                                     />
                                     {{ col.label }}
@@ -504,14 +504,17 @@ const colCount = computed(() => {
                 <tr
                     v-for="(ticket, index) in tickets.data"
                     :key="ticket.id"
-                    :class="['group', navigable && focusedIndex === index ? 'bg-indigo-50' : 'hover:bg-gray-50']"
+                    :class="[
+                        'group',
+                        navigable && focusedIndex === index ? 'bg-[var(--esc-panel-active)]' : 'hover:bg-gray-50',
+                    ]"
                 >
                     <td v-if="selectable" class="w-10 px-3 py-3">
                         <input
                             type="checkbox"
                             :checked="selectedIds.includes(ticket.id)"
                             aria-label="Select ticket"
-                            class="h-4 w-4 rounded border-gray-300 text-indigo-600 focus:ring-indigo-500"
+                            class="h-4 w-4 rounded border-gray-300 text-[var(--esc-panel-accent)] focus:ring-[var(--esc-panel-accent)]"
                             @change="toggleOne(ticket.id)"
                         />
                     </td>
@@ -527,7 +530,7 @@ const colCount = computed(() => {
                             ></span>
                             <Link
                                 :href="route(`${routePrefix}.show`, ticket.reference)"
-                                class="text-indigo-600 hover:text-indigo-900"
+                                class="text-[var(--esc-panel-accent)] hover:text-[var(--esc-panel-accent-hover)]"
                             >
                                 {{ ticket.reference }}
                             </Link>

package/src/composables/useChat.js

@@ -20,7 +20,7 @@ export function useChat(options = {}) {
     const connectionState = ref('disconnected'); // disconnected | connecting | connected
     const messageBuffer = ref([]);
 
-    const { echoAvailable, listen } = useRealtime();
+    const { echoAvailable, listenScoped } = useRealtime(options);
 
     function csrfToken() {
         return typeof document !== 'undefined' ? document.querySelector('meta[name="csrf-token"]')?.content || '' : '';
@@ -123,26 +123,17 @@ export function useChat(options = {}) {
     function subscribeToChat(sessionId, callbacks = {}) {
         if (!echoAvailable.value) return () => {};
 
-        const channelName = `escalated.chat.${sessionId}`;
-        const unsubs = [];
-
-        if (callbacks.onMessage) {
-            unsubs.push(listen(channelName, '.chat.message', callbacks.onMessage));
-        }
-        if (callbacks.onTyping) {
-            unsubs.push(listen(channelName, '.chat.typing', callbacks.onTyping));
-        }
-        if (callbacks.onEnded) {
-            unsubs.push(listen(channelName, '.chat.ended', callbacks.onEnded));
-        }
-        if (callbacks.onAssigned) {
-            unsubs.push(listen(channelName, '.chat.assigned', callbacks.onAssigned));
-        }
+        const unsubscribe = listenScoped(`chat.${sessionId}`, {
+            '.chat.message': callbacks.onMessage,
+            '.chat.typing': callbacks.onTyping,
+            '.chat.ended': callbacks.onEnded,
+            '.chat.assigned': callbacks.onAssigned,
+        });
 
         connectionState.value = 'connected';
 
         return () => {
-            unsubs.forEach((fn) => fn());
+            unsubscribe();
             connectionState.value = 'disconnected';
         };
     }
@@ -157,19 +148,10 @@ export function useChat(options = {}) {
     function subscribeToChatQueue(callbacks = {}) {
         if (!echoAvailable.value) return () => {};
 
-        const channelName = 'escalated.chat.queue';
-        const unsubs = [];
-
-        if (callbacks.onNewChat) {
-            unsubs.push(listen(channelName, '.chat.new', callbacks.onNewChat));
-        }
-        if (callbacks.onChatAccepted) {
-            unsubs.push(listen(channelName, '.chat.accepted', callbacks.onChatAccepted));
-        }
-
-        return () => {
-            unsubs.forEach((fn) => fn());
-        };
+        return listenScoped('chat.queue', {
+            '.chat.new': callbacks.onNewChat,
+            '.chat.accepted': callbacks.onChatAccepted,
+        });
     }
 
     return {

package/src/composables/useGuestVerification.js

@@ -0,0 +1,48 @@
+import { onScopeDispose, reactive, watch } from 'vue';
+
+/** Keep each mailbox proof tied to the form and destination that requested it. */
+export function useGuestVerification(email, purpose, requestCode, context = () => '') {
+    const state = reactive({ id: '', code: '', message: '', error: '', pending: false });
+    let generation = 0;
+    function reset() {
+        generation++;
+        Object.assign(state, { id: '', code: '', message: '', error: '', pending: false });
+    }
+    watch([email, context], reset, { flush: 'sync' });
+    onScopeDispose(reset);
+
+    async function send() {
+        if (state.pending) return;
+        reset();
+        const current = generation;
+        state.pending = true;
+        try {
+            const result = await requestCode(email(), purpose);
+            if (current !== generation) return;
+            if (typeof result.verification_id !== 'string' || !result.verification_id) {
+                throw new Error('Could not request a verification code.');
+            }
+            state.id = result.verification_id;
+            state.message = 'Check your email. Enter the 8-digit code to continue; it expires in 10 minutes.';
+        } catch (error) {
+            if (current === generation) state.error = error.message || 'Could not request a verification code.';
+        } finally {
+            if (current === generation) state.pending = false;
+        }
+    }
+
+    async function ready() {
+        if (!state.id) {
+            await send();
+            return false;
+        }
+        state.error = '';
+        if (!/^[0-9]{8}$/.test(state.code)) {
+            state.error = 'Enter the 8-digit code from your email.';
+            return false;
+        }
+        return true;
+    }
+
+    return { state, ready, send, reset, fields: () => ({ verification_id: state.id, verification_code: state.code }) };
+}