elevenlabs-voice-agent-mcp 1.0.14 → 1.1.0

package/dist/services/elevenlabs-api.d.ts

@@ -1,37 +1,131 @@
 /**
- * ElevenLabs API client service
- *
- * Provides core HTTP request functionality for interacting with the
+ * @fileoverview ElevenLabs API client service
+ * @description Provides core HTTP request functionality for interacting with the
  * ElevenLabs Voice Agent API, including authentication and error handling.
+ * This module serves as the central communication layer for all API operations.
+ * @module services/elevenlabs-api
  */
 /**
- * Makes an authenticated request to the ElevenLabs API
+ * Makes an authenticated request to the ElevenLabs API.
+ * @description Core function that handles all HTTP communication with ElevenLabs.
+ * Automatically adds authentication headers and handles errors consistently.
+ *
+ * @template T - The expected response data type
+ * @param {("GET" | "POST" | "PUT" | "PATCH" | "DELETE")} method - HTTP method to use
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents")
+ * @param {unknown} [data] - Request body data (for POST, PUT, PATCH methods)
+ * @param {Record<string, unknown>} [params] - URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If ELEVENLABS_API_KEY is not set
+ * @throws {Error} If the API request fails (with user-friendly message)
+ *
+ * @example
+ * // GET request
+ * const agent = await makeElevenLabsRequest<Agent>("GET", "/convai/agents/ag_123");
+ *
+ * @example
+ * // POST request with data
+ * const newAgent = await makeElevenLabsRequest<Agent>("POST", "/convai/agents/create", {
+ *   name: "Support Bot",
+ *   // ... config
+ * });
  *
- * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
- * @param endpoint - API endpoint path (e.g., "/convai/agents")
- * @param data - Request body data (for POST, PUT, PATCH)
- * @param params - URL query parameters
- * @returns Response data from the API
+ * @example
+ * // GET request with query params
+ * const agents = await makeElevenLabsRequest<{agents: Agent[]}>("GET", "/convai/agents", undefined, {
+ *   limit: 20,
+ *   offset: 0
+ * });
  */
 export declare function makeElevenLabsRequest<T = unknown>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", endpoint: string, data?: unknown, params?: Record<string, unknown>): Promise<T>;
 /**
- * GET request helper
+ * Performs an authenticated GET request to the ElevenLabs API.
+ * @description Convenience wrapper for GET requests that fetch data without a body.
+ *
+ * @template T - The expected response data type
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents/ag_123")
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Fetch a single agent
+ * const agent = await getRequest<Agent>("/convai/agents/ag_abc123");
+ *
+ * @example
+ * // Fetch agents with pagination
+ * const response = await getRequest<{agents: Agent[]}>("/convai/agents", {
+ *   limit: 20,
+ *   offset: 0
+ * });
  */
 export declare function getRequest<T>(endpoint: string, params?: Record<string, unknown>): Promise<T>;
 /**
- * POST request helper
+ * Performs an authenticated POST request to the ElevenLabs API.
+ * @description Convenience wrapper for POST requests that create new resources.
+ *
+ * @template T - The expected response data type
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents/create")
+ * @param {unknown} data - Request body data to send
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Create a new agent
+ * const agent = await postRequest<Agent>("/convai/agents/create", {
+ *   name: "Customer Support",
+ *   conversation_config: { ... }
+ * });
  */
 export declare function postRequest<T>(endpoint: string, data: unknown, params?: Record<string, unknown>): Promise<T>;
 /**
- * PUT request helper
+ * Performs an authenticated PUT request to the ElevenLabs API.
+ * @description Convenience wrapper for PUT requests that replace resources entirely.
+ *
+ * @template T - The expected response data type
+ * @param {string} endpoint - API endpoint path
+ * @param {unknown} data - Request body data to send
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Replace a resource
+ * const updated = await putRequest<Resource>("/resource/123", { ... });
  */
 export declare function putRequest<T>(endpoint: string, data: unknown, params?: Record<string, unknown>): Promise<T>;
 /**
- * PATCH request helper
+ * Performs an authenticated PATCH request to the ElevenLabs API.
+ * @description Convenience wrapper for PATCH requests that partially update resources.
+ *
+ * @template T - The expected response data type
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents/ag_123")
+ * @param {unknown} data - Partial update data to send
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Update specific agent fields
+ * const updated = await patchRequest<Agent>("/convai/agents/ag_abc123", {
+ *   name: "Updated Name"
+ * });
  */
 export declare function patchRequest<T>(endpoint: string, data: unknown, params?: Record<string, unknown>): Promise<T>;
 /**
- * DELETE request helper
+ * Performs an authenticated DELETE request to the ElevenLabs API.
+ * @description Convenience wrapper for DELETE requests that remove resources.
+ *
+ * @template T - The expected response data type (often void or confirmation)
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents/ag_123")
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API (may be empty)
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Delete an agent
+ * await deleteRequest("/convai/agents/ag_abc123");
  */
 export declare function deleteRequest<T>(endpoint: string, params?: Record<string, unknown>): Promise<T>;
 //# sourceMappingURL=elevenlabs-api.d.ts.map

package/dist/services/elevenlabs-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"elevenlabs-api.d.ts","sourceRoot":"","sources":["../../src/services/elevenlabs-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EACrD,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,EACnD,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAkCZ;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ"}
+{"version":3,"file":"elevenlabs-api.d.ts","sourceRoot":"","sources":["../../src/services/elevenlabs-api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EACrD,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,EACnD,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAkCZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAEZ"}

package/dist/services/elevenlabs-api.js

@@ -1,20 +1,44 @@
 /**
- * ElevenLabs API client service
- *
- * Provides core HTTP request functionality for interacting with the
+ * @fileoverview ElevenLabs API client service
+ * @description Provides core HTTP request functionality for interacting with the
  * ElevenLabs Voice Agent API, including authentication and error handling.
+ * This module serves as the central communication layer for all API operations.
+ * @module services/elevenlabs-api
  */
 import axios from "axios";
 import { API_BASE_URL, REQUEST_TIMEOUT } from "../constants.js";
 import { handleElevenLabsError } from "../utils/error-handlers.js";
 /**
- * Makes an authenticated request to the ElevenLabs API
+ * Makes an authenticated request to the ElevenLabs API.
+ * @description Core function that handles all HTTP communication with ElevenLabs.
+ * Automatically adds authentication headers and handles errors consistently.
+ *
+ * @template T - The expected response data type
+ * @param {("GET" | "POST" | "PUT" | "PATCH" | "DELETE")} method - HTTP method to use
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents")
+ * @param {unknown} [data] - Request body data (for POST, PUT, PATCH methods)
+ * @param {Record<string, unknown>} [params] - URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If ELEVENLABS_API_KEY is not set
+ * @throws {Error} If the API request fails (with user-friendly message)
+ *
+ * @example
+ * // GET request
+ * const agent = await makeElevenLabsRequest<Agent>("GET", "/convai/agents/ag_123");
+ *
+ * @example
+ * // POST request with data
+ * const newAgent = await makeElevenLabsRequest<Agent>("POST", "/convai/agents/create", {
+ *   name: "Support Bot",
+ *   // ... config
+ * });
  *
- * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
- * @param endpoint - API endpoint path (e.g., "/convai/agents")
- * @param data - Request body data (for POST, PUT, PATCH)
- * @param params - URL query parameters
- * @returns Response data from the API
+ * @example
+ * // GET request with query params
+ * const agents = await makeElevenLabsRequest<{agents: Agent[]}>("GET", "/convai/agents", undefined, {
+ *   limit: 20,
+ *   offset: 0
+ * });
  */
 export async function makeElevenLabsRequest(method, endpoint, data, params) {
     const apiKey = process.env.ELEVENLABS_API_KEY;
@@ -46,31 +70,101 @@ export async function makeElevenLabsRequest(method, endpoint, data, params) {
     }
 }
 /**
- * GET request helper
+ * Performs an authenticated GET request to the ElevenLabs API.
+ * @description Convenience wrapper for GET requests that fetch data without a body.
+ *
+ * @template T - The expected response data type
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents/ag_123")
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Fetch a single agent
+ * const agent = await getRequest<Agent>("/convai/agents/ag_abc123");
+ *
+ * @example
+ * // Fetch agents with pagination
+ * const response = await getRequest<{agents: Agent[]}>("/convai/agents", {
+ *   limit: 20,
+ *   offset: 0
+ * });
  */
 export async function getRequest(endpoint, params) {
     return makeElevenLabsRequest("GET", endpoint, undefined, params);
 }
 /**
- * POST request helper
+ * Performs an authenticated POST request to the ElevenLabs API.
+ * @description Convenience wrapper for POST requests that create new resources.
+ *
+ * @template T - The expected response data type
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents/create")
+ * @param {unknown} data - Request body data to send
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Create a new agent
+ * const agent = await postRequest<Agent>("/convai/agents/create", {
+ *   name: "Customer Support",
+ *   conversation_config: { ... }
+ * });
  */
 export async function postRequest(endpoint, data, params) {
     return makeElevenLabsRequest("POST", endpoint, data, params);
 }
 /**
- * PUT request helper
+ * Performs an authenticated PUT request to the ElevenLabs API.
+ * @description Convenience wrapper for PUT requests that replace resources entirely.
+ *
+ * @template T - The expected response data type
+ * @param {string} endpoint - API endpoint path
+ * @param {unknown} data - Request body data to send
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Replace a resource
+ * const updated = await putRequest<Resource>("/resource/123", { ... });
  */
 export async function putRequest(endpoint, data, params) {
     return makeElevenLabsRequest("PUT", endpoint, data, params);
 }
 /**
- * PATCH request helper
+ * Performs an authenticated PATCH request to the ElevenLabs API.
+ * @description Convenience wrapper for PATCH requests that partially update resources.
+ *
+ * @template T - The expected response data type
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents/ag_123")
+ * @param {unknown} data - Partial update data to send
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Update specific agent fields
+ * const updated = await patchRequest<Agent>("/convai/agents/ag_abc123", {
+ *   name: "Updated Name"
+ * });
  */
 export async function patchRequest(endpoint, data, params) {
     return makeElevenLabsRequest("PATCH", endpoint, data, params);
 }
 /**
- * DELETE request helper
+ * Performs an authenticated DELETE request to the ElevenLabs API.
+ * @description Convenience wrapper for DELETE requests that remove resources.
+ *
+ * @template T - The expected response data type (often void or confirmation)
+ * @param {string} endpoint - API endpoint path (e.g., "/convai/agents/ag_123")
+ * @param {Record<string, unknown>} [params] - Optional URL query parameters
+ * @returns {Promise<T>} Response data from the API (may be empty)
+ * @throws {Error} If the request fails
+ *
+ * @example
+ * // Delete an agent
+ * await deleteRequest("/convai/agents/ag_abc123");
  */
 export async function deleteRequest(endpoint, params) {
     return makeElevenLabsRequest("DELETE", endpoint, undefined, params);

package/dist/services/elevenlabs-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"elevenlabs-api.js","sourceRoot":"","sources":["../../src/services/elevenlabs-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAA4C,MAAM,OAAO,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAmD,EACnD,QAAgB,EAChB,IAAc,EACd,MAAgC;IAEhC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAE9C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,sDAAsD;YACtD,2CAA2C,CAC5C,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAuB;QACjC,MAAM;QACN,GAAG,EAAE,GAAG,YAAY,GAAG,QAAQ,EAAE;QACjC,OAAO,EAAE;YACP,YAAY,EAAE,MAAM;YACpB,cAAc,EAAE,kBAAkB;SACnC;QACD,OAAO,EAAE,eAAe;KACzB,CAAC;IAEF,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,QAAQ,GAAqB,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;QACvD,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAgB,EAChB,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AACtE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,IAAa,EACb,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAClE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAgB,EAChB,IAAa,EACb,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,IAAa,EACb,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACnE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AACzE,CAAC"}
+{"version":3,"file":"elevenlabs-api.js","sourceRoot":"","sources":["../../src/services/elevenlabs-api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAA4C,MAAM,OAAO,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAmD,EACnD,QAAgB,EAChB,IAAc,EACd,MAAgC;IAEhC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAE9C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,sDAAsD;YACtD,2CAA2C,CAC5C,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAuB;QACjC,MAAM;QACN,GAAG,EAAE,GAAG,YAAY,GAAG,QAAQ,EAAE;QACjC,OAAO,EAAE;YACP,YAAY,EAAE,MAAM;YACpB,cAAc,EAAE,kBAAkB;SACnC;QACD,OAAO,EAAE,eAAe;KACzB,CAAC;IAEF,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,QAAQ,GAAqB,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;QACvD,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAgB,EAChB,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,IAAa,EACb,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAgB,EAChB,IAAa,EACb,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,IAAa,EACb,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,MAAgC;IAEhC,OAAO,qBAAqB,CAAI,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AACzE,CAAC"}

package/dist/services/formatters.d.ts

@@ -1,76 +1,202 @@
 /**
- * Response formatting utilities
- *
- * Converts API responses to human-readable Markdown or structured JSON format.
- * Provides consistent formatting across all MCP tools.
+ * @fileoverview Response formatting utilities
+ * @description Converts API responses to human-readable Markdown or structured JSON format.
+ * Provides consistent formatting across all MCP tools for optimal readability.
+ * @module services/formatters
  */
 import { Agent, ConversationMetadata, ToolConfig, Voice, ResponseFormat, OutboundCallResponse, BatchCallResponse, BatchCallDetailedResponse, WorkspaceBatchCallsResponse, PhoneNumber, ImportPhoneNumberResponse } from "../types.js";
 /**
- * Formats an agent in Markdown format
+ * Formats a single agent in human-readable Markdown format.
+ * @description Creates a comprehensive Markdown representation of an agent
+ * including configuration, prompt, tools, and widget settings.
+ *
+ * @param {Agent} agent - The agent object to format
+ * @returns {string} Formatted Markdown string
+ *
+ * @example
+ * const markdown = formatAgentMarkdown(agent);
+ * // Returns:
+ * // # Agent: Customer Support (ag_abc123)
+ * // **Created**: 2025-01-01T00:00:00.000Z
+ * // ## Configuration
+ * // - **LLM**: claude-sonnet-4-5@20250929
+ * // ...
  */
 export declare function formatAgentMarkdown(agent: Agent): string;
 /**
- * Formats a list of agents in Markdown format
+ * Formats a paginated list of agents in Markdown format.
+ * @description Creates a Markdown list with agent summaries and pagination guidance.
+ *
+ * @param {Agent[]} agents - Array of agent objects to format
+ * @param {number} total - Total number of agents available
+ * @param {number} offset - Current pagination offset
+ * @param {boolean} hasMore - Whether more agents are available
+ * @returns {string} Formatted Markdown string with pagination info
+ *
+ * @example
+ * const markdown = formatAgentListMarkdown(agents, 50, 0, true);
+ * // Returns:
+ * // # Agents (20 of 50)
+ * // ## 1. Customer Support
+ * // - **ID**: ag_abc123
+ * // ...
  */
 export declare function formatAgentListMarkdown(agents: Agent[], total: number, offset: number, hasMore: boolean): string;
 /**
- * Formats a conversation in Markdown format
+ * Formats a conversation with full transcript in Markdown format.
+ * @description Creates a detailed Markdown representation including metadata,
+ * transcript entries, tool calls, and conversation analysis.
+ *
+ * @param {ConversationMetadata} conversation - The conversation object to format
+ * @returns {string} Formatted Markdown string with transcript
+ *
+ * @example
+ * const markdown = formatConversationMarkdown(conversation);
+ * // Returns:
+ * // # Conversation: conv_xyz789
+ * // - **Agent ID**: ag_abc123
+ * // - **Status**: completed
+ * // ## Transcript (5 messages)
+ * // ...
  */
 export declare function formatConversationMarkdown(conversation: ConversationMetadata): string;
 /**
- * Formats a list of conversations in Markdown format
+ * Formats a paginated list of conversations in Markdown format.
+ * @description Creates a Markdown list with conversation summaries and pagination guidance.
+ *
+ * @param {ConversationMetadata[]} conversations - Array of conversations to format
+ * @param {number} total - Total number of conversations available
+ * @param {number} offset - Current pagination offset
+ * @param {boolean} hasMore - Whether more conversations are available
+ * @returns {string} Formatted Markdown string with pagination info
  */
 export declare function formatConversationListMarkdown(conversations: ConversationMetadata[], total: number, offset: number, hasMore: boolean): string;
 /**
- * Formats a tool configuration in Markdown format
+ * Formats a single tool configuration in Markdown format.
+ * @description Creates a detailed Markdown representation of a webhook tool
+ * including parameters, URL, and method.
+ *
+ * @param {ToolConfig} tool - The tool configuration to format
+ * @returns {string} Formatted Markdown string
  */
 export declare function formatToolMarkdown(tool: ToolConfig): string;
 /**
- * Formats a list of tools in Markdown format
+ * Formats a list of tool configurations in Markdown format.
+ * @description Creates a summary list of all tools configured for an agent.
+ *
+ * @param {ToolConfig[]} tools - Array of tool configurations to format
+ * @returns {string} Formatted Markdown string
  */
 export declare function formatToolListMarkdown(tools: ToolConfig[]): string;
 /**
- * Formats a list of voices in Markdown format
+ * Formats a list of available voices in Markdown format.
+ * @description Creates a browseable list of voices with labels and preview URLs.
+ *
+ * @param {Voice[]} voices - Array of voice objects to format
+ * @returns {string} Formatted Markdown string
  */
 export declare function formatVoiceListMarkdown(voices: Voice[]): string;
 /**
- * Formats widget embed code
+ * Generates HTML embed code for a voice agent widget.
+ * @description Creates ready-to-use HTML/JavaScript code for embedding
+ * a voice agent widget on a webpage.
+ *
+ * @param {string} agentId - The agent ID to embed
+ * @param {string} [color] - Optional widget theme color (hex format)
+ * @param {string} [avatarUrl] - Optional avatar image URL
+ * @returns {string} Formatted Markdown with HTML code block
+ *
+ * @example
+ * const code = formatWidgetCode("ag_abc123", "#4A90E2");
+ * // Returns Markdown with embeddable script tag
  */
 export declare function formatWidgetCode(agentId: string, color?: string, avatarUrl?: string): string;
 /**
- * Formats an outbound call response in Markdown format
+ * Formats an outbound call response in Markdown format.
+ * @description Creates a status summary for a call initiation attempt
+ * including conversation ID and Twilio call SID.
+ *
+ * @param {OutboundCallResponse} response - The outbound call response to format
+ * @returns {string} Formatted Markdown string
  */
 export declare function formatOutboundCallMarkdown(response: OutboundCallResponse): string;
 /**
- * Formats a batch call response in Markdown format
+ * Formats a batch call job summary in Markdown format.
+ * @description Creates a status summary for a batch calling job
+ * including timing and call statistics.
+ *
+ * @param {BatchCallResponse} batch - The batch call response to format
+ * @returns {string} Formatted Markdown string
  */
 export declare function formatBatchCallMarkdown(batch: BatchCallResponse): string;
 /**
- * Formats a batch call list in Markdown format
+ * Formats a paginated list of batch calls in Markdown format.
+ * @description Creates a summary list of batch calling jobs with status info.
+ *
+ * @param {WorkspaceBatchCallsResponse} response - The batch list response to format
+ * @returns {string} Formatted Markdown string with pagination cursor
  */
 export declare function formatBatchCallListMarkdown(response: WorkspaceBatchCallsResponse): string;
 /**
- * Formats detailed batch call information with recipient statuses
+ * Formats detailed batch call information with all recipient statuses.
+ * @description Creates a comprehensive view of a batch job including
+ * status breakdown and individual recipient details.
+ *
+ * @param {BatchCallDetailedResponse} batch - The detailed batch response to format
+ * @returns {string} Formatted Markdown string with recipient statuses
  */
 export declare function formatBatchCallDetailMarkdown(batch: BatchCallDetailedResponse): string;
 /**
- * Formats a list of phone numbers in Markdown format
+ * Formats a list of phone numbers in Markdown format.
+ * @description Creates a summary list of phone numbers with capabilities and assignments.
+ *
+ * @param {PhoneNumber[]} phoneNumbers - Array of phone numbers to format
+ * @returns {string} Formatted Markdown string
  */
 export declare function formatPhoneNumberListMarkdown(phoneNumbers: PhoneNumber[]): string;
 /**
- * Formats a single phone number in Markdown format
+ * Formats a single phone number with full details in Markdown format.
+ * @description Creates a detailed view of a phone number including
+ * capabilities, assignment, and provider-specific configuration.
+ *
+ * @param {PhoneNumber} phone - The phone number object to format
+ * @returns {string} Formatted Markdown string
  */
 export declare function formatPhoneNumberMarkdown(phone: PhoneNumber): string;
 /**
- * Formats phone number import response in Markdown format
+ * Formats a phone number import success response in Markdown format.
+ * @description Creates a confirmation message with next steps guidance.
+ *
+ * @param {ImportPhoneNumberResponse} response - The import response to format
+ * @returns {string} Formatted Markdown string with next steps
  */
 export declare function formatPhoneNumberImportMarkdown(response: ImportPhoneNumberResponse): string;
 /**
- * Formats any response as JSON
+ * Formats any response data as a JSON string.
+ * @description Converts data to pretty-printed JSON with automatic truncation
+ * if the output exceeds character limits.
+ *
+ * @param {unknown} data - Any data to format as JSON
+ * @returns {string} Pretty-printed JSON string
  */
 export declare function formatAsJSON(data: unknown): string;
 /**
- * Main formatting function that routes to appropriate formatter
+ * Main formatting function that routes to the appropriate formatter.
+ * @description Central dispatch function that formats data based on the requested
+ * format (JSON or Markdown) and data type. Used by all MCP tool handlers.
+ *
+ * @param {unknown} data - The data to format
+ * @param {ResponseFormat} format - Output format (JSON or Markdown)
+ * @param {string} type - Data type identifier for selecting the appropriate formatter
+ * @returns {string} Formatted output string
+ *
+ * @example
+ * // Format an agent as Markdown
+ * const output = formatResponse(agent, ResponseFormat.MARKDOWN, "agent");
+ *
+ * @example
+ * // Format agent list as JSON
+ * const output = formatResponse(agents, ResponseFormat.JSON, "agent_list");
  */
 export declare function formatResponse(data: unknown, format: ResponseFormat, type: "agent" | "agent_list" | "conversation" | "conversation_list" | "tool" | "tool_list" | "voice_list" | "widget" | "outbound_call" | "batch_call" | "batch_call_list" | "batch_call_detail" | "phone_number_list" | "phone_number" | "phone_number_import" | "generic"): string;
 //# sourceMappingURL=formatters.d.ts.map

package/dist/services/formatters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/services/formatters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,EACL,oBAAoB,EACpB,UAAU,EACV,KAAK,EACL,cAAc,EAEd,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,2BAA2B,EAC3B,WAAW,EACX,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAGrB;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAuDxD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACf,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,oBAAoB,GAAG,MAAM,CAgDrF;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,oBAAoB,EAAE,EACrC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACf,MAAM,CA0BR;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAuB3D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,CAoBlE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAmC/D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAuB5F;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAkBjF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAwBxE;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,2BAA2B,GAAG,MAAM,CAuBzF;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,yBAAyB,GAAG,MAAM,CA2CtF;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,MAAM,CA6BjF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAgCpE;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,yBAAyB,GAAG,MAAM,CAS3F;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAElD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,cAAc,GAAG,mBAAmB,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,GAAG,eAAe,GAAG,YAAY,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,cAAc,GAAG,qBAAqB,GAAG,SAAS,GACzQ,MAAM,CAsER"}
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/services/formatters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,EACL,oBAAoB,EACpB,UAAU,EACV,KAAK,EACL,cAAc,EAEd,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,2BAA2B,EAC3B,WAAW,EACX,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAuDxD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACf,MAAM,CAsBR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,oBAAoB,GAAG,MAAM,CAgDrF;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,oBAAoB,EAAE,EACrC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACf,MAAM,CA0BR;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAuB3D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,CAoBlE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAmC/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAuB5F;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAkBjF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAwBxE;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,2BAA2B,GAAG,MAAM,CAuBzF;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,yBAAyB,GAAG,MAAM,CA2CtF;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,MAAM,CA6BjF;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAgCpE;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,yBAAyB,GAAG,MAAM,CAS3F;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,cAAc,GAAG,mBAAmB,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,GAAG,eAAe,GAAG,YAAY,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,cAAc,GAAG,qBAAqB,GAAG,SAAS,GACzQ,MAAM,CAsER"}