retell-utils 0.3.2 → 0.3.3

package/dist/agent.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+/** Response engine variant: Retell-hosted LLM. */
+export declare const ResponseEngineRetellLlmSchema: z.ZodObject<{
+    type: z.ZodLiteral<"retell-llm">;
+    llm_id: z.ZodString;
+    version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+/** Response engine variant: custom (self-hosted) LLM. */
+export declare const ResponseEngineCustomLlmSchema: z.ZodObject<{
+    type: z.ZodLiteral<"custom-llm">;
+    llm_websocket_url: z.ZodString;
+}, z.core.$strip>;
+/** Response engine variant: conversation flow. */
+export declare const ResponseEngineConversationFlowSchema: z.ZodObject<{
+    type: z.ZodLiteral<"conversation-flow">;
+    conversation_flow_id: z.ZodString;
+    version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+/**
+ * Discriminated union of all response engine types. Used in both voice and chat
+ * agent responses.
+ */
+export declare const ResponseEngineSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"retell-llm">;
+    llm_id: z.ZodString;
+    version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"custom-llm">;
+    llm_websocket_url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"conversation-flow">;
+    conversation_flow_id: z.ZodString;
+    version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>], "type">;
+/**
+ * Zod schema for a voice agent response from the Retell API. Validates
+ * structural fields (IDs, response engine, version) and passes through all
+ * other fields for forward compatibility.
+ */
+export declare const VoiceAgentResponseSchema: z.ZodObject<{
+    agent_id: z.ZodString;
+    agent_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    response_engine: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"retell-llm">;
+        llm_id: z.ZodString;
+        version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"custom-llm">;
+        llm_websocket_url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"conversation-flow">;
+        conversation_flow_id: z.ZodString;
+        version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>], "type">;
+    voice_id: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+    is_published: z.ZodOptional<z.ZodBoolean>;
+    last_modification_timestamp: z.ZodNumber;
+    language: z.ZodOptional<z.ZodString>;
+    data_storage_setting: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        everything: "everything";
+        everything_except_pii: "everything_except_pii";
+        basic_attributes_only: "basic_attributes_only";
+    }>>>;
+}, z.core.$loose>;
+/**
+ * Zod schema for a chat agent response from the Retell API. Same philosophy as
+ * VoiceAgentResponseSchema: validate structural fields, passthrough the rest.
+ */
+export declare const ChatAgentResponseSchema: z.ZodObject<{
+    agent_id: z.ZodString;
+    agent_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    response_engine: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"retell-llm">;
+        llm_id: z.ZodString;
+        version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"custom-llm">;
+        llm_websocket_url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"conversation-flow">;
+        conversation_flow_id: z.ZodString;
+        version: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>], "type">;
+    version: z.ZodOptional<z.ZodNumber>;
+    is_published: z.ZodOptional<z.ZodBoolean>;
+    last_modification_timestamp: z.ZodNumber;
+    language: z.ZodOptional<z.ZodString>;
+    data_storage_setting: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        everything: "everything";
+        everything_except_pii: "everything_except_pii";
+        basic_attributes_only: "basic_attributes_only";
+    }>>>;
+}, z.core.$loose>;

package/dist/agent.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { DataStorageSettingSchema } from "./enums.js";
+// ---------------------------------------------------------------------------
+// Response engine (shared by voice and chat agents)
+// ---------------------------------------------------------------------------
+/** Response engine variant: Retell-hosted LLM. */
+export const ResponseEngineRetellLlmSchema = z.object({
+    type: z.literal("retell-llm"),
+    llm_id: z.string(),
+    version: z.number().nullable().optional(),
+});
+/** Response engine variant: custom (self-hosted) LLM. */
+export const ResponseEngineCustomLlmSchema = z.object({
+    type: z.literal("custom-llm"),
+    llm_websocket_url: z.string(),
+});
+/** Response engine variant: conversation flow. */
+export const ResponseEngineConversationFlowSchema = z.object({
+    type: z.literal("conversation-flow"),
+    conversation_flow_id: z.string(),
+    version: z.number().nullable().optional(),
+});
+/**
+ * Discriminated union of all response engine types. Used in both voice and chat
+ * agent responses.
+ */
+export const ResponseEngineSchema = z.discriminatedUnion("type", [
+    ResponseEngineRetellLlmSchema,
+    ResponseEngineCustomLlmSchema,
+    ResponseEngineConversationFlowSchema,
+]);
+// ---------------------------------------------------------------------------
+// Voice agent response
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for a voice agent response from the Retell API. Validates
+ * structural fields (IDs, response engine, version) and passes through all
+ * other fields for forward compatibility.
+ */
+export const VoiceAgentResponseSchema = z
+    .object({
+    agent_id: z.string(),
+    agent_name: z.string().nullable().optional(),
+    response_engine: ResponseEngineSchema,
+    voice_id: z.string(),
+    version: z.number().optional(),
+    is_published: z.boolean().optional(),
+    last_modification_timestamp: z.number(),
+    language: z.string().optional(),
+    data_storage_setting: DataStorageSettingSchema.nullable().optional(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// Chat agent response
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for a chat agent response from the Retell API. Same philosophy as
+ * VoiceAgentResponseSchema: validate structural fields, passthrough the rest.
+ */
+export const ChatAgentResponseSchema = z
+    .object({
+    agent_id: z.string(),
+    agent_name: z.string().nullable().optional(),
+    response_engine: ResponseEngineSchema,
+    version: z.number().optional(),
+    is_published: z.boolean().optional(),
+    last_modification_timestamp: z.number(),
+    language: z.string().optional(),
+    data_storage_setting: DataStorageSettingSchema.nullable().optional(),
+})
+    .passthrough();

package/dist/flow.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/**
+ * Zod schema for a conversation flow response. Validates structural fields and
+ * passes through the rest (nodes, components, etc.) for forward compatibility.
+ */
+export declare const ConversationFlowResponseSchema: z.ZodObject<{
+    conversation_flow_id: z.ZodString;
+    version: z.ZodNumber;
+    is_published: z.ZodOptional<z.ZodBoolean>;
+    global_prompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    nodes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{}, z.core.$loose>>>>;
+}, z.core.$loose>;

package/dist/flow.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/**
+ * Zod schema for a conversation flow response. Validates structural fields and
+ * passes through the rest (nodes, components, etc.) for forward compatibility.
+ */
+export const ConversationFlowResponseSchema = z
+    .object({
+    conversation_flow_id: z.string(),
+    version: z.number(),
+    /** SDK types omit this, but the API returns it. */
+    is_published: z.boolean().optional(),
+    global_prompt: z.string().nullable().optional(),
+    nodes: z.array(z.looseObject({})).nullable().optional(),
+})
+    .passthrough();

package/dist/index.d.ts

@@ -8,3 +8,8 @@ export { createCallAnalysisSchema, createChatAnalysisSchema } from "./analysis.j
 export { type CallSchemaConfig, CallSchemas, callSchemaDefaults, createCallSchemas, } from "./call.js";
 export { type ChatSchemaConfig, ChatSchemas, chatSchemaDefaults, createChatSchemas, } from "./chat.js";
 export { WebhookSchemas, createWebhookSchemas } from "./webhook.js";
+export { ChatAgentResponseSchema, ResponseEngineConversationFlowSchema, ResponseEngineCustomLlmSchema, ResponseEngineRetellLlmSchema, ResponseEngineSchema, VoiceAgentResponseSchema, } from "./agent.js";
+export { LlmResponseSchema } from "./llm.js";
+export { ConversationFlowResponseSchema } from "./flow.js";
+export { InputMatchRuleSchema, TestCaseDefinitionSchema, TestCaseResponseEngineSchema, ToolMockSchema, } from "./test-case.js";
+export { retellPagination } from "./pagination.js";

package/dist/index.js

@@ -18,3 +18,13 @@ export { CallSchemas, callSchemaDefaults, createCallSchemas, } from "./call.js";
 export { ChatSchemas, chatSchemaDefaults, createChatSchemas, } from "./chat.js";
 // Webhook schemas + factory
 export { WebhookSchemas, createWebhookSchemas } from "./webhook.js";
+// Agent config schemas
+export { ChatAgentResponseSchema, ResponseEngineConversationFlowSchema, ResponseEngineCustomLlmSchema, ResponseEngineRetellLlmSchema, ResponseEngineSchema, VoiceAgentResponseSchema, } from "./agent.js";
+// LLM config schemas
+export { LlmResponseSchema } from "./llm.js";
+// Conversation flow config schemas
+export { ConversationFlowResponseSchema } from "./flow.js";
+// Test case schemas
+export { InputMatchRuleSchema, TestCaseDefinitionSchema, TestCaseResponseEngineSchema, ToolMockSchema, } from "./test-case.js";
+// Pagination utility
+export { retellPagination } from "./pagination.js";

package/dist/llm.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+/**
+ * Zod schema for a Retell LLM response. Validates structural fields and passes
+ * through all other fields (tools, states, etc.) for forward compatibility.
+ */
+export declare const LlmResponseSchema: z.ZodObject<{
+    llm_id: z.ZodString;
+    last_modification_timestamp: z.ZodNumber;
+    version: z.ZodOptional<z.ZodNumber>;
+    is_published: z.ZodOptional<z.ZodBoolean>;
+    general_prompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    begin_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;

package/dist/llm.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * Zod schema for a Retell LLM response. Validates structural fields and passes
+ * through all other fields (tools, states, etc.) for forward compatibility.
+ */
+export const LlmResponseSchema = z
+    .object({
+    llm_id: z.string(),
+    last_modification_timestamp: z.number(),
+    version: z.number().optional(),
+    /** SDK types omit this, but the API returns it. */
+    is_published: z.boolean().optional(),
+    general_prompt: z.string().nullable().optional(),
+    begin_message: z.string().nullable().optional(),
+})
+    .passthrough();

package/dist/pagination.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Fetches all pages from a paginated Retell API list endpoint. The Retell API
+ * uses cursor-based pagination where the last item's ID and version are passed
+ * as the cursor for the next page.
+ */
+export declare function retellPagination<T>(
+/** The list API call, receiving pagination options. */
+op: (opts: {
+    limit?: number;
+    pagination_key?: string;
+    pagination_key_version?: number;
+}) => Promise<T[]>, 
+/** The property name used as the pagination key (e.g. "agent_id", "llm_id"). */
+idKey: keyof T & string, limit?: number): Promise<T[]>;

package/dist/pagination.js

@@ -0,0 +1,35 @@
+/**
+ * Fetches all pages from a paginated Retell API list endpoint. The Retell API
+ * uses cursor-based pagination where the last item's ID and version are passed
+ * as the cursor for the next page.
+ */
+export async function retellPagination(
+/** The list API call, receiving pagination options. */
+op, 
+/** The property name used as the pagination key (e.g. "agent_id", "llm_id"). */
+idKey, limit = 1000) {
+    const results = [];
+    let paginationKey;
+    let paginationKeyVersion;
+    while (true) {
+        const page = await op({
+            limit,
+            pagination_key: paginationKey,
+            pagination_key_version: paginationKeyVersion,
+        });
+        for (const item of page)
+            results.push(item);
+        if (page.length < limit)
+            break;
+        const lastItem = page.at(-1);
+        if (!lastItem)
+            break;
+        const id = lastItem[idKey];
+        if (typeof id !== "string")
+            break;
+        paginationKey = id;
+        const version = lastItem.version;
+        paginationKeyVersion = typeof version === "number" ? version : undefined;
+    }
+    return results;
+}

package/dist/test-case.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+/** Zod schema for input match rule types in test case tool mocks. */
+export declare const InputMatchRuleSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"any">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"partial_match">;
+    args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>], "type">;
+/** Zod schema for tool mock configurations in test cases. */
+export declare const ToolMockSchema: z.ZodObject<{
+    tool_name: z.ZodString;
+    input_match_rule: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"any">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"partial_match">;
+        args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>], "type">;
+    output: z.ZodString;
+    result: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+/** Zod schema for response engine references in test cases. */
+export declare const TestCaseResponseEngineSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"retell-llm">;
+    llm_id: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"conversation-flow">;
+    conversation_flow_id: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "type">;
+/** Zod schema for a test case definition from the Retell API. */
+export declare const TestCaseDefinitionSchema: z.ZodObject<{
+    test_case_definition_id: z.ZodString;
+    name: z.ZodString;
+    response_engine: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"retell-llm">;
+        llm_id: z.ZodString;
+        version: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"conversation-flow">;
+        conversation_flow_id: z.ZodString;
+        version: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>], "type">;
+    dynamic_variables: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    metrics: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    user_prompt: z.ZodString;
+    creation_timestamp: z.ZodNumber;
+    user_modified_timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"simulation">;
+    tool_mocks: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tool_name: z.ZodString;
+        input_match_rule: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"any">;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"partial_match">;
+            args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>], "type">;
+        output: z.ZodString;
+        result: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strip>>>>;
+    llm_model: z.ZodString;
+}, z.core.$strip>;

package/dist/test-case.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+/** Zod schema for input match rule types in test case tool mocks. */
+export const InputMatchRuleSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("any") }),
+    z.object({
+        type: z.literal("partial_match"),
+        args: z.record(z.string(), z.unknown()),
+    }),
+]);
+/** Zod schema for tool mock configurations in test cases. */
+export const ToolMockSchema = z.object({
+    tool_name: z.string(),
+    input_match_rule: InputMatchRuleSchema,
+    output: z.string(),
+    result: z.boolean().nullable().optional(),
+});
+/** Zod schema for response engine references in test cases. */
+export const TestCaseResponseEngineSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("retell-llm"),
+        llm_id: z.string(),
+        version: z.number().optional(),
+    }),
+    z.object({
+        type: z.literal("conversation-flow"),
+        conversation_flow_id: z.string(),
+        version: z.number().optional(),
+    }),
+]);
+/** Zod schema for a test case definition from the Retell API. */
+export const TestCaseDefinitionSchema = z.object({
+    test_case_definition_id: z.string(),
+    name: z.string(),
+    response_engine: TestCaseResponseEngineSchema,
+    dynamic_variables: z.record(z.string(), z.unknown()).optional().default({}),
+    metrics: z.array(z.string()).optional().default([]),
+    user_prompt: z.string(),
+    creation_timestamp: z.number(),
+    user_modified_timestamp: z.number(),
+    type: z.literal("simulation"),
+    tool_mocks: z.array(ToolMockSchema).optional().default([]),
+    llm_model: z.string(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retell-utils",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Type-safe Zod schemas for Retell AI API resources with lifecycle-aware discriminated unions and generic customization",
   "type": "module",
   "zshy": {
@@ -17,8 +17,8 @@
     "test": "bun test",
     "prepublishOnly": "bun run build"
   },
-  "peerDependencies": {
-    "zod": "^4.0.0"
+  "dependencies": {
+    "zod": "^4.3.5"
   },
   "devDependencies": {
     "@types/bun": "latest",
@@ -27,7 +27,6 @@
     "prettier": "latest",
     "prettier-plugin-jsdoc": "^1.8.0",
     "typescript": "^5.8.3",
-    "zod": "^4.3.5",
     "zshy": "^0.7.0"
   },
   "license": "MIT",