@velaro/mcp-server 0.6.104 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "0.6.104",
+  "version": "1.0.1",
   "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": {
@@ -45,6 +45,7 @@
     "tool-annotations.js",
     "log-search.js",
     "messaging-base.js",
+    "workflow-schedule.js",
     "server.json",
     "README.md"
   ],

package/server.js

@@ -51,6 +51,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import { withAnnotations } from './tool-annotations.js';
 import { resolveMessagingApi } from './messaging-base.js';
+import { buildResolvePath, buildTimelinePath, buildOverrideBody, buildValidateBody, buildBannerPath, buildOverrideListPath, tolerant, VALIDATE_PATH, OVERRIDE_PATH } from './workflow-schedule.js';
 
 // Default was 'https://help.velaro.com'. Renamed to the recognizable admin API hostname for
 // clarity during the 2026-09-10 Donaldson bot Calendly status investigation
@@ -156,6 +157,25 @@ function extractLogEntries(response) {
   return [];
 }
 
+/** Body for POST/PUT ApplePayPresetOrders: only passed fields; the server computes the total. */
+function applePayPresetBody(args) {
+  const body = {};
+  for (const k of ['name', 'description', 'currencyCode', 'isActive', 'overrideRestrictedToManagers']) {
+    if (args[k] !== undefined) body[k] = args[k];
+  }
+  if (args.lineItems !== undefined) {
+    if (!Array.isArray(args.lineItems) || args.lineItems.length > 20) throw new Error('lineItems must be an array of at most 20 items');
+    body.lineItems = args.lineItems.map(li => ({ label: String(li?.label ?? ''), amount: Number(li?.amount) }));
+  }
+  return body;
+}
+
+function applePayPresetId(raw) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) throw new Error('id must be a positive whole number');
+  return n;
+}
+
 /**
  * Body for PUT avatar/groups|workflows/{id}/override. Merge by default (only passed fields change, "" clears one);
  * `replace: true` replaces the whole override. Mirrors cli/lib/commands/avatar.js.
@@ -212,6 +232,65 @@ function execInsightsRange(days) {
 
 const messagingDel   = (path)       => messagingRequest('DELETE', path);
 
+// Visitor link helpers (mirrors cli/lib/visitor-link.js; keep in sync, covered by cli/lib/visitor-link.test.js)
+
+const MAX_TTL_MINUTES = 1440;
+
+function decodeLinkToken(token) {
+  const out = { ok: false, problems: [] };
+  if (typeof token !== 'string' || !token.trim()) { out.problems.push('empty token'); return out; }
+  const parts = token.trim().split('.');
+  if (parts.length !== 3 || parts[0] !== 'vlk1') { out.problems.push('not a vlk1 link token (expected vlk1.<payload>.<signature>)'); return out; }
+  const payload = Buffer.from(parts[1].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
+  const f = payload.split('|');
+  if (f.length < 6) { out.problems.push('payload has fewer than 6 fields'); return out; }
+  const [siteId, visitorId, conversationBaseId, scope, iat, exp] = f;
+  const toMs = (v) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? (n > 1e12 ? n : n * 1000) : null; };
+  const issuedMs = toMs(iat);
+  const expMs = toMs(exp);
+  Object.assign(out, {
+    ok: true,
+    siteId: Number(siteId) || null,
+    visitorId,
+    conversationBaseId: Number(conversationBaseId) || null,
+    scope,
+    issuedAt: issuedMs ? new Date(issuedMs).toISOString() : null,
+    expiresAt: expMs ? new Date(expMs).toISOString() : null,
+    signaturePresent: parts[2].length > 0,
+  });
+  if (scope !== 'link') out.problems.push(`unexpected scope "${scope}" (v1 only issues "link")`);
+  if (!out.signaturePresent) out.problems.push('signature missing');
+  if (!expMs) out.problems.push('expiry not parseable');
+  return out;
+}
+
+function diagnoseLink({ token, siteId, settings, now = Date.now() }) {
+  const claims = token ? decodeLinkToken(token) : { ok: false, problems: [] };
+  const findings = [...claims.problems];
+  if (claims.ok) {
+    if (siteId && claims.siteId && Number(siteId) !== claims.siteId) findings.push(`token was minted for site ${claims.siteId}, not site ${siteId}: cross-site tokens always fail`);
+    if (claims.expiresAt && Date.parse(claims.expiresAt) <= now) findings.push(`token expired at ${claims.expiresAt}`);
+    if (!claims.conversationBaseId) findings.push('token carries no conversation id (visitor had not started a chat when it was minted)');
+  }
+  if (settings) {
+    if (!settings.enabled) findings.push('visitor linking is OFF for this site: mint returns linking_disabled');
+    if (settings.keyConfigured === false) findings.push('link signing key is not configured on the server: mint and resolve fail closed (503 key_not_configured)');
+  }
+  return { claims, settings: settings ?? null, findings, healthy: findings.length === 0 };
+}
+
+function validateSettingsArgs({ enabled, ttlMinutes }) {
+  if (enabled === undefined && ttlMinutes === undefined) throw new Error('Pass enabled and/or ttlMinutes.');
+  if (ttlMinutes !== undefined && (!Number.isInteger(ttlMinutes) || ttlMinutes < 1 || ttlMinutes > MAX_TTL_MINUTES)) {
+    throw new Error(`ttlMinutes must be a whole number from 1 to ${MAX_TTL_MINUTES}.`);
+  }
+  const body = {};
+  if (enabled !== undefined) body.enabled = !!enabled;
+  if (ttlMinutes !== undefined) body.ttlMinutes = ttlMinutes;
+  return body;
+}
+
+
 // Skill-based routing CRUD helper for SkillRouting/{Skills|Assignments|Requirements}.
 async function skillRoutingCrud(resource, args, fields) {
   const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
@@ -1114,6 +1193,66 @@ const TOOLS = [
       required: ['name', 'trigger'],
     },
   },
+  {
+    name: 'workflow_schedule_resolve',
+    description: 'Which workflow runs at a given date/time? Returns { mode, first (winner), gap, winnerOverrideId, active (ordered workflows with priority), trace } (workflow schedule priority; schedule-only preview, a workflow own trigger conditions are not evaluated). Site comes from auth. Answers "why did workflow X (not) fire at 6 PM Dec 25". Read-only.',
+    inputSchema: { type: 'object', properties: {
+      trigger: { type: 'string', description: 'Trigger type, e.g. "conversation_opened"' },
+      channel: { type: 'string', description: 'Channel, e.g. "Chat", "Sms"' },
+      at:      { type: 'string', description: 'ISO date-time to evaluate (default now)' },
+      tz:      { type: 'string', description: 'IANA time zone, e.g. "America/Los_Angeles"' },
+    }, required: ['trigger'] },
+  },
+  {
+    name: 'workflow_schedule_timeline',
+    description: 'Timeline of which workflow wins over a date range for a trigger/channel: returns { segments: [{ fromUtc, toUtc, workflowId, workflowName, gap }], gaps (count) }. Read-only.',
+    inputSchema: { type: 'object', properties: {
+      from:    { type: 'string', description: 'ISO start with offset (default now)' },
+      to:      { type: 'string', description: 'ISO end with offset (default from + 14 days; range max 62 days)' },
+      trigger: { type: 'string' },
+      channel: { type: 'string' },
+    }, required: ['trigger'] },
+  },
+  {
+    name: 'workflow_schedule_validate',
+    description: 'Dry-run one draft schedule override without saving: what would the next 400 days look like. Returns { ok, errors, warnings, gapCount }; same-priority overlap and a bad target block, gaps warn. Omit override to just list current gaps. Read-only.',
+    inputSchema: { type: 'object', properties: {
+      trigger:  { type: 'string' },
+      channel:  { type: 'string' },
+      override: { type: 'object', description: 'Draft override: { sharedScheduleId, name, startDate, endDate, action ("SwitchWorkflow" or 3), targetWorkflowId, recurringYearly, autoExpiresAt, isActive }' },
+    }, required: ['trigger'] },
+  },
+  {
+    name: 'workflow_schedule_banner',
+    description: 'The first gap (no workflow scheduled to run) in the next 7 days for a trigger/channel: { hasGap, fromUtc, toUtc, message }. Read-only.',
+    inputSchema: { type: 'object', properties: { trigger: { type: 'string' }, channel: { type: 'string' } } },
+  },
+  {
+    name: 'workflow_schedule_override_list',
+    description: 'List this site\'s schedule overrides, optionally only one action ("SwitchWorkflow" or 3). Read-only.',
+    inputSchema: { type: 'object', properties: { action: { description: '"SwitchWorkflow" or an int action value' } } },
+  },
+  {
+    name: 'workflow_schedule_override_delete',
+    description: 'Delete a schedule override by id (site admins only). Writes: confirm with the user first.',
+    inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
+  },
+  {
+    name: 'workflow_schedule_override_save',
+    description: 'Create (omit id) or update (id) a schedule override. action accepts "SwitchWorkflow" (3) with targetWorkflowId to run a different workflow on those dates, alongside the existing actions. Writes: confirm the dates and target with the user first.',
+    inputSchema: { type: 'object', properties: {
+      id:               { type: 'number', description: 'Existing override id to update; omit to create' },
+      sharedScheduleId: { type: 'number' },
+      name:             { type: 'string' },
+      startDate:        { type: 'string', description: 'YYYY-MM-DD' },
+      endDate:          { type: 'string', description: 'YYYY-MM-DD, optional' },
+      recurringYearly:  { type: 'boolean' },
+      autoExpiresAt:    { type: 'string', description: 'ISO date-time with offset, optional' },
+      isActive:         { type: 'boolean', description: 'Default true' },
+      action:          { description: '"SwitchWorkflow" or its int value 3 (or an existing action value)' },
+      targetWorkflowId: { type: 'number', description: 'Workflow to run when action is SwitchWorkflow' },
+    }, required: ['action'] },
+  },
   {
     name: 'workflow_update_node',
     description: `Update a single node in a workflow. Use workflow_get first to read current nodes, then pass the full updated node. The node must already exist.
@@ -1681,6 +1820,41 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['message'],
     },
   },
+  {
+    name: 'visitor_link_get_settings',
+    description: 'Get the visitor-linking settings for this site: whether chat visitors can be linked to later form/survey submissions (default off), the link lifetime in minutes, and whether the signing key is configured. Site is resolved server-side.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'visitor_link_set_settings',
+    description: 'Turn visitor linking on or off for this site and/or set the link lifetime (1-1440 minutes). Only fields you pass change. Links are only created for visitors who have chatted and, when the site uses a consent banner, granted functional storage.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enabled:    { type: 'boolean', description: 'Enable or disable visitor linking' },
+        ttlMinutes: { type: 'number', description: 'Link lifetime in minutes, 1-1440' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'visitor_link_diagnose',
+    description: 'Explain why visitor linking is or is not working for this site. Reads the current settings and, if you pass a vlk1 link token, decodes its claims (site, conversation, expiry) and reports cross-site, expired, missing-conversation and key problems. The signature is not verified here; use visitor_link_resolve for the real server-side check.',
+    inputSchema: {
+      type: 'object',
+      properties: { token: { type: 'string', description: 'Optional vlk1 link token from a form hidden field' } },
+      required: [],
+    },
+  },
+  {
+    name: 'visitor_link_resolve',
+    description: 'Exchange a vlk1 link token for the visitor id, conversation id and contact id (what your own server does when a form arrives). Cross-site and expired tokens fail.',
+    inputSchema: {
+      type: 'object',
+      properties: { token: { type: 'string', description: 'vlk1 link token' } },
+      required: ['token'],
+    },
+  },
   {
     name: 'teams_push_settings_get',
     description: 'Get the Velaro Bot proactive-alert settings for this site: per-alert switches (new chat, missed chat, ticket created, ticket assigned, daily digest), the effective daily cap and the push count for today. Site is resolved server-side.',
@@ -3464,7 +3638,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     inputSchema: {
       type: 'object',
       properties: {
-        report:       { type: 'string', enum: ['program_breakdown', 'agent_scorecard', 'qa_coverage', 'coaching_queue', 'sentiment_breakdown', 'topic_radar', 'weekly_brief', 'weekly_brief_send_test', 'repeat_contact', 'demand_coverage', 'bot_containment', 'effort_index', 'promise_ledger', 'promise_dismiss', 'new_agent_ramp', 'year_in_review'] },
+        report:       { type: 'string', enum: ['program_breakdown', 'agent_scorecard', 'qa_coverage', 'coaching_queue', 'sentiment_breakdown', 'topic_radar', 'weekly_brief', 'weekly_brief_send_test', 'repeat_contact', 'demand_coverage', 'bot_containment', 'effort_index', 'promise_ledger', 'promise_dismiss', 'new_agent_ramp', 'year_in_review', 'bonus_insights', 'operations_briefing', 'entitled'] },
         from:         { type: 'string', description: 'yyyy-MM-dd start (default: 30 days ago).' },
         to:           { type: 'string', description: 'yyyy-MM-dd end, inclusive (default: today).' },
         groupBy:      { type: 'string', description: 'program_breakdown: website|team|platform|device|entrypage. sentiment_breakdown: website|team|agent|theme.' },
@@ -3481,6 +3655,13 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         timeZone:     { type: 'string', description: 'demand_coverage: IANA time zone (default America/Los_Angeles).' },
         lowScore:     { type: 'number', description: 'bot_containment: QA score below which a handed-off chat counts as regret (1-100, default 60).' },
         includeDemo:  { type: 'boolean', description: 'true = show only the seeded sample (demo) data. Default false.' },
+        name:         { type: 'string', description: 'bonus_insights: which analysis: coverage_gap|next_best_fix|escalation_risk|skill_gap_matrix|handle_quality_outliers|abandon_causes.' },
+        narrative:    { type: 'boolean', description: 'operations_briefing: include the cached AI narrative (default true).' },
+        minutesPerReview: { type: 'number', description: 'bonus_insights: assumed minutes per manual review (0-240).' },
+        hourlyCost:   { type: 'number', description: 'bonus_insights: assumed reviewer hourly cost (0-1000).' },
+        deflectionPct: { type: 'number', description: 'bonus_insights: assumed deflection percent (0-100).' },
+        costPerChat:  { type: 'number', description: 'bonus_insights: assumed cost per chat (0-1000).' },
+        waitMinutes:  { type: 'number', description: 'bonus_insights: wait minutes that counts as abandoned (1-1440).' },
         promiseId:    { type: 'string', description: 'promise_dismiss: the promise id to dismiss (managers only).' },
         buildId:      { type: 'string', description: 'year_in_review: the build id returned by a start call; when given, returns that build\'s status (queued|building|completed|failed) and download link instead of starting a new build.' },
       },
@@ -3706,6 +3887,51 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  // ── Apple Pay pre-canned (preset) orders ───────────────────────────────────
+  {
+    name: 'apple_pay_preset_list',
+    description: 'List the Apple Pay pre-canned (preset) orders for the authenticated site: name, line items (label + amount), currency, server-computed total, active flag, and whether only managers may change amounts at send time. Use the id or name with the AI skill (preset_order_id / preset_order_name) or the composer.',
+    inputSchema: { type: 'object', properties: { activeOnly: { type: 'boolean', description: 'Only return active presets (default false).' } } },
+  },
+  {
+    name: 'apple_pay_preset_create',
+    description: 'Create an Apple Pay pre-canned order (up to 20 line items). The total is computed by the server from the line items; never send one.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Preset name, e.g. "Haircut and tip".' },
+        description: { type: 'string', description: 'Optional description.' },
+        currencyCode: { type: 'string', description: 'ISO currency code, default USD.' },
+        lineItems: { type: 'array', maxItems: 20, description: 'Line items.', items: { type: 'object', properties: { label: { type: 'string' }, amount: { type: 'number' } }, required: ['label', 'amount'] } },
+        isActive: { type: 'boolean', description: 'Available to agents and the AI (default true).' },
+        overrideRestrictedToManagers: { type: 'boolean', description: 'Only managers can change amounts at send time.' },
+      },
+      required: ['name', 'lineItems'],
+    },
+  },
+  {
+    name: 'apple_pay_preset_update',
+    description: 'Update an Apple Pay preset order. Only the fields you pass change; passing lineItems replaces the whole list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Preset order id (from apple_pay_preset_list).' },
+        name: { type: 'string' },
+        description: { type: 'string' },
+        currencyCode: { type: 'string' },
+        lineItems: { type: 'array', maxItems: 20, items: { type: 'object', properties: { label: { type: 'string' }, amount: { type: 'number' } }, required: ['label', 'amount'] } },
+        isActive: { type: 'boolean' },
+        overrideRestrictedToManagers: { type: 'boolean' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'apple_pay_preset_delete',
+    description: 'Delete an Apple Pay preset order by id.',
+    inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Preset order id.' } }, required: ['id'] },
+  },
+
   // ── Velaro Avatar (first-party provider) — library, personalities, site/group inheritance ──
   {
     name: 'avatar_list_library',
@@ -4581,6 +4807,15 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  {
+    name: 'netsuite_rollback_auth',
+    description: 'Undo a NetSuite connection-type switch: sets a connection that was moved to OAuth 2.0 / M2M back to the legacy OAuth 1.0a credentials. Refused (409) once the old credentials were cleared. Nothing is deleted. Administrator only, audited. Lives in velaro-messaging - requires VELARO_MESSAGING_API.',
+    inputSchema: {
+      type: 'object',
+      properties: { configId: { type: 'number', description: 'NetSuite config ID (see netsuite_list_configs).' } },
+      required: ['configId'],
+    },
+  },
   {
     name: 'netsuite_suiteapp_download',
     description: 'Download the NetSuite screen-pop SuiteApp (SDF project zip) to a local file. With includeKey=true (default) a new crm-embed-only key is minted and baked into the zip, so NO NetSuite API Secret and no key paste is needed. With includeKey=false the zip is key-less and the admin must create a NetSuite API Secret: type ID velaro_api_key in the form (NetSuite adds the prefix, giving custsecret_velaro_api_key). Lives in velaro-messaging - requires VELARO_MESSAGING_API.',
@@ -4888,6 +5123,21 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   // Distinct from the reusable coupon-CODE catalog, which lives in velaro-messaging
   // (superadmin/billing/coupons). Pass couponCode here only to record which catalog code a grant
   // corresponds to.
+  {
+    name: 'sign_versions_list',
+    description: 'Velaro Sign: list every uploaded document version of a contract (owner-only; signers never see old versions). Newest first with sha256, pages, uploader, note.',
+    inputSchema: { type: 'object', properties: { contractId: { type: 'number', description: 'Contract ID' } }, required: ['contractId'] },
+  },
+  {
+    name: 'sign_versions_diff',
+    description: 'Velaro Sign: text diff between two document versions of a contract (changed blocks only: removed vs added lines). Owner-only.',
+    inputSchema: { type: 'object', properties: { contractId: { type: 'number' }, from: { type: 'number', description: 'Older version number' }, to: { type: 'number', description: 'Newer version number' } }, required: ['contractId', 'from', 'to'] },
+  },
+  {
+    name: 'sign_versions_upload',
+    description: 'Velaro Sign: upload a new PDF version of a contract document from a local file path. Allowed only while the contract is a draft; after send/sign, void and re-send.',
+    inputSchema: { type: 'object', properties: { contractId: { type: 'number' }, filePath: { type: 'string', description: 'Local path of the PDF' }, note: { type: 'string', description: 'Change note' } }, required: ['contractId', 'filePath'] },
+  },
   {
     name: 'coupon_grant_list',
     description: 'List per-account Stripe discount grants. Velaro billing staff only. Shows which accounts currently have a discount and its status.',
@@ -5013,6 +5263,51 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['id'],
     },
   },
+  {
+    name: 'usage_alerts',
+    description: 'Plan-limit alerts for the authenticated site: every metered resource at or above its warning threshold (80%+), with used/limit, percent, level (warning | critical | limit) and whether overage is billed. Same rules as the usage-limit emails and the dashboard banner. Use to answer "are they near a limit?" or "why did they get a usage email?". Read-only. To raise a limit, a customer uses Billing > Contact Account Manager; staff use support_set_limit.',
+  },
+  {
+    name: 'billing_notify_settings_get',
+    description: 'Billing notifications: the global settings (receipts.card, receipts.ach, receipts.other, invoices.bcc, digest.recipients). Staff only.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'billing_notify_setting_set',
+    description: 'Billing notifications: set one global setting. receipts.card|receipts.ach|receipts.other = never|send; invoices.bcc = comma-separated emails (blank = none); digest.recipients = comma-separated emails. Staff only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        key:   { type: 'string', enum: ['receipts.card', 'receipts.ach', 'receipts.other', 'invoices.bcc', 'digest.recipients'], description: 'Setting key' },
+        value: { type: 'string', description: 'New value' },
+      },
+      required: ['key', 'value'],
+    },
+  },
+  {
+    name: 'billing_receipt_overrides_set',
+    description: 'Billing notifications: set receipt overrides on one subscription (never|send per channel). Channels you omit keep their current override. Staff only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        subscriptionId: { type: 'number', description: 'Billing subscription ID' },
+        card:  { type: 'string', enum: ['never', 'send'], description: 'Card receipts override' },
+        ach:   { type: 'string', enum: ['never', 'send'], description: 'ACH receipts override' },
+        other: { type: 'string', enum: ['never', 'send'], description: 'Other (check, cash, wire) receipts override' },
+      },
+      required: ['subscriptionId'],
+    },
+  },
+  {
+    name: 'billing_digest_send_now',
+    description: 'Billing notifications: send the daily billing digest now to digest.recipients (same email the 7am run sends). Staff only.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'billing_receipts_run_now',
+    description: 'Billing notifications: decide pending payment receipts now instead of at :05. Returns the counts (sent, skipped, failed). Staff only.',
+    inputSchema: { type: 'object', properties: {} },
+  },
   {
     name: 'billing_plan_status',
     description: 'Returns the current subscription state for the authenticated site: active Enable* feature flags, licensed seat count, self-serve seats toggle, and recent Stripe payment session history. Use this to answer "what plan are they on?" or "which features are active?"',
@@ -5122,6 +5417,43 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId', 'featureKey', 'value'],
     },
   },
+  {
+    name: 'entitlement_trial_get',
+    description: 'Trial governance view for one site: trial status, days left, and the grant ledger (active/held/purchased/revoked). Superadmin only.',
+    inputSchema: { type: 'object', properties: { siteId: { type: 'number', description: 'Site ID.' } }, required: ['siteId'] },
+  },
+  {
+    name: 'entitlement_trial_recommend',
+    description: 'Deterministic package recommendation for a trial site, from its recorded trial usage. Returns customer-safe text plus a staff-only rationale. Superadmin only.',
+    inputSchema: { type: 'object', properties: { siteId: { type: 'number', description: 'Site ID.' } }, required: ['siteId'] },
+  },
+  {
+    name: 'entitlement_trial_grant',
+    description: 'Grant one feature to a trial site and record it in the trial ledger (who, when, why). Superadmin only; the site must be in a trial.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:     { type: 'number', description: 'Site ID.' },
+        featureKey: { type: 'string', description: 'Feature key, e.g. "EnableIvr".' },
+        reason:     { type: 'string', description: 'Why this feature is granted (required, recorded).' },
+      },
+      required: ['siteId', 'featureKey', 'reason'],
+    },
+  },
+  {
+    name: 'entitlement_trial_set_limit',
+    description: 'Set a per-site trial cap (MaxIndexedChunkTotal, MaxKbArticles, MaxKnowledgeDocuments, MaxScraperPagesPerMonth). Whole number >= 0; audited. Superadmin only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Site ID.' },
+        key:    { type: 'string', description: 'Cap name.' },
+        value:  { type: 'number', description: 'Whole number >= 0.' },
+        reason: { type: 'string', description: 'Why (required, audited).' },
+      },
+      required: ['siteId', 'key', 'value', 'reason'],
+    },
+  },
   {
     name: 'entitlement_remove_override',
     description: 'Remove a per-site feature override, reverting the site to its plan default. Superadmin only.',
@@ -6197,7 +6529,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   {"name":"skill_routing_assignments","description":"Skill-based routing: assign skills to agents with proficiency 1-5. action = list | create | update | delete.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"workspaceUserId":{"type":"number"},"agentSkillId":{"type":"number"},"proficiency":{"type":"number"}},"required":["action"]}},
   {"name":"skill_routing_requirements","description":"Skill-based routing: required/preferred skills per deployment and/or team. action = list | create | update | delete. Update is partial. Requirements are disabled by default; set isEnabled true to turn on.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"deploymentId":{"type":"number"},"teamId":{"type":"number"},"requiredSkillIds":{"type":"array","items":{"type":"number"}},"preferredSkillIds":{"type":"array","items":{"type":"number"}},"overflowWaitSeconds":{"type":"number"},"isEnabled":{"type":"boolean"}},"required":["action"]}},
   {"name":"skill_routing_simulate","description":"Dry-run skill routing for a team: shows which agents would be narrowed to and why. Never assigns a conversation or writes the decision log.","inputSchema":{"type":"object","properties":{"teamId":{"type":"number"},"waitedSeconds":{"type":"number"}}}},
-  {"name":"qa_rubric","description":"Conversation Quality QA rubrics. action = list | get | default | create | update | delete. Pass rubric fields in \"rubric\". Requires EnableConversationQuality.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"rubric":{"type":"object"}},"required":["action"]}},
+  {"name":"qa_rubric","description":"Conversation Quality QA rubrics. action = list | get | default | starter (create the starter rubric if the site has none) | create | update | clone (inactive copy; optional rubric.name) | activate | deactivate | rescore (re-score recent chats against the active rubric; pass days 1-90 and limit 1-500) | delete. Pass rubric fields in \"rubric\". Weights are relative and shown as percents; max 20 criteria. Requires EnableConversationQuality and the Administrator role for writes.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"rubric":{"type":"object"},"days":{"type":"number"},"limit":{"type":"number"}},"required":["action"]}},
   {"name":"qa_low_scores","description":"Conversations scoring below the rubric threshold, for QA review.","inputSchema":{"type":"object","properties":{"threshold":{"type":"number"},"days":{"type":"number"},"agentId":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}}}},
   {"name":"ai_field_extraction_get_config","description":"Get the AI field extraction config (opt-in, default off; monthly cap). Requires the ai_field_extraction entitlement.","inputSchema":{"type":"object","properties":{}}},
   {"name":"ai_field_extraction_update_config","description":"Update AI field extraction config (partial). enabled, monthlyCap (null = 500 default, hard ceiling 50000), createThemeTags.","inputSchema":{"type":"object","properties":{"enabled":{"type":"boolean"},"monthlyCap":{"type":"number"},"createThemeTags":{"type":"boolean"}}}},
@@ -6838,6 +7170,29 @@ async function handleTool(name, args) {
       return await rpc('conversation_search', args);
 
     // ── Workflows ──────────────────────────────────────────────────────────
+    case 'workflow_schedule_resolve':
+      return await tolerant(() => messagingGet(buildResolvePath(args)));
+
+    case 'workflow_schedule_timeline':
+      return await tolerant(() => messagingGet(buildTimelinePath(args)));
+
+    case 'workflow_schedule_validate':
+      return await tolerant(() => messagingPost(VALIDATE_PATH, buildValidateBody(args)));
+
+    case 'workflow_schedule_banner':
+      return await tolerant(() => messagingGet(buildBannerPath(args)));
+
+    case 'workflow_schedule_override_list':
+      return await tolerant(() => messagingGet(buildOverrideListPath(args)));
+
+    case 'workflow_schedule_override_delete':
+      return await tolerant(async () => { await messagingDel(`${OVERRIDE_PATH}/${args.id}`); return { success: true, deleted: args.id }; });
+
+    case 'workflow_schedule_override_save':
+      return await tolerant(() => args.id
+        ? messagingPut(`${OVERRIDE_PATH}/${args.id}`, buildOverrideBody(args))
+        : messagingPost(OVERRIDE_PATH, buildOverrideBody(args)));
+
     case 'workflow_list':
       return await rpc('workflow_list', args);
 
@@ -7358,6 +7713,20 @@ reply: ${r?.reply}`;
       return `Sent to Teams webhook "${webhook.name}".`;
     }
 
+    case 'visitor_link_get_settings':
+      return await messagingGet('/SiteSettings/visitor-linking');
+
+    case 'visitor_link_set_settings':
+      return await messagingPut('/SiteSettings/visitor-linking', validateSettingsArgs({ enabled: args.enabled, ttlMinutes: args.ttlMinutes }));
+
+    case 'visitor_link_diagnose': {
+      const settings = await messagingGet('/SiteSettings/visitor-linking');
+      return diagnoseLink({ token: args.token, settings });
+    }
+
+    case 'visitor_link_resolve':
+      return await messagingPost('/api/v1/visitor-links/resolve', { token: args.token });
+
     case 'teams_push_settings_get':
       return await api('GET', '/TeamsBot/PushSettings');
 
@@ -9568,6 +9937,7 @@ reply: ${r?.reply}`;
         weekly_brief: 'weekly-brief', weekly_brief_send_test: 'weekly-brief/send-test',
         repeat_contact: 'repeat-contact', demand_coverage: 'demand-coverage', bot_containment: 'bot-containment',
         effort_index: 'effort-index', promise_ledger: 'promise-ledger', new_agent_ramp: 'new-agent-ramp',
+        bonus_insights: 'bonus', operations_briefing: 'operations-briefing', entitled: 'entitled',
       };
       if (args.report === 'promise_dismiss') {
         if (!args.promiseId) throw new Error('promiseId is required for promise_dismiss');
@@ -9600,11 +9970,15 @@ reply: ${r?.reply}`;
         if (f > t) throw new Error('from must be on or before to');
         return JSON.stringify(await messagingPost('/api/enterprise-reports/year-in-review', { from: midnightIso(f), to: midnightIso(addDays(t, 1)) }), null, 2);
       }
-      const seg = ER_PATHS[args.report];
+      let seg = ER_PATHS[args.report];
       if (!seg) throw new Error('report must be one of: ' + Object.keys(ER_PATHS).join(', ') + ', promise_dismiss, year_in_review');
+      if (args.report === 'bonus_insights') {
+        if (!args.name) throw new Error('name is required for bonus_insights (coverage_gap|next_best_fix|escalation_risk|skill_gap_matrix|handle_quality_outliers|abandon_causes)');
+        seg = 'bonus/' + encodeURIComponent(String(args.name).replace(/-/g, '_'));
+      }
       if (args.report === 'weekly_brief_send_test') return JSON.stringify(await messagingPost('/api/enterprise-reports/' + seg, {}), null, 2);
       const qs = new URLSearchParams();
-      for (const k of ['from', 'to', 'groupBy', 'deploymentId', 'teamId', 'threshold', 'perAgent', 'limit', 'days', 'windowDays', 'weeks', 'handleMinutes', 'maxConcurrent', 'timeZone', 'lowScore', 'includeDemo']) {
+      for (const k of ['from', 'to', 'groupBy', 'deploymentId', 'teamId', 'threshold', 'perAgent', 'limit', 'days', 'windowDays', 'weeks', 'handleMinutes', 'maxConcurrent', 'timeZone', 'lowScore', 'includeDemo', 'narrative', 'minutesPerReview', 'hourlyCost', 'deflectionPct', 'costPerChat', 'waitMinutes']) {
         if (args[k] != null && args[k] !== '') qs.set(k, String(args[k]));
       }
       const q = qs.toString();
@@ -9803,6 +10177,15 @@ reply: ${r?.reply}`;
       return `✓ AI Video Avatar updated for site ${args.siteId}. Provider: ${res.providerSlug}, enabled: ${res.enabled}, maxAvatarMinutesPerMonth: ${res.maxAvatarMinutesPerMonth ?? 'n/a'}, maxAvatarTtsChars: ${res.maxAvatarTtsChars ?? 'n/a'}`;
     }
 
+    case 'apple_pay_preset_list':
+      return JSON.stringify(await messagingRequest('GET', `/ApplePayPresetOrders${args.activeOnly ? '?activeOnly=true' : ''}`), null, 2);
+    case 'apple_pay_preset_create':
+      return JSON.stringify(await messagingRequest('POST', '/ApplePayPresetOrders', applePayPresetBody(args)), null, 2);
+    case 'apple_pay_preset_update':
+      return JSON.stringify(await messagingRequest('PUT', `/ApplePayPresetOrders/${applePayPresetId(args.id)}`, applePayPresetBody(args)), null, 2);
+    case 'apple_pay_preset_delete':
+      return JSON.stringify(await messagingRequest('DELETE', `/ApplePayPresetOrders/${applePayPresetId(args.id)}`), null, 2);
+
     case 'avatar_list_library':
       return JSON.stringify(await messagingRequest('GET', `/avatar/library${args.kind ? `?kind=${encodeURIComponent(args.kind)}` : ''}`), null, 2);
     case 'avatar_list_personalities':
@@ -10556,6 +10939,10 @@ reply: ${r?.reply}`;
         ? `Embed key exists but the SuiteApp is not connected (last polled ${d.lastPolledAt}, outside the connected window).`
         : 'Embed key exists but the SuiteApp has not polled yet.';
     }
+    case 'netsuite_rollback_auth': {
+      const r = await messagingPost('/NetSuite/Auth/RollbackAuthType', { id: args.configId });
+      return `Config ${r?.id ?? args.configId} switched back to ${r?.authType ?? 'oauth1'}. Run a connection test to confirm.`;
+    }
 
     case 'netsuite_m2m_init': {
       const r = await messagingPost('/NetSuite/M2M/Init', { id: args.configId ?? null, company: args.company, displayName: args.displayName });
@@ -10947,6 +11334,31 @@ ${JSON.stringify(result, null, 2)}`;
     }
 
     // ── Stripe discount grants ────────────────────────────────────────────────────
+    case 'sign_versions_list': {
+      const r = await api('GET', `/api/Contract/${args.contractId}/versions`);
+      const rows = r.versions || [];
+      if (!rows.length) return `Contract ${args.contractId}: no document versions yet.`;
+      return rows.map(v => `v${v.versionNumber} ${String(v.uploadedAt||'').slice(0,19)} ${v.uploadedBy||'-'} ${v.fileName||'-'} ${v.pageCount??'?'}p sha256:${String(v.sha256||'').slice(0,12)}${v.note ? ' note: '+v.note : ''}`).join('\n');
+    }
+
+    case 'sign_versions_diff': {
+      const r = await api('GET', `/api/Contract/${args.contractId}/diff?from=${args.from}&to=${args.to}`);
+      if (r.identical) return `v${r.from} and v${r.to} are byte-identical.`;
+      return (r.blocks || []).map(b => [...(b.removed||[]).map(x => '- '+x), ...(b.added||[]).map(x => '+ '+x)].join('\n')).join('\n\n') || 'No text differences.';
+    }
+
+    case 'sign_versions_upload': {
+      const buf = _readFileSync(args.filePath);
+      if (buf.subarray(0, 5).toString('latin1') !== '%PDF-') throw new Error('Only PDF files can be uploaded as a contract version.');
+      const form = new FormData();
+      form.append('file', new Blob([buf], { type: 'application/pdf' }), String(args.filePath).split(/[\/]/).pop());
+      if (args.note) form.append('note', args.note);
+      const res = await fetch(`${API_BASE}/api/Contract/${args.contractId}/document`, { method: 'POST', headers: { Authorization: authHeader() }, body: form, signal: AbortSignal.timeout(60000) });
+      const t = await res.text();
+      if (!res.ok) throw new Error(`Upload failed ${res.status}: ${t.slice(0,300)} (new versions only while draft; after send/sign void and re-send)`);
+      return `Uploaded new version for contract ${args.contractId}.`;
+    }
+
     case 'coupon_grant_list': {
       const qs = new URLSearchParams();
       if (args.siteId !== undefined) qs.set('siteId', String(args.siteId));
@@ -11049,6 +11461,42 @@ ${JSON.stringify(result, null, 2)}`;
       return `✅ Billing contact ${args.id} removed.`;
     }
 
+    case 'usage_alerts': {
+      const r = await messagingApi('/Usage/alerts');
+      if (!r.alerts?.length) return 'No plan-limit alerts. Every metered resource is under its warning threshold.';
+      return r.alerts.map(a => `[${a.level.toUpperCase()}] ${a.displayName}: ${a.current} of ${a.limit} (${a.percent}%)${a.softLimit ? ' - overage is billed' : ''}`).join(' | ');
+    }
+    case 'billing_notify_settings_get': {
+      const all = await api('GET', '/api/BillingNotifications/settings');
+      return Object.entries(all).map(([k, v]) => `${k}: ${v ?? '(not set: code default)'}`).join('\n');
+    }
+
+    case 'billing_notify_setting_set': {
+      await api('PUT', `/api/BillingNotifications/settings/${encodeURIComponent(args.key)}`, { value: args.value });
+      return `✅ ${args.key} set to ${args.value}.`;
+    }
+
+    case 'billing_receipt_overrides_set': {
+      // The API replaces all three channels, so keep the ones the caller did not pass.
+      const sub = await api('GET', `/api/BillingSubscription/${args.subscriptionId}`);
+      const res = await api('PUT', `/api/BillingNotifications/subscriptions/${args.subscriptionId}/receipts`, {
+        card:  args.card  ?? sub.receiptCardOverride  ?? null,
+        ach:   args.ach   ?? sub.receiptAchOverride   ?? null,
+        other: args.other ?? sub.receiptOtherOverride ?? null,
+      });
+      return `✅ Subscription ${res.id} receipts: card=${res.card ?? 'inherit'} ach=${res.ach ?? 'inherit'} other=${res.other ?? 'inherit'}.`;
+    }
+
+    case 'billing_digest_send_now': {
+      const res = await api('POST', '/api/BillingNotifications/digest/send-now', {});
+      return `✅ Digest sent to ${res.recipients.join(', ')}: ${res.subject}`;
+    }
+
+    case 'billing_receipts_run_now': {
+      const res = await api('POST', '/api/BillingNotifications/receipts/run-now', {});
+      return `✅ Receipts run: ${res.summary}`;
+    }
+
     case 'billing_plan_status': {
       const s = await api('GET', '/api/BillingPayment/plan-status');
       const lines = [`Site ${s.siteId} — Subscription Status`];
@@ -11220,6 +11668,32 @@ ${JSON.stringify(result, null, 2)}`;
       return `✅ Site ${args.siteId}: ${args.featureKey} = ${args.value}${args.reason ? ` (${args.reason})` : ''}`;
     }
 
+    case 'entitlement_trial_get': {
+      if (!args.siteId) throw new Error('siteId is required');
+      return JSON.stringify(await api('GET', `/Entitlements/${args.siteId}/trial`), null, 2);
+    }
+
+    case 'entitlement_trial_recommend': {
+      if (!args.siteId) throw new Error('siteId is required');
+      return JSON.stringify(await api('GET', `/Entitlements/${args.siteId}/trial/recommendation`), null, 2);
+    }
+
+    case 'entitlement_trial_grant': {
+      if (!args.siteId) throw new Error('siteId is required');
+      if (!args.featureKey) throw new Error('featureKey is required');
+      if (!args.reason) throw new Error('reason is required');
+      const res = await api('POST', `/Entitlements/${args.siteId}/trial/grant`, { featureKey: args.featureKey, reason: args.reason });
+      return `Site ${args.siteId}: ${res.featureKey} granted for the trial (${res.state}).`;
+    }
+
+    case 'entitlement_trial_set_limit': {
+      if (!args.siteId) throw new Error('siteId is required');
+      if (!Number.isInteger(args.value) || args.value < 0) throw new Error('value must be a whole number >= 0');
+      if (!args.key || !args.reason) throw new Error('key and reason are required');
+      const res = await api('POST', `/Entitlements/${args.siteId}/trial/limit`, { key: args.key, value: args.value, reason: args.reason });
+      return `Site ${args.siteId}: ${res.key} ${res.old} -> ${res.value}.`;
+    }
+
     case 'entitlement_remove_override': {
       if (!args.siteId) throw new Error('siteId is required');
       if (!args.featureKey) throw new Error('featureKey is required');
@@ -12058,7 +12532,12 @@ ${JSON.stringify(result, null, 2)}`;
       if (a === 'create') return await messagingPost('/api/admin/QualityQa/rubrics', args.rubric ?? {});
       if (a === 'update') return await messagingPut('/api/admin/QualityQa/rubrics/' + args.id, args.rubric ?? {});
       if (a === 'delete') return await messagingDel('/api/admin/QualityQa/rubrics/' + args.id);
-      throw new Error('action must be list|get|default|create|update|delete');
+      if (a === 'starter') return await messagingPost('/api/admin/QualityQa/rubrics/starter', {});
+      if (a === 'clone') return await messagingPost('/api/admin/QualityQa/rubrics/' + args.id + '/clone', args.rubric ?? {});
+      if (a === 'activate') return await messagingPut('/api/admin/QualityQa/rubrics/' + args.id, { isActive: true });
+      if (a === 'deactivate') return await messagingPut('/api/admin/QualityQa/rubrics/' + args.id, { isActive: false });
+      if (a === 'rescore') return await messagingPost('/api/admin/QualityQa/rescore?days=' + encodeURIComponent(args.days ?? 30) + '&limit=' + encodeURIComponent(args.limit ?? 200), {});
+      throw new Error('action must be list|get|default|starter|create|update|clone|activate|deactivate|rescore|delete');
     }
     case 'qa_low_scores': {
       const qs = new URLSearchParams({ days: String(args.days ?? 30), skip: String(args.skip ?? 0), take: String(args.take ?? 50) });
@@ -12128,7 +12607,7 @@ const PROMPTS = [
 ];
 
 const server = new Server(
-  { name: 'velaro', version: '0.4.0' },
+  { name: 'velaro', version: JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), 'package.json'), 'utf8')).version },
   { capabilities: { tools: {}, prompts: {} } }
 );
 

package/server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/velaro/velaro-admin",
     "source": "github"
   },
-  "version": "0.6.0",
+  "version": "1.0.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@velaro/mcp-server",
-      "version": "0.6.0",
+      "version": "1.0.0",
       "transport": {
         "type": "stdio"
       },

package/workflow-schedule.js

@@ -0,0 +1,70 @@
+// Shared helpers for the workflow schedule-priority tools (velaro MCP). Messaging owns the REST
+// endpoints under /Workflows/schedule/*; the site always comes from auth, never a parameter.
+// An older messaging without the endpoints answers 404/501 -> we return a friendly message.
+
+export const SCHEDULE_NOT_AVAILABLE = "Workflow scheduling is not available on this site's version.";
+
+export const SCHEDULE_ACTIONS = { SwitchWorkflow: 3 };
+
+export function buildResolvePath({ trigger, channel, at, tz } = {}) {
+  const q = new URLSearchParams();
+  if (trigger) q.set('trigger', trigger);
+  if (channel) q.set('channel', channel);
+  if (at) q.set('at', at);
+  if (tz) q.set('tz', tz);
+  return `/Workflows/schedule/resolve?${q}`;
+}
+
+export function buildTimelinePath({ from, to, trigger, channel } = {}) {
+  const q = new URLSearchParams();
+  if (from) q.set('from', from);
+  if (to) q.set('to', to);
+  if (trigger) q.set('trigger', trigger);
+  if (channel) q.set('channel', channel);
+  return `/Workflows/schedule/timeline?${q}`;
+}
+
+export const VALIDATE_PATH = '/Workflows/schedule/validate';
+export const BANNER_PATH = '/Workflows/schedule/banner';
+export const OVERRIDE_PATH = '/ScheduleOverride';
+
+// Normalizes the action to the int messaging expects (accepts 'SwitchWorkflow' or 3).
+export function buildOverrideBody(args = {}) {
+  const { action, targetWorkflowId, ...rest } = args;
+  const body = { ...rest };
+  if (action !== undefined) body.action = typeof action === 'string' && action in SCHEDULE_ACTIONS ? SCHEDULE_ACTIONS[action] : action;
+  if (targetWorkflowId !== undefined) body.targetWorkflowId = targetWorkflowId;
+  return body;
+}
+
+// Messaging's POST /Workflows/schedule/validate takes { trigger, channel, override } (one draft override).
+export function buildValidateBody({ trigger, channel, override } = {}) {
+  const body = { trigger: trigger || 'conversation_opened' };
+  if (channel) body.channel = channel;
+  if (override) body.override = buildOverrideBody(override);
+  return body;
+}
+
+export function buildBannerPath({ trigger, channel } = {}) {
+  const q = new URLSearchParams();
+  if (trigger) q.set('trigger', trigger);
+  if (channel) q.set('channel', channel);
+  return `${BANNER_PATH}?${q}`;
+}
+
+export function buildOverrideListPath({ action } = {}) {
+  if (action === undefined || action === '') return OVERRIDE_PATH;
+  const n = typeof action === 'string' && action in SCHEDULE_ACTIONS ? SCHEDULE_ACTIONS[action] : action;
+  return `${OVERRIDE_PATH}?action=${encodeURIComponent(n)}`;
+}
+
+// Runs fn(); a 404/501 (error message contains "-> 404:" / "-> 501:" or err.status) maps to the friendly string.
+export async function tolerant(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    const status = err?.status ?? Number(/->\s*(\d{3})/.exec(err?.message ?? '')?.[1]);
+    if (status === 404 || status === 501) return SCHEDULE_NOT_AVAILABLE;
+    throw err;
+  }
+}