import type { AnalyticsApi } from "purecloud-platform-client-v2";
import { z } from "zod";
import { createTool, type ToolFactory } from "../utils/createTool.js";
import { errorResult } from "../utils/errorResult.js";
import { isUnauthorisedError } from "../utils/genesys/isUnauthorisedError.js";
import { waitFor } from "../utils/waitFor.js";
import { isQueueUsedInConvo } from "./isQueueUsedInConvo.js";
export interface ToolDependencies {
readonly analyticsApi: Pick<
AnalyticsApi,
| "postAnalyticsConversationsDetailsJobs"
| "getAnalyticsConversationsDetailsJob"
| "getAnalyticsConversationsDetailsJobResults"
>;
}
const MAX_ATTEMPTS = 10;
const paramsSchema = z.object({
queueIds: z
.array(
z
.string()
.uuid()
.describe(
"A UUID for a queue. (e.g., 00000000-0000-0000-0000-000000000000)",
),
)
.min(1)
.max(300)
.describe("List of up to MAX of 300 queue IDs"),
startDate: z
.string()
.describe(
"The start date/time in ISO-8601 format (e.g., '2024-01-01T00:00:00Z')",
),
endDate: z
.string()
.describe(
"The end date/time in ISO-8601 format (e.g., '2024-01-07T23:59:59Z')",
),
});
export const queryQueueVolumes: ToolFactory<
ToolDependencies,
typeof paramsSchema
> = ({ analyticsApi }) =>
createTool({
schema: {
name: "query_queue_volumes",
annotations: { title: "Query Queue Volumes" },
description:
"Returns a breakdown of how many conversations occurred in each specified queue between two dates. Useful for comparing workload across queues. MAX 300 queue IDs.",
paramsSchema,
},
call: async ({ queueIds, startDate, endDate }) => {
const from = new Date(startDate);
const to = new Date(endDate);
if (Number.isNaN(from.getTime()))
return errorResult("startDate is not a valid ISO-8601 date");
if (Number.isNaN(to.getTime()))
return errorResult("endDate is not a valid ISO-8601 date");
if (from >= to) return errorResult("Start date must be before end date");
const now = new Date();
if (to > now) {
to.setTime(now.getTime());
}
try {
const job = await analyticsApi.postAnalyticsConversationsDetailsJobs({
interval: `${from.toISOString()}/${to.toISOString()}`,
order: "asc",
orderBy: "conversationStart",
segmentFilters: [
{
type: "and",
predicates: [
{
dimension: "purpose",
value: "customer",
},
],
},
{
type: "or",
predicates: queueIds.map((id) => ({
dimension: "queueId",
value: id,
})),
},
],
});
const jobId = job.jobId;
if (!jobId)
return errorResult("Job ID not returned from Genesys Cloud.");
let state: string | undefined;
let attempts = 0;
while (attempts < MAX_ATTEMPTS) {
const jobStatus =
await analyticsApi.getAnalyticsConversationsDetailsJob(jobId);
state = jobStatus.state ?? "UNKNOWN";
if (state === "FULFILLED") break;
switch (jobStatus.state) {
case "FAILED":
return errorResult("Analytics job failed.");
case "CANCELLED":
return errorResult("Analytics job was cancelled.");
case "EXPIRED":
return errorResult("Analytics job results have expired.");
case "UNKNOWN":
return errorResult(
"Analytics job returned an unknown or undefined state.",
);
}
await waitFor(3000);
attempts++;
}
if (state !== "FULFILLED") {
return errorResult(
"Timed out waiting for analytics job to complete.",
);
}
const results =
await analyticsApi.getAnalyticsConversationsDetailsJobResults(jobId);
const conversations = results.conversations ?? [];
const queueConversationCount = new Map<string, number>();
for (const convo of conversations) {
for (const queueId of queueIds) {
if (isQueueUsedInConvo(queueId, convo)) {
const count = queueConversationCount.get(queueId) ?? 0;
queueConversationCount.set(queueId, count + 1);
}
}
}
const queueBreakdown = queueIds.map((id) => {
const totalConversations = queueConversationCount.get(id) ?? 0;
return { queueId: id, totalConversations };
});
return {
content: [
{
type: "text",
text: JSON.stringify({ queues: queueBreakdown }),
},
],
};
} catch (error: unknown) {
const errorMessage = isUnauthorisedError(error)
? "Failed to query conversations: Unauthorised access. Please check API credentials or permissions"
: `Failed to query conversations: ${error instanceof Error ? error.message : JSON.stringify(error)}`;
return errorResult(errorMessage);
}
},
});
