@velaro/mcp-server 2.0.118 → 2.0.120

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -25,3 +25,29 @@ export function buildMultiTabUpdateFields(current, mode) {
25
25
  languageConfig: JSON.stringify(current.languageConfig ?? {}),
26
26
  };
27
27
  }
28
+
29
+ // Per-chat-window "visitors can email themselves a transcript" (MessengerStyleConfig.EnableEmailTranscriptButton).
30
+ // Global default is ON; an absent key (null) follows it. A transcript requested while a chat is still open is
31
+ // emailed in full once when the chat ends.
32
+ /** Returns true | false | null (follow the global default, on). Throws on anything else. */
33
+ export function normalizeEmailTranscript(raw) {
34
+ if (raw === null || raw === undefined) return null;
35
+ if (typeof raw === 'boolean') return raw;
36
+ const v = String(raw).trim().toLowerCase();
37
+ if (['default', 'follow-default', 'null', ''].includes(v)) return null;
38
+ if (['on', 'true', 'yes', '1'].includes(v)) return true;
39
+ if (['off', 'false', 'no', '0'].includes(v)) return false;
40
+ throw new Error('enableEmailTranscriptButton must be on, off or default (follows the global default, on).');
41
+ }
42
+
43
+ /** Fields of the update form for a chat window with only enableEmailTranscriptButton changed. */
44
+ export function buildEmailTranscriptUpdateFields(current, value) {
45
+ if (!current || typeof current !== 'object') throw new Error('chat window not found');
46
+ const styleConfig = { ...(current.styleConfig ?? {}) };
47
+ if (value === null) delete styleConfig.enableEmailTranscriptButton; else styleConfig.enableEmailTranscriptButton = value;
48
+ return {
49
+ name: current.name ?? '',
50
+ styleConfig: JSON.stringify(styleConfig),
51
+ languageConfig: JSON.stringify(current.languageConfig ?? {}),
52
+ };
53
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/mcp-server",
3
- "version": "2.0.118",
3
+ "version": "2.0.120",
4
4
  "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro account: KB, workflows, bots, conversations, contacts, routing, and more.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -0,0 +1,152 @@
1
+ // MCP parity for `velaro crm-doc-template` and `velaro crm-deal-doc` (cli/lib/commands/crm-document-templates.js).
2
+ // Backend: velaro-messaging CrmDocumentTemplates and CrmDealDocuments controllers
3
+ // (docs/architecture/crm-studio-program.md, feature 20). Site from the credential, never an argument.
4
+ // Binary downloads (PDF, signed copy) are not returned here: use the CLI (velaro crm-deal-doc download / signed --out).
5
+
6
+ const KINDS = ['quote', 'proposal', 'agreement'];
7
+
8
+ const data = (r) => (r && typeof r === 'object' && 'data' in r ? r.data : r);
9
+ const q = (o) => {
10
+ const p = Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${k}=${encodeURIComponent(v)}`);
11
+ return p.length ? `?${p.join('&')}` : '';
12
+ };
13
+ const id = (v) => encodeURIComponent(v);
14
+ const num = { type: 'number' };
15
+
16
+ export const tools = [
17
+ {
18
+ name: 'crm_doc_template_list',
19
+ description: 'List the CRM document templates (quote, proposal, agreement) of this account, optionally by kind. Part of the CRM Studio package (see your plan).',
20
+ inputSchema: { type: 'object', properties: { kind: { type: 'string', enum: KINDS } } },
21
+ },
22
+ {
23
+ name: 'crm_doc_template_get',
24
+ description: 'Get one document template with its HTML body and version.',
25
+ inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
26
+ },
27
+ {
28
+ name: 'crm_doc_template_fields',
29
+ description: 'List the merge fields a template may use (deal, contact, company, line items, today, sender, and this account\'s custom fields).',
30
+ inputSchema: { type: 'object', properties: {} },
31
+ },
32
+ {
33
+ name: 'crm_doc_template_validate',
34
+ description: 'Check a template body for unknown or malformed merge fields without saving it. Returns valid, used, unknown and malformed.',
35
+ inputSchema: { type: 'object', properties: { bodyHtml: { type: 'string' } }, required: ['bodyHtml'] },
36
+ },
37
+ {
38
+ name: 'crm_doc_template_create',
39
+ description: 'Create a document template. Manager or Administrator only. Unknown merge fields are rejected on save.',
40
+ inputSchema: { type: 'object', properties: { name: { type: 'string' }, kind: { type: 'string', enum: KINDS }, description: { type: 'string' }, bodyHtml: { type: 'string' } }, required: ['name', 'bodyHtml'] },
41
+ },
42
+ {
43
+ name: 'crm_doc_template_update',
44
+ description: 'Change a document template; only the fields passed change and a new version is saved. Pass expectedVersion to refuse the save if someone else changed it. Manager or Administrator only.',
45
+ inputSchema: { type: 'object', properties: { id: num, name: { type: 'string' }, kind: { type: 'string', enum: KINDS }, description: { type: 'string' }, bodyHtml: { type: 'string' }, expectedVersion: num }, required: ['id'] },
46
+ },
47
+ {
48
+ name: 'crm_doc_template_archive',
49
+ description: 'Archive a document template (never hard-deleted; documents already made from it are kept). Manager or Administrator only.',
50
+ inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
51
+ },
52
+ {
53
+ name: 'crm_doc_template_versions',
54
+ description: 'List the saved versions of a document template.',
55
+ inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
56
+ },
57
+ {
58
+ name: 'crm_doc_template_restore',
59
+ description: 'Restore an earlier version of a document template; the restore is saved as a new version. Manager or Administrator only.',
60
+ inputSchema: { type: 'object', properties: { id: num, version: num }, required: ['id', 'version'] },
61
+ },
62
+ {
63
+ name: 'crm_deal_doc_preview',
64
+ description: 'Render a template for a deal and return the HTML. Nothing is kept on the deal.',
65
+ inputSchema: { type: 'object', properties: { templateId: num, dealId: num }, required: ['templateId', 'dealId'] },
66
+ },
67
+ {
68
+ name: 'crm_deal_doc_generate',
69
+ description: 'Render a template for a deal, keep the copy as a draft document and save its PDF to the deal attachments.',
70
+ inputSchema: { type: 'object', properties: { templateId: num, dealId: num }, required: ['templateId', 'dealId'] },
71
+ },
72
+ {
73
+ name: 'crm_deal_doc_list',
74
+ description: 'List the documents of a deal with their status (draft, sent, signed, voided, expired).',
75
+ inputSchema: { type: 'object', properties: { dealId: num }, required: ['dealId'] },
76
+ },
77
+ {
78
+ name: 'crm_deal_doc_get',
79
+ description: 'Get one deal document and its signature status.',
80
+ inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
81
+ },
82
+ {
83
+ name: 'crm_deal_doc_download_info',
84
+ description: 'Say where a deal document can be downloaded as PDF or HTML. File downloads are not returned by this tool; use the CLI: velaro crm-deal-doc download <id> --format pdf|html --out <file>.',
85
+ inputSchema: { type: 'object', properties: { id: num, format: { type: 'string', enum: ['pdf', 'html'] } }, required: ['id'] },
86
+ },
87
+ {
88
+ name: 'crm_deal_doc_send',
89
+ description: 'Send a deal document for signature with Velaro Sign. signers is a list of { name, email, order }; with no signers the primary contact of the deal signs. mode is sequential or parallel.',
90
+ inputSchema: {
91
+ type: 'object',
92
+ properties: {
93
+ id: num,
94
+ signers: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string' }, order: num }, required: ['email'] } },
95
+ mode: { type: 'string', enum: ['sequential', 'parallel'] },
96
+ message: { type: 'string' },
97
+ },
98
+ required: ['id'],
99
+ },
100
+ },
101
+ {
102
+ name: 'crm_deal_doc_sync',
103
+ description: 'Pull the latest signature status of a deal document from Velaro Sign; a signed document is saved to the deal with a timeline note.',
104
+ inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
105
+ },
106
+ {
107
+ name: 'crm_deal_doc_void',
108
+ description: 'Void a sent deal document so it can no longer be signed.',
109
+ inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
110
+ },
111
+ {
112
+ name: 'crm_deal_doc_signed_info',
113
+ description: 'Say where the signed PDF of a deal document can be downloaded once signed. The file itself is not returned by this tool; use the CLI: velaro crm-deal-doc signed <id> --out <file>.',
114
+ inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
115
+ },
116
+ ];
117
+
118
+ export const handlers = {
119
+ crm_doc_template_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmDocumentTemplates${q({ kind: a.kind })}`)),
120
+ crm_doc_template_get: async (a, ctx) => data(await ctx.messagingGet(`/CrmDocumentTemplates/${id(a.id)}`)),
121
+ crm_doc_template_fields: async (_a, ctx) => data(await ctx.messagingGet('/CrmDocumentTemplates/merge-fields')),
122
+ crm_doc_template_validate: async (a, ctx) => data(await ctx.messagingPost('/CrmDocumentTemplates/validate', { bodyHtml: a.bodyHtml })),
123
+ crm_doc_template_create: async (a, ctx) => data(await ctx.messagingPost('/CrmDocumentTemplates', { name: a.name, kind: a.kind ?? 'quote', description: a.description ?? '', bodyHtml: a.bodyHtml })),
124
+ crm_doc_template_update: async (a, ctx) => {
125
+ const body = {};
126
+ for (const k of ['name', 'kind', 'description', 'bodyHtml', 'expectedVersion']) if (a[k] !== undefined && a[k] !== null) body[k] = a[k];
127
+ return data(await ctx.messagingPut(`/CrmDocumentTemplates/${id(a.id)}`, body));
128
+ },
129
+ crm_doc_template_archive: async (a, ctx) => data(await ctx.messagingDel(`/CrmDocumentTemplates/${id(a.id)}`)),
130
+ crm_doc_template_versions: async (a, ctx) => data(await ctx.messagingGet(`/CrmDocumentTemplates/${id(a.id)}/versions`)),
131
+ crm_doc_template_restore: async (a, ctx) => data(await ctx.messagingPost(`/CrmDocumentTemplates/${id(a.id)}/versions/${id(a.version)}/restore`, {})),
132
+ crm_deal_doc_preview: async (a, ctx) => data(await ctx.messagingPost('/CrmDealDocuments/render', { templateId: a.templateId, dealId: a.dealId })),
133
+ crm_deal_doc_generate: async (a, ctx) => data(await ctx.messagingPost('/CrmDealDocuments', { templateId: a.templateId, dealId: a.dealId })),
134
+ crm_deal_doc_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmDealDocuments/deal/${id(a.dealId)}`)),
135
+ crm_deal_doc_get: async (a, ctx) => data(await ctx.messagingGet(`/CrmDealDocuments/${id(a.id)}`)),
136
+ crm_deal_doc_download_info: async (a) => ({
137
+ path: `/CrmDealDocuments/${id(a.id)}/${a.format === 'html' ? 'html' : 'pdf'}`,
138
+ note: `The file is not returned here. Run: velaro crm-deal-doc download ${a.id} --format ${a.format === 'html' ? 'html' : 'pdf'} --out <file>`,
139
+ }),
140
+ crm_deal_doc_send: async (a, ctx) => {
141
+ const signers = (a.signers ?? []).map((s, i) => ({ name: s.name ?? String(s.email ?? '').split('@')[0], email: s.email, order: s.order ?? i + 1 }));
142
+ const body = { signers, mode: a.mode ?? 'sequential' };
143
+ if (a.message) body.message = a.message;
144
+ return data(await ctx.messagingPost(`/CrmDealDocuments/${id(a.id)}/send-for-signature`, body));
145
+ },
146
+ crm_deal_doc_sync: async (a, ctx) => data(await ctx.messagingPost(`/CrmDealDocuments/${id(a.id)}/sync-signature`, {})),
147
+ crm_deal_doc_void: async (a, ctx) => data(await ctx.messagingPost(`/CrmDealDocuments/${id(a.id)}/void`, {})),
148
+ crm_deal_doc_signed_info: async (a) => ({
149
+ path: `/CrmDealDocuments/${id(a.id)}/signed-document`,
150
+ note: `The file is not returned here. Run: velaro crm-deal-doc signed ${a.id} --out <file>`,
151
+ }),
152
+ };
package/server.js CHANGED
@@ -54,7 +54,7 @@ import { withAnnotations } from './tool-annotations.js';
54
54
  import { loadParity, runParity } from './parity/loader.js';
55
55
  import { parseToolsets, filterTools, toolsetBlockedMessage } from './toolsets.js';
56
56
  import { resolveMessagingApi } from './messaging-base.js';
57
- import { normalizeMultiTabMode, buildMultiTabUpdateFields } from './chat-window-style.js';
57
+ import { normalizeMultiTabMode, buildMultiTabUpdateFields, normalizeEmailTranscript, buildEmailTranscriptUpdateFields } from './chat-window-style.js';
58
58
  import { buildResolvePath, buildTimelinePath, buildOverrideBody, buildValidateBody, buildBannerPath, buildOverrideListPath, tolerant, VALIDATE_PATH, OVERRIDE_PATH } from './workflow-schedule.js';
59
59
  import { applyEmailSubmissionsTo } from './survey-email.js';
60
60
 
@@ -2991,6 +2991,18 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
2991
2991
  required: ['id', 'multiTabMode'],
2992
2992
  },
2993
2993
  },
2994
+ {
2995
+ name: 'chat_window_set_email_transcript',
2996
+ description: 'Turn the visitor "email me this transcript" option on or off for a chat window, or "default" to follow the global default (on). If a visitor asks for a transcript while the chat is still open, the full transcript is emailed once when the chat ends. Reads the window first and saves it with only this field changed.',
2997
+ inputSchema: {
2998
+ type: 'object',
2999
+ properties: {
3000
+ id: { type: 'number', description: 'Chat window ID (see chat_window_list)' },
3001
+ value: { type: 'string', enum: ['on', 'off', 'default'], description: '"default" clears the override (global default is on)' },
3002
+ },
3003
+ required: ['id', 'value'],
3004
+ },
3005
+ },
2994
3006
  // ── Visitor Monitor (session-scoped: SiteId comes from the caller's JWT, never an arg) ──
2995
3007
  {
2996
3008
  name: 'visitor_monitor_active',
@@ -8253,6 +8265,20 @@ reply: ${r?.reply}`;
8253
8265
  return JSON.stringify({ id: updated.id, multiTabMode: updated.styleConfig?.multiTabMode ?? null }, null, 2);
8254
8266
  }
8255
8267
 
8268
+ case 'chat_window_set_email_transcript': {
8269
+ if (!args.id) throw new Error('id is required');
8270
+ const value = normalizeEmailTranscript(args.value);
8271
+ const current = await messagingGet(`/ChatWindow/get/${args.id}`);
8272
+ const form = new FormData();
8273
+ for (const [k, v] of Object.entries(buildEmailTranscriptUpdateFields(current, value))) form.append(k, v);
8274
+ const res = await fetch(`${MESSAGING_API}/ChatWindow/Update/${args.id}`, {
8275
+ method: 'POST', headers: { Authorization: authHeader() }, body: form, signal: AbortSignal.timeout(30000),
8276
+ });
8277
+ if (!res.ok) throw new Error(`/ChatWindow/Update/${args.id} -> ${res.status}: ${(await res.text().catch(() => '')).slice(0, 300)}`);
8278
+ const updated = await res.json();
8279
+ return JSON.stringify({ id: updated.id, enableEmailTranscriptButton: updated.styleConfig?.enableEmailTranscriptButton ?? null }, null, 2);
8280
+ }
8281
+
8256
8282
  case 'widget_container_get': {
8257
8283
  const c = await api('GET', `/PageWidgetContainers/${args.id}`);
8258
8284
  return JSON.stringify(c, null, 2);