@transcend-io/mcp-server-assessment 0.3.19 → 0.4.0

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.
@@ -1,1117 +0,0 @@
1
- import { PaginationSchema, TranscendGraphQLBase, createListResult, createToolResult, defineTool, z } from "@transcend-io/mcp-server-base";
2
- import { AssessmentFormStatus, AssessmentFormTemplateStatus } from "@transcend-io/privacy-types";
3
- //#region src/tools/assessments_add_section.ts
4
- const AddSectionSchema = z.object({
5
- template_id: z.string().describe("ID of the assessment form template to add the section to"),
6
- title: z.string().describe("Title of the new section"),
7
- questions: z.array(z.record(z.string(), z.unknown())).optional().describe("Array of question objects: [{title, type, subType?, description?, placeholder?, isRequired?, referenceId?, answerOptions?: [{value}], allowSelectOther?, requireRiskEvaluation?}]")
8
- });
9
- function createAssessmentsAddSectionTool(clients) {
10
- const graphql = clients.graphql;
11
- return defineTool({
12
- name: "assessments_add_section",
13
- description: "Add a new section (with optional inline questions) to an existing assessment form template. Useful for building templates incrementally or adding sections to imported templates. Same auto-corrections as assessments_create_template apply to questions.",
14
- category: "Assessments",
15
- readOnly: false,
16
- confirmationHint: "Adds a section to the assessment template",
17
- annotations: {
18
- readOnlyHint: false,
19
- destructiveHint: false,
20
- idempotentHint: false
21
- },
22
- zodSchema: AddSectionSchema,
23
- handler: async ({ template_id, title, questions }) => {
24
- return createToolResult(true, {
25
- section: await graphql.createAssessmentSection({
26
- assessmentFormTemplateId: template_id,
27
- title,
28
- questions
29
- }),
30
- message: `Section "${title}" added to template successfully`
31
- });
32
- }
33
- });
34
- }
35
- //#endregion
36
- //#region src/tools/assessments_answer_question.ts
37
- const AnswerQuestionValueSchema = z.object({
38
- value: z.string(),
39
- isUserCreated: z.boolean()
40
- });
41
- const AnswerQuestionSchema = z.object({
42
- assessment_question_id: z.string().describe("ID of the assessment question to answer"),
43
- assessment_answer_ids: z.array(z.string()).optional().describe("IDs of existing answer options to select (for SINGLE_SELECT/MULTI_SELECT questions)"),
44
- assessment_answer_values: z.array(AnswerQuestionValueSchema).optional().describe("Free-text answer values to create and select (for text questions). Each item: {value: string, isUserCreated: boolean}")
45
- });
46
- function createAssessmentsAnswerQuestionTool(clients) {
47
- const graphql = clients.graphql;
48
- return defineTool({
49
- name: "assessments_answer_question",
50
- description: "Answer an assessment question by selecting existing answer options or providing free-text values. For SINGLE_SELECT/MULTI_SELECT questions, provide assessmentAnswerIds from the answerOptions. For SHORT_ANSWER_TEXT/LONG_ANSWER_TEXT, provide assessmentAnswerValues with {value, isUserCreated: true}.",
51
- category: "Assessments",
52
- readOnly: false,
53
- confirmationHint: "Records answer to the assessment question",
54
- annotations: {
55
- readOnlyHint: false,
56
- destructiveHint: false,
57
- idempotentHint: true
58
- },
59
- zodSchema: AnswerQuestionSchema,
60
- handler: async ({ assessment_question_id, assessment_answer_ids, assessment_answer_values }) => {
61
- const input = { assessmentQuestionId: assessment_question_id };
62
- if (assessment_answer_ids) input.assessmentAnswerIds = assessment_answer_ids;
63
- if (assessment_answer_values) input.assessmentAnswerValues = assessment_answer_values;
64
- return createToolResult(true, {
65
- selectedAnswers: await graphql.selectAssessmentQuestionAnswers(input),
66
- message: "Assessment question answered successfully"
67
- });
68
- }
69
- });
70
- }
71
- //#endregion
72
- //#region src/helpers/buildAssessmentLinks.ts
73
- /**
74
- * Build the canonical admin-dashboard deep link for an assessment.
75
- *
76
- * Always points at `/assessments/forms/:id/response`, mirroring the
77
- * dashboard's own "View Responses" row action. The fillable
78
- * `/assessments/forms/:id/view` route is intentionally not emitted —
79
- * it only resolves for the form's assignee, which the MCP can't verify.
80
- */
81
- function buildAssessmentLinks({ dashboardUrl, assessmentFormId }) {
82
- return { url: `${dashboardUrl.replace(/\/$/, "")}/assessments/forms/${assessmentFormId}/response` };
83
- }
84
- /** Build a link to the assessment-group page (for group-level tools). */
85
- function buildAssessmentGroupUrl(dashboardUrl, assessmentGroupId) {
86
- return `${dashboardUrl.replace(/\/$/, "")}/assessments/groups/${assessmentGroupId}`;
87
- }
88
- //#endregion
89
- //#region src/tools/_helpers.ts
90
- /**
91
- * Resolves a template_id to an assessment group ID by searching through all groups.
92
- * Returns either the group ID or an error result.
93
- */
94
- async function resolveTemplateToGroupId(graphql, templateId) {
95
- const matchingGroups = (await graphql.listAssessmentGroups({ first: 100 })).nodes.filter((g) => g.assessmentFormTemplate?.id === templateId);
96
- if (matchingGroups.length === 0) return { error: createToolResult(false, void 0, `No assessment group found for template_id "${templateId}". Use assessments_list_groups to see available groups.`) };
97
- if (matchingGroups.length > 1) return { error: createToolResult(false, void 0, `Multiple assessment groups found for template_id "${templateId}" (group IDs: ${matchingGroups.map((g) => g.id).join(", ")}). Please specify assessment_group_id explicitly. Use assessments_list_groups to find available groups.`) };
98
- return { groupId: matchingGroups[0].id };
99
- }
100
- //#endregion
101
- //#region src/tools/assessments_create.ts
102
- const CreateAssessmentSchema = z.object({
103
- title: z.string().describe("Title of the assessment"),
104
- assessment_group_id: z.string().optional().describe("ID of the assessment group to create the assessment in (preferred). Use assessments_list_groups to find available groups."),
105
- template_id: z.string().optional().describe("ID of the assessment template. If assessment_group_id is not provided, the first group using this template will be used."),
106
- assignee_ids: z.array(z.string()).optional().describe("Array of user IDs to assign the assessment to")
107
- });
108
- function createAssessmentsCreateTool(clients) {
109
- const graphql = clients.graphql;
110
- const { dashboardUrl } = clients;
111
- return defineTool({
112
- name: "assessments_create",
113
- description: "Create a new privacy assessment within an assessment group. Assessment groups are linked to templates. You can provide either an assessment_group_id directly, or a template_id to auto-resolve the first matching group. Use assessments_list_groups to find available groups. The response includes a `url` field with the canonical admin-dashboard link — surface that to the user verbatim and do not construct assessment URLs from raw IDs.",
114
- category: "Assessments",
115
- readOnly: false,
116
- confirmationHint: "Creates a new privacy assessment",
117
- annotations: {
118
- readOnlyHint: false,
119
- destructiveHint: false,
120
- idempotentHint: false
121
- },
122
- zodSchema: CreateAssessmentSchema,
123
- handler: async ({ title, assessment_group_id, template_id, assignee_ids }) => {
124
- let assessmentGroupId = assessment_group_id;
125
- if (!assessmentGroupId && template_id) {
126
- const resolved = await resolveTemplateToGroupId(graphql, template_id);
127
- if ("error" in resolved) return resolved.error;
128
- assessmentGroupId = resolved.groupId;
129
- }
130
- if (!assessmentGroupId) return createToolResult(false, void 0, "Either assessment_group_id or template_id must be provided. Use assessments_list_groups to find available groups.");
131
- const result = await graphql.createAssessment({
132
- title,
133
- assessmentGroupId,
134
- assigneeIds: assignee_ids
135
- });
136
- const links = buildAssessmentLinks({
137
- dashboardUrl,
138
- assessmentFormId: result.id
139
- });
140
- return createToolResult(true, {
141
- assessment: {
142
- ...result,
143
- ...links
144
- },
145
- ...links,
146
- message: `Assessment "${title}" created successfully. Open it at ${links.url}`
147
- });
148
- }
149
- });
150
- }
151
- //#endregion
152
- //#region src/tools/assessments_create_group.ts
153
- const CreateGroupSchema = z.object({
154
- title: z.string().describe("Title of the assessment group"),
155
- template_id: z.string().describe("ID of the assessment template to link this group to"),
156
- description: z.string().optional().describe("Description of the assessment group (optional)"),
157
- reviewer_ids: z.array(z.string()).optional().describe("IDs of users assigned to review new assessments in this group (optional)")
158
- });
159
- function createAssessmentsCreateGroupTool(clients) {
160
- const graphql = clients.graphql;
161
- const { dashboardUrl } = clients;
162
- return defineTool({
163
- name: "assessments_create_group",
164
- description: "Create a new assessment group linked to a template. Assessment groups are containers for assessments. The response includes a `groupUrl` field with the canonical admin-dashboard link to the group — surface that to the user verbatim.",
165
- category: "Assessments",
166
- readOnly: false,
167
- confirmationHint: "Creates a new assessment group",
168
- annotations: {
169
- readOnlyHint: false,
170
- destructiveHint: false,
171
- idempotentHint: false
172
- },
173
- zodSchema: CreateGroupSchema,
174
- handler: async ({ title, template_id, description, reviewer_ids }) => {
175
- const result = await graphql.createAssessmentGroup({
176
- title,
177
- assessmentFormTemplateId: template_id,
178
- description,
179
- reviewerIds: reviewer_ids
180
- });
181
- const groupUrl = buildAssessmentGroupUrl(dashboardUrl, result.id);
182
- return createToolResult(true, {
183
- assessmentGroup: {
184
- ...result,
185
- groupUrl
186
- },
187
- groupUrl,
188
- message: `Assessment group "${title}" created successfully. View it at ${groupUrl}`
189
- });
190
- }
191
- });
192
- }
193
- //#endregion
194
- //#region src/tools/assessments_create_template.ts
195
- const CreateTemplateSchema = z.object({
196
- title: z.string().describe("Title of the assessment form template"),
197
- description: z.string().optional().describe("Description of the template"),
198
- status: z.nativeEnum(AssessmentFormTemplateStatus).optional().describe("Template status: DRAFT or PUBLISHED (default: DRAFT)"),
199
- sections: z.array(z.record(z.string(), z.unknown())).optional().describe("Array of section objects with title and optional questions array")
200
- });
201
- function createAssessmentsCreateTemplateTool(clients) {
202
- const graphql = clients.graphql;
203
- return defineTool({
204
- name: "assessments_create_template",
205
- description: "Create a new assessment form template with sections and questions inline. This is the \"import\" side of the JSON import/export workflow. You can provide the full template structure (sections with questions and answer options) in a single call. Question types: LONG_ANSWER_TEXT, SHORT_ANSWER_TEXT, SINGLE_SELECT, MULTI_SELECT, FILE. SubTypes: NONE, CUSTOM, USER, TEAM, DATA_SUB_CATEGORY, HAS_PERSONAL_DATA, ATTRIBUTE_KEY, SENSITIVE_CATEGORY. Auto-corrections: referenceId is auto-generated as UUID if missing or not UUID format; subType is auto-set to CUSTOM when allowSelectOther is true; requireRiskEvaluation is ignored when no riskFrameworkId is provided.",
206
- category: "Assessments",
207
- readOnly: false,
208
- confirmationHint: "Creates a new assessment form template",
209
- annotations: {
210
- readOnlyHint: false,
211
- destructiveHint: false,
212
- idempotentHint: false
213
- },
214
- zodSchema: CreateTemplateSchema,
215
- handler: async ({ title, description, status, sections }) => {
216
- const input = {
217
- title,
218
- description,
219
- status: status ?? "DRAFT",
220
- sections
221
- };
222
- return createToolResult(true, {
223
- template: await graphql.createAssessmentFormTemplate(input),
224
- message: `Assessment template "${title}" created successfully`
225
- });
226
- }
227
- });
228
- }
229
- //#endregion
230
- //#region src/tools/assessments_export_template.ts
231
- const ExportTemplateSchema = z.object({ template_id: z.string().describe("ID of the assessment form template to export") });
232
- function createAssessmentsExportTemplateTool(clients) {
233
- const graphql = clients.graphql;
234
- return defineTool({
235
- name: "assessments_export_template",
236
- description: "Export a full assessment form template as JSON, including all sections, questions, answer options, and configuration. This is the \"export\" side of the JSON import/export workflow. The output can be used as input for assessments_create_template to recreate the template elsewhere.",
237
- category: "Assessments",
238
- readOnly: true,
239
- annotations: {
240
- readOnlyHint: true,
241
- destructiveHint: false,
242
- idempotentHint: true
243
- },
244
- zodSchema: ExportTemplateSchema,
245
- handler: async ({ template_id }) => {
246
- const template = await graphql.getAssessmentFormTemplate(template_id);
247
- return createToolResult(true, {
248
- _exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
249
- _format: "transcend-assessment-template-v1",
250
- template: {
251
- title: template.title,
252
- description: template.description,
253
- status: template.status,
254
- sections: template.sections.map((section) => ({
255
- title: section.title,
256
- questions: section.questions.map((q) => ({
257
- title: q.title,
258
- type: q.type,
259
- subType: q.subType,
260
- description: q.description,
261
- placeholder: q.placeholder,
262
- isRequired: q.isRequired,
263
- referenceId: q.referenceId,
264
- allowSelectOther: q.allowSelectOther,
265
- requireRiskEvaluation: q.requireRiskEvaluation,
266
- answerOptions: q.answerOptions.map((opt) => ({ value: opt.value }))
267
- }))
268
- }))
269
- },
270
- _raw: template
271
- });
272
- }
273
- });
274
- }
275
- //#endregion
276
- //#region src/tools/assessments_get.ts
277
- const GetAssessmentSchema = z.object({
278
- assessment_id: z.string().describe("ID of the assessment to retrieve"),
279
- assessment_name: z.string().optional().describe("Optional human-readable name (e.g. title) for the tool call in chat; not sent to the API.")
280
- });
281
- function createAssessmentsGetTool(clients) {
282
- const graphql = clients.graphql;
283
- const { dashboardUrl } = clients;
284
- return defineTool({
285
- name: "assessments_get",
286
- description: "Get detailed information about a specific assessment including questions and responses. The response includes a `url` field with the canonical admin-dashboard link — surface that to the user verbatim and do not construct assessment URLs from raw IDs.",
287
- category: "Assessments",
288
- readOnly: true,
289
- annotations: {
290
- readOnlyHint: true,
291
- destructiveHint: false,
292
- idempotentHint: true
293
- },
294
- zodSchema: GetAssessmentSchema,
295
- handler: async ({ assessment_id }) => {
296
- const result = await graphql.getAssessment(assessment_id);
297
- const links = buildAssessmentLinks({
298
- dashboardUrl,
299
- assessmentFormId: result.id
300
- });
301
- return createToolResult(true, {
302
- ...result,
303
- ...links
304
- });
305
- }
306
- });
307
- }
308
- //#endregion
309
- //#region src/tools/assessments_list.ts
310
- const AssessmentStatusEnum = z.nativeEnum(AssessmentFormStatus);
311
- const ListAssessmentsSchema = z.object({ status: AssessmentStatusEnum.optional().describe("Filter by assessment status") }).merge(PaginationSchema);
312
- function createAssessmentsListTool(clients) {
313
- const graphql = clients.graphql;
314
- const { dashboardUrl } = clients;
315
- return defineTool({
316
- name: "assessments_list",
317
- description: "List all privacy assessments in your organization. Supports filtering by status. Each row includes a `url` field with the canonical admin-dashboard link for that assessment — surface those to the user verbatim and do not construct assessment URLs from raw IDs. Note: Cursor pagination is not supported (max 100 results).",
318
- category: "Assessments",
319
- readOnly: true,
320
- annotations: {
321
- readOnlyHint: true,
322
- destructiveHint: false,
323
- idempotentHint: true
324
- },
325
- zodSchema: ListAssessmentsSchema,
326
- handler: async ({ status, limit, cursor }) => {
327
- const result = await graphql.listAssessments({
328
- first: limit,
329
- after: cursor,
330
- filterBy: status ? { statuses: [status] } : void 0
331
- });
332
- return createListResult(result.nodes.map((node) => ({
333
- ...node,
334
- ...buildAssessmentLinks({
335
- dashboardUrl,
336
- assessmentFormId: node.id
337
- })
338
- })), {
339
- totalCount: result.totalCount,
340
- hasNextPage: result.pageInfo?.hasNextPage
341
- });
342
- }
343
- });
344
- }
345
- //#endregion
346
- //#region src/tools/assessments_list_groups.ts
347
- const ListGroupsSchema = PaginationSchema;
348
- function createAssessmentsListGroupsTool(clients) {
349
- const graphql = clients.graphql;
350
- const { dashboardUrl } = clients;
351
- return defineTool({
352
- name: "assessments_list_groups",
353
- description: "List all assessment groups. Groups are containers for assessments and are linked to templates. Use this to find the right group ID for creating assessments. Each row includes a `groupUrl` field with the canonical admin-dashboard link — surface those to the user verbatim.",
354
- category: "Assessments",
355
- readOnly: true,
356
- annotations: {
357
- readOnlyHint: true,
358
- destructiveHint: false,
359
- idempotentHint: true
360
- },
361
- zodSchema: ListGroupsSchema,
362
- handler: async ({ limit, cursor }) => {
363
- const result = await graphql.listAssessmentGroups({
364
- first: limit,
365
- after: cursor
366
- });
367
- return createListResult(result.nodes.map((node) => ({
368
- ...node,
369
- groupUrl: buildAssessmentGroupUrl(dashboardUrl, node.id)
370
- })), {
371
- totalCount: result.totalCount,
372
- hasNextPage: result.pageInfo?.hasNextPage
373
- });
374
- }
375
- });
376
- }
377
- //#endregion
378
- //#region src/tools/assessments_list_templates.ts
379
- const ListTemplatesSchema = PaginationSchema;
380
- function createAssessmentsListTemplatesTool(clients) {
381
- const graphql = clients.graphql;
382
- return defineTool({
383
- name: "assessments_list_templates",
384
- description: "List all available assessment templates. Note: Cursor pagination is not supported by the Transcend API for templates - use limit to control results (max 100).",
385
- category: "Assessments",
386
- readOnly: true,
387
- annotations: {
388
- readOnlyHint: true,
389
- destructiveHint: false,
390
- idempotentHint: true
391
- },
392
- zodSchema: ListTemplatesSchema,
393
- handler: async ({ limit, cursor }) => {
394
- const result = await graphql.listAssessmentTemplates({
395
- first: limit,
396
- after: cursor
397
- });
398
- return createListResult(result.nodes, {
399
- totalCount: result.totalCount,
400
- hasNextPage: result.pageInfo?.hasNextPage
401
- });
402
- }
403
- });
404
- }
405
- //#endregion
406
- //#region src/tools/assessments_prefill.ts
407
- const PrefillSchema = z.object({
408
- title: z.string().describe("Title for the new assessment form"),
409
- template_id: z.string().optional().describe("Template ID to create the form from. Will auto-resolve to the first matching assessment group."),
410
- assessment_group_id: z.string().optional().describe("Assessment group ID (alternative to template_id)"),
411
- answers: z.record(z.string(), z.union([z.string(), z.array(z.string())])).describe("Map of answers keyed by question title or referenceId. Values should be strings for text/single-select, or arrays of strings for multi-select."),
412
- assignee_ids: z.array(z.string()).optional().describe("Internal user IDs to assign the form to (optional)"),
413
- assignee_emails: z.array(z.string()).optional().describe("External email addresses to assign the form to (optional)"),
414
- reviewer_ids: z.array(z.string()).optional().describe("User IDs to set as reviewers (optional)"),
415
- submit_for_review: z.boolean().optional().describe("Whether to automatically submit the form for review after prefilling (default: false)")
416
- });
417
- function createAssessmentsPrefillTool(clients) {
418
- const graphql = clients.graphql;
419
- return defineTool({
420
- name: "assessments_prefill",
421
- description: "Convenience tool: Create a new assessment form, AI-prefill all the answers, and assign it to a reviewer. Combines: create form → get questions → answer each question → assign reviewers → optionally submit for review. Provide answers as a map of {questionTitle: answer} or {referenceId: answer}. For SINGLE_SELECT/MULTI_SELECT, the answer should match the exact text of the answer option(s). For text questions, provide the free-text answer string. For multi-select, provide an array of answer option values.",
422
- category: "Assessments",
423
- readOnly: false,
424
- confirmationHint: "Creates assessment, prefills answers, assigns reviewers",
425
- annotations: {
426
- readOnlyHint: false,
427
- destructiveHint: false,
428
- idempotentHint: false
429
- },
430
- zodSchema: PrefillSchema,
431
- handler: async ({ answers, title, assessment_group_id, template_id, assignee_ids, assignee_emails, reviewer_ids, submit_for_review }) => {
432
- let assessmentGroupId = assessment_group_id;
433
- if (!assessmentGroupId && template_id) {
434
- const resolved = await resolveTemplateToGroupId(graphql, template_id);
435
- if ("error" in resolved) return resolved.error;
436
- assessmentGroupId = resolved.groupId;
437
- }
438
- if (!assessmentGroupId) return createToolResult(false, void 0, "Either template_id or assessment_group_id is required.");
439
- const assessmentId = (await graphql.createAssessment({
440
- title,
441
- assessmentGroupId
442
- })).id;
443
- const fullForm = await graphql.getAssessment(assessmentId);
444
- if (!fullForm.sections || fullForm.sections.length === 0) return createToolResult(true, {
445
- assessment: fullForm,
446
- message: "Assessment created but has no sections/questions to prefill.",
447
- answersApplied: 0
448
- });
449
- const results = [];
450
- let answersApplied = 0;
451
- let answersSkipped = 0;
452
- for (const section of fullForm.sections) {
453
- if (!section.questions) continue;
454
- for (const question of section.questions) {
455
- const answerKey = Object.keys(answers).find((key) => key === question.referenceId || key.toLowerCase() === (question.title || "").toLowerCase() || key === question.id);
456
- if (!answerKey) {
457
- results.push({
458
- question: question.title || question.id,
459
- status: "skipped"
460
- });
461
- answersSkipped++;
462
- continue;
463
- }
464
- const answerValue = answers[answerKey];
465
- if (answerValue === void 0) {
466
- results.push({
467
- question: question.title || question.id,
468
- status: "skipped"
469
- });
470
- answersSkipped++;
471
- continue;
472
- }
473
- try {
474
- const qType = (question.type || "").toUpperCase();
475
- if (qType === "SINGLE_SELECT" || qType === "MULTI_SELECT") {
476
- const answerValues = Array.isArray(answerValue) ? answerValue : [answerValue];
477
- const matchedIds = [];
478
- for (const val of answerValues) {
479
- const matchedOption = (question.answerOptions || []).find((opt) => opt.value.toLowerCase() === val.toLowerCase());
480
- if (matchedOption) matchedIds.push(matchedOption.id);
481
- }
482
- if (matchedIds.length > 0) {
483
- await graphql.selectAssessmentQuestionAnswers({
484
- assessmentQuestionId: question.id,
485
- assessmentAnswerIds: matchedIds
486
- });
487
- answersApplied++;
488
- results.push({
489
- question: question.title || question.id,
490
- status: "answered",
491
- answer: answerValues.join(", ")
492
- });
493
- } else {
494
- await graphql.selectAssessmentQuestionAnswers({
495
- assessmentQuestionId: question.id,
496
- assessmentAnswerValues: answerValues.map((v) => ({
497
- value: v,
498
- isUserCreated: true
499
- }))
500
- });
501
- answersApplied++;
502
- results.push({
503
- question: question.title || question.id,
504
- status: "answered (custom value)",
505
- answer: answerValues.join(", ")
506
- });
507
- }
508
- } else {
509
- const textValue = Array.isArray(answerValue) ? answerValue.join("\n") : answerValue;
510
- await graphql.selectAssessmentQuestionAnswers({
511
- assessmentQuestionId: question.id,
512
- assessmentAnswerValues: [{
513
- value: textValue,
514
- isUserCreated: true
515
- }]
516
- });
517
- answersApplied++;
518
- results.push({
519
- question: question.title || question.id,
520
- status: "answered",
521
- answer: textValue.length > 100 ? textValue.substring(0, 100) + "..." : textValue
522
- });
523
- }
524
- } catch (err) {
525
- results.push({
526
- question: question.title || question.id,
527
- status: `error: ${err instanceof Error ? err.message : String(err)}`
528
- });
529
- }
530
- }
531
- }
532
- let assignmentResult = null;
533
- if (assignee_ids || assignee_emails) assignmentResult = await graphql.updateAssessmentFormAssignees({
534
- id: assessmentId,
535
- assigneeIds: assignee_ids,
536
- externalAssigneeEmails: assignee_emails
537
- });
538
- if (reviewer_ids) await graphql.updateAssessment({
539
- id: assessmentId,
540
- reviewerIds: reviewer_ids
541
- });
542
- let submitResult = null;
543
- if (submit_for_review) {
544
- const sectionIds = fullForm.sections.map((s) => s.id);
545
- if (sectionIds.length > 0) submitResult = await graphql.submitAssessmentForReview({
546
- id: assessmentId,
547
- assessmentSectionIds: sectionIds
548
- });
549
- }
550
- return createToolResult(true, {
551
- assessmentId,
552
- title,
553
- answersApplied,
554
- answersSkipped,
555
- totalQuestions: results.length,
556
- results,
557
- assignment: assignmentResult ? {
558
- status: assignmentResult.status,
559
- message: "Assignees updated"
560
- } : null,
561
- submittedForReview: !!submitResult,
562
- message: `Assessment "${title}" created and prefilled with ${answersApplied}/${results.length} answers. ` + (assignmentResult ? `Assigned to reviewers. ` : "") + (submitResult ? "Submitted for review." : "Ready for manual submission.")
563
- });
564
- }
565
- });
566
- }
567
- //#endregion
568
- //#region src/tools/assessments_submit_response.ts
569
- const SubmitResponseSchema = z.object({
570
- assessment_id: z.string().describe("ID of the assessment to submit for review"),
571
- assessment_section_ids: z.array(z.string()).describe("Array of section IDs to submit for review. Required by the API.")
572
- });
573
- function createAssessmentsSubmitResponseTool(clients) {
574
- const graphql = clients.graphql;
575
- const { dashboardUrl } = clients;
576
- return defineTool({
577
- name: "assessments_submit_response",
578
- description: "Submit an assessment form for review. Optionally specify which sections to submit. This transitions the assessment toward the IN_REVIEW status. The response includes a `url` field pointing at the assessment-group page where reviewers can find the submitted form — surface that to the user verbatim and do not construct assessment URLs from raw IDs.",
579
- category: "Assessments",
580
- readOnly: false,
581
- confirmationHint: "Submits assessment for review — cannot be undone",
582
- annotations: {
583
- readOnlyHint: false,
584
- destructiveHint: true,
585
- idempotentHint: false
586
- },
587
- zodSchema: SubmitResponseSchema,
588
- handler: async ({ assessment_id, assessment_section_ids }) => {
589
- const result = await graphql.submitAssessmentForReview({
590
- id: assessment_id,
591
- assessmentSectionIds: assessment_section_ids
592
- });
593
- const links = buildAssessmentLinks({
594
- dashboardUrl,
595
- assessmentFormId: result.id
596
- });
597
- return createToolResult(true, {
598
- assessment: {
599
- ...result,
600
- ...links
601
- },
602
- ...links,
603
- message: `Assessment submitted for review successfully. View it at ${links.url}`
604
- });
605
- }
606
- });
607
- }
608
- //#endregion
609
- //#region src/tools/assessments_update.ts
610
- const UpdateAssessmentSchema = z.object({
611
- assessment_id: z.string().describe("ID of the assessment to update"),
612
- title: z.string().optional().describe("New title for the assessment"),
613
- description: z.string().optional().describe("New description"),
614
- reviewer_ids: z.array(z.string()).optional().describe("IDs of users assigned to review this assessment"),
615
- due_date: z.string().optional().describe("New due date (ISO format)"),
616
- status: AssessmentStatusEnum.optional().describe("New status")
617
- });
618
- function createAssessmentsUpdateTool(clients) {
619
- const graphql = clients.graphql;
620
- const { dashboardUrl } = clients;
621
- return defineTool({
622
- name: "assessments_update",
623
- description: "Update an existing assessment. The response includes a `url` field with the canonical admin-dashboard link — surface that to the user verbatim and do not construct assessment URLs from raw IDs.",
624
- category: "Assessments",
625
- readOnly: false,
626
- confirmationHint: "Updates the assessment",
627
- annotations: {
628
- readOnlyHint: false,
629
- destructiveHint: false,
630
- idempotentHint: true
631
- },
632
- zodSchema: UpdateAssessmentSchema,
633
- handler: async ({ assessment_id, title, description, reviewer_ids, due_date, status }) => {
634
- const result = await graphql.updateAssessment({
635
- id: assessment_id,
636
- title,
637
- description,
638
- reviewerIds: reviewer_ids,
639
- dueDate: due_date,
640
- status
641
- });
642
- const links = buildAssessmentLinks({
643
- dashboardUrl,
644
- assessmentFormId: result.id
645
- });
646
- return createToolResult(true, {
647
- assessment: {
648
- ...result,
649
- ...links
650
- },
651
- ...links,
652
- message: `Assessment updated successfully. View it at ${links.url}`
653
- });
654
- }
655
- });
656
- }
657
- //#endregion
658
- //#region src/tools/assessments_update_assignees.ts
659
- const UpdateAssigneesSchema = z.object({
660
- assessment_id: z.string().describe("ID of the assessment form to update assignees for"),
661
- assignee_ids: z.array(z.string()).optional().describe("Array of internal user IDs to assign to the assessment"),
662
- external_assignee_emails: z.array(z.string()).optional().describe("Array of external email addresses to assign to the assessment")
663
- });
664
- function createAssessmentsUpdateAssigneesTool(clients) {
665
- const graphql = clients.graphql;
666
- return defineTool({
667
- name: "assessments_update_assignees",
668
- description: "Assign internal users (by ID) or external users (by email) to an assessment form. This also transitions DRAFT assessments to SHARED status.",
669
- category: "Assessments",
670
- readOnly: false,
671
- confirmationHint: "Assigns users to the assessment form",
672
- annotations: {
673
- readOnlyHint: false,
674
- destructiveHint: false,
675
- idempotentHint: true
676
- },
677
- zodSchema: UpdateAssigneesSchema,
678
- handler: async ({ assessment_id, assignee_ids, external_assignee_emails }) => {
679
- const result = await graphql.updateAssessmentFormAssignees({
680
- id: assessment_id,
681
- assigneeIds: assignee_ids,
682
- externalAssigneeEmails: external_assignee_emails
683
- });
684
- return createToolResult(true, {
685
- assessment: result,
686
- message: `Assessment assignees updated successfully. Status: ${result.status}`
687
- });
688
- }
689
- });
690
- }
691
- //#endregion
692
- //#region src/tools/index.ts
693
- function getAssessmentTools(clients) {
694
- return [
695
- createAssessmentsListTool(clients),
696
- createAssessmentsGetTool(clients),
697
- createAssessmentsCreateTool(clients),
698
- createAssessmentsCreateGroupTool(clients),
699
- createAssessmentsListGroupsTool(clients),
700
- createAssessmentsUpdateTool(clients),
701
- createAssessmentsListTemplatesTool(clients),
702
- createAssessmentsUpdateAssigneesTool(clients),
703
- createAssessmentsAnswerQuestionTool(clients),
704
- createAssessmentsSubmitResponseTool(clients),
705
- createAssessmentsCreateTemplateTool(clients),
706
- createAssessmentsAddSectionTool(clients),
707
- createAssessmentsExportTemplateTool(clients),
708
- createAssessmentsPrefillTool(clients)
709
- ];
710
- }
711
- //#endregion
712
- //#region src/graphql.ts
713
- const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
714
- function generateUUID() {
715
- return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
716
- const r = Math.random() * 16 | 0;
717
- return (c === "x" ? r : r & 3 | 8).toString(16);
718
- });
719
- }
720
- function normalizeQuestion(q) {
721
- let { referenceId, subType, allowSelectOther, requireRiskEvaluation } = q;
722
- if (!referenceId || !UUID_RE.test(referenceId)) referenceId = generateUUID();
723
- if (allowSelectOther && (!subType || subType === "NONE")) subType = "CUSTOM";
724
- if (requireRiskEvaluation && !q.riskFrameworkId) requireRiskEvaluation = false;
725
- return {
726
- title: q.title,
727
- type: q.type,
728
- subType: subType || "NONE",
729
- placeholder: q.placeholder || "",
730
- description: q.description || "",
731
- isRequired: q.isRequired ?? false,
732
- referenceId,
733
- answerOptions: q.answerOptions || [],
734
- allowSelectOther: allowSelectOther ?? false,
735
- requireRiskEvaluation: requireRiskEvaluation ?? false,
736
- ...q.riskLogic && { riskLogic: q.riskLogic },
737
- ...q.riskCategoryIds && { riskCategoryIds: q.riskCategoryIds },
738
- ...q.riskFrameworkId && { riskFrameworkId: q.riskFrameworkId },
739
- ...q.displayLogic && { displayLogic: q.displayLogic }
740
- };
741
- }
742
- var AssessmentsMixin = class extends TranscendGraphQLBase {
743
- async listAssessments(options) {
744
- const data = await this.makeRequest(`
745
- query ListAssessments($first: Int, $filterBy: AssessmentFormFiltersInput) {
746
- assessmentForms(first: $first, filterBy: $filterBy) {
747
- nodes {
748
- id
749
- title
750
- status
751
- createdAt
752
- assessmentGroup {
753
- id
754
- }
755
- }
756
- totalCount
757
- }
758
- }
759
- `, {
760
- first: Math.min(options?.first || 50, 100),
761
- filterBy: options?.filterBy?.statuses ? { statuses: options.filterBy.statuses } : void 0
762
- });
763
- return {
764
- nodes: data.assessmentForms.nodes.map(({ assessmentGroup, ...rest }) => ({
765
- ...rest,
766
- assessmentGroupId: assessmentGroup?.id
767
- })),
768
- pageInfo: {
769
- hasNextPage: data.assessmentForms.nodes.length < data.assessmentForms.totalCount,
770
- hasPreviousPage: false
771
- },
772
- totalCount: data.assessmentForms.totalCount
773
- };
774
- }
775
- async getAssessment(id) {
776
- const node = (await this.makeRequest(`
777
- query GetAssessment($ids: [ID!]!) {
778
- assessmentForms(first: 1, filterBy: { ids: $ids }) {
779
- nodes {
780
- id
781
- title
782
- status
783
- dueDate
784
- submittedAt
785
- createdAt
786
- updatedAt
787
- assessmentGroup {
788
- id
789
- }
790
- sections {
791
- id
792
- title
793
- index
794
- status
795
- questions {
796
- id
797
- title
798
- index
799
- type
800
- subType
801
- description
802
- isRequired
803
- placeholder
804
- answerOptions {
805
- id
806
- index
807
- value
808
- }
809
- selectedAnswers {
810
- id
811
- index
812
- value
813
- }
814
- }
815
- }
816
- }
817
- }
818
- }
819
- `, { ids: [id] })).assessmentForms.nodes[0];
820
- if (!node) throw new Error(`Assessment with id ${id} not found`);
821
- const { assessmentGroup, ...rest } = node;
822
- return {
823
- ...rest,
824
- assessmentGroupId: assessmentGroup?.id
825
- };
826
- }
827
- async selectAssessmentQuestionAnswers(input) {
828
- return (await this.makeRequest(`
829
- mutation SelectAssessmentQuestionAnswers($input: SelectAssessmentQuestionAnswerInput!) {
830
- selectAssessmentQuestionAnswers(input: $input) {
831
- selectedAnswers {
832
- id
833
- index
834
- value
835
- }
836
- }
837
- }
838
- `, { input })).selectAssessmentQuestionAnswers.selectedAnswers;
839
- }
840
- async updateAssessmentFormAssignees(input) {
841
- return (await this.makeRequest(`
842
- mutation UpdateAssessmentFormAssignees($input: UpdateAssessmentFormAssigneesInput!) {
843
- updateAssessmentFormAssignees(input: $input) {
844
- assessmentForm {
845
- id
846
- title
847
- status
848
- }
849
- }
850
- }
851
- `, { input })).updateAssessmentFormAssignees.assessmentForm;
852
- }
853
- async listAssessmentGroups(options) {
854
- const data = await this.makeRequest(`
855
- query ListAssessmentGroups($first: Int) {
856
- assessmentGroups(first: $first) {
857
- nodes {
858
- id
859
- title
860
- assessmentFormTemplate {
861
- id
862
- title
863
- }
864
- }
865
- totalCount
866
- }
867
- }
868
- `, { first: Math.min(options?.first || 50, 100) });
869
- return {
870
- nodes: data.assessmentGroups.nodes,
871
- pageInfo: {
872
- hasNextPage: data.assessmentGroups.nodes.length < data.assessmentGroups.totalCount,
873
- hasPreviousPage: false
874
- },
875
- totalCount: data.assessmentGroups.totalCount
876
- };
877
- }
878
- async createAssessmentGroup(input) {
879
- return (await this.makeRequest(`
880
- mutation CreateAssessmentGroup($input: CreateAssessmentGroupInput!) {
881
- createAssessmentGroup(input: $input) {
882
- assessmentGroup {
883
- id
884
- title
885
- }
886
- }
887
- }
888
- `, { input })).createAssessmentGroup.assessmentGroup;
889
- }
890
- async createAssessment(input) {
891
- const mutation = `
892
- mutation CreateAssessmentForms($input: CreateAssessmentFormsInput!) {
893
- createAssessmentForms(input: $input) {
894
- assessmentForms {
895
- id
896
- title
897
- status
898
- createdAt
899
- }
900
- }
901
- }
902
- `;
903
- const batchInput = { assessmentForms: [{
904
- title: input.title,
905
- assessmentGroupId: input.assessmentGroupId,
906
- ...input.assigneeIds && { assigneeIds: input.assigneeIds }
907
- }] };
908
- const created = (await this.makeRequest(mutation, { input: batchInput })).createAssessmentForms.assessmentForms[0];
909
- if (!created) throw new Error("createAssessmentForms returned an empty array");
910
- return {
911
- ...created,
912
- assessmentGroupId: input.assessmentGroupId
913
- };
914
- }
915
- async updateAssessment(input) {
916
- const { assessmentGroup, ...rest } = (await this.makeRequest(`
917
- mutation UpdateAssessmentForm($input: UpdateAssessmentFormInput!) {
918
- updateAssessmentForm(input: $input) {
919
- assessmentForm {
920
- id
921
- title
922
- description
923
- status
924
- dueDate
925
- updatedAt
926
- assessmentGroup {
927
- id
928
- }
929
- }
930
- }
931
- }
932
- `, { input })).updateAssessmentForm.assessmentForm;
933
- return {
934
- ...rest,
935
- assessmentGroupId: assessmentGroup?.id
936
- };
937
- }
938
- async listAssessmentTemplates(options) {
939
- const data = await this.makeRequest(`
940
- query ListAssessmentTemplates($first: Int) {
941
- assessmentFormTemplates(first: $first) {
942
- nodes {
943
- id
944
- title
945
- description
946
- }
947
- totalCount
948
- }
949
- }
950
- `, { first: Math.min(options?.first || 50, 100) });
951
- return {
952
- nodes: data.assessmentFormTemplates.nodes.map((t) => ({
953
- id: t.id,
954
- title: t.title,
955
- description: t.description || void 0,
956
- version: "1.0.0",
957
- isActive: true,
958
- createdAt: (/* @__PURE__ */ new Date()).toISOString()
959
- })),
960
- pageInfo: {
961
- hasNextPage: data.assessmentFormTemplates.nodes.length < data.assessmentFormTemplates.totalCount,
962
- hasPreviousPage: false
963
- },
964
- totalCount: data.assessmentFormTemplates.totalCount
965
- };
966
- }
967
- async submitAssessmentForReview(input) {
968
- await this.makeRequest(`
969
- mutation SubmitAssessmentFormForReview($input: SubmitAssessmentFormForReviewInput!) {
970
- submitAssessmentFormForReview(input: $input) {
971
- clientMutationId
972
- }
973
- }
974
- `, { input });
975
- return this.getAssessment(input.id);
976
- }
977
- async createAssessmentFormTemplate(input) {
978
- const mutation = `
979
- mutation CreateAssessmentFormTemplate($input: CreateAssessmentFormTemplateInput!) {
980
- createAssessmentFormTemplate(input: $input) {
981
- assessmentFormTemplate {
982
- id
983
- title
984
- status
985
- sections {
986
- id
987
- title
988
- index
989
- questions {
990
- id
991
- title
992
- index
993
- type
994
- subType
995
- referenceId
996
- }
997
- }
998
- }
999
- }
1000
- }
1001
- `;
1002
- const gqlInput = {
1003
- title: input.title,
1004
- description: input.description || "",
1005
- status: input.status || "DRAFT",
1006
- source: input.source || "MANUAL"
1007
- };
1008
- if (input.sections) gqlInput.sections = input.sections.map((s) => ({
1009
- title: s.title,
1010
- questions: s.questions?.map(normalizeQuestion) || []
1011
- }));
1012
- return (await this.makeRequest(mutation, { input: gqlInput })).createAssessmentFormTemplate.assessmentFormTemplate;
1013
- }
1014
- async createAssessmentSection(input) {
1015
- const mutation = `
1016
- mutation CreateAssessmentSection($input: CreateAssessmentSectionInput!) {
1017
- createAssessmentSection(input: $input) {
1018
- assessmentSection {
1019
- id
1020
- title
1021
- index
1022
- questions {
1023
- id
1024
- title
1025
- index
1026
- type
1027
- subType
1028
- referenceId
1029
- }
1030
- }
1031
- }
1032
- }
1033
- `;
1034
- const gqlInput = {
1035
- assessmentFormTemplateId: input.assessmentFormTemplateId,
1036
- title: input.title
1037
- };
1038
- if (input.questions) gqlInput.questions = input.questions.map(normalizeQuestion);
1039
- return (await this.makeRequest(mutation, { input: gqlInput })).createAssessmentSection.assessmentSection;
1040
- }
1041
- async createAssessmentQuestions(assessmentSectionId, questions) {
1042
- const mutation = `
1043
- mutation CreateAssessmentQuestions($input: [CreateAssessmentQuestionInput!]!) {
1044
- createAssessmentQuestions(input: $input) {
1045
- assessmentQuestions {
1046
- id
1047
- title
1048
- index
1049
- type
1050
- subType
1051
- referenceId
1052
- }
1053
- }
1054
- }
1055
- `;
1056
- const input = questions.map((q) => ({
1057
- title: q.title,
1058
- type: q.type,
1059
- subType: q.subType || "NONE",
1060
- placeholder: q.placeholder || "",
1061
- description: q.description || "",
1062
- isRequired: q.isRequired ?? false,
1063
- referenceId: q.referenceId,
1064
- assessmentSectionId,
1065
- answerOptions: q.answerOptions || [],
1066
- allowSelectOther: q.allowSelectOther ?? false,
1067
- requireRiskEvaluation: q.requireRiskEvaluation ?? false
1068
- }));
1069
- return (await this.makeRequest(mutation, { input })).createAssessmentQuestions.assessmentQuestions;
1070
- }
1071
- async getAssessmentFormTemplate(templateId) {
1072
- const node = (await this.makeRequest(`
1073
- query GetAssessmentFormTemplate($ids: [ID!]) {
1074
- assessmentFormTemplates(first: 1, filterBy: { ids: $ids }) {
1075
- nodes {
1076
- id
1077
- title
1078
- description
1079
- status
1080
- source
1081
- createdAt
1082
- updatedAt
1083
- sections {
1084
- id
1085
- title
1086
- index
1087
- questions {
1088
- id
1089
- title
1090
- index
1091
- type
1092
- subType
1093
- description
1094
- placeholder
1095
- isRequired
1096
- referenceId
1097
- allowSelectOther
1098
- requireRiskEvaluation
1099
- answerOptions {
1100
- id
1101
- index
1102
- value
1103
- }
1104
- }
1105
- }
1106
- }
1107
- }
1108
- }
1109
- `, { ids: [templateId] })).assessmentFormTemplates.nodes[0];
1110
- if (!node) throw new Error(`Assessment template with id ${templateId} not found`);
1111
- return node;
1112
- }
1113
- };
1114
- //#endregion
1115
- export { buildAssessmentLinks as _, SubmitResponseSchema as a, AddSectionSchema as b, ListGroupsSchema as c, GetAssessmentSchema as d, ExportTemplateSchema as f, buildAssessmentGroupUrl as g, CreateAssessmentSchema as h, UpdateAssessmentSchema as i, AssessmentStatusEnum as l, CreateGroupSchema as m, getAssessmentTools as n, PrefillSchema as o, CreateTemplateSchema as p, UpdateAssigneesSchema as r, ListTemplatesSchema as s, AssessmentsMixin as t, ListAssessmentsSchema as u, AnswerQuestionSchema as v, AnswerQuestionValueSchema as y };
1116
-
1117
- //# sourceMappingURL=graphql-DMh8AG9n.mjs.map