searchVoiceConversations.ts

import { formatDistanceStrict } from "date-fns/formatDistanceStrict";
import type { AnalyticsApi, Models } 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 { paginationSection } from "./utils/paginationSection.js";

export interface ToolDependencies {
  readonly analyticsApi: Pick<
    AnalyticsApi,
    "postAnalyticsConversationsDetailsQuery"
  >;
}

function normalisePhoneNumber(phoneNumber: string): string {
  // N.B. This appears to be what is happening within the Genesys Cloud UI,
  // although I don't know if my version is too simplistic.
  return phoneNumber.replace(/\D/g, "");
}

function createAniSegmentFilter(
  phoneNumber: string,
): Models.SegmentDetailQueryFilter {
  return {
    type: "or",
    predicates: [
      {
        dimension: "ani",
        value: normalisePhoneNumber(phoneNumber),
      },
    ],
  };
}

const paramsSchema = z.object({
  phoneNumber: z
    .string()
    .optional()
    .describe(
      "Optional. Filters results to only include conversations involving this phone number (e.g., '+440000000000')",
    ),
  pageNumber: z
    .number()
    .int()
    .positive()
    .optional()
    .describe(
      "The page number of the results to retrieve, starting from 1. Defaults to 1 if not specified. Used with 'pageSize' for navigating large result sets",
    ),
  pageSize: z
    .number()
    .int()
    .positive()
    .max(100)
    .optional()
    .describe(
      "The maximum number of conversations to return per page. Defaults to 100 if not specified. Used with 'pageNumber' for pagination. The maximum value is 100",
    ),
  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 searchVoiceConversations: ToolFactory<
  ToolDependencies,
  typeof paramsSchema
> = ({ analyticsApi }) =>
  createTool({
    schema: {
      name: "search_voice_conversations",
      annotations: { title: "Search Voice Conversations" },
      description:
        "Searches for voice conversations within a specified time window, optionally filtering by phone number. Returns a paginated list of conversation IDs and call duration for use in further analysis or tool calls.",
      paramsSchema,
    },
    call: async ({
      phoneNumber,
      startDate,
      endDate,
      pageNumber = 1,
      pageSize = 100,
    }) => {
      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());
      }

      let result: Models.AnalyticsConversationQueryResponse;

      try {
        result = await analyticsApi.postAnalyticsConversationsDetailsQuery({
          order: "desc",
          orderBy: "conversationStart",
          paging: { pageSize, pageNumber },
          interval: `${from.toISOString()}/${to.toISOString()}`,
          segmentFilters: [
            {
              type: "or",
              predicates: [
                {
                  dimension: "mediaType",
                  value: "voice",
                },
              ],
            },
            {
              type: "or",
              predicates: [
                {
                  dimension: "direction",
                  value: "inbound",
                },
                {
                  dimension: "direction",
                  value: "outbound",
                },
              ],
            },
            ...(phoneNumber ? [createAniSegmentFilter(phoneNumber)] : []),
          ],
          conversationFilters: [],
          evaluationFilters: [],
          surveyFilters: [],
        });
      } catch (error: unknown) {
        const errorMessage = isUnauthorisedError(error)
          ? "Failed to search conversations: Unauthorised access. Please check API credentials or permissions"
          : `Failed to search conversations: ${error instanceof Error ? error.message : JSON.stringify(error)}`;

        return errorResult(errorMessage);
      }

      const conversationToDurationMapping = (result.conversations ?? [])
        .filter((convo) => convo.conversationId)
        .map((conversation) => {
          let distance: string | null = null;
          if (conversation.conversationStart && conversation.conversationEnd) {
            distance = formatDistanceStrict(
              conversation.conversationStart,
              conversation.conversationEnd,
            );
          }

          return {
            conversationId: conversation.conversationId,
            ...(distance !== null ? { duration: distance } : {}),
          };
        });

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              conversations: conversationToDurationMapping,
              pagination: paginationSection("totalConversationsReturned", {
                pageSize,
                pageNumber,
                totalHits: result.totalHits,
              }),
            }),
          },
        ],
      };
    },
  });