@smartytalent/mcp-tools 0.1.33-dev.27 → 0.1.33-dev.29

package/dist/tools.json

@@ -336,7 +336,7 @@
         },
         "include": {
           "type": "string",
-          "description": "JSON:API compound document request — comma-separated list of relationship paths to include in the response (e.g. `feedbacks`, `feedbacks,boeUser`). Currently advisory: the service always returns all declared relationships with empty defaults."
+          "description": "JSON:API compound document request - comma-separated list of relationship paths to include in the response (e.g. `feedbacks`, `feedbacks,boeUser`). Currently advisory: the service always returns all declared relationships with empty defaults."
         }
       },
       "required": [
@@ -7877,7 +7877,7 @@
                 "outcomes": {
                   "title": "FeedbackOutcomesSchema",
                   "type": "object",
-                  "description": "Per-outcome feedback rules. Outcome keys map to candidate.recommendationStatusCode: 1=notFit, 2=maybe, 3=fit. Code 0 (not evaluated) never triggers feedback — the workflow pauses instead.",
+                  "description": "Per-outcome feedback rules. Outcome keys map to candidate.recommendationStatusCode: 1=notFit, 2=maybe, 3=fit. Code 0 (not evaluated) never triggers feedback - the workflow pauses instead.",
                   "properties": {
                     "notFit": {
                       "title": "FeedbackOutcomeRuleSchema",
@@ -8291,7 +8291,7 @@
                     "outcomes": {
                       "title": "FeedbackOutcomesSchema",
                       "type": "object",
-                      "description": "Per-outcome feedback rules. Outcome keys map to candidate.recommendationStatusCode: 1=notFit, 2=maybe, 3=fit. Code 0 (not evaluated) never triggers feedback — the workflow pauses instead.",
+                      "description": "Per-outcome feedback rules. Outcome keys map to candidate.recommendationStatusCode: 1=notFit, 2=maybe, 3=fit. Code 0 (not evaluated) never triggers feedback - the workflow pauses instead.",
                       "properties": {
                         "notFit": {
                           "title": "FeedbackOutcomeRuleSchema",
@@ -8777,7 +8777,7 @@
                     },
                     "actionName": {
                       "type": "string",
-                      "description": "Action identifier (e.g. `email:send`, `call:initiate`). Resolved by the same convention the workflow engine uses — `resource:verb` maps to `sm-${env}-tb-service-action-function-${resource}-${verb}`."
+                      "description": "Action identifier (e.g. `email:send`, `call:initiate`). Resolved by the same convention the workflow engine uses - `resource:verb` maps to `sm-${env}-tb-service-action-function-${resource}-${verb}`."
                     },
                     "input": {
                       "type": "object",
@@ -9040,7 +9040,7 @@
                         },
                         "actionName": {
                           "type": "string",
-                          "description": "Action identifier (e.g. `email:send`, `call:initiate`). Resolved by the same convention the workflow engine uses — `resource:verb` maps to `sm-${env}-tb-service-action-function-${resource}-${verb}`."
+                          "description": "Action identifier (e.g. `email:send`, `call:initiate`). Resolved by the same convention the workflow engine uses - `resource:verb` maps to `sm-${env}-tb-service-action-function-${resource}-${verb}`."
                         },
                         "input": {
                           "type": "object",
@@ -9297,7 +9297,7 @@
                     "candidate",
                     "talent"
                   ],
-                  "description": "Submission type — determines which workflow to trigger"
+                  "description": "Submission type - determines which workflow to trigger"
                 },
                 "status": {
                   "type": "string",
@@ -9611,7 +9611,7 @@
             "candidate",
             "talent"
           ],
-          "description": "Submission type — determines which workflow to trigger. Auto-derived from jobId if omitted."
+          "description": "Submission type - determines which workflow to trigger. Auto-derived from jobId if omitted."
         },
         "referral": {
           "type": "object",
@@ -9798,7 +9798,7 @@
                         "candidate",
                         "talent"
                       ],
-                      "description": "Submission type — determines which workflow to trigger"
+                      "description": "Submission type - determines which workflow to trigger"
                     },
                     "status": {
                       "type": "string",
@@ -10814,14 +10814,81 @@
     "inputSchema": {
       "type": "object",
       "properties": {
-        "filterStatus": {
+        "filterFolder": {
           "type": "string",
-          "description": "Returns calls with the current status (active, archived). If not provided, the default value will be set to 'active'.",
+          "description": "Filter by folder bucket. Mirrors the left-nav chips. Single-status\nfolders translate to filterStatus + filterDirection internally\n(drafts/scheduled/cancelled/archived/incoming/outgoing). Multi-\nstatus folders (active, missed) use a Scan path. Conflicts with\nexplicit filterStatus / filterDirection (request returns 400).",
           "enum": [
+            "drafts",
+            "scheduled",
             "active",
+            "incoming",
+            "outgoing",
+            "missed",
+            "cancelled",
+            "archived"
+          ]
+        },
+        "filterStatus": {
+          "type": "string",
+          "description": "Filter by status. Accepts single value or comma-separated list\n(e.g. `queued,ringing,in-progress`). Comma-list routes to the\nScan path (slower, no cursor pagination).",
+          "enum": [
+            "draft",
+            "scheduled",
+            "cancelled",
+            "queued",
+            "ringing",
+            "in-progress",
+            "completed",
+            "failed",
+            "no-answer",
+            "busy",
+            "voicemail",
+            "abandoned",
             "archived"
           ]
         },
+        "filterDirection": {
+          "type": "string",
+          "description": "Filter by direction (inbound or outbound).",
+          "enum": [
+            "inbound",
+            "outbound"
+          ]
+        },
+        "filterProtocol": {
+          "type": "string",
+          "description": "Filter by wire protocol. `phone` is PSTN via Twilio; `webrtc` reserved for the future recruiter Voice SDK.",
+          "enum": [
+            "phone",
+            "webrtc"
+          ]
+        },
+        "filterFromIdentifier": {
+          "type": "string",
+          "description": "Filter by caller's protocol-native handle (E.164 phone for PSTN). Indexed via FromIdentifierIndex GSI."
+        },
+        "filterToIdentifier": {
+          "type": "string",
+          "description": "Filter by callee's protocol-native handle (E.164 phone for PSTN). Indexed via ToIdentifierIndex GSI. Use for 'all calls to this number' views."
+        },
+        "filterConversationId": {
+          "type": "string",
+          "description": "Filter all calls in a conversation thread. Indexed via ConversationIdIndex GSI."
+        },
+        "filterIntent": {
+          "type": "string",
+          "description": "Filter by AI intent classifier output (inbound calls only). Post-filtered after pagination - acceptable while intent classification is small-scale.",
+          "enum": [
+            "brief_request",
+            "sales_chat",
+            "faq",
+            "other"
+          ]
+        },
+        "include": {
+          "type": "string",
+          "description": "JSON:API `?include=` sideloads. Comma-list of relationship\nslots; each resolved to a per-resource entry in the response\n`included[]` array. Eliminates N+1 lookups for avatars /\nnames. Allowed slots: conversation, candidate, talent, user,\nboeUser, job, brief, schedule. Each included resource carries\n`attributes.name` plus type-specific extras (`avatarUrl` +\n`isBoe` for users, `company` for candidate/talent, `title` +\n`shortCode` for job, `subject` + `type` for conversation,\n`fireAt` + `status` for schedule)."
+        },
         "filterCreatedFrom": {
           "type": "string",
           "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format."
@@ -10853,6 +10920,16 @@
         "pageBefore": {
           "type": "string",
           "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+        },
+        "sort": {
+          "type": "string",
+          "description": "Sort order. Default `-created` (newest first). Currently\nsupports `-created`, `created`, `-modified`, `modified`. Sort\nby `-startedAt` / `-endedAt` / `-durationSec` deferred until\ncomposite GSIs land - see backend backlog #93.",
+          "enum": [
+            "-created",
+            "created",
+            "-modified",
+            "modified"
+          ]
         }
       }
     },
@@ -11070,6 +11147,116 @@
                   "type": "string",
                   "description": "Unique short identifier (provider/lookup correlation)."
                 },
+                "transcriptSegments": {
+                  "type": "array",
+                  "description": "Structured transcript with timing. Each segment is one turn captured live by the Realtime API. Single shape (NOT translated); text is in `languageCode`. Drives the audio player's clickable speaker timeline.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "startMs": {
+                        "type": "integer",
+                        "description": "Offset from call start in milliseconds when the speaker began this turn."
+                      },
+                      "endMs": {
+                        "type": "integer",
+                        "description": "Offset from call start in milliseconds when the speaker finished this turn."
+                      },
+                      "speakerType": {
+                        "type": "string",
+                        "enum": [
+                          "ai",
+                          "human"
+                        ],
+                        "description": "Which side spoke this turn."
+                      },
+                      "speakerName": {
+                        "type": "string",
+                        "description": "Display name of the speaker at write time."
+                      },
+                      "text": {
+                        "type": "string",
+                        "description": "What the speaker said, in `languageCode`."
+                      }
+                    }
+                  }
+                },
+                "speakerStats": {
+                  "type": "array",
+                  "description": "Per-speaker talk statistics computed once on call finalization. Used by the timeline UI to show talk-time bars.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "speakerType": {
+                        "type": "string",
+                        "enum": [
+                          "ai",
+                          "human"
+                        ]
+                      },
+                      "speakerName": {
+                        "type": "string"
+                      },
+                      "talkPercentageBp": {
+                        "type": "integer",
+                        "description": "Talk-time percentage in basis points (10000 = 100.00%). Integer to avoid float rounding mismatches across clients."
+                      }
+                    }
+                  }
+                },
+                "keyNotes": {
+                  "type": "array",
+                  "description": "AI-generated bullet points distilled from the transcript. In `languageCode` (NOT multilingual - single shape; FE renders as-is).",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "topicsDiscussed": {
+                  "type": "array",
+                  "description": "Stable facet keys (e.g. `salary`, `experience`, `languagesSpoken`) covered in the call. FE renders via shared `callTopics` dictionary for human-readable labels.",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "sentiment": {
+                  "type": "string",
+                  "enum": [
+                    "positive",
+                    "neutral",
+                    "negative",
+                    "mixed"
+                  ],
+                  "description": "AI-derived sentiment of the conversation as a whole."
+                },
+                "summaryGeneratedAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp when the AI summary pipeline (keyNotes + topicsDiscussed + sentiment + summary) finalized. Null until the post-call AI Step Function completes."
+                },
+                "folder": {
+                  "type": "string",
+                  "enum": [
+                    "drafts",
+                    "scheduled",
+                    "active",
+                    "incoming",
+                    "outgoing",
+                    "missed",
+                    "cancelled",
+                    "archived"
+                  ],
+                  "description": "Server-derived bucket for the left-nav / filter chips, computed from (direction, status). Mirror of email/chat folder. UI uses this directly; do NOT compute on the client."
+                },
+                "isLive": {
+                  "type": "boolean",
+                  "description": "Server-derived: true when status is in {queued, ringing, in-progress}. Drives the live indicator + polling decision in the UI."
+                },
+                "hasRecording": {
+                  "type": "boolean",
+                  "description": "Server-derived: true when recording.mixedMp3Url is present. Lets the list page show a play icon without sending the heavy `recording` block."
+                },
+                "hasTranscript": {
+                  "type": "boolean",
+                  "description": "Server-derived: true when transcriptSegments has any entries OR transcript dict has any locale keys. Lets the list page show a transcript icon without sending the heavy `transcript`/`transcriptSegments` payload."
+                },
                 "timestamps": {
                   "title": "ResourceTimestampsSchema",
                   "type": "object",
@@ -11273,7 +11460,12 @@
     "description": "Show Call",
     "inputSchema": {
       "type": "object",
-      "properties": {}
+      "properties": {
+        "include": {
+          "type": "string",
+          "description": "JSON:API `?include=` sideloads. Comma-list of relationship\nslots; each resolved entry is added to the response\n`included[]` array. Allowed slots: conversation, candidate,\ntalent, user, boeUser, job, brief, schedule."
+        }
+      }
     },
     "_meta": {
       "method": "GET",
@@ -11493,6 +11685,116 @@
                   "type": "string",
                   "description": "Unique short identifier (provider/lookup correlation)."
                 },
+                "transcriptSegments": {
+                  "type": "array",
+                  "description": "Structured transcript with timing. Each segment is one turn captured live by the Realtime API. Single shape (NOT translated); text is in `languageCode`. Drives the audio player's clickable speaker timeline.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "startMs": {
+                        "type": "integer",
+                        "description": "Offset from call start in milliseconds when the speaker began this turn."
+                      },
+                      "endMs": {
+                        "type": "integer",
+                        "description": "Offset from call start in milliseconds when the speaker finished this turn."
+                      },
+                      "speakerType": {
+                        "type": "string",
+                        "enum": [
+                          "ai",
+                          "human"
+                        ],
+                        "description": "Which side spoke this turn."
+                      },
+                      "speakerName": {
+                        "type": "string",
+                        "description": "Display name of the speaker at write time."
+                      },
+                      "text": {
+                        "type": "string",
+                        "description": "What the speaker said, in `languageCode`."
+                      }
+                    }
+                  }
+                },
+                "speakerStats": {
+                  "type": "array",
+                  "description": "Per-speaker talk statistics computed once on call finalization. Used by the timeline UI to show talk-time bars.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "speakerType": {
+                        "type": "string",
+                        "enum": [
+                          "ai",
+                          "human"
+                        ]
+                      },
+                      "speakerName": {
+                        "type": "string"
+                      },
+                      "talkPercentageBp": {
+                        "type": "integer",
+                        "description": "Talk-time percentage in basis points (10000 = 100.00%). Integer to avoid float rounding mismatches across clients."
+                      }
+                    }
+                  }
+                },
+                "keyNotes": {
+                  "type": "array",
+                  "description": "AI-generated bullet points distilled from the transcript. In `languageCode` (NOT multilingual - single shape; FE renders as-is).",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "topicsDiscussed": {
+                  "type": "array",
+                  "description": "Stable facet keys (e.g. `salary`, `experience`, `languagesSpoken`) covered in the call. FE renders via shared `callTopics` dictionary for human-readable labels.",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "sentiment": {
+                  "type": "string",
+                  "enum": [
+                    "positive",
+                    "neutral",
+                    "negative",
+                    "mixed"
+                  ],
+                  "description": "AI-derived sentiment of the conversation as a whole."
+                },
+                "summaryGeneratedAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp when the AI summary pipeline (keyNotes + topicsDiscussed + sentiment + summary) finalized. Null until the post-call AI Step Function completes."
+                },
+                "folder": {
+                  "type": "string",
+                  "enum": [
+                    "drafts",
+                    "scheduled",
+                    "active",
+                    "incoming",
+                    "outgoing",
+                    "missed",
+                    "cancelled",
+                    "archived"
+                  ],
+                  "description": "Server-derived bucket for the left-nav / filter chips, computed from (direction, status). Mirror of email/chat folder. UI uses this directly; do NOT compute on the client."
+                },
+                "isLive": {
+                  "type": "boolean",
+                  "description": "Server-derived: true when status is in {queued, ringing, in-progress}. Drives the live indicator + polling decision in the UI."
+                },
+                "hasRecording": {
+                  "type": "boolean",
+                  "description": "Server-derived: true when recording.mixedMp3Url is present. Lets the list page show a play icon without sending the heavy `recording` block."
+                },
+                "hasTranscript": {
+                  "type": "boolean",
+                  "description": "Server-derived: true when transcriptSegments has any entries OR transcript dict has any locale keys. Lets the list page show a transcript icon without sending the heavy `transcript`/`transcriptSegments` payload."
+                },
                 "timestamps": {
                   "title": "ResourceTimestampsSchema",
                   "type": "object",
@@ -11545,6 +11847,255 @@
       "operationId": "callOptions"
     }
   },
+  {
+    "name": "list_comments",
+    "description": "List Comments",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "filterTargetType": {
+          "type": "string",
+          "description": "Limit to comments on this resource type. Pair with filterTargetId.",
+          "enum": [
+            "calls",
+            "chats",
+            "emails",
+            "candidates",
+            "jobs",
+            "talents",
+            "briefs",
+            "tasks"
+          ]
+        },
+        "filterTargetId": {
+          "type": "string",
+          "description": "Limit to comments on this specific target id. Requires filterTargetType."
+        },
+        "filterAuthorId": {
+          "type": "string",
+          "description": "Limit to comments authored by this user. Indexed via AuthorIndex."
+        },
+        "filterIsResolved": {
+          "type": "boolean",
+          "description": "Filter by `isResolved` flag (true/false). Post-filtered after pagination - acceptable while resolution is rare."
+        },
+        "include": {
+          "type": "string",
+          "description": "JSON:API sideload. Currently supports `author` (resolves to the user row with name + avatarUrl + isBoe)."
+        },
+        "filterCreatedFrom": {
+          "type": "string",
+          "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format."
+        },
+        "filterCreatedTo": {
+          "type": "string",
+          "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format."
+        },
+        "filterModifiedFrom": {
+          "type": "string",
+          "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format."
+        },
+        "filterModifiedTo": {
+          "type": "string",
+          "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format."
+        },
+        "pageSize": {
+          "type": "integer",
+          "description": "Specifies the number of items to retrieve per page. The maximum value is 100."
+        },
+        "pageNumber": {
+          "type": "integer",
+          "description": "Specifies the page number to retrieve. Used for traditional pagination."
+        },
+        "pageAfter": {
+          "type": "string",
+          "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it."
+        },
+        "pageBefore": {
+          "type": "string",
+          "description": "Returns the data encoded in Base64 format, used for cursor-based pagination"
+        },
+        "sort": {
+          "type": "string",
+          "description": "Sort order. Default `-created` (newest first).",
+          "enum": [
+            "-created",
+            "created",
+            "-modified",
+            "modified"
+          ]
+        }
+      }
+    },
+    "_meta": {
+      "method": "GET",
+      "path": "/v1/comments",
+      "operationId": "listComments"
+    }
+  },
+  {
+    "name": "create_comment",
+    "description": "Create Comment",
+    "inputSchema": {
+      "title": "CreateCommentRequestSchema",
+      "type": "object",
+      "properties": {
+        "data": {
+          "type": "object",
+          "required": [
+            "type",
+            "attributes"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "comments"
+              ]
+            },
+            "attributes": {
+              "type": "object",
+              "required": [
+                "body",
+                "targetType",
+                "targetId"
+              ],
+              "properties": {
+                "body": {
+                  "type": "string",
+                  "maxLength": 5000
+                },
+                "targetType": {
+                  "type": "string",
+                  "enum": [
+                    "calls",
+                    "chats",
+                    "emails",
+                    "candidates",
+                    "jobs",
+                    "talents",
+                    "briefs",
+                    "tasks"
+                  ]
+                },
+                "targetId": {
+                  "type": "string"
+                },
+                "parentCommentId": {
+                  "type": "string"
+                },
+                "mentionedUserIds": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "isResolved": {
+                  "type": "boolean"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "_meta": {
+      "method": "POST",
+      "path": "/v1/comments",
+      "operationId": "createComment"
+    }
+  },
+  {
+    "name": "show_comment",
+    "description": "Show Comment",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "include": {
+          "type": "string",
+          "description": "JSON:API sideload. `author` resolves the user row."
+        }
+      }
+    },
+    "_meta": {
+      "method": "GET",
+      "path": "/v1/comments/{commentId}",
+      "operationId": "showComment"
+    }
+  },
+  {
+    "name": "update_comment",
+    "description": "Update Comment",
+    "inputSchema": {
+      "title": "UpdateCommentRequestSchema",
+      "type": "object",
+      "properties": {
+        "data": {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "comments"
+              ]
+            },
+            "id": {
+              "type": "string"
+            },
+            "attributes": {
+              "type": "object",
+              "description": "Patchable fields. Only `body`, `isResolved`, and `mentionedUserIds` are editable. Edit by author OR tenant admin/owner; others get 403.",
+              "properties": {
+                "body": {
+                  "type": "string",
+                  "maxLength": 5000
+                },
+                "isResolved": {
+                  "type": "boolean"
+                },
+                "mentionedUserIds": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "_meta": {
+      "method": "PATCH",
+      "path": "/v1/comments/{commentId}",
+      "operationId": "updateComment"
+    }
+  },
+  {
+    "name": "delete_comment",
+    "description": "Delete Comment",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "permanentDelete": {
+          "type": "string",
+          "description": "Set to `true` for hard-delete. Default is soft-delete (status=archived).",
+          "enum": [
+            "true",
+            "false"
+          ]
+        }
+      }
+    },
+    "_meta": {
+      "method": "DELETE",
+      "path": "/v1/comments/{commentId}",
+      "operationId": "deleteComment"
+    }
+  },
   {
     "name": "list_chats",
     "description": "List Chats",
@@ -12776,6 +13327,9 @@
           "description": "Only return states for this resource type.",
           "enum": [
             "emails",
+            "chats",
+            "calls",
+            "comments",
             "candidates",
             "conversations",
             "jobs",
@@ -13097,10 +13651,12 @@
       "properties": {
         "filterResourceType": {
           "type": "string",
-          "description": "Only return aggregates for this resource type (e.g. emails, chats).",
+          "description": "Only return aggregates for this resource type (e.g. emails, chats, calls, comments).",
           "enum": [
             "emails",
             "chats",
+            "calls",
+            "comments",
             "candidates",
             "conversations",
             "jobs",
@@ -15946,7 +16502,7 @@
         },
         "filterCategory": {
           "type": "string",
-          "description": "Filter by category (sourcing, screening, assessment, onboarding, operational, general). Uses CategoryIndex GSI — efficient at scale.",
+          "description": "Filter by category (sourcing, screening, assessment, onboarding, operational, general). Uses CategoryIndex GSI - efficient at scale.",
           "enum": [
             "sourcing",
             "screening",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartytalent/mcp-tools",
-  "version": "0.1.33-dev.27",
+  "version": "0.1.33-dev.29",
   "description": "MCP tool definitions for SmartyTalent API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",