@apollo/client-ai-apps 0.2.4 → 0.3.1

package/src/{hooks → react/hooks/__tests__}/useToolEffect.test.tsx

@@ -1,15 +1,20 @@
 import { expect, test, vi } from "vitest";
-import { useToolEffect, ToolUseProvider } from "./useToolEffect";
+import { useToolEffect } from "../useToolEffect";
 import { renderHook } from "@testing-library/react";
+import { ToolUseProvider } from "../../context/ToolUseContext";
 
 test("Should trigger effect when tool name matches toolResponseMetadata", async () => {
   vi.stubGlobal("openai", {
     toolResponseMetadata: { toolName: "my-app--my-tool" },
   });
   const navigate = vi.fn();
-  const wrapper = ({ children }: { children: any }) => <ToolUseProvider appName="my-app">{children}</ToolUseProvider>;
+  const wrapper = ({ children }: { children: any }) => (
+    <ToolUseProvider appName="my-app">{children}</ToolUseProvider>
+  );
 
-  renderHook(() => useToolEffect("my-tool", () => navigate(), [navigate]), { wrapper });
+  renderHook(() => useToolEffect("my-tool", () => navigate(), [navigate]), {
+    wrapper,
+  });
 
   expect(navigate).toBeCalled();
 });
@@ -19,9 +24,17 @@ test("Should trigger effect when one of multiple tool name matches toolResponseM
     toolResponseMetadata: { toolName: "my-app--my-tool" },
   });
   const navigate = vi.fn();
-  const wrapper = ({ children }: { children: any }) => <ToolUseProvider appName="my-app">{children}</ToolUseProvider>;
+  const wrapper = ({ children }: { children: any }) => (
+    <ToolUseProvider appName="my-app">{children}</ToolUseProvider>
+  );
 
-  renderHook(() => useToolEffect(["my-tool", "my-similar-tool"], () => navigate(), [navigate]), { wrapper });
+  renderHook(
+    () =>
+      useToolEffect(["my-tool", "my-similar-tool"], () => navigate(), [
+        navigate,
+      ]),
+    { wrapper }
+  );
 
   expect(navigate).toBeCalled();
 });
@@ -31,9 +44,13 @@ test("Should not trigger effect when tool name does not match toolResponseMetada
     toolResponseMetadata: { toolName: "my-app--my-other-tool" },
   });
   const navigate = vi.fn();
-  const wrapper = ({ children }: { children: any }) => <ToolUseProvider appName="my-app">{children}</ToolUseProvider>;
+  const wrapper = ({ children }: { children: any }) => (
+    <ToolUseProvider appName="my-app">{children}</ToolUseProvider>
+  );
 
-  renderHook(() => useToolEffect("my-tool", () => navigate(), [navigate]), { wrapper });
+  renderHook(() => useToolEffect("my-tool", () => navigate(), [navigate]), {
+    wrapper,
+  });
 
   expect(navigate).not.toBeCalled();
 });
@@ -44,7 +61,7 @@ test("Should throw an error when used outside of a ToolUseProvider", async () =>
   });
   const navigate = vi.fn();
 
-  expect(() => renderHook(() => useToolEffect("my-tool", () => navigate(), [navigate]))).toThrowError(
-    "useToolEffect must be used within ToolUseProvider"
-  );
+  expect(() =>
+    renderHook(() => useToolEffect("my-tool", () => navigate(), [navigate]))
+  ).toThrowError("useToolEffect must be used within ToolUseProvider");
 });

package/src/{hooks → react/hooks/__tests__}/useToolInput.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, vi } from "vitest";
-import { useToolInput } from "./useToolInput";
+import { useToolInput } from "../useToolInput";
 import { renderHook } from "@testing-library/react";
 
 test("Should return tool input when called", async () => {

package/src/{hooks → react/hooks/__tests__}/useToolName.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, vi } from "vitest";
-import { useToolName } from "./useToolName";
+import { useToolName } from "../useToolName";
 import { renderHook } from "@testing-library/react";
 
 test("Should return tool input when called", async () => {

package/src/react/hooks/__tests__/useToolOutput.test.tsx

@@ -0,0 +1,49 @@
+import { afterEach, expect, test, vi } from "vitest";
+import {
+  dispatchStateChange,
+  stubOpenAiGlobals,
+} from "../../../testing/internal";
+import { renderHookToSnapshotStream } from "@testing-library/react-render-stream";
+import { useToolOutput } from "../useToolOutput";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+test("returns the tool output set in window", async () => {
+  stubOpenAiGlobals({ toolOutput: { test: true } });
+
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useToolOutput()
+  );
+
+  await expect(takeSnapshot()).resolves.toEqual({ test: true });
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("returns null when not set", async () => {
+  stubOpenAiGlobals();
+
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useToolOutput()
+  );
+
+  await expect(takeSnapshot()).resolves.toBeNull();
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("reacts to changes in globals", async () => {
+  stubOpenAiGlobals({ toolOutput: { initial: true } });
+
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useToolOutput()
+  );
+
+  await expect(takeSnapshot()).resolves.toEqual({ initial: true });
+
+  window.openai.toolOutput = { updated: true };
+  dispatchStateChange();
+
+  await expect(takeSnapshot()).resolves.toEqual({ updated: true });
+  await expect(takeSnapshot).not.toRerender();
+});

package/src/react/hooks/__tests__/useToolResponseMetadata.test.tsx

@@ -0,0 +1,49 @@
+import { afterEach, expect, test, vi } from "vitest";
+import {
+  dispatchStateChange,
+  stubOpenAiGlobals,
+} from "../../../testing/internal";
+import { renderHookToSnapshotStream } from "@testing-library/react-render-stream";
+import { useToolResponseMetadata } from "../useToolResponseMetadata";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+test("returns the tool output set in window", async () => {
+  stubOpenAiGlobals({ toolResponseMetadata: { test: true } });
+
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useToolResponseMetadata()
+  );
+
+  await expect(takeSnapshot()).resolves.toEqual({ test: true });
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("returns null when not set", async () => {
+  stubOpenAiGlobals();
+
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useToolResponseMetadata()
+  );
+
+  await expect(takeSnapshot()).resolves.toBeNull();
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("reacts to changes in globals", async () => {
+  stubOpenAiGlobals({ toolResponseMetadata: { initial: true } });
+
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useToolResponseMetadata()
+  );
+
+  await expect(takeSnapshot()).resolves.toEqual({ initial: true });
+
+  window.openai.toolResponseMetadata = { updated: true };
+  dispatchStateChange();
+
+  await expect(takeSnapshot()).resolves.toEqual({ updated: true });
+  await expect(takeSnapshot).not.toRerender();
+});

package/src/react/hooks/__tests__/useWidgetState.test.tsx

@@ -0,0 +1,158 @@
+import { afterEach, expect, test, vi } from "vitest";
+import {
+  disableActEnvironment,
+  renderHookToSnapshotStream,
+} from "@testing-library/react-render-stream";
+import { useWidgetState } from "../useWidgetState";
+import { stubOpenAiGlobals } from "../../../testing/internal";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+test("returns state from global", async () => {
+  stubOpenAiGlobals({ widgetState: { test: true } });
+
+  using _disabledAct = disableActEnvironment();
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useWidgetState()
+  );
+
+  const [widgetState] = await takeSnapshot();
+
+  expect(widgetState).toEqual({ test: true });
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("returns null when global does not exist", async () => {
+  stubOpenAiGlobals();
+
+  using _disabledAct = disableActEnvironment();
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useWidgetState()
+  );
+
+  const [widgetState] = await takeSnapshot();
+
+  expect(widgetState).toBeNull();
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("returns provided default state when global does not exist", async () => {
+  stubOpenAiGlobals();
+
+  using _disabledAct = disableActEnvironment();
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useWidgetState({ defaultValue: true })
+  );
+
+  const [widgetState] = await takeSnapshot();
+
+  expect(widgetState).toEqual({ defaultValue: true });
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("returns provided default state returned from init function when global does not exist", async () => {
+  stubOpenAiGlobals();
+
+  using _disabledAct = disableActEnvironment();
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useWidgetState(() => ({ defaultValueFromFunction: true }))
+  );
+
+  const [widgetState] = await takeSnapshot();
+
+  expect(widgetState).toEqual({ defaultValueFromFunction: true });
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("prefers global value over default value", async () => {
+  stubOpenAiGlobals({ widgetState: { globalWidgetState: true } });
+
+  using _disabledAct = disableActEnvironment();
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useWidgetState({ defaultValue: true })
+  );
+
+  const [widgetState] = await takeSnapshot();
+
+  expect(widgetState).toEqual({ globalWidgetState: true });
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("rerenders with new value after setting new value", async () => {
+  stubOpenAiGlobals({ widgetState: { globalWidgetState: true } });
+
+  using _disabledAct = disableActEnvironment();
+  const { takeSnapshot, getCurrentSnapshot } = await renderHookToSnapshotStream(
+    () => useWidgetState()
+  );
+
+  {
+    const [widgetState] = await takeSnapshot();
+
+    expect(widgetState).toEqual({ globalWidgetState: true });
+  }
+
+  const [, setWidgetState] = getCurrentSnapshot();
+  setWidgetState({ rerendered: true });
+
+  {
+    const [widgetState] = await takeSnapshot();
+
+    expect(widgetState).toEqual({ rerendered: true });
+  }
+
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("allows state setter function with previous value", async () => {
+  stubOpenAiGlobals({ widgetState: { globalWidgetState: true } });
+
+  using _disabledAct = disableActEnvironment();
+  const { takeSnapshot, getCurrentSnapshot } = await renderHookToSnapshotStream(
+    () => useWidgetState()
+  );
+
+  {
+    const [widgetState] = await takeSnapshot();
+
+    expect(widgetState).toEqual({ globalWidgetState: true });
+  }
+
+  const [, setWidgetState] = getCurrentSnapshot();
+  setWidgetState((prev) => ({ ...prev, rerendered: true }));
+
+  {
+    const [widgetState] = await takeSnapshot();
+
+    expect(widgetState).toEqual({ globalWidgetState: true, rerendered: true });
+  }
+
+  await expect(takeSnapshot).not.toRerender();
+});
+
+test("updates value from window when changed globally", async () => {
+  stubOpenAiGlobals({ widgetState: { globalWidgetState: true } });
+
+  using _disabledAct = disableActEnvironment();
+  const { takeSnapshot } = await renderHookToSnapshotStream(() =>
+    useWidgetState()
+  );
+
+  {
+    const [widgetState] = await takeSnapshot();
+
+    expect(widgetState).toEqual({ globalWidgetState: true });
+  }
+
+  window.openai.setWidgetState({ fromEvent: true });
+
+  {
+    const [widgetState] = await takeSnapshot();
+
+    expect(widgetState).toEqual({ fromEvent: true });
+  }
+
+  await expect(takeSnapshot).not.toRerender();
+});

package/src/react/hooks/useCallTool.ts

@@ -0,0 +1,13 @@
+type UseCallToolResult = <K>(
+  toolId: string,
+  variables?: Record<string, unknown> | undefined
+) => Promise<K>;
+
+export const useCallTool = (): UseCallToolResult => {
+  const callTool = async (
+    toolId: string,
+    variables: Record<string, unknown> | undefined = {}
+  ) => await window.openai?.callTool(toolId, variables);
+
+  return callTool;
+};

package/src/{hooks → react/hooks}/useOpenAiGlobal.ts

@@ -1,9 +1,15 @@
-import { useSyncExternalStore } from "react";
-import { SET_GLOBALS_EVENT_TYPE, SetGlobalsEvent, OpenAiGlobals } from "../types/openai";
+import { useSyncExternalStore, useCallback } from "react";
+import {
+  SET_GLOBALS_EVENT_TYPE,
+  SetGlobalsEvent,
+  OpenAiGlobals,
+} from "../../types/openai";
 
-export function useOpenAiGlobal<K extends keyof OpenAiGlobals>(key: K): OpenAiGlobals[K] {
+export function useOpenAiGlobal<K extends keyof OpenAiGlobals>(
+  key: K
+): OpenAiGlobals[K] {
   return useSyncExternalStore(
-    (onChange) => {
+    useCallback((onChange) => {
       const handleSetGlobal = (event: SetGlobalsEvent) => {
         const value = event.detail.globals[key];
         if (value === undefined) {
@@ -20,7 +26,7 @@ export function useOpenAiGlobal<K extends keyof OpenAiGlobals>(key: K): OpenAiGl
       return () => {
         window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
       };
-    },
+    }, []),
     () => window.openai[key]
   );
 }

package/src/react/hooks/useOpenExternal.ts

@@ -0,0 +1,11 @@
+import { useCallback } from "react";
+import { API } from "../../types/openai";
+
+type OpenExternalFn = API<any>["openExternal"];
+
+export function useOpenExternal() {
+  return useCallback<OpenExternalFn>(
+    (...args) => window.openai.openExternal(...args),
+    []
+  );
+}

package/src/{hooks → react/hooks}/useRequestDisplayMode.ts

@@ -1,4 +1,4 @@
-import { DisplayMode } from "../types/openai";
+import { DisplayMode } from "../../types/openai";
 
 export const useRequestDisplayMode = () => {
   return async (args: { mode: DisplayMode }) => {

package/src/react/hooks/useToolEffect.tsx

@@ -0,0 +1,37 @@
+import React, { useEffect } from "react";
+import { useToolName } from "./useToolName";
+import { useToolInput } from "./useToolInput";
+import { useToolUseState } from "../context/ToolUseContext";
+
+export const useToolEffect = (
+  toolName: string | string[],
+  effect: (toolInput: any) => void,
+  deps: React.DependencyList = []
+) => {
+  const ctx = useToolUseState();
+  const fullToolName = useToolName();
+  const toolInput = useToolInput();
+  if (!ctx)
+    throw new Error("useToolEffect must be used within ToolUseProvider");
+
+  const toolNames = Array.isArray(toolName) ? toolName : [toolName];
+
+  useEffect(() => {
+    const matches = toolNames.some(
+      (name) => fullToolName === `${ctx.appName}--${name}`
+    );
+
+    if (!ctx.hasNavigated && matches) {
+      effect(toolInput);
+      ctx.setHasNavigated(true);
+    }
+  }, [
+    ctx.hasNavigated,
+    ctx.setHasNavigated,
+    ctx.appName,
+    toolNames,
+    fullToolName,
+    toolInput,
+    ...deps,
+  ]);
+};

package/src/{hooks → react/hooks}/useToolName.ts

@@ -3,5 +3,5 @@ import { useOpenAiGlobal } from "./useOpenAiGlobal";
 export const useToolName = (): string | undefined => {
   const toolResponseMetadata = useOpenAiGlobal("toolResponseMetadata");
 
-  return toolResponseMetadata?.toolName;
+  return toolResponseMetadata?.toolName as string;
 };

package/src/react/hooks/useToolOutput.ts

@@ -0,0 +1,5 @@
+import { useOpenAiGlobal } from "./useOpenAiGlobal";
+
+export function useToolOutput() {
+  return useOpenAiGlobal("toolOutput") ?? null;
+}

package/src/react/hooks/useToolResponseMetadata.ts

@@ -0,0 +1,5 @@
+import { useOpenAiGlobal } from "./useOpenAiGlobal";
+
+export function useToolResponseMetadata() {
+  return useOpenAiGlobal("toolResponseMetadata") ?? null;
+}

package/src/react/hooks/useWidgetState.ts

@@ -0,0 +1,48 @@
+import { SetStateAction, useCallback, useState } from "react";
+import { UnknownObject } from "../../types/openai";
+import { useOpenAiGlobal } from "./useOpenAiGlobal";
+
+export function useWidgetState<T extends UnknownObject>(
+  defaultState: T | (() => T)
+): readonly [T, (state: SetStateAction<T>) => void];
+
+export function useWidgetState<T extends UnknownObject>(
+  defaultState?: T | (() => T | null) | null
+): readonly [T | null, (state: SetStateAction<T | null>) => void];
+
+export function useWidgetState<T extends UnknownObject>(
+  defaultState?: T | (() => T | null) | null
+): readonly [T | null, (state: SetStateAction<T | null>) => void] {
+  const widgetStateFromWindow = useOpenAiGlobal("widgetState") as T;
+  const [previousWidgetStateFromWindow, setPreviousWidgetStateFromWindow] =
+    useState(widgetStateFromWindow);
+
+  let [widgetState, _setWidgetState] = useState<T | null>(() => {
+    if (widgetStateFromWindow != null) {
+      return widgetStateFromWindow;
+    }
+
+    return typeof defaultState === "function" ? defaultState() : (
+        (defaultState ?? null)
+      );
+  });
+
+  if (previousWidgetStateFromWindow !== widgetStateFromWindow) {
+    _setWidgetState((widgetState = widgetStateFromWindow));
+    setPreviousWidgetStateFromWindow(widgetStateFromWindow);
+  }
+
+  const setWidgetState = useCallback((state: SetStateAction<T | null>) => {
+    _setWidgetState((prevState) => {
+      const newState = typeof state === "function" ? state(prevState) : state;
+
+      if (newState != null && typeof window !== "undefined") {
+        void window.openai?.setWidgetState?.(newState);
+      }
+
+      return newState;
+    });
+  }, []);
+
+  return [widgetState, setWidgetState];
+}

package/src/testing/internal/index.ts

@@ -0,0 +1,2 @@
+export { dispatchStateChange } from "./openai/dispatchStateChange";
+export { stubOpenAiGlobals } from "./openai/stubOpenAiGlobals";

package/src/testing/internal/matchers/index.d.ts

@@ -0,0 +1,9 @@
+import { NextRenderOptions } from "@testing-library/react-render-stream";
+
+interface CustomMatchers<R = unknown> {
+  toRerender: (options?: NextRenderOptions) => Promise<R>;
+}
+
+declare module "vitest" {
+  interface Assertion<T = any> extends CustomMatchers<T> {}
+}

package/src/testing/internal/matchers/index.ts

@@ -0,0 +1 @@
+import "./toRerender";

package/src/testing/internal/matchers/toRerender.ts

@@ -0,0 +1,49 @@
+// Vitest port of toRerender from
+// https://github.com/testing-library/react-render-stream-testing-library/blob/main/src/expect/renderStreamMatchers.ts
+import {
+  Assertable,
+  NextRenderOptions,
+  RenderStream,
+  WaitForRenderTimeoutError,
+} from "@testing-library/react-render-stream";
+
+import { expect } from "vitest";
+
+const assertableSymbol = Symbol.for(
+  "@testing-library/react-render-stream:assertable"
+);
+
+expect.extend({
+  async toRerender(actual, options: NextRenderOptions) {
+    const _stream = actual as RenderStream<any> | Assertable;
+    const stream = (
+      assertableSymbol in _stream ?
+        _stream[assertableSymbol]
+      : _stream) as RenderStream<any>;
+    const hint = this.utils.matcherHint("toRerender", undefined, undefined, {
+      isNot: this.isNot,
+    });
+
+    let pass = true;
+
+    try {
+      await stream.peekRender({ timeout: 100, ...options });
+    } catch (e) {
+      if (e instanceof WaitForRenderTimeoutError) {
+        pass = false;
+      } else {
+        throw e;
+      }
+    }
+
+    return {
+      pass,
+      message() {
+        return (
+          `${hint}\n\nExpected component to${pass ? " not" : ""} rerender, ` +
+          `but it did${pass ? "" : " not"}.`
+        );
+      },
+    };
+  },
+});

package/src/testing/internal/openai/dispatchStateChange.ts

@@ -0,0 +1,9 @@
+import { SET_GLOBALS_EVENT_TYPE } from "../../../types/openai";
+
+export function dispatchStateChange() {
+  window.dispatchEvent(
+    new CustomEvent(SET_GLOBALS_EVENT_TYPE, {
+      detail: { globals: window.openai },
+    })
+  );
+}

package/src/testing/internal/openai/stubOpenAiGlobals.ts

@@ -0,0 +1,13 @@
+import { vi } from "vitest";
+import { API, OpenAiGlobals, UnknownObject } from "../../../types/openai";
+import { dispatchStateChange } from "./dispatchStateChange";
+
+export function stubOpenAiGlobals(globals?: Partial<API<any> & OpenAiGlobals>) {
+  vi.stubGlobal("openai", {
+    setWidgetState: (state: UnknownObject) => {
+      window.openai.widgetState = state;
+      dispatchStateChange();
+    },
+    ...globals,
+  });
+}

package/src/types/openai.ts

@@ -1,4 +1,4 @@
-type UnknownObject = any;
+export type UnknownObject = Record<string, unknown>;
 
 declare global {
   interface Window {
@@ -14,7 +14,7 @@ export type OpenAiGlobals<
   ToolInput extends UnknownObject = UnknownObject,
   ToolOutput extends UnknownObject = UnknownObject,
   ToolResponseMetadata extends UnknownObject = UnknownObject,
-  WidgetState extends UnknownObject = UnknownObject
+  WidgetState extends UnknownObject = UnknownObject,
 > = {
   theme: Theme;
   userAgent: UserAgent;
@@ -62,7 +62,10 @@ export class SetGlobalsEvent extends CustomEvent<{
   readonly type = SET_GLOBALS_EVENT_TYPE;
 }
 
-export type CallTool = (name: string, args: Record<string, unknown>) => Promise<any>;
+export type CallTool = (
+  name: string,
+  args: Record<string, unknown>
+) => Promise<any>;
 
 export type DisplayMode = "pip" | "inline" | "fullscreen";
 

package/src/vite/{absolute_asset_imports_plugin.test.ts → __tests__/absolute_asset_imports_plugin.test.ts}

@@ -1,5 +1,5 @@
 import { expect, test, vi, describe, beforeEach, Mock } from "vitest";
-import { AbsoluteAssetImportsPlugin } from "./absolute_asset_imports_plugin";
+import { AbsoluteAssetImportsPlugin } from "../absolute_asset_imports_plugin";
 
 test("Should replace root relative scripts with full url when origin is provided", () => {
   const ctx = {
@@ -96,5 +96,7 @@ test("Should not modify html when not running a local server", () => {
 
   let result = plugin.transformIndexHtml(html, ctx);
 
-  expect(result).toMatchInlineSnapshot(`"<html><head><script type="module" src="/@vite/client"></script></head><body><script module src="/assets/main.ts?t=12345"></script></body></html>"`);
+  expect(result).toMatchInlineSnapshot(
+    `"<html><head><script type="module" src="/@vite/client"></script></head><body><script module src="/assets/main.ts?t=12345"></script></body></html>"`
+  );
 });