@zaapi/open-api-mcp 1.1.1 → 1.3.0

package/dist/tools/contacts/list-contacts.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-contacts.js","sourceRoot":"","sources":["../../../src/tools/contacts/list-contacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,gBAAgB,GAEjB,MAAM,cAAc,CAAC;AAEtB,MAAM,SAAS,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AAElD,MAAM,CAAC,MAAM,YAAY,GAAiB;IACxC,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,eAAe;IACtB,WAAW,EAAE,kCAAkC,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,EAAE,SAAS,CAAC,iEAAiE;IAC3K,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,mBAAmB;IACzB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,GAAG,gBAAgB;QACnB,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,GAAG,CAAC,GAAG,CAAC;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,oFAAoF,CACrF;QACH,YAAY,EAAE,CAAC;aACZ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,oFAAoF,CACrF;QACH,aAAa,EAAE,CAAC;aACb,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,+EAA+E,CAChF;KACJ,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"list-contacts.js","sourceRoot":"","sources":["../../../src/tools/contacts/list-contacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAqB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,SAAS,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AAElD,MAAM,CAAC,MAAM,YAAY,GAAiB;IACxC,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,eAAe;IACtB,WAAW,EACT,+XAA+X;IACjY,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,mBAAmB;IACzB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,GAAG,gBAAgB;QACnB,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,GAAG,CAAC,GAAG,CAAC;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,uEAAuE,CACxE;QACH,YAAY,EAAE,CAAC;aACZ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,kEAAkE,CACnE;QACH,aAAa,EAAE,CAAC;aACb,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,6DAA6D,CAAC;KAC3E,CAAC;IACF,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,qBAAqB,EAAE;QAC9D,SAAS,EAAE,IAAI;KAChB,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/contacts/search-contacts.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { cursor, searchQuery } from '../common.js';
+import { contactSearchHit, envelope } from '../responses.js';
+const queryKeys = ['query', 'cursor'];
+export const searchContacts = {
+    name: 'searchContacts',
+    title: 'Search contacts',
+    description: 'Find contacts by name, email, phone, address or note when you do not have a contact id. Returns 10 hits per page, most relevant first, each listing the fields that matched. A hit is a summary, not the full record — call getContactById with the id for custom fields and the timestamps the write tools need. Page with cursor alone; this operation does not accept pageSize. Requires the contacts:read scope.',
+    scope: 'contacts:read',
+    method: 'GET',
+    path: '/v1/contacts/search',
+    queryKeys,
+    inputSchema: z.object({
+        query: searchQuery,
+        cursor,
+    }),
+    outputSchema: envelope(z.array(contactSearchHit), 'Matching contacts, most relevant first. Up to 10 per page.', { paginated: true }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+};
+//# sourceMappingURL=search-contacts.js.map

package/dist/tools/contacts/search-contacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-contacts.js","sourceRoot":"","sources":["../../../src/tools/contacts/search-contacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAqB,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE7D,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAU,CAAC;AAE/C,MAAM,CAAC,MAAM,cAAc,GAAiB;IAC1C,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,iBAAiB;IACxB,WAAW,EACT,sZAAsZ;IACxZ,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,qBAAqB;IAC3B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,KAAK,EAAE,WAAW;QAClB,MAAM;KACP,CAAC;IACF,YAAY,EAAE,QAAQ,CACpB,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,EACzB,4DAA4D,EAC5D,EAAE,SAAS,EAAE,IAAI,EAAE,CACpB;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/contacts/update-contact-field.js

@@ -1,25 +1,30 @@
 import { z } from 'zod';
-import { describeHttpRequest, fieldValue, } from '../common.js';
+import { fieldValue } from '../common.js';
 const queryKeys = [];
 export const updateContactField = {
     name: 'updateContactField',
     title: 'Update a contact field value',
-    description: `Required scope: contacts:write. ${describeHttpRequest('PATCH', '/v1/contacts/fields', queryKeys)} Set or clear a custom field. Pass the customFieldsUpdatedAt you last read as updatedAt; a mismatch is rejected with 409.`,
+    description: 'Set or clear one custom field on a contact. Resolve contactFieldId with listContactFields and read the contact first: updatedAt must be the customFieldsUpdatedAt from that read, or the contact’s updatedAt when the contact has no custom field writes yet. A stale value is rejected with 409 — re-read and retry. Send null as value to clear. The response is only an acknowledgement, so re-read with getContactById to confirm. Requires the contacts:write scope.',
+    scope: 'contacts:write',
     method: 'PATCH',
     path: '/v1/contacts/fields',
     queryKeys,
     inputSchema: z.object({
-        contactId: z.string().min(1).describe('JSON body. The ID of the contact.'),
+        contactId: z.string().min(1).describe('The ID of the contact.'),
         contactFieldId: z
             .string()
             .min(1)
-            .describe('JSON body. The ID of the contact field to update.'),
-        value: fieldValue.describe('JSON body. New value for the field. Send null to clear it. Must match the field definition.'),
+            .describe('The ID of the contact field, from listContactFields.'),
+        value: fieldValue.describe('New value, matching the field dataType and any select options. Send null to clear.'),
         updatedAt: z
             .string()
             .min(1)
-            .describe('JSON body. ISO 8601 date-time. Pass customFieldsUpdatedAt from the last read, or the contact updatedAt when customFieldsUpdatedAt is absent.'),
+            .describe('ISO 8601 date-time. The customFieldsUpdatedAt from the last read, or the contact updatedAt when customFieldsUpdatedAt is absent.'),
     }),
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
 };
 //# sourceMappingURL=update-contact-field.js.map

package/dist/tools/contacts/update-contact-field.js.map

@@ -1 +1 @@
-{"version":3,"file":"update-contact-field.js","sourceRoot":"","sources":["../../../src/tools/contacts/update-contact-field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,UAAU,GAEX,MAAM,cAAc,CAAC;AAEtB,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,kBAAkB,GAAiB;IAC9C,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,8BAA8B;IACrC,WAAW,EAAE,mCAAmC,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,EAAE,SAAS,CAAC,2HAA2H;IACzO,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,qBAAqB;IAC3B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,mCAAmC,CAAC;QAC1E,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,mDAAmD,CAAC;QAChE,KAAK,EAAE,UAAU,CAAC,QAAQ,CACxB,6FAA6F,CAC9F;QACD,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CACP,8IAA8I,CAC/I;KACJ,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE;CAC7D,CAAC"}
+{"version":3,"file":"update-contact-field.js","sourceRoot":"","sources":["../../../src/tools/contacts/update-contact-field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAqB,MAAM,cAAc,CAAC;AAE7D,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,kBAAkB,GAAiB;IAC9C,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,8BAA8B;IACrC,WAAW,EACT,2cAA2c;IAC7c,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,qBAAqB;IAC3B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QAC/D,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,sDAAsD,CAAC;QACnE,KAAK,EAAE,UAAU,CAAC,QAAQ,CACxB,oFAAoF,CACrF;QACD,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CACP,kIAAkI,CACnI;KACJ,CAAC;IACF,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,aAAa,EAAE,IAAI;KACpB;CACF,CAAC"}

package/dist/tools/conversations/filter-conversations.js

@@ -1,11 +1,12 @@
 import { z } from 'zod';
-import { describeHttpRequest, expand, paginationFields, paginationQueryKeys, } from '../common.js';
+import { expand, paginationFields, paginationQueryKeys, } from '../common.js';
+import { conversation, envelope } from '../responses.js';
 const queryKeys = ['conversationId', 'contactId', ...paginationQueryKeys];
-const filterConversationsExpand = expand('Pass account to replace accountId with { id, name, channel }. assignee is not valid on conversations.');
 export const filterConversations = {
     name: 'filterConversations',
     title: 'Filter conversations by ID or contact',
-    description: `Required scope: conversations:read. ${describeHttpRequest('GET', '/v1/conversations', queryKeys)} Send conversationId and/or contactId — at least one is required. Paginate with pageSize (max 50) and cursor. Pass expand=account to replace accountId.`,
+    description: 'Fetch conversations by id, or every conversation belonging to one contact. Returns the thread record itself: channel, contact, current labelIds, unread count and a last-message snippet. There is no way to list conversations without an id — to find one, start from listTickets, searchMessages or a contact. Requires the conversations:read scope.',
+    scope: 'conversations:read',
     method: 'GET',
     path: '/v1/conversations',
     queryKeys,
@@ -15,18 +16,21 @@ export const filterConversations = {
             .string()
             .min(1)
             .optional()
-            .describe('Query parameter. The ID of the conversation.'),
+            .describe('The ID of the conversation.'),
         contactId: z
             .string()
             .min(1)
             .optional()
-            .describe('Query parameter. The ID of the contact.'),
+            .describe('Return every conversation this contact has, across channels.'),
         ...paginationFields,
-        expand: filterConversationsExpand,
+        expand: expand(['account'], 'Replace accountId with { id, name, channel }.'),
     })
         .refine((value) => Boolean(value.conversationId || value.contactId), {
         message: 'Send conversationId and/or contactId.',
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(conversation), 'The matching conversations.', {
+        paginated: true,
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=filter-conversations.js.map

package/dist/tools/conversations/filter-conversations.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter-conversations.js","sourceRoot":"","sources":["../../../src/tools/conversations/filter-conversations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AAEtB,MAAM,SAAS,GAAG,CAAC,gBAAgB,EAAE,WAAW,EAAE,GAAG,mBAAmB,CAAC,CAAC;AAE1E,MAAM,yBAAyB,GAAG,MAAM,CACtC,uGAAuG,CACxG,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAiB;IAC/C,IAAI,EAAE,qBAAqB;IAC3B,KAAK,EAAE,uCAAuC;IAC9C,WAAW,EAAE,uCAAuC,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,EAAE,SAAS,CAAC,yJAAyJ;IACvQ,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,mBAAmB;IACzB,SAAS;IACT,WAAW,EAAE,CAAC;SACX,MAAM,CAAC;QACN,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CAAC,8CAA8C,CAAC;QAC3D,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CAAC,yCAAyC,CAAC;QACtD,GAAG,gBAAgB;QACnB,MAAM,EAAE,yBAAyB;KAClC,CAAC;SACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,SAAS,CAAC,EAAE;QACnE,OAAO,EAAE,uCAAuC;KACjD,CAAC;IACJ,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"filter-conversations.js","sourceRoot":"","sources":["../../../src/tools/conversations/filter-conversations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,MAAM,EACN,gBAAgB,EAChB,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEzD,MAAM,SAAS,GAAG,CAAC,gBAAgB,EAAE,WAAW,EAAE,GAAG,mBAAmB,CAAC,CAAC;AAE1E,MAAM,CAAC,MAAM,mBAAmB,GAAiB;IAC/C,IAAI,EAAE,qBAAqB;IAC3B,KAAK,EAAE,uCAAuC;IAC9C,WAAW,EACT,0VAA0V;IAC5V,KAAK,EAAE,oBAAoB;IAC3B,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,mBAAmB;IACzB,SAAS;IACT,WAAW,EAAE,CAAC;SACX,MAAM,CAAC;QACN,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CAAC,6BAA6B,CAAC;QAC1C,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CACP,8DAA8D,CAC/D;QACH,GAAG,gBAAgB;QACnB,MAAM,EAAE,MAAM,CACZ,CAAC,SAAS,CAAC,EACX,+CAA+C,CAChD;KACF,CAAC;SACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,SAAS,CAAC,EAAE;QACnE,OAAO,EAAE,uCAAuC;KACjD,CAAC;IACJ,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,6BAA6B,EAAE;QAC3E,SAAS,EAAE,IAAI;KAChB,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/conversations/mark-conversation-read.js

@@ -1,23 +1,21 @@
 import { z } from 'zod';
-import { describeHttpRequest } from '../common.js';
 const queryKeys = [];
 export const markConversationRead = {
     name: 'markConversationRead',
     title: 'Mark a conversation as read',
-    description: `Required scope: conversations:write. ${describeHttpRequest('PATCH', '/v1/conversations/read', queryKeys)} Clears the unread count on the conversation's open ticket. Idempotent. A conversation with no open ticket returns 404.`,
+    description: "Clear the unread count on the conversation's open ticket. Idempotent, so it is safe to repeat. A conversation with no open ticket returns 404. Requires the conversations:write scope.",
+    scope: 'conversations:write',
     method: 'PATCH',
     path: '/v1/conversations/read',
     queryKeys,
     inputSchema: z.object({
-        conversationId: z
-            .string()
-            .min(1)
-            .describe('JSON body. The ID of the conversation.'),
+        conversationId: z.string().min(1).describe('The ID of the conversation.'),
     }),
     annotations: {
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: true,
+        openWorldHint: true,
     },
 };
 //# sourceMappingURL=mark-conversation-read.js.map

package/dist/tools/conversations/mark-conversation-read.js.map

@@ -1 +1 @@
-{"version":3,"file":"mark-conversation-read.js","sourceRoot":"","sources":["../../../src/tools/conversations/mark-conversation-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAqB,MAAM,cAAc,CAAC;AAEtE,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,oBAAoB,GAAiB;IAChD,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,6BAA6B;IACpC,WAAW,EAAE,wCAAwC,mBAAmB,CAAC,OAAO,EAAE,wBAAwB,EAAE,SAAS,CAAC,yHAAyH;IAC/O,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,wBAAwB;IAC9B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,wCAAwC,CAAC;KACtD,CAAC;IACF,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;KACrB;CACF,CAAC"}
+{"version":3,"file":"mark-conversation-read.js","sourceRoot":"","sources":["../../../src/tools/conversations/mark-conversation-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,oBAAoB,GAAiB;IAChD,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,6BAA6B;IACpC,WAAW,EACT,wLAAwL;IAC1L,KAAK,EAAE,qBAAqB;IAC5B,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,wBAAwB;IAC9B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;KAC1E,CAAC;IACF,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,IAAI;KACpB;CACF,CAAC"}

package/dist/tools/conversations/update-conversation-labels.js

@@ -1,33 +1,34 @@
 import { z } from 'zod';
-import { describeHttpRequest } from '../common.js';
 const queryKeys = [];
 const MAX_LABELS_PER_REQUEST = 10;
 export const updateConversationLabels = {
     name: 'updateConversationLabels',
     title: 'Update conversation labels',
-    description: `Required scope: conversations:write. ${describeHttpRequest('PATCH', '/v1/conversations/labels', queryKeys)} Add and/or remove up to 10 labels. At least one of addLabels or removeLabels is required. Labels already applied (or not applied) are ignored.`,
+    description: 'Add and/or remove labels on a conversation, up to 10 of each per call. Labels live on the conversation, not on its tickets, so this affects every ticket on the thread. Both lists take existing label ids from listLabels — this does not create labels. At least one of addLabels or removeLabels is required; labels already applied, or already absent, are ignored. The response is only an acknowledgement, so re-read with filterConversations to confirm labelIds. Requires the conversations:write scope.',
+    scope: 'conversations:write',
     method: 'PATCH',
     path: '/v1/conversations/labels',
     queryKeys,
     inputSchema: z
         .object({
-        conversationId: z
-            .string()
-            .min(1)
-            .describe('JSON body. The ID of the conversation.'),
+        conversationId: z.string().min(1).describe('The ID of the conversation.'),
         addLabels: z
             .array(z.string())
             .max(MAX_LABELS_PER_REQUEST)
             .optional()
-            .describe('JSON body. Existing label IDs to add. Maximum 10.'),
+            .describe('Existing label IDs to add, from listLabels. Maximum 10.'),
         removeLabels: z
             .array(z.string())
             .max(MAX_LABELS_PER_REQUEST)
             .optional()
-            .describe('JSON body. Existing label IDs to remove. Maximum 10.'),
+            .describe('Existing label IDs to remove, from listLabels. Maximum 10.'),
     })
         .refine((value) => (value.addLabels?.length ?? 0) > 0 ||
         (value.removeLabels?.length ?? 0) > 0, { message: 'Send addLabels and/or removeLabels.' }),
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
 };
 //# sourceMappingURL=update-conversation-labels.js.map

package/dist/tools/conversations/update-conversation-labels.js.map

@@ -1 +1 @@
-{"version":3,"file":"update-conversation-labels.js","sourceRoot":"","sources":["../../../src/tools/conversations/update-conversation-labels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAqB,MAAM,cAAc,CAAC;AAEtE,MAAM,SAAS,GAAG,EAAW,CAAC;AAC9B,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAElC,MAAM,CAAC,MAAM,wBAAwB,GAAiB;IACpD,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,4BAA4B;IACnC,WAAW,EAAE,wCAAwC,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,EAAE,SAAS,CAAC,iJAAiJ;IACzQ,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,0BAA0B;IAChC,SAAS;IACT,WAAW,EAAE,CAAC;SACX,MAAM,CAAC;QACN,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,wCAAwC,CAAC;QACrD,SAAS,EAAE,CAAC;aACT,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,GAAG,CAAC,sBAAsB,CAAC;aAC3B,QAAQ,EAAE;aACV,QAAQ,CAAC,mDAAmD,CAAC;QAChE,YAAY,EAAE,CAAC;aACZ,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,GAAG,CAAC,sBAAsB,CAAC;aAC3B,QAAQ,EAAE;aACV,QAAQ,CAAC,sDAAsD,CAAC;KACpE,CAAC;SACD,MAAM,CACL,CAAC,KAAK,EAAE,EAAE,CACR,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC;QAClC,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,EACvC,EAAE,OAAO,EAAE,qCAAqC,EAAE,CACnD;IACH,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE;CAC7D,CAAC"}
+{"version":3,"file":"update-conversation-labels.js","sourceRoot":"","sources":["../../../src/tools/conversations/update-conversation-labels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,SAAS,GAAG,EAAW,CAAC;AAC9B,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAElC,MAAM,CAAC,MAAM,wBAAwB,GAAiB;IACpD,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,4BAA4B;IACnC,WAAW,EACT,ofAAof;IACtf,KAAK,EAAE,qBAAqB;IAC5B,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,0BAA0B;IAChC,SAAS;IACT,WAAW,EAAE,CAAC;SACX,MAAM,CAAC;QACN,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACzE,SAAS,EAAE,CAAC;aACT,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,GAAG,CAAC,sBAAsB,CAAC;aAC3B,QAAQ,EAAE;aACV,QAAQ,CAAC,yDAAyD,CAAC;QACtE,YAAY,EAAE,CAAC;aACZ,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,GAAG,CAAC,sBAAsB,CAAC;aAC3B,QAAQ,EAAE;aACV,QAAQ,CAAC,4DAA4D,CAAC;KAC1E,CAAC;SACD,MAAM,CACL,CAAC,KAAK,EAAE,EAAE,CACR,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC;QAClC,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,EACvC,EAAE,OAAO,EAAE,qCAAqC,EAAE,CACnD;IACH,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,aAAa,EAAE,IAAI;KACpB;CACF,CAAC"}

package/dist/tools/index.js

@@ -15,6 +15,8 @@ import { listTicketFields } from './tickets/list-ticket-fields.js';
 import { listTickets } from './tickets/list-tickets.js';
 import { listUsers } from './users/list-users.js';
 import { markConversationRead } from './conversations/mark-conversation-read.js';
+import { searchContacts } from './contacts/search-contacts.js';
+import { searchMessages } from './messages/search-messages.js';
 import { sendPlainTextMessage } from './messages/send-plain-text-message.js';
 import { updateContactField } from './contacts/update-contact-field.js';
 import { updateConversationLabels } from './conversations/update-conversation-labels.js';
@@ -29,11 +31,13 @@ export const tools = [
     markConversationRead,
     updateConversationLabels,
     getContactById,
+    searchContacts,
     listContacts,
     listContactFields,
     createContact,
     updateContactField,
     getMessages,
+    searchMessages,
     listInternalComments,
     createInternalComment,
     sendPlainTextMessage,

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAIrE,MAAM,CAAC,MAAM,KAAK,GAAmB;IACnC,aAAa;IACb,WAAW;IACX,gBAAgB;IAChB,iBAAiB;IACjB,WAAW;IACX,mBAAmB;IACnB,oBAAoB;IACpB,wBAAwB;IACxB,cAAc;IACd,YAAY;IACZ,iBAAiB;IACjB,aAAa;IACb,kBAAkB;IAClB,WAAW;IACX,oBAAoB;IACpB,qBAAqB;IACrB,oBAAoB;IACpB,SAAS;IACT,UAAU;IACV,SAAS;IACT,YAAY;CACb,CAAC;AAEF,MAAM,UAAU,UAAU,CACxB,KAA8B,EAC9B,SAA4B;IAE5B,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,MAAM,IAAI,GAA4B,EAAE,CAAC;IAEzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,SAAS;QACX,CAAC;QACD,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK;QACL,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAIrE,MAAM,CAAC,MAAM,KAAK,GAAmB;IACnC,aAAa;IACb,WAAW;IACX,gBAAgB;IAChB,iBAAiB;IACjB,WAAW;IACX,mBAAmB;IACnB,oBAAoB;IACpB,wBAAwB;IACxB,cAAc;IACd,cAAc;IACd,YAAY;IACZ,iBAAiB;IACjB,aAAa;IACb,kBAAkB;IAClB,WAAW;IACX,cAAc;IACd,oBAAoB;IACpB,qBAAqB;IACrB,oBAAoB;IACpB,SAAS;IACT,UAAU;IACV,SAAS;IACT,YAAY;CACb,CAAC;AAEF,MAAM,UAAU,UAAU,CACxB,KAA8B,EAC9B,SAA4B;IAE5B,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,MAAM,IAAI,GAA4B,EAAE,CAAC;IAEzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,SAAS;QACX,CAAC;QACD,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK;QACL,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClD,CAAC;AACJ,CAAC"}

package/dist/tools/labels/list-labels.js

@@ -1,10 +1,12 @@
 import { z } from 'zod';
-import { describeHttpRequest, paginationFields, } from '../common.js';
+import { paginationFields } from '../common.js';
+import { envelope, label } from '../responses.js';
 const queryKeys = ['searchTerm', 'pageSize', 'cursor'];
 export const listLabels = {
     name: 'listLabels',
     title: 'List labels',
-    description: `Required scope: labels:read. ${describeHttpRequest('GET', '/v1/labels', queryKeys)} Labels for the store, most recently updated first. searchTerm must be 3–100 characters. Whitespace-only searchTerm is treated as omitted.`,
+    description: 'Page through the labels defined on the store, most recently updated first. Labels are applied to conversations, not tickets — resolve a label name to its id here before calling updateConversationLabels, which only accepts ids that already exist. searchTerm must be 3 to 100 characters; a shorter one is rejected, and a whitespace-only one is treated as omitted. Requires the labels:read scope.',
+    scope: 'labels:read',
     method: 'GET',
     path: '/v1/labels',
     queryKeys,
@@ -14,9 +16,10 @@ export const listLabels = {
             .min(3)
             .max(100)
             .optional()
-            .describe('Query parameter. Optional case-insensitive search on the label text. 3–100 characters.'),
+            .describe('Case-insensitive match on the label text. 3 to 100 characters. Omit to list everything.'),
         ...paginationFields,
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(label), 'A page of labels, most recently updated first.', { paginated: true }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=list-labels.js.map

package/dist/tools/labels/list-labels.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-labels.js","sourceRoot":"","sources":["../../../src/tools/labels/list-labels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,gBAAgB,GAEjB,MAAM,cAAc,CAAC;AAEtB,MAAM,SAAS,GAAG,CAAC,YAAY,EAAE,UAAU,EAAE,QAAQ,CAAU,CAAC;AAEhE,MAAM,CAAC,MAAM,UAAU,GAAiB;IACtC,IAAI,EAAE,YAAY;IAClB,KAAK,EAAE,aAAa;IACpB,WAAW,EAAE,gCAAgC,mBAAmB,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,CAAC,4IAA4I;IAC5O,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,YAAY;IAClB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,GAAG,CAAC;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,wFAAwF,CACzF;QACH,GAAG,gBAAgB;KACpB,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"list-labels.js","sourceRoot":"","sources":["../../../src/tools/labels/list-labels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAqB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,SAAS,GAAG,CAAC,YAAY,EAAE,UAAU,EAAE,QAAQ,CAAU,CAAC;AAEhE,MAAM,CAAC,MAAM,UAAU,GAAiB;IACtC,IAAI,EAAE,YAAY;IAClB,KAAK,EAAE,aAAa;IACpB,WAAW,EACT,2YAA2Y;IAC7Y,KAAK,EAAE,aAAa;IACpB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,YAAY;IAClB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,GAAG,CAAC;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,yFAAyF,CAC1F;QACH,GAAG,gBAAgB;KACpB,CAAC;IACF,YAAY,EAAE,QAAQ,CACpB,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EACd,gDAAgD,EAChD,EAAE,SAAS,EAAE,IAAI,EAAE,CACpB;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/messages/create-internal-comment.js

@@ -1,23 +1,24 @@
 import { z } from 'zod';
-import { describeHttpRequest } from '../common.js';
 const queryKeys = [];
 export const createInternalComment = {
     name: 'createInternalComment',
     title: 'Add an internal comment',
-    description: `Required scope: messages:write. ${describeHttpRequest('POST', '/v1/messages/internal-comments', queryKeys)} Add a seller-private note. Not sent to the customer.`,
+    description: 'Leave a seller-private note on a conversation. It is visible to the team only and is never delivered to the customer — use sendPlainTextMessage for anything the customer should see. The response is only an acknowledgement, so re-read with listInternalComments to confirm. Requires the messages:write scope.',
+    scope: 'messages:write',
     method: 'POST',
     path: '/v1/messages/internal-comments',
     queryKeys,
     inputSchema: z.object({
-        conversationId: z
-            .string()
-            .min(1)
-            .describe('JSON body. The ID of the conversation.'),
+        conversationId: z.string().min(1).describe('The ID of the conversation.'),
         text: z
             .string()
             .min(1)
-            .describe('JSON body. Internal comment text. Not sent to the customer.'),
+            .describe('Internal comment text. Seller-private, not sent to the customer.'),
     }),
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
 };
 //# sourceMappingURL=create-internal-comment.js.map

package/dist/tools/messages/create-internal-comment.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-internal-comment.js","sourceRoot":"","sources":["../../../src/tools/messages/create-internal-comment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAqB,MAAM,cAAc,CAAC;AAEtE,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,yBAAyB;IAChC,WAAW,EAAE,mCAAmC,mBAAmB,CAAC,MAAM,EAAE,gCAAgC,EAAE,SAAS,CAAC,uDAAuD;IAC/K,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,gCAAgC;IACtC,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,wCAAwC,CAAC;QACrD,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,6DAA6D,CAAC;KAC3E,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE;CAC7D,CAAC"}
+{"version":3,"file":"create-internal-comment.js","sourceRoot":"","sources":["../../../src/tools/messages/create-internal-comment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,yBAAyB;IAChC,WAAW,EACT,oTAAoT;IACtT,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,gCAAgC;IACtC,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACzE,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CACP,kEAAkE,CACnE;KACJ,CAAC;IACF,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,aAAa,EAAE,IAAI;KACpB;CACF,CAAC"}

package/dist/tools/messages/get-messages.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { cursor, describeHttpRequest, expand, messagePageSize, } from '../common.js';
+import { cursor, expand, messagePageSize, } from '../common.js';
+import { envelope, message } from '../responses.js';
 const queryKeys = [
     'conversationId',
     'ticketId',
@@ -7,11 +8,11 @@ const queryKeys = [
     'cursor',
     'expand',
 ];
-const getMessagesExpand = expand('Pass sentBy,conversation,account to add related names. Those ids stay on the message.');
 export const getMessages = {
     name: 'getMessages',
     title: 'List messages',
-    description: `Required scope: messages:read. ${describeHttpRequest('GET', '/v1/messages', queryKeys)} Customer-facing messages, newest first. Events and internal comments are excluded. Send conversationId and/or ticketId — at least one is required. When ticketId is set, results are limited to that ticket's time window. pageSize defaults to 15 and cannot exceed 15.`,
+    description: "Read the customer-facing messages on a thread, newest first. System events and internal comments are excluded — use listInternalComments for the private notes. Send conversationId for the whole thread, ticketId to narrow to one ticket's time window, or both. At least one is required. pageSize defaults to 15 and accepts up to 100, so ask for more in one call rather than walking the cursor. Requires the messages:read scope.",
+    scope: 'messages:read',
     method: 'GET',
     path: '/v1/messages',
     queryKeys,
@@ -21,19 +22,20 @@ export const getMessages = {
             .string()
             .min(1)
             .optional()
-            .describe('Query parameter. The ID of the conversation.'),
+            .describe('The ID of the conversation.'),
         ticketId: z
             .string()
             .min(1)
             .optional()
-            .describe("Query parameter. The ID of the ticket. When set, results are limited to that ticket's time window."),
+            .describe("The ID of the ticket. Narrows results to that ticket's time window."),
         pageSize: messagePageSize,
         cursor,
-        expand: getMessagesExpand,
+        expand: expand(['sentBy', 'conversation', 'account'], 'Add the named object beside the message. The underlying ids stay on the message.'),
     })
         .refine((value) => Boolean(value.conversationId || value.ticketId), {
         message: 'Send conversationId and/or ticketId.',
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(message), 'A page of customer-facing messages, newest first.', { paginated: true }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=get-messages.js.map

package/dist/tools/messages/get-messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-messages.js","sourceRoot":"","sources":["../../../src/tools/messages/get-messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,MAAM,EACN,eAAe,GAEhB,MAAM,cAAc,CAAC;AAEtB,MAAM,SAAS,GAAG;IAChB,gBAAgB;IAChB,UAAU;IACV,UAAU;IACV,QAAQ;IACR,QAAQ;CACA,CAAC;AAEX,MAAM,iBAAiB,GAAG,MAAM,CAC9B,uFAAuF,CACxF,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC,IAAI,EAAE,aAAa;IACnB,KAAK,EAAE,eAAe;IACtB,WAAW,EAAE,kCAAkC,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,SAAS,CAAC,2QAA2Q;IAC/W,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,cAAc;IACpB,SAAS;IACT,WAAW,EAAE,CAAC;SACX,MAAM,CAAC;QACN,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CAAC,8CAA8C,CAAC;QAC3D,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CACP,oGAAoG,CACrG;QACH,QAAQ,EAAE,eAAe;QACzB,MAAM;QACN,MAAM,EAAE,iBAAiB;KAC1B,CAAC;SACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE;QAClE,OAAO,EAAE,sCAAsC;KAChD,CAAC;IACJ,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"get-messages.js","sourceRoot":"","sources":["../../../src/tools/messages/get-messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,MAAM,EACN,MAAM,EACN,eAAe,GAEhB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,SAAS,GAAG;IAChB,gBAAgB;IAChB,UAAU;IACV,UAAU;IACV,QAAQ;IACR,QAAQ;CACA,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC,IAAI,EAAE,aAAa;IACnB,KAAK,EAAE,eAAe;IACtB,WAAW,EACT,2aAA2a;IAC7a,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,cAAc;IACpB,SAAS;IACT,WAAW,EAAE,CAAC;SACX,MAAM,CAAC;QACN,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CAAC,6BAA6B,CAAC;QAC1C,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CACP,qEAAqE,CACtE;QACH,QAAQ,EAAE,eAAe;QACzB,MAAM;QACN,MAAM,EAAE,MAAM,CACZ,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,CAAC,EACrC,kFAAkF,CACnF;KACF,CAAC;SACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE;QAClE,OAAO,EAAE,sCAAsC;KAChD,CAAC;IACJ,YAAY,EAAE,QAAQ,CACpB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAChB,mDAAmD,EACnD,EAAE,SAAS,EAAE,IAAI,EAAE,CACpB;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/messages/list-internal-comments.js

@@ -1,21 +1,21 @@
 import { z } from 'zod';
-import { describeHttpRequest, expand, paginationFields, paginationQueryKeys, } from '../common.js';
+import { expand, paginationFields, paginationQueryKeys, } from '../common.js';
+import { envelope, internalComment } from '../responses.js';
 const queryKeys = ['conversationId', ...paginationQueryKeys];
 export const listInternalComments = {
     name: 'listInternalComments',
     title: 'List internal comments',
-    description: `Required scope: messages:read. ${describeHttpRequest('GET', '/v1/messages/internal-comments', queryKeys)} Seller-private notes on a conversation, newest first. These do not reach the customer. Paginate with pageSize (max 50) and cursor.`,
+    description: 'Read the seller-private notes on a conversation, newest first. These never reached the customer and are not covered by searchMessages, so check them for context an agent left behind before answering. Requires the messages:read scope.',
+    scope: 'messages:read',
     method: 'GET',
     path: '/v1/messages/internal-comments',
     queryKeys,
     inputSchema: z.object({
-        conversationId: z
-            .string()
-            .min(1)
-            .describe('Query parameter. The ID of the conversation.'),
+        conversationId: z.string().min(1).describe('The ID of the conversation.'),
         ...paginationFields,
-        expand: expand('Pass createdBy,conversation,account to resolve related names.'),
+        expand: expand(['createdBy', 'conversation', 'account'], 'Resolve the related names. createdBy replaces noteData.createdBy in place.'),
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(internalComment), 'A page of internal comments, newest first.', { paginated: true }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=list-internal-comments.js.map

package/dist/tools/messages/list-internal-comments.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-internal-comments.js","sourceRoot":"","sources":["../../../src/tools/messages/list-internal-comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AAEtB,MAAM,SAAS,GAAG,CAAC,gBAAgB,EAAE,GAAG,mBAAmB,CAAC,CAAC;AAE7D,MAAM,CAAC,MAAM,oBAAoB,GAAiB;IAChD,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,wBAAwB;IAC/B,WAAW,EAAE,kCAAkC,mBAAmB,CAAC,KAAK,EAAE,gCAAgC,EAAE,SAAS,CAAC,qIAAqI;IAC3P,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,gCAAgC;IACtC,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,8CAA8C,CAAC;QAC3D,GAAG,gBAAgB;QACnB,MAAM,EAAE,MAAM,CACZ,+DAA+D,CAChE;KACF,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"list-internal-comments.js","sourceRoot":"","sources":["../../../src/tools/messages/list-internal-comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,MAAM,EACN,gBAAgB,EAChB,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE5D,MAAM,SAAS,GAAG,CAAC,gBAAgB,EAAE,GAAG,mBAAmB,CAAC,CAAC;AAE7D,MAAM,CAAC,MAAM,oBAAoB,GAAiB;IAChD,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,wBAAwB;IAC/B,WAAW,EACT,2OAA2O;IAC7O,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,gCAAgC;IACtC,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACzE,GAAG,gBAAgB;QACnB,MAAM,EAAE,MAAM,CACZ,CAAC,WAAW,EAAE,cAAc,EAAE,SAAS,CAAC,EACxC,4EAA4E,CAC7E;KACF,CAAC;IACF,YAAY,EAAE,QAAQ,CACpB,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,EACxB,4CAA4C,EAC5C,EAAE,SAAS,EAAE,IAAI,EAAE,CACpB;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/messages/search-messages.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { cursor, searchQuery } from '../common.js';
+import { envelope, messageSearchHit } from '../responses.js';
+const queryKeys = ['query', 'cursor'];
+export const searchMessages = {
+    name: 'searchMessages',
+    title: 'Search messages',
+    description: 'Find conversations by what was said in them. This is the only way to reach a thread from message content, so start here when the request names a topic rather than a ticket, conversation or contact. Returns 10 hits per page, most relevant first; every hit carries conversationId, which getMessages reads in full and listTickets turns into the tickets on that thread. Searches customer-facing message text only — internal comments are not indexed. Page with cursor alone; this operation does not accept pageSize. Requires the messages:read scope.',
+    scope: 'messages:read',
+    method: 'GET',
+    path: '/v1/messages/search',
+    queryKeys,
+    inputSchema: z.object({
+        query: searchQuery,
+        cursor,
+    }),
+    outputSchema: envelope(z.array(messageSearchHit), 'Matching messages, most relevant first. Up to 10 per page.', { paginated: true }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+};
+//# sourceMappingURL=search-messages.js.map

package/dist/tools/messages/search-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-messages.js","sourceRoot":"","sources":["../../../src/tools/messages/search-messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAqB,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE7D,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAU,CAAC;AAE/C,MAAM,CAAC,MAAM,cAAc,GAAiB;IAC1C,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,iBAAiB;IACxB,WAAW,EACT,kiBAAkiB;IACpiB,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,qBAAqB;IAC3B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,KAAK,EAAE,WAAW;QAClB,MAAM;KACP,CAAC;IACF,YAAY,EAAE,QAAQ,CACpB,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,EACzB,4DAA4D,EAC5D,EAAE,SAAS,EAAE,IAAI,EAAE,CACpB;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/messages/send-plain-text-message.js

@@ -1,24 +1,25 @@
 import { z } from 'zod';
-import { describeHttpRequest } from '../common.js';
 const queryKeys = [];
 export const sendPlainTextMessage = {
     name: 'sendPlainTextMessage',
     title: 'Send a plain text message',
-    description: `Required scope: messages:write. ${describeHttpRequest('POST', '/v1/messages/plain-text', queryKeys)} Send plain text to the customer on a conversation.`,
+    description: 'Send plain text to the customer on a conversation. This reaches a real person on the channel and cannot be recalled, so confirm the wording before calling it; for a note only the team can see, use createInternalComment instead. Delivery can still fail downstream when the account is unhealthy or the channel has closed its reply window — the response is only an acknowledgement, so re-read with getMessages to confirm the message landed. Requires the messages:write scope.',
+    scope: 'messages:write',
     method: 'POST',
     path: '/v1/messages/plain-text',
     queryKeys,
     inputSchema: z.object({
-        conversationId: z
-            .string()
-            .min(1)
-            .describe('JSON body. The ID of the conversation.'),
+        conversationId: z.string().min(1).describe('The ID of the conversation.'),
         text: z
             .string()
             .min(1)
             .max(1000)
-            .describe('JSON body. Plain text to send to the customer. Maximum 1000 characters.'),
+            .describe('Plain text sent to the customer. Maximum 1000 characters.'),
     }),
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
 };
 //# sourceMappingURL=send-plain-text-message.js.map

package/dist/tools/messages/send-plain-text-message.js.map

@@ -1 +1 @@
-{"version":3,"file":"send-plain-text-message.js","sourceRoot":"","sources":["../../../src/tools/messages/send-plain-text-message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAqB,MAAM,cAAc,CAAC;AAEtE,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,oBAAoB,GAAiB;IAChD,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,2BAA2B;IAClC,WAAW,EAAE,mCAAmC,mBAAmB,CAAC,MAAM,EAAE,yBAAyB,EAAE,SAAS,CAAC,qDAAqD;IACtK,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,yBAAyB;IAC/B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,wCAAwC,CAAC;QACrD,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,IAAI,CAAC;aACT,QAAQ,CACP,yEAAyE,CAC1E;KACJ,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE;CAC7D,CAAC"}
+{"version":3,"file":"send-plain-text-message.js","sourceRoot":"","sources":["../../../src/tools/messages/send-plain-text-message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,oBAAoB,GAAiB;IAChD,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,2BAA2B;IAClC,WAAW,EACT,0dAA0d;IAC5d,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,yBAAyB;IAC/B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACzE,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,IAAI,CAAC;aACT,QAAQ,CAAC,2DAA2D,CAAC;KACzE,CAAC;IACF,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,aAAa,EAAE,IAAI;KACpB;CACF,CAAC"}