@absolutejs/voice 0.0.22-beta.469 → 0.0.22-beta.470

package/README.md

@@ -8,6 +8,50 @@ Use it when you want Vapi/Retell/Bland-style voice-agent capability, but you wan
 
 ## What's new
 
+### 0.0.22-beta.470 · Vapi parity — named tool catalog
+
+Five named-tool factories that mirror Vapi's built-in `tools[].type` entries 1:1. Drop them straight into `createVoiceAssistant({ tools: [...] })` to get the same buyer ergonomics without writing the wiring yourself.
+
+```ts
+import {
+  createVoiceAssistant,
+  createVoiceApiRequestTool,
+  createVoiceDTMFTool,
+  createVoiceEndCallTool,
+  createVoiceTransferCallTool,
+  createVoiceVoicemailDetectionTool,
+} from "@absolutejs/voice";
+
+const tools = [
+  createVoiceEndCallTool({ farewell: "Thanks for calling, goodbye." }),
+  createVoiceTransferCallTool({
+    destinations: [
+      { id: "billing", target: "+15551234567", message: "Connecting you to billing." },
+      { id: "supervisor", target: "sip:supervisor@pbx", metadata: { queue: "vip" } },
+    ],
+  }),
+  createVoiceDTMFTool({
+    send: async ({ args, api }) => api.transfer({ target: "ivr", metadata: { digits: args.digits } }),
+  }),
+  createVoiceVoicemailDetectionTool({ completeAfterMarking: true }),
+  createVoiceApiRequestTool({
+    description: "Look up a customer record",
+    name: "lookupCustomer",
+    method: "GET",
+    url: "https://api.example.com/customers",
+    buildQuery: ({ args }) => ({ email: String(args.email) }),
+    parameters: { type: "object", properties: { email: { type: "string" } }, required: ["email"] },
+  }),
+];
+```
+
+Per-tool highlights:
+- **`createVoiceEndCallTool`** — calls `api.complete(result)` with an optional resolved result. JSON-schema `{ reason?: string }`. Custom `farewell` (static or `({args, context, session}) => string`).
+- **`createVoiceTransferCallTool`** — multi-destination router, exposes an `enum` of destination ids to the LLM; calls `api.transfer({ target, metadata, reason, result })` with the matching destination. Pairs with `createVoiceTwilioRedirectHandoffAdapter` for live carrier transfer.
+- **`createVoiceDTMFTool`** — caller provides a `send` hook (typically forwarding to your telephony adapter); validates digits against `allowedDigits` and `maxDigits`. Default allowed set `0123456789*#`.
+- **`createVoiceVoicemailDetectionTool`** — LLM-callable companion to ML-based voicemail detection; calls `api.markVoicemail({ metadata })` and (by default) `api.complete()`. Use when the model hears a beep / "leave a message" prompt.
+- **`createVoiceApiRequestTool`** — generic HTTP-call tool with `buildBody` / `buildQuery` / `buildHeaders` / `parseResponse` hooks. Supports DI of `fetch` for tests.
+
 ### 0.0.22-beta.469 · Vapi parity — RAG-as-a-tool helper
 
 `createVoiceRAGTool(collection, options?)` wraps any `@absolutejs/rag` `RAGCollection` (or any object that satisfies `VoiceRAGCollectionLike`) into a `VoiceAgentTool` shaped like Vapi's built-in `query` / `knowledgeBaseId` flow.

package/dist/agentTools.d.ts

@@ -0,0 +1,132 @@
+import { type VoiceAgentTool } from "./agent";
+import type { VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord } from "./types";
+export type VoiceEndCallToolArgs = {
+    reason?: string;
+};
+export type VoiceEndCallToolResult = {
+    farewell?: string;
+    ok: true;
+    reason?: string;
+};
+export type VoiceEndCallToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    description?: string;
+    farewell?: string | ((input: {
+        args: VoiceEndCallToolArgs;
+        context: TContext;
+        session: TSession;
+    }) => string | undefined);
+    name?: string;
+    resolveResult?: (input: {
+        args: VoiceEndCallToolArgs;
+        context: TContext;
+        session: TSession;
+    }) => TResult | undefined;
+};
+export declare const createVoiceEndCallTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options?: VoiceEndCallToolOptions<TContext, TSession, TResult>) => VoiceAgentTool<TContext, TSession, VoiceEndCallToolArgs, VoiceEndCallToolResult, TResult>;
+export type VoiceTransferCallToolDestination = {
+    description?: string;
+    id: string;
+    message?: string;
+    metadata?: Record<string, unknown>;
+    target: string;
+};
+export type VoiceTransferCallToolArgs = {
+    destinationId: string;
+    reason?: string;
+};
+export type VoiceTransferCallToolResult = {
+    destinationId: string;
+    message?: string;
+    ok: true;
+    target: string;
+};
+export type VoiceTransferCallToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    description?: string;
+    destinations: readonly VoiceTransferCallToolDestination[];
+    name?: string;
+    resolveResult?: (input: {
+        args: VoiceTransferCallToolArgs;
+        context: TContext;
+        destination: VoiceTransferCallToolDestination;
+        session: TSession;
+    }) => TResult | undefined;
+};
+export declare const createVoiceTransferCallTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceTransferCallToolOptions<TContext, TSession, TResult>) => VoiceAgentTool<TContext, TSession, VoiceTransferCallToolArgs, VoiceTransferCallToolResult, TResult>;
+export type VoiceDTMFToolArgs = {
+    digits: string;
+};
+export type VoiceDTMFToolResult = {
+    digits: string;
+    ok: true;
+};
+export type VoiceDTMFToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord> = {
+    allowedDigits?: string;
+    description?: string;
+    maxDigits?: number;
+    name?: string;
+    send: (input: {
+        api: VoiceSessionHandle<TContext, TSession>;
+        args: VoiceDTMFToolArgs;
+        context: TContext;
+        session: TSession;
+    }) => Promise<void> | void;
+};
+export declare const createVoiceDTMFTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord>(options: VoiceDTMFToolOptions<TContext, TSession>) => VoiceAgentTool<TContext, TSession, VoiceDTMFToolArgs, VoiceDTMFToolResult>;
+export type VoiceVoicemailDetectionToolArgs = {
+    confidence?: number;
+    reason?: string;
+};
+export type VoiceVoicemailDetectionToolResult = {
+    confidence?: number;
+    ok: true;
+    reason?: string;
+};
+export type VoiceVoicemailDetectionToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    completeAfterMarking?: boolean;
+    description?: string;
+    message?: string;
+    name?: string;
+    resolveResult?: (input: {
+        args: VoiceVoicemailDetectionToolArgs;
+        context: TContext;
+        session: TSession;
+    }) => TResult | undefined;
+};
+export declare const createVoiceVoicemailDetectionTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options?: VoiceVoicemailDetectionToolOptions<TContext, TSession, TResult>) => VoiceAgentTool<TContext, TSession, VoiceVoicemailDetectionToolArgs, VoiceVoicemailDetectionToolResult, TResult>;
+export type VoiceApiRequestToolHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+export type VoiceApiRequestToolArgs = Record<string, unknown>;
+export type VoiceApiRequestToolResult<TResponse = unknown> = {
+    body: TResponse;
+    ok: boolean;
+    status: number;
+    url: string;
+};
+export type VoiceApiRequestToolFetch = (request: Request) => Promise<Response> | Response;
+export type VoiceApiRequestToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs extends VoiceApiRequestToolArgs = VoiceApiRequestToolArgs, TResponse = unknown> = {
+    buildBody?: (input: {
+        args: TArgs;
+        context: TContext;
+        session: TSession;
+    }) => unknown;
+    buildHeaders?: (input: {
+        args: TArgs;
+        context: TContext;
+        session: TSession;
+    }) => HeadersInit | undefined;
+    buildQuery?: (input: {
+        args: TArgs;
+        context: TContext;
+        session: TSession;
+    }) => Record<string, string | number | undefined> | undefined;
+    description: string;
+    fetch?: VoiceApiRequestToolFetch;
+    formatResult?: (result: VoiceApiRequestToolResult<TResponse>) => string;
+    headers?: HeadersInit;
+    method?: VoiceApiRequestToolHttpMethod;
+    name: string;
+    parameters?: Record<string, unknown>;
+    parseResponse?: (response: Response) => Promise<TResponse> | TResponse;
+    url: string;
+};
+export declare const createVoiceApiRequestTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs extends VoiceApiRequestToolArgs = VoiceApiRequestToolArgs, TResponse = unknown>(options: VoiceApiRequestToolOptions<TContext, TSession, TArgs, TResponse>) => VoiceAgentTool<TContext, TSession, TArgs, VoiceApiRequestToolResult<TResponse>>;
+export type VoiceRouteResultLike = VoiceRouteResult<unknown>;

package/dist/index.d.ts

@@ -71,6 +71,8 @@ export { createVoiceSessionListRoutes, createVoiceSessionReplayHTMLHandler, crea
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool, } from "./agent";
 export { createVoiceRAGTool } from "./ragTool";
 export type { VoiceRAGCollectionLike, VoiceRAGQueryResult, VoiceRAGSearchInput, VoiceRAGToolArgs, VoiceRAGToolOptions, VoiceRAGToolResult, } from "./ragTool";
+export { createVoiceApiRequestTool, createVoiceDTMFTool, createVoiceEndCallTool, createVoiceTransferCallTool, createVoiceVoicemailDetectionTool, } from "./agentTools";
+export type { VoiceApiRequestToolArgs, VoiceApiRequestToolFetch, VoiceApiRequestToolHttpMethod, VoiceApiRequestToolOptions, VoiceApiRequestToolResult, VoiceDTMFToolArgs, VoiceDTMFToolOptions, VoiceDTMFToolResult, VoiceEndCallToolArgs, VoiceEndCallToolOptions, VoiceEndCallToolResult, VoiceTransferCallToolArgs, VoiceTransferCallToolDestination, VoiceTransferCallToolOptions, VoiceTransferCallToolResult, VoiceVoicemailDetectionToolArgs, VoiceVoicemailDetectionToolOptions, VoiceVoicemailDetectionToolResult, } from "./agentTools";
 export { assertVoiceAgentSquadContractEvidence, assertVoiceAgentSquadContract, evaluateVoiceAgentSquadContractEvidence, runVoiceAgentSquadContract, } from "./agentSquadContract";
 export { createVoiceToolIdempotencyKey, createVoiceToolRuntime, } from "./toolRuntime";
 export { assertVoiceToolContractEvidence, createVoiceToolContract, createVoiceToolContractHTMLHandler, createVoiceToolContractJSONHandler, createVoiceToolContractRoutes, createVoiceToolRuntimeContractDefaults, evaluateVoiceToolContractEvidence, renderVoiceToolContractHTML, runVoiceToolContractSuite, runVoiceToolContract, } from "./toolContract";

package/dist/index.js

@@ -34629,6 +34629,228 @@ var createVoiceRAGTool = (collection, options = {}) => {
     resultToMessage: options.resultToMessage ?? ((result) => result.message)
   });
 };
+// src/agentTools.ts
+var createVoiceEndCallTool = (options = {}) => createVoiceAgentTool({
+  description: options.description ?? "End the call gracefully. Call this only when the conversation is complete or the caller asks to hang up.",
+  execute: async ({ api, args, context, session }) => {
+    const farewell = typeof options.farewell === "function" ? options.farewell({ args, context, session }) : options.farewell;
+    const result = options.resolveResult?.({ args, context, session });
+    await api.complete(result);
+    return {
+      farewell,
+      ok: true,
+      reason: args?.reason
+    };
+  },
+  name: options.name ?? "endCall",
+  parameters: {
+    additionalProperties: false,
+    properties: {
+      reason: {
+        description: "Optional one-line note about why the call is ending.",
+        type: "string"
+      }
+    },
+    type: "object"
+  },
+  resultToMessage: (result) => result.farewell ?? "Call ended."
+});
+var createVoiceTransferCallTool = (options) => {
+  if (options.destinations.length === 0) {
+    throw new Error("createVoiceTransferCallTool requires at least one destination.");
+  }
+  const destinationIds = options.destinations.map((entry) => entry.id);
+  const destinationDocs = options.destinations.map((entry) => `- ${entry.id} \u2192 ${entry.target}${entry.description ? `: ${entry.description}` : ""}`).join(`
+`);
+  return createVoiceAgentTool({
+    description: options.description ?? `Transfer the caller to a human or another route. Available destinations:
+${destinationDocs}`,
+    execute: async ({ api, args, context, session }) => {
+      const destination = options.destinations.find((entry) => entry.id === args?.destinationId);
+      if (!destination) {
+        throw new Error(`Unknown transfer destination "${String(args?.destinationId)}". Allowed: ${destinationIds.join(", ")}.`);
+      }
+      const result = options.resolveResult?.({
+        args,
+        context,
+        destination,
+        session
+      });
+      await api.transfer({
+        metadata: destination.metadata,
+        reason: args?.reason,
+        result,
+        target: destination.target
+      });
+      return {
+        destinationId: destination.id,
+        message: destination.message,
+        ok: true,
+        target: destination.target
+      };
+    },
+    name: options.name ?? "transferCall",
+    parameters: {
+      additionalProperties: false,
+      properties: {
+        destinationId: {
+          description: "Which configured destination to transfer the call to.",
+          enum: destinationIds,
+          type: "string"
+        },
+        reason: {
+          description: "Optional one-line summary of why the transfer is happening.",
+          type: "string"
+        }
+      },
+      required: ["destinationId"],
+      type: "object"
+    },
+    resultToMessage: (result) => result.message ?? `Transferring you to ${result.target}.`
+  });
+};
+var DEFAULT_DTMF_ALLOWED = "0123456789*#";
+var createVoiceDTMFTool = (options) => {
+  const allowedSet = new Set((options.allowedDigits ?? DEFAULT_DTMF_ALLOWED).split(""));
+  const maxDigits = options.maxDigits ?? 32;
+  return createVoiceAgentTool({
+    description: options.description ?? "Send DTMF (touch-tone) digits to the active call. Use for IVR navigation and keypad entry.",
+    execute: async ({ api, args, context, session }) => {
+      const raw = typeof args?.digits === "string" ? args.digits.trim() : "";
+      if (raw.length === 0) {
+        throw new Error("DTMF tool requires a non-empty digits string.");
+      }
+      if (raw.length > maxDigits) {
+        throw new Error(`DTMF digits exceed configured maxDigits=${String(maxDigits)}.`);
+      }
+      for (const character of raw) {
+        if (!allowedSet.has(character)) {
+          throw new Error(`DTMF digit "${character}" is not in the allowed set "${options.allowedDigits ?? DEFAULT_DTMF_ALLOWED}".`);
+        }
+      }
+      await options.send({
+        api,
+        args: { digits: raw },
+        context,
+        session
+      });
+      return {
+        digits: raw,
+        ok: true
+      };
+    },
+    name: options.name ?? "sendDTMF",
+    parameters: {
+      additionalProperties: false,
+      properties: {
+        digits: {
+          description: `Digits to send. Allowed characters: ${options.allowedDigits ?? DEFAULT_DTMF_ALLOWED}. Max length ${String(maxDigits)}.`,
+          maxLength: maxDigits,
+          minLength: 1,
+          type: "string"
+        }
+      },
+      required: ["digits"],
+      type: "object"
+    },
+    resultToMessage: (result) => `Sent DTMF: ${result.digits}`
+  });
+};
+var createVoiceVoicemailDetectionTool = (options = {}) => {
+  const completeAfterMarking = options.completeAfterMarking ?? true;
+  return createVoiceAgentTool({
+    description: options.description ?? "Mark the call as a voicemail when you hear a beep, a 'please leave a message' prompt, or other voicemail cues. Call exactly once per detection.",
+    execute: async ({ api, args, context, session }) => {
+      const metadata = {};
+      if (typeof args?.confidence === "number") {
+        metadata.confidence = args.confidence;
+      }
+      if (typeof args?.reason === "string" && args.reason.length > 0) {
+        metadata.reason = args.reason;
+      }
+      const result = options.resolveResult?.({ args, context, session });
+      await api.markVoicemail({ metadata, result });
+      if (completeAfterMarking) {
+        await api.complete(result);
+      }
+      return {
+        confidence: args?.confidence,
+        ok: true,
+        reason: args?.reason
+      };
+    },
+    name: options.name ?? "markVoicemail",
+    parameters: {
+      additionalProperties: false,
+      properties: {
+        confidence: {
+          description: "Optional model confidence in the 0..1 range.",
+          maximum: 1,
+          minimum: 0,
+          type: "number"
+        },
+        reason: {
+          description: "One-line description of the cue that triggered detection.",
+          type: "string"
+        }
+      },
+      type: "object"
+    },
+    resultToMessage: (result) => options.message ?? `Voicemail detected${typeof result.confidence === "number" ? ` (confidence ${result.confidence.toFixed(2)})` : ""}.`
+  });
+};
+var appendSearchParams = (url, entries) => {
+  if (!entries)
+    return;
+  for (const [key, value] of Object.entries(entries)) {
+    if (value === undefined)
+      continue;
+    url.searchParams.set(key, String(value));
+  }
+};
+var createVoiceApiRequestTool = (options) => {
+  const method = options.method ?? "GET";
+  const fetchImpl = options.fetch ?? ((request) => fetch(request));
+  return createVoiceAgentTool({
+    description: options.description,
+    execute: async ({ args, context, session }) => {
+      const url = new URL(options.url);
+      appendSearchParams(url, options.buildQuery?.({ args, context, session }));
+      const baseHeaders = new Headers(options.headers ?? {});
+      const dynamicHeaders = options.buildHeaders?.({
+        args,
+        context,
+        session
+      });
+      if (dynamicHeaders) {
+        const merged = new Headers(dynamicHeaders);
+        merged.forEach((value, key) => baseHeaders.set(key, value));
+      }
+      const body = method === "GET" || method === "DELETE" ? undefined : options.buildBody ? JSON.stringify(options.buildBody({ args, context, session })) : JSON.stringify(args);
+      if (body !== undefined && !baseHeaders.has("content-type")) {
+        baseHeaders.set("content-type", "application/json");
+      }
+      const request = new Request(url, {
+        body,
+        headers: baseHeaders,
+        method
+      });
+      const response = await fetchImpl(request);
+      const parsedBody = options.parseResponse ? await options.parseResponse(response) : await response.json().catch(() => {
+        return;
+      });
+      return {
+        body: parsedBody,
+        ok: response.ok,
+        status: response.status,
+        url: url.toString()
+      };
+    },
+    name: options.name,
+    parameters: options.parameters,
+    resultToMessage: options.formatResult ?? ((result) => result.ok ? `API request ${options.name} succeeded (${String(result.status)}).` : `API request ${options.name} failed with status ${String(result.status)}.`)
+  });
+};
 // src/agentSquadContract.ts
 var normalizeIncludes = (value) => value.trim().toLowerCase();
 var resolveOutcome4 = (result) => {
@@ -43185,6 +43407,7 @@ export {
   createVoiceWebhookDeliveryWorkerLoop,
   createVoiceWebhookDeliveryWorker,
   createVoiceWebhookDeliverySink,
+  createVoiceVoicemailDetectionTool,
   createVoiceTwilioRedirectHandoffAdapter,
   createVoiceTwilioCampaignDialer,
   createVoiceTurnQualityRoutes,
@@ -43193,6 +43416,7 @@ export {
   createVoiceTurnLatencyRoutes,
   createVoiceTurnLatencyJSONHandler,
   createVoiceTurnLatencyHTMLHandler,
+  createVoiceTransferCallTool,
   createVoiceTraceTimelineRoutes,
   createVoiceTraceSinkStore,
   createVoiceTraceSinkDeliveryWorkerLoop,
@@ -43431,6 +43655,7 @@ export {
   createVoiceExperiment,
   createVoiceEvidenceAssertion,
   createVoiceEvalRoutes,
+  createVoiceEndCallTool,
   createVoiceDiagnosticsRoutes,
   createVoiceDemoReadyRoutes,
   createVoiceDeliverySinkRoutes,
@@ -43440,6 +43665,7 @@ export {
   createVoiceDeliveryRuntimePresetConfig,
   createVoiceDeliveryRuntime,
   createVoiceDataControlRoutes,
+  createVoiceDTMFTool,
   createVoiceCompetitiveCoverageRoutes,
   createVoiceCampaignWorkerLoop,
   createVoiceCampaignWorker,
@@ -43475,6 +43701,7 @@ export {
   createVoiceAssistantHealthJSONHandler,
   createVoiceAssistantHealthHTMLHandler,
   createVoiceAssistant,
+  createVoiceApiRequestTool,
   createVoiceAgentTool,
   createVoiceAgentSquad,
   createVoiceAgent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/voice",
-  "version": "0.0.22-beta.469",
+  "version": "0.0.22-beta.470",
   "description": "Voice primitives and Elysia plugin for AbsoluteJS",
   "repository": {
     "type": "git",