@copilotkit/sdk-js 1.9.2-next.2 → 1.9.2-next.21

package/src/__tests__/error-handling.test.ts

@@ -0,0 +1,207 @@
+import { CopilotKitMisuseError } from "@copilotkit/shared";
+import {
+  copilotKitInterrupt,
+  convertActionToDynamicStructuredTool,
+  convertActionsToDynamicStructuredTools,
+  copilotkitCustomizeConfig,
+  copilotkitEmitMessage,
+  copilotkitEmitState,
+  copilotkitEmitToolCall,
+  copilotkitExit,
+} from "../langgraph";
+
+describe("SDK-JS Error Handling", () => {
+  describe("copilotKitInterrupt", () => {
+    it("should throw CopilotKitMisuseError when neither message nor action provided", () => {
+      expect(() => {
+        copilotKitInterrupt({});
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        copilotKitInterrupt({});
+      }).toThrow(
+        "Either message or action (and optional arguments) must be provided for copilotKitInterrupt",
+      );
+    });
+
+    it("should throw CopilotKitMisuseError when action is not a string", () => {
+      expect(() => {
+        copilotKitInterrupt({ action: 123 as any });
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        copilotKitInterrupt({ action: 123 as any });
+      }).toThrow("Action must be a string when provided to copilotKitInterrupt");
+    });
+
+    it("should throw CopilotKitMisuseError when message is not a string", () => {
+      expect(() => {
+        copilotKitInterrupt({ message: 123 as any });
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        copilotKitInterrupt({ message: 123 as any });
+      }).toThrow("Message must be a string when provided to copilotKitInterrupt");
+    });
+
+    it("should throw CopilotKitMisuseError when args is not an object", () => {
+      expect(() => {
+        copilotKitInterrupt({ action: "test", args: "invalid" as any });
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        copilotKitInterrupt({ action: "test", args: "invalid" as any });
+      }).toThrow("Args must be an object when provided to copilotKitInterrupt");
+    });
+  });
+
+  describe("convertActionToDynamicStructuredTool", () => {
+    it("should throw CopilotKitMisuseError when actionInput is null/undefined", () => {
+      expect(() => {
+        convertActionToDynamicStructuredTool(null);
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        convertActionToDynamicStructuredTool(null);
+      }).toThrow("Action input is required but was not provided");
+    });
+
+    it("should throw CopilotKitMisuseError when name is missing", () => {
+      expect(() => {
+        convertActionToDynamicStructuredTool({ description: "test" });
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        convertActionToDynamicStructuredTool({ description: "test" });
+      }).toThrow("Action must have a valid 'name' property of type string");
+    });
+
+    it("should throw CopilotKitMisuseError when description is missing", () => {
+      expect(() => {
+        convertActionToDynamicStructuredTool({ name: "test" });
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        convertActionToDynamicStructuredTool({ name: "test" });
+      }).toThrow("Action 'test' must have a valid 'description' property of type string");
+    });
+
+    it("should throw CopilotKitMisuseError when parameters is missing", () => {
+      expect(() => {
+        convertActionToDynamicStructuredTool({ name: "test", description: "test desc" });
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        convertActionToDynamicStructuredTool({ name: "test", description: "test desc" });
+      }).toThrow("Action 'test' must have a 'parameters' property");
+    });
+  });
+
+  describe("convertActionsToDynamicStructuredTools", () => {
+    it("should throw CopilotKitMisuseError when actions is not an array", () => {
+      expect(() => {
+        convertActionsToDynamicStructuredTools("not an array" as any);
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        convertActionsToDynamicStructuredTools("not an array" as any);
+      }).toThrow("Actions must be an array");
+    });
+  });
+
+  describe("copilotkitCustomizeConfig", () => {
+    it("should throw CopilotKitMisuseError when baseConfig is not an object", () => {
+      expect(() => {
+        copilotkitCustomizeConfig("invalid" as any);
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        copilotkitCustomizeConfig("invalid" as any);
+      }).toThrow("baseConfig must be an object or null/undefined");
+    });
+
+    it("should throw CopilotKitMisuseError when options is not an object", () => {
+      expect(() => {
+        copilotkitCustomizeConfig({}, "invalid" as any);
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        copilotkitCustomizeConfig({}, "invalid" as any);
+      }).toThrow("options must be an object when provided");
+    });
+
+    it("should throw CopilotKitMisuseError when emitIntermediateState is not an array", () => {
+      expect(() => {
+        copilotkitCustomizeConfig({}, { emitIntermediateState: "invalid" as any });
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        copilotkitCustomizeConfig({}, { emitIntermediateState: "invalid" as any });
+      }).toThrow("emitIntermediateState must be an array when provided");
+    });
+
+    it("should throw CopilotKitMisuseError when emitIntermediateState item is invalid", () => {
+      expect(() => {
+        copilotkitCustomizeConfig({}, { emitIntermediateState: [{ invalidKey: "value" }] as any });
+      }).toThrow(CopilotKitMisuseError);
+
+      expect(() => {
+        copilotkitCustomizeConfig({}, { emitIntermediateState: [{ invalidKey: "value" }] as any });
+      }).toThrow("emitIntermediateState[0] must have a valid 'stateKey' string property");
+    });
+  });
+
+  describe("emit functions", () => {
+    const mockConfig = { metadata: {} };
+
+    it("should throw CopilotKitMisuseError when config is missing for copilotkitExit", async () => {
+      await expect(copilotkitExit(null as any)).rejects.toThrow(CopilotKitMisuseError);
+      await expect(copilotkitExit(null as any)).rejects.toThrow(
+        "LangGraph configuration is required for copilotkitExit",
+      );
+    });
+
+    it("should throw CopilotKitMisuseError when config is missing for copilotkitEmitState", async () => {
+      await expect(copilotkitEmitState(null as any, {})).rejects.toThrow(CopilotKitMisuseError);
+      await expect(copilotkitEmitState(null as any, {})).rejects.toThrow(
+        "LangGraph configuration is required for copilotkitEmitState",
+      );
+    });
+
+    it("should throw CopilotKitMisuseError when state is undefined for copilotkitEmitState", async () => {
+      await expect(copilotkitEmitState(mockConfig, undefined)).rejects.toThrow(
+        CopilotKitMisuseError,
+      );
+      await expect(copilotkitEmitState(mockConfig, undefined)).rejects.toThrow(
+        "State is required for copilotkitEmitState",
+      );
+    });
+
+    it("should throw CopilotKitMisuseError when message is invalid for copilotkitEmitMessage", async () => {
+      await expect(copilotkitEmitMessage(mockConfig, "" as any)).rejects.toThrow(
+        CopilotKitMisuseError,
+      );
+      await expect(copilotkitEmitMessage(mockConfig, "" as any)).rejects.toThrow(
+        "Message must be a non-empty string for copilotkitEmitMessage",
+      );
+    });
+
+    it("should throw CopilotKitMisuseError when tool name is invalid for copilotkitEmitToolCall", async () => {
+      await expect(copilotkitEmitToolCall(mockConfig, "", {})).rejects.toThrow(
+        CopilotKitMisuseError,
+      );
+      await expect(copilotkitEmitToolCall(mockConfig, "", {})).rejects.toThrow(
+        "Tool name must be a non-empty string for copilotkitEmitToolCall",
+      );
+    });
+
+    it("should throw CopilotKitMisuseError when args is undefined for copilotkitEmitToolCall", async () => {
+      await expect(copilotkitEmitToolCall(mockConfig, "testTool", undefined)).rejects.toThrow(
+        CopilotKitMisuseError,
+      );
+      await expect(copilotkitEmitToolCall(mockConfig, "testTool", undefined)).rejects.toThrow(
+        "Tool arguments are required for copilotkitEmitToolCall",
+      );
+    });
+  });
+});

package/src/langgraph.ts

@@ -1,6 +1,6 @@
 import { RunnableConfig } from "@langchain/core/runnables";
 import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
-import { convertJsonSchemaToZodSchema, randomId } from "@copilotkit/shared";
+import { convertJsonSchemaToZodSchema, randomId, CopilotKitMisuseError } from "@copilotkit/shared";
 import { Annotation, MessagesAnnotation, interrupt } from "@langchain/langgraph";
 import { DynamicStructuredTool } from "@langchain/core/tools";
 import { AIMessage } from "@langchain/core/messages";
@@ -90,36 +90,89 @@ export function copilotkitCustomizeConfig(
    */
   options?: OptionsConfig,
 ): RunnableConfig {
-  const metadata = baseConfig?.metadata || {};
-
-  if (options?.emitAll) {
-    metadata["copilotkit:emit-tool-calls"] = true;
-    metadata["copilotkit:emit-messages"] = true;
-  } else {
-    if (options?.emitToolCalls !== undefined) {
-      metadata["copilotkit:emit-tool-calls"] = options.emitToolCalls;
-    }
-    if (options?.emitMessages !== undefined) {
-      metadata["copilotkit:emit-messages"] = options.emitMessages;
-    }
+  if (baseConfig && typeof baseConfig !== "object") {
+    throw new CopilotKitMisuseError({
+      message: "baseConfig must be an object or null/undefined",
+    });
+  }
+
+  if (options && typeof options !== "object") {
+    throw new CopilotKitMisuseError({
+      message: "options must be an object when provided",
+    });
   }
 
+  // Validate emitIntermediateState structure
   if (options?.emitIntermediateState) {
-    const snakeCaseIntermediateState = options.emitIntermediateState.map((state) => ({
-      tool: state.tool,
-      tool_argument: state.toolArgument,
-      state_key: state.stateKey,
-    }));
+    if (!Array.isArray(options.emitIntermediateState)) {
+      throw new CopilotKitMisuseError({
+        message: "emitIntermediateState must be an array when provided",
+      });
+    }
+
+    options.emitIntermediateState.forEach((state, index) => {
+      if (!state || typeof state !== "object") {
+        throw new CopilotKitMisuseError({
+          message: `emitIntermediateState[${index}] must be an object`,
+        });
+      }
+
+      if (!state.stateKey || typeof state.stateKey !== "string") {
+        throw new CopilotKitMisuseError({
+          message: `emitIntermediateState[${index}] must have a valid 'stateKey' string property`,
+        });
+      }
 
-    metadata["copilotkit:emit-intermediate-state"] = snakeCaseIntermediateState;
+      if (!state.tool || typeof state.tool !== "string") {
+        throw new CopilotKitMisuseError({
+          message: `emitIntermediateState[${index}] must have a valid 'tool' string property`,
+        });
+      }
+
+      if (state.toolArgument && typeof state.toolArgument !== "string") {
+        throw new CopilotKitMisuseError({
+          message: `emitIntermediateState[${index}].toolArgument must be a string when provided`,
+        });
+      }
+    });
   }
 
-  baseConfig = baseConfig || {};
+  try {
+    const metadata = baseConfig?.metadata || {};
 
-  return {
-    ...baseConfig,
-    metadata: metadata,
-  };
+    if (options?.emitAll) {
+      metadata["copilotkit:emit-tool-calls"] = true;
+      metadata["copilotkit:emit-messages"] = true;
+    } else {
+      if (options?.emitToolCalls !== undefined) {
+        metadata["copilotkit:emit-tool-calls"] = options.emitToolCalls;
+      }
+      if (options?.emitMessages !== undefined) {
+        metadata["copilotkit:emit-messages"] = options.emitMessages;
+      }
+    }
+
+    if (options?.emitIntermediateState) {
+      const snakeCaseIntermediateState = options.emitIntermediateState.map((state) => ({
+        tool: state.tool,
+        tool_argument: state.toolArgument,
+        state_key: state.stateKey,
+      }));
+
+      metadata["copilotkit:emit-intermediate-state"] = snakeCaseIntermediateState;
+    }
+
+    baseConfig = baseConfig || {};
+
+    return {
+      ...baseConfig,
+      metadata: metadata,
+    };
+  } catch (error) {
+    throw new CopilotKitMisuseError({
+      message: `Failed to customize config: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
 }
 /**
  * Exits the current agent after the run completes. Calling copilotkit_exit() will
@@ -142,7 +195,19 @@ export async function copilotkitExit(
    */
   config: RunnableConfig,
 ) {
-  await dispatchCustomEvent("copilotkit_exit", {}, config);
+  if (!config) {
+    throw new CopilotKitMisuseError({
+      message: "LangGraph configuration is required for copilotkitExit",
+    });
+  }
+
+  try {
+    await dispatchCustomEvent("copilotkit_exit", {}, config);
+  } catch (error) {
+    throw new CopilotKitMisuseError({
+      message: `Failed to dispatch exit event: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
 }
 /**
  * Emits intermediate state to CopilotKit. Useful if you have a longer running node and you want to
@@ -169,7 +234,25 @@ export async function copilotkitEmitState(
    */
   state: any,
 ) {
-  await dispatchCustomEvent("copilotkit_manually_emit_intermediate_state", state, config);
+  if (!config) {
+    throw new CopilotKitMisuseError({
+      message: "LangGraph configuration is required for copilotkitEmitState",
+    });
+  }
+
+  if (state === undefined) {
+    throw new CopilotKitMisuseError({
+      message: "State is required for copilotkitEmitState",
+    });
+  }
+
+  try {
+    await dispatchCustomEvent("copilotkit_manually_emit_intermediate_state", state, config);
+  } catch (error) {
+    throw new CopilotKitMisuseError({
+      message: `Failed to emit state: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
 }
 /**
  * Manually emits a message to CopilotKit. Useful in longer running nodes to update the user.
@@ -199,11 +282,29 @@ export async function copilotkitEmitMessage(
    */
   message: string,
 ) {
-  await dispatchCustomEvent(
-    "copilotkit_manually_emit_message",
-    { message, message_id: randomId(), role: "assistant" },
-    config,
-  );
+  if (!config) {
+    throw new CopilotKitMisuseError({
+      message: "LangGraph configuration is required for copilotkitEmitMessage",
+    });
+  }
+
+  if (!message || typeof message !== "string") {
+    throw new CopilotKitMisuseError({
+      message: "Message must be a non-empty string for copilotkitEmitMessage",
+    });
+  }
+
+  try {
+    await dispatchCustomEvent(
+      "copilotkit_manually_emit_message",
+      { message, message_id: randomId(), role: "assistant" },
+      config,
+    );
+  } catch (error) {
+    throw new CopilotKitMisuseError({
+      message: `Failed to emit message: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
 }
 /**
  * Manually emits a tool call to CopilotKit.
@@ -230,22 +331,76 @@ export async function copilotkitEmitToolCall(
    */
   args: any,
 ) {
-  await dispatchCustomEvent(
-    "copilotkit_manually_emit_tool_call",
-    { name, args, id: randomId() },
-    config,
-  );
+  if (!config) {
+    throw new CopilotKitMisuseError({
+      message: "LangGraph configuration is required for copilotkitEmitToolCall",
+    });
+  }
+
+  if (!name || typeof name !== "string") {
+    throw new CopilotKitMisuseError({
+      message: "Tool name must be a non-empty string for copilotkitEmitToolCall",
+    });
+  }
+
+  if (args === undefined) {
+    throw new CopilotKitMisuseError({
+      message: "Tool arguments are required for copilotkitEmitToolCall",
+    });
+  }
+
+  try {
+    await dispatchCustomEvent(
+      "copilotkit_manually_emit_tool_call",
+      { name, args, id: randomId() },
+      config,
+    );
+  } catch (error) {
+    throw new CopilotKitMisuseError({
+      message: `Failed to emit tool call '${name}': ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
 }
 
 export function convertActionToDynamicStructuredTool(actionInput: any): DynamicStructuredTool<any> {
-  return new DynamicStructuredTool({
-    name: actionInput.name,
-    description: actionInput.description,
-    schema: convertJsonSchemaToZodSchema(actionInput.parameters, true),
-    func: async () => {
-      return "";
-    },
-  });
+  if (!actionInput) {
+    throw new CopilotKitMisuseError({
+      message: "Action input is required but was not provided",
+    });
+  }
+
+  if (!actionInput.name || typeof actionInput.name !== "string") {
+    throw new CopilotKitMisuseError({
+      message: "Action must have a valid 'name' property of type string",
+    });
+  }
+
+  if (!actionInput.description || typeof actionInput.description !== "string") {
+    throw new CopilotKitMisuseError({
+      message: `Action '${actionInput.name}' must have a valid 'description' property of type string`,
+    });
+  }
+
+  if (!actionInput.parameters) {
+    throw new CopilotKitMisuseError({
+      message: `Action '${actionInput.name}' must have a 'parameters' property`,
+    });
+  }
+
+  try {
+    return new DynamicStructuredTool({
+      name: actionInput.name,
+      description: actionInput.description,
+      schema: convertJsonSchemaToZodSchema(actionInput.parameters, true),
+      func: async () => {
+        return "";
+      },
+    });
+  } catch (error) {
+    throw new CopilotKitMisuseError({
+      message: `Failed to convert action '${actionInput.name}' to DynamicStructuredTool: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
 }
 /**
  * Use this function to convert a list of actions you get from state
@@ -265,7 +420,21 @@ export function convertActionsToDynamicStructuredTools(
    */
   actions: any[],
 ): DynamicStructuredTool<any>[] {
-  return actions.map((action) => convertActionToDynamicStructuredTool(action));
+  if (!Array.isArray(actions)) {
+    throw new CopilotKitMisuseError({
+      message: "Actions must be an array",
+    });
+  }
+
+  return actions.map((action, index) => {
+    try {
+      return convertActionToDynamicStructuredTool(action);
+    } catch (error) {
+      throw new CopilotKitMisuseError({
+        message: `Failed to convert action at index ${index}: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  });
 }
 
 export function copilotKitInterrupt({
@@ -278,35 +447,63 @@ export function copilotKitInterrupt({
   args?: Record<string, any>;
 }) {
   if (!message && !action) {
-    throw new Error("Either message or action (and optional arguments) must be provided");
+    throw new CopilotKitMisuseError({
+      message:
+        "Either message or action (and optional arguments) must be provided for copilotKitInterrupt",
+    });
+  }
+
+  if (action && typeof action !== "string") {
+    throw new CopilotKitMisuseError({
+      message: "Action must be a string when provided to copilotKitInterrupt",
+    });
+  }
+
+  if (message && typeof message !== "string") {
+    throw new CopilotKitMisuseError({
+      message: "Message must be a string when provided to copilotKitInterrupt",
+    });
+  }
+
+  if (args && typeof args !== "object") {
+    throw new CopilotKitMisuseError({
+      message: "Args must be an object when provided to copilotKitInterrupt",
+    });
   }
 
   let interruptValues = null;
   let interruptMessage = null;
   let answer = null;
-  if (message) {
-    interruptValues = message;
-    interruptMessage = new AIMessage({ content: message, id: randomId() });
-  } else {
-    const toolId = randomId();
-    interruptMessage = new AIMessage({
-      content: "",
-      tool_calls: [{ id: toolId, name: action, args: args ?? {} }],
+
+  try {
+    if (message) {
+      interruptValues = message;
+      interruptMessage = new AIMessage({ content: message, id: randomId() });
+    } else {
+      const toolId = randomId();
+      interruptMessage = new AIMessage({
+        content: "",
+        tool_calls: [{ id: toolId, name: action, args: args ?? {} }],
+      });
+      interruptValues = {
+        action,
+        args: args ?? {},
+      };
+    }
+
+    const response = interrupt({
+      __copilotkit_interrupt_value__: interruptValues,
+      __copilotkit_messages__: [interruptMessage],
     });
-    interruptValues = {
-      action,
-      args: args ?? {},
+    answer = response[response.length - 1].content;
+
+    return {
+      answer,
+      messages: response,
     };
+  } catch (error) {
+    throw new CopilotKitMisuseError({
+      message: `Failed to create interrupt: ${error instanceof Error ? error.message : String(error)}`,
+    });
   }
-
-  const response = interrupt({
-    __copilotkit_interrupt_value__: interruptValues,
-    __copilotkit_messages__: [interruptMessage],
-  });
-  answer = response[response.length - 1].content;
-
-  return {
-    answer,
-    messages: response,
-  };
 }