@velaro/mcp-server 0.6.64 → 0.6.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "0.6.64",
+  "version": "0.6.66",
   "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro account: KB, workflows, bots, conversations, contacts, routing, and more.",
   "type": "module",
   "bin": {

package/server.js

@@ -1544,7 +1544,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         preferPreviousAgentOnTimeout:     { type: 'boolean', description: 'On timeout, prefer agent from visitor\'s prior session (loyalty routing)' },
         agentFollowUpFlagEnabled:         { type: 'boolean', description: 'Flag conversations that required multiple reroutes' },
         queueUnavailableGracePeriodSeconds: { type: 'number', description: 'Wait before returning unavailable when agents are transiently busy (seconds)' },
-        terminalActionOverride:           { type: 'number',  description: 'Terminal action: 0=Survey 1=CreateTicket 2=SurveyAndCreateTicket 3=Queue 4=OfflineMessage 5=NoOp 6=EndChat 7=NotifyManager 8=RunWorkflow (needs inactivityTerminalWorkflowId). Null = default (Survey).' },
+        terminalActionOverride:           { type: 'number',  description: 'Terminal action: 0=Survey 1=CreateTicket 2=SurveyAndCreateTicket 3=Queue 4=OfflineMessage 5=NoOp 6=EndChat 7=NotifyManager 8=RunWorkflow (needs inactivityTerminalWorkflowId) 9=ReturnToBot (needs advancedTerminalBotProfileId). Null = default (Survey).' },
         exhaustionMessageTemplate:        { type: 'string',  description: 'Message sent to the visitor with the final action (max 500 characters).' },
         reassignmentMode:                 { type: 'string',  enum: ['Observe','QueueOnly','Reassign'], description: "Observe (default) only records what would happen; QueueOnly returns a silent agent's chat to the group queue; Reassign hands it to the next agent. Backup group and no-agent-available steps need Reassign." },
         inactivityChainEnabled:           { type: 'boolean', description: 'Master switch for the agent inactivity fallback chain. Off by default.' },
@@ -1559,6 +1559,14 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         queueEscalationAfterMinutes:      { type: 'number',  description: 'Widen the queue alert to backup group and managers after this many minutes (1-240).' },
         inactivityVisitorText:            { type: 'string',  description: 'Message the visitor sees when the chat is moved (max 500 characters).' },
         inactivityAgentText:              { type: 'string',  description: 'Message agents see on a re-queued chat (max 500 characters).' },
+        advancedNoTypingAfterSeconds:     { type: 'number',  description: 'Advanced (opt-in): seconds an agent can go without typing in a waiting chat before the no-typing steps run (10-3600). Inert unless the inactivity chain is on.' },
+        advancedNoTypingVisitorMessage:   { type: 'string',  description: 'Advanced: message sent to the visitor when the agent steps away (max 500 characters).' },
+        advancedNoTypingAlertSupervisor:  { type: 'boolean', description: 'Advanced: alert a supervisor when the agent stops typing.' },
+        advancedNoTypingReroute:          { type: 'boolean', description: 'Advanced: move the chat to another agent when the agent stops typing.' },
+        advancedEscalationTeamId:         { type: 'number',  description: 'Advanced: group alerted when the chat stays unattended (escalation tier).' },
+        advancedEscalationAfterSeconds:   { type: 'number',  description: 'Advanced: seconds unattended before the escalation group is alerted (30-14400). Needs advancedEscalationTeamId.' },
+        advancedTerminalBotProfileId:     { type: 'number',  description: 'Advanced: bot (AI configuration id) the chat returns to when terminalActionOverride is 9 (ReturnToBot).' },
+        advancedApplyToRoutingActions:    { type: 'number',  description: 'Advanced: 1 = auto-routing only, 2 = queue only. Omit to leave unchanged (default covers both).' },
       },
       required: [],
     },
@@ -2562,6 +2570,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         from:   { type: 'string', description: 'yyyy-MM-dd start (default: 7 days ago).' },
         to:     { type: 'string', description: 'yyyy-MM-dd end (default: today).' },
         teamId: { type: 'number', description: 'Optional team ID to narrow the report.' },
+        includeDemo: { type: 'boolean', description: 'true = show only the seeded sample (demo) data instead of real conversations. Default false. The response demoAvailable flag says whether sample data exists for the range.' },
       },
     },
   },
@@ -4630,7 +4639,7 @@ function parseBusinessHours(input) {
 
 // -- Agent inactivity chain helpers (velaro-messaging PR #1471, v20 ONLY) ------------------------
 // Terminal action ints are persisted by messaging (append-only enum). The API returns/accepts the NAME.
-const TERMINAL_ACTION_NAMES = ['Survey','CreateTicket','SurveyAndCreateTicket','Queue','OfflineMessage','NoOp','EndChat','NotifyManager','RunWorkflow'];
+const TERMINAL_ACTION_NAMES = ['Survey','CreateTicket','SurveyAndCreateTicket','Queue','OfflineMessage','NoOp','EndChat','NotifyManager','RunWorkflow','ReturnToBot'];
 function terminalActionLabel(v) {
   if (v === null || v === undefined || v === '') return 'Default (Survey)';
   if (typeof v === 'number') return TERMINAL_ACTION_NAMES[v] ?? String(v);
@@ -4650,6 +4659,37 @@ function terminalActionForSave(v) {
   if (!hit) throw new Error(`Unknown terminal action "${v}". Use one of: ${valid}`);
   return hit;
 }
+// Advanced inactivity routing (stepped away / not typing). Mirrors the messaging validation; the server stays the authority.
+function validateAdvancedPatch(a) {
+  const int = (v) => Number.isInteger(v);
+  if (a.noTypingAfterSeconds !== undefined && !(int(a.noTypingAfterSeconds) && a.noTypingAfterSeconds >= 10 && a.noTypingAfterSeconds <= 3600))
+    return 'advancedNoTypingAfterSeconds must be a whole number from 10 to 3600.';
+  if (a.escalationAfterSeconds !== undefined && !(int(a.escalationAfterSeconds) && a.escalationAfterSeconds >= 30 && a.escalationAfterSeconds <= 14400))
+    return 'advancedEscalationAfterSeconds must be a whole number from 30 to 14400.';
+  if (typeof a.noTypingVisitorMessage === 'string' && a.noTypingVisitorMessage.length > 500)
+    return 'advancedNoTypingVisitorMessage must be 500 characters or fewer.';
+  if (a.applyToRoutingActions !== undefined && a.applyToRoutingActions !== 1 && a.applyToRoutingActions !== 2)
+    return 'advancedApplyToRoutingActions must be 1 (auto-routing) or 2 (queue). Omit it to leave the setting unchanged.';
+  return null;
+}
+
+function describeAdvanced(adv) {
+  if (!adv) return ['', '(This messaging build does not report the advanced stepped-away settings.)'];
+  const from = (f) => (adv.inheritedFrom?.[f] ? ` [from ${adv.inheritedFrom[f]}]` : '');
+  const v = (x) => (x === null || x === undefined ? 'not set' : x);
+  return [
+    '',
+    'Advanced (stepped away / not typing):',
+    `  No typing after:           ${adv.noTypingAfterSeconds != null ? `${adv.noTypingAfterSeconds}s` : 'off'}${from('noTypingAfterSeconds')}`,
+    `  Visitor message:           ${v(adv.noTypingVisitorMessage)}${from('noTypingVisitorMessage')}`,
+    `  Alert supervisor:          ${v(adv.noTypingAlertSupervisor)}${from('noTypingAlertSupervisor')}`,
+    `  Move to another agent:     ${v(adv.noTypingReroute)}${from('noTypingReroute')}`,
+    `  Escalation group:          ${v(adv.escalationTeamId)}${adv.escalationAfterSeconds != null ? ` after ${adv.escalationAfterSeconds}s` : ''}${from('escalationTeamId')}`,
+    `  Return-to-bot bot:         ${v(adv.terminalBotProfileId)}${from('terminalBotProfileId')}`,
+    `  Applies to:                ${adv.applyToRoutingActions === 1 ? 'auto-routing only' : adv.applyToRoutingActions === 2 ? 'queue only' : 'auto-routing and queue'}${from('applyToRoutingActions')}`,
+  ];
+}
+
 const CHAIN_FIELDS = [
   'enabled','backupTeamId','backupTeamAfterSeconds','noTargetActionAfterSeconds','rerouteOnAgentUnavailable',
   'alertAvailableAgentsOnRelease','notifyManagersOnInactivity','rerouteCooldownSeconds','queueEscalationAfterMinutes',
@@ -5614,6 +5654,7 @@ async function handleTool(name, args) {
           `  Terminal workflow:         ${chain.terminalWorkflowId ?? 'none'}`,
         ] : []),
       ] : ['', '(This messaging build does not report the inactivity chain.)'];
+      chainLines.push(...describeAdvanced(p.advanced));
       return [
         `Enabled:                     ${p.enabled}`,
         `Initial response timeout:    ${p.initialResponseTimeoutSeconds}s`,
@@ -5678,6 +5719,29 @@ async function handleTool(name, args) {
         for (const f of CHAIN_FIELDS) if (chainPatch[f] !== undefined) chain[f] = chainPatch[f];
         merged.inactivityChain = chain;
       }
+      // Advanced block (stepped away / not typing). null = unchanged on the server, so send only what was passed.
+      const advancedPatch = {
+        noTypingAfterSeconds: args.advancedNoTypingAfterSeconds,
+        noTypingVisitorMessage: args.advancedNoTypingVisitorMessage,
+        noTypingAlertSupervisor: args.advancedNoTypingAlertSupervisor,
+        noTypingReroute: args.advancedNoTypingReroute,
+        escalationTeamId: args.advancedEscalationTeamId,
+        escalationAfterSeconds: args.advancedEscalationAfterSeconds,
+        terminalBotProfileId: args.advancedTerminalBotProfileId,
+        applyToRoutingActions: args.advancedApplyToRoutingActions,
+      };
+      delete merged.advanced; // never echo the read-side block (it carries inheritedFrom) back unchanged
+      if (Object.values(advancedPatch).some((v) => v !== undefined)) {
+        if (!('advanced' in current)) {
+          throw new Error('This messaging build does not report the advanced inactivity settings yet; they cannot be saved.');
+        }
+        const advErr = validateAdvancedPatch(advancedPatch);
+        if (advErr) throw new Error(advErr);
+        merged.advanced = Object.fromEntries(Object.entries(advancedPatch).map(([k, v]) => [k, v === undefined ? null : v]));
+      }
+      if (merged.terminalActionOverride === 'ReturnToBot' && args.advancedTerminalBotProfileId == null && current.advanced?.terminalBotProfileId == null) {
+        throw new Error('Terminal action 9 (ReturnToBot) needs advancedTerminalBotProfileId.');
+      }
       await messagingPut('/AutoRoutingPolicy', merged);
       // PUT answers { updated: true }, not the policy: re-read so the reply reports what is really stored.
       const saved = await messagingGet('/AutoRoutingPolicy');
@@ -7245,6 +7309,7 @@ async function handleTool(name, args) {
     case 'experience_impact_report': {
       const qs = new URLSearchParams();
       for (const k of ['from', 'to', 'teamId']) if (args[k] != null && args[k] !== '') qs.set(k, String(args[k]));
+      if (args.includeDemo === true) qs.set('includeDemo', 'true');
       const r = await messagingGet(`/Reports/experience-impact${qs.toString() ? '?' + qs : ''}`);
       const sm = r.summary ?? {};
       const lines = [
@@ -7252,6 +7317,7 @@ async function handleTool(name, args) {
         `Experience index: ${sm.experienceIndex ?? '-'} / 100`,
         `Adherence ${sm.adherencePct ?? '-'}% | Service level ${sm.serviceLevelPct ?? '-'}% | Missed chats ${sm.missedChats ?? '-'} | Avg wait ${sm.avgWaitSec ?? '-'}s | CSAT ${sm.csatAvg ?? '-'} (${sm.csatResponses ?? 0} responses)`,
         ...(r.insights ?? []).map(i => `  [${i.severity}] ${i.text}`),
+        ...(r.demoAvailable ? ['Sample (demo) data is available for this range; pass includeDemo=true to view it.'] : []),
         `Intervals: ${(r.intervals ?? []).length} | Agents: ${(r.agents ?? []).length}`,
       ];
       if (r.botVsHuman) {