@velaro/mcp-server 2.0.2 → 2.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "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/parity/agent-crm-identity.customer.js

@@ -0,0 +1,87 @@
+// MCP parity for `velaro agent crm-identity` (cli/lib/commands/agent.js). Backend: velaro-messaging
+// api/v1/AgentCrmIdentities (administrator key). Site from the credential, never an argument.
+// A CRM login (NetSuite / Dynamics 365 / HubSpot user) linked to a Velaro agent makes the CRM call pop show that
+// agent's calls and makes calls logged to the CRM owned by that CRM user.
+
+const PROVIDERS = ['netsuite', 'dynamics', 'hubspot', 'salesforce', 'zoho', 'other'];
+
+const agentProps = {
+  workspaceUserId: { type: 'number', description: 'Velaro agent id (WorkspaceUser id). Use this or agentEmail.' },
+  agentEmail: { type: 'string', description: 'Velaro agent email. Use this or workspaceUserId.' },
+};
+
+export const tools = [
+  {
+    name: 'agent_crm_identity_list',
+    description: 'List the CRM logins linked to your agents (all agents, or one agent). Each row: CRM, login email, CRM user id, agent, and whether it was linked manually or automatically.',
+    inputSchema: { type: 'object', properties: { workspaceUserId: agentProps.workspaceUserId } },
+  },
+  {
+    name: 'agent_crm_identity_add',
+    description: 'Link a CRM login to a Velaro agent so the CRM call pop shows that agent\'s calls and calls logged to the CRM are owned by that CRM user. Give the login email, the CRM user id (NetSuite employee id, Dynamics systemuserid, HubSpot owner id), or both.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ...agentProps,
+        provider: { type: 'string', enum: PROVIDERS, description: 'Which CRM the login belongs to.' },
+        loginEmail: { type: 'string', description: 'The CRM login email.' },
+        crmUserId: { type: 'string', description: 'The CRM user id.' },
+      },
+      required: ['provider'],
+    },
+  },
+  {
+    name: 'agent_crm_identity_remove',
+    description: 'Unlink a CRM login from its agent (id from agent_crm_identity_list).',
+    inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'CRM login link id.' } }, required: ['id'] },
+  },
+  {
+    name: 'agent_crm_identity_list_unlinked',
+    description: 'List CRM logins that opened the Velaro call pop inside your CRM but are linked to no agent (they never see a call until linked).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'agent_crm_identity_link',
+    description: 'Link one unlinked CRM login (id from agent_crm_identity_list_unlinked) to a Velaro agent.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Unlinked CRM login id.' }, ...agentProps },
+      required: ['id'],
+    },
+  },
+];
+
+function agentBody(a) {
+  if (!a.workspaceUserId && !a.agentEmail) throw new Error('Pass workspaceUserId or agentEmail.');
+  return { workspaceUserId: a.workspaceUserId ?? null, agentEmail: a.agentEmail ?? null };
+}
+
+export const handlers = {
+  agent_crm_identity_list: async (a, ctx) => {
+    const q = a.workspaceUserId ? `?workspaceUserId=${encodeURIComponent(a.workspaceUserId)}` : '';
+    const r = await ctx.messagingGet(`/api/v1/AgentCrmIdentities${q}`);
+    return { identities: r?.data?.identities ?? [] };
+  },
+  agent_crm_identity_add: async (a, ctx) => {
+    if (!a.loginEmail && !a.crmUserId) throw new Error('Pass loginEmail, crmUserId, or both.');
+    const r = await ctx.messagingPost('/api/v1/AgentCrmIdentities', {
+      ...agentBody(a),
+      provider: a.provider,
+      loginEmail: a.loginEmail ?? null,
+      crmUserId: a.crmUserId ?? null,
+    });
+    return r?.data ?? r;
+  },
+  agent_crm_identity_remove: async (a, ctx) => {
+    await ctx.messagingDel(`/api/v1/AgentCrmIdentities/${encodeURIComponent(a.id)}`);
+    return { removed: true, id: a.id };
+  },
+  agent_crm_identity_list_unlinked: async (_a, ctx) => {
+    const r = await ctx.messagingGet('/api/v1/AgentCrmIdentities/unlinked-logins');
+    return { logins: r?.data?.logins ?? [] };
+  },
+  agent_crm_identity_link: async (a, ctx) => {
+    const r = await ctx.messagingPost(`/api/v1/AgentCrmIdentities/unlinked-logins/${encodeURIComponent(a.id)}/link`, agentBody(a));
+    return r?.data ?? r;
+  },
+};

package/server.js

@@ -967,6 +967,7 @@ Key node shapes:
 • transferToAI:   { type:"action", actionType:"transferToAI", aiConfigId:N }
 • selectPreChat:  { type:"action", actionType:"selectPreChat", surveyId:N, surveyCompact:true|false|null, child:N }
   surveyCompact (optional tri-state): null/omitted = follow the survey's own compactMode, true = compact, false = regular.
+• redirectToUrl:  { type:"action", actionType:"redirectToUrl", redirectUrl:"https://host/path" | "//host/path", child:N }   (chat_button_clicked only: browser goes to the page instead of opening chat; http/https only; use on an Unavailable branch)
 • sendSurvey:     { type:"action", actionType:"sendSurvey", sendSurveyId:N, surveyDeliveryMode:"conversational"|"form", closeAfterSurvey:true|false, child:N }
   closeAfterSurvey (optional, default false): when true the chat closes once the visitor completes the survey (use for Unavailable/after-hours surveys that replace a live chat). Omit to keep the old behaviour.
   AI follow-up suggestions ("AI mode"): add suggestFollowUps:true|false (omit = use the account default, set via ai_followups_site_set), suggestFollowUpCount:2-4, suggestFollowUpInstruction:"<=300 chars". After each web-chat bot reply the bot offers short tappable follow-up replies; typing stays available.
@@ -2407,6 +2408,17 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: [],
     },
   },
+  {
+    name: 'outbound_activity_volume',
+    description: 'Daily outbound email volume for this account over the last N days (1-90, default 30), split sent vs failed, for campaign (sequence) and broadcast sends. Transactional mail is reported as NOT COUNTED until messaging exposes a daily aggregate. Site scoping is enforced server-side.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'number', description: 'Window in days, 1-90 (default 30)' },
+      },
+      required: [],
+    },
+  },
   {
     name: 'outbound_activity_for_contact',
     description: 'Every email this account has sent to ONE specific address, across transactional, sequence and broadcast sends — the "what have we sent this customer" answer that previously required checking three separate screens. The email address is REQUIRED and matched exactly; it is never optional, because an omitted address must not widen this into a site-wide listing.',
@@ -4063,6 +4075,77 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['contactId'],
     },
   },
+  // -- Current Sales (time-boxed bot override Q&A + per-customer coupons). Site comes from the credential, never an arg. --
+  {
+    name: 'site_sale_list',
+    description: "List this site's Current Sales (temporary sales or discounts the bot answers about deterministically until they end).",
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'site_sale_create',
+    description: 'Create a Current Sale: while active, the bot answers sales, discount and coupon questions from this definition and can issue per-customer coupons (Magento sites mint a real cart price rule). It stops at the end time. Times are UTC; convert from Pacific.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:             { type: 'string', description: 'Sale name shown to customers' },
+        description:      { type: 'string', description: 'Short description the bot can quote' },
+        appliesTo:        { type: 'string', enum: ['all','category','products'], description: 'Scope of the sale' },
+        appliesToValue:   { type: 'string', description: 'Category name or comma-separated product identifiers when appliesTo is category or products' },
+        discountType:     { type: 'string', enum: ['percentage','fixed_amount','free_shipping'], description: 'Kind of discount' },
+        discountValue:    { type: 'number', description: 'Percent or fixed amount (ignored for free_shipping)' },
+        startsAtUtc:      { type: 'string', description: 'ISO 8601 start time in UTC (convert from Pacific)' },
+        endsAtUtc:        { type: 'string', description: 'ISO 8601 end time in UTC; the sale stops answering at this time' },
+        couponCode:       { type: 'string', description: 'Optional shared coupon code' },
+        autoGenerateCoupons:   { type: 'boolean', description: 'Let the bot issue a unique coupon per customer' },
+        maxCouponsPerCustomer: { type: 'number', description: 'Max coupons the bot issues to one customer' },
+        couponUsageLimit:      { type: 'number', description: 'Times each coupon can be used' },
+        couponExpiresHours:    { type: 'number', description: 'Hours before an issued coupon expires' },
+      },
+      required: ['name', 'discountType', 'startsAtUtc', 'endsAtUtc'],
+    },
+  },
+  {
+    name: 'site_sale_update',
+    description: 'Update a Current Sale by id. Omit a field to leave it unchanged.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Sale ID from site_sale_list. Required.' },
+        name:             { type: 'string', description: 'Sale name shown to customers' },
+        description:      { type: 'string', description: 'Short description the bot can quote' },
+        appliesTo:        { type: 'string', enum: ['all','category','products'], description: 'Scope of the sale' },
+        appliesToValue:   { type: 'string', description: 'Category name or comma-separated product identifiers when appliesTo is category or products' },
+        discountType:     { type: 'string', enum: ['percentage','fixed_amount','free_shipping'], description: 'Kind of discount' },
+        discountValue:    { type: 'number', description: 'Percent or fixed amount (ignored for free_shipping)' },
+        startsAtUtc:      { type: 'string', description: 'ISO 8601 start time in UTC (convert from Pacific)' },
+        endsAtUtc:        { type: 'string', description: 'ISO 8601 end time in UTC; the sale stops answering at this time' },
+        couponCode:       { type: 'string', description: 'Optional shared coupon code' },
+        autoGenerateCoupons:   { type: 'boolean', description: 'Let the bot issue a unique coupon per customer' },
+        maxCouponsPerCustomer: { type: 'number', description: 'Max coupons the bot issues to one customer' },
+        couponUsageLimit:      { type: 'number', description: 'Times each coupon can be used' },
+        couponExpiresHours:    { type: 'number', description: 'Hours before an issued coupon expires' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'site_sale_end',
+    description: 'End a Current Sale now. The bot stops answering from it immediately.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Sale ID. Required.' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'site_sale_delete',
+    description: 'Delete a Current Sale by id.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Sale ID. Required.' } },
+      required: ['id'],
+    },
+  },
   {
     name: 'pickup_get_config',
     description: 'Get this site\'s Pickup & Reminder Texting configuration (default cadence, max reminders, message template, enabled state, quiet-hours override). Returns null/404 if no config has been created yet -- use pickup_update_config to create one.',
@@ -6999,6 +7082,28 @@ reply: ${r?.reply}`;
       return JSON.stringify(r, null, 2);
     }
 
+    // ── Unified Outbound Activity: daily volume ──────────────────────────
+    case 'outbound_activity_volume': {
+      const days = Math.min(90, Math.max(1, Number(args.days ?? 30)));
+      const v = await api('GET', `/Marketing/OutboundActivity/Volume?days=${days}`);
+      const byDay = new Map();
+      for (const b of v?.buckets ?? []) {
+        const d = byDay.get(b.date) ?? { sent: 0, failed: 0 };
+        if (b.status === 'Failed') d.failed += b.count;
+        else if (b.status === 'Sent') d.sent += b.count;
+        byDay.set(b.date, d);
+      }
+      const lines = [`=== Outbound volume, last ${days} days (campaign + broadcast) ===`];
+      if (v?.degradedSources?.length) {
+        lines.push(`  ! NOT COUNTED: ${v.degradedSources.join(', ')}`);
+      }
+      for (const [date, d] of [...byDay.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        lines.push(`  ${date}  sent ${d.sent}  failed ${d.failed}`);
+      }
+      if (!byDay.size) lines.push('  No campaign or broadcast sends in this window.');
+      return lines.join('\n');
+    }
+
     // ── Unified Outbound Activity ──────────────────────────────────────────
     case 'outbound_activity_list':
     case 'outbound_activity_for_contact': {
@@ -8341,6 +8446,66 @@ ${JSON.stringify(result, null, 2)}`;
       return JSON.stringify(history, null, 2);
     }
 
+    case 'site_sale_list': {
+      const result = await messagingGet('/SiteSales');
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'site_sale_create': {
+      if (!args.name || !args.discountType || !args.startsAtUtc || !args.endsAtUtc) return 'name, discountType, startsAtUtc and endsAtUtc are required.';
+      // Field names must match the SiteSales request on the messaging API exactly (undefined is dropped by JSON).
+      const body = {
+        name: args.name,
+        description: args.description,
+        appliesTo: args.appliesTo,
+        appliesToValue: args.appliesToValue,
+        discountType: args.discountType,
+        discountValue: args.discountValue,
+        startsAtUtc: args.startsAtUtc,
+        endsAtUtc: args.endsAtUtc,
+        couponCode: args.couponCode,
+        autoGenerateCoupons: args.autoGenerateCoupons,
+        maxCouponsPerCustomer: args.maxCouponsPerCustomer,
+        couponUsageLimit: args.couponUsageLimit,
+        couponExpiresHours: args.couponExpiresHours,
+      };
+      const result = await messagingPost('/SiteSales', body);
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'site_sale_update': {
+      if (args.id == null) return 'id is required.';
+      const body = {
+        name: args.name,
+        description: args.description,
+        appliesTo: args.appliesTo,
+        appliesToValue: args.appliesToValue,
+        discountType: args.discountType,
+        discountValue: args.discountValue,
+        startsAtUtc: args.startsAtUtc,
+        endsAtUtc: args.endsAtUtc,
+        couponCode: args.couponCode,
+        autoGenerateCoupons: args.autoGenerateCoupons,
+        maxCouponsPerCustomer: args.maxCouponsPerCustomer,
+        couponUsageLimit: args.couponUsageLimit,
+        couponExpiresHours: args.couponExpiresHours,
+      };
+      const result = await messagingPut(`/SiteSales/${encodeURIComponent(args.id)}`, body);
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'site_sale_end': {
+      if (args.id == null) return 'id is required.';
+      const result = await messagingPost(`/SiteSales/${encodeURIComponent(args.id)}/end`, {});
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'site_sale_delete': {
+      if (args.id == null) return 'id is required.';
+      const result = await messagingDel(`/SiteSales/${encodeURIComponent(args.id)}`);
+      return JSON.stringify(result, null, 2);
+    }
+
     case 'pickup_get_config': {
       const config = await messagingGet('/PickupNotifications/Config').catch(err => {
         if (String(err.message).includes(' 404')) return null;

package/tool-annotations.js

@@ -25,6 +25,7 @@ const MUTATING = new Set([
   'routing_team_update_config', 'pickup_update_config', 'payment_recovery_update_config',
   'recruiting_sync_jobs', 'ai_config_set_reply_format', 'magento_set_sidebar_fields',
   'zoom_phone_set_config',
+  'site_sale_create', 'site_sale_update', 'site_sale_end',
 ]);
 
 // Names that look like writes but only read (checked before the write rules).
@@ -56,7 +57,7 @@ const READ_ONLY_EXPLICIT = new Set([
 // Write tools that are additive even though their name carries a destructive-looking token.
 const NON_DESTRUCTIVE_EXPLICIT = new Set([
   'safety_settings_test', 'safety_need_help', 'canned_learning_record_edit', 'netsuite_suiteapp_download',
-  'chat_topics_reclassify',
+  'chat_topics_reclassify', 'agent_crm_identity_link',
 ]);
 
 const DESTRUCTIVE_TOKENS = new Set([